Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Executor
✓ import { Executor } from 'cql-execution';
✗ const Executor = require('cql-execution').Executor;
The primary class for executing ELM against data and terminology services. ESM import is standard, CJS is often problematic since v3.
PatientSource
✓ import { PatientSource } from 'cql-execution';
✗ import { DataProvider } from 'cql-execution';
An interface for providing patient data to the Executor. While referred to as `DataProvider` in some docs, the exported interface is `PatientSource`. Implementations must be asynchronous since v3.0.0.
CodeService
✓ import { CodeService } from 'cql-execution';
✗ import { TerminologyProvider } from 'cql-execution';
An interface for providing terminology services (e.g., ValueSet resolution) to the Executor. Referred to as `TerminologyProvider` in some docs, the exported interface is `CodeService`. Implementations must be asynchronous since v3.0.0.
Demonstrates how to load a simple ELM library, create mock `PatientSource` and `CodeService` implementations, and execute basic CQL logic for a single patient using the asynchronous execution engine.
import { Executor, PatientSource, CodeService } from 'cql-execution';
// 1. Define a simple ELM library (JSON representation of CQL)
const elm = {
library: {
identifier: { id: 'MyLibrary', version: '1.0.0' },
statements: {
def: [
{
name: 'TrueExpression',
context: 'Patient',
expression: { type: 'Literal', valueType: '{http://www.w3.org/2001/XMLSchema}boolean', value: 'true' }
},
{
name: 'PatientAge',
context: 'Patient',
expression: {
type: 'AgeInYears',
operand: {
type: 'SingletonFrom',
operand: {
type: 'Retrieve',
dataType: '{http://hl7.org/fhir/R4}Patient'
}
}
}
}
]
}
}
};
// 2. Implement a mock PatientSource (DataProvider)
class MockPatientSource implements PatientSource {
private patients: any[];
constructor(patients: any[]) {
this.patients = patients;
}
async currentPatient(): Promise<any> { return this.patients[0]; }
async nextPatient(): Promise<any | undefined> {
this.patients.shift();
return this.patients[0];
}
async retrieve(patientId: string, dataType: string, template: string, codes: any[], dateRange: any): Promise<any[]> {
if (dataType === '{http://hl7.org/fhir/R4}Patient') {
// Mock patient data for AgeInYears calculation. Real impl would query a data source.
return [{ birthDate: '1990-01-01' }];
}
return [];
}
async loadPatients(): Promise<void> { /* no-op for mock */ }
getPatientSourceIterator(): AsyncIterator<any> {
let index = 0;
const patients = this.patients;
return {
next: async () => {
if (index < patients.length) {
const value = patients[index++];
return { value, done: false };
} else {
return { value: undefined, done: true };
}
}
};
}
count(): number { return this.patients.length; }
}
// 3. Implement a mock CodeService (TerminologyProvider)
class MockCodeService implements CodeService {
async findValueSet(valueSetUrl: string, version?: string): Promise<any> { return { codes: [] }; }
async findCodes(code: any): Promise<any> { return []; }
async resolveValueSet(valueSet: any): Promise<any> { return { codes: [] }; }
}
async function executeCql() {
const patientSource = new MockPatientSource([{ id: 'patient1', birthDate: '1990-01-01' }]);
const codeService = new MockCodeService();
const executor = new Executor(elm);
const results = await executor.execute(patientSource, codeService, {
// `executionDateTime` is crucial for date-related CQL operations.
executionDateTime: '2025-01-01T12:00:00Z',
verbose: true
});
console.log('Results for Patient 1:');
for (const patientId in results.patientResults) {
const patientResults = results.patientResults[patientId];
console.log(` Patient ID: ${patientId}`);
console.log(` TrueExpression: ${patientResults.TrueExpression}`);
console.log(` PatientAge: ${patientResults.PatientAge}`);
}
}
executeCql().catch(console.error);
Errors
Common errors & fixes
TypeError: executor.exec is not a function
Attempting to use the deprecated `exec` method for execution, which was renamed to `execute` in v3.0.1.
fixUpdate the execution call from `executor.exec(...)` to `executor.execute(...)`.
TypeError: patientSource.currentPatient is not a function
Your custom `PatientSource` (or `CodeService`) implementation is not an `async` function and/or not returning a `Promise` for its methods, a requirement since v3.0.0.
fixEnsure all methods within your `PatientSource` and `CodeService` implementations are declared `async` and explicitly return `Promise` objects, even if the internal operation is synchronous (e.g., `return Promise.resolve(data);`).
AnnotatedError: Encountered unexpected error at Library.MyLibrary.1.0.0.TrueExpression: Cannot read properties of undefined (reading 'value')
A runtime error occurred during CQL expression evaluation, often due to unexpected `null` or `undefined` data, an unsupported operation, or malformed ELM. The error message indicates the exact ELM path.
fixExamine the `AnnotatedError` message for the specific CQL expression and location. Debug your CQL logic and verify the patient data or terminology provided to the `Executor`.
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax to import `cql-execution` in an ECMAScript Module (ESM) environment (e.g., a modern Node.js project with `"type": "module"` or browser bundlers).
fixSwitch to ESM `import` statements: `import { Executor } from 'cql-execution';`. Ensure your project's build configuration or Node.js environment is set up for ESM. Audit
Dependencies
cql-exec-fhiroptionalProvides a FHIR-based data source for the execution engine. Often used together for FHIR-based CQL logic.
cql-exec-vsacoptionalProvides a VSAC-enabled terminology service for looking up value sets. Often used together for terminology resolution.
cqm-executionoptionalA project built on cql-execution for executing electronic Clinical Quality Measures (eCQMs) using the QDM data model.