You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This will install [lerna](https://www.npmjs.com/package/lerna) and bootstrap the various packages, dedpuing and hoisting dependencies into the root folder.
43
-
44
-
If later you wish to remove all the `node_modules`/`dist` folders and start again, run `npm run reset && npm install` from the root.
45
-
46
-
See the scripts section of the root [`package.json`](./package.json) for more commands.
47
-
48
-
### Publishing new versions
49
-
50
-
1. Ensure you have a `GH_TOKEN` env var containing a GitHub [Personal Access Token](https://github.com/settings/tokens) with `public_repo` permissions
51
-
2. From the root of this repo run `npm run release` and follow the on screen prompts. It will use [conventional commits](https://www.conventionalcommits.org) to work out the new package version
52
-
53
-
### Using prerelease versions
54
-
55
-
Any changed packages from each successful build of master are published to npm as canary builds under the npm tag `next`.
56
-
57
-
Canary builds only consider changes to packages in the last built commit so changes to the root config files should not result in new prereleases being published to npm.
The UnixFS Exporter provides a means to read DAGs from a blockstore given a CID.
40
13
41
14
## Example
42
15
@@ -79,175 +52,32 @@ for await (const buf of entry.content()) {
79
52
console.info(bytes) // 0, 1, 2, 3
80
53
```
81
54
82
-
## API
83
-
84
-
```js
85
-
import { exporter } from'ipfs-unixfs-exporter'
86
-
```
87
-
88
-
### `exporter(cid, blockstore, options)`
89
-
90
-
Uses the given [blockstore][] instance to fetch an IPFS node by it's CID.
91
-
92
-
Returns a Promise which resolves to a `UnixFSEntry`.
93
-
94
-
`options` is an optional object argument that might include the following keys:
95
-
96
-
-`signal` ([AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)): Used to cancel any network requests that are initiated as a result of this export
97
-
98
-
### UnixFSEntry
55
+
# Install
99
56
100
-
```javascript
101
-
{
102
-
type:'file'// or 'directory'
103
-
name:'foo.txt',
104
-
path:'Qmbar/foo.txt',
105
-
cid:CID, // see https://github.com/multiformats/js-cid
106
-
content:function, // returns an async iterator
107
-
unixfs: UnixFS // see https://github.com/ipfs/js-ipfs-unixfs
108
-
}
109
-
```
110
-
111
-
If the entry is a file, `entry.content()` returns an async iterator that yields one or more Uint8Arrays containing the file content:
112
-
113
-
```javascript
114
-
if (entry.type === 'file') {
115
-
forawait (constchunkofentry.content()) {
116
-
// chunk is a Buffer
117
-
}
118
-
}
119
-
```
120
-
121
-
If the entry is a directory, `entry.content()` returns further `entry` objects:
122
-
123
-
```javascript
124
-
if (entry.type==='directory') {
125
-
forawait (constentryofdir.content()) {
126
-
console.info(entry.name)
127
-
}
128
-
}
129
-
```
130
-
131
-
### Raw entries
132
-
133
-
Entries with a `raw` codec `CID` return raw entries:
134
-
135
-
```javascript
136
-
{
137
-
name:'foo.txt',
138
-
path:'Qmbar/foo.txt',
139
-
cid:CID, // see https://github.com/multiformats/js-cid
140
-
node: Buffer, // see https://nodejs.org/api/buffer.html
141
-
content:function, // returns an async iterator
142
-
}
143
-
```
144
-
145
-
`entry.content()` returns an async iterator that yields a buffer containing the node content:
146
-
147
-
```javascript
148
-
for await (const chunk of entry.content()) {
149
-
// chunk is a Buffer
150
-
}
151
-
```
152
-
153
-
Unless you an options object containing `offset` and `length` keys as an argument to `entry.content()`, `chunk` will be equal to `entry.node`.
154
-
155
-
### CBOR entries
156
-
157
-
Entries with a `dag-cbor` codec `CID` return JavaScript object entries:
158
-
159
-
```javascript
160
-
{
161
-
name:'foo.txt',
162
-
path:'Qmbar/foo.txt',
163
-
cid:CID, // see https://github.com/multiformats/js-cid
164
-
node:Uint8Array,
165
-
content:function// returns an async iterator that yields a single object - see https://github.com/ipld/js-ipld-dag-cbor
166
-
}
167
-
```
168
-
169
-
There is no `content` function for a `CBOR` node.
170
-
171
-
### `entry.content({ offset, length })`
172
-
173
-
When `entry` is a file or a `raw` node, `offset` and/or `length` arguments can be passed to `entry.content()` to return slices of data:
174
-
175
-
```javascript
176
-
const length = 5
177
-
const data = new Uint8Array(length)
178
-
let offset = 0
179
-
180
-
for await (const chunk of entry.content({
181
-
offset:0,
182
-
length
183
-
})) {
184
-
data.set(chunk, offset)
185
-
offset +=chunk.length
186
-
}
187
-
188
-
// `data` contains the first 5 bytes of the file
189
-
return data
190
-
```
191
-
192
-
If `entry` is a directory, passing `offset` and/or `length` to `entry.content()` will limit the number of files returned from the directory.
193
-
194
-
```javascript
195
-
constentries= []
196
-
197
-
forawait (constentryofdir.content({
198
-
offset:0,
199
-
length:5
200
-
})) {
201
-
entries.push(entry)
202
-
}
203
-
204
-
// `entries` contains the first 5 files/directories in the directory
205
-
```
206
-
207
-
### `walkPath(cid, blockstore)`
208
-
209
-
`walkPath` will return an async iterator that yields entries for all segments in a path:
`stream` will output file info objects as files get stored in IPFS. When stats on a node are emitted they are guaranteed to have been written.
119
-
120
-
`blockstore` is an instance of a [blockstore][]
121
-
122
-
The input's file paths and directory structure will be preserved in the [`dag-pb`](https://github.com/ipld/js-dag-pb) created nodes.
123
-
124
-
### const result = await importFile(content, blockstore \[, options])
125
-
126
-
A convenience function for importing a single file or directory.
127
-
128
-
### const result = await importDirectory(content, blockstore \[, options])
129
-
130
-
A convenience function for importing a directory - note this is non-recursive, to import recursively use the [importer](#const-stream--importersource-blockstore--options) function.
131
-
132
-
### const result = await importBytes(buf, blockstore \[, options])
133
-
134
-
A convenience function for importing a single Uint8Array.
135
-
136
-
### const result = await importByteStream(source, blockstore \[, options])
137
-
138
-
A convenience function for importing a single stream of Uint8Arrays.
This module contains the protobuf definition of the UnixFS data structure found at the root of all UnixFS DAGs.
46
13
47
-
The UnixFS spec can be found inside the [ipfs/specs repository](http://github.com/ipfs/specs)
14
+
The UnixFS spec can be found in the [ipfs/specs repository](http://github.com/ipfs/specs)
48
15
49
-
### Use in Node.js
50
-
51
-
```JavaScript
52
-
import { UnixFS } from'ipfs-unixfs'
53
-
```
54
-
55
-
### Use in a browser with browserify, webpack or any other bundler
56
-
57
-
The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.
58
-
59
-
```JavaScript
60
-
import { UnixFS } from'ipfs-unixfs'
61
-
```
62
-
63
-
## Examples
64
-
65
-
### Create a file composed by several blocks
16
+
## Example - Create a file composed of several blocks
66
17
67
18
```JavaScript
68
19
constdata=newUnixFS({ type:'file' })
@@ -71,50 +22,15 @@ data.addBlockSize(256)
71
22
// ...
72
23
```
73
24
74
-
###Create a directory that contains several files
25
+
##Example - Create a directory that contains several files
75
26
76
27
Creating a directory that contains several files is achieve by creating a unixfs element that identifies a MerkleDAG node as a directory. The links of that MerkleDAG node are the files that are contained in this directory.
77
28
78
29
```JavaScript
79
30
constdata=newUnixFS({ type:'directory' })
80
31
```
81
32
82
-
### UnixFS Data Structure
83
-
84
-
```protobuf
85
-
syntax = "proto2";
86
-
87
-
message Data {
88
-
enum DataType {
89
-
Raw = 0;
90
-
Directory = 1;
91
-
File = 2;
92
-
Metadata = 3;
93
-
Symlink = 4;
94
-
HAMTShard = 5;
95
-
}
96
-
97
-
required DataType Type = 1;
98
-
optional bytes Data = 2;
99
-
optional uint64 filesize = 3;
100
-
repeated uint64 blocksizes = 4;
101
-
optional uint64 hashType = 5;
102
-
optional uint64 fanout = 6;
103
-
optional uint32 mode = 7;
104
-
optional UnixTime mtime = 8;
105
-
}
106
-
107
-
message UnixTime {
108
-
required int64 Seconds = 1;
109
-
optional fixed32 FractionalNanoseconds = 2;
110
-
}
111
-
112
-
message Metadata {
113
-
optional string MimeType = 1;
114
-
}
115
-
```
116
-
117
-
### create an unixfs Data element
33
+
## Example - Create an unixfs Data element
118
34
119
35
```JavaScript
120
36
constdata=newUnixFS([options])
@@ -134,7 +50,7 @@ const data = new UnixFS([options])
134
50
- mode (Number, default `0644` for files, `0755` for directories/hamt-sharded-directories) file mode
135
51
- mtime (`Date`, `{ secs, nsecs }`, `{ Seconds, FractionalNanoseconds }`, `[ secs, nsecs ]`): The modification time of this node
136
52
137
-
### add and remove a block size to the block size list
53
+
##Example - Add and remove a block size to the block size list
138
54
139
55
```JavaScript
140
56
data.addBlockSize(<size in bytes>)
@@ -144,20 +60,20 @@ data.addBlockSize(<size in bytes>)
Copy file name to clipboardExpand all lines: packages/ipfs-unixfs/src/index.ts
+92
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,95 @@
1
+
/**
2
+
* @packageDocumentation
3
+
*
4
+
* This module contains the protobuf definition of the UnixFS data structure found at the root of all UnixFS DAGs.
5
+
*
6
+
* The UnixFS spec can be found in the [ipfs/specs repository](http://github.com/ipfs/specs)
7
+
*
8
+
* @example Create a file composed of several blocks
9
+
*
10
+
* ```JavaScript
11
+
* const data = new UnixFS({ type: 'file' })
12
+
* data.addBlockSize(256) // add the size of each block
13
+
* data.addBlockSize(256)
14
+
* // ...
15
+
* ```
16
+
*
17
+
* @example Create a directory that contains several files
18
+
*
19
+
* Creating a directory that contains several files is achieve by creating a unixfs element that identifies a MerkleDAG node as a directory. The links of that MerkleDAG node are the files that are contained in this directory.
20
+
*
21
+
* ```JavaScript
22
+
* const data = new UnixFS({ type: 'directory' })
23
+
* ```
24
+
*
25
+
* @example Create an unixfs Data element
26
+
*
27
+
* ```JavaScript
28
+
* const data = new UnixFS([options])
29
+
* ```
30
+
*
31
+
* `options` is an optional object argument that might include the following keys:
32
+
*
33
+
* - type (string, default `file`): The type of UnixFS entry. Can be:
34
+
* - `raw`
35
+
* - `directory`
36
+
* - `file`
37
+
* - `metadata`
38
+
* - `symlink`
39
+
* - `hamt-sharded-directory`
40
+
* - data (Uint8Array): The optional data field for this node
41
+
* - blockSizes (Array, default: `[]`): If this is a `file` node that is made up of multiple blocks, `blockSizes` is a list numbers that represent the size of the file chunks stored in each child node. It is used to calculate the total file size.
42
+
* - mode (Number, default `0644` for files, `0755` for directories/hamt-sharded-directories) file mode
43
+
* - mtime (`Date`, `{ secs, nsecs }`, `{ Seconds, FractionalNanoseconds }`, `[ secs, nsecs ]`): The modification time of this node
44
+
*
45
+
* @example Add and remove a block size to the block size list
46
+
*
47
+
* ```JavaScript
48
+
* data.addBlockSize(<size in bytes>)
49
+
* ```
50
+
*
51
+
* ```JavaScript
52
+
* data.removeBlockSize(<index>)
53
+
* ```
54
+
*
55
+
* @example Get total fileSize
56
+
*
57
+
* ```JavaScript
58
+
* data.fileSize() // => size in bytes
59
+
* ```
60
+
*
61
+
* @example Marshal and unmarshal
62
+
*
63
+
* ```javascript
64
+
* const marshaled = data.marshal()
65
+
* const unmarshaled = Unixfs.unmarshal(marshaled)
66
+
* ```
67
+
*
68
+
* @example Is this UnixFS entry a directory?
69
+
*
70
+
* ```JavaScript
71
+
* const dir = new Data({ type: 'directory' })
72
+
* dir.isDirectory() // true
73
+
*
74
+
* const file = new Data({ type: 'file' })
75
+
* file.isDirectory() // false
76
+
* ```
77
+
*
78
+
* @example Has an mtime been set?
79
+
*
80
+
* If no modification time has been set, no `mtime` property will be present on the `Data` instance:
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments