@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.
Files changed (2) hide show
  1. package/README.md +78 -210
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,228 +1,96 @@
1
- # HasteHealth Client
1
+ # @haste-health/client
2
2
 
3
- HTTPClient and classes + middleware to define your own clients to conform to the FHIR specification.
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
- ## Client Types
5
+ The Haste Health admin app, CLI, React components and TestScript runner all use it.
6
6
 
7
- Clients are built using middleware. To define a client you create a middleware handler and pass it in as an argument to either the SynchronousClient, AsynchronousClient constructor.
7
+ ## Install
8
8
 
9
- ## Middleware
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
- Depending on whether client is asynchronous or syncrhonous will either be the object directly or a promise resolving to this object.
13
+ ## Usage
35
14
 
36
- ### Client
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
- Constructor that allows you to create asynchronous FHIR clients.
20
+ const client = createHTTPClient({
21
+ url: "https://<host>/w/<tenant>/<project>/api/v1/fhir",
22
+ getAccessToken: async () => accessToken,
23
+ });
39
24
 
40
- ```typescript
41
- import {
42
- createMiddlewareAsync,
43
- MiddlewareAsync,
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
- return new AsynchronousClient<StateType, CTX>(
48
- initialState,
49
- createMiddlewareAsync<State, CTX>(middlewarefunctions)
30
+ const { resources, total } = await client.search_type(
31
+ {},
32
+ R4,
33
+ "Patient",
34
+ "name=Smith&_count=10",
50
35
  );
51
- ```
52
36
 
53
- ## HTTPClient
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
- ### Usage
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
- ```typescript
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
- import HTTPClient from "@haste-health/client/http";
193
- import { OperationDefinition } from "@haste-health/fhir-types/r4/types";
194
- import { R4 } from "@haste-health/fhir-types/version";
88
+ ## Links
195
89
 
196
- const client = HTTPClient({
197
- url: "FHIR_API_ROOT_URL",
198
- getAccessToken: async function () {
199
- return "API TOKEN";
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
- const operationDefinition: OperationDefinition = {
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.0",
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.0"
30
+ "@haste-health/fhir-types": "^0.127.2"
31
31
  },
32
32
  "dependencies": {
33
- "@haste-health/operation-execution": "^0.127.0",
34
- "@haste-health/operation-outcomes": "^0.127.0"
33
+ "@haste-health/operation-execution": "^0.127.2",
34
+ "@haste-health/operation-outcomes": "^0.127.2"
35
35
  },
36
36
  "files": [
37
37
  "lib/**",