bunqueue 2.9.0 → 2.9.2

package/dist/domain/queue/priorityQueue.js

@@ -1,36 +1,29 @@
-/**
- * Indexed Priority Queue
- * Combines binary heap for O(log n) priority operations
- * with Map for O(1) lookups by job ID
- */
+import { copyGroupFifoOrder } from '../job/groupFifoOrder';
 import { comparePriorityEntries } from './priorityQueueOrder';
-/**
- * Indexed Priority Queue implementation with 4-ary heap
- * 4-ary provides better cache locality than binary heap
- * O(log₄ n) push, pop, update
- * O(1) find, has
- */
+/** Indexed map-backed 4-ary heap with O(log4 n) mutations and O(1) lookup. */
 export class IndexedPriorityQueue {
-    /** Branching factor - 4 provides optimal cache performance */
+    hooks;
+    compare;
+    order;
     static D = 4;
     heap = [];
     index = new Map();
-    // Use BigInt to prevent overflow at extreme throughput
     generation = 0n;
-    /** Get current size */
+    hooksActive = false;
+    constructor(hooks, compare = comparePriorityEntries, order) {
+        this.hooks = hooks;
+        this.compare = compare;
+        this.order = order;
+    }
     get size() {
         return this.index.size;
     }
-    /** Check if empty */
     get isEmpty() {
         return this.index.size === 0;
     }
-    /** Push a job into the queue */
     push(job) {
         const gen = this.generation++;
-        // Store in index
         this.index.set(job.id, { job, generation: gen });
-        // Add to heap
         const entry = {
             jobId: job.id,
             priority: job.priority,
@@ -38,32 +31,38 @@ export class IndexedPriorityQueue {
             lifo: job.lifo,
             generation: gen,
         };
+        if (this.order) {
+            const groupFifoOrder = this.order(job);
+            if (groupFifoOrder !== null)
+                entry.groupFifoOrder = groupFifoOrder;
+        }
         this.heap.push(entry);
         this.bubbleUp(this.heap.length - 1);
+        if (this.hooks && (this.hooksActive || job.groupId)) {
+            this.hooksActive = this.hooks.onInsert(job);
+        }
     }
-    /** Pop the highest priority job */
     pop() {
         while (this.heap.length > 0) {
             const entry = this.heap[0];
             const indexed = this.index.get(entry.jobId);
-            // Skip stale entries (generation mismatch = updated or removed)
             if (indexed?.generation !== entry.generation) {
                 this.removeTop();
                 continue;
             }
-            // Remove from both structures
             this.removeTop();
             this.index.delete(entry.jobId);
+            if (this.hooks && this.hooksActive) {
+                this.hooksActive = this.hooks.onRemove(indexed.job);
+            }
             return indexed.job;
         }
         return null;
     }
-    /** Peek at the highest priority job without removing */
     peek() {
         while (this.heap.length > 0) {
             const entry = this.heap[0];
             const indexed = this.index.get(entry.jobId);
-            // Skip stale entries
             if (indexed?.generation !== entry.generation) {
                 this.removeTop();
                 continue;
@@ -72,21 +71,20 @@ export class IndexedPriorityQueue {
         }
         return null;
     }
-    /** Find a job by ID - O(1) */
     find(jobId) {
         return this.index.get(jobId)?.job ?? null;
     }
-    /** Check if job exists - O(1) */
     has(jobId) {
         return this.index.has(jobId);
     }
-    /** Remove a job by ID - O(1) for index, heap cleans lazily */
     remove(jobId) {
         const indexed = this.index.get(jobId);
         if (!indexed)
             return null;
         this.index.delete(jobId);
-        // Heap entry becomes stale, will be skipped on pop
+        if (this.hooks && this.hooksActive) {
+            this.hooksActive = this.hooks.onRemove(indexed.job);
+        }
         return indexed.job;
     }
     /** Update job priority - O(log n). Optionally update the LIFO tie-break flag. */
@@ -95,15 +93,13 @@ export class IndexedPriorityQueue {
         if (!indexed)
             return false;
         const lifo = newLifo ?? indexed.job.lifo;
-        // Create new job with updated priority (immutable pattern)
         const updatedJob = {
             ...indexed.job,
             priority: newPriority,
             lifo,
         };
-        // Create new heap entry with new generation
+        copyGroupFifoOrder(indexed.job, updatedJob);
         const gen = this.generation++;
-        // Update index with new job and generation
         this.index.set(jobId, { job: updatedJob, generation: gen });
         const entry = {
             jobId: updatedJob.id,
@@ -112,8 +108,16 @@ export class IndexedPriorityQueue {
             lifo,
             generation: gen,
         };
+        if (this.order) {
+            const groupFifoOrder = this.order(updatedJob);
+            if (groupFifoOrder !== null)
+                entry.groupFifoOrder = groupFifoOrder;
+        }
         this.heap.push(entry);
         this.bubbleUp(this.heap.length - 1);
+        if (this.hooks && (this.hooksActive || updatedJob.groupId)) {
+            this.hooksActive = this.hooks.onInsert(updatedJob);
+        }
         return true;
     }
     /** Update job runAt (for delay changes) - O(log n) */
@@ -121,14 +125,12 @@ export class IndexedPriorityQueue {
         const indexed = this.index.get(jobId);
         if (!indexed)
             return false;
-        // Create new job with updated runAt (immutable pattern)
         const updatedJob = {
             ...indexed.job,
             runAt: newRunAt,
         };
-        // Create new heap entry with new generation
+        copyGroupFifoOrder(indexed.job, updatedJob);
         const gen = this.generation++;
-        // Update index with new job and generation
         this.index.set(jobId, { job: updatedJob, generation: gen });
         const entry = {
             jobId: updatedJob.id,
@@ -137,19 +139,33 @@ export class IndexedPriorityQueue {
             lifo: updatedJob.lifo,
             generation: gen,
         };
+        if (this.order) {
+            const groupFifoOrder = this.order(updatedJob);
+            if (groupFifoOrder !== null)
+                entry.groupFifoOrder = groupFifoOrder;
+        }
         this.heap.push(entry);
         this.bubbleUp(this.heap.length - 1);
+        if (this.hooks && (this.hooksActive || updatedJob.groupId)) {
+            this.hooksActive = this.hooks.onInsert(updatedJob);
+        }
         return true;
     }
-    /** Get all jobs (for iteration) */
     values() {
         return Array.from(this.index.values()).map((v) => v.job);
     }
-    /** Clear the queue */
     clear() {
+        if (this.hooks) {
+            for (const { job } of this.index.values()) {
+                if (!this.hooksActive)
+                    break;
+                this.hooksActive = this.hooks.onRemove(job);
+            }
+        }
         this.heap = [];
         this.index.clear();
         this.generation = 0n;
+        this.hooksActive = false;
     }
     /**
      * Get the ratio of stale entries in the heap
@@ -180,11 +196,8 @@ export class IndexedPriorityQueue {
         this.heap = validEntries;
         this.heapify();
     }
-    /** Rebuild heap property from arbitrary array - O(n) */
     heapify() {
         const D = IndexedPriorityQueue.D;
-        // Start from last non-leaf node and bubble down
-        // In D-ary heap, last non-leaf is at floor((n-2)/D)
         for (let i = Math.floor((this.heap.length - 2) / D); i >= 0; i--) {
             this.bubbleDown(i);
         }
@@ -193,7 +206,6 @@ export class IndexedPriorityQueue {
     needsCompaction(threshold = 0.2) {
         return this.getStaleRatio() > threshold;
     }
-    // ============ Heap Operations ============
     removeTop() {
         if (this.heap.length <= 1) {
             this.heap.pop();
@@ -207,7 +219,7 @@ export class IndexedPriorityQueue {
         const D = IndexedPriorityQueue.D;
         while (idx > 0) {
             const parentIdx = Math.floor((idx - 1) / D);
-            if (comparePriorityEntries(this.heap[idx], this.heap[parentIdx]) >= 0) {
+            if (this.compare(this.heap[idx], this.heap[parentIdx]) >= 0) {
                 break;
             }
             this.swap(idx, parentIdx);
@@ -223,11 +235,10 @@ export class IndexedPriorityQueue {
             const firstChild = D * idx + 1;
             if (firstChild >= length)
                 break;
-            // Find minimum among up to D children (cache-friendly sequential access)
             let smallest = idx;
             const lastChild = Math.min(firstChild + D, length);
             for (let c = firstChild; c < lastChild; c++) {
-                if (comparePriorityEntries(heap[c], heap[smallest]) < 0) {
+                if (this.compare(heap[c], heap[smallest]) < 0) {
                     smallest = c;
                 }
             }

package/dist/domain/queue/shard/keys.d.ts

@@ -15,4 +15,5 @@ export declare class ShardKeys extends ShardState {
     isGroupActive(queue: string, groupId: string): boolean;
     activateGroup(queue: string, groupId: string): void;
     releaseGroup(queue: string, groupId: string): void;
+    getGroupActiveCount(queue: string, groupId: string): number;
 }

package/dist/domain/queue/shard/keys.js

@@ -29,7 +29,7 @@ export class ShardKeys extends ShardState {
         return this.uniqueKeyManager.getMap();
     }
     isGroupActive(queue, groupId) {
-        return this.activeGroups.get(queue)?.has(groupId) ?? false;
+        return (this.activeGroupCounts.get(queue)?.get(groupId) ?? 0) > 0;
     }
     activateGroup(queue, groupId) {
         let groups = this.activeGroups.get(queue);
@@ -38,8 +38,31 @@ export class ShardKeys extends ShardState {
             this.activeGroups.set(queue, groups);
         }
         groups.add(groupId);
+        let counts = this.activeGroupCounts.get(queue);
+        if (!counts) {
+            counts = new Map();
+            this.activeGroupCounts.set(queue, counts);
+        }
+        counts.set(groupId, (counts.get(groupId) ?? 0) + 1);
     }
     releaseGroup(queue, groupId) {
-        this.activeGroups.get(queue)?.delete(groupId);
+        const counts = this.activeGroupCounts.get(queue);
+        const count = (counts?.get(groupId) ?? 0) - 1;
+        if (count > 0) {
+            counts?.set(groupId, count);
+        }
+        else {
+            counts?.delete(groupId);
+            const groups = this.activeGroups.get(queue);
+            groups?.delete(groupId);
+            if (groups?.size === 0)
+                this.activeGroups.delete(queue);
+        }
+        if (counts?.size === 0)
+            this.activeGroupCounts.delete(queue);
+        this.notify(queue);
+    }
+    getGroupActiveCount(queue, groupId) {
+        return this.activeGroupCounts.get(queue)?.get(groupId) ?? 0;
     }
 }

package/dist/domain/queue/shard/lifecycle.js

@@ -12,6 +12,7 @@ export class ShardLifecycle extends ShardMetrics {
             this.temporalManager.removeDelayed(job.id);
         }
         priorityQueue.clear();
+        this.groupScheduler.clearQueue(queue);
         this.temporalManager.clearIndexForQueue(queue);
         this.counters.adjustQueued(-count);
         this.counters.syncDelayedCount();
@@ -37,7 +38,10 @@ export class ShardLifecycle extends ShardMetrics {
         this.queues.delete(queue);
         this.uniqueKeyManager.clearQueue(queue);
         this.limiterManager.deleteQueue(queue);
+        this.groupScheduler.clearQueue(queue);
+        this.groupLimiterManager.clearQueue(queue);
         this.activeGroups.delete(queue);
+        this.activeGroupCounts.delete(queue);
         return Array.from(removed);
     }
 }

package/dist/domain/queue/shard/limits.d.ts

@@ -1,8 +1,27 @@
-import type { JobId } from '../../types/job';
+import type { Job, JobId } from '../../types/job';
+import type { GroupPullOptions, GroupRateLimitOverride } from '../../types/group';
+import type { GroupCandidate } from '../groupScheduler';
 import type { QueueState } from '../../types/queue';
 import { ShardKeys } from './keys';
 /** Queue rate, concurrency, and resource ownership operations. */
 export declare class ShardLimits extends ShardKeys {
+    hasGroupScheduler(queue: string): boolean;
+    assignGroupFifoOrder(job: Job): void;
+    observeGroupFifoOrder(job: Job): void;
+    peekGroupCandidate(queue: string, now: number, options?: GroupPullOptions): GroupCandidate;
+    acquireGroup(queue: string, groupId: string, options?: GroupPullOptions, now?: number): boolean;
+    advanceGroup(queue: string, groupId: string): void;
+    getGroupJobsCount(queue: string, groupId: string): number;
+    getGroupsJobsCount(queue: string): number;
+    cleanExpiredGroupWindows(now: number): void;
+    clearEmptyGroupRuntime(queue: string): void;
+    setGroupRateLimit(queue: string, groupId: string, max: number, duration: number): void;
+    getGroupRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null;
+    removeGroupRateLimit(queue: string, groupId: string): number;
+    getGroupRateLimitTtl(queue: string, groupId: string, maxJobs?: number): number;
+    setGroupConcurrency(queue: string, groupId: string, concurrency: number): void;
+    getGroupConcurrency(queue: string, groupId: string): number | null;
+    removeGroupConcurrency(queue: string, groupId: string): number;
     setRateLimit(queue: string, limit: number, durationMs?: number, ttlMs?: number): void;
     clearRateLimit(queue: string): void;
     expireRateLimitIfNeeded(queue: string): void;

package/dist/domain/queue/shard/limits.js

@@ -1,6 +1,62 @@
 import { ShardKeys } from './keys';
 /** Queue rate, concurrency, and resource ownership operations. */
 export class ShardLimits extends ShardKeys {
+    hasGroupScheduler(queue) {
+        return this.groupScheduler.isActive(queue);
+    }
+    assignGroupFifoOrder(job) {
+        this.groupScheduler.assignFifoOrder(job);
+    }
+    observeGroupFifoOrder(job) {
+        this.groupScheduler.observeFifoOrder(job);
+    }
+    peekGroupCandidate(queue, now, options) {
+        return this.groupScheduler.peek(queue, now, (groupId) => this.groupLimiterManager.status(queue, groupId, options, this.getGroupActiveCount(queue, groupId), now));
+    }
+    acquireGroup(queue, groupId, options, now) {
+        const acquired = this.groupLimiterManager.acquire(queue, groupId, options, this.getGroupActiveCount(queue, groupId), now);
+        if (acquired)
+            this.activateGroup(queue, groupId);
+        return acquired;
+    }
+    advanceGroup(queue, groupId) {
+        this.groupScheduler.advance(queue, groupId);
+    }
+    getGroupJobsCount(queue, groupId) {
+        return this.groupScheduler.getGroupJobsCount(queue, groupId);
+    }
+    getGroupsJobsCount(queue) {
+        return this.groupScheduler.getGroupsJobsCount(queue);
+    }
+    cleanExpiredGroupWindows(now) {
+        this.groupLimiterManager.pruneExpiredWindows(now);
+    }
+    clearEmptyGroupRuntime(queue) {
+        this.groupScheduler.clearQueue(queue);
+        this.activeGroups.delete(queue);
+        this.activeGroupCounts.delete(queue);
+    }
+    setGroupRateLimit(queue, groupId, max, duration) {
+        this.groupLimiterManager.setRateLimit(queue, groupId, max, duration);
+    }
+    getGroupRateLimit(queue, groupId) {
+        return this.groupLimiterManager.getRateLimit(queue, groupId);
+    }
+    removeGroupRateLimit(queue, groupId) {
+        return this.groupLimiterManager.removeRateLimit(queue, groupId);
+    }
+    getGroupRateLimitTtl(queue, groupId, maxJobs) {
+        return this.groupLimiterManager.getRateLimitTtl(queue, groupId, maxJobs);
+    }
+    setGroupConcurrency(queue, groupId, concurrency) {
+        this.groupLimiterManager.setConcurrency(queue, groupId, concurrency);
+    }
+    getGroupConcurrency(queue, groupId) {
+        return this.groupLimiterManager.getConcurrency(queue, groupId);
+    }
+    removeGroupConcurrency(queue, groupId) {
+        return this.groupLimiterManager.removeConcurrency(queue, groupId);
+    }
     setRateLimit(queue, limit, durationMs, ttlMs) {
         this.limiterManager.setRateLimit(queue, limit, durationMs, ttlMs);
     }

package/dist/domain/queue/shard/state.d.ts

@@ -4,6 +4,8 @@ import { DependencyTracker } from '../dependencyTracker';
 import { DlqShard } from '../dlqShard';
 import { LimiterManager } from '../limiterManager';
 import { IndexedPriorityQueue } from '../priorityQueue';
+import { GroupLimiterManager } from '../groupLimiterManager';
+import { GroupScheduler } from '../groupScheduler';
 import { ShardCounters } from '../shardCounters';
 import { TemporalManager } from '../temporalManager';
 import { UniqueKeyManager } from '../uniqueKeyManager';
@@ -12,9 +14,12 @@ import { WaiterManager } from '../waiterManager';
 export declare class ShardState {
     readonly queues: Map<string, IndexedPriorityQueue>;
     readonly activeGroups: Map<string, Set<string>>;
+    readonly activeGroupCounts: Map<string, Map<string, number>>;
     protected readonly uniqueKeyManager: UniqueKeyManager;
     protected readonly dlqManager: DlqShard;
     protected readonly limiterManager: LimiterManager;
+    protected readonly groupLimiterManager: GroupLimiterManager;
+    protected readonly groupScheduler: GroupScheduler;
     protected readonly dependencyTracker: DependencyTracker;
     protected readonly temporalManager: TemporalManager;
     protected readonly waiterManager: WaiterManager;

package/dist/domain/queue/shard/state.js

@@ -2,6 +2,8 @@ import { DependencyTracker } from '../dependencyTracker';
 import { DlqShard } from '../dlqShard';
 import { LimiterManager } from '../limiterManager';
 import { IndexedPriorityQueue } from '../priorityQueue';
+import { GroupLimiterManager } from '../groupLimiterManager';
+import { GroupScheduler } from '../groupScheduler';
 import { ShardCounters } from '../shardCounters';
 import { TemporalManager } from '../temporalManager';
 import { UniqueKeyManager } from '../uniqueKeyManager';
@@ -10,9 +12,12 @@ import { WaiterManager } from '../waiterManager';
 export class ShardState {
     queues = new Map();
     activeGroups = new Map();
+    activeGroupCounts = new Map();
     uniqueKeyManager = new UniqueKeyManager();
     dlqManager;
     limiterManager = new LimiterManager();
+    groupLimiterManager = new GroupLimiterManager();
+    groupScheduler = new GroupScheduler();
     dependencyTracker = new DependencyTracker();
     temporalManager = new TemporalManager();
     waiterManager = new WaiterManager();
@@ -49,7 +54,10 @@ export class ShardState {
     getQueue(name) {
         let queue = this.queues.get(name);
         if (!queue) {
-            queue = new IndexedPriorityQueue();
+            queue = new IndexedPriorityQueue({
+                onInsert: (job) => this.groupScheduler.insert(name, job, () => this.queues.get(name)?.values() ?? []),
+                onRemove: (job) => this.groupScheduler.remove(name, job),
+            });
             this.queues.set(name, queue);
         }
         return queue;

package/dist/domain/types/commands/core.d.ts

@@ -1,5 +1,6 @@
 import type { AtomicFlowJobInput } from '../flow';
 import type { JobInput } from '../job';
+import type { GroupPullOptions } from '../group';
 import type { BaseCommand } from './base';
 export interface PushCommand extends BaseCommand {
     readonly cmd: 'PUSH';
@@ -72,6 +73,7 @@ export interface PullCommand extends BaseCommand {
     readonly owner?: string;
     readonly lockTtl?: number;
     readonly detach?: boolean;
+    readonly group?: GroupPullOptions;
 }
 export interface PullBatchCommand extends BaseCommand {
     readonly cmd: 'PULLB';
@@ -80,6 +82,7 @@ export interface PullBatchCommand extends BaseCommand {
     readonly timeout?: number;
     readonly owner?: string;
     readonly lockTtl?: number;
+    readonly group?: GroupPullOptions;
 }
 export interface AckCommand extends BaseCommand {
     readonly cmd: 'ACK';

package/dist/domain/types/commands/limits.d.ts

@@ -52,3 +52,44 @@ export interface GetStallConfigCommand extends BaseCommand {
     readonly cmd: 'GetStallConfig';
     readonly queue: string;
 }
+interface GroupCommand extends BaseCommand {
+    readonly queue: string;
+    readonly groupId: string;
+}
+export interface GetGroupJobsCountCommand extends GroupCommand {
+    readonly cmd: 'GetGroupJobsCount';
+}
+export interface GetGroupsJobsCountCommand extends BaseCommand {
+    readonly cmd: 'GetGroupsJobsCount';
+    readonly queue: string;
+    readonly maxCount?: number;
+}
+export interface GetGroupActiveCountCommand extends GroupCommand {
+    readonly cmd: 'GetGroupActiveCount';
+}
+export interface SetGroupRateLimitCommand extends GroupCommand {
+    readonly cmd: 'SetGroupRateLimit';
+    readonly max: number;
+    readonly duration: number;
+}
+export interface GetGroupRateLimitCommand extends GroupCommand {
+    readonly cmd: 'GetGroupRateLimit';
+}
+export interface RemoveGroupRateLimitCommand extends GroupCommand {
+    readonly cmd: 'RemoveGroupRateLimit';
+}
+export interface GetGroupRateLimitTtlCommand extends GroupCommand {
+    readonly cmd: 'GetGroupRateLimitTtl';
+    readonly maxJobs?: number;
+}
+export interface SetGroupConcurrencyCommand extends GroupCommand {
+    readonly cmd: 'SetGroupConcurrency';
+    readonly concurrency: number;
+}
+export interface GetGroupConcurrencyCommand extends GroupCommand {
+    readonly cmd: 'GetGroupConcurrency';
+}
+export interface RemoveGroupConcurrencyCommand extends GroupCommand {
+    readonly cmd: 'RemoveGroupConcurrency';
+}
+export {};

package/dist/domain/types/commands/union.d.ts

@@ -9,5 +9,5 @@ import type * as Monitoring from './monitoring';
 import type * as Protocol from './protocol';
 import type * as Query from './query';
 import type * as Workers from './workers';
-export type Command = Core.PushCommand | Core.PushBatchCommand | Core.PushFlowCommand | Core.PullCommand | Core.PullBatchCommand | Core.AckCommand | Core.AckBatchCommand | Core.FailCommand | Query.GetJobCommand | Query.GetStateCommand | Query.GetResultCommand | Query.GetJobsCommand | Query.GetJobCountsCommand | Query.GetCountsPerPriorityCommand | Query.GetJobByCustomIdCommand | Query.CountCommand | Query.GetProgressCommand | Query.GetChildrenValuesCommand | Management.CancelCommand | Management.ProgressCommand | Management.UpdateCommand | Management.ChangePriorityCommand | Management.PromoteCommand | Management.WaitJobCommand | Management.MoveToDelayedCommand | Management.DiscardCommand | Management.PauseCommand | Management.ResumeCommand | Management.IsPausedCommand | Management.DrainCommand | Management.ObliterateCommand | Management.ListQueuesCommand | Management.CleanCommand | Dlq.DlqCommand | Dlq.GetDlqStatsCommand | Dlq.RetryDlqCommand | Dlq.PurgeDlqCommand | Dlq.RemoveDlqJobCommand | Dlq.RetryCompletedCommand | Dlq.SetDlqConfigCommand | Dlq.GetDlqConfigCommand | Limits.GetQueueLimitsCommand | Limits.GetDeduplicationJobIdCommand | Limits.RemoveDeduplicationKeyCommand | Limits.RemoveJobDeduplicationKeyCommand | Limits.MoveToWaitingChildrenCommand | Limits.RateLimitCommand | Limits.SetConcurrencyCommand | Limits.RateLimitClearCommand | Limits.ClearConcurrencyCommand | Limits.SetStallConfigCommand | Limits.GetStallConfigCommand | Cron.CronCommand | Cron.CronDeleteCommand | Cron.CronListCommand | Cron.CronGetCommand | Monitoring.AddLogCommand | Monitoring.GetLogsCommand | Monitoring.AddWebhookCommand | Monitoring.RemoveWebhookCommand | Monitoring.ListWebhooksCommand | Monitoring.StatsCommand | Monitoring.MetricsCommand | Monitoring.TrimEventsCommand | Monitoring.PrometheusCommand | Monitoring.StorageStatusCommand | Workers.HeartbeatCommand | Workers.JobHeartbeatCommand | Workers.JobHeartbeatBatchCommand | Workers.PingCommand | Workers.RegisterWorkerCommand | Workers.UnregisterWorkerCommand | Workers.ListWorkersCommand | Extended.ClearLogsCommand | Extended.ExtendLockCommand | Extended.ExtendLocksCommand | Extended.ChangeDelayCommand | Extended.SetWebhookEnabledCommand | Extended.CompactMemoryCommand | Extended.UpdateParentCommand | Extended.GetFailedChildrenValuesCommand | Extended.GetIgnoredChildrenFailuresCommand | Extended.RemoveChildDependencyCommand | Extended.RemoveUnprocessedChildrenCommand | Extended.MoveToWaitCommand | Extended.PromoteJobsCommand | Dashboard.DashboardOverviewCommand | Dashboard.DashboardQueuesCommand | Dashboard.DashboardQueueCommand | Protocol.AuthCommand | Protocol.HelloCommand | Protocol.SubscribeEventsCommand | Protocol.UnsubscribeEventsCommand;
+export type Command = Core.PushCommand | Core.PushBatchCommand | Core.PushFlowCommand | Core.PullCommand | Core.PullBatchCommand | Core.AckCommand | Core.AckBatchCommand | Core.FailCommand | Query.GetJobCommand | Query.GetStateCommand | Query.GetResultCommand | Query.GetJobsCommand | Query.GetJobCountsCommand | Query.GetCountsPerPriorityCommand | Query.GetJobByCustomIdCommand | Query.CountCommand | Query.GetProgressCommand | Query.GetChildrenValuesCommand | Management.CancelCommand | Management.ProgressCommand | Management.UpdateCommand | Management.ChangePriorityCommand | Management.PromoteCommand | Management.WaitJobCommand | Management.MoveToDelayedCommand | Management.DiscardCommand | Management.PauseCommand | Management.ResumeCommand | Management.IsPausedCommand | Management.DrainCommand | Management.ObliterateCommand | Management.ListQueuesCommand | Management.CleanCommand | Dlq.DlqCommand | Dlq.GetDlqStatsCommand | Dlq.RetryDlqCommand | Dlq.PurgeDlqCommand | Dlq.RemoveDlqJobCommand | Dlq.RetryCompletedCommand | Dlq.SetDlqConfigCommand | Dlq.GetDlqConfigCommand | Limits.GetQueueLimitsCommand | Limits.GetDeduplicationJobIdCommand | Limits.RemoveDeduplicationKeyCommand | Limits.RemoveJobDeduplicationKeyCommand | Limits.MoveToWaitingChildrenCommand | Limits.RateLimitCommand | Limits.SetConcurrencyCommand | Limits.RateLimitClearCommand | Limits.ClearConcurrencyCommand | Limits.SetStallConfigCommand | Limits.GetStallConfigCommand | Limits.GetGroupJobsCountCommand | Limits.GetGroupsJobsCountCommand | Limits.GetGroupActiveCountCommand | Limits.SetGroupRateLimitCommand | Limits.GetGroupRateLimitCommand | Limits.RemoveGroupRateLimitCommand | Limits.GetGroupRateLimitTtlCommand | Limits.SetGroupConcurrencyCommand | Limits.GetGroupConcurrencyCommand | Limits.RemoveGroupConcurrencyCommand | Cron.CronCommand | Cron.CronDeleteCommand | Cron.CronListCommand | Cron.CronGetCommand | Monitoring.AddLogCommand | Monitoring.GetLogsCommand | Monitoring.AddWebhookCommand | Monitoring.RemoveWebhookCommand | Monitoring.ListWebhooksCommand | Monitoring.StatsCommand | Monitoring.MetricsCommand | Monitoring.TrimEventsCommand | Monitoring.PrometheusCommand | Monitoring.StorageStatusCommand | Workers.HeartbeatCommand | Workers.JobHeartbeatCommand | Workers.JobHeartbeatBatchCommand | Workers.PingCommand | Workers.RegisterWorkerCommand | Workers.UnregisterWorkerCommand | Workers.ListWorkersCommand | Extended.ClearLogsCommand | Extended.ExtendLockCommand | Extended.ExtendLocksCommand | Extended.ChangeDelayCommand | Extended.SetWebhookEnabledCommand | Extended.CompactMemoryCommand | Extended.UpdateParentCommand | Extended.GetFailedChildrenValuesCommand | Extended.GetIgnoredChildrenFailuresCommand | Extended.RemoveChildDependencyCommand | Extended.RemoveUnprocessedChildrenCommand | Extended.MoveToWaitCommand | Extended.PromoteJobsCommand | Dashboard.DashboardOverviewCommand | Dashboard.DashboardQueuesCommand | Dashboard.DashboardQueueCommand | Protocol.AuthCommand | Protocol.HelloCommand | Protocol.SubscribeEventsCommand | Protocol.UnsubscribeEventsCommand;
 export type CommandType = Command['cmd'];

package/dist/domain/types/group.d.ts

@@ -0,0 +1,21 @@
+export interface GroupRateLimit {
+    readonly max: number;
+    readonly duration: number;
+}
+/** Worker-side defaults enforced authoritatively by the broker. */
+export interface GroupPullOptions {
+    readonly concurrency?: number;
+    readonly limit?: GroupRateLimit;
+}
+export interface GroupRateLimitOverride extends GroupRateLimit {
+}
+/** Validate the canonical string form shared by every broker and persistence backend. */
+export declare function validateGroupId(value: unknown, required?: boolean): string | null;
+export declare function assertGroupId(value: unknown): asserts value is string;
+export declare function assertOptionalGroupId(value: unknown): asserts value is string | undefined;
+/** Normalize BullMQ-compatible numeric IDs without accepting arbitrary coercion. */
+export declare function normalizeGroupId(value: unknown): string;
+export declare function validatePositiveSafeInteger(value: unknown, name: string): string | null;
+export declare function assertPositiveSafeInteger(value: unknown, name: string): asserts value is number;
+export declare function validateGroupPullOptions(options: unknown): string | null;
+export declare function assertGroupPullOptions(options: unknown): asserts options is GroupPullOptions;

package/dist/domain/types/group.js

@@ -0,0 +1,78 @@
+/** Validate the canonical string form shared by every broker and persistence backend. */
+export function validateGroupId(value, required = false) {
+    if (value === undefined)
+        return required ? 'groupId is required' : null;
+    if (typeof value !== 'string')
+        return 'groupId must be a string';
+    if (value.length === 0)
+        return 'groupId must be a non-empty string';
+    if (value.length > 256)
+        return 'groupId must be at most 256 characters';
+    if (value.includes('\0'))
+        return 'groupId must not contain NUL characters';
+    return null;
+}
+export function assertGroupId(value) {
+    const error = validateGroupId(value, true);
+    if (error)
+        throw new Error(error);
+}
+export function assertOptionalGroupId(value) {
+    const error = validateGroupId(value);
+    if (error)
+        throw new Error(error);
+}
+/** Normalize BullMQ-compatible numeric IDs without accepting arbitrary coercion. */
+export function normalizeGroupId(value) {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new Error('groupId must be a string or number');
+    }
+    if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+        throw new Error('numeric groupId must be a safe integer');
+    }
+    const groupId = String(value);
+    assertGroupId(groupId);
+    return groupId;
+}
+export function validatePositiveSafeInteger(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        return `${name} must be a positive safe integer`;
+    }
+    return null;
+}
+export function assertPositiveSafeInteger(value, name) {
+    const error = validatePositiveSafeInteger(value, name);
+    if (error)
+        throw new Error(error);
+}
+export function validateGroupPullOptions(options) {
+    if (options === undefined)
+        return null;
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        return 'group must be an object';
+    }
+    const group = options;
+    if (group.concurrency !== undefined) {
+        const error = validatePositiveSafeInteger(group.concurrency, 'group.concurrency');
+        if (error)
+            return error;
+    }
+    if (group.limit !== undefined) {
+        if (!group.limit || typeof group.limit !== 'object' || Array.isArray(group.limit)) {
+            return 'group.limit must be an object';
+        }
+        const limit = group.limit;
+        const maxError = validatePositiveSafeInteger(limit.max, 'group.limit.max');
+        if (maxError)
+            return maxError;
+        const durationError = validatePositiveSafeInteger(limit.duration, 'group.limit.duration');
+        if (durationError)
+            return durationError;
+    }
+    return null;
+}
+export function assertGroupPullOptions(options) {
+    const error = validateGroupPullOptions(options);
+    if (error)
+        throw new Error(error);
+}

package/dist/domain/types/priorityQueue.d.ts

@@ -5,6 +5,7 @@ export interface HeapEntry {
     runAt: number;
     lifo: boolean;
     generation: bigint;
+    groupFifoOrder?: bigint;
 }
 export interface IndexedJob {
     job: Job;

package/dist/infrastructure/persistence/jobOptionsBlob.d.ts

@@ -11,6 +11,7 @@ export interface StoredJobOptions {
     debounceId: string | null;
     debounceTtl: number | null;
     durable: boolean;
+    groupFifoOrder: string | null;
 }
 /** Persist generation policies that do not have dedicated legacy columns. */
 export declare function encodeJobOptions(job: Job): Uint8Array;