@boringnode/queue 0.0.1-alpha.4 → 0.1.0

package/README.md

@@ -1,5 +1,15 @@
 # @boringnode/queue
 
+<div align="center">
+
+[![typescript-image]][typescript-url]
+[![gh-workflow-image]][gh-workflow-url]
+[![npm-image]][npm-url]
+[![npm-download-image]][npm-download-url]
+[![license-image]][license-url]
+
+</div>
+
 A simple and efficient queue system for Node.js applications. Built for simplicity and ease of use, `@boringnode/queue` allows you to dispatch background jobs and process them asynchronously with support for multiple queue adapters.
 
 ## Installation
@@ -19,6 +29,7 @@ npm install @boringnode/queue
 - **Priority Queues**: Process high-priority jobs first
 - **Retry with Backoff**: Automatic retries with exponential, linear, or fixed backoff strategies
 - **Job Timeout**: Automatically fail or retry jobs that exceed a time limit
+- **Scheduled Jobs**: Cron-based or interval-based job scheduling with pause/resume support
 
 ## Quick Start
 
@@ -41,10 +52,6 @@ export default class SendEmailJob extends Job<SendEmailPayload> {
     queue: 'email',
   }
 
-  constructor(payload: SendEmailPayload, context: JobContext) {
-    super(payload, context)
-  }
-
   async execute(): Promise<void> {
     console.log(`[Attempt ${this.context.attempt}] Sending email to: ${this.payload.to}`)
   }
@@ -125,7 +132,7 @@ interface QueueManagerConfig {
   // Worker configuration
   worker: {
     concurrency: number
-    pollingInterval: string
+    idleDelay: Duration
   }
 
   // Job discovery locations
@@ -232,9 +239,9 @@ Schedule jobs to run in the future:
 ```typescript
 // Various time formats
 await SendEmailJob.dispatch(payload).in('30s') // 30 seconds
-await SendEmailJob.dispatch(payload).in('5m') // 5 minutes
-await SendEmailJob.dispatch(payload).in('2h') // 2 hours
-await SendEmailJob.dispatch(payload).in('1d') // 1 day
+await SendEmailJob.dispatch(payload).in('5m')  // 5 minutes
+await SendEmailJob.dispatch(payload).in('2h')  // 2 hours
+await SendEmailJob.dispatch(payload).in('1d')  // 1 day
 ```
 
 ## Priority
@@ -349,7 +356,7 @@ export default class MyJob extends Job<Payload> {
 ### Context Properties
 
 | Property       | Type   | Description                                     |
-| -------------- | ------ | ----------------------------------------------- |
+|----------------|--------|-------------------------------------------------|
 | `jobId`        | string | Unique identifier for this job                  |
 | `name`         | string | Job class name                                  |
 | `attempt`      | number | Current attempt number (1-based)                |
@@ -407,6 +414,97 @@ export default class SendEmailJob extends Job<SendEmailPayload> {
 
 Without a `jobFactory`, jobs are instantiated with `new JobClass(payload, context)`.
 
+## Scheduled Jobs
+
+Schedule jobs to run on a recurring basis using cron expressions or fixed intervals. Schedules are persisted and survive worker restarts.
+
+### Creating a Schedule
+
+```typescript
+import { Schedule } from '@boringnode/queue'
+
+// Run every 10 seconds (uses job name as schedule ID by default)
+const { scheduleId } = await MetricsJob.schedule({ endpoint: '/api/health' }).every('10s').run()
+
+// Run on a cron schedule with custom ID
+await CleanupJob.schedule({ days: 30 })
+  .id('daily-cleanup') // Custom ID (optional, defaults to job name)
+  .cron('0 * * * *') // Every hour at minute 0
+  .timezone('Europe/Paris') // Optional timezone (default: UTC)
+  .run()
+
+// Schedule with constraints
+await ReportJob.schedule({ type: 'weekly' })
+  .id('weekly-report')
+  .cron('0 9 * * MON') // Every Monday at 9am
+  .from(new Date('2024-01-01')) // Start date
+  .to(new Date('2024-12-31')) // End date
+  .limit(52) // Maximum 52 runs
+  .run()
+```
+
+### Managing Schedules
+
+```typescript
+import { Schedule } from '@boringnode/queue'
+
+// Find a schedule by ID
+const schedule = await Schedule.find('health-check')
+
+if (schedule) {
+  console.log(`Status: ${schedule.status}`) // 'active' or 'paused'
+  console.log(`Run count: ${schedule.runCount}`)
+  console.log(`Next run: ${schedule.nextRunAt}`)
+  console.log(`Last run: ${schedule.lastRunAt}`)
+
+  // Pause the schedule
+  await schedule.pause()
+
+  // Resume the schedule
+  await schedule.resume()
+
+  // Trigger an immediate run (outside of the normal schedule)
+  await schedule.trigger()
+
+  // Delete the schedule
+  await schedule.delete()
+}
+```
+
+### Listing Schedules
+
+```typescript
+import { Schedule } from '@boringnode/queue'
+
+// List all schedules
+const all = await Schedule.list()
+
+// Filter by status
+const active = await Schedule.list({ status: 'active' })
+const paused = await Schedule.list({ status: 'paused' })
+```
+
+### Schedule Options
+
+| Method               | Description                                     |
+|----------------------|-------------------------------------------------|
+| `.id(string)`        | Unique identifier (defaults to job name)        |
+| `.every(duration)`   | Run at fixed intervals ('5s', '1m', '1h', '1d') |
+| `.cron(expression)`  | Run on a cron schedule                          |
+| `.timezone(tz)`      | Timezone for cron expressions (default: 'UTC')  |
+| `.from(date)`        | Don't run before this date                      |
+| `.to(date)`          | Don't run after this date                       |
+| `.between(from, to)` | Shorthand for `.from().to()`                    |
+| `.limit(n)`          | Maximum number of runs                          |
+
+### How Scheduling Works
+
+- Schedules are **persisted** in the database (via the adapter)
+- The **Worker** polls for due schedules and dispatches jobs automatically
+- Each schedule run creates a **new job** with a unique ID
+- Multiple workers can run concurrently - only one will claim each due schedule
+- Failed jobs do **not** affect the schedule (the next run will still occur)
+
 ## Job Discovery
 
 The queue manager automatically discovers and registers jobs from the specified locations:
@@ -449,7 +547,7 @@ By default, a simple console logger is used that only outputs warnings and error
 Performance comparison with BullMQ using realistic jobs (5ms simulated work per job):
 
 | Jobs | Concurrency | @boringnode/queue | BullMQ | Diff        |
-| ---- | ----------- | ----------------- | ------ | ----------- |
+|------|-------------|-------------------|--------|-------------|
 | 100  | 1           | 562ms             | 596ms  | 5.7% faster |
 | 100  | 5           | 116ms             | 117ms  | ~same       |
 | 100  | 10          | 62ms              | 62ms   | ~same       |
@@ -475,3 +573,14 @@ npm run benchmark
 # Custom job duration
 npm run benchmark -- --duration=10
 ```
+
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/boringnode/queue/checks.yml?branch=main&style=for-the-badge
+[gh-workflow-url]: https://github.com/boringnode/queue/actions/workflows/checks.yml
+[npm-image]: https://img.shields.io/npm/v/@boringnode/queue.svg?style=for-the-badge&logo=npm
+[npm-url]: https://www.npmjs.com/package/@boringnode/queue
+[npm-download-image]: https://img.shields.io/npm/dm/@boringnode/queue?style=for-the-badge
+[npm-download-url]: https://www.npmjs.com/package/@boringnode/queue
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org
+[license-image]: https://img.shields.io/npm/l/@boringnode/queue?color=blueviolet&style=for-the-badge
+[license-url]: LICENSE.md

package/build/{chunk-5PDDRF5O.js → chunk-NPQKBCCY.js}

@@ -1,7 +1,7 @@
 import {
   E_INVALID_DURATION_EXPRESSION,
   PRIORITY_SCORE_MULTIPLIER
-} from "./chunk-HMGNQSSG.js";
+} from "./chunk-SMOKFZ46.js";
 
 // src/utils.ts
 import { parse as parseDuration } from "@lukeed/ms";
@@ -23,4 +23,4 @@ export {
   parse,
   calculateScore
 };
-//# sourceMappingURL=chunk-5PDDRF5O.js.map
+//# sourceMappingURL=chunk-NPQKBCCY.js.map

package/build/{chunk-HMGNQSSG.js → chunk-SMOKFZ46.js}

@@ -10,9 +10,11 @@ __export(exceptions_exports, {
   E_ADAPTER_INIT_ERROR: () => E_ADAPTER_INIT_ERROR,
   E_CONFIGURATION_ERROR: () => E_CONFIGURATION_ERROR,
   E_INVALID_BASE_DELAY: () => E_INVALID_BASE_DELAY,
+  E_INVALID_CRON_EXPRESSION: () => E_INVALID_CRON_EXPRESSION,
   E_INVALID_DURATION_EXPRESSION: () => E_INVALID_DURATION_EXPRESSION,
   E_INVALID_MAX_DELAY: () => E_INVALID_MAX_DELAY,
   E_INVALID_MULTIPLIER: () => E_INVALID_MULTIPLIER,
+  E_INVALID_SCHEDULE_CONFIG: () => E_INVALID_SCHEDULE_CONFIG,
   E_JOB_MAX_ATTEMPTS_REACHED: () => E_JOB_MAX_ATTEMPTS_REACHED,
   E_JOB_NOT_FOUND: () => E_JOB_NOT_FOUND,
   E_JOB_TIMEOUT: () => E_JOB_TIMEOUT,
@@ -72,6 +74,16 @@ var E_NO_JOBS_FOUND = createError(
   "E_NO_JOBS_FOUND",
   500
 );
+var E_INVALID_CRON_EXPRESSION = createError(
+  'Invalid cron expression "%s": %s',
+  "E_INVALID_CRON_EXPRESSION",
+  500
+);
+var E_INVALID_SCHEDULE_CONFIG = createError(
+  "Invalid schedule configuration: %s",
+  "E_INVALID_SCHEDULE_CONFIG",
+  500
+);
 
 // src/constants.ts
 var DEFAULT_PRIORITY = 5;
@@ -92,6 +104,8 @@ export {
   E_JOB_TIMEOUT,
   E_QUEUE_NOT_INITIALIZED,
   E_ADAPTER_INIT_ERROR,
+  E_INVALID_CRON_EXPRESSION,
+  E_INVALID_SCHEDULE_CONFIG,
   exceptions_exports,
   DEFAULT_PRIORITY,
   PRIORITY_SCORE_MULTIPLIER,
@@ -100,4 +114,4 @@ export {
   DEFAULT_STALLED_THRESHOLD,
   DEFAULT_ERROR_RETRY_DELAY
 };
-//# sourceMappingURL=chunk-HMGNQSSG.js.map
+//# sourceMappingURL=chunk-SMOKFZ46.js.map

package/build/chunk-SMOKFZ46.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/exceptions.ts","../src/constants.ts"],"sourcesContent":["import { createError } from '@poppinss/utils'\n\nexport const E_INVALID_DURATION_EXPRESSION = createError(\n  'Invalid duration expression: \"%s\"',\n  'E_INVALID_DURATION_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_BASE_DELAY = createError<[reason: string]>(\n  'Invalid base delay. Reason: %s',\n  'E_INVALID_BASE_DELAY',\n  500\n)\n\nexport const E_INVALID_MAX_DELAY = createError<[reason: string]>(\n  'Invalid max delay. Reason: %s',\n  'E_INVALID_MAX_DELAY',\n  500\n)\n\nexport const E_INVALID_MULTIPLIER = createError<[reason: string]>(\n  'Invalid multiplier. Reason: %s',\n  'E_INVALID_MULTIPLIER',\n  500\n)\n\nexport const E_CONFIGURATION_ERROR = createError<[reason: string]>(\n  'Configuration error. Reason: %s',\n  'E_CONFIGURATION_ERROR',\n  500\n)\n\nexport const E_JOB_NOT_FOUND = createError<[jobName: string]>(\n  'Requested job \"%s\" is not registered',\n  'E_JOB_NOT_FOUND'\n)\n\nexport const E_JOB_MAX_ATTEMPTS_REACHED = createError<[jobName: string]>(\n  'The job \"%s\" has reached the maximum number of retry attempts',\n  'E_JOB_MAX_ATTEMPTS_REACHED'\n)\n\nexport const E_JOB_TIMEOUT = createError<[jobName: string, timeout: number]>(\n  'The job \"%s\" has exceeded the timeout of %dms',\n  'E_JOB_TIMEOUT'\n)\n\nexport const E_QUEUE_NOT_INITIALIZED = createError(\n  'QueueManager is not initialized. Call QueueManager.init() before using it.',\n  'E_QUEUE_NOT_INITIALIZED',\n  500\n)\n\nexport const E_ADAPTER_INIT_ERROR = createError<[adapterName: string, originalMessage: string]>(\n  'Failed to initialize adapter \"%s\". Reason: %s',\n  'E_ADAPTER_INIT_ERROR',\n  500\n)\n\nexport const E_NO_JOBS_FOUND = createError<[patterns: string]>(\n  'No jobs found for the specified locations: %s. Verify your glob patterns match your job files.',\n  'E_NO_JOBS_FOUND',\n  500\n)\n\nexport const E_INVALID_CRON_EXPRESSION = createError<[expression: string, reason: string]>(\n  'Invalid cron expression \"%s\": %s',\n  'E_INVALID_CRON_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_SCHEDULE_CONFIG = createError<[reason: string]>(\n  'Invalid schedule configuration: %s',\n  'E_INVALID_SCHEDULE_CONFIG',\n  500\n)\n","/**\n * Default job priority (1-10 scale, lower = higher priority)\n */\nexport const DEFAULT_PRIORITY = 5\n\n/**\n * Multiplier used in score calculation: priority * multiplier + timestamp\n *\n * This ensures higher priority jobs are processed first,\n * while preserving FIFO order within the same priority.\n * The value (1e13) leaves room for ~300 years of millisecond timestamps.\n */\nexport const PRIORITY_SCORE_MULTIPLIER = 1e13\n\n/**\n * Default delay when the worker is idle (no jobs in queue)\n */\nexport const DEFAULT_IDLE_DELAY = '2s'\n\n/**\n * Default interval between stalled job checks\n */\nexport const DEFAULT_STALLED_INTERVAL = '30s'\n\n/**\n * Default threshold after which a job is considered stalled\n */\nexport const DEFAULT_STALLED_THRESHOLD = '30s'\n\n/**\n * Default delay before retrying after an error\n */\nexport const DEFAULT_ERROR_RETRY_DELAY = '5s'\n"],"mappings":";;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAAS,mBAAmB;AAErB,IAAM,gCAAgC;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AACF;AAEO,IAAM,6BAA6B;AAAA,EACxC;AAAA,EACA;AACF;AAEO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;AAEO,IAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;;;ACxEO,IAAM,mBAAmB;AASzB,IAAM,4BAA4B;AAKlC,IAAM,qBAAqB;AAK3B,IAAM,2BAA2B;AAKjC,IAAM,4BAA4B;AAKlC,IAAM,4BAA4B;","names":[]}

package/build/{chunk-CD45GT6E.js → chunk-US7THLSZ.js}

@@ -3,7 +3,7 @@ import {
   E_CONFIGURATION_ERROR,
   E_JOB_NOT_FOUND,
   E_QUEUE_NOT_INITIALIZED
-} from "./chunk-HMGNQSSG.js";
+} from "./chunk-SMOKFZ46.js";
 
 // src/debug.ts
 import { debuglog } from "util";
@@ -354,4 +354,4 @@ export {
   Locator,
   QueueManager
 };
-//# sourceMappingURL=chunk-CD45GT6E.js.map
+//# sourceMappingURL=chunk-US7THLSZ.js.map

package/build/{index-C3_tlebh.d.ts → index-2Ng_OpVK.d.ts}

@@ -186,6 +186,19 @@ interface Logger {
 }
 
 type Duration = number | string;
+/**
+ * Result returned when dispatching a job.
+ *
+ * @example
+ * ```typescript
+ * const { jobId } = await SendEmailJob.dispatch(payload)
+ * console.log(`Dispatched job: ${jobId}`)
+ * ```
+ */
+interface DispatchResult {
+    /** Unique identifier for this specific job instance */
+    jobId: string;
+}
 interface JobData {
     id: string;
     name: string;
@@ -345,6 +358,82 @@ type WorkerCycle = {
     suggestedDelay: Duration;
 };
 type AdapterFactory<T extends Adapter = Adapter> = () => T;
+/**
+ * Status of a schedule.
+ */
+type ScheduleStatus = 'active' | 'paused';
+/**
+ * Configuration for creating a schedule.
+ * Used by ScheduleBuilder to collect schedule options before creation.
+ */
+interface ScheduleConfig {
+    /** Optional ID for the schedule (UUID if not set). Used for upsert. */
+    id?: string;
+    /** Job class name */
+    jobName: string;
+    /** Job payload */
+    payload: any;
+    /** Cron expression (mutually exclusive with everyMs) */
+    cronExpression?: string;
+    /** Interval in milliseconds (mutually exclusive with cronExpression) */
+    everyMs?: number;
+    /** IANA timezone for cron evaluation */
+    timezone: string;
+    /** Start boundary - no jobs dispatched before this */
+    from?: Date;
+    /** End boundary - no jobs dispatched after this */
+    to?: Date;
+    /** Maximum number of runs (null = unlimited) */
+    limit?: number;
+}
+/**
+ * Persisted schedule data.
+ * Represents a schedule stored in the adapter.
+ */
+interface ScheduleData {
+    /** Unique identifier */
+    id: string;
+    /** Job class name */
+    jobName: string;
+    /** Job payload */
+    payload: any;
+    /** Cron expression (null if using interval) */
+    cronExpression: string | null;
+    /** Interval in milliseconds (null if using cron) */
+    everyMs: number | null;
+    /** IANA timezone */
+    timezone: string;
+    /** Start boundary - no jobs dispatched before this */
+    from: Date | null;
+    /** End boundary - no jobs dispatched after this */
+    to: Date | null;
+    /** Maximum number of runs */
+    limit: number | null;
+    /** Number of times this schedule has run */
+    runCount: number;
+    /** Next scheduled run time */
+    nextRunAt: Date | null;
+    /** Last run time */
+    lastRunAt: Date | null;
+    /** Current status */
+    status: ScheduleStatus;
+    /** When the schedule was created */
+    createdAt: Date;
+}
+/**
+ * Result returned when creating a schedule.
+ */
+interface ScheduleResult {
+    /** Unique identifier for the schedule */
+    scheduleId: string;
+}
+/**
+ * Options for listing schedules.
+ */
+interface ScheduleListOptions {
+    /** Filter by status */
+    status?: ScheduleStatus;
+}
 interface QueueManagerConfig {
     default: string;
     adapters: Record<string, AdapterFactory>;
@@ -504,6 +593,57 @@ interface Adapter {
      * Called when the worker stops or the adapter is no longer needed.
      */
     destroy(): Promise<void>;
+    /**
+     * Create or update a schedule.
+     *
+     * If a schedule with the given id exists, it will be updated (upsert).
+     * Otherwise, a new schedule is created.
+     *
+     * @param config - The schedule configuration
+     * @returns The schedule ID
+     */
+    createSchedule(config: ScheduleConfig): Promise<string>;
+    /**
+     * Get a schedule by ID.
+     *
+     * @param id - The schedule ID
+     * @returns The schedule data, or null if not found
+     */
+    getSchedule(id: string): Promise<ScheduleData | null>;
+    /**
+     * List all schedules matching the given options.
+     *
+     * @param options - Optional filters for listing
+     * @returns Array of schedule data
+     */
+    listSchedules(options?: ScheduleListOptions): Promise<ScheduleData[]>;
+    /**
+     * Update a schedule's status or run metadata.
+     *
+     * @param id - The schedule ID
+     * @param updates - The fields to update
+     */
+    updateSchedule(id: string, updates: Partial<Pick<ScheduleData, 'status' | 'nextRunAt' | 'lastRunAt' | 'runCount'>>): Promise<void>;
+    /**
+     * Delete a schedule permanently.
+     *
+     * @param id - The schedule ID to delete
+     */
+    deleteSchedule(id: string): Promise<void>;
+    /**
+     * Atomically claim a due schedule for execution.
+     *
+     * This method:
+     * 1. Finds ONE schedule where nextRunAt <= now AND status = 'active'
+     * 2. Calculates and updates its nextRunAt to the next occurrence
+     * 3. Increments runCount and sets lastRunAt
+     * 4. Returns the schedule data for job dispatching
+     *
+     * The atomic nature prevents multiple workers from claiming the same schedule.
+     *
+     * @returns The claimed schedule, or null if no schedules are due
+     */
+    claimDueSchedule(): Promise<ScheduleData | null>;
 }
 
 /**
@@ -616,15 +756,15 @@ declare class JobDispatcher<T> {
     /**
      * 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}`)
      * ```
      */
-    run(): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+    run(): Promise<DispatchResult>;
     /**
      * Thenable implementation for auto-dispatch when awaited.
      *
@@ -632,9 +772,80 @@ declare class JobDispatcher<T> {
      *
      * @param onFulfilled - Success callback
      * @param onRejected - Error callback
-     * @returns Promise resolving to the job ID
+     * @returns Promise resolving to the DispatchResult
      */
-    then(onFulfilled?: (value: string) => any, onRejected?: (reason: any) => any): Promise<any>;
+    then(onFulfilled?: (value: DispatchResult) => any, onRejected?: (reason: any) => any): Promise<any>;
+}
+
+/**
+ * Fluent builder for creating job schedules.
+ *
+ * @example
+ * ```typescript
+ * // Create with cron
+ * const { scheduleId } = await new ScheduleBuilder('CleanupJob', { days: 30 })
+ *   .id('cleanup-daily')
+ *   .cron('0 0 * * *')
+ *   .timezone('Europe/Paris')
+ *   .run()
+ *
+ * // Create with interval
+ * const { scheduleId } = await new ScheduleBuilder('SyncJob', {})
+ *   .every('5m')
+ *   .run()
+ * ```
+ */
+declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
+    #private;
+    constructor(jobName: string, payload: any);
+    /**
+     * 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: string): this;
+    /**
+     * Set a cron expression for the schedule.
+     * Mutually exclusive with `every()`.
+     */
+    cron(expression: string): this;
+    /**
+     * Set a repeating interval for the schedule.
+     * Mutually exclusive with `cron()`.
+     */
+    every(interval: Duration): this;
+    /**
+     * Set the timezone for cron evaluation.
+     * @default 'UTC'
+     */
+    timezone(tz: string): this;
+    /**
+     * Set the start boundary for the schedule.
+     * No jobs will be dispatched before this date.
+     */
+    from(date: Date): this;
+    /**
+     * Set the end boundary for the schedule.
+     * No jobs will be dispatched after this date.
+     */
+    to(date: Date): this;
+    /**
+     * Set both start and end boundaries for the schedule.
+     * Shorthand for `.from(start).to(end)`.
+     */
+    between(from: Date, to: Date): this;
+    /**
+     * Set the maximum number of runs for this schedule.
+     */
+    limit(maxRuns: number): this;
+    /**
+     * Create the schedule and return the schedule ID.
+     */
+    run(): Promise<ScheduleResult>;
+    /**
+     * Implement PromiseLike to allow `await builder.every('5m')` syntax.
+     */
+    then<TResult1 = ScheduleResult, TResult2 = never>(onfulfilled?: ((value: ScheduleResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
 
 /**
@@ -731,6 +942,32 @@ declare abstract class Job<Payload = any> {
      * ```
      */
     static dispatch<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
+    /**
+     * 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<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder;
     /**
      * Execute the job's business logic.
      *
@@ -773,4 +1010,4 @@ declare abstract class Job<Payload = any> {
     failed?(error: Error): Promise<void>;
 }
 
-export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type WorkerCycle as W, type AcquiredJob as a, type JobFactory as b, Job as c, type JobClass as d, customBackoff as e, exponentialBackoff as f, fixedBackoff as g, type JobOptions as h, type JobContext as i, type BackoffConfig as j, type QueueConfig as k, linearBackoff as l, type WorkerConfig as m, type AdapterFactory as n };
+export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type AcquiredJob as a, type ScheduleData as b, type ScheduleListOptions as c, type JobFactory as d, Job as e, type JobClass as f, type ScheduleStatus as g, ScheduleBuilder as h, customBackoff as i, exponentialBackoff as j, fixedBackoff as k, linearBackoff as l, type DispatchResult as m, type JobOptions as n, type JobContext as o, type BackoffConfig as p, type QueueConfig as q, type WorkerConfig as r, type AdapterFactory as s, type ScheduleResult as t };

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-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 * 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 jobName(): 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 };