@highalch/story 0.0.0 → 0.0.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.
@@ -0,0 +1,599 @@
1
+ import * as Model from "@alchemy.run/domain/Model";
2
+ import { Cause, Context, Data, Effect, Layer, Option, Stream } from "effect";
3
+ import * as HighAlch from "@highalch/db";
4
+ import { Retry, Settings, Settled, TaggedFailure } from "@highalch/db";
5
+ import { CollectionStatus, DbClient, HealthNode, Transaction } from "@tanstack/db";
6
+ import { Answer, Input, Row, Rows, Timers, Wait } from "@highalch/db/internal";
7
+ import * as Domain from "@alchemy.run/domain";
8
+ import { RpcClientError } from "effect/rpc/RpcClientError";
9
+ import * as Aggregate from "@alchemy.run/domain/Aggregate";
10
+ import { Step } from "@alchemy.run/domain/Story";
11
+ /** The Api client of an Api, as its `Client` service yields it. */
12
+ type ClientOf<A extends Domain.Api.Any> = A["Client"] extends Context.Service<infer _Identifier, infer Client> ? Client : never;
13
+ /**
14
+ * Where a story's Domain runs. `client(scope)` is the Api client a reader of `scope` uses (the
15
+ * story wraps it for its own clients, and uses it unwrapped as "another client"). The rest is
16
+ * optional: `idle` (the server has nothing queued), `seed` (history for `given`), `send` (a
17
+ * command as another writer, for `remote(ref, command)`: its failure, if any) and `service` (a
18
+ * service of the host, for `check`).
19
+ */
20
+ type Host<A extends Domain.Api.Any> = {
21
+ readonly api: A;
22
+ readonly client: (scope: string) => Promise<ClientOf<A>>;
23
+ readonly idle?: () => Promise<boolean>;
24
+ readonly seed?: (ref: Aggregate.Ref, events: ReadonlyArray<TaggedFailure>) => Promise<void>;
25
+ readonly send?: (ref: Aggregate.Ref, command: TaggedFailure, commandId: string) => Promise<Option.Option<string>>;
26
+ readonly service?: <I, S>(key: Context.Key<I, S>) => Promise<S>;
27
+ readonly dispose: () => Promise<void>;
28
+ };
29
+ /** Builds a fresh host for each story. */
30
+ type Hosting<A extends Domain.Api.Any> = () => Promise<Host<A>>;
31
+ /**
32
+ * The services an Api's in-process client needs besides the model: its middleware (a reader's
33
+ * session) and their clients.
34
+ */
35
+ type SessionOf<A extends Domain.Api.Any> = A extends {
36
+ readonly layerClientInProcess: Layer.Layer<infer _Out, infer _E, infer In>;
37
+ } ? Exclude<In, Model.Internals> : never;
38
+ /**
39
+ * How to host an Api's model in memory: its handlers and projections (`layer`, as the model's
40
+ * `layer` takes them), the services they share with the story (`services`: stores a `check` step
41
+ * reads with `world.host.service(Tag)`), and the session a reader of a scope runs with when the
42
+ * Api's reads are guarded. Both are functions: each story builds them afresh.
43
+ */
44
+ type Memory<A extends Domain.Api.Any, Out, E, R, S> = {
45
+ readonly api: A;
46
+ readonly layer: () => Layer.Layer<Out, E, R>;
47
+ readonly services?: () => Layer.Layer<S>;
48
+ readonly session?: (scope: string) => Layer.Layer<SessionOf<A>>;
49
+ };
50
+ /**
51
+ * Hosts an Api's model on alchemy's in-memory platform, as the story runs it: projections and
52
+ * policies run in the background (not alchemy's manual scheduling, since the client runs
53
+ * concurrently), `given` seeds history through the model's stores exactly as alchemy's own `Story`
54
+ * does, and `idle` is the platform's own quiescence.
55
+ */
56
+ declare const memory: <A extends Domain.Api.Any, Out, E, R, S>(options: Memory<A, Out, E, R, S>) => Hosting<A>;
57
+ /** A fresh transport failure, as the websocket protocol reports giving up. */
58
+ declare const transport: (message?: string) => RpcClientError;
59
+ /** A command one of the story's clients sent: its name, target and input. */
60
+ type Sent = {
61
+ readonly name: string;
62
+ readonly target: string;
63
+ readonly input: Input;
64
+ };
65
+ /** A command or query of an Api client. */
66
+ type Call = (...args: ReadonlyArray<never>) => Effect.Effect<Answer | null, TaggedFailure>;
67
+ /** A stream's latest entry, as `peek` answers it. */
68
+ type Latest = {
69
+ readonly envelope: {
70
+ readonly seq: number;
71
+ };
72
+ };
73
+ /** A served stream of an Api client: its latest entry, and its entries after a cursor. */
74
+ type Feed = {
75
+ readonly peek: (key: string, ...rest: ReadonlyArray<never>) => Effect.Effect<Latest | null, TaggedFailure>;
76
+ readonly events: (key: string, options: {
77
+ readonly after: number;
78
+ }) => Stream.Stream<Answer, TaggedFailure>;
79
+ };
80
+ /** An Api client's endpoints by name: methods (commands, queries) and served streams. */
81
+ type Endpoints = Readonly<Record<string, Call | Feed>>;
82
+ /**
83
+ * The faults and counts of one client's connection. The story's client of a scope talks to the
84
+ * Domain through it: it counts requests in flight (so the story knows when the network is quiet),
85
+ * records sent commands, and injects the world's events: a dropped feed (`drop`/`resume`), a
86
+ * feed that delivers nothing (`mute`), a failing query or command (`fail`/`recover`) and held
87
+ * answers (`hold`/`release`, a query answers with what it saw when asked, later).
88
+ */
89
+ declare class Wire {
90
+ /** Requests running and not held. */
91
+ inflight: number;
92
+ /** Feed connections open now. */
93
+ open: number;
94
+ /** Feed connections made. */
95
+ connections: number;
96
+ /** Commands sent, in order. */
97
+ readonly sent: Array<Sent>;
98
+ /** Queries asked, by name, in order. */
99
+ readonly asked: Array<string>;
100
+ private down;
101
+ /** Whether the feed delivers nothing now (`mute`). */
102
+ muted: boolean;
103
+ /** Whether the feed was ever muted: the entries it dropped are lost to this connection. */
104
+ lossy: boolean;
105
+ /** Closed while the story is not letting time pass: command replies wait at it. */
106
+ private network;
107
+ private readonly cuts;
108
+ private readonly failing;
109
+ private gate;
110
+ /** Whether the feed is held down (`drop` without `resume`). */
111
+ get dropped(): boolean;
112
+ /** Fails every open feed with `error`; reconnections fail too until `resume`. */
113
+ drop: (error?: RpcClientError) => void;
114
+ /** Lets feeds connect again. */
115
+ resume: () => void;
116
+ /** Drops feed entries (a feed that stays connected and delivers nothing) while on. */
117
+ mute: (on: boolean) => void;
118
+ /** The endpoint `name` fails with `error`, `times` times (or until `recover`). */
119
+ fail: (name: string, error: TaggedFailure, times?: number) => void;
120
+ recover: (name: string) => void;
121
+ /**
122
+ * Lets replies through (the story is settling) or holds them again (`flow(false)`): a command's
123
+ * reply reaches the client only while the story lets time pass, so the steps between `when`
124
+ * and the next settling step see the optimistic rows whatever the server already did.
125
+ */
126
+ flow: (on: boolean) => void;
127
+ /** Holds every query's answer until `release`. */
128
+ hold: () => void;
129
+ release: () => void;
130
+ /** Waits, uncounted, at a gate (if it is closed now). */
131
+ private waitAt;
132
+ /**
133
+ * Counts a request while it runs; a held query's answer (read when asked) waits for `release`,
134
+ * a command's reply waits until the story lets time pass. Fails it when the story says so.
135
+ */
136
+ private counted;
137
+ private feed;
138
+ /** Wraps an Api client's endpoints: every endpoint goes through this wire. */
139
+ wrap: (endpoints: Endpoints, queries: ReadonlySet<string>) => Endpoints;
140
+ }
141
+ /**
142
+ * The clock a story's clients schedule their waits on (retries, reload debounces, settle
143
+ * timeouts). `manual`: nothing fires until the story advances it, so a story decides when a retry
144
+ * or a timeout happens. `real`: the global `setTimeout`, with the waits still tracked so the story
145
+ * knows when something is about to happen.
146
+ */
147
+ declare class Clock {
148
+ readonly mode: "manual" | "real";
149
+ now: number;
150
+ private sequence;
151
+ private readonly pending;
152
+ constructor(mode: "manual" | "real");
153
+ /** The `timers` a client is given. */
154
+ readonly timers: Timers;
155
+ /** Whether a wait of one of these kinds is scheduled. */
156
+ waiting: (...waits: ReadonlyArray<Wait>) => boolean;
157
+ /** The scheduled waits, soonest first (then in the order they were scheduled). */
158
+ scheduled: () => {
159
+ at: number;
160
+ wait: Wait;
161
+ }[];
162
+ /** Fires the soonest wait due by `until` (of the given kinds, if any); whether one fired. */
163
+ fireNext: (until: number, waits?: ReadonlyArray<Wait>) => boolean;
164
+ }
165
+ /** A row as a story compares it: its fields, without TanStack DB's virtual `$` fields. */
166
+ type Plain = Readonly<Record<string, Field>>;
167
+ /** A field of a row (any value, or nothing). */
168
+ type Field = Answer | null | undefined;
169
+ /** A row a collection shows: its fields, and whether a local transaction is pending on it. */
170
+ type Shown = {
171
+ readonly row: Plain;
172
+ readonly pending: boolean;
173
+ };
174
+ /** One change a story observed in a collection: the row of `key` after it (`None`: it left). */
175
+ type Observation = {
176
+ /** The world's observation counter when it happened. */
177
+ readonly tick: number;
178
+ /** The step that was running. */
179
+ readonly step: number;
180
+ readonly key: string;
181
+ readonly shown: Option.Option<Shown>;
182
+ };
183
+ /** Removes TanStack DB's virtual fields. */
184
+ declare const plain: (row: Row) => Plain;
185
+ /** A row as stable JSON (fields sorted), for comparisons. */
186
+ declare const json: <V>(value: V) => string;
187
+ /** A source a consumer passes to `useLiveQuery`: a collection descriptor. */
188
+ type Source$1<Row extends object = object> = HighAlch.Source<Row>;
189
+ /** One change of a collection, as a story reads it (with TanStack DB's virtual fields). */
190
+ type Change = {
191
+ readonly type: string;
192
+ readonly key: string | number;
193
+ readonly value: object & {
194
+ readonly $hasPendingWrites?: boolean;
195
+ };
196
+ };
197
+ /** What a story reads of a collection: its id, state, rows and changes; `reload` for `retry`. */
198
+ type Watched = {
199
+ readonly id: string;
200
+ readonly status: CollectionStatus;
201
+ readonly health: HealthNode;
202
+ readonly values: () => Iterable<object>;
203
+ readonly reload: () => Promise<void>;
204
+ readonly subscribeChanges: (callback: (changes: ReadonlyArray<Change>) => void, options: {
205
+ readonly includeInitialState: boolean;
206
+ }) => {
207
+ readonly unsubscribe: () => void;
208
+ };
209
+ };
210
+ /**
211
+ * One source a story's client materialised and keeps observed, as a mounted `useLiveQuery`
212
+ * would: its rows now (with their pending flag) and every change it showed.
213
+ */
214
+ declare class Observed {
215
+ readonly world: World;
216
+ readonly scope: string;
217
+ readonly label: string;
218
+ readonly collection: Watched;
219
+ readonly rows: Map<string, Shown>;
220
+ readonly history: Array<Observation>;
221
+ private readonly subscription;
222
+ constructor(world: World, scope: string, label: string, collection: Watched);
223
+ get id(): string;
224
+ /** The entity whose subset this is, when it is one (a `HighAlch.query` result is not). */
225
+ entity: () => Option.Option<Rows.Any>;
226
+ /** The rows now, by key. */
227
+ sorted: () => [string, Shown][];
228
+ /**
229
+ * The source's read state as `match` reads a stock live query result over it: `Loading`,
230
+ * `Retrying`, `Ready`, `Missing` (with `single`), or the typed error.
231
+ */
232
+ state: (single?: boolean) => TaggedFailure;
233
+ close: () => void;
234
+ }
235
+ /**
236
+ * How a command of a story ended: still `Pending`; `Committed` (its `Settled` value when the call
237
+ * reported one) or `Unconfirmed`; `Rejected` with its typed error; or `Died` with a defect.
238
+ */
239
+ type Outcome = Data.TaggedEnum<{
240
+ Pending: {};
241
+ Committed: {
242
+ readonly value: Option.Option<Settled<Reply>>;
243
+ };
244
+ Unconfirmed: {
245
+ readonly value: Settled<Reply>;
246
+ };
247
+ Rejected: {
248
+ readonly error: TaggedFailure;
249
+ };
250
+ Died: {
251
+ readonly cause: Cause.Cause<never>;
252
+ };
253
+ }>;
254
+ declare const Outcome: Data.TaggedEnum.Constructor<{
255
+ readonly _tag: "Committed";
256
+ readonly value: Option.Option<Settled<Reply>>;
257
+ } | {
258
+ readonly _tag: "Died";
259
+ readonly cause: Cause.Cause<never>;
260
+ } | {
261
+ readonly _tag: "Pending";
262
+ } | {
263
+ readonly _tag: "Rejected";
264
+ readonly error: TaggedFailure;
265
+ } | {
266
+ readonly _tag: "Unconfirmed";
267
+ readonly value: Settled<Reply>;
268
+ }>;
269
+ /** What a command replies, as a story holds it. */
270
+ type Reply = Answer | void;
271
+ /** A declared `HighAlch` command, as a story holds it (to compare it with what a machine ran). */
272
+ interface Declared {}
273
+ /** A command one of the story's clients ran (a `when` step, or one a machine invoked). */
274
+ type Run = {
275
+ readonly label: string;
276
+ readonly scope: string;
277
+ /** What ran it: the story itself or a machine. */
278
+ readonly by: string;
279
+ /** The key of the row it addresses (empty for a command with no rows). */
280
+ readonly key: string;
281
+ readonly transaction: Transaction;
282
+ /** The command it called, when a step or machine called a declared command. */
283
+ readonly command: Option.Option<Declared>;
284
+ readonly input: Input;
285
+ readonly tick: number;
286
+ readonly step: number;
287
+ /** What every observed source of its client showed for each key just before it ran. */
288
+ readonly before: ReadonlyMap<string, ReadonlyMap<string, Shown>>;
289
+ outcome: Outcome;
290
+ /** The tick it ended at. */
291
+ ended: number;
292
+ readonly done: Promise<void>;
293
+ };
294
+ /** One entry of a feed, as a story reads the feed to judge what its clients showed. */
295
+ type Entry = {
296
+ readonly seq: number;
297
+ readonly commandId: string;
298
+ readonly entity: string;
299
+ readonly key: string;
300
+ /** The row after it, decoded by its entity's schema (`None`: removed). */
301
+ readonly row: Option.Option<Plain>;
302
+ };
303
+ /** One client of a story: an account's `DbClient`, its wire, and the sources it observes. */
304
+ type Client = {
305
+ readonly scope: string;
306
+ readonly db: DbClient;
307
+ readonly wire: Wire;
308
+ readonly observed: Map<string, Observed>;
309
+ };
310
+ /** What a story's clients are, besides how they reach the Api. */
311
+ type Options = Partial<Omit<Settings, "scope" | "timers">> & {
312
+ /** The clock retries, reload debounces and settle timeouts wait on (default `manual`). */
313
+ readonly clock?: "manual" | "real";
314
+ };
315
+ /** Retries transport failures (every 100 ms on the story's clock); stops for anything else. */
316
+ declare const retryTransport: Retry;
317
+ /** A value a kind of step keeps on a story's stage (a machine's snapshot or actor). */
318
+ interface Slot {}
319
+ /**
320
+ * Everything one story run holds: its host, its clients (one per scope), the clock they wait on,
321
+ * the commands they ran and every row state they showed. Steps act on it; `check` steps and
322
+ * invariants read it. Nothing is global: a story builds its own world and disposes it.
323
+ */
324
+ declare class World<A extends Domain.Api.Any = Domain.Api.Any> {
325
+ readonly host: Host<A>;
326
+ readonly home: string;
327
+ readonly options: Options;
328
+ /** The observation counter. */
329
+ tick: number;
330
+ /** The step running now (from 1). */
331
+ step: number;
332
+ /** The tick at which the world last settled. */
333
+ settled: number;
334
+ readonly clock: Clock;
335
+ readonly runs: Array<Run>;
336
+ private readonly clients;
337
+ private readonly raws;
338
+ /** Releases of clients `activate`d by steps, run when the story ends. */
339
+ readonly releases: Array<() => void>;
340
+ /** Extra conditions for quiet, from extensions (a running machine). */
341
+ readonly quiet: Array<() => boolean>;
342
+ private readonly queries;
343
+ /** The scope steps act as now: the story's first scope, or the one an `as` step names. */
344
+ scope: string;
345
+ constructor(host: Host<A>, home: string, options: Options);
346
+ next: () => number;
347
+ /** The Api client a reader of `scope` uses, unwrapped: "another client". */
348
+ raw: (scope: string) => Promise<Readonly<Record<string, ((...args: ReadonlyArray<never>) => Effect.Effect<Answer | null, TaggedFailure>) | Feed>>>;
349
+ /** Opens the client of `scope`. */
350
+ connect: (scope?: string) => Promise<Client>;
351
+ /** The client of `scope`; it must have been opened. */
352
+ client: (scope?: string) => Client;
353
+ /** Every client opened so far. */
354
+ all: () => Client[];
355
+ /** Every source observed so far, in every client. */
356
+ observed: () => Observed[];
357
+ /** Materialises a source in the client of `scope` and keeps it observed. */
358
+ observe: <Row extends object>(source: Source$1<Row>, scope?: string) => Promise<{
359
+ observed: Observed;
360
+ opened: boolean;
361
+ }>;
362
+ /** Runs one command on the client of `scope` and records it; returns the record. */
363
+ start: (label: string, scope: string, by: string, input: Input, call: (db: DbClient, onCommitted: (value: Settled<Reply>) => void) => Transaction, command?: Option.Option<Declared>) => Promise<Run>;
364
+ /**
365
+ * The feed entries of every entity the clients of `scope` read, in order, with rows decoded by
366
+ * their entity's schema. Read from the Domain itself (not through the story's wire).
367
+ */
368
+ entries: (scope?: string) => Promise<ReadonlyArray<Entry>>;
369
+ /** The server's latest `seq` of a stream for a scope, read from the Domain itself. */
370
+ private cursor;
371
+ /** Why the world is not quiet now, or `None`. */
372
+ busy: () => Promise<Option.Option<string>>;
373
+ /**
374
+ * Waits until nothing more happens by itself: the server is idle, no request is in flight, every
375
+ * live feed delivered the server's latest entry, and (with the real clock) no retry or reload is
376
+ * due. Waits on the story's manual clock never fire here: `advance` fires them. Command replies
377
+ * reach the clients only while the world settles; `flow: false` waits without letting them
378
+ * through (the client and its machines catch up, the commands stay in flight).
379
+ */
380
+ settle: (flow?: boolean) => Promise<void>;
381
+ /**
382
+ * Settles, then fires the manual clock's waits due within `ms` (in time order), settling after
383
+ * each.
384
+ */
385
+ advance: (ms: number) => Promise<void>;
386
+ /**
387
+ * Closes a client. `HighAlch.close` waits until the commands it sent have settled, and a story
388
+ * holds them (replies wait at the wire, settle timeouts on the manual clock): a story that ended
389
+ * or failed with a command in flight lets its replies through and runs the clock's waits until
390
+ * the close returns, so disposing never hangs. Gives up waiting after `deadline`.
391
+ */
392
+ private close;
393
+ /** Closes every client and the host. */
394
+ dispose: () => Promise<void>;
395
+ }
396
+ /** A failed expectation inside a step: what it was about, what it expected and what it saw. */
397
+ declare class Mismatch extends Error {
398
+ readonly reason: string;
399
+ readonly detail: ReadonlyArray<string>;
400
+ constructor(reason: string, detail?: ReadonlyArray<string>);
401
+ }
402
+ /** A step that passed: its number (from 1) and label. */
403
+ type Done = {
404
+ readonly step: number;
405
+ readonly label: string;
406
+ };
407
+ /**
408
+ * One run of a story, as every step sees it: the hosted world (`None` in a hostless story), the
409
+ * number of the step running, and the state that kinds of steps keep for the length of the run
410
+ * (a machine's snapshot or its actor). A step kind interprets itself against it: data steps read
411
+ * the world through `hosted`, machine steps keep their machines in a `slot`.
412
+ */
413
+ declare class Stage {
414
+ readonly world: Option.Option<World>;
415
+ /** The story's name (`story.with({ name })`), for what a kind of step writes per story. */
416
+ readonly name: Option.Option<string>;
417
+ /** The step running now (from 1). */
418
+ step: number;
419
+ private readonly slots;
420
+ private readonly afters;
421
+ private readonly ends;
422
+ constructor(world: Option.Option<World>,
423
+ /** The story's name (`story.with({ name })`), for what a kind of step writes per story. */
424
+ name?: Option.Option<string>);
425
+ /**
426
+ * Runs `run` after every later step that passed, the registering step included, before the
427
+ * invariants (a screen captures a frame). A failure in it is that step's failure.
428
+ */
429
+ after: (run: (done: Done) => Promise<void>) => void;
430
+ /** Runs `run` when the story ends, passed or failed, before its world is disposed. */
431
+ end: (run: () => Promise<void>) => void;
432
+ /** The runner calls this after each step that passed. */
433
+ passed: (done: Done) => Promise<void>;
434
+ /** The runner calls this once when the story ends; the first failure, if any. */
435
+ close: () => Promise<Option.Option<unknown>>;
436
+ /**
437
+ * The hosted world, for a step that needs one (a data step, a running machine). In a hostless
438
+ * story it fails at once, naming the step.
439
+ */
440
+ hosted: (label: string) => World;
441
+ /** A value a step kind keeps for the length of the run, under its own private key. */
442
+ slot: <T extends Slot>(key: symbol, make: () => T) => T;
443
+ }
444
+ /**
445
+ * One step of a story: a label for its report and how it interprets itself against the story's
446
+ * run (`Stage`). Steps are plain values, and every kind carries its own interpretation: data steps
447
+ * (`step`) act on the hosted world, machine steps (`@highalch/story/xstate`) keep their
448
+ * machines on the stage, and a consumer's own kinds are built with `staged`. One runner runs them
449
+ * all, in any order.
450
+ */
451
+ type Step$1 = {
452
+ readonly label: string;
453
+ readonly run: (stage: Stage) => Promise<void>;
454
+ };
455
+ /** A step, or a list of them (helpers may return several). */
456
+ type Steps = Step$1 | ReadonlyArray<Steps>;
457
+ /**
458
+ * Builds a data step: it acts on (or checks) the hosted world. In a hostless story it fails at
459
+ * once, naming the step.
460
+ */
461
+ declare const step: (label: string, run: (world: World) => Promise<void>) => Step$1;
462
+ /**
463
+ * Builds a step of any kind from the stage: `stage.world` (the hosted world, `None` in a hostless
464
+ * story), `stage.hosted(label)` (the world, or a failure naming the step) and `stage.slot(key)`
465
+ * (state the kind keeps for the run). The machine steps are built so.
466
+ */
467
+ declare const staged: (label: string, run: (stage: Stage) => Promise<void>) => Step$1;
468
+ /** Every state one key showed in an observed source, in order: `a → b (pending) → -`. */
469
+ declare const historyOf: (observed: Observed, key: string, fields?: ReadonlyArray<string>) => string;
470
+ /** The rows a source shows, as `shows` compares them: by key, with `$hasPendingWrites`. */
471
+ type ShownRow<Row> = Row & {
472
+ readonly $hasPendingWrites: boolean;
473
+ };
474
+ /** What a `shows` step expects: rows by key order (each compared partially), or a predicate. */
475
+ type Expected<Row> = ReadonlyArray<Partial<Row> & {
476
+ readonly $hasPendingWrites?: boolean;
477
+ }> | ((rows: ReadonlyArray<ShownRow<Row>>) => boolean);
478
+ /** Which client a step acts as, and the source's label in reports. */
479
+ type Scoped = {
480
+ readonly as?: string;
481
+ };
482
+ /**
483
+ * Seeds history: events committed on an aggregate before the story continues, as alchemy's
484
+ * `Story.given(ref, ...events)` does (through the model's stores; they reach projections and so
485
+ * the row feed, but no policy). Then the world settles. Needs a host that can seed (`memory`).
486
+ */
487
+ declare const given: <A extends Aggregate.Any>(ref: Aggregate.Ref<A>, ...events: ReadonlyArray<Aggregate.EventOf<A>>) => Step$1;
488
+ /**
489
+ * Another client writes: a Domain command sent outside the story's clients, either to an
490
+ * aggregate (`remote(ref, command)`, as alchemy's `Story.when`; needs a host that can send) or
491
+ * through the Api client of the step's scope (`remote(label, (api) => api.RenameNote(...))`).
492
+ * It must be accepted; then the world settles.
493
+ */
494
+ declare function remote<A extends Aggregate.Any>(ref: Aggregate.Ref<A>, command: Aggregate.CommandOf<A> & TaggedFailure): Step$1;
495
+ declare function remote<C, E>(label: string, send: (api: C) => Effect.Effect<Answer | void, E>): Step$1;
496
+ /** Materialises a source in the step's client and keeps it observed (`settle: false`: as is). */
497
+ declare const open: <Row extends object>(source: Source$1<Row>, options?: Scoped & {
498
+ readonly settle?: boolean;
499
+ }) => Step$1;
500
+ /**
501
+ * What a source shows now in the step's client, as `useLiveQuery` over it would: its rows by key
502
+ * (each compared partially; `$hasPendingWrites` names a pending row), or a predicate over them.
503
+ * A source not yet observed is opened and settled first.
504
+ */
505
+ declare const shows: <Row extends object>(source: Source$1<Row>, expected: Expected<Row>, options?: Scoped) => Step$1;
506
+ /** A read state as a `state` step names it: one of `match`'s own tags, or a typed error. */
507
+ type ReadState = "Loading" | "Retrying" | "Ready" | "Missing" | TaggedFailure;
508
+ /**
509
+ * The source's read state now, as `match` reads a `useLiveQuery` result over it (the same
510
+ * conversion): `Loading`, `Retrying`, `Ready`, `Missing` (with `single`, for a `findOne`),
511
+ * optionally with some of the state's fields (`state(list, "Retrying", { attempt: 2 })`), or the
512
+ * typed error, which compares by class and fields.
513
+ */
514
+ declare const state: <Row extends object>(source: Source$1<Row>, expected: ReadState, fields?: Plain, options?: Scoped & {
515
+ readonly single?: boolean;
516
+ }) => Step$1;
517
+ /** A command a `when` step can call: a `HighAlch` command, bound to the story's client. */
518
+ type Callable<I> = {
519
+ readonly with: (options: {
520
+ readonly client?: DbClient;
521
+ }) => (input: I, callbacks?: {
522
+ readonly onCommitted?: (value: Settled<Reply>) => void;
523
+ }) => Transaction;
524
+ };
525
+ /** What a `when(label, call)` step's call gets: the client, and `activate` for `.options`/`.paced`. */
526
+ type Acting = {
527
+ readonly client: DbClient;
528
+ /** Registers the client for commands called without one (until the story ends). */
529
+ readonly activate: () => void;
530
+ };
531
+ /**
532
+ * The client runs a command, as a component calls it: `when(notes.rename, input)` calls the
533
+ * declared command with its input on the step's client (`command.with({ client })(input)`), and
534
+ * `when(label, ({ client, activate }) => transaction)` runs anything that returns a transaction
535
+ * (`createOptimisticAction(command.options)`, `createPacedMutations({ ...command.paced })`). The
536
+ * step does not wait: the next step sees the optimistic rows; `settled`/`rejected` wait.
537
+ */
538
+ declare function when<I extends Input>(command: Callable<I> & Declared, input: I): Step$1;
539
+ declare function when(label: string, call: (acting: Acting) => Transaction): Step$1;
540
+ /**
541
+ * The last command settled (the transaction completed): as `Committed` (the feed delivered its
542
+ * change) or `Unconfirmed` (the settle timeout passed first), or either when no tag is given.
543
+ */
544
+ declare const settled: (expected?: "Committed" | "Unconfirmed") => Step$1;
545
+ /**
546
+ * The last command was rejected with this typed error: the same class (its original instance)
547
+ * with the same fields. The transaction rolled back.
548
+ */
549
+ declare const rejected: (expected: TaggedFailure) => Step$1;
550
+ /** The feed of the step's client drops (a transport failure); reconnecting fails until `resume`. */
551
+ declare const drop: (error?: import("effect/rpc/RpcClientError").RpcClientError) => Step$1;
552
+ /** The feed can connect again; its pending retries run now, and the world settles. */
553
+ declare const resume: () => Step$1;
554
+ /** The feed stays connected and delivers nothing while muted. */
555
+ declare const mute: (on?: boolean) => Step$1;
556
+ /**
557
+ * An endpoint (a query or command, by name) fails with a typed error for the step's client,
558
+ * `times` times or until `recover`.
559
+ */
560
+ declare const fail: (name: string, error: TaggedFailure, times?: number) => Step$1;
561
+ /** The endpoint answers again. */
562
+ declare const recover: (name: string) => Step$1;
563
+ /** Every query of the step's client answers with what it saw when asked, but only at `release`. */
564
+ declare const hold: () => Step$1;
565
+ declare const release: () => Step$1;
566
+ /** An entity, as `HighAlch.reload(db, Rows)` takes it. */
567
+ type Entity = {
568
+ readonly entityName: string;
569
+ };
570
+ /**
571
+ * `reload(source)` reloads a source, as the `retry` a `match` handler receives does
572
+ * (`collection.reload()`). `reload(Rows)` reloads every loaded subset of an entity in the step's
573
+ * client, as `HighAlch.reload(db, Rows)` does after a write the feed does not carry; its debounce
574
+ * (`reloadDelay`) passes, so the subsets have reloaded when the step ends.
575
+ */
576
+ declare function reload<Row extends object>(source: Source$1<Row>, options?: Scoped): Step$1;
577
+ declare function reload(entity: Entity, options?: Scoped): Step$1;
578
+ /**
579
+ * Time passes on the story's manual clock: every retry, reload debounce and settle timeout due
580
+ * within `ms` fires, in time order, the world settling after each.
581
+ */
582
+ declare const advance: (ms: number) => Step$1;
583
+ /** Waits until nothing more happens by itself (see `World.settle`). */
584
+ declare const settle: () => Step$1;
585
+ /** Waits until every command ran so far has ended, then settles. */
586
+ declare const idle: () => Step$1;
587
+ /** Any check of the world (the host's services, a client's wire, the runs); throw to fail. */
588
+ declare const check: (label: string, assert: (world: World) => Promise<void> | void) => Step$1;
589
+ /** Runs steps as the client of another scope (opened on first use): two accounts in one story. */
590
+ declare const as: (scope: string, ...steps: ReadonlyArray<Steps>) => ReadonlyArray<Step$1>;
591
+ /** Steps as one list. */
592
+ declare const flatten: (steps: ReadonlyArray<Steps>) => ReadonlyArray<Step$1>;
593
+ /**
594
+ * Alchemy's own story steps, run on the story's host: `Story.given(ref, ...events)` seeds history
595
+ * (as `given`) and `Story.when(ref, command)` is another client's write (as `remote`). Other
596
+ * alchemy steps assert server decisions only: run them with alchemy's `Story.make`.
597
+ */
598
+ declare const alchemy: (from: Step) => Step$1;
599
+ export { Hosting as $, staged as A, Options as B, release as C, settle as D, resume as E, Stage as F, World as G, Run as H, Client as I, retryTransport as J, json as K, Entry as L, step as M, when as N, settled as O, Mismatch as P, Host as Q, Observation as R, rejected as S, remote as T, Shown as U, Outcome as V, Source$1 as W, transport as X, Wire as Y, ClientOf as Z, hold as _, ShownRow as a, open as b, advance as c, check as d, Memory as et, drop as f, historyOf as g, given as h, ReadState as i, state as j, shows as k, alchemy as l, flatten as m, Callable as n, memory as nt, Step$1 as o, fail as p, plain as q, Expected as r, Steps as s, Acting as t, SessionOf as tt, as as u, idle as v, reload as w, recover as x, mute as y, Observed as z };