npm package: @quicore/task-queue-fhir-tools
Description: Helper tools for FHIR processing using Task Queue Server
Author: quicore
Latest version: 1.1.0

# @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