@cbortech/cbor 0.23.0

package/dist/index.d.ts

@@ -0,0 +1,695 @@
+/* Excluded from this release type: AnnotatedLine */
+
+/**
+ * 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);
+ */
+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;
+}
+export { CBOR }
+export default CBOR;
+
+/**
+ * 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 declare const CBOR_TAG: unique symbol;
+
+declare interface CborComment {
+    kind: 'line' | 'block';
+    marker: '#' | '//' | '/*' | '/';
+    text: string;
+    start: number;
+    end: number;
+    line: number;
+    col: number;
+}
+
+declare interface CborComments {
+    leading?: CborComment[];
+    trailing?: CborComment[];
+    dangling?: CborComment[];
+}
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * Abstract base class for all CBOR AST nodes.
+ *
+ * Every node can serialize itself to CBOR binary, CBOR-EDN text, and a
+ * plain JavaScript value.  Concrete implementations are provided in each
+ * subclass (added in later phases).
+ */
+export declare abstract class CborItem {
+    /**
+     * Character offset of the first character of this item in the parsed source.
+     * Set by parsers; undefined when the node was constructed directly.
+     * For CBOR input this is a byte offset.
+     */
+    start?: number;
+    /**
+     * Character offset just past the last character of this item in the parsed source.
+     * Set by parsers; undefined when the node was constructed directly.
+     * For CBOR input this is a byte offset.
+     */
+    end?: number;
+    /**
+     * Comments captured from CBOR-EDN source when `preserveComments` is enabled.
+     * They do not affect CBOR bytes or JS conversion.
+     */
+    comments?: CborComments;
+    /* Excluded from this release type: _defaults */
+    /** Serialize this node to CBOR binary. */
+    toCBOR(options?: ToCBOROptions): Uint8Array;
+    /** Serialize this node to a CBOR-EDN text string. */
+    toEDN(options?: ToEDNOptions): string;
+    /**
+     * Convert this CBOR AST node to a plain JavaScript value.
+     *
+     * If `options.reviver` is supplied it is called with key `''` on the root
+     * result after the full tree has been converted (matching the semantics of
+     * `JSON.parse`).  Container nodes call the reviver on each of their direct
+     * children during conversion, so the walk is bottom-up.
+     */
+    toJS(options?: ToJSOptions): unknown;
+    /**
+     * Generate an RFC 8949 §3 style annotated hex dump of this value.
+     *
+     * @example
+     * const cbor = CBOR.fromEDN('[_ 1, [2, 3]]');
+     * console.log(cbor.toHexDump());
+     * // 9F        -- Start indefinite-length array
+     * //    01     -- 1
+     * //    82     -- Array of length 2
+     * //       02  -- 2
+     * //       03  -- 3
+     * //    FF     -- "break"
+     * // FF        -- "break"
+     */
+    toHexDump(options?: ToHexDumpOptions): string;
+    /* Excluded from this release type: _toCBOR */
+    /* Excluded from this release type: _toEDN */
+    /* Excluded from this release type: _toJS */
+    /* Excluded from this release type: _toHexDump */
+}
+
+/**
+ * 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 declare type CBOROptions = FromEDNOptions & FromJSOptions & ToCBOROptions & ToEDNOptions & ToJSOptions & ToHexDumpOptions;
+
+/**
+ * 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 declare 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[];
+}
+
+export declare 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;
+}
+
+/**
+ * Options for parsing an annotated hex dump.
+ */
+export declare 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 declare 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 declare class MapEntries extends Array<[unknown, unknown]> {
+    toJSON(): Record<string, unknown>;
+}
+
+export declare class Null {
+    valueOf(): null;
+    toJSON(): null;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+export declare interface ToCBOROptions {
+}
+
+export declare 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 declare 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 declare 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 declare class Undefined {
+    valueOf(): undefined;
+    toJSON(): undefined;
+}
+
+export { }