WIP MITHealthcare Services

FHIR TS Client

TypeScript FHIR R4 client optimized for Angular, type-safe and tree-shakeable

Status
WIP
License
MIT
Category
Healthcare Services
Updated
GitHub source

Project status

Description

FHIR TS Client is a TypeScript utility library for consuming FHIR R4 servers from Angular 21 applications with end-to-end type safety. It fixes a concrete gap in the FHIR JavaScript ecosystem: existing libraries (fhir.js, @types/fhir) are either untyped or not optimized for Angular (no RxJS, no tree-shaking, not SSR-safe). FHIR TS Client offers TypeScript 5.9 type definitions generated from the official R4 StructureDefinitions (Patient, Observation, Condition, Encounter, MedicationStatement, ... up to 145+ Resource types), an HTTP client based on Angular HttpClient with RxJS Observables (no Promises everywhere), runtime validation with Zod for response payloads, ESM tree-shaking optimized to reduce bundle size (you import only the Resources you use, not all 145), SSR-safe support (no window/document references), a Repository pattern for Resource CRUD (find, findById, create, update, delete, search with FHIR criteria), FHIR Bundle pagination handling (automatic next/previous link), typed error handling with the OperationOutcome FHIR Resource. The library is designed as a Quick Win Tier 1 Q2 2026: a focused utility, narrow scope, immediately useful to Angular developers integrating with existing FHIR servers (HAPI FHIR, Smile CDR, Microsoft FHIR Server, Google Cloud Healthcare). MIT license for maximum adoption, no AGPL viral effect, aligned with the 'utility library → MIT' rule of 08_strategia_pubblicazione.md. Test coverage 80%+ with Karma + Jasmine, E2E with Playwright against a dockerized HAPI FHIR server. MkDocs documentation with examples for every Resource type.

Key Features

  • Type-safe FHIR R4 Resources

    Type definitions generate official StructureDefinition R4 content, 145+ resource types, rich IntelliSense in IDE, type narrowing for profiles.

  • Angular Native RXJS Observables

    Client HTTP + Observable pattern, no Promise wrapping, natural integration with async pipe + Signals interoperability (toSignal).

  • Runtime Validation for Zod

    Schema Zod for each resource type, payload validation server response, fail-fast on schema mismatch, type narrowing after validation.

  • Tree-shakable ESM

    Import per-resource (import

  • SSR-safe Angular Universal

    No window/document references, Angular standard, prerender-friendly, tested with Angular Server-Side Rendering 21.

  • Repository pattern for CRUD operations

    Patient Repository Class with find/findById/create/update/delete/search, query builder for FHIR criteria, auto-paginated Bundles.

  • Error Handling Operation Outcome

    Errors typed as OperationOutcome FHIR Resource, severity (error/warning/information), location FHIRPath, structured issue details.

  • Test coverage 80%+

    Karma + Jasmine unit test, Playwright E2E against HAPI FHIR Dockerized, Coverage Report HTML, CI-ready.

Tech stack

  • TypeScript 5.9
  • Angular 21
  • RxJS
  • Zod
  • FHIR R4
  • HAPI FHIR (test server)
  • Karma
  • Jasmine
  • Playwright
  • MkDocs Material

Use cases

  • Angular developers integrating existing frontend with server FHIR R4 (HAPI FHIR, Smile CDR, Microsoft FHIR Server)
  • Team builds patient portals on FHIR standards for enterprise healthcare.
  • Start your digital health startup with type safety and FHIR without writing boilerplate code.
  • System integrator migrating from fhir.js untyped to a type-safe Angular-native library

Road Map

  1. v0.1.0Scheduled

    Core: Patient Profile and Medical Conditions

    • Type definitions: Patient, Observation, and Condition
    • HTTP Client Base with FHIR Interceptor and Content-Type
    • Patient Repository CRUD Base
    • Schema Validation MVP
  2. v0.5.0Scheduled

    Expansion: 30+ Resource Types + Search

    • 30+ resource types with repositories
    • Type-Safe Query Builder for FHIR Search Criteria
    • Automatic bundle pagination
    • Error handling tips for operations.
  3. v1.0.0Scheduled

    Full coverage 145 Resources + Production Ready

    • Type definitions for all 145 R4 Resources
    • Tree shaking optimized ESM.
    • Test coverage 80%+ + Playwright E2E
    • npm publish and complete MkDocs documentation

Who is it for

  • Junior/ Mid-Level Developer
  • For Developer Senior

Quick start

Start the project locally in just a few commands. 

# Quick start (work-in-progress, repo non ancora pubblicato)
# npm install @fedcal/fhir-ts-client
# import { PatientClient } from '@fedcal/fhir-ts-client/patient';
# const client = inject(PatientClient);
# client.findById('123').subscribe(patient => console.log(patient.name));

Contribute to the project

FHIR TS Client is open source. Open an issue, propose a pull request or leave a star on GitHub: every contribution, no matter how small, is welcome.

  • ⭐ Leave a star if it's useful
  • 🐛 Report bugs or suggest features via issue
  • 🔧 Send a pull request with fixes or improvements
  • 📣 Share the project if you find it interesting
Star on GitHubOpen an issuePull request
← ⭐ View on GitHub