fhirsmith 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to the Health Intersections Node Server will be documented i
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-mm-dd
+
+### Added
+
+- Upgrade the tx registry module to support exclusions and languages
+- Add support for sealed caches 
+
+### Changed
+
+- rework caching
+- Remember filter analysis on cached value sets 
+- Improved Rendering for CodeSystem and ValueSets
+- Update ECL & tests given ECL functionality confirmations
+- Update snomed subset from test IG
+- improved error when multiple cache-id headers passed to the server
+- fix slow crawling for FHIRsmith servers by the tx registry
+- make tx search page size default to 1000 for json/xml and leave it at 20 for html
+- rework batch processing for caches
+
+### Fixed
+
+- Report the FIRST matching coding, not the last, and only one message about status
+- rework how expansions on complex codesystems are handled
+- better handling of expansions on grammar based systems
+- (SNOMED CT) consistent use of designations
+- give preferredForLanguage a display in expansions
+- fix various ECL processing bugs
+- fix precedence order problem loading THO content after core content
+- fix links in metadata statements 
+- fix unhandled promises 
+- fix handling of properties in R4 expansions
+- fix bug validating codes from erroneously coded R4 v2 tables
+ 
+### Tx Conformance Statement
+
+FHIRsmith passed all 2729 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed, tests v1.9.2, runner v6.9.12
 
 ## [v0.10.1] - 2026-06-27
 

package/changelog-template.md

@@ -0,0 +1,22 @@
+## [m.n.p] - 2026-mm-dd
+
+### Security
+
+- 
+
+### Added
+
+- 
+
+### Changed
+
+- 
+
+### Fixed
+
+- 
+
+### Tx Conformance Statement
+
+(paste)
+

package/library/logger.js

@@ -226,7 +226,14 @@ class Logger {
 
     if (messageOrError instanceof Error) {
       message = messageOrError.message;
-      stack = messageOrError.stack;
+      // Expected, client-facing errors - an OperationOutcome/Issue carrying a 4xx
+      // statusCode (e.g. "code not found", "cache-id unknown") - are routine and
+      // don't warrant a stack trace in the log. Keep the stack for genuinely
+      // unexpected errors (5xx, or no statusCode at all), and for everything when
+      // debug logging is enabled.
+      const sc = messageOrError.statusCode;
+      const expected = typeof sc === 'number' && sc >= 400 && sc < 500;
+      stack = (expected && !this._shouldLog('debug')) ? undefined : messageOrError.stack;
     } else {
       message = String(messageOrError);
       stack = meta?.stack;

package/library/package-manager.js

@@ -823,7 +823,7 @@ class PackageContentLoader {
 
         try {
             const content = await fs.readFile(filePath, 'utf8');
-            return JSON.parse(content);
+            return normalizeVersionedCanonicals(JSON.parse(content));
         } catch (error) {
             throw new Error(`Failed to load file ${entry.filename}: ${error.message}`);
         }
@@ -923,4 +923,42 @@ class PackageContentLoader {
 }
 
 
-module.exports = { PackageManager, PackageContentLoader };
+/**
+ * Some R4-era core package resources bake a version into the canonical url itself:
+ * hl7.fhir.r4.core#4.0.1 publishes the multi-version v2 tables (0006, 0360, 0391)
+ * as e.g. url "http://terminology.hl7.org/CodeSystem/v2-0360|2.7" with version "0360"
+ * (the table number!). The base packages can never be republished, so normalize at
+ * load time: split the pipe into url + version, on the CodeSystems themselves and on
+ * ValueSet compose include/exclude systems that reference them. Without this,
+ * provider.system() never matches the system in a coding, so validation fails -
+ * silently, in the CodeSystem $validate-code case.
+ */
+function normalizeVersionedCanonicals(resource) {
+    if (!resource || typeof resource !== 'object') {
+        return resource;
+    }
+    if (resource.resourceType === 'CodeSystem' || resource.resourceType === 'ValueSet') {
+        if (typeof resource.url === 'string' && resource.url.includes('|')) {
+            const cut = resource.url.indexOf('|');
+            // the url-embedded version wins over the version element (which is "0360" etc)
+            resource.version = resource.url.substring(cut + 1);
+            resource.url = resource.url.substring(0, cut);
+        }
+        if (resource.resourceType === 'ValueSet' && resource.compose) {
+            for (const list of [resource.compose.include, resource.compose.exclude]) {
+                for (const inc of list || []) {
+                    if (typeof inc.system === 'string' && inc.system.includes('|')) {
+                        const cut = inc.system.indexOf('|');
+                        if (!inc.version) {
+                            inc.version = inc.system.substring(cut + 1);
+                        }
+                        inc.system = inc.system.substring(0, cut);
+                    }
+                }
+            }
+        }
+    }
+    return resource;
+}
+
+module.exports = { PackageManager, PackageContentLoader, normalizeVersionedCanonicals };

package/npmprojector/watcher.js

@@ -313,7 +313,7 @@ class PackageWatcher {
    */
   stop() {
     if (this.watcher) {
-      this.watcher.close();
+      this.watcher.close().catch((err) => this.log.error('Error closing watcher: ' + err.message));
       this.watcher = null;
     }
     if (this.debounceTimer) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhirsmith",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "txVersion": "1.9.1",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",
@@ -109,7 +109,8 @@
     "fast-xml-parser": "^5.3.4",
     "inquirer": {
       "lodash": "4.18.1"
-    }
+    },
+    "brace-expansion": "^5.0.8"
   },
   "bin": {
     "tx-import": "./tx/importers/tx-import.js",

package/packages/packages.js

@@ -605,10 +605,6 @@ class PackagesModule {
       this.crawler = new PackageCrawler(this.config, this.db, this.stats);
     }
 
-    // The feed uses the versioned package.tgz url as the (permalink) GUID, so reusing
-    // the link as the GUID keeps a later crawl from inserting a duplicate.
-    const guid = link;
-
     const buffer = await this.crawler.fetchUrl(link);
     const npm = await this.crawler.extractNpmPackage(buffer, link);
 
@@ -618,22 +614,37 @@ class PackagesModule {
     }
 
     const idver = npm.id + '#' + npm.version;
-    const replaced = await this.deleteVersionsByGuid(guid);
+
+    // Delete whatever is stored for this package version, matching on the id#version
+    // actually found in the fetched tarball. This used to match on GUID = link, but the
+    // stored GUID is whatever the feed said at crawl time (http vs https, or another
+    // permalink form), so an exact string match could silently delete nothing and leave
+    // the stale copy in place alongside the newly stored one.
+    const old = await this.deleteVersionsByIdVersion(npm.id, npm.version);
+
+    // Keep the old row's GUID when there was one - it is the feed's permalink, and
+    // reusing it stops the next crawl from re-inserting the package as a duplicate.
+    // When we never had the package, the link is the best available GUID (the feeds
+    // use the versioned package.tgz url as the permalink GUID anyway).
+    const guid = old.guids[0] || link;
 
     const itemLog = { status: '??' };
     await this.crawler.store(link, link, guid, new Date(), buffer, idver, itemLog);
 
-    pckLog.info('Force-updated ' + idver + ' from ' + link + ' (replaced ' + replaced + ' existing row(s))');
-    return { status: 'updated', id: npm.id, version: npm.version, replaced };
+    pckLog.info('Force-updated ' + idver + ' from ' + link + ' (replaced ' + old.count + ' existing row(s), guid ' + guid + ')');
+    return { status: 'updated', id: npm.id, version: npm.version, replaced: old.count };
   }
 
-  // Delete a stored package version and all of its child rows, by GUID.
-  deleteVersionsByGuid(guid) {
+  // Delete a stored package version and all of its child rows, by package id and
+  // version. Resolves to { count, guids }: how many PackageVersions rows went, and
+  // the distinct GUIDs they were stored under (so a caller can reuse the permalink).
+  deleteVersionsByIdVersion(id, version) {
     return new Promise((resolve, reject) => {
-      this.db.all('SELECT PackageVersionKey FROM PackageVersions WHERE GUID = ?', [guid], (err, rows) => {
+      this.db.all('SELECT PackageVersionKey, GUID FROM PackageVersions WHERE Id = ? AND Version = ?', [id, version], (err, rows) => {
         if (err) return reject(err);
         const keys = (rows || []).map(r => r.PackageVersionKey);
-        if (keys.length === 0) return resolve(0);
+        const guids = [...new Set((rows || []).map(r => r.GUID))];
+        if (keys.length === 0) return resolve({ count: 0, guids: [] });
         const ph = keys.map(() => '?').join(',');
         const stmts = [
           'DELETE FROM PackageFHIRVersions WHERE PackageVersionKey IN (' + ph + ')',
@@ -642,7 +653,7 @@ class PackagesModule {
           'DELETE FROM PackageVersions WHERE PackageVersionKey IN (' + ph + ')'
         ];
         const runNext = (i) => {
-          if (i >= stmts.length) return resolve(keys.length);
+          if (i >= stmts.length) return resolve({ count: keys.length, guids });
           this.db.run(stmts[i], keys, (e) => e ? reject(e) : runNext(i + 1));
         };
         runNext(0);
@@ -1289,8 +1300,10 @@ class PackagesModule {
     //
     //   POST /update-package   { "links": ["http://hl7.org/fhir/uv/ips/2.0.1/package.tgz", ...] }
     //
-    // The link is the versioned package.tgz url, which is exactly the GUID the feed uses,
-    // so the replacement keeps the same GUID and a later crawl won't create a duplicate.
+    // The link is the versioned package.tgz url. The stored copy to replace is found by
+    // the id#version inside the fetched tarball (not by matching the link against the
+    // stored GUID, which can differ in scheme or form from what the feed published), and
+    // the replacement keeps the old row's GUID so a later crawl won't create a duplicate.
     // If config.updateToken is set, the request must carry it in the x-update-token header.
     this.router.post('/update-package', async (req, res) => {
       const start = Date.now();
@@ -1712,7 +1725,7 @@ class PackagesModule {
       // Update download counts after successful response
       // Do this asynchronously to not delay the response
       setImmediate(() => {
-        this.incrementDownloadCounts(packageData.PackageVersionKey, id);
+        void this.incrementDownloadCounts(packageData.PackageVersionKey, id); // fire-and-forget; errors handled internally
       });
 
     } catch (error) {

package/publisher/publisher.js

@@ -2665,14 +2665,14 @@ class PublisherModule {
     return colors[status] || 'secondary';
   }
 
-  async logUserAction(userId, action, targetId, ipAddress) {
-    return new Promise((resolve) => {
-      this.db.run(
-          'INSERT INTO user_actions (user_id, action, target_id, ip_address) VALUES (?, ?, ?, ?)',
-          [userId, action, targetId, ipAddress],
-          () => resolve() // Don't fail if logging fails
-      );
-    });
+  // Fire-and-forget audit logging: callers don't await this, and it must never fail a
+  // request, so it returns void and swallows any DB error in the callback.
+  logUserAction(userId, action, targetId, ipAddress) {
+    this.db.run(
+        'INSERT INTO user_actions (user_id, action, target_id, ip_address) VALUES (?, ?, ?, ?)',
+        [userId, action, targetId, ipAddress],
+        () => {} // don't fail (or block) the request if audit logging fails
+    );
   }
 
   getStatus() {

package/registry/api.js

@@ -10,18 +10,20 @@ class RegistryAPI {
 
   /**
    * Build rows for code system queries
-   * Matches the Pascal buildRowsCS functionality
+   * Build the discovery rows for a code system query
    */
   buildRowsForCodeSystem(params = {}) {
     const {
       registryCode = '',
       serverCode = '',
       version = '',
-      codeSystem = ''
+      codeSystem = '',
+      language = ''
     } = params;
 
     const rows = [];
     const data = this.crawler.getData();
+    const requestLangs = ServerRegistryUtilities.parseAcceptLanguage(language);
 
     data.registries.forEach(registry => {
       if (registryCode && registry.code !== registryCode) return;
@@ -29,13 +31,15 @@ class RegistryAPI {
       registry.servers.forEach(server => {
         if (serverCode && server.code !== serverCode) return;
 
-        // Check if server is authoritative for this code system
-        const isAuth = codeSystem ? ServerRegistryUtilities.hasMatchingCodeSystem(
-          codeSystem,
-          server.authCSList,
-          true, // support wildcards,
-            false // allow version matching
-        ) : false;
+        // Excluded content is hidden from the ecosystem entirely for this server
+        if (codeSystem && server.isExcludedTarget(codeSystem)) return;
+
+        // Check if server is authoritative for this code system, taking language
+        // specific claims into account (maskBase matches hasMatchingCodeSystem semantics)
+        const authMatch = codeSystem
+          ? server.matchAuthCS(codeSystem, requestLangs, true)
+          : { isAuth: false, scoped: false };
+        const isAuth = authMatch.isAuth;
 
         server.versions.forEach(versionInfo => {
           if (version && !ServerRegistryUtilities.versionMatches(version, versionInfo.version)) {
@@ -64,6 +68,9 @@ class RegistryAPI {
               versionInfo,
               isAuth
             );
+            if (authMatch.scoped) {
+              row.languages = [authMatch.tag];
+            }
             rows.push(row);
           }
         });
@@ -75,7 +82,7 @@ class RegistryAPI {
 
   /**
    * Build rows for value set queries
-   * Matches the Pascal buildRowsVS functionality
+   * Build the discovery rows for a value set query
    */
   buildRowsForValueSet(params = {}) {
     const {
@@ -94,7 +101,11 @@ class RegistryAPI {
       registry.servers.forEach(server => {
         if (serverCode && server.code !== serverCode) return;
 
+        // Excluded content is hidden from the ecosystem entirely for this server
+        if (valueSet && server.isExcludedTarget(valueSet)) return;
+
         // Check if server is authoritative for this value set
+        // (value set claims have no language dimension at this time)
         const isAuth = valueSet ? ServerRegistryUtilities.hasMatchingValueSet(
           valueSet,
           server.authVSList,
@@ -129,7 +140,7 @@ class RegistryAPI {
             );
 
             // Include if authoritative OR has the value set
-            // This matches the Pascal logic: if auth or hasMatchingValueSet
+            // if the server is authoritative, all its versions are included
             if (isAuth || hasValueSet) {
               includeRow = true;
             }
@@ -339,13 +350,13 @@ class RegistryAPI {
   /**
    * Find best server for a given code system/value set
    */
-  findBestServer(type, url, version) {
+  findBestServer(type, url, version, language = '') {
     let rows;
 
     if (type === 'codesystem') {
-      rows = this.buildRowsForCodeSystem({ codeSystem: url, version });
+      rows = this.buildRowsForCodeSystem({ codeSystem: url, version, language });
     } else if (type === 'valueset') {
-      rows = this.buildRowsForValueSet({ valueSet: url, version });
+      rows = this.buildRowsForValueSet({ valueSet: url, version, language });
     } else {
       throw new Error(`Unknown type: ${type}`);
     }
@@ -378,9 +389,9 @@ class RegistryAPI {
 
   /**
    * NEW FUNCTION: Resolve the best server for a code system
-   * Based on Pascal resolveCS function
+   * Implements the ecosystem Resolution API for code systems
    */
-  resolveCodeSystem(fhirVersion, codeSystem, authoritativeOnly, usage = '') {
+  resolveCodeSystem(fhirVersion, codeSystem, authoritativeOnly, usage = '', language = '') {
     if (!fhirVersion) {
       throw new Error('A FHIR version is required');
     }
@@ -388,6 +399,7 @@ class RegistryAPI {
       throw new Error('A code system URL is required');
     }
     const normalizedVersion = this._normalizeFhirVersion(fhirVersion);
+    const requestLangs = ServerRegistryUtilities.parseAcceptLanguage(language);
 
     const result = {
       formatVersion: '1',
@@ -397,18 +409,26 @@ class RegistryAPI {
     };
 
     const matchedServers = [];
+    const authMatches = []; // {entry, score} - sorted by language match before returning
     const data = this.crawler.getData();
 
     data.registries.forEach(registry => {
       registry.servers.forEach(server => {
         let added = false;
 
+        // Excluded content is hidden from the ecosystem entirely for this server -
+        // not authoritative, not a candidate
+        if (server.isExcludedTarget(codeSystem)) return;
+
         // Check if server supports the requested usage tag
         if (server.usageList.length === 0 ||
           (usage && server.usageList.includes(usage))) {
 
-          // Check if server is authoritative for this code system
-          const isAuth = server.isAuthCS(codeSystem);
+          // Check if server is authoritative for this code system, taking language
+          // specific claims into account (a language specific claim is invisible to
+          // requests without a matching language)
+          const authMatch = server.matchAuthCS(codeSystem, requestLangs);
+          const isAuth = authMatch.isAuth;
 
           server.versions.forEach(version => {
             if (ServerRegistryUtilities.versionMatches(normalizedVersion, version.version)) {
@@ -425,9 +445,19 @@ class RegistryAPI {
 
               if (hasMatchingCS) {
                 if (isAuth) {
-                  result.authoritative.push(this.createServerEntry(server, version));
+                  authMatches.push({
+                    entry: this.createServerEntry(server, version, null, authMatch),
+                    score: authMatch.score
+                  });
                 } else if (!authoritativeOnly) {
-                  result.candidates.push(this.createServerEntry(server, version, content.content));
+                  const candidate = this.createServerEntry(server, version, content.content);
+                  if (requestLangs) {
+                    // the ecosystem has no knowledge of a candidate's language abilities -
+                    // mark it so clients can apply their wildcard strictness policy
+                    // (see 'Language Specific Claims' in the tx ecosystem IG)
+                    candidate['language-support'] = 'unknown';
+                  }
+                  result.candidates.push(candidate);
                 }
                 added = true;
               }
@@ -442,20 +472,27 @@ class RegistryAPI {
     });
 
     // NEW: Fallback - if no matches found, check for authoritative pattern matches
-    if (result.authoritative.length === 0 && result.candidates.length === 0) {
+    if (authMatches.length === 0 && result.candidates.length === 0) {
       data.registries.forEach(registry => {
         registry.servers.forEach(server => {
+          // Excluded content stays hidden in the fallback path too
+          if (server.isExcludedTarget(codeSystem)) return;
+
           // Check if server supports the requested usage tag
           if (server.usageList.length === 0 ||
             (usage && server.usageList.includes(usage))) {
 
             // Check if server is authoritative for this code system
-            const isAuth = server.isAuthCS(codeSystem);
+            // (taking language specific claims into account)
+            const authMatch = server.matchAuthCS(codeSystem, requestLangs);
 
-            if (isAuth) {
+            if (authMatch.isAuth) {
               server.versions.forEach(version => {
                 if (ServerRegistryUtilities.versionMatches(normalizedVersion, version.version)) {
-                  result.authoritative.push(this.createServerEntry(server, version));
+                  authMatches.push({
+                    entry: this.createServerEntry(server, version, null, authMatch),
+                    score: authMatch.score
+                  });
                   if (!matchedServers.includes(server.code)) {
                     matchedServers.push(server.code);
                   }
@@ -467,6 +504,12 @@ class RegistryAPI {
       });
     }
 
+    // Language specific matches rank before authoritative-list matches, most specific
+    // match first. Array.prototype.sort is stable, so entries with equal scores (e.g.
+    // all matched on the authoritative list) keep their existing (registration) order
+    authMatches.sort((a, b) => a.score - b.score);
+    result.authoritative = authMatches.map(m => m.entry);
+
     return {
       result: this._cleanEmptyArrays(result),
       matches: matchedServers.length > 0 ? matchedServers.join(',') : '--'
@@ -475,9 +518,13 @@ class RegistryAPI {
 
   /**
    * NEW FUNCTION: Resolve the best server for a value set
-   * Based on Pascal resolveVS function
+   * Implements the ecosystem Resolution API for value sets
    */
-  resolveValueSet(fhirVersion, valueSet, authoritativeOnly, usage = '') {
+  // eslint-disable-next-line no-unused-vars -- language is accepted for API symmetry (see note below)
+  resolveValueSet(fhirVersion, valueSet, authoritativeOnly, usage = '', language = '') {
+    // Note: the language parameter is accepted for API symmetry with resolveCodeSystem,
+    // but value set claims have no language dimension at this time (language specific
+    // claims - the languages property - apply to code systems only), so it has no effect
     if (!fhirVersion) {
       throw new Error('A FHIR version is required');
     }
@@ -508,6 +555,10 @@ class RegistryAPI {
       registry.servers.forEach(server => {
         let added = false;
 
+        // Excluded content is hidden from the ecosystem entirely for this server -
+        // not authoritative, not a candidate
+        if (server.isExcludedTarget(valueSet)) return;
+
         // Check if server supports the requested usage tag
         if (server.usageList.length === 0 ||
           (usage && server.usageList.includes(usage))) {
@@ -562,8 +613,11 @@ class RegistryAPI {
 
   /**
    * Helper function to create a server entry for resolve results
+   * @param {Object} authMatch - optional result of server.matchAuthCS(); when the entry
+   *   was matched on a language specific claim, the claim's language tag is reported so
+   *   the client can tell language routing applied (vs falling through to the default server)
    */
-  createServerEntry(server, version) {
+  createServerEntry(server, version, content = null, authMatch = null) {
     const entry = {
       'server-name': server.name,
       url: version.address
@@ -575,8 +629,15 @@ class RegistryAPI {
     if (server.accessInfo) {
       entry.access_info = server.accessInfo;
     }
-    if (version.content) {
-      entry.content = version.content;
+    // Report the content mode of the matched code system, if the server provided one
+    // (per the resolve API in the tx ecosystem IG, candidates report content when known).
+    // This was previously read from version.content, which doesn't exist - the value
+    // passed by resolveCodeSystem was silently dropped.
+    if (content) {
+      entry.content = content;
+    }
+    if (authMatch && authMatch.scoped && authMatch.isAuth) {
+      entry.languages = [authMatch.tag];
     }
 
     return entry;
@@ -584,7 +645,7 @@ class RegistryAPI {
 
   /**
    * NEW FUNCTION: Render a JSON result as an HTML table
-   * Based on Pascal renderJson function
+   * Renders a discovery result as an HTML table
    */
   renderJsonToHtml(json, path, regCode = '', serverCode = '', versionCode = '') {
     let html = '<table class="grid">\n';
@@ -648,7 +709,7 @@ class RegistryAPI {
 
   /**
    * NEW FUNCTION: Render registry info as HTML
-   * Based on Pascal renderInfo function
+   * Renders the registry tree as HTML
    */
   renderInfoToHtml() {
     const data = this.crawler.getData();

package/registry/crawler.js

@@ -255,6 +255,20 @@ class RegistryCrawler {
     server.authCSList = (serverConfig.authoritative || []).sort();
     server.authVSList = (serverConfig['authoritative-valuesets'] || []).sort();
     server.usageList = (serverConfig.usage || []).sort();
+    // Content hidden from the ecosystem entirely - also filtered out of the discovered
+    // content lists below, and checked during claim matching (see the tx ecosystem IG)
+    server.exclusions = (serverConfig.exclusions || []).sort();
+    // Language specific authoritative claims: BCP-47 tag -> list of CS masks.
+    // A backwards compatible addition to registry format 1 - see the tx ecosystem IG
+    server.languages = {};
+    if (serverConfig.languages && typeof serverConfig.languages === 'object' && !Array.isArray(serverConfig.languages)) {
+      for (const tag of Object.keys(serverConfig.languages)) {
+        const masks = serverConfig.languages[tag];
+        if (Array.isArray(masks)) {
+          server.languages[tag] = masks.filter(m => typeof m === 'string').sort();
+        }
+      }
+    }
     
     // Process each FHIR version
     const fhirVersions = serverConfig.fhirVersions || [];
@@ -427,7 +441,7 @@ class RegistryCrawler {
   async fetchValueSets(version, server, exclusions) {
     // Initial search URL
     let count = 0;
-    let searchUrl = `${version.address}/ValueSet?_elements=url,version`+(version.address.includes("fhir.org") ? "&_count=200" : "");
+    let searchUrl = `${version.address}/ValueSet?_elements=url,version&_count=1000`;
     try {
       // Set of URLs to avoid duplicates
       const valueSetUrls = new Set();