CQL Worker

A library for executing Clinical Quality Language (CQL) expressions asynchronously via Web Workers. This allows web applications to evaluate CQL expressions in a non-blocking manner. For examples where this can be useful, see the Alcohol Screening and Brief Intervention (ASBI) Clinical Decision Support (CDS) Screening and Intervention apps.

Underlying Technologies

CQL Execution Engine

All CQL calculations are executed using the CQL Execution Engine, an open source library that implements the CQL standard.

FHIRHelpers

FHIRHelpers is a library that defines functions for converting between FHIR and CQL data types. cql-worker includes version 4.0.1 of FHIRHelpers, which is available under an Apache 2.0 License, Copyright 2014 The MITRE Corporation. Other versions of FHIRHelpers can be found here.

CQL Execution FHIR Data Source

The cql-exec-fhir is used to provide a FHIR-based data source for use with the CQL Execution Engine.

Web Workers

Web Workers provide a means to offload CQL expression calculations to a separate thread from within the browser.

Node Worker Threads

Node Worker Threads are similar to Web Workers but are for use in the Node.js runtime environment.

Current Limitations

CQL Workers has been tested with the following environments and build tools:

Browser with Webpack 4 using worker-loader.
Webpack 5 supposedly has better support for Web Workers but also includes several breaking changes when it comes to bundling Node.js applications for the web browser. CQL Worker should work with Webpack 5, but it has not been tested. Please open an issue if you run into any problems.
Node.js has been tested, but be sure to set the isNodeJs flag to true.

Example Usage

CQL Worker is published on npm and can be installed via: npm install cql-worker.

Browser with Webpack 4

// See: https://github.com/webpack-contrib/worker-loader
import Worker from "<PATH-TO-NODE-MODULES>/cql-worker/src/cql.worker.js";
import { initialzieCqlWorker } from 'cql-worker';

// Define a web worker for evaluating CQL expressions
const cqlWorker = new Worker();

// Initialize the cql-worker
let [setupExecution, sendPatientBundle, evaluateExpression] = initialzieCqlWorker(cqlWorker);

// Define `elmJson`, `valueSetJson`, `cqlParameters`, and `elmJsonDependencies`

// Send the cqlWorker an initial message containing the ELM JSON representation of the CQL expressions
setupExecution(elmJson, valueSetJson, cqlParameters, elmJsonDependencies);

// Create `patientBundle` to hold the patient's FHIR resources

// Send the patient bundle to the CQL web worker
sendPatientBundle(patientBundle);

// Define `namedExpression`, a string containing the name of a CQL expression

let result = await evaluateExpression(namedExpression);

See the ASBI CDS Screening and Intervention apps for additional information for how to configure Webpack to properly package cql-worker.

Node.js

Using CQL Workers with Node.js requires enabling the --experimental-json-modules flag.

import { Worker } from 'worker_threads';
import { initialzieCqlWorker } from 'cql-worker';
import { createRequire } from 'module';
const require = createRequire(import.meta.url);

let cqlWorker = new Worker(require.resolve('cql-worker/src/cql-worker-thread.js'));
let [setupExecution, sendPatientBundle, evaluateExpression] = initialzieCqlWorker(cqlWorker, true);

// Define `elmJson`, `valueSetJson`, and `cqlParameters`

setupExecution(elmJson, valueSetJson, cqlParameters, elmJsonDependencies);

// Create `patientBundle` to hold the patient's FHIR resources

sendPatientBundle(patientBundle);

// Define `namedExpression`, a string containing the name of a CQL expression

let result = await evaluateExpression(namedExpression);

License

Unless otherwise noted, this work is available under an Apache 2.0 license. It was produced by the MITRE Corporation for the National Center on Birth Defects and Developmental Disabilities, Centers for Disease Control and Prevention in accordance with the Statement of Work, contract number 75FCMC18D0047, task order number 75D30119F05691.

TopologyHealth / cql-worker