fhirsmith 0.3.0

package/tx/cs/cs-api.js

@@ -0,0 +1,789 @@
+/* eslint-disable no-unused-vars */
+
+const assert = require('assert');
+const {CodeSystem, CodeSystemContentMode} = require("../library/codesystem");
+const {Languages, Language, LanguageDefinitions} = require("../../library/languages");
+const { OperationContext } = require("../operation-context");
+const {Extensions} = require("../library/extensions");
+const {validateParameter, validateArrayParameter} = require("../../library/utilities");
+const {I18nSupport} = require("../../library/i18nsupport");
+const {VersionUtilities} = require("../../library/version-utilities");
+
+class FilterExecutionContext {
+  filters = [];
+}
+
+class CodeSystemProvider {
+
+  /**
+   * {OperationContext} The context in which this is executing
+   */
+  opContext;
+
+  /**
+   * @type {CodeSystem[]}
+   */
+  supplements;
+
+  constructor(opContext, supplements) {
+    this.opContext = opContext;
+    this.supplements = supplements;
+    this._ensureOpContext(opContext);
+    this._validateSupplements();
+  }
+
+  _ensureOpContext(opContext) {
+    assert(opContext && opContext instanceof OperationContext, "opContext is not an instance of OperationContext");
+  }
+
+  /**
+   * Validates that supplements are CodeSystem instances
+   * @private
+   */
+  _validateSupplements() {
+    if (!this.supplements) return;
+
+    if (!Array.isArray(this.supplements)) {
+      throw new Error('Supplements must be an array');
+    }
+
+    this.supplements.forEach((supplement, index) => {
+      if (!(supplement instanceof CodeSystem)) {
+        throw new Error(`Supplement ${index} must be a CodeSystem instance, got ${typeof supplement}`);
+      }
+    });
+  }
+
+  /**
+   * @section Metadata for the code system
+   */
+
+  /**
+   * @returns {string} uri for the code system
+   */
+  name() { return this.system() + (this.version() ? "|"+this.version() : "") }
+
+  /**
+   * @returns {string} uri for the code system
+   */
+  system() { throw new Error("Must override"); }
+
+  /**
+   * @returns {string} version for the code system
+   */
+  version() { throw new Error("Must override"); }
+
+  vurl() {
+    if (this.version()) {
+      return this.system()+ "|"+ this.version();
+    } else {
+      return this.system();
+    }
+  }
+  /**
+   * @returns {string} default language for the code system
+   */
+  defLang() { return 'en' }
+
+  /**
+   * @returns {CodeSystemContentMode} content mode for the CodeSystem
+   */
+  contentMode() { return CodeSystemContentMode.Complete; }
+
+  /**
+   * @returns {integer} agreed limitation of expansions (see CPT). 0 means no limitation
+   */
+  expandLimitation() { return 0; }
+
+  /**
+   * @returns {string} description for the code system
+   */
+  description() { throw new Error("Must override"); }
+
+  /**
+   * @returns {string} source package for the code system, if known
+   */
+  sourcePackage() { return null; }
+
+  /**
+   * @returns {integer} total number of concepts in the code system
+   */
+  totalCount() { throw new Error("Must override"); }
+
+  /**
+   * @returns {CodeSystem.property[]} defined properties for the code system
+   */
+  propertyDefinitions() { return null; }
+
+  /**
+   * returns true if the code system cannot be completely enumerated - e.g. it has a grammar
+   * @returns {boolean}
+   */
+  isNotClosed() {
+    return false;
+  }
+  /**
+   * @param {Languages} languages language specification
+   * @returns {boolean} defined properties for the code system
+   */
+  hasAnyDisplays(languages) {
+    const langs = this._ensureLanguages(languages);
+    return langs.isEnglishOrNothing();
+  }
+
+  resourceLanguageMatches(resource, languages, ifNoLang = false) {
+    if (resource.language) {
+      const resourceLang = new Language(resource.language);
+      for (const requestedLang of languages) {
+        if (resourceLang.matchesForDisplay(requestedLang)) {
+          return true;
+        }
+      }
+    } else {
+      return ifNoLang;
+    }
+  }
+
+  _hasAnySupplementDisplays(languages) {
+    // Check if any supplements have displays in the requested languages
+    if (this.supplements) {
+      // displays have preference
+      for (const supplement of this.supplements) {
+        // Check if supplement language matches and has displays
+        if (this.resourceLanguageMatches(supplement.jsonObj, languages, false)) {
+          // Check if any concept has a display
+          const allConcepts = supplement.getAllConcepts();
+          if (allConcepts.some(c => c.display)) {
+            return true;
+          }
+        }
+      }
+      // Check concept designations for display uses
+      for (const supplement of this.supplements) {
+        const allConcepts = supplement.getAllConcepts();
+        for (const concept of allConcepts) {
+          if (concept.designation) {
+            for (const designation of concept.designation) {
+              if (CodeSystem.isUseADisplay(designation.use)) {
+                if (designation.language) {
+                  const designationLang = new Language(designation.language);
+                  for (const requestedLang of languages) {
+                    if (designationLang.matchesForDisplay(requestedLang)) {
+                      return true;
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    return false; // nothing in the supplements
+  }
+
+  /**
+   * @returns {boolean} true if there's a heirarchy
+   */
+  hasParents() { return false; }
+
+  /**
+   * @returns {string} true if the code system nominates an enumeration to use in place of iterating (UCUM)
+   */
+  specialEnumeration() { return null; }
+
+  /**
+   * @param {string} url the supplement of interest
+   * @returns {boolean} true if the nominated supplement is in scope
+   */
+  hasSupplement(url) {
+    if (!this.supplements) return false;
+    return this.supplements.some(supp => supp.url === url || supp.vurl === url);
+  }
+
+  /**
+   * @returns {string[]} all supplements in scope
+   */
+  listSupplements() {
+    return this.supplements ? this.supplements.map(s => s.vurl) : [];
+  }
+
+  /**
+   * @returns {Feature[]} applicable Features
+   */
+  listFeatures() { return null; }
+
+  /**
+   * @param {string} checkVersion - first version
+   * @param {string} actualVersion - second version
+   * @returns {boolean} True if actualVersion is more detailed than checkVersion (for SCT)
+   */
+  versionIsMoreDetailed(checkVersion, actualVersion) {
+     return false;
+  }
+
+  /**
+   * @returns { {status, standardsStatus : String, experimental : boolean} } applicable Features
+   */
+  status() { return {}; }
+
+  /**
+   * @section Getting Information about the concepts in the CodeSystem
+   */
+
+  /**
+   * @param {String | CodeSystemProviderContext} code
+   * @returns {string} the correct code for the concept specified
+   */
+  async code(code) {throw new Error("Must override"); }
+
+  /**
+   * @param {String | CodeSystemProviderContext} code
+   * @returns {string} the best display given the languages in the operation context
+   */
+  async display(code) {
+    throw new Error("Must override");
+  }
+
+  /**
+   * Protected!
+   *
+   
+   * @param {String} code
+   * @returns {string} the best display given the languages in the operation context
+   */
+  _displayFromSupplements(code) {
+    assert(typeof code === 'string', 'code must be string');
+    if (this.supplements) {
+      const concepts = [];
+      // displays have preference
+      for (const supplement of this.supplements) {
+        // Check if supplement language matches and has displays
+        if (this.resourceLanguageMatches(supplement.jsonObj, this.opContext.langs, false)) {
+          // Check if any concept has a display
+          const concept= supplement.getConceptByCode(code);
+          if (concept) {
+            if (concept.display) {
+              return concept.display;
+            }
+            concepts.push(concept);
+          }
+        }
+      }
+      // Check concept designations for display uses
+      for (const concept in concepts) {
+        if (concept.designation) {
+          for (const designation of concept.designation) {
+            if (CodeSystem.isUseADisplay(designation.use) && this.opContext.langs.hasMatch(designation.language)) {
+              return designation.value;
+            }
+          }
+        }
+      }
+      // still here? try again, for any non-language display
+      for (const supplement of this.supplements) {
+        if (!supplement.jsonObj.language) {
+          const concept= supplement.getConceptByCode(code);
+          if (concept && concept.display) {
+            return concept.display;
+          }
+        }
+      }
+    }
+    return null; // nothing in the supplements
+  }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {string} the definition for the concept (if available)
+   */
+  async definition(code) {throw new Error("Must override"); }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {boolean} if the concept is abstract
+   */
+  async isAbstract(code) { return false; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {boolean} if the concept is inactive
+   */
+  async isInactive(code) { return false; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {boolean} if the concept is inactive
+   */
+  async isDeprecated(code) { return false; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {string} status
+   */
+  async getStatus(code) { return null; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {string} assigned itemWeight - if there is one
+   */
+  async itemWeight(code) { return null; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {string} parent, if there is one
+   */
+  async parent(code) { return null; }
+
+  /**
+   * This is calleed if the designation is not marked with a usual use code indicating that it is considered as a display
+   * @param designation
+   * @returns {boolean}
+   */
+  isDisplay(designation) {
+    return false;
+  }
+
+  /**
+   * @param {string | CodeSystemProviderContext} code
+   * @param {ConceptDesignations} designation list
+   * @returns {Designation[]} whatever designations exist (in all languages)
+   */
+  async designations(code, displays) { return null; }
+
+  _listSupplementDesignations(code, displays) {
+    assert(typeof code === 'string', 'code must be string');
+
+    if (this.supplements) {
+      for (const supplement of this.supplements) {
+        const concept= supplement.getConceptByCode(code);
+        if (concept) {
+          if (concept.display) {
+            displays.addDesignation(true, 'active', supplement.jsonObj.language, CodeSystem.makeUseForDisplay(), concept.display);
+          }
+          if (concept.designation) {
+            for (const d of concept.designation) {
+              let status = Extensions.readString(d, "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status");
+              displays.addDesignation(false, status || 'active', d.language, d.use, d.value, d.extension?.length > 0 ? d.extension : []);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {Extension[]} extensions, if any
+   */
+  async extensions(code) { return null; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {CodeSystem.concept.property[]} list of properties (may be empty)
+   */
+  async properties(code) { return []; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {string} information about incomplete validation on the concept, if there is any information (SCT)
+   */
+  async incompleteValidationMessage(code) { return null; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} a
+   * @param {string | CodeSystemProviderContext} b
+   * @returns {boolean} true if they're the same
+   */
+  async sameConcept(a, b) { return false; }
+
+  /**
+   * @section Finding concepts in the CodeSystem
+   */
+
+  /**
+   
+   * @param {string } code
+   * @returns {{context : CodeSystemProviderContext, message : String} the result of looking for the code
+   */
+  async locate(code) { throw new Error("Must override"); }
+
+  /**
+   
+   * @param {string} code
+   * @param {string} parent
+   * @param {boolean} disallowParent
+   * @returns {{context : CodeSystemProviderContext, message : String} the result of looking for the code in the context of the parent
+   */
+  async locateIsA(code) {
+    if (this.hasParents()) throw new Error("Must override"); else return { context : null, message: "The CodeSystem "+this.name()+" does not have parents"}
+  }
+
+  /**
+   iterate all the root concepts
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {CodeSystemIterator} a handle that can be passed to nextConcept (or null, if it can't be iterated)
+   */
+  async iterator(code) { return null }
+
+  /**
+   iterate all the concepts
+   * @param {string | CodeSystemProviderContext} code
+   * @returns {CodeSystemIterator} a handle that can be passed to nextConcept (or null, if it can't be iterated)
+   */
+  async iteratorAll() {
+    if (this.hasParents()) throw new Error("Must override"); else return await this.iterator(null);
+  }
+
+  /**
+   
+   * @param {CodeSystemIterator} context
+   * @returns {CodeSystemProviderContext} the next concept, or null
+   */
+  async nextContext(context) { return null; }
+
+  /**
+   
+   * @param {string | CodeSystemProviderContext} codeA
+   * @param {string | CodeSystemProviderContext} codeB
+   * @returns {string} one of: equivalent, subsumes, subsumed-by, and not-subsumed
+   */
+  async subsumesTest(codeA, codeB) { return 'not-subsumed'; }
+
+  /**
+   
+   * @param {CodeSystemProviderContext} ctxt the context to add properties for
+   * @param {string[]} props the properties requested
+   * @param {Parameters} params the parameters response to add to
+   */
+
+  async extendLookup(ctxt, props, params) { }
+
+  // procedure getCDSInfo(card : TCDSHookCard; langList : THTTPLanguageList; baseURL, code, display : String); virtual;
+
+  /**
+   * returns true if a filter is supported
+   *
+   * @param {String} prop
+   * @param {ValueSetFilterOperator} op
+   * @param {String} prop
+   * @returns {boolean} true if suppoted
+   * */
+  async doesFilter(prop, op, value) { return false; }
+
+  /**
+   * gets a single context in which filters will be evaluated. The application doesn't make use of this context;
+   * it's only use is to be passed back to the CodeSystem provider so it can make use of it - if it wants
+   *
+   * @param {boolean} iterate true if the conceptSets that result from this will be iterated, and false if they'll be used to locate a single code
+   * @returns {FilterExecutionContext} filter (or null, it no use for this)
+   * */
+  async getPrepContext(iterate) { return new FilterExecutionContext(); }
+
+  /**
+   * executes a text search filter (whatever that means) and returns a FilterConceptSet
+   *
+   * throws an exception if the search filter can't be handled
+   *
+   * @param {FilterExecutionContext} filterContext filtering context
+   * @param {String} filter user entered text search
+   * @param {boolean} sort ?
+   **/
+  async searchFilter(filterContext, filter, sort) { throw new Error("Must override"); } // ? must override?
+
+  /**
+   * Used for searching ucum (see specialEnumeration)
+   *
+   * throws an exception if the search filter can't be handled
+   * @param {FilterExecutionContext} filterContext filtering context
+   * @param {boolean} sort ?
+   **/
+  async specialFilter(filterContext, sort) {
+    if (this.specialEnumeration()) {
+      throw new Error("Must override");
+    }
+  } // ? must override?
+
+  /**
+   * Get a FilterConceptSet for a value set filter
+   *
+   * throws an exception if the search filter can't be handled
+   *
+   * @param {FilterExecutionContext} filterContext filtering context
+   * @param {String} prop
+   * @param {ValueSetFilterOperator} op
+   * @param {String} prop
+   **/
+  async filter(filterContext, prop, op, value) { 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.
+   * this function returns one more filters. If there were multiple filters, but only
+   * one FilterConceptSet, then the code system provider has done the join across the
+   * filters, otherwise the engine will do so as required
+   *
+   * @param {FilterExecutionContext} filterContext filtering context
+   * @returns {FilterConceptSet[]} filter sets
+   **/
+  async executeFilters(filterContext) { throw new Error("Must override"); } // well, only if any filters are actually supported
+
+  /**
+   * return how many concepts are in the filter set
+   @param {FilterExecutionContext} filterContext filtering context
+   @param {FilterConceptSet} set of interest
+   @returns {int} number of concepts in the set
+   */
+  async filterSize(filterContext, set) {throw new Error("Must override"); }
+
+  /**
+   * return true if there's an infinite number of members (or at least, beyond knowing)
+   *
+   * This is true if the code system defines a grammar
+   *
+   @param {FilterExecutionContext} filterContext filtering context
+   @returns {boolean} true if not closed
+   */
+  async filtersNotClosed(filterContext) { return false; }
+
+  /**
+   * iterate the filter set. Iteration is forwards only, using the style
+   * while (filterMore()) { something(filterConcept()};
+   *
+   @param {FilterExecutionContext} filterContext filtering context
+   @param {FilterConceptSet} set of interest
+   @returns {boolean} if there is a concept
+   */
+  async filterMore(filterContext, set) {throw new Error("Must override"); }
+
+  /**
+   * get the current concept
+   *
+   @param {FilterExecutionContext} filterContext filtering context
+   @param {FilterConceptSet} set of interest
+   @returns {CodeSystemProviderContext} if there is a concept
+   */
+  async filterConcept(filterContext, set) {throw new Error("Must override"); }
+
+  /**
+   * filterLocate - instead of iterating, find a code in the FilterConceptSet
+   *
+   @param {FilterExecutionContext} filterContext filtering context
+   @param {FilterConceptSet} set of interest
+   @param {string} code the code to find
+   @returns {string | CodeSystemProviderContext} an error explaining why it isn't in the set, or a handle to the concept
+   */
+   async filterLocate(filterContext, set, code) {throw new Error("Must override"); }
+
+   /**
+   * filterLocate - instead of iterating, find a code in the FilterConceptSet
+   *
+   @param {FilterExecutionContext} filterContext filtering context
+   @param {FilterConceptSet} set of interest
+   @param {CodeSystemProviderContext} concept the code to find
+   @returns {string | boolean } an error explaining why it isn't in the set, or true if it is
+   */
+   async filterCheck(filterContext, set, concept) {throw new Error("Must override"); }
+
+  /**
+   * filterFinish - opportunity for the provider to close up and recover resources etc
+   *
+   @param {FilterExecutionContext} filterContext filtering context
+   */
+  async filterFinish(filterContext) {
+
+  }
+
+  /**
+   * register the concept maps that are implicitly defined as part of the code system
+   *
+   * @param {ConceptMap[]} conceptMaps
+   *
+   */
+  registerConceptMaps(list) {}
+
+
+  /**
+   * register the concept maps that are implicitly defined as part of the code system
+   *
+   * @param {Coding} coding the coding to translate
+   * @param {String} target
+   * @returns {CodeTranslation[]} the list of translations
+   */
+  async getTranslations(coding, target) { return null;}
+
+  // ==== Parameter checking methods =========
+  _ensureLanguages(param) {
+    assert(
+      typeof param === 'string' ||
+      param instanceof Languages ||
+      (Array.isArray(param) && param.every(item => typeof item === 'string')),
+      'Parameter must be string, Languages object, or array of strings'
+    );
+
+    if (typeof param === 'string') {
+      return Languages.fromAcceptLanguage(param, this.languageDefinitions, false);
+    } else if (Array.isArray(param)) {
+      const languages = new Languages();
+      for (const str of param) {
+        const lang = new Language(str);
+        languages.add(lang);
+      }
+      return languages;
+    } else {
+      return param; // Already a Languages object
+    }
+  }
+
+  /**
+   * @returns {String} the version algorithm for this version of the code system
+   */
+  versionAlgorithm() {
+    return null;
+  }
+
+  versionNeeded() {
+    return false;
+  }
+
+  /**
+   * @returns {string} valueset for the code system
+   */
+  valueSet() {
+    return null;
+  }
+}
+
+class CodeSystemFactoryProvider {
+  uses = 0;
+
+  /**
+   * {I18nSupport}
+   */
+  i18n;
+
+  constructor(i18n) {
+    validateParameter(i18n, "i18n", I18nSupport);
+
+    this.i18n = i18n;
+  }
+
+
+  /**
+   * @returns {String} the latest version, if known
+   */
+  defaultVersion() { throw new Error("Must override"); }
+
+  async load() {
+    // nothing here
+  }
+
+  /**
+   
+   * @param {CodeSystem[]} supplements any supplements that are in scope
+   * @returns {CodeSystemProvider} a built provider - or an exception
+   */
+  build(opContext, supplements) { throw new Error("Must override Factory"); }
+
+  /**
+   * @returns {string} uri for the code system
+   */
+  system() {
+    throw new Error("Must override");
+  }
+
+  /**
+   * @returns {string} uri for the code system
+   */
+  name() {
+    throw new Error("Must override");
+  }
+
+  /**
+   * @returns {string} version for the code system
+   */
+  version() { throw new Error("Must override"); }
+
+  getPartialVersion() {
+    let ver = this.version();
+    if (ver && VersionUtilities.isSemVer(ver)) {
+      return VersionUtilities.getMajMin(ver);
+    }
+    return ver;
+  }
+/**
+   * @returns {number} how many times the factory has been asked to construct a provider
+   */
+  useCount() {return this.uses}
+
+  recordUse() {
+    this.uses++;
+  }
+
+  /**
+   * build and return a known value set from the URL, if there is one.
+   *
+   * @param url
+   * @param version
+   * @returns {ValueSet}
+   */
+  async buildKnownValueSet(url, version) {
+    return null;
+  }
+
+  /**
+   * build and return a known concept map from the URL, if there is one.
+   *
+   * @param url
+   * @param version
+   * @returns {ConceptMap}
+   */
+  async findImplicitConceptMaps(conceptMaps, source, dest) {
+    return null;
+  }
+
+  /**
+   * build and return a known concept map from the URL, if there is one.
+   *
+   * @param url
+   * @param version
+   * @returns {ConceptMap}
+   */
+  async findImplicitConceptMap(url, version) {
+    return null;
+  }
+
+  id() {
+    throw new Error("Must override");
+  }
+
+  codeLink(code) {
+    return undefined;
+  }
+
+  iteratable() {
+    return false;
+  }
+
+  // nothing here - might be overriden
+  async close() {
+
+  }
+}
+
+module.exports = {
+  FilterExecutionContext,
+  CodeSystemProvider,
+  CodeSystemContentMode,
+  CodeSystemFactoryProvider
+};