babelfhir-ts 1.0.26 → 1.0.28

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
@@ -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

@@ -518,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');
@@ -617,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);

package/out/generator/interfaceGenerator.js

@@ -1,72 +1,27 @@
 import fhirInterfaceNames from "./fhirInterfaces.json" with { type: 'json' };
 import { capitalize, sanitizeIdentifier, toPascalCase } from './utils.js';
-import { generateCodeUnionType, getUniformSystem } from './vsParser.js';
+import { getUniformSystem } from './vsParser.js';
+import { sanitizeValueSetName } from './valueSetGenerator.js';
 import { logger } from '../logger.js';
+import { ImportManager } from './importManager.js';
 export function generateInterfaces(interfaceName, newFields, baseResource, baseFields = [], valueSets, resourceType, existingProfiles, fhirChildTypeMap) {
     const debug = (...args) => { if (process.env.DEBUG_FHIR_GEN === 'true')
         console.log('[gen:interfaces]', ...args); };
-    const imports = new Set();
-    const customImports = new Set();
     const interfaces = [];
     const localInterfaceNames = new Set();
     const writtenLines = new Set();
     // Track minimal alias extension interfaces generated in this file to avoid duplicates
     const generatedAliasTypes = new Set();
-    // Track external profiled types that need type alias files
-    const referencedExternalProfiles = new Map();
-    const 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 = referencedExternalProfiles.get(sanitizedTypeName);
-        if (!meta) {
-            meta = { profileUrl: resolvedProfileUrl, baseTypes: new Map() };
-            referencedExternalProfiles.set(sanitizedTypeName, meta);
-        }
-        else if (profileUrl && profileUrl.length > 0 &&
-            meta.profileUrl.startsWith('http://hl7.org/fhir/StructureDefinition/')) {
-            meta.profileUrl = profileUrl;
-        }
-        if (!baseType || baseType === 'any')
-            return;
-        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;
-        }
-    };
-    // Helper to add a type import, checking if it's locally generated first
-    const addTypeImport = (typeName) => {
+    // Initialize ImportManager to handle all import statements
+    const importManager = new ImportManager(localInterfaceNames, existingProfiles);
+    // Helper to add a type import using ImportManager
+    const addTypeImport = (typeName, profileUrl, baseType, isFhirBase) => {
         // If the type is a nested interface of the current profile, don't import it (defined in same file)
         const isNestedOfThisProfile = typeName.startsWith(interfaceName);
         if (isNestedOfThisProfile && localInterfaceNames.has(typeName)) {
             return; // don't add to imports - defined locally in this file
         }
-        // If the type exists in our generated profiles/types, import locally
-        if (existingProfiles?.has(typeName) || localInterfaceNames.has(typeName)) {
-            customImports.add(typeName);
-        }
-        else if (isFhirType(typeName)) {
-            imports.add(typeName);
-        }
-        else {
-            // Check if this is a primitive type that shouldn't be fetched
-            const primitiveTypeLowerCase = typeName.toLowerCase();
-            const isPrimitiveLikeType = ['integer', 'unsignedint', 'positiveint', 'decimal', 'boolean', 'string',
-                'base64binary', 'instant', 'date', 'datetime', 'time', 'code', 'oid', 'id', 'markdown',
-                'uri', 'url', 'canonical', 'uuid'].includes(primitiveTypeLowerCase);
-            customImports.add(typeName);
-            // Track as external profile to be fetched if not already known and not a primitive type
-            if (!isPrimitiveLikeType) {
-                registerExternalProfile(typeName);
-            }
-        }
+        importManager.addType(typeName, profileUrl, baseType, isFhirBase);
     };
     // Helper to find exact interface block index (avoid prefix collisions like Foo and FooBar)
     const findInterfaceIndex = (name) => {
@@ -87,28 +42,57 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             baseFieldByLastSegment.set(seg, bf);
     }
     // Helper to apply ValueSet binding constraints to CodeableConcept types
-    const applyBindingConstraint = (fieldType, field) => {
-        // Only apply to CodeableConcept types with bindings
-        if (fieldType !== 'CodeableConcept' || !field.binding || !valueSets) {
+    const applyBindingConstraint = (fieldType, field, allFields) => {
+        // Only apply to CodeableConcept types
+        if (fieldType !== 'CodeableConcept' || !valueSets) {
             return fieldType;
         }
-        const valueSet = valueSets.get(field.binding.uri);
+        // Check if this field or any of its slices have bindings
+        let binding = field.binding;
+        let isSlicedField = false;
+        // If this is a base field (no sliceName), check if any slices have more specific bindings
+        if (!field.sliceName) {
+            const slicesForThisField = allFields.filter(f => f.name === field.name &&
+                f.sliceName &&
+                f.binding?.uri);
+            // Use the first slice binding if available (slices typically have more specific constraints)
+            if (slicesForThisField.length > 0 && slicesForThisField[0].binding) {
+                binding = slicesForThisField[0].binding;
+                isSlicedField = true;
+                debug(`Using binding from slice ${slicesForThisField[0].sliceName} for ${field.name}`);
+            }
+        }
+        if (!binding) {
+            return fieldType;
+        }
+        const valueSet = valueSets.get(binding.uri);
         if (!valueSet || !valueSet.isSmall) {
             // ValueSet not found or too large for union type - just use CodeableConcept
-            debug(`Skipping binding constraint for ${field.name}: ValueSet ${field.binding.uri} ${!valueSet ? 'not found' : 'too large'}`);
+            debug(`Skipping binding constraint for ${field.name}: ValueSet ${binding.uri} ${!valueSet ? 'not found' : 'too large'}`);
             return fieldType;
         }
-        // Generate constrained type with specific codes
-        const codeUnion = generateCodeUnionType(valueSet);
+        // Import the ValueSet module
+        const sanitizedVSName = sanitizeValueSetName(valueSet.name);
+        const vsTypeName = `${sanitizedVSName}Code`;
+        // Add import for the ValueSet type (from valuesets subdirectory)
+        importManager.addPathBasedImport(vsTypeName, './valuesets/ValueSet-' + sanitizedVSName);
+        // Generate constrained type using the imported ValueSet Code type
         const system = getUniformSystem(valueSet);
+        let constrainedType;
         if (system && valueSet.concepts.length > 0) {
-            // All codes from same system - generate strict constraint
-            return `CodeableConcept & { coding: Array<{ code: ${codeUnion}; system: "${system}" }> }`;
+            // All codes from same system - generate strict constraint with system
+            constrainedType = `CodeableConcept & { coding: Array<{ code: ${vsTypeName}; system: "${system}" }> }`;
         }
         else {
             // Mixed systems or no uniform system - just constrain the code
-            return `CodeableConcept & { coding: Array<{ code: ${codeUnion} }> }`;
+            constrainedType = `CodeableConcept & { coding: Array<{ code: ${vsTypeName} }> }`;
         }
+        // If this is a sliced field (binding comes from a slice), create a union type
+        // to allow both constrained and unconstrained elements (open slicing)
+        if (isSlicedField) {
+            return `(${constrainedType} | CodeableConcept)`;
+        }
+        return constrainedType;
     };
     function processFields(fields, parentInterfaceName, parentFieldType, isProcessingSlice = false) {
         const interfaceLines = [];
@@ -551,8 +535,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                             aliasTypes.push(alias);
                         }
                     }
-                    if (!imports.has('Extension'))
-                        imports.add('Extension');
+                    importManager.addFhirType('Extension');
                     const union = ['Extension', ...aliasTypes].join(' | ');
                     // extension on elements is always an optional array
                     const extLine = `extension?: (${union})[];`;
@@ -666,7 +649,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 // Special-case: Bundle.entry.resource should be FhirResource
                 if (fieldName === 'resource' && (baseResource === 'Bundle' || resourceType === 'Bundle')) {
                     resolvedType = 'FhirResource';
-                    imports.add('FhirResource');
+                    importManager.addFhirType('FhirResource');
                 }
                 // Final primitive normalization for nested branch as well
                 resolvedType = mapTypeToTS(resolvedType);
@@ -737,7 +720,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     const profileUrl = field.profileUrls?.[0] || (field.type && field.type.includes('http') ? field.type : undefined);
                     const baseTypeName = baseFld?.type;
                     const baseIsFhir = baseTypeName ? isFhirType(baseTypeName) : false;
-                    registerExternalProfile(resolvedType, profileUrl, baseTypeName, baseIsFhir);
+                    addTypeImport(resolvedType, profileUrl, baseTypeName, baseIsFhir);
                 }
                 if (!isPrimitiveType(resolvedType)) {
                     if (isFhirType(resolvedType)) {
@@ -771,7 +754,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                             }
                         }
                         else {
-                            customImports.add(sanitizeIdentifier(resolvedType));
+                            importManager.addCustomType(sanitizeIdentifier(resolvedType));
                         }
                     }
                 }
@@ -1023,7 +1006,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 // Special-case: Bundle.entry.resource should be FhirResource, not Resource
                 if (fieldName === 'resource' && (baseResource === 'Bundle' || resourceType === 'Bundle')) {
                     fieldType = 'FhirResource';
-                    imports.add('FhirResource');
+                    importManager.addFhirType('FhirResource');
                 }
                 // Normalize canonical URLs to local type names
                 if (!isPrimitiveType(fieldType) && !isFhirType(fieldType)) {
@@ -1044,8 +1027,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                                 aliasTypes.push(alias);
                             }
                         }
-                        if (!imports.has('Extension'))
-                            imports.add('Extension');
+                        importManager.addFhirType('Extension');
                         const union = ['Extension', ...aliasTypes].join(' | ');
                         fieldType = `(${union})[]`;
                         // We will set isArray=false to avoid adding [] twice in the final line
@@ -1070,17 +1052,16 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                                 // Track this as an external profile that needs a type alias file
                                 const profileUrl = sl.profileUrls?.[0] || sl.type || '';
                                 if (profileUrl && !isFhirType(normalizedType)) {
-                                    registerExternalProfile(normalizedType, profileUrl, 'Identifier', true);
+                                    addTypeImport(normalizedType, profileUrl, 'Identifier', true);
                                 }
                                 // Add to custom imports if not a FHIR type
                                 if (!isFhirType(normalizedType)) {
-                                    customImports.add(normalizedType);
+                                    importManager.addCustomType(normalizedType);
                                 }
                             }
                         }
                         if (profileTypes.length > 0) {
-                            if (!imports.has('Identifier'))
-                                imports.add('Identifier');
+                            importManager.addFhirType('Identifier');
                             const union = ['Identifier', ...profileTypes].join(' | ');
                             fieldType = `(${union})[]`;
                             // We will set isArray=false to avoid adding [] twice in the final line
@@ -1115,8 +1096,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                             aliasTypes.push(alias);
                         }
                     }
-                    if (!imports.has('Extension'))
-                        imports.add('Extension');
+                    importManager.addFhirType('Extension');
                     const union = ['Extension', ...aliasTypes].join(' | ');
                     const extLine = `extension?: (${union})[];`;
                     // Determine parent type to extend
@@ -1135,7 +1115,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     if (!parentT || isPrimitiveLike(parentT)) {
                         const elementIface = `${parentInterfaceName}${capitalize(fieldName)}Element`;
                         // Ensure Element import
-                        imports.add('Element');
+                        importManager.addFhirType('Element');
                         if (!interfaces.some(i => i.startsWith(`export interface ${elementIface}`))) {
                             interfaces.push(`export interface ${elementIface} extends Element {\n    ${extLine}\n}`);
                         }
@@ -1243,7 +1223,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     }
                 }
                 // Apply ValueSet binding constraints for CodeableConcept types
-                fieldType = applyBindingConstraint(fieldType, field);
+                fieldType = applyBindingConstraint(fieldType, field, fields);
                 // Preserve arrayness from base when known; if base metadata is missing and field name is a known repeating element (e.g., 'coverage' on Account),
                 // default to array to avoid incorrect narrowing.
                 // Skip adding [] if fieldType already contains array syntax (e.g., from identifier/extension union types)
@@ -1493,20 +1473,20 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
         if (!isFhirType(sanitizedBase)) {
             // Check if this profile exists in our generated files
             if (existingProfiles?.has(sanitizedBase)) {
-                customImports.add(sanitizedBase);
+                importManager.addCustomType(sanitizedBase);
             }
             else if (resourceType && isFhirType(resourceType)) {
                 // Fallback to the actual FHIR resource type if base profile doesn't exist
-                imports.add(resourceType);
+                importManager.addFhirType(resourceType);
                 // Update baseResource to use the fallback for extends clause
                 baseResource = resourceType;
             }
             else {
-                customImports.add(sanitizedBase);
+                importManager.addCustomType(sanitizedBase);
             }
         }
         else {
-            imports.add(sanitizedBase);
+            importManager.addFhirType(sanitizedBase);
         }
     }
     processFields(newFields, interfaceName);
@@ -1540,8 +1520,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 interfaces.unshift(`export interface ${alias} extends Extension { url: '${url}' }`);
                 generatedAliasTypes.add(alias);
             }
-            if (!imports.has('Extension'))
-                imports.add('Extension');
+            importManager.addFhirType('Extension');
         };
         // Helper to append a line to an existing interface body; if target doesn't exist and it's the root, synthesize it
         const appendToInterface = (name, line) => {
@@ -1551,10 +1530,10 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     const sanitizedBase = sanitizeIdentifier(baseResource);
                     // Ensure import of the base resource type
                     if (!isFhirType(sanitizedBase)) {
-                        customImports.add(sanitizedBase);
+                        importManager.addCustomType(sanitizedBase);
                     }
                     else {
-                        imports.add(sanitizedBase);
+                        importManager.addFhirType(sanitizedBase);
                     }
                     interfaces.push(`export interface ${rootName} extends ${sanitizedBase} {}`);
                 }
@@ -1623,7 +1602,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 if (isPrim) {
                     // Create Element sidecar with extension union
                     const elementIface = `${rootName}${capitalize(seg)}Element`;
-                    imports.add('Element');
+                    importManager.addFhirType('Element');
                     if (!interfaces.some(i => i.startsWith(`export interface ${elementIface}`))) {
                         interfaces.push(`export interface ${elementIface} extends Element {\n    extension?: (${union})[];\n}`);
                     }
@@ -1674,7 +1653,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         });
                     }
                     if (extendT)
-                        imports.add(extendT);
+                        addTypeImport(extendT);
                     const extendsClause = extendT ? ` extends ${extendT}` : '';
                     if (!interfaces.some(i => i.startsWith(`export interface ${nestedName}`))) {
                         interfaces.push(`export interface ${nestedName}${extendsClause} {\n    extension?: (${union})[];\n}`);
@@ -1688,7 +1667,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     appendToInterface(rootName, `${seg}${opt}: ${nestedName}${isArr};`);
                     // Also record import for known FHIR backbone
                     if (extendT && isFhirType(extendT))
-                        imports.add(extendT);
+                        addTypeImport(extendT);
                 }
             }
             else if (segs.length === 2) {
@@ -1706,7 +1685,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 if (!interfaces.some(i => i.startsWith(`export interface ${lvl1Name}`))) {
                     const extendsClause1 = extendT1 ? ` extends ${extendT1}` : '';
                     if (extendT1 && isFhirType(extendT1))
-                        imports.add(extendT1);
+                        addTypeImport(extendT1);
                     interfaces.push(`export interface ${lvl1Name}${extendsClause1} {}`);
                     appendToInterface(rootName, `${seg1}: ${lvl1Name};`);
                 }
@@ -1728,7 +1707,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     }
                 }
                 if (extendT2 && isFhirType(extendT2))
-                    imports.add(extendT2);
+                    addTypeImport(extendT2);
                 const extendsClause2 = extendT2 ? ` extends ${extendT2}` : '';
                 if (!interfaces.some(i => i.startsWith(`export interface ${lvl2Name}`))) {
                     interfaces.push(`export interface ${lvl2Name}${extendsClause2} {\n    extension?: (${union})[];\n}`);
@@ -1758,10 +1737,10 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
         if (baseResource && !isBaseAbs) {
             const sanitizedBase = sanitizedBaseRes;
             if (!isFhirType(sanitizedBase)) {
-                customImports.add(sanitizedBase);
+                importManager.addCustomType(sanitizedBase);
             }
             else {
-                imports.add(sanitizedBase);
+                importManager.addFhirType(sanitizedBase);
             }
             interfaces.push(`export type ${interfaceName} = ${sanitizedBase};`);
         }
@@ -1791,8 +1770,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     aliases.push(alias);
                 }
             }
-            if (!imports.has('Extension'))
-                imports.add('Extension');
+            importManager.addFhirType('Extension');
             const union = ['Extension', ...aliases].join(' | ');
             const idx = findInterfaceIndex(interfaceName);
             if (idx >= 0 && !/\bextension\?\s*:\s*\(/.test(interfaces[idx])) {
@@ -1800,97 +1778,12 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             }
         }
     }
-    const customImportStatements = Array.from(customImports)
-        .map((type) => `import { ${type} } from "./${type}"`); // Adjust the path as needed
-    const importStatements = Array.from(imports)
-        .map((type) => `import { ${type} } from "fhir/r4";`)
-        .join("\n");
-    let output = `${importStatements}\n${customImportStatements.join("\n")}\n${interfaces.join("\n\n")}`;
-    // Ensure HumanName import if referenced but not imported (flattened case)
-    if (/\bHumanName\b/.test(output) && !/import \{[^}]*HumanName/.test(output)) {
-        output = `import { HumanName } from "fhir/r4";\n` + output;
-    }
-    // Minimal post-processing retained only for import pruning.
-    // Prune unused imported identifiers (both FHIR and custom) to satisfy lint rules.
-    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";` : '';
-    });
-    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');
-    // Post-processing: Move locally-generated types from fhir/r4 imports to local imports
-    if (existingProfiles && existingProfiles.size > 0) {
-        // Extract ALL types from fhir/r4 imports (there may be multiple import lines)
-        const fhirImportRegex = /import \{([^}]+)\} from "fhir\/r4";/g;
-        const allFhirTypes = [];
-        let match;
-        logger.log('[DEBUG post-processing]', { interfaceName, hasSimpleQuantity: existingProfiles.has('SimpleQuantity'), existingProfilesSize: existingProfiles.size });
-        while ((match = fhirImportRegex.exec(output)) !== null) {
-            const types = match[1].split(',').map(t => t.trim()).filter(Boolean);
-            logger.log('[DEBUG found fhir/r4 import]', { types });
-            allFhirTypes.push(...types);
-        }
-        if (allFhirTypes.length > 0) {
-            const localTypes = [];
-            const remainingFhirTypes = [];
-            logger.log('[DEBUG separating types]', { allFhirTypes });
-            for (const typeName of allFhirTypes) {
-                if (existingProfiles.has(typeName)) {
-                    logger.log('[DEBUG local type]', { typeName });
-                    // Never move FhirResource to local imports; it must stay from fhir/r4
-                    if (typeName !== 'FhirResource') {
-                        localTypes.push(typeName);
-                    }
-                    else {
-                        remainingFhirTypes.push(typeName);
-                    }
-                }
-                else {
-                    logger.log('[DEBUG fhir type]', { typeName });
-                    remainingFhirTypes.push(typeName);
-                }
-            }
-            logger.log('[DEBUG separated]', { localTypes, remainingFhirTypes });
-            // 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;
-                }
-            }
-        }
-    }
+    // Generate import statements using ImportManager
+    const importStatements = importManager.generateImportStatements();
+    let output = `${importStatements}\n${interfaces.join("\n\n")}`;
+    // Post-processing: prune unused imports and reorganize local types
+    output = importManager.pruneUnusedImports(output);
+    output = importManager.reorganizeImports(output);
     // Final logging to see all interfaces
     if (interfaceName.includes('ConditionDeBasis02')) {
         logger.log('[DEBUG FINAL INTERFACES]', {
@@ -1901,6 +1794,6 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
     }
     return {
         content: output,
-        referencedExternalProfiles
+        referencedExternalProfiles: importManager.getExternalProfiles()
     };
 }

package/out/generator/sdParser.js

@@ -249,6 +249,15 @@ export async function parseStructureDefinition(structureDefinition, fhirServerUr
         console.warn(`StructureDefinition ${structureDefinition.id || "unknown"} has no elements.`);
         return { newFields: [], oldFields: baseFields };
     }
+    // Build a map from snapshot for enriching differential elements with binding information
+    const snapshotBindings = new Map();
+    if (structureDefinition.differential && structureDefinition.snapshot) {
+        for (const snapElem of structureDefinition.snapshot.element) {
+            if (snapElem.binding) {
+                snapshotBindings.set(snapElem.path, snapElem.binding);
+            }
+        }
+    }
     const newFields = elements.map((element) => {
         const name = element.path;
         // Use the profile name if it exists, otherwise fallback to the type code
@@ -327,7 +336,11 @@ export async function parseStructureDefinition(structureDefinition, fhirServerUr
             .filter((constraint) => constraint !== null);
         // ValueSet binding sampling (deterministic): capture binding.valueSet and choose a code from local map if available
         let bindingMeta = undefined;
-        const bindingUri = element.binding?.valueSet;
+        // First try element's own binding, then fall back to snapshot binding if available
+        let bindingUri = element.binding?.valueSet;
+        if (!bindingUri && snapshotBindings.has(element.path)) {
+            bindingUri = snapshotBindings.get(element.path)?.valueSet;
+        }
         // Extract sample code from pattern if present (e.g., patternCodeableConcept or patternCoding)
         let patternCode;
         if (patternValue) {

package/out/generator/utils.js

@@ -60,13 +60,17 @@ export function alignFields(newFields, oldFields) {
 }
 export function mergeFields(newFields, oldFields) {
     const fieldMap = new Map();
+    // Create unique key for field that includes sliceName if present
+    const getFieldKey = (field) => {
+        return field.sliceName ? `${field.name}:${field.sliceName}` : field.name;
+    };
     // Add oldFields to the map
     for (const field of oldFields) {
-        fieldMap.set(field.name, field);
+        fieldMap.set(getFieldKey(field), field);
     }
     // Overwrite or add newFields to the map
     for (const field of newFields) {
-        fieldMap.set(field.name, field);
+        fieldMap.set(getFieldKey(field), field);
     }
     // Return the merged fields as an array
     return Array.from(fieldMap.values());

package/out/generator/validatorGenerator.js

@@ -45,6 +45,43 @@ export function generateValidateProfileFunction(interfaceName, fields // Array o
             });
         }
     });
+    // Add slice cardinality validation for sliced fields with bindings
+    const sliceValidations = [];
+    const slicesByBase = new Map();
+    // Group slices by their base field name
+    fields.forEach(field => {
+        if (field.sliceName && field.binding?.uri) {
+            const baseName = field.name;
+            if (!slicesByBase.has(baseName)) {
+                slicesByBase.set(baseName, []);
+            }
+            slicesByBase.get(baseName).push(field);
+        }
+    });
+    // Generate validation for each sliced field
+    slicesByBase.forEach((slices, baseName) => {
+        slices.forEach(slice => {
+            const min = typeof slice.min === "number" ? slice.min : (slice.isOptional ? 0 : 1);
+            if (min > 0 && slice.binding?.codes && slice.binding.codes.length > 0) {
+                const relPath = baseName.replace(/^[^.]+\./, "");
+                const codes = slice.binding.codes.map(c => `"${c.code}"`).join(", ");
+                // Escape double quotes in codes list for use in error message string
+                const escapedCodes = slice.binding.codes.map(c => c.code).join(", ");
+                const minText = min === 1 ? "at least one" : `at least ${min}`;
+                const sliceLabel = slice.sliceName || "slice";
+                // Sanitize slice name for use as JavaScript variable name
+                const varName = sliceLabel.replace(/[^a-zA-Z0-9_]/g, '_');
+                sliceValidations.push(`
+  // Slice cardinality check for ${baseName}:${sliceLabel}
+  const ${varName}Count = resource.${relPath}?.filter(item => 
+    item.coding?.some(coding => [${codes}].includes(coding.code as string))
+  ).length || 0;
+  if (${varName}Count < ${min}) {
+    errors.push("Slice '${sliceLabel}' on ${relPath}: must have ${minText} element(s) with codes: ${escapedCodes}");
+  }`);
+            }
+        });
+    });
     // Filter out constraints that require terminology or reference resolution which our current
     // synchronous evaluator does not support in parity mode (memberOf, resolve).
     const filteredConstraints = uniqueConstraints.filter(c => !/(\bmemberOf\b|\bresolve\b)/.test(c.expression || ""));
@@ -61,20 +98,18 @@ export function generateValidateProfileFunction(interfaceName, fields // Array o
     }`;
     })
         .join("\n");
-    const hasConstraints = filteredConstraints.length > 0;
+    const hasConstraints = filteredConstraints.length > 0 || sliceValidations.length > 0;
     // Always emit a uniform signature validateX(resource: X) so callers don't branch on arity.
     // Only import fhirpath and run evaluation logic when there are constraints.
     if (!hasConstraints) {
         return `
 export async function validate${interfaceName}(resource: ${interfaceName}): Promise<{ errors: string[], warnings: string[] }> {\n  // Touch the parameter so eslint no-unused-vars doesn't flag it when there are no constraints.\n  void resource;\n  return { errors: [], warnings: [] };\n}`;
     }
-    return `
-import fhirpath from "fhirpath";
-
-export async function validate${interfaceName}(resource: ${interfaceName}): Promise<{ errors: string[], warnings: string[] }> {
+    const fhirpathImport = filteredConstraints.length > 0 ? 'import fhirpath from "fhirpath";\n\n' : '';
+    return `${fhirpathImport}export async function validate${interfaceName}(resource: ${interfaceName}): Promise<{ errors: string[], warnings: string[] }> {
   const errors: string[] = [];
   const warnings: string[] = [];
-  ${validationLogic}
+  ${validationLogic}${sliceValidations.join('')}
   return { errors, warnings };
 }`;
 }

package/out/generator/valueSetGenerator.js

@@ -56,7 +56,7 @@ export function generateValueSetTypeScript(valueSet) {
 /**
  * Sanitize ValueSet name for use as TypeScript identifier
  */
-function sanitizeValueSetName(name) {
+export function sanitizeValueSetName(name) {
     // Remove common prefixes
     let sanitized = name.replace(/^ValueSet[-_]?/i, '');
     // Split on non-alphanumeric and capitalize each part

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babelfhir-ts",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "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",
@@ -36,10 +36,30 @@
   },
   "keywords": [
     "fhir",
-    "typescript"
+    "typescript",
+    "code-generation",
+    "healthcare",
+    "hl7",
+    "fhir-profiles",
+    "implementation-guide",
+    "validation",
+    "fhir-r4",
+    "fhir-to-typescript"
   ],
   "author": "Maximilian Nussbaumer",
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quotentiroler/BabelFHIR-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/quotentiroler/BabelFHIR-ts/issues"
+  },
+  "homepage": "https://github.com/quotentiroler/BabelFHIR-ts#readme",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
     "@types/node": "^22.14.1",