fhir-snapshot-generator/dist/index.d.ts

Generate snapshots for FHIR Profiles

import { ExplorerConfig, FhirPackageExplorer, PackageIdentifier, FileIndexEntryWithPkg } from 'fhir-package-explorer';
export { PackageIdentifier } from 'fhir-package-explorer';

/**
 * © Copyright Outburn Ltd. 2022-2025 All Rights Reserved
 *   Project name: fhir-snapshot-generator
 */

interface ILogger {
    info: (msg: any) => void;
    warn: (msg: any) => void;
    error: (msg: any) => void;
}
type Prethrower = (msg: Error | any) => Error;
interface ElementDefinition {
    id: string;
    path: string;
    extension?: FhirExtensionInstance[];
    min?: number;
    max?: string;
    type?: ElementDefinitionType[];
    slicing?: ElementDefinitionSlicing;
    sliceName?: string;
    fixedUri?: string;
    binding?: ElementDefinitionBinding;
    short?: string;
    definition?: string;
    comment?: string;
    requirements?: string;
    meaningWhenMissing?: string;
    [key: string]: any;
}
type FhirExtensionInstance = {
    url: string;
    [key: string]: any;
};
type ElementConstraint = {
    source?: string;
    [key: string]: any;
};
interface ElementDefinitionType {
    code: string;
    profile?: string[];
    targetProfile?: string[];
    extension?: any;
}
interface ElementDefinitionSlicing {
    discriminator: SlicingDiscriminator[];
    rules: 'closed' | 'open' | 'openAtEnd';
    description?: string;
    ordered?: boolean;
}
interface SlicingDiscriminator {
    type: 'value' | 'exists' | 'pattern' | 'type' | 'profile';
    path: string;
}
interface ElementDefinitionBinding {
    strength: 'required' | 'extensible' | 'preferred' | 'example';
    valueSet?: string;
}
interface FhirTreeNode {
    id: string;
    path: string;
    definition?: ElementDefinition;
    children: FhirTreeNode[];
    idSegments: string[];
    pathSegments: string[];
    nodeType: 'element' | 'array' | 'poly' | 'slice' | 'resliced' | 'headslice';
    sliceName?: string;
}
/**
 * Snapshot caching strategy.
 *
 * - `'lazy'`: Default. Generate each snapshot on demand and cache it afterward.
 * - `'ensure'`: Proactively generate and cache all **missing** snapshots.
 * - `'rebuild'`: Regenerate **all** snapshots and overwrite existing cache entries.
 * - `'none'`: Fully bypass the cache. Always regenerate snapshots and do not write to cache.
 */
type SnapshotCacheMode = 'lazy' | 'ensure' | 'rebuild' | 'none';
type BaseFhirVersion = '3.0.2' | '4.0.1' | '4.3.0' | '5.0.0' | '3.0' | '4.0' | '4.3' | '5.0' | 'R3' | 'STU3' | 'R4' | 'R4B' | 'R5';
type SnapshotGeneratorConfig = Omit<ExplorerConfig, 'skipExamples'> & {
    /**
     * Determines how snapshot caching is handled.
     * Defaults to `'lazy'` if not specified.
     */
    cacheMode?: SnapshotCacheMode;
    /**
     * The FHIR version to use for the snapshot generation.
     * This is used to determine the FHIR core package to use when fetching base FHIR types.
     * Defaults to 4.0.1 if not specified.
     */
    fhirVersion?: BaseFhirVersion;
};
type SnapshotFetcher = (url: string) => Promise<ElementDefinition[]>;

/**
 * © Copyright Outburn Ltd. 2022-2025 All Rights Reserved
 *   Project name: fhir-snapshot-generator
 */
/**
 * Implicit code systems that are not distributed in FHIR packages but are assumed
 * to be supported by the handling system. These are code systems with content='not-present'
 * that we can expand internally using external data sources.
 */
interface ImplicitCodeSystemProvider {
    /** The canonical URL of the code system */
    canonicalUrl: string;
    /** Function to get all concepts in the code system */
    getConcepts: () => Map<string, string | undefined>;
}
/**
 * Registry of all supported implicit code systems
 */
declare class ImplicitCodeSystemRegistry {
    private static providers;
    /**
     * Check if a canonical URL corresponds to an implicit code system
     */
    static isImplicitCodeSystem(canonicalUrl: string): boolean;
    /**
     * Get the provider for an implicit code system
     */
    static getProvider(canonicalUrl: string): ImplicitCodeSystemProvider | undefined;
    /**
     * Get all concepts for an implicit code system
     */
    static getConcepts(canonicalUrl: string): Map<string, string | undefined> | undefined;
    /**
     * Get all supported implicit code system URLs
     */
    static getSupportedSystems(): string[];
}

/**
 * © Copyright Outburn Ltd. 2022-2025 All Rights Reserved
 *   Project name: fhir-snapshot-generator
 */

declare class FhirSnapshotGenerator {
    private fpe;
    private logger;
    private prethrow;
    private cachePath;
    private cacheMode;
    private fhirVersion;
    private fhirCorePackage;
    private resolvedBasePackages;
    private constructor();
    /**
     * Creates a new instance of the FhirSnapshotGenerator class.
     * @param config - the configuration object for the FhirPackageExplorer
     * @returns - a promise that resolves to a new instance of the FhirSnapshotGenerator class
     */
    static create(config: SnapshotGeneratorConfig): Promise<FhirSnapshotGenerator>;
    getLogger(): ILogger;
    getCachePath(): string;
    getCacheMode(): SnapshotCacheMode;
    getFhirVersion(): BaseFhirVersion;
    getFpe(): FhirPackageExplorer;
    /**
     * Get the core FHIR package for a specific FHIR package.
     * Will try to resolve the core package based on the direct dependencies of the source package or its fhirVersions array.
     * Defaults to the FHIR package of this instance's fhirVersion if no base package can be determined.
     * @param sourcePackage The source package identifier (e.g., { id: 'hl7.fhir.us.core', version: '6.1.0' }).
     * @returns The core FHIR package identifier (e.g., { id: 'hl7.fhir.r4.core', version: '4.0.1' }).
     */
    private getCorePackage;
    /**
     * Get an original StructureDefinition from a specific package by filename.
     * After resolving the metadata using any other identifier (id, url, name), filename (combind with the package id and version)
     * is the most reliable way to get to a specific StructureDefinition, and is also used as the basis for the cache.
     */
    private getStructureDefinitionByFileName;
    private getCacheFilePath;
    /**
     * Try to get an existing cached StructureDefinition snapshot. If not found, return undefined.
     */
    private getSnapshotFromCache;
    private saveSnapshotToCache;
    /**
     * Fetch StructureDefinition metadata by any identifier (id, url, name) - FSH style.
     */
    getMetadata(identifier: string, packageFilter?: PackageIdentifier): Promise<FileIndexEntryWithPkg>;
    /**
     * Generate a snapshot for a StructureDefinition.
     */
    private generate;
    /**
     * Get snapshot by metadata.
     */
    private getSnapshotByMeta;
    private getValueSetByFileName;
    private getValueSetMetadata;
    private getExpansionFromCache;
    private saveExpansionToCache;
    private flattenCodeSystemConcepts;
    private toSystemCodeMapFromContains;
    private mergeSystemMaps;
    private subtractSystemMaps;
    private buildExpansionFromSystemMap;
    private expandInclude;
    private expandValueSetByMeta;
    private ensureExpansionCached;
    private ensureSnapshotCached;
    /**
     * Get snapshot by any FSH style identifier (id, url or name), or by a metadata object.
     */
    getSnapshot(identifier: string | FileIndexEntryWithPkg, packageFilter?: PackageIdentifier): Promise<any>;
    /**
     * Get ValueSet expansion by any FSH style identifier (id, url or name), or by a metadata object.
     */
    expandValueSet(identifier: string | FileIndexEntryWithPkg, packageFilter?: PackageIdentifier): Promise<any>;
    /**
     * Resolve a CodeSystem by canonical URL inside the provided source package context.
     * Will NOT attempt a global resolution fallback (that is the responsibility of the external caller / entrypoint).
     * Only CodeSystems with content === 'complete' are eligible for expansion; if not complete an error is thrown.
     * @param url Canonical URL of the CodeSystem.
     * @param sourcePackage The package (id + version) of the ValueSet that is triggering this resolution.
     * @returns The full CodeSystem resource (content=complete).
     */
    resolveCompleteCodeSystem(url: string, sourcePackage: PackageIdentifier): Promise<any>;
}

export { type BaseFhirVersion, type ElementConstraint, type ElementDefinition, type ElementDefinitionBinding, type ElementDefinitionSlicing, type ElementDefinitionType, type FhirExtensionInstance, FhirSnapshotGenerator, type FhirTreeNode, type ILogger, ImplicitCodeSystemRegistry, type Prethrower, type SlicingDiscriminator, type SnapshotCacheMode, type SnapshotFetcher, type SnapshotGeneratorConfig };