@haste-health/client 0.127.0 → 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 +78 -210
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,228 +1,96 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @haste-health/client
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A typed FHIR client for TypeScript and JavaScript. Every FHIR interaction (read, search, create, update, patch, delete, history, operations, batch and transaction) is a method on one `AsynchronousClient`, typed against the R4 and R4B definitions in [`@haste-health/fhir-types`](https://www.npmjs.com/package/@haste-health/fhir-types). The bundled HTTP client talks to any FHIR server over `fetch`; the client itself is transport-agnostic middleware, so the same interface can wrap other transports.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The Haste Health admin app, CLI, React components and TestScript runner all use it.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
### Arguments
|
|
12
|
-
|
|
13
|
-
Middleware is built using an array of functions each function is passed the following arguments:
|
|
14
|
-
|
|
15
|
-
| Name | Description | type |
|
|
16
|
-
| ---------- | ------------------------------------------------------ | ----------- |
|
|
17
|
-
| request | A FHIRRequest object information varies based on type. | FHIRRequest |
|
|
18
|
-
| args | Object contains state and ctx | state,ctx |
|
|
19
|
-
| args.state | Internal state of the middleware. | unknown |
|
|
20
|
-
| args.ctx | Context of the call (will vary based on client). | unknown |
|
|
21
|
-
|
|
22
|
-
### Response
|
|
23
|
-
|
|
24
|
-
Middleware should return the following object:
|
|
25
|
-
|
|
26
|
-
```typescript
|
|
27
|
-
{
|
|
28
|
-
ctx: CTX;
|
|
29
|
-
state: State;
|
|
30
|
-
response: FHIRResponse;
|
|
31
|
-
}
|
|
9
|
+
```bash
|
|
10
|
+
npm install @haste-health/client
|
|
32
11
|
```
|
|
33
12
|
|
|
34
|
-
|
|
13
|
+
## Usage
|
|
35
14
|
|
|
36
|
-
|
|
15
|
+
```ts
|
|
16
|
+
import createHTTPClient from "@haste-health/client/http";
|
|
17
|
+
import type { Patient } from "@haste-health/fhir-types/r4/types";
|
|
18
|
+
import { R4 } from "@haste-health/fhir-types/versions";
|
|
37
19
|
|
|
38
|
-
|
|
20
|
+
const client = createHTTPClient({
|
|
21
|
+
url: "https://<host>/w/<tenant>/<project>/api/v1/fhir",
|
|
22
|
+
getAccessToken: async () => accessToken,
|
|
23
|
+
});
|
|
39
24
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
} from "@haste-health/client/lib/middleware/index.js";
|
|
45
|
-
import { AsynchronousClient } from "@haste-health/client/lib/index.js";
|
|
25
|
+
const created = await client.create({}, R4, {
|
|
26
|
+
resourceType: "Patient",
|
|
27
|
+
name: [{ family: "Smith", given: ["John"] }],
|
|
28
|
+
} as Patient);
|
|
46
29
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
30
|
+
const { resources, total } = await client.search_type(
|
|
31
|
+
{},
|
|
32
|
+
R4,
|
|
33
|
+
"Patient",
|
|
34
|
+
"name=Smith&_count=10",
|
|
50
35
|
);
|
|
51
|
-
```
|
|
52
36
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
We provide an HTTP client by default that allows you to call FHIR servers via API calls.
|
|
56
|
-
Supports all the method calls within the AsynchronousClient interface:
|
|
57
|
-
|
|
58
|
-
```typescript
|
|
59
|
-
export interface FHIRClientAsync<CTX> {
|
|
60
|
-
request(ctx: CTX, request: FHIRRequest): Promise<FHIRResponse>;
|
|
61
|
-
capabilities<FHIRVersion extends FHIR_VERSION>(
|
|
62
|
-
ctx: CTX,
|
|
63
|
-
fhirVersion: FHIRVersion
|
|
64
|
-
): Promise<Resource<FHIRVersion, "CapabilityStatement">>;
|
|
65
|
-
search_system<FHIRVersion extends FHIR_VERSION>(
|
|
66
|
-
ctx: CTX,
|
|
67
|
-
fhirVersion: FHIRVersion,
|
|
68
|
-
parameters: ParsedParameter<string | number>[] | string
|
|
69
|
-
): Promise<{
|
|
70
|
-
total?: number;
|
|
71
|
-
resources: Resource<FHIRVersion, AllResourceTypes>[];
|
|
72
|
-
}>;
|
|
73
|
-
search_type<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
74
|
-
ctx: CTX,
|
|
75
|
-
fhirVersion: FHIRVersion,
|
|
76
|
-
type: T,
|
|
77
|
-
parameters: ParsedParameter<string | number>[] | string
|
|
78
|
-
): Promise<{
|
|
79
|
-
total?: number;
|
|
80
|
-
resources: Resource<FHIRVersion, T>[];
|
|
81
|
-
}>;
|
|
82
|
-
create<
|
|
83
|
-
FHIRVersion extends FHIR_VERSION,
|
|
84
|
-
Value extends Resource<FHIRVersion, AllResourceTypes>
|
|
85
|
-
>(
|
|
86
|
-
ctx: CTX,
|
|
87
|
-
fhirVersion: FHIRVersion,
|
|
88
|
-
resource: Value
|
|
89
|
-
): Promise<Value>;
|
|
90
|
-
update<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
91
|
-
ctx: CTX,
|
|
92
|
-
fhirVersion: FHIRVersion,
|
|
93
|
-
resourceType: T,
|
|
94
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>,
|
|
95
|
-
resource: Resource<FHIRVersion, T>
|
|
96
|
-
): Promise<Resource<FHIRVersion, T>>;
|
|
97
|
-
patch<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
98
|
-
ctx: CTX,
|
|
99
|
-
fhirVersion: FHIRVersion,
|
|
100
|
-
resourceType: T,
|
|
101
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>,
|
|
102
|
-
patches: any
|
|
103
|
-
): Promise<Resource<FHIRVersion, T>>;
|
|
104
|
-
read<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
105
|
-
ctx: CTX,
|
|
106
|
-
fhirVersion: FHIRVersion,
|
|
107
|
-
resourceType: T,
|
|
108
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>
|
|
109
|
-
): Promise<Resource<FHIRVersion, T> | undefined>;
|
|
110
|
-
vread<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
111
|
-
ctx: CTX,
|
|
112
|
-
fhirVersion: FHIRVersion,
|
|
113
|
-
resourceType: T,
|
|
114
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>,
|
|
115
|
-
versionId: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>
|
|
116
|
-
): Promise<Resource<FHIRVersion, T> | undefined>;
|
|
117
|
-
delete<FHIRVersion extends FHIR_VERSION, T extends ResourceType<FHIRVersion>>(
|
|
118
|
-
ctx: CTX,
|
|
119
|
-
fhirVersion: FHIRVersion,
|
|
120
|
-
resourceType: T,
|
|
121
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>
|
|
122
|
-
): Promise<void>;
|
|
123
|
-
|
|
124
|
-
historySystem<FHIRVersion extends FHIR_VERSION>(
|
|
125
|
-
ctx: CTX,
|
|
126
|
-
fhirVersion: FHIRVersion,
|
|
127
|
-
parameters?: ParsedParameter<string | number>[] | string
|
|
128
|
-
): Promise<NonNullable<Resource<FHIRVersion, "Bundle">["entry"]>>;
|
|
129
|
-
historyType<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
130
|
-
ctx: CTX,
|
|
131
|
-
fhirVersion: FHIRVersion,
|
|
132
|
-
resourceType: T,
|
|
133
|
-
parameters?: ParsedParameter<string | number>[] | string
|
|
134
|
-
): Promise<NonNullable<Resource<FHIRVersion, "Bundle">["entry"]>>;
|
|
135
|
-
historyInstance<FHIRVersion extends FHIR_VERSION, T extends AllResourceTypes>(
|
|
136
|
-
ctx: CTX,
|
|
137
|
-
fhirVersion: FHIRVersion,
|
|
138
|
-
resourceType: T,
|
|
139
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>,
|
|
140
|
-
parameters?: ParsedParameter<string | number>[] | string
|
|
141
|
-
): Promise<NonNullable<Resource<FHIRVersion, "Bundle">["entry"]>>;
|
|
142
|
-
invoke_system<
|
|
143
|
-
FHIRVersion extends FHIR_VERSION,
|
|
144
|
-
Op extends IOperation<any, any>
|
|
145
|
-
>(
|
|
146
|
-
op: Op,
|
|
147
|
-
ctx: CTX,
|
|
148
|
-
fhirVersion: FHIRVersion,
|
|
149
|
-
input: OPMetadata<Op>["Input"]
|
|
150
|
-
): Promise<OPMetadata<Op>["Output"]>;
|
|
151
|
-
invoke_type<
|
|
152
|
-
FHIRVersion extends FHIR_VERSION,
|
|
153
|
-
Op extends IOperation<any, any>,
|
|
154
|
-
T extends AllResourceTypes
|
|
155
|
-
>(
|
|
156
|
-
op: Op,
|
|
157
|
-
ctx: CTX,
|
|
158
|
-
fhirVersion: FHIRVersion,
|
|
159
|
-
resourceType: T,
|
|
160
|
-
input: OPMetadata<Op>["Input"]
|
|
161
|
-
): Promise<OPMetadata<Op>["Output"]>;
|
|
162
|
-
invoke_instance<
|
|
163
|
-
FHIRVersion extends FHIR_VERSION,
|
|
164
|
-
Op extends IOperation<any, any>,
|
|
165
|
-
T extends AllResourceTypes
|
|
166
|
-
>(
|
|
167
|
-
op: Op,
|
|
168
|
-
ctx: CTX,
|
|
169
|
-
fhirVersion: FHIRVersion,
|
|
170
|
-
resourceType: T,
|
|
171
|
-
id: NonNullable<Resource<FHIRVersion, AllResourceTypes>["id"]>,
|
|
172
|
-
input: OPMetadata<Op>["Input"]
|
|
173
|
-
): Promise<OPMetadata<Op>["Output"]>;
|
|
174
|
-
transaction<FHIRVersion extends FHIR_VERSION>(
|
|
175
|
-
ctx: CTX,
|
|
176
|
-
fhirVersion: FHIRVersion,
|
|
177
|
-
bundle: Resource<FHIRVersion, "Bundle">
|
|
178
|
-
): Promise<Resource<FHIRVersion, "Bundle">>;
|
|
179
|
-
batch<FHIRVersion extends FHIR_VERSION>(
|
|
180
|
-
ctx: CTX,
|
|
181
|
-
fhirVersion: FHIRVersion,
|
|
182
|
-
bundle: Resource<FHIRVersion, "Bundle">
|
|
183
|
-
): Promise<Resource<FHIRVersion, "Bundle">>;
|
|
184
|
-
}
|
|
37
|
+
const patient = await client.read({}, R4, "Patient", created.id!);
|
|
185
38
|
```
|
|
186
39
|
|
|
187
|
-
|
|
40
|
+
The first argument of every method is the per-call context. For the HTTP client it is `{ headers?: Record<string, string> }`, so extra headers can be sent on one request.
|
|
41
|
+
|
|
42
|
+
### HTTP client options
|
|
43
|
+
|
|
44
|
+
| Option | Purpose |
|
|
45
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| `url` | The FHIR base URL, or a function from FHIR version to URL |
|
|
47
|
+
| `getAccessToken` | Called before each request; the result is sent as a `Bearer` token |
|
|
48
|
+
| `authenticate` | Called when the server answers 401, for example to start a login flow |
|
|
49
|
+
| `searchMethod` | `"GET"` (default) puts search parameters in the query string; `"POST"` form-posts them to `_search` to keep them out of URLs |
|
|
50
|
+
|
|
51
|
+
Responses with status 400 or above throw a `ResponseError` (test with `isResponseError`) carrying the request and the server's `OperationOutcome`.
|
|
52
|
+
|
|
53
|
+
### Methods
|
|
54
|
+
|
|
55
|
+
| Method | FHIR interaction |
|
|
56
|
+
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
57
|
+
| `capabilities` | `GET metadata` |
|
|
58
|
+
| `read`, `vread` | Read and version read |
|
|
59
|
+
| `search_type`, `search_system` | Search; parameters as a query string or `ParsedParameter[]`; returns `{ total, resources }` |
|
|
60
|
+
| `create`, `update`, `conditionalUpdate`, `patch` | Writes; `patch` takes a JSON Patch body |
|
|
61
|
+
| `delete_instance`, `delete_type`, `delete_system` | Deletes, including conditional ones |
|
|
62
|
+
| `history_instance`, `history_type`, `history_system` | History; returns the Bundle entries |
|
|
63
|
+
| `invoke_instance`, `invoke_type`, `invoke_system` | Operations; pass a code such as `"expand"`, or an operation from `@haste-health/generated-ops` for typed in/out |
|
|
64
|
+
| `batch`, `transaction` | Bundle submission |
|
|
65
|
+
| `request` | Send a raw `FHIRRequest` and get the `FHIRResponse` |
|
|
66
|
+
|
|
67
|
+
### Middleware
|
|
68
|
+
|
|
69
|
+
A client is an `AsynchronousClient` built on a middleware chain. Each middleware receives `(state, context, next)`, where `context` holds the `ctx`, the `FHIRRequest` and, after `next`, the `FHIRResponse`, and returns `[state, context]`. This is how the HTTP transport is implemented, and how you add caching, logging or a different transport:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { AsynchronousClient } from "@haste-health/client";
|
|
73
|
+
import { createMiddlewareAsync } from "@haste-health/client/middleware";
|
|
74
|
+
|
|
75
|
+
const client = new AsynchronousClient(
|
|
76
|
+
createMiddlewareAsync({}, [
|
|
77
|
+
async (state, context, next) => {
|
|
78
|
+
console.log(context.request.type);
|
|
79
|
+
return next(state, context);
|
|
80
|
+
},
|
|
81
|
+
async (state, context) => [state, { ...context, response: myResponse }],
|
|
82
|
+
]),
|
|
83
|
+
);
|
|
84
|
+
```
|
|
188
85
|
|
|
189
|
-
|
|
190
|
-
import { expect, test } from "@jest/globals";
|
|
86
|
+
`@haste-health/client/url` exports `parseUrl` and `parseQuery` for FHIR search strings, plus the escaping helpers (`escapeParameter`, `splitParameter`) that honour FHIR's `\` escapes for `,`, `|` and `$`. `@haste-health/client/types` and `@haste-health/client/interface` hold the request, response and client interface types.
|
|
191
87
|
|
|
192
|
-
|
|
193
|
-
import { OperationDefinition } from "@haste-health/fhir-types/r4/types";
|
|
194
|
-
import { R4 } from "@haste-health/fhir-types/version";
|
|
88
|
+
## Links
|
|
195
89
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
});
|
|
90
|
+
- [API reference](https://typescript.haste.health/modules/_haste-health_client.html)
|
|
91
|
+
- [Source](https://github.com/HasteHealth/HasteHealth/tree/main/frontend/packages/client)
|
|
92
|
+
- [TypeScript SDK overview](https://haste.health/docs/api/sdks/typescript) and the [FHIR REST API](https://haste.health/docs/api/rest_api/fhir/intro) on haste.health
|
|
93
|
+
- Related: [@haste-health/generated-ops](https://www.npmjs.com/package/@haste-health/generated-ops) for typed operations
|
|
94
|
+
- Rust equivalent: [haste-fhir-client](https://crates.io/crates/haste-fhir-client)
|
|
202
95
|
|
|
203
|
-
|
|
204
|
-
resourceType: "OperationDefinition",
|
|
205
|
-
name: "test",
|
|
206
|
-
status: "draft",
|
|
207
|
-
kind: "operation",
|
|
208
|
-
code: "my-operation",
|
|
209
|
-
system: false,
|
|
210
|
-
instance: false,
|
|
211
|
-
type: false,
|
|
212
|
-
parameter: [],
|
|
213
|
-
};
|
|
214
|
-
const response = await client.create({}, R4, operationDefinition);
|
|
215
|
-
expect(response).toMatchObject({
|
|
216
|
-
resourceType: "OperationDefinition",
|
|
217
|
-
name: "test",
|
|
218
|
-
status: "draft",
|
|
219
|
-
kind: "operation",
|
|
220
|
-
code: "my-operation",
|
|
221
|
-
system: false,
|
|
222
|
-
instance: false,
|
|
223
|
-
type: false,
|
|
224
|
-
parameter: [],
|
|
225
|
-
});
|
|
226
|
-
|
|
227
|
-
await client.delete({}, R4, "OperationDefinition", response.id as string);
|
|
228
|
-
```
|
|
96
|
+
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/client",
|
|
3
|
-
"version": "0.127.
|
|
3
|
+
"version": "0.127.2",
|
|
4
4
|
"homepage": "https://haste.health",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -27,11 +27,11 @@
|
|
|
27
27
|
"jest": "^29.7.0",
|
|
28
28
|
"ts-jest": "^29.4.11",
|
|
29
29
|
"typescript": "6.0.3",
|
|
30
|
-
"@haste-health/fhir-types": "^0.127.
|
|
30
|
+
"@haste-health/fhir-types": "^0.127.2"
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
|
-
"@haste-health/operation-execution": "^0.127.
|
|
34
|
-
"@haste-health/operation-outcomes": "^0.127.
|
|
33
|
+
"@haste-health/operation-execution": "^0.127.2",
|
|
34
|
+
"@haste-health/operation-outcomes": "^0.127.2"
|
|
35
35
|
},
|
|
36
36
|
"files": [
|
|
37
37
|
"lib/**",
|