@rethinkhealth/hl7v2-util-visit 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rethink Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,498 @@
+# @rethinkhealth/hl7v2-util-visit
+
+## Introduction
+
+This package provides a lightweight, type-safe visitor pattern for traversing [HL7v2 AST][hl7v2-ast] trees. It implements a pure functional approach inspired by [unist-util-visit-parents][] and [babel-traverse][], offering immutable path tracking with rich metadata.
+
+### What is this?
+
+`hl7v2-visitor` enables you to walk through any HL7v2 AST tree — from the root message down to individual subcomponents — with full context about where you are in the hierarchy. The visitor pattern:
+
+- **Works from any starting node** (Root, Segment, Field, Component, etc.)
+- **Tracks immutable paths** from traversal root to current node
+- **Provides rich metadata** (segment headers, group names, delimiters)
+- **Immutable path copies** — New path array created per level via spread operator
+- **Minimal allocations** — Metadata extracted once per node, path arrays reused within same level
+
+### When should I use this?
+
+Use `hl7v2-visitor` when you need to:
+
+- Validate HL7v2 message structure
+- Transform or annotate AST nodes
+- Extract specific fields with context
+- Analyze message patterns across the tree
+- Implement custom processing rules that need parent/ancestor awareness
+
+## Install
+
+```sh
+npm install @rethinkhealth/hl7v2-util-visit
+```
+
+## Use
+
+```typescript
+import { visit } from '@rethinkhealth/hl7v2-util-visit';
+import { parse } from '@rethinkhealth/hl7v2-parser'; // hypothetical parser
+
+const message = parse('MSH|^~\\&|...\rPID|...');
+
+// Visit all segments
+visit(message, 'segment', (node, path) => {
+  const entry = path.at(-1);
+  console.log(`Segment: ${entry?.data?.header} at level ${entry?.level}`);
+});
+// => Segment: MSH at level 2
+// => Segment: PID at level 2
+
+// Find fields with parent context
+visit(message, 'field', (node, path) => {
+  const segment = path.find(e => e.type === 'segment');
+  console.log(`Field in ${segment?.data?.header}`);
+});
+
+// Skip processing of sensitive segments
+visit(message, (node, path) => {
+  if (node.type === 'segment' && node.children[0]?.value === 'NTE') {
+    return 'skip'; // Skip NTE segment children
+  }
+  // Process other nodes
+});
+```
+
+## API
+
+### `visit(tree, visitor)`
+
+### `visit(tree, test, visitor)`
+
+Visit nodes in an HL7v2 AST tree.
+
+#### Parameters
+
+- **`tree`** (`Nodes`) — Tree to traverse (can be any node type, not just Root)
+- **`test`** (`string | Partial<Nodes> | Test`) — Optional filter:
+  - `string`: Match nodes by type (e.g., `'segment'`)
+  - `Partial<Nodes>`: Match nodes with matching properties (e.g., `{ name: 'PATIENT_GROUP' }`)
+  - `Test`: Custom function `(node, path) => boolean`
+- **`visitor`** (`Visitor`) — Function called for each matching node
+
+#### Returns
+
+`void`
+
+#### Important: Test vs Visitor Functions
+
+**If you pass a function as the second argument, it is always treated as a Visitor, never as a Test.**
+
+```typescript
+// ❌ WRONG - testFn will be treated as a visitor, not a test
+visit(ast, (node, path) => node.type === 'segment', ...); // Missing visitor!
+
+// ✅ CORRECT - Explicit 3-argument form
+visit(ast, (node, path) => node.type === 'segment', (node, path) => {
+  console.log('Visiting segment');
+});
+
+// ✅ CORRECT - Use string or object for simple tests
+visit(ast, 'segment', (node, path) => {
+  console.log('Visiting segment');
+});
+```
+
+This design prevents runtime errors that could occur after side effects. Since Test and Visitor functions have the same signature but different return types, they cannot be distinguished at compile time.
+
+#### Visitor Function
+
+```typescript
+type Visitor = (node: Nodes, path: Path) => Action | void | undefined;
+```
+
+The visitor receives:
+- **`node`** — Current AST node
+- **`path`** — Ordered array of `PathEntry` from traversal root to current node
+
+The visitor can return:
+- `undefined` or `void` — Continue traversal normally
+- `'skip'` — Skip children of current node
+- `'exit'` — Stop traversal immediately
+
+## Path Structure
+
+Each entry in the `path` array has the following structure:
+
+```typescript
+interface PathEntry {
+  type: string;          // Node type: 'root', 'segment', 'field', 'component', etc.
+  level: number;         // 1-based depth (root=1, children=2, ...)
+  index: number;         // 1-based position within siblings
+  node: Nodes;           // Reference to the actual AST node
+  data?: Record<string, unknown>; // Extensible metadata
+}
+```
+
+### Automatic Metadata Extraction
+
+The `data` field is populated automatically with common metadata:
+
+| Node Type | Metadata Key | Description |
+|-----------|--------------|-------------|
+| `segment` | `header` | Segment identifier (e.g., `"MSH"`, `"PID"`) |
+| `group` | `name` | Group name (e.g., `"PATIENT_GROUP"`) |
+
+Example:
+
+```typescript
+visit(ast, 'segment', (node, path) => {
+  const entry = path.at(-1);
+  console.log(entry?.data?.header); // "PID"
+});
+```
+
+## Examples
+
+### Filter by Node Type
+
+```typescript
+// Visit all segments
+visit(ast, 'segment', (node, path) => {
+  console.log(`Found segment: ${node.children[0]?.value}`);
+});
+```
+
+### Filter by Properties
+
+```typescript
+// Visit specific group
+visit(ast, { name: 'PATIENT_GROUP' }, (node, path) => {
+  console.log('Inside PATIENT_GROUP');
+});
+```
+
+### Custom Test Function
+
+```typescript
+// Visit fields in MSH segment only
+visit(
+  ast,
+  (node, path) => {
+    const parent = path[path.length - 2];
+    return node.type === 'field' && parent?.data?.header === 'MSH';
+  },
+  (node, path) => {
+    console.log('MSH field found');
+  }
+);
+```
+
+### Access Parent and Ancestors
+
+```typescript
+visit(ast, 'component', (node, path) => {
+  // Get immediate parent
+  const parent = path[path.length - 2];
+
+  // Get all ancestors
+  const ancestors = path.slice(0, -1);
+
+  // Find closest segment
+  const segment = path.findLast(e => e.type === 'segment');
+  console.log(`Component in ${segment?.data?.header}`);
+});
+```
+
+### Control Flow: Skip Children
+
+```typescript
+visit(ast, (node, path) => {
+  if (node.type === 'segment' && node.children[0]?.value === 'OBX') {
+    return 'skip'; // Don't process OBX segment children
+  }
+});
+```
+
+### Control Flow: Exit Early
+
+```typescript
+let found = false;
+visit(ast, 'field', (node, path) => {
+  if (/* some condition */) {
+    found = true;
+    return 'exit'; // Stop traversal completely
+  }
+});
+```
+
+### Start from Any Node
+
+```typescript
+import { s, f, c } from '@rethinkhealth/hl7v2-builder';
+
+// Create a standalone segment
+const segment = s('PID', f(c('value1')), f(c('value2')));
+
+// Traverse from segment (not root)
+visit(segment, 'field', (node, path) => {
+  // path[0] will be the segment, not a root node
+  console.log(`Field at index ${path.at(-1)?.index}`);
+});
+```
+
+### Track Nesting Levels
+
+```typescript
+visit(ast, (node, path) => {
+  const entry = path.at(-1);
+  const indent = '  '.repeat(entry!.level - 1);
+  console.log(`${indent}${entry!.type} [${entry!.index}]`);
+});
+// Output:
+// root [1]
+//   segment [1]
+//     field [2]
+//       field-repetition [1]
+//         component [1]
+```
+
+### Group Hierarchy Navigation
+
+```typescript
+visit(ast, 'segment', (node, path) => {
+  // Get all parent groups
+  const groups = path
+    .filter(e => e.type === 'group')
+    .map(e => e.data?.name)
+    .filter((name): name is string => typeof name === 'string');
+
+  const segmentHeader = path.at(-1)?.data?.header;
+  console.log(`${segmentHeader} is in groups: ${groups.join(' > ')}`);
+});
+// => PID is in groups: PATIENT_GROUP
+```
+
+## Real-World Use Cases
+
+### Validate Required Fields
+
+```typescript
+import { visit } from '@rethinkhealth/hl7v2-util-visit';
+
+function validateRequiredFields(ast: Root): string[] {
+  const errors: string[] = [];
+
+  visit(ast, 'segment', (node, path) => {
+    const segment = node as Segment;
+    const header = segment.children[0]?.value;
+
+    // MSH segment must have at least 12 fields
+    if (header === 'MSH' && segment.children.length < 12) {
+      errors.push(`MSH segment missing required fields (found ${segment.children.length - 1})`);
+    }
+
+    // PID segment must have patient ID (PID.3)
+    if (header === 'PID') {
+      const patientId = segment.children[3]; // Remember: 1-based, [0] is header
+      if (!patientId || patientId.children.length === 0) {
+        errors.push('PID segment missing required Patient ID (PID.3)');
+      }
+    }
+  });
+
+  return errors;
+}
+```
+
+### Extract Specific Data with Context
+
+```typescript
+// Extract all patient names with their segment location
+interface PatientName {
+  name: string;
+  segmentIndex: number;
+  inGroup?: string;
+}
+
+function extractPatientNames(ast: Root): PatientName[] {
+  const names: PatientName[] = [];
+
+  visit(ast, 'segment', (node, path) => {
+    const segment = node as Segment;
+    const header = segment.children[0]?.value;
+
+    if (header === 'PID') {
+      // PID.5 is patient name
+      const nameField = segment.children[5];
+      if (nameField?.children[0]?.children[0]) {
+        const nameComponent = nameField.children[0].children[0];
+        const name = (nameComponent.children[0] as Subcomponent)?.value || '';
+
+        // Get segment's position in parent
+        const segmentEntry = path.at(-1);
+
+        // Check if inside a group
+        const groupEntry = path.find(e => e.type === 'group');
+
+        names.push({
+          name,
+          segmentIndex: segmentEntry?.index || 0,
+          inGroup: groupEntry?.data?.name as string | undefined,
+        });
+      }
+    }
+  });
+
+  return names;
+}
+```
+
+### Message Structure Analysis
+
+```typescript
+// Analyze message structure and generate a summary
+interface MessageStructure {
+  segmentCount: number;
+  groupCount: number;
+  maxDepth: number;
+  segmentTypes: Record<string, number>;
+}
+
+function analyzeStructure(ast: Root): MessageStructure {
+  const structure: MessageStructure = {
+    segmentCount: 0,
+    groupCount: 0,
+    maxDepth: 0,
+    segmentTypes: {},
+  };
+
+  visit(ast, (node, path) => {
+    const entry = path.at(-1);
+
+    // Track max depth
+    if (entry && entry.level > structure.maxDepth) {
+      structure.maxDepth = entry.level;
+    }
+
+    // Count segments and types
+    if (node.type === 'segment') {
+      structure.segmentCount++;
+      const header = entry?.data?.header as string;
+      if (header) {
+        structure.segmentTypes[header] = (structure.segmentTypes[header] || 0) + 1;
+      }
+    }
+
+    // Count groups
+    if (node.type === 'group') {
+      structure.groupCount++;
+    }
+  });
+
+  return structure;
+}
+```
+
+### Remove Sensitive Data
+
+```typescript
+// Redact sensitive fields (like SSN in PID.19)
+function redactSensitiveData(ast: Root): void {
+  visit(ast, 'segment', (node) => {
+    const segment = node as Segment;
+    const header = segment.children[0]?.value;
+
+    if (header === 'PID') {
+      // Redact SSN (PID.19)
+      const ssnField = segment.children[19];
+      if (ssnField?.children[0]?.children[0]?.children[0]) {
+        const subcomponent = ssnField.children[0].children[0].children[0];
+        if (subcomponent.type === 'subcomponent') {
+          subcomponent.value = '***-**-****';
+        }
+      }
+    }
+
+    // Continue traversal but don't skip - we might need to redact multiple segments
+  });
+}
+```
+
+### Performance: Early Exit Optimization
+
+```typescript
+// Find first occurrence of a specific observation and exit
+function findFirstObservation(ast: Root, targetCode: string): string | null {
+  let result: string | null = null;
+
+  visit(ast, 'segment', (node) => {
+    const segment = node as Segment;
+    const header = segment.children[0]?.value;
+
+    if (header === 'OBX') {
+      // OBX.3 is observation identifier
+      const identifierField = segment.children[3];
+      const code = identifierField?.children[0]?.children[0]?.children[0]?.value;
+
+      if (code === targetCode) {
+        // OBX.5 is observation value
+        const valueField = segment.children[5];
+        result = valueField?.children[0]?.children[0]?.children[0]?.value || null;
+
+        // Exit immediately - we found what we need
+        return 'exit';
+      }
+    }
+  });
+
+  return result;
+}
+```
+
+## Types
+
+This package exports the following TypeScript types:
+
+```typescript
+export type {
+  Action,        // 'skip' | 'exit'
+  ChildProvider, // (node: Nodes) => Nodes[] | undefined
+  Path,          // readonly PathEntry[]
+  PathEntry,     // { type, level, index, node, data? }
+  Test,          // (node: Nodes, path: Path) => boolean
+  Visitor,       // (node: Nodes, path: Path) => Action | void | undefined
+} from '@rethinkhealth/hl7v2-util-visit';
+```
+
+## Performance Characteristics
+
+- **O(n) traversal** — Single pass through all nodes
+- **O(d) path construction** where d = depth (typically < 10 for HL7v2 messages)
+- **Zero defensive copying** — Paths reference the same array during visitor calls
+- **Minimal allocations** — Metadata extracted once per node
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Code of Conduct
+
+To ensure a welcoming and positive environment, we have a [Code of Conduct][github-code-of-conduct] that all contributors and participants are expected to adhere to.
+
+## License
+
+Copyright 2025 Rethink Health, SUARL. All rights reserved.
+
+This program is licensed to you under the terms of the [MIT License](https://opensource.org/licenses/MIT). This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [LICENSE][github-license] file for details.
+
+[github-code-of-conduct]: https://github.com/rethinkhealth/hl7v2/blob/main/CODE_OF_CONDUCT.md
+[github-license]: https://github.com/rethinkhealth/hl7v2/blob/main/LICENSE
+[github-contributing]: https://github.com/rethinkhealth/hl7v2/blob/main/CONTRIBUTING.md
+[hl7v2-ast]: https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-ast
+[unist-util-visit-parents]: https://github.com/syntax-tree/unist-util-visit-parents
+[babel-traverse]: https://github.com/babel/babel/tree/main/packages/babel-traverse

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Nodes } from "@rethinkhealth/hl7v2-ast";
+import type { Action, Test, Visitor } from "./types";
+export type { Action, ChildProvider, Path, PathEntry, Test, Visitor, } from "./types";
+export declare const EXIT: Action;
+export declare const SKIP: Action;
+export declare function visit(tree: Nodes, visitor: Visitor): void;
+export declare function visit<Type extends Nodes["type"]>(tree: Nodes, test: Type, visitor: Visitor<Extract<Nodes, {
+    type: Type;
+}>>): void;
+export declare function visit<T extends Nodes>(tree: Nodes, test: Test<T>, visitor: Visitor<T>): void;

package/dist/index.js

@@ -0,0 +1,117 @@
+// src/traversal.ts
+function createTraversal(childProvider) {
+  return function traverse(root, visitor) {
+    function visit2(node, path, index, level) {
+      const entry = {
+        type: node.type,
+        level,
+        index,
+        node,
+        // Extract common metadata if available
+        data: extractMetadata(node)
+      };
+      const currentPath = [...path, entry];
+      const action = visitor(node, currentPath);
+      if (action === "exit") {
+        return "exit";
+      }
+      if (action === "skip") {
+        return;
+      }
+      const children = childProvider(node);
+      if (children?.length) {
+        for (let i = 0; i < children.length; i++) {
+          const child = children[i];
+          if (!child) {
+            continue;
+          }
+          const result = visit2(child, currentPath, i + 1, level + 1);
+          if (result === "exit") {
+            return "exit";
+          }
+        }
+      }
+      return;
+    }
+    visit2(root, [], 1, 1);
+  };
+}
+function extractMetadata(node) {
+  switch (node.type) {
+    case "group": {
+      if (node.name !== void 0) {
+        return { name: node.name };
+      }
+      return;
+    }
+    case "segment": {
+      const header = node.children[0];
+      if (header?.type === "segment-header") {
+        return { header: header.value };
+      }
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+// src/utils.ts
+function createTest(test) {
+  if (test === null) {
+    return () => true;
+  }
+  if (typeof test === "string") {
+    return (node) => node.type === test;
+  }
+  if (typeof test === "function") {
+    return test;
+  }
+  return (node) => {
+    for (const key of Object.keys(test)) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype") {
+        continue;
+      }
+      const testValue = test[key];
+      const nodeValue = node[key];
+      if (testValue === void 0) {
+        if (Object.hasOwn(node, key) && nodeValue !== void 0) {
+          return false;
+        }
+      } else if (nodeValue !== testValue) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+// src/index.ts
+var EXIT = "exit";
+var SKIP = "skip";
+function visit(tree, arg2, arg3) {
+  let test = null;
+  let visitor;
+  if (arg3 === void 0) {
+    visitor = arg2;
+  } else {
+    test = arg2;
+    visitor = arg3;
+  }
+  const predicate = createTest(test);
+  const childProvider = (node) => "children" in node && Array.isArray(node.children) ? node.children : void 0;
+  const traverse = createTraversal(childProvider);
+  const wrappedVisitor = (node, path) => {
+    if (predicate(node, path)) {
+      return visitor(node, path);
+    }
+    return;
+  };
+  traverse(tree, wrappedVisitor);
+}
+export {
+  EXIT,
+  SKIP,
+  visit
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/traversal.ts","../src/utils.ts","../src/index.ts"],"sourcesContent":["import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\nimport type { ChildProvider, Path, PathEntry, Visitor } from \"./types\";\n\n/**\n * Creates a traversal function with the given child provider.\n * Pure functional approach - no classes, no mutation.\n *\n * Assumptions:\n * - Uses 1-based indexing for compatibility with HL7v2 field numbering convention\n * - Level 1 is the traversal root node (not necessarily a Root node type)\n * - Path arrays are immutable - new array created at each level via spread operator\n * - undefined/null children are safely skipped\n *\n * @param childProvider - Function to extract children from nodes\n * @returns Traversal function\n */\nexport function createTraversal(childProvider: ChildProvider) {\n  /**\n   * Traverse the tree starting from root.\n   *\n   * @param root - Starting node (can be any node type, not just Root)\n   * @param visitor - Function called for each node\n   */\n  return function traverse(root: Nodes, visitor: Visitor): void {\n    /**\n     * Internal recursive function.\n     * Uses immutable path construction (concat) like unist-visit-parents.\n     *\n     * @param node - Current node\n     * @param path - Immutable path array from traversal root to parent\n     * @param index - 1-based index within siblings (HL7v2 convention: MSH.1, MSH.2, etc.)\n     * @param level - 1-based depth level (root=1, children=2, etc.)\n     * @returns Control flow action\n     */\n    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fine\n    function visit(\n      node: Nodes,\n      path: Path,\n      index: number,\n      level: number\n    ): \"exit\" | \"skip\" | undefined {\n      // Create path entry for current node\n      const entry: PathEntry = {\n        type: node.type,\n        level,\n        index,\n        node,\n        // Extract common metadata if available\n        data: extractMetadata(node),\n      };\n\n      // Immutable path extension (like unist-visit-parents)\n      const currentPath = [...path, entry];\n\n      // Call visitor with current node and full path\n      const action = visitor(node, currentPath);\n\n      // Handle exit immediately\n      if (action === \"exit\") {\n        return \"exit\";\n      }\n\n      // Skip children if requested\n      if (action === \"skip\") {\n        return;\n      }\n\n      // Traverse children unless skipped\n      const children = childProvider(node);\n      if (children?.length) {\n        for (let i = 0; i < children.length; i++) {\n          const child = children[i];\n          if (!child) {\n            continue;\n          }\n\n          const result = visit(child, currentPath, i + 1, level + 1);\n\n          if (result === \"exit\") {\n            return \"exit\";\n          }\n        }\n      }\n\n      return;\n    }\n\n    // Start traversal with empty path, index 1, level 1\n    visit(root, [], 1, 1);\n  };\n}\n\n/**\n * Extract common metadata from node.\n * Extensible - can add more fields as needed.\n *\n * @param node - AST node\n * @returns Metadata object or undefined\n */\nfunction extractMetadata(node: Nodes): Record<string, unknown> | undefined {\n  switch (node.type) {\n    case \"group\": {\n      if (node.name !== undefined) {\n        return { name: node.name };\n      }\n      return;\n    }\n\n    case \"segment\": {\n      const header = node.children[0];\n      if (header?.type === \"segment-header\") {\n        return { header: header.value };\n      }\n      return;\n    }\n\n    default:\n      return;\n  }\n}\n","import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\nimport type { Path, Test } from \"./types\";\n\n/**\n * Create test predicate from various input types.\n *\n * Assumptions:\n * - null test matches all nodes\n * - String test matches by node.type property\n * - Object test uses strict equality (===) for property matching\n * - Explicit undefined values in test object check for property absence\n * - Dangerous keys (__proto__, constructor, prototype) are filtered for security\n *\n * @param test - Filter criteria: null (all), string (type), object (properties), or function\n * @returns Predicate function that returns true if node matches test criteria\n */\nexport function createTest(\n  test: Test<Nodes>\n): (node: Nodes, path: Path) => boolean {\n  if (test === null) {\n    return () => true;\n  }\n  if (typeof test === \"string\") {\n    return (node) => node.type === test;\n  }\n  if (typeof test === \"function\") {\n    return test;\n  }\n  // Object property matching\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Property matching requires checking multiple conditions\n  return (node) => {\n    for (const key of Object.keys(test)) {\n      // Guard against prototype pollution\n      if (key === \"__proto__\" || key === \"constructor\" || key === \"prototype\") {\n        continue;\n      }\n\n      const testValue = test[key as keyof typeof test];\n      // biome-ignore lint/suspicious/noExplicitAny: Need to access arbitrary properties on node\n      const nodeValue = (node as any)[key];\n\n      // If test has explicit undefined, check property doesn't exist or is undefined\n      if (testValue === undefined) {\n        if (Object.hasOwn(node, key) && nodeValue !== undefined) {\n          return false;\n        }\n      } else if (nodeValue !== testValue) {\n        // For non-undefined values, strict equality check\n        return false;\n      }\n    }\n    return true;\n  };\n}\n","import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\nimport { createTraversal } from \"./traversal\";\nimport type { Action, Test, Visitor } from \"./types\";\nimport { createTest } from \"./utils\";\n\n// Export all types\nexport type {\n  Action,\n  ChildProvider,\n  Path,\n  PathEntry,\n  Test,\n  Visitor,\n} from \"./types\";\n\nexport const EXIT: Action = \"exit\" as const;\nexport const SKIP: Action = \"skip\" as const;\n\n// Overload signatures\nexport function visit(tree: Nodes, visitor: Visitor): void;\nexport function visit<Type extends Nodes[\"type\"]>(\n  tree: Nodes,\n  test: Type,\n  visitor: Visitor<Extract<Nodes, { type: Type }>>\n): void;\nexport function visit<T extends Nodes>(\n  tree: Nodes,\n  test: Test<T>,\n  visitor: Visitor<T>\n): void;\n\n/**\n * Visit nodes in an HL7 AST tree.\n * Pure functional implementation - no classes, no mutations.\n *\n * @param tree - The tree to traverse (can be any node type, not just Root)\n * @param test - Optional test to filter nodes (type string, partial match, or Test function)\n * @param visitor - Function called for each matching node\n *\n * @remarks\n * **Important**: If you pass a function as the second argument, it is always treated\n * as a Visitor, never as a Test. To use a Test function, you MUST provide both the\n * test and visitor parameters: `visit(tree, testFn, visitorFn)`.\n *\n * This design choice prevents runtime checks that could miss errors and cause side\n * effects before detection. Test and Visitor functions have the same signature but\n * different return types, making them indistinguishable without execution.\n *\n * Performance characteristics:\n * - O(n) time complexity - single depth-first traversal\n * - O(d) space for path where d = tree depth (typically <10 for HL7v2)\n * - Path arrays are created once per level via spread operator\n * - Metadata extracted lazily only when needed\n * - No defensive copying - paths reused during visitor execution\n */\nexport function visit<T extends Nodes>(\n  tree: Nodes,\n  arg2: Visitor<T> | Test<T>,\n  arg3?: Visitor<T>\n): void {\n  let test: Test<T> = null;\n  let visitor: Visitor<T>;\n\n  // Handle overloads - simple discrimination based on arg count\n  if (arg3 === undefined) {\n    // 2-argument form: visit(tree, visitor)\n    // Function assumed to be Visitor (not Test)\n    visitor = arg2 as Visitor<T>;\n  } else {\n    // 3-argument form: visit(tree, test, visitor)\n    test = arg2 as Test<T>;\n    visitor = arg3;\n  }\n\n  // Create test predicate\n  const predicate = createTest(test as Test<Nodes>);\n\n  // Create child provider\n  const childProvider = (node: Nodes) =>\n    \"children\" in node && Array.isArray(node.children)\n      ? (node.children as Nodes[])\n      : undefined;\n\n  // Create traversal function\n  const traverse = createTraversal(childProvider);\n\n  // Wrap visitor to apply test\n  const wrappedVisitor: Visitor = (node, path) => {\n    if (predicate(node, path)) {\n      return visitor(node as T, path);\n    }\n    return;\n  };\n\n  // Start traversal\n  traverse(tree, wrappedVisitor);\n}\n"],"mappings":";AAgBO,SAAS,gBAAgB,eAA8B;AAO5D,SAAO,SAAS,SAAS,MAAa,SAAwB;AAY5D,aAASA,OACP,MACA,MACA,OACA,OAC6B;AAE7B,YAAM,QAAmB;AAAA,QACvB,MAAM,KAAK;AAAA,QACX;AAAA,QACA;AAAA,QACA;AAAA;AAAA,QAEA,MAAM,gBAAgB,IAAI;AAAA,MAC5B;AAGA,YAAM,cAAc,CAAC,GAAG,MAAM,KAAK;AAGnC,YAAM,SAAS,QAAQ,MAAM,WAAW;AAGxC,UAAI,WAAW,QAAQ;AACrB,eAAO;AAAA,MACT;AAGA,UAAI,WAAW,QAAQ;AACrB;AAAA,MACF;AAGA,YAAM,WAAW,cAAc,IAAI;AACnC,UAAI,UAAU,QAAQ;AACpB,iBAAS,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;AACxC,gBAAM,QAAQ,SAAS,CAAC;AACxB,cAAI,CAAC,OAAO;AACV;AAAA,UACF;AAEA,gBAAM,SAASA,OAAM,OAAO,aAAa,IAAI,GAAG,QAAQ,CAAC;AAEzD,cAAI,WAAW,QAAQ;AACrB,mBAAO;AAAA,UACT;AAAA,QACF;AAAA,MACF;AAEA;AAAA,IACF;AAGA,IAAAA,OAAM,MAAM,CAAC,GAAG,GAAG,CAAC;AAAA,EACtB;AACF;AASA,SAAS,gBAAgB,MAAkD;AACzE,UAAQ,KAAK,MAAM;AAAA,IACjB,KAAK,SAAS;AACZ,UAAI,KAAK,SAAS,QAAW;AAC3B,eAAO,EAAE,MAAM,KAAK,KAAK;AAAA,MAC3B;AACA;AAAA,IACF;AAAA,IAEA,KAAK,WAAW;AACd,YAAM,SAAS,KAAK,SAAS,CAAC;AAC9B,UAAI,QAAQ,SAAS,kBAAkB;AACrC,eAAO,EAAE,QAAQ,OAAO,MAAM;AAAA,MAChC;AACA;AAAA,IACF;AAAA,IAEA;AACE;AAAA,EACJ;AACF;;;ACvGO,SAAS,WACd,MACsC;AACtC,MAAI,SAAS,MAAM;AACjB,WAAO,MAAM;AAAA,EACf;AACA,MAAI,OAAO,SAAS,UAAU;AAC5B,WAAO,CAAC,SAAS,KAAK,SAAS;AAAA,EACjC;AACA,MAAI,OAAO,SAAS,YAAY;AAC9B,WAAO;AAAA,EACT;AAGA,SAAO,CAAC,SAAS;AACf,eAAW,OAAO,OAAO,KAAK,IAAI,GAAG;AAEnC,UAAI,QAAQ,eAAe,QAAQ,iBAAiB,QAAQ,aAAa;AACvE;AAAA,MACF;AAEA,YAAM,YAAY,KAAK,GAAwB;AAE/C,YAAM,YAAa,KAAa,GAAG;AAGnC,UAAI,cAAc,QAAW;AAC3B,YAAI,OAAO,OAAO,MAAM,GAAG,KAAK,cAAc,QAAW;AACvD,iBAAO;AAAA,QACT;AAAA,MACF,WAAW,cAAc,WAAW;AAElC,eAAO;AAAA,MACT;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACF;;;ACtCO,IAAM,OAAe;AACrB,IAAM,OAAe;AAuCrB,SAAS,MACd,MACA,MACA,MACM;AACN,MAAI,OAAgB;AACpB,MAAI;AAGJ,MAAI,SAAS,QAAW;AAGtB,cAAU;AAAA,EACZ,OAAO;AAEL,WAAO;AACP,cAAU;AAAA,EACZ;AAGA,QAAM,YAAY,WAAW,IAAmB;AAGhD,QAAM,gBAAgB,CAAC,SACrB,cAAc,QAAQ,MAAM,QAAQ,KAAK,QAAQ,IAC5C,KAAK,WACN;AAGN,QAAM,WAAW,gBAAgB,aAAa;AAG9C,QAAM,iBAA0B,CAAC,MAAM,SAAS;AAC9C,QAAI,UAAU,MAAM,IAAI,GAAG;AACzB,aAAO,QAAQ,MAAW,IAAI;AAAA,IAChC;AACA;AAAA,EACF;AAGA,WAAS,MAAM,cAAc;AAC/B;","names":["visit"]}

package/dist/traversal.d.ts

@@ -0,0 +1,16 @@
+import type { Nodes } from "@rethinkhealth/hl7v2-ast";
+import type { ChildProvider, Visitor } from "./types";
+/**
+ * Creates a traversal function with the given child provider.
+ * Pure functional approach - no classes, no mutation.
+ *
+ * Assumptions:
+ * - Uses 1-based indexing for compatibility with HL7v2 field numbering convention
+ * - Level 1 is the traversal root node (not necessarily a Root node type)
+ * - Path arrays are immutable - new array created at each level via spread operator
+ * - undefined/null children are safely skipped
+ *
+ * @param childProvider - Function to extract children from nodes
+ * @returns Traversal function
+ */
+export declare function createTraversal(childProvider: ChildProvider): (root: Nodes, visitor: Visitor) => void;

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+import type { Nodes } from "@rethinkhealth/hl7v2-ast";
+/**
+ * A single entry in the traversal path.
+ * Simple, generic structure that works for any node type.
+ */
+export type PathEntry = {
+    /** Type of the node (e.g., 'root', 'segment', 'field', 'component') */
+    type: string;
+    /** 1-based depth level in the tree (root = 1, its children = 2, etc.) */
+    level: number;
+    /** 1-based index within siblings at the same level */
+    index: number;
+    /** Reference to the actual node */
+    node: Nodes;
+    /** Extensible data object for custom metadata */
+    data?: Record<string, unknown>;
+};
+/**
+ * Ordered array of path entries from root to current node.
+ * Pure data structure - just an array.
+ */
+export type Path = readonly PathEntry[];
+/**
+ * Control flow actions for traversal.
+ */
+export type Action = "skip" | "exit";
+/**
+ * A function called for each node during traversal.
+ *
+ * @param node - Current node being visited
+ * @param path - Ordered array of PathEntry from traversal root to current node
+ * @returns Action to control traversal flow, or void/undefined to continue normally
+ */
+export type Visitor<T extends Nodes = Nodes> = (node: T, path: Path) => Action | void | undefined;
+/**
+ * Function that returns children of a node.
+ */
+export type ChildProvider = (node: Nodes) => Nodes[] | undefined;
+/**
+ * Filter criteria to determine which nodes to visit.
+ *
+ * Can be:
+ * - string: matches `node.type`
+ * - object: matches properties (partial match)
+ * - function: predicate returning boolean or type guard
+ * - null: matches everything
+ */
+export type Test<T extends Nodes = Nodes> = string | Partial<T> | ((node: Nodes, path: Path) => node is T) | ((node: Nodes, path: Path) => boolean) | null;

package/dist/utils.d.ts

@@ -0,0 +1,16 @@
+import type { Nodes } from "@rethinkhealth/hl7v2-ast";
+import type { Path, Test } from "./types";
+/**
+ * Create test predicate from various input types.
+ *
+ * Assumptions:
+ * - null test matches all nodes
+ * - String test matches by node.type property
+ * - Object test uses strict equality (===) for property matching
+ * - Explicit undefined values in test object check for property absence
+ * - Dangerous keys (__proto__, constructor, prototype) are filtered for security
+ *
+ * @param test - Filter criteria: null (all), string (type), object (properties), or function
+ * @returns Predicate function that returns true if node matches test criteria
+ */
+export declare function createTest(test: Test<Nodes>): (node: Nodes, path: Path) => boolean;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rethinkhealth/hl7v2-util-visit",
+  "description": "An AST visitor for HL7v2 messages",
+  "version": "0.3.4",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "@vitest/coverage-v8": "^4.0.5",
+    "tsup": "8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.6",
+    "@rethinkhealth/hl7v2-ast": "0.3.4",
+    "@rethinkhealth/hl7v2-builder": "0.3.4",
+    "@rethinkhealth/testing": "0.0.2",
+    "@rethinkhealth/tsconfig": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": "rethinkhealth/hl7v2.git",
+  "homepage": "https://www.rethinkhealth.io/hl7v2/docs",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript"
+  ],
+  "packageManager": "pnpm@10.14.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}