babelfhir-ts 1.0.25 → 1.0.27

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Maximilian Nussbaumer
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,5 +1,10 @@
 # BabelFHIR-TS
 
+[![npm version](https://img.shields.io/npm/v/babelfhir-ts.svg)](https://www.npmjs.com/package/babelfhir-ts)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
+
 **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.
 
 ### What you get
@@ -49,7 +54,7 @@ Download and process a package directly from a registry (defaults to `https://pa
 babelfhir-ts --package hl7.fhir.us.core@8.0.0
 ```
 
-Install a processed package into your current project:
+Download, pocess and install a processed package into your current project:
 
 ```bash
 babelfhir-ts install hl7.fhir.us.core@8.0.0
@@ -78,11 +83,11 @@ Install `fhirpath` in your app if you plan to call `.validate()` or use the gene
 
 ### Module resolution
 
-Generated packages use **`moduleResolution: "node16"`** in their `tsconfig.json` to ensure proper ESM compatibility. This works with all modern TypeScript setups including:
+Generated packages work with all modern TypeScript setups:
 
 - **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
+- **TypeScript 5.0+** with any module resolution (`node16`, `nodenext`, or `bundler`)
 
 #### FHIR type imports
 
@@ -92,13 +97,13 @@ Generated code imports base FHIR types from `"fhir/r4"`:
 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:
+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. The generated `index.d.ts` references this 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
+```ts
+/// <reference path="./fhir-r4.d.ts" />
+```
 
-> **Note**: If you're using `moduleResolution: "bundler"` in your own project, the ambient module declaration is still compatible and won't cause any issues.
+This ensures TypeScript can resolve `fhir/r4` imports automatically without any configuration in your project's `tsconfig.json`.
 
 ## CLI reference
 
@@ -188,3 +193,18 @@ We continuously improve the generator based on real-world IG usage, and your fee
 ## License
 
 ISC © Maximilian Nussbaumer
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## Security
+
+For security issues, please see [SECURITY.md](SECURITY.md) for our security policy and how to report vulnerabilities.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/babelfhir-ts)
+- [GitHub repository](https://github.com/quotentiroler/BabelFHIR-ts)
+- [Issue tracker](https://github.com/quotentiroler/BabelFHIR-ts/issues)
+- [Changelog](CHANGELOG.md)

package/out/generator/importManager.js

@@ -0,0 +1,252 @@
+import fhirInterfaceNames from "./fhirInterfaces.json" with { type: 'json' };
+import { sanitizeIdentifier } from './utils.js';
+/**
+ * Manages TypeScript import statements for generated FHIR interfaces.
+ * Handles three types of imports:
+ * 1. FHIR base types from '@types/fhir' (via 'fhir/r4')
+ * 2. Custom local types (other generated profiles in the same package)
+ * 3. External profiled types (to be fetched/generated separately)
+ * 4. Path-based imports (custom relative paths, e.g., ValueSets in subdirectories)
+ */
+export class ImportManager {
+    fhirImports = new Set();
+    customImports = new Set();
+    pathBasedImports = new Map(); // typeName -> relativePath
+    localInterfaceNames;
+    existingProfiles;
+    externalProfiles = new Map();
+    constructor(localInterfaceNames, existingProfiles) {
+        this.localInterfaceNames = localInterfaceNames;
+        this.existingProfiles = existingProfiles;
+    }
+    /**
+     * Adds a type to the appropriate import category.
+     *
+     * @param typeName - The TypeScript type name to import
+     * @param profileUrl - Optional profile URL for external profiles
+     * @param baseType - Optional base type for external profiles
+     * @param isFhirBase - Whether the base type is a FHIR type
+     */
+    addType(typeName, profileUrl, baseType, isFhirBase = false) {
+        if (!typeName)
+            return;
+        // Check if it's a nested interface of the current profile (defined locally in this file)
+        if (this.localInterfaceNames.has(typeName)) {
+            // Don't add to imports - defined in the same file
+            return;
+        }
+        // Check if it's a known FHIR type from @types/fhir
+        if (this.isFhirType(typeName)) {
+            this.fhirImports.add(typeName);
+            return;
+        }
+        // Check if it exists in our generated profiles/types
+        if (this.existingProfiles?.has(typeName)) {
+            this.customImports.add(typeName);
+            return;
+        }
+        // Check if this is a primitive type that shouldn't be fetched
+        if (this.isPrimitiveLikeType(typeName)) {
+            return;
+        }
+        // Add to custom imports (will be generated or fetched)
+        this.customImports.add(typeName);
+        // Track as external profile if we have profile metadata
+        if (profileUrl || baseType) {
+            this.registerExternalProfile(typeName, profileUrl, baseType, isFhirBase);
+        }
+    }
+    /**
+     * Registers an external profile that needs to be fetched or generated.
+     */
+    registerExternalProfile(rawTypeName, profileUrl, baseType, isFhirBase = false) {
+        if (!rawTypeName)
+            return;
+        const sanitizedTypeName = sanitizeIdentifier(rawTypeName);
+        const resolvedProfileUrl = profileUrl && profileUrl.length > 0
+            ? profileUrl
+            : `http://hl7.org/fhir/StructureDefinition/${sanitizedTypeName}`;
+        let meta = this.externalProfiles.get(sanitizedTypeName);
+        if (!meta) {
+            meta = { profileUrl: resolvedProfileUrl, baseTypes: new Map() };
+            this.externalProfiles.set(sanitizedTypeName, meta);
+        }
+        else if (profileUrl && profileUrl.length > 0 &&
+            meta.profileUrl.startsWith('http://hl7.org/fhir/StructureDefinition/')) {
+            // Update with more specific profile URL
+            meta.profileUrl = profileUrl;
+        }
+        // Track base type relationship
+        if (baseType && baseType !== 'any') {
+            const sanitizedBase = sanitizeIdentifier(baseType);
+            const existing = meta.baseTypes.get(sanitizedBase);
+            if (!existing) {
+                meta.baseTypes.set(sanitizedBase, { isFhir: isFhirBase });
+            }
+            else if (isFhirBase && !existing.isFhir) {
+                existing.isFhir = true;
+            }
+        }
+    }
+    /**
+     * Gets all registered external profile references.
+     */
+    getExternalProfiles() {
+        return this.externalProfiles;
+    }
+    /**
+     * Generates import statement lines for FHIR and custom types.
+     */
+    generateImportStatements() {
+        const statements = [];
+        // FHIR imports from 'fhir/r4'
+        if (this.fhirImports.size > 0) {
+            const sortedFhirImports = Array.from(this.fhirImports).sort();
+            statements.push(`import { ${sortedFhirImports.join(', ')} } from "fhir/r4";`);
+        }
+        // Path-based imports (e.g., ValueSets from subdirectories)
+        const sortedPathBasedImports = Array.from(this.pathBasedImports.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+        for (const [typeName, relativePath] of sortedPathBasedImports) {
+            statements.push(`import { ${typeName} } from "${relativePath}";`);
+        }
+        // Custom local imports
+        const sortedCustomImports = Array.from(this.customImports).sort();
+        for (const type of sortedCustomImports) {
+            statements.push(`import { ${type} } from "./${type}";`);
+        }
+        return statements.join('\n');
+    }
+    /**
+     * Prunes unused imports from generated code.
+     * Removes import statements for types that aren't actually used.
+     */
+    pruneUnusedImports(output) {
+        // Prune unused FHIR imports
+        output = output.replace(/import \{([^}]+)\} from "fhir\/r4";?/g, (full, inside) => {
+            const used = [];
+            const specifiers = inside.split(',').map((s) => s.trim()).filter(Boolean);
+            for (const name of specifiers) {
+                const re = new RegExp(`\\b${name}\\b`);
+                if (re.test(output.replace(full, ''))) {
+                    used.push(name);
+                }
+            }
+            return used.length ? `import { ${used.join(', ')} } from "fhir/r4";` : '';
+        });
+        // Prune unused custom imports (both path-based and standard custom imports)
+        output = output.replace(/import \{([^}]+)\} from "\.\/(.+?)";?/g, (full, inside, path) => {
+            const used = [];
+            const specifiers = inside.split(',').map((s) => s.trim()).filter(Boolean);
+            for (const name of specifiers) {
+                const re = new RegExp(`\\b${name}\\b`);
+                if (re.test(output.replace(full, ''))) {
+                    used.push(name);
+                }
+            }
+            return used.length ? `import { ${used.join(', ')} } from "./${path}";` : '';
+        });
+        // Remove now-empty import lines and collapse multiple blank lines
+        output = output.replace(/^\s*import \{\s*\}.*$/mg, '').replace(/\n{3,}/g, '\n\n');
+        return output;
+    }
+    /**
+     * Reorganizes imports to prefer local types over FHIR types where appropriate.
+     * Moves locally-generated types from fhir/r4 imports to local imports.
+     */
+    reorganizeImports(output) {
+        if (!this.existingProfiles || this.existingProfiles.size === 0) {
+            return output;
+        }
+        // Extract ALL types from fhir/r4 imports (there may be multiple import lines)
+        const fhirImportRegex = /import \{([^}]+)\} from "fhir\/r4";/g;
+        const allFhirTypes = [];
+        let match;
+        while ((match = fhirImportRegex.exec(output)) !== null) {
+            const types = match[1].split(',').map(t => t.trim()).filter(Boolean);
+            allFhirTypes.push(...types);
+        }
+        if (allFhirTypes.length === 0) {
+            return output;
+        }
+        const localTypes = [];
+        const remainingFhirTypes = [];
+        for (const typeName of allFhirTypes) {
+            if (this.existingProfiles.has(typeName)) {
+                // Never move FhirResource to local imports; it must stay from fhir/r4
+                if (typeName !== 'FhirResource') {
+                    localTypes.push(typeName);
+                }
+                else {
+                    remainingFhirTypes.push(typeName);
+                }
+            }
+            else {
+                remainingFhirTypes.push(typeName);
+            }
+        }
+        // Remove ALL old fhir/r4 import lines
+        output = output.replace(/import \{[^}]+\} from "fhir\/r4";\n?/g, '');
+        // Add back the imports at the top
+        let newImports = '';
+        if (remainingFhirTypes.length > 0) {
+            newImports += `import { ${remainingFhirTypes.join(', ')} } from "fhir/r4";\n`;
+        }
+        for (const localType of localTypes) {
+            newImports += `import { ${localType} } from "./${localType}";\n`;
+        }
+        // Insert new imports after any existing custom imports or at the top
+        if (newImports) {
+            const customImportMatch = output.match(/^(import \{[^}]+\} from "\.\/[^"]+";?\n)+/m);
+            if (customImportMatch) {
+                // Insert after existing custom imports
+                output = output.replace(customImportMatch[0], customImportMatch[0] + newImports);
+            }
+            else {
+                // Insert at the very top
+                output = newImports + output;
+            }
+        }
+        return output;
+    }
+    /**
+     * Checks if a type is a known FHIR type from @types/fhir.
+     */
+    isFhirType(type) {
+        return type === 'FhirResource' || fhirInterfaceNames.includes(type);
+    }
+    /**
+     * Checks if a type name looks like a primitive that shouldn't be imported.
+     */
+    isPrimitiveLikeType(typeName) {
+        const primitiveTypeLowerCase = typeName.toLowerCase();
+        return [
+            'integer', 'unsignedint', 'positiveint', 'decimal', 'boolean', 'string',
+            'base64binary', 'instant', 'date', 'datetime', 'time', 'code', 'oid',
+            'id', 'markdown', 'uri', 'url', 'canonical', 'uuid'
+        ].includes(primitiveTypeLowerCase);
+    }
+    /**
+     * Adds a specific FHIR type to imports.
+     */
+    addFhirType(typeName) {
+        if (this.isFhirType(typeName)) {
+            this.fhirImports.add(typeName);
+        }
+    }
+    /**
+     * Adds a specific custom local type to imports.
+     */
+    addCustomType(typeName) {
+        if (!this.localInterfaceNames.has(typeName)) {
+            this.customImports.add(typeName);
+        }
+    }
+    /**
+     * Adds an import with an explicit relative path (e.g., for ValueSets in subdirectories).
+     * @param typeName - The type name to import
+     * @param relativePath - The relative path without extension (e.g., "./valuesets/ValueSet-Example")
+     */
+    addPathBasedImport(typeName, relativePath) {
+        this.pathBasedImports.set(typeName, relativePath);
+    }
+}

package/out/generator/index.js

@@ -91,6 +91,15 @@ async function compileTypeScriptToJS(dir) {
             }
             catch { /* ignore */ }
             if (code === 0) {
+                // Add triple-slash directive to index.d.ts after compilation
+                const indexDtsPath = path.join(dir, 'index.d.ts');
+                if (fs.existsSync(indexDtsPath)) {
+                    const content = fs.readFileSync(indexDtsPath, 'utf-8');
+                    if (!content.startsWith('/// <reference')) {
+                        const newContent = `/// <reference path="./fhir-r4.d.ts" />\n${content}`;
+                        fs.writeFileSync(indexDtsPath, newContent, 'utf-8');
+                    }
+                }
                 // Remove .ts files after successful compilation
                 const files = fs.readdirSync(dir, { recursive: true, withFileTypes: true });
                 for (const file of files) {
@@ -462,27 +471,13 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         const generatedPackageJsonPath = path.join(outputDir, 'package.json');
         fs.writeFileSync(generatedPackageJsonPath, JSON.stringify(generatedPackageJson, null, 2));
         console.log(`Created package.json in generated folder: ${packageName}-generated@${packageVersion}`);
-        // Create a tsconfig.json for Node16/NodeNext module resolution
-        // This ensures fhir/r4 imports are resolved via the ambient module declaration
-        const generatedTsConfig = {
-            compilerOptions: {
-                moduleResolution: 'node16',
-                module: 'Node16',
-                target: 'ES2020',
-                strict: false,
-                skipLibCheck: true,
-                esModuleInterop: true
-            }
-        };
-        const generatedTsConfigPath = path.join(outputDir, 'tsconfig.json');
-        fs.writeFileSync(generatedTsConfigPath, JSON.stringify(generatedTsConfig, null, 2));
         // Copy fhir-r4.d.ts ambient module declaration to support fhir/r4 imports
         // The file is at out/fhir-r4.d.ts (root of compiled output)
         const fhirR4DtsSource = path.join(path.dirname(path.dirname(fileURLToPath(import.meta.url))), 'fhir-r4.d.ts');
         const fhirR4DtsDest = path.join(outputDir, 'fhir-r4.d.ts');
         if (fs.existsSync(fhirR4DtsSource)) {
             fs.copyFileSync(fhirR4DtsSource, fhirR4DtsDest);
-            console.log('Copied fhir-r4.d.ts ambient module declaration for Node16/NodeNext support');
+            console.log('Copied fhir-r4.d.ts ambient module declaration');
         }
         else {
             console.warn('Warning: fhir-r4.d.ts not found. Run: npm run generate:fhir-module');
@@ -523,6 +518,7 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         fs.mkdirSync(outputDir, { recursive: true });
     // Load ValueSets from the directory
     const valueSets = readValueSetsFromDir(inputDir);
+    const valueSetCodesMap = readValueSetCodesFromDir(inputDir);
     console.log(`Loaded ${valueSets.size} ValueSets from ${inputDir} (${Array.from(valueSets.values()).filter(vs => vs.isSmall).length} suitable for union types)`);
     // Generate TypeScript files for ValueSets
     const valueSetOutputDir = path.join(outputDir, 'valuesets');
@@ -622,7 +618,7 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         const full = path.join(inputDir, jf);
         try {
             const raw = JSON.parse(fs.readFileSync(full, 'utf-8'));
-            await processStructureDefinition(raw, { outputDir, fhirSourceHint: full, valueSets, existingStructureDefinitions, profileIdToName, flags });
+            await processStructureDefinition(raw, { outputDir, fhirSourceHint: full, valueSetCodesMap, valueSets, existingStructureDefinitions, profileIdToName, flags });
         }
         catch (err) {
             console.error(`Failed processing JSON ${jf}:`, err);