@boringnode/queue 0.2.0 → 0.3.1

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-RIXMQXYJ.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,6 +198,144 @@ 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 {
@@ -461,6 +623,48 @@ var Job = class {
     }
     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;
+  }
   /**
    * Create a schedule for this job.
    *
@@ -494,7 +698,7 @@ var Job = class {
 };
 
 // src/worker.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { setTimeout } from "timers/promises";
 
 // src/job_pool.ts
@@ -600,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);
@@ -787,23 +991,24 @@ var Worker = class {
     const startTime = performance.now();
     debug_default("worker %s: executing job %s (%s)", this.#id, job.id, job.name);
     const { instance, options, timeout, context, payload } = await this.#initJob(job, queue);
+    const retention = QueueManager.getMergedJobOptions(queue, options);
     try {
       await this.#executeWithTimeout(instance, payload, context, timeout);
-      await this.#adapter.completeJob(job.id, queue);
+      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;
       }
@@ -814,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;
@@ -848,7 +1053,8 @@ var Worker = class {
       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;
     }
   }
@@ -946,7 +1152,7 @@ var Worker = class {
       const JobClass = Locator.get(schedule.name);
       const queue = JobClass?.options?.queue ?? "default";
       await this.#adapter.pushOn(queue, {
-        id: randomUUID2(),
+        id: randomUUID3(),
         name: schedule.name,
         payload: schedule.payload,
         attempts: 0,
@@ -1223,6 +1429,7 @@ function customBackoff(config) {
 }
 export {
   Job,
+  JobBatchDispatcher,
   Locator,
   QueueManager,
   Schedule,