fhir_r5_cql 0.7.0

FHIR R5 binding for the model-independent `cql` engine: the R5 ModelResolver and TerminologyProvider implementations that let the CQL engine execute against FHIR R5 data.

fhir_r5_cql

The FHIR R5 binding for the model-independent cql engine.

The cql package translates Clinical Quality Language source into ELM and executes it, but it is deliberately FHIR-free: all access to FHIR data goes through its ModelResolver / TerminologyProvider boundary interfaces. This package supplies the FHIR R5 implementations of those interfaces — the analogue of cqframework's engine.fhir / cql-exec-fhir:

• R5ModelResolver — type checks (is/as), FHIRPath-based property navigation, and the boundary conversions between FHIR R5 types and CQL System types (FhirBoolean ↔ Boolean, Coding → Code, CodeableConcept → Concept, Quantity → System.Quantity, Period → Interval<DateTime>, Range → Interval<Quantity>, …).
• R5TerminologyProvider — resolves value-set membership by fetching the FHIR ValueSet resource (through fhir_r5_path's canonical-resource cache) and checking codes with its ValueSetChecker.

The package re-exports package:cql/cql.dart, so this single import gives you the whole engine plus the R5 wiring.

Installation

dependencies:
  fhir_r5_cql: ^0.6.0

Usage

import 'package:fhir_r5_cql/fhir_r5_cql.dart';

Future<void> main() async {
  const source = '''
library Example version '1.0.0'

define "Greeting": 'Hello, CQL'
define "Sum": 1 + 2 + 3
define "IsAdult": 21 >= 18
define "Evens": (List{1, 2, 3, 4, 5, 6}) X where X mod 2 = 0
''';

  // 1. Translate CQL source to an executable ELM library. Translation
  //    problems are recorded on `library.annotation` (mirroring the
  //    reference translator) rather than thrown.
  final library = libraryFromCql(source);

  // 2. Execute. The R5ModelResolver wires in FHIR R5 data access;
  //    expressions that retrieve (e.g. [Patient], [Observation]) resolve
  //    through it. `execute` returns the run context, keyed by define name.
  final results = await library.execute(
    <String, dynamic>{},
    const R5ModelResolver(),
  ) as Map<String, dynamic>;

  print(results['Sum']); // 6
}

A runnable version of this demo is in example/main.dart. Translated libraries round-trip through ELM JSON (library.toJson() / CqlLibrary.fromJson(...)), so they can be stored and reloaded without re-translating.

Terminology

R5TerminologyProvider resolves in "MyValueSet" membership tests. By default it fetches ValueSet resources over the network; pass a pre-populated CanonicalResourceCache to resolve offline:

final terminology = R5TerminologyProvider();

Libraries that only use locally-supplied expansions can instead place them directly in the execution context under _valueSets and need no provider.

The fhir_fli CQL family

Package	Role
cql	Model-independent CQL→ELM translator + engine
fhir_r4_cql	The FHIR R4 binding
fhir_r5_cql	This package — the FHIR R5 binding
fhir_r6_cql	The FHIR R6 binding

License

MIT — see LICENSE.