@glion/util-query 0.14.1

package/dist/index.js

@@ -0,0 +1,778 @@
+import { DEFAULT_DELIMITERS } from "@glion/utils";
+//#region src/parse.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`
+*
+* 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)
+*/
+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.
+*/
+const parseCache = /* @__PURE__ */ new Map();
+/**
+* Pre-computed PathParts for frequently accessed MSH fields.
+*
+* 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.
+*/
+const HOT_PATHS = {
+	"MSH-3": {
+		segment: { name: "MSH" },
+		field: 3
+	},
+	"MSH-4": {
+		segment: { name: "MSH" },
+		field: 4
+	},
+	"MSH-5": {
+		segment: { name: "MSH" },
+		field: 5
+	},
+	"MSH-6": {
+		segment: { name: "MSH" },
+		field: 6
+	},
+	"MSH-9": {
+		segment: { name: "MSH" },
+		field: 9
+	},
+	"MSH-9.1": {
+		segment: { name: "MSH" },
+		field: 9,
+		component: 1
+	},
+	"MSH-9.2": {
+		segment: { name: "MSH" },
+		field: 9,
+		component: 2
+	},
+	"MSH-9.3": {
+		segment: { name: "MSH" },
+		field: 9,
+		component: 3
+	},
+	"MSH-10": {
+		segment: { name: "MSH" },
+		field: 10
+	},
+	"MSH-12": {
+		segment: { name: "MSH" },
+		field: 12
+	}
+};
+/**
+* Parse an HL7 path string into structured parts.
+* Results are memoized for performance. Common MSH paths use
+* pre-computed constants to skip parsing entirely.
+*
+* @example
+*   ```typescript
+*   parse("PID-5[1].2.1");
+*   // {
+*   //   segment: { name: 'PID' },
+*   //   field: 5,
+*   //   repetition: 1,
+*   //   component: 2,
+*   //   subcomponent: 1
+*   // }
+*   ```;
+*
+* @param path - HL7 path string to parse
+* @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 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;
+	}
+	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];
+	}
+	const matchedGroups = collectGroups(scope, targetName);
+	if (matchedGroups.length > 0) {
+		const group = matchedGroups[(targetRepetition ?? 1) - 1];
+		if (group) return [group, 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.name === 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);
+	}
+	return children;
+}
+/**
+* Collect all possible scopes when groups can match multiple instances.
+* Used by selectAll to find nodes across all matching groups.
+*/
+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.name === 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);
+	}
+	return results;
+}
+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.name === 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;
+}
+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
+			});
+		}
+		if (node.type === "group") {
+			const nextAncestors = [...ancestors, node];
+			result.push(...collectSegments(filterSegmentsAndGroups(node.children), targetSegmentName, nextAncestors));
+		}
+	}
+	return result;
+}
+function collectGroups(nodes, targetGroupName) {
+	const result = [];
+	for (const node of nodes) if (node.type === "group" && node.name === targetGroupName) result.push(node);
+	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]];
+}
+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");
+}
+//#endregion
+//#region src/select.ts
+/**
+* Select the first node at the given path and return it with its ancestor
+* chain.
+*
+* 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.
+*
+* @example
+*   ```typescript
+*   const result = select(root, "PID-5");
+*   if (result) {
+*     result.node; // Type: Field
+*     result.ancestors; // [Root, Segment]
+*   }
+*   ```;
+*
+* @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
+*/
+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]
+	};
+}
+/**
+* Select all nodes that match the given path.
+*
+* 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.
+*
+* @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");
+*   ```;
+*
+* @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
+*/
+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);
+			for (const group of matchingGroups) groups.push({
+				ancestors: [...ancestors],
+				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;
+}
+//#endregion
+//#region src/value.ts
+/**
+* Get the string value at the path, drilling down through single-child nodes
+* when needed. Also returns the node and ancestor chain for context.
+*
+* 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
+* composite VID field).
+*
+* When experimental.emptyMode is "empty", nodes with no children will return
+* null to differentiate between empty strings ("") and missing values.
+*
+* @example
+*   ```typescript
+*   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, ...]
+*   }
+*   ```;
+*
+* @param root - The root node to search from
+* @param path - The HL7 path string
+* @returns Object containing the value, node, and ancestors, 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],
+			node,
+			value: null
+		};
+		const next = node.children[0];
+		if (!next) return null;
+		ancestors = [...ancestors, node];
+		node = next;
+	}
+	return {
+		ancestors,
+		node,
+		value: node.value
+	};
+}
+//#endregion
+//#region src/delimiters.ts
+/** Keys of MSH-2 encoding characters in positional order. */
+const MSH2_KEYS = [
+	"component",
+	"repetition",
+	"escape",
+	"subcomponent"
+];
+/**
+* Extract delimiters from a Root AST by reading MSH-1 and MSH-2.
+*
+* MSH-1 contains the field separator character (e.g., `|`).
+* MSH-2 contains up to 4 encoding characters: component, repetition,
+* escape, and subcomponent (e.g., `^~\&`).
+*
+* Falls back to DEFAULT_DELIMITERS for any values that cannot be derived.
+*
+* @param root - The Root AST node to extract delimiters from.
+* @returns The resolved Delimiters object.
+*/
+function delimiters(root) {
+	const result = { ...DEFAULT_DELIMITERS };
+	const msh1 = value(root, "MSH-1")?.value;
+	if (msh1 && msh1.length === 1) result.field = msh1;
+	const msh2 = value(root, "MSH-2")?.value;
+	if (msh2) {
+		const chars = [...msh2];
+		for (const [i, key] of MSH2_KEYS.entries()) {
+			const ch = chars[i];
+			if (ch) result[key] = ch;
+		}
+	}
+	return result;
+}
+//#endregion
+//#region src/format.ts
+/**
+* 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.
+*
+* @example
+*   ```typescript
+*   visit(tree, "field", (node, ancestors) => {
+*     format(node, ancestors); // "PID-5"
+*   });
+*
+*   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
+*/
+function format(node, ancestors) {
+	let result = null;
+	const chain = [...ancestors, node];
+	for (const [i, current] of chain.entries()) {
+		const parent = chain[i - 1];
+		switch (current.type) {
+			case "root": break;
+			case "group":
+			case "segment": {
+				const pos = positionOf(current, parent);
+				result = (result ?? "") + current.name;
+				if (pos > 1) result += `[${pos}]`;
+				if (current.type === "group" && current !== node) result += "-";
+				break;
+			}
+			case "field":
+				result += `-${positionOf(current, parent)}`;
+				break;
+			case "field-repetition": {
+				const pos = positionOf(current, parent);
+				if (pos > 1 || current === node) result += `[${pos}]`;
+				break;
+			}
+			case "component":
+				result += `.${positionOf(current, parent)}`;
+				break;
+			case "subcomponent":
+				result += `.${positionOf(current, parent)}`;
+				break;
+		}
+	}
+	return result;
+}
+/**
+* Compute the 1-based position of a node among its parent's children.
+*
+* For named nodes (segments, groups), counts only same-name siblings
+* because segments are identified by name: 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.
+*/
+function positionOf(node, parent) {
+	if (!parent || !("children" in parent)) return 1;
+	const children = parent.children;
+	if ("name" in node) {
+		const name = node.name;
+		const { type } = node;
+		let count = 0;
+		for (const child of children) {
+			if (child === node) return count + 1;
+			if (child.type === type && "name" in child && child.name === name) count++;
+		}
+		throw new Error("format(): node not found in parent's children array");
+	}
+	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.
+*
+* This is a convenience function equivalent to `select(root, path) !== null`,
+* but more semantically clear for existence checks.
+*
+* @example
+*   ```typescript
+*   if (matches(root, "PID-5")) {
+*     console.log("Patient has a name field");
+*   }
+*
+*   if (!matches(root, "OBX-5")) {
+*     throw new Error("Missing observation value");
+*   }
+*   ```;
+*
+* @param root - The root node to search 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 {
+		type: "field",
+		children: []
+	};
+}
+function stubRepetition() {
+	return {
+		type: "field-repetition",
+		children: []
+	};
+}
+function stubComponent() {
+	return {
+		type: "component",
+		children: []
+	};
+}
+function stubSubcomponent() {
+	return {
+		type: "subcomponent",
+		value: ""
+	};
+}
+//#endregion
+export { delimiters, format, matches, parse, select, selectAll, set, value };
+
+//# sourceMappingURL=index.js.map