Skip to content
This repository was archived by the owner on Mar 10, 2020. It is now read-only.

Commit fab6d32

Browse files
mikealmikeal
authored
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.
1 parent d7de796 commit fab6d32

File tree

1 file changed

+126
-124
lines changed

1 file changed

+126
-124
lines changed

‎SPEC/FILES.md

Lines changed: 126 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,132 @@
22

33
> The files API enables users to use the File System abstraction of IPFS.
44
5-
* [files.add](#filesadd)
6-
* [files.addReadableStream](#filesaddreadablestream)
7-
* [files.addPullStream](#filesaddpullstream)
8-
* [files.cat](#filescat)
9-
* [files.catReadableStream](#filescatreadablestream)
10-
* [files.catPullStream](#filescatpullstream)
11-
* [files.get](#filesget)
12-
* [files.getReadableStream](#filesgetreadablestream)
13-
* [files.getPullStream](#filesgetpullstream)
14-
* [ls](#ls)
15-
* [lsReadableStream](#lsreadablestream)
16-
* [lsPullStream](#lspullstream)
17-
* [files.cp](#filescp)
18-
* [files.mkdir](#filesmkdir)
19-
* [files.stat](#filesstat)
20-
* [files.rm](#filesrm)
21-
* [files.read](#filesread)
22-
* [files.readReadableStream](#filesreadreadablestream)
23-
* [files.readPullStream](#filesreadpullstream)
24-
* [files.write](#fileswrite)
25-
* [files.mv](#filesmv)
26-
* [files.flush](#filesflush)
27-
* [files.ls](#filesls)
5+
- [ls](#ls)
6+
- [lsReadableStream](#lsreadablestream)
7+
- [lsPullStream](#lspullstream)
8+
- files
9+
- [files.add](#filesadd)
10+
- [files.addReadableStream](#filesaddreadablestream)
11+
- [files.addPullStream](#filesaddpullstream)
12+
- [files.cat](#filescat)
13+
- [files.catReadableStream](#filescatreadablestream)
14+
- [files.catPullStream](#filescatpullstream)
15+
- [files.get](#filesget)
16+
- [files.getReadableStream](#filesgetreadablestream)
17+
- [files.getPullStream](#filesgetpullstream)
18+
- MFS (mutable file system)
19+
- [files.cp](#filescp)
20+
- [files.flush](#filesflush)
21+
- [files.ls](#filesls)
22+
- [files.mkdir](#filesmkdir)
23+
- [files.mv](#filesmv)
24+
- [files.read](#filesread)
25+
- [files.readPullStream](#filesreadpullstream)
26+
- [files.readReadableStream](#filesreadreadablestream)
27+
- [files.rm](#filesrm)
28+
- [files.stat](#filesstat)
29+
- [files.write](#fileswrite)
30+
31+
#### `ls`
32+
33+
> Lists a directory from IPFS that is addressed by a valid IPFS Path.
34+
35+
##### `Go` **WIP**
36+
37+
##### `JavaScript` - ipfs.ls(ipfsPath, [callback])
38+
39+
> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
40+
41+
ipfsPath can be of type:
42+
43+
- [`cid`][cid] of type:
44+
- [Buffer][b], the raw Buffer of the cid
45+
- String, the base58 encoded version of the cid
46+
- String, including the ipfs handler, a cid and a path to traverse to, ie:
47+
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
48+
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
49+
- 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
50+
51+
`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:
52+
53+
```js
54+
{
55+
depth: 1,
56+
name: 'alice.txt',
57+
path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
58+
size: 11696,
59+
hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
60+
type: 'file'
61+
}
62+
```
63+
64+
If no `callback` is passed, a promise is returned.
65+
66+
**Example:**
67+
68+
```JavaScript
69+
const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
70+
71+
ipfs.ls(validCID, function (err, files) {
72+
files.forEach((file) => {
73+
console.log(file.path)
74+
})
75+
})
76+
```
77+
78+
A great source of [examples][] can be found in the tests for this API.
79+
80+
#### `lsReadableStream`
81+
82+
> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams.
83+
84+
##### `Go` **WIP**
85+
86+
##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs]
87+
88+
> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
89+
90+
ipfsPath can be of type:
91+
92+
- [`cid`][cid] of type:
93+
- [Buffer][b], the raw Buffer of the cid
94+
- String, the base58 encoded version of the cid
95+
- String, including the ipfs handler, a cid and a path to traverse to, ie:
96+
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
97+
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
98+
- 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
99+
100+
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:
101+
102+
```js
103+
{
104+
depth: 1,
105+
name: 'alice.txt',
106+
path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
107+
size: 11696,
108+
hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
109+
type: 'file'
110+
}
111+
```
112+
113+
**Example:**
114+
115+
```JavaScript
116+
const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
117+
118+
const stream = ipfs.lsReadableStream(validCID)
119+
120+
stream.on('data', (file) => {
121+
// write the file's path and contents to standard out
122+
console.log(file.path)
123+
})
124+
```
125+
126+
A great source of [examples][] can be found in the tests for this API.
127+
128+
#### `lsPullStream`
129+
130+
> 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.
28131
29132
#### `files.add`
30133

@@ -435,107 +538,6 @@ pull(
435538
A great source of [examples][] can be found in the tests for this API.
436539

437540

438-
#### `ls`
439-
440-
> Lists a directory from IPFS that is addressed by a valid IPFS Path.
441-
442-
##### `Go` **WIP**
443-
444-
##### `JavaScript` - ipfs.ls(ipfsPath, [callback])
445-
446-
> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
447-
448-
ipfsPath can be of type:
449-
450-
- [`cid`][cid] of type:
451-
- [Buffer][b], the raw Buffer of the cid
452-
- String, the base58 encoded version of the cid
453-
- String, including the ipfs handler, a cid and a path to traverse to, ie:
454-
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
455-
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
456-
- 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
457-
458-
`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:
459-
460-
```js
461-
{
462-
depth: 1,
463-
name: 'alice.txt',
464-
path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
465-
size: 11696,
466-
hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
467-
type: 'file'
468-
}
469-
```
470-
471-
If no `callback` is passed, a promise is returned.
472-
473-
**Example:**
474-
475-
```JavaScript
476-
const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
477-
478-
ipfs.ls(validCID, function (err, files) {
479-
files.forEach((file) => {
480-
console.log(file.path)
481-
})
482-
})
483-
```
484-
485-
A great source of [examples][] can be found in the tests for this API.
486-
487-
#### `lsReadableStream`
488-
489-
> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams.
490-
491-
##### `Go` **WIP**
492-
493-
##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs]
494-
495-
> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
496-
497-
ipfsPath can be of type:
498-
499-
- [`cid`][cid] of type:
500-
- [Buffer][b], the raw Buffer of the cid
501-
- String, the base58 encoded version of the cid
502-
- String, including the ipfs handler, a cid and a path to traverse to, ie:
503-
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
504-
- '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
505-
- 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
506-
507-
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:
508-
509-
```js
510-
{
511-
depth: 1,
512-
name: 'alice.txt',
513-
path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
514-
size: 11696,
515-
hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
516-
type: 'file'
517-
}
518-
```
519-
520-
**Example:**
521-
522-
```JavaScript
523-
const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
524-
525-
const stream = ipfs.lsReadableStream(validCID)
526-
527-
stream.on('data', (file) => {
528-
// write the file's path and contents to standard out
529-
console.log(file.path)
530-
})
531-
```
532-
533-
A great source of [examples][] can be found in the tests for this API.
534-
535-
#### `lsPullStream`
536-
537-
> 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.
538-
539541
##### `Go` **WIP**
540542

541543
##### `JavaScript` - ipfs.lsPullStream(ipfsPath) -> [Pull Stream][ps]

0 commit comments

Comments
 (0)