@bcts/dcbor 1.0.0-alpha.12 → 1.0.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcts/dcbor",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.13",
   "type": "module",
   "description": "Blockchain Commons Deterministic CBOR (dCBOR) for TypeScript",
   "license": "BSD-2-Clause-Patent",
@@ -47,8 +47,6 @@
     "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:cli": "vitest run tests/cli.test.ts",
-    "test:examples": "npm run build && node scripts/test-examples.js",
     "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
     "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
     "typecheck": "tsc --noEmit",

package/src/cbor.ts

@@ -250,7 +250,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
@@ -774,8 +774,8 @@ export const attachMethods = <T extends Omit<Cbor, keyof CborMethods>>(obj: T):
     },
 
     // 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) {

package/src/diag.ts

@@ -376,14 +376,29 @@ function formatMap(map: CborMap, opts: DiagFormatOpts): string {
 
 /**
  * Format tagged value.
+ *
+ * Matches Rust's diag_item() for Tagged case.
  */
 function formatTagged(tag: number | bigint, content: Cbor, opts: DiagFormatOpts): string {
-  // Check for summarizer first
+  // Check for summarizer first (matches Rust's summarization logic)
   if (opts.summarize === true) {
     const store = resolveTagsStore(opts.tags);
     const summarizer = store?.summarizer(tag);
     if (summarizer !== undefined) {
-      return summarizer(content, opts.flat ?? false);
+      // Call summarizer and handle Result type (matching Rust's match on Result)
+      const result = summarizer(content, opts.flat ?? false);
+      if (result.ok) {
+        return result.value;
+      } else {
+        // Match Rust's error format: "<error: {}>"
+        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 `<error: ${errorMsg}>`;
+      }
     }
   }
 

package/src/index.ts

@@ -52,6 +52,7 @@ export {
   TagsStore,
   type TagsStoreTrait,
   type CborSummarizer,
+  type SummarizerResult,
   getGlobalTagsStore,
 } from "./tags-store";
 export * from "./tags";
@@ -72,15 +73,10 @@ export {
   type EdgeTypeVariant,
   type WalkElement,
   type Visitor,
+  walk,
   asSingle,
   asKeyValue,
   edgeLabel,
-  // Helper functions
-  countElements,
-  collectAtLevel,
-  findFirst,
-  collectAllText,
-  maxDepth,
 } from "./walk";
 
 // Codable interfaces

package/src/tags-store.ts

@@ -9,17 +9,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.
@@ -92,7 +101,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 +116,25 @@ export class TagsStore implements TagsStoreTrait {
    * ```
    */
   insert(tag: Tag): void {
+    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);
-    this.#tagsByValue.set(key, tag);
-    if (tag.name !== undefined) {
-      this.#tagsByName.set(tag.name, tag);
+    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);
   }
 
   /**
@@ -148,27 +177,6 @@ export class TagsStore implements TagsStoreTrait {
     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;
-  }
-
   assignedNameForTag(tag: Tag): string | undefined {
     const key = this.#valueKey(tag.value);
     const stored = this.#tagsByValue.get(key);
@@ -198,33 +206,6 @@ export class TagsStore implements TagsStoreTrait {
     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;
-  }
-
   /**
    * Create a string key for a numeric tag value.
    * Handles both number and bigint types.

package/src/tags.ts

@@ -148,11 +148,10 @@ 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";
 
 // Tag constants matching Rust
 export const TAG_DATE = 1;
@@ -169,11 +168,13 @@ 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 } };
     }
   });
 };

package/src/walk.ts

@@ -158,21 +158,20 @@ export type Visitor<State> = (
  * @param cbor - The CBOR value to traverse
  * @param initialState - Initial state value
  * @param visitor - Function to call for each element
- * @returns Final state after traversal
  *
  * @example
  * ```typescript
- * // Count all text strings in a structure
- * interface CountState { count: number }
+ * // Count all text strings in a structure using RefCell-like pattern
+ * const count = { value: 0 };
  *
  * const structure = cbor({ name: 'Alice', tags: ['urgent', 'draft'] });
- * const result = walk(structure, { count: 0 }, (element, level, edge, state) => {
+ * walk(structure, null, (element, level, edge, state) => {
  *   if (element.type === 'single' && element.cbor.type === MajorType.Text) {
- *     return [{ count: state.count + 1 }, false];
+ *     count.value++;
  *   }
  *   return [state, false];
  * });
- * console.log(result.count); // 3 (name, urgent, draft)
+ * console.log(count.value); // 3 (name, urgent, draft)
  * ```
  *
  * @example
@@ -181,7 +180,7 @@ export type Visitor<State> = (
  * const structure = cbor([1, 2, 3, 'found', 5, 6]);
  * let found = false;
  *
- * walk(structure, null, (element, level, edge) => {
+ * walk(structure, null, (element, level, edge, state) => {
  *   if (element.type === 'single' &&
  *       element.cbor.type === MajorType.Text &&
  *       element.cbor.value === 'found') {
@@ -192,8 +191,8 @@ export type Visitor<State> = (
  * });
  * ```
  */
-export const walk = <State>(cbor: Cbor, initialState: State, visitor: Visitor<State>): State => {
-  return walkInternal(cbor, 0, { type: EdgeType.None }, initialState, visitor);
+export const walk = <State>(cbor: Cbor, initialState: State, visitor: Visitor<State>): void => {
+  walkInternal(cbor, 0, { type: EdgeType.None }, initialState, visitor);
 };
 
 /**
@@ -344,173 +343,3 @@ function walkTagged<State>(
 ): State {
   return walkInternal(cbor.value, level + 1, { type: EdgeType.TaggedContent }, state, visitor);
 }
-
-/**
- * Helper: Count all elements in a CBOR tree.
- *
- * @param cbor - The CBOR value to count
- * @returns Total number of elements visited
- *
- * @example
- * ```typescript
- * const structure = cbor([1, 2, [3, 4]]);
- * const count = countElements(structure);
- * console.log(count); // 6 (array, 1, 2, inner array, 3, 4)
- * ```
- */
-export const countElements = (cbor: Cbor): number => {
-  interface CountState {
-    count: number;
-  }
-
-  const result = walk<CountState>(cbor, { count: 0 }, (_element, _level, _edge, state) => {
-    return [{ count: state.count + 1 }, false];
-  });
-
-  return result.count;
-};
-
-/**
- * Helper: Collect all elements at a specific depth level.
- *
- * @param cbor - The CBOR value to traverse
- * @param targetLevel - The depth level to collect (0 = root)
- * @returns Array of CBOR values at the target level
- *
- * @example
- * ```typescript
- * const structure = cbor([[1, 2], [3, 4]]);
- * const level1 = collectAtLevel(structure, 1);
- * // Returns: [[1, 2], [3, 4]]
- * const level2 = collectAtLevel(structure, 2);
- * // Returns: [1, 2, 3, 4]
- * ```
- */
-export const collectAtLevel = (cbor: Cbor, targetLevel: number): Cbor[] => {
-  interface CollectState {
-    items: Cbor[];
-  }
-
-  const result = walk<CollectState>(cbor, { items: [] }, (element, level, _edge, state) => {
-    if (level === targetLevel && element.type === "single") {
-      return [{ items: [...state.items, element.cbor] }, false];
-    }
-    return [state, false];
-  });
-
-  return result.items;
-};
-
-/**
- * Helper: Find first element matching a predicate.
- *
- * @template T - Type of extracted value
- * @param cbor - The CBOR value to search
- * @param predicate - Function to test each element
- * @returns First matching element, or undefined if not found
- *
- * @example
- * ```typescript
- * const structure = cbor({ users: [
- *   { name: 'Alice', age: 30 },
- *   { name: 'Bob', age: 25 }
- * ]});
- *
- * const bob = findFirst(structure, (element) => {
- *   if (element.type === 'single' &&
- *       element.cbor.type === MajorType.Text &&
- *       element.cbor.value === 'Bob') {
- *     return true;
- *   }
- *   return false;
- * });
- * ```
- */
-export const findFirst = (
-  cbor: Cbor,
-  predicate: (element: WalkElement) => boolean,
-): Cbor | undefined => {
-  interface FindState {
-    found?: Cbor;
-  }
-
-  const result = walk<FindState>(cbor, {}, (element, _level, _edge, state) => {
-    if (state.found !== undefined) {
-      // Already found, stop descending
-      return [state, true];
-    }
-
-    if (predicate(element)) {
-      if (element.type === "single") {
-        return [{ found: element.cbor }, true]; // Stop after finding
-      }
-      // Matched but not a single element, stop anyway
-      return [state, true];
-    }
-
-    return [state, false];
-  });
-
-  return result.found;
-};
-
-/**
- * Helper: Collect all text strings in a CBOR tree.
- *
- * @param cbor - The CBOR value to traverse
- * @returns Array of all text string values found
- *
- * @example
- * ```typescript
- * const doc = cbor({
- *   title: 'Document',
- *   tags: ['urgent', 'draft'],
- *   author: { name: 'Alice' }
- * });
- *
- * const texts = collectAllText(doc);
- * // Returns: ['Document', 'urgent', 'draft', 'Alice']
- * ```
- */
-export const collectAllText = (cbor: Cbor): string[] => {
-  interface TextState {
-    texts: string[];
-  }
-
-  const result = walk<TextState>(cbor, { texts: [] }, (element, _level, _edge, state) => {
-    if (element.type === "single" && element.cbor.type === MajorType.Text) {
-      return [{ texts: [...state.texts, element.cbor.value] }, false];
-    }
-    return [state, false];
-  });
-
-  return result.texts;
-};
-
-/**
- * Helper: Get the maximum depth of a CBOR tree.
- *
- * @param cbor - The CBOR value to measure
- * @returns Maximum depth (0 for leaf values, 1+ for containers)
- *
- * @example
- * ```typescript
- * const flat = cbor([1, 2, 3]);
- * console.log(maxDepth(flat)); // 1
- *
- * const nested = cbor([[[1]]]);
- * console.log(maxDepth(nested)); // 3
- * ```
- */
-export const maxDepth = (cbor: Cbor): number => {
-  interface DepthState {
-    maxDepth: number;
-  }
-
-  const result = walk<DepthState>(cbor, { maxDepth: 0 }, (_element, level, _edge, state) => {
-    const newMaxDepth = Math.max(state.maxDepth, level);
-    return [{ maxDepth: newMaxDepth }, false];
-  });
-
-  return result.maxDepth;
-};