@haste-health/fhirpath 0.127.1 → 0.127.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -0
- package/package.json +6 -6
- package/readme.md +0 -105
package/README.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# @haste-health/fhirpath
|
|
2
|
+
|
|
3
|
+
A [FHIRPath](https://hl7.org/fhirpath/) evaluator for TypeScript and JavaScript. Expressions are parsed once and cached, then evaluated against any JavaScript value. When the value is a FHIR resource, evaluation is type-aware through [`@haste-health/meta-value`](https://www.npmjs.com/package/@haste-health/meta-value): choice types resolve (`Patient.deceased` reads `deceasedBoolean`), primitive extensions are reachable (`name.given.extension`), and `is`, `as` and `ofType` know the element types of FHIR R4 and R4B.
|
|
4
|
+
|
|
5
|
+
It powers the search, validation and TestScript tooling in Haste Health's TypeScript packages: [`@haste-health/fhir-validation`](https://www.npmjs.com/package/@haste-health/fhir-validation), [`@haste-health/testscript-runner`](https://www.npmjs.com/package/@haste-health/testscript-runner), [`@haste-health/x-fhir-query`](https://www.npmjs.com/package/@haste-health/x-fhir-query), the admin app and the React components. The Haste Health server uses the Rust engine, [haste-fhirpath](https://crates.io/crates/haste-fhirpath).
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @haste-health/fhirpath
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { evaluate, evaluateWithMeta } from "@haste-health/fhirpath";
|
|
17
|
+
import type { Patient, uri } from "@haste-health/fhir-types/r4/types";
|
|
18
|
+
import { R4 } from "@haste-health/fhir-types/versions";
|
|
19
|
+
|
|
20
|
+
const patient = {
|
|
21
|
+
resourceType: "Patient",
|
|
22
|
+
name: [{ given: ["Eve"], family: "Williams" }],
|
|
23
|
+
deceasedBoolean: true,
|
|
24
|
+
} as Patient;
|
|
25
|
+
|
|
26
|
+
await evaluate("4 + 5", {}); // [9]
|
|
27
|
+
await evaluate("$this.name.given", patient); // ["Eve"]
|
|
28
|
+
await evaluate("$this.deceased", patient); // [true]
|
|
29
|
+
|
|
30
|
+
// Variables, as an object or an async lookup function
|
|
31
|
+
await evaluate(
|
|
32
|
+
"%people.name.given",
|
|
33
|
+
{},
|
|
34
|
+
{
|
|
35
|
+
variables: { people: [patient] },
|
|
36
|
+
},
|
|
37
|
+
);
|
|
38
|
+
|
|
39
|
+
// Type-aware evaluation returns MetaValues with type and location
|
|
40
|
+
const values = await evaluateWithMeta("$this.name", patient, {
|
|
41
|
+
fhirVersion: R4,
|
|
42
|
+
type: "Patient" as uri,
|
|
43
|
+
});
|
|
44
|
+
values[0].meta()?.type; // "HumanName"
|
|
45
|
+
values[0].location(); // ["name", 0]
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`evaluate(expression, context, options)` returns the result collection as plain values; `evaluateWithMeta` returns `IMetaValue`s. Options are `fhirVersion` (`R4` by default), `type` (the FHIR type of the context, otherwise taken from `resourceType`) and `variables`. `@haste-health/fhirpath/analyze` evaluates an expression against a type instead of a value and reports the types it would produce, for checking an expression before any data exists.
|
|
49
|
+
|
|
50
|
+
## Supported
|
|
51
|
+
|
|
52
|
+
| Category | Supported |
|
|
53
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| Operators | `+`, `-`, `*`, `/`, `=`, `!=`, `and`, `or`, `\|` (union), `in`, `contains`, `is`, `as` |
|
|
55
|
+
| Existence | `empty`, `exists`, `all`, `allTrue`, `anyTrue`, `allFalse`, `anyFalse`, `subsetOf`, `supersetOf`, `count`, `distinct`, `isDistinct` |
|
|
56
|
+
| Filtering | `where`, `select`, `repeat`, `ofType`, `as`, `children`, `descendants` |
|
|
57
|
+
| Other | `replace`, `type`, `resolve` (returns the reference unchanged, so `resolve() is Patient` tests the target type without fetching) |
|
|
58
|
+
| Terms | literals, `$this`, `$index`, `$total`, `%variables`, indexing `[n]`, parentheses |
|
|
59
|
+
|
|
60
|
+
Comparison (`<`, `>`), `implies`, `xor`, the string and math function groups and date arithmetic are not implemented in this engine. The Rust engine, [haste-fhirpath](https://crates.io/crates/haste-fhirpath), implements a much larger part of the specification and is what the Haste Health server evaluates with.
|
|
61
|
+
|
|
62
|
+
## Links
|
|
63
|
+
|
|
64
|
+
- [API reference](https://typescript.haste.health/modules/_haste-health_fhirpath.html)
|
|
65
|
+
- [Source](https://github.com/HasteHealth/HasteHealth/tree/main/frontend/packages/fhirpath)
|
|
66
|
+
- [TypeScript SDK overview](https://haste.health/docs/api/sdks/typescript)
|
|
67
|
+
- Rust equivalent: [haste-fhirpath](https://crates.io/crates/haste-fhirpath)
|
|
68
|
+
|
|
69
|
+
Part of [Haste Health](https://haste.health), licensed under [Apache-2.0](https://github.com/HasteHealth/HasteHealth/blob/main/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@haste-health/fhirpath",
|
|
3
|
-
"version": "0.127.
|
|
3
|
+
"version": "0.127.2",
|
|
4
4
|
"homepage": "https://haste.health",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"type": "module",
|
|
13
13
|
"dependencies": {
|
|
14
14
|
"chevrotain": "^13.2.0",
|
|
15
|
-
"@haste-health/meta-value": "^0.127.
|
|
15
|
+
"@haste-health/meta-value": "^0.127.2"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
18
|
"@babel/plugin-syntax-import-attributes": "^7.29.7",
|
|
@@ -25,10 +25,10 @@
|
|
|
25
25
|
"ts-jest": "^29.4.11",
|
|
26
26
|
"tsx": "4.11.2",
|
|
27
27
|
"typescript": "6.0.3",
|
|
28
|
-
"@haste-health/
|
|
29
|
-
"@haste-health/
|
|
30
|
-
"@haste-health/
|
|
31
|
-
"@haste-health/
|
|
28
|
+
"@haste-health/haste-health.fhir.r4.core": "^0.127.2",
|
|
29
|
+
"@haste-health/artifacts": "^0.127.2",
|
|
30
|
+
"@haste-health/fhir-types": "^0.127.2",
|
|
31
|
+
"@haste-health/hl7.fhir.r4.core": "^0.127.2"
|
|
32
32
|
},
|
|
33
33
|
"files": [
|
|
34
34
|
"lib/**"
|
package/readme.md
DELETED
|
@@ -1,105 +0,0 @@
|
|
|
1
|
-
# FHIRPath
|
|
2
|
-
|
|
3
|
-
## API
|
|
4
|
-
|
|
5
|
-
### evaluate
|
|
6
|
-
|
|
7
|
-
Returns a JS object/primitive based on the evaluation.
|
|
8
|
-
|
|
9
|
-
```typescript
|
|
10
|
-
evaluate(
|
|
11
|
-
expression: string,
|
|
12
|
-
ctx: unknown,
|
|
13
|
-
options?: Options
|
|
14
|
-
): NonNullable<unknown>[]
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
### evaluateWithMeta
|
|
18
|
-
|
|
19
|
-
Returns a @haste-health/meta-value singular value which contains data along with metadata about the evaluation.
|
|
20
|
-
|
|
21
|
-
```typescript
|
|
22
|
-
function evaluateWithMeta(
|
|
23
|
-
expression: string,
|
|
24
|
-
ctx: unknown,
|
|
25
|
-
options?: Options
|
|
26
|
-
): MetaValueSingular<NonNullable<unknown>>[];
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
### Arguments
|
|
30
|
-
|
|
31
|
-
| name | type | description |
|
|
32
|
-
| ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
33
|
-
| expression | string | FHIRPath expression to evaluate. |
|
|
34
|
-
| ctx | unknown | The context which the fhirpath is being evaluated from (sets $this context). |
|
|
35
|
-
| options | Object | Includes variables and metadata deriviation functions. |
|
|
36
|
-
| options.variables | Object \| Function | If an object is Record\<variableName, variableValue\> else (variableName)=> variableValue. |
|
|
37
|
-
| options.meta | Object | MetaInformation used to zip metadata with value. Used in type functions and operators. |
|
|
38
|
-
| options.meta.type | string | Root type for ctx. |
|
|
39
|
-
| options.meta.getSD | (fhir_version: FHIRVersion, type: string) => StructureDefinition | Returns a StructureDefinition based on type passed in. |
|
|
40
|
-
|
|
41
|
-
## Usage
|
|
42
|
-
|
|
43
|
-
```typescript
|
|
44
|
-
import * as fhirpath from "@haste-health/fhirpath";
|
|
45
|
-
|
|
46
|
-
// Default returns javascript object.
|
|
47
|
-
expect(fhirpath.evaluate("4 + 5", {})).toEqual([9]);
|
|
48
|
-
expect(fhirpath.evaluate("$this.test + 2 * 4", { test: 4 })).toEqual([12]);
|
|
49
|
-
|
|
50
|
-
// Evaluation with metavalue return (returns value in addition to meta information.)
|
|
51
|
-
expect(
|
|
52
|
-
evaluateWithMeta(
|
|
53
|
-
"$this.name",
|
|
54
|
-
{
|
|
55
|
-
resourceType: "Patient",
|
|
56
|
-
name: [{ given: ["bob"], family: "jameson" }],
|
|
57
|
-
},
|
|
58
|
-
{
|
|
59
|
-
meta: {
|
|
60
|
-
type: "Patient",
|
|
61
|
-
getSD: (fhirVersion, type: code) => {
|
|
62
|
-
const foundSD = sds.find((sd) => sd.type === type);
|
|
63
|
-
return foundSD;
|
|
64
|
-
},
|
|
65
|
-
},
|
|
66
|
-
}
|
|
67
|
-
).map((v) => v.meta()?.type)
|
|
68
|
-
).toEqual(["HumanName"]);
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## Operations supported
|
|
72
|
-
|
|
73
|
-
| Operation | Description | Supported |
|
|
74
|
-
| ------------------------- | -------------------------------------------------------------------------------------------- | --------- |
|
|
75
|
-
| + (addition) | Concatenate strings or add values if numeric. | true |
|
|
76
|
-
| - (subtraction) | Subtracts the right operand from the left operand. | true |
|
|
77
|
-
| as type specifier | Returns left operand if value is of type specified. | true |
|
|
78
|
-
| is(type : type specifier) | Filters left operand based on type specifier. | true |
|
|
79
|
-
| \* (multiplication) | Multiplies both arguments. | true |
|
|
80
|
-
| / (division) | Divides the left operand by the right operand | true |
|
|
81
|
-
| \| (union collections) | Merge the two collections into a single collection | true |
|
|
82
|
-
| = (Equals) | Returns true if the left collection is equal to the right collection | true |
|
|
83
|
-
| != (Not Equals) | Converse operator of equals returns true if left collection is not equal to right collection | true |
|
|
84
|
-
|
|
85
|
-
## Supported Functions
|
|
86
|
-
|
|
87
|
-
| Name | Description | Supported |
|
|
88
|
-
| ---------- | ------------------------------------------------------------------------------------------------------------- | --------- |
|
|
89
|
-
| empty | Returns true if the input collection is empty ({ }) and false otherwise. | true |
|
|
90
|
-
| exists | Returns true if the collection has any elements, and false otherwise. | true |
|
|
91
|
-
| all | Returns true if for every element in the input collection, criteria evaluates to true. | true |
|
|
92
|
-
| allTrue | Takes a collection of Boolean values and returns true if all the items are true. | true |
|
|
93
|
-
| anyTrue | Takes a collection of Boolean values and returns true if any of the items are true. | true |
|
|
94
|
-
| allFalse | Takes a collection of Boolean values and returns true if all the items are false. | true |
|
|
95
|
-
| anyFalse | Takes a collection of Boolean values and returns true if any of the items are false. | true |
|
|
96
|
-
| subsetOf | Returns true if all items in the input collection are members of the collection passed in. | true |
|
|
97
|
-
| supersetOf | Returns true if all items in the collection passed as the other argument are members of the input collection. | true |
|
|
98
|
-
| count | Returns the integer count of the number of items in the input collection. | true |
|
|
99
|
-
| distinct | Returns a collection containing only the unique items in the input collection. | true |
|
|
100
|
-
| isDistinct | Returns true if all the items in the input collection are distinct. | true |
|
|
101
|
-
| where | Returns a collection containing only those elements in the input collection based on where expression. | true |
|
|
102
|
-
| select | Evaluates the projection expression for each item in the input collection. | true |
|
|
103
|
-
| repeat | A version of select that will repeat the projection and add it to the output collection. | true |
|
|
104
|
-
| ofType | Returns a collection that contains all items in the input collection that are of the given type. | true |
|
|
105
|
-
| as | Returns filter same as ofType used for backwards compatibility. | true |
|