bunqueue 2.8.3 → 2.8.5

package/README.md

@@ -25,6 +25,14 @@
 
 ---
 
+## Requirements
+
+bunqueue is **Bun-only** (`bun >= 1.3.9`). The client, TCP transport and persistence
+rely on Bun's runtime APIs (`Bun.connect`, `Bun.file`, `Bun.hash`, …) and ship as
+ESM with extensionless specifiers, so they do **not** run under Node.js. Importing
+the package from Node fails fast with a clear error pointing here rather than a
+cryptic resolver crash. Install Bun from [bun.sh](https://bun.sh) and run with `bun`.
+
 ## Quickstart
 
 ```bash
@@ -453,6 +461,27 @@ await app.close();     // graceful shutdown
 await app.close(true); // force shutdown
 ```
 
+### Inspecting jobs & counts
+
+`getJobCounts()` and the per-state lists follow BullMQ semantics:
+
+```typescript
+const counts = await queue.getJobCountsAsync();
+// { waiting, prioritized, active, completed, failed, delayed, paused }
+
+// Failed jobs (those that exhausted their attempts) are enumerable by state —
+// the failed list reflects the same jobs that `failed` counts.
+const failed = await queue.getFailedAsync(0, 50);
+const alsoFailed = await queue.getJobsAsync({ state: 'failed', start: 0, end: 50 });
+
+// Paused queue: ready jobs are reported under `paused`, never double-counted as
+// `waiting`. While paused, getJobCounts() returns waiting:0 / paused:N, and the
+// jobs are listed by `getJobsAsync({ state: 'paused' })` (not by `waiting`).
+queue.pause();
+const c = await queue.getJobCountsAsync(); // waiting: 0, paused: N
+const pausedJobs = await queue.getJobsAsync({ state: 'paused', start: 0, end: 50 });
+```
+
 ### Full Example
 
 ```typescript

package/dist/application/contextFactory.js

@@ -80,6 +80,8 @@ export class ContextFactory {
             shards: this.deps.shards,
             shardLocks: this.deps.shardLocks,
             completedJobs: this.deps.completedJobs,
+            completedJobsData: this.deps.completedJobsData,
+            jobResults: this.deps.jobResults,
             customIdMap: this.deps.customIdMap,
             jobIndex: this.deps.jobIndex,
             totalPushed: this.deps.metrics.totalPushed,

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

@@ -14,6 +14,8 @@ export interface PushContext {
     shards: Shard[];
     shardLocks: RWLock[];
     completedJobs: SetLike<JobId>;
+    completedJobsData: MapLike<JobId, Job>;
+    jobResults: MapLike<JobId, unknown>;
     customIdMap: MapLike<string, JobId>;
     jobIndex: Map<JobId, JobLocation>;
     totalPushed: {

package/dist/application/operations/push.js

@@ -17,19 +17,29 @@ function handleCustomId(input, shard, ctx) {
     }
     const id = jobId(input.customId);
     const existing = ctx.customIdMap.get(input.customId);
-    // No existing mapping - register and proceed
-    if (!existing) {
-        ctx.customIdMap.set(input.customId, id);
-        return { skip: false, id };
+    // If the existing job is still queued, the add is idempotent — return it.
+    if (existing) {
+        const location = ctx.jobIndex.get(existing);
+        const existingJob = location?.type === 'queue' ? shard.getQueue(location.queueName).find(existing) : null;
+        if (existingJob) {
+            return { skip: true, existingJob };
+        }
     }
-    // Check if existing job is still in queue
-    const location = ctx.jobIndex.get(existing);
-    const existingJob = location?.type === 'queue' ? shard.getQueue(location.queueName).find(existing) : null;
-    if (existingJob) {
-        return { skip: true, existingJob };
+    // Reuse path: the id is free in the queue (no mapping, or the prior job is
+    // processing/completed). If the prior job COMPLETED, its row survives on disk
+    // (markCompleted does an UPDATE, not a DELETE) and it is still in completedJobs.
+    // Reusing the same deterministic id would then (a) make getJobState return
+    // 'completed' for the brand-new job and (b) collide on the `jobs.id` PRIMARY KEY
+    // at flush time. Evict the stale completed job so the reused id starts fresh as
+    // 'waiting' (#92). Checked regardless of customIdMap state — the mapping may have
+    // been cleared on completion, which would otherwise skip this path entirely.
+    if (ctx.completedJobs.has(id)) {
+        ctx.completedJobs.delete(id);
+        ctx.completedJobsData.delete(id);
+        ctx.jobResults.delete(id);
+        ctx.jobIndex.delete(id);
+        ctx.storage?.deleteJob(id); // removes the surviving row + result + any buffered insert
     }
-    // Job gone (processing/completed) - allow reuse of customId
-    ctx.customIdMap.delete(input.customId);
     ctx.customIdMap.set(input.customId, id);
     return { skip: false, id };
 }

package/dist/application/operations/queryOperations.js

@@ -250,28 +250,55 @@ function collectWaitingChildrenFromShard(shard, queue, max) {
     }
     return wcJobs;
 }
+/**
+ * Resolve which sources to collect for a state filter.
+ *
+ * When the queue is paused, an EXPLICIT waiting/prioritized query returns nothing:
+ * those jobs are reported under 'paused' instead (BullMQ semantics, #92). An
+ * unfiltered query (states === null) still lists them by their temporal state.
+ */
+function resolveStateNeeds(states, paused) {
+    const want = (s) => !states || states.includes(s);
+    const suppressReady = !!states && paused;
+    return {
+        waiting: want('waiting') && !suppressReady,
+        prioritized: want('prioritized') && !suppressReady,
+        delayed: want('delayed'),
+        paused: !!states && states.includes('paused') && paused,
+        active: want('active'),
+        failed: want('failed'),
+        completed: want('completed'),
+        waitingChildren: want('waiting-children'),
+    };
+}
+/** When paused, the queue's ready jobs (waiting + prioritized) ARE the paused set (#92). */
+function collectPausedJobs(shard, queue, maxPerSource) {
+    const pausedJobs = collectTemporalJobs(shard, queue, { waiting: true, prioritized: true, delayed: false }, maxPerSource);
+    return tagState(pausedJobs, 'paused');
+}
 function collectJobsByState(queue, shardIdx, states, ctx, maxPerSource = Infinity) {
     const shard = ctx.shards[shardIdx];
     const jobs = [];
-    const needWaiting = !states || states.includes('waiting');
-    const needPrioritized = !states || states.includes('prioritized');
-    const needDelayed = !states || states.includes('delayed');
-    if (needWaiting || needPrioritized || needDelayed) {
-        const temporal = collectTemporalJobs(shard, queue, { waiting: needWaiting, prioritized: needPrioritized, delayed: needDelayed }, maxPerSource);
+    const need = resolveStateNeeds(states, shard.getState(queue).paused);
+    if (need.waiting || need.prioritized || need.delayed) {
+        const temporal = collectTemporalJobs(shard, queue, { waiting: need.waiting, prioritized: need.prioritized, delayed: need.delayed }, maxPerSource);
         tagTemporalState(temporal);
         jobs.push(...temporal);
     }
-    if (!states || states.includes('active')) {
+    if (need.paused) {
+        jobs.push(...collectPausedJobs(shard, queue, maxPerSource));
+    }
+    if (need.active) {
         jobs.push(...tagState(collectActiveJobs(queue, shardIdx, ctx, maxPerSource), 'active'));
     }
-    if (!states || states.includes('failed')) {
+    if (need.failed) {
         const dlq = shard.getDlq(queue);
         jobs.push(...tagState(maxPerSource < dlq.length ? dlq.slice(0, maxPerSource) : dlq, 'failed'));
     }
-    if (!states || states.includes('completed')) {
+    if (need.completed) {
         jobs.push(...tagState(collectCompletedJobs(queue, ctx, maxPerSource), 'completed'));
     }
-    if (!states || states.includes('waiting-children')) {
+    if (need.waitingChildren) {
         jobs.push(...tagState(collectWaitingChildrenFromShard(shard, queue, maxPerSource), 'waiting-children'));
     }
     return jobs;
@@ -315,6 +342,14 @@ function querySqliteWithPriority(storage, queue, sqlFilteredStates, opts) {
     }
     return jobs.slice(0, opts.limit);
 }
+/** Merge SQL rows with in-memory extras (each gathered from index 0), sort by
+ *  createdAt, and paginate [start, end) once — so offset-unaware extras don't
+ *  duplicate or drop rows across pages (#92). */
+function mergePage(sqlJobs, extras, start, end, asc) {
+    const merged = sqlJobs.concat(extras);
+    merged.sort((a, b) => (asc ? a.createdAt - b.createdAt : b.createdAt - a.createdAt));
+    return merged.slice(start, end);
+}
 /** Get jobs from queue with filters */
 export function getJobs(queue, shardIdx, options, ctx) {
     const { state, start = 0, end = 100, asc = true } = options;
@@ -327,29 +362,60 @@ export function getJobs(queue, shardIdx, options, ctx) {
             : [state];
     const limit = end - start;
     if (ctx.storage) {
+        const shard = ctx.shards[shardIdx];
+        const isPaused = shard.getState(queue).paused;
+        const maxPerSource = end + 1;
+        // Derived sources are NOT offset-aware (the DLQ and the paused/waiting-children
+        // views come from in-memory maps). When any contributes, we must gather [0, end)
+        // from EVERY source, merge, sort, then slice [start, end) exactly once — pushing
+        // `offset` into the SQL query would drop rows and duplicate across pages (#92).
         if (!states) {
-            return ctx.storage.queryJobs(queue, { limit, offset: start, asc });
+            const dlq = tagState(shard.getDlq(queue), 'failed');
+            if (dlq.length === 0) {
+                return ctx.storage.queryJobs(queue, { limit, offset: start, asc });
+            }
+            const all = ctx.storage.queryJobs(queue, { limit: end, offset: 0, asc });
+            return mergePage(all, dlq, start, end, asc);
+        }
+        // States with no jobs-table row are collected from in-memory sources:
+        //  - 'failed'           -> DLQ (the failed job lives in the dlq table) (#92)
+        //  - 'waiting-children' -> deps/children maps
+        //  - 'paused'           -> when paused, the would-be-waiting jobs ARE the paused set (#92)
+        const extras = [];
+        if (states.includes('failed')) {
+            extras.push(...tagState(shard.getDlq(queue), 'failed'));
+        }
+        if (states.includes('waiting-children')) {
+            extras.push(...collectWaitingChildrenJobs(shard, queue));
         }
-        const hasWaitingChildren = states.includes('waiting-children');
-        const sqlFilteredStates = states.filter((s) => s !== 'waiting-children');
-        // Only waiting-children: collect from in-memory
-        if (hasWaitingChildren && sqlFilteredStates.length === 0) {
-            const jobs = collectWaitingChildrenJobs(ctx.shards[shardIdx], queue);
-            jobs.sort((a, b) => (asc ? a.createdAt - b.createdAt : b.createdAt - a.createdAt));
-            return jobs.slice(start, end);
+        if (states.includes('paused') && isPaused) {
+            const pausedJobs = collectTemporalJobs(shard, queue, { waiting: true, prioritized: true, delayed: false }, maxPerSource);
+            extras.push(...tagState(pausedJobs, 'paused'));
         }
-        const jobs = sqlFilteredStates.length > 0
+        // jobs-table states. A paused queue reports its waiting/prioritized jobs under
+        // 'paused', so they must not also surface in the waiting/prioritized lists (#92).
+        const sqlFilteredStates = states.filter((s) => s !== 'failed' &&
+            s !== 'waiting-children' &&
+            s !== 'paused' &&
+            !(isPaused && (s === 'waiting' || s === 'prioritized')));
+        // Fast path: only jobs-table states, no derived sources — SQL paginates directly.
+        if (extras.length === 0) {
+            return sqlFilteredStates.length > 0
+                ? querySqliteWithPriority(ctx.storage, queue, sqlFilteredStates, {
+                    limit,
+                    offset: start,
+                    asc,
+                })
+                : [];
+        }
+        const sqlJobs = sqlFilteredStates.length > 0
             ? querySqliteWithPriority(ctx.storage, queue, sqlFilteredStates, {
-                limit,
-                offset: start,
+                limit: end,
+                offset: 0,
                 asc,
             })
             : [];
-        if (!hasWaitingChildren)
-            return jobs;
-        const merged = jobs.concat(collectWaitingChildrenJobs(ctx.shards[shardIdx], queue));
-        merged.sort((a, b) => (asc ? a.createdAt - b.createdAt : b.createdAt - a.createdAt));
-        return merged.slice(0, limit);
+        return mergePage(sqlJobs, extras, start, end, asc);
     }
     // In-memory path (embedded mode only)
     const maxPerSource = end + 1;

package/dist/bun-only.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bun-only entry stub.
+ *
+ * bunqueue is built for the Bun runtime: its TCP transport, persistence and
+ * client rely on Bun globals (Bun.connect, Bun.file, Bun.write, Bun.hash, ...)
+ * with no Node fallback, and the published ESM uses directory/extensionless
+ * relative specifiers that Node's ESM resolver rejects (ERR_UNSUPPORTED_DIR_IMPORT).
+ *
+ * The package.json `exports` map points the `"node"` condition at this single,
+ * self-contained file so a Node import fails fast with a clear, actionable error
+ * instead of a cryptic resolver crash or a deep `Bun is not defined`. Bun resolves
+ * the real entry via the higher-priority `"bun"` condition and never loads this.
+ *
+ * Keep this file free of relative imports so it stays resolvable on its own.
+ */

package/dist/bun-only.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Bun-only entry stub.
+ *
+ * bunqueue is built for the Bun runtime: its TCP transport, persistence and
+ * client rely on Bun globals (Bun.connect, Bun.file, Bun.write, Bun.hash, ...)
+ * with no Node fallback, and the published ESM uses directory/extensionless
+ * relative specifiers that Node's ESM resolver rejects (ERR_UNSUPPORTED_DIR_IMPORT).
+ *
+ * The package.json `exports` map points the `"node"` condition at this single,
+ * self-contained file so a Node import fails fast with a clear, actionable error
+ * instead of a cryptic resolver crash or a deep `Bun is not defined`. Bun resolves
+ * the real entry via the higher-priority `"bun"` condition and never loads this.
+ *
+ * Keep this file free of relative imports so it stays resolvable on its own.
+ */
+throw new Error('bunqueue is Bun-only and requires the Bun runtime (https://bun.sh). ' +
+    'Node.js is not supported: install Bun and run your program with `bun`. ' +
+    'See https://github.com/egeominotti/bunqueue#requirements');

package/dist/client/index.d.ts

@@ -18,6 +18,7 @@
  * worker.on('progress', (job, progress) => console.log(progress));
  * ```
  */
+import '../require-bun';
 export { defineConfig } from '../config';
 export type { BunqueueConfig } from '../config';
 export { Queue } from './queue';

package/dist/client/index.js

@@ -18,6 +18,8 @@
  * worker.on('progress', (job, progress) => console.log(progress));
  * ```
  */
+// Bun-only runtime guard — must evaluate before any module touching Bun.* globals.
+import '../require-bun';
 export { defineConfig } from '../config';
 export { Queue } from './queue';
 export { Worker } from './worker';

package/dist/client/queue/operations/counts.js

@@ -4,6 +4,7 @@
  * getJobCounts, getWaitingCount, getDelayedCount, etc.
  */
 import { getSharedManager } from '../../manager';
+import { pausedView } from '../../../shared/pausedView';
 /** Get job counts (sync, embedded only) */
 export function getJobCounts(ctx) {
     if (!ctx.embedded) {
@@ -21,14 +22,17 @@ export function getJobCounts(ctx) {
     // Use queue-specific counts
     const counts = manager.getQueueJobCounts(ctx.name);
     const isPaused = manager.isPaused(ctx.name);
+    // When paused, ready jobs (waiting + prioritized) are reported under `paused` —
+    // not in their own buckets, which would double-count (#92, BullMQ semantics).
+    const pv = pausedView(counts.waiting, counts.prioritized, isPaused);
     return {
-        waiting: counts.waiting,
-        prioritized: counts.prioritized,
+        waiting: pv.waiting,
+        prioritized: pv.prioritized,
         active: counts.active,
         completed: counts.completed,
         failed: counts.failed,
         delayed: counts.delayed,
-        paused: isPaused ? counts.waiting : 0,
+        paused: pv.paused,
     };
 }
 /** Get job counts (async, works with TCP) */

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

@@ -16,6 +16,7 @@
  * const run = await engine.start('onboarding', { email: 'user@test.com' });
  * ```
  */
+import '../../require-bun';
 export { Workflow } from './workflow';
 export { Engine } from './engine';
 export { WorkflowEmitter } from './emitter';

package/dist/client/workflow/index.js

@@ -16,6 +16,8 @@
  * const run = await engine.start('onboarding', { email: 'user@test.com' });
  * ```
  */
+// Bun-only runtime guard — must evaluate before any module touching Bun.* globals.
+import '../../require-bun';
 export { Workflow } from './workflow';
 export { Engine } from './engine';
 export { WorkflowEmitter } from './emitter';

package/dist/infrastructure/cloud/snapshotHelpers.js

@@ -9,7 +9,11 @@ const prevQueueTotals = new Map();
 /** Per-queue previous waiting count for backlog velocity */
 const prevQueueWaiting = new Map();
 // ─── Heavy data collectors (called every ~90s) ───
-/** All job states (BullMQ v5 compatible) */
+/** All job states (BullMQ v5 compatible).
+ * 'paused' yields jobs only when the queue is actually paused (where 'waiting' /
+ * 'prioritized' are suppressed), so a paused queue's ready jobs still appear in
+ * the snapshot — under `paused` — instead of vanishing (#92). No double-collect:
+ * a job is returned by exactly one of waiting/prioritized/paused. */
 const ALL_STATES = [
     'waiting',
     'active',
@@ -17,6 +21,7 @@ const ALL_STATES = [
     'failed',
     'completed',
     'prioritized',
+    'paused',
     'waiting-children',
 ];
 /** Convert falsy/empty values to undefined for compact serialization */

package/dist/infrastructure/persistence/sqlite.js

@@ -34,7 +34,19 @@ export class SqliteStorage {
     static MAX_RETAINED_LOSSES = 100;
     constructor(config) {
         this.db = new Database(config.path, { create: true });
-        this.db.run(PRAGMA_SETTINGS);
+        // PRAGMA settings are performance/optimization hints, not correctness
+        // requirements. A transient filesystem IOERR (e.g. SQLITE_IOERR_FSTAT from
+        // `mmap_size` calling fstat() on the fd during a restart/cleanup race) must
+        // NOT propagate out of the constructor — in a deferred/async context Bun
+        // reports it as an "Unhandled error between tests" and tears down CI.
+        try {
+            this.db.run(PRAGMA_SETTINGS);
+        }
+        catch (err) {
+            storageLog.error('Failed to apply PRAGMA settings', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
         this.migrate();
         this.statements = prepareStatements(this.db);
         this._onCriticalLoss = config.onCriticalLoss;
@@ -44,11 +56,24 @@ export class SqliteStorage {
             if (isSqliteFullError(err)) {
                 this.setDiskFull(err.message);
             }
-            storageLog.error('Write buffer flush failed', {
-                jobCount,
-                error: err.message,
-                diskFull: this._diskFull,
-            });
+            // A constraint violation (e.g. duplicate jobs.id) is a PERMANENT per-row
+            // rejection that the WriteBuffer isolated and dropped — sibling valid jobs
+            // in the same flush were still persisted. Log it distinctly from a
+            // transient flush failure (and never route it to the DLQ, which would
+            // resurrect a duplicate).
+            if (/constraint failed/i.test(err.message)) {
+                storageLog.error('Write buffer rejected jobs (constraint violation, dropped)', {
+                    rejectedJobCount: jobCount,
+                    error: err.message,
+                });
+            }
+            else {
+                storageLog.error('Write buffer flush failed', {
+                    jobCount,
+                    error: err.message,
+                    diskFull: this._diskFull,
+                });
+            }
         }, (jobs, lastError, attempts) => {
             this.handleCriticalLoss(jobs, lastError, attempts);
         });

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

@@ -4,13 +4,33 @@
  */
 import type { Database } from 'bun:sqlite';
 import type { Job } from '../../domain/types/job';
+/** Outcome of a batch insert after isolating per-row failures. */
+export interface BatchInsertResult {
+    /** Jobs that hit a transient (non-constraint) error — caller should retry. */
+    transient: Job[];
+    /** Jobs rejected by a permanent constraint (e.g. duplicate id) — drop, never retry. */
+    conflicts: Job[];
+    /** The originating error from the fast-path failure, for logging. */
+    error?: Error;
+}
 /** Batch insert manager with prepared statement caching */
 export declare class BatchInsertManager {
     private readonly db;
     private readonly cache;
     constructor(db: Database);
-    /** Insert batch of jobs using multi-row INSERT for 50-100x speedup */
-    insertJobsBatch(jobs: Job[]): void;
+    /**
+     * Insert a batch of jobs using a single multi-row INSERT (50-100x speedup).
+     * On the common path every row succeeds and an empty result is returned.
+     *
+     * If the atomic batch fails (e.g. a single duplicate `jobs.id`), the rows are
+     * re-inserted ONE AT A TIME so a single bad row can no longer drop the rest:
+     * valid jobs persist, constraint violations are isolated as `conflicts` (drop,
+     * never retry — they would poison every future flush), and any transient
+     * failures are returned so the caller can retry just those. Never throws.
+     */
+    insertJobsBatch(jobs: Job[]): BatchInsertResult;
+    /** Fallback path: insert each job independently, isolating per-row failures. */
+    private insertRowByRow;
     /** Get or create cached prepared statement for batch insert */
     private getBatchInsertStmt;
     /** Insert a chunk of jobs with single multi-row INSERT */
@@ -52,7 +72,16 @@ export declare class WriteBuffer {
     add(job: Job): void;
     /** Add multiple jobs to buffer */
     addBatch(jobs: Job[]): void;
-    /** Flush buffer to disk using double-buffering. Returns number of jobs flushed. */
+    /**
+     * Flush buffer to disk using double-buffering. Returns number of jobs persisted.
+     *
+     * Per-row isolation (see BatchInsertManager.insertJobsBatch): valid jobs are
+     * persisted even if a sibling row violates a constraint. Constraint conflicts
+     * (e.g. duplicate id) are dropped+reported and NEVER re-buffered — re-buffering
+     * them would poison every future flush and silently drop unrelated valid jobs
+     * (the #92-class data-loss bug). Transient failures are re-buffered and retried
+     * with exponential backoff, exactly as before.
+     */
     flush(): number;
     /** Schedule a retry with exponential backoff */
     private scheduleBackoffRetry;

package/dist/infrastructure/persistence/sqliteBatch.js

@@ -3,6 +3,20 @@
  * High-performance batch insert with prepared statement caching
  */
 import { pack } from './sqliteSerializer';
+const COLS_PER_ROW = 24;
+// SQLite has a limit of ~999 variables, so batch in chunks
+const MAX_ROWS_PER_INSERT = Math.floor(999 / COLS_PER_ROW);
+/**
+ * A constraint violation (e.g. a duplicate `jobs.id` PRIMARY KEY) is PERMANENT
+ * for that row — retrying never succeeds. It must be isolated from the rest of
+ * the batch, otherwise one bad row poisons the whole atomic flush and drops
+ * unrelated valid jobs (data loss, #92-class). Everything else (disk I/O, busy,
+ * full) is treated as transient and retried.
+ */
+function isConstraintError(err) {
+    const code = err.code ?? '';
+    return code.startsWith('SQLITE_CONSTRAINT') || /constraint failed/i.test(err.message);
+}
 /** Batch insert manager with prepared statement caching */
 export class BatchInsertManager {
     db;
@@ -10,20 +24,52 @@ export class BatchInsertManager {
     constructor(db) {
         this.db = db;
     }
-    /** Insert batch of jobs using multi-row INSERT for 50-100x speedup */
+    /**
+     * Insert a batch of jobs using a single multi-row INSERT (50-100x speedup).
+     * On the common path every row succeeds and an empty result is returned.
+     *
+     * If the atomic batch fails (e.g. a single duplicate `jobs.id`), the rows are
+     * re-inserted ONE AT A TIME so a single bad row can no longer drop the rest:
+     * valid jobs persist, constraint violations are isolated as `conflicts` (drop,
+     * never retry — they would poison every future flush), and any transient
+     * failures are returned so the caller can retry just those. Never throws.
+     */
     insertJobsBatch(jobs) {
         if (jobs.length === 0)
-            return;
+            return { transient: [], conflicts: [] };
         const now = Date.now();
-        const COLS_PER_ROW = 24;
-        // SQLite has a limit of ~999 variables, so batch in chunks
-        const MAX_ROWS_PER_INSERT = Math.floor(999 / COLS_PER_ROW);
-        this.db.transaction(() => {
-            for (let offset = 0; offset < jobs.length; offset += MAX_ROWS_PER_INSERT) {
-                const chunk = jobs.slice(offset, offset + MAX_ROWS_PER_INSERT);
-                this.insertJobsChunk(chunk, now);
+        try {
+            this.db.transaction(() => {
+                for (let offset = 0; offset < jobs.length; offset += MAX_ROWS_PER_INSERT) {
+                    const chunk = jobs.slice(offset, offset + MAX_ROWS_PER_INSERT);
+                    this.insertJobsChunk(chunk, now);
+                }
+            })();
+            return { transient: [], conflicts: [] };
+        }
+        catch (err) {
+            const batchError = err instanceof Error ? err : new Error(String(err));
+            return this.insertRowByRow(jobs, now, batchError);
+        }
+    }
+    /** Fallback path: insert each job independently, isolating per-row failures. */
+    insertRowByRow(jobs, now, batchError) {
+        const transient = [];
+        const conflicts = [];
+        for (const job of jobs) {
+            try {
+                // Single-row INSERT, auto-committed: succeeds/fails independently.
+                this.insertJobsChunk([job], now);
+            }
+            catch (e) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                if (isConstraintError(err))
+                    conflicts.push(job);
+                else
+                    transient.push(job);
             }
-        })();
+        }
+        return { transient, conflicts, error: batchError };
     }
     /** Get or create cached prepared statement for batch insert */
     getBatchInsertStmt(size) {
@@ -112,7 +158,16 @@ export class WriteBuffer {
             this.flush();
         }
     }
-    /** Flush buffer to disk using double-buffering. Returns number of jobs flushed. */
+    /**
+     * Flush buffer to disk using double-buffering. Returns number of jobs persisted.
+     *
+     * Per-row isolation (see BatchInsertManager.insertJobsBatch): valid jobs are
+     * persisted even if a sibling row violates a constraint. Constraint conflicts
+     * (e.g. duplicate id) are dropped+reported and NEVER re-buffered — re-buffering
+     * them would poison every future flush and silently drop unrelated valid jobs
+     * (the #92-class data-loss bug). Transient failures are re-buffered and retried
+     * with exponential backoff, exactly as before.
+     */
     flush() {
         // Prevent flush after stop or concurrent flushes
         if (this.stopped || this.flushing)
@@ -125,53 +180,68 @@ export class WriteBuffer {
         this.activeBuffer = [];
         const jobCount = this.flushBuffer.length;
         try {
-            this.batchManager.insertJobsBatch(this.flushBuffer);
-            this.flushBuffer = []; // Clear after successful write
-            // Reset retry state on success
-            this.retryCount = 0;
-            this.currentBackoffMs = this.initialBackoffMs;
-            this.lastError = null;
-            return jobCount;
-        }
-        catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
-            this.lastError = error;
-            this.retryCount++;
-            // On failure, prepend failed jobs back to active buffer
-            // This preserves order: failed jobs first, then new jobs
-            this.activeBuffer = this.flushBuffer.concat(this.activeBuffer);
+            // BatchInsertManager.insertJobsBatch isolates per-row failures and never
+            // throws. Stay defensive: a manager that throws (or returns nothing) is
+            // treated as a transient failure of the whole batch, preserving the
+            // re-buffer/retry/critical-loss semantics.
+            let result;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive against a non-conforming batch manager (e.g. a test double returning undefined)
+                result = this.batchManager.insertJobsBatch(this.flushBuffer) ?? {
+                    transient: [],
+                    conflicts: [],
+                };
+            }
+            catch (err) {
+                result = {
+                    transient: this.flushBuffer,
+                    conflicts: [],
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+            const { transient, conflicts, error } = result;
             this.flushBuffer = [];
-            // Check if we've exceeded max retries
-            if (this.retryCount >= this.maxRetries) {
-                // Move jobs to dead letter / emit critical error
-                const lostJobs = [...this.activeBuffer];
-                this.activeBuffer = [];
-                if (this.onCriticalError) {
-                    this.onCriticalError(lostJobs, error, this.retryCount);
+            // Permanent constraint conflicts: drop + report once, never retry.
+            if (conflicts.length > 0) {
+                this.onError(error ?? new Error('Constraint violation'), conflicts.length);
+            }
+            // Transient failures: re-buffer just those and retry with backoff.
+            if (transient.length > 0) {
+                const error2 = error ?? new Error('Write buffer flush failed');
+                this.lastError = error2;
+                this.retryCount++;
+                // Prepend failed jobs back to active buffer (failed first, then new).
+                this.activeBuffer = transient.concat(this.activeBuffer);
+                if (this.retryCount >= this.maxRetries) {
+                    const lostJobs = [...this.activeBuffer];
+                    this.activeBuffer = [];
+                    if (this.onCriticalError)
+                        this.onCriticalError(lostJobs, error2, this.retryCount);
+                    this.onError(error2, lostJobs.length, {
+                        retryCount: this.retryCount,
+                        nextBackoffMs: 0,
+                        maxRetries: this.maxRetries,
+                    });
+                    this.retryCount = 0;
+                    this.currentBackoffMs = this.initialBackoffMs;
+                    this.lastError = null;
+                }
+                else {
+                    const nextBackoffMs = Math.min(this.currentBackoffMs * 2, this.maxBackoffMs);
+                    this.onError(error2, transient.length, {
+                        retryCount: this.retryCount,
+                        nextBackoffMs,
+                        maxRetries: this.maxRetries,
+                    });
+                    this.scheduleBackoffRetry();
                 }
-                // Also call onError with retry info for logging
-                this.onError(error, lostJobs.length, {
-                    retryCount: this.retryCount,
-                    nextBackoffMs: 0, // No more retries
-                    maxRetries: this.maxRetries,
-                });
-                // Reset retry state
-                this.retryCount = 0;
-                this.currentBackoffMs = this.initialBackoffMs;
-                this.lastError = null;
-                throw err;
+                return jobCount - transient.length - conflicts.length;
             }
-            // Calculate next backoff with exponential increase
-            const nextBackoffMs = Math.min(this.currentBackoffMs * 2, this.maxBackoffMs);
-            // Call error callback with retry information
-            this.onError(error, jobCount, {
-                retryCount: this.retryCount,
-                nextBackoffMs: nextBackoffMs,
-                maxRetries: this.maxRetries,
-            });
-            // Schedule backoff retry
-            this.scheduleBackoffRetry();
-            throw err;
+            // Success (or success-modulo-dropped-conflicts): reset retry state.
+            this.retryCount = 0;
+            this.currentBackoffMs = this.initialBackoffMs;
+            this.lastError = null;
+            return jobCount - conflicts.length;
         }
         finally {
             this.flushing = false;
@@ -287,6 +357,10 @@ export class WriteBuffer {
                 const flushed = this.flush();
                 clearTimeout(timeout);
                 this.stopped = true;
+                // flush() no longer throws on transient failure (it re-buffers); report
+                // anything that could not be persisted so it isn't silently lost.
+                if (this.pendingCount > 0)
+                    this.reportLostJobs();
                 resolve(flushed);
             }
             catch {

package/dist/infrastructure/server/handlers/dashboard.js

@@ -6,6 +6,7 @@
 import * as resp from '../../../domain/types/response';
 import { throughputTracker } from '../../../application/throughputTracker';
 import { latencyTracker } from '../../../application/latencyTracker';
+import { pausedView } from '../../../shared/pausedView';
 /** Dashboard overview - single call for all dashboard data */
 export function handleDashboardOverview(_cmd, ctx, reqId) {
     const stats = ctx.queueManager.getStats();
@@ -92,8 +93,17 @@ export function handleDashboardQueues(_cmd, ctx, reqId) {
 /** Dashboard single queue detail */
 export function handleDashboardQueue(cmd, ctx, reqId) {
     const queue = cmd.queue;
-    const counts = ctx.queueManager.getQueueJobCounts(queue);
+    const rawCounts = ctx.queueManager.getQueueJobCounts(queue);
     const paused = ctx.queueManager.isPaused(queue);
+    // Keep the counts consistent with the per-state lists below (#92): a paused
+    // queue reports ready jobs under `paused`, not `waiting`/`prioritized`.
+    const pv = pausedView(rawCounts.waiting, rawCounts.prioritized, paused);
+    const counts = {
+        ...rawCounts,
+        waiting: pv.waiting,
+        prioritized: pv.prioritized,
+        paused: pv.paused,
+    };
     const dlqJobs = ctx.queueManager.getDlq(queue, 10);
     const priorityCounts = ctx.queueManager.getCountsPerPriority(queue);
     const result = {
@@ -111,13 +121,19 @@ export function handleDashboardQueue(cmd, ctx, reqId) {
     };
     if (cmd.includeJobs) {
         const limit = Math.min(cmd.jobsLimit ?? 10, 50);
+        // When paused, ready jobs surface under `paused` (waiting/prioritized are
+        // empty) — match the counts above (#92).
         const waiting = ctx.queueManager.getJobs(queue, { state: 'waiting', end: limit });
         const active = ctx.queueManager.getJobs(queue, { state: 'active', end: limit });
         const delayed = ctx.queueManager.getJobs(queue, { state: 'delayed', end: limit });
+        const pausedJobs = paused
+            ? ctx.queueManager.getJobs(queue, { state: 'paused', end: limit })
+            : [];
         result.jobs = {
             waiting: waiting.map(jobSummary),
             active: active.map(jobSummary),
             delayed: delayed.map(jobSummary),
+            paused: pausedJobs.map(jobSummary),
         };
     }
     return resp.data(result, reqId);

package/dist/infrastructure/server/handlers/query.js

@@ -4,6 +4,7 @@
  */
 import * as resp from '../../../domain/types/response';
 import { jobId } from '../../../domain/types/job';
+import { pausedView } from '../../../shared/pausedView';
 /** Handle GetJob command */
 export async function handleGetJob(cmd, ctx, reqId) {
     const jid = jobId(cmd.id);
@@ -28,15 +29,18 @@ export function handleGetJobCounts(cmd, ctx, reqId) {
     // Get queue-specific counts
     const counts = ctx.queueManager.getQueueJobCounts(cmd.queue);
     const isPaused = ctx.queueManager.isPaused(cmd.queue);
+    // When paused, ready jobs (waiting + prioritized) are reported under `paused` —
+    // not in their own buckets, which would double-count (#92, BullMQ semantics).
+    const pv = pausedView(counts.waiting, counts.prioritized, isPaused);
     return resp.counts({
-        waiting: counts.waiting,
-        prioritized: counts.prioritized,
+        waiting: pv.waiting,
+        prioritized: pv.prioritized,
         delayed: counts.delayed,
         active: counts.active,
         completed: counts.completed,
         failed: counts.failed,
         'waiting-children': counts['waiting-children'],
-        paused: isPaused ? counts.waiting : 0,
+        paused: pv.paused,
     }, reqId);
 }
 /** Handle GetCountsPerPriority command */

package/dist/infrastructure/server/httpEndpoints.js

@@ -4,6 +4,7 @@
 import { VERSION } from '../../shared/version';
 import { throughputTracker } from '../../application/throughputTracker';
 import { latencyTracker } from '../../application/latencyTracker';
+import { pausedView } from '../../shared/pausedView';
 /** JSON response helper */
 export function jsonResponse(data, status = 200, corsOrigins) {
     const headers = {
@@ -256,8 +257,17 @@ export function dashboardQueuesEndpoint(queueManager, limit, offset, corsOrigins
 }
 /** Dashboard single queue detail endpoint */
 export function dashboardQueueDetailEndpoint(queueManager, queue, includeJobs, corsOrigins) {
-    const counts = queueManager.getQueueJobCounts(queue);
+    const rawCounts = queueManager.getQueueJobCounts(queue);
     const paused = queueManager.isPaused(queue);
+    // Keep counts consistent with the per-state lists below (#92): a paused queue
+    // reports ready jobs under `paused`, not `waiting`/`prioritized`.
+    const pv = pausedView(rawCounts.waiting, rawCounts.prioritized, paused);
+    const counts = {
+        ...rawCounts,
+        waiting: pv.waiting,
+        prioritized: pv.prioritized,
+        paused: pv.paused,
+    };
     const dlqJobs = queueManager.getDlq(queue, 10);
     const priorityCounts = queueManager.getCountsPerPriority(queue);
     const result = {
@@ -275,9 +285,12 @@ export function dashboardQueueDetailEndpoint(queueManager, queue, includeJobs, c
         timestamp: Date.now(),
     };
     if (includeJobs) {
+        // When paused, ready jobs surface under `paused` (waiting is empty) — match
+        // the counts above (#92).
         const waiting = queueManager.getJobs(queue, { state: 'waiting', end: 10 });
         const active = queueManager.getJobs(queue, { state: 'active', end: 10 });
         const delayed = queueManager.getJobs(queue, { state: 'delayed', end: 10 });
+        const pausedJobs = paused ? queueManager.getJobs(queue, { state: 'paused', end: 10 }) : [];
         const toSummary = (j) => ({
             id: j.id,
             priority: j.priority,
@@ -290,6 +303,7 @@ export function dashboardQueueDetailEndpoint(queueManager, queue, includeJobs, c
             waiting: waiting.map(toSummary),
             active: active.map(toSummary),
             delayed: delayed.map(toSummary),
+            paused: pausedJobs.map(toSummary),
         };
     }
     return jsonResponse(result, 200, corsOrigins);

package/dist/require-bun.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bun-only runtime guard (defense-in-depth for the bundled path).
+ *
+ * The `"node"` export condition (-> bun-only.ts) already fails fast for a plain
+ * `node` import and for node-target bundlers. This guard covers the remaining
+ * case: a browser/neutral-target bundler that inlines the real client, whose
+ * output is then run on Node. Without it, the failure surfaces deep inside as a
+ * cryptic `Bun is not defined` / `Bun.connect is not a function`.
+ *
+ * Imported FIRST by the client entrypoints so it evaluates before any module
+ * that touches `Bun.*` at top level. No-op under Bun. Keep relative-import-free.
+ */
+export {};

package/dist/require-bun.js

@@ -0,0 +1,17 @@
+/**
+ * Bun-only runtime guard (defense-in-depth for the bundled path).
+ *
+ * The `"node"` export condition (-> bun-only.ts) already fails fast for a plain
+ * `node` import and for node-target bundlers. This guard covers the remaining
+ * case: a browser/neutral-target bundler that inlines the real client, whose
+ * output is then run on Node. Without it, the failure surfaces deep inside as a
+ * cryptic `Bun is not defined` / `Bun.connect is not a function`.
+ *
+ * Imported FIRST by the client entrypoints so it evaluates before any module
+ * that touches `Bun.*` at top level. No-op under Bun. Keep relative-import-free.
+ */
+if (typeof globalThis.Bun === 'undefined') {
+    throw new Error('bunqueue is Bun-only and requires the Bun runtime (https://bun.sh). ' +
+        'Node.js is not supported: install Bun and run your program with `bun`.');
+}
+export {};

package/dist/shared/pausedView.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BullMQ paused-view counts (#92).
+ *
+ * When a queue is paused, none of its ready jobs (waiting + prioritized) can be
+ * pulled, so they are reported under `paused` — and NOT in their own buckets, to
+ * avoid double-counting a single job. This mirrors the per-state lists, where a
+ * paused queue lists those jobs under `paused` and returns nothing for `waiting`
+ * / `prioritized`. Delayed and active jobs keep their own state.
+ *
+ * Single source of truth shared by every count surface that exposes the BullMQ
+ * `getJobCounts` shape (client SDK, TCP handler, dashboard detail), so they can
+ * never drift apart.
+ */
+export interface PausedDerivedCounts {
+    waiting: number;
+    prioritized: number;
+    paused: number;
+}
+export declare function pausedView(waiting: number, prioritized: number, isPaused: boolean): PausedDerivedCounts;

package/dist/shared/pausedView.js

@@ -0,0 +1,7 @@
+export function pausedView(waiting, prioritized, isPaused) {
+    return {
+        waiting: isPaused ? 0 : waiting,
+        prioritized: isPaused ? 0 : prioritized,
+        paused: isPaused ? waiting + prioritized : 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.3",
+  "version": "2.8.5",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external dependencies.",
   "type": "module",
   "main": "dist/main.js",
@@ -12,22 +12,32 @@
   "exports": {
     ".": {
       "types": "./dist/main.d.ts",
+      "bun": "./dist/main.js",
+      "node": "./dist/bun-only.js",
       "import": "./dist/main.js"
     },
     "./client": {
       "types": "./dist/client/index.d.ts",
+      "bun": "./dist/client/index.js",
+      "node": "./dist/bun-only.js",
       "import": "./dist/client/index.js"
     },
     "./queue": {
       "types": "./dist/application/queueManager.d.ts",
+      "bun": "./dist/application/queueManager.js",
+      "node": "./dist/bun-only.js",
       "import": "./dist/application/queueManager.js"
     },
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
+      "bun": "./dist/mcp/index.js",
+      "node": "./dist/bun-only.js",
       "import": "./dist/mcp/index.js"
     },
     "./workflow": {
       "types": "./dist/client/workflow/index.d.ts",
+      "bun": "./dist/client/workflow/index.js",
+      "node": "./dist/bun-only.js",
       "import": "./dist/client/workflow/index.js"
     },
     "./package.json": "./package.json"
@@ -137,7 +147,6 @@
   },
   "homepage": "https://bunqueue.dev",
   "engines": {
-    "node": ">=18.0.0",
     "bun": ">=1.3.9"
   }
 }