@ipld/car 4.1.6 → 5.0.1

package/{lib → src}/buffer-writer.js

@@ -4,10 +4,10 @@ import { tokensToLength } from 'cborg/length'
 import * as CBOR from '@ipld/dag-cbor'
 
 /**
- * @typedef {import('../api').CID} CID
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').CarBufferWriter} Writer
- * @typedef {import('../api').CarBufferWriterOptions} Options
+ * @typedef {import('./api').CID} CID
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').CarBufferWriter} Writer
+ * @typedef {import('./api').CarBufferWriterOptions} Options
  * @typedef {import('./coding').CarEncoder} CarEncoder
  */
 
@@ -53,7 +53,7 @@ class CarBufferWriter {
    * Write a `Block` (a `{ cid:CID, bytes:Uint8Array }` pair) to the archive.
    * Throws if there is not enough capacity.
    *
-   * @param {Block} block A `{ cid:CID, bytes:Uint8Array }` pair.
+   * @param {Block} block - A `{ cid:CID, bytes:Uint8Array }` pair.
    * @returns {CarBufferWriter}
    */
   write (block) {

package/src/coding.ts

@@ -0,0 +1,56 @@
+import type { CID } from 'multiformats/cid'
+import type { Block, BlockIndex } from './api.js'
+
+export interface CarEncoder {
+  setRoots: (roots: CID[]) => Promise<void>
+
+  writeBlock: (block: Block) => Promise<void>
+
+  close: () => Promise<void>
+}
+
+export interface IteratorChannel_Writer<T> {
+  write: (chunk: T) => Promise<void>
+  end: () => Promise<void>
+}
+
+export interface IteratorChannel<T> {
+  writer: IteratorChannel_Writer<T>
+
+  iterator: AsyncIterator<T>
+}
+
+export interface CarHeader {
+  version: 1
+  roots: CID[]
+}
+
+export interface CarV2FixedHeader {
+  characteristics: [bigint, bigint]
+  dataOffset: number
+  dataSize: number
+  indexOffset: number
+}
+
+export interface CarV2Header extends CarV2FixedHeader {
+  version: 2
+  roots: CID[]
+}
+
+export interface CarDecoder {
+  header: () => Promise<CarHeader|CarV2Header>
+
+  blocks: () => AsyncGenerator<Block>
+
+  blocksIndex: () => AsyncGenerator<BlockIndex>
+}
+
+export interface BytesReader {
+  upTo: (length: number) => Promise<Uint8Array>
+
+  exactly: (length: number) => Promise<Uint8Array>
+
+  seek: (length: number) => void
+
+  pos: number
+}

package/{lib → src}/decoder.js

@@ -5,9 +5,9 @@ import { decode as decodeDagCbor } from '@ipld/dag-cbor'
 import { CarHeader as headerValidator } from './header-validator.js'
 
 /**
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').BlockHeader} BlockHeader
- * @typedef {import('../api').BlockIndex} BlockIndex
+ * @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
@@ -33,7 +33,7 @@ async function readVarint (reader) {
     throw new Error('Unexpected end of data')
   }
   const i = varint.decode(bytes)
-  reader.seek(varint.decode.bytes)
+  reader.seek(/** @type {number} */(varint.decode.bytes))
   return i
   /* c8 ignore next 2 */
   // Node.js 12 c8 bug
@@ -117,9 +117,9 @@ async function readMultihash (reader) {
 
   const bytes = await reader.upTo(8)
   varint.decode(bytes) // code
-  const codeLength = varint.decode.bytes
+  const codeLength = /** @type {number} */(varint.decode.bytes)
   const length = varint.decode(bytes.subarray(varint.decode.bytes))
-  const lengthLength = varint.decode.bytes
+  const lengthLength = /** @type {number} */(varint.decode.bytes)
   const mhLength = codeLength + lengthLength + length
   const multihash = await reader.exactly(mhLength)
   reader.seek(mhLength)
@@ -183,7 +183,7 @@ export async function readBlockHead (reader) {
 
 /**
  * @param {BytesReader} reader
- * @return {Promise<Block>}
+ * @returns {Promise<Block>}
  */
 async function readBlock (reader) {
   const { cid, blockLength } = await readBlockHead(reader)

package/{lib → src}/encoder.js

@@ -3,7 +3,7 @@ import { encode as dagCborEncode } from '@ipld/dag-cbor'
 
 /**
  * @typedef {import('multiformats').CID} CID
- * @typedef {import('../api').Block} Block
+ * @typedef {import('./api').Block} Block
  * @typedef {import('./coding').CarEncoder} CarEncoder
  * @typedef {import('./coding').IteratorChannel_Writer<Uint8Array>} IteratorChannel_Writer
  */

package/src/header-validator.js

@@ -0,0 +1,74 @@
+/* eslint-disable jsdoc/check-indentation */
+
+/** Auto-generated with ipld-schema-validator@0.0.0-dev at Thu Jun 17 2021 from IPLD Schema:
+ *
+ * type CarHeader struct {
+ *   version Int
+ *   roots optional [&Any]
+ *   # roots is _not_ optional for CarV1 but we defer that check within code to
+ *   # gracefully handle the >V1 case where it's just {version:X}
+ * }
+ *
+ */
+
+const Kinds = {
+  Null: /**
+         * @param {any} obj
+         * @returns {boolean}
+         */ (/** @type {any} */ obj) => obj === null,
+  Int: /**
+        * @param {any} obj
+        * @returns {boolean}
+        */ (/** @type {any} */ obj) => Number.isInteger(obj),
+  Float: /**
+          * @param {any} obj
+          * @returns {boolean}
+          */ (/** @type {any} */ obj) => typeof obj === 'number' && Number.isFinite(obj),
+  String: /**
+           * @param {any} obj
+           * @returns {boolean}
+           */ (/** @type {any} */ obj) => typeof obj === 'string',
+  Bool: /**
+         * @param {any} obj
+         * @returns {boolean}
+         */ (/** @type {any} */ obj) => typeof obj === 'boolean',
+  Bytes: /**
+          * @param {any} obj
+          * @returns {boolean}
+          */ (/** @type {any} */ obj) => obj instanceof Uint8Array,
+  Link: /**
+         * @param {any} obj
+         * @returns {boolean}
+         */ (/** @type {any} */ obj) => !Kinds.Null(obj) && typeof obj === 'object' && obj.asCID === obj,
+  List: /**
+         * @param {any} obj
+         * @returns {boolean}
+         */ (/** @type {any} */ obj) => Array.isArray(obj),
+  Map: /**
+        * @param {any} obj
+        * @returns {boolean}
+        */ (/** @type {any} */ obj) => !Kinds.Null(obj) && typeof obj === 'object' && obj.asCID !== obj && !Kinds.List(obj) && !Kinds.Bytes(obj)
+}
+/** @type {{ [k in string]: (obj:any)=>boolean}} */
+const Types = {
+  Int: Kinds.Int,
+  'CarHeader > version': /**
+                          * @param {any} obj
+                          * @returns {boolean}
+                          */ (/** @type {any} */ obj) => Types.Int(obj),
+  'CarHeader > roots (anon) > valueType (anon)': Kinds.Link,
+  'CarHeader > roots (anon)': /**
+                               * @param {any} obj
+                               * @returns {boolean}
+                               */ (/** @type {any} */ obj) => Kinds.List(obj) && Array.prototype.every.call(obj, Types['CarHeader > roots (anon) > valueType (anon)']),
+  'CarHeader > roots': /**
+                        * @param {any} obj
+                        * @returns {boolean}
+                        */ (/** @type {any} */ obj) => Types['CarHeader > roots (anon)'](obj),
+  CarHeader: /**
+              * @param {any} obj
+              * @returns {boolean}
+              */ (/** @type {any} */ obj) => { const keys = obj && Object.keys(obj); return Kinds.Map(obj) && ['version'].every((k) => keys.includes(k)) && Object.entries(obj).every(([name, value]) => Types['CarHeader > ' + name] && Types['CarHeader > ' + name](value)) }
+}
+
+export const CarHeader = Types.CarHeader

package/src/index-browser.js

@@ -0,0 +1,14 @@
+import { CarReader } from './reader-browser.js'
+import { CarIndexer } from './indexer.js'
+import { CarBlockIterator, CarCIDIterator } from './iterator.js'
+import { CarWriter } from './writer-browser.js'
+import { CarIndexedReader } from './indexed-reader-browser.js'
+
+export {
+  CarReader,
+  CarIndexer,
+  CarBlockIterator,
+  CarCIDIterator,
+  CarWriter,
+  CarIndexedReader
+}

package/src/index.js

@@ -0,0 +1,16 @@
+import { CarReader } from './reader.js'
+import { CarIndexer } from './indexer.js'
+import { CarBlockIterator, 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
+}

package/{lib → src}/indexed-reader.js

@@ -6,9 +6,9 @@ import { CarReader as NodeCarReader } from './reader.js'
 
 /**
  * @typedef {import('fs').promises.FileHandle} FileHandle
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').BlockIndex} BlockIndex
- * @typedef {import('../api').CarReader} CarReaderIface
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').BlockIndex} BlockIndex
+ * @typedef {import('./api').CarReader} CarReaderIface
  * @typedef {import('./reader-browser').CarReader} CarReader
  * @typedef {{ blockLength:number, blockOffset:number }} RawLocation
  */
@@ -68,7 +68,7 @@ export class CarIndexedReader {
   /**
    * See {@link CarReader#getRoots}
    *
-   * @method
+   * @function
    * @memberof CarIndexedReader
    * @instance
    * @async
@@ -83,7 +83,7 @@ export class CarIndexedReader {
   /**
    * See {@link CarReader#has}
    *
-   * @method
+   * @function
    * @memberof CarIndexedReader
    * @instance
    * @async
@@ -99,7 +99,7 @@ export class CarIndexedReader {
   /**
    * See {@link CarReader#get}
    *
-   * @method
+   * @function
    * @memberof CarIndexedReader
    * @instance
    * @async
@@ -129,7 +129,7 @@ export class CarIndexedReader {
   /**
    * See {@link CarReader#blocks}
    *
-   * @method
+   * @function
    * @memberof CarIndexedReader
    * @instance
    * @async
@@ -150,7 +150,7 @@ export class CarIndexedReader {
   /**
    * See {@link CarReader#cids}
    *
-   * @method
+   * @function
    * @memberof CarIndexedReader
    * @instance
    * @async
@@ -167,7 +167,7 @@ export class CarIndexedReader {
    * Close the underlying file descriptor maintained by this `CarIndexedReader`.
    * This must be called for proper resource clean-up to occur.
    *
-   * @method
+   * @function
    * @memberof CarIndexedReader
    * @instance
    * @async

package/{lib → src}/indexer.js

@@ -6,9 +6,9 @@ import {
 
 /**
  * @typedef {import('multiformats').CID} CID
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').RootsReader} RootsReader
- * @typedef {import('../api').BlockIndex} BlockIndex
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').RootsReader} RootsReader
+ * @typedef {import('./api').BlockIndex} BlockIndex
  * @typedef {import('./coding').BytesReader} BytesReader
  */
 
@@ -62,7 +62,7 @@ export class CarIndexer {
    * Get the list of roots defined by the CAR referenced by this indexer. May be
    * zero or more `CID`s.
    *
-   * @method
+   * @function
    * @memberof CarIndexer
    * @instance
    * @async

package/{lib → src}/iterator.js

@@ -6,8 +6,8 @@ import {
 
 /**
  * @typedef {import('multiformats').CID} CID
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').RootsReader} RootsReader
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').RootsReader} RootsReader
  * @typedef {import('./coding').BytesReader} BytesReader
  */
 
@@ -77,7 +77,7 @@ export class CarBlockIterator extends CarIteratorBase {
    * Get the list of roots defined by the CAR referenced by this iterator. May be
    * zero or more `CID`s.
    *
-   * @method getRoots
+   * @function getRoots
    * @memberof CarBlockIterator
    * @instance
    * @async
@@ -172,7 +172,7 @@ export class CarCIDIterator extends CarIteratorBase {
    * Get the list of roots defined by the CAR referenced by this iterator. May be
    * zero or more `CID`s.
    *
-   * @method getRoots
+   * @function getRoots
    * @memberof CarCIDIterator
    * @instance
    * @async

package/{lib → src}/reader-browser.js

@@ -2,8 +2,8 @@ import { asyncIterableReader, bytesReader, createDecoder } from './decoder.js'
 
 /**
  * @typedef {import('multiformats').CID} CID
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').CarReader} CarReaderIface
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').CarReader} CarReaderIface
  * @typedef {import('./coding').BytesReader} BytesReader
  * @typedef {import('./coding').CarHeader} CarHeader
  * @typedef {import('./coding').CarV2Header} CarV2Header
@@ -55,7 +55,7 @@ export class CarReader {
    * Get the list of roots defined by the CAR referenced by this reader. May be
    * zero or more `CID`s.
    *
-   * @method
+   * @function
    * @memberof CarReader
    * @instance
    * @async
@@ -71,7 +71,7 @@ export class CarReader {
    * Check whether a given `CID` exists within the CAR referenced by this
    * reader.
    *
-   * @method
+   * @function
    * @memberof CarReader
    * @instance
    * @async
@@ -90,7 +90,7 @@ export class CarReader {
    * the provided `CID` doesn't exist within the CAR, `undefined` will be
    * returned.
    *
-   * @method
+   * @function
    * @memberof CarReader
    * @instance
    * @async
@@ -109,7 +109,7 @@ export class CarReader {
    * of the `Block`s (`{ cid:CID, bytes:Uint8Array }` pairs) contained within
    * the CAR referenced by this reader.
    *
-   * @method
+   * @function
    * @memberof CarReader
    * @instance
    * @async
@@ -126,7 +126,7 @@ export class CarReader {
    * Returns a `CIDIterator` (`AsyncIterable<CID>`) that iterates over all of
    * the `CID`s contained within the CAR referenced by this reader.
    *
-   * @method
+   * @function
    * @memberof CarReader
    * @instance
    * @async

package/{lib → src}/reader.js

@@ -3,9 +3,9 @@ import { promisify } from 'util'
 import { CarReader as BrowserCarReader } from './reader-browser.js'
 
 /**
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').BlockIndex} BlockIndex
- * @typedef {import('../api').CarReader} CarReaderIface
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').BlockIndex} BlockIndex
+ * @typedef {import('./api').CarReader} CarReaderIface
  */
 
 const fsread = promisify(fs.read)
@@ -27,10 +27,10 @@ export class CarReader extends BrowserCarReader {
    * @async
    * @static
    * @memberof CarReader
-   * @param {fs.promises.FileHandle | number} fd A file descriptor from the
+   * @param {fs.promises.FileHandle | number} fd - A file descriptor from the
    * Node.js `fs` module. Either an integer, from `fs.open()` or a `FileHandle`
    * from `fs.promises.open()`.
-   * @param {BlockIndex} blockIndex An index pointing to the location of the
+   * @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 {Promise<Block>} A `{ cid:CID, bytes:Uint8Array }` pair.

package/{lib → src}/writer-browser.js

@@ -4,9 +4,9 @@ import { create as iteratorChannel } from './iterator-channel.js'
 import { bytesReader, readHeader } from './decoder.js'
 
 /**
- * @typedef {import('../api').Block} Block
- * @typedef {import('../api').BlockWriter} BlockWriter
- * @typedef {import('../api').WriterChannel} WriterChannel
+ * @typedef {import('./api').Block} Block
+ * @typedef {import('./api').BlockWriter} BlockWriter
+ * @typedef {import('./api').WriterChannel} WriterChannel
  * @typedef {import('./coding').CarEncoder} CarEncoder
  * @typedef {import('./coding').IteratorChannel<Uint8Array>} IteratorChannel
  */
@@ -62,11 +62,11 @@ export class CarWriter {
   /**
    * Write a `Block` (a `{ cid:CID, bytes:Uint8Array }` pair) to the archive.
    *
-   * @method
+   * @function
    * @memberof CarWriter
    * @instance
    * @async
-   * @param {Block} block A `{ cid:CID, bytes:Uint8Array }` pair.
+   * @param {Block} block - A `{ cid:CID, bytes:Uint8Array }` pair.
    * @returns {Promise<void>} The returned promise will only resolve once the
    * bytes this block generates are written to the `out` iterable.
    */
@@ -91,7 +91,7 @@ export class CarWriter {
    * Finalise the CAR archive and signal that the `out` iterable should end once
    * any remaining bytes are written.
    *
-   * @method
+   * @function
    * @memberof CarWriter
    * @instance
    * @async
@@ -166,7 +166,7 @@ export class CarWriter {
    * @static
    * @memberof CarWriter
    * @param {Uint8Array} bytes
-   * @param {CID[]} roots A new list of roots to replace the existing list in
+   * @param {CID[]} roots - A new list of roots to replace the existing list in
    * the CAR header. The new header must take up the same number of bytes as the
    * existing header, so the roots should collectively be the same byte length
    * as the existing roots.

package/{lib → src}/writer.js

@@ -9,7 +9,7 @@ const fswrite = promisify(fs.write)
 
 /**
  * @typedef {import('multiformats/cid').CID} CID
- * @typedef {import('../api').BlockWriter} BlockWriter
+ * @typedef {import('./api').BlockWriter} BlockWriter
  */
 
 /**
@@ -35,10 +35,10 @@ export class CarWriter extends BrowserCarWriter {
    * @async
    * @static
    * @memberof CarWriter
-   * @param {fs.promises.FileHandle | number} fd A file descriptor from the
+   * @param {fs.promises.FileHandle | number} fd - A file descriptor from the
    * Node.js `fs` module. Either an integer, from `fs.open()` or a `FileHandle`
    * from `fs.promises.open()`.
-   * @param {CID[]} roots A new list of roots to replace the existing list in
+   * @param {CID[]} roots - A new list of roots to replace the existing list in
    * the CAR header. The new header must take up the same number of bytes as the
    * existing header, so the roots should collectively be the same byte length
    * as the existing roots.

package/LICENSE-APACHE

@@ -1,13 +0,0 @@
-Copyright 2020 Protocol Labs
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.

package/LICENSE-MIT

@@ -1,7 +0,0 @@
-Copyright 2020 Protocol Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/buffer-writer

@@ -1 +0,0 @@
-module.exports = require('./cjs/lib/buffer-writer.js')

package/car-browser.js

@@ -1,14 +0,0 @@
-import { CarReader } from './lib/reader-browser.js'
-import { CarIndexer } from './lib/indexer.js'
-import { CarBlockIterator, CarCIDIterator } from './lib/iterator.js'
-import { CarWriter } from './lib/writer-browser.js'
-import { CarIndexedReader } from './lib/indexed-reader-browser.js'
-
-export {
-  CarReader,
-  CarIndexer,
-  CarBlockIterator,
-  CarCIDIterator,
-  CarWriter,
-  CarIndexedReader
-}

package/car.js

@@ -1,16 +0,0 @@
-import { CarReader } from './lib/reader.js'
-import { CarIndexer } from './lib/indexer.js'
-import { CarBlockIterator, CarCIDIterator } from './lib/iterator.js'
-import { CarWriter } from './lib/writer.js'
-import { CarIndexedReader } from './lib/indexed-reader.js'
-import * as CarBufferWriter from './lib/buffer-writer.js'
-
-export {
-  CarReader,
-  CarIndexer,
-  CarBlockIterator,
-  CarCIDIterator,
-  CarWriter,
-  CarIndexedReader,
-  CarBufferWriter
-}