microcbor 0.1.0 → 0.2.1

package/README.md

@@ -2,24 +2,26 @@
 
 [![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)
 
-Encode JSON values as canonical CBOR.
+Encode JavaScript values as canonical CBOR.
 
-microcbor is a [CBOR](https://cbor.io/) implementation that only supports the subset of CBOR that corresponds to JSON. This includes `null`, `true`, `false`, numbers, strings, objects (string keys only), and arrays. You can use microcbor to serialize JSON values to CBOR, and to deserialize them back into JSON values again. microcbor doesn't support decoding items that don't correspond to JSON values: no tags, byte strings, typed arrays, `undefined`, or indefinite length collections.
+microcbor is a minimal JavaScript [CBOR](https://cbor.io/) implementation featuring
 
-microcbor also 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`.
+- a small footprint,
+- fast performance, and
+- an async iterable streaming API
 
-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.
+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.**
+
+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.
 
 ## Table of Contents
 
 - [Install](#install)
 - [Usage](#usage)
 - [API](#api)
-  - [Encoding](#encoding)
-  - [Decoding](#decoding)
-  - [Strict mode](#strict-mode)
-- [Limitations](#limitations)
+- [Value mapping](#value-mapping)
 - [Testing](#testing)
+- [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -55,105 +57,108 @@ console.log(decode(data))
 
 ## API
 
-### Encoding
-
-```typescript
-interface EncodeOptions {
-	strict?: true
-	chunkSize?: number
+```ts
+declare type CBORValue =
+	| undefined
+	| null
+	| boolean
+	| number
+	| string
+	| Uint8Array
+	| CBORArray
+	| CBORMap
+
+interface CBORArray extends Array<CBORValue> {}
+interface CBORMap {
+	[key: string]: CBORValue
 }
 
-declare function encode(value: any, options: EncodeOptions = {}): Uint8Array
+// 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
+
+declare function encodeStream(
+	source: AsyncIterable<CBORValue>,
+	options?: { chunkSize?: number }
+): AsyncIterable<Uint8Array>
+
+declare function decode(data: Uint8Array): CBORValue
+
+declare function decodeStream(
+	source: AsyncIterable<Uint8Array>
+): AsyncIterable<CBORValue>
+
+// You can measure the byte length that a given value will
+// serialize to without actually allocating anything.
+declare function encodingLength(value: CBORValue): number
 ```
 
-`encode` accepts an `options` object that can have these properties:
+## Unsafe integer handling
 
-| property     | type    | default |
-| ------------ | ------- | ------- |
-| `strictJSON` | boolean | false   |
-| `chunkSize`  | number  | 512     |
-
-### Decoding
+- 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).
+- decoding **CBOR integers** less than `Number.MIN_SAFE_INTEGER` (major type 1 with uint64 argument greater than `2^53-2`) or greater than `Number.MAX_SAFE_INTEGER` (major type 0 with uint64 argument greater than `2^53-1`) **will throw an error**. The error will be an instance of `UnsafeIntegerError` and will have the out-of-range value as a readonly `.value: bigint` property.
 
 ```typescript
-interface DecodeOptions {
-	strict?: boolean
+declare class UnsafeIntegerError extends RangeError {
+	readonly value: bigint
+	constructor(message: string, value: bigint)
 }
-
-declare function decode<T = any>(
-	data: Uint8Array,
-	decode: DecodeOptions = {}
-): T
 ```
 
-`decode` accepts an `options` object that can have these properties:
+## Value mapping
+
+| CBOR major type              | JavaScript      | notes                                                    |
+| ---------------------------- | --------------- | -------------------------------------------------------- |
+| `0` (non-negative integer)   | `number`        | decoding throws an `UnsafeIntegerError` on unsafe values |
+| `1` (negative integer)       | `number`        | decoding throws an `UnsafeIntegerError` on unsafe values |
+| `2` (byte string)            | `Uint8Array`    |                                                          |
+| `3` (UTF-8 string)           | `string`        |                                                          |
+| `4` (array)                  | `Array`         |                                                          |
+| `5` (map)                    | `Object`        | decoding throws an error on non-string keys              |
+| `6` (tagged item)            | **Unsupported** |                                                          |
+| `7` (floating-point numbers) | `number`        |                                                          |
+| `7` (booleans)               | `boolean`       |                                                          |
+| `7` (null)                   | `null`          |                                                          |
+| `7` (undefined)              | `undefined`     |                                                          |
 
-| property     | type    | default |
-| ------------ | ------- | ------- |
-| `strictJSON` | boolean | false   |
-
-### Strict mode
-
-Technically, neither `NaN` nor `+/- Infinity` are valid JSON numbers. But microcbor functions as a direct interface between JavaScript and CBOR, so by default, you can encode them...
+## Testing
 
-```javascript
-import { encode } from "microcbor"
+Tests use [AVA](https://github.com/avajs/ava) and live in the [test](./test/) directory. Tests use [node-cbor](https://github.com/hildjj/node-cbor/) to validate encoding results. More tests are always welcome!
 
-encode(NaN) // Uint8Array(3) [ 249, 126, 0 ]
-encode(Infinity) // Uint8Array(3) [ 249, 124, 0 ]
-encode(-Infinity) // Uint8Array(3) [ 249, 252, 0 ]
 ```
-
-... and decode them...
-
-```javascript
-import { decode } from "microcbor"
-
-decode(new Uint8Array([249, 126, 0])) // NaN
-decode(new Uint8Array([249, 124, 0])) // Infinity
-decode(new Uint8Array([249, 252, 0])) // -Infinity
+npm run test
 ```
 
-If you don't want this behavior - for example, if it's important to validate that all of the values you decode are JSON-serializable - you can set `options.strict` to `true`, and microcbor will throw an error if it encounters `NaN` or `+/- Infinity`.
-
-```javascript
-import { encode } from "microcbor"
+## Comparison to node-cbor
 
-encode(NaN, { strictJSON: true })
-// Uncaught Error: cannot encode NaN when strict mode is enabled
-```
-
-```javascript
-import { decode } from "microcbor"
+- 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.
 
-decode(new Uint8Array([249, 126, 0]), { strictJSON: true })
-// Uncaught Error: cannot decode NaN when strict mode is enabled
 ```
+microcbor % npm run test -- test/benchmarks.test.js
 
-For reference, `JSON.stringify` returns `"null"` when called with `NaN` or `+/- Infinity`.
-
-## Limitations
+> microcbor@0.2.0 test
+> ava
 
-JSON numbers can be arbitrarly large and have unlimited decimal precision. CBOR has explicit types for the standard fixed-size integer and float formats, and separate tags for [arbitrarily large integers](https://www.rfc-editor.org/rfc/rfc8949.html#name-bignums) and [unlimited-precision decimal values](https://www.rfc-editor.org/rfc/rfc8949.html#name-decimal-fractions-and-bigfl). Meanwhile, JavaScript can only represent numbers as 64-bit floats or BigInts. This means there are always tradeoffs in interfacing between JSON, CBOR, and JavaScript.
 
-microcbor takes an opinionated, minimal stance:
-
-- 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).
-- decoding CBOR integers less than `Number.MIN_SAFE_INTEGER` (major type 1 with uint64 argument greater than `2^53-2`) or greater than `Number.MAX_SAFE_INTEGER` (major type 0 with uint64 argument greater than `2^53-1`) **will throw an error**. The error will be an instance of `UnsafeIntegerError` and will have the out-of-range value as a readonly `.value: bigint` property.
+  ✔ 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)
+  ─
 
-```typescript
-declare class UnsafeIntegerError extends RangeError {
-	readonly value: bigint
-	constructor(message: string, value: bigint)
-}
-```
-
-## Testing
-
-Tests use [AVA 4](https://github.com/avajs/ava) (currently in alpha) and live in the [test](./test/) directory. Tests use [node-cbor](https://github.com/hildjj/node-cbor/) to validate encoding results. More tests are always welcome!
-
-```
-npm run test
+  2 tests passed
 ```
 
 ## Contributing

package/lib/decode.d.ts

@@ -1,8 +1,2 @@
-export interface DecodeOptions {
-    strictJSON?: boolean;
-}
-export declare class UnsafeIntegerError extends RangeError {
-    readonly value: bigint;
-    constructor(message: string, value: bigint);
-}
-export declare function decode<T = any>(data: Uint8Array, options?: DecodeOptions): T;
+import type { CBORValue } from "./types.js";
+export declare function decode(data: Uint8Array): CBORValue;

package/lib/decode.js

@@ -1,174 +1,141 @@
 import { getFloat16 } from "fp16";
-const maxSafeInteger = BigInt(Number.MAX_SAFE_INTEGER);
-const minSafeInteger = BigInt(Number.MIN_SAFE_INTEGER);
-function validateFloat(state, value) {
-    if (state.options.strictJSON) {
-        if (isNaN(value)) {
-            throw new Error("cannot decode NaN when strict mode is enabled");
-        }
-        else if (value === Infinity || value === -Infinity) {
-            throw new Error("cannot decode +/- Infinity when strict mode is enabled");
-        }
-    }
-}
-const constants = {
-    float16(state) {
-        const value = getFloat16(state.view, state.offset);
-        validateFloat(state, value);
-        state.offset += 2;
-        return value;
-    },
-    float32(state) {
-        const value = state.view.getFloat32(state.offset);
-        validateFloat(state, value);
-        state.offset += 4;
-        return value;
-    },
-    float64(state) {
-        const value = state.view.getFloat64(state.offset);
-        validateFloat(state, value);
-        state.offset += 8;
-        return value;
-    },
-    uint8(state) {
-        const value = state.view.getUint8(state.offset);
-        state.offset += 1;
-        return value;
-    },
-    uint16(state) {
-        const value = state.view.getUint16(state.offset);
-        state.offset += 2;
-        return value;
-    },
-    uint32(state) {
-        const value = state.view.getUint32(state.offset);
-        state.offset += 4;
-        return value;
-    },
-    uint64(state) {
-        const value = state.view.getBigUint64(state.offset);
-        state.offset += 8;
+import { UnsafeIntegerError, maxSafeInteger, minSafeInteger } from "./utils.js";
+class Decoder {
+    constructor(data) {
+        this.data = data;
+        this.constant = (size, f) => () => {
+            const value = f();
+            this.offset += size;
+            return value;
+        };
+        this.float16 = this.constant(2, () => getFloat16(this.view, this.offset));
+        this.float32 = this.constant(4, () => this.view.getFloat32(this.offset));
+        this.float64 = this.constant(8, () => this.view.getFloat64(this.offset));
+        this.uint8 = this.constant(1, () => this.view.getUint8(this.offset));
+        this.uint16 = this.constant(2, () => this.view.getUint16(this.offset));
+        this.uint32 = this.constant(4, () => this.view.getUint32(this.offset));
+        this.uint64 = this.constant(8, () => this.view.getBigUint64(this.offset));
+        this.offset = 0;
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    }
+    decodeBytes(length) {
+        const value = new Uint8Array(length);
+        value.set(this.data.subarray(this.offset, this.offset + length), 0);
+        this.offset += length;
         return value;
-    },
-};
-function decodeString(state, length) {
-    const view = new DataView(state.view.buffer, state.view.byteOffset + state.offset, length);
-    state.offset += length;
-    return new TextDecoder().decode(view);
-}
-function getArgument(state, additionalInformation) {
-    if (additionalInformation < 24) {
-        return { value: additionalInformation };
-    }
-    else if (additionalInformation === 24) {
-        return { value: constants.uint8(state) };
     }
-    else if (additionalInformation === 25) {
-        return { value: constants.uint16(state) };
-    }
-    else if (additionalInformation === 26) {
-        return { value: constants.uint32(state) };
-    }
-    else if (additionalInformation === 27) {
-        const uint64 = constants.uint64(state);
-        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");
-    }
-}
-export class UnsafeIntegerError extends RangeError {
-    constructor(message, value) {
-        super(message);
-        this.value = value;
+    decodeString(length) {
+        const value = new TextDecoder().decode(this.data.subarray(this.offset, this.offset + length));
+        this.offset += length;
+        return value;
     }
-}
-function decodeValue(state) {
-    const initialByte = constants.uint8(state);
-    const majorType = initialByte >> 5;
-    const additionalInformation = initialByte & 0x1f;
-    if (majorType === 0) {
-        const { value, uint64 } = getArgument(state, additionalInformation);
-        if (uint64 !== undefined && maxSafeInteger < uint64) {
-            throw new UnsafeIntegerError("cannot decode integers greater than 2^53-1", uint64);
+    getArgument(additionalInformation) {
+        if (additionalInformation < 24) {
+            return { value: additionalInformation };
         }
-        else {
-            return value;
+        else if (additionalInformation === 24) {
+            return { value: this.uint8() };
         }
-    }
-    else if (majorType === 1) {
-        const { value, uint64 } = getArgument(state, additionalInformation);
-        if (uint64 !== undefined && -1n - uint64 < minSafeInteger) {
-            throw new UnsafeIntegerError("cannot decode integers less than -2^53+1", -1n - uint64);
+        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 {
-            return -1 - value;
+            throw new Error("invalid argument encoding");
         }
     }
-    else if (majorType === 2) {
-        throw new Error("microcbor does not support byte strings");
-    }
-    else if (majorType === 3) {
-        const { value: length } = getArgument(state, additionalInformation);
-        return decodeString(state, length);
-    }
-    else if (majorType === 4) {
-        const { value: length } = getArgument(state, additionalInformation);
-        const value = new Array(length);
-        for (let i = 0; i < length; i++) {
-            value[i] = decodeValue(state);
+    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;
+            }
         }
-        return value;
-    }
-    else if (majorType === 5) {
-        const { value: length } = getArgument(state, additionalInformation);
-        const value = {};
-        for (let i = 0; i < length; i++) {
-            const key = decodeValue(state);
-            if (typeof key !== "string") {
-                throw new Error("microcbor only supports string keys in objects");
+        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;
             }
-            value[key] = decodeValue(state);
         }
-        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:
-                throw new Error("microcbor does not support the undefined value");
-            case 24:
-                throw new Error("microcbor does not support decoding unassigned simple values");
-            case 25:
-                return constants.float16(state);
-            case 26:
-                return constants.float32(state);
-            case 27:
-                return constants.float64(state);
-            case 31:
-                throw new Error("microcbor does not support decoding indefinite-length items");
-            default:
-                throw new Error("invalid simple 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");
         }
-    }
-    else {
-        throw new Error("invalid major type");
     }
 }
-export function decode(data, options = {}) {
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-    const state = { options, offset: 0, view };
-    return decodeValue(state);
+export function decode(data) {
+    return new Decoder(data).decodeValue();
 }

package/lib/decodeStream.d.ts

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