# @onivoro/isomorphic-fhir

> A library for transforming FHIR (Fast Healthcare Interoperability Resources) bundles into normalized database tables following Third Normal Form (3NF).

Latest version **24.38.2** (published 2026-05-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install @onivoro/isomorphic-fhir
pnpm add @onivoro/isomorphic-fhir
yarn add @onivoro/isomorphic-fhir
bun add @onivoro/isomorphic-fhir
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 24.38.2 |
| Published | 2026-05-15 |
| First published | 2025-08-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | icedlee337 |

## Links

- npm: https://www.npmjs.com/package/@onivoro/isomorphic-fhir
- Repository: https://github.com/onivoro/monorepo
- Homepage: https://github.com/onivoro/monorepo#readme
- Issues: https://github.com/onivoro/monorepo/issues
- npm.io page: https://npm.io/package/@onivoro/isomorphic-fhir

## Recent versions

- 24.38.2 (latest) — 2026-05-15
- 24.38.1 — 2026-05-12
- 24.38.0 — 2026-05-10
- 24.37.0 — 2026-05-10
- 24.36.0 — 2026-05-09
- 24.35.4 — 2026-05-09
- 24.35.3 — 2026-05-09
- 24.35.2 — 2026-04-27
- 24.35.1 — 2026-04-24
- 24.35.0 — 2026-04-23
- 24.34.2 — 2026-04-22
- 24.34.1 — 2026-04-22
- 24.34.0 — 2026-04-22
- 24.33.21 — 2026-04-19
- 24.33.20 — 2026-04-18
- … 48 more at https://npm.io/package/@onivoro/isomorphic-fhir/versions

## README

# @onivoro/isomorphic-fhir

A library for transforming FHIR (Fast Healthcare Interoperability Resources) bundles into normalized database tables following Third Normal Form (3NF).

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

- 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

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

## Usage

```typescript
import { normalizeFhirBundle } from '@onivoro/isomorphic-fhir';

const fhirBundle = {
  resourceType: 'Bundle',
  type: 'searchset',
  entry: [
    {
      resource: {
        resourceType: 'Patient',
        id: 'patient-123',
        name: [{ family: 'Doe', given: ['John'] }],
        gender: 'male',
        birthDate: '1985-03-15'
      }
    },
    {
      resource: {
        resourceType: 'Observation',
        id: 'observation-456',
        status: 'final',
        code: { coding: [{ code: '8867-4', display: 'Heart rate' }] },
        subject: { reference: 'Patient/patient-123' },
        valueQuantity: { 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
```

## Normalized Tables Generated

The library generates 30+ normalized tables following healthcare data patterns:

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

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

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

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

Run tests with:
```bash
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

## License

This library is licensed under the MIT License. See the LICENSE file in this package for details.

---
_Source: https://npm.io/package/@onivoro/isomorphic-fhir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._