@maestro-js/recurring-jobs 1.0.0-alpha.0 → 1.0.0-alpha.10

package/README.md

@@ -1,348 +1,233 @@
-# RecurringJobs Skill
+# @maestro-js/recurring-jobs
 
-## 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.
+Cron-based recurring job scheduling with distributed lock-based deduplication.
 
 ## 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 the recurring jobs service with a queue service
-const recurringJobsService = RecurringJobs.Provider.create({
-  logger,
-  queueService: Queue.provider('default')
+// Create and register with the local (in-memory) driver
+const service = RecurringJobs.Provider.create({
+  driver: RecurringJobs.drivers.local()
 })
-RecurringJobs.Provider.register('default', recurringJobsService)
+RecurringJobs.Provider.register('default', service)
 
 // Define a recurring job
-const dailyReport = RecurringJobs.createJob({
-  name: 'daily-sales-report',
-  cron: '0 6 * * *',
-  workFn: async () => {
-    const total = await calculateDailySales()
-    return { total }
-  }
+RecurringJobs.create({
+  name: 'send-weekly-digest',
+  cron: '0 9 * * MON',
+  handle: async () => sendDigest()
 })
 
-// Start processing
-dailyReport.startProcessing()
-```
-
-## Cron Expression Format
-
-Uses the `cron-parser` library (v4.x) for standard 5-field cron expressions:
+// Start polling -- fires immediately then every 60 seconds
+const worker = RecurringJobs.work()
 
-```
- ┌───────────── minute (0-59)
- │ ┌───────────── hour (0-23)
- │ │ ┌───────────── day of month (1-31)
- │ │ │ ┌───────────── month (1-12)
- │ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
- │ │ │ │ │
- * * * * *
+// Graceful shutdown
+await worker.abort()
 ```
 
-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
+## Drivers
 
-Invalid cron expressions throw immediately when passed to `createJob()`, since `cron-parser.parseExpression()` is called at creation time.
-
-## API Reference
+### Db
 
-### Provider Setup
-
-#### `RecurringJobs.Provider.create(config)`
-
-Create a recurring jobs service instance.
+MySQL-backed, for multi-process production deployments. Uses `UPDATE ... WHERE lastRunDate < ?`
+and `INSERT IGNORE` for atomic distributed locking.
 
 ```ts
-RecurringJobs.Provider.create(config: {
-  logger: Log.Logger<[RecurringJobs.LogMessage]>
-  queueService: Queue.QueueService
+RecurringJobs.drivers.db({
+  db: Db,              // Db service instance
+  databaseTable: 'recurringJobs'
 })
 ```
 
-- `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)`
+Required table schema:
 
-Register the service instance in the named registry.
-
-```ts
-RecurringJobs.Provider.register('default', recurringJobsService)
+```sql
+CREATE TABLE recurringJobs (
+  name VARCHAR(255) NOT NULL PRIMARY KEY,
+  lastRunDate DATETIME DEFAULT NULL
+);
 ```
 
-#### `RecurringJobs.provider(key)`
-
-Resolve a named instance from the registry. Supports deferred resolution via Proxy.
-
-```ts
-const jobs = RecurringJobs.provider('default')
-```
+Source: `packages/recurring-jobs/src/db-recurring-jobs-driver.ts`
 
-### Service Methods (on the facade or provider instance)
+### Cache
 
-#### `RecurringJobs.createJob(config)`
-
-Create a recurring job with a dedicated queue. Returns a `RecurringJob` handle.
+Redis-backed via `@maestro-js/cache` with distributed locking (`cache.lock()`). Use when you
+already have Redis and don't need MySQL.
 
 ```ts
-RecurringJobs.createJob<T>(config: {
-  name: string
-  cron: string
-  workFn: () => Promise<T>
-  logger?: Log.LogFunctions<[RecurringJobs.LogMessage]>  // optional per-job logger
-}): RecurringJobs.RecurringJob<T>
+RecurringJobs.drivers.cache({
+  cache: cacheService,          // Cache.CacheService instance
+  keyPrefix: 'recurring-jobs:'  // optional, default 'recurring-jobs:'
+})
 ```
 
-Each job creates a queue named `RecurringJobs: <name>`. The cron expression is validated immediately and throws if invalid.
+Source: `packages/recurring-jobs/src/cache-recurring-jobs-driver.ts`
 
-#### `RecurringJobs.startProcessing()`
+### Local
 
-Start processing on all registered recurring jobs.
+In-memory, single-process only. No distributed locking -- every process will run every due job.
+Good for development and testing.
 
 ```ts
-RecurringJobs.startProcessing()
+RecurringJobs.drivers.local()
 ```
 
-#### `RecurringJobs.stopProcessing()`
-
-Stop processing on all registered recurring jobs.
-
-```ts
-RecurringJobs.stopProcessing()
-```
-
-#### `RecurringJobs.list()`
-
-Return the names of all registered recurring jobs.
-
-```ts
-RecurringJobs.list()  // ['daily-sales-report', 'session-cleanup']
-```
+Source: `packages/recurring-jobs/src/local-recurring-jobs-driver.ts`
 
-#### `RecurringJobs.get(name)`
+### Choosing a driver
 
-Return the recurring job with the given name, or `undefined` if not found.
+| 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
-const job = RecurringJobs.get<{ total: number }>('daily-sales-report')
-```
+\* Cache persistence depends on Redis persistence settings.
 
-### RecurringJob Instance Methods
+## API Reference
 
-#### `job.startProcessing()`
+### `RecurringJobs.create(config)`
 
-Enqueue the next scheduled run and begin polling. If a waiting job already exists, it is not duplicated (deduplication).
+Register a recurring job. Throws immediately on invalid cron expression or duplicate job name.
 
 ```ts
-dailyReport.startProcessing()
+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
+})
 ```
 
-#### `job.stopProcessing()`
+### `RecurringJobs.work()`
 
-Stop polling for this job.
+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.
 
 ```ts
-dailyReport.stopProcessing()
-```
-
-#### `job.getNextUp()`
-
-Return the first message in `waiting` status, or `null` if none exists.
+const worker = RecurringJobs.work()
 
-```ts
-const next = await dailyReport.getNextUp()
-// { id: 42, status: 'waiting', scheduledDate: '2026-02-22T06:00:00.000Z', cron: '0 6 * * *', ... }
+// Later, to stop:
+await worker.abort()
 ```
 
-#### `job.list({ pageSize, pageNumber })`
+### `RecurringJobs.stopAllWork()`
 
-Return a paginated list of all messages (past runs and pending) for this job.
+Abort all active work loops and wait for in-flight ticks to finish.
 
 ```ts
-const history = await dailyReport.list({ pageSize: 20, pageNumber: 0 })
-// [{ id: 41, status: 'success', result: { total: 15420 }, ... }, ...]
+await RecurringJobs.stopAllWork()
 ```
 
-#### `job.rescheduleJob({ jobId, scheduledDate })`
+## Common Patterns
 
-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.
+### Basic cron job
 
 ```ts
-await dailyReport.rescheduleJob({
-  jobId: 42,
-  scheduledDate: '2026-02-22T08:00:00.000Z' as Iso.Instant
+RecurringJobs.create({
+  name: 'cleanup-expired-tokens',
+  cron: '0 3 * * *', // daily at 3am
+  handle: async () => {
+    await db.update('DELETE FROM tokens WHERE expiresAt < NOW()')
+  }
 })
 ```
 
-#### `job.name` / `job.cron`
-
-Read-only properties exposing the job's name and cron expression.
+### Middleware wrapping
 
 ```ts
-dailyReport.name  // 'daily-sales-report'
-dailyReport.cron  // '0 6 * * *'
+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()
+})
 ```
 
-### JobMessage Interface
-
-Each queue message returned by `getNextUp()` and `list()` has these fields:
+### Graceful shutdown
 
 ```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
-}
-```
+const worker = RecurringJobs.work()
 
-## Common Patterns
-
-### Multiple Recurring Jobs
-
-```ts
-const report = RecurringJobs.createJob({
-  name: 'daily-report',
-  cron: '0 6 * * *',
-  workFn: async () => generateReport()
+process.on('SIGTERM', async () => {
+  await worker.abort()   // waits for in-flight tick to finish
+  process.exit(0)
 })
 
-const cleanup = RecurringJobs.createJob({
-  name: 'session-cleanup',
-  cron: '0 0 * * *',
-  workFn: async () => cleanStaleSessions()
+// Or abort all workers at once:
+process.on('SIGTERM', async () => {
+  await RecurringJobs.stopAllWork()
+  process.exit(0)
 })
-
-// Start all jobs at once
-RecurringJobs.startProcessing()
-
-// Or start individually
-report.startProcessing()
-cleanup.startProcessing()
 ```
 
-### Inspecting and Rescheduling
+### Named provider instances
 
 ```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
-    })
-  }
-}
-```
-
-### Per-Job Logger
-
-Add a dedicated logger to a specific job for fine-grained observability:
-
-```ts
-const jobLogger: Log.LogFunctions<[RecurringJobs.LogMessage]> = {
-  write({ data: [msg] }) {
-    if (msg.event === 'jobFailed') {
-      alertOpsTeam(msg.job, msg.error)
-    }
-  }
-}
-
-const criticalJob = RecurringJobs.createJob({
-  name: 'payment-reconciliation',
-  cron: '0 */4 * * *',
-  workFn: async () => reconcilePayments(),
-  logger: jobLogger
+const primary = RecurringJobs.Provider.create({
+  driver: RecurringJobs.drivers.db({ db: Db, databaseTable: 'recurringJobs' })
 })
-```
+RecurringJobs.Provider.register('default', primary)
 
-### Execution History
+const secondary = RecurringJobs.Provider.create({
+  driver: RecurringJobs.drivers.local()
+})
+RecurringJobs.Provider.register('dev', secondary)
 
-```ts
-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
-}
+RecurringJobs.provider('dev').create({ ... })
 ```
 
-## Log Events
-
-The service emits structured log events of type `RecurringJobs.LogMessage`:
+## Warnings and Gotchas
 
-| 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 |
+- **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.
 
 ## 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
+- **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)
 
-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.
+## Driver Interface
 
-Queue itself depends on Db (MySQL) for message persistence, so the full dependency chain is:
+Implement `RecurringJobs.Driver` to create a custom backend:
 
+```ts
+interface Driver {
+  listLastRunDates(jobNames: string[]): Promise<{ jobName: string; date: Iso.Instant }[]>
+  pullJob(options: { jobName: string; date: Iso.Instant }): Promise<boolean>
+}
 ```
-RecurringJobs -> Queue -> Db (MySQL)
-              -> Log
-              -> ServiceRegistry
-```
-
-### Provider Pattern
 
-This package follows the standard maestro Provider pattern:
+`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.
 
-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
+Source: `packages/recurring-jobs/src/index.ts`
 
-## Notes
+## Key Source Files
 
-- 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.
+- `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

package/dist/index.d.ts

@@ -1,200 +1,167 @@
 import { Iso } from 'iso-fns2';
-import { Queue } from '@maestro-js/queue';
 import { Log } from '@maestro-js/log';
+import { Cache } from '@maestro-js/cache';
 
-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>;
+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;
 };
+type KeysWithFallback = keyof RecurringJobs.Provider.Keys extends never ? {
+    default: unknown;
+} : RecurringJobs.Provider.Keys;
 declare function provider(key: RecurringJobs.Provider.Key): {
-    startProcessing: () => void;
-    stopProcessing: () => void;
-    list: () => string[];
-    get: <Result>(name: string) => RecurringJobs.RecurringJob<Result> | undefined;
-    createJob: <T>(jobConfig: RecurringJobs.JobConfig<T>) => RecurringJobs.RecurringJob<T>;
+    work: () => {
+        abort(): Promise<void>;
+    };
+    stopAllWork: () => Promise<void>;
+    create: <Result = any>(config: RecurringJobs.JobConfig<Result>) => void;
 };
 /**
- * Cron-based job scheduling backed by the Queue package.
+ * 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.
  *
- * 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.
+ * Three built-in drivers: `db` (MySQL row-level locking), `cache` (Redis via @maestro-js/cache),
+ * `local` (in-memory, no distributed locking).
  *
  * @example
  * ```ts
- * // 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 }
- *   }
- * })
+ * RecurringJobs.Provider.register('default', RecurringJobs.Provider.create({
+ *   driver: RecurringJobs.drivers.db({ db: Db, databaseTable: 'recurringJobs' })
+ * }))
  *
- * // Start processing and inspect upcoming runs
- * salesReport.startProcessing()
- * const next = await salesReport.getNextUp()  // { status: 'waiting', scheduledDate: '...' }
+ * RecurringJobs.create({
+ *   name: 'send-weekly-digest',
+ *   cron: '0 9 * * MON',
+ *   handle: async () => sendDigest()
+ * })
  *
- * // List all registered jobs
- * RecurringJobs.list() // ['daily-sales-report']
+ * const worker = RecurringJobs.work()
+ * // Later: await worker.abort()
  * ```
  */
 declare namespace RecurringJobs {
-    /** 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;
+    /** 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 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 */
+    /** Per-job configuration passed to {@link Service.create} */
+    interface JobConfig<Result = any> {
+        /** Cron expression defining the schedule (e.g. '0 9 * * MON') */
         cron: string;
-        /** 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>;
+        /** Async handler invoked when the job is due */
+        handle(): Promise<Result>;
+        /** Unique name identifying this job across processes */
         name: string;
-        logger?: Log.LogFunctions<[LogMessage]>;
+        /** Optional middleware chain wrapping the handler */
+        middleware?: Middleware<Result>[];
     }
     /**
-     * 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>`.
+     * Core recurring jobs service returned by {@link RecurringJobs.Provider.create}.
      *
-     * @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
-     * ```
+     * 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.
      */
-    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;
+    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;
     }
     namespace Provider {
-        /** Service-level configuration passed to `RecurringJobs.Provider.create()` */
-        interface RecurringJobsServiceConfig {
-            logger: Log.Logger<[RecurringJobs.LogMessage]>;
-            queueService: Queue.QueueService;
+        interface ServiceConfig {
+            driver: Driver;
+            logger?: Log.Logger<[LogMessage]>;
         }
-        type Key = keyof Keys;
+        type Key = keyof KeysWithFallback;
         interface Keys {
-            default: unknown;
         }
     }
 }
 /**
- * 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.
+ * 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`.
  */
 declare const RecurringJobs: {
     Provider: {
-        create: typeof create;
-        register: (name: RecurringJobs.Provider.Key, item: RecurringJobs.RecurringJobsService) => void;
+        create: typeof createService;
+        register: (name: RecurringJobs.Provider.Key, item: RecurringJobs.Service) => void;
         list: () => "default"[];
     };
     provider: typeof provider;
-    startProcessing: () => void;
-    stopProcessing: () => void;
-    list: () => string[];
-    get: <Result>(name: string) => RecurringJobs.RecurringJob<Result> | undefined;
-    createJob: <T>(jobConfig: RecurringJobs.JobConfig<T>) => RecurringJobs.RecurringJob<T>;
+    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;
+    };
 };
 
 export { RecurringJobs };

package/dist/index.js

@@ -1,152 +1,222 @@
 // src/index.ts
-import "iso-fns2";
+import { instantFns as instantFns2 } from "iso-fns2";
 import cronParser from "cron-parser";
-import { Log } from "@maestro-js/log";
 import { ServiceRegistry } from "@maestro-js/service-registry";
-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
-                });
-              }
-            }
-          }
-        ]
-      })
-    });
-    function getNextScheduledDate() {
-      const interval = cronParser.parseExpression(jobConfig.cron);
-      return interval.next().toDate().toISOString();
+
+// 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;
     }
-    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;
+    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;
+      })
+    );
+    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();
     }
-    async function list2({
-      pageNumber,
-      pageSize
-    }) {
-      const messages = await queue.listMessages({ pageNumber, pageSize });
-      return messages.map((m) => ({ ...m, cron: jobConfig.cron }));
+  }
+  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 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.")
-        );
+    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 });
       }
-      await queue.updateMessage({ messageId: jobId, scheduledDate, body: {} });
     }
-    async function addJobToQueue(nextRun) {
-      const data = await getNextUp();
-      if (data) {
-        logger.info({ event: "jobAlreadyScheduled", job: jobConfig.name, existingJobId: data.id });
-        return false;
+    if (jobsToRun.length) {
+      lastRunDatesCached = null;
+    }
+    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 });
       }
-      await queue.addMessage({}, { scheduledDate: nextRun, tracingContext: null });
-      logger.info({ event: "jobScheduled", job: jobConfig.name, nextRun });
-      return true;
     }
-    function startProcessing2() {
-      addJobToQueue(getNextScheduledDate()).catch((error) => {
-        logger.error({ event: "jobSchedulingFailed", job: jobConfig.name, error });
+  }
+  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) => {
       });
-      queue.startProcessing();
     }
-    function stopProcessing2() {
-      queue.stopProcessing();
+    doTick();
+    const interval = setInterval(doTick, 6e4);
+    async function abort() {
+      clearInterval(interval);
+      await Promise.all(ticks);
+      abortWorkFunctions = abortWorkFunctions.filter((a) => a !== abort);
     }
-    const jobFunctions = {
-      getNextUp,
-      list: list2,
-      startProcessing: startProcessing2,
-      stopProcessing: stopProcessing2,
-      rescheduleJob,
-      name: jobConfig.name,
-      cron: jobConfig.cron
+    abortWorkFunctions.push(abort);
+    return {
+      abort
     };
-    jobs.push(jobFunctions);
-    return jobFunctions;
-  }
-  function startProcessing() {
-    jobs.forEach((job) => job.startProcessing());
   }
-  function stopProcessing() {
-    jobs.forEach((job) => job.stopProcessing());
+  async function stopAllWork() {
+    await Promise.all(abortWorkFunctions.map((w) => w()));
   }
-  function list() {
-    return jobs.map((job) => job.name);
-  }
-  function get(name) {
-    return jobs.find((job) => job.name === name);
+  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);
   }
-  return { startProcessing, stopProcessing, list, get, createJob };
+  return { work, create, stopAllWork };
 }
 var registry = ServiceRegistry.createRegistry(
   ServiceRegistry.proxyFunctionsForObject
 );
 var Provider = {
-  create,
+  create: createService,
   register: registry.register,
   list: registry.list
 };
 function provider(key) {
   const service = registry.resolve(key);
   return {
-    startProcessing: service.startProcessing,
-    stopProcessing: service.stopProcessing,
-    list: service.list,
-    get: service.get,
-    createJob: service.createJob
+    work: service.work,
+    stopAllWork: service.stopAllWork,
+    create: service.create
   };
 }
 var facade = provider("default");
 var RecurringJobs = {
   Provider,
   provider,
-  startProcessing: facade.startProcessing,
-  stopProcessing: facade.stopProcessing,
-  list: facade.list,
-  get: facade.get,
-  createJob: facade.createJob
+  work: facade.work,
+  stopAllWork: facade.stopAllWork,
+  create: facade.create,
+  drivers: {
+    db: DbRecurringJobsDriver,
+    local: localRecurringJobsDriver,
+    cache: cacheRecurringJobsDriver
+  }
 };
 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 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.",
+  "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.",
   "type": "module",
   "exports": {
     ".": {
@@ -11,14 +11,20 @@
   "dependencies": {
     "cron-parser": "^4.9.0",
     "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
-    "@maestro-js/service-registry": "1.0.0-alpha.0",
-    "@maestro-js/log": "1.0.0-alpha.0"
+    "@maestro-js/service-registry": "1.0.0-alpha.10"
+  },
+  "peerDependencies": {
+    "@maestro-js/cache": "1.0.0-alpha.10",
+    "@maestro-js/log": "1.0.0-alpha.10"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
-    "@maestro-js/queue": "1.0.0-alpha.0"
+    "@maestro-js/cache": "1.0.0-alpha.10",
+    "@maestro-js/db": "1.0.0-alpha.10",
+    "@maestro-js/log": "1.0.0-alpha.10",
+    "@maestro-js/queue": "1.0.0-alpha.10"
   },
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.10",
   "publishConfig": {
     "access": "restricted"
   },
@@ -33,7 +39,7 @@
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",
     "typecheck": "tsc --noEmit",
-    "test": "echo 'No tests yet'",
+    "test": "beartest ./tests/**/*",
     "format": "prettier --write src/",
     "lint": "prettier --check src/"
   }