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

package/src/walk.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Tree traversal system for CBOR data structures.
  *
  * This module provides a visitor pattern implementation for traversing
@@ -125,16 +129,18 @@ export const asKeyValue = (element: WalkElement): [Cbor, Cbor] | undefined => {
 };
 
 /**
- * Visitor function type with state threading.
+ * Visitor function type.
  *
- * @template State - The type of state passed through the traversal
+ * @template State - The type of state passed into each visit
  * @param element - The element being visited
  * @param level - The depth level in the tree (0 = root)
  * @param edge - Information about the edge leading to this element
- * @param state - Current state value
+ * @param state - The state value cloned from the parent visit
  * @returns Tuple of [newState, stopDescent] where:
- *   - newState: The updated state to pass to subsequent visits
- *   - stopDescent: If true, don't descend into children of this element
+ *   - newState: The state to pass into descendants of this element. Each
+ *     descendant receives an independent clone of `newState`; sibling
+ *     subtrees do *not* see each other's mutations.
+ *   - stopDescent: If true, do not descend into children of this element.
  */
 export type Visitor<State> = (
   element: WalkElement,
@@ -143,57 +149,47 @@ export type Visitor<State> = (
   state: State,
 ) => [State, boolean];
 
+/**
+ * Clone helper used to give each descendant subtree an independent copy of
+ * the post-visit state — mirrors Rust `State: Clone` + `state.clone()` per
+ * child in `walk.rs`. Falls back to the value as-is for primitives (which
+ * don't need cloning) and uses `structuredClone` for objects.
+ */
+const cloneState = <S>(s: S): S => {
+  if (s === null) return s;
+  const t = typeof s;
+  if (t !== "object" && t !== "function") return s;
+  // `structuredClone` is a host-provided global available in modern Node
+  // (≥ 17) and every modern browser; declare it inline so eslint's
+  // `no-undef` is satisfied without a project-wide globals declaration.
+  return (globalThis as { structuredClone(v: unknown): unknown }).structuredClone(s) as S;
+};
+
 /**
  * Walk a CBOR tree, visiting each element with a visitor function.
  *
  * The visitor function is called for each element in the tree, in depth-first order.
- * State is threaded through the traversal, allowing accumulation of results.
+ * State semantics mirror Rust's `walk_internal`:
+ *
+ * - The visitor's returned `newState` propagates **down** to descendants of
+ *   the just-visited node only.
+ * - Sibling subtrees each receive an independent clone of the parent's
+ *   post-visit state, so accumulating mutations in one subtree never leak
+ *   into a sibling.
+ * - State changes do not propagate **up**: the public `walk` returns `void`.
  *
  * For maps, the visitor is called with:
  * 1. A 'keyvalue' element containing both key and value
  * 2. The key individually (if descent wasn't stopped)
  * 3. The value individually (if descent wasn't stopped)
  *
- * @template State - The type of state to thread through the traversal
+ * @template State - The type of state to pass into each visit
  * @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 }
- *
- * const structure = cbor({ name: 'Alice', tags: ['urgent', 'draft'] });
- * const result = walk(structure, { count: 0 }, (element, level, edge, state) => {
- *   if (element.type === 'single' && element.cbor.type === MajorType.Text) {
- *     return [{ count: state.count + 1 }, false];
- *   }
- *   return [state, false];
- * });
- * console.log(result.count); // 3 (name, urgent, draft)
- * ```
- *
- * @example
- * ```typescript
- * // Find first occurrence and stop
- * const structure = cbor([1, 2, 3, 'found', 5, 6]);
- * let found = false;
- *
- * walk(structure, null, (element, level, edge) => {
- *   if (element.type === 'single' &&
- *       element.cbor.type === MajorType.Text &&
- *       element.cbor.value === 'found') {
- *     found = true;
- *     return [null, true]; // Stop descending
- *   }
- *   return [null, false];
- * });
- * ```
  */
-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);
 };
 
 /**
@@ -207,62 +203,43 @@ function walkInternal<State>(
   edge: EdgeTypeVariant,
   state: State,
   visitor: Visitor<State>,
-  skipVisit = false,
-): State {
-  let currentState = state;
-  let stopDescent = false;
-
-  // Visit the current element (unless skipVisit is true)
-  if (!skipVisit) {
-    const element: WalkElement = { type: "single", cbor };
-    const [newState, stop] = visitor(element, level, edge, currentState);
-    currentState = newState;
-    stopDescent = stop;
-
-    // If visitor says to stop descending, return immediately
-    if (stopDescent) {
-      return currentState;
-    }
-  }
-
-  // Recursively visit children based on CBOR type
-  // Only container types (Array, Map, Tagged) need special handling; leaf nodes use default
+): void {
+  // Visit the current element.
+  const element: WalkElement = { type: "single", cbor };
+  const [postVisitState, stop] = visitor(element, level, edge, state);
+  if (stop) return;
+
+  // Recursively visit children based on CBOR type. Each child receives an
+  // independent clone of `postVisitState`, matching Rust `state.clone()`.
   // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
   switch (cbor.type) {
     case MajorType.Array:
-      currentState = walkArray(cbor, level, currentState, visitor);
+      walkArray(cbor, level, postVisitState, visitor);
       break;
-
     case MajorType.Map:
-      currentState = walkMap(cbor, level, currentState, visitor);
+      walkMap(cbor, level, postVisitState, visitor);
       break;
-
     case MajorType.Tagged:
-      currentState = walkTagged(cbor, level, currentState, visitor);
+      walkTagged(cbor, level, postVisitState, visitor);
       break;
-
-    // Leaf nodes: Unsigned, Negative, Bytes, Text, Simple
     default:
-      // No children to visit
+      // Leaf nodes (Unsigned, Negative, Bytes, Text, Simple) have no children.
       break;
   }
-
-  return currentState;
 }
 
 /**
- * Walk an array's elements.
+ * Walk an array's elements. Each element is visited with an independent
+ * clone of `parentState`.
  *
  * @internal
  */
 function walkArray<State>(
   cbor: CborArrayType,
   level: number,
-  state: State,
+  parentState: State,
   visitor: Visitor<State>,
-): State {
-  let currentState = state;
-
+): void {
   for (let index = 0; index < cbor.value.length; index++) {
     const item = cbor.value[index];
     if (item === undefined) {
@@ -271,246 +248,65 @@ function walkArray<State>(
         message: `Array element at index ${index} is undefined`,
       });
     }
-    currentState = walkInternal(
+    walkInternal(
       item,
       level + 1,
       { type: EdgeType.ArrayElement, index },
-      currentState,
+      cloneState(parentState),
       visitor,
     );
   }
-
-  return currentState;
 }
 
 /**
  * Walk a map's key-value pairs.
  *
- * For each entry:
- * 1. Visit the key-value pair as a semantic unit
- * 2. If not stopped, visit the key individually
- * 3. If not stopped, visit the value individually
+ * Each kv pair receives a clone of `parentState`. If descent isn't stopped,
+ * the key and value subtrees receive independent clones of the kv-visit's
+ * post-visit state.
  *
  * @internal
  */
 function walkMap<State>(
   cbor: CborMapType,
   level: number,
-  state: State,
+  parentState: State,
   visitor: Visitor<State>,
-): State {
-  let currentState = state;
-
+): void {
   for (const entry of cbor.value.entriesArray) {
     const { key, value } = entry;
 
-    // First, visit the key-value pair as a semantic unit
     const kvElement: WalkElement = { type: "keyvalue", key, value };
-    const [kvState, kvStop] = visitor(
+    const [kvPostState, kvStop] = visitor(
       kvElement,
       level + 1,
       { type: EdgeType.MapKeyValue },
-      currentState,
+      cloneState(parentState),
     );
-    currentState = kvState;
+    if (kvStop) continue;
 
-    // If not stopped, visit key and value individually
-    if (!kvStop) {
-      currentState = walkInternal(key, level + 1, { type: EdgeType.MapKey }, currentState, visitor);
-
-      currentState = walkInternal(
-        value,
-        level + 1,
-        { type: EdgeType.MapValue },
-        currentState,
-        visitor,
-      );
-    }
+    walkInternal(key, level + 1, { type: EdgeType.MapKey }, cloneState(kvPostState), visitor);
+    walkInternal(value, level + 1, { type: EdgeType.MapValue }, cloneState(kvPostState), visitor);
   }
-
-  return currentState;
 }
 
 /**
- * Walk a tagged value's content.
+ * Walk a tagged value's content. The content visit receives a clone of
+ * `parentState`.
  *
  * @internal
  */
 function walkTagged<State>(
   cbor: CborTaggedType,
   level: number,
-  state: State,
+  parentState: State,
   visitor: Visitor<State>,
-): State {
-  return walkInternal(cbor.value, level + 1, { type: EdgeType.TaggedContent }, state, visitor);
+): void {
+  walkInternal(
+    cbor.value,
+    level + 1,
+    { type: EdgeType.TaggedContent },
+    cloneState(parentState),
+    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;
-};