@rotorsoft/act 0.35.1 → 0.35.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/dist/.tsbuildinfo +1 -0
- package/dist/@types/act.d.ts +672 -0
- package/dist/@types/act.d.ts.map +1 -0
- package/dist/@types/adapters/console-logger.d.ts +41 -0
- package/dist/@types/adapters/console-logger.d.ts.map +1 -0
- package/dist/@types/adapters/in-memory-cache.d.ts +34 -0
- package/dist/@types/adapters/in-memory-cache.d.ts.map +1 -0
- package/dist/@types/adapters/in-memory-store.d.ts +202 -0
- package/dist/@types/adapters/in-memory-store.d.ts.map +1 -0
- package/dist/@types/adapters/index.d.ts +4 -0
- package/dist/@types/adapters/index.d.ts.map +1 -0
- package/dist/@types/builders/act-builder.d.ts +160 -0
- package/dist/@types/builders/act-builder.d.ts.map +1 -0
- package/dist/@types/builders/index.d.ts +13 -0
- package/dist/@types/builders/index.d.ts.map +1 -0
- package/dist/@types/builders/projection-builder.d.ts +101 -0
- package/dist/@types/builders/projection-builder.d.ts.map +1 -0
- package/dist/@types/builders/slice-builder.d.ts +109 -0
- package/dist/@types/builders/slice-builder.d.ts.map +1 -0
- package/dist/@types/builders/state-builder.d.ts +424 -0
- package/dist/@types/builders/state-builder.d.ts.map +1 -0
- package/dist/@types/config.d.ts +119 -0
- package/dist/@types/config.d.ts.map +1 -0
- package/dist/@types/index.d.ts +14 -0
- package/dist/@types/index.d.ts.map +1 -0
- package/dist/@types/internal/build-classify.d.ts +44 -0
- package/dist/@types/internal/build-classify.d.ts.map +1 -0
- package/dist/@types/internal/close-cycle.d.ts +38 -0
- package/dist/@types/internal/close-cycle.d.ts.map +1 -0
- package/dist/@types/internal/correlate-cycle.d.ts +78 -0
- package/dist/@types/internal/correlate-cycle.d.ts.map +1 -0
- package/dist/@types/internal/drain-cycle.d.ts +113 -0
- package/dist/@types/internal/drain-cycle.d.ts.map +1 -0
- package/dist/@types/internal/drain-ratio.d.ts +26 -0
- package/dist/@types/internal/drain-ratio.d.ts.map +1 -0
- package/dist/@types/internal/drain.d.ts +41 -0
- package/dist/@types/internal/drain.d.ts.map +1 -0
- package/dist/@types/internal/event-sourcing.d.ts +96 -0
- package/dist/@types/internal/event-sourcing.d.ts.map +1 -0
- package/dist/@types/internal/index.d.ts +29 -0
- package/dist/@types/internal/index.d.ts.map +1 -0
- package/dist/@types/internal/merge.d.ts +31 -0
- package/dist/@types/internal/merge.d.ts.map +1 -0
- package/dist/@types/internal/reactions.d.ts +54 -0
- package/dist/@types/internal/reactions.d.ts.map +1 -0
- package/dist/@types/internal/settle.d.ts +60 -0
- package/dist/@types/internal/settle.d.ts.map +1 -0
- package/dist/@types/internal/tracing.d.ts +45 -0
- package/dist/@types/internal/tracing.d.ts.map +1 -0
- package/dist/@types/lru-map.d.ts +50 -0
- package/dist/@types/lru-map.d.ts.map +1 -0
- package/dist/@types/ports.d.ts +196 -0
- package/dist/@types/ports.d.ts.map +1 -0
- package/dist/@types/signals.d.ts +2 -0
- package/dist/@types/signals.d.ts.map +1 -0
- package/dist/@types/types/action.d.ts +444 -0
- package/dist/@types/types/action.d.ts.map +1 -0
- package/dist/@types/types/errors.d.ts +284 -0
- package/dist/@types/types/errors.d.ts.map +1 -0
- package/dist/@types/types/index.d.ts +39 -0
- package/dist/@types/types/index.d.ts.map +1 -0
- package/dist/@types/types/ports.d.ts +617 -0
- package/dist/@types/types/ports.d.ts.map +1 -0
- package/dist/@types/types/reaction.d.ts +314 -0
- package/dist/@types/types/reaction.d.ts.map +1 -0
- package/dist/@types/types/registry.d.ts +74 -0
- package/dist/@types/types/registry.d.ts.map +1 -0
- package/dist/@types/types/schemas.d.ts +117 -0
- package/dist/@types/types/schemas.d.ts.map +1 -0
- package/dist/@types/utils.d.ts +54 -0
- package/dist/@types/utils.d.ts.map +1 -0
- package/dist/chunk-AGWZY6YT.js +127 -0
- package/dist/chunk-AGWZY6YT.js.map +1 -0
- package/dist/index.cjs +3144 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.js +2975 -0
- package/dist/index.js.map +1 -0
- package/dist/types/index.cjs +166 -0
- package/dist/types/index.cjs.map +1 -0
- package/dist/types/index.js +33 -0
- package/dist/types/index.js.map +1 -0
- package/package.json +6 -2
|
@@ -0,0 +1,444 @@
|
|
|
1
|
+
import type { Patch } from "@rotorsoft/act-patch";
|
|
2
|
+
import type { ZodType, z } from "zod";
|
|
3
|
+
import type { TruncateResult } from "./ports.js";
|
|
4
|
+
import type { ActorSchema, CausationEventSchema, CommittedMetaSchema, EventMetaSchema, QuerySchema } from "./schemas.js";
|
|
5
|
+
/**
|
|
6
|
+
* @packageDocumentation
|
|
7
|
+
* @module act/types
|
|
8
|
+
* @category Types
|
|
9
|
+
* Types for actions, events, schemas, and state in the Act Framework.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Represents an actor (user or system) performing an action.
|
|
13
|
+
*
|
|
14
|
+
* Actors provide audit trail and authorization context. Every action
|
|
15
|
+
* must specify who is performing it for accountability and access control.
|
|
16
|
+
*
|
|
17
|
+
* @example User actor
|
|
18
|
+
* ```typescript
|
|
19
|
+
* const actor: Actor = {
|
|
20
|
+
* id: "user-123",
|
|
21
|
+
* name: "Alice Smith"
|
|
22
|
+
* };
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* @example System actor
|
|
26
|
+
* ```typescript
|
|
27
|
+
* const systemActor: Actor = {
|
|
28
|
+
* id: "system",
|
|
29
|
+
* name: "Background Job"
|
|
30
|
+
* };
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
export type Actor = z.infer<typeof ActorSchema>;
|
|
34
|
+
/**
|
|
35
|
+
* Target specification for action execution.
|
|
36
|
+
*
|
|
37
|
+
* Identifies which state instance (stream) should process the action
|
|
38
|
+
* and who is performing it. The target combines the stream identifier
|
|
39
|
+
* with actor context for complete audit trail.
|
|
40
|
+
*
|
|
41
|
+
* @template TActor - Actor type extending base Actor (default: Actor)
|
|
42
|
+
*
|
|
43
|
+
* @example Basic target
|
|
44
|
+
* ```typescript
|
|
45
|
+
* const target: Target = {
|
|
46
|
+
* stream: "user-123",
|
|
47
|
+
* actor: { id: "admin", name: "Admin User" }
|
|
48
|
+
* };
|
|
49
|
+
*
|
|
50
|
+
* await app.do("updateProfile", target, { email: "new@example.com" });
|
|
51
|
+
* ```
|
|
52
|
+
*
|
|
53
|
+
* @example Dynamic stream ID
|
|
54
|
+
* ```typescript
|
|
55
|
+
* const userId = "user-" + Date.now();
|
|
56
|
+
* await app.do("createUser", {
|
|
57
|
+
* stream: userId,
|
|
58
|
+
* actor: currentUser
|
|
59
|
+
* }, userData);
|
|
60
|
+
* ```
|
|
61
|
+
*/
|
|
62
|
+
export type Target<TActor extends Actor = Actor> = {
|
|
63
|
+
readonly stream: string;
|
|
64
|
+
readonly actor: TActor;
|
|
65
|
+
readonly expectedVersion?: number;
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* Metadata describing the causation of an event.
|
|
69
|
+
*/
|
|
70
|
+
export type CausationEvent = z.infer<typeof CausationEventSchema>;
|
|
71
|
+
/**
|
|
72
|
+
* Metadata attached to an event, including correlation and causation.
|
|
73
|
+
*/
|
|
74
|
+
export type EventMeta = z.infer<typeof EventMetaSchema>;
|
|
75
|
+
/**
|
|
76
|
+
* Metadata attached to a committed event, including id, stream, version, and creation time.
|
|
77
|
+
*/
|
|
78
|
+
export type CommittedMeta = z.infer<typeof CommittedMetaSchema>;
|
|
79
|
+
/**
|
|
80
|
+
* Query options for event store queries.
|
|
81
|
+
*
|
|
82
|
+
* @property `stream?` - Filter by stream name (regex match by default)
|
|
83
|
+
* @property `stream_exact?` - When true, match stream name exactly instead of regex (used by load)
|
|
84
|
+
* @property `names?` - Filter by event names
|
|
85
|
+
* @property `before?` - Filter events before this id
|
|
86
|
+
* @property `after?` - Filter events after this id
|
|
87
|
+
* @property `limit?` - Limit the number of events to return
|
|
88
|
+
* @property `created_before?` - Filter events created before this date/time
|
|
89
|
+
* @property `created_after?` - Filter events created after this date/time
|
|
90
|
+
* @property `backward?` - Order descending when true
|
|
91
|
+
* @property `correlation?` - Filter by correlation
|
|
92
|
+
* @property `with_snaps?` - Include snapshots in the results, defaults to false
|
|
93
|
+
*/
|
|
94
|
+
export type Query = z.infer<typeof QuerySchema>;
|
|
95
|
+
/**
|
|
96
|
+
* Time-travel options for `load()`.
|
|
97
|
+
* Filters events by position or timestamp, bypassing cache and snapshots.
|
|
98
|
+
*/
|
|
99
|
+
export type AsOf = Pick<Query, "before" | "created_before" | "created_after" | "limit">;
|
|
100
|
+
/**
|
|
101
|
+
* A generic schema definition (plain object shape).
|
|
102
|
+
*/
|
|
103
|
+
export type Schema = Record<string, any>;
|
|
104
|
+
/**
|
|
105
|
+
* A map of named schemas.
|
|
106
|
+
*/
|
|
107
|
+
export type Schemas = Record<string, Schema>;
|
|
108
|
+
/**
|
|
109
|
+
* An empty schema (no properties).
|
|
110
|
+
*/
|
|
111
|
+
export type EmptySchema = Record<string, never>;
|
|
112
|
+
/**
|
|
113
|
+
* Maps schema names to their Zod type representations.
|
|
114
|
+
* @template T - The schemas map.
|
|
115
|
+
*/
|
|
116
|
+
export type ZodTypes<T extends Schemas> = {
|
|
117
|
+
[K in keyof T]: ZodType<T[K]>;
|
|
118
|
+
};
|
|
119
|
+
/**
|
|
120
|
+
* Represents a message (event or action) with a name and data payload.
|
|
121
|
+
*
|
|
122
|
+
* Messages are the basic building blocks of the event log. Each message
|
|
123
|
+
* has a name (event type) and data (event payload).
|
|
124
|
+
*
|
|
125
|
+
* @template TEvents - Schemas map
|
|
126
|
+
* @template TKey - Event/action name
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```typescript
|
|
130
|
+
* const message: Message<{ Incremented: { amount: number } }, "Incremented"> = {
|
|
131
|
+
* name: "Incremented",
|
|
132
|
+
* data: { amount: 5 }
|
|
133
|
+
* };
|
|
134
|
+
* ```
|
|
135
|
+
*/
|
|
136
|
+
export type Message<TEvents extends Schemas, TKey extends keyof TEvents> = {
|
|
137
|
+
/** The event or action name */
|
|
138
|
+
readonly name: TKey;
|
|
139
|
+
/** The event or action payload */
|
|
140
|
+
readonly data: Readonly<TEvents[TKey]>;
|
|
141
|
+
};
|
|
142
|
+
/**
|
|
143
|
+
* A committed event with complete metadata.
|
|
144
|
+
*
|
|
145
|
+
* Committed events include the message data plus metadata about when and how
|
|
146
|
+
* the event was created, including correlation and causation information for
|
|
147
|
+
* tracing event-driven workflows.
|
|
148
|
+
*
|
|
149
|
+
* @template TEvents - Schemas map
|
|
150
|
+
* @template TKey - Event name
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```typescript
|
|
154
|
+
* // Committed events include:
|
|
155
|
+
* // - id: global sequence number
|
|
156
|
+
* // - stream: which state instance
|
|
157
|
+
* // - version: event number within stream
|
|
158
|
+
* // - created: timestamp
|
|
159
|
+
* // - meta: correlation and causation
|
|
160
|
+
*
|
|
161
|
+
* app.on("committed", (snapshots) => {
|
|
162
|
+
* snapshots.forEach(snap => {
|
|
163
|
+
* if (snap.event) {
|
|
164
|
+
* console.log(`Event ${snap.event.name} #${snap.event.id}`);
|
|
165
|
+
* console.log(`Stream: ${snap.event.stream} v${snap.event.version}`);
|
|
166
|
+
* console.log(`Data:`, snap.event.data);
|
|
167
|
+
* }
|
|
168
|
+
* });
|
|
169
|
+
* });
|
|
170
|
+
* ```
|
|
171
|
+
*
|
|
172
|
+
* @see {@link CommittedMeta} for metadata structure
|
|
173
|
+
*/
|
|
174
|
+
export type Committed<TEvents extends Schemas, TKey extends keyof TEvents> = Message<TEvents, TKey> & CommittedMeta;
|
|
175
|
+
/**
|
|
176
|
+
* Snapshot of state at a specific point in time.
|
|
177
|
+
*
|
|
178
|
+
* Snapshots represent the current state after applying events. They include
|
|
179
|
+
* metadata about how many events have been applied (patches) and how many
|
|
180
|
+
* snapshots have been taken for optimization.
|
|
181
|
+
*
|
|
182
|
+
* @template TState - State schema
|
|
183
|
+
* @template TEvents - Event schemas
|
|
184
|
+
*
|
|
185
|
+
* @example
|
|
186
|
+
* ```typescript
|
|
187
|
+
* const snapshot = await app.load(Counter, "counter-1");
|
|
188
|
+
*
|
|
189
|
+
* console.log(snapshot.state); // { count: 42 }
|
|
190
|
+
* console.log(snapshot.patches); // 8 (events since last snapshot)
|
|
191
|
+
* console.log(snapshot.snaps); // 1 (1 snapshot taken)
|
|
192
|
+
* console.log(snapshot.event); // Last event that created this snapshot
|
|
193
|
+
* ```
|
|
194
|
+
*
|
|
195
|
+
* @example Using snapshot in action handler
|
|
196
|
+
* ```typescript
|
|
197
|
+
* .on({ increment: z.object({ by: z.number() }) })
|
|
198
|
+
* .emit((action, snapshot) => {
|
|
199
|
+
* console.log("Current count:", snapshot.state.count);
|
|
200
|
+
* console.log("Events applied:", snapshot.patches);
|
|
201
|
+
* return ["Incremented", { amount: action.by }];
|
|
202
|
+
* })
|
|
203
|
+
* ```
|
|
204
|
+
*/
|
|
205
|
+
export type Snapshot<TState extends Schema, TEvents extends Schemas> = {
|
|
206
|
+
/** Current state data */
|
|
207
|
+
readonly state: TState;
|
|
208
|
+
/** Event that created this snapshot (undefined for initial state) */
|
|
209
|
+
readonly event?: Committed<TEvents, keyof TEvents>;
|
|
210
|
+
/**
|
|
211
|
+
* Stream head version (sequence number of the last event in the
|
|
212
|
+
* stream). `-1` for a brand-new stream with no events. Always defined
|
|
213
|
+
* — populated from the cache on hit-with-no-new-events, from the last
|
|
214
|
+
* replayed event on cache miss, or from the just-committed event on
|
|
215
|
+
* snapshots returned by `action()`. Use this instead of
|
|
216
|
+
* `event?.version` when you need the version even after a cache hit
|
|
217
|
+
* skipped the event replay entirely.
|
|
218
|
+
*/
|
|
219
|
+
readonly version: number;
|
|
220
|
+
/** Number of patches applied since last snapshot */
|
|
221
|
+
readonly patches: number;
|
|
222
|
+
/** Number of snapshots taken for this stream */
|
|
223
|
+
readonly snaps: number;
|
|
224
|
+
/** Domain patch applied by this event (undefined for initial/loaded state) */
|
|
225
|
+
readonly patch?: Readonly<Patch<TState>>;
|
|
226
|
+
/**
|
|
227
|
+
* `true` when the state was reconstructed from a cached checkpoint
|
|
228
|
+
* (skipping full event replay). Set by `load()`; propagated unchanged
|
|
229
|
+
* to every snapshot `action()` returns since they all derive from the
|
|
230
|
+
* same initial load. Always `false` for time-travel loads, which
|
|
231
|
+
* bypass the cache by design.
|
|
232
|
+
*/
|
|
233
|
+
readonly cache_hit: boolean;
|
|
234
|
+
/**
|
|
235
|
+
* Number of events processed by the `load()` call that produced this
|
|
236
|
+
* snapshot — counts every snap and patch event applied past the cache
|
|
237
|
+
* point. `0` after a cache hit with no new events; equals the event
|
|
238
|
+
* count from snap/start after a cache miss. Distinct from `patches`,
|
|
239
|
+
* which is the snap-distance accumulator used by snap policies.
|
|
240
|
+
* Propagated unchanged by `action()`.
|
|
241
|
+
*/
|
|
242
|
+
readonly replayed: number;
|
|
243
|
+
};
|
|
244
|
+
/**
|
|
245
|
+
* An invariant is a condition that must always hold true for a state.
|
|
246
|
+
* @template TState - State schema.
|
|
247
|
+
* @template TActor - Actor type extending base Actor.
|
|
248
|
+
*/
|
|
249
|
+
export type Invariant<TState extends Schema, TActor extends Actor = Actor> = {
|
|
250
|
+
description: string;
|
|
251
|
+
valid: (state: Readonly<TState>, actor?: TActor) => boolean;
|
|
252
|
+
};
|
|
253
|
+
/**
|
|
254
|
+
* Represents an emitted event tuple from an action handler.
|
|
255
|
+
* @template TEvents - Event schemas.
|
|
256
|
+
*/
|
|
257
|
+
export type Emitted<TEvents extends Schemas> = {
|
|
258
|
+
[TKey in keyof TEvents]: readonly [TKey, Readonly<TEvents[TKey]>];
|
|
259
|
+
}[keyof TEvents];
|
|
260
|
+
/**
|
|
261
|
+
* Bundles the Zod types for state, events, and actions.
|
|
262
|
+
* @template TState - State schema.
|
|
263
|
+
* @template TEvents - Event schemas.
|
|
264
|
+
* @template TActions - Action schemas.
|
|
265
|
+
*/
|
|
266
|
+
export type StateSchemas<TState extends Schema, TEvents extends Schemas, TActions extends Schemas> = {
|
|
267
|
+
readonly events: ZodTypes<TEvents>;
|
|
268
|
+
readonly actions: ZodTypes<TActions>;
|
|
269
|
+
readonly state: ZodType<TState>;
|
|
270
|
+
};
|
|
271
|
+
/**
|
|
272
|
+
* Handles patching state in response to a committed event.
|
|
273
|
+
* @template TState - State schema.
|
|
274
|
+
* @template TEvents - Event schemas.
|
|
275
|
+
* @template TKey - Event name.
|
|
276
|
+
*/
|
|
277
|
+
export type PatchHandler<TState extends Schema, TEvents extends Schemas, TKey extends keyof TEvents> = (event: Committed<TEvents, TKey>, state: Readonly<TState>) => Readonly<Patch<TState>>;
|
|
278
|
+
/**
|
|
279
|
+
* Maps event names to their patch handlers.
|
|
280
|
+
* @template TState - State schema.
|
|
281
|
+
* @template TEvents - Event schemas.
|
|
282
|
+
*/
|
|
283
|
+
export type PatchHandlers<TState extends Schema, TEvents extends Schemas> = {
|
|
284
|
+
[TKey in keyof TEvents]: PatchHandler<TState, TEvents, TKey>;
|
|
285
|
+
};
|
|
286
|
+
/**
|
|
287
|
+
* Internal marker for the framework-default passthrough reducer
|
|
288
|
+
* (`({ data }) => data`). Custom user-supplied reducers never carry this
|
|
289
|
+
* flag. The builder merger uses it to resolve patch conflicts between
|
|
290
|
+
* partial states: a passthrough always yields to a custom reducer.
|
|
291
|
+
*
|
|
292
|
+
* @internal
|
|
293
|
+
*/
|
|
294
|
+
export type PassthroughPatchHandler = ((event: {
|
|
295
|
+
data: unknown;
|
|
296
|
+
}) => unknown) & {
|
|
297
|
+
readonly _passthrough: true;
|
|
298
|
+
};
|
|
299
|
+
/**
|
|
300
|
+
* Handles an action, producing one or more emitted events.
|
|
301
|
+
* @template TState - State schema.
|
|
302
|
+
* @template TEvents - Event schemas.
|
|
303
|
+
* @template TActions - Action schemas.
|
|
304
|
+
* @template TKey - Action name.
|
|
305
|
+
*/
|
|
306
|
+
export type ActionHandler<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TKey extends keyof TActions> = (action: Readonly<TActions[TKey]>, snapshot: Readonly<Snapshot<TState, TEvents>>, target: Target) => Emitted<TEvents> | Emitted<TEvents>[] | undefined;
|
|
307
|
+
/**
|
|
308
|
+
* Maps action names to their handlers.
|
|
309
|
+
* @template TState - State schema.
|
|
310
|
+
* @template TEvents - Event schemas.
|
|
311
|
+
* @template TActions - Action schemas.
|
|
312
|
+
*/
|
|
313
|
+
export type ActionHandlers<TState extends Schema, TEvents extends Schemas, TActions extends Schemas> = {
|
|
314
|
+
[TKey in keyof TActions]: ActionHandler<TState, TEvents, TActions, TKey>;
|
|
315
|
+
};
|
|
316
|
+
/**
|
|
317
|
+
* Maps action names to invariants that must hold after the action.
|
|
318
|
+
* @template TState - State schema.
|
|
319
|
+
* @template TActions - Action schemas.
|
|
320
|
+
*/
|
|
321
|
+
export type GivenHandlers<TState extends Schema, TActions extends Schemas> = {
|
|
322
|
+
[TKey in keyof TActions]?: Invariant<TState>[];
|
|
323
|
+
};
|
|
324
|
+
/**
|
|
325
|
+
* The full state definition, including schemas, handlers, and optional invariants and snapshot logic.
|
|
326
|
+
* @template TState - State schema.
|
|
327
|
+
* @template TEvents - Event schemas.
|
|
328
|
+
* @template TActions - Action schemas.
|
|
329
|
+
* @template TName - State name literal.
|
|
330
|
+
*/
|
|
331
|
+
export type State<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TName extends string = string> = StateSchemas<TState, TEvents, TActions> & {
|
|
332
|
+
name: TName;
|
|
333
|
+
init: () => Readonly<TState>;
|
|
334
|
+
patch: PatchHandlers<TState, TEvents>;
|
|
335
|
+
on: ActionHandlers<TState, TEvents, TActions>;
|
|
336
|
+
given?: GivenHandlers<TState, TActions>;
|
|
337
|
+
snap?: (snapshot: Snapshot<TState, TEvents>) => boolean;
|
|
338
|
+
};
|
|
339
|
+
/**
|
|
340
|
+
* Extracts the raw action schemas from a State definition.
|
|
341
|
+
*
|
|
342
|
+
* Use this to recover the `TActions` type parameter from a built State object,
|
|
343
|
+
* enabling construction of typed dispatchers without circular imports.
|
|
344
|
+
*
|
|
345
|
+
* @template T - A State object (or any object with `readonly actions: ZodTypes<TActions>`)
|
|
346
|
+
*
|
|
347
|
+
* @example
|
|
348
|
+
* ```typescript
|
|
349
|
+
* type Actions = InferActions<typeof Counter>;
|
|
350
|
+
* // => { increment: { by: number } }
|
|
351
|
+
* ```
|
|
352
|
+
*/
|
|
353
|
+
export type InferActions<T extends {
|
|
354
|
+
readonly actions: Record<string, ZodType>;
|
|
355
|
+
}> = {
|
|
356
|
+
[K in keyof T["actions"]]: T["actions"][K] extends ZodType<infer V> ? V : never;
|
|
357
|
+
};
|
|
358
|
+
/**
|
|
359
|
+
* Extracts the raw event schemas from a State definition.
|
|
360
|
+
*
|
|
361
|
+
* Use this to recover the `TEvents` type parameter from a built State object,
|
|
362
|
+
* enabling typed event handling without repeating the mapped type boilerplate.
|
|
363
|
+
*
|
|
364
|
+
* @template T - A State object (or any object with `readonly events: ZodTypes<TEvents>`)
|
|
365
|
+
*
|
|
366
|
+
* @example
|
|
367
|
+
* ```typescript
|
|
368
|
+
* type Events = InferEvents<typeof Counter>;
|
|
369
|
+
* // => { Incremented: { amount: number } }
|
|
370
|
+
* ```
|
|
371
|
+
*/
|
|
372
|
+
export type InferEvents<T extends {
|
|
373
|
+
readonly events: Record<string, ZodType>;
|
|
374
|
+
}> = {
|
|
375
|
+
[K in keyof T["events"]]: T["events"][K] extends ZodType<infer V> ? V : never;
|
|
376
|
+
};
|
|
377
|
+
/**
|
|
378
|
+
* Per-stream options for the archive-and-truncate (or restart-with-
|
|
379
|
+
* snapshot) operation.
|
|
380
|
+
*
|
|
381
|
+
* @see {@link IAct.close} for the close-the-books API
|
|
382
|
+
*/
|
|
383
|
+
export type CloseTarget = {
|
|
384
|
+
/** Stream name to close */
|
|
385
|
+
readonly stream: string;
|
|
386
|
+
/** When true, restart with a `__snapshot__` of the final state.
|
|
387
|
+
* When false/omitted, permanently close with a `__tombstone__`. */
|
|
388
|
+
readonly restart?: boolean;
|
|
389
|
+
/** Called before truncation while the stream is guarded (no concurrent writes).
|
|
390
|
+
* Use `app.query()` or `app.query_array()` inside for pagination.
|
|
391
|
+
* If it throws, the stream remains guarded but is not truncated. */
|
|
392
|
+
readonly archive?: () => Promise<void>;
|
|
393
|
+
};
|
|
394
|
+
/**
|
|
395
|
+
* Result of a close operation — per-stream truncate outcomes plus the
|
|
396
|
+
* names of any streams that were skipped (concurrent writes, pending
|
|
397
|
+
* reactions).
|
|
398
|
+
*
|
|
399
|
+
* @see {@link IAct.close} for the close-the-books API
|
|
400
|
+
*/
|
|
401
|
+
export type CloseResult = {
|
|
402
|
+
/** Per-stream truncate results (deleted count + committed event) */
|
|
403
|
+
readonly truncated: TruncateResult;
|
|
404
|
+
/** Streams skipped due to pending reactions or concurrent writes */
|
|
405
|
+
readonly skipped: string[];
|
|
406
|
+
};
|
|
407
|
+
/**
|
|
408
|
+
* Public interface for the Act orchestrator, passed to reaction handlers.
|
|
409
|
+
*
|
|
410
|
+
* Provides typed access to action dispatch, state loading, and event querying.
|
|
411
|
+
* Construct with {@link InferActions} and {@link InferEvents} to avoid circular
|
|
412
|
+
* imports between slice files and the bootstrap module.
|
|
413
|
+
*
|
|
414
|
+
* @template TEvents - Event schemas
|
|
415
|
+
* @template TActions - Action schemas (maps action names to payload types)
|
|
416
|
+
* @template TActor - Actor type extending base Actor
|
|
417
|
+
*
|
|
418
|
+
* @example
|
|
419
|
+
* ```typescript
|
|
420
|
+
* import type { IAct, InferActions, InferEvents } from "@rotorsoft/act";
|
|
421
|
+
*
|
|
422
|
+
* type App = IAct<
|
|
423
|
+
* InferEvents<typeof StateA> & InferEvents<typeof StateB>,
|
|
424
|
+
* InferActions<typeof StateA> & InferActions<typeof StateB>
|
|
425
|
+
* >;
|
|
426
|
+
*
|
|
427
|
+
* async function myReaction(event: ..., stream: string, app: App) {
|
|
428
|
+
* await app.do("someAction", target, payload, event);
|
|
429
|
+
* const snapshot = await app.load(MyState, "stream-1");
|
|
430
|
+
* const events = await app.query_array({ stream: "stream-1" });
|
|
431
|
+
* }
|
|
432
|
+
* ```
|
|
433
|
+
*/
|
|
434
|
+
export interface IAct<TEvents extends Schemas = Schemas, TActions extends Schemas = Schemas, TActor extends Actor = Actor> {
|
|
435
|
+
do<TKey extends keyof TActions & string>(action: TKey, target: Target<TActor>, payload: Readonly<TActions[TKey]>, reactingTo?: Committed<Schemas, string>, skipValidation?: boolean): Promise<Snapshot<any, any>[]>;
|
|
436
|
+
load(state: State<any, any, any> | string, stream: string, callback?: (snapshot: Snapshot<any, any>) => void, asOf?: AsOf): Promise<Snapshot<any, any>>;
|
|
437
|
+
query(query: Query, callback?: (event: Committed<TEvents, keyof TEvents>) => void): Promise<{
|
|
438
|
+
first?: Committed<TEvents, keyof TEvents>;
|
|
439
|
+
last?: Committed<TEvents, keyof TEvents>;
|
|
440
|
+
count: number;
|
|
441
|
+
}>;
|
|
442
|
+
query_array(query: Query): Promise<Committed<TEvents, keyof TEvents>[]>;
|
|
443
|
+
}
|
|
444
|
+
//# sourceMappingURL=action.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/types/action.ts"],"names":[],"mappings":"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"}
|