@peerbits/fhir-observation-generator 1.0.0

package/dist/units.js

@@ -0,0 +1,223 @@
+/**
+ * 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.
+ */
+const SUPPORTED_UCUM_UNITS = new Set([
+    "[degF]",
+    "Cel",
+    "[lb_av]",
+    "kg",
+    "g",
+    "[oz_av]",
+    "mg/dL",
+    "mmol/L",
+    "/min",
+    "%",
+    "mm[Hg]",
+]);
+/**
+ * Normalizes input unit strings into standard UCUM unit codes.
+ */
+export function normalizeUcumUnit(unit) {
+    const clean = unit.trim().toLowerCase();
+    switch (clean) {
+        // Temperature
+        case "degf":
+        case "°f":
+        case "f":
+        case "[degf]":
+        case "fahrenheit":
+            return "[degF]";
+        case "degc":
+        case "°c":
+        case "c":
+        case "cel":
+        case "[degc]":
+        case "celsius":
+            return "Cel";
+        // Weight
+        case "lb":
+        case "lbs":
+        case "[lb_av]":
+        case "pound":
+        case "pounds":
+            return "[lb_av]";
+        case "kg":
+        case "kilogram":
+        case "kilograms":
+            return "kg";
+        case "g":
+        case "gram":
+        case "grams":
+            return "g";
+        case "oz":
+        case "ounce":
+        case "ounces":
+        case "[oz_av]":
+            return "[oz_av]";
+        // Glucose
+        case "mg/dl":
+        case "mg/dL":
+            return "mg/dL";
+        case "mmol/l":
+        case "mmol/L":
+            return "mmol/L";
+        // Rate / frequency
+        case "bpm":
+        case "beats/min":
+        case "breaths/min":
+        case "count/min":
+        case "/min":
+        case "1/min":
+            return "/min";
+        // Percentage / SpO2
+        case "%":
+        case "percent":
+            return "%";
+        // Pressure
+        case "mmhg":
+        case "mm[hg]":
+        case "mm hg":
+            return "mm[Hg]";
+        default:
+            return unit;
+    }
+}
+/**
+ * Gets human-readable display string for a UCUM unit code.
+ */
+export function getUnitDisplay(ucumCode) {
+    switch (ucumCode) {
+        case "[degF]":
+            return "°F";
+        case "Cel":
+            return "°C";
+        case "[lb_av]":
+            return "lbs";
+        case "kg":
+            return "kg";
+        case "g":
+            return "g";
+        case "[oz_av]":
+            return "oz";
+        case "mg/dL":
+            return "mg/dL";
+        case "mmol/L":
+            return "mmol/L";
+        case "/min":
+            return "beats/min";
+        case "%":
+            return "%";
+        case "mm[Hg]":
+            return "mmHg";
+        default:
+            return ucumCode;
+    }
+}
+/**
+ * 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 function convertUnit(value, fromUnit, targetUnit) {
+    if (!Number.isFinite(value)) {
+        throw new Error("Invalid measurement value: expected a finite number");
+    }
+    if (typeof fromUnit !== "string" || !fromUnit.trim()) {
+        throw new Error("Invalid source unit: expected a non-empty string");
+    }
+    if (targetUnit !== undefined && (typeof targetUnit !== "string" || !targetUnit.trim())) {
+        throw new Error("Invalid target unit: expected a non-empty string");
+    }
+    const sourceUcum = normalizeUcumUnit(fromUnit);
+    const targetUcum = targetUnit ? normalizeUcumUnit(targetUnit) : sourceUcum;
+    if (!SUPPORTED_UCUM_UNITS.has(sourceUcum)) {
+        throw new Error(`Unsupported source unit: '${fromUnit}'`);
+    }
+    if (!SUPPORTED_UCUM_UNITS.has(targetUcum)) {
+        throw new Error(`Unsupported target unit: '${targetUnit}'`);
+    }
+    if (sourceUcum === targetUcum) {
+        return {
+            value: roundToFourDecimals(value),
+            unit: getUnitDisplay(targetUcum),
+            ucumCode: targetUcum,
+        };
+    }
+    // Temperature Conversions
+    if (sourceUcum === "[degF]" && targetUcum === "Cel") {
+        const converted = ((value - 32) * 5) / 9;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "°C",
+            ucumCode: "Cel",
+        };
+    }
+    if (sourceUcum === "Cel" && targetUcum === "[degF]") {
+        const converted = (value * 9) / 5 + 32;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "°F",
+            ucumCode: "[degF]",
+        };
+    }
+    // Weight Conversions (1 lb = 0.45359237 kg exact UCUM definition)
+    if (sourceUcum === "[lb_av]" && targetUcum === "kg") {
+        const converted = value * 0.45359237;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "kg",
+            ucumCode: "kg",
+        };
+    }
+    if (sourceUcum === "kg" && targetUcum === "[lb_av]") {
+        const converted = value / 0.45359237;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "lbs",
+            ucumCode: "[lb_av]",
+        };
+    }
+    if (sourceUcum === "g" && targetUcum === "kg") {
+        const converted = value / 1000;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "kg",
+            ucumCode: "kg",
+        };
+    }
+    if (sourceUcum === "[oz_av]" && targetUcum === "kg") {
+        const converted = value * 0.028349523125;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "kg",
+            ucumCode: "kg",
+        };
+    }
+    // Glucose Conversions (18.0182 mg/dL per mmol/L based on glucose molar mass 180.156 g/mol)
+    if (sourceUcum === "mg/dL" && targetUcum === "mmol/L") {
+        const converted = value / 18.0182;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "mmol/L",
+            ucumCode: "mmol/L",
+        };
+    }
+    if (sourceUcum === "mmol/L" && targetUcum === "mg/dL") {
+        const converted = value * 18.0182;
+        return {
+            value: roundToFourDecimals(converted),
+            unit: "mg/dL",
+            ucumCode: "mg/dL",
+        };
+    }
+    throw new Error(`Unsupported unit conversion: '${fromUnit}' to '${targetUnit}'`);
+}
+/**
+ * Rounds numbers to 4 decimal places to prevent floating point noise (e.g. 37.00000000000001).
+ */
+function roundToFourDecimals(num) {
+    return Math.round(num * 10000) / 10000;
+}

package/dist/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Structural self-check for generated FHIR Observation resources.
+ *
+ * Verifies mandatory fields according to the FHIR R4 Observation specification
+ * and US Core Vital Signs Profile requirements:
+ * - resourceType: "Observation"
+ * - status
+ * - category (containing vital-signs coding)
+ * - code (containing LOINC coding)
+ * - subject.reference
+ * - effectiveDateTime
+ * - valueQuantity OR component array (with valid values)
+ */
+import { FhirObservation, ValidationResult } from "./types.js";
+export declare function validateObservation(observation: FhirObservation): ValidationResult;

package/dist/validate.js

@@ -0,0 +1,69 @@
+/**
+ * Structural self-check for generated FHIR Observation resources.
+ *
+ * Verifies mandatory fields according to the FHIR R4 Observation specification
+ * and US Core Vital Signs Profile requirements:
+ * - resourceType: "Observation"
+ * - status
+ * - category (containing vital-signs coding)
+ * - code (containing LOINC coding)
+ * - subject.reference
+ * - effectiveDateTime
+ * - valueQuantity OR component array (with valid values)
+ */
+import { LOINC_SYSTEM } from "./loinc-map.js";
+export function validateObservation(observation) {
+    const errors = [];
+    if (!observation) {
+        return { valid: false, errors: ["Observation is null or undefined"] };
+    }
+    if (observation.resourceType !== "Observation") {
+        errors.push(`Invalid resourceType: expected 'Observation', got '${observation.resourceType}'`);
+    }
+    if (!observation.status) {
+        errors.push("Missing required field: status");
+    }
+    if (!Array.isArray(observation.category) || observation.category.length === 0) {
+        errors.push("Missing required field: category (must be non-empty array)");
+    }
+    else {
+        const hasVitalSignsCategory = observation.category.some((cat) => cat.coding?.some((c) => c.code === "vital-signs"));
+        if (!hasVitalSignsCategory) {
+            errors.push("Missing required category coding with code 'vital-signs'");
+        }
+    }
+    if (!observation.code || !Array.isArray(observation.code.coding) || observation.code.coding.length === 0) {
+        errors.push("Missing required field: code (must contain coding array)");
+    }
+    else {
+        const hasLoincCoding = observation.code.coding.some((c) => c.system === LOINC_SYSTEM && c.code && c.code.length > 0);
+        if (!hasLoincCoding) {
+            errors.push(`Missing valid LOINC coding under system '${LOINC_SYSTEM}' in code field`);
+        }
+    }
+    if (!observation.subject || typeof observation.subject.reference !== "string" || !observation.subject.reference.trim()) {
+        errors.push("Missing required field: subject.reference");
+    }
+    if (!observation.effectiveDateTime || isNaN(Date.parse(observation.effectiveDateTime))) {
+        errors.push("Missing or invalid required field: effectiveDateTime (must be valid ISO date string)");
+    }
+    // Value check: Must have valueQuantity OR component array
+    const hasValueQuantity = observation.valueQuantity &&
+        typeof observation.valueQuantity.value === "number" &&
+        Number.isFinite(observation.valueQuantity.value) &&
+        typeof observation.valueQuantity.unit === "string";
+    const hasComponents = Array.isArray(observation.component) &&
+        observation.component.length >= 2 &&
+        observation.component.every((comp) => comp.code &&
+            Array.isArray(comp.code.coding) &&
+            comp.valueQuantity &&
+            typeof comp.valueQuantity.value === "number" &&
+            Number.isFinite(comp.valueQuantity.value));
+    if (!hasValueQuantity && !hasComponents) {
+        errors.push("Observation must contain either a valid valueQuantity or a valid component array with at least 2 components");
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@peerbits/fhir-observation-generator",
+  "version": "1.0.0",
+  "description": "Generate FHIR Observation resources from RPM device readings, with correct LOINC coding and unit conversion",
+  "license": "Apache-2.0",
+  "author": "PeerbitsSolution",
+  "homepage": "https://github.com/PeerbitsSolution/fhir-observation-generator#readme",
+  "bugs": {
+    "url": "https://github.com/PeerbitsSolution/fhir-observation-generator/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build && npm run typecheck && npm test",
+    "prepublishOnly": "npm run lint && npm run prepack"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeerbitsSolution/fhir-observation-generator.git"
+  },
+  "keywords": [
+    "fhir",
+    "rpm",
+    "remote-patient-monitoring",
+    "loinc",
+    "healthcare",
+    "typescript",
+    "ucum",
+    "observation"
+  ],
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}