chore(docs): update docs to include decoder.* functions.

README.md

@@ -240,14 +240,20 @@ be directly fed to a
  * [`async CarWriter.createAppender()`](#CarWriter__createAppender)
  * [`async CarWriter.updateRootsInBytes(bytes, roots)`](#CarWriter__updateRootsInBytes)
  * [`async CarWriter.updateRootsInFile(fd, roots)`](#CarWriter__updateRootsInFile)
+ * [`async decoder.readHeader(reader)`](#async__decoder__readHeader__reader__)
+ * [`async decoder.readBlockHead(reader)`](#async__decoder__readBlockHead__reader__)
+ * [`decoder.createDecoder(reader)`](#decoder__createDecoder__reader__)
+ * [`decoder.bytesReader(bytes)`](#decoder__bytesReader__bytes__)
+ * [`decoder.asyncIterableReader(asyncIterable)`](#decoder__asyncIterableReader__asyncIterable__)
+ * [`decoder.limitReader(reader, byteLimit)`](#decoder__limitReader__reader____byteLimit__)
 
 <a name="CarReader"></a>
 ### `class CarReader`
 
 Properties:
 
 * `version` `(number)`: The version number of the CAR referenced by this
-  reader (should be `1`).
+  reader (should be `1` or `2`).
 
 Provides blockstore-like access to a CAR.
 
@@ -748,7 +754,8 @@ upon successful modification.
 
 Update the list of roots in the header of an existing CAR file. The first
 argument must be a file descriptor for CAR file that is open in read and
-write mode (not append).
+write mode (not append), e.g. `fs.open` or `fs.promises.open` with `'r+'`
+mode.
 
 This operation is an _overwrite_, the total length of the CAR will not be
 modified. A rejection will occur if the new header will not be the same
@@ -759,6 +766,71 @@ replaced encode as the same length as the new roots.
 This function is **only available in Node.js** and not a browser
 environment.
 
+<a name="async__decoder__readHeader__reader__"></a>
+### `async decoder.readHeader(reader)`
+
+* `reader` `(BytesReader)`
+* `strictVersion` `(number, optional)`
+
+* Returns:  `Promise<(CarHeader|CarV2Header)>`
+
+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.
+
+<a name="async__decoder__readBlockHead__reader__"></a>
+### `async decoder.readBlockHead(reader)`
+
+* `reader` `(BytesReader)`
+
+* Returns:  `Promise<BlockHeader>`
+
+Reads the leading data of an individual block from CAR data from a
+`BytesReader`. Returns a `BlockHeader` object which contains
+`{ cid, length, blockLength }` which can be used to either index the block
+or read the block binary data.
+
+<a name="decoder__createDecoder__reader__"></a>
+### `decoder.createDecoder(reader)`
+
+* `reader` `(BytesReader)`
+
+* Returns:  `CarDecoder`
+
+Creates a `CarDecoder` from a `BytesReader`. The `CarDecoder` is as async
+interface that will consume the bytes from the `BytesReader` to yield a
+`header()` and either `blocks()` or `blocksIndex()` data.
+
+<a name="decoder__bytesReader__bytes__"></a>
+### `decoder.bytesReader(bytes)`
+
+* `bytes` `(Uint8Array)`
+
+* Returns:  `BytesReader`
+
+Creates a `BytesReader` from a `Uint8Array`.
+
+<a name="decoder__asyncIterableReader__asyncIterable__"></a>
+### `decoder.asyncIterableReader(asyncIterable)`
+
+* `asyncIterable` `(AsyncIterable<Uint8Array>)`
+
+* Returns:  `BytesReader`
+
+Creates a `BytesReader` from an `AsyncIterable<Uint8Array>`, which allows for
+consumption of CAR data from a streaming source.
+
+<a name="decoder__limitReader__reader____byteLimit__"></a>
+### `decoder.limitReader(reader, byteLimit)`
+
+* `reader` `(BytesReader)`
+* `byteLimit` `(number)`
+
+* Returns:  `BytesReader`
+
+Wraps a `BytesReader` in a limiting `BytesReader` which limits maximum read
+to `byteLimit` bytes. It _does not_ update `pos` of the original
+`BytesReader`.
+
 ## License
 
 Licensed under either of

lib/decoder.js

@@ -66,6 +66,10 @@ async function readV2Header (reader) {
 }
 
 /**
+ * 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 async decoder.readHeader(reader)
  * @param {BytesReader} reader
  * @param {number} [strictVersion]
  * @returns {Promise<CarHeader|CarV2Header>}
@@ -151,6 +155,12 @@ async function readCid (reader) {
 }
 
 /**
+ * Reads the leading data of an individual block from CAR data from a
+ * `BytesReader`. 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 {BytesReader} reader
  * @returns {Promise<BlockHeader>}
  */
@@ -199,6 +209,11 @@ async function readBlockIndex (reader) {
 }
 
 /**
+ * Creates a `CarDecoder` from a `BytesReader`. The `CarDecoder` is as async
+ * interface that will consume the bytes from the `BytesReader` to yield a
+ * `header()` and either `blocks()` or `blocksIndex()` data.
+ *
+ * @name decoder.createDecoder(reader)
  * @param {BytesReader} reader
  * @returns {CarDecoder}
  */
@@ -234,6 +249,9 @@ export function createDecoder (reader) {
 }
 
 /**
+ * Creates a `BytesReader` from a `Uint8Array`.
+ *
+ * @name decoder.bytesReader(bytes)
  * @param {Uint8Array} bytes
  * @returns {BytesReader}
  */
@@ -346,6 +364,10 @@ export function chunkReader (readChunk /*, closer */) {
 }
 
 /**
+ * Creates a `BytesReader` from an `AsyncIterable<Uint8Array>`, which allows for
+ * consumption of CAR data from a streaming source.
+ *
+ * @name decoder.asyncIterableReader(asyncIterable)
  * @param {AsyncIterable<Uint8Array>} asyncIterable
  * @returns {BytesReader}
  */
@@ -366,8 +388,11 @@ export function asyncIterableReader (asyncIterable) {
 }
 
 /**
- * limits read maximum to `byteLimit`, doesn't update `pos`, however
+ * Wraps a `BytesReader` in a limiting `BytesReader` which limits maximum read
+ * to `byteLimit` bytes. It _does not_ update `pos` of the original
+ * `BytesReader`.
  *
+ * @name decoder.limitReader(reader, byteLimit)
  * @param {BytesReader} reader
  * @param {number} byteLimit
  * @returns {BytesReader}

package.json

@@ -19,7 +19,7 @@
     "test": "npm run lint && npm run test:node && npm run test:cjs && npm run test --prefix examples/",
     "test:ci": "npm run lint && npm run test:node && npm run test:esm && npm run test:cjs && npm run test --prefix examples/",
     "coverage": "c8 --reporter=html --reporter=text mocha test/test-*.js && npx st -d coverage -p 8888",
-    "docs": "jsdoc4readme --readme --description-only lib/reader*.js lib/indexed-reader.js lib/iterator.js lib/indexer.js lib/writer*.js"
+    "docs": "jsdoc4readme --readme --description-only lib/reader*.js lib/indexed-reader.js lib/iterator.js lib/indexer.js lib/writer*.js lib/decoder.js"
   },
   "keywords": [
     "car",