@rethinkhealth/hl7v2-builder 0.2.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rethink Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# HL7v2 Builder
+
+`@rethinkhealth/hl7v2-builder` provides a tiny set of helpers for assembling HL7v2 abstract syntax trees that follow the [`@rethinkhealth/hl7v2-ast`](../hl7v2-ast/) schema. The helpers wrap [`unist-builder`](https://github.com/syntax-tree/unist-builder) so you can build trees with a couple of function calls instead of manually nesting nodes.
+
+## Why it helps
+
+- Work directly with typed nodes while avoiding the repetitive `u('node-type', …)` boilerplate from `unist-builder`.
+- Describe complex segments declaratively without worrying about separator placement or empty components.
+
+## Philosophy
+
+- Stay explicit: you build the same AST shape you would by hand, so there is no hidden serialization logic or format guessing.
+- Compose freely: each helper is a thin wrapper over `unist-builder`, making it easy to mix raw nodes and other utilities when needed.
+- Keep things minimal: a small surface area means fewer abstractions to learn and less room for divergent interpretations of the HL7v2 model.
+
+## Functions at a glance
+
+- `m(...segments)` – build a `root` (i.e. message) node from any number of segments.
+- `s(...fields)` – build a `segment` node from one or more `Field` nodes.
+- `f(...values)` – build a `field` node from strings, components, repetitions, or arrays thereof.
+- `r(...components)` – build a `field-repetition` node from strings or components.
+- `c(...values)` – build a `component` node from strings or arrays of strings.
+
+Each helper returns objects typed from `@rethinkhealth/hl7v2-ast`, so the resulting tree can be consumed by any package in the ecosystem (parsers, linters, etc.).
+
+## Install
+
+This package is ESM-only. In Node.js 18+ run one of:
+
+```bash
+npm install @rethinkhealth/hl7v2-builder
+# or
+yarn add @rethinkhealth/hl7v2-builder
+# or
+pnpm add @rethinkhealth/hl7v2-builder
+```
+
+## Usage
+
+```typescript
+import { c, f, m, s } from '@rethinkhealth/hl7v2-builder';
+
+const tree = m(
+  s(
+    f('MSH'), // include the segment header explicitly
+    f('^~\\&')
+  ),
+  s(
+    f('PID'),
+    f(), // empty field
+    f([
+      c(['123456', 'DOE', 'JOHN']), // accept arrays or individual args interchangeably
+    ])
+  )
+);
+```
+
+`tree` is now a `Root` node with two segments (`MSH`, `PID`). You can serialise it, transform it, or feed it into other HL7v2 utilities.
+
+## API
+
+### `m(...children: RootContent[]): Root`
+
+- No arguments → empty root.
+- Pass any number of `RootContent` nodes (segments, fragments, etc.); they are appended in order.
+- Arguments are used as-is, so pass concrete AST nodes rather than nested arrays.
+
+### `s(...fields: Field[]): Segment`
+
+- No arguments → empty segment.
+- Provide the header field yourself, typically with `f('PID')`, and include it as the first argument.
+- Fields are appended in the order provided; the helper does not do any automatic flattening.
+
+### `f(...values: Array<string | Component | FieldRepetition | Array<string | Component | FieldRepetition>>): Field`
+
+- No arguments → empty field with a single empty repetition.
+- Strings become components with a single subcomponent containing the value.
+- `Component` instances are added directly.
+- `FieldRepetition` instances are preserved and allow you to control repetitions explicitly.
+- Arrays are flattened one level so you can pass a mixture of individual values and grouped lists.
+- Sequences of strings/components are grouped into a single repetition unless you introduce a `FieldRepetition` explicitly.
+
+### `r(...components: Array<string | Component | Array<string | Component>>): FieldRepetition`
+
+- No arguments → repetition with an empty component.
+- Strings become components with a single subcomponent containing the value.
+- Components are inserted as-is.
+- Arrays are flattened one level for convenience.
+
+### `c(...values: Array<string | string[]>): Component`
+
+- No arguments → component with an empty subcomponent.
+- Strings become subcomponents.
+- Arrays are flattened one level so you can pass `c('DOE', ['JOHN', 'Q'])`.
+
+> **Note**
+> These helpers are intentionally minimal. For advanced scenarios—multiple repetitions per field, custom metadata, or node reuse—you can still drop down to `unist-builder` (`u`) directly and mix those nodes with the helpers above.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Code of Conduct
+
+To ensure a welcoming and positive environment, we have a [Code of Conduct][github-code-of-conduct] that all contributors and participants are expected to adhere to.
+
+## License
+
+Copyright 2025 Rethink Health, SUARL. All rights reserved.
+
+This program is licensed to you under the terms of the [MIT License](https://opensource.org/licenses/MIT). This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [LICENSE][github-license] file for details.
+
+[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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/** biome-ignore-all lint/style/useUnifiedTypeSignatures: fine */
+import type { Component, Field, FieldRepetition, Root, RootContent, Segment } from "@rethinkhealth/hl7v2-ast";
+export declare function m(...children: RootContent[]): Root;
+export declare function s(...fields: Field[]): Segment;
+type FieldValue = FieldRepetition | Component | string;
+type Flattenable<T> = T | T[];
+/** Empty field */
+export declare function f(): Field;
+export declare function f(...values: Flattenable<FieldValue>[]): Field;
+export declare function r(): FieldRepetition;
+export declare function r(...components: Flattenable<Component | string>[]): FieldRepetition;
+export declare function c(): Component;
+export declare function c(...values: Flattenable<string>[]): Component;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,eAAe,EACf,IAAI,EACJ,WAAW,EACX,OAAO,EACR,MAAM,0BAA0B,CAAC;AAGlC,wBAAgB,CAAC,CAAC,GAAG,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAElD;AAED,wBAAgB,CAAC,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAE7C;AAED,KAAK,UAAU,GAAG,eAAe,GAAG,SAAS,GAAG,MAAM,CAAC;AACvD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAoB9B,kBAAkB;AAClB,wBAAgB,CAAC,IAAI,KAAK,CAAC;AAC3B,wBAAgB,CAAC,CAAC,GAAG,MAAM,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,GAAG,KAAK,CAAC;AA2C/D,wBAAgB,CAAC,IAAI,eAAe,CAAC;AACrC,wBAAgB,CAAC,CACf,GAAG,UAAU,EAAE,WAAW,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,GAC/C,eAAe,CAAC;AAmBnB,wBAAgB,CAAC,IAAI,SAAS,CAAC;AAC/B,wBAAgB,CAAC,CAAC,GAAG,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,84 @@
+// src/index.ts
+import { u } from "unist-builder";
+function m(...children) {
+  return u("root", children);
+}
+function s(...fields) {
+  return u("segment", fields);
+}
+function flatten(values) {
+  return values.flatMap((value) => Array.isArray(value) ? value : [value]);
+}
+function isFieldRepetition(value) {
+  return typeof value === "object" && value !== null && value.type === "field-repetition";
+}
+function isComponent(value) {
+  return typeof value === "object" && value !== null && value.type === "component";
+}
+function f(...values) {
+  if (values.length === 0) {
+    return u("field", [r()]);
+  }
+  const flat = flatten(values);
+  if (flat.length === 0) {
+    return u("field", [r()]);
+  }
+  const repetitions = [];
+  let pendingComponents = [];
+  const flushPending = () => {
+    if (pendingComponents.length === 0) {
+      return;
+    }
+    repetitions.push(r(...pendingComponents));
+    pendingComponents = [];
+  };
+  for (const value of flat) {
+    if (isFieldRepetition(value)) {
+      flushPending();
+      repetitions.push(value);
+      continue;
+    }
+    if (isComponent(value) || typeof value === "string") {
+      pendingComponents.push(value);
+    }
+  }
+  flushPending();
+  if (repetitions.length === 0) {
+    return u("field", [r()]);
+  }
+  return u("field", repetitions);
+}
+function r(...components) {
+  if (components.length === 0) {
+    return u("field-repetition", [c()]);
+  }
+  const flat = flatten(components);
+  if (flat.length === 0) {
+    return u("field-repetition", [c()]);
+  }
+  return u(
+    "field-repetition",
+    flat.map((value) => typeof value === "string" ? c(value) : value)
+  );
+}
+function c(...values) {
+  if (values.length === 0) {
+    return u("component", [u("subcomponent", "")]);
+  }
+  const flat = flatten(values);
+  if (flat.length === 0) {
+    return u("component", [u("subcomponent", "")]);
+  }
+  return u(
+    "component",
+    flat.map((subcomponent) => u("subcomponent", subcomponent))
+  );
+}
+export {
+  c,
+  f,
+  m,
+  r,
+  s
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/** biome-ignore-all lint/style/useUnifiedTypeSignatures: fine */\nimport type {\n  Component,\n  Field,\n  FieldRepetition,\n  Root,\n  RootContent,\n  Segment,\n} from \"@rethinkhealth/hl7v2-ast\";\nimport { u } from \"unist-builder\";\n\nexport function m(...children: RootContent[]): Root {\n  return u(\"root\", children);\n}\n\nexport function s(...fields: Field[]): Segment {\n  return u(\"segment\", fields);\n}\n\ntype FieldValue = FieldRepetition | Component | string;\ntype Flattenable<T> = T | T[];\n\nfunction flatten<T>(values: Flattenable<T>[]): T[] {\n  return values.flatMap((value) => (Array.isArray(value) ? value : [value]));\n}\n\nfunction isFieldRepetition(value: FieldValue): value is FieldRepetition {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    value.type === \"field-repetition\"\n  );\n}\n\nfunction isComponent(value: FieldValue): value is Component {\n  return (\n    typeof value === \"object\" && value !== null && value.type === \"component\"\n  );\n}\n\n/** Empty field */\nexport function f(): Field;\nexport function f(...values: Flattenable<FieldValue>[]): Field;\nexport function f(...values: Flattenable<FieldValue>[]): Field {\n  if (values.length === 0) {\n    return u(\"field\", [r()]);\n  }\n\n  const flat = flatten<FieldValue>(values);\n  if (flat.length === 0) {\n    return u(\"field\", [r()]);\n  }\n\n  const repetitions: FieldRepetition[] = [];\n  let pendingComponents: Array<Component | string> = [];\n\n  const flushPending = () => {\n    if (pendingComponents.length === 0) {\n      return;\n    }\n    repetitions.push(r(...pendingComponents));\n    pendingComponents = [];\n  };\n\n  for (const value of flat) {\n    if (isFieldRepetition(value)) {\n      flushPending();\n      repetitions.push(value);\n      continue;\n    }\n\n    if (isComponent(value) || typeof value === \"string\") {\n      pendingComponents.push(value);\n    }\n  }\n\n  flushPending();\n\n  if (repetitions.length === 0) {\n    return u(\"field\", [r()]);\n  }\n\n  return u(\"field\", repetitions);\n}\n\nexport function r(): FieldRepetition;\nexport function r(\n  ...components: Flattenable<Component | string>[]\n): FieldRepetition;\nexport function r(\n  ...components: Flattenable<Component | string>[]\n): FieldRepetition {\n  if (components.length === 0) {\n    return u(\"field-repetition\", [c()]);\n  }\n\n  const flat = flatten<Component | string>(components);\n  if (flat.length === 0) {\n    return u(\"field-repetition\", [c()]);\n  }\n\n  return u(\n    \"field-repetition\",\n    flat.map((value) => (typeof value === \"string\" ? c(value) : value))\n  );\n}\n\nexport function c(): Component;\nexport function c(...values: Flattenable<string>[]): Component;\nexport function c(...values: Flattenable<string>[]): Component {\n  if (values.length === 0) {\n    return u(\"component\", [u(\"subcomponent\", \"\")]);\n  }\n\n  const flat = flatten<string>(values);\n  if (flat.length === 0) {\n    return u(\"component\", [u(\"subcomponent\", \"\")]);\n  }\n\n  return u(\n    \"component\",\n    flat.map((subcomponent) => u(\"subcomponent\", subcomponent))\n  );\n}\n"],"mappings":";AASA,SAAS,SAAS;AAEX,SAAS,KAAK,UAA+B;AAClD,SAAO,EAAE,QAAQ,QAAQ;AAC3B;AAEO,SAAS,KAAK,QAA0B;AAC7C,SAAO,EAAE,WAAW,MAAM;AAC5B;AAKA,SAAS,QAAW,QAA+B;AACjD,SAAO,OAAO,QAAQ,CAAC,UAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAE;AAC3E;AAEA,SAAS,kBAAkB,OAA6C;AACtE,SACE,OAAO,UAAU,YACjB,UAAU,QACV,MAAM,SAAS;AAEnB;AAEA,SAAS,YAAY,OAAuC;AAC1D,SACE,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,SAAS;AAElE;AAKO,SAAS,KAAK,QAA0C;AAC7D,MAAI,OAAO,WAAW,GAAG;AACvB,WAAO,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;AAAA,EACzB;AAEA,QAAM,OAAO,QAAoB,MAAM;AACvC,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;AAAA,EACzB;AAEA,QAAM,cAAiC,CAAC;AACxC,MAAI,oBAA+C,CAAC;AAEpD,QAAM,eAAe,MAAM;AACzB,QAAI,kBAAkB,WAAW,GAAG;AAClC;AAAA,IACF;AACA,gBAAY,KAAK,EAAE,GAAG,iBAAiB,CAAC;AACxC,wBAAoB,CAAC;AAAA,EACvB;AAEA,aAAW,SAAS,MAAM;AACxB,QAAI,kBAAkB,KAAK,GAAG;AAC5B,mBAAa;AACb,kBAAY,KAAK,KAAK;AACtB;AAAA,IACF;AAEA,QAAI,YAAY,KAAK,KAAK,OAAO,UAAU,UAAU;AACnD,wBAAkB,KAAK,KAAK;AAAA,IAC9B;AAAA,EACF;AAEA,eAAa;AAEb,MAAI,YAAY,WAAW,GAAG;AAC5B,WAAO,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;AAAA,EACzB;AAEA,SAAO,EAAE,SAAS,WAAW;AAC/B;AAMO,SAAS,KACX,YACc;AACjB,MAAI,WAAW,WAAW,GAAG;AAC3B,WAAO,EAAE,oBAAoB,CAAC,EAAE,CAAC,CAAC;AAAA,EACpC;AAEA,QAAM,OAAO,QAA4B,UAAU;AACnD,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,EAAE,oBAAoB,CAAC,EAAE,CAAC,CAAC;AAAA,EACpC;AAEA,SAAO;AAAA,IACL;AAAA,IACA,KAAK,IAAI,CAAC,UAAW,OAAO,UAAU,WAAW,EAAE,KAAK,IAAI,KAAM;AAAA,EACpE;AACF;AAIO,SAAS,KAAK,QAA0C;AAC7D,MAAI,OAAO,WAAW,GAAG;AACvB,WAAO,EAAE,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAAA,EAC/C;AAEA,QAAM,OAAO,QAAgB,MAAM;AACnC,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,EAAE,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAAA,EAC/C;AAEA,SAAO;AAAA,IACL;AAAA,IACA,KAAK,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,YAAY,CAAC;AAAA,EAC5D;AACF;","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@rethinkhealth/hl7v2-builder",
+  "description": "Build HL7v2 AST nodes",
+  "version": "0.2.16",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "unist-builder": "4.0.0",
+    "@rethinkhealth/hl7v2-ast": "0.2.16"
+  },
+  "devDependencies": {
+    "@types/node": "24.5.2",
+    "@types/unist": "^3.0.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "8.5.0",
+    "typescript": "^5.8.3",
+    "unified": "^11.0.5",
+    "vitest": "^3.2.4",
+    "@rethinkhealth/testing": "0.0.1",
+    "@rethinkhealth/tsconfig": "0.0.1",
+    "@rethinkhealth/hl7v2-to-hl7v2": "0.2.16"
+  },
+  "repository": "rethinkhealth/hl7v2.git",
+  "homepage": "https://www.rethinkhealth.io/hl7v2/docs",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript"
+  ],
+  "packageManager": "pnpm@10.14.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}