bunqueue 2.8.0 → 2.8.2

package/dist/client/worker/processorHandlers.js

@@ -0,0 +1,372 @@
+/**
+ * Processor Handler Factories
+ * Creates callback handlers for job operations during processing
+ */
+import { jobId } from '../../domain/types/job';
+import { getSharedManager } from '../manager';
+export function createProgressHandler(embedded, tcp, emitter, jobHolder) {
+    return async (id, progress, message) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            await manager.updateProgress(jobId(id), progress, message);
+        }
+        else if (tcp) {
+            await tcp.send({ cmd: 'Progress', id, progress, message });
+        }
+        emitter.emit('progress', jobHolder.current, progress);
+    };
+}
+export function createLogHandler(embedded, tcp, emitter, jobHolder) {
+    return async (id, message) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            manager.addLog(jobId(id), message);
+        }
+        else if (tcp) {
+            await tcp.send({ cmd: 'AddLog', id, message });
+        }
+        emitter.emit('log', jobHolder.current, message);
+    };
+}
+export function createGetStateHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            return (await manager.getJobState(jobId(id)));
+        }
+        else if (tcp) {
+            const response = await tcp.send({ cmd: 'GetState', id });
+            return (response.state ?? 'unknown');
+        }
+        return 'unknown';
+    };
+}
+export function createGetChildrenValuesHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            return manager.getChildrenValues(jobId(id));
+        }
+        else if (tcp) {
+            const response = await tcp.send({ cmd: 'GetChildrenValues', id });
+            const data = response.data;
+            return data?.values ?? {};
+        }
+        return {};
+    };
+}
+export function createGetFailedChildrenValuesHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            return manager.getFailedChildrenValues(jobId(id));
+        }
+        if (!tcp)
+            return {};
+        const res = await tcp.send({ cmd: 'GetFailedChildrenValues', id });
+        return res.values ?? {};
+    };
+}
+export function createGetIgnoredChildrenFailuresHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            return manager.getIgnoredChildrenFailures(jobId(id));
+        }
+        if (!tcp)
+            return {};
+        const res = await tcp.send({ cmd: 'GetIgnoredChildrenFailures', id });
+        return res.values ?? {};
+    };
+}
+export function createRemoveChildDependencyHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            return manager.removeChildDependency(jobId(id));
+        }
+        if (!tcp)
+            return false;
+        const res = await tcp.send({ cmd: 'RemoveChildDependency', id });
+        return res.ok === true;
+    };
+}
+export function createRemoveUnprocessedChildrenHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            return manager.removeUnprocessedChildren(jobId(id));
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'RemoveUnprocessedChildren', id });
+    };
+}
+/** Issue #82: Create moveToFailed handler for use inside processor */
+export function createMoveToFailedHandler(embedded, tcp, internalJob, token, onCalled) {
+    return async (_id, error, _lockToken) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            await manager.fail(internalJob.id, error.message, token ?? undefined);
+        }
+        else if (tcp) {
+            await tcp.send({
+                cmd: 'FAIL',
+                id: internalJob.id,
+                error: error.message,
+                ...(token ? { token } : {}),
+            });
+        }
+        onCalled(error);
+    };
+}
+/** Issue #82: Create moveToCompleted handler for use inside processor */
+export function createMoveToCompletedHandler(embedded, ackBatcher, internalJob, token, onCalled) {
+    return async (_id, returnValue, _lockToken) => {
+        if (embedded) {
+            const manager = getSharedManager();
+            await manager.ack(internalJob.id, returnValue, token ?? undefined);
+        }
+        else {
+            await ackBatcher.queue(String(internalJob.id), returnValue, token ?? undefined);
+        }
+        onCalled(returnValue);
+        return null;
+    };
+}
+// ============================================================
+// Job mutation handlers (Issue #82 follow-up: wire remaining no-op methods)
+// ============================================================
+export function createRemoveHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            await getSharedManager().cancel(jobId(id));
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'Cancel', id });
+    };
+}
+export function createRetryHandler(embedded, tcp, internalJob) {
+    return async (id) => {
+        // BullMQ contract: Job.retry() moves a failed job back to waiting.
+        // Dispatch by state so it also works on an active job that wants to requeue.
+        if (embedded) {
+            const mgr = getSharedManager();
+            const state = await mgr.getJobState(jobId(id));
+            if (state === 'failed') {
+                const count = mgr.retryDlq(internalJob.queue, jobId(id));
+                if (count === 0)
+                    throw new Error(`Job ${id} is failed but not present in DLQ`);
+                return;
+            }
+            if (state === 'active') {
+                const ok = await mgr.moveActiveToWait(jobId(id));
+                if (!ok)
+                    throw new Error(`Failed to retry active job ${id}`);
+                return;
+            }
+            if (state === 'waiting' || state === 'prioritized' || state === 'delayed')
+                return;
+            throw new Error(`Cannot retry job ${id} from state '${state}'`);
+        }
+        if (!tcp)
+            return;
+        const res = await tcp.send({ cmd: 'MoveToWait', id });
+        if (res.ok !== true) {
+            const err = typeof res.error === 'string' ? res.error : 'retry failed';
+            throw new Error(err);
+        }
+    };
+}
+export function createUpdateDataHandler(embedded, tcp) {
+    return async (id, data) => {
+        if (embedded) {
+            await getSharedManager().updateJobData(jobId(id), data);
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'Update', id, data });
+    };
+}
+export function createPromoteHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            await getSharedManager().promote(jobId(id));
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'Promote', id });
+    };
+}
+export function createChangeDelayHandler(embedded, tcp) {
+    return async (id, delay) => {
+        if (embedded) {
+            await getSharedManager().changeDelay(jobId(id), delay);
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'ChangeDelay', id, delay });
+    };
+}
+export function createChangePriorityHandler(embedded, tcp) {
+    return async (id, opts) => {
+        if (embedded) {
+            await getSharedManager().changePriority(jobId(id), opts.priority, opts.lifo);
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'ChangePriority', id, priority: opts.priority, lifo: opts.lifo });
+    };
+}
+export function createExtendLockHandler(embedded, tcp) {
+    return async (id, token, duration) => {
+        if (embedded) {
+            const ok = await getSharedManager().extendLock(jobId(id), token, duration);
+            return ok ? duration : 0;
+        }
+        if (!tcp)
+            return 0;
+        const res = await tcp.send({ cmd: 'ExtendLock', id, token, duration });
+        return res.ok === true ? duration : 0;
+    };
+}
+export function createClearLogsHandler(embedded, tcp) {
+    return async (id, keepLogs) => {
+        if (embedded) {
+            getSharedManager().clearLogs(jobId(id), keepLogs);
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'ClearLogs', id, keepLogs });
+    };
+}
+export function createMoveToWaitHandler(embedded, tcp) {
+    return async (id, _token) => {
+        if (embedded) {
+            return await getSharedManager().moveActiveToWait(jobId(id));
+        }
+        if (!tcp)
+            return false;
+        const res = await tcp.send({ cmd: 'MoveToWait', id });
+        return res.ok === true;
+    };
+}
+export function createMoveToDelayedHandler(embedded, tcp) {
+    return async (id, timestamp, _token) => {
+        // BullMQ API passes absolute timestamp; server expects relative delay (ms)
+        const delay = Math.max(0, timestamp - Date.now());
+        if (embedded) {
+            await getSharedManager().moveToDelayed(jobId(id), delay);
+            return;
+        }
+        if (!tcp)
+            return;
+        await tcp.send({ cmd: 'MoveToDelayed', id, delay });
+    };
+}
+export function createMoveToWaitingChildrenHandler(embedded, tcp) {
+    return async (id) => {
+        if (embedded) {
+            return await getSharedManager().moveToWaitingChildren(jobId(id));
+        }
+        if (!tcp)
+            return false;
+        throw new Error('moveToWaitingChildren is not supported in TCP mode — no server command available');
+    };
+}
+export function createWaitUntilFinishedHandler(embedded, tcp) {
+    return async (id, _queueEvents, ttl) => {
+        const timeout = ttl ?? 30000;
+        if (embedded) {
+            const manager = getSharedManager();
+            const job = await manager.getJob(jobId(id));
+            if (!job)
+                throw new Error(`Job ${id} not found`);
+            if (job.completedAt)
+                return manager.getResult(jobId(id));
+            const completed = await manager.waitForJobCompletion(jobId(id), timeout);
+            if (!completed)
+                throw new Error(`waitUntilFinished timed out after ${timeout}ms`);
+            return manager.getResult(jobId(id));
+        }
+        if (!tcp)
+            throw new Error('waitUntilFinished: no connection');
+        const res = await tcp.send({ cmd: 'WaitJob', id, timeout });
+        const typed = res;
+        if (!typed.completed)
+            throw new Error(`waitUntilFinished timed out after ${timeout}ms`);
+        return typed.result;
+    };
+}
+export function createDiscardHandler(embedded, tcp) {
+    return (id) => {
+        if (embedded) {
+            void getSharedManager().discard(jobId(id));
+            return;
+        }
+        if (!tcp)
+            return;
+        void tcp.send({ cmd: 'Discard', id });
+    };
+}
+/**
+ * getDependencies — compute from internalJob.childrenIds by querying each child's state.
+ * No dedicated server API; derive from existing job state queries.
+ */
+export function createGetDependenciesHandler(embedded, tcp, internalJob) {
+    return async () => {
+        const childIds = internalJob.childrenIds;
+        const processed = {};
+        const unprocessed = [];
+        for (const cid of childIds) {
+            let state = 'unknown';
+            let result;
+            if (embedded) {
+                const mgr = getSharedManager();
+                state = await mgr.getJobState(cid);
+                if (state === 'completed')
+                    result = mgr.getResult(cid);
+            }
+            else if (tcp) {
+                const r = await tcp.send({ cmd: 'GetState', id: String(cid) });
+                state = r.state ?? 'unknown';
+                if (state === 'completed') {
+                    const rr = await tcp.send({ cmd: 'GetResult', id: String(cid) });
+                    result = rr.result;
+                }
+            }
+            const key = `${internalJob.queue}:${String(cid)}`;
+            if (state === 'completed' || state === 'failed') {
+                processed[key] = result ?? null;
+            }
+            else {
+                unprocessed.push(key);
+            }
+        }
+        return { processed, unprocessed };
+    };
+}
+export function createGetDependenciesCountHandler(embedded, tcp, internalJob) {
+    const getDeps = createGetDependenciesHandler(embedded, tcp, internalJob);
+    return async (id) => {
+        const deps = await getDeps(id);
+        return {
+            processed: Object.keys(deps.processed).length,
+            unprocessed: deps.unprocessed.length,
+        };
+    };
+}
+/**
+ * removeDeduplicationKey — no server primitive; throw explicit error so callers
+ * learn this isn't supported rather than silently getting `false`.
+ */
+export function createRemoveDeduplicationKeyHandler() {
+    return () => Promise.reject(new Error('removeDeduplicationKey is not implemented — no server primitive available'));
+}

package/dist/client/worker/types.d.ts

@@ -48,4 +48,3 @@ export declare const WORKER_CONSTANTS: {
     readonly MAX_POLL_TIMEOUT: 30000;
     readonly DEFAULT_ACK_INTERVAL: 50;
 };
-//# sourceMappingURL=types.d.ts.map

package/dist/client/worker/types.js

@@ -11,4 +11,3 @@ export const WORKER_CONSTANTS = {
     MAX_POLL_TIMEOUT: 30_000,
     DEFAULT_ACK_INTERVAL: 50,
 };
-//# sourceMappingURL=types.js.map

package/dist/client/worker/worker.d.ts

@@ -145,4 +145,3 @@ export declare class Worker<T = unknown, R = unknown> extends EventEmitter {
     /** Apply worker-level removeOnComplete/removeOnFail defaults to a job */
     private applyRemoveDefaults;
 }
-//# sourceMappingURL=worker.d.ts.map

package/dist/client/worker/worker.js

@@ -748,4 +748,3 @@ export class Worker extends EventEmitter {
         }
     }
 }
-//# sourceMappingURL=worker.js.map

package/dist/client/worker/workerHeartbeat.d.ts

@@ -13,4 +13,3 @@ export interface HeartbeatDeps {
 }
 export declare function startHeartbeat(deps: HeartbeatDeps, intervalMs: number): ReturnType<typeof setInterval>;
 export declare function sendHeartbeat(deps: HeartbeatDeps): Promise<void>;
-//# sourceMappingURL=workerHeartbeat.d.ts.map

package/dist/client/worker/workerHeartbeat.js

@@ -41,4 +41,3 @@ export async function sendHeartbeat(deps) {
         deps.emitter.emit('error', Object.assign(error, { context: 'heartbeat' }));
     }
 }
-//# sourceMappingURL=workerHeartbeat.js.map

package/dist/client/worker/workerPull.d.ts

@@ -18,4 +18,3 @@ export declare function pullTcp(config: PullConfig, tcp: TcpConnection, count: n
     job: InternalJob;
     token: string | null;
 }>>;
-//# sourceMappingURL=workerPull.d.ts.map

package/dist/client/worker/workerPull.js

@@ -57,4 +57,3 @@ export async function pullTcp(config, tcp, count, closing) {
         token: tokens[i] || null,
     })) ?? []);
 }
-//# sourceMappingURL=workerPull.js.map

package/dist/client/worker/workerRateLimiter.d.ts

@@ -45,4 +45,3 @@ export declare class WorkerRateLimiter {
     /** Advance head pointer past expired tokens. Compact when head > half the array. */
     private evictExpired;
 }
-//# sourceMappingURL=workerRateLimiter.d.ts.map

package/dist/client/worker/workerRateLimiter.js

@@ -97,4 +97,3 @@ export class WorkerRateLimiter {
         }
     }
 }
-//# sourceMappingURL=workerRateLimiter.js.map

package/dist/client/worker.d.ts

@@ -3,4 +3,3 @@
  * @deprecated Import from './worker' instead
  */
 export { Worker } from './worker/worker';
-//# sourceMappingURL=worker.d.ts.map

package/dist/client/worker.js

@@ -3,4 +3,3 @@
  * @deprecated Import from './worker' instead
  */
 export { Worker } from './worker/worker';
-//# sourceMappingURL=worker.js.map

package/dist/client/workflow/compensator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compensation logic - runs compensate handlers in reverse order on failure
+ */
+import type { Execution } from './types';
+import type { Workflow } from './workflow';
+import type { WorkflowStore } from './store';
+import type { WorkflowEmitter } from './emitter';
+/** Sentinel error thrown when execution must pause for a signal */
+export declare class WaitForSignalError extends Error {
+    readonly event: string;
+    constructor(event: string);
+}
+/** Run compensation handlers in reverse order for all completed steps */
+export declare function runCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null): Promise<void>;

package/dist/client/workflow/compensator.js

@@ -0,0 +1,45 @@
+/**
+ * Compensation logic - runs compensate handlers in reverse order on failure
+ */
+import { findStepDef, buildContext } from './runner';
+/** Sentinel error thrown when execution must pause for a signal */
+export class WaitForSignalError extends Error {
+    event;
+    constructor(event) {
+        super(`Waiting for signal: ${event}`);
+        this.event = event;
+    }
+}
+/** Run compensation handlers in reverse order for all completed steps */
+export async function runCompensation(exec, wf, store, emitter) {
+    const completed = Object.entries(exec.steps)
+        .filter(([name, s]) => s.status === 'completed' && !name.startsWith('__'))
+        .reverse();
+    if (completed.length === 0)
+        return;
+    exec.state = 'compensating';
+    store.update(exec);
+    emitter?.emitWorkflow('workflow:compensating', exec.id, exec.workflowName, 'compensating');
+    const baseCtx = buildContext(exec);
+    for (const [name, record] of completed) {
+        const def = findStepDef(wf, name);
+        if (def?.compensate) {
+            // For forEach iterations, restore that iteration's __item/__index so the
+            // compensate handler knows exactly which item it is rolling back.
+            const ctx = record.loopIndex !== undefined
+                ? {
+                    ...baseCtx,
+                    steps: { ...baseCtx.steps, __item: record.loopItem, __index: record.loopIndex },
+                }
+                : baseCtx;
+            try {
+                await def.compensate(ctx);
+            }
+            catch {
+                // Compensation errors don't stop the chain
+            }
+        }
+    }
+    exec.state = 'failed';
+    store.update(exec);
+}

package/dist/client/workflow/emitter.d.ts

@@ -15,4 +15,3 @@ export declare class WorkflowEmitter {
     removeAllListeners(): void;
     private dispatch;
 }
-//# sourceMappingURL=emitter.d.ts.map

package/dist/client/workflow/emitter.js

@@ -65,11 +65,22 @@ export class WorkflowEmitter {
     dispatch(type, event) {
         const typed = this.listeners.get(type);
         if (typed) {
-            for (const fn of typed)
+            for (const fn of typed) {
+                try {
+                    fn(event);
+                }
+                catch {
+                    /* listener errors must not break dispatch */
+                }
+            }
+        }
+        for (const fn of this.globalListeners) {
+            try {
                 fn(event);
+            }
+            catch {
+                /* listener errors must not break dispatch */
+            }
         }
-        for (const fn of this.globalListeners)
-            fn(event);
     }
 }
-//# sourceMappingURL=emitter.js.map

package/dist/client/workflow/engine.d.ts

@@ -3,7 +3,7 @@
  * Manages lifecycle of internal Queue, Worker, and Store.
  */
 import type { Workflow } from './workflow';
-import type { EngineOptions, RunHandle, Execution, ExecutionState, WorkflowEventType, WorkflowEventListener } from './types';
+import type { EngineOptions, RunHandle, Execution, ExecutionState, RecoverResult, WorkflowEventType, WorkflowEventListener } from './types';
 export declare class Engine {
     private readonly queue;
     private readonly worker;
@@ -21,6 +21,13 @@ export declare class Engine {
     listExecutions(workflowName?: string, state?: ExecutionState): Execution[];
     /** Send a signal to a waiting execution */
     signal(executionId: string, event: string, payload?: unknown): Promise<void>;
+    /**
+     * Recover orphaned executions after a crash/restart.
+     * - 'running' executions: re-enqueued at their current step
+     * - 'waiting' executions: timeout timers re-armed (or resumed if signal arrived)
+     * - 'compensating' executions: compensation re-run (handlers must be idempotent)
+     */
+    recover(): Promise<RecoverResult>;
     /** Subscribe to a specific workflow event type */
     on(type: WorkflowEventType, listener: WorkflowEventListener): this;
     /** Subscribe to all workflow events */
@@ -40,4 +47,3 @@ export declare class Engine {
     /** Shut down the engine */
     close(force?: boolean): Promise<void>;
 }
-//# sourceMappingURL=engine.d.ts.map

package/dist/client/workflow/engine.js

@@ -58,6 +58,15 @@ export class Engine {
     async signal(executionId, event, payload) {
         return this.executor.signal(executionId, event, payload);
     }
+    /**
+     * Recover orphaned executions after a crash/restart.
+     * - 'running' executions: re-enqueued at their current step
+     * - 'waiting' executions: timeout timers re-armed (or resumed if signal arrived)
+     * - 'compensating' executions: compensation re-run (handlers must be idempotent)
+     */
+    async recover() {
+        return this.executor.recover();
+    }
     // ============ Observability ============
     /** Subscribe to a specific workflow event type */
     on(type, listener) {
@@ -109,4 +118,3 @@ export class Engine {
         this.emitter.removeAllListeners();
     }
 }
-//# sourceMappingURL=engine.js.map

package/dist/client/workflow/executor.d.ts

@@ -3,20 +3,21 @@ import type { Queue } from '../queue/queue';
 import type { Workflow } from './workflow';
 import type { WorkflowStore } from './store';
 import type { WorkflowEmitter } from './emitter';
-import type { Execution, StepJobData, RunHandle } from './types';
+import type { Execution, StepJobData, RunHandle, RecoverResult } from './types';
 export declare class WorkflowExecutor {
     private readonly store;
     private readonly queue;
     private readonly emitter;
     private readonly workflows;
     private readonly timeoutTimers;
+    private readonly updateFn;
     constructor(store: WorkflowStore, queue: Queue, emitter?: WorkflowEmitter | null);
     register(workflow: Workflow): void;
     start(workflowName: string, input: unknown): Promise<RunHandle>;
     processStep(data: StepJobData): Promise<unknown>;
     signal(executionId: string, event: string, payload: unknown): Promise<void>;
     getExecution(id: string): Execution | null;
-    listExecutions(workflowName?: string, state?: Execution['state']): Execution[];
+    listExecutions(wfName?: string, state?: Execution['state']): Execution[];
     private executeNode;
     private runStep;
     private runBranch;
@@ -30,5 +31,6 @@ export declare class WorkflowExecutor {
     private enqueue;
     private scheduleTimeoutCheck;
     private compensate;
+    /** Recover orphaned executions after a crash/restart */
+    recover(): Promise<RecoverResult>;
 }
-//# sourceMappingURL=executor.d.ts.map