CQL Execution 3.3.0

CQL Execution 3.3.0 implements several updates and fixes to improve alignment with the CQL specification, including:

• Improved support for CQL CodeSystems, including referring to CodeSystems from other libraries and tracking CodeSystem names
• Improved support for CQL ValueSets, including representation of CQL ValueSets as first-class objects and throwing errors when a ValueSet cannot be resolved
• Updated behavior of various operations to align with clarifications/changes in CQL 1.5 and Errata, including:
  • Update AllTrue logic to return true if the items list is null.
  • Update AnyTrue logic to return false if the items list is null.
  • Update In and Contains overloads to treat null items as equal.
  • Update Includes and IncludedIn point/list overloads to treat null items as equal.
  • Update Includes and IncludedIn list/list overloads to treat null items inside of lists as equal.
  • Update Includes and IncludedIn list/list overloads to return null if either list argument is null.
  • Update ReplaceMatches to support escaping $ in the substitution by using \$.
  • Update aggregation queries to not be distinct by default.

Included Pull Requests

• Added CodeSystemRef and updated CodeSystem type by @elsaperelli in #346
• CQL-to-ELM Translator 3.27.0 by @cmoesel in #347
• Update Spec Tests and Fix Newly Found Issues by @cmoesel in #348
• Vs firstclass by @lmd59 in #349

Full Changelog: v3.2.0...v3.3.0

3.2.0

CQL Execution 3.2.0 is a minor release with improved support for expanding valuesets, passing valuesets into functions, and calculating duration. Version 3.2.0 also contains several important bug fixes. See "What's Changed" for additional details.

What's Changed

• Support for expanding valuesets by @sorliog in #332
• Handle valuesets passed into functions by @lmd59 in #341
• Combine seconds and milliseconds when calculating duration by @elsaperelli in #340
• Avoid name collisions when resolving functions from the context by @hossenlopp in #338
• Fix tuple equality with null values by @cmoesel in #327
• Pass MessageListener to included libraries by @nkarip in #330
• Fix race condition when executing arugments by @rdingwell in #336
• Add missing await to Executor.exec_expression by @hossenlopp in #334
• Fix npm audit and codecov CI by @cmoesel in #328
• Ignore console color in message listener test by @cmoesel in #343

New Contributors

• @nkarip made their first contribution in #330
• @lmd59 made their first contribution in #341

Full Changelog: v3.1.0...v3.2.0

3.1.0

What's Changed

• Implement Implies Operator and update to cql2elm 3.12.0 by @hossenlopp in #320
• Updated cql-to-elm instructions in README.md by @sorliog in #317

New Contributors

• @sorliog made their first contribution in #317

Full Changelog: v3.0.1...v3.1.0

3.0.1

What's Changed

• Use passed in executionDateTime timeZoneOffset when available by @elsaperelli in #313
• Changed use of exec to execute for expressions by @elsaperelli in #314

New Contributors

• @elsaperelli made their first contribution in #313

Full Changelog: v3.0.0...v3.0.1

3.0.0

CQL Execution 3.0.0 Overview

• CQL Execution 3.0.0 supports an asynchronous execution flow. Patients are still processed in a serial fashion, but calls to the DataProvider (a.k.a. PatientSource) and TerminologyProvider (a.k.a. CodeService) can now happen asynchronously. This allows for these providers to more easily leverage web services and databases for their data.
• In addition to the asynchronous change, cql-execution now has some performance improvements, specifically when dealing with ValueSets that have a large amount of codes. See #278 for a detailed description of these enhancements, and huge shoutout to @birick1 for the thoughtful implementation!

Breaking Changes

The asynchronous migration is a breaking change. Implementers are required to make minor updates to their code to use this release. The code snippets below demonstrate the old way of invoking the v2.x.x engine and two ways to invoke the 3.x.x engine.

// v2.x.x usage
const result = executor.exec(patientSource);
// Do something with result

// v3.x.x usage
executor.exec(patientSource).then((result) => {
  // Do something with result
})

// or

const result = await executor.exec(patientSource);
// Do something with result

Existing implementations of DataProvider (PatientSource) and TerminologyProvider (CodeService) will continue to work as-is. Implementers who maintain their own implementations of these services may want to consider updating them to return results asynchronously.

For more information, see the V2 to V3 Migration Guide.

In addition, when running cql-execution in a Node.js environment, you should use at least Node 16.

Installation

To install this release in your project, run the following command:

npm install --save cql-execution@3

Full list of PRs

• Convert cql-execution to async by @mgramigna in #271
• Update DataProvider and PatientObject to allow async and be stricter by @mgramigna in #298
• Performance improvements by @birick1 in #307

Full Changelog: v2.4.6...v3.0.0

3.0.0-beta.5

What's Changed Since Beta 4

• Fixed collapseIntervals error on null intervals by @natjoe4 in #310

CQL Execution 3.0.0 Beta Overview

CQL Execution 3.0.0 Beta supports an asynchronous execution flow. Patients are still processed in a serial fashion, but calls to the DataProvider (a.k.a. PatientSource) and TerminologyProvider (a.k.a. CodeService) can now happen asynchronously. This allows for these providers to more easily leverage web services and databases for their data.

Breaking Changes

This is a breaking change. Implementers are required to make minor updates to their code to use this release. The code snippets below demonstrate the old way of invoking the v2.x.x engine and two ways to invoke the 3.x.x engine.

// v2.x.x usage
const result = executor.exec(patientSource);
// Do something with result

// v3.x.x usage
executor.exec(patientSource).then((result) => {
  // Do something with result
})

// or

const result = await executor.exec(patientSource);
// Do something with result

Existing implementations of DataProvider (PatientSource) and TerminologyProvider (CodeService) will continue to work as-is. Implementers who maintain their own implementations of these services may want to consider updating them to return results asynchronously.

For more information, see the V2 to V3 Migration Guide.

In addition, when running cql-execution in a Node.js environment, you should use at least Node 16.

Installation

To install this beta release in your project, run the following command:

npm install --save [email protected]

This is a beta release and is subject to change. We welcome your feedback.

2.4.6

What's Changed

• fixed collapseIntervals error on null intervals by @natjoe4 in #310

Full Changelog: v2.4.5...v2.4.6

3.0.0-beta.4

What's Changed Since Beta 3

• Add Detailed Execution Error Reporting by @natjoe4 in #308

When runtime errors are thrown from cql-execution during expression execution, the engine will attempt to extract more information about the expression that caused the error via the AnnotatedError object which is now exported from cql-execution. For example, an AnnotatedError could have the following message:

AnnotatedError: Encountered unexpected error during execution.

        Error Message:  Some error message
        CQL Library:    LibraryIdentifier|x.y.z
        Expression:     SomeELMExpressionType
        ELM Local ID:   123
        CQL Locator:    7:19-19:96

This information is also programatically accessible on the AnnotatedError object:

try {
  // some execution that might throw an error
} catch(e) {
  if (e instanceof AnnotatedError) {
    e.message; // Error message shown above
    e.libraryName; // Library identifier | Library version
    e.expressionName; // Name of the expression class that threw the error
    e.localId; // localId of the offending expression (must exist on the ELM)
    e.locator; // locator of the offending clause (must exist on the ELM)
    e.cause; // original stack trace of the error that was initially thrown
  }
}

CQL Execution 3.0.0 Beta Overview

CQL Execution 3.0.0 Beta supports an asynchronous execution flow. Patients are still processed in a serial fashion, but calls to the DataProvider (a.k.a. PatientSource) and TerminologyProvider (a.k.a. CodeService) can now happen asynchronously. This allows for these providers to more easily leverage web services and databases for their data.

Breaking Changes

This is a breaking change. Implementers are required to make minor updates to their code to use this release. The code snippets below demonstrate the old way of invoking the v2.x.x engine and two ways to invoke the 3.x.x engine.

// v2.x.x usage
const result = executor.exec(patientSource);
// Do something with result

// v3.x.x usage
executor.exec(patientSource).then((result) => {
  // Do something with result
})

// or

const result = await executor.exec(patientSource);
// Do something with result

Existing implementations of DataProvider (PatientSource) and TerminologyProvider (CodeService) will continue to work as-is. Implementers who maintain their own implementations of these services may want to consider updating them to return results asynchronously.

For more information, see the V2 to V3 Migration Guide.

In addition, when running cql-execution in a Node.js environment, you should use at least Node 16.

Installation

To install this beta release in your project, run the following command:

npm install --save [email protected]

This is a beta release and is subject to change. We welcome your feedback.

2.4.5

What's Changed

• Add Detailed Execution Error Reporting by @natjoe4 in #308

When runtime errors are thrown from cql-execution during expression execution, the engine will attempt to extract more information about the expression that caused the error via the AnnotatedError object which is now exported from cql-execution. For example, an AnnotatedError could have the following message:

AnnotatedError: Encountered unexpected error during execution.

        Error Message:  Some error message
        CQL Library:    LibraryIdentifier|x.y.z
        Expression:     SomeELMExpressionType
        ELM Local ID:   123
        CQL Locator:    7:19-19:96

This information is also programatically accessible on the AnnotatedError object:

try {
  // some execution that might throw an error
} catch(e) {
  if (e instanceof AnnotatedError) {
    e.message; // Error message shown above
    e.libraryName; // Library identifier | Library version
    e.expressionName; // Name of the expression class that threw the error
    e.localId; // localId of the offending expression (must exist on the ELM)
    e.locator; // locator of the offending clause (must exist on the ELM)
    e.cause; // original stack trace of the error that was initially thrown
  }
}

New Contributors

• @natjoe4 made their first contribution in #308

Full Changelog: v2.4.4...v2.4.5

3.0.0 Beta 3

What's Changed since Beta 2

• Performance improvements for list operations by @birick1 in #307
• Support for null-sourced queries by @cmoesel in #306
• Update DataProvider and PatientObject to allow async and be stricter by @mgramigna in #298
• Update Test Framework to use CQL Translator 2.x by @cmoesel in #295

Fixes projecttacoma/fqm-execution#172

New Contributors

• @birick1 made their first contribution in #307

CQL Execution 3.0.0 Beta Overview

CQL Execution 3.0.0 Beta supports an asynchronous execution flow. Patients are still processed in a serial fashion, but calls to the DataProvider (a.k.a. PatientSource) and TerminologyProvider (a.k.a. CodeService) can now happen asynchronously. This allows for these providers to more easily leverage web services and databases for their data.

Breaking Changes

This is a breaking change. Implementers are required to make minor updates to their code to use this release. The code snippets below demonstrate the old way of invoking the v2.x.x engine and two ways to invoke the 3.x.x engine.

// v2.x.x usage
const result = executor.exec(patientSource);
// Do something with result

// v3.x.x usage
executor.exec(patientSource).then((result) => {
  // Do something with result
})

// or

const result = await executor.exec(patientSource);
// Do something with result

Existing implementations of DataProvider (PatientSource) and TerminologyProvider (CodeService) will continue to work as-is. Implementers who maintain their own implementations of these services may want to consider updating them to return results asynchronously.

For more information, see the V2 to V3 Migration Guide.

In addition, when running cql-execution in a Node.js environment, you should use at least Node 16.

Installation

To install this beta release in your project, run the following command:

npm install --save [email protected]

This is a beta release and is subject to change. We welcome your feedback.