@glion/encode-escapes 0.27.0 → 0.28.0

package/README.md

@@ -4,7 +4,9 @@ Unified plugin to encode special characters as HL7v2 escape sequences in literal
 
 ## What it does
 
-Walks an HL7v2 AST and encodes delimiter characters found in `subcomponent` node values as HL7v2 escape sequences, so a tree that has been modified in memory can be safely serialized back to HL7v2 text without breaking the delimiter structure. It is the inverse of [`@glion/decode-escapes`](https://github.com/rethinkhealth/glion/tree/main/packages/decode-escapes): encode then decode round-trips to the original values.
+Walks an HL7v2 AST and encodes delimiter and control characters found in `subcomponent` node values as HL7v2 escape sequences. It is the inverse of [`@glion/decode-escapes`](https://github.com/rethinkhealth/glion/tree/main/packages/decode-escapes): encode then decode round-trips to the original values.
+
+`@glion/to-hl7v2` encodes escape sequences while serializing, so this plugin is for a tree written with `encodeEscapes: false`.
 
 ## Install
 
@@ -22,7 +24,7 @@ import { unified } from "unified";
 // 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
+  .use(hl7v2ToHl7v2, { encodeEscapes: false }) // serialize AST to HL7v2 text
   .stringify(tree);
 ```
 
@@ -52,7 +54,7 @@ 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 (`| ^ ~ & \`).
+- `options.delimiters` (optional) — Override delimiters. If omitted, the plugin reads them from `file.data.delimiters` (set by `@glion/annotate-delimiters`). Defaults to the HL7 standard (`| ^ ~ & \`).
 
 ###### Returns
 
@@ -60,18 +62,19 @@ Nothing (`undefined`). Mutates the AST in-place.
 
 ## Behavior
 
-The plugin visits every `subcomponent` node and rewrites `node.value`, substituting delimiter and control characters with their HL7v2 escape sequences:
+The plugin visits every `subcomponent` node and rewrites `node.value`, substituting delimiter and control characters with their HL7v2 escape sequences. A formatting command such as `\H\`, `\N\`, or `\.sp 2\`, a locally defined sequence (`\Z…\`), and a character set switch (`\Cxxyy\`, `\Mxxyyzz\`) are written as they are.
 
-| Input | Output                         |
-| ----- | ------------------------------ |
-| `\|`  | `\F\` (field separator)        |
-| `^`   | `\S\` (component separator)    |
-| `~`   | `\R\` (repetition separator)   |
-| `&`   | `\T\` (subcomponent separator) |
-| `\`   | `\E\` (escape character)       |
-| `\r`  | `\.br\` (line break directive) |
+| Input                         | Output                         |
+| ----------------------------- | ------------------------------ |
+| `\|`                          | `\F\` (field separator)        |
+| `^`                           | `\S\` (component separator)    |
+| `~`                           | `\R\` (repetition separator)   |
+| `&`                           | `\T\` (subcomponent separator) |
+| `\`                           | `\E\` (escape character)       |
+| `\r`                          | `\.br\` (line break directive) |
+| other characters below U+0020 | `\Xdd\` (hexadecimal escape)   |
 
-Delimiter resolution order: `Root.data.delimiters` (preferred, set by the parser) → `options.delimiters` → HL7 defaults.
+Delimiter resolution order: `options.delimiters` → `file.data.delimiters` (set by `@glion/annotate-delimiters`) → HL7 defaults.
 
 This is the inverse of [`@glion/decode-escapes`](https://github.com/rethinkhealth/glion/tree/main/packages/decode-escapes):
 

package/dist/index.d.ts

@@ -4,13 +4,9 @@ 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\
- * - Skips MSH-1 and MSH-2 (they define the delimiters and must not be escaped)
+ * Unified plugin to encode special characters as HL7v2 escape sequences in
+ * subcomponent literals, for a tree that `@glion/to-hl7v2` writes with
+ * `encodeEscapes: false`. MSH-1 and MSH-2 are left as they are.
  *
  * Delimiter resolution order:
  *

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,UAAU,EAAE,IAAI,EAAyB,MAAM,YAAY,CAAC;AAE1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CA+BtE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAS,IAAI,EAAE,MAAM,YAAY,CAAC;AAI1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAyBtE,CAAC"}

package/dist/index.js

@@ -1,14 +1,11 @@
-import { DEFAULT_DELIMITERS } from "@glion/utils";
-import { SKIP, visit } from "unist-util-visit";
+import { selectAll } from "@glion/util-query";
+import { visit } from "@glion/util-visit";
+import { DEFAULT_DELIMITERS, encodeEscapes } from "@glion/utils";
 //#region src/index.ts
 /**
-* 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\
-* - Skips MSH-1 and MSH-2 (they define the delimiters and must not be escaped)
+* Unified plugin to encode special characters as HL7v2 escape sequences in
+* subcomponent literals, for a tree that `@glion/to-hl7v2` writes with
+* `encodeEscapes: false`. MSH-1 and MSH-2 are left as they are.
 *
 * Delimiter resolution order:
 *
@@ -17,46 +14,17 @@ import { SKIP, visit } from "unist-util-visit";
 * 3. `DEFAULT_DELIMITERS`
 */
 const hl7v2EncodeEscapes = (options) => (tree, file) => {
-	const charToEscape = buildEscapeMap({
+	const d = {
 		...file.data.delimiters ?? DEFAULT_DELIMITERS,
 		...options?.delimiters
-	});
-	visit(tree, (node, index, parent) => {
-		if (node.type === "field" && index !== void 0 && index < 2 && parent?.type === "segment" && parent.name === "MSH") return SKIP;
-		if (node.type === "subcomponent") node.value = encode(node.value, charToEscape);
+	};
+	const encodingCharacters = new Set([...selectAll(tree, "MSH.1"), ...selectAll(tree, "MSH.2")].map((match) => match.node));
+	visit(tree, "subcomponent", (node, ancestors) => {
+		if (node.value === void 0 || ancestors.some((ancestor) => encodingCharacters.has(ancestor))) return;
+		node.value = encodeEscapes(node.value, d);
 	});
 	return tree;
 };
-/**
-* Build a map from literal characters to their HL7v2 escape sequences.
-* The escape character must be mapped first to avoid double-encoding.
-*/
-function buildEscapeMap(d) {
-	return 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}`]
-	]);
-}
-/**
-* Encode special characters in a value as HL7v2 escape sequences.
-*
-* @param value - The value to encode.
-* @param charToEscape - Map of characters to their escape sequences.
-* @returns The encoded value.
-*/
-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;
-}
 //#endregion
 export { hl7v2EncodeEscapes };
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Delimiters, Root, Segment, Subcomponent } from \"@glion/ast\";\nimport { DEFAULT_DELIMITERS } from \"@glion/utils\";\nimport type { Plugin } from \"unified\";\nimport { SKIP, visit } from \"unist-util-visit\";\nimport type { VFile } from \"vfile\";\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 * - Skips MSH-1 and MSH-2 (they define the delimiters and must not be escaped)\n *\n * Delimiter resolution order:\n *\n * 1. `options.delimiters` (explicit override)\n * 2. `file.data.delimiters` (set by hl7v2-annotate-delimiters)\n * 3. `DEFAULT_DELIMITERS`\n */\nexport const hl7v2EncodeEscapes: Plugin<[HL7v2EncodeOptions?], Root, Root> =\n  (options) => (tree: Root, file: VFile) => {\n    const d = {\n      ...((file.data.delimiters as Delimiters | undefined) ??\n        DEFAULT_DELIMITERS),\n      ...options?.delimiters,\n    };\n\n    const charToEscape = buildEscapeMap(d);\n\n    visit(tree, (node, index, parent) => {\n      // Skip MSH-1 (index 0) and MSH-2 (index 1) — they define delimiters\n      if (\n        node.type === \"field\" &&\n        index !== undefined &&\n        index < 2 &&\n        parent?.type === \"segment\" &&\n        (parent as Segment).name === \"MSH\"\n      ) {\n        return SKIP;\n      }\n\n      if (node.type === \"subcomponent\") {\n        (node as Subcomponent).value = encode(\n          (node as Subcomponent).value,\n          charToEscape\n        );\n      }\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(d: Delimiters): 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":";;;;;;;;;;;;;;;;;;AAyBA,MAAa,sBACV,aAAa,MAAY,SAAgB;CAOxC,MAAM,eAAe,eAAe;EALlC,GAAK,KAAK,KAAK,cACb;EACF,GAAG,SAAS;EAGuB,CAAC;AAEtC,OAAM,OAAO,MAAM,OAAO,WAAW;AAEnC,MACE,KAAK,SAAS,WACd,UAAU,KAAA,KACV,QAAQ,KACR,QAAQ,SAAS,aAChB,OAAmB,SAAS,MAE7B,QAAO;AAGT,MAAI,KAAK,SAAS,eACf,MAAsB,QAAQ,OAC5B,KAAsB,OACvB,aACD;GAEH;AAEF,QAAO;;;;;;AAOX,SAAS,eAAe,GAA4C;AAClE,QAAO,IAAI,IAAoB;EAC7B,CAAC,EAAE,QAAQ,GAAG,EAAE,OAAO,GAAG,EAAE,SAAS;EACrC,CAAC,EAAE,OAAO,GAAG,EAAE,OAAO,GAAG,EAAE,SAAS;EACpC,CAAC,EAAE,WAAW,GAAG,EAAE,OAAO,GAAG,EAAE,SAAS;EACxC,CAAC,EAAE,YAAY,GAAG,EAAE,OAAO,GAAG,EAAE,SAAS;EACzC,CAAC,EAAE,cAAc,GAAG,EAAE,OAAO,GAAG,EAAE,SAAS;EAC3C,CAAC,EAAE,SAAS,GAAG,EAAE,OAAO,KAAK,EAAE,SAAS;EACzC,CAAC;;;;;;;;;AAUJ,SAAS,OACP,OACA,cACQ;AACR,KAAI,CAAC,MACH,QAAO;CAGT,IAAI,UAAU;AAEd,MAAK,MAAM,MAAM,OAAO;EACtB,MAAM,SAAS,aAAa,IAAI,GAAG;AACnC,aAAW,UAAU;;AAGvB,QAAO"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Delimiters, Nodes, Root } from \"@glion/ast\";\nimport { selectAll } from \"@glion/util-query\";\nimport { visit } from \"@glion/util-visit\";\nimport { DEFAULT_DELIMITERS, encodeEscapes } from \"@glion/utils\";\nimport type { Plugin } from \"unified\";\nimport type { VFile } from \"vfile\";\n\nexport interface HL7v2EncodeOptions {\n  delimiters?: Partial<Delimiters>;\n}\n\n/**\n * Unified plugin to encode special characters as HL7v2 escape sequences in\n * subcomponent literals, for a tree that `@glion/to-hl7v2` writes with\n * `encodeEscapes: false`. MSH-1 and MSH-2 are left as they are.\n *\n * Delimiter resolution order:\n *\n * 1. `options.delimiters` (explicit override)\n * 2. `file.data.delimiters` (set by hl7v2-annotate-delimiters)\n * 3. `DEFAULT_DELIMITERS`\n */\nexport const hl7v2EncodeEscapes: Plugin<[HL7v2EncodeOptions?], Root, Root> =\n  (options) => (tree: Root, file: VFile) => {\n    const d = {\n      ...((file.data.delimiters as Delimiters | undefined) ??\n        DEFAULT_DELIMITERS),\n      ...options?.delimiters,\n    };\n\n    const encodingCharacters = new Set<Nodes>(\n      [...selectAll(tree, \"MSH.1\"), ...selectAll(tree, \"MSH.2\")].map(\n        (match) => match.node\n      )\n    );\n\n    visit(tree, \"subcomponent\", (node, ancestors) => {\n      if (\n        node.value === undefined ||\n        ancestors.some((ancestor) => encodingCharacters.has(ancestor))\n      ) {\n        return;\n      }\n      node.value = encodeEscapes(node.value, d);\n    });\n\n    return tree;\n  };\n"],"mappings":";;;;;;;;;;;;;;;AAsBA,MAAa,sBACV,aAAa,MAAY,SAAgB;CACxC,MAAM,IAAI;EACR,GAAK,KAAK,KAAK,cACb;EACF,GAAG,SAAS;EACb;CAED,MAAM,qBAAqB,IAAI,IAC7B,CAAC,GAAG,UAAU,MAAM,QAAQ,EAAE,GAAG,UAAU,MAAM,QAAQ,CAAC,CAAC,KACxD,UAAU,MAAM,KAClB,CACF;AAED,OAAM,MAAM,iBAAiB,MAAM,cAAc;AAC/C,MACE,KAAK,UAAU,KAAA,KACf,UAAU,MAAM,aAAa,mBAAmB,IAAI,SAAS,CAAC,CAE9D;AAEF,OAAK,QAAQ,cAAc,KAAK,OAAO,EAAE;GACzC;AAEF,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glion/encode-escapes",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "hl7v2 plugin to encode special characters as hl7v2 escape sequences",
   "keywords": [
     "health",
@@ -34,8 +34,9 @@
   },
   "dependencies": {
     "unified": "11.0.5",
-    "unist-util-visit": "5.1.0",
-    "@glion/utils": "0.27.0"
+    "@glion/util-query": "0.28.0",
+    "@glion/util-visit": "0.28.0",
+    "@glion/utils": "0.28.0"
   },
   "devDependencies": {
     "@stryker-mutator/core": "10.0.0",
@@ -48,10 +49,10 @@
     "typescript": "6.0.3",
     "vfile": "^6.0.3",
     "vitest": "4.1.11",
-    "@glion/ast": "0.27.0",
-    "@glion/builder": "0.27.0",
+    "@glion/ast": "0.28.0",
+    "@glion/builder": "0.28.0",
     "@glion/check-readme": "0.18.0",
-    "@glion/decode-escapes": "0.27.0",
+    "@glion/decode-escapes": "0.28.0",
     "@glion/testing": "0.18.0",
     "@glion/tsconfig": "0.18.0"
   },