@rotorsoft/act 0.33.3 → 0.34.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 +26 -2
- package/package.json +1 -1
- package/dist/.tsbuildinfo +0 -1
- package/dist/@types/act.d.ts +0 -598
- package/dist/@types/act.d.ts.map +0 -1
- package/dist/@types/adapters/console-logger.d.ts +0 -41
- package/dist/@types/adapters/console-logger.d.ts.map +0 -1
- package/dist/@types/adapters/in-memory-cache.d.ts +0 -34
- package/dist/@types/adapters/in-memory-cache.d.ts.map +0 -1
- package/dist/@types/adapters/in-memory-store.d.ts +0 -181
- package/dist/@types/adapters/in-memory-store.d.ts.map +0 -1
- package/dist/@types/adapters/index.d.ts +0 -4
- package/dist/@types/adapters/index.d.ts.map +0 -1
- package/dist/@types/builders/act-builder.d.ts +0 -160
- package/dist/@types/builders/act-builder.d.ts.map +0 -1
- package/dist/@types/builders/index.d.ts +0 -13
- package/dist/@types/builders/index.d.ts.map +0 -1
- package/dist/@types/builders/projection-builder.d.ts +0 -101
- package/dist/@types/builders/projection-builder.d.ts.map +0 -1
- package/dist/@types/builders/slice-builder.d.ts +0 -109
- package/dist/@types/builders/slice-builder.d.ts.map +0 -1
- package/dist/@types/builders/state-builder.d.ts +0 -424
- package/dist/@types/builders/state-builder.d.ts.map +0 -1
- package/dist/@types/config.d.ts +0 -119
- package/dist/@types/config.d.ts.map +0 -1
- package/dist/@types/index.d.ts +0 -14
- package/dist/@types/index.d.ts.map +0 -1
- package/dist/@types/internal/build-classify.d.ts +0 -44
- package/dist/@types/internal/build-classify.d.ts.map +0 -1
- package/dist/@types/internal/close-cycle.d.ts +0 -38
- package/dist/@types/internal/close-cycle.d.ts.map +0 -1
- package/dist/@types/internal/correlate-cycle.d.ts +0 -73
- package/dist/@types/internal/correlate-cycle.d.ts.map +0 -1
- package/dist/@types/internal/drain-cycle.d.ts +0 -113
- package/dist/@types/internal/drain-cycle.d.ts.map +0 -1
- package/dist/@types/internal/drain-ratio.d.ts +0 -26
- package/dist/@types/internal/drain-ratio.d.ts.map +0 -1
- package/dist/@types/internal/drain.d.ts +0 -41
- package/dist/@types/internal/drain.d.ts.map +0 -1
- package/dist/@types/internal/event-sourcing.d.ts +0 -96
- package/dist/@types/internal/event-sourcing.d.ts.map +0 -1
- package/dist/@types/internal/index.d.ts +0 -29
- package/dist/@types/internal/index.d.ts.map +0 -1
- package/dist/@types/internal/merge.d.ts +0 -31
- package/dist/@types/internal/merge.d.ts.map +0 -1
- package/dist/@types/internal/reactions.d.ts +0 -54
- package/dist/@types/internal/reactions.d.ts.map +0 -1
- package/dist/@types/internal/settle.d.ts +0 -60
- package/dist/@types/internal/settle.d.ts.map +0 -1
- package/dist/@types/internal/tracing.d.ts +0 -45
- package/dist/@types/internal/tracing.d.ts.map +0 -1
- package/dist/@types/lru-map.d.ts +0 -50
- package/dist/@types/lru-map.d.ts.map +0 -1
- package/dist/@types/ports.d.ts +0 -196
- package/dist/@types/ports.d.ts.map +0 -1
- package/dist/@types/signals.d.ts +0 -2
- package/dist/@types/signals.d.ts.map +0 -1
- package/dist/@types/types/action.d.ts +0 -444
- package/dist/@types/types/action.d.ts.map +0 -1
- package/dist/@types/types/errors.d.ts +0 -284
- package/dist/@types/types/errors.d.ts.map +0 -1
- package/dist/@types/types/index.d.ts +0 -39
- package/dist/@types/types/index.d.ts.map +0 -1
- package/dist/@types/types/ports.d.ts +0 -485
- package/dist/@types/types/ports.d.ts.map +0 -1
- package/dist/@types/types/reaction.d.ts +0 -291
- package/dist/@types/types/reaction.d.ts.map +0 -1
- package/dist/@types/types/registry.d.ts +0 -74
- package/dist/@types/types/registry.d.ts.map +0 -1
- package/dist/@types/types/schemas.d.ts +0 -117
- package/dist/@types/types/schemas.d.ts.map +0 -1
- package/dist/@types/utils.d.ts +0 -54
- package/dist/@types/utils.d.ts.map +0 -1
- package/dist/chunk-AGWZY6YT.js +0 -127
- package/dist/chunk-AGWZY6YT.js.map +0 -1
- package/dist/index.cjs +0 -2985
- package/dist/index.cjs.map +0 -1
- package/dist/index.js +0 -2816
- package/dist/index.js.map +0 -1
- package/dist/types/index.cjs +0 -166
- package/dist/types/index.cjs.map +0 -1
- package/dist/types/index.js +0 -33
- package/dist/types/index.js.map +0 -1
|
@@ -1,485 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @packageDocumentation
|
|
3
|
-
* @module act/types
|
|
4
|
-
* @category Types
|
|
5
|
-
* Types and interfaces for event store ports and disposables in the Act Framework.
|
|
6
|
-
*/
|
|
7
|
-
import type { Committed, EventMeta, Message, Query, Schema, Schemas } from "./action.js";
|
|
8
|
-
import type { BlockedLease, Lease } from "./reaction.js";
|
|
9
|
-
/**
|
|
10
|
-
* A function that disposes of a resource asynchronously.
|
|
11
|
-
* @returns Promise that resolves when disposal is complete.
|
|
12
|
-
*/
|
|
13
|
-
export type Disposer = () => Promise<void>;
|
|
14
|
-
/**
|
|
15
|
-
* An object that can be disposed of asynchronously.
|
|
16
|
-
*/
|
|
17
|
-
export type Disposable = {
|
|
18
|
-
dispose: Disposer;
|
|
19
|
-
};
|
|
20
|
-
/**
|
|
21
|
-
* Minimal logger port compatible with pino, winston, bunyan, and console.
|
|
22
|
-
*
|
|
23
|
-
* Each log method accepts either:
|
|
24
|
-
* - `(msg: string)` — plain message
|
|
25
|
-
* - `(obj: unknown, msg?: string)` — structured data with optional message
|
|
26
|
-
*
|
|
27
|
-
* Implementations should respect `level` to gate output.
|
|
28
|
-
*
|
|
29
|
-
* @see {@link ConsoleLogger} for the default implementation
|
|
30
|
-
* @see {@link https://www.npmjs.com/package/@rotorsoft/act-pino | @rotorsoft/act-pino} for the Pino adapter
|
|
31
|
-
*/
|
|
32
|
-
export interface Logger extends Disposable {
|
|
33
|
-
level: string;
|
|
34
|
-
fatal(obj: unknown, msg?: string): void;
|
|
35
|
-
fatal(msg: string): void;
|
|
36
|
-
error(obj: unknown, msg?: string): void;
|
|
37
|
-
error(msg: string): void;
|
|
38
|
-
warn(obj: unknown, msg?: string): void;
|
|
39
|
-
warn(msg: string): void;
|
|
40
|
-
info(obj: unknown, msg?: string): void;
|
|
41
|
-
info(msg: string): void;
|
|
42
|
-
debug(obj: unknown, msg?: string): void;
|
|
43
|
-
debug(msg: string): void;
|
|
44
|
-
trace(obj: unknown, msg?: string): void;
|
|
45
|
-
trace(msg: string): void;
|
|
46
|
-
child(bindings: Record<string, unknown>): Logger;
|
|
47
|
-
}
|
|
48
|
-
/**
|
|
49
|
-
* Result of a {@link Store.truncate} operation, keyed by stream name.
|
|
50
|
-
* Each entry contains the number of deleted events and the committed
|
|
51
|
-
* seed event (snapshot or tombstone).
|
|
52
|
-
*/
|
|
53
|
-
export type TruncateResult = Map<string, {
|
|
54
|
-
deleted: number;
|
|
55
|
-
committed: Committed<Schemas, keyof Schemas>;
|
|
56
|
-
}>;
|
|
57
|
-
/**
|
|
58
|
-
* Subscription position for a registered stream.
|
|
59
|
-
*
|
|
60
|
-
* Streamed by {@link Store.query_streams} to power operational dashboards
|
|
61
|
-
* (projection lag, blocked subscriptions, in-flight leases). The shape
|
|
62
|
-
* mirrors what every adapter already tracks on its `streams` table.
|
|
63
|
-
*
|
|
64
|
-
* @property stream - The subscription target (projection or reaction stream)
|
|
65
|
-
* @property source - Optional source stream filter (for reactions)
|
|
66
|
-
* @property at - Last processed event id watermark (-1 for fresh streams)
|
|
67
|
-
* @property retry - Current retry counter
|
|
68
|
-
* @property blocked - True when the stream is blocked by a poison message
|
|
69
|
-
* @property error - Last error message (empty string when none)
|
|
70
|
-
* @property leased_by - Current lease holder UUID (when leased)
|
|
71
|
-
* @property leased_until - Lease expiration timestamp (when leased)
|
|
72
|
-
*/
|
|
73
|
-
export type StreamPosition = {
|
|
74
|
-
readonly stream: string;
|
|
75
|
-
readonly source?: string;
|
|
76
|
-
readonly at: number;
|
|
77
|
-
readonly retry: number;
|
|
78
|
-
readonly blocked: boolean;
|
|
79
|
-
readonly error: string;
|
|
80
|
-
readonly leased_by?: string;
|
|
81
|
-
readonly leased_until?: Date;
|
|
82
|
-
};
|
|
83
|
-
/**
|
|
84
|
-
* Filter options for {@link Store.query_streams}.
|
|
85
|
-
*
|
|
86
|
-
* Mirrors the {@link Query} pattern used by {@link Store.query} — pass
|
|
87
|
-
* filters server-side to keep the cost low on large tables (e.g., dynamic
|
|
88
|
-
* reactions producing one subscription per aggregate).
|
|
89
|
-
*
|
|
90
|
-
* **What the store can filter:** the columns it actually persists —
|
|
91
|
-
* `stream`, `source`, `blocked`. Higher-level classification ("is this a
|
|
92
|
-
* projection vs a reaction?", "is this a static or dynamic resolver?")
|
|
93
|
-
* is an orchestrator concern; the streams table doesn't store kinds.
|
|
94
|
-
* Layer that on top by joining results with `Act`'s built-in registry.
|
|
95
|
-
*
|
|
96
|
-
* @property stream - Stream-name filter. By default treated as a regex
|
|
97
|
-
* (PG `~`, SQLite/InMemory `LIKE`-translated). Pass `stream_exact: true`
|
|
98
|
-
* for exact string equality.
|
|
99
|
-
* @property stream_exact - Use exact match instead of pattern match for
|
|
100
|
-
* `stream`.
|
|
101
|
-
* @property source - Source-stream filter (regex by default). Useful to
|
|
102
|
-
* isolate dynamic-reaction subscriptions tied to a particular aggregate
|
|
103
|
-
* stream. Pass `source_exact: true` for exact equality.
|
|
104
|
-
* @property source_exact - Use exact match instead of pattern match for
|
|
105
|
-
* `source`.
|
|
106
|
-
* @property blocked - Restrict to blocked (`true`) or unblocked (`false`)
|
|
107
|
-
* streams. Omit for all.
|
|
108
|
-
* @property after - Keyset pagination cursor: returns only streams with
|
|
109
|
-
* `stream > after` (lexicographic). Pass the last seen `stream` to fetch
|
|
110
|
-
* the next page.
|
|
111
|
-
* @property limit - Max rows to return (default: 100).
|
|
112
|
-
*/
|
|
113
|
-
export type QueryStreams = {
|
|
114
|
-
readonly stream?: string;
|
|
115
|
-
readonly stream_exact?: boolean;
|
|
116
|
-
readonly source?: string;
|
|
117
|
-
readonly source_exact?: boolean;
|
|
118
|
-
readonly blocked?: boolean;
|
|
119
|
-
readonly after?: string;
|
|
120
|
-
readonly limit?: number;
|
|
121
|
-
};
|
|
122
|
-
/**
|
|
123
|
-
* Result of a {@link Store.query_streams} call.
|
|
124
|
-
*
|
|
125
|
-
* @property maxEventId - Highest event id in the store (-1 when empty).
|
|
126
|
-
* UI uses this to compute lag as `maxEventId - position.at`.
|
|
127
|
-
* @property count - Number of stream positions delivered to the callback.
|
|
128
|
-
*/
|
|
129
|
-
export type QueryStreamsResult = {
|
|
130
|
-
readonly maxEventId: number;
|
|
131
|
-
readonly count: number;
|
|
132
|
-
};
|
|
133
|
-
/**
|
|
134
|
-
* Interface for event store implementations.
|
|
135
|
-
*
|
|
136
|
-
* The Store interface defines the contract for persistence adapters in Act.
|
|
137
|
-
* Implementations must provide event storage, querying, and distributed processing
|
|
138
|
-
* capabilities through leasing and watermark tracking.
|
|
139
|
-
*
|
|
140
|
-
* Act includes two built-in implementations:
|
|
141
|
-
* - **InMemoryStore**: For development and testing
|
|
142
|
-
* - **PostgresStore**: For production use with PostgreSQL
|
|
143
|
-
*
|
|
144
|
-
* Custom stores can be implemented for other databases or event log systems.
|
|
145
|
-
*
|
|
146
|
-
* @example Using a custom store
|
|
147
|
-
* ```typescript
|
|
148
|
-
* import { store } from "@rotorsoft/act";
|
|
149
|
-
* import { PostgresStore } from "@rotorsoft/act-pg";
|
|
150
|
-
*
|
|
151
|
-
* // Replace the default in-memory store
|
|
152
|
-
* store(new PostgresStore({
|
|
153
|
-
* host: "localhost",
|
|
154
|
-
* port: 5432,
|
|
155
|
-
* database: "myapp",
|
|
156
|
-
* user: "postgres",
|
|
157
|
-
* password: "secret"
|
|
158
|
-
* }));
|
|
159
|
-
*
|
|
160
|
-
* const app = act()
|
|
161
|
-
* .withState(Counter)
|
|
162
|
-
* .build();
|
|
163
|
-
* ```
|
|
164
|
-
*
|
|
165
|
-
* @see {@link InMemoryStore} for the default implementation
|
|
166
|
-
* @see {@link PostgresStore} for the PostgreSQL implementation
|
|
167
|
-
*/
|
|
168
|
-
export interface Store extends Disposable {
|
|
169
|
-
/**
|
|
170
|
-
* Initializes or resets the store.
|
|
171
|
-
*
|
|
172
|
-
* Used primarily for testing to ensure a clean state between tests.
|
|
173
|
-
* For production stores, this might create necessary tables or indexes.
|
|
174
|
-
*
|
|
175
|
-
* @example
|
|
176
|
-
* ```typescript
|
|
177
|
-
* // Reset store between tests
|
|
178
|
-
* beforeEach(async () => {
|
|
179
|
-
* await store().seed();
|
|
180
|
-
* });
|
|
181
|
-
* ```
|
|
182
|
-
*/
|
|
183
|
-
seed: () => Promise<void>;
|
|
184
|
-
/**
|
|
185
|
-
* Drops all data from the store.
|
|
186
|
-
*
|
|
187
|
-
* Dangerous operation that deletes all events and state. Use with extreme caution,
|
|
188
|
-
* primarily for testing or development environments.
|
|
189
|
-
*
|
|
190
|
-
* @example
|
|
191
|
-
* ```typescript
|
|
192
|
-
* // Clean up after tests
|
|
193
|
-
* afterAll(async () => {
|
|
194
|
-
* await store().drop();
|
|
195
|
-
* });
|
|
196
|
-
* ```
|
|
197
|
-
*/
|
|
198
|
-
drop: () => Promise<void>;
|
|
199
|
-
/**
|
|
200
|
-
* Commits one or more events to a stream atomically.
|
|
201
|
-
*
|
|
202
|
-
* This is the core method for persisting events. It must:
|
|
203
|
-
* - Assign global sequence IDs to events
|
|
204
|
-
* - Increment the stream version
|
|
205
|
-
* - Check optimistic concurrency if expectedVersion is provided
|
|
206
|
-
* - Store events atomically (all or nothing)
|
|
207
|
-
* - Attach metadata (id, stream, version, created timestamp)
|
|
208
|
-
*
|
|
209
|
-
* @template E - Event schemas
|
|
210
|
-
* @param stream - The stream ID to commit to
|
|
211
|
-
* @param msgs - Array of messages (events) to commit
|
|
212
|
-
* @param meta - Event metadata (correlation, causation)
|
|
213
|
-
* @param expectedVersion - Expected current version for optimistic concurrency
|
|
214
|
-
* @returns Array of committed events with full metadata
|
|
215
|
-
*
|
|
216
|
-
* @throws {ConcurrencyError} If expectedVersion doesn't match current version
|
|
217
|
-
*
|
|
218
|
-
* @example
|
|
219
|
-
* ```typescript
|
|
220
|
-
* const events = await store().commit(
|
|
221
|
-
* "user-123",
|
|
222
|
-
* [{ name: "UserCreated", data: { email: "user@example.com" } }],
|
|
223
|
-
* { correlation: "req-456", causation: { action: {...} } },
|
|
224
|
-
* 0 // Expect version 0 (new stream)
|
|
225
|
-
* );
|
|
226
|
-
* ```
|
|
227
|
-
*/
|
|
228
|
-
commit: <E extends Schemas>(stream: string, msgs: Message<E, keyof E>[], meta: EventMeta, expectedVersion?: number) => Promise<Committed<E, keyof E>[]>;
|
|
229
|
-
/**
|
|
230
|
-
* Queries events from the store with optional filtering.
|
|
231
|
-
*
|
|
232
|
-
* Calls the callback for each matching event. The callback approach allows
|
|
233
|
-
* processing large result sets without loading everything into memory.
|
|
234
|
-
*
|
|
235
|
-
* @template E - Event schemas
|
|
236
|
-
* @param callback - Function invoked for each matching event
|
|
237
|
-
* @param query - Optional filter criteria — see {@link Query} for fields
|
|
238
|
-
* (`stream`, `name`, `after`, `before`, `created_after`, `created_before`,
|
|
239
|
-
* `limit`, `with_snaps`, `stream_exact`).
|
|
240
|
-
* @returns Total number of events processed
|
|
241
|
-
*
|
|
242
|
-
* @example Query all events for a stream
|
|
243
|
-
* ```typescript
|
|
244
|
-
* let count = 0;
|
|
245
|
-
* await store().query(
|
|
246
|
-
* (event) => {
|
|
247
|
-
* console.log(event.name, event.data);
|
|
248
|
-
* count++;
|
|
249
|
-
* },
|
|
250
|
-
* { stream: "user-123" }
|
|
251
|
-
* );
|
|
252
|
-
* console.log(`Found ${count} events`);
|
|
253
|
-
* ```
|
|
254
|
-
*/
|
|
255
|
-
query: <E extends Schemas>(callback: (event: Committed<E, keyof E>) => void, query?: Query) => Promise<number>;
|
|
256
|
-
/**
|
|
257
|
-
* Atomically discovers and leases streams for reaction processing.
|
|
258
|
-
*
|
|
259
|
-
* Atomically discovers a stream and acquires a lease in one round-trip,
|
|
260
|
-
* eliminating the race that exists when discovery and locking are separate
|
|
261
|
-
* calls (a competing worker can grab the stream between the two).
|
|
262
|
-
*
|
|
263
|
-
* PostgresStore uses `FOR UPDATE SKIP LOCKED` for zero-contention competing
|
|
264
|
-
* consumer semantics — workers never block each other, each grabbing different
|
|
265
|
-
* streams atomically. InMemoryStore fuses its poll+lease logic equivalently.
|
|
266
|
-
*
|
|
267
|
-
* Used by `Act.drain()` as the primary stream acquisition method.
|
|
268
|
-
*
|
|
269
|
-
* @param lagging - Max streams from the lagging frontier (ascending watermark)
|
|
270
|
-
* @param leading - Max streams from the leading frontier (descending watermark)
|
|
271
|
-
* @param by - Unique lease holder identifier (UUID)
|
|
272
|
-
* @param millis - Lease duration in milliseconds
|
|
273
|
-
* @returns Array of successfully leased streams with metadata
|
|
274
|
-
*
|
|
275
|
-
* @example
|
|
276
|
-
* ```typescript
|
|
277
|
-
* const leased = await store().claim(5, 5, randomUUID(), 10000);
|
|
278
|
-
* leased.forEach(({ stream, at, lagging }) => {
|
|
279
|
-
* console.log(`Leased ${stream} at ${at} (lagging: ${lagging})`);
|
|
280
|
-
* });
|
|
281
|
-
* ```
|
|
282
|
-
*
|
|
283
|
-
* @see {@link subscribe} for registering new streams (used by correlate)
|
|
284
|
-
* @see {@link ack} for acknowledging completion
|
|
285
|
-
* @see {@link block} for blocking failed streams
|
|
286
|
-
*/
|
|
287
|
-
claim: (lagging: number, leading: number, by: string, millis: number) => Promise<Lease[]>;
|
|
288
|
-
/**
|
|
289
|
-
* Registers streams for event processing.
|
|
290
|
-
*
|
|
291
|
-
* Upserts stream entries so they become visible to {@link claim}. Used by
|
|
292
|
-
* `correlate()` to register dynamically discovered reaction target streams.
|
|
293
|
-
*
|
|
294
|
-
* Also returns the current maximum watermark across all subscribed streams,
|
|
295
|
-
* used internally for correlation checkpoint initialization on cold start.
|
|
296
|
-
*
|
|
297
|
-
* @param streams - Streams to register with optional source hint
|
|
298
|
-
* @returns `subscribed` count of newly registered streams, `watermark` max `at` across all streams
|
|
299
|
-
*
|
|
300
|
-
* @example
|
|
301
|
-
* ```typescript
|
|
302
|
-
* const { subscribed, watermark } = await store().subscribe([
|
|
303
|
-
* { stream: "stats-user-1", source: "user-1" },
|
|
304
|
-
* { stream: "stats-user-2", source: "user-2" },
|
|
305
|
-
* ]);
|
|
306
|
-
* ```
|
|
307
|
-
*
|
|
308
|
-
* @see {@link claim} for discovering and leasing registered streams
|
|
309
|
-
*/
|
|
310
|
-
subscribe: (streams: Array<{
|
|
311
|
-
stream: string;
|
|
312
|
-
source?: string;
|
|
313
|
-
}>) => Promise<{
|
|
314
|
-
subscribed: number;
|
|
315
|
-
watermark: number;
|
|
316
|
-
}>;
|
|
317
|
-
/**
|
|
318
|
-
* Acknowledges successful processing of leased streams.
|
|
319
|
-
*
|
|
320
|
-
* Updates the watermark to indicate events have been processed successfully.
|
|
321
|
-
* Releases the lease so other workers can process subsequent events.
|
|
322
|
-
*
|
|
323
|
-
* @param leases - Leases to acknowledge with updated watermarks
|
|
324
|
-
* @returns Acknowledged leases
|
|
325
|
-
*
|
|
326
|
-
* @example
|
|
327
|
-
* ```typescript
|
|
328
|
-
* const leased = await store().claim(5, 5, randomUUID(), 10000);
|
|
329
|
-
* // Process events up to ID 150
|
|
330
|
-
* await store().ack(leased.map(l => ({ ...l, at: 150 })));
|
|
331
|
-
* ```
|
|
332
|
-
*
|
|
333
|
-
* @see {@link claim} for acquiring leases
|
|
334
|
-
*/
|
|
335
|
-
ack: (leases: Lease[]) => Promise<Lease[]>;
|
|
336
|
-
/**
|
|
337
|
-
* Blocks streams after persistent processing failures.
|
|
338
|
-
*
|
|
339
|
-
* Blocked streams won't be returned by {@link claim} until manually unblocked.
|
|
340
|
-
* This prevents poison messages from repeatedly failing and consuming resources.
|
|
341
|
-
*
|
|
342
|
-
* Streams are typically blocked when:
|
|
343
|
-
* - Max retries reached
|
|
344
|
-
* - `blockOnError` option is true
|
|
345
|
-
* - Handler throws an error
|
|
346
|
-
*
|
|
347
|
-
* @param leases - Leases to block with error messages
|
|
348
|
-
* @returns Blocked leases
|
|
349
|
-
*
|
|
350
|
-
* @example
|
|
351
|
-
* ```typescript
|
|
352
|
-
* try {
|
|
353
|
-
* await processEvents(lease);
|
|
354
|
-
* await store().ack([lease]);
|
|
355
|
-
* } catch (error) {
|
|
356
|
-
* if (lease.retry >= 3) {
|
|
357
|
-
* await store().block([{
|
|
358
|
-
* ...lease,
|
|
359
|
-
* error: error.message
|
|
360
|
-
* }]);
|
|
361
|
-
* }
|
|
362
|
-
* }
|
|
363
|
-
* ```
|
|
364
|
-
*
|
|
365
|
-
* @see {@link claim} for lease management
|
|
366
|
-
*/
|
|
367
|
-
block: (leases: BlockedLease[]) => Promise<BlockedLease[]>;
|
|
368
|
-
/**
|
|
369
|
-
* Resets watermarks for the given streams to -1, making them eligible
|
|
370
|
-
* for replay from the beginning. Also clears retry, blocked, error,
|
|
371
|
-
* and lease state so the streams can be claimed immediately.
|
|
372
|
-
*
|
|
373
|
-
* **Prefer `Act.reset()` over calling this directly.** This primitive
|
|
374
|
-
* only resets the store; it does not raise the orchestrator's internal
|
|
375
|
-
* "needs drain" flag, so a settled `Act` instance will short-circuit and
|
|
376
|
-
* skip the replay. `Act.reset()` wraps this and arms the flag.
|
|
377
|
-
*
|
|
378
|
-
* @param streams - Stream names to reset
|
|
379
|
-
* @returns Count of streams that were actually reset
|
|
380
|
-
*
|
|
381
|
-
* @example
|
|
382
|
-
* ```typescript
|
|
383
|
-
* // Recommended
|
|
384
|
-
* await app.reset(["my-projection"]);
|
|
385
|
-
*
|
|
386
|
-
* // Low-level (does NOT trigger replay on settled apps)
|
|
387
|
-
* await store().reset(["my-projection"]);
|
|
388
|
-
* ```
|
|
389
|
-
*
|
|
390
|
-
* @see {@link Act.reset} for the high-level rebuild API that wraps
|
|
391
|
-
* this primitive and arms the orchestrator's drain flag
|
|
392
|
-
*/
|
|
393
|
-
reset: (streams: string[]) => Promise<number>;
|
|
394
|
-
/**
|
|
395
|
-
* Atomically truncates streams and seeds each with a final event.
|
|
396
|
-
*
|
|
397
|
-
* For each target, in a single transaction:
|
|
398
|
-
* 1. Deletes all events for the stream
|
|
399
|
-
* 2. Removes the stream's entry from the streams table
|
|
400
|
-
* 3. Inserts a `__snapshot__` (when `snapshot` is provided) or
|
|
401
|
-
* `__tombstone__` event as the sole event on the stream
|
|
402
|
-
*
|
|
403
|
-
* @param targets - Streams to truncate with optional snapshot state and meta
|
|
404
|
-
* @returns Map keyed by stream name, each entry with `deleted` count and `committed` event
|
|
405
|
-
*
|
|
406
|
-
* @see {@link Act.close} for the high-level close-the-books API that
|
|
407
|
-
* orchestrates safety checks, archive callbacks, and atomic
|
|
408
|
-
* truncate+seed
|
|
409
|
-
*/
|
|
410
|
-
truncate: (targets: Array<{
|
|
411
|
-
stream: string;
|
|
412
|
-
snapshot?: Schema;
|
|
413
|
-
meta?: EventMeta;
|
|
414
|
-
}>) => Promise<TruncateResult>;
|
|
415
|
-
/**
|
|
416
|
-
* Streams registered subscription positions to a callback, plus the
|
|
417
|
-
* highest event id in the store.
|
|
418
|
-
*
|
|
419
|
-
* Read-only introspection for operational dashboards (Store /
|
|
420
|
-
* Subscriptions tab, projection lag, blocked subscriptions). Avoids
|
|
421
|
-
* forcing apps to open a second connection and run raw SQL against
|
|
422
|
-
* adapter-specific schemas.
|
|
423
|
-
*
|
|
424
|
-
* Mirrors the {@link Store.query} callback pattern: the callback is
|
|
425
|
-
* invoked once per matching position, allowing large result sets to be
|
|
426
|
-
* processed without buffering. Results are ordered by `stream` name; use
|
|
427
|
-
* `query.after` (last seen stream name) for keyset pagination on big
|
|
428
|
-
* tables (dynamic reactions can produce one subscription per aggregate).
|
|
429
|
-
*
|
|
430
|
-
* @param callback - Invoked once per matching {@link StreamPosition}.
|
|
431
|
-
* @param query - Optional {@link QueryStreams} filter (default `limit: 100`).
|
|
432
|
-
* @returns `maxEventId` and the `count` of positions emitted.
|
|
433
|
-
*
|
|
434
|
-
* @example List blocked streams with their lag
|
|
435
|
-
* ```typescript
|
|
436
|
-
* const { maxEventId } = await store().query_streams(
|
|
437
|
-
* (s) => console.log(`${s.stream}: lag=${maxEventId - s.at} ${s.error}`),
|
|
438
|
-
* { blocked: true, limit: 50 }
|
|
439
|
-
* );
|
|
440
|
-
* ```
|
|
441
|
-
*
|
|
442
|
-
* @example Page through all positions
|
|
443
|
-
* ```typescript
|
|
444
|
-
* let after: string | undefined;
|
|
445
|
-
* for (;;) {
|
|
446
|
-
* const page: StreamPosition[] = [];
|
|
447
|
-
* const { count } = await store().query_streams(
|
|
448
|
-
* (s) => page.push(s),
|
|
449
|
-
* { after, limit: 100 }
|
|
450
|
-
* );
|
|
451
|
-
* if (!count) break;
|
|
452
|
-
* // ... use page ...
|
|
453
|
-
* after = page.at(-1)?.stream;
|
|
454
|
-
* }
|
|
455
|
-
* ```
|
|
456
|
-
*/
|
|
457
|
-
query_streams: (callback: (position: StreamPosition) => void, query?: QueryStreams) => Promise<QueryStreamsResult>;
|
|
458
|
-
}
|
|
459
|
-
/**
|
|
460
|
-
* A cached snapshot entry for a stream.
|
|
461
|
-
*
|
|
462
|
-
* @template TState - The state schema type
|
|
463
|
-
*/
|
|
464
|
-
export interface CacheEntry<TState extends Schema> {
|
|
465
|
-
readonly state: TState;
|
|
466
|
-
readonly version: number;
|
|
467
|
-
readonly event_id: number;
|
|
468
|
-
readonly patches: number;
|
|
469
|
-
readonly snaps: number;
|
|
470
|
-
}
|
|
471
|
-
/**
|
|
472
|
-
* Cache port for storing stream snapshots in-process.
|
|
473
|
-
*
|
|
474
|
-
* Implementations should provide fast key-value access with bounded memory.
|
|
475
|
-
* The async interface is forward-compatible with external caches (e.g., Redis).
|
|
476
|
-
*
|
|
477
|
-
* @template TState - The state schema type
|
|
478
|
-
*/
|
|
479
|
-
export interface Cache extends Disposable {
|
|
480
|
-
get<TState extends Schema>(stream: string): Promise<CacheEntry<TState> | undefined>;
|
|
481
|
-
set<TState extends Schema>(stream: string, entry: CacheEntry<TState>): Promise<void>;
|
|
482
|
-
invalidate(stream: string): Promise<void>;
|
|
483
|
-
clear(): Promise<void>;
|
|
484
|
-
}
|
|
485
|
-
//# sourceMappingURL=ports.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../src/types/ports.ts"],"names":[],"mappings":"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"}
|