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

Commit 4c58485

Browse files
author
Alan Shaw
authored
refactor: object API write methods return CIDs (#399)
Since `ipld-dag-pb` removed `multihash` and `cid` properties, the Object API became less useful, returning the data you provided it when you call methods that write DAG nodes. This meant the user had to calculate the CID manually. This PR updates the Object API so that write methods return CID instances instead of DAG nodes. See discussion here for more context: #388 (review) License: MIT Signed-off-by: Alan Shaw <[email protected]>
1 parent 5d09dd2 commit 4c58485

File tree

14 files changed

+284
-428
lines changed

14 files changed

+284
-428
lines changed

‎SPEC/OBJECT.md

+35-35
Original file line numberDiff line numberDiff line change
@@ -17,22 +17,22 @@
1717
1818
##### `Go` **WIP**
1919

20-
##### `JavaScript` - ipfs.object.new([template][, callback])
20+
##### `JavaScript` - ipfs.object.new([template], [callback])
2121

2222
`template` if defined, must be a string `unixfs-dir` and if that is passed, the created node will be an empty unixfs style directory.
2323

24-
`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][]
24+
`callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and `cid` is an instance of [CID][].
2525

2626
If no `callback` is passed, a [promise][] is returned.
2727

2828
**Example:**
2929

3030
```JavaScript
31-
ipfs.object.new('unixfs-dir', (err, node) => {
31+
ipfs.object.new('unixfs-dir', (err, cid) => {
3232
if (err) {
3333
throw err
3434
}
35-
console.log(node.toJSON().multihash)
35+
console.log(cid.toString())
3636
// Logs:
3737
// QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn
3838
})
@@ -46,7 +46,7 @@ A great source of [examples][] can be found in the tests for this API.
4646
4747
##### `Go` **WIP**
4848

49-
##### `JavaScript` - ipfs.object.put(obj, [options, callback])
49+
##### `JavaScript` - ipfs.object.put(obj, [options], [callback])
5050

5151
`obj` is the MerkleDAG Node to be stored. Can of type:
5252

@@ -58,7 +58,7 @@ A great source of [examples][] can be found in the tests for this API.
5858

5959
- `enc`, the encoding of the Buffer (json, yml, etc), if passed a Buffer.
6060

61-
`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][]
61+
`callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and `cid` is an instance of [CID][].
6262

6363
If no `callback` is passed, a [promise][] is returned.
6464

@@ -70,11 +70,11 @@ const obj = {
7070
Links: []
7171
}
7272

73-
ipfs.object.put(obj, (err, node) => {
73+
ipfs.object.put(obj, (err, cid) => {
7474
if (err) {
7575
throw err
7676
}
77-
console.log(node.toJSON().multihash)
77+
console.log(cid.toString())
7878
// Logs:
7979
// QmPb5f92FxKPYdT3QNBd1GKiL4tZUXUrzF4Hkpdr3Gf1gK
8080
})
@@ -88,7 +88,7 @@ A great source of [examples][] can be found in the tests for this API.
8888
8989
##### `Go` **WIP**
9090

91-
##### `JavaScript` - ipfs.object.get(multihash, [options, callback])
91+
##### `JavaScript` - ipfs.object.get(multihash, [options], [callback])
9292

9393
`multihash` is a [multihash][] which can be passed as:
9494

@@ -112,9 +112,9 @@ ipfs.object.get(multihash, (err, node) => {
112112
if (err) {
113113
throw err
114114
}
115-
console.log(node.toJSON().multihash)
115+
console.log(node.data)
116116
// Logs:
117-
// QmPb5f92FxKPYdT3QNBd1GKiL4tZUXUrzF4Hkpdr3Gf1gK
117+
// some data
118118
})
119119
```
120120

@@ -126,7 +126,7 @@ A great source of [examples][] can be found in the tests for this API.
126126
127127
##### `Go` **WIP**
128128

129-
##### `JavaScript` - ipfs.object.data(multihash, [options, callback])
129+
##### `JavaScript` - ipfs.object.data(multihash, [options], [callback])
130130
`multihash` is a [multihash][] which can be passed as:
131131

132132
- Buffer, the raw Buffer of the multihash (or of and encoded version)
@@ -163,7 +163,7 @@ A great source of [examples][] can be found in the tests for this API.
163163
164164
##### `Go` **WIP**
165165

166-
##### `JavaScript` - ipfs.object.links(multihash, [options, callback])
166+
##### `JavaScript` - ipfs.object.links(multihash, [options], [callback])
167167

168168
`multihash` is a [multihash][] which can be passed as:
169169

@@ -201,7 +201,7 @@ A great source of [examples][] can be found in the tests for this API.
201201
202202
##### `Go` **WIP**
203203

204-
##### `JavaScript` - ipfs.object.stat(multihash, [options, callback])
204+
##### `JavaScript` - ipfs.object.stat(multihash, [options], [callback])
205205

206206
`multihash` is a [multihash][] which can be passed as:
207207

@@ -261,7 +261,7 @@ A great source of [examples][] can be found in the tests for this API.
261261
262262
###### `Go` **WIP**
263263

264-
###### `JavaScript` - ipfs.object.patch.addLink(multihash, link, [options, callback])
264+
###### `JavaScript` - ipfs.object.patch.addLink(multihash, link, [options], [callback])
265265

266266
`multihash` is a [multihash][] which can be passed as:
267267

@@ -290,7 +290,7 @@ const link = new DAGLink(name, size, multihash)
290290

291291
- `enc`, the encoding of multihash (base58, base64, etc), if any.
292292

293-
`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link.
293+
`callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and `cid` is an instance of [CID][] - the CID of the new DAG node that was created due to the operation.
294294

295295
If no `callback` is passed, a [promise][] is returned.
296296

@@ -301,11 +301,11 @@ ipfs.object.patch.addLink(node, {
301301
name: 'some-link'
302302
size: 10
303303
multihash: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD'
304-
}, (err, newNode) => {
304+
}, (err, cid) => {
305305
if (err) {
306306
throw err
307307
}
308-
// newNode is node with the added link
308+
// cid is CID of the DAG node created by adding a link
309309
})
310310
```
311311

@@ -317,34 +317,34 @@ A great source of [examples][] can be found in the tests for this API.
317317
318318
###### `Go` **WIP**
319319

320-
###### `JavaScript` - ipfs.object.patch.rmLink(multihash, link, [options, callback])
320+
###### `JavaScript` - ipfs.object.patch.rmLink(multihash, link, [options], [callback])
321321

322322
`multihash` is a [multihash][] which can be passed as:
323323

324324
- Buffer, the raw Buffer of the multihash (or of and encoded version)
325325
- String, the toString version of the multihash (or of an encoded version)
326326

327327
`link` is the link to be removed on the node that is identified by the `multihash`, can be passed as:
328+
328329
- `DAGLink`
329-
- Object containing name property
330330

331-
```js
332-
const link = {
333-
name: 'Qmef7ScwzJUCg1zUSrCmPAz45m8uP5jU7SLgt2EffjBmbL'
334-
};
335-
```
331+
```js
332+
const link = new DAGLink(name, size, multihash)
333+
```
336334

337-
or
335+
- Object containing a `name` property
338336

339-
```js
340-
const link = new DAGLink(name, size, multihash)
337+
```js
338+
const link = {
339+
name: 'Qmef7ScwzJUCg1zUSrCmPAz45m8uP5jU7SLgt2EffjBmbL'
340+
};
341341
```
342342

343343
`options` is a optional argument of type object, that can contain the following properties:
344344

345345
- `enc`, the encoding of multihash (base58, base64, etc), if any.
346346

347-
`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link.
347+
`callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and `cid` is an instance of [CID][] - the CID of the new DAG node that was created due to the operation.
348348

349349
If no `callback` is passed, a [promise][] is returned.
350350

@@ -361,7 +361,7 @@ A great source of [examples][] can be found in the tests for this API.
361361

362362
###### `Go` **WIP**
363363

364-
###### `JavaScript` - ipfs.object.patch.appendData(multihash, data, [options, callback])
364+
###### `JavaScript` - ipfs.object.patch.appendData(multihash, data, [options], [callback])
365365

366366
`multihash` is a [multihash][] which can be passed as:
367367

@@ -374,7 +374,7 @@ A great source of [examples][] can be found in the tests for this API.
374374

375375
- `enc`, the encoding of multihash (base58, base64, etc), if any.
376376

377-
`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link.
377+
`callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and `cid` is an instance of [CID][] - the CID of the new DAG node that was created due to the operation.
378378

379379
If no `callback` is passed, a [promise][] is returned.
380380

@@ -396,7 +396,7 @@ A great source of [examples][] can be found in the tests for this API.
396396

397397
###### `Go` **WIP**
398398

399-
###### `JavaScript` - ipfs.object.patch.setData(multihash, data, [options, callback])
399+
###### `JavaScript` - ipfs.object.patch.setData(multihash, data, [options], [callback])
400400

401401
`multihash` is a [multihash][] which can be passed as:
402402

@@ -409,23 +409,23 @@ A great source of [examples][] can be found in the tests for this API.
409409

410410
- `enc`, the encoding of multihash (base58, base64, etc), if any.
411411

412-
`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link.
412+
`callback` must follow `function (err, cid) {}` signature, where `err` is an error if the operation was not successful and `cid` is an instance of [CID][] - the CID of the new DAG node that was created due to the operation.
413413

414414
If no `callback` is passed, a [promise][] is returned.
415415

416416
**Example:**
417417

418418
```JavaScript
419-
ipfs.object.patch.setData(multihash, new Buffer('more data'), (err, node) => {
419+
ipfs.object.patch.setData(multihash, new Buffer('more data'), (err, cid) => {
420420
if (err) {
421421
throw err
422422
}
423423
})
424-
425424
```
426425

427426
A great source of [examples][] can be found in the tests for this API.
428427

428+
[CID]: https://github.com/multiformats/js-cid
429429
[DAGNode]: https://github.com/ipld/js-ipld-dag-pb
430430
[multihash]: http://github.com/multiformats/multihash
431431
[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

‎SPEC/TYPES.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,4 @@ A set of data types are exposed directly from the IPFS instance under `ipfs.type
88
- [`ipfs.types.multiaddr`](https://github.com/multiformats/js-multiaddr)
99
- [`ipfs.types.multibase`](https://github.com/multiformats/multibase)
1010
- [`ipfs.types.multihash`](https://github.com/multiformats/js-multihash)
11-
- [`ipfs.types.CID`](https://github.com/ipld/js-cid)
12-
- [`ipfs.types.dagPB`](https://github.com/ipld/js-ipld-dag-pb)
13-
- [`ipfs.types.dagCBOR`](https://github.com/ipld/js-ipld-dag-cbor)
11+
- [`ipfs.types.CID`](https://github.com/multiformats/js-cid)

‎js/src/object/data.js

+29-45
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@
55
const bs58 = require('bs58')
66
const hat = require('hat')
77
const { getDescribe, getIt, expect } = require('../utils/mocha')
8-
const {
9-
calculateCid
10-
} = require('../utils/dag-pb')
118

129
module.exports = (createCommon, options) => {
1310
const describe = getDescribe(options)
@@ -42,23 +39,19 @@ module.exports = (createCommon, options) => {
4239
Links: []
4340
}
4441

45-
ipfs.object.put(testObj, (err, node) => {
42+
ipfs.object.put(testObj, (err, nodeCid) => {
4643
expect(err).to.not.exist()
4744

48-
calculateCid(node, (err, nodeCid) => {
45+
ipfs.object.data(nodeCid, (err, data) => {
4946
expect(err).to.not.exist()
5047

51-
ipfs.object.data(nodeCid, (err, data) => {
52-
expect(err).to.not.exist()
53-
54-
// because js-ipfs-api can't infer
55-
// if the returned Data is Buffer or String
56-
if (typeof data === 'string') {
57-
data = Buffer.from(data)
58-
}
59-
expect(node.data).to.eql(data)
60-
done()
61-
})
48+
// because js-ipfs-api can't infer
49+
// if the returned Data is Buffer or String
50+
if (typeof data === 'string') {
51+
data = Buffer.from(data)
52+
}
53+
expect(testObj.Data).to.eql(data)
54+
done()
6255
})
6356
})
6457
})
@@ -69,16 +62,15 @@ module.exports = (createCommon, options) => {
6962
Links: []
7063
}
7164

72-
const node = await ipfs.object.put(testObj)
73-
const nodeCid = await calculateCid(node)
65+
const nodeCid = await ipfs.object.put(testObj)
7466
let data = await ipfs.object.data(nodeCid)
7567

7668
// because js-ipfs-api can't infer
7769
// if the returned Data is Buffer or String
7870
if (typeof data === 'string') {
7971
data = Buffer.from(data)
8072
}
81-
expect(node.data).to.deep.equal(data)
73+
expect(testObj.Data).to.deep.equal(data)
8274
})
8375

8476
it('should get data by base58 encoded multihash', (done) => {
@@ -87,23 +79,19 @@ module.exports = (createCommon, options) => {
8779
Links: []
8880
}
8981

90-
ipfs.object.put(testObj, (err, node) => {
82+
ipfs.object.put(testObj, (err, nodeCid) => {
9183
expect(err).to.not.exist()
9284

93-
calculateCid(node, (err, nodeCid) => {
85+
ipfs.object.data(bs58.encode(nodeCid.buffer), { enc: 'base58' }, (err, data) => {
9486
expect(err).to.not.exist()
9587

96-
ipfs.object.data(bs58.encode(nodeCid.buffer), { enc: 'base58' }, (err, data) => {
97-
expect(err).to.not.exist()
98-
99-
// because js-ipfs-api can't infer
100-
// if the returned Data is Buffer or String
101-
if (typeof data === 'string') {
102-
data = Buffer.from(data)
103-
}
104-
expect(node.data).to.eql(data)
105-
done()
106-
})
88+
// because js-ipfs-api can't infer
89+
// if the returned Data is Buffer or String
90+
if (typeof data === 'string') {
91+
data = Buffer.from(data)
92+
}
93+
expect(testObj.Data).to.eql(data)
94+
done()
10795
})
10896
})
10997
})
@@ -114,23 +102,19 @@ module.exports = (createCommon, options) => {
114102
Links: []
115103
}
116104

117-
ipfs.object.put(testObj, (err, node) => {
105+
ipfs.object.put(testObj, (err, nodeCid) => {
118106
expect(err).to.not.exist()
119107

120-
calculateCid(node, (err, nodeCid) => {
108+
ipfs.object.data(bs58.encode(nodeCid.buffer).toString(), { enc: 'base58' }, (err, data) => {
121109
expect(err).to.not.exist()
122110

123-
ipfs.object.data(bs58.encode(nodeCid.buffer).toString(), { enc: 'base58' }, (err, data) => {
124-
expect(err).to.not.exist()
125-
126-
// because js-ipfs-api can't infer if the
127-
// returned Data is Buffer or String
128-
if (typeof data === 'string') {
129-
data = Buffer.from(data)
130-
}
131-
expect(node.data).to.eql(data)
132-
done()
133-
})
111+
// because js-ipfs-api can't infer if the
112+
// returned Data is Buffer or String
113+
if (typeof data === 'string') {
114+
data = Buffer.from(data)
115+
}
116+
expect(testObj.Data).to.eql(data)
117+
done()
134118
})
135119
})
136120
})

0 commit comments

Comments
 (0)