@helia/car 5.0.1 → 5.1.0

package/dist/src/index.js

@@ -23,7 +23,9 @@
  * const c = car(helia)
  * const out = nodeFs.createWriteStream('example.car')
  *
- * for await (const buf of c.export(cid)) {
+ * for await (const buf of c.export(cid, {
+ *   signal: AbortSignal.timeout(5_000)
+ * })) {
  *   out.write(buf)
  * }
  *
@@ -32,6 +34,14 @@
  *
  * @example Exporting a part of a UnixFS DAG as a CAR file
  *
+ * Here the graph traversal will start at `root` and include the blocks for
+ * `root`, `/foo`, `/bar`, and all the blocks that make up `baz.txt`.
+ *
+ * If there are other files/directories in the UnixFS DAG under `root`, they
+ * will not be included.
+ *
+ * `root` will be the only entry in the CAR file roots.
+ *
  * ```typescript
  * import { createHelia } from 'helia'
  * import { car, UnixFSPath } from '@helia/car'
@@ -39,12 +49,13 @@
  * import nodeFs from 'node:fs'
  *
  * const helia = await createHelia()
- * const cid = CID.parse('QmFoo...')
+ * const root = CID.parse('QmFoo...')
  *
  * const c = car(helia)
  * const out = nodeFs.createWriteStream('example.car')
  *
- * for await (const buf of c.export(cid, {
+ * for await (const buf of c.export(root, {
+ *   signal: AbortSignal.timeout(5_000),
  *   traversal: new UnixFSPath('/foo/bar/baz.txt')
  * })) {
  *   out.write(buf)
@@ -53,6 +64,43 @@
  * out.end()
  * ```
  *
+ * @example Including traversal path above the root in a CAR
+ *
+ * The `includeTraversalBlocks` option will include the traversal blocks in the
+ * CAR when they would otherwise be excluded (for example when the traversal
+ * starts in a parent of the export root).
+ *
+ * Here `baz` is the CID for `baz.txt`.
+ *
+ * The CAR file will include the blocks for `parent`, `/foo`, `/bar`, and
+ * `/baz.txt`.
+ *
+ * `baz` will be the only entry in the CAR file roots.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ * import nodeFs from 'node:fs'
+ *
+ * const helia = await createHelia()
+ * const parent = CID.parse('QmFoo...')
+ * const baz = CID.parse('QmBar...')
+ *
+ * const c = car(helia)
+ * const out = nodeFs.createWriteStream('example.car')
+ *
+ * for await (const buf of c.export(baz, {
+ *   signal: AbortSignal.timeout(5_000),
+ *   traversal: new UnixFSPath(parent, '/foo/bar/baz.txt'),
+ *   includeTraversalBlocks: true
+ * })) {
+ *   out.write(buf)
+ * }
+ *
+ * out.end()
+ * ```
+ *
  * @example Importing all blocks from a CAR file
  *
  * ```typescript
@@ -72,7 +120,9 @@
  * const reader = await CarReader.fromIterable(inStream)
  *
  * const c = car(helia)
- * await c.import(reader)
+ * await c.import(reader, {
+ *   signal: AbortSignal.timeout(5_000)
+ * })
  * ```
  */
 import { Car as CarClass } from './car.js';
@@ -81,7 +131,7 @@ export * from './traversal-strategies/index.js';
 /**
  * Create a {@link Car} instance for use with {@link https://github.com/ipfs/helia Helia}
  */
-export function car(helia, init = {}) {
-    return new CarClass(helia, init);
+export function car(helia) {
+    return new CarClass(helia);
 }
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,UAAU,CAAA;AAgD1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA;AAgF/C;;GAEG;AACH,MAAM,UAAU,GAAG,CAAE,KAAoB,EAAE,OAAY,EAAE;IACvD,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;AAClC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8HG;AAEH,OAAO,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,UAAU,CAAA;AA0C1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA;AAuF/C;;GAEG;AACH,MAAM,UAAU,GAAG,CAAE,KAAoB;IACvC,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC"}

package/dist/src/traversal-strategies/cid-path.d.ts

@@ -1,16 +1,19 @@
 import type { TraversalStrategy } from '../index.js';
-import type { BlockView } from 'multiformats/block/interface';
+import type { CodecLoader } from '@helia/interface';
+import type { AbortOptions } from '@libp2p/interface';
+import type { Blockstore } from 'interface-blockstore';
+import type { BlockView } from 'multiformats';
 import type { CID } from 'multiformats/cid';
 /**
  * Simple strategy that traverses a known path to a target CID.
  *
  * All this strategy does is yield the next CID in the known path.
+ *
+ * The path should end with the CID to be exported
  */
 export declare class CIDPath implements TraversalStrategy {
-    private readonly pathToTarget;
-    private readonly target;
-    constructor(pathToTarget: CID[]);
-    isTarget(cid: CID): boolean;
-    traverse<T extends BlockView<any, any, any, 0 | 1>>(cid: CID, _block?: T): AsyncGenerator<CID, void, undefined>;
+    private readonly path;
+    constructor(path: CID[]);
+    traverse(root: CID, blockstore: Blockstore, getCodec: CodecLoader, options?: AbortOptions): AsyncGenerator<BlockView<unknown, number, number, 0 | 1>, void, undefined>;
 }
 //# sourceMappingURL=cid-path.d.ts.map

package/dist/src/traversal-strategies/cid-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cid-path.d.ts","sourceRoot":"","sources":["../../../src/traversal-strategies/cid-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,iBAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAO;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAK;gBAEf,YAAY,EAAE,GAAG,EAAE;IAKhC,QAAQ,CAAE,GAAG,EAAE,GAAG,GAAG,OAAO;IAIpB,QAAQ,CAAE,CAAC,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC;CAMzH"}
+{"version":3,"file":"cid-path.d.ts","sourceRoot":"","sources":["../../../src/traversal-strategies/cid-path.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C;;;;;;GAMG;AACH,qBAAa,OAAQ,YAAW,iBAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;gBAEf,IAAI,EAAE,GAAG,EAAE;IAIhB,QAAQ,CAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;CAkChL"}

package/dist/src/traversal-strategies/cid-path.js

@@ -1,22 +1,45 @@
+import toBuffer from 'it-to-buffer';
+import { createUnsafe } from 'multiformats/block';
+import { InvalidTraversalError, NotDescendantError } from '../errors.js';
 /**
  * Simple strategy that traverses a known path to a target CID.
  *
  * All this strategy does is yield the next CID in the known path.
+ *
+ * The path should end with the CID to be exported
  */
 export class CIDPath {
-    pathToTarget;
-    target;
-    constructor(pathToTarget) {
-        this.pathToTarget = pathToTarget;
-        this.target = pathToTarget[pathToTarget.length - 1];
-    }
-    isTarget(cid) {
-        return this.target.equals(cid);
+    path;
+    constructor(path) {
+        this.path = path;
     }
-    async *traverse(cid, _block) {
-        const givenCidIndex = this.pathToTarget.indexOf(cid);
-        const nextCid = this.pathToTarget[givenCidIndex + 1];
-        yield nextCid;
+    async *traverse(root, blockstore, getCodec, options) {
+        if (!this.path.some(c => c.equals(root))) {
+            throw new InvalidTraversalError(`CIDPath traversal must include ${root}`);
+        }
+        let parentBlock;
+        for (const cid of this.path) {
+            if (parentBlock != null) {
+                let isChild = false;
+                for (const [, child] of parentBlock.links()) {
+                    if (child.equals(cid)) {
+                        isChild = true;
+                        break;
+                    }
+                }
+                if (!isChild) {
+                    throw new NotDescendantError(`${cid} is not a child of ${parentBlock.cid}`);
+                }
+            }
+            const bytes = await toBuffer(blockstore.get(cid, options));
+            const block = createUnsafe({
+                cid,
+                bytes,
+                codec: await getCodec(cid.code)
+            });
+            parentBlock = block;
+            yield block;
+        }
     }
 }
 //# sourceMappingURL=cid-path.js.map

package/dist/src/traversal-strategies/cid-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"cid-path.js","sourceRoot":"","sources":["../../../src/traversal-strategies/cid-path.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACD,YAAY,CAAO;IACnB,MAAM,CAAK;IAE5B,YAAa,YAAmB;QAC9B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACrD,CAAC;IAED,QAAQ,CAAE,GAAQ;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAChC,CAAC;IAED,KAAK,CAAC,CAAE,QAAQ,CAA6C,GAAQ,EAAE,MAAU;QAC/E,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,aAAa,GAAG,CAAC,CAAC,CAAA;QAEpD,MAAM,OAAO,CAAA;IACf,CAAC;CACF"}
+{"version":3,"file":"cid-path.js","sourceRoot":"","sources":["../../../src/traversal-strategies/cid-path.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAQxE;;;;;;GAMG;AACH,MAAM,OAAO,OAAO;IACD,IAAI,CAAO;IAE5B,YAAa,IAAW;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,CAAE,QAAQ,CAAE,IAAS,EAAE,UAAsB,EAAE,QAAqB,EAAE,OAAsB;QAChG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,qBAAqB,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAA;QAC3E,CAAC;QAED,IAAI,WAAkE,CAAA;QAEtE,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;gBACxB,IAAI,OAAO,GAAG,KAAK,CAAA;gBAEnB,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;oBAC5C,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;wBACtB,OAAO,GAAG,IAAI,CAAA;wBACd,MAAK;oBACP,CAAC;gBACH,CAAC;gBAED,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,MAAM,IAAI,kBAAkB,CAAC,GAAG,GAAG,sBAAsB,WAAW,CAAC,GAAG,EAAE,CAAC,CAAA;gBAC7E,CAAC;YACH,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAA;YAC1D,MAAM,KAAK,GAAG,YAAY,CAAC;gBACzB,GAAG;gBACH,KAAK;gBACL,KAAK,EAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;aAChC,CAAC,CAAA;YAEF,WAAW,GAAG,KAAK,CAAA;YACnB,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;CACF"}

package/dist/src/traversal-strategies/graph-search.d.ts

@@ -1,14 +1,22 @@
 import type { TraversalStrategy } from '../index.js';
-import type { BlockView } from 'multiformats/block/interface';
+import type { CodecLoader } from '@helia/interface';
+import type { AbortOptions } from '@libp2p/interface';
+import type { Blockstore } from 'interface-blockstore';
+import type { BlockView } from 'multiformats';
 import type { CID } from 'multiformats/cid';
+export interface GraphSearchOptions {
+    strategy?: 'depth-first' | 'breadth-first';
+}
 /**
- * A traversal strategy that performs a breadth-first search (so as to not load blocks unnecessarily) looking for a
- * target CID. Traversal stops when we reach the target CID or run out of nodes.
+ * A traversal strategy that performs a depth-first search looking for a target
+ * CID.
  */
 export declare class GraphSearch implements TraversalStrategy {
-    private readonly target;
-    constructor(target: CID);
-    isTarget(cid: CID): boolean;
-    traverse<T extends BlockView<any, any, any, 0 | 1>>(cid: CID, block: T): AsyncGenerator<CID, void, undefined>;
+    private haystack?;
+    private readonly needle;
+    private readonly options?;
+    constructor(needle: CID, options?: GraphSearchOptions);
+    constructor(haystack: CID, needle: CID, options?: GraphSearchOptions);
+    traverse(root: CID, blockstore: Blockstore, getCodec: CodecLoader, options?: AbortOptions): AsyncGenerator<BlockView<unknown, number, number, 0 | 1>, void, undefined>;
 }
 //# sourceMappingURL=graph-search.d.ts.map

package/dist/src/traversal-strategies/graph-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-search.d.ts","sourceRoot":"","sources":["../../../src/traversal-strategies/graph-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C;;;GAGG;AACH,qBAAa,WAAY,YAAW,iBAAiB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAK;gBAEf,MAAM,EAAE,GAAG;IAIxB,QAAQ,CAAE,GAAG,EAAE,GAAG,GAAG,OAAO;IAIpB,QAAQ,CAAE,CAAC,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC;CAKvH"}
+{"version":3,"file":"graph-search.d.ts","sourceRoot":"","sources":["../../../src/traversal-strategies/graph-search.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,aAAa,GAAG,eAAe,CAAA;CAC3C;AAMD;;;GAGG;AACH,qBAAa,WAAY,YAAW,iBAAiB;IACnD,OAAO,CAAC,QAAQ,CAAC,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAoB;gBAEhC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,kBAAkB;gBACzC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,kBAAkB;IAgB7D,QAAQ,CAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;CAmChL"}

package/dist/src/traversal-strategies/graph-search.js

@@ -1,19 +1,65 @@
+import { breadthFirstWalker, depthFirstWalker } from '@helia/utils';
+import { InvalidParametersError } from '@libp2p/interface';
+import toBuffer from 'it-to-buffer';
+import { createUnsafe } from 'multiformats/block';
+import { InvalidTraversalError } from "../errors.js";
+function isCID(obj) {
+    return obj != null && obj?.asCID === obj;
+}
 /**
- * A traversal strategy that performs a breadth-first search (so as to not load blocks unnecessarily) looking for a
- * target CID. Traversal stops when we reach the target CID or run out of nodes.
+ * A traversal strategy that performs a depth-first search looking for a target
+ * CID.
  */
 export class GraphSearch {
-    target;
-    constructor(target) {
-        this.target = target;
-    }
-    isTarget(cid) {
-        return this.target.equals(cid);
+    haystack;
+    needle;
+    options;
+    constructor(...args) {
+        if (isCID(args[0])) {
+            if (isCID(args[1])) {
+                this.haystack = args[0];
+                this.needle = args[1];
+                this.options = args[2];
+            }
+            else {
+                this.needle = args[0];
+                this.options = args[1];
+            }
+        }
+        else {
+            throw new InvalidParametersError('needle must be specified');
+        }
     }
-    async *traverse(cid, block) {
-        for (const [, linkedCid] of block.links()) {
-            yield linkedCid;
+    async *traverse(root, blockstore, getCodec, options) {
+        const start = this.haystack ?? root;
+        let walker;
+        if (this.options?.strategy === 'breadth-first') {
+            walker = breadthFirstWalker({
+                blockstore,
+                getCodec
+            });
+        }
+        else {
+            walker = depthFirstWalker({
+                blockstore,
+                getCodec
+            });
+        }
+        for await (const node of walker.walk(start, options)) {
+            if (node.block.cid.equals(this.needle)) {
+                for (const cid of node.path) {
+                    const bytes = await toBuffer(blockstore.get(cid, options));
+                    const block = createUnsafe({
+                        cid,
+                        bytes,
+                        codec: await getCodec(cid.code)
+                    });
+                    yield block;
+                }
+                return;
+            }
         }
+        throw new InvalidTraversalError(`${this.needle} was not a child of ${start}`);
     }
 }
 //# sourceMappingURL=graph-search.js.map

package/dist/src/traversal-strategies/graph-search.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-search.js","sourceRoot":"","sources":["../../../src/traversal-strategies/graph-search.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,OAAO,WAAW;IACL,MAAM,CAAK;IAE5B,YAAa,MAAW;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,QAAQ,CAAE,GAAQ;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAChC,CAAC;IAED,KAAK,CAAC,CAAE,QAAQ,CAA6C,GAAQ,EAAE,KAAQ;QAC7E,KAAK,MAAM,CAAC,EAAE,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;YAC1C,MAAM,SAAS,CAAA;QACjB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"graph-search.js","sourceRoot":"","sources":["../../../src/traversal-strategies/graph-search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,QAAQ,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAapD,SAAS,KAAK,CAAE,GAAS;IACvB,OAAO,GAAG,IAAI,IAAI,IAAI,GAAG,EAAE,KAAK,KAAK,GAAG,CAAA;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,WAAW;IACd,QAAQ,CAAM;IACL,MAAM,CAAK;IACX,OAAO,CAAqB;IAI7C,YAAa,GAAG,IAAW;QACzB,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnB,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;gBACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;gBACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;YACxB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;gBACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;YACxB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,sBAAsB,CAAC,0BAA0B,CAAC,CAAA;QAC9D,CAAC;IACH,CAAC;IAED,KAAK,CAAC,CAAE,QAAQ,CAAE,IAAS,EAAE,UAAsB,EAAE,QAAqB,EAAE,OAAsB;QAChG,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAA;QACnC,IAAI,MAAmB,CAAA;QAEvB,IAAI,IAAI,CAAC,OAAO,EAAE,QAAQ,KAAK,eAAe,EAAE,CAAC;YAC/C,MAAM,GAAG,kBAAkB,CAAC;gBAC1B,UAAU;gBACV,QAAQ;aACT,CAAC,CAAA;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,gBAAgB,CAAC;gBACxB,UAAU;gBACV,QAAQ;aACT,CAAC,CAAA;QACJ,CAAC;QAED,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;YACrD,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;oBAC5B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAA;oBAC1D,MAAM,KAAK,GAAG,YAAY,CAAC;wBACzB,GAAG;wBACH,KAAK;wBACL,KAAK,EAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;qBAChC,CAAC,CAAA;oBAEF,MAAM,KAAK,CAAA;gBACb,CAAC;gBAED,OAAM;YACR,CAAC;QACH,CAAC;QAED,MAAM,IAAI,qBAAqB,CAAC,GAAG,IAAI,CAAC,MAAM,uBAAuB,KAAK,EAAE,CAAC,CAAA;IAC/E,CAAC;CACF"}

package/dist/src/traversal-strategies/unixfs-path.d.ts

@@ -1,13 +1,63 @@
 import type { TraversalStrategy } from '../index.js';
-import type { BlockView } from 'multiformats/block/interface';
+import type { CodecLoader } from '@helia/interface';
+import type { AbortOptions } from '@libp2p/interface';
+import type { Blockstore } from 'interface-blockstore';
+import type { BlockView } from 'multiformats';
 import type { CID } from 'multiformats/cid';
 /**
  * Traverses a DAG containing UnixFS directories
+ *
+ * A root CID may be specified to begin traversal from, otherwise the root
+ * currently being exported will be used.
+ *
+ * @example Begin traversal from the root being exported
+ *
+ * In this example, the UnixFS path `/foo/bar/baz.txt` path should be resolvable
+ * beneath the `root` CID.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const c = car(helia)
+ * const root = CID.parse('QmRoot')
+ *
+ * for await (const buf of c.export(root, {
+ *   traversal: new UnixFSPath('/foo/bar/baz.txt')
+ * })) {
+ *   // do something with `buf`
+ * }
+ * ```
+ *
+ * @example Begin traversal from a parent node
+ *
+ * In this example, the `root` CID should be resolvable at the UnixFS path
+ * beneath `parentCID`.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const c = car(helia)
+ * const root = CID.parse('QmRoot')
+ * const parentCID = CID.parse('QmParent')
+ *
+ * for await (const buf of c.export(root, {
+ *   traversal: new UnixFSPath(parentCID, '/foo/bar/baz.txt')
+ * })) {
+ *   // do something with `buf`
+ * }
+ * ```
  */
 export declare class UnixFSPath implements TraversalStrategy {
+    private readonly root?;
     private readonly path;
     constructor(path: string);
-    isTarget(): boolean;
-    traverse<T extends BlockView<any, any, any, 0 | 1>>(cid: CID, block: T): AsyncGenerator<CID, void, undefined>;
+    constructor(root: CID, path: string);
+    traverse(root: CID, blockstore: Blockstore, getCodec: CodecLoader, options?: AbortOptions): AsyncGenerator<BlockView<unknown, number, number, 0 | 1>, void, undefined>;
 }
 //# sourceMappingURL=unixfs-path.d.ts.map

package/dist/src/traversal-strategies/unixfs-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unixfs-path.d.ts","sourceRoot":"","sources":["../../../src/traversal-strategies/unixfs-path.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C;;GAEG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;gBAElB,IAAI,EAAE,MAAM;IAKzB,QAAQ,IAAK,OAAO;IAIZ,QAAQ,CAAE,CAAC,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC;CAkCvH"}
+{"version":3,"file":"unixfs-path.d.ts","sourceRoot":"","sources":["../../../src/traversal-strategies/unixfs-path.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;gBAEhB,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM;IAoB5B,QAAQ,CAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;CAShL"}

package/dist/src/traversal-strategies/unixfs-path.js

@@ -1,42 +1,82 @@
-import { decode } from '@ipld/dag-pb';
-import { UnixFS } from 'ipfs-unixfs';
-import { DAG_PB_CODEC_CODE } from '../constants.js';
-import { NotUnixFSError } from '../errors.js';
+import * as dagPb from '@ipld/dag-pb';
+import { walkPath } from 'ipfs-unixfs-exporter';
+import { createUnsafe } from 'multiformats/block';
 /**
  * Traverses a DAG containing UnixFS directories
+ *
+ * A root CID may be specified to begin traversal from, otherwise the root
+ * currently being exported will be used.
+ *
+ * @example Begin traversal from the root being exported
+ *
+ * In this example, the UnixFS path `/foo/bar/baz.txt` path should be resolvable
+ * beneath the `root` CID.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const c = car(helia)
+ * const root = CID.parse('QmRoot')
+ *
+ * for await (const buf of c.export(root, {
+ *   traversal: new UnixFSPath('/foo/bar/baz.txt')
+ * })) {
+ *   // do something with `buf`
+ * }
+ * ```
+ *
+ * @example Begin traversal from a parent node
+ *
+ * In this example, the `root` CID should be resolvable at the UnixFS path
+ * beneath `parentCID`.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const c = car(helia)
+ * const root = CID.parse('QmRoot')
+ * const parentCID = CID.parse('QmParent')
+ *
+ * for await (const buf of c.export(root, {
+ *   traversal: new UnixFSPath(parentCID, '/foo/bar/baz.txt')
+ * })) {
+ *   // do something with `buf`
+ * }
+ * ```
  */
 export class UnixFSPath {
+    root;
     path;
-    constructor(path) {
-        // "/foo/bar/baz.txt" -> ['foo', 'bar', 'baz.txt']
-        this.path = path.replace(/^\//, '').split('/');
-    }
-    isTarget() {
-        return this.path.length === 0;
-    }
-    async *traverse(cid, block) {
-        if (cid.code !== DAG_PB_CODEC_CODE) {
-            throw new NotUnixFSError('Target CID is not UnixFS');
+    constructor(...args) {
+        let root = args[0];
+        let path = args[1];
+        if (typeof root === 'string') {
+            path = root;
+            root = undefined;
         }
-        const segment = this.path.shift();
-        if (segment == null) {
-            return;
+        else if (args.length < 2) {
+            throw new Error('path or CID and path must be specified');
         }
-        const pb = decode(block.bytes);
-        if (pb.Data == null) {
-            throw new NotUnixFSError('Target CID has no UnixFS data in decoded bytes');
+        if (!path.startsWith('/')) {
+            path = `/${path}`;
         }
-        const unixfs = UnixFS.unmarshal(pb.Data);
-        if (unixfs.type === 'directory') {
-            const link = pb.Links.filter(link => link.Name === segment).pop();
-            if (link == null) {
-                throw new NotUnixFSError(`Target CID directory has no link with name ${segment}`);
-            }
-            yield link.Hash;
-            return;
+        this.root = root;
+        this.path = path;
+    }
+    async *traverse(root, blockstore, getCodec, options) {
+        for await (const entry of walkPath(`${this.root ?? root}${this.path}`, blockstore, options)) {
+            yield createUnsafe({
+                cid: entry.cid,
+                bytes: entry.node instanceof Uint8Array ? entry.node : dagPb.encode(entry.node),
+                codec: await getCodec(entry.cid.code)
+            });
         }
-        // TODO: HAMT support
-        throw new NotUnixFSError('Target CID is not a UnixFS directory');
     }
 }
 //# sourceMappingURL=unixfs-path.js.map

package/dist/src/traversal-strategies/unixfs-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"unixfs-path.js","sourceRoot":"","sources":["../../../src/traversal-strategies/unixfs-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAK7C;;GAEG;AACH,MAAM,OAAO,UAAU;IACJ,IAAI,CAAU;IAE/B,YAAa,IAAY;QACvB,kDAAkD;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAChD,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAA;IAC/B,CAAC;IAED,KAAK,CAAC,CAAE,QAAQ,CAA6C,GAAQ,EAAE,KAAQ;QAC7E,IAAI,GAAG,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YACnC,MAAM,IAAI,cAAc,CAAC,0BAA0B,CAAC,CAAA;QACtD,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;QAEjC,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YACpB,OAAM;QACR,CAAC;QAED,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAE9B,IAAI,EAAE,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;YACpB,MAAM,IAAI,cAAc,CAAC,gDAAgD,CAAC,CAAA;QAC5E,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;QAExC,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,EAAE,CAAA;YAEjE,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;gBACjB,MAAM,IAAI,cAAc,CAAC,8CAA8C,OAAO,EAAE,CAAC,CAAA;YACnF,CAAC;YAED,MAAM,IAAI,CAAC,IAAI,CAAA;YACf,OAAM;QACR,CAAC;QAED,qBAAqB;QAErB,MAAM,IAAI,cAAc,CAAC,sCAAsC,CAAC,CAAA;IAClE,CAAC;CACF"}
+{"version":3,"file":"unixfs-path.js","sourceRoot":"","sources":["../../../src/traversal-strategies/unixfs-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAQjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,OAAO,UAAU;IACJ,IAAI,CAAM;IACV,IAAI,CAAQ;IAI7B,YAAa,GAAG,IAAW;QACzB,IAAI,IAAI,GAA6B,IAAI,CAAC,CAAC,CAAC,CAAA;QAC5C,IAAI,IAAI,GAAW,IAAI,CAAC,CAAC,CAAC,CAAA;QAE1B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,GAAG,IAAI,CAAA;YACX,IAAI,GAAG,SAAS,CAAA;QAClB,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;QAC3D,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,GAAG,IAAI,IAAI,EAAE,CAAA;QACnB,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,CAAE,QAAQ,CAAE,IAAS,EAAE,UAAsB,EAAE,QAAqB,EAAE,OAAsB;QAChG,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;YAC5F,MAAM,YAAY,CAAC;gBACjB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,KAAK,EAAE,KAAK,CAAC,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC/E,KAAK,EAAE,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;aACtC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/typedoc-urls.json

@@ -13,6 +13,7 @@
   ".:ExportCarOptions": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportCarOptions.html",
   "ExportStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportStrategy.html",
   ".:ExportStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportStrategy.html",
+  "GraphSearchOptions": "https://ipfs.github.io/helia/interfaces/_helia_car.GraphSearchOptions.html",
   "TraversalStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.TraversalStrategy.html",
   ".:TraversalStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.TraversalStrategy.html",
   "car": "https://ipfs.github.io/helia/functions/_helia_car.car.html",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helia/car",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "Import/export car files from Helia",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/ipfs/helia/tree/main/packages/car#readme",
@@ -48,12 +48,13 @@
   },
   "dependencies": {
     "@helia/interface": "^6.0.0",
+    "@helia/utils": "^2.1.0",
     "@ipld/car": "^5.4.2",
     "@ipld/dag-pb": "^4.1.5",
     "@libp2p/interface": "^3.0.2",
     "@libp2p/utils": "^7.0.5",
     "interface-blockstore": "^6.0.1",
-    "ipfs-unixfs": "^12.0.0",
+    "ipfs-unixfs-exporter": "^14.0.1",
     "it-drain": "^3.0.10",
     "it-map": "^3.1.4",
     "it-to-buffer": "^4.0.10",
@@ -70,6 +71,7 @@
     "blockstore-core": "^6.1.1",
     "datastore-core": "^11.0.2",
     "ipfs-unixfs-importer": "^16.0.1",
+    "it-all": "^3.0.9",
     "it-foreach": "^2.1.4",
     "it-length": "^3.0.9",
     "sinon": "^21.0.0"