From 0f8c02de83dd87f538d8a1fca8681f085224b4bf Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 9 May 2018 09:46:16 +0100 Subject: [PATCH 1/3] docs: adds stream-related mfs files.read method signatures License: MIT Signed-off-by: achingbrain --- SPEC/FILES.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/SPEC/FILES.md b/SPEC/FILES.md index bd97ba3d5..bd9227d5d 100644 --- a/SPEC/FILES.md +++ b/SPEC/FILES.md @@ -728,11 +728,11 @@ 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: @@ -741,7 +741,7 @@ Where: - `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. @@ -749,7 +749,69 @@ If no `callback` is passed, a promise is returned. ```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], [callback]) + +Where: + +- `path` is the path of the object 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, stream) {}` signature, where `err` is an Error if the operation was not successful and `stream` is a [`ReadableStream`][rs] with the contents of `path`. + +If no `callback` is passed, a promise is returned. + +**Example:** + +```JavaScript +ipfs.files.readReadableStream('/hello-world', (err, stream) => { + stream.on('data', (buf) => console.log(buf.toString('utf8'))) +}) + +// Hello, World! +``` + +#### `readPullStream` + +> Read a file into a [`PullStream`][ps]. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.files.readReadableStream(path, [options], [callback]) + +Where: + +- `path` is the path of the object 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, stream) {}` signature, where `err` is an Error if the operation was not successful and `stream` is a [`PullStream`][ps] with the contents of `path`. + +If no `callback` is passed, a promise is returned. + +**Example:** + +```JavaScript +ipfs.files.readPullStream('/hello-world', (err, stream) => { + pull( + stream, + through(buf => console.log(buf.toString('utf8'))), + collect(err => {}) + ) }) // Hello, World! From b8904f196197ef83192214ddd53ed60739ca4c9b Mon Sep 17 00:00:00 2001 From: achingbrain Date: Mon, 14 May 2018 10:29:16 +0100 Subject: [PATCH 2/3] docs: document mfs write content argument --- SPEC/FILES.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/SPEC/FILES.md b/SPEC/FILES.md index bd9227d5d..1c0ef96e4 100644 --- a/SPEC/FILES.md +++ b/SPEC/FILES.md @@ -599,8 +599,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 +700,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. @@ -736,7 +736,7 @@ ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => { 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. @@ -765,7 +765,7 @@ ipfs.files.read('/hello-world', (err, buf) => { 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. @@ -790,11 +790,11 @@ ipfs.files.readReadableStream('/hello-world', (err, stream) => { ##### `Go` **WIP** -##### `JavaScript` - ipfs.files.readReadableStream(path, [options], [callback]) +##### `JavaScript` - ipfs.files.readPullStream(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. @@ -827,10 +827,13 @@ ipfs.files.readPullStream('/hello-world', (err, stream) => { 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. @@ -859,8 +862,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. @@ -943,3 +946,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 \ No newline at end of file From 06668d2696f36d39c4f44b2fb7f120b369061a0d Mon Sep 17 00:00:00 2001 From: achingbrain Date: Tue, 15 May 2018 14:14:35 +0100 Subject: [PATCH 3/3] docs: switch to returning streams instead of callbacks --- SPEC/FILES.md | 31 +++++++++++++------------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/SPEC/FILES.md b/SPEC/FILES.md index 1c0ef96e4..9f2db7441 100644 --- a/SPEC/FILES.md +++ b/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) @@ -761,7 +763,7 @@ ipfs.files.read('/hello-world', (err, buf) => { ##### `Go` **WIP** -##### `JavaScript` - ipfs.files.readReadableStream(path, [options], [callback]) +##### `JavaScript` - ipfs.files.readReadableStream(path, [options]) Where: @@ -770,16 +772,13 @@ Where: - `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, stream) {}` signature, where `err` is an Error if the operation was not successful and `stream` is a [`ReadableStream`][rs] with the contents of `path`. - -If no `callback` is passed, a promise is returned. +Returns a [`ReadableStream`][rs] with the contents of `path`. **Example:** ```JavaScript -ipfs.files.readReadableStream('/hello-world', (err, stream) => { - stream.on('data', (buf) => console.log(buf.toString('utf8'))) -}) +const stream = ipfs.files.readReadableStream('/hello-world') +stream.on('data', (buf) => console.log(buf.toString('utf8'))) // Hello, World! ``` @@ -790,7 +789,7 @@ ipfs.files.readReadableStream('/hello-world', (err, stream) => { ##### `Go` **WIP** -##### `JavaScript` - ipfs.files.readPullStream(path, [options], [callback]) +##### `JavaScript` - ipfs.files.readPullStream(path, [options]) Where: @@ -799,20 +798,16 @@ Where: - `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, stream) {}` signature, where `err` is an Error if the operation was not successful and `stream` is a [`PullStream`][ps] with the contents of `path`. - -If no `callback` is passed, a promise is returned. +Returns a [`PullStream`][ps] with the contents of `path`. **Example:** ```JavaScript -ipfs.files.readPullStream('/hello-world', (err, stream) => { - pull( - stream, - through(buf => console.log(buf.toString('utf8'))), - collect(err => {}) - ) -}) +pull( + ipfs.files.readPullStream('/hello-world'), + through(buf => console.log(buf.toString('utf8'))), + collect(err => {}) +) // Hello, World! ```