docs: Documents the offset/length arguments to ipfs.files.cat and friends (#242)

Author: achingbrain

SPEC/FILES.md

@@ -162,9 +162,9 @@ pull(
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.files.cat(ipfsPath, [callback])
+##### `JavaScript` - ipfs.files.cat(ipfsPath, [options], [callback])
 
-ipfsPath can be of type:
+`ipfsPath` can be of type:
 
 - [`cid`][cid] of type:
   - a [CID](https://github.com/ipfs/js-cid) instance
@@ -175,6 +175,10 @@ ipfsPath can be of type:
   - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
   - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
 
+`options` is an optional object that may contain the following keys:
+  - `offset` is an optional byte offset to start the stream at
+  - `length` is an optional number of bytes to read from the stream
+
 `callback` must follow `function (err, file) {}` signature, where `err` is an error if the operation was not successful and `file` is a [Buffer][b]
 
 If no `callback` is passed, a promise is returned.
@@ -199,9 +203,9 @@ A great source of [examples][] can be found in the tests for this API.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.files.catReadableStream(ipfsPath) -> [Readable Stream][rs]
+##### `JavaScript` - ipfs.files.catReadableStream(ipfsPath, [options]) -> [Readable Stream][rs]
 
-ipfsPath can be of type:
+`ipfsPath` can be of type:
 
 - [`cid`][cid] of type:
   - a [CID](https://github.com/ipfs/js-cid) instance
@@ -212,6 +216,10 @@ ipfsPath can be of type:
   - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
   - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
 
+`options` is an optional object that may contain the following keys:
+  - `offset` is an optional byte offset to start the stream at
+  - `length` is an optional number of bytes to read from the stream
+
 Returns a [Readable Stream][rs] with the contents of the file.
 
 
@@ -228,9 +236,9 @@ A great source of [examples][] can be found in the tests for this API.
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.files.catPullStream(ipfsPath) -> [Pull Stream][rs]
+##### `JavaScript` - ipfs.files.catPullStream(ipfsPath, [options]) -> [Pull Stream][rs]
 
-ipfsPath can be of type:
+`ipfsPath` can be of type:
 
 - [`cid`][cid] of type:
   - [Buffer][b], the raw Buffer of the cid
@@ -240,6 +248,10 @@ ipfsPath can be of type:
   - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
   - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
 
+`options` is an optional object that may contain the following keys:
+  - `offset` is an optional byte offset to start the stream at
+  - `length` is an optional number of bytes to read from the stream
+
 Returns a [Pull Stream][ps] with the contents of the file.
 
 ```JavaScript

js/src/files.js

@@ -25,7 +25,7 @@ module.exports = (common) => {
     this.timeout(40 * 1000)
 
     let ipfs
-    // let withGo
+    let withGo
 
     function fixture (path) {
       return loadFixture(path, 'interface-ipfs-core')
@@ -70,7 +70,7 @@ module.exports = (common) => {
           ipfs = node
           node.id((err, id) => {
             expect(err).to.not.exist()
-            // withGo = id.agentVersion.startsWith('go-ipfs')
+            withGo = id.agentVersion.startsWith('go-ipfs')
             done()
           })
         })
@@ -493,6 +493,22 @@ module.exports = (common) => {
               })
           })
       })
+
+      it('exports a chunk of a file', (done) => {
+        if (withGo) { this.skip() }
+
+        const offset = 1
+        const length = 3
+
+        ipfs.files.cat(smallFile.cid, {
+          offset,
+          length
+        }, (err, data) => {
+          expect(err).to.not.exist()
+          expect(data.toString()).to.equal('lz ')
+          done()
+        })
+      })
     })
 
     describe('.catReadableStream', () => {
@@ -507,6 +523,24 @@ module.exports = (common) => {
           done()
         }))
       })
+
+      it('exports a chunk of a file in a ReadableStream', (done) => {
+        if (withGo) { this.skip() }
+
+        const offset = 1
+        const length = 3
+
+        const stream = ipfs.files.catReadableStream(smallFile.cid, {
+          offset,
+          length
+        })
+
+        stream.pipe(bl((err, data) => {
+          expect(err).to.not.exist()
+          expect(data.toString()).to.equal('lz ')
+          done()
+        }))
+      })
     })
 
     describe('.catPullStream', () => {
@@ -525,6 +559,27 @@ module.exports = (common) => {
           })
         )
       })
+
+      it('exports a chunk of a file in a PullStream', (done) => {
+        if (withGo) { this.skip() }
+
+        const offset = 1
+        const length = 3
+
+        const stream = ipfs.files.catPullStream(smallFile.cid, {
+          offset,
+          length
+        })
+
+        pull(
+          stream,
+          pull.concat((err, data) => {
+            expect(err).to.not.exist()
+            expect(data.toString()).to.equal('lz ')
+            done()
+          })
+        )
+      })
     })
 
     describe('.get', () => {