@glion/util-visit 0.25.0 → 0.27.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Rethink Health
+Copyright (c) 2023 Rethink Health, SUARL
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 # @glion/util-visit
 
-Visitor for traversing HL7v2 AST trees with ancestor context, depth, and HL7v2-aware sequence numbers.
+Visitor for traversing HL7v2 AST trees with ancestor context.
 
 ## What it does
 
-Walks an HL7v2 AST from any starting node — Root, Segment, Field, Component, or Subcomponent — calling a visitor function for each matching node. Each call receives the node, its ancestors (root-to-parent), and a `VisitInfo` record with index, HL7v2 sequence number, depth, and extracted metadata. Supports filtering by type string, property object, or predicate, and exposes `SKIP`/`EXIT` control actions. Delegates core traversal to `unist-util-visit-parents`.
+Walks an HL7v2 AST from any starting node — Root, Group, Segment, Field, Component, or Subcomponent — calling a visitor function for each matching node with the node and its ancestors, from the node the walk starts at to the node's parent. Supports filtering by type string, property object, or predicate, and exposes `SKIP`/`EXIT` control actions. Delegates traversal to `unist-util-visit-parents`, with types from `@glion/ast`.
 
 ## Install
 
@@ -15,25 +15,21 @@ npm install @glion/util-visit
 ## Use
 
 ```typescript
-import { visit, EXIT, SKIP } from "@glion/util-visit";
-import { parse } from "@glion/parser";
+import { parseHL7v2 } from "@glion/parser";
+import { SKIP, visit } from "@glion/util-visit";
 
-const message = parse("MSH|^~\\&|...\rPID|...");
-
-// Visit all segments
-visit(message, "segment", (node, ancestors, info) => {
-  console.log(`Segment: ${info.metadata?.header} at depth ${info.depth}`);
-});
+const tree = parseHL7v2(
+  "MSH|^~\\&|LAB|FAC|EMR|RFAC|20250601120000||ORU^R01^ORU_R01|MSG00001|P|2.5\rPID|1||12345\rNTE|1||note"
+);
 
-// 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`);
+// Visit every segment
+visit(tree, "segment", (segment) => {
+  console.log(segment.name); // "MSH", "PID", "NTE"
 });
 
-// Skip processing of sensitive segments
-visit(message, (node, ancestors, info) => {
-  if (node.type === "segment" && info.metadata?.header === "NTE") {
+// Skip the fields of NTE segments
+visit(tree, (node) => {
+  if (node.type === "segment" && node.name === "NTE") {
     return SKIP;
   }
 });
@@ -45,14 +41,14 @@ visit(message, (node, ancestors, info) => {
 
 ### `visit(tree, test, visitor)`
 
-Visit nodes in an HL7v2 AST tree.
+Visit nodes in an HL7v2 AST tree, in document order.
 
 #### 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 whose own properties equal (`===`) each value (e.g., `{ name: "PATIENT_GROUP" }`). A property the node does not own reads as `undefined`: an `undefined` value matches an absent property, and a key naming an inherited member (`constructor`, `toString`) matches no node.
+  - `Partial<Nodes>` — Match nodes whose own properties equal (`===`) each value (e.g., `{ id: "PATIENT" }`). A property the node does not own reads as `undefined`: an `undefined` value matches an absent property, and a key naming an inherited member (`constructor`, `toString`) matches no node.
   - `Test` — Custom function `(node, ancestors) => boolean`.
 - `visitor` (`Visitor`) — Function called for each matching node.
 
@@ -60,23 +56,18 @@ Visit nodes in an HL7v2 AST tree.
 
 `void`.
 
-#### Important: test vs visitor functions
+#### Test vs visitor functions
 
-**If you pass a function as the second argument, it is always treated as a Visitor, never as a Test.**
+A function passed as the second argument is always the visitor, never a test. A test function needs the three-argument form:
 
 ```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');
-});
+visit(
+  tree,
+  (node) => node.type === "segment",
+  (segment) => {
+    console.log(segment.type); // "segment"
+  }
+);
 ```
 
 #### Visitor function
@@ -84,290 +75,106 @@ visit(ast, 'segment', (node, ancestors, info) => {
 ```typescript
 type Visitor<T extends Nodes = Nodes> = (
   node: T,
-  ancestors: Nodes[],
-  info: VisitInfo
+  ancestors: Nodes[]
 ) => 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.
+- `ancestors` — Ancestor nodes from the node the walk starts at to the parent, not including the current node. Empty for the starting node.
 
 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 the parent's children when the node is visited */
-  index: number;
-
-  /** `index` + 1, the HL7v2 sequence number */
-  sequence: number;
-
-  /** 1-based depth in tree (root = 1) */
-  depth: number;
-
-  /** Metadata (e.g., { name: "MSH" } or { name: "PATIENT" }) */
-  metadata: Record<string, unknown> | undefined;
-}
-```
-
-`index` and `sequence` represent the node's **position in the tree**, not its position among filtered results:
+- `undefined` or `CONTINUE` — Continue traversal, into the node's children.
+- `SKIP` — Skip the children of the current node.
+- `EXIT` — Stop traversal.
+- An index — Continue at that index among the current node's siblings.
+- `[action, index]` — Both.
 
-```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.
-
-The position is read when the node is visited, so it reflects siblings a visitor inserted or removed earlier in the same visit. A visitor that removes the current node can return `info.index` to continue with the sibling that moved into its place:
+A visitor that removes the current node returns its former index to continue with the sibling that moved into its place:
 
 ```typescript
-visit(segment, "field", (node, ancestors, info) => {
-  if (isEmptyNode(node)) {
-    ancestors.at(-1).children.splice(info.index, 1);
-    return info.index;
-  }
+visit(tree, { type: "segment", name: "NTE" }, (segment, ancestors) => {
+  const parent = ancestors.at(-1) as Root | Group;
+  const index = parent.children.indexOf(segment);
+  parent.children.splice(index, 1);
+  return index;
 });
 ```
 
-### Automatic metadata extraction
-
-The `metadata` field is populated automatically:
-
-| Node type | Metadata key | Description                                 |
-| --------- | ------------ | ------------------------------------------- |
-| `segment` | `header`     | Segment identifier (e.g., `"MSH"`, `"PID"`) |
-| `group`   | `name`       | Group name (e.g., `"PATIENT_GROUP"`)        |
+`indexOf` scans the parent's children, so removing many children of one parent this way costs time in the square of their number. To remove many, filter `parent.children` once from the parent's visitor instead.
 
 ### Exports
 
 ```typescript
 import {
-  visit, // Main traversal function
+  visit, // 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
+  Visitor, // (node, ancestors) => VisitorResult
+  VisitorResult, // Return type of a visitor
+  Test, // Filter: type string, property object, predicate, or null
   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");
+// A group's `id` is its key in paths; its `name` is the title for display
+visit(tree, { type: "group", id: "PATIENT" }, (group) => {
+  console.log(group.name); // "Patient"
 });
 ```
 
-### Custom test function
+### Read the ancestors
 
 ```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) => {
-  const parent = ancestors.at(-1);
-  const segment = ancestors.findLast((n) => n.type === "segment");
-  console.log(`Component at depth ${info.depth}`);
+visit(tree, "component", (component, ancestors) => {
+  const parent = ancestors.at(-1); // the field repetition
+  const segment = ancestors.findLast((node) => node.type === "segment");
 });
 ```
 
-### Control flow: skip children
+### Read the segment groups above a segment
 
 ```typescript
-visit(ast, (node, ancestors, info) => {
-  if (node.type === "segment" && info.metadata?.header === "OBX") {
-    return SKIP; // Don't process OBX segment children
-  }
+visit(tree, "segment", (segment, ancestors) => {
+  const groups = ancestors
+    .filter((node): node is Group => node.type === "group")
+    .map((group) => group.id);
+  console.log(`${segment.name}: ${groups.join(" > ")}`); // "PID: PATIENT_RESULT > PATIENT"
 });
 ```
 
-### Control flow: exit early
+### Stop at the first match
 
 ```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
-  }
+let first: Segment | undefined;
+visit(tree, { type: "segment", name: "OBX" }, (segment) => {
+  first = segment as Segment;
+  return EXIT;
 });
 ```
 
 ### Start from any node
 
 ```typescript
-import { s, f, c } from "@glion/builder";
+import { c, f, s } 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}]`);
+visit(segment, "field", (field, ancestors) => {
+  console.log(ancestors.length); // 1: the segment
 });
-// root [1]
-//   segment [1]
-//     segment-header [0]
-//     field [1]
-//       field-repetition [1]
-//         component [1]
-```
-
-### Group hierarchy navigation
-
-```typescript
-visit(ast, "segment", (node, ancestors, info) => {
-  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
-```
-
-### 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;
-
-    if (header === "MSH" && segment.children.length < 12) {
-      errors.push("MSH segment missing required fields");
-    }
-
-    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 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 is Group => n.type === "group"
-      );
-
-      names.push({
-        name,
-        sequence: info.sequence,
-        inGroup: groupAncestor?.name,
-      });
-    }
-  });
-
-  return names;
-}
-```
-
-### 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;
-    }
-  });
-
-  return result;
-}
 ```
 
 ## Part of Glion

package/dist/index.d.ts

@@ -1,14 +1,13 @@
 /**
- * HL7v2 AST Visitor
+ * HL7v2 AST visitor over `unist-util-visit-parents`, typed for `@glion/ast`.
  *
- * Wraps unist-util-visit-parents to add HL7v2-specific context
- * (index, sequence, depth, metadata) while delegating core traversal.
+ * @module
  */
 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 type { Predicate, Test, 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;

package/dist/index.d.ts.map

@@ -1 +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;AAE9D,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEtD,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGnE,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAG7C,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEtD,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGxD,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

@@ -47,7 +47,6 @@ function createTest(test) {
 //#region src/index.ts
 /**
 * 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
@@ -68,20 +67,9 @@ function visit(tree, arg2, arg3) {
 		visitor = arg3;
 	}
 	const predicate = createTest(test);
-	let currentIndex = 0;
-	const captureIndex = (_node, index) => {
-		currentIndex = index ?? 0;
-		return true;
-	};
-	visitParents(tree, captureIndex, (node, ancestors) => {
+	visitParents(tree, (node, ancestors) => {
 		if (!predicate(node, ancestors)) return;
-		const info = {
-			depth: ancestors.length + 1,
-			index: currentIndex,
-			metadata: "name" in node ? { name: node.name } : void 0,
-			sequence: currentIndex + 1
-		};
-		return visitor(node, ancestors, info);
+		return visitor(node, ancestors);
 	});
 }
 //#endregion

package/dist/index.js.map

@@ -1 +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 * The predicate a `visit` test describes.\n *\n * - `null` matches every node.\n * - A string matches nodes whose `type` equals it.\n * - A function is the predicate.\n * - An object matches nodes whose own property equals (`===`) each of its values.\n *   A property the node does not own reads as `undefined`, so an `undefined`\n *   value matches an absent property, and a key that names an inherited member\n *   (`constructor`, `toString`, an own `__proto__`) matches no node. The\n *   object's entries are read once, when the predicate is created.\n *\n * @example\n *   ```typescript\n *   const msh = s(\"MSH\", f(\"|\"));\n *\n *   createTest(null)(msh, []); // true\n *   createTest(\"segment\")(msh, []); // true\n *   createTest(\"field\")(msh, []); // false\n *\n *   createTest({ type: \"segment\", name: \"MSH\" })(msh, []); // true\n *   createTest({ name: \"PID\" })(msh, []); // false\n *\n *   // `undefined` matches a property the node does not have\n *   createTest({ name: undefined })(f(\"|\"), []); // true\n *\n *   // An inherited member is never matched\n *   createTest({ constructor: Object })(msh, []); // false\n *\n *   // A function receives the ancestors as well\n *   const inGroup = createTest((_node, ancestors) => ancestors.length > 1);\n *   ```;\n *\n * @param test - `null`, a node type, a property object, or a predicate.\n * @returns The predicate.\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    // Used as is: `visit` calls it with `(node, ancestors)`, so it may match on\n    // a node's position in the tree as well as on the node itself.\n    return test;\n  }\n\n  // Read once here rather than per visited node: a visit calls the predicate\n  // for every node, and a test object changed during the visit does not change\n  // which nodes match.\n  const entries = Object.entries(test);\n\n  return (node) =>\n    entries.every(\n      ([key, value]) =>\n        // `Object.hasOwn` limits the match to the node's own properties. Without\n        // it, `node[key]` also finds inherited members, so `{ constructor: x }`\n        // or `{ toString: x }` would be compared against `Object.prototype`.\n        // `Reflect.get(node, key)` is `node[key]`; it compiles for an arbitrary\n        // string key, which `Nodes` (no index signature) does not allow.\n        (Object.hasOwn(node, key) ? Reflect.get(node, key) : undefined) ===\n        value\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\nexport { EXIT, SKIP } from \"unist-util-visit-parents\";\n\nexport type { Predicate, Test, VisitInfo, Visitor } from \"./types\";\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  // visit-parents passes a node's index among its parent's children only to\n  // its test, `test(node, index, parent)`, never to its visitor. It calls the\n  // test and, when the test passes, the visitor on that same node with nothing\n  // in between (unist-util-visit-parents 6.0.2, lib/index.js; the version is\n  // pinned). `captureIndex` is that test: it stores the index for the visitor\n  // to read and passes every node. The index is the node's position when it\n  // is visited, so it reflects siblings a visitor inserted or removed earlier.\n  let currentIndex = 0;\n  const captureIndex = (_node: unknown, index?: number): boolean => {\n    // The node `visit` starts from has no parent, so it has no index.\n    currentIndex = index ?? 0;\n    return true;\n  };\n\n  visitParents(tree, captureIndex, (node, ancestors) => {\n    // The caller's test runs here, not in `captureIndex`: it may read\n    // `ancestors`, which visit-parents gives only to the visitor.\n    if (!predicate(node, ancestors)) {\n      // Returning nothing means \"continue\": visit-parents still walks into\n      // this node's children, so `visit(tree, \"field\", …)` reaches the fields\n      // of segments it does not match.\n      return;\n    }\n\n    const info: VisitInfo = {\n      depth: ancestors.length + 1,\n      index: currentIndex,\n      metadata: \"name\" in node ? { name: node.name } : undefined,\n      sequence: currentIndex + 1,\n    };\n\n    // visit-parents reads the visitor's return value to decide what to visit\n    // next, so the caller's result is passed through unchanged:\n    // - nothing or CONTINUE: walk into this node's children;\n    // - SKIP: skip this node's children;\n    // - EXIT: stop the walk;\n    // - a number: continue at that index among this node's siblings, as after\n    //   removing the current node with `splice(info.index, 1)`;\n    // - [action, index]: both.\n    // Calling the visitor without returning its result would turn every one\n    // of these into \"continue\".\n    return visitor(node as T, ancestors, info);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,WAAW,MAA8B;AACvD,KAAI,SAAS,KACX,cAAa;AAEf,KAAI,OAAO,SAAS,SAClB,SAAQ,SAAS,KAAK,SAAS;AAEjC,KAAI,OAAO,SAAS,WAGlB,QAAO;CAMT,MAAM,UAAU,OAAO,QAAQ,KAAK;AAEpC,SAAQ,SACN,QAAQ,OACL,CAAC,KAAK,YAMJ,OAAO,OAAO,MAAM,IAAI,GAAG,QAAQ,IAAI,MAAM,IAAI,GAAG,KAAA,OACrD,MACH;;;;;;;;;;;;;;;;;;ACtBL,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;CASjD,IAAI,eAAe;CACnB,MAAM,gBAAgB,OAAgB,UAA4B;AAEhE,iBAAe,SAAS;AACxB,SAAO;;AAGT,cAAa,MAAM,eAAe,MAAM,cAAc;AAGpD,MAAI,CAAC,UAAU,MAAM,UAAU,CAI7B;EAGF,MAAM,OAAkB;GACtB,OAAO,UAAU,SAAS;GAC1B,OAAO;GACP,UAAU,UAAU,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAA;GACjD,UAAU,eAAe;GAC1B;AAYD,SAAO,QAAQ,MAAW,WAAW,KAAK;GAC1C"}
+{"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 * The predicate a `visit` test describes.\n *\n * - `null` matches every node.\n * - A string matches nodes whose `type` equals it.\n * - A function is the predicate.\n * - An object matches nodes whose own property equals (`===`) each of its values.\n *   A property the node does not own reads as `undefined`, so an `undefined`\n *   value matches an absent property, and a key that names an inherited member\n *   (`constructor`, `toString`, an own `__proto__`) matches no node. The\n *   object's entries are read once, when the predicate is created.\n *\n * @example\n *   ```typescript\n *   const msh = s(\"MSH\", f(\"|\"));\n *\n *   createTest(null)(msh, []); // true\n *   createTest(\"segment\")(msh, []); // true\n *   createTest(\"field\")(msh, []); // false\n *\n *   createTest({ type: \"segment\", name: \"MSH\" })(msh, []); // true\n *   createTest({ name: \"PID\" })(msh, []); // false\n *\n *   // `undefined` matches a property the node does not have\n *   createTest({ name: undefined })(f(\"|\"), []); // true\n *\n *   // An inherited member is never matched\n *   createTest({ constructor: Object })(msh, []); // false\n *\n *   // A function receives the ancestors as well\n *   const inGroup = createTest((_node, ancestors) => ancestors.length > 1);\n *   ```;\n *\n * @param test - `null`, a node type, a property object, or a predicate.\n * @returns The predicate.\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    // Used as is: `visit` calls it with `(node, ancestors)`, so it may match on\n    // a node's position in the tree as well as on the node itself.\n    return test;\n  }\n\n  // Read once here rather than per visited node: a visit calls the predicate\n  // for every node, and a test object changed during the visit does not change\n  // which nodes match.\n  const entries = Object.entries(test);\n\n  return (node) =>\n    entries.every(\n      ([key, value]) =>\n        // `Object.hasOwn` limits the match to the node's own properties. Without\n        // it, `node[key]` also finds inherited members, so `{ constructor: x }`\n        // or `{ toString: x }` would be compared against `Object.prototype`.\n        // `Reflect.get(node, key)` is `node[key]`; it compiles for an arbitrary\n        // string key, which `Nodes` (no index signature) does not allow.\n        (Object.hasOwn(node, key) ? Reflect.get(node, key) : undefined) ===\n        value\n    );\n}\n","/**\n * HL7v2 AST visitor over `unist-util-visit-parents`, typed for `@glion/ast`.\n *\n * @module\n */\n\nimport type { Nodes } from \"@glion/ast\";\nimport { visitParents } from \"unist-util-visit-parents\";\n\nimport type { Test, Visitor } from \"./types\";\nimport { createTest } from \"./utils\";\n\nexport type { VisitorResult } from \"unist-util-visit-parents\";\n\nexport { EXIT, SKIP } from \"unist-util-visit-parents\";\n\nexport type { Predicate, Test, Visitor } from \"./types\";\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 *\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  // The caller's test runs in the visitor, not as visit-parents' test: it may\n  // read `ancestors`, which visit-parents gives only to the visitor.\n  visitParents(tree, (node, ancestors) => {\n    if (!predicate(node, ancestors)) {\n      // Returning nothing means \"continue\": visit-parents still walks into\n      // this node's children, so `visit(tree, \"field\", …)` reaches the fields\n      // of segments it does not match.\n      return;\n    }\n\n    // visit-parents reads the visitor's return value to decide what to visit\n    // next (CONTINUE, SKIP, EXIT, an index, or both), so the caller's result\n    // is passed through unchanged.\n    return visitor(node as T, ancestors);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,WAAW,MAA8B;AACvD,KAAI,SAAS,KACX,cAAa;AAEf,KAAI,OAAO,SAAS,SAClB,SAAQ,SAAS,KAAK,SAAS;AAEjC,KAAI,OAAO,SAAS,WAGlB,QAAO;CAMT,MAAM,UAAU,OAAO,QAAQ,KAAK;AAEpC,SAAQ,SACN,QAAQ,OACL,CAAC,KAAK,YAMJ,OAAO,OAAO,MAAM,IAAI,GAAG,QAAQ,IAAI,MAAM,IAAI,GAAG,KAAA,OACrD,MACH;;;;;;;;;;;;;;;;;ACxBL,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;AAIjD,cAAa,OAAO,MAAM,cAAc;AACtC,MAAI,CAAC,UAAU,MAAM,UAAU,CAI7B;AAMF,SAAO,QAAQ,MAAW,UAAU;GACpC"}

package/dist/types.d.ts

@@ -1,33 +1,13 @@
 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 the parent's children when the node is visited, or 0
-     * for the node the visit starts from. Reflects changes a visitor made to
-     * those children earlier in the same visit.
-     */
-    index: number;
-    /** `index` + 1, the HL7v2 sequence number. */
-    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;
+export type Visitor<T extends Nodes = Nodes> = (node: T, ancestors: Nodes[]) => VisitorResult;
 /**
  * Predicate function to test if a node matches filter criteria.
  * Compatible with unist-util-is predicates but uses our Nodes type.

package/dist/types.d.ts.map

@@ -1 +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;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,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;;;;;;;;;;GAUG;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"}
+{"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;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,IAAI,CAC7C,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,KAAK,EAAE,KACf,aAAa,CAAC;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAErE;;;;;;;;;;GAUG;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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glion/util-visit",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "An AST visitor for HL7v2 messages",
   "keywords": [
     "health",
@@ -45,10 +45,10 @@
     "tsdown": "0.21.10",
     "typescript": "6.0.3",
     "vitest": "4.1.11",
-    "@glion/ast": "0.25.0",
-    "@glion/builder": "0.25.0",
+    "@glion/ast": "0.27.0",
+    "@glion/builder": "0.27.0",
     "@glion/check-readme": "0.18.0",
-    "@glion/parser": "0.25.0",
+    "@glion/parser": "0.27.0",
     "@glion/testing": "0.18.0",
     "@glion/tsconfig": "0.18.0"
   },