microcbor 0.4.0 → 1.0.0

package/README.md

@@ -1,24 +1,38 @@
 # microcbor
 
-[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg)](https://github.com/RichardLitt/standard-readme) [![license](https://img.shields.io/github/license/joeltg/microcbor)](https://opensource.org/licenses/MIT) [![NPM version](https://img.shields.io/npm/v/microcbor)](https://www.npmjs.com/package/microcbor) ![TypeScript types](https://img.shields.io/npm/types/microcbor) ![lines of code](https://img.shields.io/tokei/lines/github/joeltg/microcbor)
+[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg)](https://github.com/RichardLitt/standard-readme) [![license](https://img.shields.io/github/license/joeltg/microcbor)](https://opensource.org/licenses/MIT) [![NPM version](https://img.shields.io/npm/v/microcbor)](https://www.npmjs.com/package/microcbor) ![TypeScript types](https://img.shields.io/npm/types/microcbor)
 
 Encode JavaScript values as canonical CBOR.
 
 microcbor is a minimal JavaScript [CBOR](https://cbor.io/) implementation featuring
 
-- a small footprint,
-- fast performance, and
-- `Iterable` and `AsyncIterable` streaming interfaces
+- small footprint
+- fast performance
+- `Iterable` and `AsyncIterable` streaming APIs with "chunk recycling" encoding option
+- [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)-compatible [TransformStream](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) classes
 
-microcbor follows the [deterministic CBOR encoding requirements](https://www.rfc-editor.org/rfc/rfc8949.html#core-det) - all floating-point numbers are serialized in the smallest possible size without losing precision, and object entries are always sorted by key in byte-wise lexicographic order. `NaN` is always serialized as `0xf97e00`. **microcbor doesn't support tags, bigints, typed arrays, non-string keys, or indefinite-length collections.**
+microcbor follows the [deterministic CBOR encoding requirements](https://www.rfc-editor.org/rfc/rfc8949.html#core-det) - all floating-point numbers are serialized in the smallest possible size without losing precision, and object entries are always sorted by key in byte-wise utf-8 lexicographic order. `NaN` is always serialized as `0xf97e00`. **microcbor doesn't support tags, bigints, typed arrays, non-string keys, or indefinite-length collections.**
 
-This library is TypeScript-native, ESM-only, and has just one dependency [joeltg/fp16](https://github.com/joeltg/fp16) for half-precision floats. It works in Node, the browser, and Deno.
+This library is TypeScript-native, ESM-only, and has just **one dependency** [joeltg/fp16](https://github.com/joeltg/fp16) for half-precision floats.
 
 ## Table of Contents
 
 - [Install](#install)
 - [Usage](#usage)
 - [API](#api)
+  - [CBOR Values](#cbor-values)
+  - [Encoding](#encoding)
+    - [`EncodeOptions`](#encodeoptions)
+    - [`encodingLength`](#encodinglength)
+    - [`encode`](#encode)
+    - [`encodeIterable`](#encodeiterable)
+    - [`encodeAsyncIterable`](#encodeasynciterable)
+    - [`CBOREncoderStream`](#cborencoderstream)
+  - [Decoding](#decoding)
+    - [`decode`](#decode)
+    - [`decodeIterable`](#decodeiterable)
+    - [`decodeAsyncIterable`](#decodeasynciterable)
+    - [`CBORDecoderStream`](#cbordecoderstream)
 - [Value mapping](#value-mapping)
 - [Testing](#testing)
 - [Benchmarks](#benchmarks)
@@ -31,12 +45,6 @@ This library is TypeScript-native, ESM-only, and has just one dependency [joeltg
 npm i microcbor
 ```
 
-Or in Deno:
-
-```typescript
-import { encode, decode } from "https://cdn.skypack.dev/microcbor"
-```
-
 ## Usage
 
 ```typescript
@@ -57,6 +65,8 @@ console.log(decode(data))
 
 ## API
 
+### CBOR Values
+
 ```ts
 declare type CBORValue = undefined | null | boolean | number | string | Uint8Array | CBORArray | CBORMap
 
@@ -64,27 +74,125 @@ interface CBORArray extends Array<CBORValue> {}
 interface CBORMap {
   [key: string]: CBORValue
 }
+```
 
-// If not provided, chunkSize defaults to 512 bytes.
-// It's only a guideline; `encodeStream` won't break up
-// individual CBOR values like strings or byte arrays
-// that are larger than the provided chunk size.
-declare function encode(value: CBORValue, options?: { chunkSize?: number }): Uint8Array
+### Encoding
 
-declare function encodeStream(
-  source: AsyncIterable<CBORValue>,
-  options?: { chunkSize?: number },
-): AsyncIterable<Uint8Array>
+#### `EncodeOptions`
 
-declare function decode(data: Uint8Array): CBORValue
+```ts
+export interface EncodeOptions {
+  /**
+   * Re-use the same underlying ArrayBuffer for all yielded chunks.
+   * If this is enabled, the consumer must copy each chunk content
+   * themselves to a new buffer if they wish to keep it.
+   * This mode is useful for efficiently hashing objects without
+   * ever allocating memory for the entire encoded result.
+   * @default false
+   */
+  chunkRecycling?: boolean
+
+  /**
+   * Maximum chunk size.
+   * @default 4096
+   */
+  chunkSize?: number
+
+  /**
+   * Minimum bitsize for floating-point numbers: 16, 32, or 64.
+   * @default 16
+   */
+  minFloatSize?: (typeof FloatSize)[keyof typeof FloatSize]
+}
+```
 
-declare function decodeStream(source: AsyncIterable<Uint8Array>): AsyncIterable<CBORValue>
+#### `encodingLength`
 
-// You can measure the byte length that a given value will
-// serialize to without actually allocating anything.
+```ts
+/**
+ * Calculate the byte length that a value will encode into
+ * without actually allocating anything.
+ */
 declare function encodingLength(value: CBORValue): number
 ```
 
+#### `encode`
+
+```ts
+/**
+ * Encode a single CBOR value.
+ * options.chunkRecycling has no effect here.
+ */
+export function encode(value: CBORValue, options: EncodeOptions = {}): Uint8Array
+```
+
+#### `encodeIterable`
+
+```ts
+/** Encode an iterable of CBOR values into an iterable of Uint8Array chunks */
+export function* encodeIterable(
+  source: Iterable<CBORValue>,
+  options: EncodeOptions = {},
+): IterableIterator<Uint8Array>
+
+```
+
+#### `encodeAsyncIterable`
+
+```ts
+/** Encode an async iterable of CBOR values into an async iterable of Uint8Array chunks */
+export async function* encodeAsyncIterable(
+  source: AsyncIterable<CBORValue>,
+  options: EncodeOptions = {},
+): AsyncIterableIterator<Uint8Array>
+
+```
+
+#### `CBOREncoderStream`
+
+```ts
+/**
+ * Encode a Web Streams API ReadableStream.
+ * options.chunkRecycling has no effect here.
+ */
+export class CBOREncoderStream extends TransformStream<CBORValue, Uint8Array> {
+  public constructor(options: EncodeOptions = {})
+}
+```
+
+### Decoding
+
+#### `decode`
+
+```ts
+/** Decode a single CBOR value. */
+export function decode(data: Uint8Array): CBORValue
+```
+
+#### `decodeIterable`
+
+```ts
+/** Decode an iterable of Uint8Array chunks into an iterable of CBOR values */
+export function* decodeIterable(source: Iterable<Uint8Array>): IterableIterator<CBORValue>
+
+```
+
+#### `decodeAsyncIterable`
+
+```ts
+/** Decode an async iterable of Uint8Array chunks into an async iterable of CBOR values */
+export async function* decodeAsyncIterable(source: AsyncIterable<Uint8Array>): AsyncIterable<CBORValue>
+```
+
+#### `CBORDecoderStream`
+
+```ts
+/** Decode a Web Streams API ReadableStream. */
+export class CBORDecoderStream extends TransformStream<Uint8Array, CBORValue> {
+  public constructor()
+}
+```
+
 ## Unsafe integer handling
 
 - JavaScript integers below `Number.MIN_SAFE_INTEGER` or greater than `Number.MAX_SAFE_INTEGER` will encode as CBOR floating-point numbers, as per the [suggestion in the CBOR spec](https://www.rfc-editor.org/rfc/rfc8949.html#name-converting-from-json-to-cbo).
@@ -125,40 +233,48 @@ npm run test
 - microcbor runs isomorphically on the web, in Node, and in Deno. node-cbor ships a separate cbor-web package.
 - microcbor encodes `Uint8Array` values as CBOR byte strings (major type 2). node-cbor encodes `Uint8Array` values as tagged type arrays (major type 6 / RFC 8746), and encodes NodeJS `Buffer` values as CBOR byte strings (major type 2).
 - microcbor uses async iterables for its streaming API. node-cbor uses NodeJS streams.
-- microcbor is about **5x faster** than node-cbor at encoding, and comparable at decoding.
+- microcbor is about **4x faster** than node-cbor at canonical encoding, ~2x faster than node-cbor's default non-canonical encoding, and ~1.5x faster than node-cbor at decoding.
 
 ```
 microcbor % npm run test -- test/benchmarks.test.ts
 
-> microcbor@0.3.0 test
+> microcbor@0.4.0 test
 > ava test/benchmarks.test.ts
 
-  ✔ time encode() (196ms)
+
+  ✔ time encode() (237ms)
     ℹ microcbor: {
-        avg: 0.20750288999999897,
-        std: 0.1599497238014431,
+        avg: 0.2836770999999993,
+        std: 0.1553461595001637,
       } (ms)
     ℹ node-cbor: {
-        avg: 1.012210439999998,
-        std: 1.1648550529513988,
+        avg: 0.47247252999999945,
+        std: 0.6099837601508338,
+      } (ms)
+    ℹ node-cbor (canonical): {
+        avg: 0.9973837600000031,
+        std: 1.203792591464195,
       } (ms)
     ℹ JSON.stringify: {
-        avg: 0.011432450000000358,
-        std: 0.0014736483187953618,
+        avg: 0.009709539999999493,
+        std: 0.0014329558361671918,
       } (ms)
   ✔ time decode()
     ℹ microcbor: {
-        avg: 0.3199704100000008,
-        std: 0.6562532760030573,
+        avg: 0.19635871000000235,
+        std: 0.35634472331099276,
       } (ms)
     ℹ node-cbor: {
-        avg: 0.35316917000000214,
-        std: 0.32859580328312393,
+        avg: 0.35364794999999843,
+        std: 0.31256985912702206,
       } (ms)
     ℹ JSON.parse: {
-        avg: 0.016885789999999474,
-        std: 0.0041605677456241505,
+        avg: 0.018565019999997504,
+        std: 0.004339636959421219,
       } (ms)
+  ─
+
+  2 tests passed
 ```
 
 ## Contributing

package/lib/CBORDecoderStream.d.ts

@@ -0,0 +1,5 @@
+import { CBORValue } from "./types.js";
+/** Decode a Web Streams API ReadableStream */
+export declare class CBORDecoderStream extends TransformStream<Uint8Array, CBORValue> {
+    constructor();
+}

package/lib/CBORDecoderStream.js

@@ -0,0 +1,37 @@
+import { Decoder } from "./decodeAsyncIterable.js";
+/** Decode a Web Streams API ReadableStream */
+export class CBORDecoderStream extends TransformStream {
+    constructor() {
+        let readableController;
+        const readable = new ReadableStream({
+            start(controller) {
+                readableController = controller;
+            },
+        });
+        // We need to track whick chunks have been "processed" and only resolve each
+        // .transform() promise once all data from each chunk has been enqueued.
+        const chunks = new WeakMap();
+        async function pipe(controller) {
+            const decoder = new Decoder(readable.values(), {
+                onFree: (chunk) => chunks.get(chunk)?.resolve(),
+            });
+            for await (const value of decoder) {
+                controller.enqueue(value);
+            }
+        }
+        super({
+            start(controller) {
+                pipe(controller).catch((err) => controller.error(err));
+            },
+            transform(chunk) {
+                return new Promise((resolve) => {
+                    chunks.set(chunk, { resolve });
+                    readableController.enqueue(chunk);
+                });
+            },
+            flush() {
+                readableController.close();
+            },
+        });
+    }
+}

package/lib/CBOREncoderStream.d.ts

@@ -0,0 +1,9 @@
+import { CBORValue } from "./types.js";
+import { EncodeOptions } from "./Encoder.js";
+/**
+ * Encode a Web Streams API ReadableStream.
+ * options.chunkRecycling has no effect here.
+ */
+export declare class CBOREncoderStream extends TransformStream<CBORValue, Uint8Array> {
+    constructor(options?: EncodeOptions);
+}

package/lib/CBOREncoderStream.js

@@ -0,0 +1,24 @@
+import { Encoder } from "./Encoder.js";
+/**
+ * Encode a Web Streams API ReadableStream.
+ * options.chunkRecycling has no effect here.
+ */
+export class CBOREncoderStream extends TransformStream {
+    constructor(options = {}) {
+        const encoder = new Encoder({ ...options, chunkRecycling: false });
+        super({
+            transform(value, controller) {
+                // Encode the incoming value and push all resulting chunks
+                for (const chunk of encoder.encodeValue(value)) {
+                    controller.enqueue(chunk);
+                }
+            },
+            flush(controller) {
+                // Push any remaining chunks when the stream is closing
+                for (const chunk of encoder.flush()) {
+                    controller.enqueue(chunk);
+                }
+            },
+        });
+    }
+}

package/lib/{decode.d.ts → Decoder.d.ts}

@@ -17,4 +17,5 @@ export declare class Decoder {
     private getArgument;
     decodeValue(): CBORValue;
 }
+/** Decode a single CBOR value */
 export declare function decode(data: Uint8Array): CBORValue;

package/lib/{decode.js → Decoder.js}

@@ -154,6 +154,7 @@ export class Decoder {
     }
 }
 _Decoder_offset = new WeakMap(), _Decoder_view = new WeakMap();
+/** Decode a single CBOR value */
 export function decode(data) {
     return new Decoder(data).decodeValue();
 }

package/lib/Encoder.d.ts

@@ -0,0 +1,65 @@
+import type { CBORValue } from "./types.js";
+export declare const FloatSize: {
+    f16: number;
+    f32: number;
+    f64: number;
+};
+export interface EncodeOptions {
+    /**
+     * Re-use the same underlying ArrayBuffer for all yielded chunks.
+     * If this is enabled, the consumer must copy each chunk content
+     * themselves to a new buffer if they wish to keep it.
+     * This mode is useful for efficiently hashing objects without
+     * ever allocating memory for the entire encoded result.
+     * @default false
+     */
+    chunkRecycling?: boolean;
+    /**
+     * Maximum chunk size
+     * @default 4096
+     */
+    chunkSize?: number;
+    /**
+     * Minimum bitsize for floating-point numbers: 16, 32, or 64
+     * @default 16
+     */
+    minFloatSize?: (typeof FloatSize)[keyof typeof FloatSize];
+}
+export declare class Encoder {
+    #private;
+    static defaultChunkSize: number;
+    readonly chunkRecycling: boolean;
+    readonly chunkSize: number;
+    readonly minFloatSize: (typeof FloatSize)[keyof typeof FloatSize];
+    private readonly encoder;
+    private readonly buffer;
+    private readonly view;
+    private readonly array;
+    private offset;
+    constructor(options?: EncodeOptions);
+    get closed(): boolean;
+    private allocate;
+    private float16;
+    private float32;
+    private float64;
+    private uint8;
+    private uint16;
+    private uint32;
+    private uint64;
+    private encodeTypeAndArgument;
+    private encodeNumber;
+    private encodeInteger;
+    private encodeFloat;
+    private encodeString;
+    private encodeBytes;
+    private writeBytes;
+    encodeValue(value: CBORValue): Iterable<Uint8Array>;
+    flush(): Iterable<Uint8Array>;
+    private static compareEntries;
+    private static getAdditionalInformation;
+}
+/**
+ * Encode a single CBOR value.
+ * options.chunkRecycling has no effect here.
+ */
+export declare function encode(value: CBORValue, options?: EncodeOptions): Uint8Array;

package/lib/{encode.js → Encoder.js}

@@ -10,19 +10,25 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _Encoder_instances, _Encoder_closed, _Encoder_flush;
-import { getFloat16Precision, getFloat32Precision, setFloat16, Precision } from "fp16";
-import { getByteLength } from "./encodingLength.js";
+import { Precision, getFloat16Precision, getFloat32Precision, setFloat16 } from "fp16";
 import { assert } from "./utils.js";
+export const FloatSize = {
+    f16: 16,
+    f32: 32,
+    f64: 64,
+};
 export class Encoder {
     constructor(options = {}) {
         _Encoder_instances.add(this);
         _Encoder_closed.set(this, void 0);
         this.encoder = new TextEncoder();
-        this.noCopy = options.noCopy ?? false;
+        this.minFloatSize = options.minFloatSize ?? 16;
+        this.chunkRecycling = options.chunkRecycling ?? false;
         this.chunkSize = options.chunkSize ?? Encoder.defaultChunkSize;
         assert(this.chunkSize >= 8, "expected chunkSize >= 8");
         this.buffer = new ArrayBuffer(this.chunkSize);
         this.view = new DataView(this.buffer);
+        this.array = new Uint8Array(this.buffer, 0, this.chunkSize);
         this.offset = 0;
         __classPrivateFieldSet(this, _Encoder_closed, false, "f");
     }
@@ -107,11 +113,11 @@ export class Encoder {
         }
     }
     *encodeFloat(value) {
-        if (getFloat16Precision(value) === Precision.Exact) {
+        if (this.minFloatSize === FloatSize.f16 && getFloat16Precision(value) === Precision.Exact) {
             yield* this.uint8(0xe0 | 25);
             yield* this.float16(value);
         }
-        else if (getFloat32Precision(value) === Precision.Exact) {
+        else if (this.minFloatSize <= FloatSize.f32 && getFloat32Precision(value) === Precision.Exact) {
             yield* this.uint8(0xe0 | 26);
             yield* this.float32(value);
         }
@@ -121,23 +127,27 @@ export class Encoder {
         }
     }
     *encodeString(value) {
-        const byteLength = getByteLength(value);
-        yield* this.encodeTypeAndArgument(3, byteLength);
-        let start = 0;
-        while (start < value.length) {
-            if (this.offset + 4 > this.buffer.byteLength) {
-                yield __classPrivateFieldGet(this, _Encoder_instances, "m", _Encoder_flush).call(this);
-            }
-            const target = new Uint8Array(this.buffer, this.offset);
-            const result = this.encoder.encodeInto(value.slice(start), target);
-            start += result.read;
-            this.offset += result.written;
-            assert(this.offset <= this.buffer.byteLength, "expected this.offset <= this.buffer.byteLength");
-        }
+        const bytes = this.encoder.encode(value);
+        yield* this.encodeTypeAndArgument(3, bytes.byteLength);
+        yield* this.writeBytes(bytes);
+        // const byteLength = getByteLength(value)
+        // let start = 0
+        // while (start < value.length) {
+        // 	if (this.offset + 4 > this.buffer.byteLength) {
+        // 		yield this.#flush()
+        // 	}
+        // 	const target = new Uint8Array(this.buffer, this.offset)
+        // 	const result = this.encoder.encodeInto(value.slice(start), target)
+        // 	start += result.read
+        // 	this.offset += result.written
+        // 	assert(this.offset <= this.buffer.byteLength, "expected this.offset <= this.buffer.byteLength")
+        // }
     }
     *encodeBytes(value) {
         yield* this.encodeTypeAndArgument(2, value.byteLength);
-        const target = new Uint8Array(this.buffer, 0, this.buffer.byteLength);
+        yield* this.writeBytes(value);
+    }
+    *writeBytes(value) {
         let start = 0;
         while (start < value.byteLength) {
             if (this.offset >= this.buffer.byteLength) {
@@ -146,7 +156,7 @@ export class Encoder {
             const capacity = this.buffer.byteLength - this.offset;
             const remaining = value.byteLength - start;
             const chunkLength = Math.min(capacity, remaining);
-            target.set(value.subarray(start, start + chunkLength), this.offset);
+            this.array.set(value.subarray(start, start + chunkLength), this.offset);
             start += chunkLength;
             this.offset += chunkLength;
         }
@@ -183,11 +193,14 @@ export class Encoder {
             }
         }
         else {
-            const keys = Object.keys(value).sort(Encoder.compareKeys);
-            yield* this.encodeTypeAndArgument(5, keys.length);
-            for (const key of keys) {
-                yield* this.encodeString(key);
-                yield* this.encodeValue(value[key]);
+            const entries = Object.entries(value)
+                .map(([key, value]) => [this.encoder.encode(key), value])
+                .sort(Encoder.compareEntries);
+            yield* this.encodeTypeAndArgument(5, entries.length);
+            for (const [key, value] of entries) {
+                yield* this.encodeTypeAndArgument(3, key.byteLength);
+                yield* this.writeBytes(key);
+                yield* this.encodeValue(value);
             }
         }
     }
@@ -195,31 +208,30 @@ export class Encoder {
         if (__classPrivateFieldGet(this, _Encoder_closed, "f")) {
             return;
         }
-        __classPrivateFieldSet(this, _Encoder_closed, true, "f");
         if (this.offset > 0) {
-            yield new Uint8Array(this.buffer, 0, this.offset);
+            yield __classPrivateFieldGet(this, _Encoder_instances, "m", _Encoder_flush).call(this);
         }
     }
     // Per the deterministic CBOR spec, we're supposed to sort keys
     // the byte-wise lexicographic order of the key's CBOR encoding
-    // - ie lower major types come before higher major types!
-    // However, microcbor only supports string keys, which means we
-    // can get away with sorting them without actually encoding them
-    // first. One thing we know for sure about strings is that a
-    // string with a smaller length will sort byte-wise before a string
+    // - ie lower major types come before higher major types.
+    // One thing we know for sure about strings is that a string with
+    // a smaller length will sort byte-wise before a string
     // with a longer length, since strings are encoded with a length
     // prefix (either in the additionalInformation bits, if < 24, or
     // in the next serveral bytes, but in all cases the order holds).
-    static compareKeys(a, b) {
-        if (a.length < b.length) {
+    static compareEntries([a], [b]) {
+        if (a.byteLength < b.byteLength)
             return -1;
-        }
-        else if (b.length < a.length) {
+        if (b.byteLength < a.byteLength)
             return 1;
+        for (let i = 0; i < a.byteLength; i++) {
+            if (a[i] < b[i])
+                return -1;
+            if (b[i] < a[i])
+                return 1;
         }
-        else {
-            return a < b ? -1 : 1;
-        }
+        return 0;
     }
     static getAdditionalInformation(argument) {
         if (argument < 24) {
@@ -240,7 +252,7 @@ export class Encoder {
     }
 }
 _Encoder_closed = new WeakMap(), _Encoder_instances = new WeakSet(), _Encoder_flush = function _Encoder_flush() {
-    if (this.noCopy) {
+    if (this.chunkRecycling) {
         const chunk = new Uint8Array(this.buffer, 0, this.offset);
         this.offset = 0;
         return chunk;
@@ -252,9 +264,13 @@ _Encoder_closed = new WeakMap(), _Encoder_instances = new WeakSet(), _Encoder_fl
         return chunk;
     }
 };
-Encoder.defaultChunkSize = 512;
+Encoder.defaultChunkSize = 4096;
+/**
+ * Encode a single CBOR value.
+ * options.chunkRecycling has no effect here.
+ */
 export function encode(value, options = {}) {
-    const encoder = new Encoder(options);
+    const encoder = new Encoder({ ...options, chunkRecycling: false });
     let byteLength = 0;
     const chunks = [];
     for (const chunk of encoder.encodeValue(value)) {

package/lib/decodeAsyncIterable.d.ts

@@ -0,0 +1,37 @@
+import type { CBORValue } from "./types.js";
+export declare class Decoder implements AsyncIterableIterator<CBORValue> {
+    private offset;
+    private byteLength;
+    private readonly chunks;
+    private readonly constantBuffer;
+    private readonly constantView;
+    private readonly iter;
+    private readonly onFree?;
+    constructor(source: AsyncIterable<Uint8Array>, options?: {
+        onFree?: (chunk: Uint8Array) => void;
+    });
+    [Symbol.asyncIterator]: () => this;
+    private allocate;
+    private fill;
+    private constant;
+    private float16;
+    private float32;
+    private float64;
+    private uint8;
+    private uint16;
+    private uint32;
+    private uint64;
+    private decodeBytes;
+    private decodeString;
+    private getArgument;
+    next(): Promise<{
+        done: true;
+        value: undefined;
+    } | {
+        done: false;
+        value: CBORValue;
+    }>;
+    private decodeValue;
+}
+/** Decode an async iterable of Uint8Array chunks into an async iterable of CBOR values */
+export declare function decodeAsyncIterable(source: AsyncIterable<Uint8Array>): AsyncIterableIterator<CBORValue>;

package/lib/{decodeStream.js → decodeAsyncIterable.js}

@@ -1,8 +1,8 @@
 var _a;
 import { getFloat16 } from "fp16";
 import { UnsafeIntegerError, maxSafeInteger, minSafeInteger } from "./utils.js";
-class DecoderStream {
-    constructor(source) {
+export class Decoder {
+    constructor(source, options = {}) {
         this.offset = 0;
         this.byteLength = 0;
         this.chunks = [];
@@ -25,6 +25,7 @@ class DecoderStream {
         this.uint32 = this.constant(4, (view) => view.getUint32(0));
         this.uint64 = this.constant(8, (view) => view.getBigUint64(0));
         this.iter = source[Symbol.asyncIterator]();
+        this.onFree = options.onFree;
     }
     async allocate(size) {
         while (this.byteLength < size) {
@@ -64,6 +65,11 @@ class DecoderStream {
                 this.byteLength -= capacity;
             }
         }
+        if (this.onFree !== undefined) {
+            for (let i = 0; i < deleteCount; i++) {
+                this.onFree(this.chunks[i]);
+            }
+        }
         this.chunks.splice(0, deleteCount);
     }
     async decodeBytes(length) {
@@ -200,6 +206,7 @@ class DecoderStream {
     }
 }
 _a = Symbol.asyncIterator;
-export async function* decodeStream(source) {
-    yield* new DecoderStream(source);
+/** Decode an async iterable of Uint8Array chunks into an async iterable of CBOR values */
+export async function* decodeAsyncIterable(source) {
+    yield* new Decoder(source);
 }

package/lib/decodeIterable.d.ts

@@ -0,0 +1,3 @@
+import type { CBORValue } from "./types.js";
+/** Decode an iterable of Uint8Array chunks into an iterable of CBOR values */
+export declare function decodeIterable(source: Iterable<Uint8Array>): IterableIterator<CBORValue>;

package/lib/decodeIterable.js

@@ -0,0 +1,206 @@
+var _a;
+import { getFloat16 } from "fp16";
+import { UnsafeIntegerError, maxSafeInteger, minSafeInteger } from "./utils.js";
+class Decoder {
+    constructor(source) {
+        this.offset = 0;
+        this.byteLength = 0;
+        this.chunks = [];
+        this.constantBuffer = new ArrayBuffer(8);
+        this.constantView = new DataView(this.constantBuffer);
+        this[_a] = () => this;
+        this.constant = (size, f) => {
+            return () => {
+                this.allocate(size);
+                const array = new Uint8Array(this.constantBuffer, 0, size);
+                this.fill(array);
+                return f(this.constantView);
+            };
+        };
+        this.float16 = this.constant(2, (view) => getFloat16(view, 0));
+        this.float32 = this.constant(4, (view) => view.getFloat32(0));
+        this.float64 = this.constant(8, (view) => view.getFloat64(0));
+        this.uint8 = this.constant(1, (view) => view.getUint8(0));
+        this.uint16 = this.constant(2, (view) => view.getUint16(0));
+        this.uint32 = this.constant(4, (view) => view.getUint32(0));
+        this.uint64 = this.constant(8, (view) => view.getBigUint64(0));
+        this.iter = source[Symbol.iterator]();
+    }
+    allocate(size) {
+        while (this.byteLength < size) {
+            const { done, value } = this.iter.next();
+            if (done) {
+                throw new Error("stream ended prematurely");
+            }
+            else {
+                this.chunks.push(value);
+                this.byteLength += value.byteLength;
+            }
+        }
+    }
+    fill(target) {
+        if (this.byteLength < target.byteLength) {
+            throw new Error("internal error - please file a bug report!");
+        }
+        let byteLength = 0;
+        let deleteCount = 0;
+        for (let i = 0; byteLength < target.byteLength; i++) {
+            const chunk = this.chunks[i];
+            const capacity = target.byteLength - byteLength;
+            const length = chunk.byteLength - this.offset;
+            if (length <= capacity) {
+                // copy the entire remainder of the chunk
+                target.set(chunk.subarray(this.offset), byteLength);
+                byteLength += length;
+                deleteCount += 1;
+                this.offset = 0;
+                this.byteLength -= length;
+            }
+            else {
+                // fill the remainder of the target
+                target.set(chunk.subarray(this.offset, this.offset + capacity), byteLength);
+                byteLength += capacity; // equivalent to break
+                this.offset += capacity;
+                this.byteLength -= capacity;
+            }
+        }
+        this.chunks.splice(0, deleteCount);
+    }
+    decodeBytes(length) {
+        this.allocate(length);
+        const array = new Uint8Array(length);
+        this.fill(array);
+        return array;
+    }
+    decodeString(length) {
+        this.allocate(length);
+        const data = new Uint8Array(length);
+        this.fill(data);
+        return new TextDecoder().decode(data);
+    }
+    getArgument(additionalInformation) {
+        if (additionalInformation < 24) {
+            return { value: additionalInformation };
+        }
+        else if (additionalInformation === 24) {
+            return { value: this.uint8() };
+        }
+        else if (additionalInformation === 25) {
+            return { value: this.uint16() };
+        }
+        else if (additionalInformation === 26) {
+            return { value: this.uint32() };
+        }
+        else if (additionalInformation === 27) {
+            const uint64 = this.uint64();
+            const value = maxSafeInteger < uint64 ? Infinity : Number(uint64);
+            return { value, uint64 };
+        }
+        else if (additionalInformation === 31) {
+            throw new Error("microcbor does not support decoding indefinite-length items");
+        }
+        else {
+            throw new Error("invalid argument encoding");
+        }
+    }
+    next() {
+        while (this.byteLength === 0) {
+            const { done, value } = this.iter.next();
+            if (done) {
+                return { done: true, value: undefined };
+            }
+            else if (value.byteLength > 0) {
+                this.chunks.push(value);
+                this.byteLength += value.byteLength;
+            }
+        }
+        const value = this.decodeValue();
+        return { done: false, value };
+    }
+    decodeValue() {
+        const initialByte = this.uint8();
+        const majorType = initialByte >> 5;
+        const additionalInformation = initialByte & 0x1f;
+        if (majorType === 0) {
+            const { value, uint64 } = this.getArgument(additionalInformation);
+            if (uint64 !== undefined && maxSafeInteger < uint64) {
+                throw new UnsafeIntegerError("cannot decode integers greater than 2^53-1", uint64);
+            }
+            else {
+                return value;
+            }
+        }
+        else if (majorType === 1) {
+            const { value, uint64 } = this.getArgument(additionalInformation);
+            if (uint64 !== undefined && -1n - uint64 < minSafeInteger) {
+                throw new UnsafeIntegerError("cannot decode integers less than -2^53+1", -1n - uint64);
+            }
+            else {
+                return -1 - value;
+            }
+        }
+        else if (majorType === 2) {
+            const { value: length } = this.getArgument(additionalInformation);
+            return this.decodeBytes(length);
+        }
+        else if (majorType === 3) {
+            const { value: length } = this.getArgument(additionalInformation);
+            return this.decodeString(length);
+        }
+        else if (majorType === 4) {
+            const { value: length } = this.getArgument(additionalInformation);
+            const value = new Array(length);
+            for (let i = 0; i < length; i++) {
+                value[i] = this.decodeValue();
+            }
+            return value;
+        }
+        else if (majorType === 5) {
+            const { value: length } = this.getArgument(additionalInformation);
+            const value = {};
+            for (let i = 0; i < length; i++) {
+                const key = this.decodeValue();
+                if (typeof key !== "string") {
+                    throw new Error("microcbor only supports string keys in objects");
+                }
+                value[key] = this.decodeValue();
+            }
+            return value;
+        }
+        else if (majorType === 6) {
+            throw new Error("microcbor does not support tagged data items");
+        }
+        else if (majorType === 7) {
+            switch (additionalInformation) {
+                case 20:
+                    return false;
+                case 21:
+                    return true;
+                case 22:
+                    return null;
+                case 23:
+                    return undefined;
+                case 24:
+                    throw new Error("microcbor does not support decoding unassigned simple values");
+                case 25:
+                    return this.float16();
+                case 26:
+                    return this.float32();
+                case 27:
+                    return this.float64();
+                case 31:
+                    throw new Error("microcbor does not support decoding indefinite-length items");
+                default:
+                    throw new Error("invalid simple value");
+            }
+        }
+        else {
+            throw new Error("invalid major type");
+        }
+    }
+}
+_a = Symbol.iterator;
+/** Decode an iterable of Uint8Array chunks into an iterable of CBOR values */
+export function* decodeIterable(source) {
+    yield* new Decoder(source);
+}

package/lib/encodeAsyncIterable.d.ts

@@ -0,0 +1,4 @@
+import type { CBORValue } from "./types.js";
+import { EncodeOptions } from "./Encoder.js";
+/** Encode an async iterable of CBOR values into an async iterable of Uint8Array chunks */
+export declare function encodeAsyncIterable(source: AsyncIterable<CBORValue>, options?: EncodeOptions): AsyncIterableIterator<Uint8Array>;

package/lib/encodeAsyncIterable.js

@@ -0,0 +1,9 @@
+import { Encoder } from "./Encoder.js";
+/** Encode an async iterable of CBOR values into an async iterable of Uint8Array chunks */
+export async function* encodeAsyncIterable(source, options = {}) {
+    const encoder = new Encoder(options);
+    for await (const value of source) {
+        yield* encoder.encodeValue(value);
+    }
+    yield* encoder.flush();
+}

package/lib/encodeIterable.d.ts

@@ -0,0 +1,4 @@
+import type { CBORValue } from "./types.js";
+import { EncodeOptions } from "./Encoder.js";
+/** Encode an iterable of CBOR values into an iterable of Uint8Array chunks */
+export declare function encodeIterable(source: Iterable<CBORValue>, options?: EncodeOptions): IterableIterator<Uint8Array>;

package/lib/encodeIterable.js

@@ -0,0 +1,9 @@
+import { Encoder } from "./Encoder.js";
+/** Encode an iterable of CBOR values into an iterable of Uint8Array chunks */
+export function* encodeIterable(source, options = {}) {
+    const encoder = new Encoder(options);
+    for (const value of source) {
+        yield* encoder.encodeValue(value);
+    }
+    yield* encoder.flush();
+}

package/lib/encodingLength.d.ts

@@ -1,3 +1,6 @@
-import type { CBORValue } from "./types.js";
+import { CBORValue } from "./types.js";
+/**
+ * Calculate the byte length that a value will encode into
+ * without actually allocating anything.
+ */
 export declare function encodingLength(value: CBORValue): number;
-export declare function getByteLength(string: string): number;

package/lib/encodingLength.js

@@ -1,4 +1,9 @@
-import { getFloat16Precision, getFloat32Precision, Precision } from "fp16";
+import { Precision, getFloat16Precision, getFloat32Precision } from "fp16";
+import { getByteLength } from "./utils.js";
+/**
+ * Calculate the byte length that a value will encode into
+ * without actually allocating anything.
+ */
 export function encodingLength(value) {
     if (value === false) {
         return 1;
@@ -104,63 +109,3 @@ function bytesEncodingLength(value) {
     const length = value.byteLength;
     return argumentEncodingLength(length) + length;
 }
-// https://github.com/feross/buffer/blob/57caad4450d241207066ca3832fb8e9095ad402f/index.js#L434
-export function getByteLength(string) {
-    let codePoint;
-    const length = string.length;
-    let leadSurrogate = null;
-    let bytes = 0;
-    for (let i = 0; i < length; ++i) {
-        codePoint = string.charCodeAt(i);
-        // is surrogate component
-        if (codePoint > 0xd7ff && codePoint < 0xe000) {
-            // last char was a lead
-            if (!leadSurrogate) {
-                // no lead yet
-                if (codePoint > 0xdbff) {
-                    // unexpected trail
-                    bytes += 3;
-                    continue;
-                }
-                else if (i + 1 === length) {
-                    // unpaired lead
-                    bytes += 3;
-                    continue;
-                }
-                // valid lead
-                leadSurrogate = codePoint;
-                continue;
-            }
-            // 2 leads in a row
-            if (codePoint < 0xdc00) {
-                bytes += 3;
-                leadSurrogate = codePoint;
-                continue;
-            }
-            // valid surrogate pair
-            codePoint = (((leadSurrogate - 0xd800) << 10) | (codePoint - 0xdc00)) + 0x10000;
-        }
-        else if (leadSurrogate) {
-            // valid bmp char, but last char was a lead
-            bytes += 3;
-        }
-        leadSurrogate = null;
-        // encode utf8
-        if (codePoint < 0x80) {
-            bytes += 1;
-        }
-        else if (codePoint < 0x800) {
-            bytes += 2;
-        }
-        else if (codePoint < 0x10000) {
-            bytes += 3;
-        }
-        else if (codePoint < 0x110000) {
-            bytes += 4;
-        }
-        else {
-            throw new Error("Invalid code point");
-        }
-    }
-    return bytes;
-}

package/lib/index.d.ts

@@ -1,7 +1,11 @@
 export type { CBORValue, CBORMap, CBORArray } from "./types.js";
-export { encode, Encoder } from "./encode.js";
-export { decode, Decoder } from "./decode.js";
-export { encodeStream } from "./encodeStream.js";
-export { decodeStream } from "./decodeStream.js";
 export { encodingLength } from "./encodingLength.js";
+export { Encoder, encode } from "./Encoder.js";
+export { Decoder, decode } from "./Decoder.js";
+export { encodeIterable } from "./encodeIterable.js";
+export { decodeIterable } from "./decodeIterable.js";
+export { encodeAsyncIterable } from "./encodeAsyncIterable.js";
+export { decodeAsyncIterable } from "./decodeAsyncIterable.js";
+export { CBORDecoderStream } from "./CBORDecoderStream.js";
+export { CBOREncoderStream } from "./CBOREncoderStream.js";
 export { UnsafeIntegerError } from "./utils.js";

package/lib/index.js

@@ -1,6 +1,10 @@
-export { encode, Encoder } from "./encode.js";
-export { decode, Decoder } from "./decode.js";
-export { encodeStream } from "./encodeStream.js";
-export { decodeStream } from "./decodeStream.js";
 export { encodingLength } from "./encodingLength.js";
+export { Encoder, encode } from "./Encoder.js";
+export { Decoder, decode } from "./Decoder.js";
+export { encodeIterable } from "./encodeIterable.js";
+export { decodeIterable } from "./decodeIterable.js";
+export { encodeAsyncIterable } from "./encodeAsyncIterable.js";
+export { decodeAsyncIterable } from "./decodeAsyncIterable.js";
+export { CBORDecoderStream } from "./CBORDecoderStream.js";
+export { CBOREncoderStream } from "./CBOREncoderStream.js";
 export { UnsafeIntegerError } from "./utils.js";

package/lib/utils.d.ts

@@ -10,3 +10,4 @@ export declare class AssertError extends Error {
     constructor(message: string, props?: any | undefined);
 }
 export declare function assert(condition: unknown, message?: string, props?: any): asserts condition;
+export declare function getByteLength(string: string): number;

package/lib/utils.js

@@ -18,3 +18,63 @@ export function assert(condition, message = "assertion failed", props) {
         throw new AssertError(message, props);
     }
 }
+// https://github.com/feross/buffer/blob/57caad4450d241207066ca3832fb8e9095ad402f/index.js#L434
+export function getByteLength(string) {
+    let codePoint;
+    const length = string.length;
+    let leadSurrogate = null;
+    let bytes = 0;
+    for (let i = 0; i < length; ++i) {
+        codePoint = string.charCodeAt(i);
+        // is surrogate component
+        if (codePoint > 0xd7ff && codePoint < 0xe000) {
+            // last char was a lead
+            if (!leadSurrogate) {
+                // no lead yet
+                if (codePoint > 0xdbff) {
+                    // unexpected trail
+                    bytes += 3;
+                    continue;
+                }
+                else if (i + 1 === length) {
+                    // unpaired lead
+                    bytes += 3;
+                    continue;
+                }
+                // valid lead
+                leadSurrogate = codePoint;
+                continue;
+            }
+            // 2 leads in a row
+            if (codePoint < 0xdc00) {
+                bytes += 3;
+                leadSurrogate = codePoint;
+                continue;
+            }
+            // valid surrogate pair
+            codePoint = (((leadSurrogate - 0xd800) << 10) | (codePoint - 0xdc00)) + 0x10000;
+        }
+        else if (leadSurrogate) {
+            // valid bmp char, but last char was a lead
+            bytes += 3;
+        }
+        leadSurrogate = null;
+        // encode utf8
+        if (codePoint < 0x80) {
+            bytes += 1;
+        }
+        else if (codePoint < 0x800) {
+            bytes += 2;
+        }
+        else if (codePoint < 0x10000) {
+            bytes += 3;
+        }
+        else if (codePoint < 0x110000) {
+            bytes += 4;
+        }
+        else {
+            throw new Error("Invalid code point");
+        }
+    }
+    return bytes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "microcbor",
-	"version": "0.4.0",
+	"version": "1.0.0",
 	"type": "module",
 	"files": [
 		"lib"
@@ -35,7 +35,7 @@
 		"@ava/typescript": "^5.0.0",
 		"@types/node": "^22.13.9",
 		"ava": "^6.2.0",
-		"cbor": "^8.1.0",
+		"cbor": "^10.0.3",
 		"typescript": "^5.6.0"
 	},
 	"dependencies": {

package/lib/decodeStream.d.ts

@@ -1,2 +0,0 @@
-import type { CBORValue } from "./types.js";
-export declare function decodeStream(source: AsyncIterable<Uint8Array>): AsyncIterable<CBORValue>;

package/lib/encode.d.ts

@@ -1,37 +0,0 @@
-import type { CBORValue } from "./types.js";
-export declare class Encoder {
-    #private;
-    static defaultChunkSize: number;
-    readonly noCopy: boolean;
-    readonly chunkSize: number;
-    private readonly encoder;
-    private readonly buffer;
-    private readonly view;
-    private offset;
-    constructor(options?: {
-        noCopy?: boolean;
-        chunkSize?: number;
-    });
-    get closed(): boolean;
-    private allocate;
-    private float16;
-    private float32;
-    private float64;
-    private uint8;
-    private uint16;
-    private uint32;
-    private uint64;
-    private encodeTypeAndArgument;
-    private encodeNumber;
-    private encodeInteger;
-    private encodeFloat;
-    private encodeString;
-    private encodeBytes;
-    encodeValue(value: CBORValue): Iterable<Uint8Array>;
-    flush(): Iterable<Uint8Array>;
-    private static compareKeys;
-    private static getAdditionalInformation;
-}
-export declare function encode(value: CBORValue, options?: {
-    chunkSize?: number;
-}): Uint8Array;

package/lib/encodeStream.d.ts

@@ -1,5 +0,0 @@
-import type { CBORValue } from "./types.js";
-export declare function encodeStream(source: AsyncIterable<CBORValue>, options?: {
-    chunkSize?: number;
-    noCopy?: boolean;
-}): AsyncIterable<Uint8Array>;

package/lib/encodeStream.js

@@ -1,8 +0,0 @@
-import { Encoder } from "./encode.js";
-export async function* encodeStream(source, options = {}) {
-    const encoder = new Encoder(options);
-    for await (const value of source) {
-        yield* encoder.encodeValue(value);
-    }
-    yield* encoder.flush();
-}