fhir-terminology-runtime 0.1.0 → 1.0.0

package/README.md

@@ -398,7 +398,7 @@ Consider a large ValueSet `VS` and a code lookup `inValueSet('C10', VS)`:
 #### Priming is not ValueSet expansion caching
 
 FTR has two separate caching concepts:
-- **Expansion caching**: stores the expanded ValueSet JSON on disk under `.ftr/` alongside packages.
+- **Expansion caching**: stores the expanded ValueSet JSON on disk under `.ftr.expansions/` alongside package contents.
 - **Membership caching**: accelerates `inValueSet` lookups (in-memory LRUs + optional external cache).
 
 “Priming” only refers to the **external membership cache** behavior.
@@ -422,7 +422,7 @@ When expanding ValueSets the runtime resolves referenced CodeSystems by canonica
 
 ### Expansion Caching
 
-Expanded (or fallback) ValueSets are cached in a dedicated `.ftr` directory alongside source packages. Repeated calls reuse the cached expansion unless `cacheMode` is `none`.
+Expanded (or fallback) ValueSets are cached in a dedicated `.ftr.expansions/` directory inside package folders in the FHIR package cache folder. Repeated calls reuse the cached expansion unless `cacheMode` is `none`.
 
 ## Context
 You must provide an array of FHIR packages in `context`. Any package or its dependencies missing in the local FHIR package cache will be downloaded and installed (by [`fhir-package-installer`](https://github.com/Outburn-IL/fhir-package-installer)).
@@ -447,7 +447,7 @@ Supports `<id>#<version>`, `<id>@<version>`, `<id>` (latest version) or a packag
 Cached artifacts are stored under:
 
 ```
-<cachePath>/<packageId>#<packageVersion>/.ftr/<FTR version>/
+<cachePath>/<packageId>#<packageVersion>/.ftr.expansions/<FTR version>/
 ```
 - Filenames mirror originals in `<cachePath>/<packageId>#<packageVersion>/package`.
 - FTR Version directory uses major.minor.x (e.g. `0.1.x`).

package/dist/index.cjs

@@ -958,36 +958,13 @@ var ImplicitCodeSystemRegistry = class {
   }
 };
 
-// src/utils/logger.ts
-var defaultLogger = {
-  info: (msg) => console.log(msg),
-  warn: (msg) => console.warn(msg),
-  error: (msg) => console.error(msg)
-};
-var defaultPrethrow = (msg) => {
-  if (msg instanceof Error) {
-    return msg;
-  }
-  const error = new Error(msg);
-  return error;
-};
-var customPrethrower = (logger) => {
-  return (msg) => {
-    if (msg instanceof Error) {
-      logger.error(msg);
-      return msg;
-    }
-    const error = new Error(msg);
-    logger.error(error);
-    return error;
-  };
-};
-
 // package.json
-var version = "0.1.0";
+var version = "1.0.0";
 
 // src/index.ts
 var versionedCacheDir = `v${version.split(".").slice(0, 2).join(".")}.x`;
+var FTR_VERSION_EXTENSION_URL = "http://fhir.fume.health/StructureDefinition/ftr-version";
+var FTR_EXPANSION_FAILED_EXTENSION_URL = "http://fhir.fume.health/StructureDefinition/ftr-expansion-failed";
 var FTR_DEFAULT_LIMITS = {
   valueSet: {
     smallThresholdUniqueCodes: 50,
@@ -1033,13 +1010,16 @@ var FhirTerminologyRuntime = class _FhirTerminologyRuntime {
     // Cache for resolving server ConceptMap identifiers (url/id/name) -> deterministic server key.
     // Keyed by baseUrl + identifier.
     this.serverConceptMapIdentifierKeyCache = /* @__PURE__ */ new Map();
-    if (logger) {
-      this.logger = logger;
-      this.prethrow = customPrethrower(this.logger);
-    } else {
-      this.logger = defaultLogger;
-      this.prethrow = defaultPrethrow;
-    }
+    this.logger = logger || {
+      debug: () => {
+      },
+      info: () => {
+      },
+      warn: () => {
+      },
+      error: () => {
+      }
+    };
     this.cacheMode = cacheMode;
     this.fhirVersion = fhirVersion;
     this.fpe = fpe;
@@ -1058,55 +1038,49 @@ var FhirTerminologyRuntime = class _FhirTerminologyRuntime {
    * @returns - A promise that resolves to a new instance of the FhirTerminologyRuntime class
    */
   static async create(config) {
-    const logger = config.logger || defaultLogger;
-    const prethrow = config.logger ? customPrethrower(logger) : defaultPrethrow;
-    try {
-      const cacheMode = config.cacheMode || "lazy";
-      const fhirVersion = config.fhirVersion || "4.0.1";
-      const fpe = config.fpe;
-      const ftr = new _FhirTerminologyRuntime(
-        fpe,
-        cacheMode,
-        fhirVersion,
-        config.logger,
-        config.membershipCache,
-        config.conceptMapCache,
-        config.fhirClient
-      );
-      let precache = false;
-      if (cacheMode === "rebuild") {
-        precache = true;
-        const packageList = fpe.getContextPackages().map((pkg) => path__default.default.join(fpe.getCachePath(), `${pkg.id}#${pkg.version}`, ".ftr.expansions", versionedCacheDir));
-        for (const expansionCacheDir of packageList) {
-          if (await fs__default.default.exists(expansionCacheDir)) {
-            fs__default.default.removeSync(expansionCacheDir);
-          }
+    const cacheMode = config.cacheMode || "lazy";
+    const fhirVersion = config.fhirVersion || "4.0.1";
+    const fpe = config.fpe;
+    const ftr = new _FhirTerminologyRuntime(
+      fpe,
+      cacheMode,
+      fhirVersion,
+      config.logger,
+      config.membershipCache,
+      config.conceptMapCache,
+      config.fhirClient
+    );
+    let precache = false;
+    if (cacheMode === "rebuild") {
+      precache = true;
+      const packageList = fpe.getContextPackages().map((pkg) => path__default.default.join(fpe.getCachePath(), `${pkg.id}#${pkg.version}`, ".ftr.expansions", versionedCacheDir));
+      for (const expansionCacheDir of packageList) {
+        if (await fs__default.default.exists(expansionCacheDir)) {
+          fs__default.default.removeSync(expansionCacheDir);
         }
       }
-      if (cacheMode === "ensure") precache = true;
-      if (precache) {
-        logger.info(`Pre-caching ValueSet expansions in '${cacheMode}' mode...`);
-        const vsErrors = [];
-        const allVs = await fpe.lookupMeta({ resourceType: "ValueSet" });
-        for (const vs of allVs) {
-          const { filename, __packageId: packageId, __packageVersion: packageVersion, url } = vs;
-          try {
-            await ftr.ensureExpansionCached(filename, packageId, packageVersion);
-          } catch (e) {
-            vsErrors.push(`Failed to ${cacheMode} expansion for '${url || filename}' in package '${packageId}@${packageVersion}': ${e instanceof Error ? e.message : String(e)}`);
-          }
+    }
+    if (cacheMode === "ensure") precache = true;
+    if (precache) {
+      ftr.getLogger().info(`Pre-caching ValueSet expansions in '${cacheMode}' mode...`);
+      const vsErrors = [];
+      const allVs = await fpe.lookupMeta({ resourceType: "ValueSet" });
+      for (const vs of allVs) {
+        const { filename, __packageId: packageId, __packageVersion: packageVersion, url } = vs;
+        try {
+          await ftr.ensureExpansionCached(filename, packageId, packageVersion);
+        } catch (e) {
+          vsErrors.push(`Failed to ${cacheMode} expansion for '${url || filename}' in package '${packageId}@${packageVersion}': ${e instanceof Error ? e.message : String(e)}`);
         }
-        if (vsErrors.length > 0) {
-          logger.warn(`Errors during pre-caching ValueSet expansions (${vsErrors.length} total):
+      }
+      if (vsErrors.length > 0) {
+        ftr.getLogger().warn(`Errors during pre-caching ValueSet expansions (${vsErrors.length} total):
 ${vsErrors.join("\n")}`);
-        } else {
-          logger.info(`Pre-caching ValueSet expansions in '${cacheMode}' mode completed successfully.`);
-        }
+      } else {
+        ftr.getLogger().info(`Pre-caching ValueSet expansions in '${cacheMode}' mode completed successfully.`);
       }
-      return ftr;
-    } catch (e) {
-      throw prethrow(e);
     }
+    return ftr;
   }
   getLogger() {
     return this.logger;
@@ -1130,6 +1104,33 @@ ${vsErrors.join("\n")}`);
   async getValueSetByFileName(filename, packageId, packageVersion) {
     return await this.fpe.resolve({ filename, package: { id: packageId, version: packageVersion } });
   }
+  withFtrVersionExtensionInExpansion(resource) {
+    const expansion = resource?.expansion;
+    if (!expansion || typeof expansion !== "object") return resource;
+    const existing = Array.isArray(expansion.extension) ? expansion.extension : [];
+    const alreadyPresent = existing.some((e) => e?.url === FTR_VERSION_EXTENSION_URL);
+    if (alreadyPresent) return resource;
+    const nextExpansion = {
+      ...expansion,
+      extension: existing.concat([{ url: FTR_VERSION_EXTENSION_URL, valueCode: version }])
+    };
+    return { ...resource, expansion: nextExpansion };
+  }
+  getExtensionValue(expansion, url) {
+    const ext = Array.isArray(expansion?.extension) ? expansion.extension : [];
+    return ext.find((e) => e?.url === url);
+  }
+  getFtrVersionFromExpansion(resource) {
+    const exp = resource?.expansion;
+    const ext = this.getExtensionValue(exp, FTR_VERSION_EXTENSION_URL);
+    return typeof ext?.valueCode === "string" && ext.valueCode.length > 0 ? ext.valueCode : void 0;
+  }
+  isExpansionMarkedFailed(resource) {
+    if (resource?.expansion?.__failure === true) return true;
+    const exp = resource?.expansion;
+    const ext = this.getExtensionValue(exp, FTR_EXPANSION_FAILED_EXTENSION_URL);
+    return ext?.valueBoolean === true;
+  }
   stableStringify(value) {
     const seen = /* @__PURE__ */ new WeakSet();
     const normalize = (v) => {
@@ -1497,10 +1498,14 @@ ${vsErrors.join("\n")}`);
     const { filename, __packageId: packageId, __packageVersion: packageVersion } = metadata;
     const cached = this.cacheMode !== "none" ? await this.getExpansionFromCache(filename, packageId, packageVersion) : void 0;
     if (cached) {
-      if (cached?.expansion?.__failure === true) {
-        throw new Error(`Previous expansion attempt failed for ValueSet '${cached.url || cached.id || filename}' (cached).`);
+      if (this.isExpansionMarkedFailed(cached)) {
+        const cachedVersion = this.getFtrVersionFromExpansion(cached);
+        if (cachedVersion === version) {
+          throw new Error(`Previous expansion attempt failed for ValueSet '${cached.url || cached.id || filename}' (cached).`);
+        }
+      } else {
+        return this.withFtrVersionExtensionInExpansion(cached);
       }
-      return cached;
     }
     const vs = await this.getValueSetByFileName(filename, packageId, packageVersion);
     if (!vs || vs.resourceType !== "ValueSet") throw new Error(`File '${filename}' not found as a ValueSet in package '${packageId}@${packageVersion}'.`);
@@ -1520,7 +1525,15 @@ ${vsErrors.join("\n")}`);
       }
       this.subtractSystemMaps(includeMap, excludeMap);
       const { contains, total } = this.buildExpansionFromSystemMap(includeMap);
-      const expanded = { ...vs, expansion: { timestamp: (/* @__PURE__ */ new Date()).toISOString(), total, contains } };
+      const expanded = {
+        ...vs,
+        expansion: {
+          extension: [{ url: FTR_VERSION_EXTENSION_URL, valueCode: version }],
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          total,
+          contains
+        }
+      };
       if (this.cacheMode !== "none") {
         await this.saveExpansionToCache(filename, packageId, packageVersion, expanded);
       }
@@ -1528,13 +1541,23 @@ ${vsErrors.join("\n")}`);
     } catch (e) {
       this.logger.warn(`Failed to expand ValueSet '${vs?.url || vs?.id || filename}': ${e instanceof Error ? e.message : String(e)}. Falling back to original expansion if present.`);
       if (vs?.expansion?.contains && Array.isArray(vs.expansion.contains)) {
+        const normalized = this.withFtrVersionExtensionInExpansion(vs);
         if (this.cacheMode !== "none") {
-          await this.saveExpansionToCache(filename, packageId, packageVersion, vs);
+          await this.saveExpansionToCache(filename, packageId, packageVersion, normalized);
         }
-        return vs;
+        return normalized;
       }
       if (this.cacheMode !== "none") {
-        const failureStub = { ...vs, expansion: { timestamp: (/* @__PURE__ */ new Date()).toISOString(), __failure: true } };
+        const failureStub = {
+          ...vs,
+          expansion: {
+            extension: [
+              { url: FTR_VERSION_EXTENSION_URL, valueCode: version },
+              { url: FTR_EXPANSION_FAILED_EXTENSION_URL, valueBoolean: true }
+            ],
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        };
         try {
           await this.saveExpansionToCache(filename, packageId, packageVersion, failureStub);
         } catch {
@@ -1561,25 +1584,21 @@ ${vsErrors.join("\n")}`);
    * Get ValueSet expansion by any FSH style identifier (id, url or name), or by a metadata object.
    */
   async expandValueSet(identifier, packageFilter) {
-    try {
-      let metadata;
-      if (typeof identifier === "string") {
-        metadata = await this.getValueSetMetadata(identifier, packageFilter);
-        if (!metadata) {
-          throw new Error(`ValueSet '${identifier}' not found in context. Could not get or generate an expansion.`);
-        }
-      } else {
-        metadata = identifier;
-        if (!metadata) {
-          throw new Error(`ValueSet with metadata: 
+    let metadata;
+    if (typeof identifier === "string") {
+      metadata = await this.getValueSetMetadata(identifier, packageFilter);
+      if (!metadata) {
+        throw new Error(`ValueSet '${identifier}' not found in context. Could not get or generate an expansion.`);
+      }
+    } else {
+      metadata = identifier;
+      if (!metadata) {
+        throw new Error(`ValueSet with metadata: 
 ${JSON.stringify(identifier, null, 2)}
 not found in context. Could not get or generate an expansion.`);
-        }
       }
-      return await this.expandValueSetByMeta(metadata);
-    } catch (e) {
-      throw this.prethrow(e);
     }
+    return await this.expandValueSetByMeta(metadata);
   }
   /**
    * Get the count of concepts in the expansion of a ValueSet.
@@ -1633,55 +1652,51 @@ not found in context. Could not get or generate an expansion.`);
    * @returns The full CodeSystem resource (content=complete).
    */
   async resolveCompleteCodeSystem(url, sourcePackage) {
-    try {
-      if (!url) {
-        throw new Error("CodeSystem canonical URL missing.");
-      }
-      if (ImplicitCodeSystemRegistry.isImplicitCodeSystem(url)) {
-        const concepts = ImplicitCodeSystemRegistry.getConcepts(url);
-        if (!concepts) {
-          throw new Error(`Implicit CodeSystem '${url}' provider returned no concepts.`);
-        }
-        return {
-          resourceType: "CodeSystem",
-          url,
-          status: "active",
-          content: "complete",
-          concept: Array.from(concepts.entries()).map(([code, display]) => ({
-            code,
-            display
-          }))
-        };
+    if (!url) {
+      throw new Error("CodeSystem canonical URL missing.");
+    }
+    if (ImplicitCodeSystemRegistry.isImplicitCodeSystem(url)) {
+      const concepts = ImplicitCodeSystemRegistry.getConcepts(url);
+      if (!concepts) {
+        throw new Error(`Implicit CodeSystem '${url}' provider returned no concepts.`);
       }
-      let meta;
+      return {
+        resourceType: "CodeSystem",
+        url,
+        status: "active",
+        content: "complete",
+        concept: Array.from(concepts.entries()).map(([code, display]) => ({
+          code,
+          display
+        }))
+      };
+    }
+    let meta;
+    try {
+      meta = await this.resolveMetaCached({ resourceType: "CodeSystem", url, package: sourcePackage });
+    } catch {
+    }
+    if (!meta) {
       try {
-        meta = await this.resolveMetaCached({ resourceType: "CodeSystem", url, package: sourcePackage });
+        meta = await this.resolveMetaCached({ resourceType: "CodeSystem", url });
       } catch {
+        throw new Error(`CodeSystem '${url}' not found (searched in package '${sourcePackage.id}@${sourcePackage.version}' then globally).`);
       }
-      if (!meta) {
-        try {
-          meta = await this.resolveMetaCached({ resourceType: "CodeSystem", url });
-        } catch {
-          throw new Error(`CodeSystem '${url}' not found (searched in package '${sourcePackage.id}@${sourcePackage.version}' then globally).`);
-        }
-      }
-      if (!meta?.content || typeof meta?.content === "string" && meta.content !== "complete") {
-        throw new Error(`CodeSystem '${url}' has content='${meta.content}' and cannot be expanded (only 'complete' supported).`);
-      }
-      const cs = await this.fpe.resolve({ filename: meta.filename, package: { id: meta.__packageId, version: meta.__packageVersion } });
-      if (!cs) {
-        throw new Error(`Failed to load CodeSystem '${url}' from package '${meta.__packageId}@${meta.__packageVersion}'.`);
-      }
-      if (cs.resourceType !== "CodeSystem") {
-        throw new Error(`Resolved resource for '${url}' is not a CodeSystem (got '${cs.resourceType || "unknown"}').`);
-      }
-      if (cs.content !== "complete") {
-        throw new Error(`CodeSystem '${url}' has content='${cs.content || "undefined"}' and cannot be expanded (only 'complete' supported).`);
-      }
-      return cs;
-    } catch (e) {
-      throw this.prethrow(e);
     }
+    if (!meta?.content || typeof meta?.content === "string" && meta.content !== "complete") {
+      throw new Error(`CodeSystem '${url}' has content='${meta.content}' and cannot be expanded (only 'complete' supported).`);
+    }
+    const cs = await this.fpe.resolve({ filename: meta.filename, package: { id: meta.__packageId, version: meta.__packageVersion } });
+    if (!cs) {
+      throw new Error(`Failed to load CodeSystem '${url}' from package '${meta.__packageId}@${meta.__packageVersion}'.`);
+    }
+    if (cs.resourceType !== "CodeSystem") {
+      throw new Error(`Resolved resource for '${url}' is not a CodeSystem (got '${cs.resourceType || "unknown"}').`);
+    }
+    if (cs.content !== "complete") {
+      throw new Error(`CodeSystem '${url}' has content='${cs.content || "undefined"}' and cannot be expanded (only 'complete' supported).`);
+    }
+    return cs;
   }
   /**
    * Check whether a code (string) or Coding-like object is a member of a ValueSet.
@@ -1883,7 +1898,7 @@ not found in context. Could not get or generate an expansion.`);
     if (!cmKey) {
       const err = new Error(`ConceptMap '${typeof conceptMap === "string" ? conceptMap : conceptMap?.filename || "unknown"}' could not be resolved.`);
       err.errors = errors;
-      throw this.prethrow(err);
+      throw err;
     }
     const cmKeyStr = this.toConceptMapKeyString(cmKey);
     const smallIndex = this.smallConceptMapIndexLru.get(cmKeyStr);
@@ -1917,12 +1932,12 @@ not found in context. Could not get or generate an expansion.`);
     } catch (e) {
       const err = new Error(`Failed to load ConceptMap for key '${cmKeyStr}'.`);
       err.errors = errors.concat([e]);
-      throw this.prethrow(err);
+      throw err;
     }
     if (!cm || cm.resourceType !== "ConceptMap") {
       const err = new Error(`Resolved ConceptMap '${cmKeyStr}' is not a ConceptMap.`);
       err.errors = errors;
-      throw this.prethrow(err);
+      throw err;
     }
     const flatIndex = buildIndexFromConceptMap(cm);
     if (flatIndex.uniqueSourceCodeCount <= FTR_DEFAULT_LIMITS.conceptMap.smallThresholdUniqueSourceCodes) {