Improve Support for ValueSet Versions

README.md

@@ -11,6 +11,24 @@ valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.
 // or valueset "Diabetes": '2.16.840.1.113883.3.464.1003.103.12.1001'
 ```
 
+As of 1.1.1, this library supports Value Set versions, so the following is also supported:
+
+```
+valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.103.12.1001' version '20190315'
+// or valueset "Diabetes": 'urn:oid:2.16.840.1.113883.3.464.1003.103.12.1001' version '20190315'
+// or valueset "Diabetes": '2.16.840.1.113883.3.464.1003.103.12.1001' version '20190315'
+```
+
+When using the canonical URL as a Value Set identifier, it is also possible to embed the version directly in the URL, using a vertical bar (`|`) to separate the identifier and version:
+
+```
+valueset "Diabetes": 'https://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.103.12.1001|20190315'
+```
+
+The embedded version, however, is only supported for the canonical URL form of value sets.  It is not supported for URN or OID identifiers.
+
+## Credentials Required
+
 This library requires that the credentials of a valid UMLS account be provided to it.  If you do not have an UMLS
 account, you can request one here: https://uts.nlm.nih.gov/license.html
 

lib/download-vsac.js

@@ -7,34 +7,31 @@ const extractOidAndVersion = require('./extractOidAndVersion');
 const debug = require('debug')('vsac'); // To turn on DEBUG: $ export DEBUG=vsac
 
 function downloadFromVSAC(username, password, input, output, vsDB={}, caching=true) {
-  var vsJSON = {};
-  if (typeof(input) === 'string') {
-    path.resolve(input);
-    vsJSON = require(input);
-  } else {
-    var keys = Object.keys(input);
-    keys.forEach(function(val) {
-      const [oid] = extractOidAndVersion(input[val].id);
-      if (!(oid in vsDB)) {
-        vsJSON[input[val].name] = oid;
-      }
-    });
-  }
-  if (Object.keys(vsJSON).length > 0) {
+  const oidsAndVersions = [];
+  Object.keys(input).forEach((key) => {
+    let [id, version] = [input[key].id, input[key].version];
+    const [oid, embeddedVersion] = extractOidAndVersion(id);
+    if (version == null && embeddedVersion != null) {
+      version = embeddedVersion;
+    }
+    if (vsDB[oid] == null || vsDB[oid][version] == null) {
+      oidsAndVersions.push({ oid, version });
+    }
+  });
+  if (oidsAndVersions.length) {
     output = path.resolve(output);
-    const oids = Object.keys(vsJSON).map(k => vsJSON[k]);
     if (caching && !fs.existsSync(output)){
       mkdirp.sync(output);
     }
     return getTicketGrantingTicket(username, password)
       .then((ticketGrantingTicket) => {
-        const promises = oids.map(oid => {
+        const promises = oidsAndVersions.map(({ oid, version }) => {
         // Catch errors and convert to resolutions returning an error.  This ensures Promise.all waits for all promises.
         // See: http://stackoverflow.com/questions/31424561/wait-until-all-es6-promises-complete-even-rejected-promises
-          return downloadValueSet(ticketGrantingTicket, oid, output, vsDB, caching)
+          return downloadValueSet(ticketGrantingTicket, oid, version, output, vsDB, caching)
             .catch((err) => {
-              debug(`Error downloading valueset ${oid}`, err);
-              return new Error(`Error downloading valueset: ${oid}`);
+              debug(`Error downloading valueset ${oid}${version || ''}`, err);
+              return new Error(`Error downloading valueset: ${oid}${version || ''}`);
             });
         });
         return Promise.all(promises);
@@ -68,10 +65,10 @@ function getTicketGrantingTicket(username, password) {
   return rpn(options);
 }
 
-function downloadValueSet(ticketGrantingTicket, oid, output, vsDB={}, caching=true) {
+function downloadValueSet(ticketGrantingTicket, oid, version, output, vsDB={}, caching=true) {
   return  getServiceTicket(ticketGrantingTicket)
     .then((serviceTicket) => {
-      return getValueSet(serviceTicket, oid);
+      return getValueSet(serviceTicket, oid, version);
     })
     .then((data) => {
       parseVSACXML(data, vsDB);
@@ -89,12 +86,15 @@ function getServiceTicket(ticketGrantingTicket) {
   return rpn(options);
 }
 
-function getValueSet(serviceTicket, oid) {
-  debug('Getting ValueSet:', oid);
+function getValueSet(serviceTicket, oid, version) {
+  debug(`Getting ValueSet: ${oid}${version || ''}`);
   const options = {
     url: 'https://vsac.nlm.nih.gov/vsac/svs/RetrieveValueSet',
     qs: { id: oid, ticket: serviceTicket }
   };
+  if (version != null) {
+    options.qs.version = version;
+  }
   return rpn(options);
 }
 

lib/extractOidAndVersion.js

@@ -1,8 +1,9 @@
 /**
- * Extracts just the oid from a urn, url, or oid. If it is not a valid urn or VSAC URL,
- * it is assumed to be an oid and returned as-is.
+ * Extracts the oid and version from a url, urn, or oid. Only url supports an embedded version
+ * (separately by |); urn and oid will never return a version. If the input value is not a valid
+ * urn or VSAC URL, it is assumed to be an oid and returned as-is.
  * @param {string} id - the urn, url, or oid
- * @returns {string} the oid
+ * @returns {[string,string]} the oid and optional version as a pair
  */
 function extractOidAndVersion(id) {
   if (id == null) return [];

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cql-exec-vsac",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",