@glion/annotate-profile-fields-code-systems 0.15.1 → 0.15.3

package/README.md

@@ -0,0 +1,90 @@
+# @glion/annotate-profile-fields-code-systems
+
+Unified plugin to annotate HL7v2 field-level coded values with UTG code system metadata.
+
+## What it does
+
+Fields bound to HL7v2 tables (such as PID-8 `Administrative Sex` bound to table `0001`, or MSH-11.1 `Processing ID` bound to table `0103`) carry coded values that expand into human-readable displays and lifecycle statuses. This plugin resolves each field's table reference against the UTG code system registry in `@glion/profiles`, then writes the code system identity onto the field and the resolved value entry onto each repetition. It requires `@glion/annotate-profile-fields` to run first so that `field.data.table` is populated.
+
+## Install
+
+```bash
+npm install @glion/annotate-profile-fields-code-systems
+```
+
+## Use
+
+```ts
+import { hl7v2AnnotateProfileContext } from "@glion/annotate-profile-context";
+import { hl7v2AnnotateProfileFields } from "@glion/annotate-profile-fields";
+import { hl7v2AnnotateProfileFieldsCodeSystems } from "@glion/annotate-profile-fields-code-systems";
+import { hl7v2Parser } from "@glion/parser";
+import { unified } from "unified";
+
+const processor = unified()
+  .use(hl7v2Parser)
+  .use(hl7v2AnnotateProfileContext)
+  .use(hl7v2AnnotateProfileFields)
+  .use(hl7v2AnnotateProfileFieldsCodeSystems);
+
+const file = await processor.process(
+  "MSH|^~\\&|SENDER||RECEIVER||20241201||ADT^A01|MSG123|P|2.5\rPID|1||12345||Doe^John||19800101|M"
+);
+
+// PID-8 field.data.codeSystem === { id: "v2-0001", name: "AdministrativeSex", title: "Administrative Sex" }
+// PID-8 repetition.data.code   === { value: "M", display: "Male", status: "A" }
+```
+
+## API
+
+This package exports the named constant `hl7v2AnnotateProfileFieldsCodeSystems`. The default export is the plugin itself.
+
+```ts
+import type { Root } from "@glion/ast";
+import type { Plugin } from "unified";
+
+export const hl7v2AnnotateProfileFieldsCodeSystems: Plugin<[], Root, Root>;
+```
+
+The plugin is async. Code system loads run in parallel; failures for unknown code systems are silent, while other errors attach a `VFile` message with source `hl7v2-annotate-profile-fields-code-systems`.
+
+## What it annotates
+
+This plugin visits coded `field` nodes (fields with a table reference on `field.data.table`) and writes two pieces of metadata: a code system identity on the field itself (shared across all repetitions) and a resolved code entry on each repetition. Per the HL7v2 spec, when a coded field uses a composite datatype (CWE or CNE) the table binding constrains CWE.1 — the first subcomponent of the first component — which is the value this plugin reads.
+
+### `node.data` (Field, FieldRepetition)
+
+After this plugin runs, the augmented interfaces are:
+
+```ts
+declare module "@glion/ast" {
+  interface FieldData {
+    // Code system identity for the field's table reference.
+    // Present only when the table resolves in the UTG registry.
+    codeSystem?: {
+      id: string; // e.g. "v2-0001" (derived from "HL70001")
+      name: string; // e.g. "AdministrativeSex"
+      title: string; // e.g. "Administrative Sex"
+    };
+  }
+
+  interface FieldRepetitionData {
+    // Resolved code entry for this repetition's primary value.
+    // Present only when the repetition's CWE.1 value matches a code.
+    code?: {
+      value: string; // as written in the message, e.g. "M"
+      display: string; // e.g. "Male"
+      status: string; // UTG lifecycle status, e.g. "A" (active)
+    };
+  }
+}
+```
+
+Table references are converted from the HL7v2 form (`HL70001`) to the UTG form (`v2-0001`) before lookup. Fields whose table does not resolve in the UTG registry are left untouched, and repetitions whose primary value does not match any code in the registry are left without a `code` entry.
+
+## Part of Glion
+
+`@glion/annotate-profile-fields-code-systems` 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glion/annotate-profile-fields-code-systems",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "Unified plugin to annotate HL7v2 field-level coded values with UTG code system metadata",
   "keywords": [
     "annotate",
@@ -41,21 +41,23 @@
   "dependencies": {
     "unified": "11.0.5",
     "vfile": "6.0.3",
-    "@glion/ast": "0.15.1",
-    "@glion/profiles": "0.15.1",
-    "@glion/util-visit": "0.15.1"
+    "@glion/ast": "0.15.3",
+    "@glion/profiles": "0.15.3",
+    "@glion/util-visit": "0.15.3"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "@vitest/coverage-v8": "4.1.2",
+    "publint": "0.3.18",
     "tsdown": "0.21.7",
     "typescript": "^5.9.3",
     "vitest": "4.1.2",
-    "@glion/annotate-profile-context": "0.15.1",
-    "@glion/annotate-profile-fields": "0.15.1",
-    "@glion/builder": "0.15.1",
-    "@glion/testing": "0.15.1",
-    "@glion/tsconfig": "0.15.1"
+    "@glion/annotate-profile-fields": "0.15.3",
+    "@glion/builder": "0.15.3",
+    "@glion/check-readme": "0.15.3",
+    "@glion/tsconfig": "0.15.3",
+    "@glion/testing": "0.15.3",
+    "@glion/annotate-profile-context": "0.15.3"
   },
   "engines": {
     "node": ">=18"
@@ -64,9 +66,11 @@
   "scripts": {
     "build": "tsdown && tsc --emitDeclarationOnly",
     "check-types": "tsc --noEmit",
+    "check:readme": "glion-check-readme",
     "bench": "vitest bench --run",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "publint": "publint --strict"
   }
 }