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

package/src/tags-store.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Tag registry and management system.
  *
  * The TagsStore provides a centralized registry for CBOR tags,
@@ -9,17 +13,26 @@
 
 import type { Cbor, CborNumber } from "./cbor";
 import type { Tag } from "./tag";
+import type { Error as CborErrorType } from "./error";
+
+/**
+ * Result type for summarizer functions, matching Rust's Result<String, Error>.
+ */
+export type SummarizerResult =
+  | { readonly ok: true; readonly value: string }
+  | { readonly ok: false; readonly error: CborErrorType };
 
 /**
  * Function type for custom CBOR value summarizers.
  *
  * Summarizers provide custom string representations for tagged values.
+ * Returns a Result type matching Rust's `Result<String, Error>`.
  *
  * @param cbor - The CBOR value to summarize
  * @param flat - If true, produce single-line output
- * @returns String summary of the value
+ * @returns Result with summary string on success, or error on failure
  */
-export type CborSummarizer = (cbor: Cbor, flat: boolean) => string;
+export type CborSummarizer = (cbor: Cbor, flat: boolean) => SummarizerResult;
 
 /**
  * Interface for tag store operations.
@@ -80,9 +93,9 @@ export interface TagsStoreTrait {
  * Stores tags with their names and optional summarizer functions.
  */
 export class TagsStore implements TagsStoreTrait {
-  readonly #tagsByValue = new Map<string, Tag>();
-  readonly #tagsByName = new Map<string, Tag>();
-  readonly #summarizers = new Map<string, CborSummarizer>();
+  private readonly _tagsByValue = new Map<string, Tag>();
+  private readonly _tagsByName = new Map<string, Tag>();
+  private readonly _summarizers = new Map<string, CborSummarizer>();
 
   constructor() {
     // Start with empty store, matching Rust's Default implementation
@@ -92,7 +105,13 @@ export class TagsStore implements TagsStoreTrait {
   /**
    * Insert a tag into the registry.
    *
-   * @param tag - The tag to register
+   * Matches Rust's TagsStore::insert() behavior:
+   * - Throws if the tag name is undefined or empty
+   * - Throws if a tag with the same value exists with a different name
+   * - Allows re-registering the same tag value with the same name
+   *
+   * @param tag - The tag to register (must have a non-empty name)
+   * @throws Error if tag has no name, empty name, or conflicts with existing registration
    *
    * @example
    * ```typescript
@@ -101,11 +120,25 @@ export class TagsStore implements TagsStoreTrait {
    * ```
    */
   insert(tag: Tag): void {
-    const key = this.#valueKey(tag.value);
-    this.#tagsByValue.set(key, tag);
-    if (tag.name !== undefined) {
-      this.#tagsByName.set(tag.name, tag);
+    const name = tag.name;
+
+    // Rust: let name = tag.name().unwrap(); assert!(!name.is_empty());
+    if (name === undefined || name === "") {
+      throw new Error(`Tag ${tag.value} must have a non-empty name`);
     }
+
+    const key = this._valueKey(tag.value);
+    const existing = this._tagsByValue.get(key);
+
+    // Rust: if old_name != name { panic!(...) }
+    if (existing?.name !== undefined && existing.name !== name) {
+      throw new Error(
+        `Attempt to register tag: ${tag.value} '${existing.name}' with different name: '${name}'`,
+      );
+    }
+
+    this._tagsByValue.set(key, tag);
+    this._tagsByName.set(name, tag);
   }
 
   /**
@@ -144,34 +177,13 @@ export class TagsStore implements TagsStoreTrait {
    * ```
    */
   setSummarizer(tagValue: CborNumber, summarizer: CborSummarizer): void {
-    const key = this.#valueKey(tagValue);
-    this.#summarizers.set(key, summarizer);
-  }
-
-  /**
-   * Remove a tag from the registry.
-   *
-   * @param tagValue - The numeric tag value to remove
-   * @returns true if a tag was removed, false otherwise
-   */
-  remove(tagValue: CborNumber): boolean {
-    const key = this.#valueKey(tagValue);
-    const tag = this.#tagsByValue.get(key);
-    if (tag === undefined) {
-      return false;
-    }
-
-    this.#tagsByValue.delete(key);
-    if (tag.name !== undefined) {
-      this.#tagsByName.delete(tag.name);
-    }
-    this.#summarizers.delete(key);
-    return true;
+    const key = this._valueKey(tagValue);
+    this._summarizers.set(key, summarizer);
   }
 
   assignedNameForTag(tag: Tag): string | undefined {
-    const key = this.#valueKey(tag.value);
-    const stored = this.#tagsByValue.get(key);
+    const key = this._valueKey(tag.value);
+    const stored = this._tagsByValue.get(key);
     return stored?.name;
   }
 
@@ -180,12 +192,12 @@ export class TagsStore implements TagsStoreTrait {
   }
 
   tagForValue(value: CborNumber): Tag | undefined {
-    const key = this.#valueKey(value);
-    return this.#tagsByValue.get(key);
+    const key = this._valueKey(value);
+    return this._tagsByValue.get(key);
   }
 
   tagForName(name: string): Tag | undefined {
-    return this.#tagsByName.get(name);
+    return this._tagsByName.get(name);
   }
 
   nameForValue(value: CborNumber): string {
@@ -194,35 +206,8 @@ export class TagsStore implements TagsStoreTrait {
   }
 
   summarizer(tag: CborNumber): CborSummarizer | undefined {
-    const key = this.#valueKey(tag);
-    return this.#summarizers.get(key);
-  }
-
-  /**
-   * Get all registered tags.
-   *
-   * @returns Array of all registered tags
-   */
-  getAllTags(): Tag[] {
-    return Array.from(this.#tagsByValue.values());
-  }
-
-  /**
-   * Clear all registered tags and summarizers.
-   */
-  clear(): void {
-    this.#tagsByValue.clear();
-    this.#tagsByName.clear();
-    this.#summarizers.clear();
-  }
-
-  /**
-   * Get the number of registered tags.
-   *
-   * @returns Number of tags in the registry
-   */
-  get size(): number {
-    return this.#tagsByValue.size;
+    const key = this._valueKey(tag);
+    return this._summarizers.get(key);
   }
 
   /**
@@ -231,7 +216,7 @@ export class TagsStore implements TagsStoreTrait {
    *
    * @private
    */
-  #valueKey(value: CborNumber): string {
+  private _valueKey(value: CborNumber): string {
     return value.toString();
   }
 }

package/src/tags.ts

@@ -1,6 +1,21 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Standard CBOR tag definitions from the IANA registry.
  *
+ * **Cross-package note (parity with Rust).** `bc-dcbor-rust/src/tags.rs`
+ * intentionally only defines the three tags dcbor itself needs:
+ * `TAG_DATE` (1), `TAG_POSITIVE_BIGNUM` (2), `TAG_NEGATIVE_BIGNUM` (3).
+ * Every other Blockchain Commons tag — UR types, IANA semantic tags, the
+ * Envelope/XID family — lives in the dedicated `bc-tags-rust` crate
+ * (mirrored as `@bcts/tags` in TypeScript). This file additionally
+ * re-exports many of those constants for ergonomic in-package use; they
+ * are duplicate convenience definitions, not authoritative. Prefer
+ * importing from `@bcts/tags` in new code; treat the extras here as
+ * deprecated aliases that may be relocated in a future release.
+ *
  * @module tags
  * @see https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
  */
@@ -40,6 +55,18 @@ export const TAG_POSITIVE_BIGNUM = 2;
  */
 export const TAG_NEGATIVE_BIGNUM = 3;
 
+/**
+ * Name for tag 2 (positive bignum).
+ * Matches Rust's `TAG_NAME_POSITIVE_BIGNUM`.
+ */
+export const TAG_NAME_POSITIVE_BIGNUM = "positive-bignum";
+
+/**
+ * Name for tag 3 (negative bignum).
+ * Matches Rust's `TAG_NAME_NEGATIVE_BIGNUM`.
+ */
+export const TAG_NAME_NEGATIVE_BIGNUM = "negative-bignum";
+
 /**
  * Tag 4: Decimal fraction [exponent, mantissa]
  */
@@ -148,11 +175,11 @@ export const TAG_SELF_DESCRIBE_CBOR = 55799;
 // Matches Rust's register_tags() functionality
 // ============================================================================
 
-import type { TagsStore } from "./tags-store";
+import type { TagsStore, SummarizerResult } from "./tags-store";
 import { getGlobalTagsStore } from "./tags-store";
 import { CborDate } from "./date";
 import type { Cbor } from "./cbor";
-import { diagnostic } from "./diag";
+import { biguintFromUntaggedCbor, bigintFromNegativeUntaggedCbor } from "./bignum";
 
 // Tag constants matching Rust
 export const TAG_DATE = 1;
@@ -169,13 +196,48 @@ export const registerTagsIn = (tagsStore: TagsStore): void => {
   tagsStore.insertAll(tags);
 
   // Set summarizer for date tag
-  tagsStore.setSummarizer(TAG_DATE, (untaggedCbor: Cbor, _flat: boolean): string => {
+  tagsStore.setSummarizer(TAG_DATE, (untaggedCbor: Cbor, _flat: boolean): SummarizerResult => {
     try {
-      return CborDate.fromUntaggedCbor(untaggedCbor).toString();
-    } catch {
-      return diagnostic(untaggedCbor);
+      return { ok: true, value: CborDate.fromUntaggedCbor(untaggedCbor).toString() };
+    } catch (e) {
+      // On error, return error result matching Rust's Result::Err
+      const message = e instanceof Error ? e.message : String(e);
+      return { ok: false, error: { type: "Custom", message } };
     }
   });
+
+  // Register bignum tags (matching Rust's #[cfg(feature = "num-bigint")] block)
+  const biguintTag = createTag(TAG_POSITIVE_BIGNUM, TAG_NAME_POSITIVE_BIGNUM);
+  const bigintTag = createTag(TAG_NEGATIVE_BIGNUM, TAG_NAME_NEGATIVE_BIGNUM);
+  tagsStore.insertAll([biguintTag, bigintTag]);
+
+  // Summarizer for tag 2 (positive bignum)
+  tagsStore.setSummarizer(
+    TAG_POSITIVE_BIGNUM,
+    (untaggedCbor: Cbor, _flat: boolean): SummarizerResult => {
+      try {
+        const value = biguintFromUntaggedCbor(untaggedCbor);
+        return { ok: true, value: `bignum(${value})` };
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { ok: false, error: { type: "Custom", message } };
+      }
+    },
+  );
+
+  // Summarizer for tag 3 (negative bignum)
+  tagsStore.setSummarizer(
+    TAG_NEGATIVE_BIGNUM,
+    (untaggedCbor: Cbor, _flat: boolean): SummarizerResult => {
+      try {
+        const value = bigintFromNegativeUntaggedCbor(untaggedCbor);
+        return { ok: true, value: `bignum(${value})` };
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { ok: false, error: { type: "Custom", message } };
+      }
+    },
+  );
 };
 
 /**

package/src/varint.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 import { type CborNumber, isCborNumber, type MajorType } from "./cbor";
 import { hasFractionalPart } from "./float";
 import { CborError } from "./error";
@@ -47,21 +53,20 @@ export const encodeVarInt = (value: CborNumber, majorType: MajorType): Uint8Arra
       return new Uint8Array(buffer);
     }
   } else {
-    value = BigInt(value);
-    const bitsNeeded = Math.ceil(Math.log2(Number(value)) / 8) * 8;
-    if (bitsNeeded > 64) {
+    // Bigint branch — value is strictly greater than `Number.MAX_SAFE_INTEGER`,
+    // therefore strictly greater than `0xffffffff`. The CBOR encoding rule
+    // collapses to: 9 bytes total (header `0x1b | type` + 8 big-endian bytes)
+    // if the value fits in u64, otherwise `OutOfRange`. We must NOT use
+    // `Math.log2(Number(value))` here — `Number(value)` is lossy past 2^53
+    // and would mis-pick the encoding length for values near u64::MAX.
+    const big = BigInt(value);
+    if (big > 0xffffffffffffffffn) {
       throw new CborError({ type: "OutOfRange" });
     }
-    const length = Math.ceil(bitsNeeded / 8) + 1;
-    const buffer = new ArrayBuffer(length);
+    const buffer = new ArrayBuffer(9);
     const view = new DataView(buffer);
-    let i = length - 1;
-    while (value > 0) {
-      view.setUint8(i, Number(value & 0xffn));
-      value >>= 8n;
-      i--;
-    }
     view.setUint8(0, 0x1b | type);
+    view.setBigUint64(1, big);
     return new Uint8Array(buffer);
   }
 };