@rethinkhealth/hl7v2-jsonify 0.2.1

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,128 @@
+# @rethinkhealth/hl7v2-jsonify
+
+**[unified](https://unifiedjs.com/)** plugin to transform HL7v2 message ASTs into a simplified JSON representation.
+
+## What is this?
+
+`@rethinkhealth/hl7v2-jsonify` is a [unified](https://unifiedjs.com/) plugin that takes an HL7v2 syntax tree (produced by a parser such as [`@rethinkhealth/hl7v2-ast`][https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-parser]) and compiles it to a clean, structured JSON format.
+
+It strips away [unist](https://github.com/syntax-tree/unist) metadata and preserves only meaningful HL7v2 properties such as segment type, field indexes, and values.
+
+## When should I use this?
+
+Use this plugin when you need:
+
+* A minimal JSON representation of HL7v2 messages for downstream processing.
+* To serialize HL7v2 ASTs into a format suitable for APIs or storage.
+
+If you need to parse raw HL7v2 messages first, use [`@rethinkhealth/hl7v2-ast`](https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-parser) before applying this plugin.
+
+## Install
+
+This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+
+In Node.js (version 16+), install with [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm):
+
+```sh
+npm install @rethinkhealth/hl7v2-jsonify
+```
+
+## Use
+
+Say we have an HL7v2 message and want to convert it to JSON:
+
+```js
+import { unified } from 'unified'
+import { hl7v2Parse } from '@rethinkhealth/hl7v2-ast'
+import { hl7v2Jsonify } from '@rethinkhealth/hl7v2-jsonify'
+
+const msg = `MSH|^~\\&|HIS|RIH|EKG|EKG|200202150930||ADT^A01|MSG00001|P|2.4\rPID|||555-44-4444||DOE^JOHN`
+
+const file = await unified()
+  .use(hl7v2Parse)
+  .use(hl7v2Jsonify)
+  .process(msg)
+
+console.log(String(file))
+```
+
+Yields:
+
+```json
+{
+  "type": "Message",
+  "children": [
+    {
+      "type": "Segment",
+      "name": "MSH",
+      "children": [
+        { "type": "Field", "name": "MSH-1", "value": "|" },
+        { "type": "Field", "name": "MSH-2", "value": "^~\\&" },
+        ...
+      ]
+    },
+    {
+      "type": "Segment",
+      "name": "PID",
+      "children": [
+        { "type": "Field", "name": "PID-3", "value": "555-44-4444" },
+        { "type": "Field", "name": "PID-5", "value": "DOE^JOHN" }
+      ]
+    }
+  ]
+}
+```
+
+## API
+
+### `unified().use(hl7v2Jsonify)`
+
+Transform an HL7v2 AST into JSON.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Nothing (`undefined`). The unified compiler returns a stringified JSON document.
+
+## JSON Schema
+
+The output JSON has the following shape:
+
+```ts
+interface HL7v2JsonNode {
+  type: string
+  name?: string
+  index?: number
+  value?: string
+  delimiter?: string
+  children?: HL7v2JsonNode[]
+}
+```
+
+## Security
+
+This plugin only transforms AST nodes and does not execute code. Ensure you trust the source of HL7v2 messages before processing.
+
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) 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](CODE_OF_CONDUCT.md) 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](LICENSE) file for details.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { HL7v2Node } from '@rethinkhealth/hl7v2-ast';
+import type { Plugin } from 'unified';
+type SegmentJSON = {
+    segment: string;
+    fields: (string | string[])[];
+};
+export declare const hl7v2Jsonify: Plugin<[], HL7v2Node, string>;
+export declare function toJson(root: HL7v2Node): SegmentJSON[];
+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,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAStD,CAAC;AAEF,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,EAAE,CA6BrD"}

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/index.ts
+import { visitParents } from "unist-util-visit-parents";
+var hl7v2Jsonify = function() {
+  const self = this;
+  function compiler(tree) {
+    return JSON.stringify(toJson(tree), null, 2);
+  }
+  self.compiler = compiler;
+};
+function toJson(root) {
+  const segments = [];
+  let currentSegment = null;
+  visitParents(root, (node, ancestors) => {
+    if (node.type === "segment") {
+      currentSegment = { segment: node.name || "UNKNOWN", fields: [] };
+      segments.push(currentSegment);
+    }
+    if (node.value !== void 0 && currentSegment) {
+      const path = [...ancestors, node].filter(
+        (n) => n.index !== void 0 && n.type !== "segment" && n.type !== "root"
+      ).map((n) => {
+        if (typeof n.index !== "number") {
+          throw new Error("HL7 AST node is missing a numeric index");
+        }
+        return n.index - 1;
+      });
+      setNestedArrayValue(currentSegment.fields, path, node.value);
+    }
+  });
+  return segments;
+}
+function setNestedArrayValue(arr, path, value) {
+  let current = arr;
+  for (let i = 0; i < path.length - 1; i++) {
+    const idx = path[i];
+    if (idx === void 0) {
+      return;
+    }
+    if (!current[idx]) {
+      current[idx] = [];
+    }
+    current = current[idx];
+  }
+  const lastKey = path.at(-1);
+  if (lastKey === void 0) {
+    return;
+  }
+  current[lastKey] = value;
+}
+export {
+  hl7v2Jsonify,
+  toJson
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { HL7v2Node } from '@rethinkhealth/hl7v2-ast';\nimport type { Plugin } from 'unified';\nimport type { Node } from 'unist';\nimport { visitParents } from 'unist-util-visit-parents';\n\ntype SegmentJSON = {\n  segment: string;\n  fields: (string | string[])[]; // Nested arrays for fields/repetitions/components\n};\n\nexport const hl7v2Jsonify: Plugin<[], HL7v2Node, string> = function (): void {\n  // biome-ignore lint/complexity/noUselessThisAlias: this is a plugin\n  const self = this;\n\n  function compiler(tree: Node): string {\n    return JSON.stringify(toJson(tree as HL7v2Node), null, 2);\n  }\n\n  self.compiler = compiler;\n};\n\nexport function toJson(root: HL7v2Node): SegmentJSON[] {\n  const segments: SegmentJSON[] = [];\n  let currentSegment: SegmentJSON | null = null;\n\n  visitParents<HL7v2Node, HL7v2Node>(root, (node, ancestors) => {\n    if (node.type === 'segment') {\n      currentSegment = { segment: node.name || 'UNKNOWN', fields: [] };\n      segments.push(currentSegment);\n    }\n\n    if (node.value !== undefined && currentSegment) {\n      // Build numeric path for all indices except segment/root\n      const path = [...ancestors, node]\n        .filter(\n          (n) =>\n            n.index !== undefined && n.type !== 'segment' && n.type !== 'root'\n        )\n        .map((n) => {\n          if (typeof n.index !== 'number') {\n            throw new Error('HL7 AST node is missing a numeric index');\n          }\n          return n.index - 1;\n        });\n\n      setNestedArrayValue(currentSegment.fields, path, node.value);\n    }\n  });\n\n  return segments;\n}\n\n/**\n * Recursively create nested arrays along the path and set the value.\n */\nfunction setNestedArrayValue(\n  arr: (string | string[])[],\n  path: number[],\n  value: string\n) {\n  let current: (string | string[])[] = arr;\n  for (let i = 0; i < path.length - 1; i++) {\n    const idx = path[i];\n\n    if (idx === undefined) {\n      return;\n    }\n\n    if (!current[idx]) {\n      current[idx] = [];\n    }\n    current = current[idx] as (string | string[])[];\n  }\n\n  const lastKey = path.at(-1);\n  if (lastKey === undefined) {\n    return;\n  }\n\n  current[lastKey] = value;\n}\n"],"mappings":";AAGA,SAAS,oBAAoB;AAOtB,IAAM,eAA8C,WAAkB;AAE3E,QAAM,OAAO;AAEb,WAAS,SAAS,MAAoB;AACpC,WAAO,KAAK,UAAU,OAAO,IAAiB,GAAG,MAAM,CAAC;AAAA,EAC1D;AAEA,OAAK,WAAW;AAClB;AAEO,SAAS,OAAO,MAAgC;AACrD,QAAM,WAA0B,CAAC;AACjC,MAAI,iBAAqC;AAEzC,eAAmC,MAAM,CAAC,MAAM,cAAc;AAC5D,QAAI,KAAK,SAAS,WAAW;AAC3B,uBAAiB,EAAE,SAAS,KAAK,QAAQ,WAAW,QAAQ,CAAC,EAAE;AAC/D,eAAS,KAAK,cAAc;AAAA,IAC9B;AAEA,QAAI,KAAK,UAAU,UAAa,gBAAgB;AAE9C,YAAM,OAAO,CAAC,GAAG,WAAW,IAAI,EAC7B;AAAA,QACC,CAAC,MACC,EAAE,UAAU,UAAa,EAAE,SAAS,aAAa,EAAE,SAAS;AAAA,MAChE,EACC,IAAI,CAAC,MAAM;AACV,YAAI,OAAO,EAAE,UAAU,UAAU;AAC/B,gBAAM,IAAI,MAAM,yCAAyC;AAAA,QAC3D;AACA,eAAO,EAAE,QAAQ;AAAA,MACnB,CAAC;AAEH,0BAAoB,eAAe,QAAQ,MAAM,KAAK,KAAK;AAAA,IAC7D;AAAA,EACF,CAAC;AAED,SAAO;AACT;AAKA,SAAS,oBACP,KACA,MACA,OACA;AACA,MAAI,UAAiC;AACrC,WAAS,IAAI,GAAG,IAAI,KAAK,SAAS,GAAG,KAAK;AACxC,UAAM,MAAM,KAAK,CAAC;AAElB,QAAI,QAAQ,QAAW;AACrB;AAAA,IACF;AAEA,QAAI,CAAC,QAAQ,GAAG,GAAG;AACjB,cAAQ,GAAG,IAAI,CAAC;AAAA,IAClB;AACA,cAAU,QAAQ,GAAG;AAAA,EACvB;AAEA,QAAM,UAAU,KAAK,GAAG,EAAE;AAC1B,MAAI,YAAY,QAAW;AACzB;AAAA,EACF;AAEA,UAAQ,OAAO,IAAI;AACrB;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@rethinkhealth/hl7v2-jsonify",
+  "description": "hl7v2 plugin to transform hl7v2 messages to a simplified JSON representation",
+  "version": "0.2.1",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "unified": "11.0.1",
+    "unist-util-visit": "^5.0.0",
+    "unist-util-visit-parents": "^6.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.31",
+    "@types/unist": "^3.0.3",
+    "@vitest/coverage-c8": "^0.33.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@rethinkhealth/hl7v2-ast": "0.2.1",
+    "@rethinkhealth/testing": "0.0.0",
+    "@rethinkhealth/tsconfig": "0.0.0"
+  },
+  "repository": "rethinkhealth/hl7v2.git",
+  "homepage": "https://www.rethinkhealth.io/hl7v2/docs",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}