@nestjs/workflows 0.0.1

package/dist/services/workflow-execution.service.d.ts

@@ -0,0 +1,267 @@
+import { type Type } from '@nestjs/common';
+import type { LeasedRun } from '../core/interfaces/leased-worker-options.interface.js';
+import type { WorkflowClock } from '../interfaces/workflow-clock.interface.js';
+import { type Duration } from '../core/time/duration.js';
+import type { SerializedWorkflowError } from '../interfaces/serialized-workflow-error.interface.js';
+import type { WorkflowContext } from '../interfaces/workflow-context.interface.js';
+import type { WorkflowInstance, WorkflowJournalEntry, WorkflowStatus, WorkflowWait } from '../interfaces/workflow-instance.interface.js';
+import type { WorkflowMetadata } from '../interfaces/workflow-decorator-options.interface.js';
+import type { ResolvedRetry } from '../core/interfaces/retry-settings.interface.js';
+import type { WorkflowJournalLimits } from '../interfaces/workflows-module-options.interface.js';
+import type { WorkflowEvents } from '../events/workflow-events.service.js';
+import type { NewWorkflowInstance } from '../interfaces/workflow-store.interface.js';
+import type { WorkflowInstanceStore } from '../storage/encoded-workflow.store.js';
+/** An instance under a worker's lease. */
+export interface ClaimedWorkflowInstance extends WorkflowInstance {
+    leaseToken: string;
+}
+/** One entry per name, as the store expects: the last version of each, in the order the names first appear. */
+export declare function uniqueEntries<T extends {
+    name: string;
+}>(entries: T[]): T[];
+export interface ExecutionDeps {
+    store: WorkflowInstanceStore;
+    /** The workflow `ctx.startChild()` starts: its name, version and run timeout (`WorkflowRegistry.resolve()`). */
+    resolve(workflow: Type<unknown> | string, version?: number): WorkflowMetadata;
+    /**
+     * Creates a child, or finds the one an interrupted execution created, and throws
+     * `WorkflowIdConflictError` if the id holds another instance.
+     */
+    createChild(instance: NewWorkflowInstance): Promise<WorkflowInstance>;
+    clock: WorkflowClock;
+    events: WorkflowEvents;
+    defaultRetry: ResolvedRetry;
+    journalLimits: Required<WorkflowJournalLimits>;
+}
+export type RunOutcome = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: unknown;
+};
+export type CompensationOutcome = {
+    state: 'done';
+    count: number;
+} | {
+    state: 'suspended';
+    wakeAt: number | null;
+} | {
+    state: 'failed';
+    error: SerializedWorkflowError;
+} | {
+    state: 'interrupted';
+} | {
+    state: 'terminated';
+};
+/**
+ * What `ctx.signalWait()` and `ctx.timer()` make for `ctx.waitForAny()`: a description of what to
+ * wait for, and how the winner's journaled payload becomes its value.
+ */
+export declare class Condition {
+    readonly wait: WorkflowWait | null;
+    readonly match: ((payload: any) => boolean) | undefined;
+    readonly timer: Duration | {
+        until: Date | number;
+    } | undefined;
+    readonly settle: (payload: unknown) => unknown;
+    private constructor();
+    static signal(wait: WorkflowWait, match?: (payload: any) => boolean, settle?: (payload: unknown) => unknown): Condition;
+    static timer(when: Duration | {
+        until: Date | number;
+    }): Condition;
+}
+/** What a child sends its parent when it ends (`CHILD_ENDED_SIGNAL`). */
+export interface ChildEnded {
+    status: WorkflowStatus;
+    output?: unknown;
+    error?: SerializedWorkflowError | null;
+}
+/** `ChildWorkflowHandle`: waits for the child's end, once per execution, as `result()` or as a `waitForAny()` condition. */
+export declare class ChildHandle {
+    readonly id: string;
+    readonly workflow: string;
+    readonly version: number;
+    private readonly wait;
+    readonly condition: Condition;
+    private outcome?;
+    private waiting?;
+    constructor(id: string, workflow: string, version: number, wait: (handle: ChildHandle) => Promise<unknown>);
+    result(): Promise<unknown>;
+    /** The child's output, from its journaled end, or its failure, thrown. Kept, so a later `result()` returns it. */
+    settle(payload: unknown): unknown;
+}
+/**
+ * One execution of a workflow instance: runs `run()` from the top against the
+ * journal loaded at claim time.
+ *
+ * - A journaled step returns its stored result (or re-throws its stored
+ *   failure) without running.
+ * - The first step that is not journaled is the frontier. Before it runs, the
+ *   execution lets the replay settle and checks that every journaled entry was
+ *   reached. If one was not, the code changed under a running instance and the
+ *   instance fails instead of re-running a renamed side effect.
+ * - A pending sleep, wait or retry backoff records a suspension and throws
+ *   `WorkflowInterrupt`. After that no new step starts and nothing new is
+ *   journaled except other sleeps and waits of the same `Promise.all`; the
+ *   engine parks the instance once in-flight steps settle.
+ * - A cancel, shutdown, lost lease or store failure also throws
+ *   `WorkflowInterrupt`, and decides the outcome whatever `run()` does with it:
+ *   swallowing or wrapping it can't complete the instance.
+ * - In replay-only mode (compensating or cancelling after a restart) nothing
+ *   new runs: the replay only rebuilds the list of compensations.
+ */
+export declare class WorkflowExecution {
+    readonly instance: ClaimedWorkflowInstance;
+    /** Highest signal id visible to this execution's waits. */
+    readonly signalCursor: number;
+    private readonly deps;
+    /** The worker's run of this instance: its lease, renewed on a heartbeat, and a signal for a lost lease or a shutdown. */
+    private readonly lease;
+    readonly context: WorkflowContext;
+    readonly journal: Map<string, WorkflowJournalEntry>;
+    readonly abort: AbortController;
+    suspension: {
+        wakeAt: number | null;
+        waits: WorkflowWait[];
+    } | null;
+    fatal: Error | null;
+    /** Why the journal limit stopped the run, once it did. */
+    journalLimitError: SerializedWorkflowError | null;
+    leaseLost: boolean;
+    storeError: unknown;
+    shuttingDown: boolean;
+    cancelRequested: boolean;
+    /** A terminate was requested: stop compensating too. */
+    terminateRequested: boolean;
+    /** Attempt counters to restore when a shutdown interrupts an attempt. */
+    readonly rollbacks: WorkflowJournalEntry[];
+    private mode;
+    private userSettled;
+    private buffer;
+    private frontier?;
+    private readonly visited;
+    private readonly compensations;
+    private readonly inflight;
+    private readonly consumed;
+    /** The last journal write issued; the next one waits for it (see `write()`). */
+    private writes;
+    private readonly counters;
+    /** Children started so far in this run, per workflow name: the default child ids. */
+    private readonly childCounters;
+    /** The first interrupt that stops this execution (not a suspension). */
+    private stoppedBy;
+    /** The step whose function is running, in that function's async context. */
+    private readonly insideStep;
+    /** Each journal entry's size in bytes, by name, and their sum. */
+    private readonly entrySizes;
+    private journalBytes;
+    /** Whether the journal is past the warning line: it warns once, when it crosses it. */
+    private journalLarge;
+    /** The last `ctx.setStatus()` value, and the stored one (canonical JSON). */
+    private customStatus;
+    private storedStatus;
+    private static readonly logger;
+    constructor(instance: ClaimedWorkflowInstance, journal: WorkflowJournalEntry[], 
+    /** Highest signal id visible to this execution's waits. */
+    signalCursor: number, deps: ExecutionDeps, 
+    /** The worker's run of this instance: its lease, renewed on a heartbeat, and a signal for a lost lease or a shutdown. */
+    lease: LeasedRun, replayOnly: boolean);
+    /** Runs the user's `run()` and waits for every step it started. */
+    run(fn: () => Promise<unknown>): Promise<RunOutcome>;
+    /** Journal entries that this execution never reached (compensations and retry records excluded). */
+    unvisited(): string[];
+    /** Staged entries (sleeps, helpers) not yet written; the engine commits them. */
+    drainBuffer(): WorkflowJournalEntry[];
+    requestShutdown(): void;
+    /** Past the shutdown timeout, the worker stopped waiting for it: never touch the store again. */
+    get detached(): boolean;
+    /**
+     * Extends the lease, for `WorkflowStepContext.heartbeat()` (the worker renews it on its own heartbeat too). The
+     * worker hands the execution the cancel and terminate requests the renewal reads.
+     */
+    renew(): Promise<void>;
+    /** Runs registered compensations in reverse order, each as a journaled, retried step. */
+    compensate(reason: SerializedWorkflowError): Promise<CompensationOutcome>;
+    private step;
+    private sleep;
+    /** `waitForSignal()`, and (`internal`) a child handle's `result()`, whose wait is named `$result:<id>`. */
+    private receive;
+    private startChild;
+    private handle;
+    /** Whether this instance started children, whose `parentClose` applies when it ends. */
+    hasChildren(): boolean;
+    private waitForAny;
+    /** Signals sent since the instance started, up to this execution's cursor: one that arrived before the wait was reached still counts. */
+    private signalsFor;
+    /** The first of `candidates` a wait can take: not taken by another wait, sent by `deadline`, and matching. */
+    private peek;
+    /** `peek()`, and marks the signal taken. Call it with no `await` between the read and the take. */
+    private take;
+    private commit;
+    private setStatus;
+    /** `{ customStatus }` when `ctx.setStatus()` changed it since it was last written, else `{}`: spread into a write. */
+    statusChange(): {
+        customStatus?: unknown;
+    };
+    /** After a write that carried `change` landed. */
+    statusWritten(change: {
+        customStatus?: unknown;
+    }): void;
+    /**
+     * Entries still pending when the instance ends without completing: a sleep
+     * or wait that will never resolve, a retry that will never run.
+     */
+    abandoned(): WorkflowJournalEntry[];
+    private helper;
+    /**
+     * Resolves a step's (or compensation's) retry and timeouts. Throws a
+     * `TypeError` for invalid options before an attempt is recorded, instead of
+     * spending the step's attempts on it.
+     */
+    private plan;
+    private attempt;
+    private invoke;
+    private giveUp;
+    private track;
+    /**
+     * A step's function runs once; its result is all a replay sees. A `ctx` call
+     * made inside it would be journaled on the first run and missing on every
+     * replay, so it is a definition error, reported where it happens.
+     */
+    private assertNotInStep;
+    private visit;
+    /**
+     * Before the first new step runs, let every replayable call happen (replayed
+     * results resolve in microtasks, so one macrotask is enough), then require
+     * that the whole journal was reached.
+     */
+    private reachFrontier;
+    /** Reserves the step's compensation in call order; `arm()` it with the result once the step completed. */
+    private reserveCompensation;
+    private assertAlive;
+    /** Whether the instance's run timeout has passed. */
+    pastDeadline(): boolean;
+    /** No new step starts once the execution is suspending or `run()` has settled. */
+    private assertCanStart;
+    private suspendUntil;
+    private stage;
+    /** Keeps `entry` as the journal's entry of its name, and tracks the journal's size. */
+    private record;
+    private measure;
+    private pastWarning;
+    /**
+     * Before a new name is journaled in run mode: a journal at its limit stops the run, which then
+     * compensates (compensations may still record their entries) and fails.
+     */
+    private assertJournalRoom;
+    /** Fenced write of staged entries plus `entries`. */
+    private write;
+    private loseLease;
+    private abortInterrupt;
+    /** Every interrupt `ctx` throws goes through here; the first one that stops the run is kept. */
+    private interrupt;
+    private setFatal;
+    private describe;
+    private emit;
+}