microcbor 1.0.0 → 1.2.0

package/README.md

@@ -68,7 +68,15 @@ console.log(decode(data))
 ### CBOR Values
 
 ```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 {
@@ -82,6 +90,12 @@ interface CBORMap {
 
 ```ts
 export interface EncodeOptions {
+  /**
+   * Allow `undefined`
+   * @default true
+   */
+  allowUndefined?: boolean
+
   /**
    * Re-use the same underlying ArrayBuffer for all yielded chunks.
    * If this is enabled, the consumer must copy each chunk content
@@ -113,7 +127,10 @@ export interface EncodeOptions {
  * Calculate the byte length that a value will encode into
  * without actually allocating anything.
  */
-declare function encodingLength(value: CBORValue): number
+declare function encodingLength(
+  value: CBORValue,
+  options?: EncodeOptions,
+): number
 ```
 
 #### `encode`
@@ -123,7 +140,7 @@ declare function encodingLength(value: CBORValue): number
  * Encode a single CBOR value.
  * options.chunkRecycling has no effect here.
  */
-export function encode(value: CBORValue, options: EncodeOptions = {}): Uint8Array
+export function encode(value: CBORValue, options?: EncodeOptions): Uint8Array
 ```
 
 #### `encodeIterable`
@@ -132,7 +149,7 @@ export function encode(value: CBORValue, options: EncodeOptions = {}): Uint8Arra
 /** Encode an iterable of CBOR values into an iterable of Uint8Array chunks */
 export function* encodeIterable(
   source: Iterable<CBORValue>,
-  options: EncodeOptions = {},
+  options?: EncodeOptions,
 ): IterableIterator<Uint8Array>
 
 ```
@@ -143,7 +160,7 @@ export function* encodeIterable(
 /** Encode an async iterable of CBOR values into an async iterable of Uint8Array chunks */
 export async function* encodeAsyncIterable(
   source: AsyncIterable<CBORValue>,
-  options: EncodeOptions = {},
+  options?: EncodeOptions,
 ): AsyncIterableIterator<Uint8Array>
 
 ```
@@ -156,39 +173,67 @@ export async function* encodeAsyncIterable(
  * options.chunkRecycling has no effect here.
  */
 export class CBOREncoderStream extends TransformStream<CBORValue, Uint8Array> {
-  public constructor(options: EncodeOptions = {})
+  public constructor(options?: EncodeOptions)
 }
 ```
 
 ### Decoding
 
+#### `DecodeOptions`
+
+```ts
+export interface DecodeOptions {
+  /**
+   * Allow `undefined`
+   * @default true
+   */
+  allowUndefined?: boolean
+
+  /**
+   * Minimum bitsize for floating-point numbers: 16, 32, or 64
+   * @default 16
+   */
+  minFloatSize?: (typeof FloatSize)[keyof typeof FloatSize]
+}
+```
+
 #### `decode`
 
 ```ts
 /** Decode a single CBOR value. */
-export function decode(data: Uint8Array): CBORValue
+export function decode<T extends CBORValue = CBORValue>(
+  data: Uint8Array,
+  options?: DecodeOptions,
+): T
 ```
 
 #### `decodeIterable`
 
 ```ts
 /** Decode an iterable of Uint8Array chunks into an iterable of CBOR values */
-export function* decodeIterable(source: Iterable<Uint8Array>): IterableIterator<CBORValue>
-
+export function* decodeIterable<T extends CBORValue = CBORValue>(
+  source: Iterable<Uint8Array>,
+  options?: DecodeOptions,
+): IterableIterator<T>
 ```
 
 #### `decodeAsyncIterable`
 
 ```ts
 /** Decode an async iterable of Uint8Array chunks into an async iterable of CBOR values */
-export async function* decodeAsyncIterable(source: AsyncIterable<Uint8Array>): AsyncIterable<CBORValue>
+export async function* decodeAsyncIterable<T extends CBORValue = CBORValue>(
+  source: AsyncIterable<Uint8Array>,
+  options?: DecodeOptions,
+): AsyncIterable<CBORValue>
 ```
 
 #### `CBORDecoderStream`
 
 ```ts
 /** Decode a Web Streams API ReadableStream. */
-export class CBORDecoderStream extends TransformStream<Uint8Array, CBORValue> {
+export class CBORDecoderStream<
+  T extends CBORValue = CBORValue,
+> extends TransformStream<Uint8Array, T> {
   public constructor()
 }
 ```

package/lib/CBORDecoderStream.d.ts

@@ -1,5 +1,6 @@
+import { DecodeOptions } from "./options.js";
 import { CBORValue } from "./types.js";
 /** Decode a Web Streams API ReadableStream */
-export declare class CBORDecoderStream extends TransformStream<Uint8Array, CBORValue> {
-    constructor();
+export declare class CBORDecoderStream<T extends CBORValue = CBORValue> extends TransformStream<Uint8Array, T> {
+    constructor(options?: DecodeOptions);
 }

package/lib/CBORDecoderStream.js

@@ -1,7 +1,7 @@
 import { Decoder } from "./decodeAsyncIterable.js";
 /** Decode a Web Streams API ReadableStream */
 export class CBORDecoderStream extends TransformStream {
-    constructor() {
+    constructor(options = {}) {
         let readableController;
         const readable = new ReadableStream({
             start(controller) {
@@ -13,6 +13,7 @@ export class CBORDecoderStream extends TransformStream {
         const chunks = new WeakMap();
         async function pipe(controller) {
             const decoder = new Decoder(readable.values(), {
+                ...options,
                 onFree: (chunk) => chunks.get(chunk)?.resolve(),
             });
             for await (const value of decoder) {

package/lib/CBOREncoderStream.d.ts

@@ -1,5 +1,5 @@
 import { CBORValue } from "./types.js";
-import { EncodeOptions } from "./Encoder.js";
+import { EncodeOptions } from "./options.js";
 /**
  * Encode a Web Streams API ReadableStream.
  * options.chunkRecycling has no effect here.

package/lib/Decoder.d.ts

@@ -1,8 +1,11 @@
 import type { CBORValue } from "./types.js";
+import type { DecodeOptions, FloatSize } from "./options.js";
 export declare class Decoder {
     #private;
     private readonly data;
-    constructor(data: Uint8Array);
+    readonly allowUndefined: boolean;
+    readonly minFloatSize: (typeof FloatSize)[keyof typeof FloatSize];
+    constructor(data: Uint8Array, options?: DecodeOptions);
     getOffset(): number;
     private constant;
     private float16;
@@ -18,4 +21,4 @@ export declare class Decoder {
     decodeValue(): CBORValue;
 }
 /** Decode a single CBOR value */
-export declare function decode(data: Uint8Array): CBORValue;
+export declare function decode<T extends CBORValue = CBORValue>(data: Uint8Array, options?: DecodeOptions): T;

package/lib/Decoder.js

@@ -13,7 +13,7 @@ var _Decoder_offset, _Decoder_view;
 import { getFloat16 } from "fp16";
 import { UnsafeIntegerError, maxSafeInteger, minSafeInteger } from "./utils.js";
 export class Decoder {
-    constructor(data) {
+    constructor(data, options = {}) {
         this.data = data;
         _Decoder_offset.set(this, void 0);
         _Decoder_view.set(this, void 0);
@@ -31,6 +31,8 @@ export class Decoder {
         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");
+        this.allowUndefined = options.allowUndefined ?? true;
+        this.minFloatSize = options.minFloatSize ?? 16;
     }
     getOffset() {
         return __classPrivateFieldGet(this, _Decoder_offset, "f");
@@ -133,13 +135,28 @@ export class Decoder {
                 case 22:
                     return null;
                 case 23:
-                    return undefined;
+                    if (this.allowUndefined) {
+                        return undefined;
+                    }
+                    else {
+                        throw new TypeError("`undefined` not allowed");
+                    }
                 case 24:
                     throw new Error("microcbor does not support decoding unassigned simple values");
                 case 25:
-                    return this.float16();
+                    if (this.minFloatSize <= 16) {
+                        return this.float16();
+                    }
+                    else {
+                        throw new Error("cannot decode float16 type - below provided minFloatSize");
+                    }
                 case 26:
-                    return this.float32();
+                    if (this.minFloatSize <= 32) {
+                        return this.float32();
+                    }
+                    else {
+                        throw new Error("cannot decode float32 type - below provided minFloatSize");
+                    }
                 case 27:
                     return this.float64();
                 case 31:
@@ -155,6 +172,6 @@ export class Decoder {
 }
 _Decoder_offset = new WeakMap(), _Decoder_view = new WeakMap();
 /** Decode a single CBOR value */
-export function decode(data) {
-    return new Decoder(data).decodeValue();
+export function decode(data, options = {}) {
+    return new Decoder(data, options).decodeValue();
 }

package/lib/Encoder.d.ts

@@ -1,33 +1,9 @@
 import type { CBORValue } from "./types.js";
-export declare const FloatSize: {
-    f16: number;
-    f32: number;
-    f64: number;
-};
-export interface EncodeOptions {
-    /**
-     * Re-use the same underlying ArrayBuffer for all yielded chunks.
-     * If this is enabled, the consumer must copy each chunk content
-     * themselves to a new buffer if they wish to keep it.
-     * This mode is useful for efficiently hashing objects without
-     * ever allocating memory for the entire encoded result.
-     * @default false
-     */
-    chunkRecycling?: boolean;
-    /**
-     * Maximum chunk size
-     * @default 4096
-     */
-    chunkSize?: number;
-    /**
-     * Minimum bitsize for floating-point numbers: 16, 32, or 64
-     * @default 16
-     */
-    minFloatSize?: (typeof FloatSize)[keyof typeof FloatSize];
-}
+import { EncodeOptions, FloatSize } from "./options.js";
 export declare class Encoder {
     #private;
     static defaultChunkSize: number;
+    readonly allowUndefined: boolean;
     readonly chunkRecycling: boolean;
     readonly chunkSize: number;
     readonly minFloatSize: (typeof FloatSize)[keyof typeof FloatSize];

package/lib/Encoder.js

@@ -11,17 +11,14 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Encoder_instances, _Encoder_closed, _Encoder_flush;
 import { Precision, getFloat16Precision, getFloat32Precision, setFloat16 } from "fp16";
+import { FloatSize } from "./options.js";
 import { assert } from "./utils.js";
-export const FloatSize = {
-    f16: 16,
-    f32: 32,
-    f64: 64,
-};
 export class Encoder {
     constructor(options = {}) {
         _Encoder_instances.add(this);
         _Encoder_closed.set(this, void 0);
         this.encoder = new TextEncoder();
+        this.allowUndefined = options.allowUndefined ?? true;
         this.minFloatSize = options.minFloatSize ?? 16;
         this.chunkRecycling = options.chunkRecycling ?? false;
         this.chunkSize = options.chunkSize ?? Encoder.defaultChunkSize;
@@ -175,7 +172,12 @@ export class Encoder {
             yield* this.uint8(0xf6);
         }
         else if (value === undefined) {
-            yield* this.uint8(0xf7);
+            if (this.allowUndefined) {
+                yield* this.uint8(0xf7);
+            }
+            else {
+                throw new TypeError("`undefined` is not allowed");
+            }
         }
         else if (typeof value === "number") {
             yield* this.encodeNumber(value);

package/lib/decodeAsyncIterable.d.ts

@@ -1,5 +1,11 @@
 import type { CBORValue } from "./types.js";
-export declare class Decoder implements AsyncIterableIterator<CBORValue> {
+import { DecodeOptions, FloatSize } from "./options.js";
+export interface AsyncDecodeOptions extends DecodeOptions {
+    onFree?: (chunk: Uint8Array) => void;
+}
+export declare class Decoder<T extends CBORValue = CBORValue> implements AsyncIterableIterator<T> {
+    readonly allowUndefined: boolean;
+    readonly minFloatSize: (typeof FloatSize)[keyof typeof FloatSize];
     private offset;
     private byteLength;
     private readonly chunks;
@@ -7,9 +13,7 @@ export declare class Decoder implements AsyncIterableIterator<CBORValue> {
     private readonly constantView;
     private readonly iter;
     private readonly onFree?;
-    constructor(source: AsyncIterable<Uint8Array>, options?: {
-        onFree?: (chunk: Uint8Array) => void;
-    });
+    constructor(source: AsyncIterable<Uint8Array>, options?: AsyncDecodeOptions);
     [Symbol.asyncIterator]: () => this;
     private allocate;
     private fill;
@@ -29,9 +33,9 @@ export declare class Decoder implements AsyncIterableIterator<CBORValue> {
         value: undefined;
     } | {
         done: false;
-        value: CBORValue;
+        value: T;
     }>;
     private decodeValue;
 }
 /** Decode an async iterable of Uint8Array chunks into an async iterable of CBOR values */
-export declare function decodeAsyncIterable(source: AsyncIterable<Uint8Array>): AsyncIterableIterator<CBORValue>;
+export declare function decodeAsyncIterable(source: AsyncIterable<Uint8Array>, options?: AsyncDecodeOptions): AsyncIterableIterator<CBORValue>;

package/lib/decodeAsyncIterable.js

@@ -24,8 +24,10 @@ export class Decoder {
         this.uint16 = this.constant(2, (view) => view.getUint16(0));
         this.uint32 = this.constant(4, (view) => view.getUint32(0));
         this.uint64 = this.constant(8, (view) => view.getBigUint64(0));
-        this.iter = source[Symbol.asyncIterator]();
         this.onFree = options.onFree;
+        this.allowUndefined = options.allowUndefined ?? true;
+        this.minFloatSize = options.minFloatSize ?? 16;
+        this.iter = source[Symbol.asyncIterator]();
     }
     async allocate(size) {
         while (this.byteLength < size) {
@@ -121,7 +123,7 @@ export class Decoder {
             }
         }
         const value = await this.decodeValue();
-        return { done: false, value };
+        return { done: false, value: value };
     }
     async decodeValue() {
         const initialByte = await this.uint8();
@@ -185,13 +187,28 @@ export class Decoder {
                 case 22:
                     return null;
                 case 23:
-                    return undefined;
+                    if (this.allowUndefined) {
+                        return undefined;
+                    }
+                    else {
+                        throw new TypeError("`undefined` not allowed");
+                    }
                 case 24:
                     throw new Error("microcbor does not support decoding unassigned simple values");
                 case 25:
-                    return await this.float16();
+                    if (this.minFloatSize <= 16) {
+                        return this.float16();
+                    }
+                    else {
+                        throw new Error("cannot decode float16 type - below provided minFloatSize");
+                    }
                 case 26:
-                    return await this.float32();
+                    if (this.minFloatSize <= 32) {
+                        return this.float32();
+                    }
+                    else {
+                        throw new Error("cannot decode float32 type - below provided minFloatSize");
+                    }
                 case 27:
                     return await this.float64();
                 case 31:
@@ -207,6 +224,6 @@ export class Decoder {
 }
 _a = Symbol.asyncIterator;
 /** Decode an async iterable of Uint8Array chunks into an async iterable of CBOR values */
-export async function* decodeAsyncIterable(source) {
-    yield* new Decoder(source);
+export async function* decodeAsyncIterable(source, options = {}) {
+    yield* new Decoder(source, options);
 }

package/lib/decodeIterable.d.ts

@@ -1,3 +1,37 @@
 import type { CBORValue } from "./types.js";
+import type { DecodeOptions, FloatSize } from "./options.js";
+export declare class Decoder<T extends CBORValue = CBORValue> implements IterableIterator<T> {
+    readonly allowUndefined: boolean;
+    readonly minFloatSize: (typeof FloatSize)[keyof typeof FloatSize];
+    private offset;
+    private byteLength;
+    private readonly chunks;
+    private readonly constantBuffer;
+    private readonly constantView;
+    private readonly iter;
+    constructor(source: Iterable<Uint8Array>, options?: DecodeOptions);
+    [Symbol.iterator]: () => this;
+    private allocate;
+    private fill;
+    private constant;
+    private float16;
+    private float32;
+    private float64;
+    private uint8;
+    private uint16;
+    private uint32;
+    private uint64;
+    private decodeBytes;
+    private decodeString;
+    private getArgument;
+    next(): {
+        done: true;
+        value: undefined;
+    } | {
+        done: false;
+        value: T;
+    };
+    private decodeValue;
+}
 /** Decode an iterable of Uint8Array chunks into an iterable of CBOR values */
 export declare function decodeIterable(source: Iterable<Uint8Array>): IterableIterator<CBORValue>;

package/lib/decodeIterable.js

@@ -1,8 +1,8 @@
 var _a;
 import { getFloat16 } from "fp16";
 import { UnsafeIntegerError, maxSafeInteger, minSafeInteger } from "./utils.js";
-class Decoder {
-    constructor(source) {
+export class Decoder {
+    constructor(source, options = {}) {
         this.offset = 0;
         this.byteLength = 0;
         this.chunks = [];
@@ -24,6 +24,8 @@ class Decoder {
         this.uint16 = this.constant(2, (view) => view.getUint16(0));
         this.uint32 = this.constant(4, (view) => view.getUint32(0));
         this.uint64 = this.constant(8, (view) => view.getBigUint64(0));
+        this.allowUndefined = options.allowUndefined ?? true;
+        this.minFloatSize = options.minFloatSize ?? 16;
         this.iter = source[Symbol.iterator]();
     }
     allocate(size) {
@@ -115,7 +117,7 @@ class Decoder {
             }
         }
         const value = this.decodeValue();
-        return { done: false, value };
+        return { done: false, value: value };
     }
     decodeValue() {
         const initialByte = this.uint8();
@@ -179,13 +181,28 @@ class Decoder {
                 case 22:
                     return null;
                 case 23:
-                    return undefined;
+                    if (this.allowUndefined) {
+                        return undefined;
+                    }
+                    else {
+                        throw new TypeError("`undefined` not allowed");
+                    }
                 case 24:
                     throw new Error("microcbor does not support decoding unassigned simple values");
                 case 25:
-                    return this.float16();
+                    if (this.minFloatSize <= 16) {
+                        return this.float16();
+                    }
+                    else {
+                        throw new Error("cannot decode float16 type - below provided minFloatSize");
+                    }
                 case 26:
-                    return this.float32();
+                    if (this.minFloatSize <= 32) {
+                        return this.float32();
+                    }
+                    else {
+                        throw new Error("cannot decode float32 type - below provided minFloatSize");
+                    }
                 case 27:
                     return this.float64();
                 case 31:

package/lib/encodeAsyncIterable.d.ts

@@ -1,4 +1,4 @@
 import type { CBORValue } from "./types.js";
-import { EncodeOptions } from "./Encoder.js";
+import { EncodeOptions } from "./options.js";
 /** Encode an async iterable of CBOR values into an async iterable of Uint8Array chunks */
 export declare function encodeAsyncIterable(source: AsyncIterable<CBORValue>, options?: EncodeOptions): AsyncIterableIterator<Uint8Array>;

package/lib/encodeIterable.d.ts

@@ -1,4 +1,4 @@
 import type { CBORValue } from "./types.js";
-import { EncodeOptions } from "./Encoder.js";
+import { EncodeOptions } from "./options.js";
 /** Encode an iterable of CBOR values into an iterable of Uint8Array chunks */
 export declare function encodeIterable(source: Iterable<CBORValue>, options?: EncodeOptions): IterableIterator<Uint8Array>;

package/lib/encodingLength.d.ts

@@ -1,6 +1,7 @@
 import { CBORValue } from "./types.js";
+import { EncodeOptions } from "./options.js";
 /**
  * Calculate the byte length that a value will encode into
  * without actually allocating anything.
  */
-export declare function encodingLength(value: CBORValue): number;
+export declare function encodingLength(value: CBORValue, options?: EncodeOptions): number;

package/lib/encodingLength.js

@@ -4,7 +4,7 @@ import { getByteLength } from "./utils.js";
  * Calculate the byte length that a value will encode into
  * without actually allocating anything.
  */
-export function encodingLength(value) {
+export function encodingLength(value, options = {}) {
     if (value === false) {
         return 1;
     }
@@ -15,10 +15,15 @@ export function encodingLength(value) {
         return 1;
     }
     else if (value === undefined) {
-        return 1;
+        if (options.allowUndefined ?? true) {
+            return 1;
+        }
+        else {
+            throw new Error("`undefined` is not allowed");
+        }
     }
     else if (typeof value === "number") {
-        return numberEncodingLength(value);
+        return numberEncodingLength(value, options);
     }
     else if (typeof value === "string") {
         return stringEncodingLength(value);
@@ -29,7 +34,7 @@ export function encodingLength(value) {
     else if (Array.isArray(value)) {
         let length = argumentEncodingLength(value.length);
         for (const element of value) {
-            length += encodingLength(element);
+            length += encodingLength(element, options);
         }
         return length;
     }
@@ -39,7 +44,7 @@ export function encodingLength(value) {
         for (const key of keys) {
             if (typeof key === "string") {
                 length += stringEncodingLength(key);
-                length += encodingLength(value[key]);
+                length += encodingLength(value[key], options);
             }
             else {
                 throw new Error("object keys must be strings");
@@ -68,18 +73,18 @@ function argumentEncodingLength(argument) {
         return 1 + 8;
     }
 }
-function numberEncodingLength(value) {
+function numberEncodingLength(value, options) {
     if (Object.is(value, 0)) {
         return integerEncodingLength(value);
     }
     else if (Object.is(value, -0)) {
-        return floatEncodingLength(value);
+        return floatEncodingLength(value, options);
     }
     else if (Math.floor(value) === value && Number.MIN_SAFE_INTEGER <= value && value <= Number.MAX_SAFE_INTEGER) {
         return integerEncodingLength(value);
     }
     else {
-        return floatEncodingLength(value);
+        return floatEncodingLength(value, options);
     }
 }
 function integerEncodingLength(value) {
@@ -90,11 +95,12 @@ function integerEncodingLength(value) {
         return argumentEncodingLength(value);
     }
 }
-function floatEncodingLength(value) {
-    if (getFloat16Precision(value) === Precision.Exact) {
+function floatEncodingLength(value, options) {
+    const { minFloatSize = 16 } = options;
+    if (minFloatSize <= 16 && getFloat16Precision(value) === Precision.Exact) {
         return 1 + 2;
     }
-    else if (getFloat32Precision(value) === Precision.Exact) {
+    else if (minFloatSize <= 32 && getFloat32Precision(value) === Precision.Exact) {
         return 1 + 4;
     }
     else {

package/lib/options.d.ts

@@ -0,0 +1,43 @@
+export declare const FloatSize: {
+    f16: number;
+    f32: number;
+    f64: number;
+};
+export interface EncodeOptions {
+    /**
+     * Allow `undefined`
+     * @default true
+     */
+    allowUndefined?: boolean;
+    /**
+     * Re-use the same underlying ArrayBuffer for all yielded chunks.
+     * If this is enabled, the consumer must copy each chunk content
+     * themselves to a new buffer if they wish to keep it.
+     * This mode is useful for efficiently hashing objects without
+     * ever allocating memory for the entire encoded result.
+     * @default false
+     */
+    chunkRecycling?: boolean;
+    /**
+     * Maximum chunk size
+     * @default 4096
+     */
+    chunkSize?: number;
+    /**
+     * Minimum bitsize for floating-point numbers: 16, 32, or 64
+     * @default 16
+     */
+    minFloatSize?: (typeof FloatSize)[keyof typeof FloatSize];
+}
+export interface DecodeOptions {
+    /**
+     * Allow `undefined`
+     * @default true
+     */
+    allowUndefined?: boolean;
+    /**
+     * Minimum bitsize for floating-point numbers: 16, 32, or 64
+     * @default 16
+     */
+    minFloatSize?: (typeof FloatSize)[keyof typeof FloatSize];
+}

package/lib/options.js

@@ -0,0 +1,5 @@
+export const FloatSize = {
+    f16: 16,
+    f32: 32,
+    f64: 64,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "microcbor",
-	"version": "1.0.0",
+	"version": "1.2.0",
 	"type": "module",
 	"files": [
 		"lib"