@glion/annotate-profile-tables 0.0.0-stage → 0.25.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

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# @glion/annotate-profile-tables
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unified plugin to annotate HL7v2 primitive values with their entry in the table of the message's version.
+
+## What it does
+
+A primitive value bound to an HL7v2 table, such as PID-8 `Administrative Sex` (IS, table `0001`) in v2.5 or XPN.7 `Name Type Code` (ID, table `0200`), is a code that the table describes. This plugin looks up each such value in its table, as printed in the HL7v2 version the message declares in MSH-12, and writes the matching entry onto the node that holds the value: a field repetition, a component, or a subcomponent. A code the message's version does not define is left unannotated, even when a later version defines it. A code the table prints only as part of a range, such as `E1 ... E9` in table 0141, is left unannotated too. For a user-defined table, the description is the one HL7 suggests.
+
+Composite values, such as a CWE field, are not annotated.
+
+## Install
+
+```bash
+npm install @glion/annotate-profile-tables
+```
+
+## Use
+
+```ts
+import { hl7v2AnnotateProfileContext } from "@glion/annotate-profile-context";
+import { hl7v2AnnotateProfileDatatypes } from "@glion/annotate-profile-datatypes";
+import { hl7v2AnnotateProfileFields } from "@glion/annotate-profile-fields";
+import { hl7v2AnnotateProfileTables } from "@glion/annotate-profile-tables";
+import { hl7v2Parser } from "@glion/parser";
+import { unified } from "unified";
+import { VFile } from "vfile";
+
+const processor = unified()
+  .use(hl7v2Parser)
+  .use(hl7v2AnnotateProfileContext)
+  .use(hl7v2AnnotateProfileFields)
+  .use(hl7v2AnnotateProfileDatatypes)
+  .use(hl7v2AnnotateProfileTables);
+
+const file = new VFile(
+  "MSH|^~\\&|SENDER||RECEIVER||20241201||ADT^A01|MSG123|P|2.5\rPID|1||12345||Doe^John||19800101|M"
+);
+const tree = await processor.run(processor.parse(file), file);
+
+// PID-8 field-repetition data.tableValue === { value: "M", description: "Male" }
+```
+
+## API
+
+This package exports the named constant `hl7v2AnnotateProfileTables` and the type `TableValue`. The default export is the plugin itself.
+
+```ts
+import type { Root } from "@glion/ast";
+import type { Plugin } from "unified";
+
+export interface TableValue {
+  value: string;
+  description: string;
+}
+export const hl7v2AnnotateProfileTables: Plugin<[], Root, Root>;
+```
+
+The plugin reads `kind` and `table` from `node.data`, set by `@glion/annotate-profile-datatypes`, and the tables in `file.data.profile`, set by `@glion/annotate-profile-context`. Both must run first. Without `file.data.profile`, the tree is returned unchanged.
+
+## What it annotates
+
+The plugin visits every field repetition, component, and subcomponent whose `data.kind` is `"primitive"` and whose `data.table` is set. The value is the node's first subcomponent; components a primitive datatype does not define are ignored. For example:
+
+- PID-8 in v2.5 (IS): the field repetition.
+- PID-5 in v2.6 (XPN): XPN.6, XPN.7, XPN.8, and XPN.11.
+- LDP-10 (VH): VH.1 and VH.2.
+- XCN.9 (HD) in PV1-7: the subcomponent HD.3.
+
+### `node.data` (FieldRepetition, Component, Subcomponent)
+
+```ts
+declare module "@glion/ast" {
+  interface FieldRepetitionData {
+    tableValue?: TableValue;
+  }
+  interface ComponentData {
+    tableValue?: TableValue;
+  }
+  interface SubcomponentData {
+    tableValue?: TableValue;
+  }
+}
+
+// The entry of the node's table that its value matches.
+// Absent when the value is empty or not in the table.
+interface TableValue {
+  value: string; // as written in the message, e.g. "M"
+  description: string; // from the table, e.g. "Male"
+}
+```
+
+## Part of Glion
+
+`@glion/annotate-profile-tables` is part of **[Glion]**, the application framework for HL7v2. See the [Glion README] for the full package catalog and architecture.
+
+[Glion]: https://github.com/rethinkhealth/glion#readme
+[Glion README]: https://github.com/rethinkhealth/glion#readme

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import type { Root } from "@glion/ast";
+import type { Plugin } from "unified";
+/**
+ * An entry of an HL7v2 table that a primitive value matches.
+ *
+ * @example
+ *   ```ts
+ *   // PID-8 `F` in a v2.5 message, table 0001 (Administrative Sex)
+ *   const entry: TableValue = { value: "F", description: "Female" };
+ *   ```
+ */
+export interface TableValue {
+    /** The value as written in the message, such as `"F"`. */
+    value: string;
+    /** The description the table prints for the value, such as `"Female"`. */
+    description: string;
+}
+declare module "@glion/ast" {
+    interface FieldRepetitionData {
+        /** The entry of `table` this repetition's value matches. */
+        tableValue?: TableValue | undefined;
+    }
+    interface ComponentData {
+        /** The entry of `table` this component's value matches. */
+        tableValue?: TableValue | undefined;
+    }
+    interface SubcomponentData {
+        /** The entry of `table` this subcomponent's value matches. */
+        tableValue?: TableValue | undefined;
+    }
+}
+/**
+ * Unified plugin that annotates each primitive node with a table (a field
+ * repetition, component, or subcomponent whose `data.kind` is `"primitive"`
+ * and whose `data.table` is set) with the entry of that table its value
+ * matches, as `node.data.tableValue`.
+ *
+ * Reads `kind` and `table` from `node.data`, set by
+ * `@glion/annotate-profile-datatypes`, and the tables of the message's HL7v2
+ * version from `file.data.profile`, set by `@glion/annotate-profile-context`.
+ * Both MUST run before it; without `file.data.profile` the tree is returned
+ * unchanged.
+ *
+ * Composite nodes are not annotated. A node whose value is empty or not in its
+ * table has no `tableValue`. Idempotent.
+ *
+ * @example
+ *   ```ts
+ *   unified()
+ *   .use(hl7v2AnnotateProfileContext)
+ *   .use(hl7v2AnnotateProfileFields)
+ *   .use(hl7v2AnnotateProfileDatatypes)
+ *   .use(hl7v2AnnotateProfileTables);
+ *   // v2.5 `PID|1||12345||Doe||19800101|M`:
+ *   // the PID-8 field repetition gets
+ *   // data.tableValue = { value: "M", description: "Male" }
+ *   ```
+ */
+export declare const hl7v2AnnotateProfileTables: Plugin<[], Root, Root>;
+export default hl7v2AnnotateProfileTables;
+//# 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":"AAIA,OAAO,KAAK,EAKV,IAAI,EAGL,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,mBAAmB;QAC3B,4DAA4D;QAC5D,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;KACrC;IACD,UAAU,aAAa;QACrB,2DAA2D;QAC3D,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;KACrC;IACD,UAAU,gBAAgB;QACxB,8DAA8D;QAC9D,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;KACrC;CACF;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CA+B3D,CAAC;AAEJ,eAAe,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,62 @@
+import { visit } from "@glion/util-visit";
+//#region src/index.ts
+/**
+* The value of a primitive node: its first subcomponent, or `undefined` when
+* the node has none.
+*
+* Components and subcomponents a primitive datatype does not define are
+* ignored, as HL7v2 tells the recipient to ignore "components, subcomponents,
+* and extra repetitions of a field that are present but were not expected"
+* (v2.5.1 chapter 2, section 2.6.2).
+*/
+function primitiveValue(node) {
+	switch (node.type) {
+		case "field-repetition": return node.children[0]?.children[0]?.value;
+		case "component": return node.children[0]?.value;
+		case "subcomponent": return node.value;
+	}
+}
+/**
+* Unified plugin that annotates each primitive node with a table (a field
+* repetition, component, or subcomponent whose `data.kind` is `"primitive"`
+* and whose `data.table` is set) with the entry of that table its value
+* matches, as `node.data.tableValue`.
+*
+* Reads `kind` and `table` from `node.data`, set by
+* `@glion/annotate-profile-datatypes`, and the tables of the message's HL7v2
+* version from `file.data.profile`, set by `@glion/annotate-profile-context`.
+* Both MUST run before it; without `file.data.profile` the tree is returned
+* unchanged.
+*
+* Composite nodes are not annotated. A node whose value is empty or not in its
+* table has no `tableValue`. Idempotent.
+*
+* @example
+*   ```ts
+*   unified()
+*   .use(hl7v2AnnotateProfileContext)
+*   .use(hl7v2AnnotateProfileFields)
+*   .use(hl7v2AnnotateProfileDatatypes)
+*   .use(hl7v2AnnotateProfileTables);
+*   // v2.5 `PID|1||12345||Doe||19800101|M`:
+*   // the PID-8 field repetition gets
+*   // data.tableValue = { value: "M", description: "Male" }
+*   ```
+*/
+const hl7v2AnnotateProfileTables = () => (tree, file) => {
+	const tables = file.data.profile?.tables;
+	if (!tables) return tree;
+	visit(tree, (node) => (node.type === "field-repetition" || node.type === "component" || node.type === "subcomponent") && node.data?.kind === "primitive" && node.data.table !== void 0, (node) => {
+		const value = primitiveValue(node);
+		const entry = value ? tables.get(node.data.table)?.codes.get(value) : void 0;
+		if (value && entry) node.data.tableValue = {
+			description: entry.description,
+			value
+		};
+	});
+	return tree;
+};
+//#endregion
+export { hl7v2AnnotateProfileTables as default, hl7v2AnnotateProfileTables };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// oxlint-disable-next-line no-unused-vars -- triggers VFile DataMap augmentation\nimport type { ProfileContext } from \"@glion/annotate-profile-context\";\n// oxlint-disable-next-line no-unused-vars -- triggers FieldRepetitionData, ComponentData and SubcomponentData augmentation\nimport type { hl7v2AnnotateProfileDatatypes } from \"@glion/annotate-profile-datatypes\";\nimport type {\n  Component,\n  ComponentData,\n  FieldRepetition,\n  FieldRepetitionData,\n  Root,\n  Subcomponent,\n  SubcomponentData,\n} from \"@glion/ast\";\nimport { visit } from \"@glion/util-visit\";\nimport type { Plugin } from \"unified\";\nimport type { VFile } from \"vfile\";\n\n/**\n * An entry of an HL7v2 table that a primitive value matches.\n *\n * @example\n *   ```ts\n *   // PID-8 `F` in a v2.5 message, table 0001 (Administrative Sex)\n *   const entry: TableValue = { value: \"F\", description: \"Female\" };\n *   ```\n */\nexport interface TableValue {\n  /** The value as written in the message, such as `\"F\"`. */\n  value: string;\n  /** The description the table prints for the value, such as `\"Female\"`. */\n  description: string;\n}\n\ndeclare module \"@glion/ast\" {\n  interface FieldRepetitionData {\n    /** The entry of `table` this repetition's value matches. */\n    tableValue?: TableValue | undefined;\n  }\n  interface ComponentData {\n    /** The entry of `table` this component's value matches. */\n    tableValue?: TableValue | undefined;\n  }\n  interface SubcomponentData {\n    /** The entry of `table` this subcomponent's value matches. */\n    tableValue?: TableValue | undefined;\n  }\n}\n\n/**\n * A primitive field repetition, component, or subcomponent bound to a table:\n * its `data.kind` is `\"primitive\"` and its `data.table` is set.\n */\ntype CodedPrimitive = (FieldRepetition | Component | Subcomponent) & {\n  data: (FieldRepetitionData | ComponentData | SubcomponentData) & {\n    table: string;\n  };\n};\n\n/**\n * The value of a primitive node: its first subcomponent, or `undefined` when\n * the node has none.\n *\n * Components and subcomponents a primitive datatype does not define are\n * ignored, as HL7v2 tells the recipient to ignore \"components, subcomponents,\n * and extra repetitions of a field that are present but were not expected\"\n * (v2.5.1 chapter 2, section 2.6.2).\n */\nfunction primitiveValue(\n  node: FieldRepetition | Component | Subcomponent\n): string | undefined {\n  switch (node.type) {\n    case \"field-repetition\": {\n      // A primitive field, such as v2.5 PID-8 (IS): `F^Female` → `F`\n      return node.children[0]?.children[0]?.value;\n    }\n    case \"component\": {\n      // A primitive component, such as XPN.7 (ID): `M`\n      return node.children[0]?.value;\n    }\n    case \"subcomponent\": {\n      // A primitive subcomponent, such as HD.3 (ID) inside XCN.9\n      return node.value;\n    }\n  }\n}\n\n/**\n * Unified plugin that annotates each primitive node with a table (a field\n * repetition, component, or subcomponent whose `data.kind` is `\"primitive\"`\n * and whose `data.table` is set) with the entry of that table its value\n * matches, as `node.data.tableValue`.\n *\n * Reads `kind` and `table` from `node.data`, set by\n * `@glion/annotate-profile-datatypes`, and the tables of the message's HL7v2\n * version from `file.data.profile`, set by `@glion/annotate-profile-context`.\n * Both MUST run before it; without `file.data.profile` the tree is returned\n * unchanged.\n *\n * Composite nodes are not annotated. A node whose value is empty or not in its\n * table has no `tableValue`. Idempotent.\n *\n * @example\n *   ```ts\n *   unified()\n *   .use(hl7v2AnnotateProfileContext)\n *   .use(hl7v2AnnotateProfileFields)\n *   .use(hl7v2AnnotateProfileDatatypes)\n *   .use(hl7v2AnnotateProfileTables);\n *   // v2.5 `PID|1||12345||Doe||19800101|M`:\n *   // the PID-8 field repetition gets\n *   // data.tableValue = { value: \"M\", description: \"Male\" }\n *   ```\n */\nexport const hl7v2AnnotateProfileTables: Plugin<[], Root, Root> =\n  () => (tree: Root, file: VFile) => {\n    const tables = file.data.profile?.tables;\n    if (!tables) {\n      return tree;\n    }\n\n    visit(\n      tree,\n      // Test: which nodes are visited. Primitive field repetitions,\n      // components, and subcomponents bound to a table.\n      (node): node is CodedPrimitive =>\n        (node.type === \"field-repetition\" ||\n          node.type === \"component\" ||\n          node.type === \"subcomponent\") &&\n        node.data?.kind === \"primitive\" &&\n        node.data.table !== undefined,\n      // Visitor: what happens to each. Look the value up in the node's table\n      // and, on a match, write the entry to `data.tableValue`.\n      (node) => {\n        const value = primitiveValue(node);\n        const entry = value\n          ? tables.get(node.data.table)?.codes.get(value)\n          : undefined;\n        if (value && entry) {\n          node.data.tableValue = { description: entry.description, value };\n        }\n      }\n    );\n\n    return tree;\n  };\n\nexport default hl7v2AnnotateProfileTables;\n"],"mappings":";;;;;;;;;;;AAmEA,SAAS,eACP,MACoB;AACpB,SAAQ,KAAK,MAAb;EACE,KAAK,mBAEH,QAAO,KAAK,SAAS,IAAI,SAAS,IAAI;EAExC,KAAK,YAEH,QAAO,KAAK,SAAS,IAAI;EAE3B,KAAK,eAEH,QAAO,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgClB,MAAa,oCACJ,MAAY,SAAgB;CACjC,MAAM,SAAS,KAAK,KAAK,SAAS;AAClC,KAAI,CAAC,OACH,QAAO;AAGT,OACE,OAGC,UACE,KAAK,SAAS,sBACb,KAAK,SAAS,eACd,KAAK,SAAS,mBAChB,KAAK,MAAM,SAAS,eACpB,KAAK,KAAK,UAAU,KAAA,IAGrB,SAAS;EACR,MAAM,QAAQ,eAAe,KAAK;EAClC,MAAM,QAAQ,QACV,OAAO,IAAI,KAAK,KAAK,MAAM,EAAE,MAAM,IAAI,MAAM,GAC7C,KAAA;AACJ,MAAI,SAAS,MACX,MAAK,KAAK,aAAa;GAAE,aAAa,MAAM;GAAa;GAAO;GAGrE;AAED,QAAO"}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@glion/annotate-profile-tables",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.25.0",
+  "description": "Unified plugin to annotate HL7v2 primitive values with their entry in the table of the message version",
+  "keywords": [
+    "annotate",
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "plugin",
+    "profile",
+    "table",
+    "typescript",
+    "unified"
+  ],
+  "homepage": "https://glion.dev",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rethinkhealth/glion.git",
+    "directory": "packages/annotate-profile-tables"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "unified": "11.0.5",
+    "vfile": "6.0.3",
+    "@glion/annotate-profile-context": "0.25.0",
+    "@glion/ast": "0.25.0",
+    "@glion/annotate-profile-datatypes": "0.25.0",
+    "@glion/util-visit": "0.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "publint": "0.3.18",
+    "tsdown": "0.21.10",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11",
+    "@glion/builder": "0.25.0",
+    "@glion/annotate-profile-fields": "0.25.0",
+    "@glion/check-readme": "0.18.0",
+    "@glion/parser": "0.25.0",
+    "@glion/testing": "0.18.0",
+    "@glion/tsconfig": "0.18.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "check:readme": "glion-check-readme",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "publint": "publint --strict"
+  }
 }