@fhirfly-io/fhir-builder

Build valid FHIR R4 resources in TypeScript with a fluent API. No server required. Works entirely offline.

Quick Start

npm install @fhirfly-io/fhir-builder

import { FHIRBuilder } from '@fhirfly-io/fhir-builder';

const fb = new FHIRBuilder();

const patient = fb.patient()
  .name('Jane', 'Doe')
  .dob('1990-01-15')
  .gender('female')
  .mrn('12345', 'http://my-hospital.org/mrn')
  .build();

Why fhir-builder?

• Zero dependencies — no transitive supply chain risk, works offline
• Fluent API — readable, chainable builder pattern for all 13 FHIR R4 resource types
• US Core built-in — race, ethnicity, birth sex extensions constructed correctly out of the box
• Optional enrichment — pair with @fhirfly-io/terminology for display names and crosswalks, or use standalone
• Bundle reference resolution — automatic urn:uuid rewriting for transaction bundles
• Validation on build — build() throws ValidationError with structured errors when required fields are missing

Features

• Fluent builder API for 12+ FHIR R4 resource types
• Bundle builder with automatic reference resolution
• US Core extensions (race, ethnicity, birth sex) built correctly out of the box
• Common code system URIs baked in (LOINC, SNOMED, ICD-10, NDC, RxNorm, CVX, HCPCS, CPT)
• Zero runtime dependencies
• Full TypeScript support with strict types

Supported Resources

| Resource | Builder | Common Code Systems | |----------|---------|-------------------| | Patient | fb.patient() | — | | Observation | fb.observation() | LOINC, UCUM | | Condition | fb.condition() | ICD-10, SNOMED | | MedicationStatement | fb.medicationStatement() | NDC, RxNorm | | MedicationRequest | fb.medicationRequest() | NDC, RxNorm | | AllergyIntolerance | fb.allergyIntolerance() | SNOMED, RxNorm | | Immunization | fb.immunization() | CVX, MVX | | Procedure | fb.procedure() | SNOMED, HCPCS, CPT | | Encounter | fb.encounter() | ActCode | | Coverage | fb.coverage() | — | | ExplanationOfBenefit | fb.explanationOfBenefit() | HCPCS, CPT, NDC | | DiagnosticReport | fb.diagnosticReport() | LOINC | | Bundle | fb.bundle() | — |

Enrichment (Optional)

Resources built with @fhirfly-io/fhir-builder are structurally valid on their own. For richer output — display names, crosswalks, and additional FHIR Codings — pair with @fhirfly-io/terminology:

import { FHIRBuilder } from '@fhirfly-io/fhir-builder';
import { Fhirfly } from '@fhirfly-io/terminology';

const fb = new FHIRBuilder();
const api = new Fhirfly({ apiKey: process.env.FHIRFLY_KEY });

// Look up the NDC code
const ndc = await api.ndc.lookup('0069-0151-01');

// Build an enriched medication statement
const med = fb.medicationStatement()
  .medicationByNDC('0069-0151-01', ndc.display)
  .addCoding(ndc.fhir_coding.rxnorm)
  .status('active')
  .subject(patient)
  .build();

Without enrichment, you get a valid code with system and code. With enrichment, you also get display names and crosswalked codings from RxNorm, SNOMED, and more.

See the Enrichment Guide for detailed examples.

Validation

This library produces valid FHIR R4 JSON by construction. For full profile validation (US Core, IPS, custom IGs), use the HL7 FHIR Validator:

java -jar validator_cli.jar resource.json -version 4.0.1 -ig hl7.fhir.us.core#6.1.0

See the Validation Guide for more examples.

Documentation

• Getting Started
• API Reference
• Enrichment Guide
• Validation Guide

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0. See LICENSE for details.