@healthcare-interoperability/fhir-tools 1.0.0 → 1.2.0

package/README.md

@@ -1,20 +1,27 @@
 # @healthcare-interoperability/fhir-tools
 
-Utilities for working with **FHIR (Fast Healthcare Interoperability Resources)** in JavaScript/Node.js, focused on **safe reference assignment, deterministic ID generation, and schema-aware data shaping**.
+A lightweight but powerful toolkit for **FHIR reference normalization**, **deterministic ID generation**, and **schema-aware traversal** of FHIR resources in JavaScript / Node.js.
 
-This package is designed for **interop pipelines**, **FHIR normalization layers**, and **HL7 → FHIR transformations**, where nested structures and reference integrity matter.
+Designed for **healthcare interoperability pipelines**, **HL7 → FHIR transforms**, and **US Core–aligned processing**.
 
 ---
 
-## ✨ Features
+## ✨ What This Package Solves
 
-* ✅ Assign FHIR references to **deeply nested object paths**
-* ✅ Automatically **creates missing objects and arrays**
-* ✅ Prevents **type conflicts** during assignment
-* ✅ Supports **explicit array declarations** in paths
-* ✅ Generates **deterministic FHIR IDs** using integration context
-* ✅ Produces **clear, path-aware error messages**
-* ✅ Zero runtime dependencies (except ID generator)
+FHIR resources contain many `Reference` fields that:
+
+* appear at different depths
+* can be single or arrays
+* vary by resource type
+* need consistent internal identifiers
+
+This package provides:
+
+* 🔗 **Safe FHIR reference extraction**
+* 🧭 **Config-driven reference traversal**
+* 🆔 **Deterministic, integration-scoped ID generation**
+* 🏗️ **Automatic object & array creation**
+* 🇺🇸 **Built-in US Core reference rules**
 
 ---
 
@@ -26,229 +33,324 @@ npm install @healthcare-interoperability/fhir-tools
 
 ---
 
-## 🔧 Dependencies
+## 🔧 Peer Dependency
 
-This package depends on:
+This package relies on deterministic ID generation:
 
 ```ts
 @quicore/resource-id
 ```
 
-Make sure it is resolvable in your project.
-
 ---
 
-## 🚀 Quick Start
+## 🧠 Core Components
 
-```ts
-import { FHIRReferenceAssigner } from "@healthcare-interoperability/fhir-tools";
+### 1️⃣ `FHIRReferenceAssigner`
 
-const assigner = new FHIRReferenceAssigner("my-integration-id");
+Low-level utility that **assigns a normalized FHIR reference** to a declared object path.
 
-const resource = {};
+* Creates missing objects and arrays
+* Enforces correct types
+* Preserves original FHIR reference
+* Generates deterministic IDs
 
-assigner.assign(
-  resource,
-  ["subject"],
-  "Patient/123"
-);
+📌 Use this when you need **manual or custom reference placement**.
 
-console.log(resource);
-```
+---
 
-### Output
+### 2️⃣ `FHIRReferenceEngine`
 
-```json
-{
-  "subject": {
-    "id": "generated-fhir-id",
-    "type": "Patient",
-    "originalReference": "Patient/123"
-  }
-}
-```
+A **config-driven processor** that:
+
+* Scans a FHIR resource
+* Finds reference fields based on rules
+* Normalizes all references into a single `_reference` tree
+
+📌 Use this for **automated pipeline processing**.
 
 ---
 
-## 🧠 Core Concept
+### 3️⃣ `USCoreFHIRReferenceEngine`
 
-FHIR data structures are often:
+A ready-to-use engine with **US Core–aligned reference rules** for common resources like:
 
-* deeply nested
-* partially populated
-* array-heavy
-* schema-sensitive
+* Encounter
+* Observation
+* Condition
+* Procedure
+* MedicationRequest
+* Claim / Coverage
 
-`FHIRReferenceAssigner` safely **walks a declared path**, creates intermediate structures if needed, validates types, and assigns a **normalized FHIR reference object**.
+📌 Use this if you process **US Core FHIR R4 data**.
 
 ---
 
-## 🏗️ Path Segments Explained
+## 🚀 Quick Start (US Core)
 
-The `pathSegments` argument is an array where each segment describes **how to traverse or create the structure**.
+```ts
+import { USCoreFHIRReferenceEngine } from "@healthcare-interoperability/fhir-tools";
+
+const engine = new USCoreFHIRReferenceEngine("my-integration-id");
 
-| Segment Type | Meaning                                  |
-| ------------ | ---------------------------------------- |
-| `string`     | Object key                               |
-| `number`     | Array index                              |
-| `string[]`   | Explicitly declares an array at that key |
+engine.process(fhirResource);
+
+console.log(fhirResource._reference);
+```
 
 ---
 
-## 📌 Examples
+## 🧾 What Gets Generated
 
-### 1️⃣ Assigning into Nested Objects
+All normalized references are stored under:
 
 ```ts
-assigner.assign(
-  resource,
-  ["encounter", "serviceProvider"],
-  "Organization/456"
-);
+resource._reference
 ```
 
-```json
+Each reference has the shape:
+
+```ts
 {
-  "encounter": {
-    "serviceProvider": {
-      "id": "generated-id",
-      "type": "Organization",
-      "originalReference": "Organization/456"
-    }
-  }
+  id: string;                 // Deterministic internal ID
+  type: string;               // FHIR resource type
+  originalReference: string;  // Original FHIR reference (ResourceType/ID)
 }
 ```
 
+This allows:
+
+* consistent internal linking
+* traceability back to source FHIR
+* safe downstream joins and indexing
+
 ---
 
-### 2️⃣ Assigning into Arrays (Implicit)
+## 🧩 How the Engine Works
+
+### Step 1: Match Rules
+
+Each rule declares:
+
+* `resourceType` (or `"*"`)
+* one or more reference paths
+
+Example:
 
 ```ts
-assigner.assign(
-  resource,
-  ["participant", 0, "individual"],
-  "Practitioner/789"
-);
+{
+  resourceType: "Encounter",
+  references: [
+    { path: ["serviceProvider"] },
+    { path: ["participant"], array: true, nested: "individual" }
+  ]
+}
 ```
 
-Creates `participant` as an array automatically.
+---
+
+### Step 2: Traverse Resource
+
+For each rule:
+
+* the engine checks if the path exists
+* supports arrays automatically
+* supports nested reference fields
 
 ---
 
-### 3️⃣ Explicit Array Declaration
+### Step 3: Normalize References
 
-Use `["key"]` to **force an array**, even if no numeric index is present yet.
+References like:
 
-```ts
-assigner.assign(
-  resource,
-  [["performer"], 0, "actor"],
-  "Practitioner/321"
-);
+```json
+{
+  "reference": "Patient/123"
+}
 ```
 
-This ensures `performer` **must be an array**.
+Are transformed into:
+
+```json
+_reference: {
+  subject: {
+    id: "...",
+    type: "Patient",
+    originalReference: "Patient/123"
+  }
+}
+```
 
 ---
 
-## 🧩 Reference Object Structure
+## 📐 Rule Definition Reference
+
+Each reference rule supports:
+
+| Field    | Type       | Description                  |
+| -------- | ---------- | ---------------------------- |
+| `path`   | `string[]` | Path to the reference field  |
+| `array`  | `boolean`  | Whether the path is an array |
+| `nested` | `string`   | Nested reference key         |
 
-Every assigned reference has the shape:
+### Example (Array + Nested)
 
 ```ts
 {
-  id: string;                // Generated FHIR ID
-  type: string;              // Resource type (Patient, Practitioner, etc.)
-  originalReference: string; // Original FHIR reference (ResourceType/ID)
+  path: ["participant"],
+  array: true,
+  nested: "individual"
 }
 ```
 
-This preserves traceability while enabling internal ID normalization.
+Targets:
+
+```ts
+participant[].individual.reference
+```
 
 ---
 
-## 🔐 Validation & Safety
+## 🇺🇸 US Core Coverage
 
-### ✔ Reference Format Validation
+The built-in `US_CORE_REFERENCE_CONFIG` covers:
 
-Only valid FHIR references are accepted:
+### Common (All Resources)
 
-```
-ResourceType/ID
-```
+* subject
+* patient
+* beneficiary
+* encounter
+* author
+* custodian
+* recorder
+* requester
+* organization
+* provider
 
-Invalid formats throw immediately.
+### Encounter
 
----
+* serviceProvider
+* partOf
+* location[].location
+* participant[].individual
+* diagnosis[].condition
+* reasonReference[]
 
-### ✔ Type Conflict Detection
+### Observation
 
-If an existing path segment conflicts with the expected type:
+* specimen
+* device
+* focus[]
+* hasMember[]
+* derivedFrom[]
+* performer[]
 
-* object vs array
-* array vs object
+### Condition
 
-An error is thrown with **full path context**, e.g.:
+* asserter
+* recorder
+* evidence[].detail
 
-```
-Path segment 'participant' at 'participant[0]' must be an array
-```
+### Procedure
 
----
+* location
+* usedReference[]
+* reasonReference[]
+* report[]
+* performer[].actor
 
-### ✔ Array Bounds Protection
+### MedicationRequest
 
-Array indices are validated to avoid runaway memory usage:
+* medicationReference
+* recorder
+* performer
+* reasonReference[]
+* basedOn[]
 
-```ts
-RangeError: Array index out of bounds
-```
+### DiagnosticReport
+
+* specimen[]
+* result[]
+* imagingStudy[]
+
+### Claim / Coverage
 
-(Max index: `10000`)
+* insurer
+* insurance[].coverage
+* careTeam[].provider
+* diagnosis[].diagnosisReference
+* procedure[].procedureReference
+* beneficiary
+* payor[]
 
 ---
 
-## 🧪 Error Handling
+## 🔐 Error Handling Philosophy
 
-Errors are explicit and actionable:
+* Invalid references are **ignored safely**
+* Structural conflicts are prevented
+* Failures are **logged, not fatal**
+
+```ts
+console.warn(
+  `Reference assign failed Encounter/123 at ["participant",0,"individual"]`
+);
+```
 
-* `TypeError` → structural conflicts
-* `RangeError` → invalid array access
-* `Error` → invalid references or ID generation failures
+This makes the engine safe for:
 
-This makes the class **safe for automated pipelines and AI-driven transformations**.
+* batch processing
+* partial data
+* real-world EHR payloads
 
 ---
 
 ## 🏥 Typical Use Cases
 
-* HL7v2 → FHIR normalization
-* FHIR ingestion pipelines
-* Appointment, Encounter, and Observation consolidation
-* Interop middleware and data harmonization layers
-* Schema-aware AI preprocessing
+* HL7v2 → FHIR pipelines
+* US Core ingestion
+* Appointment & encounter consolidation
+* Claim normalization
+* AI-ready FHIR preprocessing
+* Cross-resource reference indexing
 
 ---
 
-## 📄 API
+## 📄 API Summary
 
-### `new FHIRReferenceAssigner(integrationId: string)`
+### `FHIRReferenceAssigner`
 
-Creates a new assigner scoped to an integration.
+```ts
+new FHIRReferenceAssigner(integrationId)
+assign(baseObject, pathSegments, sourceReference)
+```
 
 ---
 
-### `assign(baseObject, pathSegments, sourceReference)`
+### `FHIRReferenceEngine`
 
-Assigns a normalized FHIR reference to the target path.
+```ts
+new FHIRReferenceEngine(integrationId, config)
+process(resource)
+```
+
+---
+
+### `USCoreFHIRReferenceEngine`
+
+```ts
+new USCoreFHIRReferenceEngine(integrationId)
+```
+
+---
 
-**Parameters**
+## 🧪 Design Goals
 
-| Name              | Type                               | Description                        |
-| ----------------- | ---------------------------------- | ---------------------------------- |
-| `baseObject`      | `Object`                           | Root object to mutate              |
-| `pathSegments`    | `(string \| number \| string[])[]` | Path definition                    |
-| `sourceReference` | `string`                           | FHIR reference (`ResourceType/ID`) |
+* Deterministic
+* Schema-aware
+* Safe-by-default
+* Interop-friendly
+* AI-readable output
 
 ---
 
@@ -260,8 +362,9 @@ MIT
 
 ## 🤝 Contributing
 
-Contributions, issues, and design discussions are welcome—especially around:
+Contributions are welcome—especially for:
 
-* FHIR R4/R5 alignment
-* Schema validation helpers
-* Bulk reference assignment utilities
+* Additional FHIR profiles
+* R5 support
+* Custom profile generators
+* Reference validation helpers

package/dist/FHIRReferenceEngine.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FHIRReferenceEngine = void 0;
+var _FHIRReferenceAssigner = require("./FHIRReferenceAssigner");
+class FHIRReferenceEngine {
+  constructor(integrationId, config) {
+    if (!integrationId) {
+      throw new Error('integrationId is required');
+    }
+    if (!Array.isArray(config)) {
+      throw new Error('Reference config must be an array');
+    }
+    this.integrationId = integrationId;
+    this.config = config;
+    this.assigner = new _FHIRReferenceAssigner.FHIRReferenceAssigner(integrationId);
+  }
+
+  /**
+   * Process a single FHIR resource
+   */
+  process(resource) {
+    if (!resource?.resourceType) return;
+    if (!resource._reference) {
+      resource._reference = {};
+    }
+    const applicableRules = this.config.filter(rule => rule.resourceType === '*' || rule.resourceType === resource.resourceType);
+    applicableRules.forEach(rule => {
+      rule.references.forEach(refRule => {
+        this.applyRule(resource, refRule);
+      });
+    });
+  }
+  applyRule(resource, rule) {
+    const {
+      path,
+      array,
+      nested
+    } = rule;
+    const target = resource?.[path[0]];
+    if (!target) return;
+    if (array && Array.isArray(target)) {
+      target.forEach((item, index) => {
+        const reference = nested ? item?.[nested]?.reference : item?.reference;
+        if (!reference) return;
+        this.safeAssign(resource, [[path[0]], index, ...(nested ? [nested] : [])], reference);
+      });
+    } else {
+      const reference = nested ? target?.[nested]?.reference : target?.reference;
+      if (!reference) return;
+      this.safeAssign(resource, path, reference);
+    }
+  }
+  safeAssign(resource, path, reference) {
+    try {
+      this.assigner.assign(resource._reference, path, reference, this.integrationId);
+    } catch (err) {
+      console.warn(`Reference assign failed ${resource.resourceType}/${resource.id || 'unknown'} at ${JSON.stringify(path)}`);
+    }
+  }
+}
+exports.FHIRReferenceEngine = FHIRReferenceEngine;

package/dist/USCoreFHIRReferenceEngine.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.USCoreFHIRReferenceEngine = void 0;
+var _uscoreReference = require("./config/references/uscore.reference.config");
+var _FHIRReferenceEngine = require("./FHIRReferenceEngine");
+class USCoreFHIRReferenceEngine extends _FHIRReferenceEngine.FHIRReferenceEngine {
+  constructor(integrationId) {
+    super(integrationId, _uscoreReference.US_CORE_REFERENCE_CONFIG);
+  }
+}
+exports.USCoreFHIRReferenceEngine = USCoreFHIRReferenceEngine;

package/dist/config/references/uscore.reference.config.js

@@ -0,0 +1,197 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.US_CORE_REFERENCE_CONFIG = void 0;
+/**
+ * US Core FHIR Reference Configuration
+ *
+ * Each rule declares:
+ * - resourceType (or "*")
+ * - path to reference(s)
+ * - whether the path is an array
+ * - optional nested reference field
+ */
+const US_CORE_REFERENCE_CONFIG = exports.US_CORE_REFERENCE_CONFIG = [
+// ======================================================
+// COMMON (applies to most resources)
+// ======================================================
+{
+  resourceType: '*',
+  references: [{
+    path: ['subject']
+  }, {
+    path: ['patient']
+  }, {
+    path: ['beneficiary']
+  }, {
+    path: ['encounter']
+  }, {
+    path: ['author']
+  }, {
+    path: ['custodian']
+  }, {
+    path: ['recorder']
+  }, {
+    path: ['requester']
+  }, {
+    path: ['organization']
+  }, {
+    path: ['provider']
+  }]
+},
+// ======================================================
+// ENCOUNTER
+// ======================================================
+{
+  resourceType: 'Encounter',
+  references: [{
+    path: ['serviceProvider']
+  }, {
+    path: ['partOf']
+  }, {
+    path: ['location'],
+    array: true,
+    nested: 'location'
+  }, {
+    path: ['participant'],
+    array: true,
+    nested: 'individual'
+  }, {
+    path: ['diagnosis'],
+    array: true,
+    nested: 'condition'
+  }, {
+    path: ['reasonReference'],
+    array: true
+  }]
+},
+// ======================================================
+// OBSERVATION
+// ======================================================
+{
+  resourceType: 'Observation',
+  references: [{
+    path: ['specimen']
+  }, {
+    path: ['device']
+  }, {
+    path: ['focus'],
+    array: true
+  }, {
+    path: ['hasMember'],
+    array: true
+  }, {
+    path: ['derivedFrom'],
+    array: true
+  }, {
+    path: ['performer'],
+    array: true
+  }]
+},
+// ======================================================
+// CONDITION
+// ======================================================
+{
+  resourceType: 'Condition',
+  references: [{
+    path: ['asserter']
+  }, {
+    path: ['recorder']
+  }, {
+    path: ['evidence'],
+    array: true,
+    nested: 'detail'
+  }]
+},
+// ======================================================
+// PROCEDURE
+// ======================================================
+{
+  resourceType: 'Procedure',
+  references: [{
+    path: ['location']
+  }, {
+    path: ['usedReference'],
+    array: true
+  }, {
+    path: ['reasonReference'],
+    array: true
+  }, {
+    path: ['report'],
+    array: true
+  }, {
+    path: ['performer'],
+    array: true,
+    nested: 'actor'
+  }]
+},
+// ======================================================
+// MEDICATION
+// ======================================================
+{
+  resourceType: 'MedicationRequest',
+  references: [{
+    path: ['medicationReference']
+  }, {
+    path: ['recorder']
+  }, {
+    path: ['performer']
+  }, {
+    path: ['reasonReference'],
+    array: true
+  }, {
+    path: ['basedOn'],
+    array: true
+  }]
+},
+// ======================================================
+// DIAGNOSTIC REPORT
+// ======================================================
+{
+  resourceType: 'DiagnosticReport',
+  references: [{
+    path: ['specimen'],
+    array: true
+  }, {
+    path: ['result'],
+    array: true
+  }, {
+    path: ['imagingStudy'],
+    array: true
+  }]
+},
+// ======================================================
+// CLAIM / COVERAGE
+// ======================================================
+{
+  resourceType: 'Claim',
+  references: [{
+    path: ['insurer']
+  }, {
+    path: ['insurance'],
+    array: true,
+    nested: 'coverage'
+  }, {
+    path: ['careTeam'],
+    array: true,
+    nested: 'provider'
+  }, {
+    path: ['diagnosis'],
+    array: true,
+    nested: 'diagnosisReference'
+  }, {
+    path: ['procedure'],
+    array: true,
+    nested: 'procedureReference'
+  }]
+}, {
+  resourceType: 'Coverage',
+  references: [{
+    path: ['beneficiary']
+  }, {
+    path: ['payor'],
+    array: true
+  }]
+}];

package/dist/index.js

@@ -9,4 +9,25 @@ Object.defineProperty(exports, "FHIRReferenceAssigner", {
     return _FHIRReferenceAssigner.FHIRReferenceAssigner;
   }
 });
-var _FHIRReferenceAssigner = require("./FHIRReferenceAssigner");
+Object.defineProperty(exports, "FHIRReferenceEngine", {
+  enumerable: true,
+  get: function () {
+    return _FHIRReferenceEngine.FHIRReferenceEngine;
+  }
+});
+Object.defineProperty(exports, "USCoreFHIRReferenceEngine", {
+  enumerable: true,
+  get: function () {
+    return _USCoreFHIRReferenceEngine.USCoreFHIRReferenceEngine;
+  }
+});
+Object.defineProperty(exports, "US_CORE_REFERENCE_CONFIG", {
+  enumerable: true,
+  get: function () {
+    return _uscoreReference.US_CORE_REFERENCE_CONFIG;
+  }
+});
+var _FHIRReferenceAssigner = require("./FHIRReferenceAssigner");
+var _FHIRReferenceEngine = require("./FHIRReferenceEngine");
+var _USCoreFHIRReferenceEngine = require("./USCoreFHIRReferenceEngine");
+var _uscoreReference = require("./config/references/uscore.reference.config");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcare-interoperability/fhir-tools",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Helper tools for FHIR processing",
   "main": "dist/index.js",
   "scripts": {