microcbor 0.3.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
-- an async iterable streaming API
+- 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,47 +65,134 @@ console.log(decode(data))
 
 ## API
 
+### CBOR Values
+
 ```ts
-declare type CBORValue =
-	| undefined
-	| null
-	| boolean
-	| number
-	| string
-	| Uint8Array
-	| CBORArray
-	| CBORMap
+declare type CBORValue = undefined | null | boolean | number | string | Uint8Array | CBORArray | CBORMap
 
 interface CBORArray extends Array<CBORValue> {}
 interface CBORMap {
-	[key: string]: CBORValue
+  [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).
@@ -105,7 +200,7 @@ declare function encodingLength(value: CBORValue): number
 
 ```typescript
 declare class UnsafeIntegerError extends RangeError {
-	readonly value: bigint
+  readonly value: bigint
 }
 ```
 
@@ -138,23 +233,45 @@ 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 **2x faster** than node-cbor at encoding and about **1.5x faster** than node-cbor 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.js
-
-> microcbor@0.2.0 test
-> ava
-
-
-  ✔ time encode() (390ms)
-    ℹ microcbor: 66.47262525558472 (ms)
-    ℹ node-cbor: 155.0249171257019 (ms)
-    ℹ JSON.stringify: 5.56374979019165 (ms)
-  ✔ time decode() (161ms)
-    ℹ microcbor: 64.23729228973389 (ms)
-    ℹ node-cbor: 91.34658432006836 (ms)
-    ℹ JSON.parse: 2.7592921257019043 (ms)
+microcbor % npm run test -- test/benchmarks.test.ts
+
+> microcbor@0.4.0 test
+> ava test/benchmarks.test.ts
+
+
+  ✔ time encode() (237ms)
+    ℹ microcbor: {
+        avg: 0.2836770999999993,
+        std: 0.1553461595001637,
+      } (ms)
+    ℹ node-cbor: {
+        avg: 0.47247252999999945,
+        std: 0.6099837601508338,
+      } (ms)
+    ℹ node-cbor (canonical): {
+        avg: 0.9973837600000031,
+        std: 1.203792591464195,
+      } (ms)
+    ℹ JSON.stringify: {
+        avg: 0.009709539999999493,
+        std: 0.0014329558361671918,
+      } (ms)
+  ✔ time decode()
+    ℹ microcbor: {
+        avg: 0.19635871000000235,
+        std: 0.35634472331099276,
+      } (ms)
+    ℹ node-cbor: {
+        avg: 0.35364794999999843,
+        std: 0.31256985912702206,
+      } (ms)
+    ℹ JSON.parse: {
+        avg: 0.018565019999997504,
+        std: 0.004339636959421219,
+      } (ms)
   ─
 
   2 tests passed

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;