@venturekit/runtime 0.0.0-dev.20260312012510 → 0.0.0-dev.20260329102450
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 +1 -1
- package/dist/config/env.d.ts +62 -0
- package/dist/config/env.d.ts.map +1 -0
- package/dist/config/env.js +98 -0
- package/dist/config/env.js.map +1 -0
- package/dist/config/secrets.d.ts +67 -0
- package/dist/config/secrets.d.ts.map +1 -0
- package/dist/config/secrets.js +132 -0
- package/dist/config/secrets.js.map +1 -0
- package/dist/handler/adapter.d.ts.map +1 -0
- package/dist/{adapter.js → handler/adapter.js} +5 -44
- package/dist/handler/adapter.js.map +1 -0
- package/dist/{context.d.ts → handler/context.d.ts} +44 -3
- package/dist/handler/context.d.ts.map +1 -0
- package/dist/{context.js → handler/context.js} +9 -9
- package/dist/handler/context.js.map +1 -0
- package/dist/handler/errors.d.ts.map +1 -0
- package/dist/{errors.js → handler/errors.js} +11 -25
- package/dist/handler/errors.js.map +1 -0
- package/dist/{handler.d.ts → handler/handler.d.ts} +36 -3
- package/dist/handler/handler.d.ts.map +1 -0
- package/dist/{handler.js → handler/handler.js} +59 -23
- package/dist/handler/handler.js.map +1 -0
- package/dist/handler/response.d.ts.map +1 -0
- package/dist/{response.js → handler/response.js} +9 -17
- package/dist/handler/response.js.map +1 -0
- package/dist/handler/task-handler.d.ts +192 -0
- package/dist/handler/task-handler.d.ts.map +1 -0
- package/dist/handler/task-handler.js +262 -0
- package/dist/handler/task-handler.js.map +1 -0
- package/dist/index.d.ts +33 -14
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +30 -48
- package/dist/index.js.map +1 -1
- package/dist/{logger.d.ts → logging/logger.d.ts} +1 -1
- package/dist/logging/logger.d.ts.map +1 -0
- package/dist/{logger.js → logging/logger.js} +8 -16
- package/dist/logging/logger.js.map +1 -0
- package/dist/logging/tracing.d.ts +51 -0
- package/dist/logging/tracing.d.ts.map +1 -0
- package/dist/logging/tracing.js +77 -0
- package/dist/logging/tracing.js.map +1 -0
- package/dist/middleware/middleware.d.ts +120 -0
- package/dist/middleware/middleware.d.ts.map +1 -0
- package/dist/middleware/middleware.js +270 -0
- package/dist/middleware/middleware.js.map +1 -0
- package/dist/middleware/rate-limit-store.d.ts +153 -0
- package/dist/middleware/rate-limit-store.d.ts.map +1 -0
- package/dist/middleware/rate-limit-store.js +182 -0
- package/dist/middleware/rate-limit-store.js.map +1 -0
- package/dist/openapi/openapi.d.ts +147 -0
- package/dist/openapi/openapi.d.ts.map +1 -0
- package/dist/openapi/openapi.js +235 -0
- package/dist/openapi/openapi.js.map +1 -0
- package/dist/openapi.d.ts +10 -0
- package/dist/openapi.d.ts.map +1 -0
- package/dist/openapi.js +9 -0
- package/dist/openapi.js.map +1 -0
- package/dist/patterns/circuit-breaker.d.ts +78 -0
- package/dist/patterns/circuit-breaker.d.ts.map +1 -0
- package/dist/patterns/circuit-breaker.js +113 -0
- package/dist/patterns/circuit-breaker.js.map +1 -0
- package/dist/patterns/idempotency.d.ts +175 -0
- package/dist/patterns/idempotency.d.ts.map +1 -0
- package/dist/patterns/idempotency.js +305 -0
- package/dist/patterns/idempotency.js.map +1 -0
- package/dist/patterns/invoke.d.ts +279 -0
- package/dist/patterns/invoke.d.ts.map +1 -0
- package/dist/patterns/invoke.js +581 -0
- package/dist/patterns/invoke.js.map +1 -0
- package/dist/patterns/saga.d.ts +391 -0
- package/dist/patterns/saga.d.ts.map +1 -0
- package/dist/patterns/saga.js +556 -0
- package/dist/patterns/saga.js.map +1 -0
- package/dist/patterns.d.ts +17 -0
- package/dist/patterns.d.ts.map +1 -0
- package/dist/patterns.js +17 -0
- package/dist/patterns.js.map +1 -0
- package/dist/rate-limit.d.ts +16 -0
- package/dist/rate-limit.d.ts.map +1 -0
- package/dist/rate-limit.js +15 -0
- package/dist/rate-limit.js.map +1 -0
- package/dist/secrets.d.ts +11 -0
- package/dist/secrets.d.ts.map +1 -0
- package/dist/secrets.js +10 -0
- package/dist/secrets.js.map +1 -0
- package/dist/testing/test-utils.d.ts +99 -0
- package/dist/testing/test-utils.d.ts.map +1 -0
- package/dist/testing/test-utils.js +153 -0
- package/dist/testing/test-utils.js.map +1 -0
- package/dist/testing.d.ts +10 -0
- package/dist/testing.d.ts.map +1 -0
- package/dist/testing.js +9 -0
- package/dist/testing.js.map +1 -0
- package/dist/ws/ws.d.ts +139 -0
- package/dist/ws/ws.d.ts.map +1 -0
- package/dist/ws/ws.js +294 -0
- package/dist/ws/ws.js.map +1 -0
- package/dist/ws.d.ts +5 -133
- package/dist/ws.d.ts.map +1 -1
- package/dist/ws.js +4 -291
- package/dist/ws.js.map +1 -1
- package/package.json +47 -5
- package/dist/adapter.d.ts.map +0 -1
- package/dist/adapter.js.map +0 -1
- package/dist/context.d.ts.map +0 -1
- package/dist/context.js.map +0 -1
- package/dist/errors.d.ts.map +0 -1
- package/dist/errors.js.map +0 -1
- package/dist/handler.d.ts.map +0 -1
- package/dist/handler.js.map +0 -1
- package/dist/logger.d.ts.map +0 -1
- package/dist/logger.js.map +0 -1
- package/dist/middleware.d.ts +0 -47
- package/dist/middleware.d.ts.map +0 -1
- package/dist/middleware.js +0 -147
- package/dist/middleware.js.map +0 -1
- package/dist/response.d.ts.map +0 -1
- package/dist/response.js.map +0 -1
- /package/dist/{adapter.d.ts → handler/adapter.d.ts} +0 -0
- /package/dist/{errors.d.ts → handler/errors.d.ts} +0 -0
- /package/dist/{response.d.ts → handler/response.d.ts} +0 -0
|
@@ -0,0 +1,391 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* VentureKit Saga Orchestrator
|
|
3
|
+
*
|
|
4
|
+
* Distributed transaction coordination using the Saga pattern.
|
|
5
|
+
* Supports sequential and parallel steps, automatic rollback on failure,
|
|
6
|
+
* DynamoDB state persistence, resume from failure, and idempotent execution.
|
|
7
|
+
*
|
|
8
|
+
* ## Quick Start
|
|
9
|
+
* ```typescript
|
|
10
|
+
* import { saga } from '@venturekit/runtime';
|
|
11
|
+
*
|
|
12
|
+
* const createOrder = saga('create-order', [
|
|
13
|
+
* { name: 'reserve-inventory', execute: reserveInventory, compensate: releaseInventory },
|
|
14
|
+
* { name: 'charge-payment', execute: chargeCard, compensate: refundCharge },
|
|
15
|
+
* { name: 'send-confirmation', execute: sendEmail },
|
|
16
|
+
* ]);
|
|
17
|
+
*
|
|
18
|
+
* const result = await createOrder.run({ items: [...], total: 99 });
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* ## Parallel Steps
|
|
22
|
+
* ```typescript
|
|
23
|
+
* const checkout = saga('checkout', [
|
|
24
|
+
* parallel('validate', [
|
|
25
|
+
* { name: 'check-inventory', execute: checkStock },
|
|
26
|
+
* { name: 'verify-payment', execute: verifyCard },
|
|
27
|
+
* ]),
|
|
28
|
+
* { name: 'charge-payment', execute: chargeCard, compensate: refundCharge },
|
|
29
|
+
* ]);
|
|
30
|
+
* ```
|
|
31
|
+
*/
|
|
32
|
+
/**
|
|
33
|
+
* Saga step definition
|
|
34
|
+
*/
|
|
35
|
+
export interface SagaStep<TContext = Record<string, unknown>> {
|
|
36
|
+
/** Step name (for logging/tracking) */
|
|
37
|
+
name: string;
|
|
38
|
+
/** Execute this step. Receives saga context, returns updated context. */
|
|
39
|
+
execute: (ctx: TContext) => Promise<TContext>;
|
|
40
|
+
/** Compensate (undo) this step on failure. Called in reverse order. */
|
|
41
|
+
compensate?: (ctx: TContext) => Promise<void>;
|
|
42
|
+
/**
|
|
43
|
+
* If true, this step is idempotent and will be skipped on resume
|
|
44
|
+
* if it was already completed. Default: true when a store is used.
|
|
45
|
+
*/
|
|
46
|
+
idempotent?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* If true, this step runs fire-and-forget: the saga does NOT wait
|
|
49
|
+
* for it to complete and moves to the next step immediately.
|
|
50
|
+
* The step's return value is NOT merged into the context.
|
|
51
|
+
* Compensation is NOT called for async steps (they may not have finished).
|
|
52
|
+
*
|
|
53
|
+
* Use cases: sending notifications, triggering analytics, audit logging.
|
|
54
|
+
*/
|
|
55
|
+
async?: boolean;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* A group of steps that execute in parallel.
|
|
59
|
+
* All steps in the group share the same input context.
|
|
60
|
+
* Their output contexts are shallow-merged (later steps override earlier keys).
|
|
61
|
+
* If any step fails, all completed steps in the group are compensated.
|
|
62
|
+
*/
|
|
63
|
+
export interface ParallelStepGroup<TContext = Record<string, unknown>> {
|
|
64
|
+
/** Group name */
|
|
65
|
+
name: string;
|
|
66
|
+
/** Marks this as a parallel group */
|
|
67
|
+
type: 'parallel';
|
|
68
|
+
/** Steps to execute concurrently */
|
|
69
|
+
steps: SagaStep<TContext>[];
|
|
70
|
+
}
|
|
71
|
+
/** A saga step entry is either a single step or a parallel group */
|
|
72
|
+
export type SagaStepEntry<TContext = Record<string, unknown>> = SagaStep<TContext> | ParallelStepGroup<TContext>;
|
|
73
|
+
/**
|
|
74
|
+
* Helper to create a parallel step group.
|
|
75
|
+
*
|
|
76
|
+
* @example
|
|
77
|
+
* ```typescript
|
|
78
|
+
* saga('checkout', [
|
|
79
|
+
* parallel('validate', [
|
|
80
|
+
* { name: 'check-stock', execute: checkStock },
|
|
81
|
+
* { name: 'verify-card', execute: verifyCard },
|
|
82
|
+
* ]),
|
|
83
|
+
* { name: 'charge', execute: charge, compensate: refund },
|
|
84
|
+
* ]);
|
|
85
|
+
* ```
|
|
86
|
+
*/
|
|
87
|
+
export declare function parallel<TContext extends Record<string, unknown> = Record<string, unknown>>(name: string, steps: SagaStep<TContext>[]): ParallelStepGroup<TContext>;
|
|
88
|
+
/**
|
|
89
|
+
* Saga execution status
|
|
90
|
+
*/
|
|
91
|
+
export type SagaStatus = 'pending' | 'running' | 'completed' | 'compensating' | 'failed' | 'compensated';
|
|
92
|
+
/**
|
|
93
|
+
* Saga execution record (for persistence)
|
|
94
|
+
*/
|
|
95
|
+
export interface SagaRecord<TContext = Record<string, unknown>> {
|
|
96
|
+
/** Unique saga execution ID */
|
|
97
|
+
id: string;
|
|
98
|
+
/** Saga name */
|
|
99
|
+
name: string;
|
|
100
|
+
/** Current status */
|
|
101
|
+
status: SagaStatus;
|
|
102
|
+
/** Current step index */
|
|
103
|
+
currentStep: number;
|
|
104
|
+
/** Saga context (accumulated state from steps) */
|
|
105
|
+
context: TContext;
|
|
106
|
+
/** Completed step names */
|
|
107
|
+
completedSteps: string[];
|
|
108
|
+
/** Error that caused failure (if any) */
|
|
109
|
+
error?: string;
|
|
110
|
+
/** Trace ID for distributed tracing */
|
|
111
|
+
traceId?: string;
|
|
112
|
+
/** Timestamps */
|
|
113
|
+
startedAt: number;
|
|
114
|
+
completedAt?: number;
|
|
115
|
+
/** Number of times this saga has been attempted */
|
|
116
|
+
attempts: number;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Saga state store interface.
|
|
120
|
+
* Implement this to persist saga state (DynamoDB, Postgres, etc.).
|
|
121
|
+
*/
|
|
122
|
+
export interface SagaStore {
|
|
123
|
+
save(record: SagaRecord): Promise<void>;
|
|
124
|
+
update(id: string, updates: Partial<SagaRecord>): Promise<void>;
|
|
125
|
+
get(id: string): Promise<SagaRecord | null>;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Per-step result entry.
|
|
129
|
+
* Captured after each step executes, allowing the orchestrator to
|
|
130
|
+
* inspect individual step outputs without digging through the merged context.
|
|
131
|
+
*/
|
|
132
|
+
export interface StepResult<TContext = Record<string, unknown>> {
|
|
133
|
+
/** Step name */
|
|
134
|
+
name: string;
|
|
135
|
+
/** The context snapshot returned by this step's execute() */
|
|
136
|
+
output: TContext;
|
|
137
|
+
/** Whether this step was fire-and-forget (async) */
|
|
138
|
+
async: boolean;
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* Saga execution result
|
|
142
|
+
*/
|
|
143
|
+
export interface SagaResult<TContext = Record<string, unknown>> {
|
|
144
|
+
/** Whether the saga completed successfully */
|
|
145
|
+
success: boolean;
|
|
146
|
+
/** Final saga context (accumulated from all steps) */
|
|
147
|
+
context: TContext;
|
|
148
|
+
/** Saga execution record */
|
|
149
|
+
record: SagaRecord<TContext>;
|
|
150
|
+
/**
|
|
151
|
+
* Per-step results map.
|
|
152
|
+
* Access any step's output: `result.steps['step-name'].output`
|
|
153
|
+
*
|
|
154
|
+
* For parallel groups, each sub-step has its own entry.
|
|
155
|
+
* Async (fire-and-forget) steps have `async: true` and their output
|
|
156
|
+
* is the input context (since the saga didn't wait for them).
|
|
157
|
+
*/
|
|
158
|
+
steps: Record<string, StepResult<TContext>>;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* Event passed to onStepComplete callback.
|
|
162
|
+
*/
|
|
163
|
+
export interface SagaStepEvent<TContext = Record<string, unknown>> {
|
|
164
|
+
/** Step name */
|
|
165
|
+
name: string;
|
|
166
|
+
/** Step index within the saga */
|
|
167
|
+
index: number;
|
|
168
|
+
/** Context snapshot after step execution */
|
|
169
|
+
context: TContext;
|
|
170
|
+
/** Step execution duration in milliseconds */
|
|
171
|
+
durationMs: number;
|
|
172
|
+
/** Whether this was a fire-and-forget step */
|
|
173
|
+
async: boolean;
|
|
174
|
+
/** Saga execution ID */
|
|
175
|
+
sagaId: string;
|
|
176
|
+
/** Saga name */
|
|
177
|
+
sagaName: string;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Event passed to onCompensating callback.
|
|
181
|
+
*/
|
|
182
|
+
export interface SagaCompensateEvent<TContext = Record<string, unknown>> {
|
|
183
|
+
/** Step name being compensated */
|
|
184
|
+
name: string;
|
|
185
|
+
/** Step index within the saga */
|
|
186
|
+
index: number;
|
|
187
|
+
/** Current context at time of compensation */
|
|
188
|
+
context: TContext;
|
|
189
|
+
/** The original error that triggered compensation */
|
|
190
|
+
reason: Error;
|
|
191
|
+
/** Saga execution ID */
|
|
192
|
+
sagaId: string;
|
|
193
|
+
/** Saga name */
|
|
194
|
+
sagaName: string;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Event passed to onFailed callback.
|
|
198
|
+
*/
|
|
199
|
+
export interface SagaFailedEvent<TContext = Record<string, unknown>> {
|
|
200
|
+
/** The error that caused the saga to fail */
|
|
201
|
+
error: Error;
|
|
202
|
+
/** Saga execution record */
|
|
203
|
+
record: SagaRecord<TContext>;
|
|
204
|
+
/** Final context at time of failure */
|
|
205
|
+
context: TContext;
|
|
206
|
+
/** The step that failed (name), if identifiable */
|
|
207
|
+
failedStep?: string;
|
|
208
|
+
/** Total saga duration in milliseconds */
|
|
209
|
+
durationMs: number;
|
|
210
|
+
}
|
|
211
|
+
/**
|
|
212
|
+
* Saga options
|
|
213
|
+
*/
|
|
214
|
+
export interface SagaOptions<TContext = Record<string, unknown>> {
|
|
215
|
+
/** Optional state store for persistence + resume capability */
|
|
216
|
+
store?: SagaStore;
|
|
217
|
+
/** Trace ID for distributed tracing (propagated to all step logs) */
|
|
218
|
+
traceId?: string;
|
|
219
|
+
/** Called when a step completes successfully */
|
|
220
|
+
onStepComplete?: (event: SagaStepEvent<TContext>) => void;
|
|
221
|
+
/** Called when a step compensation begins */
|
|
222
|
+
onCompensating?: (event: SagaCompensateEvent<TContext>) => void;
|
|
223
|
+
/** Called when the saga fails (after compensation attempt) */
|
|
224
|
+
onFailed?: (event: SagaFailedEvent<TContext>) => void;
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Options for saga.run()
|
|
228
|
+
*/
|
|
229
|
+
export interface SagaRunOptions {
|
|
230
|
+
/** Provide an explicit saga execution ID (for idempotency / resume) */
|
|
231
|
+
id?: string;
|
|
232
|
+
/** Trace ID override for this execution */
|
|
233
|
+
traceId?: string;
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* Define a saga orchestrator.
|
|
237
|
+
*
|
|
238
|
+
* @param name - Saga name (used in logs and state records)
|
|
239
|
+
* @param steps - Ordered list of steps (sequential or parallel groups)
|
|
240
|
+
* @param options - Saga options (store, tracing, callbacks)
|
|
241
|
+
*
|
|
242
|
+
* @example Sequential steps
|
|
243
|
+
* ```typescript
|
|
244
|
+
* const createOrder = saga('create-order', [
|
|
245
|
+
* {
|
|
246
|
+
* name: 'reserve-inventory',
|
|
247
|
+
* execute: async (ctx) => {
|
|
248
|
+
* const reservation = await reserveInventory(ctx.items);
|
|
249
|
+
* return { ...ctx, reservationId: reservation.id };
|
|
250
|
+
* },
|
|
251
|
+
* compensate: async (ctx) => {
|
|
252
|
+
* await releaseInventory(ctx.reservationId);
|
|
253
|
+
* },
|
|
254
|
+
* },
|
|
255
|
+
* {
|
|
256
|
+
* name: 'charge-payment',
|
|
257
|
+
* execute: async (ctx) => {
|
|
258
|
+
* const charge = await chargeCard(ctx.paymentMethod, ctx.total);
|
|
259
|
+
* return { ...ctx, chargeId: charge.id };
|
|
260
|
+
* },
|
|
261
|
+
* compensate: async (ctx) => {
|
|
262
|
+
* await refundCharge(ctx.chargeId);
|
|
263
|
+
* },
|
|
264
|
+
* },
|
|
265
|
+
* {
|
|
266
|
+
* name: 'send-confirmation',
|
|
267
|
+
* execute: async (ctx) => {
|
|
268
|
+
* await sendEmail(ctx.email, 'Order confirmed');
|
|
269
|
+
* return ctx;
|
|
270
|
+
* },
|
|
271
|
+
* },
|
|
272
|
+
* ]);
|
|
273
|
+
*
|
|
274
|
+
* const result = await createOrder.run({ items: [...], paymentMethod: 'pm_xxx' });
|
|
275
|
+
* ```
|
|
276
|
+
*
|
|
277
|
+
* @example Parallel + sequential
|
|
278
|
+
* ```typescript
|
|
279
|
+
* const checkout = saga('checkout', [
|
|
280
|
+
* parallel('validate', [
|
|
281
|
+
* { name: 'check-stock', execute: checkStock },
|
|
282
|
+
* { name: 'verify-card', execute: verifyCard },
|
|
283
|
+
* ]),
|
|
284
|
+
* { name: 'charge', execute: charge, compensate: refund },
|
|
285
|
+
* { name: 'email', execute: sendConfirmation },
|
|
286
|
+
* ]);
|
|
287
|
+
* ```
|
|
288
|
+
*
|
|
289
|
+
* @example Resume from failure
|
|
290
|
+
* ```typescript
|
|
291
|
+
* const store = await createDefaultSagaStore();
|
|
292
|
+
* const mySaga = saga('order', steps, { store });
|
|
293
|
+
*
|
|
294
|
+
* // First attempt — fails at step 2
|
|
295
|
+
* const first = await mySaga.run(ctx, { id: 'order-123' });
|
|
296
|
+
*
|
|
297
|
+
* // Fix the issue, then resume — skips already-completed steps
|
|
298
|
+
* const second = await mySaga.resume('order-123');
|
|
299
|
+
* ```
|
|
300
|
+
*/
|
|
301
|
+
export declare function saga<TContext extends Record<string, unknown> = Record<string, unknown>>(name: string, steps: SagaStepEntry<TContext>[], options?: SagaOptions<TContext>): {
|
|
302
|
+
name: string;
|
|
303
|
+
steps: SagaStepEntry<TContext>[];
|
|
304
|
+
/**
|
|
305
|
+
* Execute the saga from the beginning or resume a previously failed saga.
|
|
306
|
+
*
|
|
307
|
+
* @param initialContext - Starting context for the saga
|
|
308
|
+
* @param runOptions - Optional ID (for idempotency) and traceId
|
|
309
|
+
*/
|
|
310
|
+
run(initialContext: TContext, runOptions?: SagaRunOptions): Promise<SagaResult<TContext>>;
|
|
311
|
+
/**
|
|
312
|
+
* Resume a previously failed or compensated saga.
|
|
313
|
+
* Requires a store to be configured.
|
|
314
|
+
* Skips steps that were already completed in the previous attempt.
|
|
315
|
+
*
|
|
316
|
+
* @param sagaId - The saga execution ID to resume
|
|
317
|
+
* @param runOptions - Optional traceId override
|
|
318
|
+
*/
|
|
319
|
+
resume(sagaId: string, runOptions?: Omit<SagaRunOptions, "id">): Promise<SagaResult<TContext>>;
|
|
320
|
+
};
|
|
321
|
+
/**
|
|
322
|
+
* In-memory saga store (for development/testing).
|
|
323
|
+
*
|
|
324
|
+
* **WARNING:** State is lost when the process restarts.
|
|
325
|
+
* For production, use `createDynamoDBSagaStore()`.
|
|
326
|
+
*/
|
|
327
|
+
export declare function createMemorySagaStore(): SagaStore;
|
|
328
|
+
/**
|
|
329
|
+
* DynamoDB saga store options.
|
|
330
|
+
*/
|
|
331
|
+
export interface DynamoDBSagaStoreOptions {
|
|
332
|
+
/** DynamoDB table name (default: 'venturekit-sagas') */
|
|
333
|
+
tableName?: string;
|
|
334
|
+
/** TTL in seconds for completed/failed records (default: 604800 = 7 days) */
|
|
335
|
+
ttlSeconds?: number;
|
|
336
|
+
/** AWS region (default: process.env.AWS_REGION) */
|
|
337
|
+
region?: string;
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Create a DynamoDB-backed saga state store.
|
|
341
|
+
*
|
|
342
|
+
* Persists saga execution state so sagas can be resumed after failure,
|
|
343
|
+
* tracked in logs, and audited.
|
|
344
|
+
*
|
|
345
|
+
* ### DynamoDB Table Schema
|
|
346
|
+
*
|
|
347
|
+
* The table must have:
|
|
348
|
+
* - **Partition key:** `pk` (String) — the saga execution ID
|
|
349
|
+
* - **TTL attribute:** `ttl` (Number) — epoch seconds for auto-cleanup
|
|
350
|
+
*
|
|
351
|
+
* @example
|
|
352
|
+
* ```typescript
|
|
353
|
+
* import { saga, createDynamoDBSagaStore } from '@venturekit/runtime';
|
|
354
|
+
*
|
|
355
|
+
* const store = await createDynamoDBSagaStore();
|
|
356
|
+
* const mySaga = saga('create-order', steps, { store });
|
|
357
|
+
*
|
|
358
|
+
* const result = await mySaga.run(ctx, { id: 'order-123' });
|
|
359
|
+
*
|
|
360
|
+
* // If failed, resume later:
|
|
361
|
+
* const resumed = await mySaga.resume('order-123');
|
|
362
|
+
* ```
|
|
363
|
+
*/
|
|
364
|
+
export declare function createDynamoDBSagaStore(options?: DynamoDBSagaStoreOptions): Promise<SagaStore>;
|
|
365
|
+
/**
|
|
366
|
+
* Options for the default saga store.
|
|
367
|
+
*/
|
|
368
|
+
export interface DefaultSagaStoreOptions {
|
|
369
|
+
/** DynamoDB table name */
|
|
370
|
+
tableName?: string;
|
|
371
|
+
/** TTL in seconds for records */
|
|
372
|
+
ttlSeconds?: number;
|
|
373
|
+
/** Force in-memory store even in production */
|
|
374
|
+
forceMemory?: boolean;
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Create a saga store with sensible defaults.
|
|
378
|
+
*
|
|
379
|
+
* - In production (Lambda): uses DynamoDB for distributed state persistence
|
|
380
|
+
* - In local dev: uses in-memory store
|
|
381
|
+
*
|
|
382
|
+
* @example
|
|
383
|
+
* ```typescript
|
|
384
|
+
* import { saga, createDefaultSagaStore } from '@venturekit/runtime';
|
|
385
|
+
*
|
|
386
|
+
* const store = await createDefaultSagaStore();
|
|
387
|
+
* const mySaga = saga('create-order', steps, { store });
|
|
388
|
+
* ```
|
|
389
|
+
*/
|
|
390
|
+
export declare function createDefaultSagaStore(options?: DefaultSagaStoreOptions): Promise<SagaStore>;
|
|
391
|
+
//# sourceMappingURL=saga.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"saga.d.ts","sourceRoot":"","sources":["../../src/patterns/saga.ts"],"names":[],"mappings":"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"}
|