@healthcare-interoperability/fhir-tools 1.0.0

package/.babelrc

@@ -0,0 +1,9 @@
+{
+  "presets": [
+    ["@babel/env", {
+      "targets": {
+        "node": "current"
+      }
+    }]
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 quicore
+
+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,267 @@
+# @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**.
+
+This package is designed for **interop pipelines**, **FHIR normalization layers**, and **HL7 → FHIR transformations**, where nested structures and reference integrity matter.
+
+---
+
+## ✨ Features
+
+* ✅ 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)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @healthcare-interoperability/fhir-tools
+```
+
+---
+
+## 🔧 Dependencies
+
+This package depends on:
+
+```ts
+@quicore/resource-id
+```
+
+Make sure it is resolvable in your project.
+
+---
+
+## 🚀 Quick Start
+
+```ts
+import { FHIRReferenceAssigner } from "@healthcare-interoperability/fhir-tools";
+
+const assigner = new FHIRReferenceAssigner("my-integration-id");
+
+const resource = {};
+
+assigner.assign(
+  resource,
+  ["subject"],
+  "Patient/123"
+);
+
+console.log(resource);
+```
+
+### Output
+
+```json
+{
+  "subject": {
+    "id": "generated-fhir-id",
+    "type": "Patient",
+    "originalReference": "Patient/123"
+  }
+}
+```
+
+---
+
+## 🧠 Core Concept
+
+FHIR data structures are often:
+
+* deeply nested
+* partially populated
+* array-heavy
+* schema-sensitive
+
+`FHIRReferenceAssigner` safely **walks a declared path**, creates intermediate structures if needed, validates types, and assigns a **normalized FHIR reference object**.
+
+---
+
+## 🏗️ Path Segments Explained
+
+The `pathSegments` argument is an array where each segment describes **how to traverse or create the structure**.
+
+| Segment Type | Meaning                                  |
+| ------------ | ---------------------------------------- |
+| `string`     | Object key                               |
+| `number`     | Array index                              |
+| `string[]`   | Explicitly declares an array at that key |
+
+---
+
+## 📌 Examples
+
+### 1️⃣ Assigning into Nested Objects
+
+```ts
+assigner.assign(
+  resource,
+  ["encounter", "serviceProvider"],
+  "Organization/456"
+);
+```
+
+```json
+{
+  "encounter": {
+    "serviceProvider": {
+      "id": "generated-id",
+      "type": "Organization",
+      "originalReference": "Organization/456"
+    }
+  }
+}
+```
+
+---
+
+### 2️⃣ Assigning into Arrays (Implicit)
+
+```ts
+assigner.assign(
+  resource,
+  ["participant", 0, "individual"],
+  "Practitioner/789"
+);
+```
+
+Creates `participant` as an array automatically.
+
+---
+
+### 3️⃣ Explicit Array Declaration
+
+Use `["key"]` to **force an array**, even if no numeric index is present yet.
+
+```ts
+assigner.assign(
+  resource,
+  [["performer"], 0, "actor"],
+  "Practitioner/321"
+);
+```
+
+This ensures `performer` **must be an array**.
+
+---
+
+## 🧩 Reference Object Structure
+
+Every assigned reference has the shape:
+
+```ts
+{
+  id: string;                // Generated FHIR ID
+  type: string;              // Resource type (Patient, Practitioner, etc.)
+  originalReference: string; // Original FHIR reference (ResourceType/ID)
+}
+```
+
+This preserves traceability while enabling internal ID normalization.
+
+---
+
+## 🔐 Validation & Safety
+
+### ✔ Reference Format Validation
+
+Only valid FHIR references are accepted:
+
+```
+ResourceType/ID
+```
+
+Invalid formats throw immediately.
+
+---
+
+### ✔ Type Conflict Detection
+
+If an existing path segment conflicts with the expected type:
+
+* object vs array
+* array vs object
+
+An error is thrown with **full path context**, e.g.:
+
+```
+Path segment 'participant' at 'participant[0]' must be an array
+```
+
+---
+
+### ✔ Array Bounds Protection
+
+Array indices are validated to avoid runaway memory usage:
+
+```ts
+RangeError: Array index out of bounds
+```
+
+(Max index: `10000`)
+
+---
+
+## 🧪 Error Handling
+
+Errors are explicit and actionable:
+
+* `TypeError` → structural conflicts
+* `RangeError` → invalid array access
+* `Error` → invalid references or ID generation failures
+
+This makes the class **safe for automated pipelines and AI-driven transformations**.
+
+---
+
+## 🏥 Typical Use Cases
+
+* HL7v2 → FHIR normalization
+* FHIR ingestion pipelines
+* Appointment, Encounter, and Observation consolidation
+* Interop middleware and data harmonization layers
+* Schema-aware AI preprocessing
+
+---
+
+## 📄 API
+
+### `new FHIRReferenceAssigner(integrationId: string)`
+
+Creates a new assigner scoped to an integration.
+
+---
+
+### `assign(baseObject, pathSegments, sourceReference)`
+
+Assigns a normalized FHIR reference to the target path.
+
+**Parameters**
+
+| Name              | Type                               | Description                        |
+| ----------------- | ---------------------------------- | ---------------------------------- |
+| `baseObject`      | `Object`                           | Root object to mutate              |
+| `pathSegments`    | `(string \| number \| string[])[]` | Path definition                    |
+| `sourceReference` | `string`                           | FHIR reference (`ResourceType/ID`) |
+
+---
+
+## 📜 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+Contributions, issues, and design discussions are welcome—especially around:
+
+* FHIR R4/R5 alignment
+* Schema validation helpers
+* Bulk reference assignment utilities

package/dist/FHIRReferenceAssigner.js

@@ -0,0 +1,132 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FHIRReferenceAssigner = void 0;
+var _resourceId = require("@quicore/resource-id");
+/**
+ * FHIRReferenceAssigner
+ *
+ * This class provides utilities for assigning FHIR (Fast Healthcare Interoperability Resources)
+ * reference IDs to nested object paths within healthcare data records.
+ */
+class FHIRReferenceAssigner {
+  /**
+   * Creates a new FHIRReferenceAssigner
+   * 
+   * @param {string} integrationId - Integration ID used in FHIRID generation
+   */
+  constructor(integrationId) {
+    if (!integrationId || typeof integrationId !== 'string') {
+      throw new TypeError("integrationId must be a non-empty string");
+    }
+    this.integrationId = integrationId;
+  }
+
+  /**
+   * Assigns a FHIR reference to a nested object path.
+   * 
+   * This method provides robust handling of nested paths, including:
+   * - Creating intermediate objects and arrays as needed
+   * - Validating existing field types to prevent conflicts
+   * - Supporting explicit array declarations via wrapped syntax
+   * - Comprehensive error reporting with full path context
+   * 
+   * @param {Object} baseObject - The root object to modify
+   * @param {Array<string | number | string[]>} pathSegments - Array of path segments:
+   *   - string: object key
+   *   - number: array index
+   *   - string[]: declares array at given key
+   * @param {string} sourceReference - FHIR reference string (e.g., "Patient/123")
+   * 
+   * @throws {TypeError} If existing values conflict with required types
+   * @throws {RangeError} If array index is invalid
+   * @throws {Error} If sourceReference is invalid or FHIR ID generation fails
+   */
+  assign(baseObject, pathSegments, sourceReference) {
+    if (!sourceReference) return;
+    if (!FHIRReferenceAssigner.isValidFHIRReference(sourceReference)) {
+      throw new Error(`Invalid FHIR reference format: "${sourceReference}". Expected format: "ResourceType/ID"`);
+    }
+    let current = baseObject;
+    const totalSegments = pathSegments.length;
+    for (let i = 0; i < totalSegments - 1; i++) {
+      const segment = pathSegments[i];
+      const nextSegment = pathSegments[i + 1];
+      const currentPath = FHIRReferenceAssigner.buildPathString(pathSegments, i + 1);
+      let actualSegment = Array.isArray(segment) ? segment[0] : segment;
+      const isArray = Array.isArray(segment) || typeof nextSegment === 'number';
+      if (current[actualSegment] == null) {
+        current[actualSegment] = isArray ? [] : {};
+      } else {
+        const actualType = typeof current[actualSegment];
+        if (isArray && !Array.isArray(current[actualSegment])) {
+          throw new TypeError(`Path segment '${actualSegment}' at '${currentPath}' must be an array`);
+        }
+        if (!isArray && (actualType !== 'object' || Array.isArray(current[actualSegment]))) {
+          throw new TypeError(`Path segment '${actualSegment}' at '${currentPath}' must be an object`);
+        }
+      }
+      if (typeof nextSegment === 'number') {
+        if (nextSegment < 0 || nextSegment > 10000) {
+          throw new RangeError(`Array index out of bounds at '${currentPath}': ${nextSegment}`);
+        }
+        FHIRReferenceAssigner.ensureArrayLength(current[actualSegment], nextSegment);
+      }
+      current = current[actualSegment];
+    }
+    const finalSegment = Array.isArray(pathSegments[totalSegments - 1]) ? pathSegments[totalSegments - 1][0] : pathSegments[totalSegments - 1];
+    const [resourceType, sourceId] = sourceReference.split('/');
+    try {
+      const idGen = new _resourceId.FHIRIDGenerator({
+        id: sourceId,
+        resourceType
+      }).setIntegrationId(this.integrationId);
+      current[finalSegment] = {
+        id: idGen.generate(),
+        type: resourceType,
+        originalReference: sourceReference
+      };
+    } catch (err) {
+      throw new Error(`Failed to generate FHIR ID for reference '${sourceReference}': ${err.message}`);
+    }
+  }
+
+  /**
+   * Validates that a reference string follows the FHIR reference format (ResourceType/ID)
+   * 
+   * @param {string} reference - The reference string to validate
+   * @returns {boolean} True if valid, false otherwise
+   * @private
+   */
+  static isValidFHIRReference(reference) {
+    if (!reference || typeof reference !== 'string') return false;
+    const parts = reference.split('/');
+    return parts.length === 2 && parts[0] && parts[1];
+  }
+
+  /**
+   * Builds a human-readable path string from path segments
+   * 
+   * @param {Array<string | number | string[]>} segments - Path segments
+   * @param {number} upTo - Index up to which path should be built
+   * @returns {string} Path string
+   * @private
+   */
+  static buildPathString(segments, upTo = segments.length) {
+    return segments.slice(0, upTo).map(seg => Array.isArray(seg) ? `[${seg[0]}]` : typeof seg === 'number' ? `[${seg}]` : seg).join('.');
+  }
+
+  /**
+   * Ensures an array has at least requiredIndex+1 elements
+   * 
+   * @param {Array} arr - The array to extend
+   * @param {number} requiredIndex - Index that must be valid
+   * @private
+   */
+  static ensureArrayLength(arr, requiredIndex) {
+    while (arr.length <= requiredIndex) arr.push({});
+  }
+}
+exports.FHIRReferenceAssigner = FHIRReferenceAssigner;

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "FHIRReferenceAssigner", {
+  enumerable: true,
+  get: function () {
+    return _FHIRReferenceAssigner.FHIRReferenceAssigner;
+  }
+});
+var _FHIRReferenceAssigner = require("./FHIRReferenceAssigner");

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@healthcare-interoperability/fhir-tools",
+  "version": "1.0.0",
+  "description": "Helper tools for FHIR processing",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "babel src -d dist"
+  },
+  "keywords": [
+    "fhir",
+    "healthcare",
+    "quicore"
+  ],
+  "author": "quicore",
+  "license": "MIT",
+  "dependencies": {
+    "@quicore/resource-id": "^1.0.0"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.27.0",
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}