@bluelibs/runner 5.1.0 → 5.2.1

package/dist/types/node/durable/core/StepBuilder.d.ts

@@ -0,0 +1,23 @@
+import type { IStepBuilder, StepOptions } from "./interfaces/context";
+import type { DurableContext } from "./DurableContext";
+/**
+ * Fluent helper for building a durable step.
+ *
+ * This is the ergonomic layer behind `ctx.step("id")`:
+ * - `up()` defines the memoized computation
+ * - `down()` registers a compensation to be invoked by `ctx.rollback()`
+ *
+ * It is `PromiseLike`, so users can `await ctx.step("x").up(...).down(...)`.
+ */
+export declare class StepBuilder<T> implements IStepBuilder<T> {
+    private readonly context;
+    private readonly stepId;
+    private readonly options;
+    private upFn?;
+    private downFn?;
+    constructor(context: DurableContext, stepId: string, options?: StepOptions);
+    up(fn: () => Promise<T>): this;
+    down(fn: (result: T) => Promise<void>): this;
+    private execute;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
+}

package/dist/types/node/durable/core/audit.d.ts

@@ -0,0 +1,152 @@
+import type { ExecutionStatus } from "./types";
+export declare const DurableAuditEntryKind: {
+    readonly ExecutionStatusChanged: "execution_status_changed";
+    readonly StepCompleted: "step_completed";
+    readonly SleepScheduled: "sleep_scheduled";
+    readonly SleepCompleted: "sleep_completed";
+    readonly SignalWaiting: "signal_waiting";
+    readonly SignalDelivered: "signal_delivered";
+    readonly SignalTimedOut: "signal_timed_out";
+    readonly EmitPublished: "emit_published";
+    readonly SwitchEvaluated: "switch_evaluated";
+    readonly Note: "note";
+};
+export type DurableAuditEntryKind = (typeof DurableAuditEntryKind)[keyof typeof DurableAuditEntryKind];
+export interface DurableAuditEntryBase {
+    id: string;
+    executionId: string;
+    at: Date;
+    kind: DurableAuditEntryKind;
+    attempt: number;
+    taskId?: string;
+}
+export type DurableAuditEntry = (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.ExecutionStatusChanged;
+    from: ExecutionStatus | null;
+    to: ExecutionStatus;
+    reason?: string;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.StepCompleted;
+    stepId: string;
+    durationMs: number;
+    isInternal: boolean;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.SleepScheduled;
+    stepId: string;
+    timerId: string;
+    durationMs: number;
+    fireAt: Date;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.SleepCompleted;
+    stepId: string;
+    timerId: string;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.SignalWaiting;
+    stepId: string;
+    signalId: string;
+    timeoutMs?: number;
+    timeoutAtMs?: number;
+    timerId?: string;
+    reason?: "initial" | "timeout_armed";
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.SignalDelivered;
+    stepId: string;
+    signalId: string;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.SignalTimedOut;
+    stepId: string;
+    signalId: string;
+    timerId: string;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.EmitPublished;
+    stepId: string;
+    eventId: string;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.SwitchEvaluated;
+    stepId: string;
+    branchId: string;
+    durationMs: number;
+}) | (DurableAuditEntryBase & {
+    kind: typeof DurableAuditEntryKind.Note;
+    message: string;
+    meta?: Record<string, unknown>;
+});
+/**
+ * Input type for appendAuditEntry - omits auto-generated fields (id, at).
+ * Preserves the discriminated union for proper type checking at call sites.
+ * executionId and attempt are required for service-level entries but filled by context.
+ */
+export type DurableAuditEntryInput = {
+    kind: typeof DurableAuditEntryKind.ExecutionStatusChanged;
+    executionId: string;
+    attempt: number;
+    from: ExecutionStatus | null;
+    to: ExecutionStatus;
+    reason?: string;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.StepCompleted;
+    stepId: string;
+    durationMs: number;
+    isInternal: boolean;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.SleepScheduled;
+    stepId: string;
+    timerId: string;
+    durationMs: number;
+    fireAt: Date;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.SleepCompleted;
+    executionId: string;
+    attempt: number;
+    stepId: string;
+    timerId: string;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.SignalWaiting;
+    stepId: string;
+    signalId: string;
+    timeoutMs?: number;
+    timeoutAtMs?: number;
+    timerId?: string;
+    reason?: "initial" | "timeout_armed";
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.SignalDelivered;
+    executionId: string;
+    attempt: number;
+    stepId: string;
+    signalId: string;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.SignalTimedOut;
+    executionId: string;
+    attempt: number;
+    stepId: string;
+    signalId: string;
+    timerId: string;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.EmitPublished;
+    stepId: string;
+    eventId: string;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.SwitchEvaluated;
+    stepId: string;
+    branchId: string;
+    durationMs: number;
+    taskId?: string;
+} | {
+    kind: typeof DurableAuditEntryKind.Note;
+    message: string;
+    meta?: Record<string, unknown>;
+    taskId?: string;
+};
+export interface DurableAuditEmitter {
+    emit(entry: DurableAuditEntry): Promise<void>;
+}
+export declare function isDurableInternalStepId(stepId: string): boolean;
+export declare function createDurableAuditEntryId(atMs?: number): string;

package/dist/types/node/durable/core/createRunnerDurableRuntime.d.ts

@@ -0,0 +1,18 @@
+import type { DurableServiceConfig } from "./interfaces/service";
+import { DurableResource } from "./DurableResource";
+import type { EventManager } from "../../../models/EventManager";
+import type { TaskRunner } from "../../../models/TaskRunner";
+import type { Store } from "../../../models/Store";
+export type RunnerDurableRuntimeConfig = Omit<DurableServiceConfig, "taskExecutor" | "tasks" | "taskResolver" | "contextProvider"> & {
+    /**
+     * Starts an embedded worker (queue consumer) in this process.
+     * Has effect only when `queue` is configured.
+     */
+    worker?: boolean;
+};
+export interface RunnerDurableDeps {
+    taskRunner: TaskRunner;
+    eventManager: EventManager;
+    runnerStore: Store;
+}
+export declare function createRunnerDurableRuntime(config: RunnerDurableRuntimeConfig, deps: RunnerDurableDeps): Promise<DurableResource>;

package/dist/types/node/durable/core/durable-context/DurableContext.audit.d.ts

@@ -0,0 +1,14 @@
+import type { IDurableStore } from "../interfaces/store";
+import { type DurableAuditEmitter, type DurableAuditEntryInput } from "../audit";
+export type DurableContextAudit = {
+    /** True if we have at least one sink (store persistence and/or emitter). */
+    isEnabled: () => boolean;
+    append: (entry: DurableAuditEntryInput) => Promise<void>;
+};
+export declare function createDurableContextAudit(params: {
+    store: IDurableStore;
+    executionId: string;
+    attempt: number;
+    enabled: boolean;
+    emitter: DurableAuditEmitter | null;
+}): DurableContextAudit;

package/dist/types/node/durable/core/durable-context/DurableContext.determinism.d.ts

@@ -0,0 +1,13 @@
+export type ImplicitInternalStepIdKind = "sleep" | "emit" | "waitForSignal";
+export type ImplicitInternalStepIdsPolicy = "allow" | "warn" | "error";
+export type DurableContextDeterminism = {
+    assertOrWarnImplicitInternalStepId: (kind: ImplicitInternalStepIdKind) => void;
+    assertUniqueStepId: (stepId: string) => void;
+    assertUserStepId: (stepId: string) => void;
+};
+export declare function createDurableContextDeterminism(params: {
+    policy: ImplicitInternalStepIdsPolicy;
+    warnedKinds: Set<ImplicitInternalStepIdKind>;
+    seenStepIds: Set<string>;
+    warn: (message: string) => void;
+}): DurableContextDeterminism;

package/dist/types/node/durable/core/durable-context/DurableContext.emit.d.ts

@@ -0,0 +1,16 @@
+import type { IEventBus } from "../interfaces/bus";
+import type { EmitOptions, IStepBuilder, StepOptions } from "../interfaces/context";
+import type { IEventDefinition } from "../../../../types/event";
+import { type DurableAuditEntryInput } from "../audit";
+export declare function emitDurably<TPayload>(params: {
+    bus: IEventBus;
+    assertNotCancelled: () => Promise<void>;
+    appendAuditEntry: (entry: DurableAuditEntryInput) => Promise<void>;
+    assertUniqueStepId: (stepId: string) => void;
+    assertOrWarnImplicitInternalStepId: (kind: "sleep" | "emit" | "waitForSignal") => void;
+    emitIndexes: Map<string, number>;
+    internalStep: <T>(stepId: string, options?: StepOptions) => IStepBuilder<T>;
+    event: IEventDefinition<TPayload>;
+    payload: TPayload;
+    options?: EmitOptions;
+}): Promise<void>;

package/dist/types/node/durable/core/durable-context/DurableContext.sleep.d.ts

@@ -0,0 +1,16 @@
+import type { SleepOptions } from "../interfaces/context";
+import type { IDurableStore } from "../interfaces/store";
+import { type DurableAuditEntryInput } from "../audit";
+export declare function sleepDurably(params: {
+    store: IDurableStore;
+    executionId: string;
+    assertNotCancelled: () => Promise<void>;
+    appendAuditEntry: (entry: DurableAuditEntryInput) => Promise<void>;
+    assertUniqueStepId: (stepId: string) => void;
+    assertOrWarnImplicitInternalStepId: (kind: "sleep" | "emit" | "waitForSignal") => void;
+    sleepIndexRef: {
+        current: number;
+    };
+    durationMs: number;
+    options?: SleepOptions;
+}): Promise<void>;

package/dist/types/node/durable/core/durable-context/DurableContext.steps.d.ts

@@ -0,0 +1,25 @@
+import type { DurableAuditEntryInput } from "../audit";
+import type { IStepBuilder, StepOptions } from "../interfaces/context";
+import type { IDurableStore } from "../interfaces/store";
+export type DurableCompensation = {
+    stepId: string;
+    action: () => Promise<void>;
+};
+export declare function executeDurableStep<T>(params: {
+    store: IDurableStore;
+    executionId: string;
+    assertNotCancelled: () => Promise<void>;
+    appendAuditEntry: (entry: DurableAuditEntryInput) => Promise<void>;
+    stepId: string;
+    options: StepOptions;
+    upFn: () => Promise<T>;
+    downFn?: (result: T) => Promise<void>;
+    compensations: DurableCompensation[];
+}): Promise<T>;
+export declare function rollbackDurableCompensations(params: {
+    store: IDurableStore;
+    executionId: string;
+    compensations: DurableCompensation[];
+    assertUniqueStepId: (stepId: string) => void;
+    internalStep: <T>(stepId: string, options?: StepOptions) => IStepBuilder<T>;
+}): Promise<void>;

package/dist/types/node/durable/core/durable-context/DurableContext.switch.d.ts

@@ -0,0 +1,22 @@
+import type { SwitchBranch } from "../interfaces/context";
+import type { IDurableStore } from "../interfaces/store";
+import { type DurableAuditEntryInput } from "../audit";
+/**
+ * Replay-safe switch implementation for durable workflows.
+ *
+ * On first execution the matchers are evaluated in order; the first matching
+ * branch's `run()` is invoked and the `{ branchId, result }` pair is persisted.
+ * On replay the cached branch result is returned immediately — matchers and
+ * `run()` are never re-executed.
+ */
+export declare function switchDurably<TValue, TResult>(params: {
+    store: IDurableStore;
+    executionId: string;
+    assertNotCancelled: () => Promise<void>;
+    appendAuditEntry: (entry: DurableAuditEntryInput) => Promise<void>;
+    assertUniqueStepId: (stepId: string) => void;
+    stepId: string;
+    value: TValue;
+    branches: SwitchBranch<TValue, TResult>[];
+    defaultBranch?: Omit<SwitchBranch<TValue, TResult>, "match">;
+}): Promise<TResult>;

package/dist/types/node/durable/core/durable-context/DurableContext.waitForSignal.d.ts

@@ -0,0 +1,23 @@
+import type { SignalOptions } from "../interfaces/context";
+import type { IDurableStore } from "../interfaces/store";
+import type { IEventDefinition } from "../../../../types/event";
+import { type DurableAuditEntryInput } from "../audit";
+export type WaitForSignalOutcome<TPayload> = {
+    kind: "signal";
+    payload: TPayload;
+} | {
+    kind: "timeout";
+};
+type SignalInput<TPayload> = IEventDefinition<TPayload>;
+export declare function waitForSignalDurably<TPayload>(params: {
+    store: IDurableStore;
+    executionId: string;
+    assertNotCancelled: () => Promise<void>;
+    appendAuditEntry: (entry: DurableAuditEntryInput) => Promise<void>;
+    assertUniqueStepId: (stepId: string) => void;
+    assertOrWarnImplicitInternalStepId: (kind: "sleep" | "emit" | "waitForSignal") => void;
+    signalIndexes: Map<string, number>;
+    signal: SignalInput<TPayload>;
+    options?: SignalOptions;
+}): Promise<TPayload | WaitForSignalOutcome<TPayload>>;
+export {};

package/dist/types/node/durable/core/flowShape.d.ts

@@ -0,0 +1,50 @@
+import type { IDurableContext } from "./interfaces/context";
+/** Discriminated union describing a single node in a durable workflow. */
+export type FlowNode = FlowStepNode | FlowSleepNode | FlowSignalNode | FlowEmitNode | FlowSwitchNode | FlowNoteNode;
+export interface FlowStepNode {
+    kind: "step";
+    stepId: string;
+    hasCompensation: boolean;
+}
+export interface FlowSleepNode {
+    kind: "sleep";
+    durationMs: number;
+    stepId?: string;
+}
+export interface FlowSignalNode {
+    kind: "waitForSignal";
+    signalId: string;
+    timeoutMs?: number;
+    stepId?: string;
+}
+export interface FlowEmitNode {
+    kind: "emit";
+    eventId: string;
+    stepId?: string;
+}
+export interface FlowSwitchNode {
+    kind: "switch";
+    stepId: string;
+    branchIds: string[];
+    hasDefault: boolean;
+}
+export interface FlowNoteNode {
+    kind: "note";
+    message: string;
+}
+/**
+ * Serializable description of a durable workflow's structure.
+ *
+ * Produced by `recordFlowShape()` without actually executing the workflow.
+ * Useful for documentation, visualization dashboards, and tooling.
+ */
+export interface DurableFlowShape {
+    nodes: FlowNode[];
+}
+/**
+ * Record a durable workflow flow-shape without executing it.
+ *
+ * This runs the descriptor against a recording `IDurableContext` that captures
+ * `ctx.*` calls into a serializable shape.
+ */
+export declare function recordFlowShape(descriptor: (ctx: IDurableContext) => Promise<void>): Promise<DurableFlowShape>;

package/dist/types/node/durable/core/ids.d.ts

@@ -0,0 +1,11 @@
+import type { IEventDefinition } from "../../../types/event";
+export type DurableSignalId<TPayload = unknown> = IEventDefinition<TPayload>;
+export interface DurableStepId<TResult = unknown> {
+    id: string;
+    /**
+     * Phantom field used only for type inference. Not present at runtime.
+     * The result type is carried through the object type.
+     */
+    readonly __result?: TResult;
+}
+export declare function createDurableStepId<TResult>(id: string): DurableStepId<TResult>;

package/dist/types/node/durable/core/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./interfaces/bus";
+export * from "./interfaces/queue";
+export * from "./interfaces/store";
+export * from "./interfaces/context";
+export * from "./interfaces/service";
+export * from "./CronParser";
+export * from "./DurableContext";
+export * from "./DurableService";
+export * from "./DurableWorker";
+export * from "./flowShape";

package/dist/types/node/durable/core/interfaces/bus.d.ts

@@ -0,0 +1,13 @@
+export interface BusEvent {
+    type: string;
+    payload: unknown;
+    timestamp: Date;
+}
+export type BusEventHandler = (event: BusEvent) => Promise<void>;
+export interface IEventBus {
+    publish(channel: string, event: BusEvent): Promise<void>;
+    subscribe(channel: string, handler: BusEventHandler): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    init?(): Promise<void>;
+    dispose?(): Promise<void>;
+}

package/dist/types/node/durable/core/interfaces/context.d.ts

@@ -0,0 +1,105 @@
+import type { IEventDefinition } from "../../../../types/event";
+import type { DurableStepId } from "../ids";
+export interface StepOptions {
+    retries?: number;
+    timeout?: number;
+}
+/**
+ * Options for sleep operations.
+ * Use `stepId` to provide a stable identifier that survives code refactoring.
+ */
+export interface SleepOptions {
+    /** Explicit step ID for replay stability. If not provided, an auto-indexed ID is used. */
+    stepId?: string;
+}
+/**
+ * Options for waitForSignal operations.
+ */
+export interface SignalOptions {
+    /** Timeout in milliseconds. If provided, returns a discriminated union with kind. */
+    timeoutMs?: number;
+    /** Explicit step ID for replay stability. If not provided, an auto-indexed ID is used. */
+    stepId?: string;
+}
+/**
+ * Options for emit operations.
+ */
+export interface EmitOptions {
+    /** Explicit step ID for replay stability. If not provided, an auto-indexed ID is used. */
+    stepId?: string;
+}
+/**
+ * A single branch in a durable switch expression.
+ *
+ * `id` identifies the branch for replay; `match` tests whether this branch applies;
+ * `run` executes the branch logic (only on first evaluation, cached on replay).
+ */
+export interface SwitchBranch<TValue, TResult> {
+    /** Stable identifier for this branch. Persisted for replay. */
+    id: string;
+    /** Predicate that selects this branch based on the switch value. */
+    match: (value: TValue) => boolean;
+    /** Logic to execute when this branch is selected. */
+    run: (value: TValue) => Promise<TResult>;
+}
+export interface IStepBuilder<T> extends PromiseLike<T> {
+    up(fn: () => Promise<T>): this;
+    down(fn: (result: T) => Promise<void>): this;
+}
+export interface IDurableContext {
+    readonly executionId: string;
+    readonly attempt: number;
+    step<T>(stepId: string): IStepBuilder<T>;
+    step<T>(stepId: DurableStepId<T>): IStepBuilder<T>;
+    step<T>(stepId: string, fn: () => Promise<T>): Promise<T>;
+    step<T>(stepId: DurableStepId<T>, fn: () => Promise<T>): Promise<T>;
+    step<T>(stepId: string, options: StepOptions, fn: () => Promise<T>): Promise<T>;
+    step<T>(stepId: DurableStepId<T>, options: StepOptions, fn: () => Promise<T>): Promise<T>;
+    sleep(durationMs: number, options?: SleepOptions): Promise<void>;
+    /**
+     * Suspend until an external signal is delivered via DurableService.signal().
+     * The signal is memoized as a durable step under `__signal:<signalId>[:index]`.
+     * Use options.stepId to provide a stable identifier for replay safety.
+     */
+    waitForSignal<TPayload>(signal: IEventDefinition<TPayload>): Promise<TPayload>;
+    waitForSignal<TPayload>(signal: IEventDefinition<TPayload>, options: SignalOptions & {
+        timeoutMs: number;
+    }): Promise<{
+        kind: "signal";
+        payload: TPayload;
+    } | {
+        kind: "timeout";
+    }>;
+    waitForSignal<TPayload>(signal: IEventDefinition<TPayload>, options: SignalOptions): Promise<TPayload>;
+    emit<TPayload>(event: IEventDefinition<TPayload>, payload: TPayload, options?: EmitOptions): Promise<void>;
+    /**
+     * Append a custom audit entry for observability and debugging.
+     * This is a no-op if audit is disabled or the store does not support it.
+     */
+    note(message: string, meta?: Record<string, unknown>): Promise<void>;
+    /**
+     * Replay-safe branching primitive.
+     *
+     * Evaluates `branches` against `value` to find the first matching branch.
+     * The matched branch's `id` and result are persisted; on replay the matchers
+     * are skipped and the cached result is returned directly.
+     *
+     * Throws if no branch matches and no `defaultBranch` is provided.
+     */
+    switch<TValue, TResult>(stepId: string, value: TValue, branches: SwitchBranch<TValue, TResult>[], defaultBranch?: Omit<SwitchBranch<TValue, TResult>, "match">): Promise<TResult>;
+    rollback(): Promise<void>;
+}
+/**
+ * Internal control-flow signal used to suspend a durable execution without failing it.
+ *
+ * `DurableContext` throws this error to indicate "pause here and resume later":
+ * - `"sleep"`: durable sleep timer was scheduled
+ * - `"yield"`: waiting for a signal (or signal-timeout timer) to complete
+ *
+ * `ExecutionManager` treats this as a normal suspension and will not mark the execution
+ * as failed; instead it schedules a resume via timers/queue depending on configuration.
+ */
+export declare class SuspensionSignal extends Error {
+    readonly reason: "sleep" | "yield" | "timeout";
+    constructor(reason: "sleep" | "yield" | "timeout");
+}

package/dist/types/node/durable/core/interfaces/queue.d.ts

@@ -0,0 +1,17 @@
+export interface QueueMessage<T = unknown> {
+    id: string;
+    type: "execute" | "resume" | "schedule";
+    payload: T;
+    attempts: number;
+    maxAttempts: number;
+    createdAt: Date;
+}
+export type MessageHandler<T = unknown> = (message: QueueMessage<T>) => Promise<void>;
+export interface IDurableQueue {
+    enqueue<T>(message: Omit<QueueMessage<T>, "id" | "createdAt" | "attempts">): Promise<string>;
+    consume<T>(handler: MessageHandler<T>): Promise<void>;
+    ack(messageId: string): Promise<void>;
+    nack(messageId: string, requeue?: boolean): Promise<void>;
+    init?(): Promise<void>;
+    dispose?(): Promise<void>;
+}