@boringnode/queue 0.1.0 → 0.3.0

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, d as JobFactory, e as Job, f as JobClass, b as ScheduleData, g as ScheduleStatus, c as ScheduleListOptions } from './index-2Ng_OpVK.js';
-export { h as ScheduleBuilder, i as customBackoff, j as exponentialBackoff, k as fixedBackoff, l as linearBackoff } from './index-2Ng_OpVK.js';
+import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, f as JobFactory, g as JobOptions, h as Job, i as JobClass, d as ScheduleData, j as ScheduleStatus, e as ScheduleListOptions } from './index-PDfE6h8d.js';
+export { m as AdapterFactory, D as DispatchManyResult, l as JobBatchDispatcher, k as ScheduleBuilder, n as customBackoff, p as exponentialBackoff, q as fixedBackoff, o as linearBackoff } from './index-PDfE6h8d.js';
 import * as _poppinss_utils from '@poppinss/utils';
 
 /**
@@ -232,6 +232,10 @@ declare class QueueManagerSingleton {
      * @returns The job factory function, or undefined if not configured
      */
     getJobFactory(): JobFactory | undefined;
+    /**
+     * Get the merged job options for a job (priority: job > queue > global).
+     */
+    getMergedJobOptions(queue: string, jobOptions?: JobOptions): JobOptions;
     /**
      * Clean up all adapter instances and reset state.
      *
@@ -368,7 +372,7 @@ declare class Schedule {
     #private;
     constructor(data: ScheduleData);
     get id(): string;
-    get jobName(): string;
+    get name(): string;
     get payload(): any;
     get cronExpression(): string | null;
     get everyMs(): number | null;
@@ -449,4 +453,4 @@ declare namespace exceptions {
   export { exceptions_E_ADAPTER_INIT_ERROR as E_ADAPTER_INIT_ERROR, exceptions_E_CONFIGURATION_ERROR as E_CONFIGURATION_ERROR, exceptions_E_INVALID_BASE_DELAY as E_INVALID_BASE_DELAY, exceptions_E_INVALID_CRON_EXPRESSION as E_INVALID_CRON_EXPRESSION, exceptions_E_INVALID_DURATION_EXPRESSION as E_INVALID_DURATION_EXPRESSION, exceptions_E_INVALID_MAX_DELAY as E_INVALID_MAX_DELAY, exceptions_E_INVALID_MULTIPLIER as E_INVALID_MULTIPLIER, exceptions_E_INVALID_SCHEDULE_CONFIG as E_INVALID_SCHEDULE_CONFIG, exceptions_E_JOB_MAX_ATTEMPTS_REACHED as E_JOB_MAX_ATTEMPTS_REACHED, exceptions_E_JOB_NOT_FOUND as E_JOB_NOT_FOUND, exceptions_E_JOB_TIMEOUT as E_JOB_TIMEOUT, exceptions_E_NO_JOBS_FOUND as E_NO_JOBS_FOUND, exceptions_E_QUEUE_NOT_INITIALIZED as E_QUEUE_NOT_INITIALIZED };
 }
 
-export { Job, Locator, QueueManager, Schedule, Worker, exceptions as errors };
+export { Job, JobFactory, Locator, QueueManager, Schedule, Worker, exceptions as errors };

package/build/index.js

@@ -1,11 +1,11 @@
 import {
   parse
-} from "./chunk-NPQKBCCY.js";
+} from "./chunk-PBGPIFI5.js";
 import {
   Locator,
   QueueManager,
   debug_default
-} from "./chunk-US7THLSZ.js";
+} from "./chunk-LI2ZMCNO.js";
 import {
   DEFAULT_ERROR_RETRY_DELAY,
   DEFAULT_IDLE_DELAY,
@@ -31,6 +31,7 @@ var JobDispatcher = class {
   #adapter;
   #delay;
   #priority;
+  #groupId;
   /**
    * Create a new job dispatcher.
    *
@@ -100,6 +101,28 @@ var JobDispatcher = class {
     this.#priority = priority;
     return this;
   }
+  /**
+   * Assign this job to a group.
+   *
+   * Jobs with the same groupId can be filtered and displayed together
+   * in monitoring UIs. Useful for batch operations like newsletters
+   * or bulk exports.
+   *
+   * @param groupId - Group identifier
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // Group newsletter jobs together
+   * await SendEmailJob.dispatch({ to: 'user@example.com' })
+   *   .group('newsletter-jan-2025')
+   *   .run()
+   * ```
+   */
+  group(groupId) {
+    this.#groupId = groupId;
+    return this;
+  }
   /**
    * Use a specific adapter for this job.
    *
@@ -139,7 +162,8 @@ var JobDispatcher = class {
       name: this.#name,
       payload: this.#payload,
       attempts: 0,
-      priority: this.#priority
+      priority: this.#priority,
+      groupId: this.#groupId
     };
     if (this.#delay) {
       const parsedDelay = parse(this.#delay);
@@ -174,10 +198,148 @@ var JobDispatcher = class {
   }
 };
 
+// src/job_batch_dispatcher.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var JobBatchDispatcher = class {
+  #name;
+  #payloads;
+  #queue = "default";
+  #adapter;
+  #priority;
+  #groupId;
+  /**
+   * Create a new batch job dispatcher.
+   *
+   * @param name - The job class name (used to locate the class at runtime)
+   * @param payloads - Array of data to pass to each job
+   */
+  constructor(name, payloads) {
+    this.#name = name;
+    this.#payloads = payloads;
+  }
+  /**
+   * Set the target queue for all jobs.
+   *
+   * @param queue - Queue name (default: 'default')
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await SendEmailJob.dispatchMany(payloads).toQueue('emails')
+   * ```
+   */
+  toQueue(queue) {
+    this.#queue = queue;
+    return this;
+  }
+  /**
+   * Set the priority for all jobs.
+   *
+   * Lower numbers = higher priority. Jobs with lower priority values
+   * are processed before jobs with higher values.
+   *
+   * @param priority - Priority level (1-10, default: 5)
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await UrgentJob.dispatchMany(payloads).priority(1)
+   * ```
+   */
+  priority(priority) {
+    this.#priority = priority;
+    return this;
+  }
+  /**
+   * Assign all jobs to a group.
+   *
+   * Jobs with the same groupId can be filtered and displayed together
+   * in monitoring UIs. Useful for batch operations like newsletters
+   * or bulk exports.
+   *
+   * @param groupId - Group identifier
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await SendEmailJob.dispatchMany(recipients)
+   *   .group('newsletter-jan-2025')
+   *   .run()
+   * ```
+   */
+  group(groupId) {
+    this.#groupId = groupId;
+    return this;
+  }
+  /**
+   * Use a specific adapter for these jobs.
+   *
+   * @param adapter - Adapter name or factory function
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await Job.dispatchMany(payloads).with('redis')
+   * ```
+   */
+  with(adapter) {
+    this.#adapter = adapter;
+    return this;
+  }
+  /**
+   * Dispatch all jobs to the queue.
+   *
+   * @returns A DispatchManyResult containing all jobIds
+   *
+   * @example
+   * ```typescript
+   * const { jobIds } = await SendEmailJob.dispatchMany(payloads).run()
+   * console.log(`Dispatched ${jobIds.length} jobs`)
+   * ```
+   */
+  async run() {
+    debug_default("dispatching %d jobs of type %s", this.#payloads.length, this.#name);
+    const adapter = this.#getAdapterInstance();
+    const jobs = this.#payloads.map((payload) => ({
+      id: randomUUID2(),
+      name: this.#name,
+      payload,
+      attempts: 0,
+      priority: this.#priority,
+      groupId: this.#groupId
+    }));
+    await adapter.pushManyOn(this.#queue, jobs);
+    return {
+      jobIds: jobs.map((job) => job.id)
+    };
+  }
+  /**
+   * Thenable implementation for auto-dispatch when awaited.
+   *
+   * Allows `await Job.dispatchMany(payloads)` without explicit `.run()`.
+   *
+   * @param onFulfilled - Success callback
+   * @param onRejected - Error callback
+   * @returns Promise resolving to the DispatchManyResult
+   */
+  then(onFulfilled, onRejected) {
+    return this.run().then(onFulfilled, onRejected);
+  }
+  #getAdapterInstance() {
+    if (!this.#adapter) {
+      return QueueManager.use();
+    }
+    if (typeof this.#adapter === "string") {
+      return QueueManager.use(this.#adapter);
+    }
+    return this.#adapter();
+  }
+};
+
 // src/schedule_builder.ts
 import { CronExpressionParser } from "cron-parser";
 var ScheduleBuilder = class {
-  #jobName;
+  #name;
   #payload;
   #id;
   #cronExpression;
@@ -186,8 +348,8 @@ var ScheduleBuilder = class {
   #from;
   #to;
   #limit;
-  constructor(jobName, payload) {
-    this.#jobName = jobName;
+  constructor(name, payload) {
+    this.#name = name;
     this.#payload = payload;
   }
   /**
@@ -275,8 +437,8 @@ var ScheduleBuilder = class {
       }
     }
     const config = {
-      id: this.#id ?? this.#jobName,
-      jobName: this.#jobName,
+      id: this.#id ?? this.#name,
+      name: this.#name,
       payload: this.#payload,
       cronExpression: this.#cronExpression,
       everyMs: this.#everyMs,
@@ -331,9 +493,39 @@ var ScheduleBuilder = class {
 var Job = class {
   #payload;
   #context;
-  /** Static options for this job class (queue, retries, timeout, etc.) */
+  #signal;
+  /**
+   * Static options for this job class.
+   *
+   * Override this property in subclasses to configure job behavior
+   * such as queue name, retry policy, timeout, and more.
+   *
+   * @example
+   * ```typescript
+   * class SendEmailJob extends Job<SendEmailPayload> {
+   *   static options = {
+   *     queue: 'emails',
+   *     maxRetries: 3,
+   *     timeout: '30s',
+   *   }
+   * }
+   * ```
+   */
   static options = {};
-  /** The payload data passed to this job instance */
+  /**
+   * The payload data passed to this job instance.
+   *
+   * Contains the data provided when the job was dispatched.
+   * Available after the job has been hydrated by the worker.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   const { to, subject, body } = this.payload
+   *   await sendEmail(to, subject, body)
+   * }
+   * ```
+   */
   get payload() {
     return this.#payload;
   }
@@ -357,14 +549,41 @@ var Job = class {
     return this.#context;
   }
   /**
-   * Create a new job instance.
+   * The abort signal for timeout handling.
+   *
+   * Check `signal.aborted` in long-running operations to handle timeouts gracefully.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   for (const item of this.payload.items) {
+   *     if (this.signal?.aborted) {
+   *       throw new Error('Job timed out')
+   *     }
+   *     await processItem(item)
+   *   }
+   * }
+   * ```
+   */
+  get signal() {
+    return this.#signal;
+  }
+  /**
+   * Hydrate the job with payload, context, and optional abort signal.
+   *
+   * This method is called by the worker after instantiation to provide
+   * the job's runtime data. It should not be called directly by user code.
    *
    * @param payload - The data to be processed by this job
-   * @param context - The job execution context (provided by the worker)
+   * @param context - The job execution context
+   * @param signal - Optional abort signal for timeout handling
+   *
+   * @internal
    */
-  constructor(payload, context) {
+  $hydrate(payload, context, signal) {
     this.#payload = payload;
     this.#context = Object.freeze(context);
+    this.#signal = signal;
   }
   /**
    * Dispatch this job to the queue.
@@ -390,18 +609,59 @@ var Job = class {
    * ```
    */
   static dispatch(payload) {
-    const dispatcher = new JobDispatcher(
-      this.jobName,
-      payload
-    );
-    if (this.options.queue) {
-      dispatcher.toQueue(this.options.queue);
+    const options = this.options || {};
+    const jobName = options.name || this.name;
+    const dispatcher = new JobDispatcher(jobName, payload);
+    if (options.queue) {
+      dispatcher.toQueue(options.queue);
     }
-    if (this.options.adapter) {
-      dispatcher.with(this.options.adapter);
+    if (options.adapter) {
+      dispatcher.with(options.adapter);
     }
-    if (this.options.priority !== void 0) {
-      dispatcher.priority(this.options.priority);
+    if (options.priority !== void 0) {
+      dispatcher.priority(options.priority);
+    }
+    return dispatcher;
+  }
+  /**
+   * Dispatch multiple jobs to the queue in a single batch.
+   *
+   * Returns a JobBatchDispatcher for fluent configuration before dispatching.
+   * The jobs are not actually dispatched until `.run()` is called or the
+   * dispatcher is awaited.
+   *
+   * This is more efficient than calling `dispatch()` multiple times as it
+   * uses batched operations (e.g., Redis pipeline, SQL batch insert).
+   *
+   * @param payloads - Array of data to pass to each job
+   * @returns A JobBatchDispatcher for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * // Batch dispatch for newsletter
+   * const { jobIds } = await SendEmailJob.dispatchMany([
+   *   { to: 'user1@example.com', subject: 'Newsletter' },
+   *   { to: 'user2@example.com', subject: 'Newsletter' },
+   * ])
+   *   .group('newsletter-jan-2025')
+   *   .toQueue('emails')
+   *   .run()
+   *
+   * console.log(`Dispatched ${jobIds.length} jobs`)
+   * ```
+   */
+  static dispatchMany(payloads) {
+    const options = this.options || {};
+    const jobName = options.name || this.name;
+    const dispatcher = new JobBatchDispatcher(jobName, payloads);
+    if (options.queue) {
+      dispatcher.toQueue(options.queue);
+    }
+    if (options.adapter) {
+      dispatcher.with(options.adapter);
+    }
+    if (options.priority !== void 0) {
+      dispatcher.priority(options.priority);
     }
     return dispatcher;
   }
@@ -431,12 +691,14 @@ var Job = class {
    * ```
    */
   static schedule(payload) {
-    return new ScheduleBuilder(this.jobName, payload);
+    const options = this.options || {};
+    const jobName = options.name || this.name;
+    return new ScheduleBuilder(jobName, payload);
   }
 };
 
 // src/worker.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { setTimeout } from "timers/promises";
 
 // src/job_pool.ts
@@ -542,7 +804,7 @@ var Worker = class {
    */
   constructor(config) {
     this.#config = config;
-    this.#id = randomUUID2();
+    this.#id = randomUUID3();
     this.#idleDelay = parse(config.worker?.idleDelay ?? DEFAULT_IDLE_DELAY);
     this.#stalledInterval = parse(config.worker?.stalledInterval ?? DEFAULT_STALLED_INTERVAL);
     this.#stalledThreshold = parse(config.worker?.stalledThreshold ?? DEFAULT_STALLED_THRESHOLD);
@@ -728,24 +990,25 @@ var Worker = class {
   async #execute(job, queue) {
     const startTime = performance.now();
     debug_default("worker %s: executing job %s (%s)", this.#id, job.id, job.name);
-    const { instance, options, timeout } = await this.#initJob(job, queue);
+    const { instance, options, timeout, context, payload } = await this.#initJob(job, queue);
+    const retention = QueueManager.getMergedJobOptions(queue, options);
     try {
-      await this.#executeWithTimeout(instance, timeout);
-      await this.#adapter.completeJob(job.id, queue);
+      await this.#executeWithTimeout(instance, payload, context, timeout);
+      await this.#adapter.completeJob(job.id, queue, retention.removeOnComplete);
       const duration = (performance.now() - startTime).toFixed(2);
       debug_default("worker %s: successfully executed job %s in %dms", this.#id, job.id, duration);
     } catch (e) {
       const isTimeout = e instanceof E_JOB_TIMEOUT;
       if (isTimeout && options.failOnTimeout) {
         debug_default("worker %s: job %s timed out and failOnTimeout is set", this.#id, job.id);
-        await this.#adapter.failJob(job.id, queue, e);
+        await this.#adapter.failJob(job.id, queue, e, retention.removeOnFail);
         await instance.failed?.(e);
         return;
       }
       const mergedConfig = QueueManager.getMergedRetryConfig(queue, options.retry);
       if (typeof mergedConfig.maxRetries === "undefined" || mergedConfig.maxRetries <= 0) {
         debug_default("worker %s: job %s has no retries configured, marking as failed", this.#id, job.id);
-        await this.#adapter.failJob(job.id, queue, e);
+        await this.#adapter.failJob(job.id, queue, e, retention.removeOnFail);
         await instance.failed?.(e);
         return;
       }
@@ -756,7 +1019,7 @@ var Worker = class {
           job.id,
           mergedConfig.maxRetries
         );
-        await this.#adapter.failJob(job.id, queue, e);
+        await this.#adapter.failJob(job.id, queue, e, retention.removeOnFail);
         const exception = new E_JOB_MAX_ATTEMPTS_REACHED([job.name]);
         await instance.failed?.(exception);
         return;
@@ -774,7 +1037,7 @@ var Worker = class {
   async #initJob(job, queue) {
     try {
       const JobClass = Locator.getOrThrow(job.name);
-      const context = Object.freeze({
+      const context = {
         jobId: job.id,
         name: job.name,
         attempt: job.attempts + 1,
@@ -782,15 +1045,16 @@ var Worker = class {
         priority: job.priority ?? DEFAULT_PRIORITY,
         acquiredAt: new Date(job.acquiredAt),
         stalledCount: job.stalledCount ?? 0
-      });
+      };
       const jobFactory = QueueManager.getJobFactory();
-      const instance = jobFactory ? await jobFactory(JobClass, job.payload, context) : new JobClass(job.payload, context);
+      const instance = jobFactory ? await jobFactory(JobClass) : new JobClass();
       const options = JobClass.options || {};
       const timeout = this.#getJobTimeout(options);
-      return { instance, options, timeout };
+      return { instance, options, timeout, context, payload: job.payload };
     } catch (error) {
       debug_default("worker %s: failed to initialize job %s (%s)", this.#id, job.id, job.name);
-      await this.#adapter.failJob(job.id, queue, error);
+      const retention = QueueManager.getMergedJobOptions(queue);
+      await this.#adapter.failJob(job.id, queue, error, retention.removeOnFail);
       throw error;
     }
   }
@@ -803,17 +1067,19 @@ var Worker = class {
     }
     return void 0;
   }
-  async #executeWithTimeout(instance, timeout) {
+  async #executeWithTimeout(instance, payload, context, timeout) {
     if (!timeout) {
+      instance.$hydrate(payload, context);
       return instance.execute();
     }
     const signal = AbortSignal.timeout(timeout);
+    instance.$hydrate(payload, context, signal);
     const abortPromise = new Promise((_, reject) => {
       signal.addEventListener("abort", () => {
         reject(new E_JOB_TIMEOUT([instance.constructor.name, timeout]));
       });
     });
-    await Promise.race([instance.execute(signal), abortPromise]);
+    await Promise.race([instance.execute(), abortPromise]);
   }
   async #acquireNextJob(queues) {
     for (const queue of queues) {
@@ -879,15 +1145,15 @@ var Worker = class {
       debug_default(
         "worker %s: dispatching scheduled job %s (schedule: %s, runCount: %d)",
         this.#id,
-        schedule.jobName,
+        schedule.name,
         schedule.id,
         schedule.runCount + 1
       );
-      const JobClass = Locator.get(schedule.jobName);
+      const JobClass = Locator.get(schedule.name);
       const queue = JobClass?.options?.queue ?? "default";
       await this.#adapter.pushOn(queue, {
-        id: randomUUID2(),
-        name: schedule.jobName,
+        id: randomUUID3(),
+        name: schedule.name,
         payload: schedule.payload,
         attempts: 0,
         priority: JobClass?.options?.priority
@@ -905,8 +1171,8 @@ var Schedule = class _Schedule {
   get id() {
     return this.#data.id;
   }
-  get jobName() {
-    return this.#data.jobName;
+  get name() {
+    return this.#data.name;
   }
   get payload() {
     return this.#data.payload;
@@ -1003,7 +1269,7 @@ var Schedule = class _Schedule {
       return;
     }
     const adapter = QueueManager.use();
-    const dispatcher = new JobDispatcher(this.#data.jobName, this.#data.payload);
+    const dispatcher = new JobDispatcher(this.#data.name, this.#data.payload);
     await dispatcher.run();
     const now = /* @__PURE__ */ new Date();
     const newRunCount = this.#data.runCount + 1;
@@ -1163,6 +1429,7 @@ function customBackoff(config) {
 }
 export {
   Job,
+  JobBatchDispatcher,
   Locator,
   QueueManager,
   Schedule,