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

package/src/cbor.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 import { CborMap } from "./map";
 import type { Simple } from "./simple";
 import { simpleCborData, isFloat as isSimpleFloat } from "./simple";
@@ -11,8 +17,7 @@ import type { ByteString } from "./byte-string";
 import type { CborDate } from "./date";
 import { diagnosticOpt } from "./diag";
 import { decodeCbor } from "./decode";
-import type { TagsStore } from "./tags-store";
-import { getGlobalTagsStore } from "./tags-store";
+import { getGlobalTagsStore, type TagsStore } from "./tags-store";
 import type { Visitor } from "./walk";
 import { walk } from "./walk";
 import { CborError } from "./error";
@@ -250,7 +255,7 @@ export interface CborMethods {
    * @param initialState - Initial state for the visitor
    * @param visitor - Visitor function called for each element
    */
-  walk<State>(initialState: State, visitor: Visitor<State>): State;
+  walk<State>(initialState: State, visitor: Visitor<State>): void;
   /**
    * Validate that value has one of the expected tags.
    * @param expectedTags - Array of expected tag values
@@ -290,6 +295,40 @@ export interface TaggedCborEncodable {
 /**
  * Type guard to check if value has taggedCbor method.
  */
+/**
+ * Resolve a numeric/bigint tag value to a `Tag` object, looking up the
+ * canonical name from the global tags store (matches Rust's
+ * `try_into_tagged_value` returning the stored `Tag`). Falls back to a
+ * name-less `{ value }` if no name is registered — never synthesizes a
+ * placeholder `tag-${value}` string.
+ */
+const resolveTag = (value: number | bigint): Tag => {
+  const stored = getGlobalTagsStore().tagForValue(value);
+  if (stored !== undefined) return stored;
+  return { value };
+};
+
+/**
+ * Structural CBOR value equality.
+ *
+ * Mirrors Rust's `derive(PartialEq) for CBOR`. dCBOR encoding is
+ * deterministic, so two CBOR values are equal iff they encode to the
+ * same byte sequence — this is the simplest correct comparator.
+ *
+ * Use this rather than `===` (which compares JS object references) when
+ * you need value equality across two `Cbor` instances built independently.
+ */
+export const cborEquals = (a: Cbor, b: Cbor): boolean => {
+  if (a === b) return true;
+  const aBytes = a.toData();
+  const bBytes = b.toData();
+  if (aBytes.length !== bBytes.length) return false;
+  for (let i = 0; i < aBytes.length; i++) {
+    if (aBytes[i] !== bBytes[i]) return false;
+  }
+  return true;
+};
+
 const hasTaggedCbor = (value: unknown): value is TaggedCborEncodable => {
   return (
     typeof value === "object" &&
@@ -337,6 +376,20 @@ export const cbor = (value: CborInput): Cbor => {
       result = { isCbor: true, type: MajorType.Simple, value: { type: "Float", value: Infinity } };
     } else if (value == -Infinity) {
       result = { isCbor: true, type: MajorType.Simple, value: { type: "Float", value: -Infinity } };
+    } else if (typeof value === "number" && !Number.isSafeInteger(value)) {
+      // Mirrors Rust `f64::exact_from_f64`: any finite, integer-valued
+      // float that exceeds the safe-integer range (so adjacent integers
+      // can't be distinguished, e.g. `1e21`) cannot be encoded as a
+      // canonical integer. Route to Float instead — Rust's `From<f64>
+      // for CBOR` does the same fallback.
+      result = { isCbor: true, type: MajorType.Simple, value: { type: "Float", value: value } };
+    } else if (
+      typeof value === "bigint" &&
+      (value > 0xffffffffffffffffn || value < -0x10000000000000000n)
+    ) {
+      // bigint outside the [-(2^64), 2^64 - 1] CBOR-encodable integer
+      // range. Surface immediately rather than crashing in encodeVarInt.
+      throw new CborError({ type: "OutOfRange" });
     } else if (value < 0) {
       // Store the magnitude to encode, matching Rust's representation
       // For a negative value n, CBOR encodes it as -1-n, so we store -n-1
@@ -642,8 +695,7 @@ export const attachMethods = <T extends Omit<Cbor, keyof CborMethods>>(obj: T):
       if (this.type !== MajorType.Tagged) {
         return undefined;
       }
-      const tag: Tag = { value: this.tag, name: `tag-${this.tag}` };
-      return [tag, this.value];
+      return [resolveTag(this.tag), this.value];
     },
     asBool(this: Cbor): boolean | undefined {
       if (this.type !== MajorType.Simple) return undefined;
@@ -720,8 +772,7 @@ export const attachMethods = <T extends Omit<Cbor, keyof CborMethods>>(obj: T):
           `Cannot convert CBOR to Tagged: expected Tagged type, got ${getMajorTypeName(this.type)}`,
         );
       }
-      const tag: Tag = { value: this.tag, name: `tag-${this.tag}` };
-      return [tag, this.value];
+      return [resolveTag(this.tag), this.value];
     },
     toBool(this: Cbor): boolean {
       const result = this.asBool();
@@ -762,33 +813,37 @@ export const attachMethods = <T extends Omit<Cbor, keyof CborMethods>>(obj: T):
       if (this.type !== MajorType.Tagged) {
         throw new CborError({ type: "WrongType" });
       }
-      const expectedValue =
-        typeof expectedTag === "object" && "value" in expectedTag ? expectedTag.value : expectedTag;
-      if (this.tag !== expectedValue) {
+      const expected: Tag =
+        typeof expectedTag === "object" && "value" in expectedTag
+          ? expectedTag
+          : { value: expectedTag };
+      if (this.tag !== expected.value) {
+        // Mirror Rust `Error::WrongTag(expected, actual)`.
         throw new CborError({
-          type: "Custom",
-          message: `Wrong tag: expected ${expectedValue}, got ${this.tag}`,
+          type: "WrongTag",
+          expected,
+          actual: { value: this.tag },
         });
       }
       return this.value;
     },
 
     // Advanced operations
-    walk<State>(this: Cbor, initialState: State, visitor: Visitor<State>): State {
-      return walk(this, initialState, visitor);
+    walk<State>(this: Cbor, initialState: State, visitor: Visitor<State>): void {
+      walk(this, initialState, visitor);
     },
     validateTag(this: Cbor, expectedTags: Tag[]): Tag {
       if (this.type !== MajorType.Tagged) {
         throw new CborError({ type: "WrongType" });
       }
-      const expectedValues = expectedTags.map((t) => t.value);
       const tagValue = this.tag;
       const matchingTag = expectedTags.find((t) => t.value === tagValue);
       if (matchingTag === undefined) {
-        const expectedStr = expectedValues.join(" or ");
+        // Mirror Rust `Error::WrongTag(expected, actual)`.
         throw new CborError({
-          type: "Custom",
-          message: `Wrong tag: expected ${expectedStr}, got ${tagValue}`,
+          type: "WrongTag",
+          expected: expectedTags[0],
+          actual: { value: tagValue },
         });
       }
       return matchingTag;

package/src/conveniences.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Convenience utilities for working with CBOR values.
  *
  * Provides type-safe helpers for checking types, extracting values,
@@ -738,17 +742,26 @@ export const getTaggedContent = (cbor: Cbor, tag: number | bigint): Cbor | undef
 /**
  * Extract content if has specific tag, throwing if not.
  *
+ * Mirrors Rust `try_into_expected_tagged_value`. Throws `{ type: "WrongType" }`
+ * if `cbor` is not tagged at all, otherwise `{ type: "WrongTag", expected,
+ * actual }` if the tag doesn't match.
+ *
  * @param cbor - CBOR value
  * @param tag - Expected tag value
  * @returns Tagged content
- * @throws {CborError} With type 'WrongType' if cbor is not tagged with the expected tag
  */
 export const expectTaggedContent = (cbor: Cbor, tag: number | bigint): Cbor => {
-  const content = getTaggedContent(cbor, tag);
-  if (content === undefined) {
+  if (cbor.type !== MajorType.Tagged) {
     throw new CborError({ type: "WrongType" });
   }
-  return content;
+  if (cbor.tag !== tag) {
+    throw new CborError({
+      type: "WrongTag",
+      expected: { value: tag },
+      actual: { value: cbor.tag },
+    });
+  }
+  return cbor.value;
 };
 
 // ============================================================================
@@ -757,6 +770,7 @@ export const expectTaggedContent = (cbor: Cbor, tag: number | bigint): Cbor => {
 // ============================================================================
 
 import type { Tag } from "./tag";
+import { getGlobalTagsStore } from "./tags-store";
 
 /**
  * Extract tagged value as tuple [Tag, Cbor] if CBOR is tagged.
@@ -769,7 +783,11 @@ export const asTaggedValue = (cbor: Cbor): [Tag, Cbor] | undefined => {
   if (cbor.type !== MajorType.Tagged) {
     return undefined;
   }
-  const tag: Tag = { value: cbor.tag, name: `tag-${cbor.tag}` };
+  // Mirrors Rust `try_into_tagged_value` which returns the stored `Tag`.
+  // Resolve the canonical name (if any) via the global tags store rather
+  // than synthesizing a `tag-${value}` placeholder.
+  const resolved = getGlobalTagsStore().tagForValue(cbor.tag);
+  const tag: Tag = resolved ?? { value: cbor.tag };
   return [tag, cbor.value];
 };
 

package/src/date.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Date/time support for CBOR with tag(1) encoding.
  *
  * A CBOR-friendly representation of a date and time.
@@ -67,7 +71,20 @@ import { CborError } from "./error";
  * ```
  */
 export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDecodable<CborDate> {
-  #datetime: Date;
+  /**
+   * Canonical timestamp in seconds since the Unix epoch as a JS `number`
+   * (`f64`). dCBOR encodes Date (tag 1) as a numeric value in seconds, so
+   * keeping `_seconds` as the source of truth avoids the millisecond-only
+   * round-trip precision loss that going through a JS `Date` instance
+   * introduced in earlier versions of this port.
+   *
+   * f64 still bounds the achievable precision (~16 decimal digits, so
+   * roughly microseconds for current epoch values); Rust's
+   * `chrono::DateTime<Utc>` retains nanoseconds in memory but encodes
+   * to the same f64 over the wire, so the *encode/decode round-trip* is
+   * byte-identical.
+   */
+  private _seconds: number;
 
   /**
    * Creates a new `CborDate` from the given JavaScript `Date`.
@@ -87,7 +104,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    */
   static fromDatetime(dateTime: Date): CborDate {
     const instance = new CborDate();
-    instance.#datetime = new Date(dateTime);
+    instance._seconds = dateTime.getTime() / 1000;
     return instance;
   }
 
@@ -174,10 +191,9 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   static fromTimestamp(secondsSinceUnixEpoch: number): CborDate {
-    const wholeSecondsSinceUnixEpoch = Math.trunc(secondsSinceUnixEpoch);
-    const fractionalSeconds = secondsSinceUnixEpoch - wholeSecondsSinceUnixEpoch;
-    const milliseconds = wholeSecondsSinceUnixEpoch * 1000 + fractionalSeconds * 1000;
-    return CborDate.fromDatetime(new Date(milliseconds));
+    const instance = new CborDate();
+    instance._seconds = secondsSinceUnixEpoch;
+    return instance;
   }
 
   /**
@@ -209,7 +225,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
     // Try parsing as ISO 8601 date string
     const dt = new Date(value);
     if (isNaN(dt.getTime())) {
-      throw new CborError({ type: "InvalidDate", message: `Invalid date string: ${value}` });
+      throw new CborError({ type: "InvalidDate", message: "Invalid date string" });
     }
     return CborDate.fromDatetime(dt);
   }
@@ -265,7 +281,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   datetime(): Date {
-    return new Date(this.#datetime);
+    return new Date(this._seconds * 1000);
   }
 
   /**
@@ -285,9 +301,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   timestamp(): number {
-    const wholeSecondsSinceUnixEpoch = Math.trunc(this.#datetime.getTime() / 1000);
-    const msecs = this.#datetime.getTime() % 1000;
-    return wholeSecondsSinceUnixEpoch + msecs / 1000.0;
+    return this._seconds;
   }
 
   /**
@@ -415,22 +429,17 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
         if (cbor.value.type === "Float") {
           timestamp = cbor.value.value;
         } else {
-          throw new CborError({
-            type: "Custom",
-            message: "Invalid date CBOR: expected numeric value",
-          });
+          // Mirrors Rust `f64::try_from(CBOR)` returning `Error::WrongType`
+          // for non-numeric / non-Float Simple values.
+          throw new CborError({ type: "WrongType" });
         }
         break;
 
       default:
-        throw new CborError({
-          type: "Custom",
-          message: "Invalid date CBOR: expected numeric value",
-        });
+        throw new CborError({ type: "WrongType" });
     }
 
-    const date = CborDate.fromTimestamp(timestamp);
-    this.#datetime = date.#datetime;
+    this._seconds = timestamp;
     return this;
   }
 
@@ -495,7 +504,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   toString(): string {
-    const dt = this.#datetime;
+    const dt = new Date(this._seconds * 1000);
     // Check only hours, minutes, and seconds (not milliseconds) to match Rust behavior
     const hasTime = dt.getUTCHours() !== 0 || dt.getUTCMinutes() !== 0 || dt.getUTCSeconds() !== 0;
 
@@ -521,7 +530,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * @returns true if dates represent the same moment in time
    */
   equals(other: CborDate): boolean {
-    return this.#datetime.getTime() === other.#datetime.getTime();
+    return this._seconds === other._seconds;
   }
 
   /**
@@ -531,10 +540,8 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * @returns -1 if this < other, 0 if equal, 1 if this > other
    */
   compare(other: CborDate): number {
-    const thisTime = this.#datetime.getTime();
-    const otherTime = other.#datetime.getTime();
-    if (thisTime < otherTime) return -1;
-    if (thisTime > otherTime) return 1;
+    if (this._seconds < other._seconds) return -1;
+    if (this._seconds > other._seconds) return 1;
     return 0;
   }
 
@@ -548,6 +555,6 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
   }
 
   private constructor() {
-    this.#datetime = new Date();
+    this._seconds = Date.now() / 1000;
   }
 }

package/src/decode.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 import {
   type Cbor,
   type CborNumber,
@@ -201,6 +207,13 @@ function decodeCborInternal(data: DataView): { cbor: Cbor; len: number } {
       switch (varIntLen) {
         case 3: {
           const f = binary16ToNumber(new Uint8Array(data.buffer, data.byteOffset + 1, 2));
+          // dCBOR canonical-encoding check via re-encode-and-compare. JS's
+          // `Number` type does not preserve NaN payload bits — every NaN
+          // collapses to the same value — so we cannot port Rust's
+          // `validate_canonical_f16(n)`'s bit-level check directly.
+          // Re-encoding round-trips through the canonicalising encoder,
+          // catching every non-canonical NaN, ±Infinity, and
+          // integer-reducible float. See float.ts for the encoder rules.
           checkCanonicalEncoding(f, new Uint8Array(data.buffer, data.byteOffset, varIntLen));
           const cborObj = {
             isCbor: true,