microcbor 0.2.0 → 0.2.1

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
 ```
 
@@ -132,19 +112,19 @@ 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`    |                                                          |
+| 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 +134,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 +148,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/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,4 +1,5 @@
-export { encode } from "./encode.js";
+export type { CBORValue, CBORMap, CBORArray } from "./types.js";
+export { encode, Encoder } from "./encode.js";
 export { decode } from "./decode.js";
 export { encodeStream } from "./encodeStream.js";
 export { decodeStream } from "./decodeStream.js";

package/lib/index.js

@@ -1,4 +1,4 @@
-export { encode } from "./encode.js";
+export { encode, Encoder } from "./encode.js";
 export { decode } from "./decode.js";
 export { encodeStream } from "./encodeStream.js";
 export { decodeStream } from "./decodeStream.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "microcbor",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Encode JavaScript values as canonical CBOR",
 	"type": "module",
 	"main": "lib/index.js",