feat: add fullPath option

When exporting a path with a subtree it's sometimes useful to get
information about everything in the path and not just the node
at the end.

This PR adds an option to return intermediate nodes in the export
stream.

It also documents the `maxDepth` option and lowers the sharding
threshold to make the shard tests more reliable in the browser.

Author: achingbrain

README.md

@@ -104,6 +104,91 @@ pull(
 )
 ```
 
+### `fullPath`
+
+If specified the exporter will emit an entry for every path component encountered.
+
+```javascript
+const exporter = require('ipfs-unixfs-exporter')
+const pull = require('pull-stream')
+const collect = require('pull-stream/sinks/collect')
+
+pull(
+  exporter('QmFoo.../bar/baz.txt', ipld, {
+    fullPath: true
+  })
+  collect((err, files) => {
+    console.info(files)
+
+    // [{
+    //   depth: 0,
+    //   name: 'QmFoo...',
+    //   path: 'QmFoo...',
+    //   size: ...
+    //   hash: Buffer
+    //   content: undefined
+    //   type: 'dir'
+    // }, {
+    //   depth: 1,
+    //   name: 'bar',
+    //   path: 'QmFoo.../bar',
+    //   size: ...
+    //   hash: Buffer
+    //   content: undefined
+    //   type: 'dir'
+    // }, {
+    //   depth: 2,
+    //   name: 'baz.txt',
+    //   path: 'QmFoo.../bar/baz.txt',
+    //   size: ...
+    //   hash: Buffer
+    //   content: <Pull stream>
+    //   type: 'file'
+    // }]
+    //
+  })
+)
+```
+
+### `maxDepth`
+
+If specified the exporter will only emit entries up to the specified depth.
+
+```javascript
+const exporter = require('ipfs-unixfs-exporter')
+const pull = require('pull-stream')
+const collect = require('pull-stream/sinks/collect')
+
+pull(
+  exporter('QmFoo.../bar/baz.txt', ipld, {
+    fullPath: true,
+    maxDepth: 1
+  })
+  collect((err, files) => {
+    console.info(files)
+
+    // [{
+    //   depth: 0,
+    //   name: 'QmFoo...',
+    //   path: 'QmFoo...',
+    //   size: ...
+    //   hash: Buffer
+    //   content: undefined
+    //   type: 'dir'
+    // }, {
+    //   depth: 1,
+    //   name: 'bar',
+    //   path: 'QmFoo.../bar',
+    //   size: ...
+    //   hash: Buffer
+    //   content: undefined
+    //   type: 'dir'
+    // }]
+    //
+  })
+)
+```
+
 [dag API]: https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/DAG.md
 [ipld-resolver instance]: https://github.com/ipld/js-ipld-resolver
 [UnixFS]: https://github.com/ipfs/specs/tree/master/unixfs

src/dir-flat.js

@@ -6,7 +6,7 @@ const cat = require('pull-cat')
 // Logic to export a unixfs directory.
 module.exports = dirExporter
 
-function dirExporter (cid, node, name, path, pathRest, resolve, size, dag, parent, depth) {
+function dirExporter (cid, node, name, path, pathRest, resolve, size, dag, parent, depth, options) {
   const accepts = pathRest[0]
 
   const dir = {
@@ -37,7 +37,7 @@ function dirExporter (cid, node, name, path, pathRest, resolve, size, dag, paren
   ]
 
   // place dir before if not specifying subtree
-  if (!pathRest.length) {
+  if (!pathRest.length || options.fullPath) {
     streams.unshift(pull.values([dir]))
   }
 

src/dir-hamt-sharded.js

@@ -6,7 +6,7 @@ const cat = require('pull-cat')
 // Logic to export a unixfs directory.
 module.exports = shardedDirExporter
 
-function shardedDirExporter (cid, node, name, path, pathRest, resolve, size, dag, parent, depth) {
+function shardedDirExporter (cid, node, name, path, pathRest, resolve, size, dag, parent, depth, options) {
   let dir
   if (!parent || (parent.path !== path)) {
     dir = {
@@ -49,7 +49,7 @@ function shardedDirExporter (cid, node, name, path, pathRest, resolve, size, dag
     )
   ]
 
-  if (!pathRest.length) {
+  if (!pathRest.length || options.fullPath) {
     streams.unshift(pull.values([dir]))
   }
 

src/file.js

@@ -7,7 +7,7 @@ const paramap = require('pull-paramap')
 const extractDataFromBlock = require('./extract-data-from-block')
 
 // Logic to export a single (possibly chunked) unixfs file.
-module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, depth, offset, length) => {
+module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, depth, options) => {
   const accepts = pathRest[0]
 
   if (accepts !== undefined && accepts !== path) {
@@ -24,19 +24,19 @@ module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, d
 
   const fileSize = size || file.fileSize()
 
-  if (offset < 0) {
+  if (options.offset < 0) {
     return pull.error(new Error('Offset must be greater than or equal to 0'))
   }
 
-  if (offset > fileSize) {
+  if (options.offset > fileSize) {
     return pull.error(new Error('Offset must be less than the file size'))
   }
 
-  if (length < 0) {
+  if (options.length < 0) {
     return pull.error(new Error('Length must be greater than or equal to 0'))
   }
 
-  if (length === 0) {
+  if (options.length === 0) {
     return pull.once({
       depth: depth,
       content: pull.once(Buffer.alloc(0)),
@@ -48,15 +48,15 @@ module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, d
     })
   }
 
-  if (!offset) {
-    offset = 0
+  if (!options.offset) {
+    options.offset = 0
   }
 
-  if (!length || (offset + length > fileSize)) {
-    length = fileSize - offset
+  if (!options.length || (options.offset + options.length > fileSize)) {
+    options.length = fileSize - options.offset
   }
 
-  const content = streamBytes(dag, node, fileSize, offset, length)
+  const content = streamBytes(dag, node, fileSize, options.offset, options.length)
 
   return pull.values([{
     depth: depth,

src/index.js

@@ -38,7 +38,8 @@ function pathBaseAndRest (path) {
 const defaultOptions = {
   maxDepth: Infinity,
   offset: undefined,
-  length: undefined
+  length: undefined,
+  fullPath: false
 }
 
 module.exports = (path, dag, options) => {
@@ -70,7 +71,7 @@ module.exports = (path, dag, options) => {
       return {
         depth: node.depth,
         name: node.name,
-        path: finalPathFor(node),
+        path: options.fullPath ? node.path : finalPathFor(node),
         size: node.size,
         hash: node.multihash,
         content: node.content,

src/raw.js

@@ -4,7 +4,7 @@ const pull = require('pull-stream')
 const extractDataFromBlock = require('./extract-data-from-block')
 
 // Logic to export a single raw block
-module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, depth, offset, length) => {
+module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, depth, options) => {
   const accepts = pathRest[0]
 
   if (accepts !== undefined && accepts !== path) {
@@ -13,19 +13,19 @@ module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, d
 
   size = size || node.length
 
-  if (offset < 0) {
+  if (options.offset < 0) {
     return pull.error(new Error('Offset must be greater than or equal to 0'))
   }
 
-  if (offset > size) {
+  if (options.offset > size) {
     return pull.error(new Error('Offset must be less than the file size'))
   }
 
-  if (length < 0) {
+  if (options.length < 0) {
     return pull.error(new Error('Length must be greater than or equal to 0'))
   }
 
-  if (length === 0) {
+  if (options.length === 0) {
     return pull.once({
       depth,
       content: pull.once(Buffer.alloc(0)),
@@ -37,17 +37,17 @@ module.exports = (cid, node, name, path, pathRest, resolve, size, dag, parent, d
     })
   }
 
-  if (!offset) {
-    offset = 0
+  if (!options.offset) {
+    options.offset = 0
   }
 
-  if (!length || (offset + length > size)) {
-    length = size - offset
+  if (!options.length || (options.offset + options.length > size)) {
+    options.length = size - options.offset
   }
 
   return pull.once({
     depth,
-    content: pull.once(extractDataFromBlock(node, 0, offset, offset + length)),
+    content: pull.once(extractDataFromBlock(node, 0, options.offset, options.offset + options.length)),
     hash: cid,
     name,
     path,

src/resolve.js

@@ -4,6 +4,7 @@ const UnixFS = require('ipfs-unixfs')
 const pull = require('pull-stream')
 const paramap = require('pull-paramap')
 const CID = require('cids')
+const waterfall = require('async/waterfall')
 
 const resolvers = {
   directory: require('./dir-flat'),
@@ -34,30 +35,37 @@ function createResolver (dag, options, depth, parent) {
       }
 
       if (item.object) {
-        return cb(null, resolveItem(null, item.object, item, options.offset, options.length))
+        return cb(null, resolveItem(null, item.object, item, options))
       }
 
       const cid = new CID(item.multihash)
 
-      dag.get(cid, (err, node) => {
-        if (err) {
-          return cb(err)
-        }
-
-        // const name = item.fromPathRest ? item.name : item.path
-        cb(null, resolveItem(cid, node.value, item, options.offset, options.length))
-      })
+      waterfall([
+        (done) => dag.get(cid, done),
+        (node, done) => done(null, resolveItem(cid, node.value, item, options))
+      ], cb)
     }),
     pull.flatten(),
     pull.filter(Boolean),
     pull.filter((node) => node.depth <= options.maxDepth)
   )
 
-  function resolveItem (cid, node, item, offset, length) {
-    return resolve(cid, node, item.name, item.path, item.pathRest, item.size, dag, item.parent || parent, item.depth, offset, length)
+  function resolveItem (cid, node, item, options) {
+    return resolve({
+      cid,
+      node,
+      name: item.name,
+      path: item.path,
+      pathRest: item.pathRest,
+      size: item.size,
+      dag,
+      parentNode: item.parent || parent,
+      depth: item.depth,
+      options
+    })
   }
 
-  function resolve (cid, node, name, path, pathRest, size, dag, parentNode, depth, offset, length) {
+  function resolve ({ cid, node, name, path, pathRest, size, dag, parentNode, depth, options }) {
     let type
 
     try {
@@ -67,11 +75,14 @@ function createResolver (dag, options, depth, parent) {
     }
 
     const nodeResolver = resolvers[type]
+
     if (!nodeResolver) {
       return pull.error(new Error('Unkown node type ' + type))
     }
+
     const resolveDeep = createResolver(dag, options, depth, node)
-    return nodeResolver(cid, node, name, path, pathRest, resolveDeep, size, dag, parentNode, depth, offset, length)
+
+    return nodeResolver(cid, node, name, path, pathRest, resolveDeep, size, dag, parentNode, depth, options)
   }
 }
 

test/exporter-sharded.spec.js

@@ -15,7 +15,7 @@ const randomBytes = require('./helpers/random-bytes')
 const exporter = require('../src')
 const importer = require('ipfs-unixfs-importer')
 
-const SHARD_SPLIT_THRESHOLD = 1000
+const SHARD_SPLIT_THRESHOLD = 10
 
 describe('exporter sharded', () => {
   let ipld
@@ -49,7 +49,8 @@ describe('exporter sharded', () => {
           }))
         ),
         importer(ipld, {
-          wrap: true
+          wrap: true,
+          shardSplitThreshold: SHARD_SPLIT_THRESHOLD
         }),
         pull.collect(cb)
       ),