Merge branch 'feature/LF-2985/async-functions' into 'master'

Added support for async functions

See merge request lfor/fhirpath.js!17

Author: yuriy-sedinkin

Diff for: .eslintrc.yml

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

Diff for: CHANGELOG.md

@@ -3,6 +3,15 @@
 This log documents significant changes for each release.  This project follows
 [Semantic Versioning](http://semver.org/).
 
+## [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.

Diff for: 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:
 
@@ -47,6 +57,37 @@ Evaluating FHIRPath:
 ```js
 evaluate(resourceObject, fhirPathExpression, environment, 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
+* environment - a hash of variable name/value pairs.
+* 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.
 
 Note:  The resource will be modified by this function to add type information.
 
@@ -153,6 +194,27 @@ let tracefunction = function (x, label) {
 const res = fhirpath.evaluate(contextNode, path, environment, 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 +389,11 @@ 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.
 
 ## Development Notes
 

Diff for: 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-v18.14.2-linux-x64
 #
 # Set path
 PATH=~/${NODE}/bin:/bin:/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/etc

Diff for: 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, " "));
+}