@maestro-js/recurring-jobs 1.0.0-alpha.19 → 1.0.0-alpha.2

package/README.md

@@ -1,233 +1,348 @@
-# @maestro-js/recurring-jobs
+# RecurringJobs Skill
 
-Cron-based recurring job scheduling with distributed lock-based deduplication.
+## Overview
+
+RecurringJobs provides cron-based job scheduling backed by the Queue package. Each recurring job gets its own dedicated queue where every execution is a persisted message with full lifecycle tracking. The next run is enqueued before the work function executes, guaranteeing the schedule continues even if the current run fails.
 
 ## Quick Setup
 
 ```ts
 import { RecurringJobs } from '@maestro-js/recurring-jobs'
+import { Queue } from '@maestro-js/queue'
+import { Log } from '@maestro-js/log'
+
+// Create a logger for recurring job events
+const logger = Log.create<[RecurringJobs.LogMessage]>({
+  transports: [{ write: ({ data: [msg] }) => console.log(msg) }]
+})
 
-// Create and register with the local (in-memory) driver
-const service = RecurringJobs.Provider.create({
-  driver: RecurringJobs.drivers.local()
+// Create and register the recurring jobs service with a queue service
+const recurringJobsService = RecurringJobs.Provider.create({
+  logger,
+  queueService: Queue.provider('default')
 })
-RecurringJobs.Provider.register('default', service)
+RecurringJobs.Provider.register('default', recurringJobsService)
 
 // Define a recurring job
-RecurringJobs.create({
-  name: 'send-weekly-digest',
-  cron: '0 9 * * MON',
-  handle: async () => sendDigest()
+const dailyReport = RecurringJobs.createJob({
+  name: 'daily-sales-report',
+  cron: '0 6 * * *',
+  workFn: async () => {
+    const total = await calculateDailySales()
+    return { total }
+  }
 })
 
-// Start polling -- fires immediately then every 60 seconds
-const worker = RecurringJobs.work()
+// Start processing
+dailyReport.startProcessing()
+```
+
+## Cron Expression Format
+
+Uses the `cron-parser` library (v4.x) for standard 5-field cron expressions:
 
-// Graceful shutdown
-await worker.abort()
+```
+ ┌───────────── minute (0-59)
+ │ ┌───────────── hour (0-23)
+ │ │ ┌───────────── day of month (1-31)
+ │ │ │ ┌───────────── month (1-12)
+ │ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
+ │ │ │ │ │
+ * * * * *
 ```
 
-## Drivers
+Common examples:
+- `0 6 * * *` -- every day at 6:00 AM
+- `*/15 * * * *` -- every 15 minutes
+- `0 0 * * 0` -- every Sunday at midnight
+- `0 9 1 * *` -- first day of every month at 9:00 AM
+- `30 */2 * * *` -- every 2 hours at the 30-minute mark
 
-### Db
+Invalid cron expressions throw immediately when passed to `createJob()`, since `cron-parser.parseExpression()` is called at creation time.
+
+## API Reference
 
-MySQL-backed, for multi-process production deployments. Uses `UPDATE ... WHERE lastRunDate < ?`
-and `INSERT IGNORE` for atomic distributed locking.
+### Provider Setup
+
+#### `RecurringJobs.Provider.create(config)`
+
+Create a recurring jobs service instance.
 
 ```ts
-RecurringJobs.drivers.db({
-  db: Db,              // Db service instance
-  databaseTable: 'recurringJobs'
+RecurringJobs.Provider.create(config: {
+  logger: Log.Logger<[RecurringJobs.LogMessage]>
+  queueService: Queue.QueueService
 })
 ```
 
-Required table schema:
+- `logger` -- a Log instance typed to `RecurringJobs.LogMessage` for structured job lifecycle events
+- `queueService` -- the Queue service used to back each recurring job's dedicated queue
+
+#### `RecurringJobs.Provider.register(name, service)`
 
-```sql
-CREATE TABLE recurringJobs (
-  name VARCHAR(255) NOT NULL PRIMARY KEY,
-  lastRunDate DATETIME DEFAULT NULL
-);
+Register the service instance in the named registry.
+
+```ts
+RecurringJobs.Provider.register('default', recurringJobsService)
 ```
 
-Source: `packages/recurring-jobs/src/db-recurring-jobs-driver.ts`
+#### `RecurringJobs.provider(key)`
+
+Resolve a named instance from the registry. Supports deferred resolution via Proxy.
+
+```ts
+const jobs = RecurringJobs.provider('default')
+```
 
-### Cache
+### Service Methods (on the facade or provider instance)
 
-Redis-backed via `@maestro-js/cache` with distributed locking (`cache.lock()`). Use when you
-already have Redis and don't need MySQL.
+#### `RecurringJobs.createJob(config)`
+
+Create a recurring job with a dedicated queue. Returns a `RecurringJob` handle.
 
 ```ts
-RecurringJobs.drivers.cache({
-  cache: cacheService,          // Cache.CacheService instance
-  keyPrefix: 'recurring-jobs:'  // optional, default 'recurring-jobs:'
-})
+RecurringJobs.createJob<T>(config: {
+  name: string
+  cron: string
+  workFn: () => Promise<T>
+  logger?: Log.LogFunctions<[RecurringJobs.LogMessage]>  // optional per-job logger
+}): RecurringJobs.RecurringJob<T>
 ```
 
-Source: `packages/recurring-jobs/src/cache-recurring-jobs-driver.ts`
+Each job creates a queue named `RecurringJobs: <name>`. The cron expression is validated immediately and throws if invalid.
 
-### Local
+#### `RecurringJobs.startProcessing()`
 
-In-memory, single-process only. No distributed locking -- every process will run every due job.
-Good for development and testing.
+Start processing on all registered recurring jobs.
 
 ```ts
-RecurringJobs.drivers.local()
+RecurringJobs.startProcessing()
 ```
 
-Source: `packages/recurring-jobs/src/local-recurring-jobs-driver.ts`
+#### `RecurringJobs.stopProcessing()`
 
-### Choosing a driver
+Stop processing on all registered recurring jobs.
 
-| Driver  | Distributed locking | Persistence | Best for                              |
-|---------|---------------------|-------------|---------------------------------------|
-| **Db**  | Yes (MySQL row)     | Yes         | Multi-process production              |
-| **Cache** | Yes (Redis lock)  | Yes*        | Production when you have Redis, no MySQL |
-| **Local** | No                | No          | Development and testing               |
+```ts
+RecurringJobs.stopProcessing()
+```
 
-\* Cache persistence depends on Redis persistence settings.
+#### `RecurringJobs.list()`
 
-## API Reference
+Return the names of all registered recurring jobs.
 
-### `RecurringJobs.create(config)`
+```ts
+RecurringJobs.list()  // ['daily-sales-report', 'session-cleanup']
+```
 
-Register a recurring job. Throws immediately on invalid cron expression or duplicate job name.
+#### `RecurringJobs.get(name)`
+
+Return the recurring job with the given name, or `undefined` if not found.
 
 ```ts
-RecurringJobs.create({
-  name: string,                          // unique job identifier
-  cron: string,                          // cron expression (e.g. '0 9 * * MON')
-  handle: () => Promise<Result>,         // async handler
-  middleware?: Middleware<Result>[]       // optional middleware chain
-})
+const job = RecurringJobs.get<{ total: number }>('daily-sales-report')
 ```
 
-### `RecurringJobs.work()`
+### RecurringJob Instance Methods
 
-Start a 60-second polling loop that checks for due jobs, acquires distributed locks via the
-driver, and executes handlers. Returns an object with `abort()` to stop the loop and wait for
-in-flight ticks.
+#### `job.startProcessing()`
+
+Enqueue the next scheduled run and begin polling. If a waiting job already exists, it is not duplicated (deduplication).
 
 ```ts
-const worker = RecurringJobs.work()
+dailyReport.startProcessing()
+```
+
+#### `job.stopProcessing()`
 
-// Later, to stop:
-await worker.abort()
+Stop polling for this job.
+
+```ts
+dailyReport.stopProcessing()
 ```
 
-### `RecurringJobs.stopAllWork()`
+#### `job.getNextUp()`
 
-Abort all active work loops and wait for in-flight ticks to finish.
+Return the first message in `waiting` status, or `null` if none exists.
 
 ```ts
-await RecurringJobs.stopAllWork()
+const next = await dailyReport.getNextUp()
+// { id: 42, status: 'waiting', scheduledDate: '2026-02-22T06:00:00.000Z', cron: '0 6 * * *', ... }
 ```
 
-## Common Patterns
+#### `job.list({ pageSize, pageNumber })`
 
-### Basic cron job
+Return a paginated list of all messages (past runs and pending) for this job.
 
 ```ts
-RecurringJobs.create({
-  name: 'cleanup-expired-tokens',
-  cron: '0 3 * * *', // daily at 3am
-  handle: async () => {
-    await db.update('DELETE FROM tokens WHERE expiresAt < NOW()')
-  }
-})
+const history = await dailyReport.list({ pageSize: 20, pageNumber: 0 })
+// [{ id: 41, status: 'success', result: { total: 15420 }, ... }, ...]
 ```
 
-### Middleware wrapping
+#### `job.rescheduleJob({ jobId, scheduledDate })`
+
+Change the scheduled time of a waiting job. Only the next waiting job can be rescheduled; throws if `jobId` does not match the current waiting job.
 
 ```ts
-RecurringJobs.create({
-  name: 'generate-report',
-  cron: '0 6 * * MON',
-  middleware: [
-    async (next) => {
-      try {
-        return await next()
-      } catch (e) {
-        await errorReporter.capture(e)
-        throw e
-      }
-    }
-  ],
-  handle: async () => generateWeeklyReport()
+await dailyReport.rescheduleJob({
+  jobId: 42,
+  scheduledDate: '2026-02-22T08:00:00.000Z' as Iso.Instant
 })
 ```
 
-### Graceful shutdown
+#### `job.name` / `job.cron`
+
+Read-only properties exposing the job's name and cron expression.
 
 ```ts
-const worker = RecurringJobs.work()
+dailyReport.name  // 'daily-sales-report'
+dailyReport.cron  // '0 6 * * *'
+```
 
-process.on('SIGTERM', async () => {
-  await worker.abort()   // waits for in-flight tick to finish
-  process.exit(0)
-})
+### JobMessage Interface
 
-// Or abort all workers at once:
-process.on('SIGTERM', async () => {
-  await RecurringJobs.stopAllWork()
-  process.exit(0)
-})
+Each queue message returned by `getNextUp()` and `list()` has these fields:
+
+```ts
+interface JobMessage<Result = any> {
+  id: number
+  batchId: number | null
+  queue: string
+  scheduledDate: Iso.Instant
+  enqueuedDate: Iso.Instant
+  startedDate: Iso.Instant | null
+  status: 'waiting' | 'processing' | 'success' | 'error' | 'stuck'
+  result: Result
+  recovered: number
+  runningTime: number | null
+  uniqueKey: number | null
+  priority: number | null
+  cron: string
+}
 ```
 
-### Named provider instances
+## Common Patterns
+
+### Multiple Recurring Jobs
 
 ```ts
-const primary = RecurringJobs.Provider.create({
-  driver: RecurringJobs.drivers.db({ db: Db, databaseTable: 'recurringJobs' })
+const report = RecurringJobs.createJob({
+  name: 'daily-report',
+  cron: '0 6 * * *',
+  workFn: async () => generateReport()
 })
-RecurringJobs.Provider.register('default', primary)
 
-const secondary = RecurringJobs.Provider.create({
-  driver: RecurringJobs.drivers.local()
+const cleanup = RecurringJobs.createJob({
+  name: 'session-cleanup',
+  cron: '0 0 * * *',
+  workFn: async () => cleanStaleSessions()
 })
-RecurringJobs.Provider.register('dev', secondary)
 
-RecurringJobs.provider('dev').create({ ... })
+// Start all jobs at once
+RecurringJobs.startProcessing()
+
+// Or start individually
+report.startProcessing()
+cleanup.startProcessing()
 ```
 
-## Warnings and Gotchas
+### Inspecting and Rescheduling
 
-- **60-second polling**: Jobs won't fire more precisely than ~1 minute.
-- **Unique job names**: Duplicate names within a service instance throw at `create()` time.
-- **Eager cron validation**: Invalid cron expressions throw at `create()` time, not at poll time.
-- **First-time jobs**: A never-before-run job doesn't fire immediately on `work()` -- it waits
-  until its cron expression's next occurrence from now.
-- **Handler errors don't crash the loop**: Failed handlers are logged as `jobFailed` and other
-  jobs continue normally.
-- **Db driver requires a table**: The `recurringJobs` table must exist with the schema shown above.
-- **Local driver has no distributed locking**: All processes will independently run the same job.
+```ts
+const job = RecurringJobs.get('daily-report')
+if (job) {
+  const next = await job.getNextUp()
+  if (next) {
+    // Delay the next run by 2 hours
+    const delayed = new Date(new Date(next.scheduledDate).getTime() + 2 * 60 * 60 * 1000)
+    await job.rescheduleJob({
+      jobId: next.id,
+      scheduledDate: delayed.toISOString() as Iso.Instant
+    })
+  }
+}
+```
 
-## Cross-Package Integration
+### Per-Job Logger
 
-- **Depends on**: `@maestro-js/service-registry` (Provider pattern), `@maestro-js/log` (structured
-  logging), `cron-parser` (cron expression parsing)
-- **Optional drivers depend on**: `@maestro-js/db` (Db driver), `@maestro-js/cache` (Cache driver)
+Add a dedicated logger to a specific job for fine-grained observability:
 
-## Driver Interface
+```ts
+const jobLogger: Log.LogFunctions<[RecurringJobs.LogMessage]> = {
+  write({ data: [msg] }) {
+    if (msg.event === 'jobFailed') {
+      alertOpsTeam(msg.job, msg.error)
+    }
+  }
+}
 
-Implement `RecurringJobs.Driver` to create a custom backend:
+const criticalJob = RecurringJobs.createJob({
+  name: 'payment-reconciliation',
+  cron: '0 */4 * * *',
+  workFn: async () => reconcilePayments(),
+  logger: jobLogger
+})
+```
+
+### Execution History
 
 ```ts
-interface Driver {
-  listLastRunDates(jobNames: string[]): Promise<{ jobName: string; date: Iso.Instant }[]>
-  pullJob(options: { jobName: string; date: Iso.Instant }): Promise<boolean>
+const job = RecurringJobs.get('daily-report')
+if (job) {
+  const runs = await job.list({ pageSize: 50, pageNumber: 0 })
+  const failures = runs.filter(r => r.status === 'error')
+  const avgRuntime = runs
+    .filter(r => r.runningTime !== null)
+    .reduce((sum, r) => sum + r.runningTime!, 0) / runs.length
 }
 ```
 
-`listLastRunDates` returns the last run date for each known job name. `pullJob` attempts to
-acquire a lock for the given job and date -- returns `true` if the lock was acquired (this process
-should run the job), `false` otherwise.
+## Log Events
+
+The service emits structured log events of type `RecurringJobs.LogMessage`:
+
+| Event | Level | Description |
+|---|---|---|
+| `jobProcessing` | info | A job message was dequeued and is about to execute |
+| `jobSucceeded` | info | The work function completed successfully |
+| `jobFailed` | error | The work function threw an error |
+| `jobScheduled` | info | The next run was enqueued with its scheduled date |
+| `jobAlreadyScheduled` | info | A waiting job already exists; skip enqueueing |
+| `jobSchedulingFailed` | error | Failed to enqueue the next run |
+
+## Cross-Package Integration
+
+### Dependencies
+
+- **@maestro-js/service-registry** -- foundation for the Provider pattern (registry, deferred Proxy resolution)
+- **@maestro-js/queue** -- each recurring job creates a dedicated queue via `queueService.create()`. Queue handles message persistence, polling, dequeuing, and lifecycle transitions
+- **@maestro-js/log** -- structured logging with pluggable transports for job lifecycle events
+
+### How It Connects
+
+RecurringJobs wraps Queue to add cron scheduling semantics. When `startProcessing()` is called, the next cron-derived date is computed and a queue message is enqueued for that date. When the Queue dequeues and runs the message, the work function fires and the next run is enqueued before the work executes. This ensures schedule continuity even on failure.
+
+Queue itself depends on Db (MySQL) for message persistence, so the full dependency chain is:
+
+```
+RecurringJobs -> Queue -> Db (MySQL)
+              -> Log
+              -> ServiceRegistry
+```
+
+### Provider Pattern
+
+This package follows the standard maestro Provider pattern:
 
-Source: `packages/recurring-jobs/src/index.ts`
+1. `RecurringJobs.Provider.create(config)` -- factory that instantiates the service
+2. `RecurringJobs.Provider.register(name, service)` -- registers the instance by name
+3. `RecurringJobs.provider(key)` -- resolves a named instance (deferred via Proxy)
+4. `RecurringJobs.*` -- facade that spreads `provider('default')` for direct method access
 
-## Key Source Files
+## Notes
 
-- `packages/recurring-jobs/src/index.ts` -- main export, Provider pattern, polling loop, middleware
-- `packages/recurring-jobs/src/db-recurring-jobs-driver.ts` -- MySQL driver with row-level locking
-- `packages/recurring-jobs/src/cache-recurring-jobs-driver.ts` -- Redis driver via @maestro-js/cache
-- `packages/recurring-jobs/src/local-recurring-jobs-driver.ts` -- in-memory driver for dev/testing
+- No tests exist for this package yet (`pnpm --filter @maestro-js/recurring-jobs test` prints "No tests yet").
+- The `cron-parser` library validates cron expressions at job creation time; invalid expressions throw immediately.
+- Deduplication: `startProcessing()` checks for an existing waiting message before enqueueing, preventing double-fires across process restarts.
+- The next run is enqueued inside the queue's `workFn` (before the user's `workFn` runs), so the schedule continues even if the current execution fails.
+- Only the next waiting job can be rescheduled via `rescheduleJob()`. Attempting to reschedule a non-waiting or non-next job throws an error.

package/dist/index.d.ts

@@ -1,167 +1,200 @@
 import { Iso } from 'iso-fns2';
+import { Queue } from '@maestro-js/queue';
 import { Log } from '@maestro-js/log';
-import { Cache } from '@maestro-js/cache';
 
-interface DbRecurringJobsDriverConfig {
-    db: {
-        update(query: string, params?: any[]): Promise<{
-            affectedRows: number;
-            changedRows: number;
-        }>;
-        select(query: string, params?: any[]): Promise<Array<Record<string, any>>>;
-        insert(query: string, params?: any[]): Promise<{
-            insertId: number;
-        }>;
-    };
-    databaseTable: string;
-}
-declare function DbRecurringJobsDriver({ db, databaseTable }: DbRecurringJobsDriverConfig): RecurringJobs.Driver;
-
-declare function localRecurringJobsDriver(): RecurringJobs.Driver;
-
-interface CacheRecurringJobsDriverConfig {
-    cache: Cache.CacheService;
-    keyPrefix?: string;
-}
-declare function cacheRecurringJobsDriver({ cache, keyPrefix }: CacheRecurringJobsDriverConfig): RecurringJobs.Driver;
-
-declare function createService({ driver, logger: serviceLogger }: RecurringJobs.Provider.ServiceConfig): RecurringJobs.Service;
-type RecurringJobsLogMessage = {
-    event: 'jobDue';
-    jobName: string;
-    nextRun: string;
-} | {
-    event: 'jobLockAcquired';
-    jobName: string;
-    nextRun: string;
-} | {
-    event: 'jobLockFailed';
-    jobName: string;
-    nextRun: string;
-    error: unknown;
-} | {
-    event: 'jobProcessed';
-    jobName: string;
-} | {
-    event: 'jobFailed';
-    jobName: string;
-    error: unknown;
+declare function create(serviceConfig: RecurringJobs.Provider.RecurringJobsServiceConfig): {
+    startProcessing: () => void;
+    stopProcessing: () => void;
+    list: () => string[];
+    get: <Result>(name: string) => RecurringJobs.RecurringJob<Result> | undefined;
+    createJob: <T>(jobConfig: RecurringJobs.JobConfig<T>) => RecurringJobs.RecurringJob<T>;
 };
-type KeysWithFallback = keyof RecurringJobs.Provider.Keys extends never ? {
-    default: unknown;
-} : RecurringJobs.Provider.Keys;
 declare function provider(key: RecurringJobs.Provider.Key): {
-    work: () => {
-        abort(): Promise<void>;
-    };
-    stopAllWork: () => Promise<void>;
-    create: <Result = any>(config: RecurringJobs.JobConfig<Result>) => void;
+    startProcessing: () => void;
+    stopProcessing: () => void;
+    list: () => string[];
+    get: <Result>(name: string) => RecurringJobs.RecurringJob<Result> | undefined;
+    createJob: <T>(jobConfig: RecurringJobs.JobConfig<T>) => RecurringJobs.RecurringJob<T>;
 };
 /**
- * Cron-based recurring job scheduling with distributed lock-based deduplication.
- *
- * Register a service with `RecurringJobs.Provider.register('default', RecurringJobs.Provider.create({ driver }))`,
- * then define jobs with `RecurringJobs.create({ name, cron, handle })`. Call `RecurringJobs.work()` to start
- * a 60-second polling loop that checks for due jobs, acquires distributed locks via the driver, and executes
- * handlers with optional middleware.
+ * Cron-based job scheduling backed by the Queue package.
  *
- * Three built-in drivers: `db` (MySQL row-level locking), `cache` (Redis via @maestro-js/cache),
- * `local` (in-memory, no distributed locking).
+ * Each recurring job gets its own dedicated queue where every execution is a
+ * persisted message with full lifecycle tracking. The next run is enqueued
+ * *before* the work function executes, guaranteeing the schedule continues
+ * even if the current run fails. Deduplication prevents double-fires across
+ * process restarts.
  *
  * @example
  * ```ts
- * RecurringJobs.Provider.register('default', RecurringJobs.Provider.create({
- *   driver: RecurringJobs.drivers.db({ db: Db, databaseTable: 'recurringJobs' })
- * }))
- *
- * RecurringJobs.create({
- *   name: 'send-weekly-digest',
- *   cron: '0 9 * * MON',
- *   handle: async () => sendDigest()
+ * // Create a daily sales report job
+ * const salesReport = RecurringJobs.createJob({
+ *   name: 'daily-sales-report',
+ *   cron: '0 6 * * *',
+ *   workFn: async () => {
+ *     const total = await calculateDailySales()
+ *     return { total }
+ *   }
  * })
  *
- * const worker = RecurringJobs.work()
- * // Later: await worker.abort()
+ * // Start processing and inspect upcoming runs
+ * salesReport.startProcessing()
+ * const next = await salesReport.getNextUp()  // { status: 'waiting', scheduledDate: '...' }
+ *
+ * // List all registered jobs
+ * RecurringJobs.list() // ['daily-sales-report']
  * ```
  */
 declare namespace RecurringJobs {
-    /** Union of all recurring jobs lifecycle log event shapes */
-    type LogMessage = RecurringJobsLogMessage;
-    /** Middleware function that wraps recurring job execution */
-    type Middleware<Result = any> = (next: () => Promise<Result>) => Promise<Result>;
-    /** Pluggable storage backend for tracking job run dates and acquiring distributed locks */
-    interface Driver {
-        /** Returns the last run date for each of the given job names */
-        listLastRunDates(jobNames: string[]): Promise<{
-            jobName: string;
-            date: Iso.Instant;
-        }[]>;
-        /** Attempts to acquire a lock for the given job and date — returns true if the lock was acquired */
-        pullJob(options: {
-            jobName: string;
-            date: Iso.Instant;
-        }): Promise<boolean>;
+    /** A single queue message representing one scheduled or completed job execution */
+    interface JobMessage<Result = any> {
+        id: number;
+        batchId: number | null;
+        queue: string;
+        scheduledDate: Iso.Instant;
+        enqueuedDate: Iso.Instant;
+        startedDate: Iso.Instant | null;
+        status: 'waiting' | 'processing' | 'success' | 'error' | 'stuck';
+        result: Result;
+        recovered: number;
+        runningTimeSeconds: number | null;
+        uniqueKey: number | null;
+        priority: number | null;
+        cron: string;
     }
-    /** Per-job configuration passed to {@link Service.create} */
-    interface JobConfig<Result = any> {
-        /** Cron expression defining the schedule (e.g. '0 9 * * MON') */
+    /**
+     * A single recurring job instance with its own dedicated queue.
+     *
+     * Each job has independent start/stop lifecycle, execution history, and
+     * rescheduling capability. The queue stores one message per scheduled run —
+     * call {@link list} to page through past and pending executions, or
+     * {@link getNextUp} to peek at the next waiting run.
+     *
+     * @example
+     * ```ts
+     * const job = RecurringJobs.createJob({
+     *   name: 'stale-session-cleanup',
+     *   cron: '0 0 * * *',
+     *   workFn: async () => { await cleanStaleSessions() }
+     * })
+     * job.startProcessing()
+     * const next = await job.getNextUp() // { status: 'waiting', ... }
+     * ```
+     */
+    interface RecurringJob<T = unknown> {
+        /** Enqueues the next scheduled run and begins polling */
+        startProcessing(): void;
+        /** Stops polling for this job */
+        stopProcessing(): void;
+        /** The name of the recurring job as specified in the config */
+        name: string;
+        /** The cron expression defining this job's schedule */
         cron: string;
-        /** Async handler invoked when the job is due */
-        handle(): Promise<Result>;
-        /** Unique name identifying this job across processes */
+        /** Changes the scheduled time of a waiting job */
+        rescheduleJob(job: {
+            jobId: number;
+            scheduledDate: Iso.Instant;
+        }): Promise<void>;
+        /** Returns the first message in `waiting` status, or `null` if none exists */
+        getNextUp(): Promise<JobMessage<T> | null>;
+        /** Returns a paginated list of all messages (past runs and pending) for this job */
+        list(options: {
+            pageSize: number;
+            pageNumber: number;
+        }): Promise<JobMessage<unknown>[]>;
+    }
+    /** Union of all recurring job lifecycle log event shapes */
+    type LogMessage = {
+        event: 'jobProcessing';
+        job: string;
+        driver: Queue.Driver;
+        messageId: number;
+    } | {
+        event: 'jobSucceeded';
+        job: string;
+        driver: Queue.Driver;
+        result: unknown;
+        messageId: number;
+    } | {
+        event: 'jobFailed';
+        job: string;
+        driver: Queue.Driver;
+        error: unknown;
+        messageId: number;
+    } | {
+        event: 'jobScheduled';
+        job: string;
+        nextRun: Iso.Instant;
+    } | {
+        event: 'jobAlreadyScheduled';
+        job: string;
+        existingJobId: number;
+    } | {
+        event: 'jobSchedulingFailed';
+        job: string;
+        error: unknown;
+    };
+    /** Configuration for a single recurring job passed to {@link RecurringJobsService.createJob} */
+    interface JobConfig<T = unknown> {
+        cron: string;
+        workFn(): Promise<T>;
         name: string;
-        /** Optional middleware chain wrapping the handler */
-        middleware?: Middleware<Result>[];
+        logger?: Log.LogFunctions<[LogMessage]>;
     }
     /**
-     * Core recurring jobs service returned by {@link RecurringJobs.Provider.create}.
+     * Container that manages multiple recurring jobs sharing the same queue service.
+     *
+     * Create individual jobs with {@link createJob}, then start or stop processing
+     * across all jobs at once or individually. Each job gets its own dedicated queue
+     * named `RecurringJobs: <jobName>`.
      *
-     * Use {@link Service.create create} to register jobs, then call {@link Service.work work}
-     * to start polling. The service checks every 60 seconds for due jobs, acquires distributed
-     * locks via the driver, and executes handlers with middleware.
+     * @example
+     * ```ts
+     * const report = RecurringJobs.createJob({ name: 'daily-report', cron: '0 6 * * *', workFn: generateReport })
+     * const cleanup = RecurringJobs.createJob({ name: 'session-cleanup', cron: '0 0 * * *', workFn: cleanSessions })
+     * RecurringJobs.startProcessing() // starts both jobs
+     * ```
      */
-    interface Service {
-        /** Starts a polling loop that checks for and executes due jobs every 60 seconds — returns an object with an `abort()` method to stop */
-        work(): {
-            abort(): Promise<void>;
-        };
-        /** Aborts all active work loops and waits for in-flight ticks to finish */
-        stopAllWork(): Promise<void>;
-        /** Registers a new recurring job with the given cron schedule and handler */
-        create<Result = any>(config: JobConfig<Result>): void;
+    interface RecurringJobsService {
+        /** Creates a recurring job with its own dedicated queue */
+        createJob<T>(jobConfig: RecurringJobs.JobConfig<T>): RecurringJobs.RecurringJob<T>;
+        /** Starts processing on all registered recurring jobs */
+        startProcessing: () => void;
+        /** Stops processing on all registered recurring jobs */
+        stopProcessing: () => void;
+        /** Returns the names of all registered recurring jobs */
+        list: () => string[];
+        /** Returns the recurring job with the given name, or `undefined` if not found */
+        get: <Result>(name: string) => RecurringJobs.RecurringJob<Result> | undefined;
     }
     namespace Provider {
-        interface ServiceConfig {
-            driver: Driver;
-            logger?: Log.Logger<[LogMessage]>;
+        /** Service-level configuration passed to `RecurringJobs.Provider.create()` */
+        interface RecurringJobsServiceConfig {
+            logger: Log.Logger<[RecurringJobs.LogMessage]>;
+            queueService: Queue.QueueService;
         }
-        type Key = keyof KeysWithFallback;
+        type Key = keyof Keys;
         interface Keys {
+            default: unknown;
         }
     }
 }
 /**
- * Cron-based recurring job scheduling with distributed lock-based deduplication.
- * Call `RecurringJobs.Provider.create()` with a driver, register it, then use `RecurringJobs.create()` to define jobs
- * and `RecurringJobs.work()` to start the 60-second polling loop. Drivers: `db`, `cache`, `local`.
+ * Cron-based job scheduling backed by the Queue package.
+ * Call `RecurringJobs.Provider.create()` with a queue service, register it, then use `RecurringJobs.createJob()` to define jobs.
  */
 declare const RecurringJobs: {
     Provider: {
-        create: typeof createService;
-        register: (name: RecurringJobs.Provider.Key, item: RecurringJobs.Service) => void;
+        create: typeof create;
+        register: (name: RecurringJobs.Provider.Key, item: RecurringJobs.RecurringJobsService) => void;
         list: () => "default"[];
     };
     provider: typeof provider;
-    work: () => {
-        abort(): Promise<void>;
-    };
-    stopAllWork: () => Promise<void>;
-    create: <Result = any>(config: RecurringJobs.JobConfig<Result>) => void;
-    drivers: {
-        db: typeof DbRecurringJobsDriver;
-        local: typeof localRecurringJobsDriver;
-        cache: typeof cacheRecurringJobsDriver;
-    };
+    startProcessing: () => void;
+    stopProcessing: () => void;
+    list: () => string[];
+    get: <Result>(name: string) => RecurringJobs.RecurringJob<Result> | undefined;
+    createJob: <T>(jobConfig: RecurringJobs.JobConfig<T>) => RecurringJobs.RecurringJob<T>;
 };
 
 export { RecurringJobs };

package/dist/index.js

@@ -1,222 +1,152 @@
 // src/index.ts
-import { instantFns as instantFns2 } from "iso-fns2";
+import "iso-fns2";
 import cronParser from "cron-parser";
+import { Log } from "@maestro-js/log";
 import { ServiceRegistry } from "@maestro-js/service-registry";
-
-// src/db-recurring-jobs-driver.ts
-import { instantFns } from "iso-fns2";
-function DbRecurringJobsDriver({ db, databaseTable }) {
-  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(databaseTable)) {
-    throw new Error(`Invalid databaseTable name: ${databaseTable}`);
-  }
-  async function listLastRunDates(jobNames) {
-    if (jobNames.length === 0) return [];
-    const placeholders = jobNames.map(() => "?").join(", ");
-    const rows = await db.select(`SELECT name, lastRunDate FROM ${databaseTable} WHERE name IN (${placeholders})`, jobNames);
-    return rows.filter((row) => row["lastRunDate"] != null).map((row) => ({
-      jobName: row["name"],
-      date: row["lastRunDate"]
-    }));
-  }
-  async function pullJob({ jobName, date }) {
-    const formattedDate = instantFns.formatISO9075(date);
-    const { changedRows } = await db.update(
-      `UPDATE ${databaseTable} SET lastRunDate = ? WHERE name = ? AND (lastRunDate IS NULL OR lastRunDate < ?)`,
-      [formattedDate, jobName, formattedDate]
-    );
-    if (changedRows > 0) return true;
-    const insert = await db.update(`INSERT IGNORE INTO ${databaseTable} (name, lastRunDate) VALUES (?, ?)`, [
-      jobName,
-      formattedDate
-    ]);
-    return insert.affectedRows > 0;
-  }
-  return { listLastRunDates, pullJob };
-}
-
-// src/local-recurring-jobs-driver.ts
-function localRecurringJobsDriver() {
-  const lastRunDates = /* @__PURE__ */ new Map();
-  async function listLastRunDates(jobNames) {
-    if (jobNames.length === 0) return [];
-    return jobNames.filter((name) => lastRunDates.has(name)).map((name) => ({
-      jobName: name,
-      date: lastRunDates.get(name)
-    }));
-  }
-  async function pullJob({ jobName, date }) {
-    const current = lastRunDates.get(jobName);
-    if (current == null || current < date) {
-      lastRunDates.set(jobName, date);
-      return true;
-    }
-    return false;
-  }
-  return { listLastRunDates, pullJob };
-}
-
-// src/cache-recurring-jobs-driver.ts
-function cacheRecurringJobsDriver({
-  cache,
-  keyPrefix = "recurring-jobs:"
-}) {
-  async function listLastRunDates(jobNames) {
-    if (jobNames.length === 0) return [];
-    const results = await Promise.all(
-      jobNames.map(async (name) => {
-        const date = await cache.get(keyPrefix + name);
-        return date != null ? { jobName: name, date } : null;
+function create(serviceConfig) {
+  const queueService = serviceConfig.queueService;
+  const jobs = [];
+  function createJob(jobConfig) {
+    cronParser.parseExpression(jobConfig.cron);
+    const logger = Log.create({
+      transports: [serviceConfig.logger, ...jobConfig.logger ? [jobConfig.logger] : []]
+    });
+    const queue = queueService.create({
+      name: `RecurringJobs: ${jobConfig.name}`,
+      workFn: async () => {
+        await addJobToQueue(getNextScheduledDate());
+        return jobConfig.workFn();
+      },
+      logger: Log.create({
+        transports: [
+          {
+            write({ data: [message] }) {
+              if (message.event === "messageDequeued") {
+                logger.info({
+                  event: "jobProcessing",
+                  job: jobConfig.name,
+                  driver: message.driver,
+                  messageId: message.messageId
+                });
+              } else if (message.event === "messageProcessed") {
+                logger.info({
+                  event: "jobSucceeded",
+                  job: jobConfig.name,
+                  driver: message.driver,
+                  result: message.result,
+                  messageId: message.messageId
+                });
+              } else if (message.event === "messageFailed") {
+                logger.error({
+                  event: "jobFailed",
+                  job: jobConfig.name,
+                  driver: message.driver,
+                  error: message.error,
+                  messageId: message.messageId
+                });
+              }
+            }
+          }
+        ]
       })
-    );
-    return results.filter((r) => r != null);
-  }
-  async function pullJob({ jobName, date }) {
-    const lock = cache.lock(keyPrefix + "lock:" + jobName, 10);
-    const acquired = await lock.get();
-    if (!acquired) return false;
-    try {
-      const current = await cache.get(keyPrefix + jobName);
-      if (current == null || current < date) {
-        await cache.set(keyPrefix + jobName, date, null);
-        return true;
-      }
-      return false;
-    } finally {
-      await lock.release();
+    });
+    function getNextScheduledDate() {
+      const interval = cronParser.parseExpression(jobConfig.cron);
+      return interval.next().toDate().toISOString();
     }
-  }
-  return { listLastRunDates, pullJob };
-}
-
-// src/index.ts
-function createService({ driver, logger: serviceLogger }) {
-  const allJobs = /* @__PURE__ */ new Map();
-  const logger = serviceLogger;
-  let lastRunDatesCached = null;
-  async function refreshLastRunDates() {
-    const rows = await driver.listLastRunDates([...allJobs.keys()]);
-    const map = /* @__PURE__ */ new Map();
-    for (const row of rows) map.set(row.jobName, row.date);
-    lastRunDatesCached = map;
-    return map;
-  }
-  async function executeJob(job) {
-    const middleware = job.middleware ?? [];
-    const executeFn = middleware.reduceRight(
-      (acc, cur) => {
-        return () => cur(acc);
-      },
-      () => job.handle()
-    );
-    return executeFn();
-  }
-  async function tick() {
-    const now = instantFns2.now();
-    const lastRunDates = lastRunDatesCached ?? await refreshLastRunDates();
-    const jobsToRun = [...allJobs.values()].map((jobConfig) => {
-      const lastRun = lastRunDates.get(jobConfig.name);
-      const cron = cronParser.parseExpression(jobConfig.cron);
-      if (lastRun) {
-        cron.reset(lastRun);
-      }
-      const nextRun = cron.next().toDate().toISOString();
-      return { ...jobConfig, nextRun };
-    }).filter((c) => c.nextRun <= now);
-    for (const job of jobsToRun) {
-      logger?.info({ event: "jobDue", jobName: job.name, nextRun: job.nextRun });
+    async function getNextUp() {
+      const messages = await queue.listMessages({ pageNumber: 0, pageSize: 100 });
+      const result = messages.find((m) => m.status === "waiting");
+      return result ? { ...result, cron: jobConfig.cron } : null;
     }
-    const lockedJobs = [];
-    for (const job of jobsToRun) {
-      try {
-        const haveLock = await driver.pullJob({ jobName: job.name, date: job.nextRun });
-        if (haveLock) {
-          logger?.info({ event: "jobLockAcquired", jobName: job.name, nextRun: job.nextRun });
-          lockedJobs.push(job);
-        }
-      } catch (e) {
-        logger?.error({ event: "jobLockFailed", jobName: job.name, nextRun: job.nextRun, error: e });
-      }
+    async function list2({
+      pageNumber,
+      pageSize
+    }) {
+      const messages = await queue.listMessages({ pageNumber, pageSize });
+      return messages.map((m) => ({ ...m, cron: jobConfig.cron }));
     }
-    if (jobsToRun.length) {
-      lastRunDatesCached = null;
+    async function rescheduleJob({ jobId, scheduledDate }) {
+      const nextUp = await getNextUp();
+      if (!nextUp || nextUp.id !== jobId) {
+        throw new Error(
+          `Cannot reschedule job ${jobId}: only the next waiting job can be rescheduled.` + (nextUp ? ` The current waiting job is ${nextUp.id}.` : " No waiting job found.")
+        );
+      }
+      await queue.updateMessage({ messageId: jobId, scheduledDate, body: {} });
     }
-    const results = await Promise.allSettled(lockedJobs.map(executeJob));
-    for (let i = 0; i < results.length; i++) {
-      if (results[i].status === "rejected") {
-        logger?.error({
-          event: "jobFailed",
-          jobName: lockedJobs[i].name,
-          error: results[i].reason
-        });
-      } else {
-        logger?.info({ event: "jobProcessed", jobName: lockedJobs[i].name });
+    async function addJobToQueue(nextRun) {
+      const data = await getNextUp();
+      if (data) {
+        logger.info({ event: "jobAlreadyScheduled", job: jobConfig.name, existingJobId: data.id });
+        return false;
       }
+      await queue.addMessage({}, { scheduledDate: nextRun, tracingContext: null });
+      logger.info({ event: "jobScheduled", job: jobConfig.name, nextRun });
+      return true;
     }
-  }
-  let abortWorkFunctions = [];
-  function work() {
-    let ticks = [];
-    function doTick() {
-      const promise = tick();
-      ticks.push(promise);
-      promise.finally(() => {
-        ticks = ticks.filter((t) => t !== promise);
-      });
-      return promise.catch((e) => {
+    function startProcessing2() {
+      addJobToQueue(getNextScheduledDate()).catch((error) => {
+        logger.error({ event: "jobSchedulingFailed", job: jobConfig.name, error });
       });
+      queue.startProcessing();
     }
-    doTick();
-    const interval = setInterval(doTick, 6e4);
-    async function abort() {
-      clearInterval(interval);
-      await Promise.all(ticks);
-      abortWorkFunctions = abortWorkFunctions.filter((a) => a !== abort);
+    function stopProcessing2() {
+      queue.stopProcessing();
     }
-    abortWorkFunctions.push(abort);
-    return {
-      abort
+    const jobFunctions = {
+      getNextUp,
+      list: list2,
+      startProcessing: startProcessing2,
+      stopProcessing: stopProcessing2,
+      rescheduleJob,
+      name: jobConfig.name,
+      cron: jobConfig.cron
     };
+    jobs.push(jobFunctions);
+    return jobFunctions;
   }
-  async function stopAllWork() {
-    await Promise.all(abortWorkFunctions.map((w) => w()));
+  function startProcessing() {
+    jobs.forEach((job) => job.startProcessing());
   }
-  function create(config) {
-    cronParser.parseExpression(config.cron);
-    if (allJobs.has(config.name)) {
-      throw new Error(`Cannot have multiple recurring jobs with name "${config.name}"`);
-    }
-    allJobs.set(config.name, config);
+  function stopProcessing() {
+    jobs.forEach((job) => job.stopProcessing());
   }
-  return { work, create, stopAllWork };
+  function list() {
+    return jobs.map((job) => job.name);
+  }
+  function get(name) {
+    return jobs.find((job) => job.name === name);
+  }
+  return { startProcessing, stopProcessing, list, get, createJob };
 }
 var registry = ServiceRegistry.createRegistry(
   ServiceRegistry.proxyFunctionsForObject
 );
 var Provider = {
-  create: createService,
+  create,
   register: registry.register,
   list: registry.list
 };
 function provider(key) {
   const service = registry.resolve(key);
   return {
-    work: service.work,
-    stopAllWork: service.stopAllWork,
-    create: service.create
+    startProcessing: service.startProcessing,
+    stopProcessing: service.stopProcessing,
+    list: service.list,
+    get: service.get,
+    createJob: service.createJob
   };
 }
 var facade = provider("default");
 var RecurringJobs = {
   Provider,
   provider,
-  work: facade.work,
-  stopAllWork: facade.stopAllWork,
-  create: facade.create,
-  drivers: {
-    db: DbRecurringJobsDriver,
-    local: localRecurringJobsDriver,
-    cache: cacheRecurringJobsDriver
-  }
+  startProcessing: facade.startProcessing,
+  stopProcessing: facade.stopProcessing,
+  list: facade.list,
+  get: facade.get,
+  createJob: facade.createJob
 };
 export {
   RecurringJobs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestro-js/recurring-jobs",
-  "description": "Use when working with @maestro-js/recurring-jobs. Cron-based recurring job scheduling with distributed lock-based deduplication. Use for cron scheduling, periodic background tasks, and recurring jobs that must run exactly once across processes. Drivers: Db (MySQL), Cache (Redis via @maestro-js/cache), Local (in-memory). Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, 60-second polling loop, per-job distributed locking, optional middleware wrapping, eager cron validation, structured lifecycle log events (jobDue, jobLockAcquired, jobFailed, jobProcessed), and graceful shutdown via abort/stopAllWork.",
+  "description": "Use when working with @maestro-js/recurring-jobs. Cron-based job scheduling backed by the Queue package. Covers creating recurring jobs, managing schedules, start/stop processing, rescheduling, listing jobs, and inspecting upcoming runs. Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, deduplication across process restarts, per-job dedicated queues, structured log events, and paginated execution history.",
   "type": "module",
   "exports": {
     ".": {
@@ -11,20 +11,14 @@
   "dependencies": {
     "cron-parser": "^4.9.0",
     "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
-    "@maestro-js/service-registry": "1.0.0-alpha.19"
-  },
-  "peerDependencies": {
-    "@maestro-js/log": "1.0.0-alpha.19",
-    "@maestro-js/cache": "1.0.0-alpha.19"
+    "@maestro-js/log": "1.0.0-alpha.2",
+    "@maestro-js/service-registry": "1.0.0-alpha.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
-    "@maestro-js/cache": "1.0.0-alpha.19",
-    "@maestro-js/db": "1.0.0-alpha.19",
-    "@maestro-js/log": "1.0.0-alpha.19",
-    "@maestro-js/queue": "1.0.0-alpha.19"
+    "@maestro-js/queue": "1.0.0-alpha.2"
   },
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.2",
   "publishConfig": {
     "access": "restricted"
   },
@@ -39,7 +33,7 @@
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",
     "typecheck": "tsc --noEmit",
-    "test": "beartest ./tests/**/*",
+    "test": "echo 'No tests yet'",
     "format": "prettier --write src/",
     "lint": "prettier --check src/"
   }