@bcts/dcbor 1.0.0-alpha.8 → 1.0.0-beta.0

package/src/diag.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Enhanced diagnostic formatting for CBOR values.
  *
  * Provides multiple formatting options including
@@ -16,6 +20,7 @@ import type { CborMap } from "./map";
 import { getGlobalTagsStore, type TagsStore } from "./tags-store";
 import type { Tag } from "./tag";
 import type { WalkElement } from "./walk";
+import { flanked } from "./string-util";
 
 /**
  * Options for diagnostic formatting.
@@ -47,9 +52,14 @@ export interface DiagFormatOpts {
 
   /**
    * Tag store to use for tag name resolution.
-   * - TagsStore instance: Use specific store
-   * - 'global': Use global singleton store
-   * - 'none': Don't use any store (show tag numbers)
+   *
+   * Mirrors Rust's `TagsStoreOpt<'a>` enum (`Custom(&'a dyn TagsStoreTrait)`,
+   * `Global`, `None`). The TS port models the same three-way choice as a
+   * string-literal union — semantically equivalent, just stringly-typed.
+   *
+   * - `TagsStore` instance: use this specific store (Rust `Custom`)
+   * - `'global'`: use global singleton store (Rust `Global`)
+   * - `'none'`: don't resolve names; print bare tag numbers (Rust `None`)
    *
    * @default 'global'
    */
@@ -100,7 +110,9 @@ const DEFAULT_OPTS = {
  */
 export function diagnosticOpt(cbor: Cbor, opts?: DiagFormatOpts): string {
   const options = { ...DEFAULT_OPTS, ...opts };
-  return formatDiagnostic(cbor, options);
+  // `summarize` implies `flat` per Rust `DiagFormatOpts::summarize`.
+  if (options.summarize === true) options.flat = true;
+  return diagFormat(diagItem(cbor, options), options);
 }
 
 /**
@@ -167,15 +179,14 @@ export function diagnosticFlat(input: Cbor | WalkElement): string {
     "type" in input &&
     (input.type === "single" || input.type === "keyvalue")
   ) {
-    const element = input as WalkElement;
-    if (element.type === "single") {
-      return diagnosticOpt(element.cbor, { flat: true });
+    if (input.type === "single") {
+      return diagnosticOpt(input.cbor, { flat: true });
     } else {
-      return `${diagnosticOpt(element.key, { flat: true })}: ${diagnosticOpt(element.value, { flat: true })}`;
+      return `${diagnosticOpt(input.key, { flat: true })}: ${diagnosticOpt(input.value, { flat: true })}`;
     }
   }
   // Otherwise treat as Cbor
-  return diagnosticOpt(input as Cbor, { flat: true });
+  return diagnosticOpt(input, { flat: true });
 }
 
 /**
@@ -199,195 +210,218 @@ export function summary(cbor: Cbor): string {
   return diagnosticOpt(cbor, { summarize: true, flat: true });
 }
 
-/**
- * Internal recursive formatter.
- *
- * @internal
- */
-function formatDiagnostic(cbor: Cbor, opts: DiagFormatOpts): string {
-  switch (cbor.type) {
-    case MajorType.Unsigned:
-      return formatUnsigned(cbor.value);
+// =====================================================================
+// DiagItem AST
+//
+// Mirrors Rust `DiagItem` enum in `bc-dcbor-rust/src/diag.rs`. Building an
+// AST first lets the formatter use Rust-identical multi-line heuristics
+// (`contains_group || total_strings_len > 20 || greatest_strings_len > 20`)
+// rather than ad-hoc thresholds applied at recursion time.
+// =====================================================================
 
-    case MajorType.Negative:
-      return formatNegative(cbor.value);
+type DiagItem = DiagItemNode | DiagItemGroup;
 
-    case MajorType.ByteString:
-      return formatBytes(cbor.value);
+interface DiagItemNode {
+  kind: "item";
+  value: string;
+}
 
-    case MajorType.Text:
-      return formatText(cbor.value);
+interface DiagItemGroup {
+  kind: "group";
+  begin: string;
+  end: string;
+  items: DiagItem[];
+  /** True for maps (`{...}`) — items alternate key, value. */
+  isPairs: boolean;
+  /** Optional comment rendered as `   / comment /` after the line. */
+  comment?: string;
+}
 
-    case MajorType.Array:
-      return formatArray(cbor.value, opts);
+const item = (value: string): DiagItemNode => ({ kind: "item", value });
 
-    case MajorType.Map:
-      return formatMap(cbor.value, opts);
+const group = (
+  begin: string,
+  end: string,
+  items: DiagItem[],
+  isPairs: boolean,
+  comment?: string,
+): DiagItemGroup => {
+  const g: DiagItemGroup = { kind: "group", begin, end, items, isPairs };
+  if (comment !== undefined) g.comment = comment;
+  return g;
+};
 
-    case MajorType.Tagged:
-      return formatTagged(cbor.tag, cbor.value, opts);
+const isGroup = (i: DiagItem): boolean => i.kind === "group";
 
-    case MajorType.Simple:
-      return formatSimple(cbor.value);
-  }
-}
+const containsGroup = (i: DiagItem): boolean => i.kind === "group" && i.items.some(isGroup);
 
-/**
- * Format unsigned integer.
- */
-function formatUnsigned(value: number | bigint): string {
-  return String(value);
-}
+const totalStringsLen = (i: DiagItem): number =>
+  i.kind === "item" ? i.value.length : i.items.reduce((acc, c) => acc + totalStringsLen(c), 0);
+
+const greatestStringsLen = (i: DiagItem): number =>
+  i.kind === "item"
+    ? i.value.length
+    : i.items.reduce((acc, c) => Math.max(acc, totalStringsLen(c)), 0);
 
 /**
- * Format negative integer.
+ * Mirrors Rust `DiagItem::joined`: alternates between `pairSeparator`
+ * (after even-indexed items — keys) and `itemSeparator` (after odd-indexed
+ * items — values). Falls back to `itemSeparator` for non-pair groups.
  */
-function formatNegative(value: number | bigint): string {
-  // Value is stored as magnitude, convert to actual negative value for display
-  if (typeof value === "bigint") {
-    return String(-value - 1n);
-  } else {
-    return String(-value - 1);
+function joined(elements: string[], itemSeparator: string, pairSeparator?: string): string {
+  const sep = pairSeparator ?? itemSeparator;
+  let result = "";
+  const len = elements.length;
+  for (let i = 0; i < len; i++) {
+    result += elements[i];
+    if (i !== len - 1) {
+      result += (i & 1) !== 0 ? itemSeparator : sep;
+    }
   }
+  return result;
 }
 
-/**
- * Format byte string.
- */
-function formatBytes(value: Uint8Array): string {
-  return `h'${bytesToHex(value)}'`;
-}
+const diagFormat = (i: DiagItem, opts: DiagFormatOpts): string => diagFormatOpt(i, 0, "", opts);
 
-/**
- * Format text string.
- */
-function formatText(value: string): string {
-  // Escape special characters
-  const escaped = value
-    .replace(/\\/g, "\\\\")
-    .replace(/"/g, '\\"')
-    .replace(/\n/g, "\\n")
-    .replace(/\r/g, "\\r")
-    .replace(/\t/g, "\\t");
-  return `"${escaped}"`;
+function diagFormatOpt(
+  i: DiagItem,
+  level: number,
+  separator: string,
+  opts: DiagFormatOpts,
+): string {
+  if (i.kind === "item") {
+    return formatLine(level, opts, i.value, separator, undefined);
+  }
+  if (
+    opts.flat !== true &&
+    (containsGroup(i) || totalStringsLen(i) > 20 || greatestStringsLen(i) > 20)
+  ) {
+    return multilineComposition(i, level, separator, opts);
+  }
+  return singleLineComposition(i, level, separator, opts);
 }
 
-/**
- * Format array.
- */
-function formatArray(items: readonly Cbor[], opts: DiagFormatOpts): string {
-  if (items.length === 0) {
-    return "[]";
+function formatLine(
+  level: number,
+  opts: DiagFormatOpts,
+  string: string,
+  separator: string,
+  comment: string | undefined,
+): string {
+  const indent = opts.flat === true ? "" : " ".repeat(level * 4);
+  const result = `${indent}${string}${separator}`;
+  if (comment !== undefined) {
+    return `${result}   / ${comment} /`;
   }
+  return result;
+}
 
-  // Format items first to check their lengths
-  const formatted = items.map((item) => formatDiagnostic(item, opts));
-
-  // Decide between single-line and multi-line based on complexity
-  const shouldUseMultiLine =
-    opts.flat !== true &&
-    (containsComplexStructure(items) ||
-      formatted.join(", ").length > 20 ||
-      formatted.some((s) => s.length > 20));
-
-  if (shouldUseMultiLine) {
-    // Multi-line formatting
-    const indent = opts.indent ?? 0;
-    const indentStr = (opts.indentString ?? "    ").repeat(indent);
-    const itemIndentStr = (opts.indentString ?? "    ").repeat(indent + 1);
-
-    const formattedWithIndent = items.map((item) => {
-      const childOpts = { ...opts, indent: indent + 1 };
-      const itemStr = formatDiagnostic(item, childOpts);
-      return `${itemIndentStr}${itemStr}`;
-    });
-
-    return `[\n${formattedWithIndent.join(",\n")}\n${indentStr}]`;
+function singleLineComposition(
+  i: DiagItem,
+  level: number,
+  separator: string,
+  opts: DiagFormatOpts,
+): string {
+  let str: string;
+  let comment: string | undefined;
+  if (i.kind === "item") {
+    str = i.value;
+    comment = undefined;
   } else {
-    // Single-line formatting
-    return `[${formatted.join(", ")}]`;
+    const components = i.items.map((c) =>
+      c.kind === "item" ? c.value : singleLineComposition(c, level + 1, separator, opts),
+    );
+    const pairSeparator = i.isPairs ? ": " : ", ";
+    str = flanked(joined(components, ", ", pairSeparator), i.begin, i.end);
+    comment = i.comment;
   }
+  return formatLine(level, opts, str, separator, comment);
 }
 
-/**
- * Check if items contain complex structures (arrays or maps).
- */
-function containsComplexStructure(items: readonly Cbor[]): boolean {
-  return items.some((item) => item.type === MajorType.Array || item.type === MajorType.Map);
+function multilineComposition(
+  i: DiagItem,
+  level: number,
+  separator: string,
+  opts: DiagFormatOpts,
+): string {
+  if (i.kind === "item") return i.value;
+  const lines: string[] = [];
+  // Opening line: print `begin` (with comment) at this level, never flat.
+  const openOpts: DiagFormatOpts = { ...opts, flat: false };
+  lines.push(formatLine(level, openOpts, i.begin, "", i.comment));
+  for (let idx = 0; idx < i.items.length; idx++) {
+    const sep = idx === i.items.length - 1 ? "" : i.isPairs && (idx & 1) === 0 ? ":" : ",";
+    lines.push(diagFormatOpt(i.items[idx], level + 1, sep, opts));
+  }
+  // Closing line: print `end` at the parent level, with the outer separator.
+  lines.push(formatLine(level, opts, i.end, separator, undefined));
+  return lines.join("\n");
 }
 
-/**
- * Format map.
- */
-function formatMap(map: CborMap, opts: DiagFormatOpts): string {
-  // Extract entries from CborMap or use empty array
-  const entries = map?.entriesArray ?? [];
+// =====================================================================
+// AST construction (`diag_item` in Rust)
+// =====================================================================
 
-  if (entries.length === 0) {
-    return "{}";
-  }
-
-  interface FormattedPair {
-    key: string;
-    value: string;
+function diagItem(cbor: Cbor, opts: DiagFormatOpts): DiagItem {
+  switch (cbor.type) {
+    case MajorType.Unsigned:
+      return item(formatUnsigned(cbor.value));
+    case MajorType.Negative:
+      return item(formatNegative(cbor.value));
+    case MajorType.ByteString:
+      return item(formatBytes(cbor.value));
+    case MajorType.Text:
+      return item(formatText(cbor.value));
+    case MajorType.Array:
+      return item_array(cbor.value, opts);
+    case MajorType.Map:
+      return item_map(cbor.value, opts);
+    case MajorType.Tagged:
+      return item_tagged(cbor.tag, cbor.value, opts);
+    case MajorType.Simple:
+      return item(formatSimple(cbor.value));
   }
+}
 
-  // Format each key-value pair
-  const formattedPairs: FormattedPair[] = entries.map((entry: { key: Cbor; value: Cbor }) => ({
-    key: formatDiagnostic(entry.key, opts),
-    value: formatDiagnostic(entry.value, opts),
-  }));
-
-  // Decide between single-line and multi-line based on complexity
-  const totalLength = formattedPairs.reduce(
-    (sum: number, pair: FormattedPair) => sum + pair.key.length + pair.value.length + 2,
-    0,
-  ); // +2 for ": "
+function item_array(items: readonly Cbor[], opts: DiagFormatOpts): DiagItem {
+  return group(
+    "[",
+    "]",
+    items.map((it) => diagItem(it, opts)),
+    false,
+  );
+}
 
-  const shouldUseMultiLine =
-    opts.flat !== true &&
-    (entries.some(
-      (e: { key: Cbor; value: Cbor }) =>
-        e.key.type === MajorType.Array ||
-        e.key.type === MajorType.Map ||
-        e.value.type === MajorType.Array ||
-        e.value.type === MajorType.Map,
-    ) ||
-      totalLength > 40 ||
-      entries.length > 3);
-
-  if (shouldUseMultiLine) {
-    // Multi-line formatting
-    const indent = opts.indent ?? 0;
-    const indentStr = (opts.indentString ?? "    ").repeat(indent);
-    const itemIndentStr = (opts.indentString ?? "    ").repeat(indent + 1);
-
-    const formattedEntries = formattedPairs.map((pair: FormattedPair) => {
-      return `${itemIndentStr}${pair.key}:\n${itemIndentStr}${pair.value}`;
-    });
-
-    return `{\n${formattedEntries.join(",\n")}\n${indentStr}}`;
-  } else {
-    // Single-line formatting
-    const pairs = formattedPairs.map((pair: FormattedPair) => `${pair.key}: ${pair.value}`);
-    return `{${pairs.join(", ")}}`;
+function item_map(map: CborMap, opts: DiagFormatOpts): DiagItem {
+  const entries = map?.entriesArray ?? [];
+  const flatItems: DiagItem[] = [];
+  for (const e of entries) {
+    flatItems.push(diagItem(e.key, opts));
+    flatItems.push(diagItem(e.value, opts));
   }
+  return group("{", "}", flatItems, true);
 }
 
-/**
- * Format tagged value.
- */
-function formatTagged(tag: number | bigint, content: Cbor, opts: DiagFormatOpts): string {
-  // Check for summarizer first
+function item_tagged(tag: number | bigint, content: Cbor, opts: DiagFormatOpts): DiagItem {
+  // Summarizer path — matches Rust's summarization branch.
   if (opts.summarize === true) {
     const store = resolveTagsStore(opts.tags);
     const summarizer = store?.summarizer(tag);
     if (summarizer !== undefined) {
-      return summarizer(content, opts.flat ?? false);
+      const result = summarizer(content, opts.flat ?? false);
+      if (result.ok) {
+        return item(result.value);
+      }
+      const errorMsg =
+        result.error.type === "Custom"
+          ? result.error.message
+          : result.error.type === "WrongTag"
+            ? `expected CBOR tag ${result.error.expected.value}, but got ${result.error.actual.value}`
+            : result.error.type;
+      return item(`<error: ${errorMsg}>`);
     }
   }
 
-  // Get tag name as comment if annotation is enabled
   let comment: string | undefined;
   if (opts.annotate === true) {
     const store = resolveTagsStore(opts.tags);
@@ -398,25 +432,34 @@ function formatTagged(tag: number | bigint, content: Cbor, opts: DiagFormatOpts)
     }
   }
 
-  // Always use tag number (not name) in the output
-  const tagStr = String(tag);
+  return group(`${String(tag)}(`, ")", [diagItem(content, opts)], false, comment);
+}
+
+// Primitive formatters reused by both single- and multi-line paths.
+function formatUnsigned(value: number | bigint): string {
+  return String(value);
+}
+
+function formatNegative(value: number | bigint): string {
+  if (typeof value === "bigint") return String(-value - 1n);
+  return String(-value - 1);
+}
 
-  // Format content
-  const contentStr = formatDiagnostic(content, opts);
+function formatBytes(value: Uint8Array): string {
+  return `h'${bytesToHex(value)}'`;
+}
 
-  // Add comment if present
-  const result = `${tagStr}(${contentStr})`;
-  if (comment !== undefined) {
-    return `${result}   / ${comment} /`;
-  }
-  return result;
+function formatText(value: string): string {
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t");
+  return `"${escaped}"`;
 }
 
-/**
- * Format simple value.
- */
 function formatSimple(value: Simple): string {
-  // Handle discriminated union
   switch (value.type) {
     case "True":
       return "true";
@@ -430,33 +473,27 @@ function formatSimple(value: Simple): string {
 }
 
 /**
- * Format float value.
+ * Format a finite CBOR float to match Rust `Simple::format!("{:?}", v)`.
+ *
+ * - `1.0` → `"1.0"` (Rust Debug). JS `String(1.0)` gives `"1"` so we append `.0`.
+ * - `1.5` → `"1.5"`.
+ * - `1e100` → `"1e100"` (Rust uses no `+` sign in the exponent). JS uses `1e+100`.
+ * - Specials (NaN / ±Infinity) produce the exact Rust strings.
  */
 function formatFloat(value: number): string {
-  if (isNaN(value)) {
-    return "NaN";
-  } else if (!isFinite(value)) {
-    return value > 0 ? "Infinity" : "-Infinity";
-  } else {
-    // Show decimal point for clarity, unless already in scientific notation
-    const str = String(value);
-    // Scientific notation (contains 'e') or already has decimal point
-    if (str.includes(".") || str.includes("e")) {
-      return str;
-    }
-    return `${str}.0`;
+  if (Number.isNaN(value)) return "NaN";
+  if (!Number.isFinite(value)) return value > 0 ? "Infinity" : "-Infinity";
+  let str = String(value);
+  // Strip the JS-only `+` in scientific exponents to match Rust Debug format.
+  str = str.replace(/e\+/, "e");
+  if (!str.includes(".") && !str.includes("e")) {
+    str = `${str}.0`;
   }
+  return str;
 }
 
-/**
- * Resolve tags store from option.
- */
 function resolveTagsStore(tags?: TagsStore | "global" | "none"): TagsStore | undefined {
-  if (tags === "none") {
-    return undefined;
-  } else if (tags === "global" || tags === undefined) {
-    return getGlobalTagsStore();
-  } else {
-    return tags;
-  }
+  if (tags === "none") return undefined;
+  if (tags === "global" || tags === undefined) return getGlobalTagsStore();
+  return tags;
 }

package/src/dump.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Hex dump utilities for CBOR data.
  *
  * Affordances for viewing the encoded binary representation of CBOR as hexadecimal.
@@ -37,6 +41,13 @@ export const bytesToHex = (bytes: Uint8Array): string => {
 
 /**
  * Convert hex string to bytes.
+ *
+ * **Whitespace tolerance.** This implementation strips ASCII whitespace
+ * before decoding so users can paste annotated hex dumps directly. Rust's
+ * `hex::decode` is strict and panics on any whitespace. This is a
+ * deliberate TS-side ergonomic divergence — callers who need strict
+ * Rust-compatible parsing should validate the input first (e.g.
+ * `if (/\s/.test(s)) throw …`).
  */
 export const hexToBytes = (hexString: string): Uint8Array => {
   const hex = hexString.replace(/\s/g, "");
@@ -223,10 +234,10 @@ function dumpItems(cbor: Cbor, level: number, opts: HexFormatOpts): DumpItem[] {
       if (tagValue === undefined) {
         throw new CborError({ type: "Custom", message: "Tagged CBOR value must have a tag" });
       }
-      const header = encodeVarInt(
-        typeof tagValue === "bigint" ? Number(tagValue) : tagValue,
-        MajorType.Tagged,
-      );
+      // Pass the tag value through directly — `encodeVarInt` accepts both
+      // `number` and `bigint`. The previous `Number(bigint)` cast was lossy
+      // for tags > MAX_SAFE_INTEGER.
+      const header = encodeVarInt(tagValue, MajorType.Tagged);
       const firstByte = header[0];
       if (firstByte === undefined) {
         throw new CborError({ type: "Custom", message: "Invalid varint encoding" });
@@ -235,9 +246,9 @@ function dumpItems(cbor: Cbor, level: number, opts: HexFormatOpts): DumpItem[] {
 
       const noteComponents: string[] = [`tag(${tagValue})`];
 
-      // Add tag name if tags store is provided
-      const numericTagValue = typeof tagValue === "bigint" ? Number(tagValue) : tagValue;
-      const tag = createTag(numericTagValue);
+      // Add tag name if tags store is provided. `createTag` accepts the
+      // raw `tagValue` (number | bigint); no `Number()` coercion needed.
+      const tag = createTag(tagValue);
       const tagName = opts.tagsStore?.assignedNameForTag(tag);
       if (tagName !== undefined) {
         noteComponents.push(tagName);

package/src/error.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Error types for CBOR encoding and decoding.
  *
  * @module error

package/src/exact.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Exact numeric conversions.
  *
  * This module is based on the Swift `exactly` initializers.

package/src/float.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Float encoding and conversion utilities for dCBOR.
  *
  * # Floating Point Number Support in dCBOR
@@ -128,9 +132,20 @@ export const f64CborData = (value: number): Uint8Array => {
 
 /**
  * Validate canonical encoding for f64.
- * Matches Rust's validate_canonical_f64 function.
  *
- * TODO: Check if this is legacy code
+ * Counterpart to Rust's `validate_canonical_f64`. **NOT used by the
+ * decoder.** JavaScript's `Number` type does not preserve NaN payload
+ * bits — every NaN collapses to a single value — which means the
+ * Rust-style `n.to_bits() != 0x7e00` distinction can't be made on a
+ * post-decoded `number`. The TS decoder uses
+ * {@link checkCanonicalEncoding} (re-encode-and-compare) instead, which
+ * handles every same-failure case including non-canonical NaNs because
+ * the canonicalising encoder always re-emits the canonical bit pattern.
+ *
+ * Kept for API parity with Rust's `pub(crate)` helper, plus as a
+ * documentation anchor; not recommended for callers.
+ *
+ * @internal
  */
 export const validateCanonicalF64 = (n: number): void => {
   const f32Bytes = numberToBinary32(n);
@@ -184,9 +199,11 @@ export const f32CborData = (value: number): Uint8Array => {
 
 /**
  * Validate canonical encoding for f32.
- * Matches Rust's validate_canonical_f32 function.
  *
- * TODO: Check if this is legacy code
+ * @see {@link validateCanonicalF64} — same caveat about JS NaN bit
+ *   preservation. The decoder relies on {@link checkCanonicalEncoding}.
+ *
+ * @internal
  */
 export const validateCanonicalF32 = (n: number): void => {
   const f16Bytes = numberToBinary16(n);
@@ -233,9 +250,11 @@ export const f16CborData = (value: number): Uint8Array => {
 
 /**
  * Validate canonical encoding for f16.
- * Matches Rust's validate_canonical_f16 function.
  *
- * TODO: Check if this is legacy code
+ * @see {@link validateCanonicalF64} — same caveat about JS NaN bit
+ *   preservation. The decoder relies on {@link checkCanonicalEncoding}.
+ *
+ * @internal
  */
 export const validateCanonicalF16 = (value: number): void => {
   const n = value;