@cbortech/cbor 0.25.0 → 0.25.2

package/README.ja.md

@@ -326,37 +326,117 @@ console.log(text);
 
 ## オプション extension
 
+このパッケージには、デフォルト有効ではないものの本体に同梱されている
+extension があります。必要なものを `import` し、
+`extensions` オプションに渡して使います。
+
+### b32 / h32
+
+[RFC 4648](https://www.rfc-editor.org/rfc/rfc4648) の Base32 エンコードによるバイト列リテラルです。
+[RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) §8 に記載があり、[draft-ietf-cbor-edn-literals](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/) でも触れられています。
+
+- `b32` — §6 Base32（`A–Z 2–7` アルファベット）
+- `h32` — §7 Base32Hex（`0–9 A–V` アルファベット）
+
+```ts
+import { CBOR, b32, h32 } from '@cbortech/cbor';
+
+const v1 = CBOR.fromCDN("b32'AEBAGBA'", { extensions: [b32] });
+console.log(v1.toCDN({ appStrings: false }));
+// h'01020304'
+
+const v2 = CBOR.fromCDN("h32'00P00'", { extensions: [h32] });
+console.log(v2.toCDN({ appStrings: false }));
+// h'003200'
+```
+
+### float
+
+16 進数のビットパターンを IEEE 754 浮動小数点値として解釈します。
+[draft-bormann-cbor-edn-app-ext](https://datatracker.ietf.org/doc/draft-bormann-cbor-edn-app-ext/)
+に記載があり、[cbor-test-vectors](https://github.com/cbor-wg/cbor-test-vectors) でも使われています。
+
+```ts
+import { CBOR, float } from '@cbortech/cbor';
+
+const v = CBOR.fromCDN("float'7e00'", { extensions: [float] });
+console.log(v.toCDN({ appStrings: false }));
+// NaN
+
+// バイト列から解釈する場合
+const v2 = CBOR.fromCDN("float<<h'3f800000'>>", { extensions: [float] });
+console.log(v2.toCDN({ appStrings: false }));
+// 1.0_2
+```
+
+### same
+
+`same<<expr, expr, ...>>` は、シーケンス内のすべての要素が同一の CBOR
+バイト列になることを検証し、最初の要素を返す extension です。
+[draft-bormann-cbor-edn-app-ext](https://datatracker.ietf.org/doc/draft-bormann-cbor-edn-app-ext/)
+に記載があります。
+
+```ts
+import { CBOR, same } from '@cbortech/cbor';
+
+// すべての要素が同じバイト列かを検証し、最初の要素を返す
+const v = CBOR.fromCDN("same<<h'0102', h'0102'>>", { extensions: [same] });
+console.log(v.toCDN({ appStrings: false }));
+// h'0102'
+
+// 要素が 1 つでも有効（常にパスする）
+const v2 = CBOR.fromCDN('same<<42>>', { extensions: [same] });
+console.log(v2.toCDN({ appStrings: false }));
+// 42
+```
+
+---
+
 追加の application extension は別パッケージとして公開されています。必要なものを
 インストールし、`extensions` オプションに渡して使います。
 
-`hash` は CDN の仕様に含まれる application extension ですが、利用には
-外部パッケージが必要です。そのため、このパッケージ本体には含めず、
-`@cbortech/hash-extension` として提供しています。
+### hash
 
-`uuid` は CDN の仕様には定められていない、このライブラリ独自の
-application extension です。仕様上の標準機能と区別するため、
-`@cbortech/uuid-extension` として別パッケージで提供しています。
+`hash` は [draft-ietf-cbor-edn-literals](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/) §3.3 で定義された標準の application extension です。
+ハッシュアルゴリズムと値を `hash'algorithm:value'` の形式で表現します。
+実装には外部の暗号ライブラリが必要なため、[@cbortech/hash-extension](https://www.npmjs.com/package/@cbortech/hash-extension) として
+別パッケージで提供しています。
 
 ```bash
-npm install @cbortech/hash-extension @cbortech/uuid-extension
+npm install @cbortech/hash-extension
 ```
 
 ```ts
 import { CBOR } from '@cbortech/cbor';
-import hashExtension from '@cbortech/hash-extension';
-import uuidExtension from '@cbortech/uuid-extension';
+import { hash } from '@cbortech/hash-extension';
 
-const cbor = new CBOR({
-  extensions: [hashExtension, uuidExtension],
-});
+const cbor = new CBOR({ extensions: [hash] });
+
+const digest = cbor.parse(
+  "hash'sha-256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='"
+);
+// Uint8Array(32) [227, 176, 196, 66, 152, 252, 28, 20, 154, 251, 244, 200,
+//                 153, 111, 185, 36, 39, 174, 65, 228, 100, 155, 147, 76,
+//                 164, 149, 153, 27, 120, 82, 184, 85]
+```
+
+### uuid
+
+`uuid` はこのライブラリ独自の application extension です。
+[@cbortech/uuid-extension](https://www.npmjs.com/package/@cbortech/uuid-extension) として別パッケージで提供しています。
+
+```bash
+npm install @cbortech/uuid-extension
+```
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+import { uuid } from '@cbortech/uuid-extension';
 
-const digest = cbor.fromCDN("hash'foo'");
-console.log(digest.toCDN());
-// hash'foo'
+const cbor = new CBOR({ extensions: [uuid] });
 
-const id = cbor.fromCDN("uuid'550e8400-e29b-41d4-a716-446655440000'");
-console.log(id.toCDN());
-// uuid'550e8400-e29b-41d4-a716-446655440000'
+const id = cbor.parse("uuid'550e8400-e29b-41d4-a716-446655440000'");
+// Uint8Array(16) [85, 14, 132, 0, 226, 155, 65, 212, 167, 22, 68, 102, 85, 68, 0, 0]
 ```
 
 ## タグ

package/README.md

@@ -330,37 +330,118 @@ console.log(text);
 
 ## Optional Extensions
 
+This package includes several bundled extensions that are not enabled by
+default. Import what you need and pass it through the `extensions` option.
+
+### b32 / h32
+
+Byte-string literals using [RFC 4648](https://www.rfc-editor.org/rfc/rfc4648)
+Base32 encoding. These prefixes are described in §8 of
+[RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) and also mentioned in
+[draft-ietf-cbor-edn-literals](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/).
+
+- `b32` — §6 Base32 (`A–Z 2–7` alphabet)
+- `h32` — §7 Base32Hex (`0–9 A–V` alphabet)
+
+```ts
+import { CBOR, b32, h32 } from '@cbortech/cbor';
+
+const v1 = CBOR.fromCDN("b32'AEBAGBA'", { extensions: [b32] });
+console.log(v1.toCDN({ appStrings: false }));
+// h'01020304'
+
+const v2 = CBOR.fromCDN("h32'00P00'", { extensions: [h32] });
+console.log(v2.toCDN({ appStrings: false }));
+// h'003200'
+```
+
+### float
+
+Interprets a hex bit-pattern as an IEEE 754 floating-point value. This
+extension is described in
+[draft-bormann-cbor-edn-app-ext](https://datatracker.ietf.org/doc/draft-bormann-cbor-edn-app-ext/)
+and also used in [cbor-test-vectors](https://github.com/cbor-wg/cbor-test-vectors).
+
+```ts
+import { CBOR, float } from '@cbortech/cbor';
+
+const v = CBOR.fromCDN("float'7e00'", { extensions: [float] });
+console.log(v.toCDN({ appStrings: false }));
+// NaN
+
+// Interpret bytes as float bits
+const v2 = CBOR.fromCDN("float<<h'3f800000'>>", { extensions: [float] });
+console.log(v2.toCDN({ appStrings: false }));
+// 1.0_2
+```
+
+### same
+
+`same<<expr, expr, ...>>` verifies that every item in the sequence encodes to
+identical CBOR bytes and returns the first item. This extension is described in
+[draft-bormann-cbor-edn-app-ext](https://datatracker.ietf.org/doc/draft-bormann-cbor-edn-app-ext/).
+
+```ts
+import { CBOR, same } from '@cbortech/cbor';
+
+const v = CBOR.fromCDN("same<<h'0102', h'0102'>>", { extensions: [same] });
+console.log(v.toCDN({ appStrings: false }));
+// h'0102'
+
+// A single-item sequence always passes
+const v2 = CBOR.fromCDN('same<<42>>', { extensions: [same] });
+console.log(v2.toCDN({ appStrings: false }));
+// 42
+```
+
+---
+
 Additional application extensions are published as separate packages. Install
 the ones you need and pass them through the `extensions` option.
 
-`hash` is an application extension defined by the CDN specification, but
-it requires an external package. For that reason, it is not bundled with this
-package and is provided separately as `@cbortech/hash-extension`.
+### hash
 
-`uuid` is a library-specific application extension that is not defined by the
-CDN specification. To keep it distinct from standard CDN features, it
-is provided separately as `@cbortech/uuid-extension`.
+`hash` is an application extension defined in §3.3 of
+[draft-ietf-cbor-edn-literals](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/).
+It represents cryptographic hash values in the form `hash'algorithm:value'`.
+Because it requires an external cryptographic library, it is provided separately
+as [@cbortech/hash-extension](https://www.npmjs.com/package/@cbortech/hash-extension).
 
 ```bash
-npm install @cbortech/hash-extension @cbortech/uuid-extension
+npm install @cbortech/hash-extension
 ```
 
 ```ts
 import { CBOR } from '@cbortech/cbor';
-import hashExtension from '@cbortech/hash-extension';
-import uuidExtension from '@cbortech/uuid-extension';
+import { hash } from '@cbortech/hash-extension';
 
-const cbor = new CBOR({
-  extensions: [hashExtension, uuidExtension],
-});
+const cbor = new CBOR({ extensions: [hash] });
+
+const digest = cbor.parse(
+  "hash'sha-256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='"
+);
+// Uint8Array(32) [227, 176, 196, 66, 152, 252, 28, 20, 154, 251, 244, 200,
+//                 153, 111, 185, 36, 39, 174, 65, 228, 100, 155, 147, 76,
+//                 164, 149, 153, 27, 120, 82, 184, 85]
+```
+
+### uuid
+
+`uuid` is a library-specific application extension, provided separately as
+[@cbortech/uuid-extension](https://www.npmjs.com/package/@cbortech/uuid-extension).
+
+```bash
+npm install @cbortech/uuid-extension
+```
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+import { uuid } from '@cbortech/uuid-extension';
 
-const digest = cbor.fromCDN("hash'foo'");
-console.log(digest.toCDN());
-// hash'foo'
+const cbor = new CBOR({ extensions: [uuid] });
 
-const id = cbor.fromCDN("uuid'550e8400-e29b-41d4-a716-446655440000'");
-console.log(id.toCDN());
-// uuid'550e8400-e29b-41d4-a716-446655440000'
+const id = cbor.parse("uuid'550e8400-e29b-41d4-a716-446655440000'");
+// Uint8Array(16) [85, 14, 132, 0, 226, 155, 65, 212, 167, 22, 68, 102, 85, 68, 0, 0]
 ```
 
 ## Tags

package/dist/ast/CborAppSeqResult.d.ts

@@ -0,0 +1,21 @@
+import { ToCDNOptions, ToCBOROptions, ToJSOptions } from '../types';
+import { CborItem } from './CborItem';
+import { CborWriter } from '../cbor/encode';
+/**
+ * Wraps a resolved app-sequence result and preserves the original EDN source
+ * text for round-trip fidelity.
+ *
+ * When `appStrings !== false`, `_toCDN` returns the stored source text verbatim.
+ * Otherwise it delegates to the wrapped item so the caller gets a plain value.
+ *
+ * CBOR encoding and JS conversion always delegate to the inner item so the
+ * wrapper is fully transparent for those operations.
+ */
+export declare class CborAppSeqResult extends CborItem {
+    readonly inner: CborItem;
+    readonly ednSource: string;
+    constructor(inner: CborItem, ednSource: string);
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
+    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toJS(options?: ToJSOptions): unknown;
+}

package/dist/ast/CborArray.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem, AnnotatedLine } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 4 — array (definite- or indefinite-length). */
 export declare class CborArray extends CborItem {
     readonly items: CborItem[];
@@ -10,7 +10,7 @@ export declare class CborArray extends CborItem {
         indefiniteLength?: boolean;
         encodingWidth?: EncodingWidth;
     });
-    _toCBOR(options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(options?: ToJSOptions): unknown;

package/dist/ast/CborByteString.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 2 — definite-length byte string. */
 export declare class CborByteString extends CborItem {
     readonly indefiniteLength: false;
@@ -14,7 +14,7 @@ export declare class CborByteString extends CborItem {
         encodingWidth?: EncodingWidth;
         ednSource?: string;
     });
-    _toCBOR(_options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborEmbeddedCBOR.d.ts

@@ -1,5 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem, AnnotatedLine } from './CborItem';
+import { CborWriter } from '../cbor/encode';
 /**
  * CBOR Sequence Literal (§2.5.6) — `<<item, item, ...>>`.
  *
@@ -15,7 +16,7 @@ export declare class CborEmbeddedCBOR extends CborItem {
     constructor(items: CborItem[]);
     /** The raw concatenated CBOR bytes of all contained items. */
     private _content;
-    _toCBOR(options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;

package/dist/ast/CborFloat.d.ts

@@ -1,5 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
+import { CborWriter } from '../cbor/encode';
 export type FloatPrecision = 'half' | 'single' | 'double';
 /**
  * CBOR Major Type 7 — IEEE 754 floating-point number.
@@ -18,10 +19,16 @@ export declare class CborFloat extends CborItem {
      * - `undefined`: encoder auto-selects the smallest lossless size.
      */
     readonly precision: FloatPrecision | undefined;
+    /**
+     * Original app-string source (e.g. `float'7e00'`), set by the parser when
+     * this float is the result of a `float'...'` app-string.  Used by toCDN()
+     * to round-trip the literal when `appStrings` is not false.
+     */
+    ednSource?: string;
     constructor(value: number, options?: {
         precision?: FloatPrecision;
     });
-    _toCBOR(_options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborIndefiniteByteString.d.ts

@@ -1,12 +1,13 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem, AnnotatedLine } from './CborItem';
 import { CborByteString } from './CborByteString';
+import { CborWriter } from '../cbor/encode';
 /** CBOR Major Type 2 — indefinite-length byte string (chunked). */
 export declare class CborIndefiniteByteString extends CborItem {
     readonly indefiniteLength: true;
     readonly chunks: CborByteString[];
     constructor(chunks: CborByteString[]);
-    _toCBOR(options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;

package/dist/ast/CborIndefiniteTextString.d.ts

@@ -1,12 +1,13 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem, AnnotatedLine } from './CborItem';
 import { CborTextString } from './CborTextString';
+import { CborWriter } from '../cbor/encode';
 /** CBOR Major Type 3 — indefinite-length UTF-8 text string (chunked). */
 export declare class CborIndefiniteTextString extends CborItem {
     readonly indefiniteLength: true;
     readonly chunks: CborTextString[];
     constructor(chunks: CborTextString[]);
-    _toCBOR(options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;

package/dist/ast/CborItem.d.ts

@@ -1,4 +1,5 @@
-import { CBOROptions, ToCDNOptions, ToJSOptions, ToHexDumpOptions, ToCBOROptions, CborComments } from '../types';
+import { CBOROptions, ToCDNOptions, ToJSOptions, ToHexDumpOptions, ToCBOROptions, CborComments, DecodeWarning, ParseWarning } from '../types';
+import { CborWriter } from '../cbor/encode';
 /** @internal One line of an annotated hex dump. */
 export interface AnnotatedLine {
     depth: number;
@@ -30,6 +31,12 @@ export declare abstract class CborItem {
      * They do not affect CBOR bytes or JS conversion.
      */
     comments?: CborComments;
+    /**
+     * Validity violations detected while decoding or parsing this node.
+     * Populated when `strict: false` is set in `FromCBOROptions` or
+     * `FromCDNOptions`.
+     */
+    warnings?: (DecodeWarning | ParseWarning)[];
     /**
      * Default options bound by a {@link CBOR} instance factory method.
      * Per-call options always take precedence.
@@ -70,8 +77,34 @@ export declare abstract class CborItem {
      * // FF        -- "break"
      */
     toHexDump(options?: ToHexDumpOptions): string;
-    /** @internal Subclass CBOR encoding implementation. */
-    abstract _toCBOR(options?: ToCBOROptions): Uint8Array;
+    /**
+     * @internal
+     * Encode this node into `writer`, honoring `_toCBOR()` overrides.
+     *
+     * This is the entry point used by `toCBOR()` and by container nodes when
+     * recursing into children.  A subclass that overrides `_toCBOR()` (e.g. to
+     * emit a pre-computed bit pattern) is authoritative even when one of its
+     * built-in base classes implements `_encodeTo()`.
+     */
+    _encode(writer: CborWriter, options?: ToCBOROptions): void;
+    /**
+     * @internal
+     * Write this node's CBOR encoding into `writer`.
+     *
+     * Built-in nodes override this so that an entire encode pass shares one
+     * growing buffer (no per-node Uint8Array allocations or re-copies).
+     * Container implementations must recurse via `child._encode()`, never
+     * `child._encodeTo()`, so that `_toCBOR()` overrides are honored.
+     */
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
+    /**
+     * @internal
+     * Subclass CBOR encoding implementation.
+     * The default builds the bytes via `_encodeTo()`; subclasses may instead
+     * override this method directly when producing a standalone byte array is
+     * more natural (e.g. emitting a pre-computed bit pattern).
+     */
+    _toCBOR(options?: ToCBOROptions): Uint8Array;
     /**
      * @internal
      * Depth-aware CDN serialization.

package/dist/ast/CborMap.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem, AnnotatedLine } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 5 — map (definite- or indefinite-length). */
 export declare class CborMap extends CborItem {
     readonly entries: [CborItem, CborItem][];
@@ -10,7 +10,7 @@ export declare class CborMap extends CborItem {
         indefiniteLength?: boolean;
         encodingWidth?: EncodingWidth;
     });
-    _toCBOR(options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(options?: ToJSOptions): unknown;

package/dist/ast/CborNint.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /**
  * CBOR Major Type 1 — negative integer (−2^64 … −1).
  *
@@ -21,7 +21,7 @@ export declare class CborNint extends CborItem {
     });
     /** The actual decoded negative value (−1 − argument). */
     get value(): bigint;
-    _toCBOR(_options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toJS(options?: ToJSOptions): unknown;
 }

package/dist/ast/CborSimple.d.ts

@@ -1,5 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
+import { CborWriter } from '../cbor/encode';
 /**
  * CBOR Major Type 7 — simple value (0–255).
  *
@@ -16,7 +17,7 @@ export declare class CborSimple extends CborItem {
     static readonly TRUE: CborSimple;
     static readonly NULL: CborSimple;
     static readonly UNDEFINED: CborSimple;
-    _toCBOR(_options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(_options: ToCDNOptions | undefined, _depth: number): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborTag.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem, AnnotatedLine } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 6 — tagged data item. */
 export declare class CborTag extends CborItem {
     readonly tag: bigint;
@@ -9,7 +9,7 @@ export declare class CborTag extends CborItem {
     constructor(tag: number | bigint, content: CborItem, options?: {
         encodingWidth?: EncodingWidth;
     });
-    _toCBOR(options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(options?: ToJSOptions): unknown;

package/dist/ast/CborTextString.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 3 — definite-length UTF-8 text string. */
 export declare class CborTextString extends CborItem {
     readonly indefiniteLength: false;
@@ -9,7 +9,7 @@ export declare class CborTextString extends CborItem {
     constructor(value: string, options?: {
         encodingWidth?: EncodingWidth;
     });
-    _toCBOR(_options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborUint.d.ts

@@ -1,6 +1,6 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
-import { EncodingWidth } from '../cbor/encode';
+import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 0 — unsigned integer (0 … 2^64−1). */
 export declare class CborUint extends CborItem {
     readonly value: bigint;
@@ -8,7 +8,7 @@ export declare class CborUint extends CborItem {
     constructor(value: number | bigint, options?: {
         encodingWidth?: EncodingWidth;
     });
-    _toCBOR(_options?: ToCBOROptions): Uint8Array;
+    _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toJS(options?: ToJSOptions): unknown;
 }

package/dist/ast/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../mapEntries-CNxwMt7o.cjs`);exports.CborArray=e.p,exports.CborBigNint=e.c,exports.CborBigUint=e.l,exports.CborByteString=e.g,exports.CborEmbeddedCBOR=e.u,exports.CborFloat=e.v,exports.CborIndefiniteByteString=e.h,exports.CborIndefiniteTextString=e.m,exports.CborItem=e.x,exports.CborMap=e.f,exports.CborNint=e.y,exports.CborSimple=e.d,exports.CborTag=e._,exports.CborTextString=e.o,exports.CborUint=e.b;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-DZKHc3VY.cjs");exports.CborArray=e.p,exports.CborBigNint=e.c,exports.CborBigUint=e.l,exports.CborByteString=e.g,exports.CborEmbeddedCBOR=e.u,exports.CborFloat=e.v,exports.CborIndefiniteByteString=e.h,exports.CborIndefiniteTextString=e.m,exports.CborItem=e.x,exports.CborMap=e.f,exports.CborNint=e.y,exports.CborSimple=e.d,exports.CborTag=e._,exports.CborTextString=e.o,exports.CborUint=e.b;

package/dist/ast/index.js

@@ -1,2 +1,2 @@
-import { _ as e, b as t, c as n, d as r, f as i, g as a, h as o, l as s, m as c, o as l, p as u, u as d, v as f, x as p, y as m } from "../mapEntries-Da-2HMRf.js";
+import { _ as e, b as t, c as n, d as r, f as i, g as a, h as o, l as s, m as c, o as l, p as u, u as d, v as f, x as p, y as m } from "../mapEntries-BMMPg2FB.js";
 export { u as CborArray, n as CborBigNint, s as CborBigUint, a as CborByteString, d as CborEmbeddedCBOR, f as CborFloat, o as CborIndefiniteByteString, c as CborIndefiniteTextString, p as CborItem, i as CborMap, m as CborNint, r as CborSimple, e as CborTag, l as CborTextString, t as CborUint };

package/dist/cbor/encode.d.ts

@@ -9,15 +9,49 @@ import { FloatPrecision } from '../ast/CborFloat';
  */
 export type EncodingWidth = 'i' | 0 | 1 | 2 | 3;
 /**
- * Encode a CBOR initial byte + argument into a Uint8Array.
+ * Growable byte buffer used by the CBOR encoder.
+ *
+ * AST nodes write themselves into a single shared writer via `_encodeTo`,
+ * so an encode pass performs one buffer copy at the end instead of
+ * re-copying every child's bytes at each nesting level.
+ *
+ * @internal
+ */
+export declare class CborWriter {
+    private buf;
+    private len;
+    constructor(initialCapacity?: number);
+    private _ensure;
+    writeByte(b: number): void;
+    writeBytes(bytes: Uint8Array): void;
+    writeUint16(value: number): void;
+    writeUint32(value: number): void;
+    writeBigUint64(value: bigint): void;
+    writeFloat16(value: number): void;
+    writeFloat32(value: number): void;
+    writeFloat64(value: number): void;
+    /** Copy of the bytes written so far. */
+    finish(): Uint8Array;
+}
+/** Maximum CBOR argument value representable with the given encoding width. */
+export declare function maxForEncodingWidth(ew: EncodingWidth): bigint;
+/**
+ * Write a CBOR initial byte + argument into `w`.
  *
  * When `encodingWidth` is provided the argument is always written using that
  * many additional bytes (AI = 24 + encodingWidth), even if the value would fit
  * in fewer bytes.  Without it the smallest valid encoding is chosen.
+ *
+ * `value` may be a number (common for lengths and counts — avoids a BigInt
+ * allocation per head) or a bigint (required for full uint64 range).
+ */
+export declare function writeHeadTo(w: CborWriter, mt: number, value: number | bigint, encodingWidth?: EncodingWidth): void;
+/**
+ * Encode a CBOR initial byte + argument into a Uint8Array.
+ * Convenience wrapper around {@link writeHeadTo} for callers that need the
+ * bytes directly (e.g. hex dumps).
  */
-export declare function writeHead(mt: number, value: bigint, encodingWidth?: EncodingWidth): Uint8Array;
-/** Concatenate multiple Uint8Arrays into one. */
-export declare function concat(parts: Uint8Array[]): Uint8Array;
+export declare function writeHead(mt: number, value: number | bigint, encodingWidth?: EncodingWidth): Uint8Array;
 /**
  * Returns true if `value` can be exactly represented as a float16 without
  * precision loss (including -0, Infinity, -Infinity, NaN identity).