@onivoro/isomorphic-fhir 24.38.2 → 25.0.2

package/README.md

@@ -1,44 +1,53 @@
 # @onivoro/isomorphic-fhir
 
-A library for transforming FHIR (Fast Healthcare Interoperability Resources) bundles into normalized database tables following Third Normal Form (3NF).
+A library for flattening FHIR (Fast Healthcare Interoperability Resources) R4 bundles into a set of relational-style tables (plain arrays of row objects), plus TypeScript interfaces for the supported FHIR resources and the generated tables.
+
+## Installation
+
+```bash
+npm install @onivoro/isomorphic-fhir
+```
 
 ## Overview
 
-This library takes FHIR R4 bundles containing healthcare resources and transforms them into a set of normalized tables that can be used to populate a relational database. The transformation process:
+`normalizeFhirBundle` walks a bundle's entries and splits each supported resource into a main row plus child rows for its repeating and nested parts. Along the way it:
 
-- Eliminates data redundancy across FHIR resources
-- Ensures referential integrity between healthcare entities
-- Creates proper foreign key relationships
-- Generates unique IDs for normalized records
-- Preserves FHIR resource relationships through reference tables
-- Handles complex nested structures like CodeableConcepts and Extensions
+- Generates a new UUID (v4) `id` for every row and links child rows to their parent through that id (e.g. `patientNames[].patientId`, `codings[].codeableConceptId`)
+- Keeps the original FHIR `id` in `resourceId` on main rows
+- Stores shared data types (addresses, telecoms, CodeableConcepts and codings, notes, attachments, references) in generic tables keyed by `resourceType` + `resourceId` (+ `fieldName` where relevant)
+- Copies FHIR reference strings (e.g. `"Patient/patient-123"`) as-is into `*Reference` columns and the `references` table; references are not resolved to generated ids
+- Stamps rows with `createdAt` (and `updatedAt` on main rows) set to the time of normalization
+
+It does not deduplicate rows (two identical addresses produce two `addresses` rows), validate resources, or talk to a database.
 
 ## Supported FHIR Resources
 
-The library currently supports normalization of the following FHIR R4 resources:
-
-- **Patient**: Demographics, identifiers, names, contacts, addresses
-- **Practitioner**: Healthcare providers, qualifications, contact information
-- **Organization**: Healthcare organizations, types, contact details
-- **Encounter**: Healthcare encounters, participants, locations
-- **Condition**: Medical conditions, clinical status, evidence
-- **Observation**: Clinical measurements, vital signs, lab results
-- **MedicationRequest**: Medication prescriptions, dosage instructions
-- **Procedure**: Medical procedures, performers, outcomes
-- **Immunization**: Vaccinations, reactions, protocols
-- **AllergyIntolerance**: Allergies, reactions, manifestations
-- **DiagnosticReport**: Diagnostic test results, conclusions
-- **Location**: Healthcare facilities, positions, contact info
-- **Appointment**: Scheduled appointments, participants
-- **CareTeam**: Care team members, roles, periods
-- **CarePlan**: Care plans, activities, goals
+Entries whose `resourceType` is one of the following are normalized; any other resource type only produces a `bundleEntries` row.
+
+- **Patient**: demographics, identifiers, names, contacts (with their telecoms/address), addresses, telecoms, general practitioners, photos, marital status
+- **Practitioner**: demographics, qualifications, identifiers, names, telecoms, addresses, photos, communication languages
+- **Organization**: types, identifiers, telecoms, addresses, endpoints
+- **Encounter**: class, status, period, participants, subject, identifiers, basedOn, appointments, reasons
+- **Condition**: clinical/verification status, code, category, body site, notes
+- **Observation**: code, value, components, category, interpretation, notes, performers, related references
+- **MedicationRequest**: medication, dosage instructions (first dose/rate), category, reasons, notes, related references
+- **Procedure**: performers, reasons, body site, complications, follow-up, notes, used items
+- **Immunization**: vaccine, dose, site/route, reasons, subpotent reasons, program eligibility, notes
+- **AllergyIntolerance**: reactions, manifestations, categories, notes
+- **DiagnosticReport**: result references, category, performers, conclusion codes, presented forms
+- **Location**: position, type, aliases, telecoms, address, endpoints
+- **Appointment**: participants, reasons, slots, related references
+- **CareTeam**: participants, category, reasons, managing organizations, telecoms, notes
+- **CarePlan**: activities, category, goals, care teams and other references, notes
+
+Sub-structures not listed (for example `Condition.evidence`, `Encounter.location`, `Immunization.reaction`/`protocolApplied`, `Patient.communication`) are typed but not normalized.
 
 ## Usage
 
 ```typescript
-import { normalizeFhirBundle } from '@onivoro/isomorphic-fhir';
+import { normalizeFhirBundle, IFhirBundle } from '@onivoro/isomorphic-fhir';
 
-const fhirBundle = {
+const fhirBundle: IFhirBundle = {
   resourceType: 'Bundle',
   type: 'searchset',
   entry: [
@@ -48,8 +57,8 @@ const fhirBundle = {
         id: 'patient-123',
         name: [{ family: 'Doe', given: ['John'] }],
         gender: 'male',
-        birthDate: '1985-03-15'
-      }
+        birthDate: '1985-03-15',
+      },
     },
     {
       resource: {
@@ -58,132 +67,88 @@ const fhirBundle = {
         status: 'final',
         code: { coding: [{ code: '8867-4', display: 'Heart rate' }] },
         subject: { reference: 'Patient/patient-123' },
-        valueQuantity: { value: 72, unit: 'beats/min' }
-      }
-    }
-  ]
+        value: { value: 72, unit: 'beats/min' },
+      },
+    },
+  ],
 };
 
 const normalizedData = normalizeFhirBundle(fhirBundle);
 
-// normalizedData contains normalized tables:
-console.log(normalizedData.patients);      // Patient demographics
-console.log(normalizedData.patientNames);  // Patient names (separate table)
-console.log(normalizedData.observations);  // Clinical observations
-console.log(normalizedData.addresses);     // Addresses (deduplicated)
-console.log(normalizedData.telecoms);      // Contact points
-console.log(normalizedData.references);    // Resource relationships
+console.log(normalizedData.bundles); // one row for the bundle
+console.log(normalizedData.patients); // patient demographics
+console.log(normalizedData.patientNames); // patient names, linked by patientId
+console.log(normalizedData.observations); // valueType 'Quantity', valueNumber 72, valueString 'beats/min'
+```
+
+### Choice-type (`[x]`) fields
+
+The input interfaces model FHIR choice-type elements with a single un-suffixed property, and the normalizer only reads that property. Use `value`, `effective`, `onset`, `abatement`, `deceased`, `multipleBirth`, `medication`, `performed`, `occurrence`, `asNeeded` and `scheduled` rather than the wire-format names such as `valueQuantity`, `effectiveDateTime` or `medicationCodeableConcept`. Raw FHIR JSON from a server must be mapped to these names first, or those fields are left empty.
+
+## API
+
+### `normalizeFhirBundle(bundle: IFhirBundle): INormalizedFhirData`
+
+Returns an `INormalizedFhirData` object with one array per table. Every array is always present (empty when there is nothing to put in it).
+
+### Types
+
+- **Input interfaces** (`fhir-resources.interface`): `IFhirBundle`, `IFhirBundleEntry`, the `IFhirResource` union, one interface per supported resource (`IFhirPatient`, `IFhirPractitioner`, `IFhirOrganization`, `IFhirEncounter`, `IFhirCondition`, `IFhirObservation`, `IFhirMedicationRequest`, `IFhirProcedure`, `IFhirImmunization`, `IFhirAllergyIntolerance`, `IFhirDiagnosticReport`, `IFhirLocation`, `IFhirAppointment`, `IFhirCareTeam`, `IFhirCarePlan`), common data types (`IFhirIdentifier`, `IFhirHumanName`, `IFhirContactPoint`, `IFhirAddress`, `IFhirCodeableConcept`, `IFhirCoding`, `IFhirReference`, `IFhirPeriod`, `IFhirQuantity`, `IFhirRange`, `IFhirAge`, `IFhirAttachment`, `IFhirAnnotation`, `IFhirDuration`, `IFhirDateTime`, `IFhirDosage`, `IFhirTiming`, `IFhirTimingRepeat`, `IFhirRatio`, `IFhirDosageDoseAndRate`) and backbone elements (e.g. `IFhirPatientContact`, `IFhirEncounterParticipant`, `IFhirObservationComponent`, `IFhirCarePlanActivityDetail`).
+- **Output interfaces** (`fhir-normalized-tables.interface`): `INormalizedFhirData` and one row interface per table, named `I<Table>Table` (e.g. `IPatientTable`, `IObservationComponentTable`, `ICodingTable`, `IReferenceTable`, `IBundleEntryTable`).
+
+```typescript
+import { INormalizedFhirData, IPatientTable } from '@onivoro/isomorphic-fhir';
+
+function patientsBornBefore(data: INormalizedFhirData, isoDate: string): IPatientTable[] {
+  return data.patients.filter((p) => p.birthDate && p.birthDate < isoDate);
+}
 ```
 
 ## Normalized Tables Generated
 
-The library generates 30+ normalized tables following healthcare data patterns:
+`INormalizedFhirData` has 39 tables.
 
 ### Core Resource Tables
-- **bundles**: FHIR bundle metadata
-- **bundleEntries**: Bundle entry information
-- **patients**: Patient demographics
-- **practitioners**: Healthcare provider information
-- **organizations**: Healthcare organizations
-- **encounters**: Healthcare encounters
-- **conditions**: Medical conditions and diagnoses
-- **observations**: Clinical measurements and findings
-- **medicationRequests**: Medication prescriptions
-- **procedures**: Medical procedures performed
-- **immunizations**: Vaccination records
-- **allergyIntolerances**: Allergy and intolerance information
-- **diagnosticReports**: Diagnostic test reports
-- **locations**: Healthcare facility information
-- **appointments**: Scheduled appointments
-- **careTeams**: Care team compositions
-- **carePlans**: Patient care plans
+
+- **bundles**: bundle metadata (`type`, `timestamp`, `total`)
+- **bundleEntries**: one row per entry (`fullUrl`, search mode/score, `resourceType`, `resourceId`)
+- **patients**, **practitioners**, **organizations**, **encounters**, **conditions**, **observations**, **medicationRequests**, **procedures**, **immunizations**, **allergyIntolerances**, **diagnosticReports**, **locations**, **appointments**, **careTeams**, **carePlans**: one row per resource; coded fields are flattened to the first coding's code/display
 
 ### Relationship and Detail Tables
-- **patientIdentifiers**: Patient identifier systems
-- **patientNames**: Patient name variations
-- **patientContacts**: Emergency/family contacts
-- **practitionerQualifications**: Provider credentials
-- **organizationTypes**: Organization classifications
-- **encounterParticipants**: Encounter participants
-- **observationComponents**: Multi-component observations
-- **medicationDosages**: Medication dosing instructions
-- **procedurePerformers**: Procedure performers
-- **allergyReactions**: Allergic reactions
-- **allergyManifestations**: Reaction manifestations
-- **diagnosticReportResults**: Report result references
-- **appointmentParticipants**: Appointment participants
-- **careTeamParticipants**: Care team member details
-- **carePlanActivities**: Care plan activity details
+
+- **patientIdentifiers**, **patientNames**, **patientContacts**
+- **practitionerQualifications**
+- **organizationTypes** (first coding of each type)
+- **encounterParticipants**
+- **observationComponents**
+- **medicationDosages**
+- **procedurePerformers**
+- **allergyReactions**, **allergyManifestations**
+- **diagnosticReportResults**
+- **appointmentParticipants**
+- **careTeamParticipants**
+- **carePlanActivities**
 
 ### Common Data Type Tables
-- **addresses**: Physical addresses (deduplicated)
-- **telecoms**: Contact points (phone, email, etc.)
-- **codeableConcepts**: Coded concepts with text
-- **codings**: Individual coding systems
-- **notes**: Annotations and comments
-- **attachments**: Binary attachments and documents
-- **references**: Resource references and relationships
-
-## Key Features
-
-### FHIR Compliance
-- Full FHIR R4 resource support
-- Proper handling of FHIR data types (CodeableConcept, Reference, etc.)
-- Preservation of clinical terminology and coding systems
-- Support for complex nested structures
-
-### Data Integrity
-- Referential integrity through normalized foreign keys
-- Unique constraint handling for identifiers
-- Proper temporal data handling (effective periods, timestamps)
-- Clinical status and verification status preservation
-
-### Healthcare-Specific Patterns
-- Support for multiple identifier systems per resource
-- Proper handling of clinical hierarchies (conditions, observations)
-- Care team and care plan relationship modeling
-- Medication dosing and administration patterns
-- Allergy and adverse reaction tracking
-
-### Performance Optimized
-- Efficient deduplication of common entities (addresses, codings)
-- Bulk insert-friendly table structures
-- Indexed foreign key relationships
-- Minimal data redundancy
 
-## Testing
+- **addresses**: addresses of any resource (`line` joined with `\n`)
+- **telecoms**: contact points
+- **codeableConcepts**: one row per CodeableConcept, with `fieldName` (e.g. `category`, `reasonCode`)
+- **codings**: codings of each CodeableConcept, linked by `codeableConceptId`
+- **notes**: annotations
+- **attachments**: photos and presented forms
+- **references**: references, keyed by `fieldName` (e.g. `subject`, `basedOn`, `performer`)
+
+Identifiers of resources other than Patient are stored in **references** with `fieldName: 'identifier'` (the identifier's `type` goes to **codeableConcepts** as `identifier.type`). Practitioner names are stored as text in **codeableConcepts** with `fieldName: 'name'`: the name's `text`, or else its prefix, given, family and suffix parts joined with spaces, skipping missing parts. Patient contact names follow the same rule (`text`, or else given and family). The generic tables' `resourceId` is the generated row id of the owning record, not the FHIR id.
 
-The library includes comprehensive tests covering:
-- Complete FHIR bundle normalization
-- Individual resource type processing
-- Complex nested structure handling
-- Reference relationship preservation
-- Edge cases and error conditions
+## Testing
 
-Run tests with:
 ```bash
-nx test lib-isomorphic-fhir
+npx nx test lib-isomorphic-fhir
 ```
 
-## FHIR Standards Compliance
-
-This library is designed to work with FHIR R4 resources and follows HL7 FHIR standards for:
-- Resource structure and cardinality
-- Data type handling and validation
-- Reference resolution and integrity
-- Clinical terminology bindings
-- Healthcare workflow patterns
-
-## Use Cases
-
-Perfect for:
-- **EHR Data Warehousing**: Normalize FHIR data for analytics
-- **Clinical Data Lakes**: Store FHIR resources in relational format
-- **Interoperability Solutions**: Transform FHIR for legacy systems
-- **Healthcare Analytics**: Enable SQL-based analysis of clinical data
-- **Compliance Reporting**: Structure data for regulatory requirements
-- **Research Databases**: Prepare clinical data for research queries
+The project also contains integration specs that call the public HAPI FHIR server; see `INTEGRATION_TESTS.md` in the repository.
 
 ## License
 
-This library is licensed under the MIT License. See the LICENSE file in this package for details.
+This library is licensed under the MIT License. See the LICENSE file in this package for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onivoro/isomorphic-fhir",
-  "version": "24.38.2",
+  "version": "25.0.2",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -10,9 +10,8 @@
     "url": "https://github.com/onivoro/monorepo.git"
   },
   "dependencies": {
-    "@nestjs/swagger": "*",
     "tslib": "^2.3.0",
-    "uuid": "*"
+    "uuid": "^9.0.1"
   },
   "files": [
     "**/*.js",