Merge pull request #265 from ipfs/add-mfs-read-methods

docs: adds stream-related mfs files.read method signatures

Author: alanshaw

SPEC/FILES.md

@@ -19,6 +19,8 @@
 * [files.stat](#filesmkdir)
 * [files.rm](#filesrm)
 * [files.read](#filesread)
+* [files.readReadableStream](#filesreadreadablestream)
+* [files.readPullStream](#filesreadpullstream)
 * [files.write](#fileswrite)
 * [files.mv](#filesmv)
 * [files.flush](#filesflush)
@@ -599,8 +601,8 @@ The Mutable File System (MFS) is a virtual file system on top of IPFS that expos
 
 Where:
 
-- `from` is the path of the source object to copy.
-- `to` is the path of the destination object to copy to.
+- `from` is the path of the source file to copy.
+- `to` is the path of the destination file to copy to.
 
 `callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
 
@@ -700,7 +702,7 @@ ipfs.files.stat('/file.txt', (err, stats) => {
 
 Where:
 
-- `path` is the path of the object to remove.
+- `path` is the path of the file to remove.
 - `options` is an optional Object that might contain the following keys:
   - `recursive` is a Boolean value to decide whether or not to remove directories recursively.
 
@@ -728,33 +730,88 @@ ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => {
 
 #### `files.read`
 
-> Read a file.
+> Read a file into a [`Buffer`][b].
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.files.read(path, [options, callback])
+##### `JavaScript` - ipfs.files.read(path, [options], [callback])
 
 Where:
 
-- `path` is the path of the object to read.
+- `path` is the path of the file to read.
 - `options` is an optional Object that might contain the following keys:
   - `offset` is an Integer with the byte offset to begin reading from.
   - `count` is an Integer with the maximum number of bytes to read.
 
-`callback` must follow the `function (err, buf) {}` signature, where `err` is an Error if the operation was not successful and `buf` is a Buffer with the contents of `path`.
+`callback` must follow the `function (err, buf) {}` signature, where `err` is an Error if the operation was not successful and `buf` is a [`Buffer`][b] with the contents of `path`.
 
 If no `callback` is passed, a promise is returned.
 
 **Example:**
 
 ```JavaScript
 ipfs.files.read('/hello-world', (err, buf) => {
-  console.log(buf.toString())
+  console.log(buf.toString('utf8'))
 })
 
 // Hello, World!
 ```
 
+#### `readReadableStream`
+
+> Read a file into a [`ReadableStream`][rs].
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.readReadableStream(path, [options])
+
+Where:
+
+- `path` is the path of the file to read.
+- `options` is an optional Object that might contain the following keys:
+  - `offset` is an Integer with the byte offset to begin reading from.
+  - `count` is an Integer with the maximum number of bytes to read.
+
+Returns a [`ReadableStream`][rs] with the contents of `path`.
+
+**Example:**
+
+```JavaScript
+const stream = ipfs.files.readReadableStream('/hello-world')
+stream.on('data', (buf) => console.log(buf.toString('utf8')))
+
+// Hello, World!
+```
+
+#### `readPullStream`
+
+> Read a file into a [`PullStream`][ps].
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.readPullStream(path, [options])
+
+Where:
+
+- `path` is the path of the file to read.
+- `options` is an optional Object that might contain the following keys:
+  - `offset` is an Integer with the byte offset to begin reading from.
+  - `count` is an Integer with the maximum number of bytes to read.
+
+Returns a [`PullStream`][ps] with the contents of `path`.
+
+**Example:**
+
+```JavaScript
+pull(
+  ipfs.files.readPullStream('/hello-world'),
+  through(buf => console.log(buf.toString('utf8'))),
+  collect(err => {})
+)
+
+// Hello, World!
+```
+
 #### `files.write`
 
 > Write to a file.
@@ -765,10 +822,13 @@ ipfs.files.read('/hello-world', (err, buf) => {
 
 Where:
 
-- `path` is the path of the object to write.
+- `path` is the path of the file to write.
 - `content` can be:
-  - a Buffer instance.
-  - a Path (caveat: will only work in Node.js).
+  - a [`Buffer`][b]
+  - a [`PullStream`][ps]
+  - a [`ReadableStream`][rs]
+  - a [`Blob`][blob] (caveat: will only work in the browser)
+  - a string path to a file (caveat: will only work in Node.js)
 - `options` is an optional Object that might contain the following keys:
   - `offset` is an Integer with the byte offset to begin writing at.
   - `create` is a Boolean to indicate to create the file if it doesn't exist.
@@ -797,8 +857,8 @@ ipfs.files.write('/hello-world', Buffer.from('Hello, world!'), (err) => {
 
 Where:
 
-- `from` is the path of the source object to move.
-- `to` is the path of the destination object to move to.
+- `from` is the path of the source file to move.
+- `to` is the path of the destination file to move to.
 
 `callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
 
@@ -881,3 +941,4 @@ ipfs.files.ls('/screenshots', function (err, files) {
 [rs]: https://www.npmjs.com/package/readable-stream
 [ps]: https://www.npmjs.com/package/pull-stream
 [cid]: https://www.npmjs.com/package/cids
+[blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob