babelfhir-ts 1.0.15 → 1.0.17

package/README.md

@@ -4,9 +4,9 @@
 
 ## Why BabelFHIR-TS?
 
-**The FHIR Challenge**: Implementation Guides define strict profiles (e.g., US Core, German basisprofil) that constrain base FHIR resources with 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.
+**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 must-support fields, flags missing extensions at compile-time, and validates FHIRPath invariants at runtime.
+**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
 
@@ -15,19 +15,11 @@
 - **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.
 
-## Key features
-
-- 🎯 **Profile-first design** – generate interfaces that understand your IG's must-support elements, slices, and extensions
-- ⚙️ **CLI-first workflow** – install globally or run with `npx`; works against package archives, entire directories, or single `.json` profiles
-- ✅ **Built-in validation** – every generated class includes an async `validate()` function that executes profile constraints through FHIRPath *(high-level checks only; see details below)*
-- 🔌 **Extension-aware** – properly types extension slices, nested extensions, and sidecar `_field` elements for primitive extensions
-- 📦 **Package-friendly** – re-embeds generated code back into `.tgz` archives or expands into a target folder for direct consumption
-- 🌐 **Registry integration** – download and process packages directly from Simplifier, HL7, or custom FHIR registries
-- ♻️ **Caching + cleanup** – opt into `--no-cache` to remove temporary `.cache` directories after generation
-
 ## Installation
 
 Install globally (recommended when using the CLI frequently):
@@ -85,18 +77,18 @@ const { errors, warnings } = await patient.validate();
 babelfhir-ts [options] [<input> [output]]
 ```
 
-| Argument / option | Description |
-| ----------------- | ----------- |
-| `<input>` | Directory of FHIR packages/StructureDefinitions, single package (`.tgz`/`.zip`), or single StructureDefinition `.json`. Defaults to `./input` when omitted. |
-| `<output>` | Destination directory or archive. Defaults to `./output` when omitted. |
-| `install` | Downloads, processes, and installs a package as a project dependency. |
-| `--package <pkg@version>` | Fetch a package from a registry and process it without manual download. |
-| `--registry <url>` | Custom registry base URL (default: `https://packages.simplifier.net`). |
-| `--log <level>` | Control logging output: `none` (default), `console`, or `file`. |
-| `--no-cache` | Remove the `.cache` directory once generation completes. |
-| `--no-classes` | Skip emitting helper classes (interfaces & validators only). |
-| `-h, --help` | Print usage help. |
-| `-v, --version` | Print the BabelFHIR-TS version. |
+| Argument / option           | Description                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<input>`                 | Directory of FHIR packages/StructureDefinitions, single package (`.tgz`/`.zip`), or single StructureDefinition `.json`. Defaults to `./input` when omitted. |
+| `<output>`                | Destination directory or archive. Defaults to `./output` when omitted.                                                                                            |
+| `install`                 | Downloads, processes, and installs a package as a project dependency.                                                                                               |
+| `--package <pkg@version>` | Fetch a package from a registry and process it without manual download.                                                                                             |
+| `--registry <url>`        | Custom registry base URL (default:`https://packages.simplifier.net`).                                                                                             |
+| `--log <level>`           | Control logging output:`none` (default), `console`, or `file`.                                                                                                |
+| `--no-cache`              | Remove the `.cache` directory once generation completes.                                                                                                          |
+| `--no-classes`            | Skip emitting helper classes (interfaces & validators only).                                                                                                        |
+| `-h, --help`              | Print usage help.                                                                                                                                                   |
+| `-v, --version`           | Print the BabelFHIR-TS version.                                                                                                                                     |
 
 ### Supported inputs
 
@@ -115,21 +107,113 @@ For each StructureDefinition the generator produces:
   - `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.
+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[] }>;
+
+```
 
 ## Scripts for contributors
 
-| Script | Purpose |
-| ------ | ------- |
-| `npm run generate` | Execute the CLI against the local `input/` folder and refresh `output/`. |
-| `npm run generate:check` | End-to-end check: generate, type-check, and lint the emitted output. |
-| `npm test` | Type-check and run all Vitest suites (coverage enabled). |
-| `npm run download-validator` | Fetch the official HL7 validation jar used for parity testing. |
+| Script                         | Purpose                                                                      |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `npm run generate`           | Execute the CLI against the local `input/` folder and refresh `output/`. |
+| `npm run generate:check`     | End-to-end check: generate, type-check, and lint the emitted output.         |
+| `npm test`                   | Type-check and run all Vitest suites (coverage enabled).                     |
+| `npm run download-validator` | Fetch the official HL7 validation jar used for parity testing.               |
 
 ## Caching notes
 
 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.
 
+## 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:
+
+### Profile Mapping Accuracy
+
+- **Not guaranteed for all IGs**: The generator uses heuristics to interpret StructureDefinition constraints, slicing rules, and extensions. Complex or unusual profiling patterns may not map correctly to TypeScript.
+- **Test before production**: Always validate the generated code against your specific Implementation Guide's examples and test cases. We recommend running the official FHIR validator alongside BabelFHIR-TS in your QA pipeline.
+- **Edge cases**: Rare profiling constructs (deeply nested slicing, conditional constraints, complex discriminators) may generate suboptimal or incomplete types.
+
+### Validation Scope
+
+- **High-level checks only**: The generated `validate()` functions execute FHIRPath expressions from profile invariants but do **not** perform:
+  - Terminology expansion or ValueSet validation
+  - Reference resolution (checking that referenced resources exist)
+  - Full cardinality enforcement for complex slicing scenarios
+  - Server-side business logic or workflow rules
+- **Use the official validator**: For production conformance testing, use the [HL7 FHIR Validator](https://github.com/hapifhir/org.hl7.fhir.core) alongside BabelFHIR-TS.
+
+### TypeScript Limitations
+
+- **Runtime type checking is limited**: TypeScript types are erased at compile time. The generated interfaces provide compile-time safety but cannot enforce constraints at runtime without the validator functions.
+- **Extension slicing**: While the generator creates typed extension interfaces, TypeScript cannot enforce that extension arrays contain exactly the required slices at compile time (this is validated at runtime).
+- **Choice types**: FHIR's `[x]` choice types (e.g., `value[x]`) are represented as union types in TypeScript, which may require runtime type narrowing.
+
+### FHIR Version Support
+
+- **R4 only**: The current version targets FHIR R4. Support for R5, DSTU2, or STU3 is not yet available.
+- **Dependencies**: Generated code depends on `@types/fhir` (R4 definitions) and `fhirpath` (R4 compatible).
+
+### 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
+- Any validation errors or type mismatches
+
+We continuously improve the generator based on real-world IG usage, and your feedback helps make BabelFHIR-TS more robust.
+
 ## License
 
 ISC © Maximilian Nussbaumer

package/out/main.js

@@ -210,6 +210,8 @@ async function run() {
             console.error('     or: babelfhir-ts install ./package.tgz');
             process.exit(1);
         }
+        // Force no-cache for install command
+        flags.noCache = true;
         try {
             let downloadedPath;
             // Check if packageToInstall is a local file path
@@ -234,38 +236,55 @@ async function run() {
             }
             console.log(`✓ Package processed successfully: ${path.basename(outputArchive)}`);
             // Extract the archive to access generated folder
-            console.log(`Extracting package for installation...`);
+            console.log(`Extracting generated code...`);
             const { extract } = await import('tar');
             const extractDir = path.join(process.cwd(), '.temp-install');
             if (!fs.existsSync(extractDir)) {
                 fs.mkdirSync(extractDir, { recursive: true });
             }
             await extract({ cwd: extractDir, file: outputArchive });
-            // Create a tarball from the generated folder
-            const generatedDir = path.join(extractDir, 'generated');
+            // Look for generated folder - could be at root or under 'package' subfolder
+            let generatedDir = path.join(extractDir, 'generated');
+            if (!fs.existsSync(generatedDir)) {
+                generatedDir = path.join(extractDir, 'package', 'generated');
+            }
             if (!fs.existsSync(generatedDir)) {
                 throw new Error('Generated folder not found in package archive');
             }
-            console.log(`Creating package from generated folder...`);
+            // Verify package.json exists
+            const pkgJsonPath = path.join(generatedDir, 'package.json');
+            if (!fs.existsSync(pkgJsonPath)) {
+                throw new Error(`package.json not found in generated folder: ${generatedDir}`);
+            }
+            // Create a tarball from the generated folder to avoid symlink issues on Windows
+            const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+            const packageName = pkgJson.name;
+            console.log(`Creating package tarball for ${packageName}...`);
+            // Use npm pack to create a proper tarball
             const { create } = await import('tar');
-            const generatedTarball = path.join(process.cwd(), `${baseName}-generated.tgz`);
+            const tarballName = `${packageName.replace(/[@/]/g, '-')}.tgz`;
+            const tarballPath = path.join(process.cwd(), tarballName);
+            // Create tarball from the generated directory
             await create({
                 gzip: true,
-                file: generatedTarball,
-                cwd: generatedDir
-            }, ['.']);
-            // Install the generated tarball with npm
-            await npmInstall(generatedTarball);
-            // Clean up extraction directory and archives
+                file: tarballPath,
+                cwd: path.dirname(generatedDir)
+            }, [path.basename(generatedDir)]);
+            console.log(`Installing ${packageName}...`);
+            // Install from the tarball (this creates a proper copy, not a symlink)
+            await npmInstall(tarballPath);
+            // Clean up temporary files
             console.log(`Cleaning up temporary files...`);
             if (fs.existsSync(extractDir)) {
                 fs.rmSync(extractDir, { recursive: true, force: true });
             }
             if (fs.existsSync(outputArchive)) {
                 fs.unlinkSync(outputArchive);
+                console.log(`✓ Removed ${path.basename(outputArchive)}`);
             }
-            if (fs.existsSync(generatedTarball)) {
-                fs.unlinkSync(generatedTarball);
+            if (fs.existsSync(tarballPath)) {
+                fs.unlinkSync(tarballPath);
+                console.log(`✓ Removed ${path.basename(tarballPath)}`);
             }
             if (flags.noCache) {
                 cleanupCache();
@@ -274,7 +293,7 @@ async function run() {
             return;
         }
         catch (error) {
-            // Clean up temp directory and archive on error
+            // Clean up temporary files on error
             const tempDir = path.join(process.cwd(), '.temp-download');
             if (fs.existsSync(tempDir)) {
                 fs.rmSync(tempDir, { recursive: true, force: true });
@@ -283,6 +302,14 @@ async function run() {
             if (fs.existsSync(extractDir)) {
                 fs.rmSync(extractDir, { recursive: true, force: true });
             }
+            // Clean up any leftover archive
+            const baseName = packageToInstall.includes('@')
+                ? packageToInstall.replace('@', '-').replace(/\//g, '-')
+                : path.basename(packageToInstall, path.extname(packageToInstall));
+            const outputArchive = path.join(process.cwd(), `${baseName}.with-generated.tgz`);
+            if (fs.existsSync(outputArchive)) {
+                fs.unlinkSync(outputArchive);
+            }
             console.error(`Error: ${error.message}`);
             process.exit(1);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babelfhir-ts",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4 StructureDefinitions (profiles) directly inside package archives.",
   "type": "module",
   "main": "out/main.js",