Merge branch 'feature/LF-3354/add-support-for-fhirclient' into 'master'

Add support for fhirclient

See merge request lfor/fhirpath.js!44

Author: yuriy-sedinkin

CHANGELOG.md

@@ -3,6 +3,12 @@
 This log documents significant changes for each release.  This project follows
 [Semantic Versioning](http://semver.org/).
 
+## [4.6.0] - 2025-08-21
+### Added
+- the ability to pass HTTP headers in requests to FHIR servers, which can be
+  used for authorization obtained via a third-party library (see fhirclient
+  example in docs/auth.md).
+
 ## [4.5.1] - 2025-07-09
 ### Added
 - tests for the R5 model.

README.md

@@ -93,8 +93,21 @@ where:
       currently supported %terminologies APIs.
     * options.fhirServerUrl - a URL pointing to a FHIR RESTful API server that
       is used to `resolve()` resources.
-    * options.signal - an AbortSignal object that allows you to abort the
-      asynchronous FHIRPath expression evaluation.
+    * options.signal - an AbortSignal object that allows you to [abort the
+      asynchronous FHIRPath expression evaluation](docs/abort.md).
+    * options.httpHeaders - an object with HTTP headers that will be used
+      when making requests to FHIR servers (e.g. for terminology servers).
+      The object has the following structure:
+      ```
+      {
+        <server base url>: {
+          <header name>: <header value>,
+          ...
+        },
+        ...
+      }
+      ```
+      See [authentication to FHIR servers](docs/auth.md).
 
 Note:  The resource will be modified by this function to add type information.
 
@@ -186,22 +199,6 @@ 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":
 

demo/package-lock.json

@@ -0,0 +1,19 @@
+# Aborting the asynchronous FHIRPath expression evaluation
+
+If you are using the `async` option, you may also pass in the `signal` option
+to allow for aborting the asynchronous evaluation of the FHIRPath expression.
+Note that passing the `signal` option to `compile()` whose result is used more
+than once is not allowed. 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 evalExpr = fhirpath.compile(
+  expression, model, {async: true}
+);
+const abortController = new AbortController();
+const signal = abortController.signal;
+let res = evalExpr(resource, environment, {signal});
+// Abort the evaluation of the compiled expression
+abortController.abort();
+```

docs/abort.md

@@ -0,0 +1,31 @@
+# Authentication to FHIR servers
+
+You may want to use third-party authentication to access FHIR servers
+(e.g. for terminology servers). In this case, you can pass in the `httpHeaders`
+option.
+
+For example, if in your application you use
+[fhirclient npm-package](https://www.npmjs.com/package/fhirclient),
+which sets the `Authorization` header for requests to the FHIR server,
+you can pass in the same header to fhirpath.js so that it can
+access the FHIR server with the same authorization:
+```js
+FHIR.oauth2.ready().then(client => {
+  const res = fhirpath.evaluate(
+    {"resourceType": "QuestionnaireResponse", ...},
+    '%context.repeat(item).answer.weight().sum()',
+    {},
+    fhirpath_r4_model,
+    {
+      async: true,
+      terminologyUrl: 'https://some-server',
+      httpHeaders: {
+        'https://some-server': {
+          // Use the same Authorization header as fhirClient
+          Authorization: client.getAuthorizationHeader()
+        }
+      }
+    }
+  );
+});
+```