@dudousxd/nestjs-durable 0.53.0 → 0.54.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.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
- export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
1
+ import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
+ export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, EventSubscription, InferSearchAttributes, LIFECYCLE_PENDING_TAG, LifecycleEventOf, LifecycleKind, OnErrorInput, OnEventEntry, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowLifecycleEvent, WorkflowRun, hmacTenantVerifier, lifecycleRunId, lifecycleSourceOf, prevCronFireMs, readSearchAttributes, runCompletedEvent, runFailedEvent, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken, triggeredRunsOf } from '@dudousxd/nestjs-durable-core';
3
3
  import { z } from 'zod';
4
4
  import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
5
5
  import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -141,8 +141,8 @@ interface WorkflowMeta {
141
141
  validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
142
142
  /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
143
143
  searchAttributes?: SearchAttributesSchema | undefined;
144
- /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
145
- onEvent?: string[] | undefined;
144
+ /** Events that start a fresh run of this workflow. See `WorkflowOptions`. */
145
+ onEvent?: OnEventEntry[] | undefined;
146
146
  /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
147
147
  debounce?: string | number | undefined;
148
148
  /** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
@@ -277,9 +277,10 @@ interface WorkflowOptions {
277
277
  * Start a fresh run of this workflow whenever any of these events is published via
278
278
  * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
279
279
  * `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
280
- * the `@OnDurableEvent(...)` class decorator; the two are merged.
280
+ * the `@OnDurableEvent(...)` class decorator; the two are merged. An entry can also be
281
+ * `{ event, where }`, where `where(payload)` decides per event whether this workflow starts.
281
282
  */
282
- onEvent?: string[];
283
+ onEvent?: OnEventEntry[];
283
284
  /**
284
285
  * Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
285
286
  * for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
@@ -458,11 +459,121 @@ declare const ON_EVENT_METADATA: unique symbol;
458
459
  * Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
459
460
  * app using both libs an auto-import picking the wrong one fails silently in either direction.
460
461
  */
461
- declare function OnDurableEvent(...events: string[]): ClassDecorator;
462
+ declare function OnDurableEvent(...events: OnEventEntry[]): ClassDecorator;
463
+ /**
464
+ * Coalesce a subscriber's triggers by **debouncing**: start it once events have been quiet for
465
+ * `windowMs`, with the last one. `key` splits that per key: it receives the subscriber's input (what
466
+ * `input` builds), and each distinct key debounces on its own.
467
+ */
468
+ interface SubscriberDebounce<TRunInput> {
469
+ windowMs: number | string;
470
+ key?: ((input: TRunInput) => string) | undefined;
471
+ }
472
+ /**
473
+ * Coalesce a subscriber's triggers by **batching**: start it with `{ events }` once `maxSize` arrive
474
+ * or `windowMs` passes since the first. `key` batches each distinct key on its own.
475
+ */
476
+ interface SubscriberBatch<TRunInput> {
477
+ maxSize: number;
478
+ windowMs: number | string;
479
+ key?: ((input: TRunInput) => string) | undefined;
480
+ }
481
+ /** Options for {@link OnWorkflowCompleted} / {@link OnWorkflowFailed}. */
482
+ interface OnWorkflowSettledOptions<TEvent, TRunInput> {
483
+ /** Start only for the settled runs this returns true for, e.g. by `input` or `searchAttributes`. */
484
+ where?: ((event: TEvent) => boolean) | undefined;
485
+ /**
486
+ * The started run's input, built from the event. Without it the run receives the
487
+ * {@link WorkflowLifecycleEvent} itself. Lets an existing workflow subscribe with its own input
488
+ * shape, and keeps the settled run's whole input and output out of the new run's row.
489
+ */
490
+ input?: ((event: TEvent) => TRunInput) | undefined;
491
+ /**
492
+ * Debounce this workflow's triggers (see {@link SubscriberDebounce}). Sets the workflow's
493
+ * `onEvent` coalescing, so it applies to every event it subscribes to; a different `debounce` or
494
+ * `batch` already declared on it fails at registration. Not with `batch`.
495
+ */
496
+ debounce?: SubscriberDebounce<TRunInput> | undefined;
497
+ /**
498
+ * Batch this workflow's triggers (see {@link SubscriberBatch}); the run's input becomes
499
+ * `{ events: TRunInput[] }`. Same scope and conflicts as `debounce`. Not with `debounce`.
500
+ */
501
+ batch?: SubscriberBatch<TRunInput> | undefined;
502
+ }
503
+ /** Options for {@link OnWorkflowFailed}: also which endings start the subscriber. */
504
+ interface OnWorkflowFailedOptions<TEvent, TRunInput> extends OnWorkflowSettledOptions<TEvent, TRunInput> {
505
+ /** The endings that start it. Defaults to all three: `failed`, `cancelled` and `dead`. */
506
+ statuses?: Array<'failed' | 'cancelled' | 'dead'> | undefined;
507
+ }
508
+ /** `O` with a required `batch` (and no `debounce`): the overload whose subscriber takes `{ events }`. */
509
+ type Batched<O, TRunInput> = O & {
510
+ batch: SubscriberBatch<TRunInput>;
511
+ debounce?: undefined;
512
+ };
513
+ /** `O` without `batch`: the overload whose subscriber takes `TRunInput` itself. */
514
+ type Unbatched<O> = O & {
515
+ batch?: undefined;
516
+ };
517
+ /**
518
+ * A class decorator that only accepts a workflow whose `run(ctx, input)` takes `TRunInput`, so a
519
+ * subscriber with the wrong input shape fails to compile instead of failing at runtime.
520
+ */
521
+ type SubscriberDecorator<TRunInput> = <T extends abstract new (...args: never[]) => {
522
+ run: (ctx: never, input: TRunInput) => unknown;
523
+ }>(target: T) => void;
524
+ /**
525
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` **completes**. The new
526
+ * run's input is the {@link WorkflowLifecycleEvent} (run id, input, output, tags, search
527
+ * attributes), or what `input` builds from it. The settling workflow does not know about its
528
+ * subscribers. Exactly once per settled run: see `runCompletedEvent` in
529
+ * `@dudousxd/nestjs-durable-core`.
530
+ *
531
+ * With a class ref, the decorated workflow's `run` input is type-checked against the event (or
532
+ * against `input`'s return type, or `{ events }` of it with `batch`). Child runs publish too, so a
533
+ * workflow that `etl` starts as a child also starts its subscribers.
534
+ *
535
+ * ```ts
536
+ * @Workflow({ name: 'refresh-summaries' })
537
+ * @OnWorkflowCompleted(IngestionWorkflow, {
538
+ * where: (e) => e.input.type === 'mvr',
539
+ * input: (e) => ({ baseId: e.input.baseId }),
540
+ * debounce: { windowMs: '30s', key: (input) => input.baseId },
541
+ * })
542
+ * class RefreshSummariesWorkflow {
543
+ * async run(ctx: WorkflowCtx, input: { baseId: string }) {}
544
+ * }
545
+ * ```
546
+ */
547
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
548
+ events: TRunInput[];
549
+ }>;
550
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
551
+ declare function OnWorkflowCompleted(workflow: string, options?: OnWorkflowSettledOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
552
+ /**
553
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` ends **failed,
554
+ * cancelled or dead** (narrow it with `statuses`). Same contract as {@link OnWorkflowCompleted};
555
+ * the event carries `error` and `status` instead of `output`.
556
+ */
557
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
558
+ events: TRunInput[];
559
+ }>;
560
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
561
+ declare function OnWorkflowFailed(workflow: string, options?: OnWorkflowFailedOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
562
+ /** Metadata key for the `onEvent` coalescing `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. */
563
+ declare const ON_EVENT_BATCH_METADATA: unique symbol;
564
+ /**
565
+ * How a workflow coalesces its `onEvent` triggers: `@Workflow({ debounce | batch })`, or what its
566
+ * `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. Throws when both are set and differ, so a
567
+ * workflow never silently coalesces one way while its decorator says another.
568
+ */
569
+ declare function eventBatchOf(meta: WorkflowMeta, target: object): EventBatchConfig | undefined;
462
570
  /** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
463
571
  declare const OnEvent: typeof OnDurableEvent;
464
- /** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnDurableEvent`. */
465
- declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
572
+ /**
573
+ * All events a workflow class subscribes to: `@Workflow({ onEvent })`, `@OnDurableEvent`,
574
+ * `@OnWorkflowCompleted` and `@OnWorkflowFailed`. Repeated bare names collapse to one.
575
+ */
576
+ declare function getOnEvents(meta: WorkflowMeta, target: object): OnEventEntry[];
466
577
 
467
578
  /**
468
579
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
@@ -1109,6 +1220,10 @@ declare function inAppWorkerProviders(): Provider[];
1109
1220
  * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
1110
1221
  */
1111
1222
  declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
1223
+ /** The error `code` a responder replies with for a request it rejects as malformed or not allowed. */
1224
+ declare const BAD_RUN_REQUEST = "bad-request";
1225
+ /** The most settled runs one tenant republish reads; a larger `limit` is lowered to it. */
1226
+ declare const TENANT_REPUBLISH_MAX_LIMIT = 1000;
1112
1227
  /** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
1113
1228
  * correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
1114
1229
  * transports carry the run-request/reply protocol); the caller capability-checks before wiring
@@ -1133,20 +1248,6 @@ interface RunRequestResponderOptions {
1133
1248
  */
1134
1249
  warnWithoutVerifier?: boolean | undefined;
1135
1250
  }
1136
- /**
1137
- * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
1138
- * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
1139
- * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
1140
- * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
1141
- * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
1142
- * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
1143
- * sent. This is the security boundary of the tenant run gateway — do not weaken it.
1144
- *
1145
- * With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
1146
- * wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
1147
- * token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
1148
- * that throws becomes an error reply too.
1149
- */
1150
1251
  declare class RunRequestResponder {
1151
1252
  private readonly transport;
1152
1253
  private readonly gateway;
@@ -1156,20 +1257,34 @@ declare class RunRequestResponder {
1156
1257
  * failure never throws back into the transport (errors are captured into an error reply). */
1157
1258
  start(): void;
1158
1259
  private handle;
1260
+ /**
1261
+ * `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
1262
+ * (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
1263
+ * namespace, as the `workflowLifecycle` verb answers them.
1264
+ */
1265
+ private scopeLifecycle;
1266
+ /**
1267
+ * Why a tenant republish naming `subscriber` is refused, or undefined when it may go ahead: the
1268
+ * subscriber must be owed the event of `workflow` settling (as `kind`, when given) by a run of
1269
+ * the tenant's namespace (the gateway's `lifecycleSubscribers`, else the tenant's
1270
+ * `workflowLifecycle` links), so a tenant cannot have the event owed to an arbitrary name. Without
1271
+ * `subscriber` there is nothing to check.
1272
+ */
1273
+ private refuseSubscriber;
1159
1274
  private callVerb;
1160
1275
  }
1161
1276
 
1162
1277
  /**
1163
1278
  * An error reply from the control plane. `code` carries the reply's machine-readable reason when it
1164
1279
  * sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
1165
- * another tenant), ... — so a caller can tell an authentication failure from a real one, as with
1280
+ * another tenant), `bad-request` (the request was malformed or not allowed), ... — so a caller can tell an authentication failure from a real one, as with
1166
1281
  * Agora's proxy.
1167
1282
  */
1168
1283
  /**
1169
1284
  * The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
1170
1285
  * plane assignable without losing autocomplete on the known ones.
1171
1286
  */
1172
- type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1287
+ type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof BAD_RUN_REQUEST | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1173
1288
  declare class RunGatewayError extends Error {
1174
1289
  readonly code: RunGatewayErrorCode | undefined;
1175
1290
  constructor(message: string, code?: RunGatewayErrorCode);
@@ -1251,6 +1366,20 @@ declare class ProxyRunGateway implements RunGateway {
1251
1366
  redispatchPending(runId: string): Promise<(RunResult & {
1252
1367
  redispatched: number;
1253
1368
  }) | null>;
1369
+ /**
1370
+ * Republished on the control plane: a one-run target is checked against this tenant like
1371
+ * `retry`, a by-workflow one is read over this tenant's namespace only. A control plane too old to
1372
+ * know the verb fails it with an {@link UNSUPPORTED_RUN_REQUEST} error rather than a timeout.
1373
+ */
1374
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1375
+ /** Answered by the control plane's engine; same version-skew error as {@link republishLifecycle}. */
1376
+ workflowLifecycle(workflow: string): Promise<WorkflowLifecycleLinks>;
1377
+ /**
1378
+ * A verb with no fallback on an older control plane: its unsupported-request error, or the empty
1379
+ * `ok: true` reply the oldest responders send for an unknown verb, becomes a
1380
+ * {@link RunGatewayError} with code {@link UNSUPPORTED_RUN_REQUEST}.
1381
+ */
1382
+ private requestNewVerb;
1254
1383
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1255
1384
  }
1256
1385
 
@@ -1299,6 +1428,18 @@ declare class StoreRunGateway implements RunGateway {
1299
1428
  constructor(store: StateStore, engine: WorkflowEngine);
1300
1429
  topology(): DurableTopology;
1301
1430
  getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
1431
+ /**
1432
+ * What a run detail reads beyond the run row and its checkpoints: what this run's settling
1433
+ * started, the subscribers its lifecycle event goes to (of its namespace) and where it stands for
1434
+ * each, what started it, its workflow's lifecycle links, and the `ctx.waitForRun` waits on either
1435
+ * side of it with the other run's status. A few reads per detail: the run's own waiters while it
1436
+ * is suspended, the waiters on it (one prefix read), and one batched read of every linked run.
1437
+ */
1438
+ private lifecycleLinks;
1439
+ workflowLifecycle(workflow: string, opts?: {
1440
+ namespace?: string | undefined;
1441
+ }): Promise<WorkflowLifecycleLinks>;
1442
+ lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
1302
1443
  getRun(runId: string): Promise<WorkflowRun | null>;
1303
1444
  getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
1304
1445
  listRuns(query: RunQuery): Promise<RunListItem[]>;
@@ -1343,6 +1484,7 @@ declare class StoreRunGateway implements RunGateway {
1343
1484
  redispatchPending(runId: string): Promise<(RunResult & {
1344
1485
  redispatched: number;
1345
1486
  }) | null>;
1487
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1346
1488
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1347
1489
  }
1348
1490
 
@@ -1457,6 +1599,18 @@ declare class WorkflowService {
1457
1599
  id?: string;
1458
1600
  buffer?: boolean;
1459
1601
  }): Promise<number>;
1602
+ /**
1603
+ * The runs started by `runId` settling, through `@OnWorkflowCompleted` / `@OnWorkflowFailed` (or
1604
+ * an `onEvent` on `runCompletedEvent(...)`). Only subscribers registered on this engine are
1605
+ * considered. For the reverse link, `lifecycleSourceOf(run)` reads it from the run itself.
1606
+ */
1607
+ triggeredRuns(runId: string): Promise<string[]>;
1608
+ /**
1609
+ * Publish settled runs' lifecycle events again: to a subscriber registered after they settled, or
1610
+ * one restricted by `subscriber`. Subscribers already started for a run are not started again.
1611
+ * See `WorkflowEngine.republishLifecycle`.
1612
+ */
1613
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1460
1614
  }
1461
1615
 
1462
- export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
1616
+ export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, OnWorkflowCompleted, OnWorkflowFailed, type OnWorkflowFailedOptions, type OnWorkflowSettledOptions, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
- export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
1
+ import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
+ export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, EventSubscription, InferSearchAttributes, LIFECYCLE_PENDING_TAG, LifecycleEventOf, LifecycleKind, OnErrorInput, OnEventEntry, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowLifecycleEvent, WorkflowRun, hmacTenantVerifier, lifecycleRunId, lifecycleSourceOf, prevCronFireMs, readSearchAttributes, runCompletedEvent, runFailedEvent, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken, triggeredRunsOf } from '@dudousxd/nestjs-durable-core';
3
3
  import { z } from 'zod';
4
4
  import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
5
5
  import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -141,8 +141,8 @@ interface WorkflowMeta {
141
141
  validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
142
142
  /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
143
143
  searchAttributes?: SearchAttributesSchema | undefined;
144
- /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
145
- onEvent?: string[] | undefined;
144
+ /** Events that start a fresh run of this workflow. See `WorkflowOptions`. */
145
+ onEvent?: OnEventEntry[] | undefined;
146
146
  /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
147
147
  debounce?: string | number | undefined;
148
148
  /** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
@@ -277,9 +277,10 @@ interface WorkflowOptions {
277
277
  * Start a fresh run of this workflow whenever any of these events is published via
278
278
  * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
279
279
  * `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
280
- * the `@OnDurableEvent(...)` class decorator; the two are merged.
280
+ * the `@OnDurableEvent(...)` class decorator; the two are merged. An entry can also be
281
+ * `{ event, where }`, where `where(payload)` decides per event whether this workflow starts.
281
282
  */
282
- onEvent?: string[];
283
+ onEvent?: OnEventEntry[];
283
284
  /**
284
285
  * Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
285
286
  * for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
@@ -458,11 +459,121 @@ declare const ON_EVENT_METADATA: unique symbol;
458
459
  * Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
459
460
  * app using both libs an auto-import picking the wrong one fails silently in either direction.
460
461
  */
461
- declare function OnDurableEvent(...events: string[]): ClassDecorator;
462
+ declare function OnDurableEvent(...events: OnEventEntry[]): ClassDecorator;
463
+ /**
464
+ * Coalesce a subscriber's triggers by **debouncing**: start it once events have been quiet for
465
+ * `windowMs`, with the last one. `key` splits that per key: it receives the subscriber's input (what
466
+ * `input` builds), and each distinct key debounces on its own.
467
+ */
468
+ interface SubscriberDebounce<TRunInput> {
469
+ windowMs: number | string;
470
+ key?: ((input: TRunInput) => string) | undefined;
471
+ }
472
+ /**
473
+ * Coalesce a subscriber's triggers by **batching**: start it with `{ events }` once `maxSize` arrive
474
+ * or `windowMs` passes since the first. `key` batches each distinct key on its own.
475
+ */
476
+ interface SubscriberBatch<TRunInput> {
477
+ maxSize: number;
478
+ windowMs: number | string;
479
+ key?: ((input: TRunInput) => string) | undefined;
480
+ }
481
+ /** Options for {@link OnWorkflowCompleted} / {@link OnWorkflowFailed}. */
482
+ interface OnWorkflowSettledOptions<TEvent, TRunInput> {
483
+ /** Start only for the settled runs this returns true for, e.g. by `input` or `searchAttributes`. */
484
+ where?: ((event: TEvent) => boolean) | undefined;
485
+ /**
486
+ * The started run's input, built from the event. Without it the run receives the
487
+ * {@link WorkflowLifecycleEvent} itself. Lets an existing workflow subscribe with its own input
488
+ * shape, and keeps the settled run's whole input and output out of the new run's row.
489
+ */
490
+ input?: ((event: TEvent) => TRunInput) | undefined;
491
+ /**
492
+ * Debounce this workflow's triggers (see {@link SubscriberDebounce}). Sets the workflow's
493
+ * `onEvent` coalescing, so it applies to every event it subscribes to; a different `debounce` or
494
+ * `batch` already declared on it fails at registration. Not with `batch`.
495
+ */
496
+ debounce?: SubscriberDebounce<TRunInput> | undefined;
497
+ /**
498
+ * Batch this workflow's triggers (see {@link SubscriberBatch}); the run's input becomes
499
+ * `{ events: TRunInput[] }`. Same scope and conflicts as `debounce`. Not with `debounce`.
500
+ */
501
+ batch?: SubscriberBatch<TRunInput> | undefined;
502
+ }
503
+ /** Options for {@link OnWorkflowFailed}: also which endings start the subscriber. */
504
+ interface OnWorkflowFailedOptions<TEvent, TRunInput> extends OnWorkflowSettledOptions<TEvent, TRunInput> {
505
+ /** The endings that start it. Defaults to all three: `failed`, `cancelled` and `dead`. */
506
+ statuses?: Array<'failed' | 'cancelled' | 'dead'> | undefined;
507
+ }
508
+ /** `O` with a required `batch` (and no `debounce`): the overload whose subscriber takes `{ events }`. */
509
+ type Batched<O, TRunInput> = O & {
510
+ batch: SubscriberBatch<TRunInput>;
511
+ debounce?: undefined;
512
+ };
513
+ /** `O` without `batch`: the overload whose subscriber takes `TRunInput` itself. */
514
+ type Unbatched<O> = O & {
515
+ batch?: undefined;
516
+ };
517
+ /**
518
+ * A class decorator that only accepts a workflow whose `run(ctx, input)` takes `TRunInput`, so a
519
+ * subscriber with the wrong input shape fails to compile instead of failing at runtime.
520
+ */
521
+ type SubscriberDecorator<TRunInput> = <T extends abstract new (...args: never[]) => {
522
+ run: (ctx: never, input: TRunInput) => unknown;
523
+ }>(target: T) => void;
524
+ /**
525
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` **completes**. The new
526
+ * run's input is the {@link WorkflowLifecycleEvent} (run id, input, output, tags, search
527
+ * attributes), or what `input` builds from it. The settling workflow does not know about its
528
+ * subscribers. Exactly once per settled run: see `runCompletedEvent` in
529
+ * `@dudousxd/nestjs-durable-core`.
530
+ *
531
+ * With a class ref, the decorated workflow's `run` input is type-checked against the event (or
532
+ * against `input`'s return type, or `{ events }` of it with `batch`). Child runs publish too, so a
533
+ * workflow that `etl` starts as a child also starts its subscribers.
534
+ *
535
+ * ```ts
536
+ * @Workflow({ name: 'refresh-summaries' })
537
+ * @OnWorkflowCompleted(IngestionWorkflow, {
538
+ * where: (e) => e.input.type === 'mvr',
539
+ * input: (e) => ({ baseId: e.input.baseId }),
540
+ * debounce: { windowMs: '30s', key: (input) => input.baseId },
541
+ * })
542
+ * class RefreshSummariesWorkflow {
543
+ * async run(ctx: WorkflowCtx, input: { baseId: string }) {}
544
+ * }
545
+ * ```
546
+ */
547
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
548
+ events: TRunInput[];
549
+ }>;
550
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
551
+ declare function OnWorkflowCompleted(workflow: string, options?: OnWorkflowSettledOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
552
+ /**
553
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` ends **failed,
554
+ * cancelled or dead** (narrow it with `statuses`). Same contract as {@link OnWorkflowCompleted};
555
+ * the event carries `error` and `status` instead of `output`.
556
+ */
557
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
558
+ events: TRunInput[];
559
+ }>;
560
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
561
+ declare function OnWorkflowFailed(workflow: string, options?: OnWorkflowFailedOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
562
+ /** Metadata key for the `onEvent` coalescing `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. */
563
+ declare const ON_EVENT_BATCH_METADATA: unique symbol;
564
+ /**
565
+ * How a workflow coalesces its `onEvent` triggers: `@Workflow({ debounce | batch })`, or what its
566
+ * `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. Throws when both are set and differ, so a
567
+ * workflow never silently coalesces one way while its decorator says another.
568
+ */
569
+ declare function eventBatchOf(meta: WorkflowMeta, target: object): EventBatchConfig | undefined;
462
570
  /** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
463
571
  declare const OnEvent: typeof OnDurableEvent;
464
- /** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnDurableEvent`. */
465
- declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
572
+ /**
573
+ * All events a workflow class subscribes to: `@Workflow({ onEvent })`, `@OnDurableEvent`,
574
+ * `@OnWorkflowCompleted` and `@OnWorkflowFailed`. Repeated bare names collapse to one.
575
+ */
576
+ declare function getOnEvents(meta: WorkflowMeta, target: object): OnEventEntry[];
466
577
 
467
578
  /**
468
579
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
@@ -1109,6 +1220,10 @@ declare function inAppWorkerProviders(): Provider[];
1109
1220
  * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
1110
1221
  */
1111
1222
  declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
1223
+ /** The error `code` a responder replies with for a request it rejects as malformed or not allowed. */
1224
+ declare const BAD_RUN_REQUEST = "bad-request";
1225
+ /** The most settled runs one tenant republish reads; a larger `limit` is lowered to it. */
1226
+ declare const TENANT_REPUBLISH_MAX_LIMIT = 1000;
1112
1227
  /** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
1113
1228
  * correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
1114
1229
  * transports carry the run-request/reply protocol); the caller capability-checks before wiring
@@ -1133,20 +1248,6 @@ interface RunRequestResponderOptions {
1133
1248
  */
1134
1249
  warnWithoutVerifier?: boolean | undefined;
1135
1250
  }
1136
- /**
1137
- * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
1138
- * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
1139
- * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
1140
- * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
1141
- * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
1142
- * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
1143
- * sent. This is the security boundary of the tenant run gateway — do not weaken it.
1144
- *
1145
- * With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
1146
- * wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
1147
- * token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
1148
- * that throws becomes an error reply too.
1149
- */
1150
1251
  declare class RunRequestResponder {
1151
1252
  private readonly transport;
1152
1253
  private readonly gateway;
@@ -1156,20 +1257,34 @@ declare class RunRequestResponder {
1156
1257
  * failure never throws back into the transport (errors are captured into an error reply). */
1157
1258
  start(): void;
1158
1259
  private handle;
1260
+ /**
1261
+ * `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
1262
+ * (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
1263
+ * namespace, as the `workflowLifecycle` verb answers them.
1264
+ */
1265
+ private scopeLifecycle;
1266
+ /**
1267
+ * Why a tenant republish naming `subscriber` is refused, or undefined when it may go ahead: the
1268
+ * subscriber must be owed the event of `workflow` settling (as `kind`, when given) by a run of
1269
+ * the tenant's namespace (the gateway's `lifecycleSubscribers`, else the tenant's
1270
+ * `workflowLifecycle` links), so a tenant cannot have the event owed to an arbitrary name. Without
1271
+ * `subscriber` there is nothing to check.
1272
+ */
1273
+ private refuseSubscriber;
1159
1274
  private callVerb;
1160
1275
  }
1161
1276
 
1162
1277
  /**
1163
1278
  * An error reply from the control plane. `code` carries the reply's machine-readable reason when it
1164
1279
  * sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
1165
- * another tenant), ... — so a caller can tell an authentication failure from a real one, as with
1280
+ * another tenant), `bad-request` (the request was malformed or not allowed), ... — so a caller can tell an authentication failure from a real one, as with
1166
1281
  * Agora's proxy.
1167
1282
  */
1168
1283
  /**
1169
1284
  * The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
1170
1285
  * plane assignable without losing autocomplete on the known ones.
1171
1286
  */
1172
- type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1287
+ type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof BAD_RUN_REQUEST | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1173
1288
  declare class RunGatewayError extends Error {
1174
1289
  readonly code: RunGatewayErrorCode | undefined;
1175
1290
  constructor(message: string, code?: RunGatewayErrorCode);
@@ -1251,6 +1366,20 @@ declare class ProxyRunGateway implements RunGateway {
1251
1366
  redispatchPending(runId: string): Promise<(RunResult & {
1252
1367
  redispatched: number;
1253
1368
  }) | null>;
1369
+ /**
1370
+ * Republished on the control plane: a one-run target is checked against this tenant like
1371
+ * `retry`, a by-workflow one is read over this tenant's namespace only. A control plane too old to
1372
+ * know the verb fails it with an {@link UNSUPPORTED_RUN_REQUEST} error rather than a timeout.
1373
+ */
1374
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1375
+ /** Answered by the control plane's engine; same version-skew error as {@link republishLifecycle}. */
1376
+ workflowLifecycle(workflow: string): Promise<WorkflowLifecycleLinks>;
1377
+ /**
1378
+ * A verb with no fallback on an older control plane: its unsupported-request error, or the empty
1379
+ * `ok: true` reply the oldest responders send for an unknown verb, becomes a
1380
+ * {@link RunGatewayError} with code {@link UNSUPPORTED_RUN_REQUEST}.
1381
+ */
1382
+ private requestNewVerb;
1254
1383
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1255
1384
  }
1256
1385
 
@@ -1299,6 +1428,18 @@ declare class StoreRunGateway implements RunGateway {
1299
1428
  constructor(store: StateStore, engine: WorkflowEngine);
1300
1429
  topology(): DurableTopology;
1301
1430
  getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
1431
+ /**
1432
+ * What a run detail reads beyond the run row and its checkpoints: what this run's settling
1433
+ * started, the subscribers its lifecycle event goes to (of its namespace) and where it stands for
1434
+ * each, what started it, its workflow's lifecycle links, and the `ctx.waitForRun` waits on either
1435
+ * side of it with the other run's status. A few reads per detail: the run's own waiters while it
1436
+ * is suspended, the waiters on it (one prefix read), and one batched read of every linked run.
1437
+ */
1438
+ private lifecycleLinks;
1439
+ workflowLifecycle(workflow: string, opts?: {
1440
+ namespace?: string | undefined;
1441
+ }): Promise<WorkflowLifecycleLinks>;
1442
+ lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
1302
1443
  getRun(runId: string): Promise<WorkflowRun | null>;
1303
1444
  getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
1304
1445
  listRuns(query: RunQuery): Promise<RunListItem[]>;
@@ -1343,6 +1484,7 @@ declare class StoreRunGateway implements RunGateway {
1343
1484
  redispatchPending(runId: string): Promise<(RunResult & {
1344
1485
  redispatched: number;
1345
1486
  }) | null>;
1487
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1346
1488
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1347
1489
  }
1348
1490
 
@@ -1457,6 +1599,18 @@ declare class WorkflowService {
1457
1599
  id?: string;
1458
1600
  buffer?: boolean;
1459
1601
  }): Promise<number>;
1602
+ /**
1603
+ * The runs started by `runId` settling, through `@OnWorkflowCompleted` / `@OnWorkflowFailed` (or
1604
+ * an `onEvent` on `runCompletedEvent(...)`). Only subscribers registered on this engine are
1605
+ * considered. For the reverse link, `lifecycleSourceOf(run)` reads it from the run itself.
1606
+ */
1607
+ triggeredRuns(runId: string): Promise<string[]>;
1608
+ /**
1609
+ * Publish settled runs' lifecycle events again: to a subscriber registered after they settled, or
1610
+ * one restricted by `subscriber`. Subscribers already started for a run are not started again.
1611
+ * See `WorkflowEngine.republishLifecycle`.
1612
+ */
1613
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1460
1614
  }
1461
1615
 
1462
- export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
1616
+ export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, OnWorkflowCompleted, OnWorkflowFailed, type OnWorkflowFailedOptions, type OnWorkflowSettledOptions, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };