@rethinkhealth/hl7v2-utils 0.3.0 → 0.3.1

package/README.md

@@ -54,126 +54,133 @@ report(file, requiredFieldRule, {
 });
 ```
 
-### `Diagnostic`
+### `getByteLength(node)`
 
-Type definition for diagnostic rules. Diagnostics are used to report issues about HL7v2 messages.
+Calculate the byte length of any HL7v2 AST node. This utility efficiently computes the total serialized length including all children and separators (assumed to be 1 byte each).
 
-#### Properties
-
-- `type` (`string`) - Tool/plugin category (e.g., "validator", "lint", "annotator", "transformer", "parser")
-- `namespace` (`string`) - Domain/concern (e.g., "order", "field", "segment", "conformance")
-- `code` (`string`) - Specific issue code (e.g., "transition", "required", "acceptance")
-- `title` (`string`) - Human-readable title
-- `description` (`string`) - Full description of the rule
-- `severity` (`"error" | "warning" | "info" | null | undefined`) - Default severity level
-- `message` (`(context: Record<string, unknown>) => string`) - Message formatter function
-- `helpUrl` (`string`, optional) - URL to documentation
+#### Parameters
 
-#### Rule ID Format
+- `node` (`Nodes | null | undefined`) - The AST node to measure
 
-The rule ID is automatically constructed as `type:namespace:code` (e.g., `lint:field:required`).
+#### Returns
 
-#### Example
+`number` - The total byte length when the node is serialized
 
-```typescript
-const invalidTransitionRule: Diagnostic = {
-  type: 'validator',
-  namespace: 'order',
-  code: 'transition',
-  title: 'Invalid Segment Transition',
-  description: 'A segment arrived that is not allowed in this position.',
-  severity: 'error',
-  message: (ctx) => {
-    const expected = Array.isArray(ctx.expected) 
-      ? ctx.expected.join(', ') 
-      : ctx.expected;
-    return `Expected ${expected}, got '${ctx.actual}'`;
-  },
-  helpUrl: 'https://example.com/docs/segment-order'
-};
-```
+#### Algorithm
 
-### `DEFAULT_DELIMITERS`
+- For literal nodes (Subcomponent, SegmentHeader): returns the byte length of the value using UTF-8 encoding (i.e., `Buffer.byteLength(value, 'utf8')`)
+- For parent nodes: recursively sums the byte length of all children plus 1 byte per separator between children
+- Handles all node types: Root, Segment, Group, Field, FieldRepetition, Component, Subcomponent
 
-Standard HL7v2 delimiters as defined in the specification.
+#### Performance
 
-```typescript
-export const DEFAULT_DELIMITERS = {
-  field: "|",
-  component: "^",
-  repetition: "~",
-  subcomponent: "&",
-  escape: "\\",
-  segment: "\r",
-};
-```
+The function is optimized for performance with O(n) time complexity where n is the total number of nodes in the tree. It uses a simple recursive approach with minimal overhead.
 
 #### Example
 
 ```typescript
-import { DEFAULT_DELIMITERS } from '@rethinkhealth/hl7v2-utils';
+import { getByteLength } from '@rethinkhealth/hl7v2-utils';
+import type { Field } from '@rethinkhealth/hl7v2-ast';
+
+const field: Field = {
+  type: 'field',
+  children: [
+    {
+      type: 'field-repetition',
+      children: [
+        {
+          type: 'component',
+          children: [
+            { type: 'subcomponent', value: 'SMITH' },
+            { type: 'subcomponent', value: 'JOHN' }
+          ]
+        }
+      ]
+    }
+  ]
+};
 
-const message = segments.join(DEFAULT_DELIMITERS.segment);
+// Calculate: SMITH&JOHN = 5 + 1 + 4 = 10 bytes
+const length = getByteLength(field); // Returns: 10
 ```
 
-### `isEmptyNode(node)`
+#### Use Cases
+
+- Validating field or message size constraints
+- Memory allocation planning
+- Message size reporting and analytics
+- Performance optimization by avoiding full serialization
+
+### `getLength(node)`
 
-Check if an AST node is semantically empty. This is useful for validation and transformation logic.
+Calculate the string length of any HL7v2 AST node. This utility efficiently computes the total serialized character length including all children and separators (assumed to be 1 character each).
 
 #### Parameters
 
-- `node` (`Nodes | null | undefined`) - The AST node to check
+- `node` (`Nodes | null | undefined`) - The AST node to measure
 
 #### Returns
 
-`boolean` - `true` if the node is empty, `false` otherwise
+`number` - The total string length when the node is serialized
+
+#### Algorithm
+
+- For literal nodes (Subcomponent, SegmentHeader): returns `value.length` (JavaScript string length)
+- For parent nodes: recursively sums the string length of all children plus 1 character per separator between children
+- Handles all node types: Root, Segment, Group, Field, FieldRepetition, Component, Subcomponent
+
+#### Important Note
+
+Returns JavaScript string length (UTF-16 code units). For UTF-8 byte length (e.g., for wire protocol or size constraints), use `getByteLength` instead. These values differ for characters outside the ASCII range.
+
+#### Performance
+
+The function is optimized for performance with O(n) time complexity where n is the total number of nodes in the tree. It uses a simple recursive approach with minimal overhead.
 
 #### Example
 
 ```typescript
-import { isEmptyNode } from '@rethinkhealth/hl7v2-utils';
-
-if (isEmptyNode(field)) {
-  report(file, requiredFieldRule, { 
-    context: { fieldPath: 'PID-5' },
-    node: field 
-  });
-}
+import { getLength } from '@rethinkhealth/hl7v2-utils';
+import type { Field } from '@rethinkhealth/hl7v2-ast';
+
+const field: Field = {
+  type: 'field',
+  children: [
+    {
+      type: 'field-repetition',
+      children: [
+        {
+          type: 'component',
+          children: [
+            { type: 'subcomponent', value: 'SMITH' },
+            { type: 'subcomponent', value: 'JOHN' }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+// Calculate: SMITH&JOHN = 5 + 1 + 4 = 10 characters
+const length = getLength(field); // Returns: 10
 ```
 
-## Usage
+#### Use Cases
+
+- UI display and text formatting
+- Character-based validation rules
+- String manipulation operations
+- Quick length checks where byte-level precision is not required
 
-### Creating a Custom Linter
+#### Comparison with `getByteLength`
 
 ```typescript
-import { visit } from 'unist-util-visit';
-import { report } from '@rethinkhealth/hl7v2-utils';
-import type { Diagnostic } from '@rethinkhealth/hl7v2-utils';
-import type { Root } from '@rethinkhealth/hl7v2-ast';
-import type { VFile } from 'vfile';
+import { getLength, getByteLength } from '@rethinkhealth/hl7v2-utils';
 
-const noEmptySegmentRule: Diagnostic = {
-  type: 'lint',
-  namespace: 'segment',
-  code: 'no-empty',
-  title: 'Empty Segment',
-  description: 'Segments should not be empty.',
-  severity: 'warning',
-  message: (ctx) => `Segment '${ctx.segmentId}' is empty`
-};
+const subcomponent = { type: 'subcomponent', value: 'café' };
 
-function lintNoEmptySegment() {
-  return (tree: Root, file: VFile) => {
-    visit(tree, 'segment', (node) => {
-      if (isEmptyNode(node)) {
-        report(file, noEmptySegmentRule, {
-          node,
-          context: { segmentId: node.segmentId }
-        });
-      }
-    });
-  };
-}
+getLength(subcomponent);     // Returns: 4 (4 characters)
+getByteLength(subcomponent); // Returns: 5 (5 bytes in UTF-8: c-a-f-C3-A9)
 ```
 
 ## Contributing

package/dist/index.d.ts

@@ -11,4 +11,41 @@ export declare const DEFAULT_DELIMITERS: {
  * 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 plus 1 byte
+ * per separator (assumed to be single-byte delimiters).
+ *
+ * @param node - The HL7v2 AST node to measure
+ * @returns The total byte length of the node when serialized
+ *
+ * @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 plus 1
+ * per separator (assumed to be single-character delimiters).
+ *
+ * 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 when serialized
+ *
+ * @example
+ * ```ts
+ * const field: Field = { type: "field", children: [...] };
+ * const length = getLength(field); // e.g., 42
+ * ```
+ */
+export declare function getLength(node: Nodes | null | undefined): number;
 //# 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,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;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAcpE;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAchE"}

package/dist/index.js

@@ -25,8 +25,34 @@ function isEmptyNode(node) {
   }
   return false;
 }
+function getByteLength(node) {
+  if (!node) {
+    return 0;
+  }
+  if ("value" in node) {
+    return Buffer.byteLength(node.value, "utf8");
+  }
+  return node.children.reduce(
+    (total, child, i) => total + getByteLength(child) + (i < node.children.length - 1 ? 1 : 0),
+    0
+  );
+}
+function getLength(node) {
+  if (!node) {
+    return 0;
+  }
+  if ("value" in node) {
+    return node.value.length;
+  }
+  return node.children.reduce(
+    (total, child, i) => total + getLength(child) + (i < node.children.length - 1 ? 1 : 0),
+    0
+  );
+}
 export {
   DEFAULT_DELIMITERS,
+  getByteLength,
+  getLength,
   isEmptyNode
 };
 //# 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/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 plus 1 byte\n * per separator (assumed to be single-byte delimiters).\n *\n * @param node - The HL7v2 AST node to measure\n * @returns The total byte length of the node when serialized\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, i) =>\n      total + getByteLength(child) + (i < node.children.length - 1 ? 1 : 0),\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 plus 1\n * per separator (assumed to be single-character delimiters).\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 when serialized\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(\n    (total, child, i) =>\n      total + getLength(child) + (i < node.children.length - 1 ? 1 : 0),\n    0\n  );\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;AAsBO,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,OAAO,MACb,QAAQ,cAAc,KAAK,KAAK,IAAI,KAAK,SAAS,SAAS,IAAI,IAAI;AAAA,IACrE;AAAA,EACF;AACF;AAyBO,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;AAAA,IACnB,CAAC,OAAO,OAAO,MACb,QAAQ,UAAU,KAAK,KAAK,IAAI,KAAK,SAAS,SAAS,IAAI,IAAI;AAAA,IACjE;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rethinkhealth/hl7v2-utils",
   "description": "hl7v2 utilities",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "author": {
     "name": "Melek Somai",
@@ -24,9 +24,9 @@
     "unist-builder": "^4.0.0",
     "vfile": "^6.0.3",
     "vitest": "^4.0.6",
-    "@rethinkhealth/hl7v2-ast": "0.3.0",
-    "@rethinkhealth/testing": "0.0.2",
-    "@rethinkhealth/tsconfig": "0.0.1"
+    "@rethinkhealth/hl7v2-ast": "0.3.1",
+    "@rethinkhealth/tsconfig": "0.0.1",
+    "@rethinkhealth/testing": "0.0.2"
   },
   "repository": "rethinkhealth/hl7v2.git",
   "homepage": "https://www.rethinkhealth.io/hl7v2/docs",