@rethinkhealth/hl7v2-utils 0.3.3 → 0.4.0

package/README.md

@@ -3,9 +3,11 @@
 A utility package for working with HL7v2 messages, most commonly used within the `@rethinkhealth/hl7v2` ecosystem — a unist-inspired collection of plugins and utilities designed to parse, transform, validate, and manipulate HL7v2 messages.
 
 This package provides core utilities including:
+
 - Diagnostic reporting system for linters, validators, and transformers
 - Standard HL7v2 delimiters
 - AST node utility functions
+- Conformance validation utilities (cardinality, length, optionality)
 
 ## Installation
 
@@ -183,6 +185,82 @@ getLength(subcomponent);     // Returns: 4 (4 characters)
 getByteLength(subcomponent); // Returns: 5 (5 bytes in UTF-8: c-a-f-C3-A9)
 ```
 
+### Conformance Utilities
+
+The package provides stateless, composable functions to validate HL7v2 AST nodes against constraints like optionality (usage), cardinality, and length.
+
+#### `ValidationResult`
+
+All conformance functions return a `ValidationResult` object:
+
+```typescript
+type ValidationResult = 
+  | { ok: true }
+  | { 
+      ok: false; 
+      error: { 
+        code: string; 
+        message: string;
+        expected?: string | number | Array<string | number>;
+        actual?: string | number | Array<string | number>;
+      } 
+    };
+```
+
+#### `checkOptionality(node, optionality)`
+
+Checks if a node satisfies the optionality (usage) constraint.
+
+- **node**: `Nodes | undefined` - The AST node to check.
+- **optionality**: `string` - The usage code (e.g., 'R', 'O', 'X').
+- **Returns**: `ValidationResult`
+
+```typescript
+import { checkOptionality } from '@rethinkhealth/hl7v2-utils';
+
+// 'R' (Required), 'RE' (Required or Empty), 'O' (Optional), 'X' (Not Supported)
+const result = checkOptionality(myFieldNode, 'R');
+
+if (!result.ok) {
+  console.error(result.error.message); // "is required but missing"
+}
+```
+
+#### `checkCardinality(node, min, max)`
+
+Checks if a field has the correct number of repetitions.
+
+- **node**: `Field | undefined` - The field node to check.
+- **min**: `number` - Minimum repetitions.
+- **max**: `number | '*'` - Maximum repetitions.
+- **Returns**: `ValidationResult`
+
+```typescript
+import { checkCardinality } from '@rethinkhealth/hl7v2-utils';
+
+// Field must repeat between 1 and 5 times
+const result = checkCardinality(myFieldNode, 1, 5);
+```
+
+#### `checkLength(node, max, min?)`
+
+Checks if the content of a node falls within the minimum and maximum length.
+
+- **node**: `Nodes | undefined` - The node to check (length is calculated recursively).
+- **max**: `number` - Maximum length.
+- **min**: `number` (optional, default: 0) - Minimum length.
+- **Returns**: `ValidationResult`
+
+```typescript
+import { checkLength } from '@rethinkhealth/hl7v2-utils';
+
+// Content length must be between 1 and 10 characters
+const result = checkLength(myNode, 10, 1);
+
+// Content length must be at most 10 characters (min defaults to 0)
+const result2 = checkLength(myNode, 10);
+```
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
@@ -205,4 +283,4 @@ This program is licensed to you under the terms of the [MIT License](https://ope
 
 [github-code-of-conduct]: https://github.com/rethinkhealth/hl7v2/blob/main/CODE_OF_CONDUCT.md
 [github-license]: https://github.com/rethinkhealth/hl7v2/blob/main/LICENSE
-[github-contributing]: https://github.com/rethinkhealth/hl7v2/blob/main/CONTRIBUTING.md
+[github-contributing]: https://github.com/rethinkhealth/hl7v2/blob/main/CONTRIBUTING.md

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_DELIMITERS: {
+    field: string;
+    component: string;
+    repetition: string;
+    subcomponent: string;
+    escape: string;
+    segment: string;
+};

package/dist/constraints.d.ts

@@ -0,0 +1,92 @@
+import type { Field, Nodes } from "@rethinkhealth/hl7v2-ast";
+export type ValidationErrorCode = "MISSING" | "EMPTY" | "UNEXPECTED_CONTENT" | "CARDINALITY_UNDERFLOW" | "CARDINALITY_OVERFLOW" | "LENGTH_UNDERFLOW" | "LENGTH_OVERFLOW" | "VALUE_NOT_IN_TABLE";
+export type ValidationError = {
+    code: ValidationErrorCode;
+    message: string;
+    expected?: string | number | Array<string | number>;
+    actual?: string | number | Array<string | number>;
+};
+export type ValidationSuccess = {
+    ok: true;
+};
+export type ValidationFailure = {
+    ok: false;
+    error: ValidationError;
+};
+export type ValidationResult = ValidationSuccess | ValidationFailure;
+export declare const OptionalityCode: {
+    readonly Required: "R";
+    /**
+     * Required, but may be empty.
+     *
+     * @remarks
+     * The use of the RE usage code is qualified with the “if data is known”
+     * clause. The sender must interpret the clause as “the capability must always
+     * be supported, and data must always be sent if known”. To clarify, the
+     * sender does not determine whether the data should be sent; to be conformant
+     * to the rule, the data must be sent. There is a misconception where the RE
+     * usage is interpreted as “the capability must always be supported, and data
+     * may or may not be sent even when known based on a condition external to the
+     * profile specification”.
+     *
+     * The receiving application must process in a meaningful way the information
+     * conveyed by an element with an “RE” usage designation.
+     * The receiving application must process the message if the element is omitted
+     * (that is, an exception must not be raised because the element is missing). A
+     * receiving application must not raise an exception due to the presence of a
+     * required element.
+     */
+    readonly RequiredOrEmpty: "RE";
+    /**
+     * Optional
+     *
+     * There are no implementation requirements. The “O” usage designation is a
+     * placeholder indicating that the usage for this element has not yet been
+     * specified.
+     */
+    readonly Optional: "O";
+    /**
+     * Undeclared / Conditional.
+     *
+     * There are no implementation requirements. The “C” usage designation is a
+     * placeholder indicating that the usage for this element has not yet been
+     * specified.
+     */
+    readonly Conditional: "C";
+    /**
+     * Not Supported.
+     *
+     * There are no implementation requirements. The application must not value an
+     * element with an “X” usage designation.
+     */
+    readonly NotSupported: "X";
+    /**
+     * Backward Compatible
+     *
+     * There are no implementation requirements. The “B” usage indicates that the
+     * element is retained for backwards compatibility of the element. Another
+     * usage indicator may be assigned in a derived profile.
+     */
+    readonly BackwardCompatible: "B";
+    /**
+     * Withdrawn
+     *
+     * The element has been withdrawn from the standard. There are no
+     * implementation requirements. The application must not value an element with
+     * a "W" usage designation.
+     */
+    readonly Withdrawn: "W";
+};
+export type OptionalityCode = (typeof OptionalityCode)[keyof typeof OptionalityCode];
+/**
+ * Checks if a field satisfies the cardinality constraint.
+ */
+export declare function checkCardinality(node: Field | undefined, min: number, max: number | "*"): ValidationResult;
+/**
+ * Checks if a node satisfies the length constraint.
+ */
+export declare function checkLength(node: Nodes | undefined, max: number, min?: number): ValidationResult;
+/**
+ * Checks if a node satisfies the optionality constraint.
+ */
+export declare function checkOptionality(node: Nodes | undefined, optionality: OptionalityCode | string): ValidationResult;

package/dist/index.d.ts

@@ -1,48 +1,3 @@
-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;
-/**
- * Calculate the byte length of any HL7v2 AST node.
- *
- * For literal nodes (Subcomponent, SegmentHeader), returns the UTF-8 byte length of the value.
- * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.
- *
- * @param node - The HL7v2 AST node to measure
- * @returns The total byte length of the node content
- *
- * @example
- * ```ts
- * const field: Field = { type: "field", children: [...] };
- * const length = getByteLength(field); // e.g., 42
- * ```
- */
-export declare function getByteLength(node: Nodes | null | undefined): number;
-/**
- * Calculate the string length of any HL7v2 AST node.
- *
- * For literal nodes (Subcomponent, SegmentHeader), returns `value.length`.
- * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.
- *
- * Note: Returns JavaScript string length (UTF-16 code units). For UTF-8 byte
- * length (e.g., for wire protocol), use `getByteLength` instead.
- *
- * @param node - The HL7v2 AST node to measure
- * @returns The total string length of the node content
- *
- * @example
- * ```ts
- * const field: Field = { type: "field", children: [...] };
- * const length = getLength(field); // e.g., 42
- * ```
- */
-export declare function getLength(node: Nodes | null | undefined): number;
+export * from "./constants";
+export * from "./constraints";
+export * from "./utils";

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/index.ts
+// src/constants.ts
 var DEFAULT_DELIMITERS = {
   field: "|",
   component: "^",
@@ -7,6 +7,8 @@ var DEFAULT_DELIMITERS = {
   escape: "\\",
   segment: "\r"
 };
+
+// src/utils.ts
 function isEmptyNode(node) {
   if (!node) {
     return true;
@@ -46,8 +48,188 @@ function getLength(node) {
   }
   return node.children.reduce((total, child) => total + getLength(child), 0);
 }
+
+// src/constraints.ts
+var OptionalityCode = {
+  Required: "R",
+  /**
+   * Required, but may be empty.
+   *
+   * @remarks
+   * The use of the RE usage code is qualified with the “if data is known”
+   * clause. The sender must interpret the clause as “the capability must always
+   * be supported, and data must always be sent if known”. To clarify, the
+   * sender does not determine whether the data should be sent; to be conformant
+   * to the rule, the data must be sent. There is a misconception where the RE
+   * usage is interpreted as “the capability must always be supported, and data
+   * may or may not be sent even when known based on a condition external to the
+   * profile specification”.
+   *
+   * The receiving application must process in a meaningful way the information
+   * conveyed by an element with an “RE” usage designation.
+   * The receiving application must process the message if the element is omitted
+   * (that is, an exception must not be raised because the element is missing). A
+   * receiving application must not raise an exception due to the presence of a
+   * required element.
+   */
+  RequiredOrEmpty: "RE",
+  /**
+   * Optional
+   *
+   * There are no implementation requirements. The “O” usage designation is a
+   * placeholder indicating that the usage for this element has not yet been
+   * specified.
+   */
+  Optional: "O",
+  /**
+   * Undeclared / Conditional.
+   *
+   * There are no implementation requirements. The “C” usage designation is a
+   * placeholder indicating that the usage for this element has not yet been
+   * specified.
+   */
+  Conditional: "C",
+  /**
+   * Not Supported.
+   *
+   * There are no implementation requirements. The application must not value an
+   * element with an “X” usage designation.
+   */
+  NotSupported: "X",
+  /**
+   * Backward Compatible
+   *
+   * There are no implementation requirements. The “B” usage indicates that the
+   * element is retained for backwards compatibility of the element. Another
+   * usage indicator may be assigned in a derived profile.
+   */
+  BackwardCompatible: "B",
+  /**
+   * Withdrawn
+   *
+   * The element has been withdrawn from the standard. There are no
+   * implementation requirements. The application must not value an element with
+   * a "W" usage designation.
+   */
+  Withdrawn: "W"
+};
+function checkCardinality(node, min, max) {
+  if (min < 0 || max !== "*" && max < 0) {
+    throw new Error("Min and max lengths must be non-negative");
+  }
+  if (max !== "*" && min > max) {
+    throw new Error("Min length cannot be greater than max length");
+  }
+  const count = node?.children ? node.children.length : 0;
+  if (count < min) {
+    return {
+      ok: false,
+      error: {
+        code: "CARDINALITY_UNDERFLOW",
+        message: `has ${count} repetitions but requires at least ${min}`,
+        expected: min,
+        actual: count
+      }
+    };
+  }
+  if (max !== "*" && count > max) {
+    return {
+      ok: false,
+      error: {
+        code: "CARDINALITY_OVERFLOW",
+        message: `has ${count} repetitions but allows at most ${max}`,
+        expected: max,
+        actual: count
+      }
+    };
+  }
+  return { ok: true };
+}
+function checkLength(node, max, min = 0) {
+  if (min < 0 || max < 0) {
+    throw new Error("Min and max lengths must be non-negative");
+  }
+  if (min > max) {
+    throw new Error("Min length cannot be greater than max length");
+  }
+  const length = getLength(node);
+  if (length < min) {
+    return {
+      ok: false,
+      error: {
+        code: "LENGTH_UNDERFLOW",
+        message: `has length ${length} but requires at least ${min}`,
+        expected: min,
+        actual: length
+      }
+    };
+  }
+  if (length > max) {
+    return {
+      ok: false,
+      error: {
+        code: "LENGTH_OVERFLOW",
+        message: `has length ${length} but allows at most ${max}`,
+        expected: max,
+        actual: length
+      }
+    };
+  }
+  return { ok: true };
+}
+function checkOptionality(node, optionality) {
+  const code = optionality.toUpperCase();
+  switch (code) {
+    case OptionalityCode.Required:
+      if (!node) {
+        return {
+          ok: false,
+          error: {
+            code: "MISSING",
+            message: "is required but missing",
+            expected: "R"
+          }
+        };
+      }
+      if (isEmptyNode(node)) {
+        return {
+          ok: false,
+          error: {
+            code: "EMPTY",
+            message: "is required but empty",
+            expected: "R"
+          }
+        };
+      }
+      return { ok: true };
+    case OptionalityCode.NotSupported:
+      if (node && !isEmptyNode(node)) {
+        return {
+          ok: false,
+          error: {
+            code: "UNEXPECTED_CONTENT",
+            message: "is not supported but present",
+            expected: "X"
+          }
+        };
+      }
+      return { ok: true };
+    case OptionalityCode.RequiredOrEmpty:
+    case OptionalityCode.Optional:
+    case OptionalityCode.Conditional:
+    case OptionalityCode.BackwardCompatible:
+    case OptionalityCode.Withdrawn:
+      return { ok: true };
+    default:
+      return { ok: true };
+  }
+}
 export {
   DEFAULT_DELIMITERS,
+  OptionalityCode,
+  checkCardinality,
+  checkLength,
+  checkOptionality,
   getByteLength,
   getLength,
   isEmptyNode

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\n// -------------\n// Byte Length\n// -------------\n\n/**\n * Calculate the byte length of any HL7v2 AST node.\n *\n * For literal nodes (Subcomponent, SegmentHeader), 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  return node.children.reduce(\n    (total, child) => total + getByteLength(child),\n    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, SegmentHeader), 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  return node.children.reduce((total, child) => total + getLength(child), 0);\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;AAqBO,SAAS,cAAc,MAAwC;AACpE,MAAI,CAAC,MAAM;AACT,WAAO;AAAA,EACT;AAEA,MAAI,WAAW,MAAM;AACnB,WAAO,OAAO,WAAW,KAAK,OAAO,MAAM;AAAA,EAC7C;AAEA,SAAO,KAAK,SAAS;AAAA,IACnB,CAAC,OAAO,UAAU,QAAQ,cAAc,KAAK;AAAA,IAC7C;AAAA,EACF;AACF;AAwBO,SAAS,UAAU,MAAwC;AAChE,MAAI,CAAC,MAAM;AACT,WAAO;AAAA,EACT;AAEA,MAAI,WAAW,MAAM;AACnB,WAAO,KAAK,MAAM;AAAA,EACpB;AAEA,SAAO,KAAK,SAAS,OAAO,CAAC,OAAO,UAAU,QAAQ,UAAU,KAAK,GAAG,CAAC;AAC3E;","names":[]}
+{"version":3,"sources":["../src/constants.ts","../src/utils.ts","../src/constraints.ts"],"sourcesContent":["// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  field: \"|\",\n  component: \"^\",\n  repetition: \"~\",\n  subcomponent: \"&\",\n  escape: \"\\\\\",\n  segment: \"\\r\",\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, SegmentHeader), 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  return node.children.reduce(\n    (total, child) => total + getByteLength(child),\n    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, SegmentHeader), 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  return node.children.reduce((total, child) => total + getLength(child), 0);\n}\n","import type { Field, Nodes } from \"@rethinkhealth/hl7v2-ast\";\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 type ValidationError = {\n  code: ValidationErrorCode;\n  message: string;\n  expected?: string | number | Array<string | number>;\n  actual?: string | number | Array<string | number>;\n};\n\nexport type ValidationSuccess = {\n  ok: true;\n};\n\nexport type ValidationFailure = {\n  ok: false;\n  error: ValidationError;\n};\n\nexport type ValidationResult = ValidationSuccess | ValidationFailure;\n\nexport const OptionalityCode = {\n  Required: \"R\",\n  /**\n   * Required, but may be empty.\n   *\n   * @remarks\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   * 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   * 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   * 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   * 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   * 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      ok: false,\n      error: {\n        code: \"CARDINALITY_UNDERFLOW\",\n        message: `has ${count} repetitions but requires at least ${min}`,\n        expected: min,\n        actual: count,\n      },\n    };\n  }\n\n  if (max !== \"*\" && count > max) {\n    return {\n      ok: false,\n      error: {\n        code: \"CARDINALITY_OVERFLOW\",\n        message: `has ${count} repetitions but allows at most ${max}`,\n        expected: max,\n        actual: count,\n      },\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      ok: false,\n      error: {\n        code: \"LENGTH_UNDERFLOW\",\n        message: `has length ${length} but requires at least ${min}`,\n        expected: min,\n        actual: length,\n      },\n    };\n  }\n\n  if (length > max) {\n    return {\n      ok: false,\n      error: {\n        code: \"LENGTH_OVERFLOW\",\n        message: `has length ${length} but allows at most ${max}`,\n        expected: max,\n        actual: length,\n      },\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          ok: false,\n          error: {\n            code: \"MISSING\",\n            message: \"is required but missing\",\n            expected: \"R\",\n          },\n        };\n      }\n      if (isEmptyNode(node)) {\n        return {\n          ok: false,\n          error: {\n            code: \"EMPTY\",\n            message: \"is required but empty\",\n            expected: \"R\",\n          },\n        };\n      }\n      return { ok: true };\n\n    case OptionalityCode.NotSupported:\n      if (node && !isEmptyNode(node)) {\n        return {\n          ok: false,\n          error: {\n            code: \"UNEXPECTED_CONTENT\",\n            message: \"is not supported but present\",\n            expected: \"X\",\n          },\n        };\n      }\n      return { ok: true };\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    default:\n      return { ok: true };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/utils.d.ts

@@ -0,0 +1,40 @@
+import type { Nodes } from "@rethinkhealth/hl7v2-ast";
+/**
+ * Utility: check if a node is semantically empty
+ */
+export declare function isEmptyNode(node: Nodes | null | undefined): boolean;
+/**
+ * Calculate the byte length of any HL7v2 AST node.
+ *
+ * For literal nodes (Subcomponent, SegmentHeader), returns the UTF-8 byte length of the value.
+ * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.
+ *
+ * @param node - The HL7v2 AST node to measure
+ * @returns The total byte length of the node content
+ *
+ * @example
+ * ```ts
+ * const field: Field = { type: "field", children: [...] };
+ * const length = getByteLength(field); // e.g., 42
+ * ```
+ */
+export declare function getByteLength(node: Nodes | null | undefined): number;
+/**
+ * Calculate the string length of any HL7v2 AST node.
+ *
+ * For literal nodes (Subcomponent, SegmentHeader), returns `value.length`.
+ * For parent nodes, recursively calculates the length of all children. Delimiters are NOT included.
+ *
+ * Note: Returns JavaScript string length (UTF-16 code units). For UTF-8 byte
+ * length (e.g., for wire protocol), use `getByteLength` instead.
+ *
+ * @param node - The HL7v2 AST node to measure
+ * @returns The total string length of the node content
+ *
+ * @example
+ * ```ts
+ * const field: Field = { type: "field", children: [...] };
+ * const length = getLength(field); // e.g., 42
+ * ```
+ */
+export declare function getLength(node: Nodes | null | undefined): number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rethinkhealth/hl7v2-utils",
   "description": "hl7v2 utilities",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "license": "MIT",
   "author": {
     "name": "Melek Somai",
@@ -16,18 +16,21 @@
     ".": "./dist/index.js"
   },
   "devDependencies": {
-    "@types/node": "24.10.0",
+    "@types/node": "24.10.1",
     "@types/unist": "^3.0.3",
-    "@vitest/coverage-v8": "^4.0.5",
-    "tsup": "8.5.0",
+    "@vitest/coverage-v8": "4.0.14",
+    "tsup": "8.5.1",
     "typescript": "^5.9.3",
     "unist-builder": "^4.0.0",
     "vfile": "^6.0.3",
-    "vitest": "^4.0.6",
-    "@rethinkhealth/hl7v2-ast": "0.3.3",
+    "vitest": "4.0.14",
+    "@rethinkhealth/hl7v2-ast": "0.4.0",
     "@rethinkhealth/testing": "0.0.2",
     "@rethinkhealth/tsconfig": "0.0.1"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "repository": "rethinkhealth/hl7v2.git",
   "homepage": "https://www.rethinkhealth.io/hl7v2/docs",
   "keywords": [
@@ -38,9 +41,6 @@
     "nodejs",
     "typescript"
   ],
-  "engines": {
-    "node": ">=18"
-  },
   "packageManager": "pnpm@10.14.0",
   "publishConfig": {
     "access": "public"