@boringnode/queue 0.0.1-alpha.4 → 0.2.0

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, b as JobFactory, c as Job, d as JobClass } from './index-C3_tlebh.js';
-export { e as customBackoff, f as exponentialBackoff, g as fixedBackoff, l as linearBackoff } from './index-C3_tlebh.js';
+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-C0Xg6F4E.js';
+export { h as ScheduleBuilder, i as customBackoff, j as exponentialBackoff, k as fixedBackoff, l as linearBackoff } from './index-C0Xg6F4E.js';
 import * as _poppinss_utils from '@poppinss/utils';
 
 /**
@@ -345,6 +345,79 @@ declare class LocatorSingleton {
 /** Global job class registry singleton */
 declare const Locator: LocatorSingleton;
 
+/**
+ * Represents a persisted job schedule.
+ *
+ * Use `Schedule.find()` or `Schedule.list()` to retrieve schedules,
+ * then use instance methods to manage them.
+ *
+ * @example
+ * ```typescript
+ * const schedule = await Schedule.find('cleanup-daily')
+ * if (schedule) {
+ *   await schedule.pause()
+ *   // Later...
+ *   await schedule.resume()
+ * }
+ *
+ * // List all active schedules
+ * const activeSchedules = await Schedule.list({ status: 'active' })
+ * ```
+ */
+declare class Schedule {
+    #private;
+    constructor(data: ScheduleData);
+    get id(): string;
+    get name(): string;
+    get payload(): any;
+    get cronExpression(): string | null;
+    get everyMs(): number | null;
+    get timezone(): string;
+    get from(): Date | null;
+    get to(): Date | null;
+    get limit(): number | null;
+    get runCount(): number;
+    get nextRunAt(): Date | null;
+    get lastRunAt(): Date | null;
+    get status(): ScheduleStatus;
+    get createdAt(): Date;
+    /**
+     * Find a schedule by ID.
+     *
+     * @param id - The schedule ID
+     * @returns The schedule instance, or null if not found
+     */
+    static find(id: string): Promise<Schedule | null>;
+    /**
+     * List all schedules matching the given options.
+     *
+     * @param options - Optional filters for listing
+     * @returns Array of schedule instances
+     */
+    static list(options?: ScheduleListOptions): Promise<Schedule[]>;
+    /**
+     * Pause this schedule.
+     * No jobs will be dispatched while paused.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume this schedule.
+     * Jobs will be dispatched according to the schedule.
+     */
+    resume(): Promise<void>;
+    /**
+     * Delete this schedule permanently.
+     */
+    delete(): Promise<void>;
+    /**
+     * 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.
+     */
+    trigger(): Promise<void>;
+}
+
 declare const E_INVALID_DURATION_EXPRESSION: new (args?: any, options?: ErrorOptions) => _poppinss_utils.Exception;
 declare const E_INVALID_BASE_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
 declare const E_INVALID_MAX_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
@@ -356,20 +429,24 @@ declare const E_JOB_TIMEOUT: new (args: [jobName: string, timeout: number], opti
 declare const E_QUEUE_NOT_INITIALIZED: new (args?: any, options?: ErrorOptions) => _poppinss_utils.Exception;
 declare const E_ADAPTER_INIT_ERROR: new (args: [adapterName: string, originalMessage: string], options?: ErrorOptions) => _poppinss_utils.Exception;
 declare const E_NO_JOBS_FOUND: new (args: [patterns: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_INVALID_CRON_EXPRESSION: new (args: [expression: string, reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_INVALID_SCHEDULE_CONFIG: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
 
 declare const exceptions_E_ADAPTER_INIT_ERROR: typeof E_ADAPTER_INIT_ERROR;
 declare const exceptions_E_CONFIGURATION_ERROR: typeof E_CONFIGURATION_ERROR;
 declare const exceptions_E_INVALID_BASE_DELAY: typeof E_INVALID_BASE_DELAY;
+declare const exceptions_E_INVALID_CRON_EXPRESSION: typeof E_INVALID_CRON_EXPRESSION;
 declare const exceptions_E_INVALID_DURATION_EXPRESSION: typeof E_INVALID_DURATION_EXPRESSION;
 declare const exceptions_E_INVALID_MAX_DELAY: typeof E_INVALID_MAX_DELAY;
 declare const exceptions_E_INVALID_MULTIPLIER: typeof E_INVALID_MULTIPLIER;
+declare const exceptions_E_INVALID_SCHEDULE_CONFIG: typeof E_INVALID_SCHEDULE_CONFIG;
 declare const exceptions_E_JOB_MAX_ATTEMPTS_REACHED: typeof E_JOB_MAX_ATTEMPTS_REACHED;
 declare const exceptions_E_JOB_NOT_FOUND: typeof E_JOB_NOT_FOUND;
 declare const exceptions_E_JOB_TIMEOUT: typeof E_JOB_TIMEOUT;
 declare const exceptions_E_NO_JOBS_FOUND: typeof E_NO_JOBS_FOUND;
 declare const exceptions_E_QUEUE_NOT_INITIALIZED: typeof E_QUEUE_NOT_INITIALIZED;
 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_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_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 { 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, Worker, exceptions as errors };
+export { Job, Locator, QueueManager, Schedule, Worker, exceptions as errors };

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-RIXMQXYJ.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,13 +174,196 @@ var JobDispatcher = class {
   }
 };
 
+// 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;
-  /** 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;
   }
@@ -200,14 +387,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.
@@ -233,21 +447,50 @@ 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;
   }
+  /**
+   * 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);
+  }
 };
 
 // src/worker.ts
@@ -510,6 +753,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 };
@@ -542,9 +786,9 @@ 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);
     try {
-      await this.#executeWithTimeout(instance, timeout);
+      await this.#executeWithTimeout(instance, payload, context, timeout);
       await this.#adapter.completeJob(job.id, queue);
       const duration = (performance.now() - startTime).toFixed(2);
       debug_default("worker %s: successfully executed job %s in %dms", this.#id, job.id, duration);
@@ -588,7 +832,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,
@@ -596,12 +840,12 @@ 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);
@@ -617,17 +861,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) {
@@ -678,6 +924,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.name,
+        schedule.id,
+        schedule.runCount + 1
+      );
+      const JobClass = Locator.get(schedule.name);
+      const queue = JobClass?.options?.queue ?? "default";
+      await this.#adapter.pushOn(queue, {
+        id: randomUUID2(),
+        name: schedule.name,
+        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 name() {
+    return this.#data.name;
+  }
+  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.name, 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 +1225,8 @@ export {
   Job,
   Locator,
   QueueManager,
+  Schedule,
+  ScheduleBuilder,
   Worker,
   customBackoff,
   exceptions_exports as errors,