babelfhir-ts 1.0.17 → 1.0.25

package/README.md

@@ -2,23 +2,16 @@
 
 **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 (built on `@types/fhir`)
+- **Strongly typed interfaces** that merge profile constraints with base FHIR types (types come from `@types/fhir`)
+- **Compiled output by default** — packages ship JavaScript (`.js`) plus TypeScript declarations (`.d.ts`)
 - **Runtime validation** using FHIRPath expressions from the profile—no external validator required for basic checks
 - **Type-safe extension handling** with proper slicing and nested extension support
 - **Random data builders** for testing and development (when class generation is enabled)
 - **Zero manual mapping**—consume any FHIR package or Implementation Guide directly from registries
-- **Fast and lightweight**—pure TypeScript code generation with no runtime dependencies except `fhirpath` for validation
-- **Install any FHIR profile as a node module**—use `babelfhir-ts install` to add Implementation Guides directly to your TypeScript project
-
-Use it to build FHIR-compliant APIs, validate incoming resources against profiles, or generate type-safe client SDKs from Implementation Guides.
+- **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
 
 ## Installation
 
@@ -71,6 +64,42 @@ const patient = USCorePatientClass.random();
 const { errors, warnings } = await patient.validate();
 ```
 
+## Using the generated code in your project
+
+Generated profile packages installed via `babelfhir-ts install` are published as **compiled JavaScript with TypeScript declarations**:
+
+- JavaScript for runtime: `index.js`, `*.js`
+- Type declarations for IDE/TS: `index.d.ts`, `*.d.ts`
+- Dependencies:
+  - `@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.
+
+### 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
+
+Generated code imports base FHIR types from `"fhir/r4"`:
+
+```ts
+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
 
 ```
@@ -94,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
 
@@ -174,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:
@@ -207,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

package/bin/babelfhir-ts.js

@@ -9,24 +9,16 @@ import fs from 'fs';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Use tsx to run the compiled JavaScript (tsx handles ES module resolution better)
-const tsxBin = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
-const tsxPath = join(__dirname, '..', 'node_modules', '.bin', tsxBin);
+// Use node directly to run the compiled JavaScript
 const mainJsPath = join(__dirname, '..', 'out', 'main.js');
 
-// Check if tsx exists
-if (!fs.existsSync(tsxPath)) {
-  console.error('tsx not found. Please install dependencies with: npm install');
-  process.exit(1);
-}
-
 // Check if the compiled file exists
 if (!fs.existsSync(mainJsPath)) {
   console.error('Compiled main.js not found. Please ensure the package was built correctly.');
   process.exit(1);
 }
 
-const child = spawn(tsxPath, [mainJsPath, ...process.argv.slice(2)], {
+const child = spawn('node', [mainJsPath, ...process.argv.slice(2)], {
   stdio: 'inherit',
   cwd: process.cwd(),  // Use the current working directory where the command was invoked
   shell: process.platform === 'win32'