From fab6d32f6958162723f752496a3c1ed6845cc53e Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Tue, 19 Jun 2018 11:33:34 -0700 Subject: [PATCH] Separate MFS from other files APIs. This is in line with how the TOC is written on https://github.com/ipfs/js-ipfs-api/blob/master/README.md and makes it much clearer which APIs are for MFS. --- SPEC/FILES.md | 250 +++++++++++++++++++++++++------------------------- 1 file changed, 126 insertions(+), 124 deletions(-) diff --git a/SPEC/FILES.md b/SPEC/FILES.md index 7427701de..ec1fc84cd 100644 --- a/SPEC/FILES.md +++ b/SPEC/FILES.md @@ -2,29 +2,132 @@ > The files API enables users to use the File System abstraction of IPFS. -* [files.add](#filesadd) -* [files.addReadableStream](#filesaddreadablestream) -* [files.addPullStream](#filesaddpullstream) -* [files.cat](#filescat) -* [files.catReadableStream](#filescatreadablestream) -* [files.catPullStream](#filescatpullstream) -* [files.get](#filesget) -* [files.getReadableStream](#filesgetreadablestream) -* [files.getPullStream](#filesgetpullstream) -* [ls](#ls) -* [lsReadableStream](#lsreadablestream) -* [lsPullStream](#lspullstream) -* [files.cp](#filescp) -* [files.mkdir](#filesmkdir) -* [files.stat](#filesstat) -* [files.rm](#filesrm) -* [files.read](#filesread) -* [files.readReadableStream](#filesreadreadablestream) -* [files.readPullStream](#filesreadpullstream) -* [files.write](#fileswrite) -* [files.mv](#filesmv) -* [files.flush](#filesflush) -* [files.ls](#filesls) +- [ls](#ls) +- [lsReadableStream](#lsreadablestream) +- [lsPullStream](#lspullstream) +- files + - [files.add](#filesadd) + - [files.addReadableStream](#filesaddreadablestream) + - [files.addPullStream](#filesaddpullstream) + - [files.cat](#filescat) + - [files.catReadableStream](#filescatreadablestream) + - [files.catPullStream](#filescatpullstream) + - [files.get](#filesget) + - [files.getReadableStream](#filesgetreadablestream) + - [files.getPullStream](#filesgetpullstream) + - MFS (mutable file system) + - [files.cp](#filescp) + - [files.flush](#filesflush) + - [files.ls](#filesls) + - [files.mkdir](#filesmkdir) + - [files.mv](#filesmv) + - [files.read](#filesread) + - [files.readPullStream](#filesreadpullstream) + - [files.readReadableStream](#filesreadreadablestream) + - [files.rm](#filesrm) + - [files.stat](#filesstat) + - [files.write](#fileswrite) + +#### `ls` + +> Lists a directory from IPFS that is addressed by a valid IPFS Path. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.ls(ipfsPath, [callback]) + +> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. + +ipfsPath can be of type: + +- [`cid`][cid] of type: + - [Buffer][b], the raw Buffer of the cid + - String, the base58 encoded version of the cid +- String, including the ipfs handler, a cid and a path to traverse to, ie: + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + +`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing objects of the following form: + +```js +{ + depth: 1, + name: 'alice.txt', + path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', + size: 11696, + hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', + type: 'file' +} +``` + +If no `callback` is passed, a promise is returned. + +**Example:** + +```JavaScript +const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' + +ipfs.ls(validCID, function (err, files) { + files.forEach((file) => { + console.log(file.path) + }) +}) +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `lsReadableStream` + +> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs] + +> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. + +ipfsPath can be of type: + +- [`cid`][cid] of type: + - [Buffer][b], the raw Buffer of the cid + - String, the base58 encoded version of the cid +- String, including the ipfs handler, a cid and a path to traverse to, ie: + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' + - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' + +It returns a [Readable Stream][rs] in [Object mode](https://nodejs.org/api/stream.html#stream_object_mode) that will yield objects of the form: + +```js +{ + depth: 1, + name: 'alice.txt', + path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', + size: 11696, + hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', + type: 'file' +} +``` + +**Example:** + +```JavaScript +const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' + +const stream = ipfs.lsReadableStream(validCID) + +stream.on('data', (file) => { + // write the file's path and contents to standard out + console.log(file.path) +}) +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `lsPullStream` + +> Fetch a file or an entire directory tree from IPFS that is addressed by a valid IPFS Path. The files will be yielded through a Pull Stream. #### `files.add` @@ -435,107 +538,6 @@ pull( A great source of [examples][] can be found in the tests for this API. -#### `ls` - -> Lists a directory from IPFS that is addressed by a valid IPFS Path. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.ls(ipfsPath, [callback]) - -> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. - -ipfsPath can be of type: - -- [`cid`][cid] of type: - - [Buffer][b], the raw Buffer of the cid - - String, the base58 encoded version of the cid -- String, including the ipfs handler, a cid and a path to traverse to, ie: - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - -`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing objects of the following form: - -```js -{ - depth: 1, - name: 'alice.txt', - path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', - size: 11696, - hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', - type: 'file' -} -``` - -If no `callback` is passed, a promise is returned. - -**Example:** - -```JavaScript -const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' - -ipfs.ls(validCID, function (err, files) { - files.forEach((file) => { - console.log(file.path) - }) -}) -``` - -A great source of [examples][] can be found in the tests for this API. - -#### `lsReadableStream` - -> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs] - -> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality. - -ipfsPath can be of type: - -- [`cid`][cid] of type: - - [Buffer][b], the raw Buffer of the cid - - String, the base58 encoded version of the cid -- String, including the ipfs handler, a cid and a path to traverse to, ie: - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66' - - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt' - -It returns a [Readable Stream][rs] in [Object mode](https://nodejs.org/api/stream.html#stream_object_mode) that will yield objects of the form: - -```js -{ - depth: 1, - name: 'alice.txt', - path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt', - size: 11696, - hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi', - type: 'file' -} -``` - -**Example:** - -```JavaScript -const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF' - -const stream = ipfs.lsReadableStream(validCID) - -stream.on('data', (file) => { - // write the file's path and contents to standard out - console.log(file.path) -}) -``` - -A great source of [examples][] can be found in the tests for this API. - -#### `lsPullStream` - -> Fetch a file or an entire directory tree from IPFS that is addressed by a valid IPFS Path. The files will be yielded through a Pull Stream. - ##### `Go` **WIP** ##### `JavaScript` - ipfs.lsPullStream(ipfsPath) -> [Pull Stream][ps]