microcbor 0.1.0 → 0.2.0

package/README.md

@@ -2,11 +2,11 @@
 
 [![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. You can use microcbor to serialize JavaScript values to CBOR, and to deserialize them back into JavaScript values again. **microcbor doesn't support tags, bigints, typed arrays, non-string keys, or indefinite-length collections.**
 
-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`.
+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`.
 
 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.
 
@@ -15,11 +15,13 @@ This library is TypeScript-native, ESM-only, and has just one dependency ([joelt
 - [Install](#install)
 - [Usage](#usage)
 - [API](#api)
+  - [Value types](#value-types)
   - [Encoding](#encoding)
   - [Decoding](#decoding)
-  - [Strict mode](#strict-mode)
-- [Limitations](#limitations)
+  - [Encoding length](#encoding-length)
+- [Support](#support)
 - [Testing](#testing)
+- [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -32,7 +34,15 @@ npm i microcbor
 Or in Deno:
 
 ```typescript
-import { encode, decode } from "https://cdn.skypack.dev/microcbor"
+import {
+	encode,
+	decode,
+	encodeStream,
+	decodeStream,
+	encodingLength,
+	CBORValue,
+	UnsafeIntegerError,
+} from "https://cdn.skypack.dev/microcbor"
 ```
 
 ## Usage
@@ -55,91 +65,63 @@ console.log(decode(data))
 
 ## API
 
-### Encoding
-
-```typescript
-interface EncodeOptions {
-	strict?: true
-	chunkSize?: number
+### Value types
+
+```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
 ```
 
-`encode` accepts an `options` object that can have these properties:
-
-| property     | type    | default |
-| ------------ | ------- | ------- |
-| `strictJSON` | boolean | false   |
-| `chunkSize`  | number  | 512     |
-
-### Decoding
+### Encoding
 
 ```typescript
-interface DecodeOptions {
-	strict?: boolean
-}
-
-declare function decode<T = any>(
-	data: Uint8Array,
-	decode: DecodeOptions = {}
-): T
+declare function encode(
+	value: CBORValue,
+	options: { chunkSize?: number } = {}
+): Uint8Array
+
+declare function encodeStream(
+	source: AsyncIterable<CBORValue>,
+	options?: { chunkSize?: number }
+): AsyncIterable<Uint8Array>
 ```
 
-`decode` accepts an `options` object that can have these properties:
-
-| 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...
+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.
 
-```javascript
-import { encode } from "microcbor"
-
-encode(NaN) // Uint8Array(3) [ 249, 126, 0 ]
-encode(Infinity) // Uint8Array(3) [ 249, 124, 0 ]
-encode(-Infinity) // Uint8Array(3) [ 249, 252, 0 ]
-```
-
-... and decode them...
+### Decoding
 
-```javascript
-import { decode } from "microcbor"
+```typescript
+declare function decode(data: Uint8Array): CBORValue
 
-decode(new Uint8Array([249, 126, 0])) // NaN
-decode(new Uint8Array([249, 124, 0])) // Infinity
-decode(new Uint8Array([249, 252, 0])) // -Infinity
+declare function decodeStream(
+	source: AsyncIterable<Uint8Array>
+): AsyncIterable<CBORValue>
 ```
 
-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`.
+### Encoding length
 
-```javascript
-import { encode } from "microcbor"
+You can measure the byte length that a given value will serialize to without actually allocating anything.
 
-encode(NaN, { strictJSON: true })
-// Uncaught Error: cannot encode NaN when strict mode is enabled
+```ts
+declare function encodingLength(value: CBORValue): number
 ```
 
-```javascript
-import { decode } from "microcbor"
-
-decode(new Uint8Array([249, 126, 0]), { strictJSON: true })
-// Uncaught Error: cannot decode NaN when strict mode is enabled
-```
-
-For reference, `JSON.stringify` returns `"null"` when called with `NaN` or `+/- Infinity`.
-
-## Limitations
-
-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:
+## 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).
-- 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.
+- 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
 declare class UnsafeIntegerError extends RangeError {
@@ -148,14 +130,52 @@ declare class UnsafeIntegerError extends RangeError {
 }
 ```
 
+## 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 ❌ | decoding throws an error on non-string keys              |
+| `7` (floating-point numbers) | `number`       |                                                          |
+| `7` (booleans)               | `boolean`      |                                                          |
+| `7` (null)                   | `null`         |                                                          |
+| `7` (undefined)              | `undefined`    |                                                          |
+
 ## 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!
+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!
 
 ```
 npm run test
 ```
 
+## Benchmarks
+
+Basic testing in [src/benchmarks.test.js](src/benchmarks.test.js) indicate that microcbor is about **2x as fast** as node-cbor at encoding and about **1.5x as fast** as node-cbor at decoding.
+
+```
+microcbor % npm run test -- test/benchmarks.test.js
+
+> microcbor@0.2.0 test
+> ava
+
+
+  ✔ time encode() (382ms)
+    ℹ microcbor: 63.44141721725464 (ms)
+    ℹ node-cbor: 152.31466674804688 (ms)
+  ✔ time decode() (164ms)
+    ℹ microcbor: 72.13012504577637 (ms)
+    ℹ node-cbor: 87.16287469863892 (ms)
+  ─
+
+  2 tests passed
+```
+
 ## Contributing
 
 I don't expect to add any additional features to this library. But if you have suggestions for better interfaces, find a bug, or would like to add more tests, please open an issue to discuss it!

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>;