@haste-health/operation-execution 0.127.1 → 0.127.3

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 +63 -1
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1 +1,63 @@
1
- # operation_execution
1
+ # @haste-health/operation-execution
2
+
3
+ Turns a FHIR [OperationDefinition](https://hl7.org/fhir/R4/operationdefinition.html) into a typed, validating operation object. An `Operation<Input, Output>` converts between the `Parameters` resource FHIR sends over the wire and a plain object keyed by parameter name, and validates both directions against the definition with [`@haste-health/fhir-validation`](https://www.npmjs.com/package/@haste-health/fhir-validation).
4
+
5
+ [`@haste-health/generated-ops`](https://www.npmjs.com/package/@haste-health/generated-ops) generates one `Operation` per OperationDefinition that Haste Health ships, and [`@haste-health/client`](https://www.npmjs.com/package/@haste-health/client) accepts any `IOperation` in `invoke_system`, `invoke_type` and `invoke_instance`, so operation calls are type-checked end to end.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @haste-health/operation-execution
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { Operation, OpCTX } from "@haste-health/operation-execution";
17
+ import type { ValueSet, uri } from "@haste-health/fhir-types/r4/types";
18
+
19
+ type Input = { url: uri; filter?: string };
20
+ type Output = ValueSet;
21
+
22
+ // valueSetExpandDefinition is the OperationDefinition resource for ValueSet/$expand.
23
+ const expand = new Operation<Input, Output>(valueSetExpandDefinition);
24
+
25
+ // Plain object -> Parameters resource, following the definition's "in" parameters.
26
+ const parameters = expand.parseToParameters("in", {
27
+ url: "http://hl7.org/fhir/ValueSet/administrative-gender" as uri,
28
+ });
29
+ // { resourceType: "Parameters", parameter: [{ name: "url", valueUri: "..." }] }
30
+
31
+ // Parameters resource -> plain object. "out" does the same for responses.
32
+ const input = expand.parseToObject("in", parameters);
33
+
34
+ // Validate input or output against the definition. Issues are OperationOutcome issues.
35
+ const issues = await expand.validate(ctx, "in", input);
36
+ ```
37
+
38
+ `ctx` is an `OpCTX`: the `ValidationCTX` of `@haste-health/fhir-validation` (`fhirVersion` and `resolveCanonical`, which looks up StructureDefinitions by URL) plus `level`, one of `"system"`, `"type"` or `"instance"`.
39
+
40
+ ## Behaviour
41
+
42
+ - Parameters with `max: "*"` become arrays, single-valued ones scalars; nested `part` parameters become nested objects.
43
+ - Resource-typed parameters (`Any`, `Resource` or a resource type) travel in `parameter.resource`; everything else in the matching `value[Type]` field.
44
+ - An operation whose only output is a required `return` resource is passed through as that resource rather than wrapped in `Parameters`, and an operation with exactly one resource input accepts that resource directly as the request body, as the FHIR specification allows.
45
+ - Unknown parameter names, missing required parameters and cardinality overflows throw an `OperationError` from [`@haste-health/operation-outcomes`](https://www.npmjs.com/package/@haste-health/operation-outcomes).
46
+
47
+ ## API
48
+
49
+ | Export | Purpose |
50
+ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
51
+ | `Operation<I, O>`, `IOperation<I, O>` | The class and the interface it implements: `code`, `operationDefinition`, `parseToObject`, `parseToParameters`, `validate` |
52
+ | `parseParameters(definition, use, parameters)`, `toParametersResource(definition, use, value)` | The converters behind `Operation`, usable on their own |
53
+ | `OPMetadata<Op>` | Extracts `{ Input, Output }` from an operation type; the client's `invoke_*` signatures are built on it |
54
+ | `Invocation`, `Executor<CTX, I, O>`, `OpCTX`, `isParameters` | Types and helpers for writing an operation handler |
55
+
56
+ ## Links
57
+
58
+ - [API reference](https://typescript.haste.health/modules/_haste-health_operation-execution.html)
59
+ - [Source](https://github.com/HasteHealth/HasteHealth/tree/main/frontend/packages/operation-execution)
60
+ - [FHIR REST API: invoking operations](https://haste.health/docs/api/rest_api/fhir/intro) and the [TypeScript SDK overview](https://haste.health/docs/api/sdks/typescript)
61
+ - Rust equivalent: [haste-fhir-ops](https://crates.io/crates/haste-fhir-ops)
62
+
63
+ 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/operation-execution",
3
- "version": "0.127.1",
3
+ "version": "0.127.3",
4
4
  "homepage": "https://haste.health",
5
5
  "repository": {
6
6
  "type": "git",
@@ -11,19 +11,19 @@
11
11
  "main": "lib/index.js",
12
12
  "types": "lib/index.d.ts",
13
13
  "dependencies": {
14
- "@haste-health/fhir-pointer": "^0.127.1",
15
- "@haste-health/fhir-types": "^0.127.1",
16
- "@haste-health/operation-outcomes": "^0.127.1",
17
- "@haste-health/fhir-validation": "^0.127.1"
14
+ "@haste-health/fhir-pointer": "^0.127.3",
15
+ "@haste-health/fhir-validation": "^0.127.3",
16
+ "@haste-health/operation-outcomes": "^0.127.3",
17
+ "@haste-health/fhir-types": "^0.127.3"
18
18
  },
19
19
  "devDependencies": {
20
20
  "@jest/globals": "^29.7.0",
21
21
  "jest": "^29.7.0",
22
22
  "ts-jest": "^29.4.11",
23
23
  "typescript": "6.0.3",
24
- "@haste-health/artifacts": "^0.127.1",
25
- "@haste-health/hl7.fhir.r4.core": "^0.127.1",
26
- "@haste-health/haste-health.fhir.r4.core": "^0.127.1"
24
+ "@haste-health/artifacts": "^0.127.3",
25
+ "@haste-health/haste-health.fhir.r4.core": "^0.127.3",
26
+ "@haste-health/hl7.fhir.r4.core": "^0.127.3"
27
27
  },
28
28
  "files": [
29
29
  "lib/**"