fhirsmith 0.10.1 → 0.11.0

package/tsconfig.eslint.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "allowJs": true, "checkJs": false, "noEmit": true,
+    "moduleResolution": "node", "target": "es2022", "module": "commonjs",
+    "strict": false, "skipLibCheck": true
+  },
+  "include": ["**/*.js"],
+  "exclude": ["node_modules", "static", "**/*.test.js", "tests", "coverage"]
+}

package/tx/cs/cs-api.js

@@ -118,6 +118,19 @@ class CodeSystemProvider {
    */
   totalCount() { throw new Error("Must override"); }
 
+  /**
+   * The number of codes an "all codes" expansion of this code system would
+   * contain, computed WITHOUT materialising them - used by the count=0 (count
+   * only) expansion fast path. `excludeInactive` mirrors the expansion's
+   * active-only handling. Defaults to totalCount(); providers that distinguish
+   * active from inactive override this to honour excludeInactive.
+   * @param {boolean} excludeInactive
+   * @returns {integer}
+   */
+  async countAllCodes(excludeInactive) {  // eslint-disable-line no-unused-vars
+    return await this.totalCount();
+  }
+
   /**
    * @returns {CodeSystem.property[]} defined properties for the code system
    */
@@ -131,6 +144,18 @@ class CodeSystemProvider {
     return false;
   }
 
+  /**
+   * returns false if the code system cannot be iterated / enumerated in any
+   * meaningful sense - as distinct from isNotClosed(), which marks a code system
+   * that has a grammar whose base set may still be partially expanded. An
+   * expansion that would need to iterate a system for which this is false
+   * returns an OperationOutcome rather than attempting the iteration.
+   * @returns {boolean}
+   */
+  canBeExpanded() {
+    return true;
+  }
+
   /**
    * returns true if the code system is case sensitive when comparing codes.
    * this is true by default
@@ -372,11 +397,21 @@ class CodeSystemProvider {
   }
 
   /**
+   * List the designations for a concept, adding them to `displays`.
+   *
    * @param {string | CodeSystemProviderContext} code
-   * @param {ConceptDesignations} designation list
+   * @param {ConceptDesignations} displays - designation list to add to
+   * @param {boolean} [significantOnly=false] - when true, emit only the
+   *   designations that are significant for a value set expansion (the display,
+   *   and - for code systems that distinguish them - the fully specified name
+   *   and the preferred term), rather than every designation in every language.
+   *   The $expand worker passes true; $lookup uses the default (false) to return
+   *   the complete set. Providers that do not distinguish significant
+   *   designations may ignore this parameter and return all designations either
+   *   way.
    * @returns {Designation[]} whatever designations exist (in all languages)
    */
-  async designations(code, displays) { return null; }
+  async designations(code, displays, significantOnly = false) { return null; }
 
   _listSupplementDesignations(code, displays) {
     assert(typeof code === 'string', 'code must be string');
@@ -582,9 +617,27 @@ class CodeSystemProvider {
    * @param {boolean} forIteration - whether this filter is going to be iterated
    * @param {String} prop
    * @param {ValueSetFilterOperator} op
-   * @param {String} prop
+   * @param {String} value
+   * @param {Object} [fc] the ValueSet compose filter element
+   *   (ValueSet.compose.include.filter) this filter was derived from. It is a stable
+   *   sub-object of the (cached) ValueSet resource, so a provider MAY use it as a place
+   *   to memoise the resolved analysis of this filter (e.g. the enumerated concept set),
+   *   which is then reused on subsequent expand/validate calls for as long as the
+   *   ValueSet stays cached - trading memory for the cost of re-preparing the filter.
+   *
+   *   Two rules govern any such cache:
+   *   - It MUST be pinned to the resolved code system VERSION. The same ValueSet can be
+   *     resolved against different versions/editions, and a resolved filter (a set of
+   *     version-specific concept references) is only valid for the version it was
+   *     computed against.
+   *   - It must NOT be pinned to forIteration. The same ValueSet is used both ways
+   *     (iterated for $expand, non-iterated for validate), so if the iterated and
+   *     non-iterated resolved forms differ, store BOTH rather than assuming one.
+   *
+   *   Providers that gain nothing from this (the SQL-backed providers, and the trivial
+   *   in-memory enumerations) simply ignore fc.
    **/
-  async filter(filterContext, forIteration, prop, op, value) { throw new Error("Must override"); } // well, only if any filters are actually supported
+  async filter(filterContext, forIteration, prop, op, value, fc) { throw new Error("Must override"); } // well, only if any filters are actually supported
 
   /**
    * called once all the filters have been handled, and iteration is about to happen.

package/tx/cs/cs-cs.js

@@ -8,6 +8,17 @@ const {Extensions} = require("../library/extensions");
 const {BaseCSServices} = require("./cs-base");
 const regexUtilities = require("../../library/regex-utilities");
 
+// Symbol key under which resolved filter analysis is memoised directly on the
+// ValueSet compose.include.filter element (`fc`). Symbol-keyed and defined
+// non-enumerable, so it never serialises, clones (structuredClone), or spreads
+// into a response - it simply lives and dies with the filter element (and thus
+// the cached ValueSet). The value is Map(codeSystemVersionKey -> concepts[]):
+// the resolved concept list is only valid for the code system version it was
+// computed against. Only the expensive full-scan / subtree-walk filters are
+// cached (see _isCacheableFilter); cheap ones (=, in, child-of) are not. cs-cs
+// filter results do not depend on forIteration, so one form is stored per version.
+const FILTER_ANALYSIS = Symbol('filterAnalysis');
+
 /**
  * Context class for FHIR CodeSystem provider concepts
  */
@@ -1218,40 +1229,70 @@ class FhirCodeSystemProvider extends BaseCSServices {
    * @param {string} value - Filter value
    * @returns {Promise<FhirCodeSystemProviderFilterContext>} Filter results
    */
-  async filter(filterContext, forIteration, prop, op, value) {
-    
-
+  async filter(filterContext, forIteration, prop, op, value, fc) {
     let results = null;
 
-    // Handle concept/code hierarchy filters
-    if ((prop === 'concept' || prop === 'code')) {
-      results = await this._handleConceptFilter(filterContext, prop, op, value);
+    // Reuse previously resolved analysis when this same cached value set filter
+    // is resolved again against the same code system version (see filter()/fc).
+    // Only expensive filters are cached; the concept list is shared read-only,
+    // wrapped in a fresh context so iteration state (the cursor) is per-use.
+    // Caching needs a stable code system identity. When the code system has no
+    // url (odd corner cases) _filterCacheVersionKey returns null and caching is
+    // skipped entirely - there's no safe key to store or look up under.
+    const vkey = fc ? this._filterCacheVersionKey() : null;
+    const cacheable = vkey !== null && this._isCacheableFilter(prop, op);
+    if (cacheable) {
+      const byVersion = fc[FILTER_ANALYSIS];
+      const cachedConcepts = byVersion ? byVersion.get(vkey) : null;
+      if (cachedConcepts) {
+        results = new FhirCodeSystemProviderFilterContext();
+        results.concepts = cachedConcepts; // immutable: read-only from here
+      }
     }
 
-    // Handle child existence filter
-    if (prop === 'child' && op === 'exists') {
-      results = await this._handleChildExistsFilter(filterContext, value);
-    }
+    if (!results) {
+      // Handle concept/code hierarchy filters
+      if ((prop === 'concept' || prop === 'code')) {
+        results = await this._handleConceptFilter(filterContext, prop, op, value);
+      }
 
-    // Handle property-based filters
-    const propertyDefs = this.propertyDefinitions();
-    if (propertyDefs) {
-      const propertyDef = propertyDefs.find(p => p.code === prop);
-      if (propertyDef) {
-        results = await this._handlePropertyFilter(filterContext, propertyDef, op, value);
+      // Handle child existence filter
+      if (prop === 'child' && op === 'exists') {
+        results = await this._handleChildExistsFilter(filterContext, value);
       }
-    }
 
-    // Handle known special properties
-    const knownProperties = ['notSelectable', 'status', 'inactive', 'deprecated'];
-    if (knownProperties.includes(prop)) {
-      results = await this._handleKnownPropertyFilter(filterContext, prop, op, value);
-    }
+      // Handle property-based filters
+      const propertyDefs = this.propertyDefinitions();
+      if (propertyDefs) {
+        const propertyDef = propertyDefs.find(p => p.code === prop);
+        if (propertyDef) {
+          results = await this._handlePropertyFilter(filterContext, propertyDef, op, value);
+        }
+      }
 
-    if (!results) {
-      throw new Issue('error', 'exception', null, 'FILTER_NOT_UNDERSTOOD',
-            this.opContext.i18n.translate('FILTER_NOT_UNDERSTOOD', this.opContext.langs, [prop, op, value]), 'vs-invalid', 422);
+      // Handle known special properties
+      const knownProperties = ['notSelectable', 'status', 'inactive', 'deprecated'];
+      if (knownProperties.includes(prop)) {
+        results = await this._handleKnownPropertyFilter(filterContext, prop, op, value);
+      }
+
+      if (!results) {
+        throw new Issue('error', 'exception', null, 'FILTER_NOT_UNDERSTOOD',
+              this.opContext.i18n.translate('FILTER_NOT_UNDERSTOOD', this.opContext.langs, [prop, op, value]), 'vs-invalid', 422);
+      }
+
+      // Store a private copy of the resolved concept list for reuse. A slice
+      // isolates the cache from any later mutation of this request's context.
+      if (cacheable) {
+        let byVersion = fc[FILTER_ANALYSIS];
+        if (!byVersion) {
+          byVersion = new Map();
+          Object.defineProperty(fc, FILTER_ANALYSIS, { value: byVersion, enumerable: false, configurable: true, writable: true });
+        }
+        byVersion.set(vkey, results.concepts.slice());
+      }
     }
+
     // Add to filter context
     if (!filterContext.filters) {
       filterContext.filters = [];
@@ -1261,6 +1302,38 @@ class FhirCodeSystemProvider extends BaseCSServices {
     return results;
   }
 
+  /**
+   * Whether a filter is expensive enough to be worth memoising: the full-scan
+   * or subtree-walk families. Cheap lookups (=, in on a code list, child-of)
+   * are not cached. Mirrors the dispatch in filter().
+   * @private
+   */
+  _isCacheableFilter(prop, op) {
+    if (prop === 'concept' || prop === 'code') {
+      return op === 'is-a' || op === 'descendent-of' || op === 'is-not-a' || op === 'regex';
+    }
+    if (prop === 'child' && op === 'exists') {
+      return true;
+    }
+    const propertyDefs = this.propertyDefinitions();
+    if (propertyDefs && propertyDefs.find(p => p.code === prop)) {
+      return true;
+    }
+    return ['notSelectable', 'status', 'inactive', 'deprecated'].includes(prop);
+  }
+
+  /**
+   * Cache key pinning resolved analysis to the code system identity + version.
+   * @private
+   */
+  _filterCacheVersionKey() {
+    const url = this.codeSystem.jsonObj.url;
+    if (!url) {
+      return null;
+    }
+    return url + '|' + (this.codeSystem.jsonObj.version || '');
+  }
+
   /**
    * Handle concept/code filters (is-a, descendent-of, etc.)
    * @param {FilterExecutionContext} filterContext - Filter context

package/tx/cs/cs-hgvs.js

@@ -42,6 +42,10 @@ class HGVSServices extends CodeSystemProvider {
     return null;
   }
 
+  canBeExpanded() {
+    return false; // HGVS is a grammar validated externally; its codes cannot be iterated
+  }
+
   defaultToLatest() {
     return true;
   }

package/tx/cs/cs-lang.js

@@ -430,6 +430,14 @@ class IETFLanguageCodeProvider extends CodeSystemProvider {
     return null;
   }
 
+  specialEnumeration() {
+    // The BCP-47 language grammar is unbounded, but a useful base expansion is
+    // the common languages enumerated by the THO "Languages" value set. A whole-
+    // code-system expansion returns that value set marked as an incomplete
+    // (unclosed) expansion, mirroring how UCUM uses its common-units value set.
+    return 'http://terminology.hl7.org/ValueSet/Languages';
+  }
+
   isNotClosed() {
     return true;
   }

package/tx/cs/cs-mimetypes.js

@@ -188,6 +188,10 @@ class MimeTypeServices extends CodeSystemProvider {
     return true;
   }
 
+  canBeExpanded() {
+    return false; // MIME types cannot be iterated / enumerated
+  }
+
 }
 
 class MimeTypeServicesFactory extends CodeSystemFactoryProvider {