@basaltkit/queue 1.0.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.d.ts

@@ -3,6 +3,11 @@ import { DurationInput, BasaltError } from '@basaltkit/core';
 import { ConnectionOptions } from 'bullmq';
 import { EventBus, BasaltEvent } from '@basaltkit/events';
 
+/** Driver-neutral retention: `true`/`false`, a count, or `{ ageMs, count }`. */
+type RetentionOption = boolean | number | {
+    ageMs?: number;
+    count?: number;
+};
 interface AddJobOptions {
     attempts: number;
     backoff?: {
@@ -11,6 +16,10 @@ interface AddJobOptions {
     } | undefined;
     delayMs?: number | undefined;
     priority?: number | undefined;
+    /** Retention for completed jobs. Undefined → the driver's default. */
+    removeOnComplete?: RetentionOption | undefined;
+    /** Retention for failed jobs. Undefined → the driver's default. */
+    removeOnFail?: RetentionOption | undefined;
 }
 type JobExecutor = (jobName: string, data: unknown) => Promise<void>;
 /**
@@ -96,12 +105,26 @@ interface JobBackoff {
     type: 'exponential' | 'fixed';
     delay: DurationInput;
 }
+/**
+ * Redis retention for finished jobs (BullMQ driver): `true` removes it as soon as
+ * it finishes, `false` keeps it forever, a number keeps that many most-recent, and
+ * `{ age, count }` keeps by age and/or count. Defaults: completed `{ count: 1000 }`,
+ * failed `false` (keep all). The sync driver ignores it (it stores nothing).
+ */
+type JobRetention = boolean | number | {
+    age?: DurationInput;
+    count?: number;
+};
 interface JobDefinition<T = unknown> {
     readonly name: string;
     readonly schema?: JobSchema<T> | undefined;
     readonly queue: string;
     readonly attempts: number;
     readonly backoff?: JobBackoff | undefined;
+    /** Retention for completed jobs. Overrides the queuePlugin default. */
+    readonly removeOnComplete?: JobRetention | undefined;
+    /** Retention for failed jobs. Overrides the queuePlugin default. */
+    readonly removeOnFail?: JobRetention | undefined;
     handle(payload: T): void | Promise<void>;
     /** Enqueues the job — available after registration in a QueueManager. */
     dispatch(payload: T, options?: DispatchOptions): Promise<void>;
@@ -128,6 +151,8 @@ declare function defineJob<T = unknown>(config: {
     queue?: string;
     attempts?: number;
     backoff?: JobBackoff;
+    removeOnComplete?: JobRetention;
+    removeOnFail?: JobRetention;
     handle(payload: T): void | Promise<void>;
 }): JobDefinition<T>;
 
@@ -151,6 +176,10 @@ interface QueueManagerOptions {
     onUnsupported?: UnsupportedPolicy;
     /** Sink for 'warn' diagnostics. Default console.warn. */
     warn?: (message: string) => void;
+    /** Default retention for completed jobs (a job can override). Driver default: keep 1000. */
+    removeOnComplete?: JobRetention;
+    /** Default retention for failed jobs (a job can override). Driver default: keep all. */
+    removeOnFail?: JobRetention;
 }
 declare class QueueManager implements JobDispatcher {
     private readonly driver;
@@ -158,6 +187,8 @@ declare class QueueManager implements JobDispatcher {
     private readonly onUnsupported;
     private readonly warn;
     private readonly warned;
+    private readonly defaultRemoveOnComplete;
+    private readonly defaultRemoveOnFail;
     constructor(driver: QueueDriver, options?: QueueManagerOptions);
     /**
      * Checks the dispatch's options against the driver's declared capabilities.
@@ -236,7 +267,18 @@ interface QueuePluginOptions {
      * 'throw' in production for a hard guarantee, 'ignore' for the old behavior.
      */
     onUnsupported?: UnsupportedPolicy;
+    /**
+     * Default retention for completed jobs in Redis (BullMQ). `true` removes on
+     * finish, a number keeps that many, `{ age: '7d', count: 500 }` caps both.
+     * Default: keep the last 1000. A job can override via `defineJob`.
+     */
+    removeOnComplete?: JobRetention;
+    /**
+     * Default retention for failed jobs. Default `false` (keep all, for inspection
+     * and retries) — set e.g. `{ age: '14d' }` so failures don't grow unbounded.
+     */
+    removeOnFail?: JobRetention;
 }
 declare function queuePlugin(options?: QueuePluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
 
-export { type AddJobOptions, type BullmqDriverOptions, BullmqQueueDriver, type DispatchOptions, type DriverCapabilities, type JobBackoff, type JobDefinition, type JobExecutor, JobNotRegisteredError, type JobSchema, JobValidationError, QUEUE, type QueueDriver, QueueManager, type QueueManagerOptions, type QueuePluginOptions, type QueuedListenerOptions, SyncQueueDriver, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, defineJob, queuePlugin, queuedOn };
+export { type AddJobOptions, type BullmqDriverOptions, BullmqQueueDriver, type DispatchOptions, type DriverCapabilities, type JobBackoff, type JobDefinition, type JobExecutor, JobNotRegisteredError, type JobRetention, type JobSchema, JobValidationError, QUEUE, type QueueDriver, QueueManager, type QueueManagerOptions, type QueuePluginOptions, type QueuedListenerOptions, SyncQueueDriver, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, defineJob, queuePlugin, queuedOn };

package/dist/index.js

@@ -3,6 +3,14 @@ import { createToken, definePlugin } from "@basaltkit/core";
 
 // src/drivers/bullmq.ts
 import { Queue, Worker } from "bullmq";
+function toBullRetention(retention, fallback) {
+  if (retention === void 0) return fallback;
+  if (typeof retention === "boolean" || typeof retention === "number") return retention;
+  const out = {};
+  if (retention.ageMs !== void 0) out.age = Math.max(1, Math.round(retention.ageMs / 1e3));
+  if (retention.count !== void 0) out.count = retention.count;
+  return out;
+}
 var BullmqQueueDriver = class {
   name = "bullmq";
   capabilities = { delayed: true, priority: true, retries: true, backoff: true };
@@ -22,8 +30,8 @@ var BullmqQueueDriver = class {
       ...options.backoff ? { backoff: { type: options.backoff.type, delay: options.backoff.delayMs } } : {},
       ...options.delayMs !== void 0 ? { delay: options.delayMs } : {},
       ...options.priority !== void 0 ? { priority: options.priority } : {},
-      removeOnComplete: { count: 1e3 },
-      removeOnFail: false
+      removeOnComplete: toBullRetention(options.removeOnComplete, { count: 1e3 }),
+      removeOnFail: toBullRetention(options.removeOnFail, false)
     });
   }
   startWorker(queue, options = {}) {
@@ -128,6 +136,8 @@ function defineJob(config) {
     queue: config.queue ?? "default",
     attempts: config.attempts ?? 1,
     backoff: config.backoff,
+    removeOnComplete: config.removeOnComplete,
+    removeOnFail: config.removeOnFail,
     handle: config.handle,
     async dispatch(payload, options) {
       if (!dispatcher) throw new JobNotRegisteredError(config.name);
@@ -150,6 +160,14 @@ function validatePayload(job, payload) {
 }
 
 // src/manager.ts
+function resolveRetention(retention) {
+  if (retention === void 0) return void 0;
+  if (typeof retention === "boolean" || typeof retention === "number") return retention;
+  const out = {};
+  if (retention.age !== void 0) out.ageMs = parseDuration(retention.age);
+  if (retention.count !== void 0) out.count = retention.count;
+  return out;
+}
 var UnknownJobError = class extends BasaltError2 {
   constructor(job) {
     super(
@@ -187,6 +205,8 @@ var QueueManager = class {
     this.driver = driver;
     this.onUnsupported = options.onUnsupported ?? "warn";
     this.warn = options.warn ?? ((message) => console.warn(message));
+    this.defaultRemoveOnComplete = options.removeOnComplete;
+    this.defaultRemoveOnFail = options.removeOnFail;
     driver.setExecutor((jobName, data) => this.execute(jobName, data));
   }
   driver;
@@ -194,6 +214,8 @@ var QueueManager = class {
   onUnsupported;
   warn;
   warned = /* @__PURE__ */ new Set();
+  defaultRemoveOnComplete;
+  defaultRemoveOnFail;
   /**
    * Checks the dispatch's options against the driver's declared capabilities.
    * A driver that omits `capabilities` is assumed fully capable (back-compat).
@@ -228,7 +250,10 @@ var QueueManager = class {
       attempts: job.attempts,
       backoff: job.backoff ? { type: job.backoff.type, delayMs: parseDuration(job.backoff.delay) } : void 0,
       delayMs: options.delay === void 0 ? void 0 : parseDuration(options.delay),
-      priority: options.priority
+      priority: options.priority,
+      // Per-job overrides the queuePlugin default; undefined leaves the driver default.
+      removeOnComplete: resolveRetention(job.removeOnComplete ?? this.defaultRemoveOnComplete),
+      removeOnFail: resolveRetention(job.removeOnFail ?? this.defaultRemoveOnFail)
     };
     this.assertSupported(job.name, addOptions);
     await this.driver.add(job.queue, job.name, envelope, addOptions);
@@ -287,10 +312,11 @@ function queuePlugin(options = {}) {
     register({ container }) {
       container.singleton(QUEUE, () => {
         const driver = options.driver ?? (options.connection ? new BullmqQueueDriver({ connection: options.connection }) : new SyncQueueDriver());
-        const manager = new QueueManager(
-          driver,
-          options.onUnsupported !== void 0 ? { onUnsupported: options.onUnsupported } : {}
-        );
+        const manager = new QueueManager(driver, {
+          ...options.onUnsupported !== void 0 ? { onUnsupported: options.onUnsupported } : {},
+          ...options.removeOnComplete !== void 0 ? { removeOnComplete: options.removeOnComplete } : {},
+          ...options.removeOnFail !== void 0 ? { removeOnFail: options.removeOnFail } : {}
+        });
         for (const job of options.jobs ?? []) manager.register(job);
         return manager;
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/queue",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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",