@quicore/task-queue-fhir-tools 1.1.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,118 @@
+# @quicore/task-queue-fhir-tools
+
+A specialized library for generating MongoDB update queries from FHIR resources. It extends the standard FHIR-to-Mongo mapping with support for **deterministic IDs**, **multi-tenant data segregation (Customer IDs)**, and **Task ID association**.
+
+## Features
+
+* **Deterministic ID Generation**: Creates consistent MongoDB `_id` values based on resource content and integration context.
+* **Multi-Tenancy**: Support for tagging resources with `customerId` and optionally segregating data into customer-specific records.
+* **Task Association**: Automatically links FHIR resources to specific Task IDs for workflow tracking.
+* **Bulk Processing**: Efficiently process entire FHIR Bundles into categorized MongoDB `bulkWrite` operations.
+* **Chainable API**: Fluid interface for setting metadata and configuration.
+
+---
+
+## Installation
+
+```bash
+npm install @quicore/task-queue-fhir-tools
+```
+
+---
+
+## Usage
+
+### 1. Processing a Single Resource
+
+Use `TaskFHIRQuery` to generate an update query for an individual FHIR resource.
+
+```javascript
+import { TaskFHIRQuery } from '@quicore/task-queue-fhir-tools';
+
+const patientResource = {
+    resourceType: "Patient",
+    id: "123",
+    name: [{ family: "Doe", given: ["John"] }]
+};
+
+const queryGenerator = new TaskFHIRQuery(patientResource)
+    .setIntegrationId("my-integration-01")
+    .setCustomerId("cust_99")
+    .setTaskId("task_abc_123");
+
+const mongoQueries = queryGenerator.query();
+// Returns an array of updateOne operations
+
+```
+
+### 2. Processing a FHIR Bundle
+
+Use `TaskFHIRBundleProcessor` to process a bundle and group queries by `resourceType` for efficient database writes.
+
+```javascript
+import { TaskFHIRBundleProcessor } from '@quicore/task-queue-fhir-tools';
+
+const bundle = {
+    resourceType: "Bundle",
+    entry: [ /* ... FHIR resources ... */ ]
+};
+
+const processor = new TaskFHIRBundleProcessor(bundle)
+    .setCustomerId(["cust_A", "cust_B"])
+    .setTaskId("workflow_456")
+    .customerSpecificDataStore(true); // Generates separate records for each customer
+
+const queriesByType = processor.query();
+
+/* Output format:
+{
+  "Patient": [ { updateOne: { ... } }, ... ],
+  "Observation": [ { updateOne: { ... } }, ... ]
+}
+*/
+
+```
+
+---
+
+## Key Concepts
+
+### Customer Specific Data Storage
+
+By default, the processor adds customer IDs to an array (`_sourceCustomerId`) within a single shared record. If you call `.customerSpecificDataStore(true)`, the library will:
+
+1. Generate a unique record for **each** customer ID provided.
+2. Append the customer ID to the canonical string used for hashing the `_id`.
+3. Set a flag `_customerSpecificStore: true` in the document.
+
+### Canonical String Construction
+
+The deterministic `_id` is derived from a canonical string. If customer segregation is enabled, the format is:
+`{integrationId}::{resourceType}::{resourceId}::{customerId}`
+
+---
+
+## API Reference
+
+### `TaskFHIRQuery`
+
+| Method | Description |
+| --- | --- |
+| `setTaskId(string)` | Associates the resource with a specific Task ID. |
+| `setCustomerId(string \| string[])` | Adds one or more customer identifiers. |
+| `customerSpecificDataStore(boolean)` | If true, creates unique records per customer. |
+| `query(upsert = true)` | Finalizes and returns the MongoDB update array. |
+
+### `TaskFHIRBundleProcessor`
+
+| Method | Description |
+| --- | --- |
+| `setCustomerId(string \| string[])` | Sets the source customer(s) for all resources in the bundle. |
+| `setTaskId(string)` | Sets the task ID for all resources in the bundle. |
+| `query()` | Returns an object containing arrays of queries keyed by resource type. |
+
+---
+
+## License
+
+MIT © quicore

package/dist/TaskFHIRBundleProcessor.js

@@ -0,0 +1,90 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TaskFHIRBundleProcessor = void 0;
+var _fhirQueryMongoStore = require("@healthcare-interoperability/fhir-query-mongo-store");
+var _TaskFHIRQuery = require("./TaskFHIRQuery");
+class TaskFHIRBundleProcessor extends _fhirQueryMongoStore.FHIRMongoBundleProcessor {
+  /**
+   * A flag indicating whether to store data specific to each customer ID.
+   * @private
+   * @type {boolean}
+   */
+  customerSpecificData = false;
+
+  /**
+   * The customer ID(s) associated with the resources in the bundle.
+   * @private
+   * @type {string | string[] | undefined}
+   */
+  sourceCustomerId;
+
+  /**
+   * The task ID associated with the resources in the bundle.
+   * @private
+   * @type {string | undefined}
+   */
+  taskId;
+
+  /**
+   * Creates an instance of TaskFHIRBundleProcessor.
+   * @param {object} bundle - The FHIR Bundle resource.
+   */
+  constructor(bundle) {
+    super(bundle);
+    this.customerSpecificData = false;
+  }
+
+  /**
+   * Enables or disables customer-specific data storage for the bundle.
+   * @param {boolean} [enable=true] - Whether to enable customer-specific data storage.
+   * @returns {this} The FHIRBundleProcessor instance for chaining.
+   */
+  customerSpecificDataStore(enable = true) {
+    this.customerSpecificData = enable;
+    return this;
+  }
+
+  /**
+   * Sets the customer ID(s) associated with the resources in the bundle.
+   * @param {string | string[]} sourceCustomerId - The customer ID(s).
+   * @returns {this} The FHIRBundleProcessor instance for chaining.
+   */
+  setCustomerId(sourceCustomerId) {
+    this.sourceCustomerId = sourceCustomerId;
+    return this;
+  }
+
+  /**
+   * Sets the task ID associated with the resources in the bundle.
+   * @param {string} taskId - The task ID.
+   * @returns {this} The FHIRBundleProcessor instance for chaining.
+   */
+  setTaskId(taskId) {
+    this.taskId = taskId;
+    return this;
+  }
+  _getQueryInstance(resource) {
+    return new _TaskFHIRQuery.TaskFHIRQuery(resource);
+  }
+
+  /**
+   * Prepares a FHIRQuery object for a single resource.
+   * @private
+   * @param {object} resource - The FHIR resource.
+   * @returns {Array<{query: {updateOne: object}, resourceType: string | undefined}>} An array of queries.
+   */
+  _prepareQuery(resource) {
+    const query = this._getQueryInstance(resource);
+    if (this.integrationId) query.setIntegrationId(this.integrationId);
+    if (query instanceof _TaskFHIRQuery.TaskFHIRQuery) {
+      if (this.sourceCustomerId) query.setCustomerId(this.sourceCustomerId);
+      if (this.taskId) query.setTaskId(this.taskId);
+      if (this.customerSpecificData) query.customerSpecificDataStore(true);
+      return query.query();
+    }
+  }
+}
+exports.TaskFHIRBundleProcessor = TaskFHIRBundleProcessor;

package/dist/TaskFHIRQuery.js

@@ -0,0 +1,198 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TaskFHIRQuery = void 0;
+var _fhirQueryMongoStore = require("@healthcare-interoperability/fhir-query-mongo-store");
+/**
+ * Generates a FHIR query for MongoDB with a deterministic ID, with added support for
+ * CustomerID specific deduplication and segregation, and Task ID association.
+ * Extends {@link FHIRMongoQuery}.
+ */
+class TaskFHIRQuery extends _fhirQueryMongoStore.FHIRMongoQuery {
+  /**
+   * An array of customer IDs associated with this resource. Used for customer-specific data handling.
+   * @private
+   * @type {string[]}
+   */
+  customerId = [];
+
+  /**
+   * A flag indicating whether to store data specific to each customer ID.
+   * If true, separate queries will be generated for each customer ID.
+   * @private
+   * @type {boolean}
+   */
+  customerSpecificData = false;
+
+  /**
+   * The ID of the task associated with this resource.
+   * @private
+   * @type {string | undefined}
+   */
+  taskId;
+
+  /**
+   * Creates an instance of TQSFHIRQuery.
+   * @param {object} resource - The FHIR resource object.
+   */
+  constructor(resource) {
+    super(resource);
+  }
+
+  /**
+   * Sets the task ID associated with the resource.
+   * @param {string} taskId - The task ID.
+   * @returns {this} The TQSFHIRQuery instance for chaining.
+   */
+  setTaskId(taskId) {
+    this.taskId = taskId;
+    return this;
+  }
+
+  /**
+   * Sets the customer ID(s) associated with the resource. Accepts a single ID or an array of IDs.
+   * @param {string | string[]} customerId - The customer ID(s).
+   * @returns {this} The TQSFHIRQuery instance for chaining.
+   */
+  setCustomerId(customerId) {
+    if (!customerId) return this;
+    if (Array.isArray(customerId)) {
+      this.customerId.push(...customerId);
+    } else {
+      this.customerId.push(customerId);
+    }
+    return this;
+  }
+
+  /**
+  * Combines components in a canonical string format for hashing.
+  * @returns {string} Canonical string.
+  */
+  createCanonicalString() {
+    if (this.components.customerId) {
+      return `${this.components.integrationId}::${this.components.resourceType}::${this.components.resourceId}::${this.components.customerId}`;
+    }
+    return `${this.components.integrationId}::${this.components.resourceType}::${this.components.resourceId}`;
+  }
+
+  /**
+   * Enables or disables customer-specific data storage.
+   * When enabled, separate records are created for each customer ID.
+   * @param {boolean} [enable=true] - Whether to enable customer-specific data storage.
+   * @returns {this} The TQSFHIRQuery instance for chaining.
+   */
+  customerSpecificDataStore(enable = true) {
+    this.customerSpecificData = enable;
+    return this;
+  }
+
+  /**
+   * Builds an array of MongoDB update queries based on the resource and customer-specific settings.
+   * If `customerSpecificData` is enabled, it generates a query for each customer ID.
+   * @private
+   * @returns {Array<{id: string, set: object, setOnInsert: object, inc: object, addToSet: object}>}
+   * An array of objects, each containing the data for a MongoDB update operation.
+   */
+  queryBuilder() {
+    const queries = [];
+    const baseSetOnInsert = {
+      _processFlags: [],
+      _searchTags: [],
+      _changeLogs: []
+    };
+
+    /**
+     * Creates a query object with overrides for set and addToSet.
+     * @param {object} base - The base query data from prepareResource.
+     * @param {object} [addToSetOverrides={}] - Overrides for the $addToSet operator.
+     * @param {object} [setOverrides={}] - Overrides for the $set operator.
+     * @returns {{id: string, set: object, setOnInsert: object, inc: object, addToSet: object}}
+     */
+    const makeQuery = (base, addToSetOverrides = {}, setOverrides = {}) => ({
+      id: base.id,
+      set: {
+        ...base.set,
+        ...setOverrides,
+        syncedAt: new Date()
+      },
+      setOnInsert: {
+        ...base.setOnInsert,
+        ...baseSetOnInsert
+      },
+      inc: base.inc,
+      addToSet: {
+        ...(base.addToSet || {}),
+        ...addToSetOverrides
+      }
+    });
+    const dedupId = super.generate(); // Generate a common deduplication ID for the base resource
+
+    if (this.customerSpecificData && this.customerId?.length) {
+      for (const cid of this.customerId) {
+        this.setComponent('customerId', cid);
+        const base = super.prepareResource();
+        const addToSet = {
+          _sourceCustomerId: cid,
+          ...(this.taskId ? {
+            sourceTask: this.taskId
+          } : {})
+        };
+        queries.push(makeQuery(base, addToSet, {
+          _dedupId: dedupId,
+          _customerSpecificStore: true
+        }));
+      }
+    } else {
+      const base = super.prepareResource();
+      const addToSet = {
+        ...(this.customerId?.length ? {
+          _sourceCustomerId: {
+            $each: this.customerId
+          }
+        } : {}),
+        ...(this.taskId ? {
+          sourceTask: this.taskId
+        } : {})
+      };
+      queries.push(makeQuery(base, addToSet, {
+        _dedupId: dedupId
+      }));
+    }
+    return queries;
+  }
+
+  /**
+   * Generates an array of MongoDB update queries for the FHIR resource, handling customer-specific data if enabled.
+   * @param {boolean} [upsert=true] - Whether to perform an upsert operation.
+   * @returns {Array<{query: {updateOne: {filter: object, update: object, upsert: boolean}}, resourceType: string | undefined}>}
+   * An array of objects, each containing a MongoDB update query and the resource type.
+   */
+  query(upsert = true) {
+    return this.queryBuilder().map(({
+      id,
+      set,
+      setOnInsert,
+      inc,
+      addToSet
+    }) => ({
+      query: {
+        updateOne: {
+          filter: {
+            _id: id
+          },
+          update: {
+            $set: set,
+            $setOnInsert: setOnInsert,
+            $inc: inc,
+            $addToSet: addToSet
+          },
+          upsert
+        }
+      },
+      resourceType: this.resourceType
+    }));
+  }
+}
+exports.TaskFHIRQuery = TaskFHIRQuery;

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "TaskFHIRBundleProcessor", {
+  enumerable: true,
+  get: function () {
+    return _TaskFHIRBundleProcessor.TaskFHIRBundleProcessor;
+  }
+});
+Object.defineProperty(exports, "TaskFHIRQuery", {
+  enumerable: true,
+  get: function () {
+    return _TaskFHIRQuery.TaskFHIRQuery;
+  }
+});
+var _TaskFHIRBundleProcessor = require("./TaskFHIRBundleProcessor");
+var _TaskFHIRQuery = require("./TaskFHIRQuery");

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@quicore/task-queue-fhir-tools",
+  "version": "1.1.0",
+  "description": "Helper tools for FHIR processing using Task Queue Server",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "babel src -d dist"
+  },
+  "keywords": [
+    "fhir",
+    "healthcare",
+    "quicore",
+    "task-queue"
+  ],
+  "author": "quicore",
+  "license": "MIT",
+  "dependencies": {
+    "@healthcare-interoperability/fhir-query-mongo-store": "^1.0.0",
+    "@healthcare-interoperability/fhir-tools": "^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"
+  }
+}