@ufbfung/fhir-types

Minimal, hand-rolled HL7 FHIR R4 TypeScript types.

This package intentionally starts small and dependency-free, focusing on a clean, ergonomic type surface that can grow incrementally over time. The long-term goal is to support optional, transparent code generation — without sacrificing readability or control.

📓 See CHANGELOG.md for release notes and version history.

Installation

npm install @ufbfung/fhir-types

Usage

import type {
  Patient,
  Observation,
  Condition,
  AllergyIntolerance,
  Practitioner,
} from "@ufbfung/fhir-types";

const patient: Patient = {
  resourceType: "Patient",
  id: "123",
};

const observation: Observation = {
  resourceType: "Observation",
  status: "final",
  code: { text: "Heart rate" },
  valueQuantity: { value: 72, unit: "beats/min" },
};

All resources use resourceType as a discriminant, making them safe and ergonomic to use in unions, type guards, and switch statements.

Supported Resources

This package is intentionally constrained. Only explicitly supported resources are exported and included in the public API.

Currently supported:

• Patient
• Observation
• Condition
• AllergyIntolerance
• Practitioner

These are also exposed via:

• SUPPORTED_RESOURCE_TYPES
• SupportedResourceType
• SupportedResource
• Runtime guards:
  • isSupportedResourceType
  • isSupportedResource
  • assertSupportedResource

This design allows downstream systems (e.g. FHIR servers, validators, ingestion pipelines) to fail fast when encountering unsupported resource types.

Profile-Aware Types (US Core)

In addition to base FHIR R4 resources, this package includes profile-aware types for common U.S. implementation guides.

US Core Patient

The package provides a strict USCorePatient type aligned with US Core Patient (STU6.1).

This type enforces key cardinality constraints at compile time:

• identifier → required, non-empty (1..*)
• name → required, non-empty (1..*)
• gender → required (1..1)
• meta.profile → required, must include the US Core Patient canonical URL

Example:

import type { USCorePatient } from "@ufbfung/fhir-types";

const patient: USCorePatient = {
  resourceType: "Patient",
  meta: {
    profile: ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"],
  },
  identifier: [{ system: "urn:mrn", value: "12345" }],
  name: [{ family: "Doe", given: ["Jane"] }],
  gender: "female",
};

If any required fields are missing, TypeScript will fail at author time — similar to how SUSHI validates FHIR instances against profiles.

Draft Construction Pattern

To support ergonomic, incremental object construction, a DraftUSCorePatient type is also provided.

This pattern allows developers to build partial objects and then explicitly confirm conformance when ready.

import type {
  DraftUSCorePatient,
  USCorePatient,
} from "@ufbfung/fhir-types";

const draft: DraftUSCorePatient = {
  resourceType: "Patient",
};

draft.identifier = [{ value: "12345" }];
draft.name = [{ family: "Doe", given: ["Jane"] }];
draft.gender = "female";
draft.meta = {
  profile: ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"],
};

const finalPatient = draft as USCorePatient;

Future versions may optionally replace this assertion with runtime validation.

Shared Datatypes

A minimal but practical set of common FHIR datatypes is included, aligned with the FHIR specification:

• CodeableConcept
• Coding
• Identifier
• HumanName
• Reference
• Quantity
• Period
• Extension
• Element
• Primitive wrappers (e.g. FhirString, FhirDate, etc.)

These datatypes are reused across all supported resources.

Design Principles

• Types-first, runtime-light
• No required runtime dependencies
• Incremental growth over full spec coverage
• Clear, auditable type definitions
• Generator-friendly file structure
• Explicitly scoped support
• Static enforcement of simple profile constraints (cardinality + profile identity)

This is not a full FHIR SDK. It is a deliberately minimal foundation designed to grow alongside real usage, not ahead of it.

Roadmap (High-Level)

Planned or considered additions:

• More core R4 resources
• AnySupportedResource discriminated unions
• Explicit supported-version metadata
• Optional schema-driven generator
• Additional profile / Implementation Guide–aware types (e.g. US Core)
• Optional future runtime validators (e.g. invariants, slicing) layered on top

Breaking changes will be versioned conservatively.

FHIR Version

• HL7 FHIR R4 (4.0.1)

License

MIT