@rethinkhealth/hl7v2-encode-escapes 0.7.0

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,118 @@
+# @rethinkhealth/hl7v2-encode-escapes
+
+**[unified](https://unifiedjs.com/)** plugin to encode special characters as HL7v2 escape sequences in literal values.
+
+## What is this?
+
+`@rethinkhealth/hl7v2-encode-escapes` is a [unified](https://unifiedjs.com/) plugin that traverses an HL7v2 syntax tree and encodes delimiter characters in all literal values (`subcomponent` nodes) as HL7v2 escape sequences.
+
+This is the inverse of [`@rethinkhealth/hl7v2-decode-escapes`](https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-decode-escapes), handling:
+
+- Delimiter encoding (`|` → `\F\`, `^` → `\S\`, `~` → `\R\`, `&` → `\T\`)
+- Escape character encoding (`\` → `\E\`)
+- Line break encoding (`\r` → `\.br\`)
+
+## When should I use this?
+
+Use this plugin when you need to:
+
+- Prepare an HL7v2 AST for serialization after modifying subcomponent values that may contain delimiter characters.
+- Ensure values with special characters are safely encoded before converting the AST back to HL7v2 text with [`@rethinkhealth/hl7v2-to-hl7v2`](https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-to-hl7v2).
+
+## Install
+
+This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+
+In Node.js (version 18+), install with [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm):
+
+```sh
+npm install @rethinkhealth/hl7v2-encode-escapes
+```
+
+## Use
+
+```js
+import { unified } from "unified";
+import { hl7v2EncodeEscapes } from "@rethinkhealth/hl7v2-encode-escapes";
+import { hl7v2ToHl7v2 } from "@rethinkhealth/hl7v2-to-hl7v2";
+
+// After modifying AST values that may contain delimiters:
+const file = await unified()
+  .use(hl7v2EncodeEscapes) // encode special chars as escape sequences
+  .use(hl7v2ToHl7v2) // serialize AST to HL7v2 text
+  .stringify(tree);
+```
+
+Before encoding, a `subcomponent.value` might contain literal delimiters:
+
+```json
+{
+  "type": "subcomponent",
+  "value": "Patient allergic to |Peanuts| and \rSevere reaction"
+}
+```
+
+After this plugin runs:
+
+```json
+{
+  "type": "subcomponent",
+  "value": "Patient allergic to \\F\\Peanuts\\F\\ and \\.br\\Severe reaction"
+}
+```
+
+## API
+
+### `unified().use(hl7v2EncodeEscapes[, options])`
+
+Encode special characters as 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.
+
+## Round-trip compatibility
+
+This plugin is the inverse of `@rethinkhealth/hl7v2-decode-escapes`. Encoding then decoding restores the original value:
+
+```js
+import { hl7v2DecodeEscapes } from "@rethinkhealth/hl7v2-decode-escapes";
+import { hl7v2EncodeEscapes } from "@rethinkhealth/hl7v2-encode-escapes";
+
+// encode → decode round-trip
+const encoded = await unified().use(hl7v2EncodeEscapes).run(tree);
+const decoded = await unified().use(hl7v2DecodeEscapes).run(encoded);
+// decoded values === original values
+```
+
+## 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][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,16 @@
+import type { Delimiters, Root } from "@rethinkhealth/hl7v2-ast";
+import type { Plugin } from "unified";
+export interface HL7v2EncodeOptions {
+    delimiters?: Partial<Delimiters>;
+}
+/**
+ * Unified plugin to encode special characters as HL7v2 escape sequences
+ * in subcomponent literals.
+ *
+ * - Encodes delimiter characters: | → \F\, ^ → \S\, ~ → \R\, & → \T\
+ * - Encodes escape character: \ → \E\
+ * - Encodes segment delimiter: \r → \.br\
+ * - Uses delimiters from Root.data.delimiters if available
+ */
+export declare const hl7v2EncodeEscapes: Plugin<[HL7v2EncodeOptions?], Root, 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,UAAU,EAAE,IAAI,EAAgB,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAetE,CAAC"}

package/dist/index.js

@@ -0,0 +1,40 @@
+// src/index.ts
+import { DEFAULT_DELIMITERS } from "@rethinkhealth/hl7v2-utils";
+import { visit } from "unist-util-visit";
+var hl7v2EncodeEscapes = (options) => (tree) => {
+  const d = {
+    ...DEFAULT_DELIMITERS,
+    ...tree.data?.delimiters,
+    ...options?.delimiters
+  };
+  const charToEscape = buildEscapeMap(d);
+  visit(tree, "subcomponent", (node) => {
+    node.value = encode(node.value, charToEscape);
+  });
+  return tree;
+};
+function buildEscapeMap(d) {
+  return /* @__PURE__ */ new Map([
+    [d.escape, `${d.escape}E${d.escape}`],
+    [d.field, `${d.escape}F${d.escape}`],
+    [d.component, `${d.escape}S${d.escape}`],
+    [d.repetition, `${d.escape}R${d.escape}`],
+    [d.subcomponent, `${d.escape}T${d.escape}`],
+    [d.segment, `${d.escape}.br${d.escape}`]
+  ]);
+}
+function encode(value, charToEscape) {
+  if (!value) {
+    return value;
+  }
+  let encoded = "";
+  for (const ch of value) {
+    const escape = charToEscape.get(ch);
+    encoded += escape ?? ch;
+  }
+  return encoded;
+}
+export {
+  hl7v2EncodeEscapes
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Delimiters, Root, Subcomponent } from \"@rethinkhealth/hl7v2-ast\";\nimport { DEFAULT_DELIMITERS } from \"@rethinkhealth/hl7v2-utils\";\nimport type { Plugin } from \"unified\";\nimport { visit } from \"unist-util-visit\";\n\nexport interface HL7v2EncodeOptions {\n  delimiters?: Partial<Delimiters>;\n}\n\n/**\n * Unified plugin to encode special characters as HL7v2 escape sequences\n * in subcomponent literals.\n *\n * - Encodes delimiter characters: | → \\F\\, ^ → \\S\\, ~ → \\R\\, & → \\T\\\n * - Encodes escape character: \\ → \\E\\\n * - Encodes segment delimiter: \\r → \\.br\\\n * - Uses delimiters from Root.data.delimiters if available\n */\nexport const hl7v2EncodeEscapes: Plugin<[HL7v2EncodeOptions?], Root, Root> =\n  (options) => (tree: Root) => {\n    const d = {\n      ...DEFAULT_DELIMITERS,\n      ...(tree.data as { delimiters?: Partial<Delimiters> })?.delimiters,\n      ...options?.delimiters,\n    };\n\n    const charToEscape = buildEscapeMap(d);\n\n    visit(tree, \"subcomponent\", (node: Subcomponent) => {\n      node.value = encode(node.value, charToEscape);\n    });\n\n    return tree;\n  };\n\n/**\n * Build a map from literal characters to their HL7v2 escape sequences.\n * The escape character must be mapped first to avoid double-encoding.\n */\nfunction buildEscapeMap(\n  d: typeof DEFAULT_DELIMITERS\n): ReadonlyMap<string, string> {\n  return new Map<string, string>([\n    [d.escape, `${d.escape}E${d.escape}`],\n    [d.field, `${d.escape}F${d.escape}`],\n    [d.component, `${d.escape}S${d.escape}`],\n    [d.repetition, `${d.escape}R${d.escape}`],\n    [d.subcomponent, `${d.escape}T${d.escape}`],\n    [d.segment, `${d.escape}.br${d.escape}`],\n  ]);\n}\n\n/**\n * Encode special characters in a value as HL7v2 escape sequences.\n *\n * @param value - The value to encode.\n * @param charToEscape - Map of characters to their escape sequences.\n * @returns The encoded value.\n */\nfunction encode(\n  value: string,\n  charToEscape: ReadonlyMap<string, string>\n): string {\n  if (!value) {\n    return value;\n  }\n\n  let encoded = \"\";\n\n  for (const ch of value) {\n    const escape = charToEscape.get(ch);\n    encoded += escape ?? ch;\n  }\n\n  return encoded;\n}\n"],"mappings":";AACA,SAAS,0BAA0B;AAEnC,SAAS,aAAa;AAef,IAAM,qBACX,CAAC,YAAY,CAAC,SAAe;AAC3B,QAAM,IAAI;AAAA,IACR,GAAG;AAAA,IACH,GAAI,KAAK,MAA+C;AAAA,IACxD,GAAG,SAAS;AAAA,EACd;AAEA,QAAM,eAAe,eAAe,CAAC;AAErC,QAAM,MAAM,gBAAgB,CAAC,SAAuB;AAClD,SAAK,QAAQ,OAAO,KAAK,OAAO,YAAY;AAAA,EAC9C,CAAC;AAED,SAAO;AACT;AAMF,SAAS,eACP,GAC6B;AAC7B,SAAO,oBAAI,IAAoB;AAAA,IAC7B,CAAC,EAAE,QAAQ,GAAG,EAAE,MAAM,IAAI,EAAE,MAAM,EAAE;AAAA,IACpC,CAAC,EAAE,OAAO,GAAG,EAAE,MAAM,IAAI,EAAE,MAAM,EAAE;AAAA,IACnC,CAAC,EAAE,WAAW,GAAG,EAAE,MAAM,IAAI,EAAE,MAAM,EAAE;AAAA,IACvC,CAAC,EAAE,YAAY,GAAG,EAAE,MAAM,IAAI,EAAE,MAAM,EAAE;AAAA,IACxC,CAAC,EAAE,cAAc,GAAG,EAAE,MAAM,IAAI,EAAE,MAAM,EAAE;AAAA,IAC1C,CAAC,EAAE,SAAS,GAAG,EAAE,MAAM,MAAM,EAAE,MAAM,EAAE;AAAA,EACzC,CAAC;AACH;AASA,SAAS,OACP,OACA,cACQ;AACR,MAAI,CAAC,OAAO;AACV,WAAO;AAAA,EACT;AAEA,MAAI,UAAU;AAEd,aAAW,MAAM,OAAO;AACtB,UAAM,SAAS,aAAa,IAAI,EAAE;AAClC,eAAW,UAAU;AAAA,EACvB;AAEA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@rethinkhealth/hl7v2-encode-escapes",
+  "version": "0.7.0",
+  "description": "hl7v2 plugin to encode special characters as hl7v2 escape sequences",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript"
+  ],
+  "homepage": "https://www.rethinkhealth.io/hl7v2/docs",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": "rethinkhealth/hl7v2.git",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "unified": "11.0.5",
+    "unist-util-visit": "5.0.0",
+    "@rethinkhealth/hl7v2-utils": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/unist": "^3.0.3",
+    "@vitest/coverage-v8": "4.0.18",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.0",
+    "@rethinkhealth/hl7v2-ast": "0.7.0",
+    "@rethinkhealth/hl7v2-builder": "0.7.0",
+    "@rethinkhealth/hl7v2-decode-escapes": "0.7.0",
+    "@rethinkhealth/testing": "0.0.2",
+    "@rethinkhealth/tsconfig": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.14.0",
+  "scripts": {
+    "bench": "vitest bench --run",
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}