bunqueue 2.8.60 → 2.9.2

package/dist/client/queue/runtime/state.d.ts

@@ -18,6 +18,7 @@ export declare class QueueState<T> {
         embedded: boolean;
         tcp: TcpConnectionPool | null;
         prefixKey: string;
+        dataPath: string | undefined;
     };
     protected get addCtx(): {
         opts: QueueOptions;
@@ -55,6 +56,7 @@ export declare class QueueState<T> {
         embedded: boolean;
         tcp: TcpConnectionPool | null;
         prefixKey: string;
+        dataPath: string | undefined;
     };
     protected get queryCtx(): {
         getJobState: (id: string) => Promise<import("../../types").JobStateType>;
@@ -84,6 +86,7 @@ export declare class QueueState<T> {
         embedded: boolean;
         tcp: TcpConnectionPool | null;
         prefixKey: string;
+        dataPath: string | undefined;
     };
     protected get moveCtx(): {
         getJobState: (id: string) => Promise<import("../../types").JobStateType>;
@@ -92,6 +95,7 @@ export declare class QueueState<T> {
         embedded: boolean;
         tcp: TcpConnectionPool | null;
         prefixKey: string;
+        dataPath: string | undefined;
     };
     protected releaseConnection(): void;
 }

package/dist/client/queue/runtime/state.js

@@ -78,6 +78,7 @@ export class QueueState {
             embedded: this.embedded,
             tcp: this.tcpPool,
             prefixKey: this.prefixKey,
+            dataPath: this.opts.dataPath,
         };
     }
     get addCtx() {

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

@@ -4,7 +4,7 @@ export type { ActiveEvent, CompletedEvent, DelayedEvent, DrainedEvent, Duplicate
 export type { FlowJobData, Processor, QueueEventType } from './flow';
 export type { ChangePriorityOpts, GetDependenciesOpts, Job, JobDependencies, JobDependenciesCount, JobJson, JobJsonRaw, JobStateType, } from './job';
 export type { QueueMetrics, QueueMetricsMeta, QueueMetricType } from './metrics';
-export type { BackoffOptions, DebounceOptions, DeduplicationOptions, JobOptions, KeepJobs, ParentOpts, RepeatOptions, } from './options';
-export type { RateLimiterOptions, StallConfig, WorkerOptions } from './worker';
+export type { BackoffOptions, DebounceOptions, DeduplicationOptions, GroupJobOptions, JobOptions, KeepJobs, ParentOpts, RepeatOptions, } from './options';
+export type { GroupWorkerOptions, RateLimiterOptions, StallConfig, WorkerOptions } from './worker';
 export { createPublicJob, toDlqEntry, toPublicJob } from '../jobConversion';
 export type { CreatePublicJobOptions, ToPublicJobOptions } from '../jobConversion';

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

@@ -33,6 +33,9 @@ export interface RepeatOptions {
     offset?: number;
     jobId?: string;
 }
+export interface GroupJobOptions {
+    id: string | number;
+}
 /** Options accepted when adding a job. */
 export interface JobOptions {
     priority?: number;
@@ -59,4 +62,5 @@ export interface JobOptions {
     timestamp?: number;
     deduplication?: DeduplicationOptions;
     debounce?: DebounceOptions;
+    group?: GroupJobOptions;
 }

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

@@ -4,6 +4,13 @@ export interface RateLimiterOptions {
     duration: number;
     groupKey?: string;
 }
+export interface GroupWorkerOptions {
+    concurrency?: number;
+    limit?: {
+        max: number;
+        duration: number;
+    };
+}
 export interface WorkerOptions {
     concurrency?: number;
     autorun?: boolean;
@@ -16,6 +23,7 @@ export interface WorkerOptions {
     pollTimeout?: number;
     useLocks?: boolean;
     limiter?: RateLimiterOptions;
+    group?: GroupWorkerOptions;
     lockDuration?: number;
     maxStalledCount?: number;
     skipStalledCheck?: boolean;

package/dist/client/worker/runtime/execution.js

@@ -39,15 +39,10 @@ export class WorkerExecution extends WorkerPolling {
             if (this.groupLimiter)
                 this.groupLimiter.decrement(job);
             if (this.running && !this._closing)
-                this.poll();
+                this.scheduleProcessing();
         });
-        if (this.activeJobs < this.opts.concurrency && !this._closing && !this.processingScheduled) {
-            this.processingScheduled = true;
-            setImmediate(() => {
-                this.processingScheduled = false;
-                void this.tryProcess();
-            });
-        }
+        if (this.activeJobs < this.opts.concurrency && !this._closing)
+            this.scheduleProcessing();
         return true;
     }
     registerWithServer() {
@@ -118,6 +113,7 @@ export class WorkerExecution extends WorkerPolling {
             useLocks: this.opts.useLocks,
             pollTimeout: this.opts.pollTimeout,
             lockDuration: this.opts.lockDuration,
+            group: this.opts.group,
         };
     }
 }

package/dist/client/worker/runtime/options.js

@@ -1,7 +1,9 @@
+import { assertGroupPullOptions } from '../../../domain/types/group';
 import { resolveToken } from '../../resolveToken';
 import { TcpConnectionPool } from '../../tcpPool';
 import { WORKER_CONSTANTS } from '../constants';
 export function resolveWorkerOptions(options, embedded) {
+    assertGroupPullOptions(options.group);
     return {
         concurrency: options.concurrency ?? 1,
         autorun: options.autorun ?? true,
@@ -18,6 +20,7 @@ export function resolveWorkerOptions(options, embedded) {
         removeOnComplete: options.removeOnComplete,
         removeOnFail: options.removeOnFail,
         connection: options.connection,
+        group: options.group,
     };
 }
 export function createTcpPool(options, concurrency) {

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

@@ -3,6 +3,7 @@ import { WorkerBuffer } from './buffer';
 import type { PulledJob, WorkerDelivery } from './state';
 export declare abstract class WorkerPolling<T = unknown, R = unknown> extends WorkerBuffer<T, R> {
     protected poll(): void;
+    protected scheduleProcessing(): void;
     protected tryProcess(): Promise<void>;
     protected doPullBatch(): Promise<PulledJob[]>;
     private scheduleRateLimitPoll;

package/dist/client/worker/runtime/polling.js

@@ -16,6 +16,15 @@ export class WorkerPolling extends WorkerBuffer {
         }
         void this.tryProcess();
     }
+    scheduleProcessing() {
+        if (!this.running || this._closing || this.processingScheduled)
+            return;
+        this.processingScheduled = true;
+        setImmediate(() => {
+            this.processingScheduled = false;
+            void this.tryProcess();
+        });
+    }
     async tryProcess() {
         if (!this.running || this._closing)
             return;

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

@@ -1,4 +1,4 @@
-import type { ConnectionOptions } from '../../types';
+import type { ConnectionOptions, GroupWorkerOptions } from '../../types';
 export interface ExtendedWorkerOptions {
     concurrency: number;
     autorun: boolean;
@@ -21,4 +21,5 @@ export interface ExtendedWorkerOptions {
         count?: number;
     };
     connection?: ConnectionOptions;
+    group?: GroupWorkerOptions;
 }

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

@@ -4,6 +4,7 @@
  */
 import type { Job as InternalJob } from '../../domain/types/job';
 import type { TcpConnection } from './types';
+import type { GroupWorkerOptions } from '../types';
 export interface PullConfig {
     readonly name: string;
     readonly workerId: string;
@@ -11,6 +12,7 @@ export interface PullConfig {
     readonly pollTimeout: number;
     /** Lock TTL in ms to request from the server on a lock-based pull. */
     readonly lockDuration?: number;
+    readonly group?: GroupWorkerOptions;
 }
 export declare function pullEmbedded(config: PullConfig, count: number): Promise<Array<{
     job: InternalJob;

package/dist/client/worker/workerPull.js

@@ -10,18 +10,18 @@ export async function pullEmbedded(config, count) {
     // configured lock TTL is honored in embedded mode too (undefined → server default).
     if (config.useLocks) {
         if (count === 1) {
-            const { job, token } = await manager.pullWithLock(config.name, config.workerId, 0, config.lockDuration);
+            const { job, token } = await manager.pullWithLock(config.name, config.workerId, 0, config.lockDuration, undefined, config.group);
             return job ? [{ job, token }] : [];
         }
-        const { jobs, tokens } = await manager.pullBatchWithLock(config.name, count, config.workerId, 0, config.lockDuration);
+        const { jobs, tokens } = await manager.pullBatchWithLock(config.name, count, config.workerId, 0, config.lockDuration, undefined, config.group);
         return jobs.map((job, i) => ({ job, token: tokens[i] || null }));
     }
     // No locks - use regular pull
     if (count === 1) {
-        const job = await manager.pull(config.name, 0);
+        const job = await manager.pull(config.name, 0, undefined, config.group);
         return job ? [{ job, token: null }] : [];
     }
-    const jobs = await manager.pullBatch(config.name, count, 0);
+    const jobs = await manager.pullBatch(config.name, count, 0, undefined, config.group);
     return jobs.map((job) => ({ job, token: null }));
 }
 export async function pullTcp(config, tcp, count, closing) {
@@ -36,6 +36,8 @@ export async function pullTcp(config, tcp, count, closing) {
     };
     if (count > 1)
         cmd.count = count;
+    if (config.group)
+        cmd.group = config.group;
     // Only request lock ownership when useLocks is enabled
     if (config.useLocks) {
         cmd.owner = config.workerId;

package/dist/config/resolve.d.ts

@@ -16,6 +16,20 @@ export interface ResolvedConfig {
     tlsKeyFile: string | undefined;
     authTokens: string[];
     dataPath: string | undefined;
+    storageDriver: 'memory' | 'sqlite' | 'postgres';
+    postgresUrl: string | undefined;
+    postgresNamespace: string;
+    postgresBrokerId: string | undefined;
+    postgresPoolSize: number;
+    postgresLeaseDurationMs: number;
+    postgresPollIntervalMs: number;
+    postgresStatementTimeoutMs: number;
+    postgresLockTimeoutMs: number;
+    postgresIdleTransactionTimeoutMs: number;
+    postgresMaxConcurrentOperations: number;
+    postgresMaxQueuedOperations: number;
+    postgresMaxSnapshotJobs: number;
+    postgresMaxSnapshotPayloadBytes: number;
     corsOrigins: string[];
     requireAuthForMetrics: boolean;
     maxPrometheusQueues: number;

package/dist/config/resolve.js

@@ -8,6 +8,19 @@ import { DEFAULTS as S3_DEFAULTS } from '../infrastructure/backup/s3BackupConfig
 /** Resolve server config: config file > env vars > defaults */
 export function resolveServerConfig(fileConfig) {
     const fc = fileConfig;
+    const dataPath = fc?.storage?.dataPath ??
+        Bun.env.BUNQUEUE_DATA_PATH ??
+        Bun.env.BQ_DATA_PATH ??
+        Bun.env.DATA_PATH ??
+        Bun.env.SQLITE_PATH;
+    const postgresUrl = fc?.storage?.url ?? Bun.env.BUNQUEUE_POSTGRES_URL;
+    const storageDriver = fc?.storage?.driver
+        ? resolveStorageDriver(fc.storage.driver, postgresUrl, dataPath)
+        : fc?.storage?.url
+            ? 'postgres'
+            : fc?.storage?.dataPath
+                ? 'sqlite'
+                : resolveStorageDriver(Bun.env.BUNQUEUE_STORAGE_DRIVER, postgresUrl, dataPath);
     return {
         tcpPort: fc?.server?.tcpPort ?? parseInt(Bun.env.TCP_PORT ?? '6789', 10),
         httpPort: fc?.server?.httpPort ?? parseInt(Bun.env.HTTP_PORT ?? '6790', 10),
@@ -17,11 +30,30 @@ export function resolveServerConfig(fileConfig) {
         tlsCertFile: fc?.server?.tlsCertFile ?? Bun.env.TLS_CERT_FILE,
         tlsKeyFile: fc?.server?.tlsKeyFile ?? Bun.env.TLS_KEY_FILE,
         authTokens: fc?.auth?.tokens ?? Bun.env.AUTH_TOKENS?.split(',').filter(Boolean) ?? [],
-        dataPath: fc?.storage?.dataPath ??
-            Bun.env.BUNQUEUE_DATA_PATH ??
-            Bun.env.BQ_DATA_PATH ??
-            Bun.env.DATA_PATH ??
-            Bun.env.SQLITE_PATH,
+        dataPath,
+        storageDriver,
+        postgresUrl,
+        postgresNamespace: fc?.storage?.namespace ?? Bun.env.BUNQUEUE_POSTGRES_NAMESPACE ?? 'default',
+        postgresBrokerId: fc?.storage?.brokerId ?? Bun.env.BUNQUEUE_BROKER_ID,
+        postgresPoolSize: positiveInteger(fc?.storage?.poolSize ?? parseInt(Bun.env.BUNQUEUE_POSTGRES_POOL_SIZE ?? '4', 10), 4),
+        postgresLeaseDurationMs: positiveInteger(fc?.storage?.leaseDurationMs ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_LEASE_DURATION_MS ?? '30000', 10), 30_000),
+        postgresPollIntervalMs: positiveInteger(fc?.storage?.pollIntervalMs ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_POLL_INTERVAL_MS ?? '250', 10), 250),
+        postgresStatementTimeoutMs: positiveInteger(fc?.storage?.statementTimeoutMs ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_STATEMENT_TIMEOUT_MS ?? '30000', 10), 30_000),
+        postgresLockTimeoutMs: positiveInteger(fc?.storage?.lockTimeoutMs ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_LOCK_TIMEOUT_MS ?? '5000', 10), 5_000),
+        postgresIdleTransactionTimeoutMs: positiveInteger(fc?.storage?.idleTransactionTimeoutMs ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_IDLE_TRANSACTION_TIMEOUT_MS ?? '30000', 10), 30_000),
+        postgresMaxConcurrentOperations: positiveInteger(fc?.storage?.maxConcurrentOperations ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_MAX_CONCURRENT_OPERATIONS ?? '16', 10), 16),
+        postgresMaxQueuedOperations: nonNegativeInteger(fc?.storage?.maxQueuedOperations ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_MAX_QUEUED_OPERATIONS ?? '128', 10), 128),
+        postgresMaxSnapshotJobs: positiveInteger(fc?.storage?.maxSnapshotJobs ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_MAX_SNAPSHOT_JOBS ?? '100000', 10), 100_000),
+        postgresMaxSnapshotPayloadBytes: positiveInteger(fc?.storage?.maxSnapshotPayloadBytes ??
+            parseInt(Bun.env.BUNQUEUE_POSTGRES_MAX_SNAPSHOT_PAYLOAD_BYTES ?? '268435456', 10), 256 * 1024 * 1024),
         corsOrigins: fc?.cors?.origins ?? Bun.env.CORS_ALLOW_ORIGIN?.split(',').filter(Boolean) ?? [],
         requireAuthForMetrics: fc?.auth?.requireAuthForMetrics ?? Bun.env.METRICS_AUTH === 'true',
         maxPrometheusQueues: nonNegativeInteger(fc?.telemetry?.maxPrometheusQueues ?? parseInt(Bun.env.METRICS_MAX_QUEUES ?? '100', 10), 100),
@@ -31,9 +63,22 @@ export function resolveServerConfig(fileConfig) {
         statsIntervalMs: fc?.timeouts?.stats ?? parseInt(Bun.env.STATS_INTERVAL_MS ?? '300000', 10),
     };
 }
+function resolveStorageDriver(configured, postgresUrl, dataPath) {
+    if (configured === 'memory' || configured === 'sqlite' || configured === 'postgres') {
+        return configured;
+    }
+    if (configured)
+        throw new Error(`Unsupported storage driver: ${configured}`);
+    if (postgresUrl)
+        return 'postgres';
+    return dataPath ? 'sqlite' : 'memory';
+}
 function nonNegativeInteger(value, fallback) {
     return Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
 }
+function positiveInteger(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
 /**
  * Resolve server TLS options from resolved config. Returns null when TLS is
  * not configured; throws when only one of cert/key is set (fail fast at

package/dist/config/types.d.ts

@@ -20,7 +20,25 @@ export interface BunqueueConfig {
         requireAuthForMetrics?: boolean;
     };
     storage?: {
+        /** Persistence backend. Inferred from url/dataPath when omitted. */
+        driver?: 'memory' | 'sqlite' | 'postgres';
         dataPath?: string;
+        /** PostgreSQL connection URL. Required when driver is postgres. */
+        url?: string;
+        /** Isolates independent bunqueue installations sharing one PostgreSQL database. */
+        namespace?: string;
+        /** Stable identifier for this broker process; generated automatically when omitted. */
+        brokerId?: string;
+        poolSize?: number;
+        leaseDurationMs?: number;
+        pollIntervalMs?: number;
+        statementTimeoutMs?: number;
+        lockTimeoutMs?: number;
+        idleTransactionTimeoutMs?: number;
+        maxConcurrentOperations?: number;
+        maxQueuedOperations?: number;
+        maxSnapshotJobs?: number;
+        maxSnapshotPayloadBytes?: number;
     };
     telemetry?: {
         /** Maximum queue label values exposed to Prometheus; zero disables per-queue series. */

package/dist/domain/job/groupFifoOrder.d.ts

@@ -0,0 +1,9 @@
+import type { Job } from '../types/jobs/model';
+/** Read the broker-internal admission order used by grouped FIFO lanes. */
+export declare function getGroupFifoOrder(job: Job): bigint | null;
+/** Stamp a stable order without exposing it through the public job protocol. */
+export declare function setGroupFifoOrder(job: Job, order: bigint): void;
+/** Preserve the hidden order when an immutable job replacement is created. */
+export declare function copyGroupFifoOrder(source: Job, target: Job): void;
+/** Restore a validated decimal order from SQLite extended options. */
+export declare function restoreGroupFifoOrder(job: Job, stored: string | null): void;

package/dist/domain/job/groupFifoOrder.js

@@ -0,0 +1,26 @@
+const GROUP_FIFO_ORDER = Symbol('bunqueue.groupFifoOrder');
+/** Read the broker-internal admission order used by grouped FIFO lanes. */
+export function getGroupFifoOrder(job) {
+    return job[GROUP_FIFO_ORDER] ?? null;
+}
+/** Stamp a stable order without exposing it through the public job protocol. */
+export function setGroupFifoOrder(job, order) {
+    Object.defineProperty(job, GROUP_FIFO_ORDER, {
+        value: order,
+        enumerable: true,
+        configurable: true,
+        writable: false,
+    });
+}
+/** Preserve the hidden order when an immutable job replacement is created. */
+export function copyGroupFifoOrder(source, target) {
+    const order = getGroupFifoOrder(source);
+    if (order !== null)
+        setGroupFifoOrder(target, order);
+}
+/** Restore a validated decimal order from SQLite extended options. */
+export function restoreGroupFifoOrder(job, stored) {
+    if (stored === null || !/^[1-9]\d*$/.test(stored))
+        return;
+    setGroupFifoOrder(job, BigInt(stored));
+}

package/dist/domain/queue/dlqShard.d.ts

@@ -44,6 +44,8 @@ export declare class DlqShard {
     getFiltered(queue: string, filter: DlqFilter): DlqEntry[];
     /** Remove entry from DLQ by job ID */
     remove(queue: string, jobId: JobId): DlqEntry | null;
+    /** Remove every entry with the same job ID from one queue. */
+    removeAll(queue: string, jobId: JobId): DlqEntry[];
     /** Get entries ready for auto-retry */
     getAutoRetryEntries(queue: string, now?: number): DlqEntry[];
     /** Get expired entries for cleanup */

package/dist/domain/queue/dlqShard.js

@@ -135,6 +135,22 @@ export class DlqShard {
         this.stats.decrementDlq();
         return entries.splice(idx, 1)[0];
     }
+    /** Remove every entry with the same job ID from one queue. */
+    removeAll(queue, jobId) {
+        const entries = this.dlq.get(queue);
+        if (!entries)
+            return [];
+        const removed = [];
+        const remaining = [];
+        for (const entry of entries) {
+            (entry.job.id === jobId ? removed : remaining).push(entry);
+        }
+        if (removed.length === 0)
+            return removed;
+        this.dlq.set(queue, remaining);
+        this.stats.decrementDlq(removed.length);
+        return removed;
+    }
     /** Get entries ready for auto-retry */
     getAutoRetryEntries(queue, now = Date.now()) {
         const entries = this.dlq.get(queue);

package/dist/domain/queue/groupLimiterManager.d.ts

@@ -0,0 +1,23 @@
+import { type GroupPullOptions, type GroupRateLimitOverride } from '../types/group';
+export interface GroupLimitStatus {
+    eligible: boolean;
+    retryAt: number | null;
+}
+/** Stored group overrides and broker-authoritative runtime rate windows. */
+export declare class GroupLimiterManager {
+    private readonly rateOverrides;
+    private readonly concurrencyOverrides;
+    private readonly windows;
+    status(queue: string, groupId: string, defaults: GroupPullOptions | undefined, active: number, now?: number): GroupLimitStatus;
+    acquire(queue: string, groupId: string, defaults: GroupPullOptions | undefined, active: number, now?: number): boolean;
+    setRateLimit(queue: string, groupId: string, max: number, duration: number): void;
+    getRateLimit(queue: string, groupId: string): GroupRateLimitOverride | null;
+    removeRateLimit(queue: string, groupId: string): number;
+    getRateLimitTtl(queue: string, groupId: string, maxJobs?: number, now?: number): number;
+    setConcurrency(queue: string, groupId: string, concurrency: number): void;
+    getConcurrency(queue: string, groupId: string): number | null;
+    removeConcurrency(queue: string, groupId: string): number;
+    clearQueue(queue: string): void;
+    pruneExpiredWindows(now?: number): void;
+    private currentWindow;
+}

package/dist/domain/queue/groupLimiterManager.js

@@ -0,0 +1,107 @@
+import { assertPositiveSafeInteger, } from '../types/group';
+function key(queue, groupId) {
+    return `${queue}\0${groupId}`;
+}
+/** Stored group overrides and broker-authoritative runtime rate windows. */
+export class GroupLimiterManager {
+    rateOverrides = new Map();
+    concurrencyOverrides = new Map();
+    windows = new Map();
+    status(queue, groupId, defaults, active, now = Date.now()) {
+        const groupKey = key(queue, groupId);
+        if (defaults?.concurrency !== undefined) {
+            const concurrency = this.concurrencyOverrides.get(groupKey) ?? defaults.concurrency;
+            if (active >= concurrency)
+                return { eligible: false, retryAt: null };
+        }
+        if (!defaults?.limit)
+            return { eligible: true, retryAt: null };
+        const limit = this.rateOverrides.get(groupKey) ?? defaults.limit;
+        const window = this.currentWindow(groupKey, limit.max, limit.duration, now);
+        if (window && window.count >= limit.max) {
+            return { eligible: false, retryAt: window.startedAt + window.duration };
+        }
+        return { eligible: true, retryAt: null };
+    }
+    acquire(queue, groupId, defaults, active, now = Date.now()) {
+        const status = this.status(queue, groupId, defaults, active, now);
+        if (!status.eligible)
+            return false;
+        if (!defaults?.limit)
+            return true;
+        const groupKey = key(queue, groupId);
+        const limit = this.rateOverrides.get(groupKey) ?? defaults.limit;
+        let window = this.currentWindow(groupKey, limit.max, limit.duration, now);
+        if (!window) {
+            window = { max: limit.max, duration: limit.duration, startedAt: now, count: 0 };
+            this.windows.set(groupKey, window);
+        }
+        window.count++;
+        return true;
+    }
+    setRateLimit(queue, groupId, max, duration) {
+        assertPositiveSafeInteger(max, 'max');
+        assertPositiveSafeInteger(duration, 'duration');
+        const groupKey = key(queue, groupId);
+        this.rateOverrides.set(groupKey, { max, duration });
+        this.windows.delete(groupKey);
+    }
+    getRateLimit(queue, groupId) {
+        return this.rateOverrides.get(key(queue, groupId)) ?? null;
+    }
+    removeRateLimit(queue, groupId) {
+        const groupKey = key(queue, groupId);
+        this.windows.delete(groupKey);
+        return this.rateOverrides.delete(groupKey) ? 1 : 0;
+    }
+    getRateLimitTtl(queue, groupId, maxJobs, now = Date.now()) {
+        const groupKey = key(queue, groupId);
+        const window = this.windows.get(groupKey);
+        if (!window)
+            return -2;
+        if (now >= window.startedAt + window.duration) {
+            this.windows.delete(groupKey);
+            return -2;
+        }
+        if (maxJobs !== undefined && window.count < maxJobs)
+            return 0;
+        return window.startedAt + window.duration - now;
+    }
+    setConcurrency(queue, groupId, concurrency) {
+        assertPositiveSafeInteger(concurrency, 'concurrency');
+        this.concurrencyOverrides.set(key(queue, groupId), concurrency);
+    }
+    getConcurrency(queue, groupId) {
+        return this.concurrencyOverrides.get(key(queue, groupId)) ?? null;
+    }
+    removeConcurrency(queue, groupId) {
+        return this.concurrencyOverrides.delete(key(queue, groupId)) ? 1 : 0;
+    }
+    clearQueue(queue) {
+        const prefix = `${queue}\0`;
+        for (const map of [this.rateOverrides, this.concurrencyOverrides, this.windows]) {
+            for (const groupKey of map.keys()) {
+                if (groupKey.startsWith(prefix))
+                    map.delete(groupKey);
+            }
+        }
+    }
+    pruneExpiredWindows(now = Date.now()) {
+        for (const [groupKey, window] of this.windows) {
+            if (now >= window.startedAt + window.duration)
+                this.windows.delete(groupKey);
+        }
+    }
+    currentWindow(groupKey, max, duration, now) {
+        const window = this.windows.get(groupKey);
+        if (!window)
+            return null;
+        if (now >= window.startedAt + window.duration ||
+            window.max !== max ||
+            window.duration !== duration) {
+            this.windows.delete(groupKey);
+            return null;
+        }
+        return window;
+    }
+}

package/dist/domain/queue/groupScheduler.d.ts

@@ -0,0 +1,31 @@
+import { type Job } from '../types/job';
+export interface GroupEligibility {
+    eligible: boolean;
+    retryAt: number | null;
+}
+export interface GroupCandidate {
+    job: Job | null;
+    nextRunAt: number | null;
+}
+/** Lazy secondary ready/group indexes; the primary queue remains authoritative. */
+export declare class GroupScheduler {
+    private readonly queues;
+    private nextFifoOrder;
+    assignFifoOrder(job: Job): void;
+    observeFifoOrder(job: Job): void;
+    insert(queue: string, job: Job, primaryJobs: () => readonly Job[], now?: number): boolean;
+    remove(queue: string, job: Job): boolean;
+    isActive(queue: string): boolean;
+    peek(queue: string, now: number, eligibility: (groupId: string) => GroupEligibility): GroupCandidate;
+    advance(queue: string, groupId: string): void;
+    getGroupJobsCount(queue: string, groupId: string): number;
+    getGroupsJobsCount(queue: string): number;
+    clearQueue(queue: string): void;
+    private createState;
+    private insertTracked;
+    private promoteDue;
+    private insertReady;
+    private demoteReady;
+    private attachLane;
+    private detachLane;
+}