@basaltkit/queue 1.3.0 → 1.3.1

package/README.md

@@ -330,6 +330,14 @@ The sync driver always runs immediately. Delays, timed backoff, and priority onl
 **Do I need Redis to run the tests?**
 No. Without `connection`, the plugin uses `SyncQueueDriver`. You can also instantiate the driver directly and inspect `driver.executed`.
 
+## Sync driver semantics
+
+The inline sync driver (the default without a `connection`) is at-most-once:
+handler errors reject `dispatch()` and an exhausted job is lost. Selecting it
+implicitly in production logs a boot warning — pass `driver: new
+SyncQueueDriver()` to opt in deliberately. Its `executed[]` history is capped
+at 1000 entries.
+
 ## How it connects to other modules
 
 - **`@basaltkit/core`** — provides `createApp`/`definePlugin` (`queuePlugin` is a core plugin), the ALS context (`runWithContext`/`ctx`) propagated to workers, `parseDuration` (formats `'30s'`, `'10m'`), and the base `BasaltError` class.

package/dist/drivers/sync.d.ts

@@ -3,6 +3,15 @@ import type { AddJobOptions, JobExecutor, QueueDriver } from '../driver.js';
  * Synchronous driver: executes the job inline on dispatch, honoring `attempts`
  * (immediate retry). It is the driver for tests and Redis-less dev — the
  * equivalent of Laravel's `sync` queue driver.
+ *
+ * Semantics to be aware of (they differ from a broker-backed driver):
+ * - **At-most-once.** A job that exhausts its inline retries is LOST — there is
+ *   no persistence and no later redelivery.
+ * - **Errors propagate to the dispatcher.** `job.dispatch()` rejects when the
+ *   handler fails (useful in tests/dev; a broker driver would return
+ *   immediately and retry in the background).
+ * Deploying this driver to production is almost always a misconfiguration —
+ * `queuePlugin` warns when it is selected by default there.
  */
 export declare class SyncQueueDriver implements QueueDriver {
     readonly name = "sync";
@@ -22,5 +31,8 @@ export declare class SyncQueueDriver implements QueueDriver {
     setExecutor(executor: JobExecutor): void;
     add(queue: string, jobName: string, data: unknown, options: AddJobOptions): Promise<void>;
     startWorker(): void;
+    /** Appends to `executed[]`, evicting the oldest entries past the cap so a
+     * long-running process on this driver cannot leak memory unboundedly. */
+    private record;
     close(): Promise<void>;
 }

package/dist/drivers/sync.js

@@ -1,7 +1,18 @@
+/** `executed[]` keeps at most this many entries (oldest evicted first). */
+const EXECUTED_HISTORY_LIMIT = 1000;
 /**
  * Synchronous driver: executes the job inline on dispatch, honoring `attempts`
  * (immediate retry). It is the driver for tests and Redis-less dev — the
  * equivalent of Laravel's `sync` queue driver.
+ *
+ * Semantics to be aware of (they differ from a broker-backed driver):
+ * - **At-most-once.** A job that exhausts its inline retries is LOST — there is
+ *   no persistence and no later redelivery.
+ * - **Errors propagate to the dispatcher.** `job.dispatch()` rejects when the
+ *   handler fails (useful in tests/dev; a broker driver would return
+ *   immediately and retry in the background).
+ * Deploying this driver to production is almost always a misconfiguration —
+ * `queuePlugin` warns when it is selected by default there.
  */
 export class SyncQueueDriver {
     name = 'sync';
@@ -19,18 +30,26 @@ export class SyncQueueDriver {
         for (let attempt = 1; attempt <= options.attempts; attempt++) {
             try {
                 await this.executor?.(jobName, data);
-                this.executed.push({ queue, jobName, attempts: attempt });
+                this.record({ queue, jobName, attempts: attempt });
                 return;
             }
             catch (error) {
                 lastError = error;
             }
         }
-        this.executed.push({ queue, jobName, attempts: options.attempts });
+        this.record({ queue, jobName, attempts: options.attempts });
         throw lastError;
     }
     startWorker() {
         // no-op: add() already executes inline
     }
+    /** Appends to `executed[]`, evicting the oldest entries past the cap so a
+     * long-running process on this driver cannot leak memory unboundedly. */
+    record(entry) {
+        this.executed.push(entry);
+        if (this.executed.length > EXECUTED_HISTORY_LIMIT) {
+            this.executed.splice(0, this.executed.length - EXECUTED_HISTORY_LIMIT);
+        }
+    }
     async close() { }
 }

package/dist/index.js

@@ -14,10 +14,25 @@ export function queuePlugin(options = {}) {
         register({ container }) {
             registerQueueCommands(container);
             container.singleton(QUEUE, () => {
-                const driver = options.driver ??
-                    (options.connection
-                        ? new BullmqQueueDriver({ connection: options.connection })
-                        : new SyncQueueDriver());
+                let driver = options.driver;
+                if (!driver) {
+                    if (options.connection) {
+                        driver = new BullmqQueueDriver({ connection: options.connection });
+                    }
+                    else {
+                        driver = new SyncQueueDriver();
+                        if (process.env['NODE_ENV'] === 'production') {
+                            // The silent default without a Redis connection is the inline sync
+                            // driver: at-most-once, no background retries, handler errors
+                            // propagate into the dispatching request. Deliberate sync use in
+                            // production stays possible — pass `driver: new SyncQueueDriver()`
+                            // explicitly to silence this.
+                            console.warn('[basalt:queue] No `connection` (Redis) configured — falling back to the inline sync driver. ' +
+                                'Jobs run at-most-once inside the dispatching request and are lost on failure. ' +
+                                'Configure a Redis `connection` for production, or pass `driver: new SyncQueueDriver()` to opt in explicitly.');
+                        }
+                    }
+                }
                 const manager = new QueueManager(driver, {
                     ...(options.onUnsupported !== undefined ? { onUnsupported: options.onUnsupported } : {}),
                     ...(options.removeOnComplete !== undefined ? { removeOnComplete: options.removeOnComplete } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/queue",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Basalt queues on top of BullMQ: declarative jobs with Zod payloads, context propagation (tenant/requestId) to workers and a sync driver for tests.",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,7 @@
   "dependencies": {
     "bullmq": "^6.2.1",
     "@basaltkit/core": "^1.3.0",
-    "@basaltkit/events": "^1.0.1"
+    "@basaltkit/events": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",