bunqueue 2.8.2 → 2.8.4

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

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/main 2.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env bun
+/**
+ * bunqueue - High-performance job queue server for Bun
+ * Main entry point - routes to CLI for client commands or starts server
+ */
+// Only run startup dispatch when this file is the program entry point.
+// Issue #85: re-exporting `defineConfig` means user config files import this
+// module; without this guard, the top-level dispatch would re-run the CLI/server
+// on every import and cause "Failed to listen at 0.0.0.0".
+if (import.meta.main) {
+    const clientCommands = [
+        'push',
+        'pull',
+        'ack',
+        'fail',
+        'job',
+        'queue',
+        'dlq',
+        'cron',
+        'worker',
+        'webhook',
+        'rate-limit',
+        'concurrency',
+        'stats',
+        'metrics',
+        'health',
+        'backup',
+    ];
+    const firstArg = process.argv[2];
+    const isClientCommand = firstArg && clientCommands.includes(firstArg);
+    const isStartCommand = firstArg === 'start';
+    const hasHelpOrVersion = process.argv.includes('--help') || process.argv.includes('--version');
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- process.argv[2] can be undefined at runtime
+    const hasFlags = firstArg?.startsWith('-');
+    if (isClientCommand || hasHelpOrVersion || isStartCommand || hasFlags) {
+        void import('./cli/index').then(({ main }) => main());
+    }
+    else {
+        void startServer();
+    }
+}
+import { QueueManager } from './application/queueManager';
+import { createTcpServer } from './infrastructure/server/tcp';
+import { createHttpServer } from './infrastructure/server/http';
+import { Logger, serverLog, statsLog } from './shared/logger';
+import { stopRateLimiter } from './infrastructure/server/rateLimiter';
+import { VERSION } from './shared/version';
+import { S3BackupManager } from './infrastructure/backup';
+import { CloudAgent } from './infrastructure/cloud';
+import { SHARD_COUNT } from './shared/hash';
+import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveBackupConfig, } from './config';
+export { defineConfig } from './config';
+/** Print startup banner */
+function printBanner(config, cloudUrl) {
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    const bold = '\x1b[1m';
+    const magenta = '\x1b[35m';
+    const green = '\x1b[32m';
+    const yellow = '\x1b[33m';
+    // Format TCP endpoint display
+    const tcpDisplay = config.tcpSocketPath
+        ? `${bold}${config.tcpSocketPath}${reset} ${dim}(unix)${reset}`
+        : `${bold}${config.hostname}:${config.tcpPort}${reset}`;
+    // Format HTTP endpoint display
+    const httpDisplay = config.httpSocketPath
+        ? `${bold}${config.httpSocketPath}${reset} ${dim}(unix)${reset}`
+        : `${bold}${config.hostname}:${config.httpPort}${reset}`;
+    // Socket mode display
+    const hasUnixSockets = config.tcpSocketPath !== undefined || config.httpSocketPath !== undefined;
+    const socketDisplay = hasUnixSockets
+        ? `${green}enabled${reset} ${dim}(${config.tcpSocketPath ? 'TCP' : ''}${config.tcpSocketPath && config.httpSocketPath ? '+' : ''}${config.httpSocketPath ? 'HTTP' : ''})${reset}`
+        : `${dim}disabled${reset}`;
+    console.log(`
+${magenta}        (\\(\\        ${reset}
+${magenta}        ( -.-)      ${bold}bunqueue${reset} ${dim}v${VERSION}${reset}
+${magenta}        o_(")(")    ${reset}${dim}High-performance job queue for Bun${reset}
+
+${dim}─────────────────────────────────────────────────${reset}
+
+  ${green}●${reset} TCP    ${tcpDisplay}
+  ${green}●${reset} HTTP   ${httpDisplay}
+  ${yellow}●${reset} Socket ${socketDisplay}
+  ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
+  ${yellow}●${reset} Auth   ${config.authTokens.length > 0 ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} S3 Backup ${config.s3BackupEnabled ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} Cloud  ${cloudUrl ? `${green}enabled${reset} ${dim}→ ${cloudUrl}${reset}` : `${dim}disabled${reset}`}
+  ${dim}●${reset} Shards ${bold}${SHARD_COUNT}${reset} ${dim}(${navigator.hardwareConcurrency} CPU cores)${reset}
+
+${dim}─────────────────────────────────────────────────${reset}
+
+`);
+}
+/** Start the server (direct mode) */
+async function startServer() {
+    // Load config file (bunqueue.config.ts) if present, then merge with env vars
+    const fileConfig = await loadConfigFile();
+    const config = resolveServerConfig(fileConfig);
+    // Apply logging config before anything else
+    const logFormat = fileConfig?.logging?.format ?? Bun.env.LOG_FORMAT;
+    const logLevel = fileConfig?.logging?.level ?? Bun.env.LOG_LEVEL?.toLowerCase();
+    if (logFormat === 'json')
+        Logger.enableJsonMode();
+    if (logLevel) {
+        const validLevels = ['debug', 'info', 'warn', 'error'];
+        if (validLevels.includes(logLevel))
+            Logger.setLevel(logLevel);
+    }
+    // Resolve cloud config
+    const cloudConfig = resolveCloudConfig(fileConfig, config.dataPath);
+    printBanner(config, cloudConfig?.url);
+    // Create queue manager
+    const queueManager = new QueueManager({
+        dataPath: config.dataPath,
+    });
+    // Start TCP server
+    const tcpServer = createTcpServer(queueManager, {
+        port: config.tcpPort,
+        hostname: config.hostname,
+        authTokens: config.authTokens,
+    });
+    // Start HTTP server
+    const httpServer = createHttpServer(queueManager, {
+        port: config.httpPort,
+        hostname: config.hostname,
+        authTokens: config.authTokens,
+        corsOrigins: config.corsOrigins,
+        requireAuthForMetrics: config.requireAuthForMetrics,
+    });
+    // Initialize S3 backup manager
+    let backupManager = null;
+    if (config.dataPath) {
+        const backupConfig = resolveBackupConfig(fileConfig, config.dataPath);
+        backupManager = new S3BackupManager(backupConfig);
+        backupManager.setDashboardEmit(queueManager.emitDashboardEvent.bind(queueManager));
+        backupManager.start();
+    }
+    // Initialize bunqueue Cloud agent (remote dashboard telemetry)
+    const cloudAgent = cloudConfig ? CloudAgent.createFromConfig(queueManager, cloudConfig) : null;
+    if (cloudAgent) {
+        cloudAgent.setServerHandles({
+            getConnectionCount: () => tcpServer.getConnectionCount(),
+            getWsClientCount: () => httpServer.getWsClientCount(),
+            getSseClientCount: () => httpServer.getSseClientCount(),
+            getBackupStatus: () => backupManager?.getStatus() ?? null,
+        });
+    }
+    queueManager.emitDashboardEvent('server:started', {
+        tcpPort: config.tcpPort,
+        httpPort: config.httpPort,
+        shards: SHARD_COUNT,
+    });
+    // Graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        serverLog.info(`Received ${signal}, shutting down...`);
+        // Stop stats interval immediately
+        clearInterval(statsInterval);
+        tcpServer.stop();
+        httpServer.stop();
+        const shutdownTimeout = config.shutdownTimeoutMs;
+        const start = Date.now();
+        while (Date.now() - start < shutdownTimeout) {
+            const stats = queueManager.getStats();
+            if (stats.active === 0)
+                break;
+            serverLog.info(`Waiting for ${stats.active} active jobs...`);
+            await Bun.sleep(1000);
+        }
+        // Stop backup manager
+        if (backupManager) {
+            backupManager.stop();
+        }
+        // Stop Cloud agent (sends final shutdown snapshot)
+        if (cloudAgent) {
+            await cloudAgent.stop();
+        }
+        queueManager.emitDashboardEvent('server:shutdown', { signal });
+        queueManager.shutdown();
+        stopRateLimiter();
+        serverLog.info('Shutdown complete');
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('uncaughtException', (err) => {
+        serverLog.error('Uncaught exception - initiating shutdown', {
+            error: err.message,
+            stack: err.stack,
+        });
+        void shutdown('uncaughtException');
+    });
+    process.on('unhandledRejection', (reason) => {
+        serverLog.error('Unhandled promise rejection - initiating shutdown', {
+            reason: reason instanceof Error ? reason.message : String(reason),
+            stack: reason instanceof Error ? reason.stack : undefined,
+        });
+        void shutdown('unhandledRejection');
+    });
+    // Print stats periodically
+    const statsInterval = setInterval(() => {
+        const stats = queueManager.getStats();
+        const memStats = queueManager.getMemoryStats();
+        const workerStats = queueManager.workerManager.getStats();
+        const mem = process.memoryUsage();
+        const now = new Date();
+        const timestamp = now.toLocaleTimeString('en-GB', {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+        statsLog.info('Queue statistics', {
+            time: timestamp,
+            waiting: stats.waiting,
+            active: stats.active,
+            delayed: stats.delayed,
+            completed: stats.completed,
+            dlq: stats.dlq,
+            tcp: tcpServer.getConnectionCount(),
+            ws: httpServer.getWsClientCount(),
+            sse: httpServer.getSseClientCount(),
+            workers: `${workerStats.active}/${workerStats.total}`,
+            mem: `${Math.round(mem.heapUsed / 1024 / 1024)}MB/${Math.round(mem.heapTotal / 1024 / 1024)}MB`,
+            rss: `${Math.round(mem.rss / 1024 / 1024)}MB`,
+            // Internal collection sizes (for memory debugging)
+            idx: memStats.jobIndex,
+            locks: memStats.jobLocks,
+            clients: memStats.clientJobsTotal,
+        });
+    }, config.statsIntervalMs);
+}
+// Logger env-var bootstrap only applies when this file is the entry point.
+// Imported consumers (e.g. user config files using `defineConfig`) must not
+// have their process Logger state mutated as a side effect — see Issue #85.
+if (import.meta.main) {
+    if (Bun.env.LOG_FORMAT === 'json') {
+        Logger.enableJsonMode();
+    }
+    if (Bun.env.LOG_LEVEL) {
+        const validLevels = ['debug', 'info', 'warn', 'error'];
+        const level = Bun.env.LOG_LEVEL.toLowerCase();
+        if (validLevels.includes(level)) {
+            Logger.setLevel(level);
+        }
+    }
+}
+//# sourceMappingURL=main.js.map

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.2",
+  "version": "2.8.4",
   "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,24 +12,35 @@
   "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"
   },
   "files": [
     "dist/**/*.js",
@@ -136,7 +147,6 @@
   },
   "homepage": "https://bunqueue.dev",
   "engines": {
-    "node": ">=18.0.0",
     "bun": ">=1.3.9"
   }
 }