microcbor 0.2.0 → 0.3.0

package/README.md

@@ -4,22 +4,22 @@
 
 Encode JavaScript values as canonical CBOR.
 
-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 is a minimal JavaScript [CBOR](https://cbor.io/) implementation featuring
 
-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`.
+- 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)
-  - [Value types](#value-types)
-  - [Encoding](#encoding)
-  - [Decoding](#decoding)
-  - [Encoding length](#encoding-length)
-- [Support](#support)
+- [Value mapping](#value-mapping)
 - [Testing](#testing)
 - [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
@@ -34,15 +34,7 @@ npm i microcbor
 Or in Deno:
 
 ```typescript
-import {
-	encode,
-	decode,
-	encodeStream,
-	decodeStream,
-	encodingLength,
-	CBORValue,
-	UnsafeIntegerError,
-} from "https://cdn.skypack.dev/microcbor"
+import { encode, decode } from "https://cdn.skypack.dev/microcbor"
 ```
 
 ## Usage
@@ -65,8 +57,6 @@ console.log(decode(data))
 
 ## API
 
-### Value types
-
 ```ts
 declare type CBORValue =
 	| undefined
@@ -82,39 +72,29 @@ interface CBORArray extends Array<CBORValue> {}
 interface CBORMap {
 	[key: string]: CBORValue
 }
-```
-
-### Encoding
 
-```typescript
+// 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 } = {}
+	options?: { chunkSize?: number }
 ): Uint8Array
 
 declare function encodeStream(
 	source: AsyncIterable<CBORValue>,
 	options?: { chunkSize?: number }
 ): AsyncIterable<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.
-
-### Decoding
-
-```typescript
 declare function decode(data: Uint8Array): CBORValue
 
 declare function decodeStream(
 	source: AsyncIterable<Uint8Array>
 ): AsyncIterable<CBORValue>
-```
 
-### Encoding length
-
-You can measure the byte length that a given value will serialize to without actually allocating anything.
-
-```ts
+// You can measure the byte length that a given value will
+// serialize to without actually allocating anything.
 declare function encodingLength(value: CBORValue): number
 ```
 
@@ -126,25 +106,24 @@ declare function encodingLength(value: CBORValue): number
 ```typescript
 declare class UnsafeIntegerError extends RangeError {
 	readonly value: bigint
-	constructor(message: string, value: bigint)
 }
 ```
 
 ## 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`    |                                                          |
+| 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`     |                                                          |
 
 ## Testing
 
@@ -154,9 +133,12 @@ Tests use [AVA](https://github.com/avajs/ava) and live in the [test](./test/) di
 npm run test
 ```
 
-## Benchmarks
+## Comparison to node-cbor
 
-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 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 % npm run test -- test/benchmarks.test.js
@@ -165,12 +147,14 @@ microcbor % npm run test -- test/benchmarks.test.js
 > 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)
+  ✔ 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)
   ─
 
   2 tests passed

package/lib/decode.d.ts

@@ -1,2 +1,20 @@
 import type { CBORValue } from "./types.js";
+export declare class Decoder {
+    #private;
+    private readonly data;
+    constructor(data: Uint8Array);
+    getOffset(): number;
+    private constant;
+    private float16;
+    private float32;
+    private float64;
+    private uint8;
+    private uint16;
+    private uint32;
+    private uint64;
+    private decodeBytes;
+    private decodeString;
+    private getArgument;
+    decodeValue(): CBORValue;
+}
 export declare function decode(data: Uint8Array): CBORValue;

package/lib/decode.js

@@ -1,32 +1,49 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Decoder_offset, _Decoder_view;
 import { getFloat16 } from "fp16";
 import { UnsafeIntegerError, maxSafeInteger, minSafeInteger } from "./utils.js";
-class Decoder {
+export class Decoder {
     constructor(data) {
         this.data = data;
+        _Decoder_offset.set(this, void 0);
+        _Decoder_view.set(this, void 0);
         this.constant = (size, f) => () => {
             const value = f();
-            this.offset += size;
+            __classPrivateFieldSet(this, _Decoder_offset, __classPrivateFieldGet(this, _Decoder_offset, "f") + size, "f");
             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);
+        this.float16 = this.constant(2, () => getFloat16(__classPrivateFieldGet(this, _Decoder_view, "f"), __classPrivateFieldGet(this, _Decoder_offset, "f")));
+        this.float32 = this.constant(4, () => __classPrivateFieldGet(this, _Decoder_view, "f").getFloat32(__classPrivateFieldGet(this, _Decoder_offset, "f")));
+        this.float64 = this.constant(8, () => __classPrivateFieldGet(this, _Decoder_view, "f").getFloat64(__classPrivateFieldGet(this, _Decoder_offset, "f")));
+        this.uint8 = this.constant(1, () => __classPrivateFieldGet(this, _Decoder_view, "f").getUint8(__classPrivateFieldGet(this, _Decoder_offset, "f")));
+        this.uint16 = this.constant(2, () => __classPrivateFieldGet(this, _Decoder_view, "f").getUint16(__classPrivateFieldGet(this, _Decoder_offset, "f")));
+        this.uint32 = this.constant(4, () => __classPrivateFieldGet(this, _Decoder_view, "f").getUint32(__classPrivateFieldGet(this, _Decoder_offset, "f")));
+        this.uint64 = this.constant(8, () => __classPrivateFieldGet(this, _Decoder_view, "f").getBigUint64(__classPrivateFieldGet(this, _Decoder_offset, "f")));
+        __classPrivateFieldSet(this, _Decoder_offset, 0, "f");
+        __classPrivateFieldSet(this, _Decoder_view, new DataView(data.buffer, data.byteOffset, data.byteLength), "f");
+    }
+    getOffset() {
+        return __classPrivateFieldGet(this, _Decoder_offset, "f");
     }
     decodeBytes(length) {
         const value = new Uint8Array(length);
-        value.set(this.data.subarray(this.offset, this.offset + length), 0);
-        this.offset += length;
+        value.set(this.data.subarray(__classPrivateFieldGet(this, _Decoder_offset, "f"), __classPrivateFieldGet(this, _Decoder_offset, "f") + length), 0);
+        __classPrivateFieldSet(this, _Decoder_offset, __classPrivateFieldGet(this, _Decoder_offset, "f") + length, "f");
         return value;
     }
     decodeString(length) {
-        const value = new TextDecoder().decode(this.data.subarray(this.offset, this.offset + length));
-        this.offset += length;
+        const value = new TextDecoder().decode(this.data.subarray(__classPrivateFieldGet(this, _Decoder_offset, "f"), __classPrivateFieldGet(this, _Decoder_offset, "f") + length));
+        __classPrivateFieldSet(this, _Decoder_offset, __classPrivateFieldGet(this, _Decoder_offset, "f") + length, "f");
         return value;
     }
     getArgument(additionalInformation) {
@@ -136,6 +153,7 @@ class Decoder {
         }
     }
 }
+_Decoder_offset = new WeakMap(), _Decoder_view = new WeakMap();
 export function decode(data) {
     return new Decoder(data).decodeValue();
 }

package/lib/encode.d.ts

@@ -1,15 +1,15 @@
 import type { CBORValue } from "./types.js";
 export declare class Encoder {
-    readonly options: {
-        chunkSize?: number;
-    };
     static defaultChunkSize: number;
     closed: boolean;
     private buffer;
     private view;
     private offset;
+    private readonly encoder;
+    private readonly chunkSize;
     constructor(options?: {
         chunkSize?: number;
+        noCopy?: boolean;
     });
     private allocate;
     private float16;
@@ -19,7 +19,6 @@ export declare class Encoder {
     private uint16;
     private uint32;
     private uint64;
-    private constant;
     private encodeTypeAndArgument;
     private encodeNumber;
     private encodeInteger;

package/lib/encode.js

@@ -1,15 +1,9 @@
 import { getFloat16Precision, getFloat32Precision, setFloat16, Precision, } from "fp16";
 export class Encoder {
     constructor(options = {}) {
-        this.options = options;
-        this.float16 = this.constant(2, (value) => setFloat16(this.view, this.offset, value));
-        this.float32 = this.constant(4, (value) => this.view.setFloat32(this.offset, value));
-        this.float64 = this.constant(8, (value) => this.view.setFloat64(this.offset, value));
-        this.uint8 = this.constant(1, (value) => this.view.setUint8(this.offset, value));
-        this.uint16 = this.constant(2, (value) => this.view.setUint16(this.offset, value));
-        this.uint32 = this.constant(4, (value) => this.view.setUint32(this.offset, value));
-        this.uint64 = this.constant(8, (value) => this.view.setBigUint64(this.offset, BigInt(value)));
-        this.buffer = new ArrayBuffer(options.chunkSize || Encoder.defaultChunkSize);
+        this.encoder = new TextEncoder();
+        this.chunkSize = options.chunkSize || Encoder.defaultChunkSize;
+        this.buffer = new ArrayBuffer(this.chunkSize);
         this.view = new DataView(this.buffer);
         this.offset = 0;
         this.closed = false;
@@ -17,19 +11,46 @@ export class Encoder {
     *allocate(size) {
         if (this.buffer.byteLength < this.offset + size) {
             yield new Uint8Array(this.buffer, 0, this.offset);
-            const byteLength = Math.max(size, this.options.chunkSize || Encoder.defaultChunkSize);
+            const byteLength = Math.max(size, this.chunkSize);
             this.buffer = new ArrayBuffer(byteLength);
             this.view = new DataView(this.buffer);
             this.offset = 0;
         }
     }
-    constant(size, f) {
-        const g = function* (value) {
-            yield* this.allocate(size);
-            f(value);
-            this.offset += size;
-        };
-        return g.bind(this);
+    *float16(value) {
+        yield* this.allocate(2);
+        setFloat16(this.view, this.offset, value);
+        this.offset += 2;
+    }
+    *float32(value) {
+        yield* this.allocate(4);
+        this.view.setFloat32(this.offset, value);
+        this.offset += 4;
+    }
+    *float64(value) {
+        yield* this.allocate(8);
+        this.view.setFloat64(this.offset, value);
+        this.offset += 8;
+    }
+    *uint8(value) {
+        yield* this.allocate(1);
+        this.view.setUint8(this.offset, value);
+        this.offset += 1;
+    }
+    *uint16(value) {
+        yield* this.allocate(2);
+        this.view.setUint16(this.offset, value);
+        this.offset += 2;
+    }
+    *uint32(value) {
+        yield* this.allocate(4);
+        this.view.setUint32(this.offset, value);
+        this.offset += 4;
+    }
+    *uint64(value) {
+        yield* this.allocate(8);
+        this.view.setBigUint64(this.offset, BigInt(value));
+        this.offset += 8;
     }
     *encodeTypeAndArgument(type, argument) {
         const additionalInformation = Encoder.getAdditionalInformation(argument);
@@ -84,7 +105,7 @@ export class Encoder {
         }
     }
     *encodeString(value) {
-        const data = new TextEncoder().encode(value);
+        const data = this.encoder.encode(value);
         yield* this.encodeTypeAndArgument(3, data.byteLength);
         yield* this.allocate(data.byteLength);
         new Uint8Array(this.buffer, this.offset).set(data);

package/lib/index.d.ts

@@ -1,5 +1,6 @@
-export { encode } from "./encode.js";
-export { decode } from "./decode.js";
+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";

package/lib/index.js

@@ -1,5 +1,5 @@
-export { encode } from "./encode.js";
-export { decode } from "./decode.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";

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-export declare type CBORValue = undefined | null | boolean | number | string | Uint8Array | CBORArray | CBORMap;
+export type CBORValue = undefined | null | boolean | number | string | Uint8Array | CBORArray | CBORMap;
 export interface CBORArray extends Array<CBORValue> {
 }
 export interface CBORMap {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "microcbor",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Encode JavaScript values as canonical CBOR",
 	"type": "module",
 	"main": "lib/index.js",
@@ -27,9 +27,9 @@
 	},
 	"homepage": "https://github.com/joeltg/microcbor#readme",
 	"devDependencies": {
-		"ava": "^4.3.1",
-		"cbor": "^8.0.2",
-		"typescript": "^4.8.2"
+		"ava": "^5.3.1",
+		"cbor": "^8.1.0",
+		"typescript": "^5.1.6"
 	},
 	"dependencies": {
 		"fp16": "^0.2.0"