@rethinkhealth/hl7v2-utils 0.2.14 → 0.2.15

package/dist/index.d.ts

@@ -1,14 +1,4 @@
-import type { Nodes } from '@rethinkhealth/hl7v2-ast';
-export declare const DEFAULT_DELIMITERS: {
-    field: string;
-    component: string;
-    repetition: string;
-    subcomponent: string;
-    escape: string;
-    segment: string;
-};
-/**
- * Utility: check if a node is semantically empty
- */
-export declare function isEmptyNode(node: Nodes | null | undefined): boolean;
+/** biome-ignore-all lint/performance/noBarrelFile: fine */
+export type { PathParts } from './types';
+export { DEFAULT_DELIMITERS, formatPath, getSegmentId, isEmptyNode, pathFromIndices, } from './utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAMtD,eAAO,MAAM,kBAAkB;;;;;;;CAO9B,CAAC;AAMF;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CA2BnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/index.ts
+// src/utils.ts
 var DEFAULT_DELIMITERS = {
   field: "|",
   component: "^",
@@ -25,8 +25,110 @@ function isEmptyNode(node) {
   }
   return false;
 }
+function validateHL7Number(value, componentName) {
+  if (!Number.isInteger(value)) {
+    throw new Error(`${componentName} must be an integer, got: ${value}`);
+  }
+  if (value < 1) {
+    throw new Error(
+      `${componentName} must be positive (1-based), got: ${value}`
+    );
+  }
+}
+function validateASTIndex(value, componentName) {
+  if (!Number.isInteger(value)) {
+    throw new Error(`${componentName} must be an integer, got: ${value}`);
+  }
+  if (value < 0) {
+    throw new Error(
+      `${componentName} must be non-negative (0-based), got: ${value}`
+    );
+  }
+}
+var SEGMENT_ID_PATTERN = /^[A-Z0-9]{2,4}$/;
+function validateSegmentId(segmentId) {
+  if (!segmentId || typeof segmentId !== "string") {
+    throw new Error(`segmentId must be a non-empty string, got: ${segmentId}`);
+  }
+  if (segmentId.trim() !== segmentId) {
+    throw new Error(
+      `segmentId cannot have leading/trailing whitespace, got: "${segmentId}"`
+    );
+  }
+  if (!SEGMENT_ID_PATTERN.test(segmentId)) {
+    throw new Error(
+      `segmentId must be 2-4 uppercase letters/numbers, got: "${segmentId}"`
+    );
+  }
+}
+function getSegmentId(seg) {
+  return seg.children[0]?.children[0]?.children[0]?.children[0]?.value ?? null;
+}
+function formatPath(parts) {
+  const { segmentId, field, repetition, component, subcomponent } = parts;
+  validateSegmentId(segmentId);
+  if (field != null) {
+    validateHL7Number(field, "field");
+  }
+  if (repetition != null) {
+    validateHL7Number(repetition, "repetition");
+  }
+  if (component != null) {
+    validateHL7Number(component, "component");
+  }
+  if (subcomponent != null) {
+    validateHL7Number(subcomponent, "subcomponent");
+  }
+  let out = segmentId;
+  if (typeof field === "number") {
+    out += `-${field}`;
+  }
+  if (typeof repetition === "number") {
+    out += `[${repetition}]`;
+  }
+  if (typeof component === "number") {
+    out += `.${component}`;
+  }
+  if (typeof subcomponent === "number") {
+    out += `.${subcomponent}`;
+  }
+  return out;
+}
+function pathFromIndices(parts) {
+  const {
+    segmentId,
+    fieldIndex,
+    repetitionIndex,
+    componentIndex,
+    subcomponentIndex
+  } = parts;
+  validateSegmentId(segmentId);
+  if (fieldIndex != null) {
+    validateHL7Number(fieldIndex, "fieldIndex");
+  }
+  if (repetitionIndex != null) {
+    validateASTIndex(repetitionIndex, "repetitionIndex");
+  }
+  if (componentIndex != null) {
+    validateASTIndex(componentIndex, "componentIndex");
+  }
+  if (subcomponentIndex != null) {
+    validateASTIndex(subcomponentIndex, "subcomponentIndex");
+  }
+  return formatPath({
+    segmentId,
+    field: fieldIndex,
+    // fieldIndex is already HL7 field number (or undefined)
+    repetition: repetitionIndex != null ? repetitionIndex + 1 : void 0,
+    component: componentIndex != null ? componentIndex + 1 : void 0,
+    subcomponent: subcomponentIndex != null ? subcomponentIndex + 1 : void 0
+  });
+}
 export {
   DEFAULT_DELIMITERS,
-  isEmptyNode
+  formatPath,
+  getSegmentId,
+  isEmptyNode,
+  pathFromIndices
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Nodes } from '@rethinkhealth/hl7v2-ast';\n\n// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  field: '|',\n  component: '^',\n  repetition: '~',\n  subcomponent: '&',\n  escape: '\\\\',\n  segment: '\\r',\n};\n\n// -------------\n// General\n// -------------\n\n/**\n * Utility: check if a node is semantically empty\n */\nexport function isEmptyNode(node: Nodes | null | undefined): boolean {\n  if (!node) {\n    return true;\n  }\n\n  // If node has a \"value\" property (Subcomponent, maybe Component)\n  if ('value' in node) {\n    return !node.value || node.value.trim() === '';\n  }\n\n  // If node has children (Field, Component, Repetition, Segment, Root, etc.)\n  if ('children' in node) {\n    if (!node.children || node.children.length === 0) {\n      return true;\n    }\n\n    // If node has more than one child, then it is considered non-empty\n    if (node.children.length > 1) {\n      return false;\n    }\n\n    // If node has only one child, then it is considered empty if the child is also empty\n    return isEmptyNode(node.children[0]);\n  }\n\n  // Fallback: consider unknown node as non-empty\n  return false;\n}\n"],"mappings":";AAMO,IAAM,qBAAqB;AAAA,EAChC,OAAO;AAAA,EACP,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,SAAS;AACX;AASO,SAAS,YAAY,MAAyC;AACnE,MAAI,CAAC,MAAM;AACT,WAAO;AAAA,EACT;AAGA,MAAI,WAAW,MAAM;AACnB,WAAO,CAAC,KAAK,SAAS,KAAK,MAAM,KAAK,MAAM;AAAA,EAC9C;AAGA,MAAI,cAAc,MAAM;AACtB,QAAI,CAAC,KAAK,YAAY,KAAK,SAAS,WAAW,GAAG;AAChD,aAAO;AAAA,IACT;AAGA,QAAI,KAAK,SAAS,SAAS,GAAG;AAC5B,aAAO;AAAA,IACT;AAGA,WAAO,YAAY,KAAK,SAAS,CAAC,CAAC;AAAA,EACrC;AAGA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/utils.ts"],"sourcesContent":["import type { Nodes, Segment } from '@rethinkhealth/hl7v2-ast';\nimport type { PathParts } from './types';\n\n// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  field: '|',\n  component: '^',\n  repetition: '~',\n  subcomponent: '&',\n  escape: '\\\\',\n  segment: '\\r',\n};\n\n// -------------\n// General\n// -------------\n\n/**\n * Utility: check if a node is semantically empty\n */\nexport function isEmptyNode(node: Nodes | null | undefined): boolean {\n  if (!node) {\n    return true;\n  }\n\n  // If node has a \"value\" property (Subcomponent, maybe Component)\n  if ('value' in node) {\n    return !node.value || node.value.trim() === '';\n  }\n\n  // If node has children (Field, Component, Repetition, Segment, Root, etc.)\n  if ('children' in node) {\n    if (!node.children || node.children.length === 0) {\n      return true;\n    }\n\n    // If node has more than one child, then it is considered non-empty\n    if (node.children.length > 1) {\n      return false;\n    }\n\n    // If node has only one child, then it is considered empty if the child is also empty\n    return isEmptyNode(node.children[0]);\n  }\n\n  // Fallback: consider unknown node as non-empty\n  return false;\n}\n\n/**\n * Validates that a numeric value is a valid HL7 component number.\n *\n * @param value - The value to validate\n * @param componentName - Name of the component for error messages\n * @throws {Error} If the value is not a valid positive integer\n */\nfunction validateHL7Number(value: number, componentName: string): void {\n  if (!Number.isInteger(value)) {\n    throw new Error(`${componentName} must be an integer, got: ${value}`);\n  }\n  if (value < 1) {\n    throw new Error(\n      `${componentName} must be positive (1-based), got: ${value}`\n    );\n  }\n}\n\n/**\n * Validates that an AST index is a valid non-negative integer.\n *\n * @param value - The value to validate\n * @param componentName - Name of the component for error messages\n * @throws {Error} If the value is not a valid non-negative integer\n */\nfunction validateASTIndex(value: number, componentName: string): void {\n  if (!Number.isInteger(value)) {\n    throw new Error(`${componentName} must be an integer, got: ${value}`);\n  }\n  if (value < 0) {\n    throw new Error(\n      `${componentName} must be non-negative (0-based), got: ${value}`\n    );\n  }\n}\n\n// Regex pattern for valid segment IDs (2-4 uppercase letters/numbers)\nconst SEGMENT_ID_PATTERN = /^[A-Z0-9]{2,4}$/;\n\n/**\n * Validates a segment ID string.\n *\n * @param segmentId - The segment ID to validate\n * @throws {Error} If the segment ID is invalid\n */\nfunction validateSegmentId(segmentId: string): void {\n  if (!segmentId || typeof segmentId !== 'string') {\n    throw new Error(`segmentId must be a non-empty string, got: ${segmentId}`);\n  }\n  if (segmentId.trim() !== segmentId) {\n    throw new Error(\n      `segmentId cannot have leading/trailing whitespace, got: \"${segmentId}\"`\n    );\n  }\n  if (!SEGMENT_ID_PATTERN.test(segmentId)) {\n    throw new Error(\n      `segmentId must be 2-4 uppercase letters/numbers, got: \"${segmentId}\"`\n    );\n  }\n}\n\n/**\n * Extracts the segment ID from the segment's first field.\n *\n * Traverses the AST structure to find the segment identifier stored\n * in the first field's first repetition's first component's first\n * subcomponent value.\n *\n * @param seg - The segment AST node to extract the ID from\n * @returns The segment ID string (e.g., 'PID', 'MSH'), or null if not found\n *\n * @example\n * ```ts\n * const segmentId = getSegmentId(segmentNode);\n * if (segmentId === 'PID') {\n *   console.log('Processing patient identification segment');\n * }\n * ```\n */\nexport function getSegmentId(seg: Segment): string | null {\n  return seg.children[0]?.children[0]?.children[0]?.children[0]?.value ?? null;\n}\n\n/**\n * Builds an HL7 path string from structured path components.\n *\n * Constructs a standardized HL7 path string using the format:\n * `SEGMENT-FIELD[REPETITION].COMPONENT.SUBCOMPONENT`\n *\n * **IMPORTANT: All numeric components use 1-based HL7 numbering.**\n * This function expects HL7-standard 1-based numbers, not 0-based AST indices.\n * Use `pathFromIndices()` if you have 0-based AST indices to convert.\n *\n * Components are added incrementally - if a field is not provided,\n * none of its child components will be included in the path.\n *\n * @param parts - Path components using HL7 1-based numbering\n * @param parts.segmentId - Segment identifier (required, 2-4 uppercase chars)\n * @param parts.field - HL7 field number (1-based, optional, must be ≥1)\n * @param parts.repetition - Repetition number (1-based, optional, must be ≥1)\n * @param parts.component - Component number (1-based, optional, must be ≥1)\n * @param parts.subcomponent - Subcomponent number (1-based, optional, must be ≥1)\n * @returns Formatted HL7 path string\n * @throws {Error} If any numeric component is not a positive integer\n *\n * @example\n * ```ts\n * // Segment only\n * formatPath({ segmentId: 'PID' });\n * // Result: \"PID\"\n *\n * // Field path (HL7 field 5 = 1-based)\n * formatPath({ segmentId: 'PID', field: 5 });\n * // Result: \"PID-5\"\n *\n * // Complete path with HL7 1-based numbering\n * formatPath({\n *   segmentId: 'PID',\n *   field: 5,        // HL7 field 5 (1-based)\n *   repetition: 1,   // First repetition (1-based)\n *   component: 2,    // Second component (1-based)\n *   subcomponent: 1  // First subcomponent (1-based)\n * });\n * // Result: \"PID-5[1].2.1\"\n *\n * // Error cases - these will throw:\n * formatPath({ segmentId: 'PID', field: 0 });        // Error: field must be ≥1\n * formatPath({ segmentId: 'PID', field: 1.5 });      // Error: must be integer\n * formatPath({ segmentId: '' });                     // Error: invalid segment ID\n * ```\n */\nexport function formatPath(parts: PathParts): string {\n  const { segmentId, field, repetition, component, subcomponent } = parts;\n\n  // Validate segment ID\n  validateSegmentId(segmentId);\n\n  // Validate numeric components (all should be 1-based positive integers)\n  if (field != null) {\n    validateHL7Number(field, 'field');\n  }\n  if (repetition != null) {\n    validateHL7Number(repetition, 'repetition');\n  }\n  if (component != null) {\n    validateHL7Number(component, 'component');\n  }\n  if (subcomponent != null) {\n    validateHL7Number(subcomponent, 'subcomponent');\n  }\n\n  // Build path string\n  let out = segmentId;\n  if (typeof field === 'number') {\n    out += `-${field}`;\n  }\n  if (typeof repetition === 'number') {\n    out += `[${repetition}]`;\n  }\n  if (typeof component === 'number') {\n    out += `.${component}`;\n  }\n  if (typeof subcomponent === 'number') {\n    out += `.${subcomponent}`;\n  }\n  return out;\n}\n\n/**\n * Converts AST indices to 1-based HL7 path format, including only present components.\n *\n * Helper function for converting AST traversal indices to HL7 path strings.\n * Only includes path components that are explicitly provided (not undefined).\n * This prevents generating incomplete paths like \"PID-[1]\" when field is missing.\n *\n * **IMPORTANT: Mixed indexing convention:**\n * - `fieldIndex`: HL7 field number (1-based)\n * - Other indices: 0-based AST indices, converted to 1-based HL7 numbering\n *\n * @param parts - AST index-based path components\n * @param parts.segmentId - Segment identifier (required, 2-4 uppercase chars)\n * @param parts.fieldIndex - HL7 field number (1-based, optional, must be ≥1)\n * @param parts.repetitionIndex - 0-based repetition index (optional, must be ≥0)\n * @param parts.componentIndex - 0-based component index (optional, must be ≥0)\n * @param parts.subcomponentIndex - 0-based subcomponent index (optional, must be ≥0)\n * @returns Formatted HL7 path string with only present components\n * @throws {Error} If any provided index is invalid\n *\n * @example\n * ```ts\n * // Full path with all components\n * pathFromIndices({\n *   segmentId: 'PID',\n *   fieldIndex: 4,        // HL7 field number -> HL7 field 4\n *   repetitionIndex: 0,   // 0-based AST index -> HL7 [1]\n *   componentIndex: 1     // 0-based AST index -> HL7 .2\n * });\n * // Result: \"PID-4[1].2\"\n *\n * // Partial path - only includes present components\n * pathFromIndices({\n *   segmentId: 'PID',\n *   fieldIndex: 5         // Only field provided\n * });\n * // Result: \"PID-5\" (not \"PID-5[undefined]\")\n *\n * pathFromIndices({\n *   segmentId: 'PID'      // Only segment provided\n * });\n * // Result: \"PID\" (segment-level path)\n *\n * // Common usage during AST traversal\n * visit(root, (node, index, parent) => {\n *   if (isComponent(node)) {\n *     const path = pathFromIndices({\n *       segmentId: getSegmentId(segmentNode),\n *       fieldIndex: fieldNumber,      // HL7 field number (1-based)\n *       repetitionIndex: repIndex,    // 0-based from parent.children[repIndex]\n *       componentIndex: compIndex     // 0-based from parent.children[compIndex]\n *       // subcomponentIndex omitted if not relevant\n *     });\n *\n *     reportDiagnostic(file, {\n *       code: 'invalid_value',\n *       message: 'Component value is invalid',\n *       source: 'field',\n *       path // Clean path: \"PID-4[1].2\"\n *     }, { ruleId: 'field:value' });\n *   }\n * });\n * ```\n */\nexport function pathFromIndices(parts: {\n  segmentId: string;\n  fieldIndex?: number; // HL7 field number (1-based)\n  repetitionIndex?: number; // 0-based AST index\n  componentIndex?: number; // 0-based AST index\n  subcomponentIndex?: number; // 0-based AST index\n}): string {\n  const {\n    segmentId,\n    fieldIndex,\n    repetitionIndex,\n    componentIndex,\n    subcomponentIndex,\n  } = parts;\n\n  // Validate segment ID\n  validateSegmentId(segmentId);\n\n  // Validate provided indices (undefined values are skipped)\n  if (fieldIndex != null) {\n    validateHL7Number(fieldIndex, 'fieldIndex'); // fieldIndex is HL7 field number (1-based)\n  }\n  if (repetitionIndex != null) {\n    validateASTIndex(repetitionIndex, 'repetitionIndex');\n  }\n  if (componentIndex != null) {\n    validateASTIndex(componentIndex, 'componentIndex');\n  }\n  if (subcomponentIndex != null) {\n    validateASTIndex(subcomponentIndex, 'subcomponentIndex');\n  }\n\n  // Build path with only present components\n  return formatPath({\n    segmentId,\n    field: fieldIndex, // fieldIndex is already HL7 field number (or undefined)\n    repetition: repetitionIndex != null ? repetitionIndex + 1 : undefined,\n    component: componentIndex != null ? componentIndex + 1 : undefined,\n    subcomponent: subcomponentIndex != null ? subcomponentIndex + 1 : undefined,\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Components for building HL7 path strings.
+ *
+ * All numeric components use 1-based indexing to match HL7 conventions,
+ * except where explicitly noted for AST traversal helpers.
+ */
+export type PathParts = {
+    segmentId: string;
+    field?: number;
+    repetition?: number;
+    component?: number;
+    subcomponent?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,154 @@
+import type { Nodes, Segment } from '@rethinkhealth/hl7v2-ast';
+import type { PathParts } from './types';
+export declare const DEFAULT_DELIMITERS: {
+    field: string;
+    component: string;
+    repetition: string;
+    subcomponent: string;
+    escape: string;
+    segment: string;
+};
+/**
+ * Utility: check if a node is semantically empty
+ */
+export declare function isEmptyNode(node: Nodes | null | undefined): boolean;
+/**
+ * Extracts the segment ID from the segment's first field.
+ *
+ * Traverses the AST structure to find the segment identifier stored
+ * in the first field's first repetition's first component's first
+ * subcomponent value.
+ *
+ * @param seg - The segment AST node to extract the ID from
+ * @returns The segment ID string (e.g., 'PID', 'MSH'), or null if not found
+ *
+ * @example
+ * ```ts
+ * const segmentId = getSegmentId(segmentNode);
+ * if (segmentId === 'PID') {
+ *   console.log('Processing patient identification segment');
+ * }
+ * ```
+ */
+export declare function getSegmentId(seg: Segment): string | null;
+/**
+ * Builds an HL7 path string from structured path components.
+ *
+ * Constructs a standardized HL7 path string using the format:
+ * `SEGMENT-FIELD[REPETITION].COMPONENT.SUBCOMPONENT`
+ *
+ * **IMPORTANT: All numeric components use 1-based HL7 numbering.**
+ * This function expects HL7-standard 1-based numbers, not 0-based AST indices.
+ * Use `pathFromIndices()` if you have 0-based AST indices to convert.
+ *
+ * Components are added incrementally - if a field is not provided,
+ * none of its child components will be included in the path.
+ *
+ * @param parts - Path components using HL7 1-based numbering
+ * @param parts.segmentId - Segment identifier (required, 2-4 uppercase chars)
+ * @param parts.field - HL7 field number (1-based, optional, must be ≥1)
+ * @param parts.repetition - Repetition number (1-based, optional, must be ≥1)
+ * @param parts.component - Component number (1-based, optional, must be ≥1)
+ * @param parts.subcomponent - Subcomponent number (1-based, optional, must be ≥1)
+ * @returns Formatted HL7 path string
+ * @throws {Error} If any numeric component is not a positive integer
+ *
+ * @example
+ * ```ts
+ * // Segment only
+ * formatPath({ segmentId: 'PID' });
+ * // Result: "PID"
+ *
+ * // Field path (HL7 field 5 = 1-based)
+ * formatPath({ segmentId: 'PID', field: 5 });
+ * // Result: "PID-5"
+ *
+ * // Complete path with HL7 1-based numbering
+ * formatPath({
+ *   segmentId: 'PID',
+ *   field: 5,        // HL7 field 5 (1-based)
+ *   repetition: 1,   // First repetition (1-based)
+ *   component: 2,    // Second component (1-based)
+ *   subcomponent: 1  // First subcomponent (1-based)
+ * });
+ * // Result: "PID-5[1].2.1"
+ *
+ * // Error cases - these will throw:
+ * formatPath({ segmentId: 'PID', field: 0 });        // Error: field must be ≥1
+ * formatPath({ segmentId: 'PID', field: 1.5 });      // Error: must be integer
+ * formatPath({ segmentId: '' });                     // Error: invalid segment ID
+ * ```
+ */
+export declare function formatPath(parts: PathParts): string;
+/**
+ * Converts AST indices to 1-based HL7 path format, including only present components.
+ *
+ * Helper function for converting AST traversal indices to HL7 path strings.
+ * Only includes path components that are explicitly provided (not undefined).
+ * This prevents generating incomplete paths like "PID-[1]" when field is missing.
+ *
+ * **IMPORTANT: Mixed indexing convention:**
+ * - `fieldIndex`: HL7 field number (1-based)
+ * - Other indices: 0-based AST indices, converted to 1-based HL7 numbering
+ *
+ * @param parts - AST index-based path components
+ * @param parts.segmentId - Segment identifier (required, 2-4 uppercase chars)
+ * @param parts.fieldIndex - HL7 field number (1-based, optional, must be ≥1)
+ * @param parts.repetitionIndex - 0-based repetition index (optional, must be ≥0)
+ * @param parts.componentIndex - 0-based component index (optional, must be ≥0)
+ * @param parts.subcomponentIndex - 0-based subcomponent index (optional, must be ≥0)
+ * @returns Formatted HL7 path string with only present components
+ * @throws {Error} If any provided index is invalid
+ *
+ * @example
+ * ```ts
+ * // Full path with all components
+ * pathFromIndices({
+ *   segmentId: 'PID',
+ *   fieldIndex: 4,        // HL7 field number -> HL7 field 4
+ *   repetitionIndex: 0,   // 0-based AST index -> HL7 [1]
+ *   componentIndex: 1     // 0-based AST index -> HL7 .2
+ * });
+ * // Result: "PID-4[1].2"
+ *
+ * // Partial path - only includes present components
+ * pathFromIndices({
+ *   segmentId: 'PID',
+ *   fieldIndex: 5         // Only field provided
+ * });
+ * // Result: "PID-5" (not "PID-5[undefined]")
+ *
+ * pathFromIndices({
+ *   segmentId: 'PID'      // Only segment provided
+ * });
+ * // Result: "PID" (segment-level path)
+ *
+ * // Common usage during AST traversal
+ * visit(root, (node, index, parent) => {
+ *   if (isComponent(node)) {
+ *     const path = pathFromIndices({
+ *       segmentId: getSegmentId(segmentNode),
+ *       fieldIndex: fieldNumber,      // HL7 field number (1-based)
+ *       repetitionIndex: repIndex,    // 0-based from parent.children[repIndex]
+ *       componentIndex: compIndex     // 0-based from parent.children[compIndex]
+ *       // subcomponentIndex omitted if not relevant
+ *     });
+ *
+ *     reportDiagnostic(file, {
+ *       code: 'invalid_value',
+ *       message: 'Component value is invalid',
+ *       source: 'field',
+ *       path // Clean path: "PID-4[1].2"
+ *     }, { ruleId: 'field:value' });
+ *   }
+ * });
+ * ```
+ */
+export declare function pathFromIndices(parts: {
+    segmentId: string;
+    fieldIndex?: number;
+    repetitionIndex?: number;
+    componentIndex?: number;
+    subcomponentIndex?: number;
+}): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAMzC,eAAO,MAAM,kBAAkB;;;;;;;CAO9B,CAAC;AAMF;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CA2BnE;AA+DD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAmCnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,MAAM,CAkCT"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rethinkhealth/hl7v2-utils",
   "description": "hl7v2 utilities",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "license": "MIT",
   "author": {
     "name": "Melek Somai",
@@ -24,8 +24,8 @@
     "typescript": "^5.8.3",
     "unist-builder": "^4.0.0",
     "vitest": "^3.2.4",
-    "@rethinkhealth/hl7v2-ast": "0.2.14",
     "@rethinkhealth/testing": "0.0.1",
+    "@rethinkhealth/hl7v2-ast": "0.2.15",
     "@rethinkhealth/tsconfig": "0.0.1"
   },
   "repository": "rethinkhealth/hl7v2.git",