@cbortech/cbor 0.23.0 → 0.23.1

package/dist/cbor.d.ts

@@ -0,0 +1,129 @@
+import { CborItem } from './ast/CborItem';
+import { CBOROptions, FromCBOROptions, FromHexDumpOptions, FromEDNOptions, FromJSOptions, ToCBOROptions, ToEDNOptions, ToJSOptions, CBOR_OMIT } from './types';
+import { dt_as_Date as _dt_as_Date } from './extensions/dt';
+import { MapEntries as _MapEntries } from './mapEntries';
+import { Simple as _Simple } from './simple';
+import { CBOR_TAG, Tag as _Tag } from './tag';
+/**
+ * Main facade class.
+ *
+ * Provides factory methods for constructing AST nodes from the three
+ * supported input formats, and shortcut methods that mirror the
+ * `JSON.parse` / `JSON.stringify` API.
+ *
+ * @example
+ * // CBOR binary → AST → CBOR binary
+ * const ast = CBOR.fromCBOR(bytes);
+ * const reencoded = ast.toCBOR();
+ *
+ * @example
+ * // JS value → CBOR binary (shortcut)
+ * const bytes = CBOR.encode({ hello: 'world' });
+ *
+ * @example
+ * // CBOR binary → JS value (shortcut)
+ * const value = CBOR.decode(bytes);
+ */
+export declare class CBOR {
+    #private;
+    /**
+     * Sentinel returned from a replacer or reviver to omit the key/element from
+     * the output.  Use this instead of `undefined` when `undefinedOmits` is
+     * `false` (the default) and you need to drop a specific entry.
+     */
+    static readonly OMIT: typeof CBOR_OMIT;
+    /** Unique symbol used to attach a CBOR tag number to a JS value. */
+    static readonly TAG: typeof CBOR_TAG;
+    /** Namespace for CBOR tag annotation utilities. */
+    static readonly Tag: typeof _Tag;
+    /** Wrapper for CBOR simple values other than false/true/null/undefined. */
+    static readonly Simple: typeof _Simple;
+    /** Array subclass used to preserve CBOR map entries, including duplicates. */
+    static readonly MapEntries: typeof _MapEntries;
+    /** Extension that maps CBOR-EDN dt/DT values to JavaScript Date objects. */
+    static readonly dt_as_Date: typeof _dt_as_Date;
+    /**
+     * Create a reusable instance with default options applied to every method call.
+     * Per-call options always override these defaults.
+     *
+     * @example
+     * const cbor = new CBOR({ extensions: [CBOR.dt_as_Date] });
+     * const obj  = cbor.parse('{ "dt": DT\'2024-01-01T00:00:00Z\' }');
+     * const text = cbor.stringify(obj);
+     */
+    constructor(defaults?: CBOROptions);
+    fromCBOR(input: ArrayBufferView | ArrayBufferLike, options?: FromCBOROptions): CborItem;
+    fromEDN(text: string, options?: FromEDNOptions): CborItem;
+    fromJS(value: unknown, options?: FromJSOptions): CborItem;
+    fromHexDump(text: string, options?: FromHexDumpOptions): CborItem;
+    decode(input: ArrayBufferView | ArrayBufferLike, options?: FromCBOROptions & ToJSOptions): unknown;
+    encode(value: unknown, options?: FromJSOptions & ToCBOROptions): Uint8Array;
+    cborToCborEdn(input: ArrayBufferView | ArrayBufferLike, options?: FromCBOROptions & ToEDNOptions): string;
+    cborEdnToCbor(text: string, options?: FromEDNOptions & ToCBOROptions): Uint8Array;
+    parse(text: string): unknown;
+    parse(text: string, reviver: (this: unknown, key: unknown, value: unknown) => unknown): unknown;
+    parse(text: string, options: FromEDNOptions & ToJSOptions): unknown;
+    stringify(value: unknown): string;
+    stringify(value: unknown, replacer: ((this: unknown, key: unknown, value: unknown) => unknown) | (string | number)[] | null, space?: string | number): string;
+    stringify(value: unknown, options: FromJSOptions & ToEDNOptions): string;
+    format(text: string, options?: FromEDNOptions & ToEDNOptions): string;
+    /** Decode CBOR binary data into an AST node. */
+    static fromCBOR(input: ArrayBufferView | ArrayBufferLike, options?: FromCBOROptions): CborItem;
+    /** Parse a CBOR-EDN text string into an AST node. */
+    static fromEDN(text: string, options?: FromEDNOptions): CborItem;
+    /** Convert a JavaScript value into an AST node. */
+    static fromJS(value: unknown, options?: FromJSOptions): CborItem;
+    /**
+     * Parse an annotated hex dump (as produced by {@link CborItem#toHexDump})
+     * into an AST node.
+     *
+     * Each line is expected to have the form:
+     *   `[whitespace] HH [HH …]  -- comment`
+     *   `[whitespace] HH [HH …]  # comment`
+     *   `[whitespace] HH [HH …]  // comment`
+     * Block comments may also be written as `/ comment /` or `/* comment *\/`.
+     * Lines with no hex content before the comment marker are ignored.
+     */
+    static fromHexDump(text: string, options?: FromHexDumpOptions): CborItem;
+    /** Decode CBOR binary data directly to a JavaScript value. */
+    static decode(input: ArrayBufferView | ArrayBufferLike, options?: FromCBOROptions & ToJSOptions): unknown;
+    /** Encode a JavaScript value directly to CBOR binary data. */
+    static encode(value: unknown, options?: FromJSOptions & ToCBOROptions): Uint8Array;
+    /** Convert CBOR binary data directly to a CBOR-EDN text string. */
+    static cborToCborEdn(input: ArrayBufferView | ArrayBufferLike, options?: FromCBOROptions & ToEDNOptions): string;
+    /** Convert a CBOR-EDN text string directly to CBOR binary data. */
+    static cborEdnToCbor(text: string, options?: FromEDNOptions & ToCBOROptions): Uint8Array;
+    /**
+     * Parse a CBOR-EDN text string directly to a JavaScript value.
+     *
+     * Accepts either a JSON-compatible `reviver` function as the second argument,
+     * or a plain options object (existing API).
+     *
+     * When a `reviver` is supplied it is applied bottom-up after the EDN text has
+     * been parsed and converted to a JS value, matching the semantics of
+     * `JSON.parse(text, reviver)`.
+     *
+     * Note: CBOR-specific value types such as `bigint` are passed to the reviver
+     * as-is; the reviver is responsible for handling them.
+     */
+    static parse(text: string): unknown;
+    static parse(text: string, reviver: (this: unknown, key: unknown, value: unknown) => unknown): unknown;
+    static parse(text: string, options: FromEDNOptions & ToJSOptions): unknown;
+    /**
+     * Serialize a JavaScript value directly to a CBOR-EDN text string.
+     *
+     * Accepts either JSON-compatible `replacer` + `space` arguments, or a plain
+     * options object (existing API).
+     *
+     * - `replacer` may be a function (transforms each key/value before encoding)
+     *   or an array of strings/numbers (allowlist of object keys to include).
+     *   Pass `null` to skip filtering.
+     * - `space` controls indentation, mapping to `ToEDNOptions.indent`.
+     *   Numbers are clamped to `[0, 10]`; strings are truncated to 10 characters.
+     */
+    static stringify(value: unknown): string;
+    static stringify(value: unknown, replacer: ((this: unknown, key: unknown, value: unknown) => unknown) | (string | number)[] | null, space?: string | number): string;
+    static stringify(value: unknown, options: FromJSOptions & ToEDNOptions): string;
+    /** Normalize a CBOR-EDN text string by parsing and re-serializing it. */
+    static format(text: string, options?: FromEDNOptions & ToEDNOptions): string;
+}

package/dist/edn/parser.d.ts

@@ -0,0 +1,7 @@
+import { CborItem } from '../ast/CborItem';
+import { FromEDNOptions } from '../types';
+/**
+ * Parse a CBOR-EDN diagnostic notation string into a CborItem AST node.
+ * Throws SyntaxError on invalid input.
+ */
+export declare function parseEDN(text: string, options?: FromEDNOptions): CborItem;

package/dist/edn/serialize-utils.d.ts

@@ -0,0 +1,48 @@
+import { CborComments, ToEDNOptions } from '../types';
+/** Resolve indent option to a string, or null for single-line output. */
+export declare function resolveIndent(options: ToEDNOptions | undefined): string | null;
+/** Build the indent prefix for a given depth. */
+export declare function indentOf(indentStr: string, depth: number): string;
+export interface Commented {
+    comments?: CborComments;
+}
+export declare function hasPreservedComments(item: Commented): boolean;
+export declare function hasContainerLayoutComments(item: Commented): boolean;
+export declare function formatLeadingComments(item: Commented, indent: string): string[];
+export declare function formatTrailingComments(item: Commented): string;
+export declare function formatDanglingComments(item: Commented, indent: string): string[];
+/**
+ * Resolve separator options into concrete strings.
+ *
+ * @param compact - When `true` (no `indent` option), omit spaces around
+ *   separators to produce compact single-line output (like `JSON.stringify`).
+ *
+ * @returns
+ *   - `inlineSep`    – between items on a single line
+ *   - `multilineSep` – appended after each non-last line in multi-line mode
+ *   - `trailSep`     – appended after the last item (empty string or `,`)
+ *   - `colSep`       – between map key and value (`': '` or `':'`)
+ */
+export declare function resolveSeparators(options: ToEDNOptions | undefined, compact?: boolean): {
+    inlineSep: string;
+    multilineSep: string;
+    trailSep: string;
+    colSep: string;
+};
+export declare function serializeBytes(bytes: Uint8Array, encoding?: 'hex' | 'base64' | 'base64url' | 'base32' | 'base32hex', sqstr?: 'printable-string' | 'string' | 'none'): string;
+/**
+ * Produce a single-quoted EDN app-string content `'...'` from a string value.
+ * Exported for use by app-extension `_toEDN` implementations.
+ */
+export declare function escapeAppString(s: string): string;
+/**
+ * Produce an EDN double-quoted string literal `"..."` from a string value.
+ */
+export declare function escapeString(s: string): string;
+/** Produce the numeric string for a float value (with decimal point if needed). */
+export declare function floatValueToString(value: number): string;
+/**
+ * EDN encoding-indicator suffix for a float precision.
+ * Returns '' when the auto-selected precision matches (no suffix needed).
+ */
+export declare function floatSuffix(_value: number, precision: 'half' | 'single' | 'double' | undefined, autoSelected: 'half' | 'single' | 'double'): string;

package/dist/edn/serializer.d.ts

@@ -0,0 +1,7 @@
+import { CborItem } from '../ast/CborItem';
+import { ToEDNOptions } from '../types';
+/**
+ * Serialize a CborItem AST node to CBOR-EDN diagnostic notation.
+ * Equivalent to calling value.toEDN(options) directly.
+ */
+export declare function toEDN(value: CborItem, options?: ToEDNOptions): string;

package/dist/edn/tokenizer.d.ts

@@ -0,0 +1,176 @@
+/**
+ * EDN lexer (internal).
+ *
+ * Used by parser.ts for parsing and by CborTextString serialization to collect
+ * source offsets after parseEDN() has already validated embedded CBOR-EDN.
+ */
+export type TokenType = 'INTEGER' | 'FLOAT' | 'TSTR' | 'SQSTR' | 'RAWSTRING' | 'BYTES_HEX' | 'BYTES_HEX_ELIDED' | 'BYTES_B64' | 'BYTES_B32' | 'BYTES_H32' | 'APP_STRING' | 'APP_SEQUENCE' | 'EMPTY_INDEF_BYTES' | 'EMPTY_INDEF_TEXT' | 'TRUE' | 'FALSE' | 'NULL' | 'UNDEFINED' | 'SIMPLE' | 'LBRACKET' | 'RBRACKET' | 'LBRACE' | 'RBRACE' | 'LPAREN' | 'RPAREN' | 'COLON' | 'COMMA' | 'PLUS' | 'UNDERSCORE' | 'ENCODING_INDICATOR' | 'LT_LT' | 'GT_GT' | 'ELLIPSIS' | 'EOF';
+export interface Token {
+    type: TokenType;
+    /** Processed value: decoded string content, raw number text, raw byte content, etc. */
+    value: string;
+    /** Original source text for this token. */
+    raw: string;
+    line: number;
+    col: number;
+    /** Character offset of the first character of this token in the source input. */
+    offset: number;
+    /** Character offset just past the last character of this token in the source input. */
+    endOffset: number;
+    /** Only set when type === 'APP_STRING': the extension prefix (e.g. 'dt', 'DT'). */
+    appPrefix?: string;
+}
+export interface TokenizerOptions {
+    /** Character offset at which tokenization starts. */
+    offset?: number;
+}
+export interface EdnComment {
+    kind: 'line' | 'block';
+    marker: '#' | '//' | '/*' | '/';
+    text: string;
+    start: number;
+    end: number;
+    line: number;
+    col: number;
+}
+export declare class Tokenizer {
+    private readonly input;
+    private pos;
+    private line;
+    private col;
+    private _peeked;
+    private _lastConsumedEndOffset;
+    /** Comments encountered while scanning, appended in source order. */
+    readonly comments: EdnComment[];
+    constructor(input: string, options?: TokenizerOptions);
+    peek(): Token;
+    consume(): Token;
+    /** Character offset just past the last character of the most recently consumed token. */
+    get lastEndOffset(): number;
+    private _ch;
+    private _eof;
+    private _advance;
+    private _fail;
+    private _skipWS;
+    /**
+     * Skip a comment in a quoted byte string literal (h'', b32'', h32'').
+     * Returns true if a comment was consumed, false if the current char is not a
+     * comment start. `quote` is the closing delimiter character.
+     *
+     * Supports / ... /, /* *\/, //, and # comment forms (§2.2).
+     */
+    private _skipByteStringComment;
+    /**
+     * Skip a comment in a raw byte string (h``, b32``, h32``).
+     * Called with `i` pointing at the comment-start character.
+     * Returns the index after the comment, or -1 if no comment was found.
+     *
+     * Supports / ... /, /* *\/, //, and # comment forms (§2.2).
+     * `context` is used in unterminated-comment error messages.
+     */
+    private _skipRawComment;
+    /** Skip content until a closing `/` (CBOR-EDN block comment). */
+    private _skipBlockCommentSlash;
+    /** Skip content until a closing `*\/` (JSONC block comment). */
+    private _skipBlockCommentStar;
+    /**
+     * Read content between `quote` delimiters, processing escape sequences.
+     *
+     * Strict spec compliance:
+     * - Literal LF (U+000A) is allowed; all other C0 controls and U+007F are rejected.
+     * - Literal CR (U+000D) is silently stripped (source-level CRLF normalisation).
+     * - Only spec-defined escape sequences are accepted; `\q` etc. throw SyntaxError.
+     * - `\/` is valid in both single- and double-quoted strings.
+     * - `\\` (backslash) is always a valid escape.
+     * - `\uXXXX` for a high surrogate must be immediately followed by `\uXXXX` for
+     *   the corresponding low surrogate; lone surrogates are rejected.
+     * - `\u{N}` … `\u{10FFFF}` extended syntax is supported; surrogates are rejected.
+     * - In single-quoted strings, `\u` escapes to printable ASCII (U+0020–U+007E)
+     *   are forbidden (hexchar-s restriction, draft §2.5.2 / §5.1).
+     */
+    private _readStringContent;
+    /**
+     * Parse a Unicode escape immediately after `\u` has been consumed.
+     *
+     * @param quote - The enclosing string delimiter (`"` or `'`).
+     *
+     * Handles two forms:
+     * - `\u{N}` … `\u{10FFFF}`: direct Unicode scalar value (surrogates rejected)
+     * - `\uXXXX`: exactly four hex digits; a high surrogate must be followed by
+     *   `\uXXXX` for the matching low surrogate to form a valid surrogate pair,
+     *   which is then decoded into the corresponding non-BMP code point.
+     *
+     * In single-quoted strings (`quote === "'"`), `\u` escapes that resolve to
+     * printable ASCII (U+0020–U+007E) are rejected per draft §2.5.2 / §5.1
+     * hexchar-s, except for backslash (U+005C) and single-quote (U+0027), which
+     * require escaping and cannot be written literally.
+     */
+    private _readUnicodeEscape;
+    /**
+     * Read raw text-string content between N-backtick delimiters (§2.5.3).
+     *
+     * - The opening delimiter is the maximal run of consecutive backticks (N ≥ 1).
+     * - A single leading newline (LF or CRLF) immediately after the opening is stripped.
+     * - No escape sequences are processed — content is taken verbatim.
+     * - Literal CR is stripped for source-level CRLF normalisation.
+     * - The closing delimiter is the first run of M ≥ N backticks; any excess
+     *   M-N backticks are appended to the content before closing.
+     */
+    private _readRawStringContent;
+    /**
+     * Post-process raw hex content from a `h``…``\` raw string (§5.3.3).
+     *
+     * Skips:
+     *   - lblank whitespace (LF, SP; also CR for source-level normalisation)
+     *   - `/ … /` block comments
+     *   - `# …` line comments (up to but not including LF)
+     * Detects `...` ellipsis sequences.
+     *
+     * A trailing `# comment` immediately before the closing delimiter is allowed
+     * per §5.3.3 `r-app-string-h`.
+     *
+     * Returns { value: hex-string-with-ellipsis-markers, elided: boolean }
+     */
+    private _processRawHexContent;
+    /**
+     * Post-process raw base64 content from a `b64``…``\` raw string (§5.3.4).
+     *
+     * Skips:
+     *   - lblank whitespace (LF, SP; also CR for source-level normalisation)
+     *   - `# …` line comments (up to but not including LF)
+     *
+     * Returns the stripped base64 string.
+     */
+    private _processRawB64Content;
+    /**
+     * Post-process raw base32/base32hex content from `b32``…``\` / `h32``…``\` raw strings.
+     *
+     * Supports all comment forms (§2.2): `/ ... /`, `/*...*\/`, `//`, `#`.
+     * HT is still forbidden (rawchars excludes %x09).
+     */
+    private _processRawB32Content;
+    /**
+     * Read raw byte-string content between `quote` chars (b64 / b64url).
+     *
+     * Strips whitespace and skips `# ...` line comments per §2.5.5.
+     * `/` is NOT treated as a comment delimiter because it is a valid base64 character.
+     */
+    private _readByteContent;
+    /**
+     * Read base32 / base32hex byte-string content (`b32'...'` / `h32'...'`).
+     *
+     * Supports all comment forms (§2.2): `/ ... /`, `/*...*\/`, `//`, `#`.
+     */
+    private _readB32Content;
+    /**
+     * Read hex byte-string content, recognising `...` ellipsis sequences (§4.2).
+     *
+     * Returns the raw hex string (with `...` markers embedded) and a flag
+     * indicating whether any ellipsis was found.
+     */
+    private _readHexByteContentElisionAware;
+    private _readNext;
+    private _readNextCore;
+    private _readNumber;
+    private _readIdent;
+}

package/dist/extensions/bignum.d.ts

@@ -0,0 +1,3 @@
+import { CborExtension } from './types';
+export declare const bignum: CborExtension;
+export default bignum;

package/dist/extensions/builtins.d.ts

@@ -0,0 +1,2 @@
+import { CborExtension } from './types';
+export declare const BUILTIN_EXTENSIONS: CborExtension[];

package/dist/extensions/cbordata.d.ts

@@ -0,0 +1,4 @@
+import { CborExtension } from './types';
+export declare const TAG_CBOR_DATA = 24n;
+declare const cbordata: CborExtension;
+export default cbordata;

package/dist/extensions/cri.d.ts

@@ -0,0 +1,32 @@
+import { ToEDNOptions } from '../types';
+import { CborExtension } from './types';
+import { CborArray } from '../ast/CborArray';
+import { CborTag } from '../ast/CborTag';
+/**
+ * CBOR tag number for the tagged CRI variant (draft-ietf-cbor-edn-literals-21 §3.4 / §5.2.5).
+ */
+export declare const TAG_CRI = 99n;
+/**
+ * Bare CRI array whose toEDN() emits cri'…' notation.
+ * Falls back to generic array notation if the content cannot be expressed as a URI.
+ */
+export declare class CborCriExt extends CborArray {
+    _toEDN(options: ToEDNOptions | undefined, depth: number): string;
+}
+/**
+ * tag(99, CRI array) whose toEDN() emits CRI'…' notation.
+ * Falls back to generic tag notation if the content cannot be expressed as a URI.
+ */
+export declare class CborTaggedCriExt extends CborTag {
+    constructor(content: CborArray);
+    _toEDN(options: ToEDNOptions | undefined, depth: number): string;
+}
+/**
+ * Create the cri/CRI CborExtension (§5.2.5 draft-ietf-cbor-edn-literals-20).
+ *
+ * - `cri'uri'`        → CborCriExt (bare CRI array, no CBOR tag)
+ * - `CRI'uri'`        → CborTaggedCriExt tag(99, CRI array)
+ * - parseTag(99n, …)  → CborTaggedCriExt (roundtrip from CBOR binary)
+ */
+export declare const cri: CborExtension;
+export default cri;

package/dist/extensions/dt.d.ts

@@ -0,0 +1,109 @@
+import { ToEDNOptions, ToJSOptions } from '../types';
+import { CborExtension } from './types';
+import { CborUint } from '../ast/CborUint';
+import { CborNint } from '../ast/CborNint';
+import { CborFloat } from '../ast/CborFloat';
+import { CborTag } from '../ast/CborTag';
+import { EncodingWidth } from '../cbor/encode';
+/**
+ * Convert epoch seconds to an RFC 3339 string with appropriate precision.
+ *
+ * - Integer epoch          → "…Z"           (no fractional part)
+ * - Millisecond-precision  → "….SSSZ"       (3 decimal places, e.g. ".500Z")
+ * - Sub-millisecond        → "….S…Z"        (minimal digits, e.g. ".0001Z")
+ *
+ * Millisecond precision is used whenever `Math.round(epochSeconds * 1000)`
+ * round-trips back to the same float64 value, which is the common case for
+ * timestamps stored as integer milliseconds (the JavaScript Date range).
+ * Otherwise the shortest decimal representation of the fractional seconds is
+ * used so that the float64 value is faithfully represented.
+ */
+export declare function epochToRfc3339(epochSeconds: number): string;
+/**
+ * Parse an RFC 3339 string and produce the appropriate epoch CborItem subclass.
+ * Integer seconds → CborEpochDtExtUint or CborEpochDtExtNint.
+ * Fractional seconds → CborEpochDtExtFloat.
+ *
+ * Fractional seconds are extracted from the string directly (via parseFloat)
+ * before passing the remainder to Date.parse, so sub-millisecond precision
+ * is preserved rather than being rounded to the nearest millisecond.
+ */
+export declare function parseDtAppString(str: string): CborEpochDtExtUint | CborEpochDtExtNint | CborEpochDtExtFloat;
+export declare const PREFIX_DT = "dt";
+export declare const PREFIX_DT_TAGGED = "DT";
+export declare const TAG_EPOCH = 1n;
+/**
+ * Unsigned epoch timestamp whose toEDN() emits dt'…' notation.
+ * The RFC 3339 string is re-derived from the numeric value on each call.
+ */
+export declare class CborEpochDtExtUint extends CborUint {
+    constructor(value: number | bigint, options?: {
+        encodingWidth?: EncodingWidth;
+    });
+    _toEDN(options: ToEDNOptions | undefined, _depth: number): string;
+}
+/**
+ * Negative epoch timestamp whose toEDN() emits dt'…' notation.
+ * The RFC 3339 string is re-derived from the numeric value on each call.
+ */
+export declare class CborEpochDtExtNint extends CborNint {
+    constructor(value: number | bigint, options?: {
+        encodingWidth?: EncodingWidth;
+    });
+    _toEDN(options: ToEDNOptions | undefined, _depth: number): string;
+}
+/**
+ * Float epoch timestamp whose toEDN() emits dt'…' notation.
+ * The RFC 3339 string is re-derived from the numeric value on each call.
+ */
+export declare class CborEpochDtExtFloat extends CborFloat {
+    constructor(value: number, options?: {
+        precision?: 'half' | 'single' | 'double';
+    });
+    _toEDN(options: ToEDNOptions | undefined, _depth: number): string;
+}
+/**
+ * CBOR tag(1, epoch) whose toEDN() emits DT'…' notation.
+ * The RFC 3339 string is re-derived from the numeric content on each call.
+ */
+export declare class CborTaggedEpochDtExt extends CborTag {
+    constructor(datetime: string, options?: {
+        encodingWidth?: EncodingWidth;
+    });
+    _toEDN(options: ToEDNOptions | undefined, depth: number): string;
+}
+/**
+ * CBOR tag(1, epoch) whose toJS() returns a plain Date object.
+ * Use dt_as_Date (or createDtExtension({ jsDate: true })) to produce these nodes.
+ */
+export declare class CborTaggedEpochDtAsDateExt extends CborTaggedEpochDtExt {
+    constructor(datetime: string, options?: {
+        encodingWidth?: EncodingWidth;
+    });
+    _toJS(_options?: ToJSOptions): Date;
+}
+/**
+ * Create a dt/DT CborExtension.
+ *
+ * - `createDtExtension()` — tagged DT values produce `CborTaggedEpochDtExt`;
+ *   toJS() returns a number (epoch seconds).
+ * - `createDtExtension({ jsDate: true })` — tagged DT values produce
+ *   `CborTaggedEpochDtAsDateExt`; toJS() returns a `Date` object, and
+ *   `fromJS(Date)` converts `Date` instances back to tagged epoch values.
+ */
+export declare function createDtExtension(options?: {
+    jsDate?: boolean;
+}): CborExtension;
+/**
+ * Standard dt/DT CborExtension.
+ * Tagged DT values produce CborTaggedEpochDtExt; toJS() returns a number.
+ * For Date-based toJS() use dt_as_Date or createDtExtension({ jsDate: true }).
+ */
+export declare const dt: CborExtension;
+/**
+ * Full-featured dt/DT CborExtension with Date support.
+ * Tagged DT values produce CborTaggedEpochDtAsDateExt; toJS() returns a Date.
+ * fromJS(Date) converts Date instances to tagged epoch values.
+ */
+export declare const dt_as_Date: CborExtension;
+export default dt;

package/dist/extensions/hash.d.ts

@@ -0,0 +1,17 @@
+import { ToEDNOptions } from '../types';
+import { CborExtension } from './types';
+import { CborByteString } from '../ast/CborByteString';
+import { CborTextString } from '../ast/CborTextString';
+/**
+ * A byte string produced by a hash'…' or hash<<…>> literal.
+ * Remembers the original input and algorithm so toEDN() can reconstruct
+ * the hash notation when appStrings is not false.
+ */
+export declare class CborHashExt extends CborByteString {
+    private readonly _input;
+    private readonly _algorithmId;
+    constructor(output: Uint8Array, input: CborTextString | CborByteString, algorithmId: number);
+    _toEDN(options: ToEDNOptions | undefined, _depth: number): string;
+}
+export declare const hash: CborExtension;
+export default hash;

package/dist/extensions/ip.d.ts

@@ -0,0 +1,41 @@
+import { ToEDNOptions } from '../types';
+import { CborExtension } from './types';
+import { CborItem } from '../ast/CborItem';
+import { CborByteString } from '../ast/CborByteString';
+import { CborTag } from '../ast/CborTag';
+import { CborArray } from '../ast/CborArray';
+/**
+ * Bare IP address byte string whose toEDN() emits ip'…' notation.
+ */
+export declare class CborIpExt extends CborByteString {
+    _toEDN(options: ToEDNOptions | undefined, _depth: number): string;
+}
+/**
+ * Bare IP address prefix (CIDR) whose toEDN() emits ip'…/prefix' notation.
+ * Encoded as [prefixLen, truncatedBytes] per RFC 9164 §2.3, without a tag.
+ */
+export declare class CborIpPrefixExt extends CborArray {
+    private readonly _isV4;
+    constructor(prefixLen: number, truncated: Uint8Array, isV4: boolean);
+    _toEDN(options: ToEDNOptions | undefined, depth: number): string;
+}
+/**
+ * CBOR tag(52/54, …) IP address whose toEDN() emits IP'…' notation.
+ * Content may be a byte string (plain address) or an array [prefix, bytes]
+ * (CIDR prefix per RFC 9164).
+ */
+export declare class CborTaggedIpExt extends CborTag {
+    constructor(tag: bigint, content: CborItem);
+    _toEDN(options: ToEDNOptions | undefined, depth: number): string;
+}
+/**
+ * Create an ip/IP CborExtension (RFC 9164 / §3.3 draft-ietf-cbor-edn-literals-20).
+ *
+ * - `ip'addr'`          → CborIpExt (bare byte string, 4 or 16 bytes)
+ * - `IP'addr'`          → CborTaggedIpExt  tag(52 or 54, bytes)
+ * - `IP'addr/prefix'`   → CborTaggedIpExt  tag(52 or 54, [prefix_len, bytes])
+ * - parseTag(52/54, …)  → CborTaggedIpExt  (reversible via fromCBOR)
+ * - fromJS(tagged obj)  → CborTaggedIpExt  (reversible via fromJS)
+ */
+export declare const ip: CborExtension;
+export default ip;

package/dist/extensions/types.d.ts

@@ -0,0 +1,70 @@
+import { CborItem } from '../ast/CborItem';
+import { FromJSOptions } from '../types';
+/**
+ * Plugin that extends EDN parsing, CBOR decoding, and `fromJS()` for specific
+ * application-string prefixes or CBOR tag numbers.
+ *
+ * Pass instances via `FromEDNOptions.extensions`, `FromCBOROptions.extensions`,
+ * or `FromJSOptions.extensions`.
+ *
+ * @example
+ * // Custom "ip" extension: ip'192.0.2.1' → CborByteString of 4 bytes
+ * const ipExtension: CborExtension = {
+ *   appStringPrefixes: ['ip'],
+ *   parseAppString(_prefix, content) {
+ *     return new CborByteString(parseIPv4(content));
+ *   },
+ * };
+ * parseEDN("ip'192.0.2.1'", { extensions: [ipExtension] });
+ */
+export interface CborExtension {
+    /**
+     * App-string prefixes this extension handles (e.g. `['dt', 'DT']`).
+     * The tokenizer recognises these as `APP_STRING` / `APP_SEQUENCE` tokens.
+     */
+    readonly appStringPrefixes?: readonly string[];
+    /**
+     * CBOR tag numbers this extension handles (e.g. `[0n, 1n]`).
+     * Extensions with `parseTag()` are invoked for these tag numbers during
+     * `fromCBOR()` and integer-tagged EDN items (`1(…)`) in `fromEDN()`.
+     */
+    readonly tagNumbers?: readonly bigint[];
+    /**
+     * Parse an app-string literal: `prefix'content'` or `prefix"content"`.
+     * Receives the matched `prefix` and the decoded string `content`.
+     * Throw `SyntaxError` to report invalid content.
+     */
+    parseAppString?(prefix: string, content: string): CborItem;
+    /**
+     * Parse an app-sequence literal: `prefix<<item, ...>>`.
+     * Receives the matched `prefix` and the array of parsed CBOR values.
+     * If omitted, the `<<...>>` form is rejected with a `SyntaxError`.
+     */
+    parseAppSequence?(prefix: string, items: CborItem[]): CborItem;
+    /**
+     * Called when a `CborTag` is encountered during CBOR decode (`fromCBOR`)
+     * or EDN integer-tag parsing (`fromEDN`).
+     * Return `undefined` to fall back to the default `CborTag` representation.
+     */
+    parseTag?(tag: bigint, value: CborItem): CborItem | undefined;
+    /**
+     * Called during `fromJS()` for every value before the default conversion
+     * logic.  Return `undefined` to fall through to the default behaviour.
+     * Typical uses: intercept `Date` instances, or CBOR-tagged plain objects
+     * that carry a `Symbol.for('cbor.tag')` key for a registered tag number.
+     */
+    fromJS?(value: unknown, options: FromJSOptions): CborItem | undefined;
+    /**
+     * Returns `true` if the given JS value is of a type that this extension's
+     * `fromJS()` converts.  When `true`, the replacer pipeline passes the value
+     * through as-is instead of decomposing it with `Object.keys()` traversal.
+     *
+     * Implement this alongside `fromJS` for any class instance type (e.g.
+     * `Date`) that must survive the replacer pipeline intact so that `fromJS`
+     * can convert it correctly.
+     *
+     * Implementations may narrow the return type to a type predicate
+     * (e.g. `value is Date`) for better static type inference at the call site.
+     */
+    isJSType?(value: unknown): boolean;
+}