@rotorsoft/act 0.6.28 → 0.6.29
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 -1
- package/dist/@types/act-builder.d.ts +286 -41
- package/dist/@types/act-builder.d.ts.map +1 -1
- package/dist/@types/act.d.ts +354 -52
- package/dist/@types/act.d.ts.map +1 -1
- package/dist/@types/adapters/InMemoryStore.d.ts +59 -8
- package/dist/@types/adapters/InMemoryStore.d.ts.map +1 -1
- package/dist/@types/config.d.ts +54 -6
- package/dist/@types/config.d.ts.map +1 -1
- package/dist/@types/ports.d.ts +149 -10
- package/dist/@types/ports.d.ts.map +1 -1
- package/dist/@types/state-builder.d.ts +318 -43
- package/dist/@types/state-builder.d.ts.map +1 -1
- package/dist/@types/types/action.d.ts +122 -10
- package/dist/@types/types/action.d.ts.map +1 -1
- package/dist/@types/types/errors.d.ts +211 -22
- package/dist/@types/types/errors.d.ts.map +1 -1
- package/dist/@types/types/ports.d.ts +204 -28
- package/dist/@types/types/ports.d.ts.map +1 -1
- package/dist/@types/types/reaction.d.ts +107 -18
- package/dist/@types/types/reaction.d.ts.map +1 -1
- package/dist/@types/utils.d.ts +378 -27
- package/dist/@types/utils.d.ts.map +1 -1
- package/dist/index.cjs +352 -50
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +352 -50
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -18,58 +18,234 @@ export type Disposable = {
|
|
|
18
18
|
dispose: Disposer;
|
|
19
19
|
};
|
|
20
20
|
/**
|
|
21
|
-
* Interface for
|
|
22
|
-
*
|
|
21
|
+
* Interface for event store implementations.
|
|
22
|
+
*
|
|
23
|
+
* The Store interface defines the contract for persistence adapters in Act.
|
|
24
|
+
* Implementations must provide event storage, querying, and distributed processing
|
|
25
|
+
* capabilities through leasing and watermark tracking.
|
|
26
|
+
*
|
|
27
|
+
* Act includes two built-in implementations:
|
|
28
|
+
* - **InMemoryStore**: For development and testing
|
|
29
|
+
* - **PostgresStore**: For production use with PostgreSQL
|
|
30
|
+
*
|
|
31
|
+
* Custom stores can be implemented for other databases or event log systems.
|
|
32
|
+
*
|
|
33
|
+
* @example Using a custom store
|
|
34
|
+
* ```typescript
|
|
35
|
+
* import { store } from "@rotorsoft/act";
|
|
36
|
+
* import { PostgresStore } from "@rotorsoft/act-pg";
|
|
37
|
+
*
|
|
38
|
+
* // Replace the default in-memory store
|
|
39
|
+
* store(new PostgresStore({
|
|
40
|
+
* host: "localhost",
|
|
41
|
+
* port: 5432,
|
|
42
|
+
* database: "myapp",
|
|
43
|
+
* user: "postgres",
|
|
44
|
+
* password: "secret"
|
|
45
|
+
* }));
|
|
46
|
+
*
|
|
47
|
+
* const app = act()
|
|
48
|
+
* .with(Counter)
|
|
49
|
+
* .build();
|
|
50
|
+
* ```
|
|
51
|
+
*
|
|
52
|
+
* @see {@link InMemoryStore} for the default implementation
|
|
53
|
+
* @see {@link PostgresStore} for the PostgreSQL implementation
|
|
23
54
|
*/
|
|
24
55
|
export interface Store extends Disposable {
|
|
25
56
|
/**
|
|
26
|
-
*
|
|
57
|
+
* Initializes or resets the store.
|
|
58
|
+
*
|
|
59
|
+
* Used primarily for testing to ensure a clean state between tests.
|
|
60
|
+
* For production stores, this might create necessary tables or indexes.
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```typescript
|
|
64
|
+
* // Reset store between tests
|
|
65
|
+
* beforeEach(async () => {
|
|
66
|
+
* await store().seed();
|
|
67
|
+
* });
|
|
68
|
+
* ```
|
|
27
69
|
*/
|
|
28
70
|
seed: () => Promise<void>;
|
|
29
71
|
/**
|
|
30
|
-
*
|
|
72
|
+
* Drops all data from the store.
|
|
73
|
+
*
|
|
74
|
+
* Dangerous operation that deletes all events and state. Use with extreme caution,
|
|
75
|
+
* primarily for testing or development environments.
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```typescript
|
|
79
|
+
* // Clean up after tests
|
|
80
|
+
* afterAll(async () => {
|
|
81
|
+
* await store().drop();
|
|
82
|
+
* });
|
|
83
|
+
* ```
|
|
31
84
|
*/
|
|
32
85
|
drop: () => Promise<void>;
|
|
33
86
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
87
|
+
* Commits one or more events to a stream atomically.
|
|
88
|
+
*
|
|
89
|
+
* This is the core method for persisting events. It must:
|
|
90
|
+
* - Assign global sequence IDs to events
|
|
91
|
+
* - Increment the stream version
|
|
92
|
+
* - Check optimistic concurrency if expectedVersion is provided
|
|
93
|
+
* - Store events atomically (all or nothing)
|
|
94
|
+
* - Attach metadata (id, stream, version, created timestamp)
|
|
95
|
+
*
|
|
96
|
+
* @template E - Event schemas
|
|
97
|
+
* @param stream - The stream ID to commit to
|
|
98
|
+
* @param msgs - Array of messages (events) to commit
|
|
99
|
+
* @param meta - Event metadata (correlation, causation)
|
|
100
|
+
* @param expectedVersion - Expected current version for optimistic concurrency
|
|
101
|
+
* @returns Array of committed events with full metadata
|
|
102
|
+
*
|
|
103
|
+
* @throws {ConcurrencyError} If expectedVersion doesn't match current version
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* ```typescript
|
|
107
|
+
* const events = await store().commit(
|
|
108
|
+
* "user-123",
|
|
109
|
+
* [{ name: "UserCreated", data: { email: "user@example.com" } }],
|
|
110
|
+
* { correlation: "req-456", causation: { action: {...} } },
|
|
111
|
+
* 0 // Expect version 0 (new stream)
|
|
112
|
+
* );
|
|
113
|
+
* ```
|
|
41
114
|
*/
|
|
42
115
|
commit: <E extends Schemas>(stream: string, msgs: Message<E, keyof E>[], meta: EventMeta, expectedVersion?: number) => Promise<Committed<E, keyof E>[]>;
|
|
43
116
|
/**
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
117
|
+
* Queries events from the store with optional filtering.
|
|
118
|
+
*
|
|
119
|
+
* Calls the callback for each matching event. The callback approach allows
|
|
120
|
+
* processing large result sets without loading everything into memory.
|
|
121
|
+
*
|
|
122
|
+
* @template E - Event schemas
|
|
123
|
+
* @param callback - Function invoked for each matching event
|
|
124
|
+
* @param query - Optional filter criteria
|
|
125
|
+
* @param query.stream - Filter by stream ID
|
|
126
|
+
* @param query.name - Filter by event name
|
|
127
|
+
* @param query.after - Return events after this ID
|
|
128
|
+
* @param query.before - Return events before this ID
|
|
129
|
+
* @param query.limit - Maximum number of events to return
|
|
130
|
+
* @returns Total number of events processed
|
|
131
|
+
*
|
|
132
|
+
* @example Query all events for a stream
|
|
133
|
+
* ```typescript
|
|
134
|
+
* let count = 0;
|
|
135
|
+
* await store().query(
|
|
136
|
+
* (event) => {
|
|
137
|
+
* console.log(event.name, event.data);
|
|
138
|
+
* count++;
|
|
139
|
+
* },
|
|
140
|
+
* { stream: "user-123" }
|
|
141
|
+
* );
|
|
142
|
+
* console.log(`Found ${count} events`);
|
|
143
|
+
* ```
|
|
48
144
|
*/
|
|
49
145
|
query: <E extends Schemas>(callback: (event: Committed<E, keyof E>) => void, query?: Query) => Promise<number>;
|
|
50
146
|
/**
|
|
51
|
-
* Polls
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
147
|
+
* Polls for streams that need reaction processing.
|
|
148
|
+
*
|
|
149
|
+
* Returns streams that have uncommitted events, ordered by their watermark.
|
|
150
|
+
* Uses a dual-frontier approach:
|
|
151
|
+
* - **Lagging**: New or behind streams (ascending watermark)
|
|
152
|
+
* - **Leading**: Active streams (descending watermark)
|
|
153
|
+
*
|
|
154
|
+
* Only returns unblocked streams that aren't currently leased.
|
|
155
|
+
*
|
|
156
|
+
* @param lagging - Max streams to return from lagging frontier
|
|
157
|
+
* @param leading - Max streams to return from leading frontier
|
|
158
|
+
* @returns Array of poll results with stream, source, watermark, and lag status
|
|
159
|
+
*
|
|
160
|
+
* @example
|
|
161
|
+
* ```typescript
|
|
162
|
+
* const polled = await store().poll(5, 5); // 5 lagging + 5 leading
|
|
163
|
+
* polled.forEach(({ stream, at, lagging }) => {
|
|
164
|
+
* console.log(`${stream} at ${at} (lagging: ${lagging})`);
|
|
165
|
+
* });
|
|
166
|
+
* ```
|
|
167
|
+
*
|
|
168
|
+
* @see {@link Lease} for lease management
|
|
55
169
|
*/
|
|
56
170
|
poll: (lagging: number, leading: number) => Promise<Poll[]>;
|
|
57
171
|
/**
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
172
|
+
* Acquires leases for exclusive stream processing.
|
|
173
|
+
*
|
|
174
|
+
* Leasing prevents multiple workers from processing the same stream concurrently.
|
|
175
|
+
* Only grants leases if:
|
|
176
|
+
* - Stream isn't currently leased by another worker
|
|
177
|
+
* - Lease hasn't expired
|
|
178
|
+
* - Stream isn't blocked due to errors
|
|
179
|
+
*
|
|
180
|
+
* @param leases - Array of lease requests
|
|
181
|
+
* @param millis - Lease duration in milliseconds
|
|
182
|
+
* @returns Array of successfully granted leases
|
|
183
|
+
*
|
|
184
|
+
* @example
|
|
185
|
+
* ```typescript
|
|
186
|
+
* const granted = await store().lease([
|
|
187
|
+
* { stream: "user-123", by: workerId, at: 0, retry: 0, lagging: false }
|
|
188
|
+
* ], 10000); // 10 second lease
|
|
189
|
+
*
|
|
190
|
+
* if (granted.length > 0) {
|
|
191
|
+
* // Process events...
|
|
192
|
+
* await store().ack(granted);
|
|
193
|
+
* }
|
|
194
|
+
* ```
|
|
195
|
+
*
|
|
196
|
+
* @see {@link poll} for finding streams to lease
|
|
197
|
+
* @see {@link ack} for acknowledging completion
|
|
62
198
|
*/
|
|
63
199
|
lease: (leases: Lease[], millis: number) => Promise<Lease[]>;
|
|
64
200
|
/**
|
|
65
|
-
*
|
|
66
|
-
*
|
|
201
|
+
* Acknowledges successful processing of leased streams.
|
|
202
|
+
*
|
|
203
|
+
* Updates the watermark to indicate events have been processed successfully.
|
|
204
|
+
* Releases the lease so other workers can process subsequent events.
|
|
205
|
+
*
|
|
206
|
+
* @param leases - Leases to acknowledge with updated watermarks
|
|
207
|
+
* @returns Acknowledged leases
|
|
208
|
+
*
|
|
209
|
+
* @example
|
|
210
|
+
* ```typescript
|
|
211
|
+
* const leased = await store().lease([...], 10000);
|
|
212
|
+
* // Process events up to ID 150
|
|
213
|
+
* await store().ack(leased.map(l => ({ ...l, at: 150 })));
|
|
214
|
+
* ```
|
|
215
|
+
*
|
|
216
|
+
* @see {@link lease} for acquiring leases
|
|
67
217
|
*/
|
|
68
218
|
ack: (leases: Lease[]) => Promise<Lease[]>;
|
|
69
219
|
/**
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
* @
|
|
220
|
+
* Blocks streams after persistent processing failures.
|
|
221
|
+
*
|
|
222
|
+
* Blocked streams won't be returned by {@link poll} until manually unblocked.
|
|
223
|
+
* This prevents poison messages from repeatedly failing and consuming resources.
|
|
224
|
+
*
|
|
225
|
+
* Streams are typically blocked when:
|
|
226
|
+
* - Max retries reached
|
|
227
|
+
* - `blockOnError` option is true
|
|
228
|
+
* - Handler throws an error
|
|
229
|
+
*
|
|
230
|
+
* @param leases - Leases to block with error messages
|
|
231
|
+
* @returns Blocked leases
|
|
232
|
+
*
|
|
233
|
+
* @example
|
|
234
|
+
* ```typescript
|
|
235
|
+
* try {
|
|
236
|
+
* await processEvents(lease);
|
|
237
|
+
* await store().ack([lease]);
|
|
238
|
+
* } catch (error) {
|
|
239
|
+
* if (lease.retry >= 3) {
|
|
240
|
+
* await store().block([{
|
|
241
|
+
* ...lease,
|
|
242
|
+
* error: error.message
|
|
243
|
+
* }]);
|
|
244
|
+
* }
|
|
245
|
+
* }
|
|
246
|
+
* ```
|
|
247
|
+
*
|
|
248
|
+
* @see {@link lease} for lease management
|
|
73
249
|
*/
|
|
74
250
|
block: (leases: Array<Lease & {
|
|
75
251
|
error: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../src/types/ports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,OAAO,EACP,KAAK,EACL,OAAO,EACR,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE/C
|
|
1
|
+
{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../src/types/ports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,OAAO,EACP,KAAK,EACL,OAAO,EACR,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,KAAM,SAAQ,UAAU;IACvC;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,EAAE,CAAC,CAAC,SAAS,OAAO,EACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAC3B,IAAI,EAAE,SAAS,EACf,eAAe,CAAC,EAAE,MAAM,KACrB,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,EAAE,CAAC,CAAC,SAAS,OAAO,EACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,EAChD,KAAK,CAAC,EAAE,KAAK,KACV,OAAO,CAAC,MAAM,CAAC,CAAC;IAErB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE7D;;;;;;;;;;;;;;;;;OAiBG;IACH,GAAG,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,KAAK,EAAE,CACL,MAAM,EAAE,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,KACrC,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CAChD"}
|
|
@@ -6,20 +6,81 @@
|
|
|
6
6
|
*/
|
|
7
7
|
import type { Committed, Schema, Schemas, Snapshot } from "./action.js";
|
|
8
8
|
/**
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
9
|
+
* Reaction handler function that processes committed events.
|
|
10
|
+
*
|
|
11
|
+
* Reaction handlers respond to events asynchronously. They can:
|
|
12
|
+
* - Perform side effects (send emails, call APIs, log, etc.)
|
|
13
|
+
* - Return an action tuple to trigger another action
|
|
14
|
+
* - Return `void` or `undefined` for side-effect-only reactions
|
|
15
|
+
*
|
|
16
|
+
* Handlers are called during drain cycles and support automatic retries
|
|
17
|
+
* with configurable error handling.
|
|
18
|
+
*
|
|
19
|
+
* @template E - Event schemas
|
|
20
|
+
* @template K - Event name
|
|
21
|
+
* @param event - The committed event that triggered this reaction
|
|
22
|
+
* @param stream - The target stream name for this reaction
|
|
23
|
+
* @returns Promise resolving to an action tuple or void
|
|
24
|
+
*
|
|
25
|
+
* @example Side effect only
|
|
26
|
+
* ```typescript
|
|
27
|
+
* const sendEmail: ReactionHandler<Events, "UserCreated"> = async (event) => {
|
|
28
|
+
* await emailService.send(event.data.email, "Welcome!");
|
|
29
|
+
* };
|
|
30
|
+
* ```
|
|
31
|
+
*
|
|
32
|
+
* @example Triggering another action
|
|
33
|
+
* ```typescript
|
|
34
|
+
* const reduceInventory: ReactionHandler<Events, "OrderPlaced"> = async (event) => {
|
|
35
|
+
* return ["reduceStock", { amount: event.data.items.length }];
|
|
36
|
+
* };
|
|
37
|
+
* ```
|
|
38
|
+
*
|
|
39
|
+
* @see {@link Reaction} for complete reaction configuration
|
|
15
40
|
*/
|
|
16
41
|
export type ReactionHandler<E extends Schemas, K extends keyof E> = (event: Committed<E, K>, stream: string) => Promise<Snapshot<E, Schema> | void>;
|
|
17
42
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
43
|
+
* Resolver for determining which stream a reaction should target.
|
|
44
|
+
*
|
|
45
|
+
* Resolvers enable dynamic reaction routing based on event content. They can be:
|
|
46
|
+
* - **Static**: Always route to the same target stream
|
|
47
|
+
* - **Dynamic**: Determine target based on event data at runtime
|
|
48
|
+
*
|
|
49
|
+
* Resolvers can also specify source streams for optimization, allowing the drain
|
|
50
|
+
* process to efficiently fetch only relevant events.
|
|
51
|
+
*
|
|
52
|
+
* @template E - Event schemas
|
|
53
|
+
* @template K - Event name
|
|
54
|
+
* @param event - The committed event (for dynamic resolvers)
|
|
55
|
+
* @returns Target stream configuration or undefined to skip
|
|
56
|
+
*
|
|
57
|
+
* @example Static target
|
|
58
|
+
* ```typescript
|
|
59
|
+
* .on("UserCreated")
|
|
60
|
+
* .do(sendWelcomeEmail)
|
|
61
|
+
* .to("email-queue") // Static target
|
|
62
|
+
* ```
|
|
63
|
+
*
|
|
64
|
+
* @example Dynamic target per user
|
|
65
|
+
* ```typescript
|
|
66
|
+
* .on("UserLoggedIn")
|
|
67
|
+
* .do(incrementLoginCount)
|
|
68
|
+
* .to((event) => ({
|
|
69
|
+
* target: `stats-${event.stream}` // Dynamic per user
|
|
70
|
+
* }))
|
|
71
|
+
* ```
|
|
72
|
+
*
|
|
73
|
+
* @example With source optimization
|
|
74
|
+
* ```typescript
|
|
75
|
+
* .on("UserUpdated")
|
|
76
|
+
* .do(updateReadModel)
|
|
77
|
+
* .to(({ stream }) => ({
|
|
78
|
+
* source: stream, // Only fetch from this user's stream
|
|
79
|
+
* target: `cache-${stream}` // Update corresponding cache
|
|
80
|
+
* }))
|
|
81
|
+
* ```
|
|
82
|
+
*
|
|
83
|
+
* @see {@link Reaction} for complete reaction configuration
|
|
23
84
|
*/
|
|
24
85
|
export type ReactionResolver<E extends Schemas, K extends keyof E> = {
|
|
25
86
|
target: string;
|
|
@@ -93,13 +154,41 @@ export type Fetch<E extends Schemas> = Array<{
|
|
|
93
154
|
readonly events: Committed<E, keyof E>[];
|
|
94
155
|
}>;
|
|
95
156
|
/**
|
|
96
|
-
* Lease information for stream processing.
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
157
|
+
* Lease information for distributed stream processing.
|
|
158
|
+
*
|
|
159
|
+
* Leases prevent concurrent processing of the same stream by multiple workers.
|
|
160
|
+
* When a worker acquires a lease, it has exclusive rights to process events
|
|
161
|
+
* for that stream until the lease expires or is acknowledged.
|
|
162
|
+
*
|
|
163
|
+
* The drain process uses leases to:
|
|
164
|
+
* - Prevent race conditions in distributed setups
|
|
165
|
+
* - Track processing progress (watermark)
|
|
166
|
+
* - Manage retries on failures
|
|
167
|
+
* - Balance load between lagging and leading streams
|
|
168
|
+
*
|
|
169
|
+
* @property stream - The target stream name being processed
|
|
170
|
+
* @property source - Optional source stream for filtering
|
|
171
|
+
* @property at - Watermark: last successfully processed event ID
|
|
172
|
+
* @property by - Unique identifier of the lease holder (UUID)
|
|
173
|
+
* @property retry - Number of retry attempts (0 = first attempt)
|
|
174
|
+
* @property lagging - Whether this stream is behind (lagging frontier)
|
|
175
|
+
*
|
|
176
|
+
* @example
|
|
177
|
+
* ```typescript
|
|
178
|
+
* app.on("acked", (leases) => {
|
|
179
|
+
* leases.forEach(lease => {
|
|
180
|
+
* console.log(`Processed ${lease.stream} up to event ${lease.at}`);
|
|
181
|
+
* });
|
|
182
|
+
* });
|
|
183
|
+
*
|
|
184
|
+
* app.on("blocked", (blocked) => {
|
|
185
|
+
* blocked.forEach(({ stream, retry, error }) => {
|
|
186
|
+
* console.error(`Stream ${stream} blocked after ${retry} retries: ${error}`);
|
|
187
|
+
* });
|
|
188
|
+
* });
|
|
189
|
+
* ```
|
|
190
|
+
*
|
|
191
|
+
* @see {@link Drain} for drain cycle results
|
|
103
192
|
*/
|
|
104
193
|
export type Lease = {
|
|
105
194
|
readonly stream: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"reaction.d.ts","sourceRoot":"","sources":["../../../src/types/reaction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExE
|
|
1
|
+
{"version":3,"file":"reaction.d.ts","sourceRoot":"","sources":["../../../src/types/reaction.ts"],"names":[],"mappings":"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"}
|