@hecks/client 3.14.0 → 5.0.0
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 +8 -7
- package/dist/client.d.ts +6 -0
- package/dist/client.js +9 -1
- package/dist/client.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -52,7 +52,7 @@ The package is ESM and ships its type declarations.
|
|
|
52
52
|
## Use
|
|
53
53
|
|
|
54
54
|
```ts
|
|
55
|
-
import { HostClient
|
|
55
|
+
import { HostClient } from "@hecks/client";
|
|
56
56
|
|
|
57
57
|
const client = new HostClient({
|
|
58
58
|
domain: "Shop",
|
|
@@ -66,17 +66,17 @@ const answer = await client.read();
|
|
|
66
66
|
// One aggregate's states, as [id, state] pairs.
|
|
67
67
|
const events = client.instancesOf(answer, "Event").map(([id, state]) => ({
|
|
68
68
|
id,
|
|
69
|
-
name:
|
|
70
|
-
priceCents:
|
|
69
|
+
name: state.name, // a one-field value object answers bare: "Yoga"
|
|
70
|
+
priceCents: state.price, // 10800
|
|
71
71
|
}));
|
|
72
72
|
|
|
73
73
|
// A command, judged by the state that comes back.
|
|
74
74
|
const repriced = await client.apply({
|
|
75
75
|
verb: "Event.Reprice",
|
|
76
76
|
to: "yoga-1",
|
|
77
|
-
with: { price:
|
|
77
|
+
with: { price: 12000 },
|
|
78
78
|
parse: (answer) => client.instancesOf(answer, "Event"),
|
|
79
|
-
confirm: (states) => states.find(([id]) => id === "yoga-1")?.[1].price
|
|
79
|
+
confirm: (states) => states.find(([id]) => id === "yoga-1")?.[1].price === 12000,
|
|
80
80
|
});
|
|
81
81
|
```
|
|
82
82
|
|
|
@@ -92,6 +92,7 @@ const repriced = await client.apply({
|
|
|
92
92
|
| `actorId` | The Governance identity id of the signed-in person, sent as `actor_id` with every command unless a call names its own. An identified caller should pass this and leave `role` unset, so Governance's role assignments decide. The host honors `actor_id` only on its internal protocol, from its own peers. |
|
|
93
93
|
| `timeoutMs` | How long one request may take before it counts as unreachable. Defaults to `8000`. |
|
|
94
94
|
| `fetch` | The `fetch` to send requests with, for tests or a custom agent. Defaults to the global `fetch`, looked up on each call. |
|
|
95
|
+
| `bare` | Whether the host answers a value object that has one field as that field's bare value (`name: "Yoga"`, not `name: { value: "Yoga" }`). Defaults to `true`, sent as `"bare": true` on every request; `false` asks for the wrapped shape the host stores. A command takes either form. |
|
|
95
96
|
|
|
96
97
|
The environment variables are read once, when the client is constructed. A
|
|
97
98
|
missing domain or URL throws a `TypeError`.
|
|
@@ -111,8 +112,8 @@ missing domain or URL throws a `TypeError`.
|
|
|
111
112
|
Standalone readers, importable without a client:
|
|
112
113
|
|
|
113
114
|
- `instancesOf(answer, "Domain::Aggregate")`: the same lookup with the aggregate named in full.
|
|
114
|
-
- `text(raw): string | null`: a string value object's text, `null` when absent or empty.
|
|
115
|
-
- `whole(raw, key): number`: a numeric value object's number under `key` (`"value"`, `"cents"`), `0` when absent.
|
|
115
|
+
- `text(raw): string | null`: a string value object's text, bare or wrapped, `null` when absent or empty.
|
|
116
|
+
- `whole(raw, key): number`: a numeric value object's number, bare or wrapped under `key` (`"value"`, `"cents"`), `0` when absent.
|
|
116
117
|
- `optionalWhole(raw, key): number | null`: like `whole`, but `null` when the attribute was left unset.
|
|
117
118
|
- `rowsOf(answer, name?): Record<string, unknown>[] | null`: the rows a query answered, `null` when the answer has no entry for it; throws `DomainRefusal` when the host refused the question (an unknown query, or one answered outside the domain).
|
|
118
119
|
- `refusalOf(answer, verb): DomainRefusal`: the domain's own words for why a command changed nothing.
|
package/dist/client.d.ts
CHANGED
|
@@ -23,6 +23,11 @@ export interface ClientOptions {
|
|
|
23
23
|
timeoutMs?: number;
|
|
24
24
|
/** The fetch to send requests with. Defaults to the global `fetch`, looked up on each call. */
|
|
25
25
|
fetch?: typeof fetch;
|
|
26
|
+
/**
|
|
27
|
+
* Whether the host answers a single-field value object as its bare value. Defaults to true;
|
|
28
|
+
* false asks for the wrapped shape the host stores (`{ value: "x" }`, `{ cents: 900 }`).
|
|
29
|
+
*/
|
|
30
|
+
bare?: boolean;
|
|
26
31
|
}
|
|
27
32
|
/**
|
|
28
33
|
* One command whose outcome is judged from the state that comes back.
|
|
@@ -51,6 +56,7 @@ export declare class HostClient {
|
|
|
51
56
|
private readonly actorId;
|
|
52
57
|
private readonly timeoutMs;
|
|
53
58
|
private readonly fetchImpl;
|
|
59
|
+
private readonly bare;
|
|
54
60
|
constructor(options?: ClientOptions);
|
|
55
61
|
/** A name in full: one that already carries `::` is left alone, any other is placed in this client's domain. */
|
|
56
62
|
qualify(name: string): string;
|
package/dist/client.js
CHANGED
|
@@ -9,6 +9,12 @@
|
|
|
9
9
|
// "role": "Role", "actor_id": "<id>" }
|
|
10
10
|
// -> the same shape after the command ran
|
|
11
11
|
//
|
|
12
|
+
// Every request also carries `"bare": true` unless the client was built with
|
|
13
|
+
// `bare: false`: the host then answers a value object that has one field as
|
|
14
|
+
// that field's own value (`name: "Margherita"`, not `name: { value: "Margherita" }`),
|
|
15
|
+
// the same shape a command takes it in. Without it the host answers the shape
|
|
16
|
+
// it stores.
|
|
17
|
+
//
|
|
12
18
|
// The host answers HTTP 200 whether or not the domain refused, and its
|
|
13
19
|
// `refusals` list can carry entries replayed from history, so a command is
|
|
14
20
|
// judged by the state that comes back (see `HostClient#apply`), never by the
|
|
@@ -42,6 +48,7 @@ export class HostClient {
|
|
|
42
48
|
actorId;
|
|
43
49
|
timeoutMs;
|
|
44
50
|
fetchImpl;
|
|
51
|
+
bare;
|
|
45
52
|
constructor(options = {}) {
|
|
46
53
|
const domain = options.domain ?? fromEnv("HECKS_DOMAIN");
|
|
47
54
|
const url = options.url ?? fromEnv("HECKS_SERVICE_URL");
|
|
@@ -55,6 +62,7 @@ export class HostClient {
|
|
|
55
62
|
this.actorId = options.actorId;
|
|
56
63
|
this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
57
64
|
this.fetchImpl = options.fetch;
|
|
65
|
+
this.bare = options.bare ?? true;
|
|
58
66
|
}
|
|
59
67
|
/** A name in full: one that already carries `::` is left alone, any other is placed in this client's domain. */
|
|
60
68
|
qualify(name) {
|
|
@@ -110,7 +118,7 @@ export class HostClient {
|
|
|
110
118
|
res = await send(`${this.url}/dispatch`, {
|
|
111
119
|
method: "POST",
|
|
112
120
|
headers: { "Content-Type": "application/json" },
|
|
113
|
-
body: JSON.stringify(body),
|
|
121
|
+
body: JSON.stringify(this.bare ? { ...body, bare: true } : body),
|
|
114
122
|
signal: AbortSignal.timeout(this.timeoutMs),
|
|
115
123
|
});
|
|
116
124
|
}
|
package/dist/client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,mDAAmD;AACnD,EAAE;AACF,qBAAqB;AACrB,iFAAiF;AACjF,4DAA4D;AAC5D,+EAA+E;AAC/E,uEAAuE;AACvE,2CAA2C;AAC3C,8CAA8C;AAC9C,EAAE;AACF,uEAAuE;AACvE,2EAA2E;AAC3E,6EAA6E;AAC7E,cAAc;AACd,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,wEAAwE;AACxE,qEAAqE;AACrE,yCAAyC;AACzC,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,+EAA+E;AAC/E,2EAA2E;AAC3E,SAAS;AAET,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,kBAAkB,GAAG,IAAI,CAAC;
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED