fhir-data-utils-ts 0.2.4

package/dist/vital-sign-observations.js

@@ -0,0 +1,284 @@
+import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+import { FhirCodeSystem, ObservationCategoryCodes, ObservationClaim, decodeObservationClaimList, } from './observation-claims.js';
+export { ObservationCategoryCodes, ObservationClaim } from './observation-claims.js';
+function defineCoding(system, code, display) {
+    return Object.freeze({ system, code, display, claim: `${system}|${code}` });
+}
+/** Canonical LOINC descriptors for supported vital signs. */
+export const VitalSignsCodes = Object.freeze({
+    BodyWeight: defineCoding(FhirCodeSystem.Loinc, '29463-7', 'Body weight'),
+    HeartRate: defineCoding(FhirCodeSystem.Loinc, '8867-4', 'Heart rate'),
+    BloodPressure: defineCoding(FhirCodeSystem.Loinc, '85354-9', 'Blood pressure panel'),
+    SystolicBloodPressure: defineCoding(FhirCodeSystem.Loinc, '8480-6', 'Systolic blood pressure'),
+    DiastolicBloodPressure: defineCoding(FhirCodeSystem.Loinc, '8462-4', 'Diastolic blood pressure'),
+    BodyTemperature: defineCoding(FhirCodeSystem.Loinc, '8310-5', 'Body temperature'),
+    OxygenSaturation: defineCoding(FhirCodeSystem.Loinc, '2708-6', 'Oxygen saturation'),
+    RespiratoryRate: defineCoding(FhirCodeSystem.Loinc, '9279-1', 'Respiratory rate'),
+});
+/** Canonical UCUM descriptors for supported vital signs. */
+export const VitalSignsUnits = Object.freeze({
+    BeatsPerMinute: defineCoding(FhirCodeSystem.Ucum, '/min', 'beats/minute'),
+    MillimeterOfMercury: defineCoding(FhirCodeSystem.Ucum, 'mm[Hg]', 'mmHg'),
+    Celsius: defineCoding(FhirCodeSystem.Ucum, 'Cel', 'degrees Celsius'),
+    Percent: defineCoding(FhirCodeSystem.Ucum, '%', 'percent'),
+    Kilogram: defineCoding(FhirCodeSystem.Ucum, 'kg', 'kilogram'),
+});
+/** Governed FHIR/LOINC tokens used by every channel that captures vital signs. */
+export const VitalSignCode = Object.freeze({
+    bloodPressure: VitalSignsCodes.BloodPressure.claim,
+    systolic: VitalSignsCodes.SystolicBloodPressure.claim,
+    diastolic: VitalSignsCodes.DiastolicBloodPressure.claim,
+    temperature: VitalSignsCodes.BodyTemperature.claim,
+    heartRate: VitalSignsCodes.HeartRate.claim,
+    oxygenSaturation: VitalSignsCodes.OxygenSaturation.claim,
+    respiratoryRate: VitalSignsCodes.RespiratoryRate.claim,
+    bodyWeight: VitalSignsCodes.BodyWeight.claim,
+});
+/** UCUM-compatible unit spellings persisted in flat claims. */
+export const VitalSignUnit = Object.freeze({
+    bloodPressure: VitalSignsUnits.MillimeterOfMercury.claim,
+    temperature: VitalSignsUnits.Celsius.claim,
+    heartRate: VitalSignsUnits.BeatsPerMinute.claim,
+    oxygenSaturation: VitalSignsUnits.Percent.claim,
+    respiratoryRate: VitalSignsUnits.BeatsPerMinute.claim,
+    bodyWeight: VitalSignsUnits.Kilogram.claim,
+});
+/**
+ * Builds one timestamped Observation. The device is retained as source; this
+ * helper deliberately never creates a professional performer or attester.
+ */
+export function buildVitalSignObservation(input) {
+    const measuredAt = normalizeDateTime(input.measuredAt);
+    const claims = {
+        [ObservationClaim.Identifier]: required(input.entryId, 'vital_sign_entry_id_required'),
+        [ObservationClaim.Subject]: required(input.subjectReference, 'vital_sign_subject_required'),
+        [ObservationClaim.Status]: input.status,
+        [ObservationClaim.Category]: ObservationCategoryCodes.VitalSigns.claim,
+        [ObservationClaim.EffectiveDateTime]: measuredAt,
+    };
+    if (input.deviceReference)
+        claims[ObservationClaim.Device] = required(input.deviceReference, 'vital_sign_device_required');
+    if (input.note?.trim())
+        claims[ObservationClaim.Note] = input.note.trim();
+    if (input.userSelected !== undefined)
+        claims[ObservationClaim.UserSelected] = String(input.userSelected);
+    if (input.kind === 'blood-pressure') {
+        if (!validPositive(input.systolic) || !validPositive(input.diastolic) || input.systolic <= input.diastolic) {
+            throw new TypeError('blood_pressure_values_invalid');
+        }
+        claims[ObservationClaim.Code] = VitalSignCode.bloodPressure;
+        claims[ObservationClaim.CodeDisplay] = VitalSignsCodes.BloodPressure.display ?? '';
+        const components = Object.freeze([
+            buildBloodPressureComponent(input, 'systolic', input.systolic, VitalSignsCodes.SystolicBloodPressure),
+            buildBloodPressureComponent(input, 'diastolic', input.diastolic, VitalSignsCodes.DiastolicBloodPressure),
+        ]);
+        claims[ObservationClaim.HasMember] = components.map(component => component.reference).join(',');
+        const primary = buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'Observation', claims });
+        return freezeObservationGraph(primary, components);
+    }
+    else {
+        if (!validPositive(input.value))
+            throw new TypeError('vital_sign_value_invalid');
+        const scalar = scalarDefinition(input.kind);
+        claims[ObservationClaim.Code] = scalar.coding.claim;
+        if (scalar.coding.display)
+            claims[ObservationClaim.CodeDisplay] = scalar.coding.display;
+        claims[ObservationClaim.ValueQuantityNumber] = String(input.value);
+        claims[ObservationClaim.ValueQuantityUnit] = scalar.unit;
+    }
+    return freezeObservationGraph(buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'Observation', claims }), Object.freeze([]));
+}
+/** Restores component values from the canonical graph or legacy scalar/array claims. */
+export function parseObservationComponents(source) {
+    if (isVitalSignObservationGraph(source)) {
+        return Object.freeze(source.components.map(component => componentQuantityFromEntry(component)));
+    }
+    const claims = source;
+    const codes = decodeObservationClaimList(claims[ObservationClaim.ComponentCode]);
+    const displays = decodeObservationClaimList(claims[ObservationClaim.ComponentCodeDisplay]);
+    const values = decodeObservationClaimList(claims[ObservationClaim.ComponentValueQuantityNumber]);
+    const units = decodeObservationClaimList(claims[ObservationClaim.ComponentValueQuantityUnit]);
+    if (!codes.length && claims[ObservationClaim.Code] === VitalSignCode.bloodPressure) {
+        const systolic = Number(claims[ObservationClaim.BloodPressureSystolicNumber]);
+        const diastolic = Number(claims[ObservationClaim.BloodPressureDiastolicNumber]);
+        if (Number.isFinite(systolic) && Number.isFinite(diastolic)) {
+            return Object.freeze([
+                Object.freeze({ code: VitalSignCode.systolic, value: systolic, unit: VitalSignUnit.bloodPressure }),
+                Object.freeze({ code: VitalSignCode.diastolic, value: diastolic, unit: VitalSignUnit.bloodPressure }),
+            ]);
+        }
+    }
+    if (codes.length !== values.length || codes.length !== units.length)
+        throw new TypeError('observation_components_not_aligned');
+    if (displays.length && displays.length !== codes.length)
+        throw new TypeError('observation_components_not_aligned');
+    return Object.freeze(codes.map((code, index) => {
+        const value = Number(values[index]);
+        if (typeof code !== 'string' || typeof units[index] !== 'string' || !Number.isFinite(value)) {
+            throw new TypeError('observation_component_invalid');
+        }
+        const display = displays[index];
+        if (display !== undefined && typeof display !== 'string')
+            throw new TypeError('observation_component_invalid');
+        return Object.freeze({ code, ...(display ? { display } : {}), value, unit: units[index] });
+    }));
+}
+/**
+ * Creates generic reduced rows for component-level indexes.
+ *
+ * These are internal index projections, not independent native FHIR
+ * Observations. The missing status deliberately keeps them out of normal
+ * top-level Observation results.
+ */
+export function materializeObservationComponentIndexEntries(entry) {
+    if (isVitalSignObservationGraph(entry)) {
+        return Object.freeze(entry.components.map((component, componentIndex) => Object.freeze({
+            parentReference: entry.primary.reference,
+            componentIndex,
+            claims: component.claims,
+        })));
+    }
+    if (entry.resourceType !== 'Observation')
+        throw new TypeError('vital_sign_observation_required');
+    const subject = required(entry.claims[ObservationClaim.Subject] ?? '', 'vital_sign_subject_required');
+    return Object.freeze(parseObservationComponents(entry.claims).map((component, componentIndex) => Object.freeze({
+        parentReference: entry.reference,
+        componentIndex,
+        claims: Object.freeze({
+            [ObservationClaim.Subject]: subject,
+            [ObservationClaim.Code]: component.code,
+            ...(component.display ? { [ObservationClaim.CodeDisplay]: component.display } : {}),
+            [ObservationClaim.ValueQuantityNumber]: String(component.value),
+            [ObservationClaim.ValueQuantityUnit]: component.unit,
+        }),
+    })));
+}
+/** Projects the neutral flat contract at the explicit FHIR R4 boundary. */
+export function projectVitalSignObservationR4(entry) {
+    return projectVitalSignObservation(entry);
+}
+/** Projects the neutral flat contract at the explicit FHIR R5 boundary. */
+export function projectVitalSignObservationR5(entry) {
+    return projectVitalSignObservation(entry);
+}
+function projectVitalSignObservation(source) {
+    const entry = isVitalSignObservationGraph(source) ? source.primary : source;
+    if (entry.resourceType !== 'Observation')
+        throw new TypeError('vital_sign_observation_required');
+    const claims = entry.claims;
+    const base = {
+        resourceType: 'Observation',
+        id: required(claims[ObservationClaim.Identifier] ?? '', 'vital_sign_entry_id_required'),
+        status: required(claims[ObservationClaim.Status] ?? '', 'vital_sign_status_required'),
+        category: [{ coding: [codingFromClaim(required(claims[ObservationClaim.Category] ?? '', 'vital_sign_category_required'))] }],
+        code: { coding: [codingFromClaim(required(claims[ObservationClaim.Code] ?? '', 'vital_sign_code_required'), claims[ObservationClaim.CodeDisplay])] },
+        subject: { reference: required(claims[ObservationClaim.Subject] ?? '', 'vital_sign_subject_required') },
+        effectiveDateTime: required(claims[ObservationClaim.EffectiveDateTime] ?? '', 'vital_sign_measured_at_required'),
+        ...(claims[ObservationClaim.Device] ? { device: { reference: claims[ObservationClaim.Device] } } : {}),
+    };
+    const components = parseObservationComponents(isVitalSignObservationGraph(source) ? source : claims);
+    if (components.length) {
+        return Object.freeze({ ...base, component: Object.freeze(components.map(component => Object.freeze({
+                code: { coding: [codingFromClaim(component.code, component.display)] },
+                valueQuantity: quantity(component.value, component.unit),
+            }))) });
+    }
+    const value = Number(claims[ObservationClaim.ValueQuantityNumber]);
+    if (!Number.isFinite(value))
+        throw new TypeError('vital_sign_value_invalid');
+    return Object.freeze({ ...base, valueQuantity: quantity(value, required(claims[ObservationClaim.ValueQuantityUnit] ?? '', 'vital_sign_unit_required')) });
+}
+function codingFromClaim(value, display) {
+    const separator = value.lastIndexOf('|');
+    return separator < 0
+        ? Object.freeze({ code: value, ...(display ? { display } : {}) })
+        : Object.freeze({ system: value.slice(0, separator), code: value.slice(separator + 1), ...(display ? { display } : {}) });
+}
+function quantity(value, unitClaim) {
+    const coding = codingFromClaim(unitClaim);
+    return Object.freeze({ value, unit: coding.code, ...coding });
+}
+/** Converts a device/API batch to independent preliminary Observations without aggregation. */
+export function normalizeVitalSignDeviceBatch(input) {
+    const seen = new Set();
+    return Object.freeze(input.readings.map(reading => {
+        if (seen.has(reading.entryId))
+            throw new TypeError('vital_sign_entry_id_duplicate');
+        seen.add(reading.entryId);
+        return buildVitalSignObservation({
+            ...reading,
+            subjectReference: input.subjectReference,
+            deviceReference: input.deviceReference,
+            status: 'preliminary',
+        });
+    }));
+}
+function buildBloodPressureComponent(input, role, value, coding) {
+    const entryId = `${required(input.entryId, 'vital_sign_entry_id_required')}-${role}`;
+    const claims = {
+        [ObservationClaim.Identifier]: entryId,
+        [ObservationClaim.Subject]: required(input.subjectReference, 'vital_sign_subject_required'),
+        [ObservationClaim.Category]: ObservationCategoryCodes.VitalSigns.claim,
+        [ObservationClaim.Code]: coding.claim,
+        [ObservationClaim.ValueQuantityNumber]: String(value),
+        [ObservationClaim.ValueQuantityUnit]: VitalSignUnit.bloodPressure,
+        [ObservationClaim.EffectiveDateTime]: normalizeDateTime(input.measuredAt),
+    };
+    if (coding.display)
+        claims[ObservationClaim.CodeDisplay] = coding.display;
+    if (input.deviceReference)
+        claims[ObservationClaim.Device] = required(input.deviceReference, 'vital_sign_device_required');
+    return buildFlatClaimResourceEntry({ entryId, resourceType: 'Observation', claims });
+}
+function freezeObservationGraph(primary, components) {
+    const frozenComponents = Object.freeze([...components]);
+    return Object.freeze({ primary, components: frozenComponents, entries: Object.freeze([primary, ...frozenComponents]) });
+}
+function isVitalSignObservationGraph(source) {
+    return 'primary' in source && 'components' in source && 'entries' in source;
+}
+function componentQuantityFromEntry(entry) {
+    if (entry.resourceType !== 'Observation')
+        throw new TypeError('observation_component_invalid');
+    const value = Number(entry.claims[ObservationClaim.ValueQuantityNumber]);
+    const code = entry.claims[ObservationClaim.Code];
+    const unit = entry.claims[ObservationClaim.ValueQuantityUnit];
+    if (!code || !unit || !Number.isFinite(value))
+        throw new TypeError('observation_component_invalid');
+    const display = entry.claims[ObservationClaim.CodeDisplay];
+    return Object.freeze({ code, ...(display ? { display } : {}), value, unit });
+}
+function scalarDefinition(kind) {
+    switch (kind) {
+        case 'temperature': return { coding: VitalSignsCodes.BodyTemperature, unit: VitalSignUnit.temperature };
+        case 'heart-rate': return { coding: VitalSignsCodes.HeartRate, unit: VitalSignUnit.heartRate };
+        case 'oxygen-saturation': return { coding: VitalSignsCodes.OxygenSaturation, unit: VitalSignUnit.oxygenSaturation };
+        case 'respiratory-rate': return { coding: VitalSignsCodes.RespiratoryRate, unit: VitalSignUnit.respiratoryRate };
+        case 'body-weight': return { coding: VitalSignsCodes.BodyWeight, unit: VitalSignUnit.bodyWeight };
+    }
+}
+function normalizeDateTime(value) {
+    const date = new Date(value);
+    if (!value.trim() || Number.isNaN(date.valueOf()))
+        throw new TypeError('vital_sign_measured_at_invalid');
+    return date.toISOString();
+}
+function validPositive(value) {
+    return Number.isFinite(value) && value > 0;
+}
+function required(value, error) {
+    const normalized = value.trim();
+    if (!normalized || normalized.includes(','))
+        throw new TypeError(error);
+    return normalized;
+}
+/** Reusable neutral fixtures; consumers and tests must not duplicate wire examples. */
+export const VITAL_SIGN_EXAMPLES = Object.freeze({
+    subjectReference: 'Patient/example-subject',
+    deviceReference: 'Device/example-home-monitor',
+    bloodPressure: Object.freeze({ entryId: 'bp-example-1', measuredAt: '2026-09-21T08:15:00-07:00', systolic: 121, diastolic: 79 }),
+    heartRateBatch: Object.freeze([
+        Object.freeze({ entryId: 'hr-example-1', kind: 'heart-rate', measuredAt: '2026-09-20T08:00:00Z', value: 68 }),
+        Object.freeze({ entryId: 'hr-example-2', kind: 'heart-rate', measuredAt: '2026-09-21T08:00:00Z', value: 72 }),
+    ]),
+});

package/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -0,0 +1,72 @@
+# UHC FHIR utilities migration
+
+`uhc-fhir-utils-typescript` is an archaeological source, not a dependency of
+this package. Its useful behavior must be recovered behind neutral, typed and
+version-explicit contracts. Its product branding, obsolete security choices
+and transport assumptions must not be copied.
+
+## Migration rules
+
+1. Add the smallest failing contract test here before porting behavior.
+2. Use official FHIR R4/R5/R6 structures at import/export boundaries and flat
+   claims as the version-neutral representation between those boundaries.
+3. Copy no raw claim, terminology, identifier or profile literal into a
+   consumer. Define it once in its owning neutral or sector data package.
+4. Preserve historical inputs with explicit read adapters. New writers emit
+   only the current canonical representation.
+5. Do not change `gdc-*` while those repositories are frozen. They are
+   read-only compatibility evidence until every consumer uses this package.
+
+## Reuse, rewrite or retire
+
+| Old area | Decision | Current destination or gate |
+| --- | --- | --- |
+| `Bundle` and `Composition` traversal | Rewrite from tests | Neutral graph and explicit R4/R5/R6 adapters; preserve author, attester and section boundaries |
+| `CodeableConcept`, `Identifier`, `Reference`, `Quantity` | Rewrite and reuse behavior | Small typed value modules with round-trip tests |
+| `Observation` and resource parameter models | Rewrite | Canonical claim catalogs plus version-specific projection adapters |
+| `Parameters` conversion | Rewrite | A typed FHIR Parameters module; never a transport-specific envelope |
+| Anonymization field inventory | Test input only | A separately reviewed policy contract; old field lists do not become policy automatically |
+| ATC, LOINC, SNOMED and EMA JSON | Validate before reuse | Terminology service fixtures, never authoritative embedded catalogs |
+| DICOM parsing | Extract later | Separate imaging package; do not add `dicom-parser` to the neutral core |
+| SHA-1 attachment hashing | Retire | No compatibility writer; historical read/verification belongs in a versioned adapter |
+| `MessageHeader` transport conventions | Retire | Transport is outside the FHIR data contract |
+| UHC-branded templates and defaults | Retire or move downstream | Product policy belongs in UHC packages, not here |
+| Babel/Yarn/Jest build plumbing and broad `any` models | Retire | Node 24, TypeScript strict mode and `node:test` |
+
+## Observation and component contract
+
+FHIR blood pressure is one native `Observation` with systolic and diastolic
+entries in `Observation.component[]`. Canonical flat storage is instead a
+resource graph: the primary Observation owns `Observation.has-member`, and
+each referenced reduced Observation owns its identifier, subject, category,
+date, component code, numeric value and unit. Reduced entries deliberately
+carry no `Observation.status`, so normal top-level listings ignore them while
+component-level indexes can query their ordinary Observation claims.
+
+The R4/R5 export adapter resolves the primary entry's members and reconstructs
+one native `Observation.component[]`; it does not export three independent
+native Observations. Component entries do not use `is-contained`,
+`contained-parent-reference` or `contained-reference-list`.
+
+Aligned JSON arrays and the older comma-separated `Observation.component-*`
+claims are accepted only by the migration reader. No current writer emits
+either representation.
+
+The historical `Observation.bp-systolic-number` and
+`Observation.bp-diastolic-number` fields are accepted only when reading data
+that has no component graph or historical component claims. New writers and
+generic component indexes never emit them. This prevents a new custom claim
+family for every assessment scale.
+
+## Remaining migration sequence
+
+1. Inventory imports from `gdc-common-utils-ts` in SOS, Vet, UHC, portals and
+   assistants by resource family.
+2. Move one neutral resource family at a time into this package with exact
+   compatibility vectors and R4/R5 projection tests.
+3. Release this package, pin the immutable version in the lowest downstream
+   package, and run that consumer's complete local matrix.
+4. Remove the corresponding frozen dependency only after no consumer imports
+   that family from it.
+5. Migrate imaging/DICOM and terminology payloads as separate changes because
+   they have different dependencies, security rules and release gates.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "fhir-data-utils-ts",
+  "version": "0.2.4",
+  "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./coding-review-flat-claims": {
+      "types": "./dist/coding-review-flat-claims.d.ts",
+      "default": "./dist/coding-review-flat-claims.js"
+    },
+    "./flat-claim-resource-graph": {
+      "types": "./dist/flat-claim-resource-graph.d.ts",
+      "default": "./dist/flat-claim-resource-graph.js"
+    },
+    "./search-parameters": {
+      "types": "./dist/search-parameters.d.ts",
+      "default": "./dist/search-parameters.js"
+    },
+    "./observation-claims": {
+      "types": "./dist/observation-claims.d.ts",
+      "default": "./dist/observation-claims.js"
+    },
+    "./vital-sign-observations": {
+      "types": "./dist/vital-sign-observations.d.ts",
+      "default": "./dist/vital-sign-observations.js"
+    }
+  },
+  "files": [
+    "dist",
+    ".codex/skills",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "check": "npm run typecheck && npm test",
+    "prepack": "npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}