babelfhir-ts 1.0.18 → 1.0.25

package/README.md

@@ -2,12 +2,6 @@
 
 **BabelFHIR-TS** transforms FHIR® StructureDefinitions into production-ready TypeScript code with full type safety and built-in validation. Unlike generic FHIR type definitions, BabelFHIR-TS generates **profile-aware** interfaces that understand your Implementation Guide's constraints, extensions, and slicing rules.
 
-## Why BabelFHIR-TS?
-
-**The FHIR Challenge**: Implementation Guides define strict profiles that constrain base FHIR resources with required or must-support elements, custom extensions, value set bindings, and cardinality rules. Existing TypeScript libraries can't capture these requirements when you need profile-specific types, leading to an overhead when using TypeScript to build apps that interact with FHIR servers.
-
-**The BabelFHIR-TS Solution**: Automatically generates TypeScript interfaces and validation logic directly from StructureDefinition JSON. Your IDE autocompletes required fields, flags missing extensions at compile-time, and validates FHIRPath invariants at runtime.
-
 ### What you get
 
 - **Strongly typed interfaces** that merge profile constraints with base FHIR types (types come from `@types/fhir`)
@@ -19,8 +13,6 @@
 - **Fast and lightweight**—minimal runtime deps; only `fhirpath` is required for validators
 - **Install any FHIR profile as a node module**—use `babelfhir-ts install` to add Implementation Guides directly to your project
 
-Use it to build FHIR-compliant APIs, validate incoming resources against profiles, or generate type-safe client SDKs from Implementation Guides.
-
 ## Installation
 
 Install globally (recommended when using the CLI frequently):
@@ -82,31 +74,32 @@ Generated profile packages installed via `babelfhir-ts install` are published as
   - `@types/fhir` is included as a dependency of the generated package (no extra setup in your app)
   - `fhirpath` is a peer dependency (required only if you use the generated validators/classes)
 
-Install `fhirpath` in your app if you plan to call `.validate()` or use the generated classes:
+Install `fhirpath` in your app if you plan to call `.validate()` or use the generated classes.
 
-```bash
-npm install fhirpath
-```
+### Module resolution
+
+Generated packages use **`moduleResolution: "node16"`** in their `tsconfig.json` to ensure proper ESM compatibility. This works with all modern TypeScript setups including:
+
+- **Node.js 18+** with `"type": "module"` in `package.json`
+- **Bundlers** (Vite, esbuild, Webpack) with ESM output
+- **TypeScript 5.0+** with `node16`, `nodenext`, or `bundler` module resolution
+
+#### FHIR type imports
 
-Import and use:
+Generated code imports base FHIR types from `"fhir/r4"`:
 
 ```ts
-// TypeScript or JavaScript
-import { AdmissionAppointment, AdmissionAppointmentClass } from "pink.admission-generated";
-
-// Types are available automatically via .d.ts
-const appt: AdmissionAppointment = {
-  resourceType: "Appointment",
-  status: "booked",
-  start: "2025-10-23T14:00:00Z",
-};
-
-// Optional helper class + validation
-const instance = AdmissionAppointmentClass.random();
-const result = await new AdmissionAppointmentClass(appt).validate();
-console.log(result.errors, result.warnings);
+import { Appointment, Extension, CodeableConcept } from "fhir/r4";
 ```
 
+Since `@types/fhir` doesn't provide a `package.json` `exports` field, BabelFHIR-TS includes an **ambient module declaration** (`fhir-r4.d.ts`) in every generated package. This declaration file:
+
+- Maps `"fhir/r4"` imports to the actual `@types/fhir` type definitions
+- Enables strict `node16`/`nodenext` module resolution without path configuration
+- Is automatically picked up by TypeScript—no `tsconfig.json` changes needed in your project
+
+> **Note**: If you're using `moduleResolution: "bundler"` in your own project, the ambient module declaration is still compatible and won't cause any issues.
+
 ## CLI reference
 
 ```
@@ -130,72 +123,7 @@ babelfhir-ts [options] [<input> [output]]
 
 - **Directory** – scan all `.tgz`, `.zip`, or `.json` files inside the folder
 - **Archive** – process a FHIR NPM package in `.tgz` or `.zip` format
-- **StructureDefinition JSON** – generate code for a single profile definition
-
-## Generated output
-
-For each StructureDefinition the generator produces:
-
-- `*.ts` interface definitions (extending the canonical FHIR types)
-- `*Class.ts` companions that offer:
-  - constructor helpers (`empty`, `random`, `randomClass`)
-  - deterministic field filling for required and must-support elements
-  - `validate()` that evaluates FHIR invariant expressions via `fhirpath`
-- optional validation parity artefacts when you run the test suite (`npm test validatorParity`)
-
-The validator relies on `fhirpath.evaluate(...)` to enforce profile invariants (including min cardinalities, slices, and custom expressions) without requiring a full FHIR server. It intentionally performs **high-level** checks only: terminology expansion, reference resolution, and other server-backed logic are out of scope, so keep a downstream validator (e.g. the HL7 Java validator CLI) in your QA pipeline for full conformance.
-
-### Example: Generated US Core Encounter Profile
-
-Given the US Core Encounter profile, BabelFHIR-TS generates TypeScript interfaces that capture all must-support elements and profile extensions:
-
-```typescript
-import { Encounter, Meta, Extension, Identifier, Coding, CodeableConcept, 
-         Reference, EncounterParticipant, Period, EncounterHospitalization, 
-         EncounterLocation } from "fhir/r4";
-
-// Extension interface with type-safe URL
-export interface UsCoreInterpreterNeeded extends Extension { 
-  url: 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-interpreter-needed' 
-}
-
-// Profile interface extending base Encounter with must-support constraints
-export interface USCoreEncounterProfile extends Encounter {
-  /** Must Support */
-  meta?: Meta;
-  /** Must Support */
-  identifier?: Identifier[];
-  /** Must Support */
-  class: Coding;
-  /** Must Support */
-  type: CodeableConcept[];
-  /** Must Support */
-  subject: Reference;
-  /** Must Support */
-  participant?: EncounterParticipant[];
-  /** Must Support */
-  period?: Period;
-  /** Must Support */
-  reasonCode?: CodeableConcept[];
-  /** Must Support */
-  reasonReference?: Reference[];
-  /** Must Support */
-  hospitalization?: EncounterHospitalization;
-  /** Must Support */
-  location?: EncounterLocation[];
-  /** Must Support */
-  serviceProvider?: Reference;
-
-  // Typed extension slicing
-  extension?: (Extension | UsCoreInterpreterNeeded)[];
-}
-
-// Generated validator function
-export async function validateUSCoreEncounterProfile(
-  resource: USCoreEncounterProfile
-): Promise<{ errors: string[], warnings: string[] }>;
-
-```
+- **StructureDefinition JSON** – generate code for a single profile definitio
 
 ## Scripts for contributors
 
@@ -210,6 +138,12 @@ export async function validateUSCoreEncounterProfile(
 
 The generator caches downloaded StructureDefinitions and packages inside `.cache/`. When you need a clean run, pass `--no-cache` or manually remove the folder. Temporary downloads land in `.temp-*` directories and are cleaned up automatically.
 
+## Why BabelFHIR-TS?
+
+**The FHIR Challenge**: Implementation Guides define strict profiles that constrain base FHIR resources with required or must-support elements, custom extensions, value set bindings, and cardinality rules. Existing TypeScript libraries can't capture these requirements when you need profile-specific types, leading to an overhead when using TypeScript to build apps that interact with FHIR servers.
+
+**The BabelFHIR-TS Solution**: Automatically generates TypeScript interfaces and validation logic directly from StructureDefinition JSON. Your IDE autocompletes required fields, flags missing extensions at compile-time, and validates FHIRPath invariants at runtime.
+
 ## Limitations
 
 BabelFHIR-TS is a code generation tool that parses FHIR StructureDefinitions and produces TypeScript interfaces and validators. While it handles many common FHIR profiling patterns, there are important limitations to be aware of:
@@ -243,6 +177,7 @@ BabelFHIR-TS is a code generation tool that parses FHIR StructureDefinitions and
 ### Reporting Issues
 
 If you encounter an Implementation Guide that doesn't generate correctly, please [open an issue](https://github.com/quotentiroler/BabelFHIR-ts/issues) with:
+
 - The package name and version
 - The specific StructureDefinition URL
 - Expected vs. actual generated output