@rethinkhealth/hl7v2-decode-escapes 0.2.4

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,117 @@
+# @rethinkhealth/hl7v2-decode-escapes
+
+**[unified](https://unifiedjs.com/)** plugin to decode HL7v2 escape sequences in literal values.
+
+## What is this?
+
+`@rethinkhealth/hl7v2-decode-escapes` is a [unified](https://unifiedjs.com/) plugin that traverses an HL7v2 syntax tree (produced by a parser such as [`@rethinkhealth/hl7v2-ast`](https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-parser)) and decodes HL7v2 escape sequences in all literal values (`subcomponent` nodes).
+
+It preserves the original raw value and replaces the `value` property with the decoded text, handling:
+
+* HL7 delimiter escapes (`\F\`, `\S\`, `\R\`, `\T\`, `\E\`)
+* Hexadecimal escapes (`\Xdddd\`)
+* Line break directives (`\.br\`)
+* Highlighting markers (`\H\`, `\N\`)
+
+## When should I use this?
+
+Use this plugin when you need:
+
+* Human-readable HL7v2 values with escape sequences decoded.
+* To process or display HL7v2 message content where `\F\` and similar escapes should be expanded.
+
+If you need to parse 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-decode-escapes
+```
+
+## Use
+
+Say we have an HL7v2 message with escapes:
+
+```js
+import { unified } from 'unified'
+import { hl7v2Parse } from '@rethinkhealth/hl7v2-ast'
+import { hl7v2DecodeLiterals } from '@rethinkhealth/hl7v2-decode-escapes'
+
+const msg = `OBX|1|TX|ID123||Patient allergic to \\F\\Peanuts\\F\\ and \\.br\\Severe reaction`
+
+const file = await unified()
+  .use(hl7v2Parse)
+  .use(hl7v2DecodeLiterals)
+  .process(msg)
+
+console.log(String(file))
+```
+
+Before decoding, the `subcomponent.value` contains the raw HL7 text:
+
+```json
+{
+  "type": "subcomponent",
+  "index": 1,
+  "value": "Patient allergic to \\F\\Peanuts\\F\\ and \\.br\\Severe reaction"
+}
+```
+
+After this plugin runs:
+
+```json
+{
+  "type": "subcomponent",
+  "index": 1,
+  "value": "Patient allergic to |Peanuts| and \rSevere reaction",
+}
+```
+
+## API
+
+### `unified().use(hl7v2DecodeLiterals[, options])`
+
+Decode HL7v2 escape sequences in literal nodes.
+
+###### Parameters
+
+* `options.delimiters` (optional) — Override delimiters. If omitted, the plugin reads them from `Root.data.delimiters` (set by the parser). Defaults to the HL7 standard (`| ^ ~ & \`).
+
+###### Returns
+
+Nothing (`undefined`). Mutates the AST in-place.
+
+## Behavior
+
+* Preserves original text in `node.data.raw`.
+* Decodes into `node.value`.
+* Uses `Root.data.delimiters` (preferred) or `options.delimiters`.
+* Falls back to defaults if neither is present.
+
+## 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,16 @@
+import type { Root } from '@rethinkhealth/hl7v2-ast';
+import { type HL7v2Delimiters } from '@rethinkhealth/hl7v2-utils';
+import type { Plugin } from 'unified';
+export interface HL7v2DecodeOptions {
+    delimiters?: Partial<HL7v2Delimiters>;
+}
+/**
+ * Unified plugin to decode HL7v2 escape sequences in subcomponent literals.
+ *
+ * - Decodes \F\, \S\, \T\, \R\, \E\
+ * - Decodes \Xdddd\ hex escapes
+ * - Handles \.br\ line breaks
+ * - Uses delimiters from Root.data.delimiters if available
+ */
+export declare const hl7v2DecodeEscapes: Plugin<[HL7v2DecodeOptions?], Root>;
+//# 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,IAAI,EAAgB,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC,EAAE,IAAI,CAgBlE,CAAC"}

package/dist/index.js

@@ -0,0 +1,83 @@
+// src/index.ts
+import {
+  DEFAULT_DELIMITERS
+} from "@rethinkhealth/hl7v2-utils";
+import { visit } from "unist-util-visit";
+var hl7v2DecodeEscapes = (options) => {
+  return (tree) => {
+    const delimiters = tree.data?.delimiters || options?.delimiters;
+    visit(tree, "subcomponent", (node) => {
+      const raw = node.value;
+      node.value = decode(raw, {
+        ...DEFAULT_DELIMITERS,
+        ...delimiters
+      });
+    });
+  };
+};
+function decode(value, d) {
+  if (!value?.includes(d.escape)) {
+    return value;
+  }
+  let decoded = "";
+  let i = 0;
+  while (i < value.length) {
+    if (value[i] === d.escape) {
+      const end = value.indexOf(d.escape, i + 1);
+      if (end === -1) {
+        decoded += value.slice(i);
+        break;
+      }
+      const code = value.slice(i + 1, end);
+      switch (code) {
+        case "F":
+          decoded += d.field;
+          break;
+        case "S":
+          decoded += d.component;
+          break;
+        case "R":
+          decoded += d.repetition;
+          break;
+        case "T":
+          decoded += d.subcomponent;
+          break;
+        case "E":
+          decoded += d.escape;
+          break;
+        case ".br":
+          decoded += "\r";
+          break;
+        case "H":
+        case "N":
+          break;
+        default:
+          if (code.startsWith("X") && code.length > 1) {
+            decoded += decodeHexSequence(code.slice(1));
+          } else {
+            decoded += d.escape + code + d.escape;
+          }
+          break;
+      }
+      i = end + 1;
+    } else {
+      decoded += value[i++];
+    }
+  }
+  return decoded;
+}
+function decodeHexSequence(hex) {
+  let result = "";
+  for (let i = 0; i < hex.length; i += 2) {
+    const byte = hex.slice(i, i + 2);
+    const codePoint = Number.parseInt(byte, 16);
+    if (!Number.isNaN(codePoint)) {
+      result += String.fromCharCode(codePoint);
+    }
+  }
+  return result;
+}
+export {
+  hl7v2DecodeEscapes
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Root, Subcomponent } from '@rethinkhealth/hl7v2-ast';\nimport {\n  DEFAULT_DELIMITERS,\n  type HL7v2Delimiters,\n} from '@rethinkhealth/hl7v2-utils';\nimport type { Plugin } from 'unified';\nimport { visit } from 'unist-util-visit';\n\nexport interface HL7v2DecodeOptions {\n  delimiters?: Partial<HL7v2Delimiters>;\n}\n\n/**\n * Unified plugin to decode HL7v2 escape sequences in subcomponent literals.\n *\n * - Decodes \\F\\, \\S\\, \\T\\, \\R\\, \\E\\\n * - Decodes \\Xdddd\\ hex escapes\n * - Handles \\.br\\ line breaks\n * - Uses delimiters from Root.data.delimiters if available\n */\nexport const hl7v2DecodeEscapes: Plugin<[HL7v2DecodeOptions?], Root> = (\n  options\n) => {\n  return (tree: Root) => {\n    const delimiters =\n      (tree.data as { delimiters?: Partial<HL7v2Delimiters> })?.delimiters ||\n      options?.delimiters;\n\n    visit(tree, 'subcomponent', (node: Subcomponent) => {\n      const raw = node.value;\n      node.value = decode(raw, {\n        ...DEFAULT_DELIMITERS,\n        ...delimiters,\n      });\n    });\n  };\n};\n\n/**\n * Decode HL7v2 escape sequences according to HL7 v2.8 spec.\n *\n * @param value - The value to decode.\n * @param d - The delimiters to use.\n * @returns The decoded value.\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: this function must handle multiple HL7v2 escape cases and is as simple as possible given the requirements\nfunction decode(value: string, d: typeof DEFAULT_DELIMITERS): string {\n  if (!value?.includes(d.escape)) {\n    return value;\n  }\n\n  let decoded = '';\n  let i = 0;\n\n  while (i < value.length) {\n    if (value[i] === d.escape) {\n      const end = value.indexOf(d.escape, i + 1);\n      if (end === -1) {\n        decoded += value.slice(i); // unterminated escape\n        break;\n      }\n\n      const code = value.slice(i + 1, end);\n\n      switch (code) {\n        case 'F':\n          decoded += d.field;\n          break;\n        case 'S':\n          decoded += d.component;\n          break;\n        case 'R':\n          decoded += d.repetition;\n          break;\n        case 'T':\n          decoded += d.subcomponent;\n          break;\n        case 'E':\n          decoded += d.escape;\n          break;\n        case '.br':\n          decoded += '\\r'; // or '\\n' if you prefer LF\n          break;\n        case 'H':\n        case 'N':\n          // Highlight start/end: ignored for now\n          break;\n        default:\n          if (code.startsWith('X') && code.length > 1) {\n            decoded += decodeHexSequence(code.slice(1));\n          } else {\n            // Unknown escape: preserve as-is\n            decoded += d.escape + code + d.escape;\n          }\n          break;\n      }\n\n      i = end + 1;\n    } else {\n      decoded += value[i++];\n    }\n  }\n\n  return decoded;\n}\n\n/**\n * Decode HL7 \\Xdddd\\ hexadecimal escape sequences into characters.\n */\nfunction decodeHexSequence(hex: string): string {\n  let result = '';\n  for (let i = 0; i < hex.length; i += 2) {\n    const byte = hex.slice(i, i + 2);\n    const codePoint = Number.parseInt(byte, 16);\n    if (!Number.isNaN(codePoint)) {\n      result += String.fromCharCode(codePoint);\n    }\n  }\n  return result;\n}\n"],"mappings":";AACA;AAAA,EACE;AAAA,OAEK;AAEP,SAAS,aAAa;AAcf,IAAM,qBAA0D,CACrE,YACG;AACH,SAAO,CAAC,SAAe;AACrB,UAAM,aACH,KAAK,MAAoD,cAC1D,SAAS;AAEX,UAAM,MAAM,gBAAgB,CAAC,SAAuB;AAClD,YAAM,MAAM,KAAK;AACjB,WAAK,QAAQ,OAAO,KAAK;AAAA,QACvB,GAAG;AAAA,QACH,GAAG;AAAA,MACL,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AACF;AAUA,SAAS,OAAO,OAAe,GAAsC;AACnE,MAAI,CAAC,OAAO,SAAS,EAAE,MAAM,GAAG;AAC9B,WAAO;AAAA,EACT;AAEA,MAAI,UAAU;AACd,MAAI,IAAI;AAER,SAAO,IAAI,MAAM,QAAQ;AACvB,QAAI,MAAM,CAAC,MAAM,EAAE,QAAQ;AACzB,YAAM,MAAM,MAAM,QAAQ,EAAE,QAAQ,IAAI,CAAC;AACzC,UAAI,QAAQ,IAAI;AACd,mBAAW,MAAM,MAAM,CAAC;AACxB;AAAA,MACF;AAEA,YAAM,OAAO,MAAM,MAAM,IAAI,GAAG,GAAG;AAEnC,cAAQ,MAAM;AAAA,QACZ,KAAK;AACH,qBAAW,EAAE;AACb;AAAA,QACF,KAAK;AACH,qBAAW,EAAE;AACb;AAAA,QACF,KAAK;AACH,qBAAW,EAAE;AACb;AAAA,QACF,KAAK;AACH,qBAAW,EAAE;AACb;AAAA,QACF,KAAK;AACH,qBAAW,EAAE;AACb;AAAA,QACF,KAAK;AACH,qBAAW;AACX;AAAA,QACF,KAAK;AAAA,QACL,KAAK;AAEH;AAAA,QACF;AACE,cAAI,KAAK,WAAW,GAAG,KAAK,KAAK,SAAS,GAAG;AAC3C,uBAAW,kBAAkB,KAAK,MAAM,CAAC,CAAC;AAAA,UAC5C,OAAO;AAEL,uBAAW,EAAE,SAAS,OAAO,EAAE;AAAA,UACjC;AACA;AAAA,MACJ;AAEA,UAAI,MAAM;AAAA,IACZ,OAAO;AACL,iBAAW,MAAM,GAAG;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AAKA,SAAS,kBAAkB,KAAqB;AAC9C,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK,GAAG;AACtC,UAAM,OAAO,IAAI,MAAM,GAAG,IAAI,CAAC;AAC/B,UAAM,YAAY,OAAO,SAAS,MAAM,EAAE;AAC1C,QAAI,CAAC,OAAO,MAAM,SAAS,GAAG;AAC5B,gBAAU,OAAO,aAAa,SAAS;AAAA,IACzC;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@rethinkhealth/hl7v2-decode-escapes",
+  "description": "hl7v2 plugin to decode hl7v2 escape sequences",
+  "version": "0.2.4",
+  "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",
+    "@rethinkhealth/hl7v2-utils": "0.2.4"
+  },
+  "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.4",
+    "@rethinkhealth/tsconfig": "0.0.0",
+    "@rethinkhealth/testing": "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"
+  }
+}