fhirsmith 0.14.1 → 0.15.0

package/tx/cm/cm-package.js

@@ -5,6 +5,7 @@ const { ConceptMapDatabase } = require('./cm-database');
 const { VersionUtilities } = require('../../library/version-utilities');
 const {validateParameter} = require("../../library/utilities");
 const {ConceptMap} = require("../library/conceptmap");
+const { applyIdPrefix, stripIdPrefix } = require('../library/resource-ids');
 
 /**
  * Package-based ConceptMap provider using shared database layer
@@ -34,6 +35,7 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     if (this.initialized) {
       return;
     }
+    await this.packageLoader.initialize();
 
     const dbExists = await this.database.exists();
 
@@ -43,6 +45,8 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     }
 
     this.conceptMapMap = await this.database.loadAllConceptMaps();
+    // nothing, unless the spaceId was assigned before the provider was initialized
+    this.#applyIdPrefix();
     this.initialized = true;
   }
 
@@ -63,7 +67,14 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     for (const entry of conceptMapEntries) {
       const conceptMap = await this.packageLoader.loadFile(entry);
       if (conceptMap.url) {
-        conceptMaps.push(new ConceptMap(conceptMap, this.packageLoader.fhirVersion())); // get in converted to R5 format
+        try {
+          conceptMaps.push(new ConceptMap(conceptMap, this.packageLoader.fhirVersion())); // get in converted to R5 format
+        } catch (e) {
+          // one unacceptable concept map (e.g. one with contained resources, which the
+          // server doesn't support) must not stop the rest of the package loading
+          require('../../library/logger').getInstance().child({ module: 'tx' })
+            .warn(`Package ${this.packageLoader.pid ? this.packageLoader.pid() : ''}: skipping ConceptMap ${conceptMap.url}: ${e.message}`);
+        }
       }
     }
 
@@ -121,7 +132,9 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     this._validateSearchParams(searchParams);
 
     if (this.USE_DATABASE_SEARCH) {
-      return await this.database.search(this.spaceId, searchParams, elements);
+      const results = await this.database.search(this.spaceId, searchParams, elements);
+      return this.#excludedIds.size === 0 ? results
+        : results.filter(r => !this.#excludedIds.has(stripIdPrefix(r.id, this.spaceId)));
     } else {
       const matches = [];
       const seen = new Set(); // Track by URL to avoid duplicates from versioned keys
@@ -187,9 +200,8 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
         if (isMatch) {
           seen.add(vsUrl);
-          // Return with prefixed id
-          const result = { ...json, id: `${this.spaceId}-${json.id}` };
-          matches.push(result);
+          // the id is already prefixed (see assignIds)
+          matches.push(json);
         }
       }
 
@@ -291,19 +303,53 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
   }
 
   async fetchConceptMapById(id) {
-    if (!this.spaceId) {
-      return this.conceptMapMap.get(id);
-    } else if (id.startsWith(this.spaceId+"-")) {
-      let key = id.substring(this.spaceId.length + 1);
-      return this.conceptMapMap.get(key);
-    } else {
-      return null;
+    // the map is keyed by the concept map's own id (and its url); the concept map itself
+    // carries the prefixed id, which is how a url key that happens to match is excluded
+    const cm = this.conceptMapMap.get(stripIdPrefix(id, this.spaceId));
+    return cm && cm.id === id ? cm : null;
+  }
+
+  sourcePackage() {
+    return this.packageLoader.id();
+  }
+
+  // the concept maps left out by excludeUrls, by their own (unprefixed) id
+  #excludedIds = new Set();
+
+  /**
+   * Leave out the concept maps with any of these urls: they can't be fetched, they aren't
+   * found by search, and they aren't used for translation. The FHIR core package's concept
+   * maps are left out where hl7.terminology provides the same url (see
+   * Provider.applyTHOPrecedence). Must be called once the provider is initialized - the
+   * database is shared, so it isn't changed.
+   *
+   * @param {Set<string>} urls
+   */
+  excludeUrls(urls) {
+    const excluded = new Set();
+    for (const cm of this.conceptMapMap.values()) {
+      if (cm && urls.has(cm.url)) {
+        excluded.add(cm);
+      }
+    }
+    for (const [key, cm] of [...this.conceptMapMap]) {
+      if (excluded.has(cm)) {
+        this.conceptMapMap.delete(key);
+      }
     }
+    for (const cm of excluded) {
+      this.#excludedIds.add(stripIdPrefix(cm.id, this.spaceId) ?? cm.id);
+    }
+  }
+
+  prefixIds() {
+    this.#applyIdPrefix();
   }
 
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    // nothing - we don't do any assigning.
+  #applyIdPrefix() {
+    for (const cm of new Set(this.conceptMapMap.values())) {
+      applyIdPrefix(cm, this.spaceId);
+    }
   }
 
   async findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceScope, targetScope, targetSystem) {

package/tx/cs/cs-provider-api.js

@@ -1,22 +1,37 @@
+const { assignIdSpace } = require('../library/resource-ids');
+
 /**
  * Abstract base class for value set providers
  * Defines the interface that all value set providers must implement
  */
 class AbstractCodeSystemProvider {
   /**
-   * {int} Unique number assigned to this provider
+   * {string} The prefix of this provider's id space (set by assignIds) - given for its source in the library
+   * YAML, or autonumbered. Every code system this provider provides has an id that starts
+   * with spaceId + '-' (see tx/library/resource-ids.js)
    */
   spaceId;
 
   /**
-   * ensure that the ids on the code systems are unique, if they are
-   * in the global namespace
+   * Put this provider in an id space: set spaceId, and prefix the ids of the code systems it
+   * provides with spaceId + '-'. A provider is put in one id space, once - asking for a
+   * different one later is an error (see assignIdSpace)
    *
-   * @param {Set<String>} ids
+   * @param {string} spaceId
    */
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    throw new Error('assignIds must be implemented by subclass');
+  assignIds(spaceId) {
+    if (assignIdSpace(this, spaceId)) {
+      this.prefixIds();
+    }
+  }
+
+  /**
+   * Prefix the ids of the code systems this provider provides with spaceId + '-', once spaceId
+   * is set (by assignIds). Code systems the provider provides later (see
+   * getCodeSystemChanges) must be given ids in the same space.
+   */
+  prefixIds() {
+    throw new Error('prefixIds must be implemented by subclass');
   }
 
   /**

package/tx/cs/cs-provider-list.js

@@ -1,4 +1,5 @@
 const { AbstractCodeSystemProvider } = require('./cs-provider-api');
+const { applyIdPrefix } = require('../library/resource-ids');
 
 /**
  * Package-based ValueSet provider using shared database layer
@@ -11,18 +12,18 @@ class ListCodeSystemProvider extends AbstractCodeSystemProvider {
   codeSystems = [];
 
   /**
-   * ensure that the ids on the code systems are unique, if they are
-   * in the global namespace
-   *
-   * @param {Set<String>} ids
+   * prefix the ids of the code systems with this provider's spaceId. A code system without
+   * an id gets its position in the list
    */
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
+  prefixIds() {
+    let i = 0;
     for (const cs of this.codeSystems) {
-      if (!cs.id || ids.has("CodeSystem/"+cs.id)) {
-        cs.id = ""+ids.size;
+      i++;
+      const json = cs.jsonObj || cs;
+      if (!json.id) {
+        json.id = String(i);
       }
-      ids.add("CodeSystem/"+cs.id);
+      applyIdPrefix(cs, this.spaceId);
     }
   }
 

package/tx/cs/cs-rxnorm.js

@@ -36,12 +36,27 @@ class RxNormPrep {
 
 // Iterator context
 class RxNormIteratorContext {
-  constructor(query, params = {}) {
+  /**
+   * @param {string|null} query - the SQL that produces the rows, or null for an iterator with no rows
+   * @param {object} params - the query parameters
+   * @param {number} [total] - the number of rows the query will return, if known. The expander
+   *   reads it to refuse an over-limit whole-code-system expansion before it is materialised
+   */
+  constructor(query, params = {}, total = undefined) {
     this.query = query;
     this.params = params;
     this.cursor = 0;
-    this.results = null;
-    this.executed = false;
+    if (query) {
+      this.results = null;
+      this.executed = false;
+      this.total = total;
+    } else {
+      // nothing to run: an empty statement isn't a no-op in node-sqlite3, it fails with
+      // "SQLITE_MISUSE: not an error"
+      this.results = [];
+      this.executed = true;
+      this.total = 0;
+    }
   }
 
   more() {
@@ -288,10 +303,12 @@ class RxNormServices extends CodeSystemProvider {
     if (!context) {
       // Iterate all codes
       const query = `SELECT ${this.getCodeField()}, STR FROM rxnconso WHERE SAB = ? AND TTY <> 'SY' ORDER BY ${this.getCodeField()}`;
-      return new RxNormIteratorContext(query, { sab: this.getSAB() });
+      return new RxNormIteratorContext(query, { sab: this.getSAB() }, this.totalCodeCount);
     } else {
-      // No hierarchical iteration for specific contexts in this implementation
-      return new RxNormIteratorContext('', {});
+      // No hierarchical iteration for specific contexts in this implementation. The expander
+      // asks every concept for its children (includeCodeAndDescendants), so this has to be an
+      // iterator with no rows - not one with an empty query, which sqlite rejects
+      return new RxNormIteratorContext(null, {});
     }
   }
 

package/tx/html/tx-template.html

@@ -10,6 +10,7 @@
   <meta charset="utf-8" http-equiv="X-UA-Compatible" content="IE=edge" />
 
   <link rel="stylesheet" href="/fhir.css"/>
+  [%api-head%]
 
     <!-- Bootstrap core CSS -->
   <link rel="stylesheet" href="/assets/css/bootstrap.css"/>
@@ -91,6 +92,7 @@
             <a href="[%endpoint-path%]/op.html" style="color: gold">Operations</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/ecl" style="color: gold">ECL</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/problems.html" style="color: gold">Problems</a>  &nbsp;|&nbsp;
+            [%api-link%]
             [%library-link%]
   &nbsp;
 		</div>

package/tx/library/canonical-resource.js

@@ -1,4 +1,45 @@
 const {VersionUtilities, VersionPrecision} = require("../../library/version-utilities");
+const {Issue} = require("./operation-outcome");
+
+/**
+ * Contained resources. The terminology server supports exactly one use of them: a ValueSet
+ * that contains ValueSets, which its compose refers to as #id. Any other contained resource
+ * - a contained CodeSystem or ConceptMap, anything contained in a CodeSystem or ConceptMap,
+ * or a contained ValueSet that itself contains something - is rejected, whatever path the
+ * resource arrives by (request, tx-resource, cache, package). Supporting them would mean
+ * resolving references to them everywhere, and the terminology ecosystem only requires
+ * servers to support contained value sets in value sets.
+ *
+ * @param {Object} jsonObj - the resource (R5 form)
+ * @throws {Issue} if the resource contains anything not supported
+ */
+function checkContained(jsonObj) {
+  const contained = jsonObj ? jsonObj.contained : undefined;
+  if (contained === undefined || contained === null) {
+    return;
+  }
+  const type = jsonObj.resourceType;
+  const which = `${type}${jsonObj.id ? '/' + jsonObj.id : ''}${jsonObj.url ? ' (' + jsonObj.url + ')' : ''}`;
+  if (!Array.isArray(contained)) {
+    throw new Issue('error', 'structure', `${type}.contained`, 'CONTAINED_RESOURCE_NOT_SUPPORTED',
+      `${which}: contained must be an array`, 'invalid-data', 400);
+  }
+  contained.forEach((c, i) => {
+    const ct = c && typeof c === 'object' ? c.resourceType : undefined;
+    let problem = null;
+    if (type !== 'ValueSet') {
+      problem = `${which} contains a ${ct || 'resource'}: this server only supports ValueSets contained in a ValueSet`;
+    } else if (ct !== 'ValueSet') {
+      problem = `${which} contains a ${ct || 'resource with no resourceType'}: this server only supports ValueSets contained in a ValueSet`;
+    } else if (Array.isArray(c.contained) && c.contained.length > 0) {
+      problem = `${which}: the contained ValueSet${c.id ? ' #' + c.id : ''} itself contains resources, which is not allowed`;
+    }
+    if (problem) {
+      throw new Issue('error', 'not-supported', `${type}.contained[${i}]`, 'CONTAINED_RESOURCE_NOT_SUPPORTED',
+        problem, 'not-supported', 400);
+    }
+  });
+}
 
 /**
  * Base class for metadata resources to provide common interface
@@ -31,6 +72,14 @@ class CanonicalResource {
     this.fhirVersion = fhirVersion;
   }
 
+  /**
+   * Rejects contained resources this server doesn't support - see checkContained.
+   * Subclasses call this once the resource is in R5 form.
+   */
+  checkContained() {
+    checkContained(this.jsonObj);
+  }
+
   get resourceType() {
     return this.jsonObj.resourceType;
   }
@@ -163,4 +212,4 @@ class CanonicalResource {
   }
 }
 
-module.exports = { CanonicalResource };
+module.exports = { CanonicalResource, checkContained };

package/tx/library/codesystem.js

@@ -55,6 +55,7 @@ class CodeSystem extends CanonicalResource {
       if (e.issueCode) { wrapped.issueCode = e.issueCode; }
       throw wrapped;
     }
+    this.checkContained();
     if (!noMaps) {
       this.buildMaps();
     }

package/tx/library/conceptmap.js

@@ -19,6 +19,7 @@ class ConceptMap extends CanonicalResource {
     // Convert to R5 format internally (modifies input for performance)
     this.jsonObj = conceptMapToR5(jsonObj, fhirVersion);
     this.validate();
+    this.checkContained();
     this.id = this.jsonObj.id;
     // Precalculated at construction so callers (e.g. the resource cache) have a
     // cheap O(1) sense of how large this resource is.

package/tx/library/resource-ids.js

@@ -0,0 +1,107 @@
+//
+// Resource ids in the server's id spaces
+//
+// Every CodeSystem, ValueSet and ConceptMap the server serves by id lives in the id space of
+// the provider that loaded it, and its id is the provider's prefix, a '-', then the id the
+// resource had in its source: "tho-v3-ActCode", "core-v3-MaritalStatus". The prefix is the
+// provider's spaceId: given in the library YAML (npm:hl7.terminology=tho), autonumbered by
+// the library when the YAML doesn't give one, and "core" for the FHIR core package each
+// endpoint loads for itself.
+//
+// No resource is served under its original id. Two sources can carry resources with the same
+// id (hl7.terminology and hl7.fhir.r4.core both have a CodeSystem v3-MaritalStatus), so an
+// unprefixed id can't say which one it means - and anything that looks a resource up by its
+// raw id must fail, rather than find whichever one happens to come first.
+//
+
+// resources whose id has been prefixed - so prefixing is idempotent, and a raw id that
+// happens to start with the prefix still gets one
+const prefixed = new WeakSet();
+
+/**
+ * Prefix a resource's id with spaceId. The resource is either a wrapper with a jsonObj
+ * (CodeSystem, ValueSet, ConceptMap) or a plain json object. Does nothing to a resource
+ * that has already been prefixed, or that has no id.
+ *
+ * @param {Object} resource
+ * @param {string} spaceId
+ */
+function applyIdPrefix(resource, spaceId) {
+  if (!resource || !spaceId || prefixed.has(resource)) {
+    return;
+  }
+  const json = resource.jsonObj || resource;
+  if (!json.id) {
+    return;
+  }
+  const id = `${spaceId}-${json.id}`;
+  json.id = id;
+  if (resource.jsonObj && Object.prototype.hasOwnProperty.call(resource, 'id')) {
+    resource.id = id;
+  }
+  prefixed.add(resource);
+}
+
+/**
+ * The id a resource had in its source, for an id served in spaceId - or null, if the id
+ * isn't in that space (including when it's a raw id, or there's no spaceId).
+ *
+ * @param {string} id
+ * @param {string} spaceId
+ * @returns {string|null}
+ */
+function stripIdPrefix(id, spaceId) {
+  if (!spaceId || typeof id !== 'string') {
+    return null;
+  }
+  const prefix = `${spaceId}-`;
+  return id.startsWith(prefix) && id.length > prefix.length ? id.substring(prefix.length) : null;
+}
+
+/**
+ * Whether a prefix given in the library YAML is acceptable. It's the start of an id, so it
+ * may only use id characters, and no '-', so that the prefix of any id is unambiguous.
+ * 'core' is the endpoints' own core package, and 'x' is the code system factories
+ * (CodeSystem/x-...), so neither is available.
+ *
+ * @param {string} prefix
+ * @returns {string|null} why the prefix isn't acceptable, or null if it is
+ */
+function checkIdPrefix(prefix) {
+  if (!/^[A-Za-z0-9.]{1,32}$/.test(prefix)) {
+    return `an id prefix may only contain letters, digits and '.' (up to 32 characters)`;
+  }
+  if (prefix === CORE_PREFIX || prefix === 'x') {
+    return `the id prefix '${prefix}' is reserved`;
+  }
+  return null;
+}
+
+/**
+ * Put a provider in an id space - the shared part of the providers' assignIds(spaceId).
+ * A provider is put in one id space, once: its resources are prefixed when it is, so
+ * moving it to another would leave them in the old one. Asking again for the same space
+ * does nothing.
+ *
+ * @param {Object} provider - a code system, value set or concept map provider
+ * @param {string} spaceId
+ * @returns {boolean} true if the provider has just been put in the space, and must now
+ *   prefix its resources' ids
+ */
+function assignIdSpace(provider, spaceId) {
+  if (!spaceId) {
+    throw new Error(`${provider.constructor.name}: no id space given`);
+  }
+  if (provider.spaceId) {
+    if (provider.spaceId === spaceId) {
+      return false;
+    }
+    throw new Error(`${provider.constructor.name} is already in the id space '${provider.spaceId}', so it can't be put in '${spaceId}'`);
+  }
+  provider.spaceId = spaceId;
+  return true;
+}
+
+const CORE_PREFIX = 'core';
+
+module.exports = { applyIdPrefix, stripIdPrefix, checkIdPrefix, assignIdSpace, CORE_PREFIX };

package/tx/library/valueset.js

@@ -25,12 +25,28 @@ class ValueSet extends CanonicalResource {
     // Convert to R5 format internally (modifies input for performance)
     this.jsonObj = valueSetToR5(jsonObj, fhirVersion);
     this.validate();
+    this.checkContained();
     this.buildMaps();
     // Precalculated at construction so callers (e.g. the resource cache) have a
     // cheap O(1) sense of how large this resource is.
     this._conceptCount = ValueSet._countConcepts(this.jsonObj, this._containsCount);
   }
 
+  /**
+   * What circular reference detection knows this value set by: its versioned url, or, for
+   * a contained value set (see TerminologyWorker.findValueSet), its container's key plus
+   * #id - a contained value set's own url, if it has one, says nothing about which
+   * container it came from. null for a value set with no url that isn't contained.
+   * @returns {string|null}
+   */
+  get contextKey() {
+    if (this.isContained && this.container) {
+      const base = this.container.contextKey || this.container.vurl || '(unidentified)';
+      return `${base}#${this.jsonObj.id || ''}`;
+    }
+    return this.vurl || null;
+  }
+
   /**
    * Number of concepts this ValueSet carries: the enumerated concepts in its
    * compose (include + exclude `concept` lists) plus any concepts in an inline