Support Advanced Terminology API

[cmoesel]

Currently, the TerminologyProvider (a.k.a. CodeService) API in cql-execution is quite simple:

export interface TerminologyProvider {
  findValueSetsByOid: (oid: string) => ValueSet[] | Promise<ValueSet[]>;
  findValueSet: (oid: string, version?: string) => ValueSet | Promise<ValueSet> | null;
}

This allows for easy implementation of terminology providers because it pushes most of the terminology operations to the CQL engine itself. The terminology provider need only support simple lookups and return the expanded value set(s). This, however, has performance implications since large value sets must be stored in memory and membership lookup is done by iterating the full set of codes. It also doesn't support other terminology-related operations like subsumption and code system membership.

We should introduce a v2 TerminologyProvider API that allows terminology operations to be implemented by the provider. This would allow for the provider to be backed by a terminology service or a database that can do operations more efficiently. It would also allow for implementation of advanced terminology operations that are not supported by the current engine.

The Java CQL Engine provides a fairly simple TerminologyProvider API (here) that currently supports in (VS membership), expand (VS expansion), and lookup (code display lookup). I think we can borrow some from that, but would suggest that we also cover a bit more ground:

// Notional AdvanceTerminologyProvider... VERY subject to change!
export interface AdvancedTerminologyProvider {
  capabilities: () => TerminologyCapabilities;
  inValueSet: (code: Code | Code[], valueSet: ValueSetInfo) => Promise<boolean>;
  expandValueSet: (valueSet: ValueSetInfo) => Promise<ExpandedValueSet>;
  inCodeSystem: (code: Code | Code[], codeSystem: CodeSystemInfo) => Promise<boolean>;
  expandCodeSystem: (codeSystem: CodeSystemInfo) => Promise<ExpandedCodeSystem>;
  subsumes: (subsuming: Code | Concept, subsumed: Code | Concept) => Promise<boolean>
}

The cql-execution framework can check a terminology provide to see if it has a capabilities function, and if so, inspect its capabilities and then call it as appropriate. If it doesn't have a capabilities function, then it's assumed to be a v1 provider. We should continue to support both.

This design is still very subject to change and there are some open questions:

1. Does it make sense for a terminology provider to advertise its capabilities? Or should the engine just always try (and know that sometimes it won't work).
2. If a terminology provider can't process one of these requests, should it throw? Or return null?

[hossenlopp]

Following up on some of these questions.

1. The capabilities response might make sense to ease some of the logic in the engine. But it would just be a set of booleans of if the functions are implemented or not. This could just be checked by the existence of the functions. expandValueSet should be required but the rest could just optionally be undefined.
2. I think if the terminology provider cannot process the request then it should throw an error. The engine can then consume the error and include it in a thrown error as the cause if needed. Some situations may make it appropriate for the engine to just return null for the expression. Allowing errors to pass through should help people developing their TerminologyProviders.