bunqueue 2.8.32 → 2.8.33

package/dist/domain/queue/waiterManager.js

@@ -1,69 +1,100 @@
 /**
- * WaiterManager - Manages job availability notifications
- * Handles worker polling with timeout-based waiting
+ * WaiterManager - Manages queue-scoped job availability notifications.
+ * Handles worker polling with timeout-based waiting.
  */
-/** Threshold for triggering full waiters cleanup */
-const WAITERS_CLEANUP_THRESHOLD = 1000;
+const DEFAULT_QUEUE = '';
+const COMPACT_MIN_HEAD = 1024;
 export class WaiterManager {
-    /** Waiter entries with cancellation flag for O(1) cleanup */
-    waiters = [];
-    /** Pending notification counter - incremented when notify() is called with no waiters */
-    pendingNotifications = 0;
-    /** Notify that multiple jobs are available - wakes up to `count` waiters */
-    notifyBatch(count) {
-        for (let i = 0; i < count; i++) {
-            this.notify();
-        }
+    queues = new Map();
+    activeWaiters = 0;
+    notify(queue) {
+        this.notifyQueue(queue ?? DEFAULT_QUEUE, 1);
     }
-    /** Notify that jobs are available - wakes first non-cancelled waiter */
-    notify() {
-        // Clean up leading cancelled waiters first
-        while (this.waiters.length > 0 && this.waiters[0].cancelled) {
-            this.waiters.shift();
-        }
-        // Wake the first active waiter
-        const waiter = this.waiters.shift();
-        if (waiter && !waiter.cancelled) {
-            waiter.resolve();
-        }
-        else {
-            // No active waiter - increment pending counter so next waitForJob returns immediately
-            this.pendingNotifications++;
-        }
-        // Periodic full cleanup when array grows too large
-        if (this.waiters.length > WAITERS_CLEANUP_THRESHOLD) {
-            this.cleanupWaiters();
-        }
+    notifyBatch(queueOrCount, maybeCount) {
+        const queue = typeof queueOrCount === 'string' ? queueOrCount : DEFAULT_QUEUE;
+        const count = typeof queueOrCount === 'number' ? queueOrCount : (maybeCount ?? 0);
+        if (count <= 0)
+            return;
+        this.notifyQueue(queue, count);
     }
-    /** Wait for a job to become available (with timeout) */
-    waitForJob(timeoutMs) {
+    waitForJob(queueOrTimeout, maybeTimeout) {
+        const queue = typeof queueOrTimeout === 'string' ? queueOrTimeout : DEFAULT_QUEUE;
+        const timeoutMs = typeof queueOrTimeout === 'number' ? queueOrTimeout : (maybeTimeout ?? 0);
         if (timeoutMs <= 0)
             return Promise.resolve();
-        // Check for pending notifications - if any, decrement and return immediately
-        if (this.pendingNotifications > 0) {
-            this.pendingNotifications--;
+        const state = this.queues.get(queue);
+        if (state?.pending) {
+            state.pending = false;
+            this.deleteIdleQueue(queue, state);
             return Promise.resolve();
         }
         return new Promise((resolve) => {
-            const waiter = { resolve, cancelled: false };
-            const cleanup = () => {
+            const queueState = state ?? this.createQueue(queue);
+            const waiter = {
+                resolve,
+                cancelled: false,
+                timer: undefined,
+            };
+            waiter.timer = setTimeout(() => {
                 if (waiter.cancelled)
                     return;
                 waiter.cancelled = true;
+                queueState.active--;
+                this.activeWaiters--;
                 resolve();
-            };
-            this.waiters.push(waiter);
-            setTimeout(cleanup, timeoutMs);
+                this.compact(queue, queueState);
+            }, timeoutMs);
+            queueState.entries.push(waiter);
+            queueState.active++;
+            this.activeWaiters++;
         });
     }
-    /** Remove all cancelled waiters from the array */
-    cleanupWaiters() {
-        const active = this.waiters.filter((w) => !w.cancelled);
-        this.waiters.length = 0;
-        this.waiters.push(...active);
+    notifyQueue(queue, count) {
+        const state = this.queues.get(queue);
+        if (!state) {
+            this.createQueue(queue).pending = true;
+            return;
+        }
+        let remaining = count;
+        while (remaining > 0 && state.active > 0) {
+            const waiter = state.entries[state.head++];
+            if (!waiter || waiter.cancelled)
+                continue;
+            waiter.cancelled = true;
+            clearTimeout(waiter.timer);
+            state.active--;
+            this.activeWaiters--;
+            remaining--;
+            waiter.resolve();
+        }
+        // Availability is edge-triggered: surplus notifications coalesce into one
+        // retry hint instead of accumulating an unbounded notification debt.
+        if (remaining > 0)
+            state.pending = true;
+        this.compact(queue, state);
+    }
+    createQueue(queue) {
+        const state = { entries: [], head: 0, active: 0, pending: false };
+        this.queues.set(queue, state);
+        return state;
+    }
+    compact(queue, state) {
+        if (state.active === 0) {
+            state.entries = [];
+            state.head = 0;
+            this.deleteIdleQueue(queue, state);
+            return;
+        }
+        if (state.head >= COMPACT_MIN_HEAD && state.head * 2 >= state.entries.length) {
+            state.entries = state.entries.slice(state.head);
+            state.head = 0;
+        }
+    }
+    deleteIdleQueue(queue, state) {
+        if (state.active === 0 && !state.pending)
+            this.queues.delete(queue);
     }
-    /** Current number of waiters */
     get length() {
-        return this.waiters.length;
+        return this.activeWaiters;
     }
 }

package/dist/infrastructure/cloud/commands.js

@@ -311,8 +311,11 @@ export const COMMANDS = {
     // --- Queue list ---
     'queue:list': (qm) => {
         const queueNames = qm.listQueues();
-        const queues = queueNames.map((name) => {
-            const counts = qm.getQueueJobCounts(name);
+        const countsByQueue = qm.getAllQueueJobCounts();
+        const queues = queueNames.flatMap((name) => {
+            const counts = countsByQueue.get(name);
+            if (!counts)
+                return [];
             return {
                 name,
                 waiting: counts.waiting,

package/dist/infrastructure/cloud/snapshotCollector.js

@@ -85,8 +85,11 @@ export async function collectSnapshot(params) {
     const storage = queueManager.getStorageStatus();
     const mem = process.memoryUsage();
     const queueNames = queueManager.listQueues();
-    const queues = queueNames.map((name) => {
-        const counts = queueManager.getQueueJobCounts(name);
+    const countsByQueue = queueManager.getAllQueueJobCounts();
+    const queues = queueNames.flatMap((name) => {
+        const counts = countsByQueue.get(name);
+        if (!counts)
+            return [];
         return {
             name,
             waiting: counts.waiting,

package/dist/infrastructure/cloud/statsRefresh.js

@@ -26,8 +26,11 @@ export function buildStatsRefresh(qm) {
     const mem = process.memoryUsage();
     const workerStats = qm.workerManager.getStats();
     const queueNames = qm.listQueues();
-    const queues = queueNames.map((name) => {
-        const counts = qm.getQueueJobCounts(name);
+    const countsByQueue = qm.getAllQueueJobCounts();
+    const queues = queueNames.flatMap((name) => {
+        const counts = countsByQueue.get(name);
+        if (!counts)
+            return [];
         return {
             name,
             waiting: counts.waiting,

package/dist/infrastructure/cloud/statsUpdate.js

@@ -11,8 +11,11 @@ export function buildStatsUpdate(qm) {
     const s = qm.getStats();
     const rates = throughputTracker.getRates();
     const queueNames = qm.listQueues();
-    const queues = queueNames.map((name) => {
-        const c = qm.getQueueJobCounts(name);
+    const countsByQueue = qm.getAllQueueJobCounts();
+    const queues = queueNames.flatMap((name) => {
+        const c = countsByQueue.get(name);
+        if (!c)
+            return [];
         return {
             name,
             waiting: c.waiting,

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

@@ -4,10 +4,10 @@
 /** SQLite PRAGMA settings for optimal performance */
 export declare const PRAGMA_SETTINGS = "\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\nPRAGMA page_size = 4096;\nPRAGMA busy_timeout = 5000;\n";
 /** Main schema creation */
-export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER\n);\n";
+export declare const SCHEMA = "\n-- Jobs table (using UUIDv7 for job IDs)\n-- Uses BLOB for data fields (MessagePack serialization for ~2-3x faster than JSON)\nCREATE TABLE IF NOT EXISTS jobs (\n    id TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    priority INTEGER NOT NULL DEFAULT 0,\n    created_at INTEGER NOT NULL,\n    run_at INTEGER NOT NULL,\n    started_at INTEGER,\n    completed_at INTEGER,\n    attempts INTEGER NOT NULL DEFAULT 0,\n    max_attempts INTEGER NOT NULL DEFAULT 3,\n    backoff INTEGER NOT NULL DEFAULT 1000,\n    ttl INTEGER,\n    timeout INTEGER,\n    unique_key TEXT,\n    custom_id TEXT,\n    depends_on BLOB,\n    parent_id TEXT,\n    children_ids BLOB,\n    tags BLOB,\n    state TEXT NOT NULL DEFAULT 'waiting',\n    lifo INTEGER NOT NULL DEFAULT 0,\n    group_id TEXT,\n    progress INTEGER DEFAULT 0,\n    progress_msg TEXT,\n    remove_on_complete INTEGER DEFAULT 0,\n    remove_on_fail INTEGER DEFAULT 0,\n    stall_timeout INTEGER,\n    last_heartbeat INTEGER,\n    timeline BLOB,\n    stacktrace BLOB\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state\n    ON jobs(queue, state);\n-- Stable createdAt/id pagination for unfiltered and logical-state queue views\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_created\n    ON jobs(queue, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created\n    ON jobs(queue, state, created_at, id);\nCREATE INDEX IF NOT EXISTS idx_jobs_run_at\n    ON jobs(run_at) WHERE state IN ('waiting', 'delayed');\nCREATE INDEX IF NOT EXISTS idx_jobs_unique\n    ON jobs(queue, unique_key) WHERE unique_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_custom_id\n    ON jobs(custom_id) WHERE custom_id IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_jobs_parent\n    ON jobs(parent_id) WHERE parent_id IS NOT NULL;\n\n-- Job results storage (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS job_results (\n    job_id TEXT PRIMARY KEY,\n    result BLOB,\n    completed_at INTEGER NOT NULL\n);\n\n-- Dead letter queue (BLOB for MessagePack - stores full DlqEntry)\nCREATE TABLE IF NOT EXISTS dlq (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    job_id TEXT NOT NULL,\n    queue TEXT NOT NULL,\n    entry BLOB NOT NULL,\n    entered_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_dlq_queue ON dlq(queue);\nCREATE INDEX IF NOT EXISTS idx_dlq_job_id ON dlq(job_id);\nCREATE INDEX IF NOT EXISTS idx_dlq_entered_at ON dlq(entered_at);\n\n-- Performance indexes for high-throughput operations\n-- Stall detection: runs every 5s, needs fast lookup of active jobs by started_at\nCREATE INDEX IF NOT EXISTS idx_jobs_state_started\n    ON jobs(state, started_at) WHERE state = 'active';\n\n-- Group operations: fast lookup by group_id\nCREATE INDEX IF NOT EXISTS idx_jobs_group_id\n    ON jobs(group_id) WHERE group_id IS NOT NULL;\n\n-- Pending jobs: compound index for priority-ordered retrieval\nCREATE INDEX IF NOT EXISTS idx_jobs_pending_priority\n    ON jobs(queue, state, priority DESC, run_at ASC) WHERE state IN ('waiting', 'delayed');\n\n-- Completed jobs: index for recovery ordering (issue #84)\nCREATE INDEX IF NOT EXISTS idx_jobs_completed_order\n    ON jobs(completed_at DESC) WHERE state = 'completed';\n\n-- Cron jobs (BLOB for MessagePack)\nCREATE TABLE IF NOT EXISTS cron_jobs (\n    name TEXT PRIMARY KEY,\n    queue TEXT NOT NULL,\n    data BLOB NOT NULL,\n    schedule TEXT,\n    repeat_every INTEGER,\n    priority INTEGER NOT NULL DEFAULT 0,\n    next_run INTEGER NOT NULL,\n    executions INTEGER NOT NULL DEFAULT 0,\n    max_limit INTEGER,\n    timezone TEXT,\n    unique_key TEXT,\n    dedup BLOB,\n    skip_missed_on_restart INTEGER NOT NULL DEFAULT 0,\n    skip_if_no_worker INTEGER NOT NULL DEFAULT 0,\n    prevent_overlap INTEGER NOT NULL DEFAULT 1,\n    job_options BLOB\n);\n\n-- Queue state persistence (optional)\nCREATE TABLE IF NOT EXISTS queue_state (\n    name TEXT PRIMARY KEY,\n    paused INTEGER NOT NULL DEFAULT 0,\n    rate_limit INTEGER,\n    concurrency_limit INTEGER\n);\n";
 /** Migration version table */
 export declare const MIGRATION_TABLE = "\nCREATE TABLE IF NOT EXISTS migrations (\n    version INTEGER PRIMARY KEY,\n    applied_at INTEGER NOT NULL\n);\n";
 /** Current schema version */
-export declare const SCHEMA_VERSION = 13;
+export declare const SCHEMA_VERSION = 14;
 /** All migrations in order */
 export declare const MIGRATIONS: Record<number, string>;

package/dist/infrastructure/persistence/schema.js

@@ -51,6 +51,11 @@ CREATE TABLE IF NOT EXISTS jobs (
 -- Indexes for common queries
 CREATE INDEX IF NOT EXISTS idx_jobs_queue_state
     ON jobs(queue, state);
+-- Stable createdAt/id pagination for unfiltered and logical-state queue views
+CREATE INDEX IF NOT EXISTS idx_jobs_queue_created
+    ON jobs(queue, created_at, id);
+CREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created
+    ON jobs(queue, state, created_at, id);
 CREATE INDEX IF NOT EXISTS idx_jobs_run_at
     ON jobs(run_at) WHERE state IN ('waiting', 'delayed');
 CREATE INDEX IF NOT EXISTS idx_jobs_unique
@@ -133,7 +138,7 @@ CREATE TABLE IF NOT EXISTS migrations (
 );
 `;
 /** Current schema version */
-export const SCHEMA_VERSION = 13;
+export const SCHEMA_VERSION = 14;
 /** All migrations in order */
 export const MIGRATIONS = {
     1: SCHEMA,
@@ -187,5 +192,12 @@ ALTER TABLE cron_jobs ADD COLUMN job_options BLOB;
     // Migration 13: Persist the last failure's stacktrace on jobs (issue #74)
     13: `
 ALTER TABLE jobs ADD COLUMN stacktrace BLOB;
+`,
+    // Migration 14: Stable, index-backed getJobs ordering and pagination
+    14: `
+CREATE INDEX IF NOT EXISTS idx_jobs_queue_created
+    ON jobs(queue, created_at, id);
+CREATE INDEX IF NOT EXISTS idx_jobs_queue_state_created
+    ON jobs(queue, state, created_at, id);
 `,
 };

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

@@ -142,7 +142,8 @@ export declare class SqliteStorage {
     insertJobsBatch(jobs: Job[], durable?: boolean): void;
     /**
      * Query jobs by queue with optional state filter and pagination.
-     * Uses idx_jobs_queue_state index for O(log n) lookups.
+     * This is the raw persisted-state query. Logical waiting/prioritized/delayed
+     * views should use queryJobsByLogicalStates().
      */
     queryJobs(queue: string, options: {
         state?: string;
@@ -151,9 +152,24 @@ export declare class SqliteStorage {
         offset: number;
         asc: boolean;
     }): Job[];
+    /**
+     * Query public/logical job states before applying pagination.
+     *
+     * SQLite persists pending jobs as waiting/delayed, while the public state is
+     * time-dependent: a delayed row becomes waiting or prioritized once run_at
+     * is reached. Keeping these predicates in SQL makes OFFSET count the logical
+     * result rather than the unfiltered persisted rows.
+     */
+    queryJobsByLogicalStates(queue: string, states: string[], options: {
+        limit: number;
+        offset: number;
+        asc: boolean;
+        now: number;
+    }): Job[];
     /**
      * Load pending jobs with pagination for efficient recovery.
-     * Orders by priority (desc) and run_at (asc) to process urgent jobs first.
+     * Orders by priority (desc), run_at (asc), and id (asc) so page boundaries
+     * remain deterministic when scheduling fields compare equal.
      * @param limit Max jobs to return (default: 10000)
      * @param offset Skip first N jobs (default: 0)
      */

package/dist/infrastructure/persistence/sqlite.js

@@ -482,7 +482,8 @@ export class SqliteStorage {
     // ============ Query Operations ============
     /**
      * Query jobs by queue with optional state filter and pagination.
-     * Uses idx_jobs_queue_state index for O(log n) lookups.
+     * This is the raw persisted-state query. Logical waiting/prioritized/delayed
+     * views should use queryJobsByLogicalStates().
      */
     queryJobs(queue, options) {
         const order = options.asc ? 'ASC' : 'DESC';
@@ -490,30 +491,72 @@ export class SqliteStorage {
         if (options.states && options.states.length > 0) {
             const placeholders = options.states.map(() => '?').join(',');
             rows = this.db
-                .query(`SELECT * FROM jobs WHERE queue = ? AND state IN (${placeholders}) ORDER BY created_at ${order} LIMIT ? OFFSET ?`)
+                .query(`SELECT * FROM jobs WHERE queue = ? AND state IN (${placeholders}) ORDER BY created_at ${order}, id ${order} LIMIT ? OFFSET ?`)
                 .all(queue, ...options.states, options.limit, options.offset);
         }
         else if (options.state) {
             rows = this.db
-                .query(`SELECT * FROM jobs WHERE queue = ? AND state = ? ORDER BY created_at ${order} LIMIT ? OFFSET ?`)
+                .query(`SELECT * FROM jobs WHERE queue = ? AND state = ? ORDER BY created_at ${order}, id ${order} LIMIT ? OFFSET ?`)
                 .all(queue, options.state, options.limit, options.offset);
         }
         else {
             rows = this.db
-                .query(`SELECT * FROM jobs WHERE queue = ? ORDER BY created_at ${order} LIMIT ? OFFSET ?`)
+                .query(`SELECT * FROM jobs WHERE queue = ? ORDER BY created_at ${order}, id ${order} LIMIT ? OFFSET ?`)
                 .all(queue, options.limit, options.offset);
         }
         return rows.map((row) => rowToJob(row));
     }
+    /**
+     * Query public/logical job states before applying pagination.
+     *
+     * SQLite persists pending jobs as waiting/delayed, while the public state is
+     * time-dependent: a delayed row becomes waiting or prioritized once run_at
+     * is reached. Keeping these predicates in SQL makes OFFSET count the logical
+     * result rather than the unfiltered persisted rows.
+     */
+    queryJobsByLogicalStates(queue, states, options) {
+        const uniqueStates = Array.from(new Set(states));
+        if (uniqueStates.length === 0)
+            return [];
+        const predicates = [];
+        const predicateParams = [];
+        const requested = new Set(uniqueStates);
+        if (requested.has('waiting')) {
+            predicates.push("(state IN ('waiting', 'delayed') AND run_at <= ? AND priority <= 0)");
+            predicateParams.push(options.now);
+        }
+        if (requested.has('prioritized')) {
+            predicates.push("(state IN ('waiting', 'delayed') AND run_at <= ? AND priority > 0)");
+            predicateParams.push(options.now);
+        }
+        if (requested.has('delayed')) {
+            predicates.push("(state IN ('waiting', 'delayed') AND run_at > ?)");
+            predicateParams.push(options.now);
+        }
+        const persistedStates = uniqueStates.filter((state) => state !== 'waiting' && state !== 'prioritized' && state !== 'delayed');
+        if (persistedStates.length > 0) {
+            predicates.push(`state IN (${persistedStates.map(() => '?').join(',')})`);
+            predicateParams.push(...persistedStates);
+        }
+        const order = options.asc ? 'ASC' : 'DESC';
+        const rows = this.db
+            .query(`SELECT * FROM jobs INDEXED BY idx_jobs_queue_created
+         WHERE queue = ? AND (${predicates.join(' OR ')})
+         ORDER BY created_at ${order}, id ${order}
+         LIMIT ? OFFSET ?`)
+            .all(queue, ...predicateParams, options.limit, options.offset);
+        return rows.map((row) => rowToJob(row));
+    }
     /**
      * Load pending jobs with pagination for efficient recovery.
-     * Orders by priority (desc) and run_at (asc) to process urgent jobs first.
+     * Orders by priority (desc), run_at (asc), and id (asc) so page boundaries
+     * remain deterministic when scheduling fields compare equal.
      * @param limit Max jobs to return (default: 10000)
      * @param offset Skip first N jobs (default: 0)
      */
     loadPendingJobs(limit = 10000, offset = 0) {
         const rows = this.db
-            .query("SELECT * FROM jobs WHERE state IN ('waiting', 'delayed') ORDER BY priority DESC, run_at ASC LIMIT ? OFFSET ?")
+            .query("SELECT * FROM jobs WHERE state IN ('waiting', 'delayed') ORDER BY priority DESC, run_at ASC, id ASC LIMIT ? OFFSET ?")
             .all(limit, offset);
         return rows.map((row) => rowToJob(row));
     }

package/dist/infrastructure/server/queueCountsScheduler.d.ts

@@ -0,0 +1,13 @@
+import type { QueueManager } from '../../application/queueManager';
+import type { QueueJobCounts } from '../../application/queueStatsAggregator';
+/** Coalesce high-volume job events into one queue-count aggregation per tick. */
+export declare class QueueCountsScheduler {
+    private readonly queueManager;
+    private readonly emit;
+    private readonly pendingQueues;
+    private timer;
+    constructor(queueManager: QueueManager, emit: (queue: string, counts: QueueJobCounts) => void);
+    schedule(queue: string): void;
+    stop(): void;
+    private flush;
+}

package/dist/infrastructure/server/queueCountsScheduler.js

@@ -0,0 +1,35 @@
+const COUNTS_COALESCE_MS = 10;
+/** Coalesce high-volume job events into one queue-count aggregation per tick. */
+export class QueueCountsScheduler {
+    queueManager;
+    emit;
+    pendingQueues = new Set();
+    timer = null;
+    constructor(queueManager, emit) {
+        this.queueManager = queueManager;
+        this.emit = emit;
+    }
+    schedule(queue) {
+        this.pendingQueues.add(queue);
+        this.timer ??= setTimeout(() => this.flush(), COUNTS_COALESCE_MS);
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.pendingQueues.clear();
+    }
+    flush() {
+        this.timer = null;
+        if (this.pendingQueues.size === 0)
+            return;
+        const queues = Array.from(this.pendingQueues);
+        this.pendingQueues.clear();
+        const countsByQueue = this.queueManager.getQueueJobCountsBatch(queues);
+        for (const queue of queues) {
+            const counts = countsByQueue.get(queue);
+            if (counts)
+                this.emit(queue, counts);
+        }
+    }
+}

package/dist/infrastructure/server/sseHandler.d.ts

@@ -30,6 +30,7 @@ export declare class SseHandler {
     private healthInterval;
     private storageInterval;
     private queueManager;
+    private queueCountsScheduler;
     private readonly eventBuffer;
     /** Get client count */
     get size(): number;

package/dist/infrastructure/server/sseHandler.js

@@ -13,6 +13,7 @@
  */
 import { throughputTracker } from '../../application/throughputTracker';
 import { uuid } from '../../shared/hash';
+import { QueueCountsScheduler } from './queueCountsScheduler';
 const textEncoder = new TextEncoder();
 /** Tuning constants */
 const MAX_CLIENTS = 1000;
@@ -45,6 +46,7 @@ export class SseHandler {
     healthInterval = null;
     storageInterval = null;
     queueManager = null;
+    queueCountsScheduler = null;
     eventBuffer = [];
     /** Get client count */
     get size() {
@@ -54,6 +56,17 @@ export class SseHandler {
     /** Start heartbeat + periodic broadcasts (stats, health, storage) */
     startBroadcasts(qm) {
         this.queueManager = qm;
+        this.queueCountsScheduler ??= new QueueCountsScheduler(qm, (queue, counts) => {
+            this.sendTypedEvent('queue:counts', {
+                queue,
+                waiting: counts.waiting,
+                prioritized: counts.prioritized,
+                active: counts.active,
+                completed: counts.completed,
+                failed: counts.failed,
+                delayed: counts.delayed,
+            });
+        });
         this.heartbeatTimer ??= setInterval(() => {
             this.sendHeartbeat();
         }, HEARTBEAT_MS);
@@ -78,6 +91,8 @@ export class SseHandler {
     }
     /** Stop all timers */
     stopTimers() {
+        this.queueCountsScheduler?.stop();
+        this.queueCountsScheduler = null;
         if (this.heartbeatTimer) {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
@@ -154,19 +169,9 @@ export class SseHandler {
         }
         for (const clientId of disconnected)
             this.clients.delete(clientId);
-        // Emit queue:counts on every job state change (mirrors wsHandler)
-        if (this.queueManager) {
-            const counts = this.queueManager.getQueueJobCounts(event.queue);
-            this.sendTypedEvent('queue:counts', {
-                queue: event.queue,
-                waiting: counts.waiting,
-                prioritized: counts.prioritized,
-                active: counts.active,
-                completed: counts.completed,
-                failed: counts.failed,
-                delayed: counts.delayed,
-            });
-        }
+        // Counts are eventually exact, but coalesced so a PUSHB does not perform
+        // one full queue scan per inserted job.
+        this.queueCountsScheduler?.schedule(event.queue);
     }
     // ── Dashboard / system event broadcasting ──────────────────
     /** Emit a typed event (dashboard events: worker, queue control, DLQ, etc.) */

package/dist/infrastructure/server/wsHandler.d.ts

@@ -28,7 +28,7 @@ export declare class WsHandler {
     private statsInterval;
     private healthInterval;
     private storageInterval;
-    private queueManager;
+    private queueCountsScheduler;
     droppedMessages: number;
     get size(): number;
     /** Check if a new connection can be accepted */

package/dist/infrastructure/server/wsHandler.js

@@ -14,6 +14,7 @@
 import { handleCommand } from './handler';
 import { parseCommand, serializeResponse, errorResponse } from './protocol';
 import { throughputTracker } from '../../application/throughputTracker';
+import { QueueCountsScheduler } from './queueCountsScheduler';
 const textDecoder = new TextDecoder();
 /** Old eventType → new event name */
 const EVENT_MAP = {
@@ -170,7 +171,7 @@ export class WsHandler {
     statsInterval = null;
     healthInterval = null;
     storageInterval = null;
-    queueManager = null;
+    queueCountsScheduler = null;
     droppedMessages = 0;
     get size() {
         return this.clients.size;
@@ -196,7 +197,17 @@ export class WsHandler {
     }
     /** Start periodic broadcasts */
     startBroadcasts(qm) {
-        this.queueManager = qm;
+        this.queueCountsScheduler ??= new QueueCountsScheduler(qm, (queue, counts) => {
+            this.emit('queue:counts', {
+                queue,
+                waiting: counts.waiting,
+                prioritized: counts.prioritized,
+                active: counts.active,
+                completed: counts.completed,
+                failed: counts.failed,
+                delayed: counts.delayed,
+            });
+        });
         this.statsInterval ??= setInterval(() => {
             if (this.clients.size > 0)
                 this.broadcastStats(qm);
@@ -212,6 +223,8 @@ export class WsHandler {
     }
     /** Stop periodic broadcasts */
     stopBroadcasts() {
+        this.queueCountsScheduler?.stop();
+        this.queueCountsScheduler = null;
         if (this.statsInterval) {
             clearInterval(this.statsInterval);
             this.statsInterval = null;
@@ -338,19 +351,9 @@ export class WsHandler {
         }
         for (const id of dead)
             this.clients.delete(id);
-        // Emit queue:counts on every job state change
-        if (this.queueManager) {
-            const counts = this.queueManager.getQueueJobCounts(event.queue);
-            this.emit('queue:counts', {
-                queue: event.queue,
-                waiting: counts.waiting,
-                prioritized: counts.prioritized,
-                active: counts.active,
-                completed: counts.completed,
-                failed: counts.failed,
-                delayed: counts.delayed,
-            });
-        }
+        // Counts are eventually exact, but coalesced so a PUSHB does not perform
+        // one full queue scan per inserted job.
+        this.queueCountsScheduler?.schedule(event.queue);
     }
     // ── Connection lifecycle ─────────────────────────────────
     onOpen(ws) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bunqueue",
-  "version": "2.8.32",
-  "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external dependencies.",
+  "version": "2.8.33",
+  "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -146,4 +146,4 @@
   "engines": {
     "bun": ">=1.3.9"
   }
-}
+}