@ipld/car 5.0.2 → 5.1.0

package/dist/src/buffer-reader-browser.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @typedef {import('multiformats').CID} CID
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').CarBufferReader} ICarBufferReader
+ * @typedef {import('./coding').CarHeader} CarHeader
+ * @typedef {import('./coding').CarV2Header} CarV2Header
+ */
+/**
+ * Provides blockstore-like access to a CAR.
+ *
+ * Implements the `RootsBufferReader` interface:
+ * {@link ICarBufferReader.getRoots `getRoots()`}. And the `BlockBufferReader` interface:
+ * {@link ICarBufferReader.get `get()`}, {@link ICarBufferReader.has `has()`},
+ * {@link ICarBufferReader.blocks `blocks()`} and
+ * {@link ICarBufferReader.cids `cids()`}.
+ *
+ * Load this class with either `import { CarBufferReader } from '@ipld/car/buffer-reader'`
+ * (`const { CarBufferReader } = require('@ipld/car/buffer-reader')`). Or
+ * `import { CarBufferReader } from '@ipld/car'` (`const { CarBufferReader } = require('@ipld/car')`).
+ * The former will likely result in smaller bundle sizes where this is
+ * important.
+ *
+ * @name CarBufferReader
+ * @class
+ * @implements {ICarBufferReader}
+ * @property {number} version The version number of the CAR referenced by this
+ * reader (should be `1` or `2`).
+ */
+export class CarBufferReader implements ICarBufferReader {
+    /**
+     * Instantiate a {@link CarBufferReader} from a `Uint8Array` blob. This performs a
+     * decode fully in memory and maintains the decoded state in memory for full
+     * access to the data via the `CarReader` API.
+     *
+     * @static
+     * @memberof CarBufferReader
+     * @param {Uint8Array} bytes
+     * @returns {CarBufferReader}
+     */
+    static fromBytes(bytes: Uint8Array): CarBufferReader;
+    /**
+     * @constructs CarBufferReader
+     * @param {CarHeader|CarV2Header} header
+     * @param {Block[]} blocks
+     */
+    constructor(header: CarHeader | CarV2Header, blocks: Block[]);
+    _header: import("./coding").CarHeader | import("./coding").CarV2Header;
+    _blocks: import("./api").Block[];
+    _cids: import("multiformats").CID<unknown, number, number, import("multiformats").Version>[] | undefined;
+    /**
+     * @property version
+     * @memberof CarBufferReader
+     * @instance
+     */
+    get version(): 1 | 2;
+    /**
+     * Get the list of roots defined by the CAR referenced by this reader. May be
+     * zero or more `CID`s.
+     *
+     * @function
+     * @memberof CarBufferReader
+     * @instance
+     * @returns {CID[]}
+     */
+    getRoots(): CID[];
+    /**
+     * Check whether a given `CID` exists within the CAR referenced by this
+     * reader.
+     *
+     * @function
+     * @memberof CarBufferReader
+     * @instance
+     * @param {CID} key
+     * @returns {boolean}
+     */
+    has(key: CID): boolean;
+    /**
+     * Fetch a `Block` (a `{ cid:CID, bytes:Uint8Array }` pair) from the CAR
+     * referenced by this reader matching the provided `CID`. In the case where
+     * the provided `CID` doesn't exist within the CAR, `undefined` will be
+     * returned.
+     *
+     * @function
+     * @memberof CarBufferReader
+     * @instance
+     * @param {CID} key
+     * @returns {Block | undefined}
+     */
+    get(key: CID): Block | undefined;
+    /**
+     * Returns a `Block[]` of the `Block`s (`{ cid:CID, bytes:Uint8Array }` pairs) contained within
+     * the CAR referenced by this reader.
+     *
+     * @function
+     * @memberof CarBufferReader
+     * @instance
+     * @returns {Block[]}
+     */
+    blocks(): Block[];
+    /**
+     * Returns a `CID[]` of the `CID`s contained within the CAR referenced by this reader.
+     *
+     * @function
+     * @memberof CarBufferReader
+     * @instance
+     * @returns {CID[]}
+     */
+    cids(): CID[];
+}
+export const __browser: true;
+export type CID = import('multiformats').CID;
+export type Block = import('./api').Block;
+export type ICarBufferReader = import('./api').CarBufferReader;
+export type CarHeader = import('./coding').CarHeader;
+export type CarV2Header = import('./coding').CarV2Header;
+//# sourceMappingURL=buffer-reader-browser.d.ts.map

package/dist/src/buffer-reader-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-reader-browser.d.ts","sourceRoot":"","sources":["../../src/buffer-reader-browser.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAkGE;;;;;;;;;OASG;IACH,wBAHW,UAAU,GACR,eAAe,CAS3B;IAlHD;;;;OAIG;IACH,oBAHW,SAAS,GAAC,WAAW,UACrB,KAAK,EAAE,EAMjB;IAHC,uEAAqB;IACrB,iCAAqB;IACrB,yGAAsB;IAGxB;;;;OAIG;IACH,qBAEC;IAED;;;;;;;;OAQG;IACH,YAFa,GAAG,EAAE,CAMjB;IAED;;;;;;;;;OASG;IACH,SAHW,GAAG,GACD,OAAO,CAMnB;IAED;;;;;;;;;;;OAWG;IACH,SAHW,GAAG,GACD,KAAK,GAAG,SAAS,CAM7B;IAED;;;;;;;;OAQG;IACH,UAFa,KAAK,EAAE,CAInB;IAED;;;;;;;OAOG;IACH,QAFa,GAAG,EAAE,CAOjB;CAoBF;AAED,6BAA6B;kBAlJhB,OAAO,cAAc,EAAE,GAAG;oBAC1B,OAAO,OAAO,EAAE,KAAK;+BACrB,OAAO,OAAO,EAAE,eAAe;wBAC/B,OAAO,UAAU,EAAE,SAAS;0BAC5B,OAAO,UAAU,EAAE,WAAW"}

package/dist/src/buffer-reader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @class
+ * @implements {ICarBufferReader}
+ */
+export class CarBufferReader extends BrowserCarBufferReader implements ICarBufferReader {
+    /**
+     * Reads a block directly from a file descriptor for an open CAR file. This
+     * function is **only available in Node.js** and not a browser environment.
+     *
+     * This function can be used in connection with {@link CarIndexer} which emits
+     * the `BlockIndex` objects that are required by this function.
+     *
+     * The user is responsible for opening and closing the file used in this call.
+     *
+     * @static
+     * @memberof CarBufferReader
+     * @param {number} fd - A file descriptor from the
+     * Node.js `fs` module. An integer, from `fs.open()`.
+     * @param {BlockIndex} blockIndex - An index pointing to the location of the
+     * Block required. This `BlockIndex` should take the form:
+     * `{cid:CID, blockLength:number, blockOffset:number}`.
+     * @returns {Block} A `{ cid:CID, bytes:Uint8Array }` pair.
+     */
+    static readRaw(fd: number, blockIndex: BlockIndex): Block;
+}
+export const __browser: false;
+export type Block = import('./api').Block;
+export type BlockIndex = import('./api').BlockIndex;
+export type ICarBufferReader = import('./api').CarBufferReader;
+import { CarBufferReader as BrowserCarBufferReader } from "./buffer-reader-browser.js";
+//# sourceMappingURL=buffer-reader.d.ts.map

package/dist/src/buffer-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-reader.d.ts","sourceRoot":"","sources":["../../src/buffer-reader.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH;IACE;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAPW,MAAM,cAEN,UAAU,GAGR,KAAK,CAiBjB;CACF;AAED,8BAA8B;oBAhDjB,OAAO,OAAO,EAAE,KAAK;yBACrB,OAAO,OAAO,EAAE,UAAU;+BAC1B,OAAO,OAAO,EAAE,eAAe"}

package/dist/src/coding.d.ts

@@ -32,10 +32,17 @@ export interface CarDecoder {
     blocks: () => AsyncGenerator<Block>;
     blocksIndex: () => AsyncGenerator<BlockIndex>;
 }
-export interface BytesReader {
-    upTo: (length: number) => Promise<Uint8Array>;
-    exactly: (length: number) => Promise<Uint8Array>;
+export interface Seekable {
     seek: (length: number) => void;
+}
+export interface BytesReader extends Seekable {
+    upTo: (length: number) => Promise<Uint8Array>;
+    exactly: (length: number, seek?: boolean) => Promise<Uint8Array>;
+    pos: number;
+}
+export interface BytesBufferReader extends Seekable {
+    upTo: (length: number) => Uint8Array;
+    exactly: (length: number, seek?: boolean) => Uint8Array;
     pos: number;
 }
 //# sourceMappingURL=coding.d.ts.map

package/dist/src/coding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coding.d.ts","sourceRoot":"","sources":["../../src/coding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAEjD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAA;IAEjC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,CAAC,CAAA;IACV,KAAK,EAAE,GAAG,EAAE,CAAA;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,OAAO,EAAE,CAAC,CAAA;IACV,KAAK,EAAE,GAAG,EAAE,CAAA;CACb;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,OAAO,CAAC,SAAS,GAAC,WAAW,CAAC,CAAA;IAE5C,MAAM,EAAE,MAAM,cAAc,CAAC,KAAK,CAAC,CAAA;IAEnC,WAAW,EAAE,MAAM,cAAc,CAAC,UAAU,CAAC,CAAA;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAE7C,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAEhD,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAE9B,GAAG,EAAE,MAAM,CAAA;CACZ"}
+{"version":3,"file":"coding.d.ts","sourceRoot":"","sources":["../../src/coding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAEjD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAA;IAEjC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,CAAC,CAAA;IACV,KAAK,EAAE,GAAG,EAAE,CAAA;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,OAAO,EAAE,CAAC,CAAA;IACV,KAAK,EAAE,GAAG,EAAE,CAAA;CACb;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,OAAO,CAAC,SAAS,GAAC,WAAW,CAAC,CAAA;IAE5C,MAAM,EAAE,MAAM,cAAc,CAAC,KAAK,CAAC,CAAA;IAEnC,WAAW,EAAE,MAAM,cAAc,CAAC,UAAU,CAAC,CAAA;CAC9C;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAE7C,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAEhE,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAA;IAEpC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,UAAU,CAAA;IAEvD,GAAG,EAAE,MAAM,CAAA;CACZ"}

package/dist/src/decoder-common.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Decodes varint and seeks the buffer
+ *
+ * ```js
+ * // needs bytes to be read first
+ * const bytes = reader.upTo(8) // maybe async
+ * ```
+ *
+ * @param {Uint8Array} bytes
+ * @param {import('./coding').Seekable} seeker
+ * @returns {number}
+ */
+export function decodeVarint(bytes: Uint8Array, seeker: import('./coding').Seekable): number;
+/**
+ * Decode v2 header
+ *
+ * ```js
+ * // needs bytes to be read first
+ * const bytes = reader.exactly(V2_HEADER_LENGTH, true) // maybe async
+ * ```
+ *
+ * @param {Uint8Array} bytes
+ * @returns {import('./coding').CarV2FixedHeader}
+ */
+export function decodeV2Header(bytes: Uint8Array): import('./coding').CarV2FixedHeader;
+/**
+ * Checks the length of the multihash to be read afterwards
+ *
+ * ```js
+ * // needs bytes to be read first
+ * const bytes = reader.upTo(8) // maybe async
+ * ```
+ *
+ * @param {Uint8Array} bytes
+ */
+export function getMultihashLength(bytes: Uint8Array): number;
+export namespace CIDV0_BYTES {
+    const SHA2_256: number;
+    const LENGTH: number;
+    const DAG_PB: number;
+}
+export const V2_HEADER_LENGTH: number;
+//# sourceMappingURL=decoder-common.d.ts.map

package/dist/src/decoder-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder-common.d.ts","sourceRoot":"","sources":["../../src/decoder-common.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;GAWG;AACH,oCAJW,UAAU,UACV,OAAO,UAAU,EAAE,QAAQ,GACzB,MAAM,CAWlB;AAED;;;;;;;;;;GAUG;AACH,sCAHW,UAAU,GACR,OAAO,UAAU,EAAE,gBAAgB,CAmB/C;AAED;;;;;;;;;GASG;AACH,0CAFW,UAAU,UAcpB;;;;;;AA7ED,sCAAqH"}

package/dist/src/decoder.d.ts

@@ -1,3 +1,13 @@
+/**
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').BlockHeader} BlockHeader
+ * @typedef {import('./api').BlockIndex} BlockIndex
+ * @typedef {import('./coding').BytesReader} BytesReader
+ * @typedef {import('./coding').CarHeader} CarHeader
+ * @typedef {import('./coding').CarV2Header} CarV2Header
+ * @typedef {import('./coding').CarV2FixedHeader} CarV2FixedHeader
+ * @typedef {import('./coding').CarDecoder} CarDecoder
+ */
 /**
  * Reads header data from a `BytesReader`. The header may either be in the form
  * of a `CarHeader` or `CarV2Header` depending on the CAR being read.

package/dist/src/decoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/decoder.js"],"names":[],"mappings":"AAmEA;;;;;;;;GAQG;AACH,mCAJW,WAAW,uCAET,QAAQ,SAAS,GAAC,WAAW,CAAC,CAgC1C;AAkDD;;;;;;;;;GASG;AACH,sCAHW,WAAW,GACT,QAAQ,WAAW,CAAC,CAiBhC;AA6BD;;;;;;;;GAQG;AACH,sCAHW,WAAW,GACT,UAAU,CA+BtB;AAED;;;;;;GAMG;AACH,mCAHW,UAAU,GACR,WAAW,CA8BvB;AAED;;;;;;;GAOG;AACH,uCAHW,MAAM,QAAQ,UAAU,GAAC,IAAI,CAAC,GAC5B,WAAW,CAsEvB;AAED;;;;;;;GAOG;AACH,mDAHW,cAAc,UAAU,CAAC,GACvB,WAAW,CAgBvB;AAED;;;;;;;;;GASG;AACH,oCAJW,WAAW,aACX,MAAM,GACJ,WAAW,CAoCvB;oBA1aY,OAAO,OAAO,EAAE,KAAK;0BACrB,OAAO,OAAO,EAAE,WAAW;yBAC3B,OAAO,OAAO,EAAE,UAAU;0BAC1B,OAAO,UAAU,EAAE,WAAW;wBAC9B,OAAO,UAAU,EAAE,SAAS;0BAC5B,OAAO,UAAU,EAAE,WAAW;+BAC9B,OAAO,UAAU,EAAE,gBAAgB;yBACnC,OAAO,UAAU,EAAE,UAAU"}
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/decoder.js"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,mCAJW,WAAW,uCAET,QAAQ,SAAS,GAAC,WAAW,CAAC,CA+B1C;AA2BD;;;;;;;;;GASG;AACH,sCAHW,WAAW,GACT,QAAQ,WAAW,CAAC,CAiBhC;AA4BD;;;;;;;;GAQG;AACH,sCAHW,WAAW,GACT,UAAU,CA+BtB;AAED;;;;;;GAMG;AACH,mCAHW,UAAU,GACR,WAAW,CAmCvB;AAED;;;;;;;GAOG;AACH,uCAHW,MAAM,QAAQ,UAAU,GAAC,IAAI,CAAC,GAC5B,WAAW,CA2EvB;AAED;;;;;;;GAOG;AACH,mDAHW,cAAc,UAAU,CAAC,GACvB,WAAW,CAgBvB;AAED;;;;;;;;;GASG;AACH,oCAJW,WAAW,aACX,MAAM,GACJ,WAAW,CAuCvB;oBA5WY,OAAO,OAAO,EAAE,KAAK;0BACrB,OAAO,OAAO,EAAE,WAAW;yBAC3B,OAAO,OAAO,EAAE,UAAU;0BAC1B,OAAO,UAAU,EAAE,WAAW;wBAC9B,OAAO,UAAU,EAAE,SAAS;0BAC5B,OAAO,UAAU,EAAE,WAAW;+BAC9B,OAAO,UAAU,EAAE,gBAAgB;yBACnC,OAAO,UAAU,EAAE,UAAU"}

package/dist/src/index.d.ts

@@ -1,9 +1,10 @@
 import { CarReader } from "./reader.js";
+import { CarBufferReader } from "./buffer-reader.js";
 import { CarIndexer } from "./indexer.js";
 import { CarBlockIterator } from "./iterator.js";
 import { CarCIDIterator } from "./iterator.js";
 import { CarWriter } from "./writer.js";
 import { CarIndexedReader } from "./indexed-reader.js";
 import * as CarBufferWriter from "./buffer-writer.js";
-export { CarReader, CarIndexer, CarBlockIterator, CarCIDIterator, CarWriter, CarIndexedReader, CarBufferWriter };
+export { CarReader, CarBufferReader, CarIndexer, CarBlockIterator, CarCIDIterator, CarWriter, CarIndexedReader, CarBufferWriter };
 //# sourceMappingURL=index.d.ts.map

package/dist/src/reader-browser.d.ts

@@ -43,7 +43,7 @@ export class CarReader implements CarReaderIface {
      * @static
      * @memberof CarReader
      * @param {Uint8Array} bytes
-     * @returns {Promise<CarReader>} blip blop
+     * @returns {Promise<CarReader>}
      */
     static fromBytes(bytes: Uint8Array): Promise<CarReader>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipld/car",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Content Addressable aRchive format reader and writer",
   "author": "Rod <rod@vagg.org> (http://r.va.gg/)",
   "license": "Apache-2.0 OR MIT",
@@ -78,6 +78,11 @@
       "browser": "./src/reader-browser.js",
       "import": "./src/reader.js"
     },
+    "./buffer-reader": {
+      "types": "./dist/src/buffer-reader-browser.d.ts",
+      "browser": "./src/buffer-reader-browser.js",
+      "import": "./src/buffer-reader.js"
+    },
     "./writer": {
       "types": "./dist/src/writer.d.ts",
       "browser": "./src/writer-browser.js",
@@ -190,7 +195,7 @@
     "test:examples": "npm run test --prefix examples/",
     "dep-check": "aegir dep-check",
     "coverage": "c8 --reporter=html --reporter=text mocha test/test-*.js && npx st -d coverage -p 8888",
-    "docs": "jsdoc4readme --readme --description-only src/reader*.js src/indexed-reader.js src/iterator.js src/indexer.js src/writer*.js src/buffer-writer.js src/decoder.js"
+    "docs": "jsdoc4readme --readme --description-only src/reader*.js src/indexed-reader.js src/iterator.js src/indexer.js src/writer*.js src/buffer-writer.js src/decoder.js src/buffer-reader*.js"
   },
   "dependencies": {
     "@ipld/dag-cbor": "^9.0.0",
@@ -212,6 +217,7 @@
     "./src/index.js": "./src/index-browser.js",
     "./src/index-reader.js": "./src/index-reader-browser.js",
     "./src/reader.js": "./src/reader-browser.js",
+    "./src/buffer-reader.js": "./src/buffer-reader-browser.js",
     "./src/writer.js": "./src/writer-browser.js",
     "fs": false,
     "util": false,

package/src/api.ts

@@ -1,5 +1,10 @@
 import type { CID } from 'multiformats/cid'
 
+/**
+ * Literally any `Iterable` (async or regular).
+ */
+export type AwaitIterable<T> = Iterable<T> | AsyncIterable<T>
+
 export type { CID }
 /* Generic types for interfacing with block storage */
 
@@ -24,6 +29,11 @@ export interface RootsReader {
   getRoots: () => Promise<CID[]>
 }
 
+export interface RootsBufferReader {
+  version: number
+  getRoots: () => CID[]
+}
+
 export interface BlockIterator extends AsyncIterable<Block> {}
 
 export interface CIDIterator extends AsyncIterable<CID> {}
@@ -35,6 +45,13 @@ export interface BlockReader {
   cids: () => CIDIterator
 }
 
+export interface BlockBufferReader {
+  has: (key: CID) => boolean
+  get: (key: CID) => Block | undefined
+  blocks: () => Iterable<Block>
+  cids: () => Iterable<CID>
+}
+
 export interface BlockWriter {
   put: (block: Block) => Promise<void>
   close: () => Promise<void>
@@ -60,6 +77,7 @@ export interface WriterChannel {
 }
 
 export interface CarReader extends BlockReader, RootsReader {}
+export interface CarBufferReader extends BlockBufferReader, RootsBufferReader {}
 
 /* Specific implementations for CAR block storage */
 

package/src/buffer-decoder.js

@@ -0,0 +1,226 @@
+import { CID } from 'multiformats/cid'
+import * as Digest from 'multiformats/hashes/digest'
+import { decode as decodeDagCbor } from '@ipld/dag-cbor'
+import { CarHeader as headerValidator } from './header-validator.js'
+import { CIDV0_BYTES, decodeV2Header, decodeVarint, getMultihashLength, V2_HEADER_LENGTH } from './decoder-common.js'
+
+/**
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').BlockHeader} BlockHeader
+ * @typedef {import('./api').BlockIndex} BlockIndex
+ * @typedef {import('./coding').BytesBufferReader} BytesBufferReader
+ * @typedef {import('./coding').CarHeader} CarHeader
+ * @typedef {import('./coding').CarV2Header} CarV2Header
+ * @typedef {import('./coding').CarV2FixedHeader} CarV2FixedHeader
+ */
+
+/**
+ * Reads header data from a `BytesReader`. The header may either be in the form
+ * of a `CarHeader` or `CarV2Header` depending on the CAR being read.
+ *
+ * @name decoder.readHeader(reader)
+ * @param {BytesBufferReader} reader
+ * @param {number} [strictVersion]
+ * @returns {CarHeader | CarV2Header}
+ */
+export function readHeader (reader, strictVersion) {
+  const length = decodeVarint(reader.upTo(8), reader)
+  if (length === 0) {
+    throw new Error('Invalid CAR header (zero length)')
+  }
+  const header = reader.exactly(length, true)
+  const block = decodeDagCbor(header)
+  if (!headerValidator(block)) {
+    throw new Error('Invalid CAR header format')
+  }
+  if ((block.version !== 1 && block.version !== 2) || (strictVersion !== undefined && block.version !== strictVersion)) {
+    throw new Error(`Invalid CAR version: ${block.version}${strictVersion !== undefined ? ` (expected ${strictVersion})` : ''}`)
+  }
+  // we've made 'roots' optional in the schema so we can do the version check
+  // before rejecting the block as invalid if there is no version
+  const hasRoots = Array.isArray(block.roots)
+  if ((block.version === 1 && !hasRoots) || (block.version === 2 && hasRoots)) {
+    throw new Error('Invalid CAR header format')
+  }
+  if (block.version === 1) {
+    return block
+  }
+  // version 2
+  const v2Header = decodeV2Header(reader.exactly(V2_HEADER_LENGTH, true))
+  reader.seek(v2Header.dataOffset - reader.pos)
+  const v1Header = readHeader(reader, 1)
+  return Object.assign(v1Header, v2Header)
+  /* c8 ignore next 2 */
+  // Node.js 12 c8 bug
+}
+
+/**
+ * Reads CID sync
+ *
+ * @param {BytesBufferReader} reader
+ * @returns {CID}
+ */
+function readCid (reader) {
+  const first = reader.exactly(2, false)
+  if (first[0] === CIDV0_BYTES.SHA2_256 && first[1] === CIDV0_BYTES.LENGTH) {
+    // cidv0 32-byte sha2-256
+    const bytes = reader.exactly(34, true)
+    const multihash = Digest.decode(bytes)
+    return CID.create(0, CIDV0_BYTES.DAG_PB, multihash)
+  }
+
+  const version = decodeVarint(reader.upTo(8), reader)
+  if (version !== 1) {
+    throw new Error(`Unexpected CID version (${version})`)
+  }
+  const codec = decodeVarint(reader.upTo(8), reader)
+  const bytes = reader.exactly(getMultihashLength(reader.upTo(8)), true)
+  const multihash = Digest.decode(bytes)
+  return CID.create(version, codec, multihash)
+  /* c8 ignore next 2 */
+  // Node.js 12 c8 bug
+}
+
+/**
+ * Reads the leading data of an individual block from CAR data from a
+ * `BytesBufferReader`. Returns a `BlockHeader` object which contains
+ * `{ cid, length, blockLength }` which can be used to either index the block
+ * or read the block binary data.
+ *
+ * @name async decoder.readBlockHead(reader)
+ * @param {BytesBufferReader} reader
+ * @returns {BlockHeader}
+ */
+export function readBlockHead (reader) {
+  // length includes a CID + Binary, where CID has a variable length
+  // we have to deal with
+  const start = reader.pos
+  let length = decodeVarint(reader.upTo(8), reader)
+  if (length === 0) {
+    throw new Error('Invalid CAR section (zero length)')
+  }
+  length += (reader.pos - start)
+  const cid = readCid(reader)
+  const blockLength = length - Number(reader.pos - start) // subtract CID length
+
+  return { cid, length, blockLength }
+  /* c8 ignore next 2 */
+  // Node.js 12 c8 bug
+}
+
+/**
+ * Returns Car header and blocks from a Uint8Array
+ *
+ * @param {Uint8Array} bytes
+ * @returns {{ header : CarHeader | CarV2Header , blocks: Block[]}}
+ */
+export function fromBytes (bytes) {
+  let reader = bytesReader(bytes)
+  const header = readHeader(reader)
+  if (header.version === 2) {
+    const v1length = reader.pos - header.dataOffset
+    reader = limitReader(reader, header.dataSize - v1length)
+  }
+
+  const blocks = []
+  while (reader.upTo(8).length > 0) {
+    const { cid, blockLength } = readBlockHead(reader)
+
+    blocks.push({ cid, bytes: reader.exactly(blockLength, true) })
+  }
+
+  return {
+    header, blocks
+  }
+}
+
+/**
+ * Creates a `BytesBufferReader` from a `Uint8Array`.
+ *
+ * @name decoder.bytesReader(bytes)
+ * @param {Uint8Array} bytes
+ * @returns {BytesBufferReader}
+ */
+export function bytesReader (bytes) {
+  let pos = 0
+
+  /** @type {BytesBufferReader} */
+  return {
+    upTo (length) {
+      return bytes.subarray(pos, pos + Math.min(length, bytes.length - pos))
+      /* c8 ignore next 2 */
+      // Node.js 12 c8 bug
+    },
+
+    exactly (length, seek = false) {
+      if (length > bytes.length - pos) {
+        throw new Error('Unexpected end of data')
+      }
+
+      const out = bytes.subarray(pos, pos + length)
+      if (seek) {
+        pos += length
+      }
+      return out
+      /* c8 ignore next 2 */
+      // Node.js 12 c8 bug
+    },
+
+    seek (length) {
+      pos += length
+    },
+
+    get pos () {
+      return pos
+    }
+  }
+}
+
+/**
+ * Wraps a `BytesBufferReader` in a limiting `BytesBufferReader` which limits maximum read
+ * to `byteLimit` bytes. It _does not_ update `pos` of the original
+ * `BytesBufferReader`.
+ *
+ * @name decoder.limitReader(reader, byteLimit)
+ * @param {BytesBufferReader} reader
+ * @param {number} byteLimit
+ * @returns {BytesBufferReader}
+ */
+export function limitReader (reader, byteLimit) {
+  let bytesRead = 0
+
+  /** @type {BytesBufferReader} */
+  return {
+    upTo (length) {
+      let bytes = reader.upTo(length)
+      if (bytes.length + bytesRead > byteLimit) {
+        bytes = bytes.subarray(0, byteLimit - bytesRead)
+      }
+      return bytes
+      /* c8 ignore next 2 */
+      // Node.js 12 c8 bug
+    },
+
+    exactly (length, seek = false) {
+      const bytes = reader.exactly(length, seek)
+      if (bytes.length + bytesRead > byteLimit) {
+        throw new Error('Unexpected end of data')
+      }
+      if (seek) {
+        bytesRead += length
+      }
+      return bytes
+      /* c8 ignore next 2 */
+      // Node.js 12 c8 bug
+    },
+
+    seek (length) {
+      bytesRead += length
+      reader.seek(length)
+    },
+
+    get pos () {
+      return reader.pos
+    }
+  }
+}