bunqueue 2.8.59 → 2.9.0

package/dist/application/eventsManager.js

@@ -34,9 +34,8 @@ export class EventsManager {
         // Clear all waiters
         for (const waiters of this.completionWaiters.values()) {
             for (const waiter of waiters) {
-                if (!waiter.cancelled) {
+                if (!waiter.cancelled)
                     waiter.resolve();
-                }
             }
         }
         this.completionWaiters.clear();
@@ -45,40 +44,45 @@ export class EventsManager {
      * Wait for a specific job to complete - event-driven, no polling
      * Returns true if job completed, false if timeout
      */
-    waitForJobCompletion(jobId, timeoutMs) {
+    waitForJobCompletion(jobId, timeoutMs, signal) {
         const jobKey = String(jobId);
+        if (signal?.aborted)
+            return Promise.resolve(false);
         return new Promise((resolve) => {
+            let settled = false;
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                const waiters = this.completionWaiters.get(jobKey);
+                waiters?.delete(waiter);
+                if (waiters?.size === 0)
+                    this.completionWaiters.delete(jobKey);
+            };
+            const finish = (completed) => {
+                if (settled)
+                    return;
+                settled = true;
+                waiter.cancelled = !completed;
+                cleanup();
+                resolve(completed);
+            };
+            const onAbort = () => finish(false);
             const waiter = {
-                resolve: () => {
-                    clearTimeout(timer);
-                    resolve(true);
-                },
+                resolve: () => finish(true),
+                cancel: () => finish(false),
                 cancelled: false,
             };
-            const timer = setTimeout(() => {
-                // Timeout - mark as cancelled and remove from map to prevent memory leak
-                waiter.cancelled = true;
-                // Remove the waiter from the array
-                const waiters = this.completionWaiters.get(jobKey);
-                if (waiters) {
-                    const index = waiters.indexOf(waiter);
-                    if (index !== -1) {
-                        waiters.splice(index, 1);
-                    }
-                    // Clean up empty arrays to free memory
-                    if (waiters.length === 0) {
-                        this.completionWaiters.delete(jobKey);
-                    }
-                }
-                resolve(false);
-            }, timeoutMs);
             // Add to waiters
             let waiters = this.completionWaiters.get(jobKey);
             if (!waiters) {
-                waiters = [];
+                waiters = new Set();
                 this.completionWaiters.set(jobKey, waiters);
             }
-            waiters.push(waiter);
+            waiters.add(waiter);
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
         });
     }
     /** Check if broadcast has any listeners - for batch optimizations */

package/dist/application/lockManager.js

@@ -78,7 +78,7 @@ export async function checkExpiredLocks(ctx) {
  * Process a single expired lock (called with both locks already held)
  * Lock hierarchy already satisfied: shardLock -> processingLock held by caller
  */
-// biome-ignore lint/complexity/useMaxParams: lock-processing inner fn needs the full lock context (7 params)
+// oxlint-disable-next-line max-params -- lock-processing inner fn needs the full lock context (7 params)
 function processExpiredLockInner(jobId, lock, job, shardIdx, procIdx, ctx, now) {
     const shard = ctx.shards[shardIdx];
     const queue = shard.getQueue(job.queue);

package/dist/application/operations/jobManagement.d.ts

@@ -26,6 +26,10 @@ export interface JobManagementContext {
     eventsManager: EventsManager;
     repeatChain?: Map<JobId, JobId>;
     dependencyResults: DependencyResultTracker;
+    customIdMap: {
+        get(id: string): JobId | undefined;
+        delete(id: string): boolean;
+    };
     depCompletions?: DependencyCompletionTracker;
     maxDependencyCompletions: number;
 }

package/dist/application/operations/jobMoveOperations.js

@@ -75,7 +75,7 @@ export async function discardJob(jobId, ctx) {
     const validJob = job;
     const idx = shardIndex(validJob.queue);
     const fromProcessing = location.type === 'processing';
-    const entry = await withWriteLock(ctx.shardLocks[idx], () => {
+    await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         if (fromProcessing) {
             shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId, validJob.id);
@@ -86,9 +86,14 @@ export async function discardJob(jobId, ctx) {
         }
         const dlqEntry = shard.addToDlq(validJob);
         ctx.jobIndex.set(jobId, { type: 'dlq', queueName: validJob.queue });
-        return dlqEntry;
+        // SQLite writes are synchronous. Keeping them in this critical section
+        // prevents a concurrent permanent removal from racing a late DLQ insert.
+        ctx.storage?.saveDlqEntry(dlqEntry);
+        ctx.storage?.deleteJob(jobId);
+        ctx.dependencyResults.releaseConsumer(jobId);
+        if (validJob.customId && ctx.customIdMap.get(validJob.customId) === jobId) {
+            ctx.customIdMap.delete(validJob.customId);
+        }
     });
-    ctx.storage?.saveDlqEntry(entry);
-    ctx.storage?.deleteJob(jobId);
     return true;
 }

package/dist/application/postgres-queue-manager/batchSnapshot.d.ts

@@ -0,0 +1,16 @@
+import type { Job, JobId } from '../../domain/types/job';
+import type { PostgresJobState } from '../../infrastructure/persistence/postgres';
+import type { PostgresQueueSnapshot } from './snapshot';
+interface BatchCompletionItem {
+    readonly id: JobId;
+    readonly result?: unknown;
+}
+interface BatchCompletionTransition {
+    readonly applied: boolean;
+    readonly job: Job | null;
+    readonly state: PostgresJobState | null;
+    readonly removed: boolean;
+}
+/** Apply an authoritative batch result without reloading every job in its queue. */
+export declare function applyPostgresBatchCompletion(snapshot: PostgresQueueSnapshot, item: BatchCompletionItem, transition: BatchCompletionTransition): string | null;
+export {};

package/dist/application/postgres-queue-manager/batchSnapshot.js

@@ -0,0 +1,17 @@
+/** Apply an authoritative batch result without reloading every job in its queue. */
+export function applyPostgresBatchCompletion(snapshot, item, transition) {
+    if (!transition.applied || !transition.job || transition.state !== 'completed')
+        return null;
+    snapshot.apply({
+        id: 0,
+        queue: transition.job.queue,
+        type: 'completed',
+        jobId: item.id,
+        occurredAt: transition.job.completedAt ?? Date.now(),
+        job: transition.job,
+        state: 'completed',
+        result: item.result,
+        removed: transition.removed,
+    });
+    return transition.job.repeat === null ? null : transition.job.queue;
+}

package/dist/application/postgres-queue-manager/cloud.d.ts

@@ -0,0 +1,30 @@
+import type { JobId } from '../../domain/types/job';
+import type { PostgresCloudReadModel } from '../../infrastructure/persistence/postgres/cloudReadModel';
+import { PostgresQueueManagerServices } from './services';
+/** PostgreSQL-specific Cloud read port with no eventually-consistent fallback. */
+export declare class PostgresQueueManagerCloud extends PostgresQueueManagerServices {
+    getCloudProcessStats(): {
+        waiting: number;
+        prioritized: number;
+        delayed: number;
+        active: number;
+        dlq: number;
+        completed: number;
+        'waiting-children': number;
+        totalPushed: bigint;
+        totalPulled: bigint;
+        totalCompleted: bigint;
+        totalFailed: bigint;
+        uptime: number;
+        cronJobs: number;
+        cronPending: number;
+    };
+    readCloudSnapshotDurable(): Promise<PostgresCloudReadModel>;
+    listCloudJobsDurable(queue: string, options?: {
+        state?: string | string[];
+        start?: number;
+        end?: number;
+        asc?: boolean;
+    }): Promise<import("../../domain/types").Job[]>;
+    getCloudResultDurable(id: JobId): Promise<unknown>;
+}

package/dist/application/postgres-queue-manager/cloud.js

@@ -0,0 +1,55 @@
+import { PostgresQueueManagerServices } from './services';
+const POSTGRES_STATES = new Set([
+    'waiting',
+    'prioritized',
+    'delayed',
+    'waiting-children',
+    'active',
+    'completed',
+    'failed',
+]);
+function pageIndex(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)));
+}
+function durableStates(value) {
+    if (value === undefined)
+        return undefined;
+    const requested = Array.isArray(value) ? value : [value];
+    const normalized = requested.flatMap((state) => state === 'paused' ? ['waiting', 'prioritized'] : [state]);
+    return [...new Set(normalized)].filter((state) => POSTGRES_STATES.has(state));
+}
+/** PostgreSQL-specific Cloud read port with no eventually-consistent fallback. */
+export class PostgresQueueManagerCloud extends PostgresQueueManagerServices {
+    getCloudProcessStats() {
+        return super.getStats();
+    }
+    async readCloudSnapshotDurable() {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.loadCloudReadModel();
+        });
+    }
+    async listCloudJobsDurable(queue, options = {}) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const start = pageIndex(options.start, 0);
+            const end = Math.max(start, pageIndex(options.end, 100));
+            const rows = await this.postgresStore.list(queue, {
+                states: durableStates(options.state),
+                offset: start,
+                limit: end - start,
+                asc: options.asc ?? true,
+            });
+            return rows.map((row) => row.job);
+        });
+    }
+    async getCloudResultDurable(id) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const result = await this.postgresStore.getResult(id);
+            return result.found ? result.result : null;
+        });
+    }
+}

package/dist/application/postgres-queue-manager/config.d.ts

@@ -0,0 +1,5 @@
+import type { PostgresStorageConfig } from '../../infrastructure/persistence/postgres';
+import type { QueueManagerConfig } from '../types';
+export interface PostgresQueueManagerConfig extends Omit<QueueManagerConfig, 'dataPath'> {
+    readonly postgres: PostgresStorageConfig;
+}

package/dist/application/postgres-queue-manager/config.js

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

package/dist/application/postgres-queue-manager/control.d.ts

@@ -0,0 +1,26 @@
+import { type DlqConfig } from '../../domain/types/dlq';
+import { type StallConfig } from '../../domain/types/stall';
+import { PostgresQueueManagerMaintenance } from './maintenance';
+/** Durable queue controls and policies shared by every PostgreSQL broker. */
+export declare class PostgresQueueManagerControl extends PostgresQueueManagerMaintenance {
+    pause(queue: string): void;
+    resume(queue: string): void;
+    pauseDurable(queue: string, paused: boolean): Promise<void>;
+    drain(queue: string): number;
+    drainDurable(queue: string): Promise<number>;
+    obliterate(queue: string): void;
+    obliterateDurable(queue: string): Promise<void>;
+    setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
+    clearRateLimit(queue: string): void;
+    setConcurrency(queue: string, limit: number): void;
+    clearConcurrency(queue: string): void;
+    setRateLimitDurable(queue: string, limit: number | null, durationMs: number | null, ttlMs?: number | null): Promise<void>;
+    setConcurrencyDurable(queue: string, limit: number | null): Promise<void>;
+    setStallConfig(queue: string, patch: Record<string, unknown>): void;
+    getStallConfig(queue: string): StallConfig;
+    setStallConfigDurable(queue: string, patch: Record<string, unknown>): Promise<void>;
+    setDlqConfig(queue: string, patch: Record<string, unknown>): void;
+    getDlqConfig(queue: string): DlqConfig;
+    setDlqConfigDurable(queue: string, patch: Record<string, unknown>): Promise<void>;
+    private setLocalQueueState;
+}

package/dist/application/postgres-queue-manager/control.js

@@ -0,0 +1,186 @@
+import { DEFAULT_DLQ_CONFIG } from '../../domain/types/dlq';
+import { DEFAULT_STALL_CONFIG } from '../../domain/types/stall';
+import { normalizePostgresRateLimit } from '../../infrastructure/persistence/postgres/rateLimit';
+import { PostgresQueueManagerMaintenance } from './maintenance';
+const PENDING_STATES = ['waiting', 'prioritized', 'delayed', 'waiting-children'];
+function normalizeDlq(current, patch) {
+    const next = { ...current };
+    if (typeof patch.autoRetry === 'boolean')
+        next.autoRetry = patch.autoRetry;
+    if (Number.isFinite(patch.autoRetryInterval)) {
+        next.autoRetryInterval = Math.max(0, Math.floor(patch.autoRetryInterval));
+    }
+    if (Number.isFinite(patch.maxAutoRetries)) {
+        next.maxAutoRetries = Math.max(0, Math.floor(patch.maxAutoRetries));
+    }
+    if (patch.maxAge === null)
+        next.maxAge = null;
+    else if (Number.isFinite(patch.maxAge)) {
+        next.maxAge = Math.max(0, Math.floor(patch.maxAge));
+    }
+    if (Number.isFinite(patch.maxEntries)) {
+        next.maxEntries = Math.max(1, Math.floor(patch.maxEntries));
+    }
+    return next;
+}
+/** Durable queue controls and policies shared by every PostgreSQL broker. */
+export class PostgresQueueManagerControl extends PostgresQueueManagerMaintenance {
+    pause(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { paused: true });
+            this.enqueueWrite(() => this.postgresStore.pause(queue, true));
+        });
+    }
+    resume(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { paused: false });
+            this.enqueueWrite(() => this.postgresStore.pause(queue, false));
+        });
+    }
+    async pauseDurable(queue, paused) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.pause(queue, paused);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    drain(queue) {
+        return this.operations.runSync(() => {
+            const count = this.postgresSnapshot.removeStates(queue, PENDING_STATES);
+            this.enqueueWrite(async () => {
+                await this.postgresStore.drain(queue);
+                await this.refreshQueueAfterCommit(queue);
+            });
+            return count;
+        });
+    }
+    async drainDurable(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const count = await this.postgresStore.drain(queue);
+            await this.refreshQueueAfterCommit(queue);
+            return count;
+        });
+    }
+    obliterate(queue) {
+        this.operations.runSync(() => {
+            this.postgresSnapshot.removeStates(queue, [
+                ...PENDING_STATES,
+                'active',
+                'completed',
+                'failed',
+            ]);
+            this.enqueueWrite(async () => {
+                await this.postgresStore.obliterate(queue);
+                await this.refreshQueueAfterCommit(queue);
+            });
+        });
+    }
+    async obliterateDurable(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.obliterate(queue);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setRateLimit(queue, limit, durationMs, ttlMs) {
+        this.operations.runSync(() => {
+            const normalized = normalizePostgresRateLimit(durationMs, ttlMs);
+            this.setLocalQueueState(queue, {
+                rateLimit: limit,
+                rateDurationMs: normalized.durationMs,
+                rateExpiresAt: normalized.ttlMs === null ? null : Date.now() + normalized.ttlMs,
+            });
+            this.enqueueWrite(() => this.postgresStore.setRateLimit(queue, limit, normalized.durationMs, normalized.ttlMs));
+        });
+    }
+    clearRateLimit(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, {
+                rateLimit: null,
+                rateDurationMs: null,
+                rateExpiresAt: null,
+            });
+            this.enqueueWrite(() => this.postgresStore.setRateLimit(queue, null, null));
+        });
+    }
+    setConcurrency(queue, limit) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { concurrencyLimit: limit });
+            this.enqueueWrite(() => this.postgresStore.setConcurrency(queue, limit));
+        });
+    }
+    clearConcurrency(queue) {
+        this.operations.runSync(() => {
+            this.setLocalQueueState(queue, { concurrencyLimit: null });
+            this.enqueueWrite(() => this.postgresStore.setConcurrency(queue, null));
+        });
+    }
+    async setRateLimitDurable(queue, limit, durationMs, ttlMs) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const normalized = normalizePostgresRateLimit(durationMs, ttlMs);
+            await this.postgresStore.setRateLimit(queue, limit, normalized.durationMs, normalized.ttlMs);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    async setConcurrencyDurable(queue, limit) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.setConcurrency(queue, limit);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setStallConfig(queue, patch) {
+        this.operations.runSync(() => {
+            const config = { ...this.getStallConfig(queue), ...patch };
+            this.setLocalQueueState(queue, { stallConfig: config });
+            this.enqueueWrite(() => this.postgresStore.setStallConfig(queue, config));
+        });
+    }
+    getStallConfig(queue) {
+        return this.postgresSnapshot.queueState(queue)?.stallConfig ?? DEFAULT_STALL_CONFIG;
+    }
+    async setStallConfigDurable(queue, patch) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const state = await this.postgresStore.getQueueState(queue);
+            const config = { ...state.stallConfig, ...patch };
+            await this.postgresStore.setStallConfig(queue, config);
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setDlqConfig(queue, patch) {
+        this.operations.runSync(() => {
+            const config = normalizeDlq(this.getDlqConfig(queue), patch);
+            this.setLocalQueueState(queue, { dlqConfig: config });
+            this.enqueueWrite(() => this.postgresStore.setDlqConfig(queue, config));
+        });
+    }
+    getDlqConfig(queue) {
+        return this.postgresSnapshot.queueState(queue)?.dlqConfig ?? DEFAULT_DLQ_CONFIG;
+    }
+    async setDlqConfigDurable(queue, patch) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const state = await this.postgresStore.getQueueState(queue);
+            await this.postgresStore.setDlqConfig(queue, normalizeDlq(state.dlqConfig, patch));
+            await this.refreshQueueAfterCommit(queue);
+        });
+    }
+    setLocalQueueState(queue, patch) {
+        const current = this.postgresSnapshot.queueState(queue) ?? {
+            queue,
+            paused: false,
+            rateLimit: null,
+            rateDurationMs: null,
+            rateWindowStartedAt: null,
+            rateExpiresAt: null,
+            rateCount: 0,
+            concurrencyLimit: null,
+            stallConfig: DEFAULT_STALL_CONFIG,
+            dlqConfig: DEFAULT_DLQ_CONFIG,
+        };
+        this.postgresSnapshot.setQueueState({ ...current, ...patch });
+    }
+}

package/dist/application/postgres-queue-manager/deferredWrites.d.ts

@@ -0,0 +1,13 @@
+export declare function throwDeferredWriteErrors(errors: readonly unknown[], message?: string): void;
+/** Serializes fire-and-forget writes while retaining failures until an observed drain. */
+export declare class PostgresDeferredWriteQueue {
+    private accepting;
+    private tail;
+    private nextSequence;
+    private readonly failures;
+    private checkpoint;
+    enqueue(operation: () => Promise<void>): void;
+    closeAndDrain(): Promise<unknown[]>;
+    drain(): Promise<unknown[]>;
+    flush(): Promise<void>;
+}

package/dist/application/postgres-queue-manager/deferredWrites.js

@@ -0,0 +1,60 @@
+export function throwDeferredWriteErrors(errors, message = 'Multiple deferred PostgreSQL writes failed') {
+    if (errors.length === 0)
+        return;
+    if (errors.length === 1)
+        throw errors[0];
+    throw new AggregateError(errors, message);
+}
+/** Serializes fire-and-forget writes while retaining failures until an observed drain. */
+export class PostgresDeferredWriteQueue {
+    accepting = true;
+    tail = Promise.resolve();
+    nextSequence = 0;
+    failures = [];
+    checkpoint = null;
+    enqueue(operation) {
+        if (!this.accepting)
+            throw new Error('PostgreSQL queue manager is shutting down');
+        const sequence = ++this.nextSequence;
+        this.tail = this.tail.then(async () => {
+            try {
+                await operation();
+            }
+            catch (error) {
+                this.failures.push({ sequence, error });
+            }
+        });
+    }
+    closeAndDrain() {
+        this.accepting = false;
+        return this.drain();
+    }
+    async drain() {
+        const throughSequence = this.nextSequence;
+        const pending = this.checkpoint;
+        if (pending?.sequence === throughSequence)
+            return [...(await pending.result)];
+        const throughTail = this.tail;
+        const checkpoint = {
+            sequence: throughSequence,
+            result: throughTail.then(() => {
+                const firstLaterFailure = this.failures.findIndex(({ sequence }) => sequence > throughSequence);
+                const observed = firstLaterFailure === -1
+                    ? this.failures.splice(0)
+                    : this.failures.splice(0, firstLaterFailure);
+                return observed.map(({ error }) => error);
+            }),
+        };
+        this.checkpoint = checkpoint;
+        try {
+            return [...(await checkpoint.result)];
+        }
+        finally {
+            if (this.checkpoint === checkpoint)
+                this.checkpoint = null;
+        }
+    }
+    async flush() {
+        throwDeferredWriteErrors(await this.drain());
+    }
+}

package/dist/application/postgres-queue-manager/delivery.d.ts

@@ -0,0 +1,19 @@
+import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../../domain/types/flow';
+import { type Job, type JobId, type JobInput } from '../../domain/types/job';
+import { PostgresQueueManagerTerminalDelivery } from './terminalDelivery';
+export declare class PostgresQueueManagerDelivery extends PostgresQueueManagerTerminalDelivery {
+    push(queue: string, input: JobInput): Promise<Job>;
+    pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
+    pushFlow(batch: AtomicFlowBatchInput): Promise<AtomicFlowBatchResult>;
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
+        job: Job | null;
+        token: string | null;
+    }>;
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
+        jobs: Job[];
+        tokens: string[];
+    }>;
+    private claimUntil;
+}

package/dist/application/postgres-queue-manager/delivery.js

@@ -0,0 +1,80 @@
+import { createJob, DEFAULT_LOCK_TTL, generateJobId, jobId, } from '../../domain/types/job';
+import { validateRepeatJobInput } from '../repeatJobs';
+import { PostgresQueueManagerTerminalDelivery } from './terminalDelivery';
+export class PostgresQueueManagerDelivery extends PostgresQueueManagerTerminalDelivery {
+    async push(queue, input) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            validateRepeatJobInput(input);
+            const id = input.customId ? jobId(input.customId) : generateJobId();
+            const admitted = await this.postgresStore.insert(createJob(id, queue, input, await this.postgresStore.now()));
+            await this.refreshJob(admitted.job.id, queue);
+            return admitted.job;
+        });
+    }
+    async pushBatch(queue, inputs) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            for (const input of inputs)
+                validateRepeatJobInput(input);
+            const now = await this.postgresStore.now();
+            const jobs = inputs.map((input) => createJob(input.customId ? jobId(input.customId) : generateJobId(), queue, input, now));
+            const stored = await this.postgresStore.insertMany(jobs);
+            await this.refreshJobs(stored.map((job) => job.id), queue);
+            return stored.map((job) => job.id);
+        });
+    }
+    async pushFlow(batch) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const jobs = await this.postgresStore.insertFlow(batch);
+            await Promise.all(new Set(jobs.map((job) => job.queue))
+                .values()
+                .map((queue) => this.refreshQueueAfterCommit(queue)));
+            return { jobs };
+        });
+    }
+    async pull(queue, timeoutMs = 0, signal) {
+        const claims = await this.claimUntil(queue, 1, this.postgresStore.config.brokerId, timeoutMs, undefined, signal);
+        return claims[0]?.job ?? null;
+    }
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
+        const claims = await this.claimUntil(queue, 1, owner, timeoutMs, lockTtl, signal);
+        const claim = claims[0];
+        return claim ? { job: claim.job, token: claim.token } : { job: null, token: null };
+    }
+    async pullBatch(queue, count, timeoutMs = 0, signal) {
+        const claims = await this.claimUntil(queue, count, this.postgresStore.config.brokerId, timeoutMs, undefined, signal);
+        return claims.map((claim) => claim.job);
+    }
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lease policy
+    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
+        const claims = await this.claimUntil(queue, count, owner, timeoutMs, lockTtl, signal);
+        return {
+            jobs: claims.map((claim) => claim.job),
+            tokens: claims.map((claim) => claim.token),
+        };
+    }
+    // oxlint-disable-next-line max-params -- internal bridge mirrors the public pull contract
+    async claimUntil(queue, count, owner, timeoutMs, leaseDurationMs, signal) {
+        await this.postgresReady;
+        await this.flushPostgresWrites();
+        const deadline = Date.now() + Math.max(0, timeoutMs);
+        do {
+            const claims = await this.runPostgresOperation(async () => {
+                const admitted = await this.postgresStore.claim(queue, count, owner, leaseDurationMs);
+                for (const claim of admitted) {
+                    this.applyPostgresClaim(claim);
+                }
+                return admitted;
+            });
+            if (claims.length > 0 || timeoutMs <= 0 || signal?.aborted)
+                return claims;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return [];
+            await this.postgresStore.waitForWork(queue, Math.min(remaining, this.postgresStore.config.pollIntervalMs), signal);
+        } while (!signal?.aborted);
+        return [];
+    }
+}

package/dist/application/postgres-queue-manager/lease.d.ts

@@ -0,0 +1,13 @@
+import { type JobId, type JobLock, type LockToken } from '../../domain/types/job';
+import { PostgresQueueManagerDelivery } from './delivery';
+export declare class PostgresQueueManagerLease extends PostgresQueueManagerDelivery {
+    extendLock(id: JobId | string, token: string | null, duration: number): Promise<boolean>;
+    heartbeatDurable(id: JobId, token?: string, duration?: number): Promise<boolean>;
+    heartbeatBatchDurable(ids: JobId[], tokens?: string[]): Promise<number>;
+    jobHeartbeat(id: JobId, token?: string): boolean;
+    jobHeartbeatBatch(ids: JobId[], tokens?: string[]): number;
+    verifyLock(id: JobId, token: string): boolean;
+    renewJobLock(id: JobId, token: string, ttl?: number): boolean;
+    getLockInfo(id: JobId): JobLock | null;
+    createLock(id: JobId, _owner: string, _ttl?: number): LockToken | null;
+}