@glion/util-visit 0.14.1

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,486 @@
+# @glion/util-visit
+
+## Introduction
+
+This package provides a lightweight, type-safe visitor pattern for traversing [HL7v2 AST][hl7v2-ast] trees. Built on top of the battle-tested [unist-util-visit-parents][], it adds HL7v2-specific context while delegating core traversal to a proven implementation.
+
+### What is this?
+
+`hl7v2-util-visit` 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 ancestors** from traversal root to current node
+- **Provides visit info** (index, sequence, depth, metadata)
+- **Efficient O(n) traversal** — Pre-computed index map for O(1) lookups
+- **Battle-tested core** — Delegates traversal to `unist-util-visit-parents`
+
+### When should I use this?
+
+Use `hl7v2-util-visit` 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 @glion/util-visit
+```
+
+## Use
+
+```typescript
+import { visit, EXIT, SKIP } from "@glion/util-visit";
+import { parse } from "@glion/parser";
+
+const message = parse("MSH|^~\\&|...\rPID|...");
+
+// Visit all segments
+visit(message, "segment", (node, ancestors, info) => {
+  console.log(`Segment: ${info.metadata?.header} at depth ${info.depth}`);
+});
+// => Segment: MSH at depth 2
+// => Segment: PID at depth 2
+
+// Find fields with parent context
+visit(message, "field", (node, ancestors, info) => {
+  const segment = ancestors.find((n) => n.type === "segment");
+  console.log(`Field ${info.sequence} in segment`);
+});
+
+// Skip processing of sensitive segments
+visit(message, (node, ancestors, info) => {
+  if (node.type === "segment" && info.metadata?.header === "NTE") {
+    return SKIP; // Skip NTE segment children
+  }
+});
+```
+
+## 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, ancestors) => 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) => node.type === 'segment', ...); // Missing visitor!
+
+// CORRECT - Explicit 3-argument form
+visit(ast, (node) => node.type === 'segment', (node, ancestors, info) => {
+  console.log('Visiting segment');
+});
+
+// CORRECT - Use string or object for simple tests
+visit(ast, 'segment', (node, ancestors, info) => {
+  console.log('Visiting segment');
+});
+```
+
+#### Visitor Function
+
+```typescript
+type Visitor<T extends Nodes = Nodes> = (
+  node: T,
+  ancestors: Nodes[],
+  info: VisitInfo
+) => VisitorResult;
+```
+
+The visitor receives:
+
+- **`node`** — Current AST node
+- **`ancestors`** — Array of ancestor nodes from root to parent (not including current node)
+- **`info`** — Visit information with index, sequence, depth, and metadata
+
+The visitor can return:
+
+- `undefined` or `void` — Continue traversal normally
+- `SKIP` — Skip children of current node
+- `EXIT` — Stop traversal immediately
+
+### VisitInfo
+
+```typescript
+interface VisitInfo {
+  /** 0-based index among siblings */
+  index: number;
+
+  /** 1-based sequence (HL7v2 convention). For segment-header: 0 */
+  sequence: number;
+
+  /** 1-based depth in tree (root = 1) */
+  depth: number;
+
+  /** Metadata (e.g., { header: "MSH" } or { name: "PATIENT" }) */
+  metadata: Record<string, unknown> | undefined;
+}
+```
+
+**Important**: `index` and `sequence` represent the node's **position in the tree**, not its position among filtered results. For example:
+
+```typescript
+// Structure: MSH segment with fields at positions 1, 2, 3, 4
+// Filter matches only field 3
+
+visit(
+  ast,
+  (n) => n.type === "field" && hasContent(n),
+  (node, ancestors, info) => {
+    console.log(info.sequence); // => 3 (position in segment, not "1st match")
+  }
+);
+```
+
+This is correct because HL7v2 paths like `PID.3` refer to tree positions, not filtered positions.
+
+### Automatic Metadata Extraction
+
+The `metadata` 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"`)        |
+
+### Exports
+
+```typescript
+import {
+  visit, // Main traversal function
+  EXIT, // Return to stop traversal
+  SKIP, // Return to skip children
+} from "@glion/util-visit";
+
+import type {
+  VisitInfo, // { index, sequence, depth, metadata }
+  Visitor, // (node, ancestors, info) => VisitorResult
+  VisitorResult, // Return type from visitor
+  Test, // Filter predicate
+  Predicate, // (node, ancestors) => boolean
+} from "@glion/util-visit";
+```
+
+## Examples
+
+### Filter by Node Type
+
+```typescript
+visit(ast, "segment", (node, ancestors, info) => {
+  console.log(`Found segment: ${info.metadata?.header}`);
+});
+```
+
+### Filter by Properties
+
+```typescript
+visit(ast, { name: "PATIENT_GROUP" }, (node, ancestors, info) => {
+  console.log("Inside PATIENT_GROUP");
+});
+```
+
+### Custom Test Function
+
+```typescript
+// Visit fields in MSH segment only
+visit(
+  ast,
+  (node, ancestors) => {
+    const parent = ancestors.at(-1);
+    return node.type === "field" && parent?.type === "segment";
+  },
+  (node, ancestors, info) => {
+    console.log(`Field at sequence ${info.sequence}`);
+  }
+);
+```
+
+### Access Parent and Ancestors
+
+```typescript
+visit(ast, "component", (node, ancestors, info) => {
+  // Get immediate parent
+  const parent = ancestors.at(-1);
+
+  // Find closest segment ancestor
+  const segment = ancestors.findLast((n) => n.type === "segment");
+
+  console.log(`Component at depth ${info.depth}`);
+});
+```
+
+### Control Flow: Skip Children
+
+```typescript
+visit(ast, (node, ancestors, info) => {
+  if (node.type === "segment" && info.metadata?.header === "OBX") {
+    return SKIP; // Don't process OBX segment children
+  }
+});
+```
+
+### Control Flow: Exit Early
+
+```typescript
+import { EXIT } from '@glion/util-visit';
+
+let found = false;
+visit(ast, 'field', (node, ancestors, info) => {
+  if (/* some condition */) {
+    found = true;
+    return EXIT; // Stop traversal completely
+  }
+});
+```
+
+### Start from Any Node
+
+```typescript
+import { s, f, c } from "@glion/builder";
+
+// Create a standalone segment
+const segment = s("PID", f(c("value1")), f(c("value2")));
+
+// Traverse from segment (not root)
+visit(segment, "field", (node, ancestors, info) => {
+  console.log(`Field at sequence ${info.sequence}`);
+});
+```
+
+### Track Nesting Levels
+
+```typescript
+visit(ast, (node, ancestors, info) => {
+  const indent = "  ".repeat(info.depth - 1);
+  console.log(`${indent}${node.type} [${info.sequence}]`);
+});
+// Output:
+// root [1]
+//   segment [1]
+//     segment-header [0]
+//     field [1]
+//       field-repetition [1]
+//         component [1]
+```
+
+### Group Hierarchy Navigation
+
+```typescript
+visit(ast, "segment", (node, ancestors, info) => {
+  // Get all parent groups
+  const groups = ancestors
+    .filter((n) => n.type === "group")
+    .map((n) => (n as any).name)
+    .filter((name): name is string => typeof name === "string");
+
+  console.log(`${info.metadata?.header} is in groups: ${groups.join(" > ")}`);
+});
+// => PID is in groups: PATIENT_GROUP
+```
+
+## Real-World Use Cases
+
+### Validate Required Fields
+
+```typescript
+function validateRequiredFields(ast: Root): string[] {
+  const errors: string[] = [];
+
+  visit(ast, "segment", (node, ancestors, info) => {
+    const segment = node as Segment;
+    const header = info.metadata?.header;
+
+    // MSH segment must have at least 12 fields
+    if (header === "MSH" && segment.children.length < 12) {
+      errors.push(`MSH segment missing required fields`);
+    }
+
+    // PID segment must have patient ID (PID.3)
+    if (header === "PID") {
+      const patientId = segment.children[3];
+      if (!patientId || patientId.children.length === 0) {
+        errors.push("PID segment missing required Patient ID (PID.3)");
+      }
+    }
+  });
+
+  return errors;
+}
+```
+
+### Extract Specific Data with Context
+
+```typescript
+interface PatientName {
+  name: string;
+  sequence: number;
+  inGroup?: string;
+}
+
+function extractPatientNames(ast: Root): PatientName[] {
+  const names: PatientName[] = [];
+
+  visit(ast, "segment", (node, ancestors, info) => {
+    if (info.metadata?.header !== "PID") return;
+
+    const segment = node as Segment;
+    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 || "";
+
+      const groupAncestor = ancestors.find((n) => n.type === "group");
+
+      names.push({
+        name,
+        sequence: info.sequence,
+        inGroup: groupAncestor ? (groupAncestor as any).name : undefined,
+      });
+    }
+  });
+
+  return names;
+}
+```
+
+### Message Structure Analysis
+
+```typescript
+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, ancestors, info) => {
+    structure.maxDepth = Math.max(structure.maxDepth, info.depth);
+
+    if (node.type === "segment") {
+      structure.segmentCount++;
+      const header = info.metadata?.header as string;
+      if (header) {
+        structure.segmentTypes[header] =
+          (structure.segmentTypes[header] || 0) + 1;
+      }
+    }
+
+    if (node.type === "group") {
+      structure.groupCount++;
+    }
+  });
+
+  return structure;
+}
+```
+
+### Find First Match and Exit
+
+```typescript
+function findFirstObservation(ast: Root, targetCode: string): string | null {
+  let result: string | null = null;
+
+  visit(ast, "segment", (node, ancestors, info) => {
+    if (info.metadata?.header !== "OBX") return;
+
+    const segment = node as Segment;
+    const identifierField = segment.children[3];
+    const code = identifierField?.children[0]?.children[0]?.children[0]?.value;
+
+    if (code === targetCode) {
+      const valueField = segment.children[5];
+      result = valueField?.children[0]?.children[0]?.children[0]?.value || null;
+      return EXIT; // Stop traversal
+    }
+  });
+
+  return result;
+}
+```
+
+## Architecture
+
+This library is a thin wrapper around [unist-util-visit-parents][] that adds HL7v2-specific features:
+
+1. **Core Traversal**: Delegates to `unist-util-visit-parents` (battle-tested with 50M+ weekly downloads)
+2. **Index Optimization**: Pre-computes node indices for O(1) lookups (avoids O(n²) `indexOf` calls)
+3. **HL7v2 Context**: Adds `VisitInfo` with sequence numbers, depth tracking, and metadata extraction
+4. **Domain Conventions**: Implements HL7v2-specific indexing (segment-header sequence = 0, fields = 1,2,3...)
+
+This design gives us:
+
+- ✅ Proven traversal logic (EXIT/SKIP handling, edge cases)
+- ✅ Mutation support (inherited from unist)
+- ✅ Reverse traversal support (pass `reverse: true` to underlying library)
+- ✅ Small codebase (~120 lines vs previous ~180 lines)
+- ✅ Ecosystem compatibility (works with other unist utilities)
+
+## Performance Characteristics
+
+- **O(n) traversal** — Single pass through all nodes
+- **O(n) index pre-computation** — One-time upfront cost
+- **O(1) index lookups** — Avoids O(n²) `indexOf()` anti-pattern
+- **O(d) ancestor construction** where d = depth (typically < 10 for HL7v2)
+- **Minimal allocations** — Metadata extracted once per node
+
+## Types
+
+```typescript
+export type {
+  VisitInfo, // { index, sequence, depth, metadata }
+  Visitor, // (node, ancestors, info) => VisitorResult
+  VisitorResult, // void | false | 'skip' | ActionTuple
+  Test, // string | Partial | predicate | null
+  Predicate, // (node, ancestors) => boolean
+} from "@glion/util-visit";
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
+
+## 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). See the [LICENSE][github-license] file for details.
+
+[github-code-of-conduct]: https://github.com/rethinkhealth/glion/blob/main/CODE_OF_CONDUCT.md
+[github-license]: https://github.com/rethinkhealth/glion/blob/main/LICENSE
+[github-contributing]: https://github.com/rethinkhealth/glion/blob/main/CONTRIBUTING.md
+[hl7v2-ast]: https://github.com/rethinkhealth/glion/tree/main/packages/hl7v2-ast
+[unist-util-visit-parents]: https://github.com/syntax-tree/unist-util-visit-parents

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HL7v2 AST Visitor
+ *
+ * Wraps unist-util-visit-parents to add HL7v2-specific context
+ * (index, sequence, depth, metadata) while delegating core traversal.
+ */
+import type { Nodes } from "@glion/ast";
+import type { Test, Visitor } from "./types";
+export type { VisitorResult } from "unist-util-visit-parents";
+export { EXIT, SKIP } from "unist-util-visit-parents";
+export type { Predicate, Test, VisitInfo, Visitor } from "./types";
+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;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,KAAK,EAAE,IAAI,EAAa,OAAO,EAAE,MAAM,SAAS,CAAC;AAGxD,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9D,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEtD,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AA8BnE,wBAAgB,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;AAC3D,wBAAgB,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,MAAM,CAAC,EAC9C,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,GAC/C,IAAI,CAAC;AACR,wBAAgB,KAAK,CAAC,CAAC,SAAS,KAAK,EACnC,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,IAAI,CAAC"}

package/dist/index.js

@@ -0,0 +1,97 @@
+import { EXIT, SKIP, visitParents } from "unist-util-visit-parents";
+//#region src/utils.ts
+/**
+* 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
+*/
+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;
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* Build index map for O(1) child index lookups.
+* Pre-computes the index of each node within its parent's children array.
+*
+* @param tree - Root of tree to index
+* @returns WeakMap mapping each node to its index in parent.children
+*/
+function buildIndexMap(tree) {
+	const map = /* @__PURE__ */ new WeakMap();
+	function traverse(node) {
+		if ("children" in node && Array.isArray(node.children)) for (let i = 0; i < node.children.length; i++) {
+			const child = node.children[i];
+			if (child) {
+				map.set(child, i);
+				traverse(child);
+			}
+		}
+	}
+	traverse(tree);
+	return map;
+}
+/**
+* Visit nodes in an HL7 AST tree.
+* Wraps unist-util-visit-parents to add HL7v2-specific context.
+*
+* @param tree - The tree to traverse (can be any node type, not just Root)
+* @param test - Optional test to filter nodes (type string, partial match, or
+*   Test function)
+* @param visitor - Function called for each matching node
+*
+*   **Important**: If you pass a function as the second argument, it is always
+*   treated as a Visitor, never as a Test. To use a Test function, you MUST
+*   provide both the test and visitor parameters: `visit(tree, testFn,
+*   visitorFn)`.
+*/
+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 indexMap = buildIndexMap(tree);
+	visitParents(tree, (node, ancestors) => {
+		if (!predicate(node, ancestors)) return;
+		const parent = ancestors.at(-1);
+		const childIndex = parent ? indexMap.get(node) ?? 0 : 0;
+		const info = {
+			depth: ancestors.length + 1,
+			index: parent ? childIndex : 0,
+			metadata: "name" in node && typeof node.name === "string" ? { name: node.name } : void 0,
+			sequence: parent ? childIndex + 1 : 1
+		};
+		return visitor(node, ancestors, info);
+	});
+}
+//#endregion
+export { EXIT, SKIP, visit };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/utils.ts","../src/index.ts"],"sourcesContent":["import type { Nodes } from \"@glion/ast\";\n\nimport type { Predicate, Test } from \"./types\";\n\n/**\n * Create test predicate from various input types.\n *\n * Assumptions:\n *\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\n *   (properties), or function\n * @returns Predicate function that returns true if node matches test criteria\n */\nexport function createTest(test: Test<Nodes>): Predicate {\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      // oxlint-disable-next-line typescript/no-explicit-any\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","/**\n * HL7v2 AST Visitor\n *\n * Wraps unist-util-visit-parents to add HL7v2-specific context\n * (index, sequence, depth, metadata) while delegating core traversal.\n */\n\nimport type { Nodes } from \"@glion/ast\";\nimport { visitParents } from \"unist-util-visit-parents\";\n\nimport type { Test, VisitInfo, Visitor } from \"./types\";\nimport { createTest } from \"./utils\";\n\nexport type { VisitorResult } from \"unist-util-visit-parents\";\n\n// biome-ignore lint/performance/noBarrelFile: fine\nexport { EXIT, SKIP } from \"unist-util-visit-parents\";\n\nexport type { Predicate, Test, VisitInfo, Visitor } from \"./types\";\n\n/**\n * Build index map for O(1) child index lookups.\n * Pre-computes the index of each node within its parent's children array.\n *\n * @param tree - Root of tree to index\n * @returns WeakMap mapping each node to its index in parent.children\n */\nfunction buildIndexMap(tree: Nodes): WeakMap<Nodes, number> {\n  const map = new WeakMap<Nodes, number>();\n\n  function traverse(node: Nodes): void {\n    if (\"children\" in node && Array.isArray(node.children)) {\n      // oxlint-disable-next-line no-plusplus\n      for (let i = 0; i < node.children.length; i++) {\n        const child = node.children[i];\n        if (child) {\n          map.set(child, i);\n          traverse(child);\n        }\n      }\n    }\n  }\n\n  traverse(tree);\n  return map;\n}\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 * Wraps unist-util-visit-parents to add HL7v2-specific context.\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\n *   Test function)\n * @param visitor - Function called for each matching node\n *\n *   **Important**: If you pass a function as the second argument, it is always\n *   treated as a Visitor, never as a Test. To use a Test function, you MUST\n *   provide both the test and visitor parameters: `visit(tree, testFn,\n *   visitorFn)`.\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  if (arg3 === undefined) {\n    visitor = arg2 as Visitor<T>;\n  } else {\n    test = arg2 as Test<T>;\n    visitor = arg3;\n  }\n\n  const predicate = createTest(test as Test<Nodes>);\n\n  // Pre-compute index map for O(1) lookups\n  const indexMap = buildIndexMap(tree);\n\n  // Delegate traversal to unist-util-visit-parents\n  visitParents(tree, (node, ancestors) => {\n    // Only call visitor if node matches test\n    if (!predicate(node, ancestors)) {\n      return; // Continue traversal but skip visitor\n    }\n\n    // Compute HL7v2-specific context\n    const parent = ancestors.at(-1);\n\n    // For root node (no parent), use defaults\n    // For children, look up their index in the parent's children array\n    const childIndex = parent ? (indexMap.get(node) ?? 0) : 0;\n\n    const info: VisitInfo = {\n      depth: ancestors.length + 1,\n      index: parent ? childIndex : 0,\n      metadata:\n        \"name\" in node && typeof node.name === \"string\"\n          ? { name: node.name }\n          : undefined,\n      sequence: parent ? childIndex + 1 : 1,\n    };\n\n    // Call user visitor with augmented signature\n    return visitor(node as T, ancestors, info);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,SAAgB,WAAW,MAA8B;AACvD,KAAI,SAAS,KACX,cAAa;AAEf,KAAI,OAAO,SAAS,SAClB,SAAQ,SAAS,KAAK,SAAS;AAEjC,KAAI,OAAO,SAAS,WAClB,QAAO;AAIT,SAAQ,SAAS;AACf,OAAK,MAAM,OAAO,OAAO,KAAK,KAAK,EAAE;AAEnC,OAAI,QAAQ,eAAe,QAAQ,iBAAiB,QAAQ,YAC1D;GAGF,MAAM,YAAY,KAAK;GAEvB,MAAM,YAAa,KAAa;AAGhC,OAAI,cAAc,KAAA;QACZ,OAAO,OAAO,MAAM,IAAI,IAAI,cAAc,KAAA,EAC5C,QAAO;cAEA,cAAc,UAEvB,QAAO;;AAGX,SAAO;;;;;;;;;;;;ACzBX,SAAS,cAAc,MAAqC;CAC1D,MAAM,sBAAM,IAAI,SAAwB;CAExC,SAAS,SAAS,MAAmB;AACnC,MAAI,cAAc,QAAQ,MAAM,QAAQ,KAAK,SAAS,CAEpD,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,SAAS,QAAQ,KAAK;GAC7C,MAAM,QAAQ,KAAK,SAAS;AAC5B,OAAI,OAAO;AACT,QAAI,IAAI,OAAO,EAAE;AACjB,aAAS,MAAM;;;;AAMvB,UAAS,KAAK;AACd,QAAO;;;;;;;;;;;;;;;;AA8BT,SAAgB,MACd,MACA,MACA,MACM;CACN,IAAI,OAAgB;CACpB,IAAI;AAEJ,KAAI,SAAS,KAAA,EACX,WAAU;MACL;AACL,SAAO;AACP,YAAU;;CAGZ,MAAM,YAAY,WAAW,KAAoB;CAGjD,MAAM,WAAW,cAAc,KAAK;AAGpC,cAAa,OAAO,MAAM,cAAc;AAEtC,MAAI,CAAC,UAAU,MAAM,UAAU,CAC7B;EAIF,MAAM,SAAS,UAAU,GAAG,GAAG;EAI/B,MAAM,aAAa,SAAU,SAAS,IAAI,KAAK,IAAI,IAAK;EAExD,MAAM,OAAkB;GACtB,OAAO,UAAU,SAAS;GAC1B,OAAO,SAAS,aAAa;GAC7B,UACE,UAAU,QAAQ,OAAO,KAAK,SAAS,WACnC,EAAE,MAAM,KAAK,MAAM,GACnB,KAAA;GACN,UAAU,SAAS,aAAa,IAAI;GACrC;AAGD,SAAO,QAAQ,MAAW,WAAW,KAAK;GAC1C"}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+import type { Nodes } from "@glion/ast";
+import type { VisitorResult } from "unist-util-visit-parents";
+/**
+ * Visit information computed for each node.
+ * This is HL7v2-specific context not provided by unist-util-visit-parents.
+ */
+export interface VisitInfo {
+    /** 0-based index among siblings */
+    index: number;
+    /** 1-based sequence (HL7v2 convention) */
+    sequence: number;
+    /** 1-based depth in tree (root = 1) */
+    depth: number;
+    /** Metadata extracted from node (e.g., { name: "MSH" } or { name: "PATIENT" }) */
+    metadata: Record<string, unknown> | undefined;
+}
+/**
+ * A function called for each node during traversal.
+ * Extends unist's visitor signature with HL7v2-specific context.
+ *
+ * @param node - Current node being visited
+ * @param ancestors - Array of ancestor nodes from root to parent
+ * @param info - HL7v2-specific visit info (index, sequence, depth, metadata)
+ * @returns VisitorResult to control traversal (EXIT, SKIP, etc.)
+ */
+export type Visitor<T extends Nodes = Nodes> = (node: T, ancestors: Nodes[], info: VisitInfo) => VisitorResult;
+/**
+ * Predicate function to test if a node matches filter criteria.
+ * Compatible with unist-util-is predicates but uses our Nodes type.
+ */
+export type Predicate = (node: Nodes, ancestors: Nodes[]) => boolean;
+/**
+ * Filter criteria to determine which nodes to visit.
+ * Based on unist-util-is Test but specialized for HL7v2 AST.
+ *
+ * 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, ancestors: Nodes[]) => node is T) | ((node: Nodes, ancestors: Nodes[]) => boolean) | null;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IAEd,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,IAAI,CAC7C,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,KAAK,EAAE,EAClB,IAAI,EAAE,SAAS,KACZ,aAAa,CAAC;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAErE;;;;;;;;;GASG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,IACpC,MAAM,GACN,OAAO,CAAC,CAAC,CAAC,GACV,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC,GAChD,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,GAC9C,IAAI,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+import type { Nodes } from "@glion/ast";
+import type { Predicate, 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>): Predicate;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,SAAS,CAmCvD"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@glion/util-visit",
+  "version": "0.14.1",
+  "description": "An AST visitor for HL7v2 messages",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript"
+  ],
+  "homepage": "https://glion.dev",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": "rethinkhealth/glion.git",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "unist-util-visit-parents": "6.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "4.1.2",
+    "tsdown": "0.21.7",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.2",
+    "@glion/ast": "0.14.1",
+    "@glion/parser": "0.14.1",
+    "@glion/builder": "0.14.1",
+    "@glion/testing": "0.0.2",
+    "@glion/config": "0.14.1",
+    "@glion/tsconfig": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}