@glion/util-query 0.25.0 → 0.27.0

package/dist/index.js

@@ -1,103 +1,113 @@
 import { DEFAULT_DELIMITERS } from "@glion/utils";
-//#region src/parse.ts
+//#region src/errors.ts
 /**
-* Regular expression for canonical HL7 paths.
-*
-* Format:
-* [GROUP[N]-]...[GROUP[N]-]NAME[N][-FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]]
-*
-* **Design Philosophy**: Groups vs Segments are distinguished by POSITION and
-* USAGE, not name length:
-*
-* - **Navigation (Groups)**: Names appearing as prefixes (before the final name)
-*   are treated as group navigation: `ORDER-ORC`, `ORDER-TIMING-TQ1`
-* - **Target (Segments)**: The final name in the path is the query target.
-*   Whether it's a segment or group is determined by:
-*
-*   1. Field access (-.digit): Definitively a segment → `ORC-1`, `ORDER-ORC-1`
-*   2. No field access: Query the AST to see what exists → `ORC`, `ORDER`
+* The typed failure for `@glion/util-query`. Branch on `code`; each code is
+* one cause.
 *
-* This approach:
-*
-* - Makes no assumptions about name length (works with standard 3-char segments
-*   AND edge cases)
-* - Lets the path structure indicate intent (field access = segment internals)
-* - Allows the AST to be the source of truth for what exists
-*
-* Examples:
-*
-* - `MSH-3` → MSH is segment (has field access)
-* - `ORDER-ORC` → ORDER is navigation, ORC is target (could be segment or nested
-*   group)
-* - `ORDER-ORC-1` → ORDER is navigation, ORC is segment (has field access)
+* @module
 */
-const PATH_REGEX = /^((?:[A-Z][A-Z0-9_]*(?:\[\d+\])?-)*)([A-Z][A-Z0-9_]*)(?:\[(\d+)\])?(?:-(\d+)(?:(?:\[(\d+)\])?(?:\.(\d+)(?:\.(\d+))?)?)?)?$/;
 /**
-* Cache for parsed paths to avoid re-parsing the same path multiple times.
-* No eviction — the realistic set of unique paths in an application is
-* small (50-100 entries) and the memory cost is negligible.
+* Machine-readable codes for what a path got wrong:
+*
+* - `EMPTY_PATH` — the path is empty.
+* - `INVALID_PATH` — the path does not follow the path grammar.
 */
-const parseCache = /* @__PURE__ */ new Map();
+const QueryErrorCode = {
+	EMPTY_PATH: "EMPTY_PATH",
+	INVALID_PATH: "INVALID_PATH"
+};
+function sentence(code, path) {
+	switch (code) {
+		case "EMPTY_PATH": return "The path is empty; a path is `[GROUP[N].]...NAME[N][.FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]]`, or `FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]` read from a segment, with positions from 1, such as `PID.5.1` or `5.1`.";
+		case "INVALID_PATH": return `Path \`${path}\` does not follow the path grammar; a path is \`[GROUP[N].]...NAME[N][.FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]]\`, or \`FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]\` read from a segment, with positions from 1, such as \`PID.5.1\` or \`5.1\`.`;
+	}
+}
+/** A path that `@glion/util-query` cannot read. */
+var QueryError = class extends Error {
+	name = "QueryError";
+	code;
+	path;
+	constructor(code, path) {
+		super(sentence(code, path));
+		this.code = code;
+		this.path = path;
+	}
+};
+//#endregion
+//#region src/parse.ts
 /**
-* Pre-computed PathParts for frequently accessed MSH fields.
+* Canonical HL7 path grammar, every step separated with `.`:
+*
+* [GROUP[N].]...NAME[N][.FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]]
+* FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]
 *
-* Multiple plugins and lint rules read MSH-9 (message type) and MSH-12
-* (version) on every message. Skipping regex parsing and cache lookups
-* for these paths eliminates ~100ns per call.
+* Names start with a letter and positions are numbers from 1, so the first
+* numeric step is the field. The final name is the query target. Field
+* access makes it a segment (`ORDER.ORC.1`); without it the AST decides
+* whether it names a segment or a group (`ORDER.ORC`, `ORDER`). A path that
+* starts with the field names no segment (`5.1`).
 */
-const HOT_PATHS = {
-	"MSH-10": {
-		field: 10,
-		segment: { name: "MSH" }
-	},
-	"MSH-12": {
-		field: 12,
-		segment: { name: "MSH" }
-	},
-	"MSH-3": {
+const PATH_REGEX = /^(?:([A-Z][A-Z0-9_]*(?:\[[1-9]\d*\])?(?:\.[A-Z][A-Z0-9_]*(?:\[[1-9]\d*\])?)*)(?:\.(?=[1-9])|$))?(?:([1-9]\d*)(?:\[([1-9]\d*)\])?(?:\.([1-9]\d*)(?:\.([1-9]\d*))?)?)?$/;
+const NAVIGATION_STEP_REGEX = /([A-Z][A-Z0-9_]*)(?:\[(\d+)\])?/g;
+/** Parts of the MSH paths that plugins and lint rules read on every message. */
+const PRECOMPUTED_PATHS = new Map([
+	["MSH.3", () => ({
 		field: 3,
 		segment: { name: "MSH" }
-	},
-	"MSH-4": {
+	})],
+	["MSH.4", () => ({
 		field: 4,
 		segment: { name: "MSH" }
-	},
-	"MSH-5": {
+	})],
+	["MSH.5", () => ({
 		field: 5,
 		segment: { name: "MSH" }
-	},
-	"MSH-6": {
+	})],
+	["MSH.6", () => ({
 		field: 6,
 		segment: { name: "MSH" }
-	},
-	"MSH-9": {
+	})],
+	["MSH.9", () => ({
 		field: 9,
 		segment: { name: "MSH" }
-	},
-	"MSH-9.1": {
+	})],
+	["MSH.9.1", () => ({
 		component: 1,
 		field: 9,
 		segment: { name: "MSH" }
-	},
-	"MSH-9.2": {
+	})],
+	["MSH.9.2", () => ({
 		component: 2,
 		field: 9,
 		segment: { name: "MSH" }
-	},
-	"MSH-9.3": {
+	})],
+	["MSH.9.3", () => ({
 		component: 3,
 		field: 9,
 		segment: { name: "MSH" }
-	}
-};
+	})],
+	["MSH.10", () => ({
+		field: 10,
+		segment: { name: "MSH" }
+	})],
+	["MSH.12", () => ({
+		field: 12,
+		segment: { name: "MSH" }
+	})],
+	["MSH.12.1", () => ({
+		component: 1,
+		field: 12,
+		segment: { name: "MSH" }
+	})]
+]);
 /**
 * Parse an HL7 path string into structured parts.
-* Results are memoized for performance. Common MSH paths use
-* pre-computed constants to skip parsing entirely.
+*
+* Returns a new object on every call.
 *
 * @example
 *   ```typescript
-*   parse("PID-5[1].2.1");
+*   parse("PID.5[1].2.1");
 *   // {
 *   //   segment: { name: 'PID' },
 *   //   field: 5,
@@ -111,387 +121,195 @@ const HOT_PATHS = {
 * @returns Structured path components
 */
 function parse(path) {
-	const hot = HOT_PATHS[path];
-	if (hot) return hot;
-	const cached = parseCache.get(path);
-	if (cached) return cached;
-	const result = parseImpl(path);
-	parseCache.set(path, result);
-	return result;
-}
-/**
-* Internal implementation of path parsing.
-*/
-function parseImpl(path) {
-	if (!path || typeof path !== "string") throw new Error(`Path must be a non-empty string, got: ${path}`);
-	if (path.trim() !== path) throw new Error(`Path cannot contain leading/trailing spaces: "${path}"`);
+	const precomputed = PRECOMPUTED_PATHS.get(path);
+	if (precomputed) return precomputed();
+	if (path === "") throw new QueryError("EMPTY_PATH", path);
 	const match = PATH_REGEX.exec(path);
-	if (!match) throw new Error(`Invalid HL7 path format: "${path}". Expected [GROUP[N]-]...NAME[N][-FIELD[REPETITION][.COMPONENT[.SUBCOMPONENT]]].`);
-	const [, groupsRaw, segmentName, segmentRep, fieldStr, repetitionStr, componentStr, subcomponentStr] = match;
-	if (!segmentName) throw new Error(`Path must include a segment identifier: "${path}"`);
-	const parts = { segment: { name: segmentName } };
-	if (segmentRep) {
-		const repetition = Number.parseInt(segmentRep, 10);
-		if (repetition < 1) throw new Error(`Segment repetition must be ≥1, got: ${segmentRep} in "${path}"`);
-		parts.segment.repetition = repetition;
-	}
-	if (groupsRaw) {
-		const groups = [];
-		for (const groupMatch of groupsRaw.matchAll(/([A-Z][A-Z0-9_]*)(?:\[(\d+)\])?-/g)) {
-			const name = groupMatch[1];
-			if (!name) continue;
-			const repStr = groupMatch[2];
-			const group = { name };
-			if (repStr) {
-				const repetition = Number.parseInt(repStr, 10);
-				if (repetition < 1) throw new Error(`Group repetition must be ≥1, got: ${repStr} in "${path}"`);
-				group.repetition = repetition;
-			}
-			groups.push(group);
-		}
-		if (groups.length > 0) parts.groups = groups;
-	}
-	if (fieldStr) {
-		const field = Number.parseInt(fieldStr, 10);
-		if (field < 1) throw new Error(`Field number must be ≥1, got: ${fieldStr}`);
-		parts.field = field;
-	}
-	if (repetitionStr) {
-		const repetition = Number.parseInt(repetitionStr, 10);
-		if (repetition < 1) throw new Error(`Repetition number must be ≥1, got: ${repetitionStr}`);
-		parts.repetition = repetition;
-	}
-	if (componentStr) {
-		const component = Number.parseInt(componentStr, 10);
-		if (component < 1) throw new Error(`Component number must be ≥1, got: ${componentStr}`);
-		parts.component = component;
-	}
-	if (subcomponentStr) {
-		const subcomponent = Number.parseInt(subcomponentStr, 10);
-		if (subcomponent < 1) throw new Error(`Subcomponent number must be ≥1, got: ${subcomponentStr}`);
-		parts.subcomponent = subcomponent;
-	}
+	if (!match) throw new QueryError("INVALID_PATH", path);
+	const [, navigation = "", field, repetition, component, subcomponent] = match;
+	const steps = [];
+	for (const [, name, position] of navigation.matchAll(NAVIGATION_STEP_REGEX)) steps.push(position === void 0 ? { name } : {
+		name,
+		repetition: Number(position)
+	});
+	const parts = {};
+	const segment = steps.pop();
+	if (segment !== void 0) parts.segment = segment;
+	if (steps.length > 0) parts.groups = steps;
+	if (field !== void 0) parts.field = Number(field);
+	if (repetition !== void 0) parts.repetition = Number(repetition);
+	if (component !== void 0) parts.component = Number(component);
+	if (subcomponent !== void 0) parts.subcomponent = Number(subcomponent);
 	return parts;
 }
 //#endregion
-//#region src/utils.ts
-function locateSegmentOrGroup(root, parts) {
-	const ancestors = [root];
-	const scope = followGroups(root, parts.groups ?? [], ancestors);
-	if (!scope) return null;
-	const targetName = parts.segment.name;
-	const targetRepetition = parts.segment.repetition;
-	const matchedSegments = collectSegments(scope, targetName, ancestors);
-	if (matchedSegments.length > 0) {
-		const match = matchedSegments[(targetRepetition ?? 1) - 1];
-		if (match) return [match.segment, match.ancestors];
+//#region src/resolve.ts
+/** The name a path gives a node: a segment's name, or a group's ID. */
+const keyOf = (node) => {
+	switch (node.type) {
+		case "root":
+		case "field":
+		case "field-repetition":
+		case "component":
+		case "subcomponent": return;
+		case "segment": return node.name;
+		case "group": return node.id;
 	}
-	const matchedGroups = collectGroups(scope, targetName, ancestors);
-	if (matchedGroups.length > 0) {
-		const match = matchedGroups[(targetRepetition ?? 1) - 1];
-		if (match) return [match.group, match.ancestors];
-	}
-	return null;
-}
-function locateSegment(root, parts) {
-	const ancestors = [root];
-	const scope = followGroups(root, parts.groups ?? [], ancestors);
-	if (!scope) return null;
-	const matchedSegments = collectSegments(scope, parts.segment.name, ancestors);
-	if (matchedSegments.length === 0) return null;
-	const match = matchedSegments[(parts.segment.repetition ?? 1) - 1];
-	if (!match) return null;
-	return [match.segment, match.ancestors];
-}
-function followGroups(root, groups, ancestorChain) {
-	let children = filterSegmentsAndGroups(root.children);
-	for (const locator of groups) {
-		const matchedGroups = children.filter((node) => node.type === "group" && node.id === locator.name);
-		if (matchedGroups.length === 0) return null;
-		const selected = matchedGroups[(locator.repetition ?? 1) - 1];
-		if (!selected) return null;
-		ancestorChain.push(selected);
-		children = filterSegmentsAndGroups(selected.children);
+};
+/**
+* The `position`th of `children` (1-based) when given; otherwise every one
+* when `every` is set, or the first.
+*/
+function pick(children, position, every) {
+	if (position !== void 0) {
+		const child = children[position - 1];
+		return child === void 0 ? [] : [child];
 	}
-	return children;
+	return every ? children : children.slice(0, 1);
 }
 /**
-* Collect all possible scopes when groups can match multiple instances.
-* Used by selectAll to find nodes across all matching groups.
+* The children of `parent` a path step names `name`, segments and groups
+* together: the `position`th (1-based) when given; otherwise every one when
+* `every` is set, or the first.
 */
-function collectAllScopes(root, groups) {
-	if (groups.length === 0) return [{
-		ancestors: [root],
-		scope: filterSegmentsAndGroups(root.children)
-	}];
-	const results = [];
-	const firstLocator = groups[0];
-	const remainingGroups = groups.slice(1);
-	if (!firstLocator) return [{
-		ancestors: [root],
-		scope: filterSegmentsAndGroups(root.children)
-	}];
-	const matchingGroups = filterSegmentsAndGroups(root.children).filter((node) => node.type === "group" && node.id === firstLocator.name);
-	if (firstLocator.repetition !== void 0) {
-		const selected = matchingGroups[firstLocator.repetition - 1];
-		if (!selected) return [];
-		const ancestors = [root, selected];
-		return collectAllScopesRecursive(selected.children, remainingGroups, ancestors);
-	}
-	for (const group of matchingGroups) {
-		const ancestors = [root, group];
-		const subScopes = collectAllScopesRecursive(group.children, remainingGroups, ancestors);
-		results.push(...subScopes);
+function stepChildren(parent, name, position, every) {
+	const result = [];
+	const target = position ?? 1;
+	let count = 0;
+	for (const child of parent.children) {
+		if (keyOf(child) !== name) continue;
+		if (every && position === void 0) {
+			result.push(child);
+			continue;
+		}
+		count += 1;
+		if (count === target) return [child];
 	}
-	return results;
+	return result;
 }
-function collectAllScopesRecursive(children, groups, ancestors) {
-	if (groups.length === 0) return [{
-		ancestors,
-		scope: filterSegmentsAndGroups(children)
-	}];
-	const results = [];
-	const firstLocator = groups[0];
-	const remainingGroups = groups.slice(1);
-	if (!firstLocator) return [{
-		ancestors,
-		scope: filterSegmentsAndGroups(children)
-	}];
-	const matchingGroups = filterSegmentsAndGroups(children).filter((node) => node.type === "group" && node.id === firstLocator.name);
-	if (firstLocator.repetition !== void 0) {
-		const selected = matchingGroups[firstLocator.repetition - 1];
-		if (!selected) return [];
-		const newAncestors = [...ancestors, selected];
-		return collectAllScopesRecursive(selected.children, remainingGroups, newAncestors);
-	}
-	for (const group of matchingGroups) {
-		const newAncestors = [...ancestors, group];
-		const subScopes = collectAllScopesRecursive(group.children, remainingGroups, newAncestors);
-		results.push(...subScopes);
-	}
-	return results;
+/** The children of each scope that `step` names, with their ancestors. */
+function advance(scopes, step, every) {
+	const next = [];
+	for (const scope of scopes) for (const node of stepChildren(scope.node, step.name, step.repetition, every)) next.push({
+		ancestors: [...scope.ancestors, scope.node],
+		node
+	});
+	return next;
 }
-function collectSegments(nodes, targetSegmentName, ancestors) {
-	const result = [];
-	for (const node of nodes) {
-		if (node.type === "segment") {
-			if (getSegmentName(node) === targetSegmentName) result.push({
-				ancestors: [...ancestors],
-				segment: node
+/**
+* The field, repetitions, components, or subcomponents `parts` addresses in
+* `segment`.
+*/
+function resolveField(segment, ancestors, fieldNumber, parts, every) {
+	const field = segment.children[fieldNumber - 1];
+	if (!field) return [];
+	const fieldAncestors = [...ancestors, segment];
+	if (parts.repetition === void 0 && parts.component === void 0) return [{
+		ancestors: fieldAncestors,
+		node: field
+	}];
+	const matches = [];
+	for (const repetition of pick(field.children ?? [], parts.repetition, every)) {
+		const repetitionAncestors = [...fieldAncestors, field];
+		if (parts.component === void 0) {
+			matches.push({
+				ancestors: repetitionAncestors,
+				node: repetition
 			});
+			continue;
 		}
-		if (node.type === "group") {
-			const nextAncestors = [...ancestors, node];
-			result.push(...collectSegments(filterSegmentsAndGroups(node.children), targetSegmentName, nextAncestors));
+		const component = repetition.children?.[parts.component - 1];
+		if (!component) continue;
+		const componentAncestors = [...repetitionAncestors, repetition];
+		if (parts.subcomponent === void 0) {
+			matches.push({
+				ancestors: componentAncestors,
+				node: component
+			});
+			continue;
 		}
-	}
-	return result;
-}
-function collectGroups(nodes, targetGroupId, ancestors) {
-	const result = [];
-	for (const node of nodes) {
-		if (node.type === "group" && node.id === targetGroupId) result.push({
-			ancestors: [...ancestors],
-			group: node
+		const subcomponent = component.children?.[parts.subcomponent - 1];
+		if (subcomponent) matches.push({
+			ancestors: [...componentAncestors, component],
+			node: subcomponent
 		});
-		if (node.type === "group") {
-			const nextAncestors = [...ancestors, node];
-			result.push(...collectGroups(filterSegmentsAndGroups(node.children), targetGroupId, nextAncestors));
-		}
 	}
-	return result;
-}
-function locateField(segment, fieldNum, parentAncestors) {
-	const field = getFields(segment)[fieldNum - 1];
-	if (!field) return null;
-	return [field, [...parentAncestors, segment]];
-}
-function locateRepetition(field, repetition, parentAncestors) {
-	if (repetition < 1) return null;
-	const node = field.children?.[repetition - 1];
-	if (!node) return null;
-	return [node, [...parentAncestors, field]];
-}
-function locateComponent(repetition, componentNum, parentAncestors) {
-	if (componentNum < 1) return null;
-	const component = repetition.children?.[componentNum - 1];
-	if (!component) return null;
-	return [component, [...parentAncestors, repetition]];
-}
-function locateSubcomponent(component, subcomponentNum, parentAncestors) {
-	if (subcomponentNum < 1) return null;
-	const node = component.children?.[subcomponentNum - 1];
-	if (!node) return null;
-	return [node, [...parentAncestors, component]];
+	return matches;
 }
-function getSegmentName(segment) {
-	return segment.name;
-}
-function getFields(segment) {
-	return segment.children;
-}
-function filterSegmentsAndGroups(nodes) {
-	return nodes.filter((node) => node.type === "segment" || node.type === "group");
+/**
+* The nodes `parts` addresses under `start`, in document order, each with its
+* own ancestors array, which begins at `start`.
+*
+* Every step names a direct child of the node before it; the first step
+* names a direct child of `start`. A step's `[n]` counts the children with
+* that name, segments and groups together. A step without `[n]` matches the
+* first such child, or every one when `every` is set; so does a field
+* without a repetition when the path names a component.
+*/
+function resolve(start, parts, every) {
+	let scopes = [{
+		ancestors: [],
+		node: start
+	}];
+	for (const group of parts.groups ?? []) scopes = advance(scopes, group, every);
+	if (parts.segment !== void 0) scopes = advance(scopes, parts.segment, every);
+	if (parts.field === void 0) return scopes;
+	const matches = [];
+	for (const { node, ancestors } of scopes) {
+		if (node.type !== "segment") continue;
+		for (const match of resolveField(node, ancestors, parts.field, parts, every)) matches.push(match);
+	}
+	return matches;
 }
 //#endregion
 //#region src/select.ts
 /**
-* Select the first node at the given path and return it with its ancestor
-* chain.
+* The node `path` addresses under `node`, with its ancestors from `node`, or
+* `null`.
 *
-* This function finds the first matching node for the given path. For paths
-* that can match multiple nodes (e.g., "PID" when multiple PID segments exist),
-* use {@link selectAll} to retrieve all matches.
+* Every step of `path` names a direct child of the node before it; the first
+* step names a direct child of `node`, so a path read from a segment starts
+* with the field. A step without `[n]` names the first such child, so
+* `select` returns `null` when that child does not lead to a match, even if a
+* later one does; `selectAll` returns every match.
 *
 * @example
 *   ```typescript
-*   const result = select(root, "PID-5");
-*   if (result) {
-*     result.node; // Type: Field
-*     result.ancestors; // [Root, Segment]
-*   }
+*   select(root, "PID.5"); // { node: Field, ancestors: [Root, Segment] }
+*   select(root, "PATIENT_RESULT.PATIENT.PID.5");
+*   select(segment, "5.1"); // { node: Component, ancestors: [Segment, Field, FieldRepetition] }
 *   ```;
 *
-* @param root - The root node to search from
-* @param path - The HL7 path string
-* @returns Object containing the node and its ancestors, or null if not found
+* @param node - The message, group, or segment to read from.
+* @param path - The path to the node.
+* @returns The node and its ancestors, or `null` when nothing matches.
 */
-function select(root, path) {
-	const parts = parse(path);
-	if (parts.field === void 0) {
-		const result = locateSegmentOrGroup(root, parts);
-		if (!result) return null;
-		return {
-			ancestors: result[1],
-			node: result[0]
-		};
-	}
-	const segmentResult = locateSegment(root, parts);
-	if (!segmentResult) return null;
-	const [segment, segmentAncestors] = segmentResult;
-	const fieldResult = locateField(segment, parts.field, segmentAncestors);
-	if (!fieldResult) return null;
-	const [field, fieldAncestors] = fieldResult;
-	if (parts.component === void 0 && parts.subcomponent === void 0 && parts.repetition === void 0) return {
-		ancestors: fieldAncestors,
-		node: field
-	};
-	const repetitionResult = locateRepetition(field, parts.repetition ?? 1, fieldAncestors);
-	if (!repetitionResult) return null;
-	const [repetitionNode, repetitionAncestors] = repetitionResult;
-	if (parts.component === void 0) return {
-		ancestors: repetitionAncestors,
-		node: repetitionNode
-	};
-	const componentResult = locateComponent(repetitionNode, parts.component, repetitionAncestors);
-	if (!componentResult) return null;
-	const [componentNode, componentAncestors] = componentResult;
-	if (parts.subcomponent === void 0) return {
-		ancestors: componentAncestors,
-		node: componentNode
-	};
-	const subResult = locateSubcomponent(componentNode, parts.subcomponent, componentAncestors);
-	if (!subResult) return null;
-	return {
-		ancestors: subResult[1],
-		node: subResult[0]
-	};
+function select(node, path) {
+	const [match] = resolve(node, parse(path), false);
+	return match ?? null;
 }
 /**
-* Select all nodes that match the given path.
+* Every node `path` addresses under `node`, with its ancestors from `node`, in
+* document order.
 *
-* This function returns all matching nodes for paths that can match multiple
-* elements. For example, "PID" will return all PID segments in the message, and
-* "OBX-5" will return all observation values.
+* Every step of `path` names a direct child of the node before it; the first
+* step names a direct child of `node`, so a path read from a segment starts
+* with the field. A step without `[n]` matches every such child, and so does
+* a field without a repetition when `path` names a component.
 *
 * @example
 *   ```typescript
-*   // Get all OBX segments
-*   const results = selectAll(root, "OBX");
-*   for (const { node } of results) {
-*     console.log(node.type); // 'segment'
-*   }
-*
-*   // Get all patient name fields
-*   const names = selectAll(root, "PID-5");
+*   selectAll(root, "OBX.5"); // OBX-5 of every top-level OBX
+*   selectAll(root, "OBX.1[2]"); // the second repetition of OBX-1 in every OBX
+*   selectAll(segment, "3.1"); // the first component of every repetition of field 3
 *   ```;
 *
-* @param root - The root node to search from
-* @param path - The HL7 path string (must not include repetition index)
-* @returns Array of objects containing nodes and their ancestor chains
+* @param node - The message, group, or segment to read from.
+* @param path - The path to the nodes.
+* @returns The nodes and their ancestors; empty when nothing matches.
 */
-function selectAll(root, path) {
-	const parts = parse(path);
-	if (parts.segment.repetition !== void 0 || parts.repetition !== void 0) {
-		const result = select(root, path);
-		return result ? [result] : [];
-	}
-	const results = [];
-	const scopes = collectAllScopes(root, parts.groups ?? []);
-	const segments = [];
-	const includeGroups = parts.field === void 0;
-	const groups = [];
-	for (const { scope, ancestors } of scopes) {
-		const matchingSegments = collectSegments(scope, parts.segment.name, ancestors);
-		segments.push(...matchingSegments);
-		if (includeGroups) {
-			const matchingGroups = collectGroups(scope, parts.segment.name, ancestors);
-			for (const { group, ancestors: groupAncestors } of matchingGroups) groups.push({
-				ancestors: groupAncestors,
-				group
-			});
-		}
-	}
-	if (parts.field === void 0) {
-		for (const { segment, ancestors } of segments) results.push({
-			ancestors,
-			node: segment
-		});
-		for (const { group, ancestors } of groups) results.push({
-			ancestors,
-			node: group
-		});
-		return results;
-	}
-	for (const { segment, ancestors: segmentAncestors } of segments) {
-		const fieldResult = locateField(segment, parts.field, segmentAncestors);
-		if (!fieldResult) continue;
-		const [field, fieldAncestors] = fieldResult;
-		if (parts.component === void 0 && parts.subcomponent === void 0 && parts.repetition === void 0) {
-			results.push({
-				ancestors: fieldAncestors,
-				node: field
-			});
-			continue;
-		}
-		if (!field.children) continue;
-		for (const repetitionNode of field.children) {
-			const repetitionAncestors = [...fieldAncestors, field];
-			if (parts.component === void 0) {
-				results.push({
-					ancestors: repetitionAncestors,
-					node: repetitionNode
-				});
-				continue;
-			}
-			const componentResult = locateComponent(repetitionNode, parts.component, repetitionAncestors);
-			if (!componentResult) continue;
-			const [componentNode, componentAncestors] = componentResult;
-			if (parts.subcomponent === void 0) {
-				results.push({
-					ancestors: componentAncestors,
-					node: componentNode
-				});
-				continue;
-			}
-			const subResult = locateSubcomponent(componentNode, parts.subcomponent, componentAncestors);
-			if (subResult) results.push({
-				ancestors: subResult[1],
-				node: subResult[0]
-			});
-		}
-	}
-	return results;
+function selectAll(node, path) {
+	return resolve(node, parse(path), true);
 }
 //#endregion
 //#region src/value.ts
@@ -502,7 +320,7 @@ function selectAll(root, path) {
 * This is a convenience function that automatically traverses through container
 * nodes (Field → FieldRepetition → Component → Subcomponent) to extract the
 * primary string value. When a container has multiple children, the first child
-* is selected (e.g., `value(tree, "MSH-12")` returns the first component of a
+* is selected (e.g., `value(tree, "MSH.12")` returns the first component of a
 * composite VID field).
 *
 * Nodes with no children return `value: null` to differentiate between empty
@@ -510,42 +328,51 @@ function selectAll(root, path) {
 *
 * @example
 *   ```typescript
-*   const result = value(root, "PID-5.1");
+*   const result = value(root, "PID.5.1");
 *   if (result) {
 *     console.log(result.value); // string | null
 *     console.log(result.node.type); // 'subcomponent'
 *     console.log(result.ancestors); // [Root, Segment, Field, ...]
 *   }
+*
+*   value(segment, "5.1"); // the same value, read from the PID segment
 *   ```;
 *
-* @param root - The root node to search from
+* @param node - The message, group, or segment to read from
 * @param path - The HL7 path string
-* @returns Object containing the value, node, and ancestors, or null if not
-*   found
+* @returns Object containing the value, node, and ancestors from `node`, or
+*   null if not found
 */
-function value(root, path) {
-	const selectResult = select(root, path);
-	if (!selectResult) return null;
-	let { node } = selectResult;
-	let { ancestors } = selectResult;
-	while (node.type !== "subcomponent") {
-		if (node.type === "segment" || node.type === "group" || node.type === "root") return null;
-		if (!("children" in node && node.children)) return null;
-		if (node.children.length === 0) return {
-			ancestors: [...ancestors],
+function value(node, path) {
+	const selected = select(node, path);
+	return selected ? drill(selected.node, selected.ancestors) : null;
+}
+/**
+* The first subcomponent under `node`, with its value, or `node` with value
+* `null` when a field, repetition, or component on the way has no children.
+* `null` for a root, group, or segment.
+*/
+function drill(node, ancestors) {
+	switch (node.type) {
+		case "root":
+		case "group":
+		case "segment": return null;
+		case "subcomponent": return {
+			ancestors,
 			node,
-			value: null
+			value: node.value
 		};
-		const next = node.children[0];
-		if (!next) return null;
-		ancestors = [...ancestors, node];
-		node = next;
+		case "field":
+		case "field-repetition":
+		case "component": {
+			const first = node.children?.[0];
+			return first ? drill(first, [...ancestors, node]) : {
+				ancestors,
+				node,
+				value: null
+			};
+		}
 	}
-	return {
-		ancestors,
-		node,
-		value: node.value
-	};
 }
 //#endregion
 //#region src/delimiters.ts
@@ -570,9 +397,9 @@ const MSH2_KEYS = [
 */
 function delimiters(root) {
 	const result = { ...DEFAULT_DELIMITERS };
-	const msh1 = value(root, "MSH-1")?.value;
+	const msh1 = value(root, "MSH.1")?.value;
 	if (msh1 && msh1.length === 1) result.field = msh1;
-	const msh2 = value(root, "MSH-2")?.value;
+	const msh2 = value(root, "MSH.2")?.value;
 	if (msh2) {
 		const chars = [...msh2];
 		for (const [i, key] of MSH2_KEYS.entries()) {
@@ -584,204 +411,99 @@ function delimiters(root) {
 }
 //#endregion
 //#region src/format.ts
-/** What a path names a node by: a segment's name, or a group's ID. */
-const keyOf = (node) => node.type === "group" ? node.id : node.name;
 /**
 * Format a node and its ancestor chain into a canonical HL7v2 path string.
 *
-* This is the inverse of `select`: given a node and the ancestors
-* returned by `visit` or `select`, it produces the path string that
-* would select that node.
+* When `ancestors` starts at the root, `select(root, path)` returns `node`:
+* the path names every group, and `[n]` counts the siblings with the same
+* name, segments and groups together.
 *
 * @example
 *   ```typescript
 *   visit(tree, "field", (node, ancestors) => {
-*     format(node, ancestors); // "PID-5"
+*     format(node, ancestors); // "PID.5"
 *   });
 *
-*   const result = select(root, "PID-5.2");
-*   format(result.node, result.ancestors); // "PID-5.2"
+*   const result = select(root, "PID.5.2");
+*   format(result.node, result.ancestors); // "PID.5.2"
 *   ```;
 *
 * @param node - The target AST node
 * @param ancestors - Ancestor chain from root to parent (as provided by
 *   visit/select)
-* @returns Canonical path string (e.g., "PID-5.2", "ORDER-ORC-1"), or `null` if the
-*   ancestor chain contains no segment or group
+* @returns Canonical path string (e.g., "PID.5.2", "ORDER.ORC.1"), or `null` if the
+*   ancestor chain contains no segment or group, or an ancestor does not
+*   hold the next node in the chain
 */
 function format(node, ancestors) {
-	let result = null;
 	const chain = [...ancestors, node];
-	for (const [i, current] of chain.entries()) {
-		const parent = chain[i - 1];
+	const steps = [];
+	let positions = "";
+	for (const [index, current] of chain.entries()) {
+		const position = positionOf(current, chain[index - 1]);
+		if (position === 0) return null;
 		switch (current.type) {
 			case "root": break;
 			case "group":
-			case "segment": {
-				const pos = positionOf(current, parent);
-				result = (result ?? "") + keyOf(current);
-				if (pos > 1) result += `[${pos}]`;
-				if (current.type === "group" && current !== node) result += "-";
+			case "segment":
+				steps.push(position > 1 ? `${keyOf(current)}[${position}]` : `${keyOf(current)}`);
 				break;
-			}
-			case "field":
-				result += `-${positionOf(current, parent)}`;
-				break;
-			case "field-repetition": {
-				const pos = positionOf(current, parent);
-				if (pos > 1 || current === node) result += `[${pos}]`;
+			case "field-repetition":
+				if (position > 1 || current === node) positions += `[${position}]`;
 				break;
-			}
+			case "field":
 			case "component":
-				result += `.${positionOf(current, parent)}`;
-				break;
 			case "subcomponent":
-				result += `.${positionOf(current, parent)}`;
+				positions += `.${position}`;
 				break;
 		}
 	}
-	return result;
+	return steps.length === 0 ? null : steps.join(".") + positions;
 }
 /**
-* Compute the 1-based position of a node among its parent's children.
-*
-* For segments and groups, counts only siblings with the same name (a
-* group's ID): the 2nd PID in [MSH, PID, OBX, PID] is PID[2], not PID[4].
-*
-* For positional nodes (fields, repetitions, components, subcomponents),
-* uses the array index directly.
+* The 1-based position of `node` among the children of `parent`: for a
+* segment or group, its `[n]` counted as `select` counts it; otherwise its
+* index. 1 without a parent; 0 when `parent` does not hold `node`.
 */
 function positionOf(node, parent) {
-	if (!parent || !("children" in parent)) return 1;
-	const children = parent.children;
-	if (node.type === "group" || node.type === "segment") {
-		const key = keyOf(node);
-		let count = 0;
-		for (const child of children) {
-			if (child === node) return count + 1;
-			if (child.type === node.type && keyOf(child) === key) count++;
-		}
-		throw new Error("format(): node not found in parent's children array");
+	if (parent === void 0 || !("children" in parent)) return 1;
+	switch (node.type) {
+		case "group":
+		case "segment": return stepChildren(parent, keyOf(node), void 0, true).indexOf(node) + 1;
+		case "root":
+		case "field":
+		case "field-repetition":
+		case "component":
+		case "subcomponent": return parent.children.indexOf(node) + 1;
 	}
-	const idx = children.indexOf(node);
-	if (idx === -1) throw new Error("format(): node not found in parent's children array");
-	return idx + 1;
 }
 //#endregion
 //#region src/matches.ts
 /**
-* Check if a node exists at the given path.
+* Whether `select(node, path)` finds a node.
 *
-* This is a convenience function equivalent to `select(root, path) !== null`,
-* but more semantically clear for existence checks.
+* A step without `[n]` names the first such child, so `matches` is `false`
+* when that child does not lead to a match, even if a later one does.
 *
 * @example
 *   ```typescript
-*   if (matches(root, "PID-5")) {
+*   if (matches(root, "PID.5")) {
 *     console.log("Patient has a name field");
 *   }
 *
-*   if (!matches(root, "OBX-5")) {
+*   if (!matches(root, "OBX.5")) {
 *     throw new Error("Missing observation value");
 *   }
 *   ```;
 *
-* @param root - The root node to search from
+* @param node - The message, group, or segment to read from
 * @param path - The HL7 path string
 * @returns True if the path resolves to a node, false otherwise
 */
-function matches(root, path) {
-	return select(root, path) !== null;
-}
-//#endregion
-//#region src/set.ts
-/**
-* Set a string value at the given HL7 path, creating all missing intermediate
-* nodes as needed (fields, repetitions, components, subcomponents).
-*
-* This is the write counterpart to {@link value}. It handles the full HL7v2
-* path syntax including group navigation and segment repetitions.
-*
-* Padding nodes are created with empty children arrays — they represent
-* structurally absent nodes, not empty values. Only the target node gets
-* a fully populated chain down to the subcomponent.
-*
-* @example
-*   ```typescript
-*   // Update existing value
-*   set(tree, "MSH-12", "2.7.1");
-*
-*   // Create missing MSH-9.3 (fills gaps with empty components)
-*   set(tree, "MSH-9.3", "ADT_A01");
-*
-*   // Set a specific repetition
-*   set(tree, "PID-3[2]", "ID-002");
-*
-*   // Set a subcomponent
-*   set(tree, "PID-5.1.2", "suffix");
-*   ```;
-*
-* @param root - The root node to modify
-* @param path - The HL7 path string (must include at least a field)
-* @param val - The string value to set
-* @throws When the path has no field specifier (segment-only paths)
-* @throws When the target segment does not exist in the tree
-*/
-function set(root, path, val) {
-	const parts = parse(path);
-	if (parts.field === void 0) throw new Error(`Cannot set value on segment-only path: "${path}"`);
-	const segmentResult = locateSegment(root, parts);
-	if (!segmentResult) throw new Error(`Segment "${parts.segment.name}" not found in tree`);
-	const [segment] = segmentResult;
-	const fieldIndex = parts.field - 1;
-	padArray(segment.children, fieldIndex + 1, stubField);
-	const field = segment.children[fieldIndex];
-	const repIndex = (parts.repetition ?? 1) - 1;
-	padArray(field.children, repIndex + 1, stubRepetition);
-	const repetition = field.children[repIndex];
-	const compIndex = (parts.component ?? 1) - 1;
-	padArray(repetition.children, compIndex + 1, stubComponent);
-	const component = repetition.children[compIndex];
-	const subIndex = (parts.subcomponent ?? 1) - 1;
-	padArray(component.children, subIndex + 1, stubSubcomponent);
-	component.children[subIndex].value = val;
-}
-/**
-* Pad an array to a target length using a factory function.
-*/
-function padArray(arr, targetLength, factory) {
-	while (arr.length < targetLength) arr.push(factory());
-}
-/**
-* Stub nodes for padding — created with empty children arrays to represent
-* structurally absent nodes. These are distinguishable from nodes with empty
-* values (which have a subcomponent with value "").
-*/
-function stubField() {
-	return {
-		children: [],
-		type: "field"
-	};
-}
-function stubRepetition() {
-	return {
-		children: [],
-		type: "field-repetition"
-	};
-}
-function stubComponent() {
-	return {
-		children: [],
-		type: "component"
-	};
-}
-function stubSubcomponent() {
-	return {
-		type: "subcomponent",
-		value: ""
-	};
+function matches(node, path) {
+	return select(node, path) !== null;
 }
 //#endregion
-export { delimiters, format, matches, parse, select, selectAll, set, value };
+export { QueryError, QueryErrorCode, delimiters, format, matches, parse, select, selectAll, value };
 
 //# sourceMappingURL=index.js.map