babelfhir-ts 1.3.2 → 1.3.4

package/README.md

@@ -47,7 +47,7 @@
 - **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**—minimal runtime deps; only `fhirpath` is required for validators
-- **Type-safe FHIR client** — generated client extends [`@babelfhir-ts/client-r4`](https://www.npmjs.com/package/@babelfhir-ts/client-r4) with profile-specific methods (e.g., `.usCorePatient()`, `.pASClaim()`) on top of base R4 resource accessors
+- **Type-safe FHIR client** — generated client extends [`@babelfhir-ts/client-r4`](https://www.npmjs.com/package/@babelfhir-ts/client-r4) / [`client-r4b`](https://www.npmjs.com/package/@babelfhir-ts/client-r4b) / [`client-r5`](https://www.npmjs.com/package/@babelfhir-ts/client-r5) with profile-specific methods (e.g., `.usCorePatient()`, `.pASClaim()`) on top of base resource accessors
 - **Install any FHIR profile as a node module**—use `babelfhir-ts install` to add Implementation Guides directly to your project
 
 <!-- PARITY-BADGES:START - Do not remove or modify this section -->
@@ -260,7 +260,7 @@ Full documentation is available at **[max-health-inc.github.io/BabelFHIR-TS/docs
 - [Generated Code Guide](https://max-health-inc.github.io/BabelFHIR-TS/docs/generated-code) — understanding the output, module resolution, FHIR type imports
 - [FHIR Client](https://max-health-inc.github.io/BabelFHIR-TS/docs/fhir-client) — type-safe server interactions
 - [Validation](https://max-health-inc.github.io/BabelFHIR-TS/docs/validation) — what validators check, CI pipelines, known Firely SDK issues
-- [Limitations](https://max-health-inc.github.io/BabelFHIR-TS/docs/limitations) — R4 only, edge cases, random() caveats
+- [Limitations](https://max-health-inc.github.io/BabelFHIR-TS/docs/limitations) — edge cases, random() caveats
 - [Contributing](https://max-health-inc.github.io/BabelFHIR-TS/docs/contributing) — dev setup, scripts, project structure
 
 ## License
@@ -283,7 +283,8 @@ For security issues, please see [SECURITY.md](SECURITY.md) for our security poli
 ## Links
 
 - [npm package — babelfhir-ts](https://www.npmjs.com/package/babelfhir-ts)
-- [npm package — @babelfhir-ts/client-r4](https://www.npmjs.com/package/@babelfhir-ts/client-r4)
+- [npm package — @babelfhir-ts/client-r4](https://www.npmjs.com/package/@babelfhir-ts/client-r4) / [client-r4b](https://www.npmjs.com/package/@babelfhir-ts/client-r4b) / [client-r5](https://www.npmjs.com/package/@babelfhir-ts/client-r5)
+- [npm package — @babelfhir-ts/zod](https://www.npmjs.com/package/@babelfhir-ts/zod)
 - [GitHub repository](https://github.com/Max-Health-Inc/BabelFHIR-TS)
 - [Validation report](https://max-health-inc.github.io/BabelFHIR-TS/)
 - [Issue tracker](https://github.com/Max-Health-Inc/BabelFHIR-TS/issues)

package/out/src/generator/emitters/class/randomUtilitiesTemplate.js

@@ -1,7 +1,31 @@
 import { DEFAULT_COUNTRY, TS } from '../../core/constants.js';
-import { fhirModuleSpecifier } from '../../fhir/versionContext.js';
+import { ctx, fhirModuleSpecifier } from '../../fhir/versionContext.js';
+/**
+ * Build the SampledData skeleton object literal from the active version's
+ * dataTypes map.  R4 has `period`, R5 replaced it with `interval` +
+ * `intervalUnit` — but instead of hard-coding the difference we simply
+ * inspect which fields exist for the current FHIR version.
+ */
+function buildSampledDataFields() {
+    const sdFields = ctx().dataTypes['SampledData'] ?? {};
+    const parts = [];
+    // origin is always a Quantity — use a complete skeleton
+    parts.push("origin: { value: 0, unit: 'unit', system: '" + TS.UCUM + "', code: '1' }");
+    // Version-varying numeric / string fields
+    if ('period' in sdFields)
+        parts.push('period: 1');
+    if ('interval' in sdFields)
+        parts.push('interval: 1');
+    if ('intervalUnit' in sdFields)
+        parts.push("intervalUnit: 'ms'");
+    // Always-present fields
+    parts.push('dimensions: 1');
+    parts.push("data: 'E'");
+    return parts.join(', ');
+}
 export function generateRandomUtilities() {
     const fhirModule = fhirModuleSpecifier();
+    const sampledDataFields = buildSampledDataFields();
     return `// Auto-generated helper for random resource generation with optional deterministic seeding
 // Uses official FHIR TypeScript definitions
 import type { HumanName, Address, Coding, CodeableConcept, Identifier, Reference, Period, ContactPoint, Quantity, Money, Narrative, Dosage, Ratio, Range, Annotation, Attachment, Age, Duration, Expression, RelatedArtifact, DataRequirement, ParameterDefinition, TriggerDefinition, ContactDetail, UsageContext, Signature, SampledData, Timing } from '${fhirModule}';
@@ -96,7 +120,7 @@ export function skeletonTriggerDefinition(): TriggerDefinition { return { type:
 export function skeletonContactDetail(): ContactDetail { return { name: 'Contact' }; }
 export function skeletonUsageContext(): UsageContext { return { code: { system: 'http://terminology.hl7.org/CodeSystem/usage-context-type', code: 'focus' }, valueCodeableConcept: skeletonCodeableConcept() }; }
 export function skeletonSignature(): Signature { return { type: [{ system: 'urn:iso-astm:E1762-95:2013', code: '1.2.840.10065.1.12.1.1' }], when: randomDate(), who: skeletonReference('Practitioner') }; }
-export function skeletonSampledData(): SampledData { return { origin: { value: 0, unit: 'unit', system: '${TS.UCUM}', code: '1' }, period: 1, dimensions: 1, data: 'E' }; }
+export function skeletonSampledData(): SampledData { return { ${sampledDataFields} }; }
 export function skeletonTiming(): Timing { return { repeat: { frequency: 1, period: 1, periodUnit: 'd' } }; }
 
 /**

package/out/src/generator/emitters/zod/zodStubInstaller.js

@@ -39,8 +39,8 @@ export function installBaseZodTypes(outputDir) {
         if (fs.existsSync(srcPkgJson)) {
             fs.copyFileSync(srcPkgJson, path.join(pkgDir, 'package.json'));
         }
-        // Copy all runtime dist files into the version-specific subdirectory
-        const distSlugDir = path.join(pkgDir, slug);
+        // Copy all runtime dist files into dist/<slug>/ to match package.json exports
+        const distSlugDir = path.join(pkgDir, 'dist', slug);
         fs.mkdirSync(distSlugDir, { recursive: true });
         for (const file of fs.readdirSync(runtimeDist)) {
             fs.copyFileSync(path.join(runtimeDist, file), path.join(distSlugDir, file));

package/out/src/generator/fhir/corePackageResolver.js

@@ -121,70 +121,72 @@ export function deriveVersionData(corePackageDir) {
     const resourceFields = {};
     const files = fs.readdirSync(sdDir)
         .filter(f => f.startsWith('StructureDefinition-') && f.endsWith('.json'));
-    // Two-pass approach: first collect base specialisations, then constraint profiles
-    const parsedSDs = [];
+    // Memory-efficient approach: parse SDs one file at a time.
+    // Pass 1 processes base specialisations and records which constraint SDs
+    // need full processing in Pass 2 (only complex-type constraints whose
+    // base type is a known specialisation — typically <10 out of ~828).
+    const complexTypeSpecNames = new Set();
+    const constraintSDFiles = []; // filenames needing Pass 2
     for (const file of files) {
         try {
             const raw = fs.readFileSync(path.join(sdDir, file), 'utf-8');
             const sd = JSON.parse(raw);
             if (sd.resourceType !== 'StructureDefinition')
                 continue;
-            parsedSDs.push({
-                kind: sd.kind, derivation: sd.derivation,
-                typeName: sd.type, sdName: sd.name || sd.id, sd,
-            });
+            const kind = sd.kind;
+            const derivation = sd.derivation;
+            const typeName = sd.type;
+            // Constraint SDs are deferred to Pass 2
+            if (derivation === 'constraint' && kind === 'complex-type') {
+                constraintSDFiles.push(file);
+                continue;
+            }
+            if (!typeName)
+                continue;
+            if (derivation && derivation !== 'specialization')
+                continue;
+            if (kind === 'logical')
+                continue;
+            if (kind === 'resource') {
+                resourceNames.push(typeName);
+                interfaceNames.push(typeName);
+                collectBackboneInterfaces(sd, typeName, interfaceNames);
+                collectDataTypeFields(sd, typeName, resourceFields);
+            }
+            else if (kind === 'primitive-type') {
+                primitiveTypeNames.push(typeName);
+            }
+            else if (kind === 'complex-type') {
+                complexTypeSpecNames.add(typeName);
+                interfaceNames.push(typeName);
+                collectDataTypeFields(sd, typeName, dataTypes);
+                collectBackboneInterfaces(sd, typeName, interfaceNames);
+            }
+            // sd is now GC-eligible — no reference kept
         }
         catch { /* skip */ }
     }
-    // Track complex-type specialisation names to filter constraint SDs later
-    const complexTypeSpecNames = new Set();
-    // Pass 1: base specialisation SDs (derivation = 'specialization' or absent)
-    for (const { kind, derivation, typeName, sd } of parsedSDs) {
-        if (!typeName)
-            continue;
-        // Abstract bases (Element, Resource) have no derivation field
-        if (derivation && derivation !== 'specialization')
-            continue;
-        // Skip logical types (Definition, Event, FiveWs, Request)
-        if (kind === 'logical')
-            continue;
-        if (kind === 'resource') {
-            resourceNames.push(typeName);
-            // Resources are also valid interface names (used by isFhirType)
-            interfaceNames.push(typeName);
-            collectBackboneInterfaces(sd, typeName, interfaceNames);
-            // Collect resource direct-child fields for cardinality tables
-            collectDataTypeFields(sd, typeName, resourceFields);
-        }
-        else if (kind === 'primitive-type') {
-            primitiveTypeNames.push(typeName);
-        }
-        else if (kind === 'complex-type') {
-            complexTypeSpecNames.add(typeName);
-            interfaceNames.push(typeName);
-            collectDataTypeFields(sd, typeName, dataTypes);
-            collectBackboneInterfaces(sd, typeName, interfaceNames);
-        }
-    }
-    // Pass 2: core profiles (constraint) on data types shipped in the core package
-    // Examples: MoneyQuantity, SimpleQuantity — both are constraint on Quantity
-    // Only include SDs whose base type is a known complex-type specialisation,
-    // excluding Extension (hundreds of extension constraint SDs) and
-    // infrastructure types that aren't used as field type codes.
+    // Pass 2: re-read only the constraint complex-type SDs whose base type is a
+    // known specialisation (e.g. MoneyQuantity constraining Quantity).
     const CONSTRAINT_EXCLUDE_TYPES = new Set(['Extension', 'ElementDefinition']);
-    for (const { kind, derivation, typeName, sdName, sd } of parsedSDs) {
-        if (!typeName || !sdName)
-            continue;
-        if (derivation !== 'constraint' || kind !== 'complex-type')
-            continue;
-        if (sdName === typeName)
-            continue;
-        if (!complexTypeSpecNames.has(typeName))
-            continue;
-        if (CONSTRAINT_EXCLUDE_TYPES.has(typeName))
-            continue;
-        interfaceNames.push(sdName);
-        collectDataTypeFields(sd, sdName, dataTypes);
+    for (const file of constraintSDFiles) {
+        try {
+            const raw = fs.readFileSync(path.join(sdDir, file), 'utf-8');
+            const sd = JSON.parse(raw);
+            const typeName = sd.type;
+            const sdName = sd.name || sd.id;
+            if (!typeName || !sdName)
+                continue;
+            if (sdName === typeName)
+                continue;
+            if (!complexTypeSpecNames.has(typeName))
+                continue;
+            if (CONSTRAINT_EXCLUDE_TYPES.has(typeName))
+                continue;
+            interfaceNames.push(sdName);
+            collectDataTypeFields(sd, sdName, dataTypes);
+        }
+        catch { /* skip */ }
     }
     // Deterministic ordering
     resourceNames.sort();

package/out/src/generator/fhir/corePackageResolver.ts

@@ -163,67 +163,67 @@ export function deriveVersionData(corePackageDir: string): DerivedVersionData {
   const files = fs.readdirSync(sdDir)
     .filter(f => f.startsWith('StructureDefinition-') && f.endsWith('.json'));
 
-  // Two-pass approach: first collect base specialisations, then constraint profiles
-  const parsedSDs: Array<{
-    kind?: string; derivation?: string; typeName?: string; sdName?: string;
-    sd: Record<string, unknown>;
-  }> = [];
+  // Memory-efficient approach: parse SDs one file at a time.
+  // Pass 1 processes base specialisations and records which constraint SDs
+  // need full processing in Pass 2 (only complex-type constraints whose
+  // base type is a known specialisation — typically <10 out of ~828).
+  const complexTypeSpecNames = new Set<string>();
+  const constraintSDFiles: string[] = [];  // filenames needing Pass 2
 
   for (const file of files) {
     try {
       const raw = fs.readFileSync(path.join(sdDir, file), 'utf-8');
       const sd = JSON.parse(raw);
       if (sd.resourceType !== 'StructureDefinition') continue;
-      parsedSDs.push({
-        kind: sd.kind, derivation: sd.derivation,
-        typeName: sd.type, sdName: sd.name || sd.id, sd,
-      });
-    } catch { /* skip */ }
-  }
 
-  // Track complex-type specialisation names to filter constraint SDs later
-  const complexTypeSpecNames = new Set<string>();
-
-  // Pass 1: base specialisation SDs (derivation = 'specialization' or absent)
-  for (const { kind, derivation, typeName, sd } of parsedSDs) {
-    if (!typeName) continue;
-    // Abstract bases (Element, Resource) have no derivation field
-    if (derivation && derivation !== 'specialization') continue;
-    // Skip logical types (Definition, Event, FiveWs, Request)
-    if (kind === 'logical') continue;
-
-    if (kind === 'resource') {
-      resourceNames.push(typeName);
-      // Resources are also valid interface names (used by isFhirType)
-      interfaceNames.push(typeName);
-      collectBackboneInterfaces(sd, typeName, interfaceNames);
-      // Collect resource direct-child fields for cardinality tables
-      collectDataTypeFields(sd, typeName, resourceFields);
-    } else if (kind === 'primitive-type') {
-      primitiveTypeNames.push(typeName);
-    } else if (kind === 'complex-type') {
-      complexTypeSpecNames.add(typeName);
-      interfaceNames.push(typeName);
-      collectDataTypeFields(sd, typeName, dataTypes);
-      collectBackboneInterfaces(sd, typeName, interfaceNames);
-    }
+      const kind = sd.kind;
+      const derivation = sd.derivation;
+      const typeName = sd.type;
+
+      // Constraint SDs are deferred to Pass 2
+      if (derivation === 'constraint' && kind === 'complex-type') {
+        constraintSDFiles.push(file);
+        continue;
+      }
+
+      if (!typeName) continue;
+      if (derivation && derivation !== 'specialization') continue;
+      if (kind === 'logical') continue;
+
+      if (kind === 'resource') {
+        resourceNames.push(typeName);
+        interfaceNames.push(typeName);
+        collectBackboneInterfaces(sd, typeName, interfaceNames);
+        collectDataTypeFields(sd, typeName, resourceFields);
+      } else if (kind === 'primitive-type') {
+        primitiveTypeNames.push(typeName);
+      } else if (kind === 'complex-type') {
+        complexTypeSpecNames.add(typeName);
+        interfaceNames.push(typeName);
+        collectDataTypeFields(sd, typeName, dataTypes);
+        collectBackboneInterfaces(sd, typeName, interfaceNames);
+      }
+      // sd is now GC-eligible — no reference kept
+    } catch { /* skip */ }
   }
 
-  // Pass 2: core profiles (constraint) on data types shipped in the core package
-  // Examples: MoneyQuantity, SimpleQuantity — both are constraint on Quantity
-  // Only include SDs whose base type is a known complex-type specialisation,
-  // excluding Extension (hundreds of extension constraint SDs) and
-  // infrastructure types that aren't used as field type codes.
+  // Pass 2: re-read only the constraint complex-type SDs whose base type is a
+  // known specialisation (e.g. MoneyQuantity constraining Quantity).
   const CONSTRAINT_EXCLUDE_TYPES = new Set(['Extension', 'ElementDefinition']);
-  for (const { kind, derivation, typeName, sdName, sd } of parsedSDs) {
-    if (!typeName || !sdName) continue;
-    if (derivation !== 'constraint' || kind !== 'complex-type') continue;
-    if (sdName === typeName) continue;
-    if (!complexTypeSpecNames.has(typeName)) continue;
-    if (CONSTRAINT_EXCLUDE_TYPES.has(typeName)) continue;
-
-    interfaceNames.push(sdName);
-    collectDataTypeFields(sd, sdName, dataTypes);
+  for (const file of constraintSDFiles) {
+    try {
+      const raw = fs.readFileSync(path.join(sdDir, file), 'utf-8');
+      const sd = JSON.parse(raw);
+      const typeName = sd.type;
+      const sdName = sd.name || sd.id;
+      if (!typeName || !sdName) continue;
+      if (sdName === typeName) continue;
+      if (!complexTypeSpecNames.has(typeName)) continue;
+      if (CONSTRAINT_EXCLUDE_TYPES.has(typeName)) continue;
+
+      interfaceNames.push(sdName);
+      collectDataTypeFields(sd, sdName, dataTypes);
+    } catch { /* skip */ }
   }
 
   // Deterministic ordering

package/out/src/generator/index.js

@@ -11,6 +11,8 @@ import { initVersionContext, ctx, versionSlug } from './fhir/versionContext.js';
 import { DEFAULT_FHIR_VERSION } from './fhir/types.js';
 import { spawn } from 'child_process';
 import { buildProfileRegistries, expandValueSetsWithTx, emitValueSetFiles, cleanupStaleValueSetDir, initGenerationContext, enrichValueSetsFromCodeMap, } from './generationHelpers.js';
+import { resetTimings, startPhase, getTimingSummary, formatTimingSummary } from './timing.js';
+export { getTimingSummary, formatTimingSummary } from './timing.js';
 const log = logger.withTag('generator');
 // Convert version-context dataTypes to the Map format expected by code
 function buildFhirChildTypeMapFromJson() {
@@ -284,13 +286,17 @@ export async function generate(fhirSource, outputDir, flags) {
  */
 export async function generateIntoPackage(packageArchivePath, outArchivePath, flags) {
     initGenerationContext(flags, path.dirname(outArchivePath || packageArchivePath));
+    resetTimings();
     if (!packageArchivePath.endsWith('.tgz') && !packageArchivePath.endsWith('.zip'))
         throw new Error('Only .tgz or .zip supported.');
+    let endPhase = startPhase('extract');
     const extractResult = await extractPackage(packageArchivePath);
     const extractedRoot = extractResult.path;
+    endPhase();
     const shouldCleanup = !extractResult.isCached; // Only cleanup temp directories, not cache
     try {
         // Auto-detect FHIR version from package when not explicitly set
+        endPhase = startPhase('init');
         if (!flags?.fhirVersion) {
             const detected = detectFhirVersion(extractedRoot);
             await initVersionContext(detected ?? DEFAULT_FHIR_VERSION);
@@ -299,8 +305,10 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
             await initVersionContext(flags.fhirVersion);
         }
         const fhirInterfaceNames = ctx().interfaceNames;
+        endPhase(); // init
         // Load dependencies from package.json BEFORE reading StructureDefinitions
         // This ensures base profiles (like coverage-de-basis) are available for resolution
+        endPhase = startPhase('resolve');
         const { getPackageManager } = await import('./parser/packageManager.js');
         const packageManager = getPackageManager();
         packageManager.loadDependenciesFromExtractedPackage(extractedRoot);
@@ -313,6 +321,7 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         let valueSets = readValueSetsFromDir(extractedRoot);
         logger.log(`Package contains ${structureDefinitions.length} StructureDefinitions.`);
         logger.log(`Loaded ${Object.keys(valueSetCodesMap).length} ValueSet code mappings (including dependencies)`);
+        endPhase(); // resolve
         // Enrich ValueSets with codes resolved from CodeSystems (system-only compose.include)
         const bindingUrls = collectValueSetBindingUrls(structureDefinitions);
         enrichValueSetsFromCodeMap(valueSets, valueSetCodesMap, bindingUrls);
@@ -328,6 +337,7 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         }
         ensureDirectoryExists(outputDir);
         // Generate TypeScript files for ValueSets inside the embedded package
+        endPhase = startPhase('generate');
         const didGenerateValueSets = emitValueSetFiles(valueSets, outputDir, { deduplicateFilenames: true });
         if (!didGenerateValueSets) {
             cleanupStaleValueSetDir(outputDir);
@@ -335,12 +345,12 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         const { existingStructureDefinitions, profileIdToName, profileUrlToName } = buildProfileRegistries(structureDefinitions, fhirInterfaceNames);
         // Register all local StructureDefinitions for resolution before HTTP fetches
         registerLocalStructureDefinitions(structureDefinitions);
-        // Register SDs from dependency packages so external profile resolution can find them
-        const depSDs = readStructureDefinitionsFromDependencies(extractedRoot);
-        registerLocalStructureDefinitions(depSDs);
+        // PackageManager already loaded and registered dependency SDs above —
+        // no need to re-parse them via readStructureDefinitionsFromDependencies.
         for (const sd of structureDefinitions) {
             await processStructureDefinition(sd, { outputDir, fhirSourceHint: '', valueSetCodesMap, valueSets, existingStructureDefinitions, profileIdToName, profileUrlToName, flags });
         }
+        endPhase(); // generate
         // Create package.json in generated folder
         const originalPackageJsonPath = path.join(extractedRoot, 'package', 'package.json');
         let packageName = path.basename(packageArchivePath, path.extname(packageArchivePath));
@@ -441,8 +451,10 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         fs.writeFileSync(path.join(nodeTypesDir, 'index.d.ts'), `declare module 'module' {\n  export function createRequire(filename: string | URL): NodeRequire;\n}\n`);
         fs.writeFileSync(path.join(nodeTypesDir, 'package.json'), JSON.stringify({ name: '@types/node', version: '0.0.0-stub', types: 'index.d.ts' }));
         // Compile TypeScript to JavaScript
+        endPhase = startPhase('compile');
         logger.log('Compiling TypeScript to JavaScript...');
         await compileTypeScriptToJS(outputDir);
+        endPhase(); // compile
         // Remove fhirpath stub — the real package is a peer dependency
         removeFhirpathStub(outputDir);
         // Remove @types/node stub — only needed for compilation
@@ -481,7 +493,13 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         fs.copyFileSync(generatedPackageJsonPath, rootPackageJsonPath);
         logger.log('Copied package.json to tarball root');
         const finalArchive = outArchivePath || deriveOutputArchiveName(packageArchivePath);
+        endPhase = startPhase('repack');
         await createPackageFromDir(extractedRoot, finalArchive);
+        endPhase(); // repack
+        // Write timing summary to output directory
+        const timing = getTimingSummary();
+        fs.writeFileSync(path.join(outputDir, 'generation-timing.json'), JSON.stringify(timing, null, 2));
+        logger.log(formatTimingSummary(timing));
         return finalArchive;
     }
     finally {
@@ -503,12 +521,16 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
  */
 export async function generateIntoPackageDirect(packageArchivePath, flags) {
     initGenerationContext(flags, path.dirname(packageArchivePath));
+    resetTimings();
     if (!packageArchivePath.endsWith('.tgz') && !packageArchivePath.endsWith('.zip'))
         throw new Error('Only .tgz or .zip supported.');
+    let endPhase = startPhase('extract');
     const extractResult = await extractPackage(packageArchivePath);
     const extractedRoot = extractResult.path;
+    endPhase();
     const shouldCleanup = !extractResult.isCached;
     // Auto-detect FHIR version from package when not explicitly set
+    endPhase = startPhase('init');
     if (!flags?.fhirVersion) {
         const detected = detectFhirVersion(extractedRoot);
         await initVersionContext(detected ?? DEFAULT_FHIR_VERSION);
@@ -517,6 +539,8 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
         await initVersionContext(flags.fhirVersion);
     }
     const fhirInterfaceNames = ctx().interfaceNames;
+    endPhase(); // init
+    endPhase = startPhase('resolve');
     const { getPackageManager } = await import('./parser/packageManager.js');
     const packageManager = getPackageManager();
     packageManager.loadDependenciesFromExtractedPackage(extractedRoot);
@@ -527,6 +551,7 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
     let valueSets = readValueSetsFromDir(extractedRoot);
     logger.log(`Package contains ${structureDefinitions.length} StructureDefinitions.`);
     logger.log(`Loaded ${Object.keys(valueSetCodesMap).length} ValueSet code mappings (including dependencies)`);
+    endPhase(); // resolve
     const bindingUrls = collectValueSetBindingUrls(structureDefinitions);
     enrichValueSetsFromCodeMap(valueSets, valueSetCodesMap, bindingUrls);
     if (flags?.txServer) {
@@ -539,16 +564,18 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
         fs.rmSync(outputDir, { recursive: true, force: true });
     }
     ensureDirectoryExists(outputDir);
+    endPhase = startPhase('generate');
     const didGenerateValueSets = emitValueSetFiles(valueSets, outputDir, { deduplicateFilenames: true });
     if (!didGenerateValueSets)
         cleanupStaleValueSetDir(outputDir);
     const { existingStructureDefinitions, profileIdToName, profileUrlToName } = buildProfileRegistries(structureDefinitions, fhirInterfaceNames);
     registerLocalStructureDefinitions(structureDefinitions);
-    const depSDs = readStructureDefinitionsFromDependencies(extractedRoot);
-    registerLocalStructureDefinitions(depSDs);
+    // PackageManager already loaded and registered dependency SDs above —
+    // no need to re-parse them via readStructureDefinitionsFromDependencies.
     for (const sd of structureDefinitions) {
         await processStructureDefinition(sd, { outputDir, fhirSourceHint: '', valueSetCodesMap, valueSets, existingStructureDefinitions, profileIdToName, profileUrlToName, flags });
     }
+    endPhase(); // generate
     // Create package.json in generated folder
     const originalPackageJsonPath = path.join(extractedRoot, 'package', 'package.json');
     let packageName = path.basename(packageArchivePath, path.extname(packageArchivePath));
@@ -633,8 +660,10 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
     fs.mkdirSync(nodeTypesDir, { recursive: true });
     fs.writeFileSync(path.join(nodeTypesDir, 'index.d.ts'), `declare module 'module' {\n  export function createRequire(filename: string | URL): NodeRequire;\n}\n`);
     fs.writeFileSync(path.join(nodeTypesDir, 'package.json'), JSON.stringify({ name: '@types/node', version: '0.0.0-stub', types: 'index.d.ts' }));
+    endPhase = startPhase('compile');
     logger.log('Compiling TypeScript to JavaScript...');
     await compileTypeScriptToJS(outputDir);
+    endPhase(); // compile
     removeFhirpathStub(outputDir);
     try {
         fs.rmSync(path.join(outputDir, 'node_modules', '@types'), { recursive: true, force: true });
@@ -660,6 +689,10 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
         fs.rmdirSync(nodeModulesDir);
     }
     catch { /* not empty or doesn't exist — fine */ }
+    // Write timing summary to output directory
+    const timing = getTimingSummary();
+    fs.writeFileSync(path.join(outputDir, 'generation-timing.json'), JSON.stringify(timing, null, 2));
+    logger.log(formatTimingSummary(timing));
     return {
         generatedDir: outputDir,
         cleanup: () => {
@@ -681,7 +714,9 @@ function deriveOutputArchiveName(input) {
  */
 export async function generateForDirectory(inputDir, outputDir, flags) {
     initGenerationContext(flags, outputDir);
+    resetTimings();
     // Auto-detect FHIR version from directory contents when not explicitly set
+    let endPhase = startPhase('init');
     if (!flags?.fhirVersion) {
         const detected = detectFhirVersion(inputDir);
         await initVersionContext(detected ?? DEFAULT_FHIR_VERSION);
@@ -690,11 +725,13 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         await initVersionContext(flags.fhirVersion);
     }
     const fhirInterfaceNames = ctx().interfaceNames;
+    endPhase(); // init
     if (!fs.existsSync(inputDir))
         throw new Error(`Input directory not found: ${inputDir}`);
     if (!fs.existsSync(outputDir))
         fs.mkdirSync(outputDir, { recursive: true });
     // Load ValueSets from the directory
+    endPhase = startPhase('resolve');
     const valueSets = readValueSetsFromDir(inputDir);
     // Ensure dependency packages are downloaded before loading ValueSets
     await ensureDependenciesDownloaded(inputDir);
@@ -710,6 +747,7 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         log.warn(`No archives or StructureDefinition JSON in ${inputDir}`);
         return;
     }
+    endPhase(); // resolve
     // Collect StructureDefinitions from JSON files, then build profile registries
     const localStructureDefinitions = [];
     for (const jf of jsonFiles) {
@@ -733,6 +771,7 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         }
     }
     // Generate TypeScript files for ValueSets
+    endPhase = startPhase('generate');
     if (!emitValueSetFiles(valueSets, outputDir)) {
         cleanupStaleValueSetDir(outputDir);
     }
@@ -786,6 +825,11 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         const { generateDicomweb } = await import('./emitters/dicomweb/dicomwebGenerator.js');
         generateDicomweb({ outputDir });
     }
+    endPhase(); // generate
+    // Write timing summary to output directory
+    const timing = getTimingSummary();
+    fs.writeFileSync(path.join(outputDir, 'generation-timing.json'), JSON.stringify(timing, null, 2));
+    logger.log(formatTimingSummary(timing));
 }
 export async function generateFromJsonFile(jsonFilePath, outputDir, flags) {
     // Initialize FHIR version context

package/out/src/generator/parser/packageManager.js

@@ -4,6 +4,7 @@
 import fs from 'fs';
 import path from 'path';
 import { registerLocalStructureDefinitions } from './sdParser.js';
+import { isLargeHl7Package } from './packageParser.js';
 import { logger } from '../../logger.js';
 import { getFhirPackagesCacheDir, ensureCacheDir } from '../core/cacheConfig.js';
 export class PackageManager {
@@ -166,9 +167,14 @@ export class PackageManager {
         try {
             const files = fs.readdirSync(sdDir);
             for (const file of files) {
+                // Only read StructureDefinition-*.json files (FHIR naming convention).
+                // Fall back to all .json if no prefix-matched files found (e.g. KBV packages).
                 if (!file.endsWith('.json') || file === 'package.json') {
                     continue;
                 }
+                if (!file.startsWith('StructureDefinition-')) {
+                    continue;
+                }
                 try {
                     const filePath = path.join(sdDir, file);
                     const content = fs.readFileSync(filePath, 'utf-8');
@@ -182,6 +188,25 @@ export class PackageManager {
                     continue;
                 }
             }
+            // Fallback: if no prefix-matched files, scan all JSON (non-standard naming)
+            if (sds.length === 0) {
+                for (const file of files) {
+                    if (!file.endsWith('.json') || file === 'package.json' || file.startsWith('StructureDefinition-')) {
+                        continue;
+                    }
+                    try {
+                        const filePath = path.join(sdDir, file);
+                        const content = fs.readFileSync(filePath, 'utf-8');
+                        const resource = JSON.parse(content);
+                        if (resource.resourceType === 'StructureDefinition') {
+                            sds.push(resource);
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
         }
         catch (e) {
             logger.log(`Failed to read StructureDefinitions from ${packagePath}: ${e.message}`);
@@ -243,8 +268,10 @@ export class PackageManager {
             const packageJson = JSON.parse(content);
             if (packageJson.dependencies && typeof packageJson.dependencies === 'object') {
                 for (const [depName, depVersion] of Object.entries(packageJson.dependencies)) {
-                    // Skip hl7.fhir.r4.core and similar base packages - they're too large and not needed
-                    if (depName.startsWith('hl7.fhir.') && depName.includes('.core')) {
+                    // Skip large HL7 base packages (core, extensions, terminology) —
+                    // they contain thousands of files and are handled via deriveVersionData
+                    // or on-demand fetching.
+                    if (isLargeHl7Package(depName)) {
                         continue;
                     }
                     const depRef = `${depName}@${depVersion}`;

package/out/src/generator/parser/packageParser.js

@@ -95,7 +95,7 @@ export function resolveWellKnownValueSetCodes(valueSetCodesMap) {
 function resolveValueSetCompose(visitedDirs, merged) {
     let resolved = 0;
     for (const dir of visitedDirs) {
-        const jsonFiles = findAllJsonFiles(dir);
+        const jsonFiles = findJsonFilesByPrefix(dir, 'ValueSet-');
         for (const file of jsonFiles) {
             try {
                 const content = JSON.parse(fs.readFileSync(file, 'utf-8'));
@@ -197,6 +197,37 @@ function findAllJsonFiles(dir) {
     }
     return results;
 }
+/**
+ * Find JSON files matching a filename prefix (e.g., "StructureDefinition-").
+ * FHIR packages name files by resourceType, so this avoids parsing thousands
+ * of irrelevant JSON files and dramatically reduces memory usage for large
+ * packages like hl7.fhir.r5.core (~2,970 files but only ~307 are SDs).
+ *
+ * Falls back to returning ALL JSON files when no prefix-matched files are found,
+ * because some packages (e.g. KBV) use non-standard naming conventions.
+ */
+function findJsonFilesByPrefix(dir, prefix) {
+    const prefixed = findJsonFilesMatching(dir, prefix);
+    if (prefixed.length > 0)
+        return prefixed;
+    // Non-standard naming — fall back to all JSON files
+    log.debug(`No files matching prefix "${prefix}" in ${dir}, falling back to all JSON files`);
+    return findAllJsonFiles(dir);
+}
+function findJsonFilesMatching(dir, prefix) {
+    let results = [];
+    const list = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of list) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results = results.concat(findJsonFilesMatching(fullPath, prefix));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".json") && entry.name.startsWith(prefix)) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
 /** Map FHIR version strings to slugs. */
 const FHIR_VERSION_TO_SLUG = {
     '4.0.0': 'r4', '4.0.1': 'r4',
@@ -209,8 +240,9 @@ const FHIR_VERSION_TO_SLUG = {
  * Returns the detected slug, or undefined if detection fails.
  */
 export function detectFhirVersion(extractedRoot) {
-    const jsonFiles = findAllJsonFiles(extractedRoot);
-    for (const file of jsonFiles) {
+    // Try ImplementationGuide files first (usually just 1)
+    const igFiles = findJsonFilesByPrefix(extractedRoot, 'ImplementationGuide-');
+    for (const file of igFiles) {
         try {
             const content = JSON.parse(fs.readFileSync(file, 'utf-8'));
             if (content.resourceType === 'ImplementationGuide') {
@@ -229,7 +261,8 @@ export function detectFhirVersion(extractedRoot) {
         }
     }
     // Fallback: check fhirVersion on first StructureDefinition found
-    for (const file of jsonFiles) {
+    const sdFiles = findJsonFilesByPrefix(extractedRoot, 'StructureDefinition-');
+    for (const file of sdFiles) {
         try {
             const content = JSON.parse(fs.readFileSync(file, 'utf-8'));
             if (content.resourceType === 'StructureDefinition' && content.fhirVersion) {
@@ -293,7 +326,7 @@ export async function extractPackage(packagePath) {
  * Reads all StructureDefinition resources from an already extracted package directory.
  */
 export function readStructureDefinitionsFromDir(extractedRoot) {
-    const jsonFiles = findAllJsonFiles(extractedRoot);
+    const jsonFiles = findJsonFilesByPrefix(extractedRoot, 'StructureDefinition-');
     const structureDefinitions = [];
     for (const file of jsonFiles) {
         try {
@@ -324,7 +357,7 @@ export async function createPackageFromDir(sourceDir, outFile) {
  * compose.include entries that reference a whole system without listing concepts.
  */
 export function readCodeSystemConceptsFromDir(extractedRoot) {
-    const jsonFiles = findAllJsonFiles(extractedRoot);
+    const jsonFiles = findJsonFilesByPrefix(extractedRoot, 'CodeSystem-');
     const map = {};
     for (const file of jsonFiles) {
         try {
@@ -367,7 +400,7 @@ function flattenCodeSystemConcepts(concepts) {
  * Each code entry has shape { code, system? } drawn from compose.include or expansion contains.
  */
 export function readValueSetCodesFromDir(extractedRoot, codeSystemMap) {
-    const jsonFiles = findAllJsonFiles(extractedRoot);
+    const jsonFiles = findJsonFilesByPrefix(extractedRoot, 'ValueSet-');
     const map = {};
     for (const file of jsonFiles) {
         try {
@@ -529,6 +562,28 @@ export async function ensureDependenciesDownloaded(extractedRoot) {
     }
     await walkDeps(extractedRoot);
 }
+/**
+ * Returns true for large HL7 base packages that should be skipped when walking
+ * dependency trees eagerly.  These packages contain thousands of JSON files and
+ * loading them all into memory causes OOM for R5 workloads.
+ *
+ * Core SDs are derived via `deriveVersionData()` / bundled base definitions.
+ * Extensions and terminology resources are fetched on-demand as needed.
+ */
+export function isLargeHl7Package(depName) {
+    // hl7.terminology.r5, hl7.terminology.r4, etc. — large CodeSystem/ValueSet packages
+    if (depName.startsWith('hl7.terminology'))
+        return true;
+    if (!depName.startsWith('hl7.fhir.'))
+        return false;
+    // hl7.fhir.r5.core, hl7.fhir.r4.core, etc.
+    if (depName.includes('.core'))
+        return true;
+    // hl7.fhir.uv.extensions.r5, hl7.fhir.uv.extensions.r4, etc.
+    if (depName.includes('extensions'))
+        return true;
+    return false;
+}
 /**
  * Reads StructureDefinitions from all dependency packages (recursively).
  * Returns SDs from dependencies only — the main package SDs are loaded separately.
@@ -560,6 +615,10 @@ export function readStructureDefinitionsFromDependencies(extractedRoot) {
             const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
             const deps = pkgJson.dependencies || {};
             for (const [depName, depVersion] of Object.entries(deps)) {
+                // Skip large HL7 base packages — core SDs are available via deriveVersionData /
+                // bundled base SDs, and extensions & terminology are fetched on-demand.
+                if (isLargeHl7Package(depName))
+                    continue;
                 for (const sep of ['@', '#']) {
                     const depDir = path.join(cacheDir, `${depName}${sep}${depVersion}`);
                     if (fs.existsSync(depDir)) {
@@ -608,6 +667,8 @@ export function readValueSetCodesWithDependencies(extractedRoot) {
             const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
             const deps = pkgJson.dependencies || {};
             for (const [depName, depVersion] of Object.entries(deps)) {
+                if (isLargeHl7Package(depName))
+                    continue;
                 const depDir = path.join(cacheDir, `${depName}@${depVersion}`);
                 if (fs.existsSync(depDir))
                     collectCodeSystems(depDir);
@@ -654,6 +715,8 @@ export function readValueSetCodesWithDependencies(extractedRoot) {
             const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
             const deps = pkgJson.dependencies || {};
             for (const [depName, depVersion] of Object.entries(deps)) {
+                if (isLargeHl7Package(depName))
+                    continue;
                 // Look for dependency in cache: name@version format
                 const depDir = path.join(cacheDir, `${depName}@${depVersion}`);
                 if (fs.existsSync(depDir)) {
@@ -683,7 +746,7 @@ export function readValueSetCodesWithDependencies(extractedRoot) {
  * This provides richer metadata than readValueSetCodesFromDir, including type generation capabilities.
  */
 export function readValueSetsFromDir(extractedRoot) {
-    const jsonFiles = findAllJsonFiles(extractedRoot);
+    const jsonFiles = findJsonFilesByPrefix(extractedRoot, 'ValueSet-');
     const map = new Map();
     for (const file of jsonFiles) {
         try {

package/out/src/generator/parser/sdFetcher.js

@@ -101,13 +101,12 @@ export async function fetchStructureDefinition(url, fallbackUrl) {
         url = url.replace(/^https?:\/\/hl7\.org\/fhir\/StructureDefinition\//, `http://hl7.org/fhir/${targetVersion}/StructureDefinition/`);
         logger.debug(`[fetchSD] Adjusted versionless FHIR URL to ${targetVersion}: ${originalUrl} -> ${url}`);
     }
-    // Special case: Base resource should always use resource.profile.json
-    if (url.includes('/StructureDefinition/Base') && url.includes('hl7.org/fhir')) {
-        const version = targetVersion;
-        const baseUrl = url.includes('https://') ? 'https://hl7.org/fhir' : 'http://hl7.org/fhir';
-        const resourceProfileUrl = `${baseUrl}/${version}/resource.profile.json`;
-        logger.debug(`[fetchSD] Base resource detected, redirecting to: ${resourceProfileUrl}`);
-        return fetchStructureDefinition(resourceProfileUrl, resourceProfileUrl);
+    // Special case: FHIR "Base" is the absolute root type with no parent.
+    // It has no meaningful fields to inherit. Return null to stop recursion.
+    // Note: Must match exactly /Base (not /BaseResource, /BaseSomething etc.)
+    if (/\/StructureDefinition\/Base$/.test(url) && url.includes('hl7.org/fhir')) {
+        logger.debug(`[fetchSD] Base type detected (FHIR root) — returning null to stop recursion`);
+        return null;
     }
     // First, check if we have this SD registered locally (from input directory)
     if (localStructureDefinitions.has(url)) {

package/out/src/generator/parser/sdParser.js

@@ -9,6 +9,8 @@ const log = logger.withTag('sdParser');
 // Re-export fetcher functions for backward compatibility
 export { fetchStructureDefinition, fetchStructureDefinitions, registerLocalStructureDefinitions, clearLocalStructureDefinitions, collectValueSetBindingUrls } from './sdFetcher.js';
 const processedBaseDefinitions = new Map(); // Track processed base resources
+// Guard against circular base-definition chains (e.g., Base → Base in R5)
+const _inFlightBaseUrls = new Set();
 /** Deep-clone an array of Field objects to prevent shared mutable state.
  *  Clones binding, patternConstraint, nestedCodingSlices (with their sub-objects),
  *  and requiredSlices so that mutations on one copy don't affect the other. */
@@ -84,8 +86,14 @@ export async function parseStructureDefinition(structureDefinition, fhirServerUr
             // modifying nestedCodingSlices) from bleeding between sibling profiles.
             baseFields = deepCloneFields(processedBaseDefinitions.get(baseDefinitionUrl) || []);
         }
+        else if (_inFlightBaseUrls.has(baseDefinitionUrl)) {
+            // Circular base-definition chain detected (e.g., Base → Base in R5).
+            // Treat as root type — no inherited fields.
+            log.log(`Circular baseDefinition detected for ${baseDefinitionUrl}, treating as root type.`);
+        }
         else {
             log.log(`Fetching base resource for StructureDefinition ${structureDefinition.id || "unknown"}: ${baseDefinitionUrl}`);
+            _inFlightBaseUrls.add(baseDefinitionUrl);
             // Only use fhirServerUrl if it's a valid HTTP URL AND it's not a canonical StructureDefinition URL
             // (fhirServerUrl should be a server base like "https://server.com", not a full StructureDefinition URL)
             const isValidHttpUrl = fhirServerUrl && (fhirServerUrl.startsWith('http://') || fhirServerUrl.startsWith('https://'));
@@ -138,6 +146,7 @@ export async function parseStructureDefinition(structureDefinition, fhirServerUr
                     impact: 'Generated code may have wrong types; validators cannot fully evaluate this profile.',
                 });
             }
+            _inFlightBaseUrls.delete(baseDefinitionUrl);
         }
     }
     const elements = structureDefinition.snapshot?.element || structureDefinition.differential?.element || [];

package/out/src/generator/sdProcessorHelpers.js

@@ -6,6 +6,7 @@ import fs from 'fs';
 import { logger } from '../logger.js';
 import { generateRandomSupportContent } from './emitters/class/randomSupportGenerator.js';
 import { generateValidatorOptionsContent } from './emitters/validator/validatorGenerator.js';
+import { ctx } from './fhir/versionContext.js';
 // ── Fetch failure tracking ─────────────────────────────────────────
 let failedFetchCount = 0;
 const failedFetchProfiles = [];
@@ -35,8 +36,13 @@ export function getFetchFailureWarning() {
         `Note: The .cache folder has been preserved to speed up the next generation attempt.\n`;
 }
 // ── FHIR complex type child map ────────────────────────────────────
-/** Map of FHIR complex type child field names to their primitive types */
-const COMPLEX_TYPE_CHILDREN = {
+/**
+ * Static fallback for complex type child fields.
+ * Used when ctx().dataTypes is not yet populated (early init) or for types
+ * not present in the derived data.  The canonical source of truth is
+ * ctx().dataTypes which is derived from the real FHIR core SDs.
+ */
+const COMPLEX_TYPE_CHILDREN_FALLBACK = {
     Quantity: { value: 'decimal', comparator: 'code', unit: 'string', system: 'uri', code: 'code' },
     Money: { value: 'decimal', currency: 'code' },
     Identifier: { use: 'code', system: 'uri', value: 'string' },
@@ -53,11 +59,23 @@ const COMPLEX_TYPE_CHILDREN = {
     Count: { value: 'decimal', comparator: 'code', unit: 'string', system: 'uri', code: 'code' },
     Distance: { value: 'decimal', comparator: 'code', unit: 'string', system: 'uri', code: 'code' },
     Timing: { event: 'dateTime' },
-    SampledData: { period: 'decimal', dimensions: 'positiveInt', data: 'string' },
 };
-/** Resolve the type of a child field within a known FHIR complex type */
+/**
+ * Resolve the type of a child field within a known FHIR complex type.
+ * Prefers the version-derived ctx().dataTypes (which handles cross-version
+ * differences like SampledData automatically), falling back to the static map.
+ */
 export function resolveComplexTypeChildType(parentType, childName) {
-    return COMPLEX_TYPE_CHILDREN[parentType]?.[childName];
+    // Primary: version-derived data (works for any FHIR version)
+    try {
+        const derived = ctx().dataTypes[parentType];
+        if (derived?.[childName])
+            return derived[childName].type;
+    }
+    catch {
+        // ctx() not yet initialised — fall through to static map
+    }
+    return COMPLEX_TYPE_CHILDREN_FALLBACK[parentType]?.[childName];
 }
 // ── Support file generators ────────────────────────────────────────
 /** Ensure RandomSupport.ts exists in a generation output directory */

package/out/src/generator/timing.js

@@ -0,0 +1,43 @@
+/**
+ * Lightweight generation-phase timer.
+ *
+ * Usage:
+ *   resetTimings();
+ *   const end = startPhase('fetch');
+ *   await doWork();
+ *   end();
+ *   // … more phases …
+ *   const summary = getTimingSummary();  // { phases: { fetch: 1234, … }, totalMs: 5678 }
+ */
+let _phases = {};
+let _wallStart = 0;
+/** Clear all recorded timings and start the wall clock. */
+export function resetTimings() {
+    _phases = {};
+    _wallStart = performance.now();
+}
+/**
+ * Begin timing a named phase.  Returns a callback to call when the phase ends.
+ * If the same phase name is used multiple times the durations are summed.
+ */
+export function startPhase(name) {
+    const t0 = performance.now();
+    return () => {
+        const elapsed = performance.now() - t0;
+        _phases[name] = (_phases[name] ?? 0) + elapsed;
+    };
+}
+/** Get the timing summary (all phases + wall-clock total). */
+export function getTimingSummary() {
+    return {
+        phases: { ...(_phases) },
+        totalMs: Math.round(performance.now() - _wallStart),
+    };
+}
+/** Format the summary as a human-readable string for console output. */
+export function formatTimingSummary(summary) {
+    const fmt = (ms) => ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`;
+    const lines = Object.entries(summary.phases).map(([name, ms]) => `  ${name}: ${fmt(ms)}`);
+    lines.push(`  total: ${fmt(summary.totalMs)}`);
+    return `⏱  Generation timing\n${lines.join('\n')}`;
+}

package/out/src/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { generateIntoPackage, generateForDirectory, generateFromJsonFile, generateFromProfileUrl, resetFetchFailureTracking, getFetchFailureWarning } from "./generator/index.js";
+import { generateIntoPackage, generateForDirectory, generateFromJsonFile, generateFromProfileUrl, resetFetchFailureTracking, getFetchFailureWarning, getTimingSummary, formatTimingSummary } from "./generator/index.js";
 import { generateClient } from "./generator/emitters/client/clientGenerator.js";
 import { extractPackage } from "./generator/parser/packageParser.js";
 import { getCacheConfig, getFhirPackagesCacheDir, clearAllCaches, ensureCacheDir, setCacheConfig } from "./generator/core/cacheConfig.js";
@@ -113,6 +113,10 @@ function completeGeneration(flags, outputDir) {
     const summary = formatReportSummary(report);
     if (summary.trim())
         console.log(summary);
+    // Print generation timing summary
+    const timing = getTimingSummary();
+    if (timing.totalMs > 0)
+        console.log(formatTimingSummary(timing));
     const hasWarnings = showGenerationWarnings();
     if (!hasWarnings && flags.noCache) {
         cleanupCache();

package/package.json

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