@cbortech/cbor 0.23.0 → 0.23.1

package/dist/mapEntries.d.ts

@@ -0,0 +1,3 @@
+export declare class MapEntries extends Array<[unknown, unknown]> {
+    toJSON(): Record<string, unknown>;
+}

package/dist/simple.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Wrapper for unrecognised CBOR simple values (0–255, excluding false/true/
+ * null/undefined). Returned by CborSimple.toJS() so that fromJS() can
+ * reconstruct the original CborSimple node and preserve the round-trip.
+ *
+ * Also serves as a namespace for simple-value utilities.
+ *
+ * @example
+ * const v = CBOR.fromEDN('simple(19)').toJS();
+ * Simple.is(v);    // true
+ * Simple.get(v);   // 19
+ *
+ * const node = CBOR.fromJS(new Simple(19));
+ * node.toEDN();    // "simple(19)"
+ */
+export declare class Simple {
+    readonly value: number;
+    constructor(value: number);
+    valueOf(): number;
+    toJSON(): never;
+    /** Return true if value is a Simple instance. */
+    static is(value: unknown): value is Simple;
+    /** Return the simple number if value is a Simple instance, otherwise undefined. */
+    static get(value: unknown): number | undefined;
+}

package/dist/tag.d.ts

@@ -0,0 +1,45 @@
+export declare const CBOR_TAG: unique symbol;
+export declare class Null {
+    valueOf(): null;
+    toJSON(): null;
+}
+export declare class Undefined {
+    valueOf(): undefined;
+    toJSON(): undefined;
+}
+/** @internal */
+export declare function getCborTag(value: unknown): bigint | undefined;
+/** @internal */
+export declare function setCborTag(value: unknown, tag: bigint): object;
+/** @internal */
+export declare function removeCborTag(value: unknown): unknown;
+/** @internal */
+export declare function getCborTaggedValue(value: unknown): unknown;
+/**
+ * Namespace for CBOR tag annotation utilities.
+ *
+ * @example
+ * const v = CBOR.fromEDN('42("hello")').toJS();
+ * Tag.get(v);        // 42n
+ * Tag.getValue(v);   // "hello"
+ *
+ * const tagged = Tag.set([1, 2, 3], 100n);
+ * Tag.remove(tagged); // [1, 2, 3]
+ */
+export declare class Tag {
+    private constructor();
+    /** Unique symbol used to attach a CBOR tag number to a JS value. */
+    static readonly symbol: typeof CBOR_TAG;
+    /** Wrapper class for tagged `null` values. */
+    static readonly Null: typeof Null;
+    /** Wrapper class for tagged `undefined` values. */
+    static readonly Undefined: typeof Undefined;
+    /** Return the CBOR tag number attached to `value`, or `undefined` if none. */
+    static get(value: unknown): bigint | undefined;
+    /** Attach a CBOR tag number to `value` and return the annotated value. */
+    static set(value: unknown, tag: bigint): object;
+    /** Remove the `[Tag.symbol]` annotation from `value` and return the plain value. */
+    static remove(value: unknown): unknown;
+    /** Return the underlying plain JS value held inside a tagged wrapper. */
+    static getValue(value: unknown): unknown;
+}

package/dist/types.d.ts

@@ -0,0 +1,352 @@
+import { CborExtension } from './extensions/types';
+/**
+ * Shared option types and plugin interfaces.
+ */
+/**
+ * Sentinel returned from a replacer or reviver to omit the key/element from
+ * the output.  Use this instead of returning `undefined` when `undefinedOmits`
+ * is `false` (the default) and you need to drop a specific entry.
+ *
+ * Accessible as `CBOR.OMIT` on the main class.
+ */
+export declare const CBOR_OMIT: unique symbol;
+export type { CborExtension } from './extensions/types';
+export interface ToHexDumpOptions {
+    /**
+     * Indentation per nesting level.
+     * - `number`: number of spaces (e.g. `3` → `"   "`)
+     * - `string`: literal indent string (e.g. `'\t'`)
+     * @default 3
+     */
+    indent?: number | string;
+    /** Comment marker used in the hex dump. Default: `'--'` */
+    commentStyle?: '--' | '#';
+}
+export interface ToJSOptions {
+    /**
+     * How to represent CBOR integer values (major type 0 / 1) in JavaScript.
+     * - `'auto'`: `number` when the value is within the safe integer range
+     *   (±`Number.MAX_SAFE_INTEGER`), `bigint` otherwise.
+     * - `'number'`: always `number` (precision may be lost for large values).
+     * - `'bigint'`: always `bigint`.
+     * @default 'auto'
+     */
+    integerAs?: 'auto' | 'number' | 'bigint';
+    /**
+     * How to represent CBOR map values when converting to JavaScript.
+     * - `'auto'`: text-string-only keys → `Record<string, unknown>`,
+     *   other key types → `Map<unknown, unknown>`.
+     *   Duplicate keys are silently overwritten (last value wins).
+     * - `'object'`: always `Record<string, unknown>` — non-string keys are
+     *   converted via `String()`. Duplicate keys are overwritten (last wins).
+     * - `'entries'`: always `MapEntries` (a typed `Array` subclass) — preserves all
+     *   entries including duplicate keys (§2.6.2 of draft-ietf-cbor-edn-literals-20).
+     *   `fromJS()` recognises `MapEntries` instances and converts them back to `CborMap`.
+     * @default 'auto'
+     */
+    mapAs?: 'auto' | 'object' | 'entries';
+    /**
+     * Post-conversion reviver function, applied bottom-up after the CBOR value
+     * has been converted to JavaScript.
+     *
+     * Called for every key/value pair — including map entries with non-string
+     * keys — and finally for the root value with key `''`.
+     * Return `CBOR.OMIT` to remove the entry from its parent container.
+     * When `undefinedOmits` is `true`, returning `undefined` also removes the
+     * entry (matching `JSON.parse` behavior).
+     *
+     * Note: this option is honoured by `CborItem.toJS()` and the `CBOR.*`
+     * shortcut methods.  Calling `_toJS()` directly bypasses it.
+     */
+    reviver?: (this: unknown, key: unknown, value: unknown) => unknown;
+    /**
+     * When `true`, a reviver returning `undefined` removes the entry from its
+     * parent container, matching `JSON.parse` behavior.
+     * When `false` (default), only `CBOR.OMIT` removes an entry; returning
+     * `undefined` keeps the entry as CBOR `undefined` (simple 23).
+     * @default false
+     */
+    undefinedOmits?: boolean;
+}
+export interface ToCBOROptions {
+}
+export interface FromCBOROptions {
+    /**
+     * Byte offset within the supplied input at which CBOR decoding starts.
+     * Useful for reading one item from a CBOR Sequence.
+     *
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * Allow bytes after the decoded item.
+     *
+     * When `false`, decoding still requires the item to consume the remaining
+     * input, preserving the historical single-item behaviour. Set this to `true`
+     * when using `CborItem.end` to continue decoding a CBOR Sequence.
+     *
+     * @example
+     * // Read two items from a CBOR Sequence, validating that the second is last.
+     * const first = CBOR.fromCBOR(bytes, { allowTrailing: true });
+     * const second = CBOR.fromCBOR(bytes, { offset: first.end });
+     *
+     * @default false
+     */
+    allowTrailing?: boolean;
+    /**
+     * Extension plugins applied during CBOR decoding.
+     * Extensions with `parseTag()` are invoked when a tagged item is
+     * encountered; returning a non-`undefined` value replaces the default
+     * `CborTag` node.
+     */
+    extensions?: CborExtension[];
+}
+/**
+ * Options for parsing an annotated hex dump.
+ */
+export interface FromHexDumpOptions {
+    /**
+     * Extension plugins applied during CBOR decoding.
+     * Extensions with `parseTag()` are invoked when a tagged item is encountered;
+     * returning a non-`undefined` value replaces the default `CborTag` node.
+     */
+    extensions?: CborExtension[];
+}
+export interface FromEDNOptions {
+    /**
+     * Character offset within the supplied text at which CBOR-EDN parsing starts.
+     * Leading whitespace/comments at or after this offset are skipped as usual.
+     *
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * Allow tokens after the parsed item.
+     *
+     * When `false`, parsing still requires the item to consume the remaining
+     * input, preserving the historical single-item behaviour. Set this to `true`
+     * when using `CborItem.end` to continue parsing a CBOR-EDN sequence.
+     * Top-level comma separators are not skipped by `fromEDN()` itself; handle
+     * them in sequence-level code before passing the next `offset`. For example,
+     * after parsing `1, 2`, the first item's `end` points just before the comma;
+     * advance past that comma before parsing the next item.
+     *
+     * @example
+     * // Read two whitespace-separated items, validating that the second is last.
+     * const first = CBOR.fromEDN(text, { allowTrailing: true });
+     * const second = CBOR.fromEDN(text, { offset: first.end });
+     *
+     * @default false
+     */
+    allowTrailing?: boolean;
+    /**
+     * Extension plugins for EDN parsing.
+     * Each extension declares which app-string prefixes (and, in future, tag
+     * numbers) it handles via `appStringPrefixes` / `tagNumbers`, and provides
+     * callback methods that return `CborItem`-subclassed objects controlling
+     * subsequent serialisation.
+     *
+     * User-supplied extensions take priority over the built-in `dt`/`DT`
+     * extension for the same prefix.
+     */
+    extensions?: CborExtension[];
+    /**
+     * How to handle unrecognised application-extension identifiers
+     * (§4.1 draft-ietf-cbor-edn-literals-20).
+     *
+     * - `'cpa999'`: wrap the literal in a `CPA999` tag
+     *   (`CborUnresolvedAppExt`) instead of failing. The resulting node
+     *   round-trips through `toEDN()` back to the original notation.
+     * - `'error'`: throw `SyntaxError` for unknown prefixes.
+     * @default 'cpa999'
+     */
+    unresolvedExtension?: 'cpa999' | 'error';
+    /**
+     * When `true`, byte-string chunks in text string concatenation
+     * (`"a" + h'...'`) that are not valid UTF-8 are decoded with the Unicode
+     * replacement character (U+FFFD) instead of throwing a `SyntaxError`.
+     *
+     * The CBOR text string type (RFC 8949 §3.1) requires valid UTF-8;
+     * enabling this option produces non-conformant output and should only be
+     * used when interoperating with lenient producers.
+     *
+     * @default false
+     */
+    allowInvalidUtf8?: boolean;
+    /**
+     * Preserve comments found between CBOR-EDN values and attach them to the AST.
+     *
+     * Comments are metadata only: they are ignored by CBOR binary encoding and
+     * JavaScript conversion. Use together with `ToEDNOptions.preserveComments`
+     * to include them when formatting back to EDN.
+     *
+     * @default false
+     */
+    preserveComments?: boolean;
+}
+export interface FromJSOptions {
+    /**
+     * Extension plugins applied during `fromJS()`.
+     * Extensions with `fromJS()` are given first chance to convert each value.
+     */
+    extensions?: CborExtension[];
+    /**
+     * How to encode integer-valued JS `number`s.
+     * - `'int'`: encode as CborUint / CborNint
+     * - `'float'`: always encode as CborFloat
+     * @default 'int'
+     */
+    encodeIntegerAs?: 'int' | 'float';
+    /**
+     * How to encode `Uint8Array` values.
+     * - `'bytes'`: encode as CborByteString
+     * - `'array'`: encode as CborArray of CborUint
+     * @default 'bytes'
+     */
+    uint8ArrayAs?: 'bytes' | 'array';
+    /**
+     * Pre-encoding replacer function or key allowlist, applied before the
+     * JavaScript value is converted to a CBOR AST node.
+     *
+     * - Function: called for every key/value pair (including `MapEntries`
+     *   entries with non-string keys).  Return `CBOR.OMIT` to remove the entry.
+     *   When `undefinedOmits` is `true`, returning `undefined` also removes it.
+     * - Array of strings/numbers: allowlist of object keys to include.
+     *   `MapEntries` entries retain all entries; their values are recursively
+     *   filtered.
+     *
+     * Note: this option is honoured by `fromJS()` and the `CBOR.*` shortcut
+     * methods.
+     */
+    replacer?: ((this: unknown, key: unknown, value: unknown) => unknown) | (string | number)[];
+    /**
+     * When `true`, a replacer returning `undefined` removes the entry from the
+     * output, matching `JSON.stringify` behavior.
+     * When `false` (default), only `CBOR.OMIT` removes an entry; returning
+     * `undefined` keeps the entry as CBOR `undefined` (simple 23).
+     * @default false
+     */
+    undefinedOmits?: boolean;
+}
+export interface ToEDNOptions {
+    /**
+     * Indentation for pretty-printing.
+     * - `number`: number of spaces
+     * - `string`: literal indent string (e.g. `'\t'`)
+     * - omit for single-line output
+     */
+    indent?: number | string;
+    /**
+     * Emit comments previously captured by `FromEDNOptions.preserveComments`.
+     *
+     * When enabled for containers, comment-bearing arrays/maps are emitted in
+     * multi-line form even if `indent` is omitted.
+     *
+     * @default false
+     */
+    preserveComments?: boolean;
+    /**
+     * Re-emit byte string literals parsed from EDN using their original source
+     * text when available.
+     *
+     * This preserves the spelling and interior layout of non-concatenated
+     * `h'...'`, `b64'...'`, `b32'...'`, `h32'...'`, raw-backtick byte strings,
+     * and single-quoted byte strings, including comments inside those literals.
+     * Byte strings produced by `+` concatenation are normalised as usual.
+     *
+     * When enabled, this takes precedence over `bstrEncoding` and `sqstr` for
+     * byte strings that carry original EDN source text.
+     *
+     * @default false
+     */
+    preserveByteString?: boolean;
+    /**
+     * Whether to emit commas between array/map elements.
+     * - `'comma'`: emit commas (`[1, 2, 3]`)
+     * - `'none'`: omit commas, use spaces only (`[1 2 3]`)
+     * - `'trailing'`: emit commas including a trailing comma after the last element
+     * @default 'comma'
+     */
+    commas?: 'comma' | 'none' | 'trailing';
+    /**
+    /**
+     * Fallback binary encoding for byte string literals when sqstr is not applicable.
+     * - `'hex'`: `h'...'`
+     * - `'base64'`: `b64'...'`
+     * - `'base64url'`: `b64'...'` (base64url alphabet)
+     * - `'base32'`: `b32'...'`
+     * - `'base32hex'`: `h32'...'`
+     * @default 'hex'
+     */
+    bstrEncoding?: 'hex' | 'base64' | 'base64url' | 'base32' | 'base32hex';
+    /**
+     * Whether to prefer single-quoted string form (`sqstr`) for byte strings.
+     * - `'printable-string'`: emit `'...'` when the bytes are valid UTF-8 and
+     *   contain no control characters; fall back to `bstrEncoding` otherwise.
+     * - `'string'`: emit `'...'` when the bytes are valid UTF-8;
+     *   fall back to `bstrEncoding` otherwise.
+     * - `'none'`: never emit sqstr; always use `bstrEncoding`.
+     * @default 'printable-string'
+     */
+    sqstr?: 'printable-string' | 'string' | 'none';
+    /**
+     * Whether to use application-string / app-sequence notation for built-in
+     * extensions (e.g. `dt'...'`, `DT'...'`, `ip'...'`, `IP'...'`).
+     * - `true`: emit extension notation (`DT'2023-01-01T12:00:00Z'`)
+     * - `false`: emit raw CBOR notation (`1(-14159024)`, `52(h'c000022a')`)
+     * @default true
+     */
+    appStrings?: boolean;
+    /**
+     * Numeric format for integer values in EDN output.
+     * - `'decimal'`: standard decimal notation (e.g. `42`, `-14159024`)
+     * - `'hex'`: hexadecimal notation (e.g. `0x2a`, `-0xd83130`)
+     * - `'octal'`: octal notation (e.g. `0o52`, `-0o67061560`)
+     * - `'binary'`: binary notation (e.g. `0b101010`, `-0b110110000011000100110000`)
+     * @default 'decimal'
+     */
+    intFormat?: 'decimal' | 'hex' | 'octal' | 'binary';
+    /**
+     * Numeric format for floating-point values in EDN output.
+     * - `'decimal'`: standard decimal notation (e.g. `1.5`, `145544.0_3`)
+     * - `'hex'`: C99-style hex float notation (e.g. `0x1.8p+0`, `0x1.1c54p+17_3`)
+     * @default 'decimal'
+     */
+    floatFormat?: 'decimal' | 'hex';
+    /**
+     * Split long text strings using EDN string concatenation syntax (`"a" + "b"`).
+     * Only effective when `indent` is specified.
+     *
+     * - `'newline'`: split at newline characters
+     * - `'cboredn'`: split according to CBOR-EDN structure when the string content
+     *                is parseable as CBOR-EDN (JSON superset)
+     *
+     * When both are specified, `'cboredn'` is tried first; `'newline'` is used
+     * only when the string content is not parseable as CBOR-EDN.
+     */
+    textStringFormat?: ('newline' | 'cboredn')[];
+}
+export interface CborComment {
+    kind: 'line' | 'block';
+    marker: '#' | '//' | '/*' | '/';
+    text: string;
+    start: number;
+    end: number;
+    line: number;
+    col: number;
+}
+export interface CborComments {
+    leading?: CborComment[];
+    trailing?: CborComment[];
+    dangling?: CborComment[];
+}
+/**
+ * Combined options for the `CBOR` constructor.
+ *
+ * These defaults are applied to every subsequent method call on the instance.
+ * Per-call options always take precedence over these defaults.
+ *
+ * Note: `encodeIntegerAs` (from {@link FromJSOptions}) and `integerAs` (from
+ * {@link ToJSOptions}) are distinct fields and do not conflict.
+ */
+export type CBOROptions = FromEDNOptions & FromJSOptions & ToCBOROptions & ToEDNOptions & ToJSOptions & ToHexDumpOptions;

package/dist/utils/float16.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Float16 (IEEE 754 binary16) encode/decode utilities.
+ *
+ * Uses native DataView.getFloat16 / setFloat16 when both are available,
+ * and falls back to a manual bit-manipulation implementation otherwise.
+ *
+ * binary16 format:
+ *   bit 15    : sign
+ *   bits 14-10: exponent (5 bits, bias = 15)
+ *   bits  9- 0: mantissa (10 bits)
+ */
+export declare const hasNativeFloat16: boolean;
+/**
+ * float64 → float16 bit pattern (16-bit unsigned integer).
+ *
+ * Operates directly on float64 bits to avoid double-rounding artifacts that
+ * arise from a float64 → float32 → float16 two-step conversion.
+ * Implements IEEE 754 round-to-nearest-ties-to-even (RN-TE).
+ *
+ * Exported for testing (manual vs native consistency checks).
+ */
+export declare function float64ToFloat16Bits(value: number): number;
+/**
+ * float16 bit pattern → float64.
+ * Exported for testing purposes.
+ */
+export declare function float16BitsToFloat64(bits: number): number;
+/**
+ * Write a float16 value at the given offset in a DataView.
+ */
+type WriteFloat16 = (view: DataView, offset: number, value: number, littleEndian: boolean) => void;
+/**
+ * Read a float16 value from the given offset in a DataView, returned as float64.
+ */
+type ReadFloat16 = (view: DataView, offset: number, littleEndian: boolean) => number;
+export declare const writeFloat16: WriteFloat16;
+export declare const readFloat16: ReadFloat16;
+export {};

package/dist/utils/hexfloat.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hex float (C99-style, e.g. `0x1.8p+0`) encode/decode utilities.
+ *
+ * Hex float format:
+ *   [-] 0x [hex digits] [. [hex digits]] p [+-] [decimal exponent]
+ *
+ * This notation appears in CBOR-EDN (draft-ietf-cbor-edn-literals) as an
+ * alternative representation for floating-point values (major type 7).
+ */
+/**
+ * Parse a hex float literal (e.g. `0x4711p+03`, `0x1.8p+0`, `-0x1.fp-2`)
+ * to a JS number.
+ *
+ * Assumes the string has already been stripped of any encoding-indicator
+ * suffix (`_1`, `_2`, `_3`).
+ */
+export declare function parseHexFloat(s: string): number;
+/**
+ * Convert a JS number to a normalized hex float string compatible with
+ * CBOR-EDN diagnostic notation.
+ *
+ * - Normal values: `0x1.[hex fraction]p[+-][exp]`  (e.g. `0x1.8p+0` for 1.5)
+ * - Subnormal values: `0x0.[hex fraction]p-1022`
+ * - Zero: `0x0p+0` / `-0x0p+0`
+ * - Non-finite values (NaN, ±Infinity) are returned unchanged as EDN tokens.
+ */
+export declare function floatToHexFloat(v: number): string;

package/dist/utils/ip.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared IPv4 / IPv6 address parsing and formatting utilities.
+ * Used by the "ip"/"IP" extension (RFC 9164) and the "cri"/"CRI" extension
+ * (draft-ietf-core-href).
+ */
+export declare function parseIPv4(str: string): Uint8Array;
+export declare function parseIPv6(str: string): Uint8Array;
+export declare function formatIPv4(bytes: Uint8Array): string;
+export declare function formatIPv6(bytes: Uint8Array): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cbortech/cbor",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "Convert between CBOR, CBOR-EDN, and JavaScript values",
   "keywords": [
     "cbor",
@@ -40,6 +40,16 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./ast": {
+      "import": {
+        "types": "./dist/ast/index.d.ts",
+        "default": "./dist/ast/index.js"
+      },
+      "require": {
+        "types": "./dist/ast/index.d.ts",
+        "default": "./dist/ast/index.cjs"
+      }
     }
   },
   "files": [
@@ -54,6 +64,7 @@
     "dev": "npm run build && npm start",
     "clean": "node -e \"['dist','coverage'].forEach(d=>require('fs').rmSync(d,{recursive:true,force:true}))\"",
     "test": "vitest run",
+    "test:exports": "npm run build && node scripts/check-package-exports.mjs",
     "test:vectors": "vitest run --config vitest.vectors.config.ts",
     "test:node": "vitest run",
     "test:chromium": "BROWSER=chromium vitest run --config vitest.browser.config.ts",