microcbor 0.3.0 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@ microcbor is a minimal JavaScript [CBOR](https://cbor.io/) implementation featur
 
 - a small footprint,
 - fast performance, and
-- an async iterable streaming API
+- `Iterable` and `AsyncIterable` streaming interfaces
 
 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.**
 
@@ -58,40 +58,27 @@ console.log(decode(data))
 ## API
 
 ```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
+declare function encode(value: CBORValue, options?: { chunkSize?: number }): Uint8Array
 
 declare function encodeStream(
-	source: AsyncIterable<CBORValue>,
-	options?: { chunkSize?: number }
+  source: AsyncIterable<CBORValue>,
+  options?: { chunkSize?: number },
 ): AsyncIterable<Uint8Array>
 
 declare function decode(data: Uint8Array): CBORValue
 
-declare function decodeStream(
-	source: AsyncIterable<Uint8Array>
-): AsyncIterable<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.
@@ -105,7 +92,7 @@ declare function encodingLength(value: CBORValue): number
 
 ```typescript
 declare class UnsafeIntegerError extends RangeError {
-	readonly value: bigint
+  readonly value: bigint
 }
 ```
 
@@ -138,26 +125,40 @@ 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 **5x faster** than node-cbor at encoding, and comparable 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)
-  ─
-
-  2 tests passed
+microcbor % npm run test -- test/benchmarks.test.ts
+
+> microcbor@0.3.0 test
+> ava test/benchmarks.test.ts
+
+  ✔ time encode() (196ms)
+    ℹ microcbor: {
+        avg: 0.20750288999999897,
+        std: 0.1599497238014431,
+      } (ms)
+    ℹ node-cbor: {
+        avg: 1.012210439999998,
+        std: 1.1648550529513988,
+      } (ms)
+    ℹ JSON.stringify: {
+        avg: 0.011432450000000358,
+        std: 0.0014736483187953618,
+      } (ms)
+  ✔ time decode()
+    ℹ microcbor: {
+        avg: 0.3199704100000008,
+        std: 0.6562532760030573,
+      } (ms)
+    ℹ node-cbor: {
+        avg: 0.35316917000000214,
+        std: 0.32859580328312393,
+      } (ms)
+    ℹ JSON.parse: {
+        avg: 0.016885789999999474,
+        std: 0.0041605677456241505,
+      } (ms)
 ```
 
 ## Contributing

package/lib/encode.d.ts

@@ -1,16 +1,18 @@
 import type { CBORValue } from "./types.js";
 export declare class Encoder {
+    #private;
     static defaultChunkSize: number;
-    closed: boolean;
-    private buffer;
-    private view;
-    private offset;
+    readonly noCopy: boolean;
+    readonly chunkSize: number;
     private readonly encoder;
-    private readonly chunkSize;
+    private readonly buffer;
+    private readonly view;
+    private offset;
     constructor(options?: {
-        chunkSize?: number;
         noCopy?: boolean;
+        chunkSize?: number;
     });
+    get closed(): boolean;
     private allocate;
     private float16;
     private float32;

package/lib/encode.js

@@ -1,20 +1,38 @@
-import { getFloat16Precision, getFloat32Precision, setFloat16, Precision, } from "fp16";
+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 _Encoder_instances, _Encoder_closed, _Encoder_flush;
+import { getFloat16Precision, getFloat32Precision, setFloat16, Precision } from "fp16";
+import { getByteLength } from "./encodingLength.js";
+import { assert } from "./utils.js";
 export class Encoder {
     constructor(options = {}) {
+        _Encoder_instances.add(this);
+        _Encoder_closed.set(this, void 0);
         this.encoder = new TextEncoder();
-        this.chunkSize = options.chunkSize || Encoder.defaultChunkSize;
+        this.noCopy = options.noCopy ?? 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.offset = 0;
-        this.closed = false;
+        __classPrivateFieldSet(this, _Encoder_closed, false, "f");
+    }
+    get closed() {
+        return __classPrivateFieldGet(this, _Encoder_closed, "f");
     }
     *allocate(size) {
+        assert(size <= 8, "expected size <= 8");
         if (this.buffer.byteLength < this.offset + size) {
-            yield new Uint8Array(this.buffer, 0, this.offset);
-            const byteLength = Math.max(size, this.chunkSize);
-            this.buffer = new ArrayBuffer(byteLength);
-            this.view = new DataView(this.buffer);
-            this.offset = 0;
+            yield __classPrivateFieldGet(this, _Encoder_instances, "m", _Encoder_flush).call(this);
         }
     }
     *float16(value) {
@@ -73,9 +91,7 @@ export class Encoder {
         else if (Object.is(value, -0)) {
             yield* this.encodeFloat(value);
         }
-        else if (Math.floor(value) === value &&
-            Number.MIN_SAFE_INTEGER <= value &&
-            value <= Number.MAX_SAFE_INTEGER) {
+        else if (Math.floor(value) === value && Number.MIN_SAFE_INTEGER <= value && value <= Number.MAX_SAFE_INTEGER) {
             yield* this.encodeInteger(value);
         }
         else {
@@ -105,20 +121,38 @@ export class Encoder {
         }
     }
     *encodeString(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);
-        this.offset += data.byteLength;
+        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");
+        }
     }
     *encodeBytes(value) {
         yield* this.encodeTypeAndArgument(2, value.byteLength);
-        yield* this.allocate(value.byteLength);
-        new Uint8Array(this.buffer, this.offset, value.byteLength).set(value);
-        this.offset += value.byteLength;
+        const target = new Uint8Array(this.buffer, 0, this.buffer.byteLength);
+        let start = 0;
+        while (start < value.byteLength) {
+            if (this.offset >= this.buffer.byteLength) {
+                yield __classPrivateFieldGet(this, _Encoder_instances, "m", _Encoder_flush).call(this);
+            }
+            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);
+            start += chunkLength;
+            this.offset += chunkLength;
+        }
     }
     *encodeValue(value) {
-        if (this.closed) {
+        if (__classPrivateFieldGet(this, _Encoder_closed, "f")) {
             return;
         }
         if (value === false) {
@@ -158,10 +192,10 @@ export class Encoder {
         }
     }
     *flush() {
-        if (this.closed) {
+        if (__classPrivateFieldGet(this, _Encoder_closed, "f")) {
             return;
         }
-        this.closed = true;
+        __classPrivateFieldSet(this, _Encoder_closed, true, "f");
         if (this.offset > 0) {
             yield new Uint8Array(this.buffer, 0, this.offset);
         }
@@ -205,6 +239,19 @@ export class Encoder {
         }
     }
 }
+_Encoder_closed = new WeakMap(), _Encoder_instances = new WeakSet(), _Encoder_flush = function _Encoder_flush() {
+    if (this.noCopy) {
+        const chunk = new Uint8Array(this.buffer, 0, this.offset);
+        this.offset = 0;
+        return chunk;
+    }
+    else {
+        const chunk = new Uint8Array(this.offset);
+        chunk.set(new Uint8Array(this.buffer, 0, this.offset));
+        this.offset = 0;
+        return chunk;
+    }
+};
 Encoder.defaultChunkSize = 512;
 export function encode(value, options = {}) {
     const encoder = new Encoder(options);

package/lib/encodeStream.d.ts

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

package/lib/encodingLength.d.ts

@@ -1,2 +1,3 @@
 import type { CBORValue } from "./types.js";
 export declare function encodingLength(value: CBORValue): number;
+export declare function getByteLength(string: string): number;

package/lib/encodingLength.js

@@ -70,9 +70,7 @@ function numberEncodingLength(value) {
     else if (Object.is(value, -0)) {
         return floatEncodingLength(value);
     }
-    else if (Math.floor(value) === value &&
-        Number.MIN_SAFE_INTEGER <= value &&
-        value <= Number.MAX_SAFE_INTEGER) {
+    else if (Math.floor(value) === value && Number.MIN_SAFE_INTEGER <= value && value <= Number.MAX_SAFE_INTEGER) {
         return integerEncodingLength(value);
     }
     else {
@@ -99,7 +97,7 @@ function floatEncodingLength(value) {
     }
 }
 function stringEncodingLength(value) {
-    const length = byteLength(value);
+    const length = getByteLength(value);
     return argumentEncodingLength(length) + length;
 }
 function bytesEncodingLength(value) {
@@ -107,7 +105,7 @@ function bytesEncodingLength(value) {
     return argumentEncodingLength(length) + length;
 }
 // https://github.com/feross/buffer/blob/57caad4450d241207066ca3832fb8e9095ad402f/index.js#L434
-function byteLength(string) {
+export function getByteLength(string) {
     let codePoint;
     const length = string.length;
     let leadSurrogate = null;
@@ -140,8 +138,7 @@ function byteLength(string) {
                 continue;
             }
             // valid surrogate pair
-            codePoint =
-                (((leadSurrogate - 0xd800) << 10) | (codePoint - 0xdc00)) + 0x10000;
+            codePoint = (((leadSurrogate - 0xd800) << 10) | (codePoint - 0xdc00)) + 0x10000;
         }
         else if (leadSurrogate) {
             // valid bmp char, but last char was a lead

package/lib/utils.d.ts

@@ -4,3 +4,9 @@ export declare class UnsafeIntegerError extends RangeError {
     readonly value: bigint;
     constructor(message: string, value: bigint);
 }
+export declare class AssertError extends Error {
+    readonly message: string;
+    readonly props?: any | undefined;
+    constructor(message: string, props?: any | undefined);
+}
+export declare function assert(condition: unknown, message?: string, props?: any): asserts condition;

package/lib/utils.js

@@ -6,3 +6,15 @@ export class UnsafeIntegerError extends RangeError {
         this.value = value;
     }
 }
+export class AssertError extends Error {
+    constructor(message, props) {
+        super(message);
+        this.message = message;
+        this.props = props;
+    }
+}
+export function assert(condition, message = "assertion failed", props) {
+    if (!condition) {
+        throw new AssertError(message, props);
+    }
+}

package/package.json

@@ -1,15 +1,20 @@
 {
 	"name": "microcbor",
-	"version": "0.3.0",
-	"description": "Encode JavaScript values as canonical CBOR",
+	"version": "0.4.0",
 	"type": "module",
-	"main": "lib/index.js",
-	"types": "lib/index.d.ts",
 	"files": [
 		"lib"
 	],
+	"description": "Encode JavaScript values as canonical CBOR",
+	"main": "lib/index.js",
+	"types": "./lib/index.d.ts",
+	"exports": {
+		".": "./lib/index.js"
+	},
 	"scripts": {
-		"build": "tsc",
+		"dev": "tsc --build tsconfig.json test/tsconfig.json --watch",
+		"build": "tsc --build tsconfig.json test/tsconfig.json",
+		"clean": "tsc --build tsconfig.json test/tsconfig.json --clean",
 		"test": "ava"
 	},
 	"repository": {
@@ -27,11 +32,13 @@
 	},
 	"homepage": "https://github.com/joeltg/microcbor#readme",
 	"devDependencies": {
-		"ava": "^5.3.1",
+		"@ava/typescript": "^5.0.0",
+		"@types/node": "^22.13.9",
+		"ava": "^6.2.0",
 		"cbor": "^8.1.0",
-		"typescript": "^5.1.6"
+		"typescript": "^5.6.0"
 	},
 	"dependencies": {
-		"fp16": "^0.2.0"
+		"fp16": "^1.0.0"
 	}
 }