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

package/src/global.d.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Global type declarations for cross-platform APIs
  */
 

package/src/globals.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */

package/src/index.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * BC-DCBOR TypeScript Library
  *
  * A TypeScript implementation of Blockchain Commons' Deterministic CBOR (dCBOR).
@@ -27,31 +31,52 @@ export {
 export { type Simple, simpleName, isNaN } from "./simple";
 
 // Encoding/Decoding
-export { cbor, cborData } from "./cbor";
+export { cbor, cborData, cborEquals } from "./cbor";
 export { decodeCbor } from "./decode";
 
-// Factory functions (static creators)
-export { toByteString, toByteStringFromHex, toTaggedValue } from "./cbor";
+// Factory functions (static creators).
+// `cborFalse`, `cborTrue`, `cborNull`, `cborNaN` mirror Rust
+// `CBOR::r#false()`, `CBOR::r#true()`, `CBOR::null()`, `CBOR::nan()`.
+export {
+  toByteString,
+  toByteStringFromHex,
+  toTaggedValue,
+  cborFalse,
+  cborTrue,
+  cborNull,
+  cborNaN,
+} from "./cbor";
 
 // Map and Set
 export { CborMap, type MapEntry } from "./map";
 export { CborSet } from "./set";
 
 // Tags and Tagged values
-export { type Tag, createTag } from "./tag";
+export {
+  type Tag,
+  type TagValue,
+  createTag,
+  tagWithValue,
+  tagWithStaticName,
+  tagsEqual,
+} from "./tag";
 export {
   type CborTagged,
   type CborTaggedEncodable,
   type CborTaggedDecodable,
   type CborTaggedCodable,
   createTaggedCbor,
+  taggedCborData,
   validateTag,
   extractTaggedContent,
+  fromTaggedCborData,
+  fromUntaggedCborData,
 } from "./cbor-tagged";
 export {
   TagsStore,
   type TagsStoreTrait,
   type CborSummarizer,
+  type SummarizerResult,
   getGlobalTagsStore,
 } from "./tags-store";
 export * from "./tags";
@@ -61,10 +86,17 @@ export { registerTags, registerTagsIn, tagsForValues } from "./tags";
 export { CborDate } from "./date";
 
 // Diagnostic formatting
-export { diagnosticOpt, summary, type DiagFormatOpts } from "./diag";
+export {
+  diagnostic,
+  diagnosticAnnotated,
+  diagnosticFlat,
+  diagnosticOpt,
+  summary,
+  type DiagFormatOpts,
+} from "./diag";
 
 // Hex formatting
-export { hexOpt, hexToBytes, bytesToHex, type HexFormatOpts } from "./dump";
+export { hex, hexOpt, hexAnnotated, hexToBytes, bytesToHex, type HexFormatOpts } from "./dump";
 
 // Walk/Traversal functionality
 export {
@@ -72,15 +104,10 @@ export {
   type EdgeTypeVariant,
   type WalkElement,
   type Visitor,
+  walk,
   asSingle,
   asKeyValue,
   edgeLabel,
-  // Helper functions
-  countElements,
-  collectAtLevel,
-  findFirst,
-  collectAllText,
-  maxDepth,
 } from "./walk";
 
 // Codable interfaces
@@ -92,6 +119,19 @@ export { type Error, type Result, Ok, Err, errorMsg, errorToString, CborError }
 // Note: conveniences.ts is an internal module (not exported in Rust either)
 // The main convenience functions are exported from cbor.ts above
 
+// BigNum support (CBOR tags 2/3, RFC 8949 §3.4.3)
+export {
+  biguintToCbor,
+  bigintToCbor,
+  cborToBiguint,
+  cborToBigint,
+  biguintFromUntaggedCbor,
+  bigintFromNegativeUntaggedCbor,
+} from "./bignum";
+
+// CBOR-encoding-based array sorting (Rust `array.rs::CBORSortable`).
+export { sortArrayByCborEncoding, arraySortable, setSortable, type CBORSortable } from "./sortable";
+
 // Float utilities
 export { hasFractionalPart } from "./float";
 
@@ -169,7 +209,19 @@ export {
 // Extract native JavaScript value from CBOR
 export { extractCbor } from "./conveniences";
 
-// Envelope compatibility functions
+// =============================================================================
+// Envelope compatibility helpers (TS-only, no Rust counterpart)
+//
+// These wrappers expose `dcbor` types to `@bcts/envelope`'s decode pipeline
+// in the shape it expects — mostly thin renames around the convenience
+// functions above. They have no equivalents in `bc-dcbor-rust` (Rust
+// envelope decoding goes through `TryFrom<CBOR>` directly).
+//
+// Down-stream callers wanting strict Rust parity should prefer the
+// canonical names (`asTagged` / `asBytes` / `asArray` / `asMap`,
+// `isNumber` is just a type guard). Kept here for backwards compatibility
+// with older Envelope code; do not extend.
+// =============================================================================
 export {
   asTaggedValue,
   asByteString,

package/src/map.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Map Support in dCBOR
  *
  * A deterministic CBOR map implementation that ensures maps with the same
@@ -44,14 +48,14 @@ export interface MapEntry {
  * encoded CBOR representation, ensuring deterministic encoding.
  */
 export class CborMap {
-  #dict: SortedMap<MapKey, MapEntry>;
+  private _dict: SortedMap<MapKey, MapEntry>;
 
   /**
    * Creates a new, empty CBOR Map.
    * Optionally initializes from a JavaScript Map.
    */
   constructor(map?: Map<unknown, unknown>) {
-    this.#dict = new SortedMap(null, areBytesEqual, lexicographicallyCompareBytes);
+    this._dict = new SortedMap(null, areBytesEqual, lexicographicallyCompareBytes);
 
     if (map !== undefined) {
       for (const [key, value] of map.entries()) {
@@ -76,7 +80,7 @@ export class CborMap {
     const keyCbor = cbor(key);
     const valueCbor = cbor(value);
     const keyData = cborData(keyCbor);
-    this.#dict.set(keyData, { key: keyCbor, value: valueCbor });
+    this._dict.set(keyData, { key: keyCbor, value: valueCbor });
   }
 
   /**
@@ -86,7 +90,7 @@ export class CborMap {
     this.set(key, value);
   }
 
-  #makeKey<K extends CborInput>(key: K): MapKey {
+  private _makeKey<K extends CborInput>(key: K): MapKey {
     const keyCbor = cbor(key);
     return cborData(keyCbor);
   }
@@ -97,8 +101,8 @@ export class CborMap {
    * Matches Rust's Map::get().
    */
   get<K extends CborInput, V>(key: K): V | undefined {
-    const keyData = this.#makeKey(key);
-    const value = this.#dict.get(keyData);
+    const keyData = this._makeKey(key);
+    const value = this._dict.get(keyData);
     if (value === undefined) {
       return undefined;
     }
@@ -124,24 +128,24 @@ export class CborMap {
    * Matches Rust's Map::contains_key().
    */
   containsKey<K extends CborInput>(key: K): boolean {
-    const keyData = this.#makeKey(key);
-    return this.#dict.has(keyData);
+    const keyData = this._makeKey(key);
+    return this._dict.has(keyData);
   }
 
   delete<K extends CborInput>(key: K): boolean {
-    const keyData = this.#makeKey(key);
-    const existed = this.#dict.has(keyData);
-    this.#dict.delete(keyData);
+    const keyData = this._makeKey(key);
+    const existed = this._dict.has(keyData);
+    this._dict.delete(keyData);
     return existed;
   }
 
   has<K extends CborInput>(key: K): boolean {
-    const keyData = this.#makeKey(key);
-    return this.#dict.has(keyData);
+    const keyData = this._makeKey(key);
+    return this._dict.has(keyData);
   }
 
   clear(): void {
-    this.#dict = new SortedMap(null, areBytesEqual, lexicographicallyCompareBytes);
+    this._dict = new SortedMap(null, areBytesEqual, lexicographicallyCompareBytes);
   }
 
   /**
@@ -149,7 +153,7 @@ export class CborMap {
    * Matches Rust's Map::len().
    */
   get length(): number {
-    return this.#dict.length;
+    return this._dict.length;
   }
 
   /**
@@ -157,7 +161,7 @@ export class CborMap {
    * Also matches Rust's Map::len().
    */
   get size(): number {
-    return this.#dict.length;
+    return this._dict.length;
   }
 
   /**
@@ -165,7 +169,7 @@ export class CborMap {
    * Matches Rust's Map::len().
    */
   len(): number {
-    return this.#dict.length;
+    return this._dict.length;
   }
 
   /**
@@ -173,7 +177,7 @@ export class CborMap {
    * Matches Rust's Map::is_empty().
    */
   isEmpty(): boolean {
-    return this.#dict.length === 0;
+    return this._dict.length === 0;
   }
 
   /**
@@ -181,7 +185,7 @@ export class CborMap {
    * Keys are sorted in lexicographic order of their encoded CBOR bytes.
    */
   get entriesArray(): MapEntry[] {
-    return this.#dict.map((value: MapEntry, _key: MapKey) => ({
+    return this._dict.map((value: MapEntry, _key: MapKey) => ({
       key: value.key,
       value: value.value,
     }));
@@ -213,21 +217,21 @@ export class CborMap {
    * Matches Rust's Map::insert_next().
    */
   setNext<K extends CborInput, V extends CborInput>(key: K, value: V): void {
-    const lastEntry = this.#dict.max();
+    const lastEntry = this._dict.max();
     if (lastEntry === undefined) {
       this.set(key, value);
       return;
     }
     const keyCbor = cbor(key);
     const newKey = cborData(keyCbor);
-    if (this.#dict.has(newKey)) {
+    if (this._dict.has(newKey)) {
       throw new CborError({ type: "DuplicateMapKey" });
     }
-    const lastEntryKey = this.#makeKey(lastEntry.key);
+    const lastEntryKey = this._makeKey(lastEntry.key);
     if (lexicographicallyCompareBytes(newKey, lastEntryKey) <= 0) {
       throw new CborError({ type: "MisorderedMapKey" });
     }
-    this.#dict.set(newKey, { key: keyCbor, value: cbor(value) });
+    this._dict.set(newKey, { key: keyCbor, value: cbor(value) });
   }
 
   get debug(): string {

package/src/prelude.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Prelude module - Re-exports commonly used types and classes.
  *
  * This module provides a curated set of imports matching Rust's prelude.rs.
@@ -51,8 +55,8 @@ export { ByteString } from "./byte-string";
 export { CborDate } from "./date";
 
 // Tag handling
-export type { Tag } from "./tag";
-export { createTag } from "./tag";
+export type { Tag, TagValue } from "./tag";
+export { createTag, tagWithValue, tagWithStaticName, tagsEqual } from "./tag";
 export { TagsStore, getGlobalTagsStore, withTags, withTagsMut } from "./tags-store";
 export type { TagsStoreTrait } from "./tags-store";
 export { tagsForValues } from "./tags";
@@ -65,6 +69,12 @@ export type { HexFormatOpts } from "./dump";
 export { EdgeType } from "./walk";
 export type { WalkElement, EdgeTypeVariant, Visitor } from "./walk";
 
+// BigNum support
+export { biguintToCbor, bigintToCbor, cborToBiguint, cborToBigint } from "./bignum";
+
+// CBOR-encoding-based array sorting (Rust `prelude.rs::CBORSortable`).
+export { sortArrayByCborEncoding, arraySortable, setSortable, type CBORSortable } from "./sortable";
+
 // Error handling
 export type { Error, Result } from "./error";
 export { Ok, Err, errorMsg, errorToString, CborError } from "./error";

package/src/set.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Set data structure for CBOR with tag(258) encoding.
  *
  * A Set is encoded as an array with no duplicate elements,
@@ -47,10 +51,10 @@ import { CborError } from "./error";
  * ```
  */
 export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet> {
-  readonly #map: CborMap;
+  private readonly _map: CborMap;
 
   constructor() {
-    this.#map = new CborMap();
+    this._map = new CborMap();
   }
 
   // =========================================================================
@@ -127,7 +131,27 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
   insert(value: CborInput): void {
     const cborValue = encodeCborValue(value);
     // In a set, key and value are the same
-    this.#map.set(cborValue, cborValue);
+    this._map.set(cborValue, cborValue);
+  }
+
+  /**
+   * Insert an element into the set, requiring it to be strictly greater
+   * (in canonical CBOR-encoded byte order) than every previously-inserted
+   * element. Used by the decoder to reject misordered or duplicate
+   * elements in tag-258 set encodings.
+   *
+   * Mirrors Rust `Set::insert_next` (`pub(crate)`); exposed here because
+   * TypeScript doesn't have a crate-private visibility level.
+   *
+   * @throws CborError of type `MisorderedMap` if `value` would not preserve
+   *   strict ascending CBOR-byte order, or `DuplicateMapKey` for an exact
+   *   repeat.
+   */
+  insertNext(value: CborInput): void {
+    const cborValue = encodeCborValue(value);
+    // Set is `Map<key=value, value>` in Rust. `Map::insert_next` enforces
+    // strict ascending order on the encoded key bytes.
+    this._map.setNext(cborValue, cborValue);
   }
 
   /**
@@ -145,7 +169,7 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
    */
   contains(value: CborInput): boolean {
     const cborValue = encodeCborValue(value);
-    return this.#map.has(cborValue);
+    return this._map.has(cborValue);
   }
 
   /**
@@ -163,14 +187,14 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
    */
   delete(value: CborInput): boolean {
     const cborValue = encodeCborValue(value);
-    return this.#map.delete(cborValue);
+    return this._map.delete(cborValue);
   }
 
   /**
    * Remove all elements from the set.
    */
   clear(): void {
-    this.#map.clear();
+    this._map.clear();
   }
 
   /**
@@ -179,7 +203,7 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
    * @returns Number of elements
    */
   get size(): number {
-    return this.#map.size;
+    return this._map.size;
   }
 
   /**
@@ -188,7 +212,7 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
    * @returns true if set has no elements
    */
   isEmpty(): boolean {
-    return this.#map.size === 0;
+    return this._map.size === 0;
   }
 
   // =========================================================================
@@ -313,7 +337,7 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
    * ```
    */
   *[Symbol.iterator](): Iterator<Cbor> {
-    for (const [_, value] of this.#map) {
+    for (const [_, value] of this._map) {
       yield value;
     }
   }
@@ -376,8 +400,11 @@ export class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet
     }
 
     this.clear();
+    // Mirrors Rust `Set::try_from_vec` which calls `insert_next` per item:
+    // a tag-258 wire encoding must already be in strict ascending CBOR-byte
+    // order with no duplicates.
     for (const value of c.value) {
-      this.insert(extractCbor(value) as CborInput);
+      this.insertNext(extractCbor(value) as CborInput);
     }
 
     return this;

package/src/simple.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * CBOR Simple Values (Major Type 7).
  *
  * @module simple
@@ -120,10 +124,19 @@ export const simpleEquals = (a: Simple, b: Simple): boolean => {
 /**
  * Hash a Simple value.
  *
- * Matches Rust's Hash trait implementation.
+ * **Cross-language note.** Rust derives `Hash` on `Simple` via
+ * `f64::to_bits().hash(state)` through `DefaultHasher` (SipHash). JS
+ * doesn't expose SipHash, so this implementation uses FNV-1a — a fast
+ * non-cryptographic hash. The hash codes therefore **differ between
+ * Rust and TS at runtime**; this is intentional and harmless because
+ * `Hash` is only used to drive per-runtime hash tables (e.g. dedup in
+ * `HashSet<Simple>`). It is **not** part of the deterministic CBOR wire
+ * format, which uses bytewise lex on the encoded CBOR (see
+ * `lexicographicallyCompareBytes`). Do not rely on these hash values
+ * across implementations.
  */
 export const simpleHash = (simple: Simple): number => {
-  // Simple FNV-1a hash
+  // FNV-1a hash. (See doc-comment above for why this differs from Rust.)
   let hash = 2166136261;
 
   switch (simple.type) {

package/src/sortable.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
+ * CBOR-encoding-based array sorting helpers.
+ *
+ * Ported from `bc-dcbor-rust/src/array.rs` (`sort_array_by_cbor_encoding` +
+ * `CBORSortable<T>` trait). dCBOR / CDE deterministic ordering is bytewise
+ * lexicographic over the CBOR encoding of each element — this is the same
+ * comparator that `Map`/`Set` use internally for key ordering.
+ *
+ * @module sortable
+ */
+
+import { type CborInput, cbor } from "./cbor";
+import { lexicographicallyCompareBytes } from "./stdlib";
+
+/**
+ * Return a new array sorted by the bytewise lexicographic order of each
+ * element's CBOR encoding.
+ *
+ * Mirrors Rust `pub fn sort_array_by_cbor_encoding<T>(array)`.
+ *
+ * @example
+ * ```typescript
+ * const sorted = sortArrayByCborEncoding([3, 1, 2]); // [1, 2, 3]
+ * ```
+ */
+export function sortArrayByCborEncoding<T extends CborInput>(array: readonly T[]): T[] {
+  const annotated: { encoding: Uint8Array; item: T }[] = array.map((item) => ({
+    encoding: cbor(item).toData(),
+    item,
+  }));
+  annotated.sort((a, b) => lexicographicallyCompareBytes(a.encoding, b.encoding));
+  return annotated.map((entry) => entry.item);
+}
+
+/**
+ * Sortable-by-CBOR-encoding trait shape.
+ *
+ * Mirrors Rust `pub trait CBORSortable<T> { fn sort_by_cbor_encoding(&self)
+ * -> Vec<T>; }` with blanket implementations for `Vec<T>`, `&[T]`,
+ * `HashSet<T>`. In TypeScript we expose a narrow interface plus
+ * `arraySortable` / `setSortable` helpers that wrap any iterable into a
+ * `CBORSortable` view.
+ */
+export interface CBORSortable<T extends CborInput> {
+  sortByCborEncoding(): T[];
+}
+
+/**
+ * Wrap a readonly array as a {@link CBORSortable}. Equivalent to Rust's
+ * blanket `impl CBORSortable<T> for Vec<T>` / `for &[T]`.
+ */
+export function arraySortable<T extends CborInput>(array: readonly T[]): CBORSortable<T> {
+  return {
+    sortByCborEncoding: () => sortArrayByCborEncoding(array),
+  };
+}
+
+/**
+ * Wrap a `Set<T>` as a {@link CBORSortable}. Equivalent to Rust's
+ * `impl CBORSortable<T> for HashSet<T>`.
+ */
+export function setSortable<T extends CborInput>(set: ReadonlySet<T>): CBORSortable<T> {
+  return {
+    sortByCborEncoding: () => sortArrayByCborEncoding(Array.from(set)),
+  };
+}

package/src/stdlib.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Standard library re-exports and compatibility layer.
  *
  * In Rust, this handles std/no_std feature flags.

package/src/string-util.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * String utilities for dCBOR, including Unicode normalization.
  *
  * @module string-util

package/src/tag.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * CBOR Tag support for semantic tagging of values.
  *
  * Tags provide semantic information about CBOR data items.
@@ -9,14 +13,29 @@
 
 import type { CborNumber } from "./cbor";
 
+/**
+ * Numeric tag value type alias.
+ *
+ * Mirrors Rust `pub type TagValue = u64`. Where Rust narrows to u64, TS
+ * accepts the broader `CborNumber` (`number | bigint`) since JavaScript
+ * has no native u64 — the runtime guards in `encodeVarInt` enforce the
+ * 0..=2^64-1 range.
+ */
+export type TagValue = CborNumber;
+
 /**
  * A CBOR tag with an optional name.
  *
  * Tags consist of a numeric value and an optional human-readable name.
+ *
+ * Note on equality: Rust derives `PartialEq` on `Tag` keyed on `value`
+ * only — two tags with the same value but different names compare equal.
+ * Use {@link tagsEqual} to mirror that behaviour from TypeScript; raw
+ * `===` on `Tag` objects compares by reference.
  */
 export interface Tag {
   /** The numeric tag value */
-  readonly value: CborNumber;
+  readonly value: TagValue;
   /** Optional human-readable name for the tag */
   readonly name?: string;
 }
@@ -34,13 +53,43 @@ export interface Tag {
  * const customTag = createTag(12345, 'myCustomTag');
  * ```
  */
-export const createTag = (value: CborNumber, name?: string): Tag => {
+export const createTag = (value: TagValue, name?: string): Tag => {
   if (name !== undefined) {
     return { value, name };
   }
   return { value };
 };
 
+/**
+ * Create a Tag from just its numeric value, no name attached.
+ *
+ * Mirrors Rust's `Tag::with_value(v: TagValue)`.
+ */
+export const tagWithValue = (value: TagValue): Tag => ({ value });
+
+/**
+ * Create a Tag with a static (string) name.
+ *
+ * In Rust this distinguishes `Tag::Static(&'static str)` from
+ * `Tag::Dynamic(String)`. TypeScript has no compile-time equivalent — both
+ * variants collapse to the same `{ value, name }` object — but the
+ * function name is preserved for API parity.
+ *
+ * Mirrors Rust's `Tag::with_static_name(v, name)`.
+ */
+export const tagWithStaticName = (value: TagValue, name: string): Tag => ({ value, name });
+
+/**
+ * Compare two tags for equality. Mirrors Rust's `PartialEq for Tag`, which
+ * compares by `value` only and ignores the optional `name`.
+ */
+export const tagsEqual = (a: Tag, b: Tag): boolean => {
+  if (typeof a.value === "bigint" || typeof b.value === "bigint") {
+    return BigInt(a.value) === BigInt(b.value);
+  }
+  return a.value === b.value;
+};
+
 /**
  * Get the string representation of a tag.
  * Internal function used for error messages.