@nestjs/workflows 0.0.1

package/dist/events/workflow-events.service.js

@@ -0,0 +1,38 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Injectable } from '@nestjs/common';
+import { Subject } from 'rxjs';
+import { channelFor } from './workflows.channels.js';
+/**
+ * This application's lifecycle events, for logs, metrics and alerts. Every event
+ * is also published on its `node:diagnostics_channel` channel
+ * (`nestjs:workflows:<type>`), process-wide, where tracing tools (NestJS Observe,
+ * OpenTelemetry) subscribe without Nest. An instance maps onto one trace: the
+ * instance is the root span, each execution a child span, each step attempt a
+ * span inside it (https://docs.nestjs.com/reliability/workflows#events).
+ */
+let WorkflowEvents = class WorkflowEvents {
+    constructor() {
+        this.subject = new Subject();
+        this.events$ = this.subject.asObservable();
+    }
+    emit(event) {
+        const target = channelFor(event.type);
+        if (target.hasSubscribers) {
+            target.publish(event);
+        }
+        this.subject.next(event);
+    }
+    // After onModuleDestroy, where the worker drains and may still emit.
+    onApplicationShutdown() {
+        this.subject.complete();
+    }
+};
+WorkflowEvents = __decorate([
+    Injectable()
+], WorkflowEvents);
+export { WorkflowEvents };

package/dist/events/workflows.channels.d.ts

@@ -0,0 +1,3 @@
+import { type Channel } from 'node:diagnostics_channel';
+import type { WorkflowEvent } from './workflow-events.interface.js';
+export declare const channelFor: (type: WorkflowEvent['type']) => Channel;

package/dist/events/workflows.channels.js

@@ -0,0 +1,9 @@
+import { channel } from 'node:diagnostics_channel';
+const channels = new Map();
+export const channelFor = (type) => {
+    let target = channels.get(type);
+    if (!target) {
+        channels.set(type, (target = channel(`nestjs:workflows:${type}`)));
+    }
+    return target;
+};

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { WorkflowsModule } from './workflows.module.js';
+export { WORKFLOWS_MODULE_OPTIONS } from './workflows.module-definition.js';
+export type { WorkflowsModuleAsyncOptions, WorkflowsModuleOptions, WorkflowJournalLimits, WorkflowsOptionsFactory, WorkflowWorkerOptions, } from './interfaces/index.js';
+export * from './decorators/index.js';
+export { WorkflowSignal } from './signals/index.js';
+export type { ChildWorkflowHandle, Journaled, SignalWaitOptions, StartChildWorkflowOptions, WaitForSignalOptions, WorkflowAnyResult, WorkflowCompensationContext, WorkflowConcurrency, WorkflowCondition, WorkflowContext, WorkflowDecoratorOptions, WorkflowRateLimit, WorkflowRetryOptions, WorkflowRunner, WorkflowStepContext, WorkflowStepOptions, } from './interfaces/index.js';
+export type { Duration } from './core/time/index.js';
+export { WorkflowClient, WorkflowSchedules } from './services/index.js';
+export type { SignalWorkflowOptions, StartWorkflowOptions, WorkflowCancelResult, WorkflowDeleteOptions, WorkflowInstance, WorkflowJournalEntry, WorkflowListFilter, WorkflowParentClose, WorkflowPurgeOptions, WorkflowResultOptions, WorkflowRetryInstanceOptions, UpsertWorkflowScheduleOptions, WorkflowSchedule, WorkflowScheduleDeclaration, WorkflowScheduleListFilter, WorkflowScheduleMissed, WorkflowScheduleOccurrence, WorkflowScheduleOptions, WorkflowScheduleOverlap, WorkflowSchedulePreviewOptions, WorkflowSchedulePreviewSpec, WorkflowScheduleTiming, WorkflowSignalSendResult, WorkflowStartResult, WorkflowStatus, WorkflowWait, } from './interfaces/index.js';
+export { ChildWorkflowFailedError, isWorkflowInterrupt, NonRetryableStepError, StepFailedError, StepTimeoutError, WorkflowDefinitionError, WorkflowError, WorkflowFailedError, WorkflowIdConflictError, WorkflowInterrupt, WorkflowNonDeterminismError, WorkflowNotFoundError, WorkflowResultTimeoutError, WorkflowStateError, type WorkflowFailureStatus, } from './errors/index.js';
+export type { SerializedWorkflowError } from './interfaces/index.js';
+export { WorkflowEvents, type WorkflowCancelledEvent, type WorkflowChildStartedEvent, type WorkflowCompensatingEvent, type WorkflowCompensationFailedEvent, type WorkflowCompletedEvent, type WorkflowCustomStatusEvent, type WorkflowDeletedEvent, type WorkflowEvent, type WorkflowFailedEvent, type WorkflowJournalLargeEvent, type WorkflowResumedEvent, type WorkflowRetriedEvent, type WorkflowScheduleSkippedEvent, type WorkflowSignalReceivedEvent, type WorkflowSignalTimedOutEvent, type WorkflowStartedEvent, type WorkflowStepCompensatedEvent, type WorkflowStepCompletedEvent, type WorkflowStepFailedEvent, type WorkflowSuspendedEvent, } from './events/index.js';
+export { WorkflowStorage } from './storage/index.js';
+export type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowConcurrencyLimit, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowRateLimitRule, WorkflowRateWindow, WorkflowRelease, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStorageRegisterOptions, WorkflowStore, WorkflowWrite, } from './interfaces/index.js';
+export * from './stores/index.js';
+export { AesGcmPayloadCodec, type AesGcmPayloadCodecOptions } from './core/codecs/index.js';
+export type { WorkflowPayloadCodec, WorkflowPayloadContext } from './interfaces/index.js';
+export { ManualClock as ManualWorkflowClock } from './core/time/index.js';
+export type { WorkflowClock } from './interfaces/index.js';
+export { WorkflowWorker } from './services/index.js';

package/dist/index.js

@@ -0,0 +1,23 @@
+// Module
+export { WorkflowsModule } from './workflows.module.js';
+export { WORKFLOWS_MODULE_OPTIONS } from './workflows.module-definition.js';
+// Writing workflows
+export * from './decorators/index.js';
+export { WorkflowSignal } from './signals/index.js';
+// Starting, signalling, inspecting and cancelling instances, and the schedules that start them
+export { WorkflowClient, WorkflowSchedules } from './services/index.js';
+// Errors
+export { ChildWorkflowFailedError, isWorkflowInterrupt, NonRetryableStepError, StepFailedError, StepTimeoutError, WorkflowDefinitionError, WorkflowError, WorkflowFailedError, WorkflowIdConflictError, WorkflowInterrupt, WorkflowNonDeterminismError, WorkflowNotFoundError, WorkflowResultTimeoutError, WorkflowStateError, } from './errors/index.js';
+// Observability: each event is also published on its `nestjs:workflows:<type>` diagnostics channel
+export { WorkflowEvents, } from './events/index.js';
+// Storage: the interface your store implements, the registry it registers with in its
+// constructor, and the in-memory default (for development and tests, and the test double).
+// The contract's test suite is `@nestjs/workflows/testing` (lib/testing/index.ts).
+export { WorkflowStorage } from './storage/index.js';
+export * from './stores/index.js';
+// Payloads: encode (encrypt, compress) what the store keeps, with `WorkflowsModule.forRoot({ codec })`
+export { AesGcmPayloadCodec } from './core/codecs/index.js';
+// Testing: a clock that only moves when told to, and `WorkflowWorker.drain()` to run due
+// instances now (with the contract suite in `@nestjs/workflows/testing`)
+export { ManualClock as ManualWorkflowClock } from './core/time/index.js';
+export { WorkflowWorker } from './services/index.js';

package/dist/interfaces/index.d.ts

@@ -0,0 +1,13 @@
+export * from './serialized-workflow-error.interface.js';
+export * from './workflow-client.interface.js';
+export * from './workflow-clock.interface.js';
+export * from './workflow-context.interface.js';
+export * from './workflow-decorator-options.interface.js';
+export * from './workflow-instance.interface.js';
+export * from './workflow-payload-codec.interface.js';
+export * from './workflow-retry-options.interface.js';
+export * from './workflow-runner.interface.js';
+export * from './workflow-schedule.interface.js';
+export * from './workflow-storage.interface.js';
+export * from './workflow-store.interface.js';
+export * from './workflows-module-options.interface.js';

package/dist/interfaces/index.js

@@ -0,0 +1,13 @@
+export * from './serialized-workflow-error.interface.js';
+export * from './workflow-client.interface.js';
+export * from './workflow-clock.interface.js';
+export * from './workflow-context.interface.js';
+export * from './workflow-decorator-options.interface.js';
+export * from './workflow-instance.interface.js';
+export * from './workflow-payload-codec.interface.js';
+export * from './workflow-retry-options.interface.js';
+export * from './workflow-runner.interface.js';
+export * from './workflow-schedule.interface.js';
+export * from './workflow-storage.interface.js';
+export * from './workflow-store.interface.js';
+export * from './workflows-module-options.interface.js';

package/dist/interfaces/serialized-workflow-error.interface.d.ts

@@ -0,0 +1,6 @@
+import type { SerializedError } from '../core/interfaces/payload-codec.interface.js';
+/** JSON-safe form of an error, as stored in the journal and on the instance. */
+export interface SerializedWorkflowError extends SerializedError {
+    /** For `compensation_failed`: the error of the compensation that gave up. */
+    compensation?: SerializedWorkflowError;
+}

package/dist/interfaces/serialized-workflow-error.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/workflow-client.interface.d.ts

@@ -0,0 +1,156 @@
+import type { Duration } from '../core/time/duration.js';
+import type { WorkflowInstance, WorkflowStatus } from './workflow-instance.interface.js';
+export interface StartWorkflowOptions {
+    /**
+     * Instance id; default a random UUID. Starting twice with the same id (same
+     * workflow and input) returns the existing instance instead of a second one,
+     * so derive it from the business key: `order-${orderId}`. Inside a workflow
+     * step, a start without an id gets one derived from the step's
+     * `idempotencyKey`, the workflow's name and how many instances of it the step
+     * started before, so a retried step gets its instances back (with the input
+     * they were first started with) instead of starting new ones.
+     */
+    id?: string;
+    /**
+     * Pin a version (a positive integer). Default: the highest version of the
+     * workflow's name that this application registers, also when you pass a class.
+     * Starting by name a workflow this process does not register requires it.
+     */
+    version?: number;
+    /**
+     * How long the instance may run, overriding the workflow's `@Workflow(name, { timeout })`:
+     * past it, the instance compensates and ends as `failed` with a `WorkflowTimeoutError`.
+     * Counted from this call; ignored when the instance already exists.
+     */
+    timeout?: Duration;
+    /**
+     * The key the workflow's per-key concurrency limit counts the instance under, instead of the
+     * one its `concurrency.key` computes. Needs a limit with a `key`.
+     */
+    concurrencyKey?: string;
+    /**
+     * The key the workflow's per-key rate limit counts the instance under, instead of the one its
+     * `rateLimit.key` computes. Needs a rate limit with a `key`.
+     */
+    rateLimitKey?: string;
+    /**
+     * Lower runs first: an integer from 1 to 2,097,151. Due instances are claimed by priority, then most
+     * overdue first; instances without one go before every prioritized one. The instance keeps it for every
+     * execution (each resumption waits its turn by it), and its children inherit it. Default: none.
+     */
+    priority?: number;
+    /**
+     * Your ORM's transaction: the `tx` (or `EntityManager`, `Transaction`...) your transaction
+     * callback receives. The instance is created in it, so it exists if and only if your
+     * transaction commits, together with the rows you wrote. The worker picks it up after the
+     * commit, at its next poll. Needs a store on your database that implements
+     * `createInTransaction()`.
+     */
+    transaction?: unknown;
+}
+export interface SignalWorkflowOptions {
+    /** Correlation key: only waits with the same key take the signal. */
+    key?: string;
+    /**
+     * Deduplication id, unique per signal name, such as the id of the message or event that
+     * causes the signal. A signal with the same name and id stored earlier makes this call a
+     * no-op that returns that signal's `signalId` with `created: false`: a sender that runs
+     * again (a redelivered message, a retried job) stores its signal once, and the first payload
+     * wins. The same name and id with a different key throws `WorkflowIdConflictError`.
+     * Inside a workflow step, a signal sent without an id gets one derived from the step's
+     * `idempotencyKey`, so a retried step doesn't send it again.
+     */
+    id?: string;
+    /**
+     * Your ORM's transaction, as for `start()`: the signal, and the wake-up of the instances
+     * waiting for it, commit with your writes. Signals queue behind it until it ends, so keep
+     * it short. On PostgreSQL it must be READ COMMITTED (the default).
+     */
+    transaction?: unknown;
+}
+/** What `result()` and `startAndWait()` take. */
+export interface WorkflowResultOptions {
+    /**
+     * How long to wait. Past it, the call rejects with `WorkflowResultTimeoutError`, and the
+     * instance keeps running. Wall-clock time, not the module's clock. Default: no limit.
+     */
+    timeout?: Duration;
+    /** Stops waiting once aborted (a client that went away), rejecting with the signal's reason. */
+    signal?: AbortSignal;
+}
+/** What `signal()` returns. */
+export interface WorkflowSignalSendResult {
+    /** The stored signal's id: the new one, or with `created: false` the one stored earlier with the same `id`. */
+    signalId: number;
+    /** Instances parked on a matching wait that this call woke. */
+    woken: number;
+    /** `false` if a signal with the same name and `id` was stored earlier: nothing was written. */
+    created: boolean;
+}
+/** What `start()` returns: safe to send to a client (no input, no lease details). */
+export interface WorkflowStartResult {
+    id: string;
+    workflow: string;
+    version: number;
+    /** False if an instance with this id already existed. */
+    created: boolean;
+    status: WorkflowStatus;
+}
+export interface WorkflowCancelResult extends WorkflowInstance {
+    /**
+     * True if this call requested the cancellation. False if the instance was
+     * already compensating or had finished, or a cancel was already requested
+     * (the first reason is kept). For `terminate()`: false if the instance had
+     * finished or a terminate was already requested.
+     */
+    accepted: boolean;
+}
+export interface WorkflowListFilter {
+    status?: WorkflowStatus | WorkflowStatus[];
+    /** Workflow name. */
+    workflow?: string;
+    /** With `workflow`: only instances on this version (to see whether an old version has drained). */
+    version?: number;
+    /** Only the children this instance started with `ctx.startChild()`. */
+    parentId?: string;
+    /** Only the instances this schedule started. */
+    scheduleId?: string;
+    /** Default 100. */
+    limit?: number;
+    offset?: number;
+}
+/** What `purge()` takes. */
+export interface WorkflowPurgeOptions {
+    /**
+     * How long finished instances are kept, such as `'30d'`: instances that finished longer ago
+     * go, with their journals, and so do signals older than this that no unfinished instance can
+     * take, and rate-limit windows that ended that long ago. A signal's `id` deduplicates until its
+     * signal is purged, so keep this longer than any sender's redelivery window, and longer than
+     * your longest transaction.
+     */
+    olderThan: Duration;
+    /**
+     * The finished statuses to purge. Default `completed`, `failed` and `cancelled`:
+     * `compensation_failed` instances wait for a person, so they go only when listed.
+     */
+    status?: WorkflowStatus | WorkflowStatus[];
+    /** Instances, and signals, deleted per statement. Default 500. */
+    batchSize?: number;
+}
+/** What `retry()` takes. */
+export interface WorkflowRetryInstanceOptions {
+    /**
+     * A new run timeout, counted from now; `false` removes it. Required to retry a `failed`
+     * instance whose deadline has passed, which would otherwise time out again at once. Default:
+     * the deadline it has.
+     */
+    timeout?: Duration | false;
+}
+/** What `delete()` takes. */
+export interface WorkflowDeleteOptions {
+    /**
+     * Delete an unfinished instance too, without running its compensations. A worker running it
+     * stops recording at its next write. Default `false`: only finished instances.
+     */
+    force?: boolean;
+}

package/dist/interfaces/workflow-client.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/workflow-clock.interface.d.ts

@@ -0,0 +1,7 @@
+import type { Clock } from '../core/interfaces/clock.interface.js';
+/**
+ * Every timestamp the engine reads (sleep deadlines, signal timeouts, retry
+ * times, lease expiry, `ctx.now()`) comes from this clock, so tests can move
+ * time without fake timers.
+ */
+export type WorkflowClock = Clock;

package/dist/interfaces/workflow-clock.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/workflow-context.interface.d.ts

@@ -0,0 +1,241 @@
+import type { Type } from '@nestjs/common';
+import type { Duration } from '../core/time/duration.js';
+import type { WorkflowParentClose } from './workflow-instance.interface.js';
+import type { WorkflowInput, WorkflowOutput } from './workflow-runner.interface.js';
+import type { SerializedWorkflowError } from './serialized-workflow-error.interface.js';
+import type { WorkflowSignal } from '../signals/workflow.signal.js';
+import type { WorkflowRetryOptions } from './workflow-retry-options.interface.js';
+import type { WorkflowScheduleOccurrence } from './workflow-schedule.interface.js';
+/**
+ * What a journaled value looks like after its JSON round-trip: step results,
+ * signal payloads and checkpoints come back this way on the first run and on
+ * every replay (a `Date` is a string, methods and `undefined` fields are gone,
+ * `undefined` in an array is `null`, a `Map` or `Set` is `{}`).
+ */
+export type Journaled<T> = unknown extends T ? T : T extends {
+    toJSON(...args: any[]): infer R;
+} ? Journaled<R> : T extends string | number | boolean | null | undefined | void ? T : T extends bigint | symbol | ((...args: any[]) => unknown) ? never : T extends ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> ? Record<string, never> : T extends readonly unknown[] ? {
+    [K in keyof T]: JournaledElement<T[K]>;
+} : {
+    [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: Journaled<T[K]>;
+};
+/** In arrays, `JSON.stringify` writes `undefined`, functions and symbols as `null`. */
+type JournaledElement<T> = T extends undefined | void | symbol | ((...args: any[]) => unknown) ? null : Journaled<T>;
+/** Handed to every step (and compensation) attempt. */
+export interface WorkflowStepContext<P = unknown> {
+    /**
+     * `${workflowId}:${stepName}`. Identical for every attempt and every worker
+     * that runs this step, so pass it to the API you call (`Idempotency-Key`,
+     * a unique column) to make the side effect exactly-once.
+     */
+    readonly idempotencyKey: string;
+    /** 1 for the first attempt. Interrupted attempts (crash, lost lease) count. */
+    readonly attempt: number;
+    /** Aborted on shutdown, on a lost lease, and on `timeout`/`heartbeatTimeout`. */
+    readonly signal: AbortSignal;
+    /**
+     * The last value passed to `heartbeat(progress)` by an earlier attempt of
+     * this step, or `undefined`. Type it by annotating the step function's
+     * parameter: `async ({ progress }: WorkflowStepContext<Checkpoint>) => ...`.
+     */
+    readonly progress: Journaled<P> | undefined;
+    /**
+     * Proves the step is alive (resets `heartbeatTimeout`). With an argument,
+     * the value is also checkpointed to the journal and handed to the next
+     * attempt as `progress` if this one dies.
+     */
+    heartbeat(progress?: P): Promise<void>;
+}
+export interface WorkflowCompensationContext extends WorkflowStepContext {
+    /** Why the workflow is being compensated. */
+    readonly reason: SerializedWorkflowError;
+}
+export interface WorkflowStepOptions<T> {
+    /** Default: the module's `retry` (3 attempts, 1s doubling up to 5m). */
+    retry?: number | false | WorkflowRetryOptions;
+    /** Fail the attempt (retryably) after this long. */
+    timeout?: Duration;
+    /** Fail the attempt (retryably) if `heartbeat()` is not called this often. */
+    heartbeatTimeout?: Duration;
+    /**
+     * Undo this step, once it completed, if the workflow later fails or is
+     * cancelled. Compensations run in reverse order of the `ctx.step()` calls
+     * (parallel steps included), each one journaled and retried like a step. Its
+     * return value is discarded. A later `ctx.commit()` discards it.
+     */
+    compensate?: (result: Journaled<T>, ctx: WorkflowCompensationContext) => unknown;
+    /** How `compensate` retries. Default: the step's `retry`, else the module's. */
+    compensateRetry?: number | false | WorkflowRetryOptions;
+}
+export interface WaitForSignalOptions<T> {
+    /**
+     * Correlation key: only signals sent with the same key match (see
+     * `WorkflowClient.signal()`). Without one, the wait only matches signals sent
+     * without a key.
+     */
+    key?: string;
+    /** Extra filter over the payload. Must be a pure function of it. */
+    match?: (payload: Journaled<T>) => boolean;
+    /** Resolve with `null` if no matching signal was sent before this deadline. */
+    timeout?: Duration;
+}
+declare const conditionValue: unique symbol;
+/**
+ * Something `ctx.waitForAny()` waits for, made by `ctx.signalWait()` or `ctx.timer()`, or a
+ * child's handle (`ctx.startChild()`). Only a
+ * description: nothing is waited for, and nothing journaled, until it is passed to `waitForAny()`.
+ */
+export interface WorkflowCondition<T = unknown> {
+    /** Type-only: the `value` `waitForAny()` returns when this condition wins. Never set at runtime. */
+    readonly [conditionValue]?: T;
+}
+/** What `ctx.startChild()` and `ctx.executeChild()` take. */
+export interface StartChildWorkflowOptions {
+    /**
+     * The child's id. Default: `${parentId}/${workflow}#${n}`, where `n` counts the children of
+     * that workflow this run started before it, so a replay gets the same child back. The id also
+     * names the journal entry: pass one (derived from your data) for children started from
+     * parallel branches, which can reach `startChild()` in another order on a replay.
+     */
+    id?: string;
+    /** Pin a version, as in `WorkflowClient.start()`. Default: the highest this application registers. */
+    version?: number;
+    /** The child's run timeout, overriding its `@Workflow(name, { timeout })`. */
+    timeout?: Duration;
+    /**
+     * What happens to the child if it is still running when this instance ends (completes,
+     * fails, is cancelled or terminated), or starts compensating: `'cancel'` (the default)
+     * cancels it, and its compensations run; `'terminate'` stops it without compensating;
+     * `'abandon'` leaves it running on its own.
+     */
+    parentClose?: WorkflowParentClose;
+    /** As in `WorkflowClient.start()`: the child's key for its workflow's per-key concurrency limit. */
+    concurrencyKey?: string;
+    /** As in `WorkflowClient.start()`: the child's key for its workflow's per-key rate limit. */
+    rateLimitKey?: string;
+    /** As in `WorkflowClient.start()`. Default: this instance's priority. */
+    priority?: number;
+}
+/** A started child workflow (`ctx.startChild()`). Also a condition for `ctx.waitForAny()`. */
+export interface ChildWorkflowHandle<O = unknown> extends WorkflowCondition<Journaled<O>> {
+    readonly id: string;
+    readonly workflow: string;
+    readonly version: number;
+    /**
+     * Durable wait for the child to end: resolves with its output, or throws a
+     * `ChildWorkflowFailedError` (with the child's status and error) if it failed, was cancelled
+     * or terminated. Journaled, like a signal wait. Calling it again returns the same promise.
+     */
+    result(): Promise<Journaled<O>>;
+}
+/** What `ctx.signalWait()` takes: `waitForSignal()`'s options, without a timeout (race a `ctx.timer()` instead). */
+export type SignalWaitOptions<T> = Omit<WaitForSignalOptions<T>, 'timeout'>;
+/**
+ * What `ctx.waitForAny(name, conditions)` resolves with: the key of the condition that won, and
+ * its value, typed per key (check `key` to narrow `value`).
+ */
+export type WorkflowAnyResult<C extends Record<string, WorkflowCondition<unknown>>> = {
+    [K in keyof C & string]: {
+        key: K;
+        value: C[K] extends WorkflowCondition<infer T> ? T : never;
+    };
+}[keyof C & string];
+/**
+ * The API a workflow's `run()` receives. `run()` executes again from the top every time an instance
+ * resumes: https://docs.nestjs.com/reliability/workflows#rules-for-workflow-code.
+ */
+export interface WorkflowContext {
+    readonly workflowId: string;
+    readonly workflowName: string;
+    readonly version: number;
+    /** The schedule occurrence that started this instance (`{ id, at }`: the schedule's id and the occurrence's time), or `null`. */
+    readonly schedule: WorkflowScheduleOccurrence | null;
+    /**
+     * Runs `fn` once and journals its result; replays return the journaled
+     * result without running it. `name` is unique per run and part of the
+     * contract with running instances. Don't call `ctx` methods inside `fn`.
+     */
+    step<T, P = unknown>(name: string, fn: (ctx: WorkflowStepContext<P>) => T | Promise<T>, options?: WorkflowStepOptions<T>): Promise<Journaled<T>>;
+    /** Durable timer. The instance is parked and resumed by any worker after the deadline. */
+    sleep(name: string, duration: Duration | {
+        until: Date | number;
+    }): Promise<void>;
+    /**
+     * Durable wait for a signal sent with `WorkflowClient.signal()`, including
+     * one sent after the instance started but before it reached this wait.
+     * Resolves with the payload, or `null` once `timeout` passes (compare with
+     * `=== null` when the payload itself can be falsy).
+     */
+    waitForSignal<T>(name: string, signal: WorkflowSignal<T> | string, options?: WaitForSignalOptions<T>): Promise<Journaled<T> | null>;
+    /**
+     * Durable wait for whichever of several conditions happens first: a signal
+     * (`ctx.signalWait()`), a timer (`ctx.timer()`) or a child's end (its handle). Resolves with the
+     * key of the winner and its value (a signal's payload, `null` for a timer, a child's output; a
+     * child that failed throws its `ChildWorkflowFailedError`), journaled under `name` as one entry, so a
+     * replay returns the same winner. Only the winning signal is taken: a signal that matched
+     * another condition stays for a later wait. When several are ready at once, the earliest
+     * signal (lowest id) wins, then the earliest timer; a signal sent after a timer's deadline
+     * doesn't count. Timers count from when the wait is first reached.
+     *
+     * ```ts
+     * const outcome = await ctx.waitForAny('delivery-or-cancel', {
+     *   delivered: ctx.signalWait(shipmentDelivered, { key: order.id }),
+     *   cancelled: ctx.signalWait(orderCancelled, { key: order.id }),
+     *   timeout: ctx.timer('3d'),
+     * });
+     * if (outcome.key === 'delivered') {
+     *   await ctx.step('thank', () => this.mail.thank(order, outcome.value));
+     * }
+     * ```
+     *
+     * To wait for all of several signals, await several `waitForSignal()` calls with
+     * `Promise.all()`: each is journaled on its own, and the instance parks once for all of them.
+     */
+    waitForAny<C extends Record<string, WorkflowCondition<unknown>>>(name: string, conditions: C): Promise<WorkflowAnyResult<C>>;
+    /**
+     * Starts a child instance of another workflow, linked to this one: `getStatus()` shows the
+     * link, `list({ parentId })` finds the children, and `parentClose` decides what happens to a
+     * child still running when this instance ends. Journaled: a replay returns the same child
+     * instead of starting another. Resolves with a handle to wait for the child's result.
+     * Starting a child with an id that another workflow, another parent or another input already
+     * uses throws `WorkflowIdConflictError`.
+     */
+    startChild<W>(workflow: Type<W> | string, input: WorkflowInput<W>, options?: StartChildWorkflowOptions): Promise<ChildWorkflowHandle<WorkflowOutput<W>>>;
+    /** `startChild()`, then its handle's `result()`. */
+    executeChild<W>(workflow: Type<W> | string, input: WorkflowInput<W>, options?: StartChildWorkflowOptions): Promise<Journaled<WorkflowOutput<W>>>;
+    /** A signal for `waitForAny()`: its value is the payload. */
+    signalWait<T>(signal: WorkflowSignal<T> | string, options?: SignalWaitOptions<T>): WorkflowCondition<Journaled<T>>;
+    /** A durable timer for `waitForAny()`: `duration` after the wait is first reached, or at `until`. Its value is `null`. */
+    timer(duration: Duration | {
+        until: Date | number;
+    }): WorkflowCondition<null>;
+    /**
+     * Journaled `Date.now()`: the same value on every replay. Helpers are
+     * numbered in call order, so call them from sequential code, not from
+     * parallel branches that reach them in a different order on a replay.
+     */
+    now(): number;
+    /** Journaled `Math.random()`. */
+    random(): number;
+    /** Journaled `crypto.randomUUID()`. */
+    uuid(): string;
+    /**
+     * Point of no return. Compensations of the steps called before it are
+     * discarded: a later failure or cancel runs only the compensations of steps
+     * called after it. Journaled under `name`, so it replays like a step and
+     * shows in `getStatus(id, { journal: true })`.
+     */
+    commit(name: string): void;
+    /**
+     * Sets the instance's custom status, a JSON value of up to 16 KiB that the outside world
+     * reads as `WorkflowClient.getStatus(id).customStatus` (a progress report, the stage an
+     * order is in). It is written with the instance's next journal write, suspension or end,
+     * and emitted as a `custom-status` event then. Every execution replays `run()`, and with it
+     * the `setStatus()` calls, so the status needs no journal entry of its own and is never
+     * read back by the workflow. `undefined` clears it (`null`).
+     */
+    setStatus(status: unknown): void;
+    /** Fail the instance on purpose. Compensations run (only those after a `commit()`). */
+    fail(message: string): never;
+}
+export {};

package/dist/interfaces/workflow-context.interface.js

@@ -0,0 +1 @@
+export {};