@boringnode/queue 0.3.1 → 0.3.3

package/build/index.js

@@ -1,11 +1,12 @@
 import {
-  parse
-} from "./chunk-PBGPIFI5.js";
-import {
+  Job,
+  JobBatchDispatcher,
+  JobDispatcher,
   Locator,
   QueueManager,
+  ScheduleBuilder,
   debug_default
-} from "./chunk-LI2ZMCNO.js";
+} from "./chunk-H6WOFLPJ.js";
 import {
   DEFAULT_ERROR_RETRY_DELAY,
   DEFAULT_IDLE_DELAY,
@@ -13,692 +14,16 @@ import {
   DEFAULT_STALLED_INTERVAL,
   DEFAULT_STALLED_THRESHOLD,
   E_INVALID_BASE_DELAY,
-  E_INVALID_CRON_EXPRESSION,
   E_INVALID_MAX_DELAY,
   E_INVALID_MULTIPLIER,
-  E_INVALID_SCHEDULE_CONFIG,
   E_JOB_MAX_ATTEMPTS_REACHED,
   E_JOB_TIMEOUT,
-  exceptions_exports
-} from "./chunk-SMOKFZ46.js";
-
-// src/job_dispatcher.ts
-import { randomUUID } from "crypto";
-var JobDispatcher = class {
-  #name;
-  #payload;
-  #queue = "default";
-  #adapter;
-  #delay;
-  #priority;
-  #groupId;
-  /**
-   * Create a new job dispatcher.
-   *
-   * @param name - The job class name (used to locate the class at runtime)
-   * @param payload - The data to pass to the job
-   */
-  constructor(name, payload) {
-    this.#name = name;
-    this.#payload = payload;
-  }
-  /**
-   * Set the target queue for this job.
-   *
-   * @param queue - Queue name (default: 'default')
-   * @returns This dispatcher for chaining
-   *
-   * @example
-   * ```typescript
-   * await SendEmailJob.dispatch(payload).toQueue('emails')
-   * ```
-   */
-  toQueue(queue) {
-    this.#queue = queue;
-    return this;
-  }
-  /**
-   * Delay the job execution.
-   *
-   * The job will be stored in a delayed state and moved to pending
-   * after the delay expires.
-   *
-   * @param delay - Delay as milliseconds or duration string ('5s', '1h', '7d')
-   * @returns This dispatcher for chaining
-   *
-   * @example
-   * ```typescript
-   * // Send reminder in 24 hours
-   * await ReminderJob.dispatch(payload).in('24h')
-   *
-   * // Process in 5 minutes
-   * await CleanupJob.dispatch(payload).in('5m')
-   * ```
-   */
-  in(delay) {
-    this.#delay = delay;
-    return this;
-  }
-  /**
-   * Set the job priority.
-   *
-   * 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
-   * // High priority job
-   * await UrgentJob.dispatch(payload).priority(1)
-   *
-   * // Low priority job
-   * await BackgroundJob.dispatch(payload).priority(10)
-   * ```
-   */
-  priority(priority) {
-    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.
-   *
-   * @param adapter - Adapter name or factory function
-   * @returns This dispatcher for chaining
-   *
-   * @example
-   * ```typescript
-   * // Use named adapter
-   * await Job.dispatch(payload).with('redis')
-   *
-   * // Use custom adapter instance
-   * await Job.dispatch(payload).with(() => new CustomAdapter())
-   * ```
-   */
-  with(adapter) {
-    this.#adapter = adapter;
-    return this;
-  }
-  /**
-   * Dispatch the job to the queue.
-   *
-   * @returns A DispatchResult containing the jobId
-   *
-   * @example
-   * ```typescript
-   * const { jobId } = await SendEmailJob.dispatch(payload).run()
-   * console.log(`Dispatched job: ${jobId}`)
-   * ```
-   */
-  async run() {
-    const id = randomUUID();
-    debug_default("dispatching job %s with id %s using payload %s", this.#name, id, this.#payload);
-    const adapter = this.#getAdapterInstance();
-    const payload = {
-      id,
-      name: this.#name,
-      payload: this.#payload,
-      attempts: 0,
-      priority: this.#priority,
-      groupId: this.#groupId
-    };
-    if (this.#delay) {
-      const parsedDelay = parse(this.#delay);
-      await adapter.pushLaterOn(this.#queue, payload, parsedDelay);
-    } else {
-      await adapter.pushOn(this.#queue, payload);
-    }
-    return {
-      jobId: id
-    };
-  }
-  /**
-   * Thenable implementation for auto-dispatch when awaited.
-   *
-   * Allows `await Job.dispatch(payload)` without explicit `.run()`.
-   *
-   * @param onFulfilled - Success callback
-   * @param onRejected - Error callback
-   * @returns Promise resolving to the DispatchResult
-   */
-  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/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 {
-  #name;
-  #payload;
-  #id;
-  #cronExpression;
-  #everyMs;
-  #timezone = "UTC";
-  #from;
-  #to;
-  #limit;
-  constructor(name, payload) {
-    this.#name = name;
-    this.#payload = payload;
-  }
-  /**
-   * Set a custom schedule ID.
-   * If not specified, defaults to the job name.
-   * If a schedule with this ID exists, it will be updated (upsert).
-   */
-  id(scheduleId) {
-    this.#id = scheduleId;
-    return this;
-  }
-  /**
-   * Set a cron expression for the schedule.
-   * Mutually exclusive with `every()`.
-   */
-  cron(expression) {
-    this.#cronExpression = expression;
-    return this;
-  }
-  /**
-   * Set a repeating interval for the schedule.
-   * Mutually exclusive with `cron()`.
-   */
-  every(interval) {
-    this.#everyMs = parse(interval);
-    return this;
-  }
-  /**
-   * Set the timezone for cron evaluation.
-   * @default 'UTC'
-   */
-  timezone(tz) {
-    this.#timezone = tz;
-    return this;
-  }
-  /**
-   * Set the start boundary for the schedule.
-   * No jobs will be dispatched before this date.
-   */
-  from(date) {
-    this.#from = date;
-    return this;
-  }
-  /**
-   * Set the end boundary for the schedule.
-   * No jobs will be dispatched after this date.
-   */
-  to(date) {
-    this.#to = date;
-    return this;
-  }
-  /**
-   * Set both start and end boundaries for the schedule.
-   * Shorthand for `.from(start).to(end)`.
-   */
-  between(from, to) {
-    return this.from(from).to(to);
-  }
-  /**
-   * Set the maximum number of runs for this schedule.
-   */
-  limit(maxRuns) {
-    this.#limit = maxRuns;
-    return this;
-  }
-  /**
-   * Create the schedule and return the schedule ID.
-   */
-  async run() {
-    if (!this.#cronExpression && !this.#everyMs) {
-      throw new E_INVALID_SCHEDULE_CONFIG([
-        "Schedule must have either a cron expression or an interval"
-      ]);
-    }
-    if (this.#cronExpression && this.#everyMs) {
-      throw new E_INVALID_SCHEDULE_CONFIG([
-        "Schedule cannot have both a cron expression and an interval"
-      ]);
-    }
-    if (this.#cronExpression) {
-      try {
-        CronExpressionParser.parse(this.#cronExpression, { tz: this.#timezone });
-      } catch (error) {
-        throw new E_INVALID_CRON_EXPRESSION([this.#cronExpression, error.message]);
-      }
-    }
-    const config = {
-      id: this.#id ?? this.#name,
-      name: this.#name,
-      payload: this.#payload,
-      cronExpression: this.#cronExpression,
-      everyMs: this.#everyMs,
-      timezone: this.#timezone,
-      from: this.#from,
-      to: this.#to,
-      limit: this.#limit
-    };
-    const adapter = QueueManager.use();
-    const scheduleId = await adapter.createSchedule(config);
-    const nextRunAt = this.#calculateNextRunAt();
-    await adapter.updateSchedule(scheduleId, { nextRunAt });
-    return { scheduleId };
-  }
-  /**
-   * Calculate the next run time based on cron or interval.
-   */
-  #calculateNextRunAt() {
-    const now = /* @__PURE__ */ new Date();
-    let nextRun;
-    if (this.#cronExpression) {
-      const cron = CronExpressionParser.parse(this.#cronExpression, {
-        currentDate: now,
-        tz: this.#timezone
-      });
-      nextRun = cron.next().toDate();
-    } else {
-      nextRun = new Date(now.getTime() + this.#everyMs);
-    }
-    if (this.#from && nextRun < this.#from) {
-      if (this.#cronExpression) {
-        const cron = CronExpressionParser.parse(this.#cronExpression, {
-          currentDate: this.#from,
-          tz: this.#timezone
-        });
-        nextRun = cron.next().toDate();
-      } else {
-        nextRun = this.#from;
-      }
-    }
-    return nextRun;
-  }
-  /**
-   * Implement PromiseLike to allow `await builder.every('5m')` syntax.
-   */
-  then(onfulfilled, onrejected) {
-    return this.run().then(onfulfilled, onrejected);
-  }
-};
-
-// src/job.ts
-var Job = class {
-  #payload;
-  #context;
-  #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.
-   *
-   * 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;
-  }
-  /**
-   * Context information for the current job execution.
-   *
-   * Provides metadata such as job ID, current attempt number,
-   * queue name, priority, and timing information.
-   *
-   * @example
-   * ```typescript
-   * async execute() {
-   *   if (this.context.attempt > 1) {
-   *     console.log(`Retry attempt ${this.context.attempt}`)
-   *   }
-   *   console.log(`Processing job ${this.context.jobId} on queue ${this.context.queue}`)
-   * }
-   * ```
-   */
-  get context() {
-    return this.#context;
-  }
-  /**
-   * 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
-   * @param signal - Optional abort signal for timeout handling
-   *
-   * @internal
-   */
-  $hydrate(payload, context, signal) {
-    this.#payload = payload;
-    this.#context = Object.freeze(context);
-    this.#signal = signal;
-  }
-  /**
-   * Dispatch this job to the queue.
-   *
-   * Returns a JobDispatcher for fluent configuration before dispatching.
-   * The job is not actually dispatched until `.run()` is called or the
-   * dispatcher is awaited.
-   *
-   * @param payload - The data to pass to the job
-   * @returns A JobDispatcher for fluent configuration
-   *
-   * @example
-   * ```typescript
-   * // Simple dispatch
-   * await SendEmailJob.dispatch({ to: 'user@example.com', subject: 'Hello' })
-   *
-   * // With options
-   * await SendEmailJob.dispatch({ to: 'user@example.com' })
-   *   .toQueue('high-priority')
-   *   .priority(1)
-   *   .in('5m')
-   *   .run()
-   * ```
-   */
-  static dispatch(payload) {
-    const options = this.options || {};
-    const jobName = options.name || this.name;
-    const dispatcher = new JobDispatcher(jobName, payload);
-    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;
-  }
-  /**
-   * 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.
-   *
-   * Returns a ScheduleBuilder for fluent configuration before creating the schedule.
-   * The schedule is not actually created until `.run()` is called or the
-   * builder is awaited.
-   *
-   * @param payload - The data to pass to the job on each run
-   * @returns A ScheduleBuilder for fluent configuration
-   *
-   * @example
-   * ```typescript
-   * // Cron schedule
-   * await CleanupJob.schedule({ days: 30 })
-   *   .id('cleanup-daily')
-   *   .cron('0 0 * * *')
-   *   .timezone('Europe/Paris')
-   *   .run()
-   *
-   * // Interval schedule
-   * await SyncJob.schedule({ source: 'api' })
-   *   .every('5m')
-   *   .run()
-   * ```
-   */
-  static schedule(payload) {
-    const options = this.options || {};
-    const jobName = options.name || this.name;
-    return new ScheduleBuilder(jobName, payload);
-  }
-};
+  exceptions_exports,
+  parse
+} from "./chunk-3BIR4IQD.js";
 
 // src/worker.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID } from "crypto";
 import { setTimeout } from "timers/promises";
 
 // src/job_pool.ts
@@ -804,7 +129,7 @@ var Worker = class {
    */
   constructor(config) {
     this.#config = config;
-    this.#id = randomUUID3();
+    this.#id = randomUUID();
     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);
@@ -1020,7 +345,7 @@ var Worker = class {
           mergedConfig.maxRetries
         );
         await this.#adapter.failJob(job.id, queue, e, retention.removeOnFail);
-        const exception = new E_JOB_MAX_ATTEMPTS_REACHED([job.name]);
+        const exception = new E_JOB_MAX_ATTEMPTS_REACHED([job.name], { cause: e });
         await instance.failed?.(exception);
         return;
       }
@@ -1152,7 +477,7 @@ var Worker = class {
       const JobClass = Locator.get(schedule.name);
       const queue = JobClass?.options?.queue ?? "default";
       await this.#adapter.pushOn(queue, {
-        id: randomUUID3(),
+        id: randomUUID(),
         name: schedule.name,
         payload: schedule.payload,
         attempts: 0,