@peerbits/fhir-observation-generator 1.0.0

package/dist/generators/respiratory-rate.js

@@ -0,0 +1,50 @@
+/**
+ * Respiratory Rate Observation Generator.
+ */
+import { LOINC_MAP, LOINC_SYSTEM, UCUM_SYSTEM, formatCategory } from "../loinc-map.js";
+import { convertUnit } from "../units.js";
+import { validateObservation } from "../validate.js";
+export function respiratoryRateToObservation(reading, config) {
+    if (reading.deviceType !== "respiratory-rate") {
+        throw new Error(`Invalid deviceType for respiratory rate generator: expected 'respiratory-rate', got '${reading.deviceType}'`);
+    }
+    if (typeof reading.value !== "number") {
+        throw new Error(`Invalid respiratory rate value: expected number, got ${typeof reading.value}`);
+    }
+    const mapping = LOINC_MAP["respiratory-rate"];
+    const targetUnit = config?.targetUnit || mapping.defaultUcumUnit;
+    const conv = convertUnit(reading.value, reading.unit, targetUnit);
+    const observation = {
+        resourceType: "Observation",
+        status: config?.status || "final",
+        category: formatCategory(mapping.category),
+        code: {
+            coding: [
+                {
+                    system: LOINC_SYSTEM,
+                    code: mapping.loincCode,
+                    display: mapping.display,
+                },
+            ],
+            text: mapping.display,
+        },
+        subject: {
+            reference: reading.patientRef,
+        },
+        effectiveDateTime: reading.timestamp,
+        ...(reading.deviceId ? { device: { reference: reading.deviceId } } : {}),
+        valueQuantity: {
+            value: conv.value,
+            unit: conv.unit,
+            system: UCUM_SYSTEM,
+            code: conv.ucumCode,
+        },
+    };
+    if (config?.validate) {
+        const result = validateObservation(observation);
+        if (!result.valid) {
+            throw new Error(`Structural validation failed for respiratory rate observation: ${result.errors.join(", ")}`);
+        }
+    }
+    return observation;
+}

package/dist/generators/spo2.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SpO2 (Oxygen Saturation) Observation Generator.
+ */
+import { DeviceReading, FhirObservation, GeneratorConfig } from "../types.js";
+export declare function spo2ToObservation(reading: DeviceReading, config?: GeneratorConfig): FhirObservation;

package/dist/generators/spo2.js

@@ -0,0 +1,50 @@
+/**
+ * SpO2 (Oxygen Saturation) Observation Generator.
+ */
+import { LOINC_MAP, LOINC_SYSTEM, UCUM_SYSTEM, formatCategory } from "../loinc-map.js";
+import { convertUnit } from "../units.js";
+import { validateObservation } from "../validate.js";
+export function spo2ToObservation(reading, config) {
+    if (reading.deviceType !== "spo2") {
+        throw new Error(`Invalid deviceType for spo2 generator: expected 'spo2', got '${reading.deviceType}'`);
+    }
+    if (typeof reading.value !== "number") {
+        throw new Error(`Invalid spo2 value: expected number, got ${typeof reading.value}`);
+    }
+    const mapping = LOINC_MAP["spo2"];
+    const targetUnit = config?.targetUnit || mapping.defaultUcumUnit;
+    const conv = convertUnit(reading.value, reading.unit, targetUnit);
+    const observation = {
+        resourceType: "Observation",
+        status: config?.status || "final",
+        category: formatCategory(mapping.category),
+        code: {
+            coding: [
+                {
+                    system: LOINC_SYSTEM,
+                    code: mapping.loincCode,
+                    display: mapping.display,
+                },
+            ],
+            text: mapping.display,
+        },
+        subject: {
+            reference: reading.patientRef,
+        },
+        effectiveDateTime: reading.timestamp,
+        ...(reading.deviceId ? { device: { reference: reading.deviceId } } : {}),
+        valueQuantity: {
+            value: conv.value,
+            unit: conv.unit,
+            system: UCUM_SYSTEM,
+            code: conv.ucumCode,
+        },
+    };
+    if (config?.validate) {
+        const result = validateObservation(observation);
+        if (!result.valid) {
+            throw new Error(`Structural validation failed for SpO2 observation: ${result.errors.join(", ")}`);
+        }
+    }
+    return observation;
+}

package/dist/generators/temperature.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Body Temperature Observation Generator.
+ */
+import { DeviceReading, FhirObservation, GeneratorConfig } from "../types.js";
+export declare function temperatureToObservation(reading: DeviceReading, config?: GeneratorConfig): FhirObservation;

package/dist/generators/temperature.js

@@ -0,0 +1,50 @@
+/**
+ * Body Temperature Observation Generator.
+ */
+import { LOINC_MAP, LOINC_SYSTEM, UCUM_SYSTEM, formatCategory } from "../loinc-map.js";
+import { convertUnit } from "../units.js";
+import { validateObservation } from "../validate.js";
+export function temperatureToObservation(reading, config) {
+    if (reading.deviceType !== "temperature") {
+        throw new Error(`Invalid deviceType for temperature generator: expected 'temperature', got '${reading.deviceType}'`);
+    }
+    if (typeof reading.value !== "number") {
+        throw new Error(`Invalid temperature value: expected number, got ${typeof reading.value}`);
+    }
+    const mapping = LOINC_MAP["temperature"];
+    const targetUnit = config?.targetUnit || mapping.defaultUcumUnit;
+    const conv = convertUnit(reading.value, reading.unit, targetUnit);
+    const observation = {
+        resourceType: "Observation",
+        status: config?.status || "final",
+        category: formatCategory(mapping.category),
+        code: {
+            coding: [
+                {
+                    system: LOINC_SYSTEM,
+                    code: mapping.loincCode,
+                    display: mapping.display,
+                },
+            ],
+            text: mapping.display,
+        },
+        subject: {
+            reference: reading.patientRef,
+        },
+        effectiveDateTime: reading.timestamp,
+        ...(reading.deviceId ? { device: { reference: reading.deviceId } } : {}),
+        valueQuantity: {
+            value: conv.value,
+            unit: conv.unit,
+            system: UCUM_SYSTEM,
+            code: conv.ucumCode,
+        },
+    };
+    if (config?.validate) {
+        const result = validateObservation(observation);
+        if (!result.valid) {
+            throw new Error(`Structural validation failed for temperature observation: ${result.errors.join(", ")}`);
+        }
+    }
+    return observation;
+}

package/dist/generators/weight.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Weight Observation Generator.
+ */
+import { DeviceReading, FhirObservation, GeneratorConfig } from "../types.js";
+export declare function weightToObservation(reading: DeviceReading, config?: GeneratorConfig): FhirObservation;

package/dist/generators/weight.js

@@ -0,0 +1,50 @@
+/**
+ * Weight Observation Generator.
+ */
+import { LOINC_MAP, LOINC_SYSTEM, UCUM_SYSTEM, formatCategory } from "../loinc-map.js";
+import { convertUnit } from "../units.js";
+import { validateObservation } from "../validate.js";
+export function weightToObservation(reading, config) {
+    if (reading.deviceType !== "weight") {
+        throw new Error(`Invalid deviceType for weight generator: expected 'weight', got '${reading.deviceType}'`);
+    }
+    if (typeof reading.value !== "number") {
+        throw new Error(`Invalid weight value: expected number, got ${typeof reading.value}`);
+    }
+    const mapping = LOINC_MAP["weight"];
+    const targetUnit = config?.targetUnit || mapping.defaultUcumUnit;
+    const conv = convertUnit(reading.value, reading.unit, targetUnit);
+    const observation = {
+        resourceType: "Observation",
+        status: config?.status || "final",
+        category: formatCategory(mapping.category),
+        code: {
+            coding: [
+                {
+                    system: LOINC_SYSTEM,
+                    code: mapping.loincCode,
+                    display: mapping.display,
+                },
+            ],
+            text: mapping.display,
+        },
+        subject: {
+            reference: reading.patientRef,
+        },
+        effectiveDateTime: reading.timestamp,
+        ...(reading.deviceId ? { device: { reference: reading.deviceId } } : {}),
+        valueQuantity: {
+            value: conv.value,
+            unit: conv.unit,
+            system: UCUM_SYSTEM,
+            code: conv.ucumCode,
+        },
+    };
+    if (config?.validate) {
+        const result = validateObservation(observation);
+        if (!result.valid) {
+            throw new Error(`Structural validation failed for weight observation: ${result.errors.join(", ")}`);
+        }
+    }
+    return observation;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @peerbits/fhir-observation-generator
+ *
+ * Pure data-transformation library for generating FHIR Observation resources
+ * from Remote Patient Monitoring (RPM) device readings with LOINC coding and unit conversion.
+ */
+export * from "./types.js";
+export * from "./loinc-map.js";
+export * from "./units.js";
+export * from "./validate.js";
+export * from "./bundle.js";
+export * from "./generators/index.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @peerbits/fhir-observation-generator
+ *
+ * Pure data-transformation library for generating FHIR Observation resources
+ * from Remote Patient Monitoring (RPM) device readings with LOINC coding and unit conversion.
+ */
+export * from "./types.js";
+export * from "./loinc-map.js";
+export * from "./units.js";
+export * from "./validate.js";
+export * from "./bundle.js";
+export * from "./generators/index.js";

package/dist/loinc-map.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Single source of truth mapping each deviceType to its official LOINC code,
+ * display text, FHIR Observation category, and standard UCUM target unit.
+ *
+ * Grounded in the official LOINC database (loinc.org) and US Core Vital Signs Profile.
+ */
+import { DeviceType, FhirCodeableConcept } from "./types.js";
+export interface LoincMapping {
+    deviceType: DeviceType;
+    loincCode: string;
+    display: string;
+    category: {
+        system: string;
+        code: string;
+        display: string;
+    };
+    defaultUcumUnit: string;
+    defaultUnitDisplay: string;
+}
+export interface ComponentLoincMapping {
+    loincCode: string;
+    display: string;
+    ucumUnit: string;
+    unitDisplay: string;
+}
+export declare const VITAL_SIGNS_CATEGORY: {
+    system: string;
+    code: string;
+    display: string;
+};
+export declare const LOINC_SYSTEM = "http://loinc.org";
+export declare const UCUM_SYSTEM = "http://unitsofmeasure.org";
+export declare const LOINC_MAP: Record<DeviceType, LoincMapping>;
+/**
+ * Component LOINC mappings for blood pressure components.
+ */
+export declare const LOINC_BP_SYSTOLIC: ComponentLoincMapping;
+export declare const LOINC_BP_DIASTOLIC: ComponentLoincMapping;
+/**
+ * Helper function to retrieve LOINC mapping for a deviceType.
+ */
+export declare function getLoincMapping(deviceType: DeviceType): LoincMapping;
+/**
+ * Formats a Category object into a FHIR CodeableConcept array.
+ */
+export declare function formatCategory(category: {
+    system: string;
+    code: string;
+    display: string;
+}): FhirCodeableConcept[];

package/dist/loinc-map.js

@@ -0,0 +1,112 @@
+/**
+ * Single source of truth mapping each deviceType to its official LOINC code,
+ * display text, FHIR Observation category, and standard UCUM target unit.
+ *
+ * Grounded in the official LOINC database (loinc.org) and US Core Vital Signs Profile.
+ */
+export const VITAL_SIGNS_CATEGORY = {
+    system: "http://terminology.hl7.org/CodeSystem/observation-category",
+    code: "vital-signs",
+    display: "Vital Signs",
+};
+export const LOINC_SYSTEM = "http://loinc.org";
+export const UCUM_SYSTEM = "http://unitsofmeasure.org";
+export const LOINC_MAP = {
+    "blood-pressure": {
+        deviceType: "blood-pressure",
+        loincCode: "85354-9",
+        display: "Blood pressure panel with all children optional",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "mm[Hg]",
+        defaultUnitDisplay: "mmHg",
+    },
+    "heart-rate": {
+        deviceType: "heart-rate",
+        loincCode: "8867-4",
+        display: "Heart rate",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "/min",
+        defaultUnitDisplay: "beats/min",
+    },
+    weight: {
+        deviceType: "weight",
+        loincCode: "29463-7",
+        display: "Body weight",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "kg",
+        defaultUnitDisplay: "kg",
+    },
+    spo2: {
+        deviceType: "spo2",
+        loincCode: "59408-5",
+        display: "Oxygen saturation in Arterial blood by Pulse oximetry",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "%",
+        defaultUnitDisplay: "%",
+    },
+    temperature: {
+        deviceType: "temperature",
+        loincCode: "8310-5",
+        display: "Body temperature",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "Cel",
+        defaultUnitDisplay: "°C",
+    },
+    glucose: {
+        deviceType: "glucose",
+        loincCode: "2339-0",
+        display: "Glucose [Mass/volume] in Blood",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "mg/dL",
+        defaultUnitDisplay: "mg/dL",
+    },
+    "respiratory-rate": {
+        deviceType: "respiratory-rate",
+        loincCode: "9279-1",
+        display: "Respiratory rate",
+        category: VITAL_SIGNS_CATEGORY,
+        defaultUcumUnit: "/min",
+        defaultUnitDisplay: "breaths/min",
+    },
+};
+/**
+ * Component LOINC mappings for blood pressure components.
+ */
+export const LOINC_BP_SYSTOLIC = {
+    loincCode: "8480-6",
+    display: "Systolic blood pressure",
+    ucumUnit: "mm[Hg]",
+    unitDisplay: "mmHg",
+};
+export const LOINC_BP_DIASTOLIC = {
+    loincCode: "8462-4",
+    display: "Diastolic blood pressure",
+    ucumUnit: "mm[Hg]",
+    unitDisplay: "mmHg",
+};
+/**
+ * Helper function to retrieve LOINC mapping for a deviceType.
+ */
+export function getLoincMapping(deviceType) {
+    const mapping = LOINC_MAP[deviceType];
+    if (!mapping) {
+        throw new Error(`No LOINC mapping found for deviceType: ${deviceType}`);
+    }
+    return mapping;
+}
+/**
+ * Formats a Category object into a FHIR CodeableConcept array.
+ */
+export function formatCategory(category) {
+    return [
+        {
+            coding: [
+                {
+                    system: category.system,
+                    code: category.code,
+                    display: category.display,
+                },
+            ],
+        },
+    ];
+}

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Device reading and FHIR Observation types for @peerbits/fhir-observation-generator.
+ * Grounded in US Core Vital Signs Profile and FHIR R4 Observation resource specification.
+ */
+export type DeviceType = "blood-pressure" | "heart-rate" | "weight" | "spo2" | "temperature" | "glucose" | "respiratory-rate";
+export declare const SUPPORTED_DEVICE_TYPES: DeviceType[];
+export interface BloodPressureValue {
+    systolic: number;
+    diastolic: number;
+}
+export type DeviceReadingValue = number | BloodPressureValue;
+export interface DeviceReading {
+    /**
+     * The vital type of the device reading.
+     */
+    deviceType: DeviceType;
+    /**
+     * Numeric reading value, or { systolic, diastolic } object for blood pressure.
+     */
+    value: DeviceReadingValue;
+    /**
+     * Unit of measurement as reported by the device (e.g. "degF", "lbs", "mmHg", "bpm", "%", "mg/dL").
+     */
+    unit: string;
+    /**
+     * Timestamp in ISO 8601 format (e.g. "2026-08-06T10:00:00Z").
+     */
+    timestamp: string;
+    /**
+     * Opaque reference to patient (e.g. "Patient/p-12345"). Never include real identifiers/PHI.
+     */
+    patientRef: string;
+    /**
+     * Optional opaque device identifier (e.g. "Device/d-98765").
+     */
+    deviceId?: string;
+}
+export interface GeneratorConfig {
+    /**
+     * Optional target unit to convert value into. If omitted, standard UCUM target unit is used.
+     */
+    targetUnit?: string;
+    /**
+     * Observation status. Defaults to "final".
+     */
+    status?: "registered" | "preliminary" | "final" | "amended" | "corrected" | "cancelled" | "entered-in-error" | "unknown";
+    /**
+     * If true, performs structural validation on the generated Observation before returning.
+     * Throws Error if validation fails.
+     */
+    validate?: boolean;
+}
+export interface FhirCoding {
+    system: string;
+    code: string;
+    display?: string;
+}
+export interface FhirCodeableConcept {
+    coding: FhirCoding[];
+    text?: string;
+}
+export interface FhirQuantity {
+    value: number;
+    unit: string;
+    system: string;
+    code: string;
+}
+export interface FhirObservationComponent {
+    code: FhirCodeableConcept;
+    valueQuantity?: FhirQuantity;
+}
+export interface FhirObservation {
+    resourceType: "Observation";
+    id?: string;
+    status: string;
+    category: FhirCodeableConcept[];
+    code: FhirCodeableConcept;
+    subject: {
+        reference: string;
+    };
+    effectiveDateTime: string;
+    valueQuantity?: FhirQuantity;
+    component?: FhirObservationComponent[];
+    device?: {
+        reference: string;
+    };
+}
+export interface FhirBundleEntry {
+    resource: FhirObservation;
+    request: {
+        method: "POST";
+        url: string;
+    };
+}
+export interface FhirBundle {
+    resourceType: "Bundle";
+    type: "transaction";
+    entry: FhirBundleEntry[];
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Device reading and FHIR Observation types for @peerbits/fhir-observation-generator.
+ * Grounded in US Core Vital Signs Profile and FHIR R4 Observation resource specification.
+ */
+export const SUPPORTED_DEVICE_TYPES = [
+    "blood-pressure",
+    "heart-rate",
+    "weight",
+    "spo2",
+    "temperature",
+    "glucose",
+    "respiratory-rate",
+];

package/dist/units.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Standard UCUM unit conversions for @peerbits/fhir-observation-generator.
+ *
+ * All formulas use exact standard UCUM conversion factors.
+ * Reference unit conversions are verified against clinical standards.
+ */
+export interface UnitConversionResult {
+    value: number;
+    unit: string;
+    ucumCode: string;
+}
+/**
+ * Normalizes input unit strings into standard UCUM unit codes.
+ */
+export declare function normalizeUcumUnit(unit: string): string;
+/**
+ * Gets human-readable display string for a UCUM unit code.
+ */
+export declare function getUnitDisplay(ucumCode: string): string;
+/**
+ * Converts a numeric value from source unit to target unit.
+ * If units are identical, returns value unchanged.
+ * If targetUnit is not provided, defaults to standard UCUM unit or source unit.
+ */
+export declare function convertUnit(value: number, fromUnit: string, targetUnit?: string): UnitConversionResult;