@glion/annotate-profile-fields 0.14.1

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,150 @@
+# @glion/annotate-profile-fields
+
+**[unified](https://github.com/unifiedjs/unified)** plugin to annotate HL7v2 field nodes with profile metadata.
+
+## Contents
+
+- [What is this?](#what-is-this)
+- [When should I use this?](#when-should-i-use-this)
+- [Install](#install)
+- [Use](#use)
+- [API](#api)
+- [Examples](#examples)
+- [Compatibility](#compatibility)
+- [Related](#related)
+
+## What is this?
+
+This package is a [unified](https://github.com/unifiedjs/unified) plugin that enriches Field AST nodes with metadata from HL7v2 profile definitions. After running this plugin, each field carries its profile information directly on `field.data` — making the AST self-describing.
+
+The plugin reads the message version from MSH-12, loads the corresponding field definitions from `@glion/profiles`, and spreads the profile properties onto each field node. Unknown segments (Z-segments) and unsupported versions are silently skipped.
+
+## When should I use this?
+
+Use this plugin when:
+
+- You want to inspect a parsed AST and see field names, datatypes, and constraints without loading profiles yourself
+- Building tools (serializers, debuggers, IDE integrations) that need field-level metadata
+- Creating custom processors that need to know which fields are required, repeatable, or coded
+
+## Install
+
+```bash
+npm install @glion/annotate-profile-fields
+```
+
+## Use
+
+```typescript
+import { unified } from "unified";
+import { hl7v2Parser } from "@glion/parser";
+import { hl7v2AnnotateProfileFields } from "@glion/annotate-profile-fields";
+
+const processor = unified().use(hl7v2Parser).use(hl7v2AnnotateProfileFields);
+
+const message =
+  "MSH|^~\\&|SENDER||RECEIVER||20241201||ADT^A01^ADT_A01|MSG123|P|2.5\rPID|1||12345||Doe^John";
+
+const tree = processor.parse(message);
+await processor.run(tree);
+
+// Field nodes now carry profile metadata on field.data
+// e.g., PID-3: { id: "PID-3", name: "Patient Identifier List", required: true, repeatable: true, datatype: "CX", ... }
+```
+
+## API
+
+This package exports the identifier `hl7v2AnnotateProfileFields`. The default export is `hl7v2AnnotateProfileFields`.
+
+### `unified().use(hl7v2AnnotateProfileFields)`
+
+Annotate Field nodes with profile metadata.
+
+This plugin:
+
+1. Reads the HL7v2 version from MSH-12
+2. Loads field definitions for all segments in the message
+3. Visits each Field node and spreads the matching profile properties onto `field.data`
+
+###### Returns
+
+Async transformer (`async function (Root) => Root`)
+
+### Augmented `FieldData`
+
+Importing this package augments the `FieldData` interface from `@glion/ast`:
+
+| Property     | Type      | Description                                          |
+| ------------ | --------- | ---------------------------------------------------- |
+| `id`         | `string`  | Field identifier (e.g., `"MSH-9"`, `"PID-3"`)        |
+| `name`       | `string`  | Human-readable field name (e.g., `"Patient Name"`)   |
+| `required`   | `boolean` | Whether this field is required in the segment        |
+| `repeatable` | `boolean` | Whether this field supports repetition               |
+| `datatype`   | `string`  | Datatype ID (e.g., `"XPN"`, `"ST"`, `"CWE"`)         |
+| `maxLength`  | `number`  | Maximum allowed length (when defined in the profile) |
+| `table`      | `string`  | Table reference for coded fields (e.g., `"HL70001"`) |
+| `item`       | `string`  | HL7 specification item number                        |
+
+All properties are optional (`undefined` when not available in the profile).
+
+## Examples
+
+### Accessing field metadata
+
+```typescript
+import { visit } from "@glion/util-visit";
+
+// After running the annotator...
+visit(tree, "field", (node, ancestors, info) => {
+  if (node.data?.required && node.data?.name) {
+    console.log(`Required field: ${node.data.id} (${node.data.name})`);
+  }
+});
+```
+
+### Finding coded fields
+
+```typescript
+visit(tree, "field", (node) => {
+  if (node.data?.table) {
+    console.log(`${node.data.id} uses table ${node.data.table}`);
+  }
+});
+```
+
+## Compatibility
+
+- **Node.js**: 18+
+- **TypeScript**: 5.0+
+- **unified**: 11.0+
+
+## Related
+
+- [`@glion/annotate-profile-datatypes`](../hl7v2-annotate-profile-datatypes) — Annotate components with datatype metadata
+- [`@glion/annotate-profile-code-systems`](../hl7v2-annotate-profile-code-systems) — Annotate coded values with UTG display names
+- [`@glion/preset-annotate-profile-recommended`](../hl7v2-preset-annotate-profile-recommended) — Preset bundling all profile annotators
+- [`@glion/profiles`](../hl7v2-profiles) — Profile data source
+
+## 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/glion/blob/main/CODE_OF_CONDUCT.md
+[github-license]: https://github.com/rethinkhealth/glion/blob/main/LICENSE
+[github-contributing]: https://github.com/rethinkhealth/glion/blob/main/CONTRIBUTING.md

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import type { Root } from "@glion/ast";
+import type { Plugin } from "unified";
+declare module "@glion/ast" {
+    interface FieldData {
+        /** Field identifier (e.g., "MSH-9", "PID-3"). */
+        id?: string | undefined;
+        /** Human-readable field name from the profile (e.g., "Patient Name"). */
+        name?: string | undefined;
+        /** Whether this field is required in the segment. */
+        required?: boolean | undefined;
+        /** Whether this field supports repetition. */
+        repeatable?: boolean | undefined;
+        /** Datatype ID for this field (e.g., "XPN", "ST", "CWE"). */
+        datatype?: string | undefined;
+        /** Maximum allowed length for this field. */
+        maxLength?: number | undefined;
+        /** Table reference for coded fields (e.g., "HL70001"). */
+        table?: string | undefined;
+        /** HL7 specification item number. */
+        item?: string | undefined;
+    }
+}
+/**
+ * Unified plugin that annotates Field nodes with profile metadata.
+ *
+ * Reads field definitions from `file.data.fields` (populated by
+ * `@glion/annotate-profile-context`) and spreads the profile
+ * properties directly onto each `field.data`.
+ *
+ * Unknown segments (Z-segments) and unsupported versions are silently skipped.
+ */
+export declare const hl7v2AnnotateProfileFields: Plugin<[], Root, Root>;
+export default hl7v2AnnotateProfileFields;
+//# 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":"AAEA,OAAO,KAAK,EAAa,IAAI,EAAW,MAAM,YAAY,CAAC;AAG3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,SAAS;QACjB,iDAAiD;QACjD,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACxB,yEAAyE;QACzE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,qDAAqD;QACrD,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAC/B,8CAA8C;QAC9C,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QACjC,6DAA6D;QAC7D,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC9B,6CAA6C;QAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,0DAA0D;QAC1D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,qCAAqC;QACrC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B;CACF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CA8B3D,CAAC;AAmBJ,eAAe,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,39 @@
+import { SKIP, visit } from "@glion/util-visit";
+//#region src/index.ts
+/**
+* Unified plugin that annotates Field nodes with profile metadata.
+*
+* Reads field definitions from `file.data.fields` (populated by
+* `@glion/annotate-profile-context`) and spreads the profile
+* properties directly onto each `field.data`.
+*
+* Unknown segments (Z-segments) and unsupported versions are silently skipped.
+*/
+const hl7v2AnnotateProfileFields = () => (tree, file) => {
+	const ctx = file.data.profile;
+	if (!ctx) return tree;
+	visit(tree, "field", (node, ancestors, info) => {
+		const segment = ancestors.at(-1);
+		if (segment?.type !== "segment") return SKIP;
+		const profile = ctx.fields.get(segment.name)?.bySequence.get(info.sequence);
+		if (!profile) return SKIP;
+		if (!node.data) node.data = {};
+		spreadFieldProfile(node.data, profile);
+		return SKIP;
+	});
+	return tree;
+};
+function spreadFieldProfile(data, profile) {
+	data.id = profile.id;
+	data.name = profile.name;
+	data.required = profile.required;
+	data.repeatable = profile.repeatable;
+	data.datatype = profile.datatype;
+	if (profile.maxLength !== void 0) data.maxLength = profile.maxLength;
+	if (profile.table !== void 0) data.table = profile.table;
+	if (profile.item !== void 0) data.item = profile.item;
+}
+//#endregion
+export { hl7v2AnnotateProfileFields as default, hl7v2AnnotateProfileFields };
+
+//# 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\";\nimport type { FieldData, Root, Segment } from \"@glion/ast\";\nimport type { FieldProfile } from \"@glion/profiles\";\nimport { SKIP, visit } from \"@glion/util-visit\";\nimport type { Plugin } from \"unified\";\nimport type { VFile } from \"vfile\";\n\ndeclare module \"@glion/ast\" {\n  interface FieldData {\n    /** Field identifier (e.g., \"MSH-9\", \"PID-3\"). */\n    id?: string | undefined;\n    /** Human-readable field name from the profile (e.g., \"Patient Name\"). */\n    name?: string | undefined;\n    /** Whether this field is required in the segment. */\n    required?: boolean | undefined;\n    /** Whether this field supports repetition. */\n    repeatable?: boolean | undefined;\n    /** Datatype ID for this field (e.g., \"XPN\", \"ST\", \"CWE\"). */\n    datatype?: string | undefined;\n    /** Maximum allowed length for this field. */\n    maxLength?: number | undefined;\n    /** Table reference for coded fields (e.g., \"HL70001\"). */\n    table?: string | undefined;\n    /** HL7 specification item number. */\n    item?: string | undefined;\n  }\n}\n\n/**\n * Unified plugin that annotates Field nodes with profile metadata.\n *\n * Reads field definitions from `file.data.fields` (populated by\n * `@glion/annotate-profile-context`) and spreads the profile\n * properties directly onto each `field.data`.\n *\n * Unknown segments (Z-segments) and unsupported versions are silently skipped.\n */\nexport const hl7v2AnnotateProfileFields: Plugin<[], Root, Root> =\n  () => (tree: Root, file: VFile) => {\n    const ctx = file.data.profile;\n    if (!ctx) {\n      return tree;\n    }\n\n    // Annotate each field with its profile\n    visit(tree, \"field\", (node, ancestors, info) => {\n      const segment = ancestors.at(-1) as Segment | undefined;\n      if (segment?.type !== \"segment\") {\n        return SKIP;\n      }\n\n      const profile = ctx.fields\n        .get(segment.name)\n        ?.bySequence.get(info.sequence);\n      if (!profile) {\n        return SKIP;\n      }\n\n      if (!node.data) {\n        node.data = {};\n      }\n\n      spreadFieldProfile(node.data, profile);\n      return SKIP;\n    });\n\n    return tree;\n  };\n\nfunction spreadFieldProfile(data: FieldData, profile: FieldProfile): void {\n  data.id = profile.id;\n  data.name = profile.name;\n  data.required = profile.required;\n  data.repeatable = profile.repeatable;\n  data.datatype = profile.datatype;\n  if (profile.maxLength !== undefined) {\n    data.maxLength = profile.maxLength;\n  }\n  if (profile.table !== undefined) {\n    data.table = profile.table;\n  }\n  if (profile.item !== undefined) {\n    data.item = profile.item;\n  }\n}\n\nexport default hl7v2AnnotateProfileFields;\n"],"mappings":";;;;;;;;;;;AAsCA,MAAa,oCACJ,MAAY,SAAgB;CACjC,MAAM,MAAM,KAAK,KAAK;AACtB,KAAI,CAAC,IACH,QAAO;AAIT,OAAM,MAAM,UAAU,MAAM,WAAW,SAAS;EAC9C,MAAM,UAAU,UAAU,GAAG,GAAG;AAChC,MAAI,SAAS,SAAS,UACpB,QAAO;EAGT,MAAM,UAAU,IAAI,OACjB,IAAI,QAAQ,KAAK,EAChB,WAAW,IAAI,KAAK,SAAS;AACjC,MAAI,CAAC,QACH,QAAO;AAGT,MAAI,CAAC,KAAK,KACR,MAAK,OAAO,EAAE;AAGhB,qBAAmB,KAAK,MAAM,QAAQ;AACtC,SAAO;GACP;AAEF,QAAO;;AAGX,SAAS,mBAAmB,MAAiB,SAA6B;AACxE,MAAK,KAAK,QAAQ;AAClB,MAAK,OAAO,QAAQ;AACpB,MAAK,WAAW,QAAQ;AACxB,MAAK,aAAa,QAAQ;AAC1B,MAAK,WAAW,QAAQ;AACxB,KAAI,QAAQ,cAAc,KAAA,EACxB,MAAK,YAAY,QAAQ;AAE3B,KAAI,QAAQ,UAAU,KAAA,EACpB,MAAK,QAAQ,QAAQ;AAEvB,KAAI,QAAQ,SAAS,KAAA,EACnB,MAAK,OAAO,QAAQ"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@glion/annotate-profile-fields",
+  "version": "0.14.1",
+  "description": "Unified plugin to annotate HL7v2 field nodes with profile metadata",
+  "keywords": [
+    "annotate",
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "plugin",
+    "profile",
+    "typescript",
+    "unified"
+  ],
+  "homepage": "https://glion.dev",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": "rethinkhealth/glion.git",
+  "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/util-visit": "0.14.1",
+    "@glion/ast": "0.14.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "4.1.2",
+    "tsdown": "0.21.7",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.2",
+    "@glion/profiles": "0.14.1",
+    "@glion/testing": "0.0.2",
+    "@glion/annotate-profile-context": "0.14.1",
+    "@glion/builder": "0.14.1",
+    "@glion/tsconfig": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "bench": "vitest bench --run",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}