@boringnode/queue 0.0.1-alpha.4 → 0.1.0

package/build/index.js

@@ -1,11 +1,11 @@
 import {
   parse
-} from "./chunk-5PDDRF5O.js";
+} from "./chunk-NPQKBCCY.js";
 import {
   Locator,
   QueueManager,
   debug_default
-} from "./chunk-CD45GT6E.js";
+} from "./chunk-US7THLSZ.js";
 import {
   DEFAULT_ERROR_RETRY_DELAY,
   DEFAULT_IDLE_DELAY,
@@ -13,12 +13,14 @@ 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-HMGNQSSG.js";
+} from "./chunk-SMOKFZ46.js";
 
 // src/job_dispatcher.ts
 import { randomUUID } from "crypto";
@@ -120,11 +122,11 @@ var JobDispatcher = class {
   /**
    * Dispatch the job to the queue.
    *
-   * @returns The unique job ID
+   * @returns A DispatchResult containing the jobId
    *
    * @example
    * ```typescript
-   * const jobId = await SendEmailJob.dispatch(payload).run()
+   * const { jobId } = await SendEmailJob.dispatch(payload).run()
    * console.log(`Dispatched job: ${jobId}`)
    * ```
    */
@@ -145,7 +147,9 @@ var JobDispatcher = class {
     } else {
       await adapter.pushOn(this.#queue, payload);
     }
-    return id;
+    return {
+      jobId: id
+    };
   }
   /**
    * Thenable implementation for auto-dispatch when awaited.
@@ -154,7 +158,7 @@ var JobDispatcher = class {
    *
    * @param onFulfilled - Success callback
    * @param onRejected - Error callback
-   * @returns Promise resolving to the job ID
+   * @returns Promise resolving to the DispatchResult
    */
   then(onFulfilled, onRejected) {
     return this.run().then(onFulfilled, onRejected);
@@ -170,6 +174,159 @@ var JobDispatcher = class {
   }
 };
 
+// src/schedule_builder.ts
+import { CronExpressionParser } from "cron-parser";
+var ScheduleBuilder = class {
+  #jobName;
+  #payload;
+  #id;
+  #cronExpression;
+  #everyMs;
+  #timezone = "UTC";
+  #from;
+  #to;
+  #limit;
+  constructor(jobName, payload) {
+    this.#jobName = jobName;
+    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.#jobName,
+      jobName: this.#jobName,
+      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;
@@ -248,6 +405,34 @@ var Job = class {
     }
     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) {
+    return new ScheduleBuilder(this.jobName, payload);
+  }
 };
 
 // src/worker.ts
@@ -510,6 +695,7 @@ var Worker = class {
     while (this.#running) {
       try {
         await this.#checkStalledJobs(queues);
+        await this.#dispatchDueSchedules();
         yield* this.#fillPool(queues);
         if (this.#pool.isEmpty()) {
           yield { type: "idle", suggestedDelay: this.#idleDelay };
@@ -678,6 +864,156 @@ var Worker = class {
       this.#shutdownHandler = void 0;
     }
   }
+  /**
+   * Dispatch any due scheduled jobs.
+   *
+   * Claims due schedules from the adapter and dispatches the corresponding
+   * jobs to their configured queues.
+   */
+  async #dispatchDueSchedules() {
+    while (true) {
+      const schedule = await this.#adapter.claimDueSchedule();
+      if (!schedule) {
+        break;
+      }
+      debug_default(
+        "worker %s: dispatching scheduled job %s (schedule: %s, runCount: %d)",
+        this.#id,
+        schedule.jobName,
+        schedule.id,
+        schedule.runCount + 1
+      );
+      const JobClass = Locator.get(schedule.jobName);
+      const queue = JobClass?.options?.queue ?? "default";
+      await this.#adapter.pushOn(queue, {
+        id: randomUUID2(),
+        name: schedule.jobName,
+        payload: schedule.payload,
+        attempts: 0,
+        priority: JobClass?.options?.priority
+      });
+    }
+  }
+};
+
+// src/schedule.ts
+var Schedule = class _Schedule {
+  #data;
+  constructor(data) {
+    this.#data = data;
+  }
+  get id() {
+    return this.#data.id;
+  }
+  get jobName() {
+    return this.#data.jobName;
+  }
+  get payload() {
+    return this.#data.payload;
+  }
+  get cronExpression() {
+    return this.#data.cronExpression;
+  }
+  get everyMs() {
+    return this.#data.everyMs;
+  }
+  get timezone() {
+    return this.#data.timezone;
+  }
+  get from() {
+    return this.#data.from;
+  }
+  get to() {
+    return this.#data.to;
+  }
+  get limit() {
+    return this.#data.limit;
+  }
+  get runCount() {
+    return this.#data.runCount;
+  }
+  get nextRunAt() {
+    return this.#data.nextRunAt;
+  }
+  get lastRunAt() {
+    return this.#data.lastRunAt;
+  }
+  get status() {
+    return this.#data.status;
+  }
+  get createdAt() {
+    return this.#data.createdAt;
+  }
+  /**
+   * Find a schedule by ID.
+   *
+   * @param id - The schedule ID
+   * @returns The schedule instance, or null if not found
+   */
+  static async find(id) {
+    const adapter = QueueManager.use();
+    const data = await adapter.getSchedule(id);
+    if (!data) return null;
+    return new _Schedule(data);
+  }
+  /**
+   * List all schedules matching the given options.
+   *
+   * @param options - Optional filters for listing
+   * @returns Array of schedule instances
+   */
+  static async list(options) {
+    const adapter = QueueManager.use();
+    const schedules = await adapter.listSchedules(options);
+    return schedules.map((data) => new _Schedule(data));
+  }
+  /**
+   * Pause this schedule.
+   * No jobs will be dispatched while paused.
+   */
+  async pause() {
+    const adapter = QueueManager.use();
+    await adapter.updateSchedule(this.#data.id, { status: "paused" });
+    this.#data.status = "paused";
+  }
+  /**
+   * Resume this schedule.
+   * Jobs will be dispatched according to the schedule.
+   */
+  async resume() {
+    const adapter = QueueManager.use();
+    await adapter.updateSchedule(this.#data.id, { status: "active" });
+    this.#data.status = "active";
+  }
+  /**
+   * Delete this schedule permanently.
+   */
+  async delete() {
+    const adapter = QueueManager.use();
+    await adapter.deleteSchedule(this.#data.id);
+  }
+  /**
+   * Trigger immediate execution of this schedule's job.
+   * Also updates runCount and lastRunAt.
+   *
+   * If the schedule has reached its limit, the job will not be dispatched.
+   */
+  async trigger() {
+    if (this.#data.limit !== null && this.#data.runCount >= this.#data.limit) {
+      return;
+    }
+    const adapter = QueueManager.use();
+    const dispatcher = new JobDispatcher(this.#data.jobName, this.#data.payload);
+    await dispatcher.run();
+    const now = /* @__PURE__ */ new Date();
+    const newRunCount = this.#data.runCount + 1;
+    await adapter.updateSchedule(this.#data.id, {
+      runCount: newRunCount,
+      lastRunAt: now
+    });
+    this.#data.runCount = newRunCount;
+    this.#data.lastRunAt = now;
+  }
 };
 
 // src/strategies/backoff_strategy.ts
@@ -829,6 +1165,8 @@ export {
   Job,
   Locator,
   QueueManager,
+  Schedule,
+  ScheduleBuilder,
   Worker,
   customBackoff,
   exceptions_exports as errors,