@dudousxd/nestjs-durable-core 0.46.1 → 0.48.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/dist/index.cjs +511 -178
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +225 -28
- package/dist/index.d.ts +225 -28
- package/dist/index.js +507 -178
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -161,12 +161,6 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
|
|
|
161
161
|
release(queue: string, _slotId: string): Promise<void>;
|
|
162
162
|
}
|
|
163
163
|
|
|
164
|
-
/**
|
|
165
|
-
* Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
|
|
166
|
-
* `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
|
|
167
|
-
*/
|
|
168
|
-
declare function parseDuration(duration: string | number): number;
|
|
169
|
-
|
|
170
164
|
/**
|
|
171
165
|
* Cross-package step-name stamp. The `@Step` decorator (`@dudousxd/nestjs-durable`) writes a
|
|
172
166
|
* method's derived routing name under this key; core's `ctx.step` reads it (via {@link stepNameOf})
|
|
@@ -697,6 +691,8 @@ type RunRequestKind = {
|
|
|
697
691
|
} | {
|
|
698
692
|
kind: 'listRuns';
|
|
699
693
|
query: RunQuery;
|
|
694
|
+
} | {
|
|
695
|
+
kind: 'workerHealth';
|
|
700
696
|
} | {
|
|
701
697
|
kind: 'cancel';
|
|
702
698
|
runId: string;
|
|
@@ -1221,8 +1217,16 @@ interface DurableWebhook<TPayload = unknown> {
|
|
|
1221
1217
|
* build your own).
|
|
1222
1218
|
*/
|
|
1223
1219
|
readonly url?: string | undefined;
|
|
1224
|
-
/**
|
|
1225
|
-
|
|
1220
|
+
/**
|
|
1221
|
+
* Suspend until the callback arrives, then resume with its payload. Waits indefinitely by default —
|
|
1222
|
+
* no compute consumed. Pass `{ timeoutMs }` to bound the wait: if the deadline passes first the call
|
|
1223
|
+
* throws a `SignalTimeoutError` (catch it in the workflow to branch) — same timeout semantics as
|
|
1224
|
+
* {@link WorkflowCtx.waitForSignal}. The deadline is computed once (on the first call) and persisted,
|
|
1225
|
+
* so a replay reuses the recorded deadline rather than recomputing it from the current clock.
|
|
1226
|
+
*/
|
|
1227
|
+
wait(opts?: {
|
|
1228
|
+
timeoutMs?: number;
|
|
1229
|
+
}): Promise<TPayload>;
|
|
1226
1230
|
}
|
|
1227
1231
|
/**
|
|
1228
1232
|
* Options for a dispatched {@link WorkflowCtx.step} call. `retries`/`backoff`/`backoffMs`/
|
|
@@ -1263,6 +1267,25 @@ interface StepDispatchOpts {
|
|
|
1263
1267
|
* `retries`). Omit to wait indefinitely. Overrides the `@Step`-declared value. */
|
|
1264
1268
|
timeoutMs?: number;
|
|
1265
1269
|
}
|
|
1270
|
+
/** What a saga undo handler receives: the compensated step's original input and its result — the
|
|
1271
|
+
* ONE argument a compensation `@Step` is called with, so it's self-describing on the wire (a
|
|
1272
|
+
* Python worker sees `{ input, output }` with no side-channel lookup needed). */
|
|
1273
|
+
interface StepUndo<TInput, TOutput> {
|
|
1274
|
+
input: TInput;
|
|
1275
|
+
output: TOutput;
|
|
1276
|
+
}
|
|
1277
|
+
/**
|
|
1278
|
+
* Derive a `ctx.step` compensation handler's expected argument from the ORIGINAL step's method
|
|
1279
|
+
* type, so the ref form is compile-checked against the step it undoes:
|
|
1280
|
+
*
|
|
1281
|
+
* ```ts
|
|
1282
|
+
* async cancelBooking(undo: UndoOf<FlightService['book']>) { ... }
|
|
1283
|
+
* ```
|
|
1284
|
+
*
|
|
1285
|
+
* `...rest: never[]` pins this to a single-argument method (the shape every `@Step` handler has —
|
|
1286
|
+
* see {@link StepRef}); `Awaited<R>` unwraps a `Promise<TOutput>` return down to `TOutput`.
|
|
1287
|
+
*/
|
|
1288
|
+
type UndoOf<H> = H extends (input: infer I, ...rest: never[]) => infer R ? StepUndo<I, Awaited<R>> : never;
|
|
1266
1289
|
/**
|
|
1267
1290
|
* The context handed to a workflow function. Every interaction with the outside world goes
|
|
1268
1291
|
* through it so the engine can checkpoint — the workflow body itself stays deterministic.
|
|
@@ -1286,9 +1309,20 @@ interface WorkflowCtx {
|
|
|
1286
1309
|
*
|
|
1287
1310
|
* Both forms dispatch identically — a step runs on whatever worker serves that name and the run
|
|
1288
1311
|
* suspends (zero compute) until the result lands, then resumes with it (durable, replay-safe).
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1312
|
+
*
|
|
1313
|
+
* `opts.compensate` registers a SAGA UNDO for this call, dispatched (durably, in reverse order
|
|
1314
|
+
* with every other registered undo) if the run later fails or is cancelled with
|
|
1315
|
+
* `{ compensate: true }`. The undo is itself a normal `@Step` — pass its reference (compile-time
|
|
1316
|
+
* checked: it must accept `StepUndo<TInput, TOutput>` of THIS call, see {@link UndoOf}) or its
|
|
1317
|
+
* name for a cross-runtime undo handler. It runs on whatever worker serves that name, called with
|
|
1318
|
+
* the ONE `{ input, output }` envelope — never the original handler re-invoked in-process.
|
|
1319
|
+
*/
|
|
1320
|
+
step<TInput, TOutput>(handler: StepRef<TInput, TOutput>, input: TInput, opts?: StepDispatchOpts & {
|
|
1321
|
+
compensate?: StepRef<StepUndo<TInput, TOutput>, unknown> | string;
|
|
1322
|
+
}): Promise<TOutput>;
|
|
1323
|
+
step<TOutput = unknown, TInput = unknown>(name: string, input: TInput, opts?: StepDispatchOpts & {
|
|
1324
|
+
compensate?: StepRef<StepUndo<TInput, TOutput>, unknown> | string;
|
|
1325
|
+
}): Promise<TOutput>;
|
|
1292
1326
|
/**
|
|
1293
1327
|
* **Exactly-once** durable step for DB work: runs `fn` and writes the step's checkpoint in ONE
|
|
1294
1328
|
* store transaction, so the business write and the "done" marker commit atomically — a crash can
|
|
@@ -1380,9 +1414,12 @@ interface WorkflowCtx {
|
|
|
1380
1414
|
* placeholders share a `parallelGroup` tag so the dashboard renders the fan-out as one group.
|
|
1381
1415
|
*
|
|
1382
1416
|
* `mode` (default `waitAll`): `waitAll` waits for all then throws an aggregate {@link GatherError}
|
|
1383
|
-
* if any failed; `failFast` throws as soon as a failed child is seen
|
|
1384
|
-
*
|
|
1385
|
-
*
|
|
1417
|
+
* if any failed; `failFast` throws as soon as a failed child is seen, and requests cancellation of
|
|
1418
|
+
* every sibling that hasn't completed yet (best-effort, plain cancel — no saga undo; a sibling
|
|
1419
|
+
* mid-step only observes it at its next checkpoint, it isn't force-killed mid-synchronous-execution,
|
|
1420
|
+
* so a fast sibling can still slip through and complete). Empty `inputs` returns `[]` with no side
|
|
1421
|
+
* effects. The wait-all / fan-out counterpart to {@link child}; parity with the Python SDK's
|
|
1422
|
+
* `gather_children`.
|
|
1386
1423
|
*/
|
|
1387
1424
|
all<C extends WorkflowClass>(workflow: C, inputs: WorkflowInputOf<C>[], opts?: {
|
|
1388
1425
|
mode?: 'waitAll' | 'failFast';
|
|
@@ -1462,6 +1499,16 @@ interface WorkflowCtx {
|
|
|
1462
1499
|
* `ctx.upsertSearchAttributes(…)`).
|
|
1463
1500
|
*/
|
|
1464
1501
|
upsertSearchAttributes(attrs: SearchAttributes): Promise<void>;
|
|
1502
|
+
/**
|
|
1503
|
+
* Run a checkpointed step **in-process** — the escape hatch from the always-dispatched {@link step}
|
|
1504
|
+
* for work that must run inline in the workflow body. Like `step`, its result is a durable checkpoint
|
|
1505
|
+
* (returned, not re-run, on replay); unlike `step`, the body `fn` executes here rather than on a
|
|
1506
|
+
* worker, so it can carry an in-memory `compensate` callback for **sagas** — an undo the engine runs
|
|
1507
|
+
* in reverse if the run later fails (see [Sagas & compensation](/docs/reliability/sagas)). `fn`
|
|
1508
|
+
* receives a {@link StepLogger} for sub-process events. Prefer {@link step} for ordinary work; reach
|
|
1509
|
+
* for `localStep` when you need in-process execution or a compensation.
|
|
1510
|
+
*/
|
|
1511
|
+
localStep<TOutput>(name: string, fn: (log: StepLogger) => Promise<TOutput>, options?: StepOptions): Promise<TOutput>;
|
|
1465
1512
|
}
|
|
1466
1513
|
/** Result of executing or resuming a workflow run. */
|
|
1467
1514
|
interface RunResult {
|
|
@@ -1533,15 +1580,24 @@ interface StepInvocation {
|
|
|
1533
1580
|
type StepInterceptor = (invocation: StepInvocation, next: () => Promise<unknown>) => Promise<unknown>;
|
|
1534
1581
|
|
|
1535
1582
|
/**
|
|
1536
|
-
*
|
|
1537
|
-
*
|
|
1538
|
-
*
|
|
1539
|
-
* `createWorkflowCtx` result actually carries `localStep` at runtime; this type just names the wider
|
|
1540
|
-
* shape for the internal consumers that need it, without widening the public {@link WorkflowCtx}.
|
|
1583
|
+
* Run `fn` with `ctx` as the ambient workflow context. Engine-internal: wraps every execution of a
|
|
1584
|
+
* workflow body (first run and every replay), so ambient reads inside the body see the SAME ctx the
|
|
1585
|
+
* body received.
|
|
1541
1586
|
*/
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
}
|
|
1587
|
+
declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
|
|
1588
|
+
/**
|
|
1589
|
+
* The {@link WorkflowCtx} of the workflow body currently executing on this async path — or
|
|
1590
|
+
* `undefined` outside one. Note a `@Step` HANDLER runs on a worker, off the body's path: it has no
|
|
1591
|
+
* ambient workflow context (by design — a handler is not the workflow body).
|
|
1592
|
+
*/
|
|
1593
|
+
declare function currentWorkflowCtx(): WorkflowCtx | undefined;
|
|
1594
|
+
|
|
1595
|
+
/**
|
|
1596
|
+
* Back-compat alias of {@link WorkflowCtx}. `localStep` — the checkpointed in-process step primitive
|
|
1597
|
+
* used for saga compensation — is now part of the public {@link WorkflowCtx}, so this type adds
|
|
1598
|
+
* nothing; it is kept only so internal consumers (the durable-entity runner) keep compiling.
|
|
1599
|
+
*/
|
|
1600
|
+
type InternalWorkflowCtx = WorkflowCtx;
|
|
1545
1601
|
|
|
1546
1602
|
/** One operation on a durable entity: mutate `state` in place and/or return a result. */
|
|
1547
1603
|
type EntityHandler<S = unknown> = (state: S, arg: unknown) => unknown | Promise<unknown>;
|
|
@@ -2107,6 +2163,7 @@ declare class WorkflowEngine {
|
|
|
2107
2163
|
*/
|
|
2108
2164
|
waitForRun(runId: string, opts?: {
|
|
2109
2165
|
timeoutMs?: number;
|
|
2166
|
+
until?: 'settled' | 'terminal';
|
|
2110
2167
|
}): Promise<RunResult>;
|
|
2111
2168
|
/**
|
|
2112
2169
|
* Resume each run only if this instance can acquire its recovery lease — so when several
|
|
@@ -2275,17 +2332,80 @@ declare class WorkflowEngine {
|
|
|
2275
2332
|
* Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
|
|
2276
2333
|
* exit path of a run with a compensating cancel in flight — whether the resumed replay returned,
|
|
2277
2334
|
* suspended, hit continue-as-new, or threw — so a cancel is never lost just because the body didn't
|
|
2278
|
-
* stop at a suspension point.
|
|
2335
|
+
* stop at a suspension point.
|
|
2336
|
+
*
|
|
2337
|
+
* A dispatched compensation still in flight (or backing off a retry) needs the run to keep waiting:
|
|
2338
|
+
* unlike the failure path (which is fine going `suspended` — a resumable state no different from an
|
|
2339
|
+
* ordinary in-flight `ctx.step`), THIS run must stay `cancelling` — `engine.cancel`'s idempotent
|
|
2340
|
+
* re-check, `waitForRun`'s non-terminal treatment, and crash recovery (`recoverIncomplete` only
|
|
2341
|
+
* re-drives `running`/`cancelling` runs — a `cancelling` one with a free lease, whatever it's
|
|
2342
|
+
* internally waiting on) all key off that status. So on a pending unwind this returns WITHOUT
|
|
2343
|
+
* touching `status` (already `cancelling`, untouched since `engine.cancel` set it) — the in-memory
|
|
2344
|
+
* cancel flag stays too, re-derived from the status on any later re-drive regardless.
|
|
2279
2345
|
*/
|
|
2280
2346
|
private compensateAndCancel;
|
|
2281
2347
|
/** The run body, lease held + renewed by {@link execute}. */
|
|
2282
2348
|
private runExecution;
|
|
2283
2349
|
/**
|
|
2284
|
-
*
|
|
2285
|
-
*
|
|
2286
|
-
*
|
|
2350
|
+
* Undo every registered saga compensation in strict reverse order — the shared unwind both the
|
|
2351
|
+
* run-failure path (`runExecution`'s catch) and the compensating-cancel path
|
|
2352
|
+
* (`compensateAndCancel`) drive. Every entry, LOCAL or DISPATCHED, gets a NEGATIVE checkpoint seq
|
|
2353
|
+
* `-(k + 1)` for its position `k` (0, 1, 2… walking the stack in reverse) — reserved space that can
|
|
2354
|
+
* never collide with a body position (those start at 0), so a saga's undo trail composes onto the
|
|
2355
|
+
* run's ordinary checkpoint history with no store-schema change, and shows up in run detail exactly
|
|
2356
|
+
* like any other step. Deterministic because `compensations` is rebuilt identically on every replay
|
|
2357
|
+
* (see `workflow-ctx.ts`), so the same comp always lands on the same negative seq across a crash +
|
|
2358
|
+
* re-drive — the crash-safety this whole scheme rests on.
|
|
2359
|
+
*
|
|
2360
|
+
* A LOCAL entry runs in-process (`runCompensation`), which checkpoints its own outcome — completed,
|
|
2361
|
+
* or failed once `compensationRetries` are exhausted — so a crash mid-unwind SKIPS an
|
|
2362
|
+
* already-resolved one on the next pass instead of re-running it (and re-spending its retry budget)
|
|
2363
|
+
* from attempt 1. A DISPATCHED entry is an ordinary remote-step dispatch under the hood
|
|
2364
|
+
* (`dispatchCompensation`): when it needs the run to WAIT — freshly dispatched, still in flight, or
|
|
2365
|
+
* backing off a durable retry — this function returns that wait signal immediately (skipping every
|
|
2366
|
+
* comp after it in this pass); the CALLER decides how to represent "still unwinding" (see
|
|
2367
|
+
* `compensateAndCancel`'s doc comment for why that differs between the two callers). Either way, the
|
|
2368
|
+
* run resumes later exactly like any other dispatched step: `completeRemoteResult` completes the
|
|
2369
|
+
* negative-seq checkpoint and re-drives, the body replays and deterministically re-throws the same
|
|
2370
|
+
* exit it took before (the original failure, or the suspension `compensateAndCancel` resumed from),
|
|
2371
|
+
* this function runs again, the now-resolved comp is skipped, and the unwind continues from there.
|
|
2372
|
+
*
|
|
2373
|
+
* Returns `undefined` once every compensation has resolved — the caller then finalizes the run
|
|
2374
|
+
* (`failed` with the ORIGINAL body error, never masked by a comp outcome; or `cancelled`).
|
|
2375
|
+
*/
|
|
2376
|
+
private unwindCompensations;
|
|
2377
|
+
/**
|
|
2378
|
+
* Run one LOCAL saga compensation, retried up to `compensationRetries`, emitting a
|
|
2379
|
+
* `compensate:<step>` step event for its outcome so a stranded undo is visible. Never throws — a
|
|
2380
|
+
* permanently-failing compensation is skipped so it can't mask the original failure. Checkpoints
|
|
2381
|
+
* its outcome at `seq` (a negative unwind position reserved by {@link unwindCompensations}) so a
|
|
2382
|
+
* crash mid-unwind skips an already-resolved undo on a later pass instead of re-running it (and
|
|
2383
|
+
* re-spending its retry budget) from attempt 1 — the checkpoint is durability/visibility only; the
|
|
2384
|
+
* runtime retry-in-process-back-to-back semantics of `comp.fn()` are unchanged.
|
|
2287
2385
|
*/
|
|
2288
2386
|
private runCompensation;
|
|
2387
|
+
/**
|
|
2388
|
+
* Resolve (or advance) ONE dispatched saga compensation at its reserved negative `seq` — the undo
|
|
2389
|
+
* handler is an ordinary remote `@Step`, so this mirrors `callRemote`'s pending/failed/absent
|
|
2390
|
+
* branches (engine.ts's `callRemote`), minus the queue/admission and in-memory-`timeoutMs` paths
|
|
2391
|
+
* (V1: dispatch direct by name, always durable). Returns the wait signal when the run must pause for
|
|
2392
|
+
* this compensation (freshly dispatched, still in flight, or backing off before a durable retry);
|
|
2393
|
+
* `undefined` once it's resolved — completed (crash-safe skip), or retries exhausted/non-retryable
|
|
2394
|
+
* (already visible: `completeRemoteResult` emitted `step.failed` for `compensate:<name>` when that
|
|
2395
|
+
* checkpoint landed — never re-emitted here, and never allowed to block the rest of the unwind or
|
|
2396
|
+
* mask the run's original failure).
|
|
2397
|
+
*/
|
|
2398
|
+
private dispatchCompensation;
|
|
2399
|
+
/**
|
|
2400
|
+
* Dispatch (or re-dispatch, on a durable retry) one compensation's undo handler — mirrors
|
|
2401
|
+
* `callRemote`'s dispatch block (persist the `pending` checkpoint BEFORE handing off to the
|
|
2402
|
+
* transport, so a fast result always finds it to complete). Two DIFFERENT names are in play: the
|
|
2403
|
+
* checkpoint's `name` is `compensate:<originalStepName>` (what makes this undo show up on the run's
|
|
2404
|
+
* timeline, and what `completeRemoteResult` emits `step.completed`/`step.failed` under); the WIRE
|
|
2405
|
+
* task's `name` is the undo handler's OWN routing name (`def.name`) — a worker dispatches to the
|
|
2406
|
+
* `@Step` it registered, not to this saga-visibility label.
|
|
2407
|
+
*/
|
|
2408
|
+
private dispatchCompensationAttempt;
|
|
2289
2409
|
/** The seam handed to {@link createWorkflowCtx}: the authoring API reaches durability + lifecycle
|
|
2290
2410
|
* (checkpointing, dispatch, child start) through this, so the ctx primitives live in their own
|
|
2291
2411
|
* module and the engine stays the orchestrator. */
|
|
@@ -2365,6 +2485,79 @@ declare class RemoteStepError extends Error {
|
|
|
2365
2485
|
constructor(stepError?: StepError);
|
|
2366
2486
|
}
|
|
2367
2487
|
|
|
2488
|
+
/**
|
|
2489
|
+
* What the class-first statics need from whoever registered the workflow class: the engine, or a
|
|
2490
|
+
* store-less start facade (a tenant's `DurableStartClient`). `waitForRun` is optional — a facade
|
|
2491
|
+
* without a store cannot wait, so `execute` outside a workflow throws a clear error there.
|
|
2492
|
+
*/
|
|
2493
|
+
interface WorkflowStartClient {
|
|
2494
|
+
start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
|
|
2495
|
+
waitForRun?(runId: string, opts?: {
|
|
2496
|
+
timeoutMs?: number;
|
|
2497
|
+
until?: 'settled' | 'terminal';
|
|
2498
|
+
}): Promise<RunResult>;
|
|
2499
|
+
}
|
|
2500
|
+
/**
|
|
2501
|
+
* Bind a `@Workflow` class to the client that can start it — called by the registrar for every
|
|
2502
|
+
* discovered workflow at boot. This is what lets `MyWorkflow.start()` resolve THE engine that
|
|
2503
|
+
* registered it, with no global engine singleton (two engines in one process each bind their own
|
|
2504
|
+
* classes).
|
|
2505
|
+
*/
|
|
2506
|
+
declare function bindWorkflowClass(ctor: Function, client: WorkflowStartClient): void;
|
|
2507
|
+
/**
|
|
2508
|
+
* Optional base class giving a `@Workflow` a **class-first API** — start it from anywhere without
|
|
2509
|
+
* injecting the engine or `WorkflowService`:
|
|
2510
|
+
*
|
|
2511
|
+
* ```ts
|
|
2512
|
+
* @Workflow({ name: 'checkout', version: '1' })
|
|
2513
|
+
* export class CheckoutWorkflow extends DurableWorkflow {
|
|
2514
|
+
* async run(ctx: WorkflowCtx, order: Order) { ... }
|
|
2515
|
+
* }
|
|
2516
|
+
*
|
|
2517
|
+
* const { runId } = await CheckoutWorkflow.start(order); // fire-and-forget, typed input
|
|
2518
|
+
* const result = await CheckoutWorkflow.execute(order); // run-and-await, typed output
|
|
2519
|
+
* ```
|
|
2520
|
+
*
|
|
2521
|
+
* Each method means the same thing everywhere; only the mechanism adapts to where you call it:
|
|
2522
|
+
*
|
|
2523
|
+
* - {@link DurableWorkflow.start | `start`} — **fire-and-forget**. Outside a workflow it is exactly
|
|
2524
|
+
* `engine.start` (enqueue, return `{ runId, status }` immediately). Inside a workflow body it
|
|
2525
|
+
* becomes `ctx.startChild` — checkpointed, replay-safe, parent-linked — same contract.
|
|
2526
|
+
* - {@link DurableWorkflow.execute | `execute`} — **run-and-await the typed output**. Inside a
|
|
2527
|
+
* workflow it is `ctx.child` (the parent suspends with zero compute and resumes with the result).
|
|
2528
|
+
* Outside it starts the run and waits until it settles terminally, resolving the output or
|
|
2529
|
+
* throwing `FatalError` when the run failed/cancelled/dead.
|
|
2530
|
+
*
|
|
2531
|
+
* Inside-ness is detected via the ambient workflow context the engine installs around every body
|
|
2532
|
+
* execution (see `ambient-ctx.ts`). A `@Step` handler runs on a worker, off the body's path — the
|
|
2533
|
+
* statics there start a TOP-LEVEL run, which is correct: a handler is not the workflow body.
|
|
2534
|
+
*/
|
|
2535
|
+
declare class DurableWorkflow {
|
|
2536
|
+
/**
|
|
2537
|
+
* Fire-and-forget start — `engine.start` outside a workflow, `ctx.startChild` (parent-linked)
|
|
2538
|
+
* inside one. `opts.id` pins the run id (outside) / child id (inside) for idempotent starts.
|
|
2539
|
+
*/
|
|
2540
|
+
static start<C extends WorkflowClass>(this: C, input: WorkflowInputOf<C>, opts?: {
|
|
2541
|
+
id?: string;
|
|
2542
|
+
} & StartOptions): Promise<RunResult>;
|
|
2543
|
+
/**
|
|
2544
|
+
* Run-and-await the typed output — `ctx.child` inside a workflow (suspends the parent, zero
|
|
2545
|
+
* compute); outside, starts the run and waits until it settles terminally. Throws `FatalError`
|
|
2546
|
+
* when the run does not complete. `opts.timeoutMs` bounds the OUTSIDE wait only (inside, a
|
|
2547
|
+
* suspended parent costs nothing — bound the child itself with `executionTimeout` instead).
|
|
2548
|
+
*/
|
|
2549
|
+
static execute<C extends WorkflowClass>(this: C, input: WorkflowInputOf<C>, opts?: {
|
|
2550
|
+
id?: string;
|
|
2551
|
+
timeoutMs?: number;
|
|
2552
|
+
} & StartOptions): Promise<WorkflowOutputOf<C>>;
|
|
2553
|
+
}
|
|
2554
|
+
|
|
2555
|
+
/**
|
|
2556
|
+
* Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
|
|
2557
|
+
* `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
|
|
2558
|
+
*/
|
|
2559
|
+
declare function parseDuration(duration: string | number): number;
|
|
2560
|
+
|
|
2368
2561
|
/**
|
|
2369
2562
|
* Thrown inside a step to signal an unrecoverable failure: the engine will NOT retry it,
|
|
2370
2563
|
* regardless of the step's `retries` setting, and fails the run immediately. Use it for
|
|
@@ -2541,11 +2734,15 @@ interface RunDetail {
|
|
|
2541
2734
|
* The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
|
|
2542
2735
|
* topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
|
|
2543
2736
|
* a `ProxyRunGateway` that round-trips over the transport. Deliberately smaller than the full dashboard
|
|
2544
|
-
* (no metrics/bulk/
|
|
2737
|
+
* (no metrics/bulk/update/signal) — those stay control-plane-only. `workerHealth` IS on the port: the
|
|
2738
|
+
* operator answers it scoped to the requester's own groups, so a tenant's Workers panel works too.
|
|
2545
2739
|
*/
|
|
2546
2740
|
interface RunGateway {
|
|
2547
2741
|
getRunDetail(runId: string): Promise<RunDetail | null>;
|
|
2548
2742
|
listRuns(query: RunQuery): Promise<WorkflowRun[]>;
|
|
2743
|
+
/** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
|
|
2744
|
+
* every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
|
|
2745
|
+
workerHealth(): Promise<GroupHealth[]>;
|
|
2549
2746
|
cancel(runId: string, opts?: {
|
|
2550
2747
|
compensate?: boolean;
|
|
2551
2748
|
}): Promise<RunResult | null>;
|
|
@@ -2935,4 +3132,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
|
|
|
2935
3132
|
onControl(handler: (msg: ControlMessage) => void): void;
|
|
2936
3133
|
}
|
|
2937
3134
|
|
|
2938
|
-
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
|
|
3135
|
+
export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
|