bunqueue 2.9.0 → 2.9.2

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/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/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;
+}

package/dist/domain/queue/groupScheduler.js

@@ -0,0 +1,256 @@
+import { getGroupFifoOrder, setGroupFifoOrder } from '../job/groupFifoOrder';
+import { isExpired, isReady } from '../types/job';
+import { IndexedPriorityQueue } from './priorityQueue';
+import { compareGroupFifoEntries, compareGroupWakeEntries, nextGroupCheckAt, orderedGroupClone, } from './groupSchedulerOrder';
+/** Lazy secondary ready/group indexes; the primary queue remains authoritative. */
+export class GroupScheduler {
+    queues = new Map();
+    nextFifoOrder = 1n;
+    assignFifoOrder(job) {
+        if (!job.groupId)
+            return;
+        const existing = getGroupFifoOrder(job);
+        if (existing !== null) {
+            this.observeFifoOrder(job);
+            return;
+        }
+        setGroupFifoOrder(job, this.nextFifoOrder++);
+    }
+    observeFifoOrder(job) {
+        const order = getGroupFifoOrder(job);
+        if (order !== null && order >= this.nextFifoOrder)
+            this.nextFifoOrder = order + 1n;
+    }
+    insert(queue, job, primaryJobs, now = Date.now()) {
+        this.assignFifoOrder(job);
+        let state = this.queues.get(queue);
+        const previous = state?.jobs.get(job.id);
+        if (previous) {
+            this.remove(queue, previous);
+            state = this.queues.get(queue);
+        }
+        if (!state) {
+            if (!job.groupId)
+                return false;
+            state = this.createState();
+            this.queues.set(queue, state);
+            for (const current of primaryJobs()) {
+                this.assignFifoOrder(current);
+                this.insertTracked(state, current, now);
+            }
+            return true;
+        }
+        this.insertTracked(state, job, now);
+        return true;
+    }
+    remove(queue, job) {
+        const state = this.queues.get(queue);
+        if (!state)
+            return false;
+        const tracked = state.jobs.get(job.id) ?? job;
+        const placement = state.placements.get(job.id);
+        if (!placement)
+            return true;
+        if (placement.kind === 'plain') {
+            state.plain.remove(job.id);
+        }
+        else if (placement.kind === 'delayed') {
+            state.delayed.remove(job.id);
+        }
+        else {
+            const lane = state.lanes.get(placement.groupId);
+            lane?.jobs.remove(job.id);
+            if (lane?.jobs.isEmpty)
+                this.detachLane(state, placement.groupId, lane);
+        }
+        state.placements.delete(job.id);
+        state.jobs.delete(job.id);
+        if (tracked.groupId) {
+            const count = (state.groupCounts.get(tracked.groupId) ?? 1) - 1;
+            if (count > 0)
+                state.groupCounts.set(tracked.groupId, count);
+            else {
+                state.groupCounts.delete(tracked.groupId);
+                const lane = state.lanes.get(tracked.groupId);
+                if (lane?.jobs.isEmpty && !lane.inRotation)
+                    state.lanes.delete(tracked.groupId);
+            }
+            state.groupedCount = Math.max(0, state.groupedCount - 1);
+            if (state.groupedCount === 0)
+                this.queues.delete(queue);
+        }
+        return this.queues.has(queue);
+    }
+    isActive(queue) {
+        return this.queues.has(queue);
+    }
+    peek(queue, now, eligibility) {
+        const state = this.queues.get(queue);
+        if (!state)
+            return { job: null, nextRunAt: null };
+        while (true) {
+            this.promoteDue(state, now);
+            let plain = state.plain.peek();
+            while (plain) {
+                const job = state.jobs.get(plain.id) ?? plain;
+                if (isReady(job, now) || isExpired(job, now))
+                    return { job, nextRunAt: null };
+                this.demoteReady(state, job);
+                plain = state.plain.peek();
+            }
+            let nextRunAt = state.delayed.peek()?.runAt ?? null;
+            let groupId = state.cursor;
+            let restart = false;
+            for (let visited = 0; groupId && visited < state.rotationSize; visited++) {
+                const lane = state.lanes.get(groupId);
+                if (!lane?.inRotation)
+                    break;
+                const candidate = lane.jobs.peek();
+                if (candidate) {
+                    const job = state.jobs.get(candidate.id) ?? candidate;
+                    if (!isReady(job, now) && !isExpired(job, now)) {
+                        this.demoteReady(state, job);
+                        restart = true;
+                        break;
+                    }
+                    const status = eligibility(groupId);
+                    if (status.eligible)
+                        return { job, nextRunAt };
+                    if (status.retryAt !== null) {
+                        nextRunAt = nextRunAt === null ? status.retryAt : Math.min(nextRunAt, status.retryAt);
+                    }
+                }
+                groupId = lane.next;
+            }
+            if (!restart)
+                return { job: null, nextRunAt };
+        }
+    }
+    advance(queue, groupId) {
+        const state = this.queues.get(queue);
+        const lane = state?.lanes.get(groupId);
+        if (state && lane?.inRotation)
+            state.cursor = lane.next;
+    }
+    getGroupJobsCount(queue, groupId) {
+        return this.queues.get(queue)?.groupCounts.get(groupId) ?? 0;
+    }
+    getGroupsJobsCount(queue) {
+        return this.queues.get(queue)?.groupedCount ?? 0;
+    }
+    clearQueue(queue) {
+        this.queues.delete(queue);
+    }
+    createState() {
+        return {
+            jobs: new Map(),
+            placements: new Map(),
+            plain: new IndexedPriorityQueue(),
+            delayed: new IndexedPriorityQueue(undefined, compareGroupWakeEntries, getGroupFifoOrder),
+            lanes: new Map(),
+            groupCounts: new Map(),
+            groupedCount: 0,
+            cursor: null,
+            rotationSize: 0,
+        };
+    }
+    insertTracked(state, job, now) {
+        state.jobs.set(job.id, job);
+        if (job.groupId) {
+            state.groupCounts.set(job.groupId, (state.groupCounts.get(job.groupId) ?? 0) + 1);
+            state.groupedCount++;
+        }
+        if (nextGroupCheckAt(job) > now) {
+            state.delayed.push(orderedGroupClone(job, nextGroupCheckAt(job)));
+            state.placements.set(job.id, { kind: 'delayed' });
+            return;
+        }
+        this.insertReady(state, job);
+    }
+    promoteDue(state, now) {
+        while (true) {
+            const scheduled = state.delayed.peek();
+            if (!scheduled || scheduled.runAt > now)
+                return;
+            state.delayed.pop();
+            const job = state.jobs.get(scheduled.id);
+            if (!job || state.placements.get(job.id)?.kind !== 'delayed')
+                continue;
+            this.insertReady(state, job);
+        }
+    }
+    insertReady(state, job) {
+        if (!job.groupId) {
+            state.plain.push(job);
+            state.placements.set(job.id, { kind: 'plain' });
+            return;
+        }
+        let lane = state.lanes.get(job.groupId);
+        if (!lane) {
+            lane = {
+                jobs: new IndexedPriorityQueue(undefined, compareGroupFifoEntries, getGroupFifoOrder),
+                previous: job.groupId,
+                next: job.groupId,
+                inRotation: false,
+            };
+            state.lanes.set(job.groupId, lane);
+        }
+        lane.jobs.push(orderedGroupClone(job));
+        state.placements.set(job.id, { kind: 'group', groupId: job.groupId });
+        if (!lane.inRotation)
+            this.attachLane(state, job.groupId, lane);
+    }
+    demoteReady(state, job) {
+        const placement = state.placements.get(job.id);
+        if (placement?.kind === 'plain') {
+            state.plain.remove(job.id);
+        }
+        else if (placement?.kind === 'group') {
+            const lane = state.lanes.get(placement.groupId);
+            lane?.jobs.remove(job.id);
+            if (lane?.jobs.isEmpty)
+                this.detachLane(state, placement.groupId, lane);
+        }
+        else {
+            return;
+        }
+        state.delayed.push(orderedGroupClone(job, nextGroupCheckAt(job)));
+        state.placements.set(job.id, { kind: 'delayed' });
+    }
+    attachLane(state, groupId, lane) {
+        if (state.cursor === null) {
+            lane.previous = groupId;
+            lane.next = groupId;
+            state.cursor = groupId;
+        }
+        else {
+            const cursor = state.lanes.get(state.cursor);
+            const tail = state.lanes.get(cursor.previous);
+            lane.previous = cursor.previous;
+            lane.next = state.cursor;
+            tail.next = groupId;
+            cursor.previous = groupId;
+        }
+        lane.inRotation = true;
+        state.rotationSize++;
+    }
+    detachLane(state, groupId, lane) {
+        if (!lane.inRotation)
+            return;
+        if (state.rotationSize === 1) {
+            state.cursor = null;
+        }
+        else {
+            const previous = state.lanes.get(lane.previous);
+            const next = state.lanes.get(lane.next);
+            previous.next = lane.next;
+            next.previous = lane.previous;
+            if (state.cursor === groupId)
+                state.cursor = lane.next;
+        }
+        lane.inRotation = false;
+        state.rotationSize--;
+        if (lane.jobs.isEmpty && !state.groupCounts.has(groupId))
+            state.lanes.delete(groupId);
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { Job } from '../types/job';
+import type { HeapEntry } from '../types/priorityQueue';
+export declare function orderedGroupClone(job: Job, runAt?: number): Job;
+export declare function nextGroupCheckAt(job: Job): number;
+export declare function compareGroupFifoEntries(left: HeapEntry, right: HeapEntry): number;
+export declare function compareGroupWakeEntries(left: HeapEntry, right: HeapEntry): number;

package/dist/domain/queue/groupSchedulerOrder.js

@@ -0,0 +1,30 @@
+import { copyGroupFifoOrder } from '../job/groupFifoOrder';
+export function orderedGroupClone(job, runAt = job.runAt) {
+    const clone = { ...job, priority: 0, lifo: false, runAt };
+    copyGroupFifoOrder(job, clone);
+    return clone;
+}
+export function nextGroupCheckAt(job) {
+    if (job.ttl === null)
+        return job.runAt;
+    return Math.min(job.runAt, job.createdAt + job.ttl + 1);
+}
+function compareOrder(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+export function compareGroupFifoEntries(left, right) {
+    const order = compareOrder(left.groupFifoOrder ?? left.generation, right.groupFifoOrder ?? right.generation);
+    if (order !== 0)
+        return order;
+    return left.jobId < right.jobId ? -1 : left.jobId > right.jobId ? 1 : 0;
+}
+export function compareGroupWakeEntries(left, right) {
+    if (left.runAt !== right.runAt)
+        return left.runAt - right.runAt;
+    if (left.groupFifoOrder !== undefined && right.groupFifoOrder !== undefined) {
+        const order = compareOrder(left.groupFifoOrder, right.groupFifoOrder);
+        if (order !== 0)
+            return order;
+    }
+    return left.jobId < right.jobId ? -1 : left.jobId > right.jobId ? 1 : 0;
+}

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

@@ -1,44 +1,35 @@
-/**
- * Indexed Priority Queue
- * Combines binary heap for O(log n) priority operations
- * with Map for O(1) lookups by job ID
- */
 import type { Job, JobId } from '../types/job';
-/**
- * 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
- */
+import type { HeapEntry } from '../types/priorityQueue';
+export interface PriorityQueueHooks {
+    onInsert(job: Job): boolean;
+    onRemove(job: Job): boolean;
+}
+export type PriorityQueueComparator = (left: HeapEntry, right: HeapEntry) => number;
+export type PriorityQueueOrder = (job: Job) => bigint | null;
+/** Indexed map-backed 4-ary heap with O(log4 n) mutations and O(1) lookup. */
 export declare class IndexedPriorityQueue {
-    /** Branching factor - 4 provides optimal cache performance */
+    private readonly hooks?;
+    private readonly compare;
+    private readonly order?;
     private static readonly D;
     private heap;
     private readonly index;
     private generation;
-    /** Get current size */
+    private hooksActive;
+    constructor(hooks?: PriorityQueueHooks | undefined, compare?: PriorityQueueComparator, order?: PriorityQueueOrder | undefined);
     get size(): number;
-    /** Check if empty */
     get isEmpty(): boolean;
-    /** Push a job into the queue */
     push(job: Job): void;
-    /** Pop the highest priority job */
     pop(): Job | null;
-    /** Peek at the highest priority job without removing */
     peek(): Job | null;
-    /** Find a job by ID - O(1) */
     find(jobId: JobId): Job | null;
-    /** Check if job exists - O(1) */
     has(jobId: JobId): boolean;
-    /** Remove a job by ID - O(1) for index, heap cleans lazily */
     remove(jobId: JobId): Job | null;
     /** Update job priority - O(log n). Optionally update the LIFO tie-break flag. */
     updatePriority(jobId: JobId, newPriority: number, newLifo?: boolean): boolean;
     /** Update job runAt (for delay changes) - O(log n) */
     updateRunAt(jobId: JobId, newRunAt: number): boolean;
-    /** Get all jobs (for iteration) */
     values(): Job[];
-    /** Clear the queue */
     clear(): void;
     /**
      * Get the ratio of stale entries in the heap
@@ -51,7 +42,6 @@ export declare class IndexedPriorityQueue {
      * O(n) operation but reclaims memory and improves performance
      */
     compact(): void;
-    /** Rebuild heap property from arbitrary array - O(n) */
     private heapify;
     /** Check if compaction is needed (stale ratio > threshold) */
     needsCompaction(threshold?: number): boolean;