object API

[daviddias]

WIP

[daviddias]

While I'm at the process of converging the interfaces between js-ipfs and js-ipfs-api, I realised that, although shimming interfaces is easy, shimming return types is not (or pretty much impossible to do right). What I concluded is that one of them has to change in order to match the other.

The second thought is that, since I'm at it, we better take the chance and use the newly defined data structs that weren't available before, for example, a object.get call doesn't need to return a JSON object anymore, since it can now return the DAGNode type we have defined. This will help make things consistent for internal dev and our users.

What do you think? //++@dignifiedquire & @haad

[haadcode]

The second thought is that, since I'm at it, we better take the chance and use the newly defined data structs that weren't available before, for example, a object.get call doesn't need to return a JSON object anymore, since it can now return the DAGNode type we have defined. This will help make things consistent for internal dev and our users.

I would stay away from using "types" as arguments as well as return types on the dev level. It's already painful enough to do ipfs.object.put(new Buffer(JSON.stringify({ Data: JSON.stringify(data) })) and would rather like to do ipfs.object.put(data) where data is any type of data. Same for object.get, I would like it to return { Data: <same as data>, Links: [] }.

DAGNode is internal to ipfs, but shouldn't be required for devs to wrap their heads around/require in their js file.

Does that answer your question?

[daviddias]

@haadcode @dignifiedquire, I've finished setting up the interface for Object. @haadcode as requested, here goes an example for object put and get

var obj = {
  Data: new Buffer('hey yo')
  Links: []
}
ipfs.object.put(obj, function (err, dagNode) {
  expect(err).to.not.exist
  expect(dagNode.json()).to.deep.equal(obj)
  var mh = dagNode.multihash() // multihash of this object

  ipfs.object.get(mh, function (err, dagNode2) {
    expect(err).to.not.exist
    expect(dagNode).to.deep.equal(dagNode2)
  })
})

This is a straight example, if you check the interface description, it keeps the promise interface and the new Buffer(JSON.stringify(obj)) by specifying the encoding as json as well :)

[dignifiedquire]

@diasdavid I would suggest to use dagNode.toJSON() to be consistent with built in methods like Date.prototype.toJSON()

[dignifiedquire]

I'm guessing all these except for null are meant to be strings?

[daviddias]

exactly

[daviddias]

@dignifiedquire sounds good, I like that better as well :)

[haadcode]

What would dagNode.toJSON() return? this { Data: 'hey yo' Links: [] } ?

Can one do ipfs.object.put(new Buffer('hey yo'), ...)?
Can one do ipfs.object.put('hey yo', ...)?

Can we have dagNode.Hash and dagNode.Links getters?

[daviddias]

What would dagNode.toJSON() return? this { Data: 'hey yo' Links: [] } ?

Yep :)

Can one do ipfs.object.put(new Buffer('hey yo'), ...)?

It would be able to do:
`ipfs.object.put( {data: new Buffer('hey yo')}..)

Can one do ipfs.object.put('hey yo', ...)?

Similar to the previous, we can support it, but since that the Data field is always a Buffer, it might get confusing for folks, better tell them to use Buffers

Can we have dagNode.Hash and dagNode.Links getters?

That is already there, but with .multihash() instead

[dignifiedquire]

I would really like to see at least ipfs.object.put(new Buffer('hey yo'),..) be supported without the {data} wrapper

[haadcode]

Can we have dagNode.Hash and dagNode.Links getters?
That is already there, but with .multihash() instead

These would be purely for convenience but would help to keep the current js-ipfs-api return value (object) on par with the js-ipfs.

result.Hash.startsWith(...)
result.multihash().startsWith(...)
result.toJSON().Hash.startsWith(...)

Otherwise looks good and you're right about the string vs. always buffer as the argument. Let's always require the full { Data: ..., Links: ... } object or a buffer ipfs.object.put(new Buffer('hey yo'),..) ?

[daviddias]

I would really like to see at least ipfs.object.put(new Buffer('hey yo'),..) be supported without the {data} wrapper

@dignifiedquire @haadcode the hard part of being able to put a Buffer directly, is the fact that we might indeed to send another serialised format, that go-ipfs, in a Buffer.

[dignifiedquire]

sure, but we could make this the default options object: {enc: 'json'} that way object.put(new Buffer('hello world')) works and you can always pass a different encoding to change it via the options

[daviddias]

If we default the encoding to JSON when passing the Buffer, then the Buffer should contain something like: new Buffer(JSON.stringify({data: new Buffer('hello world'), links: []))

[dignifiedquire]

lets have a call tomorrow about this..

[daviddias]

verdict

• no default encoding
• if Buffer is passed with no encoding specified, it is created a DAGNode with that Buffer as Data

[haadcode]

So the final version is:
ipfs.object.put(new Buffer('hello'), ...)
ipfs.object.put({ Data: new Buffer('hello') }, ...)
ipfs.object.put(new DAGNode('hello'), ...) (for the sake of example, fist arg is the data)

Correct?

These all do the same, and return a DAGNode where node.Data ==> 'hello', correct?
And node.Hash returns the multihash?

[daviddias]

Yes, Yes and no, following the same case as before, new DAGNode(new Buffer('hello'))

node.Data is the data
node.Links are the links
node.multihash() will return the multihash