bunqueue 2.9.0 → 2.9.2

package/README.md

@@ -82,9 +82,12 @@ is not supported. CI validates PostgreSQL 15, 16, 17, and the pinned/recommended
 18.6 release. See the
 [storage guide](https://bunqueue.dev/guide/databases/).
 
-Release images also carry the exact package version. For reproducible
-deployments, pin `ghcr.io/egeominotti/bunqueue:2.9.0`; `latest` points to the
-same multi-arch image at release time.
+Every completed release publishes `ghcr.io/egeominotti/bunqueue` with the exact
+version tag alongside `latest`, the commit SHA and a build timestamp, so pin the
+version tag for reproducible deployments. Confirm the tag exists before pinning
+it, because a release whose pipeline does not complete pushes no image;
+`docker buildx imagetools inspect ghcr.io/egeominotti/bunqueue:<tag>` resolves
+the digest.
 
 Then produce and process from the language you already use:
 
@@ -123,6 +126,7 @@ Python, PHP, Go, Rust and Elixir clients speak the same protocol — see
 - **PostgreSQL 15–18 multi-broker mode** — PostgreSQL 18.6 is recommended;
   database-authoritative claims, fenced
   leases, shared limits, cron, workers, job-state/lifecycle metrics, and failover state
+  ([tested three-broker Docker example](https://bunqueue.dev/examples/postgres-multibroker/))
 - **BullMQ-compatible API** — same `Queue`, `Worker`, `QueueEvents`; [migrating takes minutes](https://bunqueue.dev/guide/migration/)
 - **MCP server included** — 73 tools; AI agents get full queue control out of the box
 - **Everything server-side** — retries with backoff, priorities, cron, rate limits, dead letter queue

package/dist/application/background/recovery/active.d.ts

@@ -1,4 +1,5 @@
 import { type JobId } from '../../../domain/types/job';
 import type { BackgroundContext } from '../../types';
+export declare function restoreGroupPolicies(ctx: BackgroundContext, groupStates: ReturnType<NonNullable<BackgroundContext['storage']>['loadGroupState']>): void;
 export declare function restoreRecoveryPolicies(ctx: BackgroundContext, queueStates: ReturnType<NonNullable<BackgroundContext['storage']>['loadQueueState']>): void;
 export declare function recoverActiveJobs(ctx: BackgroundContext, dlqJobIds: Set<JobId>, now: number): void;

package/dist/application/background/recovery/active.js

@@ -3,6 +3,18 @@ import { calculateBackoff } from '../../../domain/types/job';
 import { isCorruptDependsOn } from '../../../infrastructure/persistence/sqliteSerializer';
 import { shardIndex } from '../../../shared/hash';
 import { quarantineCorruptDependsOn, RECOVERY_BATCH_SIZE } from './shared';
+export function restoreGroupPolicies(ctx, groupStates) {
+    for (const state of groupStates) {
+        const shard = ctx.shards[shardIndex(state.queue)];
+        if (state.rateLimit !== null && state.rateDuration !== null) {
+            shard.setGroupRateLimit(state.queue, state.groupId, state.rateLimit, state.rateDuration);
+        }
+        if (state.concurrencyLimit !== null) {
+            shard.setGroupConcurrency(state.queue, state.groupId, state.concurrencyLimit);
+        }
+        ctx.registerQueueName(state.queue);
+    }
+}
 export function restoreRecoveryPolicies(ctx, queueStates) {
     for (const queueState of queueStates) {
         if (queueState.stallConfig) {

package/dist/application/background/recovery/index.js

@@ -1,5 +1,5 @@
 import { reconcileDependencyCompletionPins } from '../../dependencyCompletions';
-import { recoverActiveJobs, restoreRecoveryPolicies } from './active';
+import { recoverActiveJobs, restoreGroupPolicies, restoreRecoveryPolicies } from './active';
 import { recoverPendingJobs } from './pending';
 import { recoverCompletedJobs, restoreDlq, restoreQueueState } from './restore';
 export function recover(ctx) {
@@ -11,7 +11,9 @@ export function recover(ctx) {
         completedInDatabase.add(record.jobId);
     const dlqJobIds = ctx.storage.loadDlqJobIds();
     const queueStates = ctx.storage.loadQueueState();
+    const groupStates = ctx.storage.loadGroupState();
     restoreRecoveryPolicies(ctx, queueStates);
+    restoreGroupPolicies(ctx, groupStates);
     const now = Date.now();
     recoverActiveJobs(ctx, dlqJobIds, now);
     recoverPendingJobs(ctx, completedInDatabase, now);

package/dist/application/background/recovery/pending.js

@@ -18,6 +18,7 @@ export function recoverPendingJobs(ctx, completedInDatabase, now) {
                 corruptPendingJobs.push(job);
                 continue;
             }
+            shard.assignGroupFifoOrder(job);
             const hasDependencies = job.dependsOn && job.dependsOn.length > 0;
             const recoveredState = persistedJobState(job);
             const wasAlreadyPromoted = recoveredState === 'waiting' ||

package/dist/application/cleanupTasks.js

@@ -26,7 +26,7 @@ export async function cleanup(ctx) {
     }
     await cleanOrphanedProcessingEntries(ctx, now, stallTimeout);
     await cleanStaleWaitingDependencies(ctx, now);
-    cleanUniqueKeysAndGroups(ctx);
+    cleanUniqueKeysAndGroups(ctx, now);
     cleanStalledCandidates(ctx);
     await cleanOrphanedJobIndex(ctx);
     cleanOrphanedJobLocks(ctx);
@@ -103,9 +103,10 @@ async function cleanStaleWaitingDependencies(ctx, now) {
         }
     }
 }
-function cleanUniqueKeysAndGroups(ctx) {
+function cleanUniqueKeysAndGroups(ctx, now) {
     for (let i = 0; i < SHARD_COUNT; i++) {
         const shard = ctx.shards[i];
+        shard.cleanExpiredGroupWindows(now);
         // Clean expired unique keys
         shard.cleanExpiredUniqueKeys();
         // Trim if too many keys remain
@@ -121,19 +122,6 @@ function cleanUniqueKeysAndGroups(ctx) {
                 }
             }
         }
-        // Clean orphaned active groups
-        for (const [_queueName, groups] of shard.activeGroups) {
-            if (groups.size > 1000) {
-                const toRemove = Math.floor(groups.size / 2);
-                const iter = groups.values();
-                for (let j = 0; j < toRemove; j++) {
-                    const { value, done } = iter.next();
-                    if (done)
-                        break;
-                    groups.delete(value);
-                }
-            }
-        }
     }
 }
 function cleanStalledCandidates(ctx) {
@@ -244,7 +232,7 @@ function cleanEmptyQueues(ctx) {
             shard.dlq.delete(queueName);
             shard.uniqueKeys.delete(queueName);
             shard.queueState.delete(queueName);
-            shard.activeGroups.delete(queueName);
+            shard.clearEmptyGroupRuntime(queueName);
             shard.clearQueueLimiters(queueName);
             shard.stallConfig.delete(queueName);
             shard.dlqConfig.delete(queueName);

package/dist/application/contextFactory.js

@@ -102,6 +102,7 @@ export class ContextFactory {
             jobIndex: this.deps.jobIndex,
             totalPushed: this.deps.metrics.totalPushed,
             broadcast: this.deps.eventsManager.broadcast.bind(this.deps.eventsManager),
+            broadcastBatch: this.deps.eventsManager.broadcastBatch.bind(this.deps.eventsManager),
             dashboardEmit: this.callbacks.emitDashboardEvent,
             registerQueueName: this.callbacks.registerQueueName,
         };
@@ -116,6 +117,7 @@ export class ContextFactory {
             jobIndex: this.deps.jobIndex,
             totalPulled: this.deps.metrics.totalPulled,
             broadcast: this.deps.eventsManager.broadcast.bind(this.deps.eventsManager),
+            broadcastBatch: this.deps.eventsManager.broadcastBatch.bind(this.deps.eventsManager),
             dashboardEmit: this.callbacks.emitDashboardEvent,
         };
     }
@@ -139,6 +141,7 @@ export class ContextFactory {
             totalFailed: this.deps.metrics.totalFailed,
             perQueueMetrics: this.deps.perQueueMetrics,
             broadcast: this.deps.eventsManager.broadcast.bind(this.deps.eventsManager),
+            broadcastBatch: this.deps.eventsManager.broadcastBatch.bind(this.deps.eventsManager),
             onJobCompleted: this.callbacks.onJobCompleted,
             onJobFailed: this.callbacks.onJobFailed,
             onJobsCompleted: this.callbacks.onJobsCompleted,

package/dist/application/dlqManager.js

@@ -196,6 +196,7 @@ function requeueCompletedJob(job, ctx) {
         timeline,
     };
     setDlqRetryState(requeued, null);
+    shard.assignGroupFifoOrder(requeued);
     // Commit the durable transition before publishing the new in-memory state.
     // A SQLite failure therefore leaves the completed generation authoritative.
     ctx.storage?.requeueCompletedJob(requeued);

package/dist/application/dlqRetry.js

@@ -44,6 +44,7 @@ function retryEntry(queue, entry, ctx, now, prepareState) {
     if (!canRetry(queue, entry.job, ctx))
         return null;
     const job = prepareRetry(entry.job, now);
+    ctx.shards[shardIndex(queue)].assignGroupFifoOrder(job);
     prepareState(job);
     ctx.storage?.requeueDlqJob(job);
     const removed = ctx.shards[shardIndex(queue)].removeFromDlq(queue, entry.job.id);

package/dist/application/eventsManager.d.ts

@@ -7,11 +7,14 @@ import { EventType, type JobEvent } from '../domain/types/queue';
 import type { WebhookManager } from './webhookManager';
 /** Event subscriber callback */
 export type EventSubscriber = (event: JobEvent) => void;
+export type EventBatchSubscriber = (events: readonly JobEvent[]) => void;
 /** Events manager class */
 export declare class EventsManager {
     private readonly webhookManager;
     /** Use Set for O(1) subscribe/unsubscribe instead of indexOf+splice */
     private readonly subscribers;
+    /** Optional batch path for internal subscribers such as durable telemetry. */
+    private readonly batchSubscribers;
     /** Waiters for specific job completions - for efficient WaitJob implementation */
     private readonly completionWaiters;
     constructor(webhookManager: WebhookManager);
@@ -20,7 +23,7 @@ export declare class EventsManager {
     /** Number of jobs with active completion waiters */
     get completionWaiterCount(): number;
     /** Subscribe to job events - O(1) add and remove */
-    subscribe(callback: EventSubscriber): () => void;
+    subscribe(callback: EventSubscriber, batchCallback?: EventBatchSubscriber): () => void;
     /** Clear all subscribers (for shutdown) */
     clear(): void;
     /**
@@ -38,6 +41,10 @@ export declare class EventsManager {
         timestamp: number;
         error?: string;
     }): void;
+    /** Broadcast an ordered batch while allowing internal subscribers to persist once. */
+    broadcastBatch(events: readonly JobEvent[]): void;
+    private notifyCompletionWaiters;
+    private triggerWebhook;
     /** Map internal event type to webhook event */
     private mapEventToWebhook;
 }

package/dist/application/eventsManager.js

@@ -8,6 +8,8 @@ export class EventsManager {
     webhookManager;
     /** Use Set for O(1) subscribe/unsubscribe instead of indexOf+splice */
     subscribers = new Set();
+    /** Optional batch path for internal subscribers such as durable telemetry. */
+    batchSubscribers = new Map();
     /** Waiters for specific job completions - for efficient WaitJob implementation */
     completionWaiters = new Map();
     constructor(webhookManager) {
@@ -22,15 +24,19 @@ export class EventsManager {
         return this.completionWaiters.size;
     }
     /** Subscribe to job events - O(1) add and remove */
-    subscribe(callback) {
+    subscribe(callback, batchCallback) {
         this.subscribers.add(callback);
+        if (batchCallback)
+            this.batchSubscribers.set(callback, batchCallback);
         return () => {
             this.subscribers.delete(callback); // O(1) instead of O(n)
+            this.batchSubscribers.delete(callback);
         };
     }
     /** Clear all subscribers (for shutdown) */
     clear() {
         this.subscribers.clear();
+        this.batchSubscribers.clear();
         // Clear all waiters
         for (const waiters of this.completionWaiters.values()) {
             for (const waiter of waiters) {
@@ -112,40 +118,81 @@ export class EventsManager {
                 }
             }
         }
-        // Notify completion waiters for WaitJob - O(1) lookup
-        if (hasWaiters) {
-            const jobKey = String(event.jobId);
-            const waiters = this.completionWaiters.get(jobKey);
-            if (waiters) {
-                this.completionWaiters.delete(jobKey);
-                // Only notify non-cancelled waiters
-                for (const waiter of waiters) {
-                    if (!waiter.cancelled) {
-                        waiter.resolve();
-                    }
+        if (hasWaiters)
+            this.notifyCompletionWaiters(event);
+        if (hasWebhooks)
+            this.triggerWebhook(event);
+    }
+    /** Broadcast an ordered batch while allowing internal subscribers to persist once. */
+    broadcastBatch(events) {
+        if (events.length === 0)
+            return;
+        const hasSubscribers = this.subscribers.size > 0;
+        const hasWebhooks = this.webhookManager.hasEnabledWebhooks();
+        const hasWaiters = this.completionWaiters.size > 0;
+        if (!hasSubscribers && !hasWebhooks && !hasWaiters)
+            return;
+        if (hasSubscribers) {
+            for (const [subscriber, batchSubscriber] of this.batchSubscribers) {
+                if (!this.subscribers.has(subscriber))
+                    continue;
+                try {
+                    batchSubscriber(events);
+                }
+                catch {
+                    // Ignore subscriber errors.
                 }
             }
         }
-        // Trigger webhooks - only if there are enabled webhooks
-        if (hasWebhooks) {
-            const webhookEvent = this.mapEventToWebhook(event.eventType);
-            if (webhookEvent) {
-                this.webhookManager
-                    .trigger(webhookEvent, String(event.jobId), event.queue, {
-                    data: event.data,
-                    error: event.error,
-                })
-                    .catch((err) => {
-                    webhookLog.error('Webhook trigger failed', {
-                        event: webhookEvent,
-                        jobId: String(event.jobId),
-                        queue: event.queue,
-                        error: String(err),
-                    });
-                });
+        for (const event of events) {
+            if (hasSubscribers) {
+                for (const subscriber of this.subscribers) {
+                    if (this.batchSubscribers.has(subscriber))
+                        continue;
+                    try {
+                        subscriber(event);
+                    }
+                    catch {
+                        // Ignore subscriber errors and continue with the ordered batch.
+                    }
+                }
             }
+            if (hasWaiters && event.eventType === "completed" /* EventType.Completed */) {
+                this.notifyCompletionWaiters(event);
+            }
+            if (hasWebhooks)
+                this.triggerWebhook(event);
+        }
+    }
+    notifyCompletionWaiters(event) {
+        const jobKey = String(event.jobId);
+        const waiters = this.completionWaiters.get(jobKey);
+        if (!waiters)
+            return;
+        this.completionWaiters.delete(jobKey);
+        for (const waiter of waiters) {
+            if (!waiter.cancelled)
+                waiter.resolve();
         }
     }
+    triggerWebhook(event) {
+        const webhookEvent = this.mapEventToWebhook(event.eventType);
+        if (!webhookEvent)
+            return;
+        this.webhookManager
+            .trigger(webhookEvent, String(event.jobId), event.queue, {
+            data: event.data,
+            error: event.error,
+        })
+            .catch((err) => {
+            webhookLog.error('Webhook trigger failed', {
+                event: webhookEvent,
+                jobId: String(event.jobId),
+                queue: event.queue,
+                error: String(err),
+            });
+        });
+    }
     /** Map internal event type to webhook event */
     mapEventToWebhook(eventType) {
         switch (eventType) {

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

@@ -2,10 +2,7 @@
 import type { Job, JobId } from '../../domain/types/job';
 import type { BatchContext, ExtractedJob, FinalizeContext } from '../types/ack';
 export type { BatchContext, ExtractedJob, FinalizeContext } from '../types/ack';
-/**
- * Group job IDs by processing shard
- * Returns Map<shardIndex, jobIds[]>
- */
+/** Group job IDs by processing shard. */
 export declare function groupByProcShard(jobIds: JobId[]): Map<number, JobId[]>;
 /**
  * Group items by processing shard (with results)

package/dist/application/operations/ackHelpers.js

@@ -4,10 +4,30 @@ import { withWriteLock } from '../../shared/lock';
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { throughputTracker } from '../throughputTracker';
 import { commitRemovedCompletion } from '../dependencyCompletions';
-/**
- * Group job IDs by processing shard
- * Returns Map<shardIndex, jobIds[]>
- */
+/** Batch only when no per-job durable result/removal ordering must be preserved. */
+function persistCompletedBatch(extractedJobs, ctx, includeResults, now) {
+    const storage = ctx.storage;
+    if (!storage || extractedJobs.length === 0)
+        return false;
+    if (extractedJobs.some(({ job, removeOnComplete }) => job.removeOnComplete || removeOnComplete === true) ||
+        (includeResults && extractedJobs.some(({ result }) => result !== undefined))) {
+        return false;
+    }
+    try {
+        storage.markCompletedBatch(extractedJobs.map(({ id: jobId, job }) => ({
+            jobId,
+            completedAt: now,
+            timeline: job.timeline.length < MAX_TIMELINE_ENTRIES
+                ? [...job.timeline, { state: 'completed', timestamp: now }]
+                : job.timeline,
+        })));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Group job IDs by processing shard. */
 export function groupByProcShard(jobIds) {
     const byProcShard = new Map();
     for (const jobId of jobIds) {
@@ -119,6 +139,7 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
     const jobCount = extractedJobs.length;
     const needsBroadcast = ctx.needsBroadcast?.() ?? true;
     const hasPendingDeps = ctx.hasPendingDeps?.() ?? true;
+    const completionBatchPersisted = persistCompletedBatch(extractedJobs, ctx, includeResults, now);
     // Batch counter update
     ctx.totalCompleted.value += BigInt(jobCount);
     // Per-queue completed counter update
@@ -160,8 +181,9 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
             // 2. Update job index and store job data for completed listing
             ctx.jobIndex.set(jobId, { type: 'completed', queueName: job.queue });
             ctx.completedJobsData.set(jobId, job);
-            if (hasStorage)
+            if (hasStorage && !completionBatchPersisted) {
                 storage.markCompleted(jobId, now, job.timeline);
+            }
             // 3. Mark as completed LAST - this is the signal other threads wait for
             ctx.completedJobs.add(jobId);
         }
@@ -180,15 +202,18 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
     }
     // Broadcast events
     if (needsBroadcast) {
-        for (let i = 0; i < jobCount; i++) {
-            const { id: jobId, job, result } = extractedJobs[i];
-            ctx.broadcast({
-                eventType: 'completed',
-                queue: job.queue,
-                jobId,
-                timestamp: now,
-                data: includeResults ? result : undefined,
-            });
+        const events = extractedJobs.map(({ id: jobId, job, result }) => ({
+            eventType: 'completed',
+            queue: job.queue,
+            jobId,
+            timestamp: now,
+            data: includeResults ? result : undefined,
+        }));
+        if (ctx.broadcastBatch)
+            ctx.broadcastBatch(events);
+        else {
+            for (const event of events)
+                ctx.broadcast(event);
         }
     }
     // Notify completions

package/dist/application/operations/flowPush.js

@@ -29,6 +29,7 @@ function assertIdsAvailable(batch, ctx) {
 function prepareJobs(batch, ctx, now) {
     return batch.jobs.map((planned) => {
         const job = createJob(planned.id, planned.queue, planned.input, now);
+        ctx.shards[shardIndex(planned.queue)].assignGroupFifoOrder(job);
         job.timeline.push({ state: initialJobState(job, ctx, now), timestamp: now });
         return job;
     });

package/dist/application/operations/flowValidation.js

@@ -1,3 +1,4 @@
+import { validateGroupId } from '../../domain/types/group';
 import { normalizeJobPayload } from '../../domain/types/job';
 import { validateFlowTopology } from './flowTopologyValidation';
 const MAX_FLOW_JOBS = 10_000;
@@ -52,10 +53,9 @@ function validateOptions(input) {
             throw new Error(`${name} must be a boolean`);
         }
     }
-    if (input.groupId !== undefined &&
-        (typeof input.groupId !== 'string' || input.groupId.length > 256)) {
-        throw new Error('groupId must be a string of at most 256 characters');
-    }
+    const groupError = validateGroupId(input.groupId);
+    if (groupError)
+        throw new Error(groupError);
     if (input.tags !== undefined &&
         (!Array.isArray(input.tags) ||
             input.tags.some((tag) => typeof tag !== 'string' || tag.length > 256))) {

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

@@ -3,13 +3,18 @@
  * Job pull logic with timeout support
  */
 import type { Job } from '../../domain/types/job';
+import { type GroupPullOptions } from '../../domain/types/group';
 import { type PullContext } from './pullStateTransition';
 export type { PullContext } from './pullStateTransition';
+interface PullRequestOptions {
+    signal?: AbortSignal;
+    group?: GroupPullOptions;
+}
 /**
  * Pull next job from queue
  */
-export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext, signal?: AbortSignal): Promise<Job | null>;
+export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
 /**
  * Pull multiple jobs from queue
  */
-export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext, signal?: AbortSignal): Promise<Job[]>;
+export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext, options?: PullRequestOptions): Promise<Job[]>;

package/dist/application/operations/pull.js

@@ -2,10 +2,11 @@
  * Pull Operations
  * Job pull logic with timeout support
  */
+import { assertGroupPullOptions } from '../../domain/types/group';
 import { withWriteLock } from '../../shared/lock';
-import { shardIndex, processingShardIndex } from '../../shared/hash';
+import { shardIndex } from '../../shared/hash';
 import { latencyTracker } from '../latencyTracker';
-import { throughputTracker } from '../throughputTracker';
+import { finalizeProcessing, finalizeProcessingBatch } from './pullFinalization';
 import { createDequeueScan, requeueJob, restoreParkedJobs, tryDequeueNextJob, } from './pullStateTransition';
 /** Wait until either a notification arrives, the next delay matures, or the pull deadline. */
 async function waitForNextCandidate(options) {
@@ -14,64 +15,18 @@ async function waitForNextCandidate(options) {
     const untilNextRun = nextRunAt === null ? remaining : Math.max(1, nextRunAt - now);
     await shard.waitForJob(queue, Math.min(remaining, untilNextRun), signal);
 }
-/**
- * Finish the handoff of a dequeued job: persist active state and broadcast.
- *
- * The job was ALREADY inserted into processingShards and jobIndex was flipped
- * to 'processing' inside the dequeue critical section (tryDequeueNextJob),
- * atomically with the queue pop, so readers never see a stale 'queue'
- * location. Only the bookkeeping that may follow an await happens here.
- *
- * Returns false when the job is no longer in processingShards: a management
- * op (discardJob, moveJobToDelayed, obliterate) claimed it between the
- * dequeue and this call. The claimer owns the job now; the pull must NOT
- * deliver it to a worker nor mark it active.
- */
-function finalizeProcessing(job, queue, ctx) {
-    const procIdx = processingShardIndex(job.id);
-    if (!ctx.processingShards[procIdx].has(job.id))
-        return false;
-    const now = Date.now();
-    try {
-        ctx.storage?.markActive(job.id, job.startedAt ?? now, job.timeline);
-    }
-    catch {
-        // Non-fatal: job is already in processingShards (in-memory source of truth).
-        // On crash, SQLite recovery will handle the stale state.
-    }
-    ctx.totalPulled.value++;
-    throughputTracker.pullRate.increment();
-    ctx.broadcast({
-        eventType: 'pulled',
-        queue,
-        jobId: job.id,
-        timestamp: now,
-    });
-    return true;
-}
-/**
- * Finish the handoff for a batch of dequeued jobs.
- * Returns the jobs actually delivered (claimed jobs are skipped, see above).
- */
-function finalizeProcessingBatch(jobs, queue, ctx) {
-    const delivered = [];
-    for (const job of jobs) {
-        if (finalizeProcessing(job, queue, ctx))
-            delivered.push(job);
-    }
-    return delivered;
-}
 /**
  * Pull next job from queue
  */
-export async function pullJob(queue, timeoutMs, ctx, signal) {
+export async function pullJob(queue, timeoutMs, ctx, signal, groupOptions) {
+    assertGroupPullOptions(groupOptions);
     const startNs = Bun.nanoseconds();
     const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
     const idx = shardIndex(queue);
     while (true) {
         if (signal?.aborted)
             return null;
-        const attempt = await tryPullFromShard(queue, idx, ctx, signal);
+        const attempt = await tryPullFromShard(queue, idx, ctx, signal, groupOptions);
         const job = attempt.job;
         if (job) {
             if (signal?.aborted) {
@@ -112,7 +67,7 @@ export async function pullJob(queue, timeoutMs, ctx, signal) {
 /**
  * Try to pull a job from a specific shard
  */
-async function tryPullFromShard(queue, idx, ctx, signal) {
+async function tryPullFromShard(queue, idx, ctx, signal, groupOptions) {
     return await withWriteLock(ctx.shardLocks[idx], () => {
         if (signal?.aborted)
             return { job: null, nextRunAt: null };
@@ -122,7 +77,7 @@ async function tryPullFromShard(queue, idx, ctx, signal) {
             return { job: null, nextRunAt: null };
         }
         const now = Date.now();
-        const scan = createDequeueScan();
+        const scan = createDequeueScan(groupOptions);
         try {
             const result = tryDequeueNextJob(shard, queue, now, ctx, scan);
             return result.status === 'job'
@@ -137,14 +92,16 @@ async function tryPullFromShard(queue, idx, ctx, signal) {
 /**
  * Pull multiple jobs from queue
  */
-export async function pullJobBatch(queue, count, timeoutMs, ctx, signal) {
+export async function pullJobBatch(queue, count, timeoutMs, ctx, options = {}) {
+    assertGroupPullOptions(options.group);
+    const { signal } = options;
     const startNs = Bun.nanoseconds();
     const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
     const idx = shardIndex(queue);
     while (true) {
         if (signal?.aborted)
             return [];
-        const attempt = await tryPullBatchFromShard(queue, idx, count, ctx, signal);
+        const attempt = await tryPullBatchFromShard(queue, idx, count, ctx, options);
         const jobs = attempt.jobs;
         if (jobs.length > 0) {
             if (signal?.aborted) {
@@ -194,7 +151,8 @@ export async function pullJobBatch(queue, count, timeoutMs, ctx, signal) {
 /**
  * Try to pull multiple jobs from a shard
  */
-async function tryPullBatchFromShard(queue, idx, count, ctx, signal) {
+async function tryPullBatchFromShard(queue, idx, count, ctx, options) {
+    const { signal, group: groupOptions } = options;
     return await withWriteLock(ctx.shardLocks[idx], () => {
         if (signal?.aborted)
             return { jobs: [], nextRunAt: null };
@@ -204,7 +162,7 @@ async function tryPullBatchFromShard(queue, idx, count, ctx, signal) {
         if (state.paused)
             return { jobs, nextRunAt: null };
         const now = Date.now();
-        const scan = createDequeueScan();
+        const scan = createDequeueScan(groupOptions);
         try {
             while (jobs.length < count) {
                 const result = tryDequeueNextJob(shard, queue, now, ctx, scan);

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

@@ -0,0 +1,6 @@
+import type { Job } from '../../domain/types/job';
+import type { PullContext } from './pullStateTransition';
+/** Persist and publish a single processing handoff. */
+export declare function finalizeProcessing(job: Job, queue: string, ctx: PullContext): boolean;
+/** Persist and publish all processing handoffs with one durable state transaction. */
+export declare function finalizeProcessingBatch(jobs: Job[], queue: string, ctx: PullContext): Job[];