initial valueset class definition

Create internal vs class

Export correct types and delay expansion of vs

Author: lmd59

src/cql-code-service.ts

@@ -1,4 +1,4 @@
-import { Code, ValueSet } from './datatypes/datatypes';
+import { Code, ValueSetExpansion } from './datatypes/datatypes';
 import { TerminologyProvider, ValueSetDictionary, ValueSetObject } from './types';
 
 export class CodeService implements TerminologyProvider {
@@ -12,16 +12,16 @@ export class CodeService implements TerminologyProvider {
         const codes = valueSetsJson[oid][version].map(
           (code: any) => new Code(code.code, code.system, code.version)
         );
-        this.valueSets[oid][version] = new ValueSet(oid, version, codes);
+        this.valueSets[oid][version] = new ValueSetExpansion(oid, version, codes);
       }
     }
   }
 
-  findValueSetsByOid(oid: string): ValueSet[] {
+  findValueSetsByOid(oid: string): ValueSetExpansion[] {
     return this.valueSets[oid] ? Object.values(this.valueSets[oid]) : [];
   }
 
-  findValueSet(oid: string, version?: string): ValueSet | null {
+  findValueSet(oid: string, version?: string): ValueSetExpansion | null {
     if (version != null) {
       return this.valueSets[oid] != null ? this.valueSets[oid][version] : null;
     } else {

src/datatypes/clinical.ts

@@ -35,15 +35,35 @@ export class Concept {
     return codesInList(toCodeList(code), this.codes);
   }
 }
+export abstract class Vocabulary {
+  constructor(public id: string, public version?: string, public name?: string) {}
+}
 
-export class ValueSet {
-  constructor(public oid: string, public version?: string, public codes: any[] = []) {
-    this.codes ||= [];
+export class CodeSystem extends Vocabulary {
+  constructor(public id: string, public version?: string, public name?: string) {
+    super(id, version, name);
+  }
+}
+
+export class ValueSet extends Vocabulary {
+  constructor(
+    public id: string,
+    public version?: string,
+    public name?: string,
+    public codesystems?: CodeSystem[]
+  ) {
+    super(id, version, name);
   }
 
   get isValueSet() {
     return true;
   }
+}
+
+export class ValueSetExpansion {
+  constructor(public oid: string, public version?: string, public codes: any[] = []) {
+    this.codes ||= [];
+  }
 
   /**
    * Determines if the provided code matches any code in the current set.
@@ -149,7 +169,3 @@ function codesInList(cl1: any, cl2: any) {
 function codesMatch(code1: Code, code2: Code) {
   return code1.code === code2.code && code1.system === code2.system;
 }
-
-export class CodeSystem {
-  constructor(public id: string, public version?: string, public name?: string) {}
-}

src/elm/clinical.ts

@@ -2,28 +2,58 @@ import { Expression } from './expression';
 import * as dt from '../datatypes/datatypes';
 import { Context } from '../runtime/context';
 import { build } from './builder';
+import { resolveValueSet } from '../util/util';
 
 export class ValueSetDef extends Expression {
   name: string;
   id: string;
   version?: string;
+  codesystems?: CodeSystemRef[];
 
   constructor(json: any) {
     super(json);
     this.name = json.name;
     this.id = json.id;
     this.version = json.version;
+    this.codesystems = json.codesystems; // TODO: fix this as needed. See what the elm json passes through to populate this. Will be a CodeSystemRef (name, libraryname)
   }
 
   //todo: code systems and versions
 
   async exec(ctx: Context) {
-    const valueset =
-      (await ctx.codeService.findValueSet(this.id, this.version)) ||
-      new dt.ValueSet(this.id, this.version);
-    ctx.rootContext().set(this.name, valueset);
+    // TODO: use the context to resolve the CodeSystemRef to a CodeSystem
+    // valueset is loaded as part of initial library load ... check if in library vs list??? if not, add
+    if (!ctx) {
+      throw Error('no context');
+    } // dumb placeholder
+    const valueset = new dt.ValueSet(this.id, this.version, this.name, this.codesystems);
+    // ctx.rootContext().set(this.name, valueset); Note (2025): this seems to be unneccesary, remove completely in future if not needed
     return valueset;
   }
+
+  // Recommendations:
+  // Resolve when we need it -> if not resolved, throw error
+
+  // TODO: ?? other places that a valueset could be created in patient data (in the middle of execution)
+  //  ^ talk to Chris Moesel about valueset that's defined on the fly
+  // ... resources could have contained valuesets -> that would be a FHIR valueset (we wouldn't have any automatic conversion of that)
+  // probably not a problem we need to solve at this juncture
+  // this could influence how we define the terminology or data provider interfaces, but that's a future issue
+
+  // Update: initially store ValueSet to context... then, when we need the expansion, call the code service to expand and (also?) store the expansion to the context
+  // This rootContext call is kind of hinky ... why are we doing this since the getValueSet function pulls from the root library vs list?
+  // Recommendations:
+  // Cache both valueset references and valueset resolutions? (could also be responsibility of the terminology provider? implementation class can choose how to cache or not cache)
+  // For simplicity, push expanded caching to terminology provider
+
+  // async exec(ctx: Context) {
+  //   const valuesetExpanded = await ctx.codeService.findValueSet(this.id, this.version);
+  //   if(!valuesetExpanded){
+  //     throw Error('TODO: Make this better');
+  //   }
+  //   ctx.rootContext().set(this.name, valuesetExpanded);
+  //   return new dt.ValueSet(this.id, this.version);
+  // }
 }
 
 export class ValueSetRef extends Expression {
@@ -37,7 +67,6 @@ export class ValueSetRef extends Expression {
   }
 
   async exec(ctx: Context) {
-    // TODO: This calls the code service every time-- should be optimized
     let valueset = ctx.getValueSet(this.name, this.libraryName);
     if (valueset instanceof Expression) {
       valueset = await valueset.execute(ctx);
@@ -64,11 +93,12 @@ export class AnyInValueSet extends Expression {
     if (codes == null) {
       return false;
     }
-    const valueset = await this.valueset.execute(ctx);
+    const valueset: dt.ValueSet = await this.valueset.execute(ctx);
     if (valueset == null || !valueset.isValueSet) {
       throw new Error('ValueSet must be provided to AnyInValueSet expression');
     }
-    return codes.some((code: any) => valueset.hasMatch(code));
+    const vsExpansion = await resolveValueSet(valueset, ctx);
+    return codes.some((code: any) => vsExpansion.hasMatch(code));
   }
 }
 
@@ -90,12 +120,13 @@ export class InValueSet extends Expression {
     if (code == null) {
       return false;
     }
-    const valueset = await this.valueset.execute(ctx);
+    const valueset: dt.ValueSet = await this.valueset.execute(ctx);
     if (valueset == null || !valueset.isValueSet) {
       throw new Error('ValueSet must be provided to InValueSet expression');
     }
     // If there is a code and valueset return whether or not the valueset has the code
-    return valueset.hasMatch(code);
+    const vsExpansion = await resolveValueSet(valueset, ctx);
+    return vsExpansion.hasMatch(code);
   }
 }
 
@@ -108,14 +139,14 @@ export class ExpandValueSet extends Expression {
   }
 
   async exec(ctx: Context) {
-    const valueset = await this.valueset.execute(ctx);
+    const valueset: dt.ValueSet = await this.valueset.execute(ctx);
     if (valueset == null) {
       return null;
     } else if (!valueset.isValueSet) {
       throw new Error('ExpandValueSet function invoked on object that is not a ValueSet');
     }
-
-    return valueset.expand();
+    const vsExpansion = await resolveValueSet(valueset, ctx);
+    return vsExpansion.expand();
   }
 }
 

src/elm/external.ts

@@ -1,5 +1,5 @@
 import { Expression } from './expression';
-import { typeIsArray } from '../util/util';
+import { resolveValueSet, typeIsArray } from '../util/util';
 import { Context } from '../runtime/context';
 import { build } from './builder';
 import { RetrieveDetails } from '../types/cql-patient.interfaces';
@@ -33,13 +33,20 @@ export class Retrieve extends Expression {
     };
 
     if (this.codes) {
-      const resolvedCodes: Code[] | ValueSet | undefined = await this.codes.execute(ctx);
+      const executedCodes: Code[] | ValueSet | undefined = await this.codes.execute(ctx);
 
-      if (resolvedCodes == null) {
+      if (executedCodes == null) {
         return [];
       }
 
-      retrieveDetails.codes = resolvedCodes;
+      if (typeIsArray(executedCodes)) {
+        retrieveDetails.codes = executedCodes;
+      } else if (executedCodes?.isValueSet) {
+        // retrieveDetails codes are expected to be expanded for external usage
+        retrieveDetails.codes = await resolveValueSet(executedCodes, ctx);
+      } else {
+        retrieveDetails.codes = undefined;
+      }
     }
 
     if (this.dateRange) {

src/elm/overloaded.ts

@@ -2,12 +2,13 @@
 import { Expression } from './expression';
 import { ThreeValuedLogic } from '../datatypes/logic';
 import { DateTime } from '../datatypes/datetime';
-import { typeIsArray } from '../util/util';
+import { resolveValueSet, typeIsArray } from '../util/util';
 import { equals, equivalent } from '../util/comparison';
 import * as DT from './datetime';
 import * as LIST from './list';
 import * as IVL from './interval';
 import { Context } from '../runtime/context';
+import { ValueSet } from '../datatypes/clinical';
 
 export class Equal extends Expression {
   constructor(json: any) {
@@ -30,12 +31,24 @@ export class Equivalent extends Expression {
   }
 
   async exec(ctx: Context) {
-    const [a, b] = await this.execArgs(ctx);
+    let [a, b] = await this.execArgs(ctx);
     if (a == null && b == null) {
       return true;
     } else if (a == null || b == null) {
       return false;
     } else {
+      // comparison of valueset id/version -> only check expanded equivalence if these don't match
+      if (a.isValueSet && b.isValueSet) {
+        if (a.id === b.id && a.version === b.version) {
+          return true;
+        }
+      }
+      if (a.isValueSet) {
+        a = await resolveValueSet(a as ValueSet, ctx);
+      }
+      if (b.isValueSet) {
+        b = await resolveValueSet(b as ValueSet, ctx);
+      }
       return equivalent(a, b);
     }
   }

src/types/cql-code-service.interfaces.ts

@@ -1,4 +1,4 @@
-import { ValueSet } from '../datatypes/datatypes';
+import { ValueSetExpansion } from '../datatypes/datatypes';
 
 /*
  * Lookup of all codes used based on their ValueSet
@@ -19,14 +19,17 @@ export interface ValueSetDictionary {
  */
 export interface ValueSetObject {
   [oid: string]: {
-    [version: string]: ValueSet;
+    [version: string]: ValueSetExpansion;
   };
 }
 
 /*
  * Structure of an implementation to look up ValueSets based on oid and version
  */
 export interface TerminologyProvider {
-  findValueSetsByOid: (oid: string) => ValueSet[] | Promise<ValueSet[]>;
-  findValueSet: (oid: string, version?: string) => ValueSet | Promise<ValueSet> | null;
+  findValueSetsByOid: (oid: string) => ValueSetExpansion[] | Promise<ValueSetExpansion[]>;
+  findValueSet: (
+    oid: string,
+    version?: string
+  ) => ValueSetExpansion | Promise<ValueSetExpansion> | null;
 }

src/types/cql-patient.interfaces.ts

@@ -1,4 +1,4 @@
-import { Code, ValueSet } from '../datatypes/clinical';
+import { Code, ValueSetExpansion } from '../datatypes/clinical';
 import { Interval } from '../datatypes/interval';
 import { AnyTypeSpecifier } from './type-specifiers.interfaces';
 
@@ -31,7 +31,7 @@ export interface RetrieveDetails {
   datatype: string;
   templateId?: string;
   codeProperty?: string;
-  codes?: Code[] | ValueSet;
+  codes?: Code[] | ValueSetExpansion;
   dateProperty?: string;
   dateRange?: Interval;
 }

src/util/util.ts

@@ -1,3 +1,6 @@
+import { ValueSet, ValueSetExpansion } from '../datatypes/clinical';
+import { Context } from '../runtime/context';
+
 export type Direction = 'asc' | 'ascending' | 'desc' | 'descending';
 
 export function removeNulls(things: any[]) {
@@ -107,3 +110,14 @@ async function merge<T>(left: T[], right: T[], compareFn: SortCompareFn<T>) {
   }
   return [...sorted, ...left, ...right];
 }
+
+export async function resolveValueSet(vs: ValueSet, ctx: Context): Promise<ValueSetExpansion> {
+  // code service owns implementation of any valueset expansion caching
+  const vsExpansion = await ctx.codeService.findValueSet(vs.id, vs.version);
+  if (!vsExpansion) {
+    throw new Error(
+      `Unable to resolve expected valueset with id ${vs.id} and version ${vs.version}`
+    );
+  }
+  return vsExpansion;
+}

test/cql-code-service-test.ts

@@ -1,9 +1,12 @@
 import should from 'should';
 import { CodeService } from '../src/cql-code-service';
-import { Code, ValueSet } from '../src/datatypes/datatypes';
+import { Code, ValueSetExpansion } from '../src/datatypes/datatypes';
 
 describe('CodeService', () => {
-  let svc: CodeService, vsOne: ValueSet, vsTwo: ValueSet, vsThree: ValueSet;
+  let svc: CodeService,
+    vsOne: ValueSetExpansion,
+    vsTwo: ValueSetExpansion,
+    vsThree: ValueSetExpansion;
   beforeEach(() => {
     svc = new CodeService({
       '1.2.3.4.5': {
@@ -26,17 +29,17 @@ describe('CodeService', () => {
         ]
       }
     });
-    vsOne = new ValueSet('1.2.3.4.5', '1', [
+    vsOne = new ValueSetExpansion('1.2.3.4.5', '1', [
       new Code('ABC', '5.4.3.2.1', '1'),
       new Code('DEF', '5.4.3.2.1', '2'),
       new Code('GHI', '5.4.3.4.5', '3')
     ]);
-    vsTwo = new ValueSet('1.2.3.4.5', '2', [
+    vsTwo = new ValueSetExpansion('1.2.3.4.5', '2', [
       new Code('ABC', '5.4.3.2.1', '1'),
       new Code('DEF', '5.4.3.2.1', '2'),
       new Code('JKL', '5.4.3.2.1', '3')
     ]);
-    vsThree = new ValueSet('6.7.8.9.0', 'A', [
+    vsThree = new ValueSetExpansion('6.7.8.9.0', 'A', [
       new Code('MNO', '2.4.6.8.0', '3'),
       new Code('PQR', '2.4.6.8.0', '2'),
       new Code('STU', '2.4.6.8.0', '1')