bunqueue 2.9.0 → 2.9.2

package/dist/application/operations/pullFinalization.js

@@ -0,0 +1,69 @@
+import { processingShardIndex } from '../../shared/hash';
+import { throughputTracker } from '../throughputTracker';
+function createPulledEvent(job, queue, ctx) {
+    if (!ctx.processingShards[processingShardIndex(job.id)].has(job.id))
+        return null;
+    return {
+        eventType: 'pulled',
+        queue,
+        jobId: job.id,
+        timestamp: Date.now(),
+    };
+}
+function persistActive(job, fallbackStartedAt, ctx) {
+    try {
+        ctx.storage?.markActive(job.id, job.startedAt ?? fallbackStartedAt, job.timeline);
+    }
+    catch {
+        // Non-fatal: the in-memory processing map remains authoritative.
+    }
+}
+function persistActiveBatch(jobs, events, ctx) {
+    const storage = ctx.storage;
+    if (!storage || jobs.length === 0)
+        return;
+    try {
+        storage.markActiveBatch(jobs.map((job, index) => ({
+            jobId: job.id,
+            startedAt: job.startedAt ?? events[index].timestamp,
+            timeline: job.timeline,
+        })));
+    }
+    catch {
+        for (let index = 0; index < jobs.length; index++) {
+            persistActive(jobs[index], events[index].timestamp, ctx);
+        }
+    }
+}
+/** Persist and publish a single processing handoff. */
+export function finalizeProcessing(job, queue, ctx) {
+    const event = createPulledEvent(job, queue, ctx);
+    if (!event)
+        return false;
+    persistActive(job, event.timestamp, ctx);
+    ctx.totalPulled.value++;
+    throughputTracker.pullRate.increment();
+    ctx.broadcast(event);
+    return true;
+}
+/** Persist and publish all processing handoffs with one durable state transaction. */
+export function finalizeProcessingBatch(jobs, queue, ctx) {
+    const delivered = [];
+    const events = [];
+    for (const job of jobs) {
+        const event = createPulledEvent(job, queue, ctx);
+        if (!event)
+            continue;
+        delivered.push(job);
+        events.push(event);
+    }
+    persistActiveBatch(delivered, events, ctx);
+    ctx.totalPulled.value += BigInt(delivered.length);
+    throughputTracker.pullRate.increment(delivered.length);
+    if (ctx.broadcastBatch)
+        ctx.broadcastBatch(events);
+    else
+        for (const event of events)
+            ctx.broadcast(event);
+    return delivered;
+}

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

@@ -3,7 +3,8 @@
  */
 import type { Shard } from '../../domain/queue/shard';
 import { type Job, type JobId } from '../../domain/types/job';
-import type { EventType, JobLocation } from '../../domain/types/queue';
+import type { GroupPullOptions } from '../../domain/types/group';
+import type { EventType, JobEvent, JobLocation } from '../../domain/types/queue';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { RWLock } from '../../shared/lock';
 /** Dependencies shared by the single and batch pull paths. */
@@ -23,11 +24,13 @@ export interface PullContext {
         jobId: JobId;
         timestamp: number;
     }) => void;
+    broadcastBatch?: (events: readonly JobEvent[]) => void;
     dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
 }
 export interface DequeueScan {
     parked: Job[];
     nextRunAt: number | null;
+    groupOptions?: GroupPullOptions;
 }
 export type DequeueResult = {
     status: 'job';
@@ -35,15 +38,13 @@ export type DequeueResult = {
 } | {
     status: 'stop';
 };
-export declare function createDequeueScan(): DequeueScan;
+export declare function createDequeueScan(groupOptions?: GroupPullOptions): DequeueScan;
 /** Restore physical heap membership without changing logical queue state. */
 export declare function restoreParkedJobs(shard: Shard, queue: string, scan: DequeueScan): void;
 /**
- * Remove the best eligible job while retaining ineligible roots in `scan`.
- *
- * A batch reuses one scan, because readiness cannot change while the synchronous
- * shard critical section is held: time is fixed and active FIFO groups only
- * grow. Its parked jobs therefore need to be restored only once after the batch.
+ * Remove the best eligible job from the shard's secondary group indexes.
+ * A batch reuses the same fixed timestamp and group defaults while its
+ * synchronous shard critical section is held.
  */
 export declare function tryDequeueNextJob(shard: Shard, queue: string, now: number, ctx: PullContext, scan: DequeueScan): DequeueResult;
 /** Restore a dequeued job when its handoff to the worker cannot complete. */

package/dist/application/operations/pullStateTransition.js

@@ -4,8 +4,8 @@
 import { isExpired, isReady, MAX_TIMELINE_ENTRIES, } from '../../domain/types/job';
 import { processingShardIndex } from '../../shared/hash';
 import { withWriteLock } from '../../shared/lock';
-export function createDequeueScan() {
-    return { parked: [], nextRunAt: null };
+export function createDequeueScan(groupOptions) {
+    return { parked: [], nextRunAt: null, groupOptions };
 }
 /** Restore physical heap membership without changing logical queue state. */
 export function restoreParkedJobs(shard, queue, scan) {
@@ -15,23 +15,30 @@ export function restoreParkedJobs(shard, queue, scan) {
     scan.parked.length = 0;
 }
 /**
- * Remove the best eligible job while retaining ineligible roots in `scan`.
- *
- * A batch reuses one scan, because readiness cannot change while the synchronous
- * shard critical section is held: time is fixed and active FIFO groups only
- * grow. Its parked jobs therefore need to be restored only once after the batch.
+ * Remove the best eligible job from the shard's secondary group indexes.
+ * A batch reuses the same fixed timestamp and group defaults while its
+ * synchronous shard critical section is held.
  */
 export function tryDequeueNextJob(shard, queue, now, ctx, scan) {
     const priorityQueue = shard.getQueue(queue);
     while (true) {
-        const job = priorityQueue.peek();
+        const grouped = shard.hasGroupScheduler(queue);
+        const candidate = grouped
+            ? shard.peekGroupCandidate(queue, now, scan.groupOptions)
+            : { job: priorityQueue.peek(), nextRunAt: null };
+        if (grouped)
+            scan.nextRunAt = candidate.nextRunAt;
+        const job = candidate.job;
         if (!job)
             return { status: 'stop' };
         if (isExpired(job, now)) {
             // Persistence is removed first so a failed durable delete leaves the
             // in-memory job available for a later attempt.
             ctx.storage?.deleteJob(job.id);
-            priorityQueue.pop();
+            if (grouped)
+                priorityQueue.remove(job.id);
+            else
+                priorityQueue.pop();
             shard.decrementQueued(job.id);
             ctx.jobIndex.delete(job.id);
             ctx.dashboardEmit?.('job:expired', {
@@ -42,19 +49,13 @@ export function tryDequeueNextJob(shard, queue, now, ctx, scan) {
             });
             continue;
         }
-        if (!isReady(job, now)) {
+        if (!grouped && !isReady(job, now)) {
             const delayed = priorityQueue.pop();
             if (delayed)
                 scan.parked.push(delayed);
             scan.nextRunAt = scan.nextRunAt === null ? job.runAt : Math.min(scan.nextRunAt, job.runAt);
             continue;
         }
-        if (job.groupId && shard.isGroupActive(queue, job.groupId)) {
-            const blocked = priorityQueue.pop();
-            if (blocked)
-                scan.parked.push(blocked);
-            continue;
-        }
         // Capacity is consumed only after an eligible job has been found.
         if (!shard.tryAcquireConcurrency(queue)) {
             ctx.dashboardEmit?.('concurrency:rejected', { queue });
@@ -65,14 +66,20 @@ export function tryDequeueNextJob(shard, queue, now, ctx, scan) {
             ctx.dashboardEmit?.('ratelimit:rejected', { queue });
             return { status: 'stop' };
         }
-        const dequeued = priorityQueue.pop();
+        if (job.groupId && !shard.acquireGroup(queue, job.groupId, scan.groupOptions, now)) {
+            shard.releaseConcurrency(queue);
+            return { status: 'stop' };
+        }
+        const dequeued = grouped ? priorityQueue.remove(job.id) : priorityQueue.pop();
         if (!dequeued) {
+            if (job.groupId)
+                shard.releaseGroup(queue, job.groupId);
             shard.releaseConcurrency(queue);
             return { status: 'stop' };
         }
         shard.decrementQueued(dequeued.id);
         if (dequeued.groupId)
-            shard.activateGroup(queue, dequeued.groupId);
+            shard.advanceGroup(queue, dequeued.groupId);
         dequeued.startedAt = now;
         dequeued.lastHeartbeat = now;
         if (dequeued.timeline.length < MAX_TIMELINE_ENTRIES) {

package/dist/application/operations/push.js

@@ -3,6 +3,7 @@
  * Single-job push logic and stable batch re-export
  */
 import { createJob } from '../../domain/types/job';
+import { assertOptionalGroupId } from '../../domain/types/group';
 import { shardIndex } from '../../shared/hash';
 import { latencyTracker } from '../latencyTracker';
 import { throughputTracker } from '../throughputTracker';
@@ -20,6 +21,7 @@ export { pushJobBatch } from './pushBatch';
  * NOTE: customId check happens INSIDE lock to prevent race conditions
  */
 export async function pushJob(queue, input, ctx) {
+    assertOptionalGroupId(input.groupId);
     validateRepeatJobInput(input);
     const startNs = Bun.nanoseconds();
     const idx = shardIndex(queue);
@@ -58,6 +60,7 @@ export async function pushJob(queue, input, ctx) {
             };
             return;
         }
+        shard.assignGroupFifoOrder(job);
         const target = { queue, shard, shardIdx: idx };
         let storageHandled = false;
         if (linkParent) {

package/dist/application/operations/pushBatch.js

@@ -1,4 +1,5 @@
 import { createJob, normalizeJobPayload, } from '../../domain/types/job';
+import { assertOptionalGroupId } from '../../domain/types/group';
 import { shardIndex } from '../../shared/hash';
 import { releaseDependencyCompletionPins } from '../dependencyCompletions';
 import { latencyTracker } from '../latencyTracker';
@@ -13,6 +14,7 @@ import { withPushWriteLocks } from './pushLocks';
 /** Push an ordered batch while preserving its accepted-prefix contract. */
 export async function pushJobBatch(queue, inputs, ctx) {
     for (const input of inputs) {
+        assertOptionalGroupId(input.groupId);
         validateRepeatJobInput(input);
         normalizeJobPayload(input);
     }
@@ -43,6 +45,7 @@ export async function pushJobBatch(queue, inputs, ctx) {
                     resultIds.push(dedupResult.existingId);
                     continue;
                 }
+                shard.assignGroupFifoOrder(job);
                 const target = { queue, shard, shardIdx: idx };
                 let storageHandled = false;
                 if (linkParent) {
@@ -111,13 +114,17 @@ export async function pushJobBatch(queue, inputs, ctx) {
         }
         ctx.totalPushed.value += BigInt(acceptedJobs.length);
         throughputTracker.pushRate.increment(acceptedJobs.length);
-        for (const job of acceptedJobs) {
-            ctx.broadcast({
-                eventType: 'pushed',
-                queue: job.queue,
-                jobId: job.id,
-                timestamp: now,
-            });
+        const events = acceptedJobs.map((job) => ({
+            eventType: 'pushed',
+            queue: job.queue,
+            jobId: job.id,
+            timestamp: now,
+        }));
+        if (ctx.broadcastBatch)
+            ctx.broadcastBatch(events);
+        else {
+            for (const event of events)
+                ctx.broadcast(event);
         }
     }
     if (jobsToInsert.length > 0)

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

@@ -1,7 +1,7 @@
 import type { Shard } from '../../domain/queue/shard';
 import type { Job, JobId } from '../../domain/types/job';
 import type { JobLocation } from '../../domain/types/queue';
-import { type EventType } from '../../domain/types/queue';
+import { type EventType, type JobEvent } from '../../domain/types/queue';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { RWLock } from '../../shared/lock';
 import type { MapLike, SetLike } from '../../shared/lru';
@@ -34,6 +34,7 @@ export interface PushContext {
         jobId: JobId;
         timestamp: number;
     }) => void;
+    broadcastBatch?: (events: readonly JobEvent[]) => void;
     dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
     registerQueueName?: (queue: string) => void;
 }

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

@@ -3,6 +3,10 @@ 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 {
+    setGroupRateLimit(queue: string, groupId: string, max: number, duration: number): Promise<void>;
+    removeGroupRateLimit(queue: string, groupId: string): Promise<number>;
+    setGroupConcurrency(queue: string, groupId: string, concurrency: number): Promise<void>;
+    removeGroupConcurrency(queue: string, groupId: string): Promise<number>;
     pause(queue: string): void;
     resume(queue: string): void;
     pauseDurable(queue: string, paused: boolean): Promise<void>;

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

@@ -25,6 +25,30 @@ function normalizeDlq(current, patch) {
 }
 /** Durable queue controls and policies shared by every PostgreSQL broker. */
 export class PostgresQueueManagerControl extends PostgresQueueManagerMaintenance {
+    async setGroupRateLimit(queue, groupId, max, duration) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.setGroupRateLimit(queue, groupId, max, duration);
+        });
+    }
+    async removeGroupRateLimit(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.removeGroupRateLimit(queue, groupId);
+        });
+    }
+    async setGroupConcurrency(queue, groupId, concurrency) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.setGroupConcurrency(queue, groupId, concurrency);
+        });
+    }
+    async removeGroupConcurrency(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.removeGroupConcurrency(queue, groupId);
+        });
+    }
     pause(queue) {
         this.operations.runSync(() => {
             this.setLocalQueueState(queue, { paused: true });

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

@@ -1,17 +1,18 @@
 import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../../domain/types/flow';
+import { type GroupPullOptions } from '../../domain/types/group';
 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<{
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): 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<{
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
         jobs: Job[];
         tokens: string[];
     }>;

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

@@ -1,3 +1,4 @@
+import { assertGroupPullOptions } from '../../domain/types/group';
 import { createJob, DEFAULT_LOCK_TTL, generateJobId, jobId, } from '../../domain/types/job';
 import { validateRepeatJobInput } from '../repeatJobs';
 import { PostgresQueueManagerTerminalDelivery } from './terminalDelivery';
@@ -34,35 +35,37 @@ export class PostgresQueueManagerDelivery extends PostgresQueueManagerTerminalDe
             return { jobs };
         });
     }
-    async pull(queue, timeoutMs = 0, signal) {
-        const claims = await this.claimUntil(queue, 1, this.postgresStore.config.brokerId, timeoutMs, undefined, signal);
+    async pull(queue, timeoutMs = 0, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, 1, this.postgresStore.config.brokerId, timeoutMs, undefined, signal, groupOptions);
         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);
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lease policy
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, 1, owner, timeoutMs, lockTtl, signal, groupOptions);
         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);
+    async pullBatch(queue, count, timeoutMs = 0, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, count, this.postgresStore.config.brokerId, timeoutMs, undefined, signal, groupOptions);
         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);
+    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const claims = await this.claimUntil(queue, count, owner, timeoutMs, lockTtl, signal, groupOptions);
         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) {
+    async claimUntil(queue, count, owner, timeoutMs, leaseDurationMs, signal, groupOptions) {
+        assertGroupPullOptions(groupOptions);
         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);
+                const admitted = await this.postgresStore.claim(queue, count, owner, leaseDurationMs, groupOptions);
                 for (const claim of admitted) {
                     this.applyPostgresClaim(claim);
                 }

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

@@ -0,0 +1,10 @@
+import { PostgresQueueManagerState } from './state';
+/** Database-authoritative group getters shared by every PostgreSQL broker. */
+export declare class PostgresQueueManagerGroupQueries extends PostgresQueueManagerState {
+    getGroupJobsCount(queue: string, groupId: string): Promise<number>;
+    getGroupsJobsCount(queue: string): Promise<number>;
+    getGroupActiveCount(queue: string, groupId: string): Promise<number>;
+    getGroupRateLimit(queue: string, groupId: string): Promise<import("../../domain/types/group").GroupRateLimitOverride | null>;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): Promise<number>;
+    getGroupConcurrency(queue: string, groupId: string): Promise<number | null>;
+}

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

@@ -0,0 +1,40 @@
+import { PostgresQueueManagerState } from './state';
+/** Database-authoritative group getters shared by every PostgreSQL broker. */
+export class PostgresQueueManagerGroupQueries extends PostgresQueueManagerState {
+    async getGroupJobsCount(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupJobsCount(queue, groupId);
+        });
+    }
+    async getGroupsJobsCount(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupJobsCount(queue);
+        });
+    }
+    async getGroupActiveCount(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupActiveCount(queue, groupId);
+        });
+    }
+    async getGroupRateLimit(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupRateLimit(queue, groupId);
+        });
+    }
+    async getGroupRateLimitTtl(queue, groupId, maxJobs) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupRateLimitTtl(queue, groupId, maxJobs);
+        });
+    }
+    async getGroupConcurrency(queue, groupId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getGroupConcurrency(queue, groupId);
+        });
+    }
+}

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

@@ -1,7 +1,7 @@
 import { type DlqEntry, type DlqFilter, type DlqStats } from '../../domain/types/dlq';
 import type { Job, JobId } from '../../domain/types/job';
-import { PostgresQueueManagerState } from './state';
-export declare class PostgresQueueManagerQueries extends PostgresQueueManagerState {
+import { PostgresQueueManagerGroupQueries } from './groupQueries';
+export declare class PostgresQueueManagerQueries extends PostgresQueueManagerGroupQueries {
     getJobIndex(): Map<JobId, import("../../domain/types").JobLocation>;
     getCompletedJobs(): Set<JobId>;
     getDepCompletions(): Set<JobId>;

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

@@ -1,4 +1,4 @@
-import { PostgresQueueManagerState } from './state';
+import { PostgresQueueManagerGroupQueries } from './groupQueries';
 function jobCounts(counts, totals) {
     return {
         waiting: counts.waiting,
@@ -12,7 +12,7 @@ function jobCounts(counts, totals) {
         totalFailed: Number(totals?.totalFailed ?? 0n),
     };
 }
-export class PostgresQueueManagerQueries extends PostgresQueueManagerState {
+export class PostgresQueueManagerQueries extends PostgresQueueManagerGroupQueries {
     getJobIndex() {
         return this.postgresSnapshot.locations();
     }

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

@@ -95,6 +95,7 @@ export class QueueManagerControl extends QueueManagerQueries {
         this.perQueueMetrics.delete(queue);
         this.telemetryJournal.clearQueue(queue);
         this.storage?.deleteQueueState(queue);
+        this.storage?.deleteGroupState(queue);
     }
     listQueues() {
         return Array.from(this.queueNamesCache);

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

@@ -1,17 +1,18 @@
 import type { Job, JobId, JobInput, JobLock } from '../../domain/types/job';
 import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../../domain/types/flow';
+import type { GroupPullOptions } from '../../domain/types/group';
 import { QueueManagerState } from './state';
 export declare class QueueManagerDelivery extends QueueManagerState {
     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<{
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): 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<{
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<{
         jobs: Job[];
         tokens: string[];
     }>;

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

@@ -20,29 +20,36 @@ export class QueueManagerDelivery extends QueueManagerState {
     async pushFlow(batch) {
         return pushFlowBatch(batch, this.contextFactory.getPushContext());
     }
-    async pull(queue, timeoutMs = 0, signal) {
-        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
+    async pull(queue, timeoutMs = 0, signal, groupOptions) {
+        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal, groupOptions);
         if (job)
             this.scheduleJobTimeout(job);
         return job;
     }
-    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
-        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lock policy
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal, groupOptions);
         if (!job)
             return { job: null, token: null };
         const token = lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl);
         this.scheduleJobTimeout(job);
         return { job, token };
     }
-    async pullBatch(queue, count, timeoutMs = 0, signal) {
-        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
+    async pullBatch(queue, count, timeoutMs = 0, signal, groupOptions) {
+        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), {
+            signal,
+            group: groupOptions,
+        });
         for (const job of jobs)
             this.scheduleJobTimeout(job);
         return jobs;
     }
     // oxlint-disable-next-line max-params -- public API includes cancellation and lock policy
-    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
-        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
+    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal, groupOptions) {
+        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), {
+            signal,
+            group: groupOptions,
+        });
         const tokens = jobs.map((job) => lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl) ?? '');
         for (const job of jobs)
             this.scheduleJobTimeout(job);

package/dist/application/queue-manager/limits.d.ts

@@ -1,7 +1,18 @@
 import type { Job, JobId } from '../../domain/types/job';
 import type { DlqEntry, DlqFilter, DlqStats } from '../../domain/types/dlq';
 import { QueueManagerControl } from './control';
+import { type GroupRateLimitOverride } from '../../domain/types/group';
 export declare class QueueManagerLimits extends QueueManagerControl {
+    getGroupJobsCount(queue: string, groupId: string): number | Promise<number>;
+    getGroupsJobsCount(queue: string): number | Promise<number>;
+    getGroupActiveCount(queue: string, groupId: string): number | Promise<number>;
+    setGroupRateLimit(queue: string, groupId: string, max: number, duration: number): void | Promise<void>;
+    getGroupRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null | Promise<GroupRateLimitOverride | null>;
+    removeGroupRateLimit(queue: string, groupId: string): number | Promise<number>;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): number | Promise<number>;
+    setGroupConcurrency(queue: string, groupId: string, concurrency: number): void | Promise<void>;
+    getGroupConcurrency(queue: string, groupId: string): number | null | Promise<number | null>;
+    removeGroupConcurrency(queue: string, groupId: string): number | Promise<number>;
     getCountsPerPriority(queue: string): Record<number, number>;
     getJobs(queue: string, options?: {
         state?: string | string[];