@rethinkhealth/hl7v2-utils 0.5.0 → 0.7.0

package/dist/index.js

@@ -20,10 +20,7 @@ function isEmptyNode(node) {
     if (!node.children || node.children.length === 0) {
       return true;
     }
-    if (node.children.length > 1) {
-      return false;
-    }
-    return isEmptyNode(node.children[0]);
+    return node.children.every((child) => isEmptyNode(child));
   }
   return false;
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts","../src/utils.ts","../src/constraints.ts"],"sourcesContent":["// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  component: \"^\",\n  escape: \"\\\\\",\n  field: \"|\",\n  repetition: \"~\",\n  segment: \"\\r\",\n  subcomponent: \"&\",\n};\n","import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\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// Byte Length\n// -------------\n\n/**\n * Calculate the byte length of any HL7v2 AST node.\n *\n * For literal nodes (Subcomponent), returns the UTF-8 byte length of the value.\n * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.\n *\n * @param node - The HL7v2 AST node to measure\n * @returns The total byte length of the node content\n *\n * @example\n * ```ts\n * const field: Field = { type: \"field\", children: [...] };\n * const length = getByteLength(field); // e.g., 42\n * ```\n */\nexport function getByteLength(node?: Nodes | null | undefined): number {\n  if (!node) {\n    return 0;\n  }\n\n  if (\"value\" in node) {\n    return Buffer.byteLength(node.value, \"utf8\");\n  }\n\n  const nameLength =\n    node.type === \"segment\" ? Buffer.byteLength(node.name, \"utf8\") : 0;\n\n  return (\n    nameLength +\n    node.children.reduce((total, child) => total + getByteLength(child), 0)\n  );\n}\n\n// -------------\n// Length\n// -------------\n\n/**\n * Calculate the string length of any HL7v2 AST node.\n *\n * For literal nodes (Subcomponent), returns `value.length`.\n * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.\n *\n * Note: Returns JavaScript string length (UTF-16 code units). For UTF-8 byte\n * length (e.g., for wire protocol), use `getByteLength` instead.\n *\n * @param node - The HL7v2 AST node to measure\n * @returns The total string length of the node content\n *\n * @example\n * ```ts\n * const field: Field = { type: \"field\", children: [...] };\n * const length = getLength(field); // e.g., 42\n * ```\n */\nexport function getLength(node?: Nodes | null | undefined): number {\n  if (!node) {\n    return 0;\n  }\n\n  if (\"value\" in node) {\n    return node.value.length;\n  }\n\n  const nameLength = node.type === \"segment\" ? node.name.length : 0;\n\n  return (\n    nameLength +\n    node.children.reduce((total, child) => total + getLength(child), 0)\n  );\n}\n","import type { Field, Nodes } from \"@rethinkhealth/hl7v2-ast\";\n\nimport { getLength, isEmptyNode } from \"./utils\";\n\nexport type ValidationErrorCode =\n  // Constraints\n  | \"MISSING\"\n  | \"EMPTY\"\n  | \"UNEXPECTED_CONTENT\"\n  | \"CARDINALITY_UNDERFLOW\"\n  | \"CARDINALITY_OVERFLOW\"\n  | \"LENGTH_UNDERFLOW\"\n  | \"LENGTH_OVERFLOW\"\n  // Value Sets\n  | \"VALUE_NOT_IN_TABLE\";\n\nexport interface ValidationError {\n  code: ValidationErrorCode;\n  message: string;\n  expected?: string | number | Array<string | number>;\n  actual?: string | number | Array<string | number>;\n}\n\nexport interface ValidationSuccess {\n  ok: true;\n}\n\nexport interface ValidationFailure {\n  ok: false;\n  error: ValidationError;\n}\n\nexport type ValidationResult = ValidationSuccess | ValidationFailure;\n\nexport const OptionalityCode = {\n  /**\n   * Backward Compatible\n   *\n   * There are no implementation requirements. The “B” usage indicates that the\n   * element is retained for backwards compatibility of the element. Another\n   * usage indicator may be assigned in a derived profile.\n   */\n  BackwardCompatible: \"B\",\n\n  /**\n   * Undeclared / Conditional.\n   *\n   * There are no implementation requirements. The “C” usage designation is a\n   * placeholder indicating that the usage for this element has not yet been\n   * specified.\n   */\n  Conditional: \"C\",\n\n  /**\n   * Not Supported.\n   *\n   * There are no implementation requirements. The application must not value an\n   * element with an “X” usage designation.\n   */\n  NotSupported: \"X\",\n\n  /**\n   * Optional\n   *\n   * There are no implementation requirements. The “O” usage designation is a\n   * placeholder indicating that the usage for this element has not yet been\n   * specified.\n   */\n  Optional: \"O\",\n\n  /**\n   * Required\n   */\n  Required: \"R\",\n\n  /**\n   * Required, but may be empty.\n   *\n   * The use of the RE usage code is qualified with the “if data is known”\n   * clause. The sender must interpret the clause as “the capability must always\n   * be supported, and data must always be sent if known”. To clarify, the\n   * sender does not determine whether the data should be sent; to be conformant\n   * to the rule, the data must be sent. There is a misconception where the RE\n   * usage is interpreted as “the capability must always be supported, and data\n   * may or may not be sent even when known based on a condition external to the\n   * profile specification”.\n   *\n   * The receiving application must process in a meaningful way the information\n   * conveyed by an element with an “RE” usage designation.\n   * The receiving application must process the message if the element is omitted\n   * (that is, an exception must not be raised because the element is missing). A\n   * receiving application must not raise an exception due to the presence of a\n   * required element.\n   */\n  RequiredOrEmpty: \"RE\",\n\n  /**\n   * Withdrawn\n   *\n   * The element has been withdrawn from the standard. There are no\n   * implementation requirements. The application must not value an element with\n   * a \"W\" usage designation.\n   */\n  Withdrawn: \"W\",\n} as const;\n\nexport type OptionalityCode =\n  (typeof OptionalityCode)[keyof typeof OptionalityCode];\n\n/**\n * Checks if a field satisfies the cardinality constraint.\n */\nexport function checkCardinality(\n  node: Field | undefined,\n  min: number,\n  max: number | \"*\"\n): ValidationResult {\n  if (min < 0 || (max !== \"*\" && max < 0)) {\n    throw new Error(\"Min and max lengths must be non-negative\");\n  }\n\n  if (max !== \"*\" && min > max) {\n    throw new Error(\"Min length cannot be greater than max length\");\n  }\n\n  const count = node?.children ? node.children.length : 0;\n\n  if (count < min) {\n    return {\n      error: {\n        actual: count,\n        code: \"CARDINALITY_UNDERFLOW\",\n        expected: min,\n        message: `has ${count} repetitions but requires at least ${min}`,\n      },\n      ok: false,\n    };\n  }\n\n  if (max !== \"*\" && count > max) {\n    return {\n      error: {\n        actual: count,\n        code: \"CARDINALITY_OVERFLOW\",\n        expected: max,\n        message: `has ${count} repetitions but allows at most ${max}`,\n      },\n      ok: false,\n    };\n  }\n\n  return { ok: true };\n}\n\n/**\n * Checks if a node satisfies the length constraint.\n */\nexport function checkLength(\n  node: Nodes | undefined,\n  max: number,\n  min = 0\n): ValidationResult {\n  if (min < 0 || max < 0) {\n    throw new Error(\"Min and max lengths must be non-negative\");\n  }\n\n  if (min > max) {\n    throw new Error(\"Min length cannot be greater than max length\");\n  }\n\n  const length = getLength(node);\n\n  if (length < min) {\n    return {\n      error: {\n        actual: length,\n        code: \"LENGTH_UNDERFLOW\",\n        expected: min,\n        message: `has length ${length} but requires at least ${min}`,\n      },\n      ok: false,\n    };\n  }\n\n  if (length > max) {\n    return {\n      error: {\n        actual: length,\n        code: \"LENGTH_OVERFLOW\",\n        expected: max,\n        message: `has length ${length} but allows at most ${max}`,\n      },\n      ok: false,\n    };\n  }\n\n  return { ok: true };\n}\n\n/**\n * Checks if a node satisfies the optionality constraint.\n */\nexport function checkOptionality(\n  node: Nodes | undefined,\n  optionality: OptionalityCode | string\n): ValidationResult {\n  const code = optionality.toUpperCase();\n\n  switch (code) {\n    case OptionalityCode.Required: {\n      if (!node) {\n        return {\n          error: {\n            code: \"MISSING\",\n            expected: \"R\",\n            message: \"is required but missing\",\n          },\n          ok: false,\n        };\n      }\n      if (isEmptyNode(node)) {\n        return {\n          error: {\n            code: \"EMPTY\",\n            expected: \"R\",\n            message: \"is required but empty\",\n          },\n          ok: false,\n        };\n      }\n      return { ok: true };\n    }\n\n    case OptionalityCode.NotSupported: {\n      if (node && !isEmptyNode(node)) {\n        return {\n          error: {\n            code: \"UNEXPECTED_CONTENT\",\n            expected: \"X\",\n            message: \"is not supported but present\",\n          },\n          ok: false,\n        };\n      }\n      return { ok: true };\n    }\n\n    case OptionalityCode.RequiredOrEmpty:\n    case OptionalityCode.Optional:\n    case OptionalityCode.Conditional:\n    case OptionalityCode.BackwardCompatible:\n    case OptionalityCode.Withdrawn: {\n      return { ok: true };\n    }\n\n    default: {\n      return { ok: true };\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/constants.ts","../src/utils.ts","../src/constraints.ts"],"sourcesContent":["// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  component: \"^\",\n  escape: \"\\\\\",\n  field: \"|\",\n  repetition: \"~\",\n  segment: \"\\r\",\n  subcomponent: \"&\",\n};\n","import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\n\n// -------------\n// General\n// -------------\n\n/**\n * Check if an HL7v2 AST node is semantically empty.\n *\n * A node is empty when it contains no meaningful data — no subcomponent\n * anywhere in its subtree has a non-empty string value.\n *\n * This follows the HL7v2 specification (Chapter 2, Section 2.5.3) and\n * Conformance Methodology R1 (2019) definition of \"non-empty value\":\n * at least one character must be a non-whitespace character.\n *\n * ## HL7v2 emptiness semantics\n *\n * | Encoding    | Wire form     | isEmpty? | Meaning                          |\n * |-------------|---------------|----------|----------------------------------|\n * | `value`     | `\\|value\\|`   | `false`  | Field has data                   |\n * | `^DOE`      | `\\|^DOE\\|`    | `false`  | Component 2 has data             |\n * | `~value`    | `\\|~value\\|`  | `false`  | Repetition 2 has data            |\n * | `\"\"`        | `\\|\"\"\\|`      | `false`  | Explicit null (delete indicator) |\n * | (empty)     | `\\|\\|`        | `true`   | Not present                      |\n * | `^^`        | `\\|^^\\|`      | `true`   | Empty components                 |\n * | `~`         | `\\|~\\|`       | `true`   | Empty repetitions                |\n * | `~^^`       | `\\|~^^\\|`     | `true`   | Empty reps with empty components |\n *\n * @param node - The HL7v2 AST node to check (or null/undefined)\n * @returns `true` if the node has no meaningful data\n */\nexport function isEmptyNode(node?: Nodes | null | undefined): boolean {\n  if (!node) {\n    return true;\n  }\n\n  // Leaf node (Subcomponent): check its string value\n  if (\"value\" in node) {\n    return !node.value || node.value.trim() === \"\";\n  }\n\n  // Parent node: empty if ALL children are empty\n  if (\"children\" in node) {\n    if (!node.children || node.children.length === 0) {\n      return true;\n    }\n\n    return node.children.every((child) => isEmptyNode(child));\n  }\n\n  // Fallback: consider unknown node as non-empty\n  return false;\n}\n\n// -------------\n// Byte Length\n// -------------\n\n/**\n * Calculate the byte length of any HL7v2 AST node.\n *\n * For literal nodes (Subcomponent), returns the UTF-8 byte length of the value.\n * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.\n *\n * @param node - The HL7v2 AST node to measure\n * @returns The total byte length of the node content\n *\n * @example\n * ```ts\n * const field: Field = { type: \"field\", children: [...] };\n * const length = getByteLength(field); // e.g., 42\n * ```\n */\nexport function getByteLength(node?: Nodes | null | undefined): number {\n  if (!node) {\n    return 0;\n  }\n\n  if (\"value\" in node) {\n    return Buffer.byteLength(node.value, \"utf8\");\n  }\n\n  const nameLength =\n    node.type === \"segment\" ? Buffer.byteLength(node.name, \"utf8\") : 0;\n\n  return (\n    nameLength +\n    node.children.reduce((total, child) => total + getByteLength(child), 0)\n  );\n}\n\n// -------------\n// Length\n// -------------\n\n/**\n * Calculate the string length of any HL7v2 AST node.\n *\n * For literal nodes (Subcomponent), returns `value.length`.\n * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.\n *\n * Note: Returns JavaScript string length (UTF-16 code units). For UTF-8 byte\n * length (e.g., for wire protocol), use `getByteLength` instead.\n *\n * @param node - The HL7v2 AST node to measure\n * @returns The total string length of the node content\n *\n * @example\n * ```ts\n * const field: Field = { type: \"field\", children: [...] };\n * const length = getLength(field); // e.g., 42\n * ```\n */\nexport function getLength(node?: Nodes | null | undefined): number {\n  if (!node) {\n    return 0;\n  }\n\n  if (\"value\" in node) {\n    return node.value.length;\n  }\n\n  const nameLength = node.type === \"segment\" ? node.name.length : 0;\n\n  return (\n    nameLength +\n    node.children.reduce((total, child) => total + getLength(child), 0)\n  );\n}\n","import type { Field, Nodes } from \"@rethinkhealth/hl7v2-ast\";\n\nimport { getLength, isEmptyNode } from \"./utils\";\n\nexport type ValidationErrorCode =\n  // Constraints\n  | \"MISSING\"\n  | \"EMPTY\"\n  | \"UNEXPECTED_CONTENT\"\n  | \"CARDINALITY_UNDERFLOW\"\n  | \"CARDINALITY_OVERFLOW\"\n  | \"LENGTH_UNDERFLOW\"\n  | \"LENGTH_OVERFLOW\"\n  // Value Sets\n  | \"VALUE_NOT_IN_TABLE\";\n\nexport interface ValidationError {\n  code: ValidationErrorCode;\n  message: string;\n  expected?: string | number | Array<string | number>;\n  actual?: string | number | Array<string | number>;\n}\n\nexport interface ValidationSuccess {\n  ok: true;\n}\n\nexport interface ValidationFailure {\n  ok: false;\n  error: ValidationError;\n}\n\nexport type ValidationResult = ValidationSuccess | ValidationFailure;\n\nexport const OptionalityCode = {\n  /**\n   * Backward Compatible\n   *\n   * There are no implementation requirements. The “B” usage indicates that the\n   * element is retained for backwards compatibility of the element. Another\n   * usage indicator may be assigned in a derived profile.\n   */\n  BackwardCompatible: \"B\",\n\n  /**\n   * Undeclared / Conditional.\n   *\n   * There are no implementation requirements. The “C” usage designation is a\n   * placeholder indicating that the usage for this element has not yet been\n   * specified.\n   */\n  Conditional: \"C\",\n\n  /**\n   * Not Supported.\n   *\n   * There are no implementation requirements. The application must not value an\n   * element with an “X” usage designation.\n   */\n  NotSupported: \"X\",\n\n  /**\n   * Optional\n   *\n   * There are no implementation requirements. The “O” usage designation is a\n   * placeholder indicating that the usage for this element has not yet been\n   * specified.\n   */\n  Optional: \"O\",\n\n  /**\n   * Required\n   */\n  Required: \"R\",\n\n  /**\n   * Required, but may be empty.\n   *\n   * The use of the RE usage code is qualified with the “if data is known”\n   * clause. The sender must interpret the clause as “the capability must always\n   * be supported, and data must always be sent if known”. To clarify, the\n   * sender does not determine whether the data should be sent; to be conformant\n   * to the rule, the data must be sent. There is a misconception where the RE\n   * usage is interpreted as “the capability must always be supported, and data\n   * may or may not be sent even when known based on a condition external to the\n   * profile specification”.\n   *\n   * The receiving application must process in a meaningful way the information\n   * conveyed by an element with an “RE” usage designation.\n   * The receiving application must process the message if the element is omitted\n   * (that is, an exception must not be raised because the element is missing). A\n   * receiving application must not raise an exception due to the presence of a\n   * required element.\n   */\n  RequiredOrEmpty: \"RE\",\n\n  /**\n   * Withdrawn\n   *\n   * The element has been withdrawn from the standard. There are no\n   * implementation requirements. The application must not value an element with\n   * a \"W\" usage designation.\n   */\n  Withdrawn: \"W\",\n} as const;\n\nexport type OptionalityCode =\n  (typeof OptionalityCode)[keyof typeof OptionalityCode];\n\n/**\n * Checks if a field satisfies the cardinality constraint.\n */\nexport function checkCardinality(\n  node: Field | undefined,\n  min: number,\n  max: number | \"*\"\n): ValidationResult {\n  if (min < 0 || (max !== \"*\" && max < 0)) {\n    throw new Error(\"Min and max lengths must be non-negative\");\n  }\n\n  if (max !== \"*\" && min > max) {\n    throw new Error(\"Min length cannot be greater than max length\");\n  }\n\n  const count = node?.children ? node.children.length : 0;\n\n  if (count < min) {\n    return {\n      error: {\n        actual: count,\n        code: \"CARDINALITY_UNDERFLOW\",\n        expected: min,\n        message: `has ${count} repetitions but requires at least ${min}`,\n      },\n      ok: false,\n    };\n  }\n\n  if (max !== \"*\" && count > max) {\n    return {\n      error: {\n        actual: count,\n        code: \"CARDINALITY_OVERFLOW\",\n        expected: max,\n        message: `has ${count} repetitions but allows at most ${max}`,\n      },\n      ok: false,\n    };\n  }\n\n  return { ok: true };\n}\n\n/**\n * Checks if a node satisfies the length constraint.\n */\nexport function checkLength(\n  node: Nodes | undefined,\n  max: number,\n  min = 0\n): ValidationResult {\n  if (min < 0 || max < 0) {\n    throw new Error(\"Min and max lengths must be non-negative\");\n  }\n\n  if (min > max) {\n    throw new Error(\"Min length cannot be greater than max length\");\n  }\n\n  const length = getLength(node);\n\n  if (length < min) {\n    return {\n      error: {\n        actual: length,\n        code: \"LENGTH_UNDERFLOW\",\n        expected: min,\n        message: `has length ${length} but requires at least ${min}`,\n      },\n      ok: false,\n    };\n  }\n\n  if (length > max) {\n    return {\n      error: {\n        actual: length,\n        code: \"LENGTH_OVERFLOW\",\n        expected: max,\n        message: `has length ${length} but allows at most ${max}`,\n      },\n      ok: false,\n    };\n  }\n\n  return { ok: true };\n}\n\n/**\n * Checks if a node satisfies the optionality constraint.\n */\nexport function checkOptionality(\n  node: Nodes | undefined,\n  optionality: OptionalityCode | string\n): ValidationResult {\n  const code = optionality.toUpperCase();\n\n  switch (code) {\n    case OptionalityCode.Required: {\n      if (!node) {\n        return {\n          error: {\n            code: \"MISSING\",\n            expected: \"R\",\n            message: \"is required but missing\",\n          },\n          ok: false,\n        };\n      }\n      if (isEmptyNode(node)) {\n        return {\n          error: {\n            code: \"EMPTY\",\n            expected: \"R\",\n            message: \"is required but empty\",\n          },\n          ok: false,\n        };\n      }\n      return { ok: true };\n    }\n\n    case OptionalityCode.NotSupported: {\n      if (node && !isEmptyNode(node)) {\n        return {\n          error: {\n            code: \"UNEXPECTED_CONTENT\",\n            expected: \"X\",\n            message: \"is not supported but present\",\n          },\n          ok: false,\n        };\n      }\n      return { ok: true };\n    }\n\n    case OptionalityCode.RequiredOrEmpty:\n    case OptionalityCode.Optional:\n    case OptionalityCode.Conditional:\n    case OptionalityCode.BackwardCompatible:\n    case OptionalityCode.Withdrawn: {\n      return { ok: true };\n    }\n\n    default: {\n      return { ok: true };\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/utils.d.ts

@@ -1,6 +1,29 @@
 import type { Nodes } from "@rethinkhealth/hl7v2-ast";
 /**
- * Utility: check if a node is semantically empty
+ * Check if an HL7v2 AST node is semantically empty.
+ *
+ * A node is empty when it contains no meaningful data — no subcomponent
+ * anywhere in its subtree has a non-empty string value.
+ *
+ * This follows the HL7v2 specification (Chapter 2, Section 2.5.3) and
+ * Conformance Methodology R1 (2019) definition of "non-empty value":
+ * at least one character must be a non-whitespace character.
+ *
+ * ## HL7v2 emptiness semantics
+ *
+ * | Encoding    | Wire form     | isEmpty? | Meaning                          |
+ * |-------------|---------------|----------|----------------------------------|
+ * | `value`     | `\|value\|`   | `false`  | Field has data                   |
+ * | `^DOE`      | `\|^DOE\|`    | `false`  | Component 2 has data             |
+ * | `~value`    | `\|~value\|`  | `false`  | Repetition 2 has data            |
+ * | `""`        | `\|""\|`      | `false`  | Explicit null (delete indicator) |
+ * | (empty)     | `\|\|`        | `true`   | Not present                      |
+ * | `^^`        | `\|^^\|`      | `true`   | Empty components                 |
+ * | `~`         | `\|~\|`       | `true`   | Empty repetitions                |
+ * | `~^^`       | `\|~^^\|`     | `true`   | Empty reps with empty components |
+ *
+ * @param node - The HL7v2 AST node to check (or null/undefined)
+ * @returns `true` if the node has no meaningful data
  */
 export declare function isEmptyNode(node?: Nodes | null | undefined): boolean;
 /**

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAMtD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CA2BpE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAgBrE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAejE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAMtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAqBpE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAgBrE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAejE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethinkhealth/hl7v2-utils",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "hl7v2 utilities",
   "keywords": [
     "health",
@@ -29,15 +29,15 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "24.10.1",
+    "@types/node": "^24.10.1",
     "@types/unist": "^3.0.3",
     "@vitest/coverage-v8": "4.0.18",
-    "tsup": "8.5.1",
+    "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "unist-builder": "^4.0.0",
     "vfile": "^6.0.3",
-    "vitest": "4.0.14",
-    "@rethinkhealth/hl7v2-ast": "0.5.0",
+    "vitest": "4.1.0",
+    "@rethinkhealth/hl7v2-ast": "0.7.0",
     "@rethinkhealth/testing": "0.0.2",
     "@rethinkhealth/tsconfig": "0.0.1"
   },