.eslintrc.yml

@@ -8,6 +8,9 @@ parserOptions:
   ecmaVersion: 2016
   requireConfigFile: false
   sourceType: module
+globals:
+  Headers: true
+  fetch: true
 rules:
   indent:
     - error

CHANGELOG.md

@@ -3,6 +3,88 @@
 This log documents significant changes for each release.  This project follows
 [Semantic Versioning](http://semver.org/).
 
+## [3.18.0] - 2024-03-21
+### Added
+- The `signal` option to the `evaluate()` function and the function that is the
+  result of executing the `compile()` function to allow the user to cancel the
+  evaluation of an asynchronous expression.
+### Changed
+- The demo application now allows you to select a model, terminology server,
+  environment variables and can evaluate asynchronous expressions.
+### Fixed
+- The `weight()`/`ordinal()` function can now search for item weight in value
+  set and code system.
+- Removed creation of global `TypeInfo.model` value to allow asynchronous
+  evaluations using different models.
+
+## [3.17.3] - 2025-03-13
+### Fixed
+- an issue where the "not implemented" exception was not raised when it should
+  have been raised.
+
+## [3.17.2] - 2025-02-25
+### Changed
+- Adjusted equality operation to take into account "id" and "extension"
+  properties for primitive types.
+
+## [3.17.1] - 2025-02-12
+### Fixed
+- exception in `toString()` for node of type `date`, `dateTime`, `instant` or
+  `time` without value but with extension and/or id.
+
+## [3.17.0] - 2025-02-03
+### Added
+- getValue() function.
+
+## [3.16.4] - 2025-01-24
+### Fixed
+- Bug where single-quoted variable names were not supported.
+
+## [3.16.3] - 2025-01-21
+### Fixed
+- Bug with async boolean expressions (when an operator takes an async value as
+  a singleton parameter).
+
+## [3.16.2] - 2025-01-16
+### Fixed
+- Bug with toString when userInvocationTable passed.
+
+## [3.16.1] - 2025-01-09
+### Fixed
+- Read environment variables only when they are used in an expression, avoiding
+  unnecessary getter calls when working with libraries like Jotai.
+
+## [3.16.0] - 2024-10-10
+### Added
+- Support for type factory API (%factory).
+
+## [3.15.2] - 2024-08-30
+### Fixed
+- Removed the need to run `(cd demo && npm ci)`.
+- Excluded unnecessary files from the npm package.
+
+## [3.15.1] - 2024-08-06
+### Fixed
+- Return data type for `evaluate` and `compile` in TypeScript type declarations.
+  The return data type now depends on the `async` option.
+
+## [3.15.0] - 2024-08-05
+### Added
+- option `async`, which allows us to get the result of an expression evaluation
+  asynchronously.
+- Support for asynchronous functions: if any function in an expression returns
+  a Promise and option `async=true`, then the result of evaluating
+  the expression is a Promise.
+- async function `memberOf`.
+
+## [3.14.1] - 2024-07-02
+### Fixed
+- impossibility to use attribute name that starts with a capital letter.
+
+## [3.14.0] - 2024-07-02
+### Added
+- supplementary function `weight()` with alternative name `ordinal()`.
+
 ## [3.13.4] - 2024-06-13
 ### Fixed
 - a bug that could cause the context input parameter containing environment

README.md

@@ -1,13 +1,23 @@
 # fhirpath.js
 
-[![Build Status](https://travis-ci.org/HL7/fhirpath.js.svg?branch=master)](https://travis-ci.org/HL7/fhirpath.js)
-
 [FHIRPath](http://hl7.org/fhirpath/) implementation in JavaScript.
 
 ## Demo
 Try it out on the [demo page](https://hl7.github.io/fhirpath.js/).
 
-
+## Table of Contents:
+- [Installation](#installation-)
+  * [Server-side (Node.js)](#server-side--nodejs-)
+  * [Web-browser](#web-browser-)
+- [API Usage](#api-usage)
+  * [Asynchronous functions](#asynchronous-functions)
+  * [User-defined functions](#user-defined-functions)
+- [fhirpath CLI](#fhirpath-cli)
+- [Implementation Status](#implementation-status)
+- [Development Notes](#development-notes)
+  * [Building the demo page](#building-the-demo-page)
+  * [Updating the FHIR module on a FHIR release](#updating-the-fhir-module-on-a-fhir-release)
+- [Credits](#credits)
 
 ## Installation:
 
@@ -45,8 +55,45 @@ These will define additional global variables like "fhirpath_dstu2_model",
 Evaluating FHIRPath:
 
 ```js
-evaluate(resourceObject, fhirPathExpression, environment, model, options);
+evaluate(resourceObject, fhirPathExpression, envVars, model, options);
 ```
+where:
+* resourceObject - FHIR resource, part of a resource (in this case
+  fhirPathExpression.base should be provided), bundle as js object or array
+  of resources.
+* fhirPathExpression - string with FHIRPath expression, sample 'Patient.name.given',
+  or object, if fhirData represents the part of the FHIR resource:
+    * fhirPathExpression.base - base path in resource from which fhirData was extracted
+    * fhirPathExpression.expression - FHIRPath expression relative to path.base
+* envVars - a hash of variable name/value pairs. It is not recommended to 
+  modify the internal fields of a variable after passing it to the evaluation
+  function, since these changes may not be taken into account in further
+  evaluations due to caching of the evaluation results.
+  We currently cache `%questionnaire` scores for the `weight()` function.
+* model - the "model" data object specific to a domain, e.g. R4.
+  For example, you could pass in the result of require("fhirpath/fhir-context/r4");
+* options - additional options:
+    * options.resolveInternalTypes - whether values of internal
+      types should be converted to standard JavaScript types (true by default).
+      If false is passed, this conversion can be done later by calling
+      fhirpath.resolveInternalTypes().
+    * options.traceFn - An optional trace function to call when tracing.
+    * options.userInvocationTable - a user invocation table used
+      to replace any existing functions or define new ones.
+    * options.async - defines how to support asynchronous functions:
+        * false or similar to false, e.g. undefined, null, or 0 (default) - throw
+          an exception,
+        * true or similar to true - return Promise, only for asynchronous functions,
+        * "always" - return Promise always.
+    * options.terminologyUrl - a URL that points to a FHIR RESTful API that is
+      used to create %terminologies that implements the Terminology Service API.
+    * options.terminologyUrl - a URL that points to a terminology server. This
+      URL is used to initialize %terminologies, as defined in the FHIR FHIRPath
+      [Terminology Service API](https://www.hl7.org/fhir/fhirpath.html#txapi).
+      See the [Implementation Status](#implementation-status) section for the
+      currently supported %terminologies APIs.
+    * options.signal - an AbortSignal object that allows you to abort the
+      asynchronous FHIRPath expression evaluation.
 
 Note:  The resource will be modified by this function to add type information.
 
@@ -88,7 +135,7 @@ Precompiling fhirpath - result can be reused against multiple resources:
 
 ```js
 const path = fhirpath.compile('Patient.name.given', fhirpath_r4_model);
-var res = path({"resourceType": "Patient", ...}, {a: 5, ...});
+let res = path({"resourceType": "Patient", ...}, {a: 5, ...});
 ```
 
 If you are going to use the above "precompile" option with a part of a resource,
@@ -101,7 +148,7 @@ expression - fhirpath expression relative to base.
 const path = fhirpath.compile({ "base": "QuestionnaireResponse.item",
                                 "expression": "answer.value = 2 year"},
                               fhirpath_r4_model);
-var res = path({ "answer": { "valueQuantity": ...}, {a: 5, ...});
+let res = path({ "answer": { "valueQuantity": ...}, {a: 5, ...});
 ```
 
 During expression evaluation, some values or parts of values may have internal
@@ -113,7 +160,7 @@ the option "resolveInternalTypes" = false:
 
 ```js
 const contextVariable = fhirpath.evaluate(
-  resource, expression, context, model, {resolveInternalTypes: false}
+  resource, expression, envVars, model, {resolveInternalTypes: false}
 );
 ```
 
@@ -125,6 +172,22 @@ const path = fhirpath.compile(
 );
 ```
 
+But passing the `signal` option to compile() whose result is used more than once
+will cause abortion problems. If you need to abort the evaluation of the compiled
+expression, you should pass the signal option to the function that is returned
+by compile():
+
+```js
+const path = fhirpath.compile(
+  expression, model, {async: true}
+);
+const abortController = new AbortController();
+const signal = abortController.signal;
+let res = path(resource, environment, {signal});
+// Abort the evaluation of the compiled expression
+abortController.abort();
+```
+
 If at some point you decide to convert all values which have internal types to
 standard JavaScript types you can use the special function "resolveInternalTypes":
 
@@ -140,7 +203,7 @@ In the next example, `res` will have a value like this:
 
 ```js
 const res = fhirpath.types(
-  fhirpath.evaluate(resource, expression, context, model, {resolveInternalTypes: false})
+  fhirpath.evaluate(resource, expression, envVars, model, {resolveInternalTypes: false})
 );
 ```
 
@@ -150,9 +213,30 @@ let tracefunction = function (x, label) {
   console.log("Trace output [" + label + "]: ", x);
 };
 
-const res = fhirpath.evaluate(contextNode, path, environment, fhirpath_r4_model, { traceFn: tracefunction });
+const res = fhirpath.evaluate(contextNode, path, envVars, fhirpath_r4_model, { traceFn: tracefunction });
 ```
 
+### Asynchronous functions
+
+Some FHIRPath functions may be asynchronous. These functions throw exceptions by default.
+To enable these functions, we need to pass the `async` option to `evaluate` or `compile`.
+`async=true` enables return of a Promise only for expressions containing asynchronous functions.
+`async='always'` enables a Promise to be returned for any expression.
+
+For example, using the `memberOf` function might look like this:
+```js
+fhirpath.evaluate(
+  resource,
+  "Observation.code.coding.where(memberOf('http://hl7.org/fhir/ValueSet/observation-vitalsignresult'))",
+  {},
+  model,
+  { async: true, terminologyUrl: 'https://lforms-fhir.nlm.nih.gov/baseR4' }
+)
+```
+
+Please note that for the `memberOf` function to work you must pass in
+a terminologyUrl option.
+
 ### User-defined functions
 
 You can also replace any existing functions or define new ones. To do this you
@@ -327,6 +411,15 @@ Completed sections:
 Supported additional functions from FHIR:
 - extension(url : string) : collection
 - hasValue() : Boolean
+- memberOf(valueset : string) : Boolean
+
+Supported [Terminology Service APIs](https://build.fhir.org/fhirpath.html#txapi):
+- only `%terminologies.validateVS(valueSet, coded, params) : Parameters` is
+  partially supported. `valueSet` can only be a URL.
+
+Supported [FHIRPath supplements](https://hl7.org/fhir/uv/sdc/expressions.html#fhirpath-supplements):
+- sum(), min(), max(), count(), avg() - short-cuts for the equivalent .aggregate().
+- ordinal()/weight() - see [description of the weight() function](docs/weight.md).
 
 ## Development Notes
 

bashrc.fhirpath

@@ -1,7 +1,7 @@
 # The following is the standard bashrc file for the
 # development team for this repository.
 
-NODE=node-v16.15.0-linux-x64
+NODE=node-v22.11.0-linux-x64
 #
 # Set path
 PATH=~/${NODE}/bin:/bin:/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/etc

bin/fhirpath

@@ -45,8 +45,25 @@ else {
         throw new Error('FHIR model must be one of '+supportedVersions);
       model = require('../fhir-context/'+options.model);
     }
-    let res = fp.evaluate(resource, base ? {base, expression} : expression, context, model);
-    console.log('fhirpath(' + expression + ') =>');
-    console.log(JSON.stringify(res, null, " "));
+    let res = fp.evaluate(
+      resource, base ? {base, expression} : expression, context, model,
+      { async: true }
+    );
+
+    if (res instanceof Promise) {
+      res.then((r) => printResult(expression, r))
+    } else {
+      printResult(expression, res);
+    }
   }
 }
+
+/**
+ * Prints the result to the console.
+ * @param {string} expression - input expression
+ * @param {Array} result - result of evaluating the expression
+ */
+function printResult(expression, result) {
+  console.log('fhirpath(' + expression + ') =>');
+  console.log(JSON.stringify(result, null, " "));
+}

bin/install-demo.js

@@ -0,0 +1,18 @@
+/**
+ * This file contains code to run "npm ci" in the demo directory if it exists.
+ * The demo directory has been excluded from the npm package, and the presence
+ * of the demo directory is a signal that we are working with the source code.
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require("fs"); // Or `import fs from "fs";` with ESM
+
+const demoDir = path.join(__dirname, '../demo');
+
+if (fs.existsSync(demoDir)) {
+  console.log('Installing node modules in the demo directory...');
+  spawn('npm', ['ci'], {
+    cwd: demoDir,
+    stdio: 'inherit'
+  });
+}