dag api: add {ls, tree}

[jbenet]

We should add the following commands to the core/dag interface:

• ipfs.dag.ls(path) - show the first level link names of the node pointed at by <path>
  • include simple return value one, for small dag objects
  • include stream/iterator based one, for huge dag objects
• ipfs.dag.tree(path) - enumerate all entries in the graph, parting from node at <path>.
  • include simple return value one, for small subgraphs
  • stream/iterator based so that we can explore massive graphs with it.

cc @diasdavid @whyrusleeping

[jbenet]

the ipld explorers will get worked on next week. would be great to have this in before that work starts. https://hackmd.io/EYVgHApgTDAsC0BDRIDG9bCgRia2E8EiqAbAAymqojkDMiQA

[jbenet]

Example for ipfs.dag.ls

var IPFSAPI = require('ipfs-api')
var ipfs = IPFSApi('/ip4/127.0.0.1/tcp/5001')

// given an object such as: 
//
// var obj = {
//     "a": 1,
//     "b": [1, 2, 3],
//     "c": {
//         "ca": [5, 6, 7],
//         "cb": "foo"
//     }
// }
// 
// ipfs.dag.put(obj, function(err, cid2) {
//     assert(cid == zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y)
// })

ipfs.dag.ls('zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y', function(err, result) {
    for (var i in result.entries) {
        console.log(result.entries[i])
    }
})
// Returns:
// a
// b
// c

ipfs.dag.ls('zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y/c', function(err, result) {
    for (var i in result.entries) {
        console.log(result.entries[i])
    }
})
// Returns:
// ca
// cb

ipfs.dag.ls('zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y/c/ca', function(err, result) {
    for (var i in result.entries) {
        console.log(result.entries[i])
    }
})
// Returns:
// 0
// 1
// 2

[jbenet]

Example: ipfs.dag.tree

var IPFSAPI = require('ipfs-api')
var ipfs = IPFSApi('/ip4/127.0.0.1/tcp/5001')

// given an object such as: 
//
// var obj = {
//     "a": 1,
//     "b": [1, 2, 3],
//     "c": {
//         "ca": [5, 6, 7],
//         "cb": "foo"
//     }
// }
// 
// ipfs.dag.put(obj, function(err, cid2) {
//     assert(cid == zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y)
// })

ipfs.dag.tree('zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y', function(err, result) {
    for (var i in result) {
        console.log(result[i])
    }
})
// Returns:
// a
// b
// b/0
// b/1
// b/2
// c
// c/ca
// c/ca/0
// c/ca/1
// c/ca/2
// c/cb

ipfs.dag.tree('zdpuAkxd9KzGwJFGhymCZRkPCXtBmBW7mB2tTuEH11HLbES9Y/c', function(err, result) {
    for (var i in result) {
        console.log(result[i])
    }
})
// Returns:
// ca
// ca/0
// ca/1
// ca/2
// cb

[whyrusleeping]

I'm not so sure i like the way dag ls works. It doesnt give you any indication if you can list down that path further. It seems to me like we might as well just use ipfs dag tree. I implemented ls and when playing with it found myself constantly 'get'ing the object again to remember what paths i could play with

[daviddias]

From using it, I can see what @whyrusleeping issue when using ls is.

I'm adding to tree a --recursive to explicitly declare that we want to traverse through the graph or stop at the first node. This way, a user can always check what it can get under a certain CID, without having to pay the cost of traversing an entire graph. Another option to implement this is to have --level, being --level=0 equal to --recursive=false and having a default of --recursive=true. I like both.

[dignifiedquire]

I think level would be more interesting, as I can see a use case where you want to just know the next level down, but not traverse everything, which you can't do with the recursive flag.

[daviddias]

@vmx ^^