@strav/queue 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@strav/queue",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Background job processing and task scheduling for the Strav framework",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "framework",
+    "typescript",
+    "strav",
+    "queue",
+    "scheduler"
+  ],
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./queue": "./src/queue/index.ts",
+    "./queue/*": "./src/queue/*.ts",
+    "./scheduler": "./src/scheduler/index.ts",
+    "./scheduler/*": "./src/scheduler/*.ts",
+    "./providers": "./src/providers/index.ts",
+    "./providers/*": "./src/providers/*.ts"
+  },
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/database": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './queue/index.ts'
+export * from './scheduler/index.ts'
+export * from './providers/index.ts'

package/src/providers/index.ts

@@ -0,0 +1,3 @@
+export { default as QueueProvider } from './queue_provider.ts'
+
+export type { QueueProviderOptions } from './queue_provider.ts'

package/src/providers/queue_provider.ts

@@ -0,0 +1,29 @@
+import ServiceProvider from '@stravigor/kernel/core/service_provider'
+import type Application from '@stravigor/kernel/core/application'
+import Queue from '../queue/queue.ts'
+
+export interface QueueProviderOptions {
+  /** Whether to auto-create the jobs tables. Default: `true` */
+  ensureTables?: boolean
+}
+
+export default class QueueProvider extends ServiceProvider {
+  readonly name = 'queue'
+  override readonly dependencies = ['database']
+
+  constructor(private options?: QueueProviderOptions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(Queue)
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Queue)
+
+    if (this.options?.ensureTables !== false) {
+      await Queue.ensureTables()
+    }
+  }
+}

package/src/queue/index.ts

@@ -0,0 +1,11 @@
+export { default as Queue } from './queue.ts'
+export { default as Worker } from './worker.ts'
+export type {
+  JobOptions,
+  QueueConfig,
+  JobMeta,
+  JobRecord,
+  FailedJobRecord,
+  JobHandler,
+} from './queue.ts'
+export type { WorkerOptions } from './worker.ts'

package/src/queue/queue.ts

@@ -0,0 +1,347 @@
+import { inject } from '@stravigor/kernel/core/inject'
+import Configuration from '@stravigor/kernel/config/configuration'
+import Database from '@stravigor/database/database/database'
+import Emitter from '@stravigor/kernel/events/emitter'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+
+export interface JobOptions {
+  queue?: string
+  delay?: number
+  attempts?: number
+  timeout?: number
+}
+
+export interface QueueConfig {
+  default: string
+  maxAttempts: number
+  timeout: number
+  retryBackoff: 'exponential' | 'linear'
+  sleep: number
+}
+
+/** Metadata passed to job handlers alongside the payload. */
+export interface JobMeta {
+  id: number
+  queue: string
+  job: string
+  attempts: number
+  maxAttempts: number
+}
+
+/** A raw job row from the _strav_jobs table. */
+export interface JobRecord {
+  id: number
+  queue: string
+  job: string
+  payload: unknown
+  attempts: number
+  maxAttempts: number
+  timeout: number
+  availableAt: Date
+  reservedAt: Date | null
+  createdAt: Date
+}
+
+/** A raw row from the _strav_failed_jobs table. */
+export interface FailedJobRecord {
+  id: number
+  queue: string
+  job: string
+  payload: unknown
+  error: string
+  failedAt: Date
+}
+
+export type JobHandler<T = any> = (payload: T, meta: JobMeta) => void | Promise<void>
+
+/**
+ * PostgreSQL-backed job queue.
+ *
+ * Resolved once via the DI container — stores the database reference
+ * and parsed config for Worker and all static methods.
+ *
+ * @example
+ * app.singleton(Queue)
+ * app.resolve(Queue)
+ * await Queue.ensureTables()
+ *
+ * Queue.handle('send-email', async (payload) => { ... })
+ * await Queue.push('send-email', { to: 'user@example.com' })
+ */
+@inject
+export default class Queue {
+  private static _db: Database
+  private static _config: QueueConfig
+  private static _handlers = new Map<string, JobHandler>()
+
+  constructor(db: Database, config: Configuration) {
+    Queue._db = db
+    Queue._config = {
+      default: config.get('queue.default', 'default') as string,
+      maxAttempts: config.get('queue.maxAttempts', 3) as number,
+      timeout: config.get('queue.timeout', 60_000) as number,
+      retryBackoff: config.get('queue.retryBackoff', 'exponential') as 'exponential' | 'linear',
+      sleep: config.get('queue.sleep', 1000) as number,
+    }
+  }
+
+  static get db(): Database {
+    if (!Queue._db)
+      throw new ConfigurationError(
+        'Queue not configured. Resolve Queue through the container first.'
+      )
+    return Queue._db
+  }
+
+  static get config(): QueueConfig {
+    return Queue._config
+  }
+
+  static get handlers(): Map<string, JobHandler> {
+    return Queue._handlers
+  }
+
+  /** Create the internal jobs and failed_jobs tables if they don't exist. */
+  static async ensureTables(): Promise<void> {
+    const sql = Queue.db.sql
+
+    await sql`
+      CREATE TABLE IF NOT EXISTS "_strav_jobs" (
+        "id" BIGSERIAL PRIMARY KEY,
+        "queue" VARCHAR(255) NOT NULL DEFAULT 'default',
+        "job" VARCHAR(255) NOT NULL,
+        "payload" JSONB NOT NULL DEFAULT '{}',
+        "attempts" INT NOT NULL DEFAULT 0,
+        "max_attempts" INT NOT NULL DEFAULT 3,
+        "timeout" INT NOT NULL DEFAULT 60000,
+        "available_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "reserved_at" TIMESTAMPTZ,
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+
+    await sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_jobs_queue_available"
+        ON "_strav_jobs" ("queue", "available_at")
+        WHERE "reserved_at" IS NULL
+    `
+
+    await sql`
+      CREATE TABLE IF NOT EXISTS "_strav_failed_jobs" (
+        "id" BIGSERIAL PRIMARY KEY,
+        "queue" VARCHAR(255) NOT NULL,
+        "job" VARCHAR(255) NOT NULL,
+        "payload" JSONB NOT NULL DEFAULT '{}',
+        "error" TEXT NOT NULL,
+        "failed_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+  }
+
+  /** Register a handler for a named job. */
+  static handle<T = any>(name: string, handler: JobHandler<T>): void {
+    Queue._handlers.set(name, handler)
+  }
+
+  /**
+   * Push a job onto the queue. Returns the job ID.
+   */
+  static async push<T = any>(name: string, payload: T, options?: JobOptions): Promise<number> {
+    const sql = Queue.db.sql
+    const queue = options?.queue ?? Queue._config.default
+    const maxAttempts = options?.attempts ?? Queue._config.maxAttempts
+    const timeout = options?.timeout ?? Queue._config.timeout
+    const availableAt = options?.delay ? new Date(Date.now() + options.delay) : new Date()
+
+    const rows = await sql`
+      INSERT INTO "_strav_jobs" ("queue", "job", "payload", "max_attempts", "timeout", "available_at")
+      VALUES (${queue}, ${name}, ${JSON.stringify(payload)}, ${maxAttempts}, ${timeout}, ${availableAt})
+      RETURNING "id"
+    `
+
+    const id = Number((rows[0] as Record<string, unknown>).id)
+
+    if (Emitter.listenerCount('queue:dispatched') > 0) {
+      Emitter.emit('queue:dispatched', { id, name, queue, payload }).catch(() => {})
+    }
+
+    return id
+  }
+
+  /**
+   * Create a listener function suitable for Emitter.on().
+   * When the event fires, the payload is pushed onto the queue.
+   *
+   * @example
+   * Emitter.on('user.registered', Queue.listener('send-welcome-email'))
+   */
+  static listener(jobName: string, options?: JobOptions): (payload: any) => Promise<void> {
+    return async (payload: any) => {
+      await Queue.push(jobName, payload, options)
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Introspection / Management
+  // ---------------------------------------------------------------------------
+
+  /** Count of pending (unreserved) jobs in a queue. */
+  static async size(queue?: string): Promise<number> {
+    const sql = Queue.db.sql
+    const q = queue ?? Queue._config.default
+
+    const rows = await sql`
+      SELECT COUNT(*)::int AS count FROM "_strav_jobs"
+      WHERE "queue" = ${q} AND "reserved_at" IS NULL
+    `
+    return (rows[0] as Record<string, unknown>).count as number
+  }
+
+  /** List pending jobs, most recent first. */
+  static async pending(queue?: string, limit = 25): Promise<JobRecord[]> {
+    const sql = Queue.db.sql
+    const q = queue ?? Queue._config.default
+
+    const rows = await sql`
+      SELECT * FROM "_strav_jobs"
+      WHERE "queue" = ${q}
+      ORDER BY "available_at" ASC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateJob)
+  }
+
+  /** List failed jobs, most recent first. */
+  static async failed(queue?: string, limit = 25): Promise<FailedJobRecord[]> {
+    const sql = Queue.db.sql
+
+    if (queue) {
+      const rows = await sql`
+        SELECT * FROM "_strav_failed_jobs"
+        WHERE "queue" = ${queue}
+        ORDER BY "failed_at" DESC
+        LIMIT ${limit}
+      `
+      return rows.map(hydrateFailedJob)
+    }
+
+    const rows = await sql`
+      SELECT * FROM "_strav_failed_jobs"
+      ORDER BY "failed_at" DESC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateFailedJob)
+  }
+
+  /** Delete all pending jobs in a queue. Returns the number deleted. */
+  static async clear(queue?: string): Promise<number> {
+    const sql = Queue.db.sql
+    const q = queue ?? Queue._config.default
+
+    const rows = await sql`
+      DELETE FROM "_strav_jobs" WHERE "queue" = ${q}
+    `
+    return rows.count
+  }
+
+  /** Move all failed jobs back to the jobs table. Returns the number retried. */
+  static async retryFailed(queue?: string): Promise<number> {
+    const sql = Queue.db.sql
+
+    if (queue) {
+      const failed = await sql`
+        DELETE FROM "_strav_failed_jobs" WHERE "queue" = ${queue} RETURNING *
+      `
+      for (const row of failed) {
+        const r = row as Record<string, unknown>
+        await sql`
+          INSERT INTO "_strav_jobs" ("queue", "job", "payload", "max_attempts")
+          VALUES (${r.queue}, ${r.job}, ${typeof r.payload === 'string' ? r.payload : JSON.stringify(r.payload)}, ${Queue._config.maxAttempts})
+        `
+      }
+      return failed.length
+    }
+
+    const failed = await sql`
+      DELETE FROM "_strav_failed_jobs" RETURNING *
+    `
+    for (const row of failed) {
+      const r = row as Record<string, unknown>
+      await sql`
+        INSERT INTO "_strav_jobs" ("queue", "job", "payload", "max_attempts")
+        VALUES (${r.queue}, ${r.job}, ${typeof r.payload === 'string' ? r.payload : JSON.stringify(r.payload)}, ${Queue._config.maxAttempts})
+      `
+    }
+    return failed.length
+  }
+
+  /** Delete all failed jobs for a queue (or all queues). Returns the number deleted. */
+  static async clearFailed(queue?: string): Promise<number> {
+    const sql = Queue.db.sql
+
+    if (queue) {
+      const rows = await sql`
+        DELETE FROM "_strav_failed_jobs" WHERE "queue" = ${queue}
+      `
+      return rows.count
+    }
+
+    const rows = await sql`
+      DELETE FROM "_strav_failed_jobs"
+    `
+    return rows.count
+  }
+
+  /** Delete all jobs and failed jobs across all queues. For dev/test only. */
+  static async flush(): Promise<void> {
+    const sql = Queue.db.sql
+    await sql`DELETE FROM "_strav_jobs"`
+    await sql`DELETE FROM "_strav_failed_jobs"`
+  }
+
+  /** Reset static state. For testing only. */
+  static reset(): void {
+    Queue._handlers.clear()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hydration helpers
+// ---------------------------------------------------------------------------
+
+function parsePayload(raw: unknown): unknown {
+  if (typeof raw === 'string') {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      return raw
+    }
+  }
+  return raw
+}
+
+export function hydrateJob(row: Record<string, unknown>): JobRecord {
+  return {
+    id: Number(row.id),
+    queue: row.queue as string,
+    job: row.job as string,
+    payload: parsePayload(row.payload),
+    attempts: row.attempts as number,
+    maxAttempts: row.max_attempts as number,
+    timeout: row.timeout as number,
+    availableAt: row.available_at as Date,
+    reservedAt: (row.reserved_at as Date) ?? null,
+    createdAt: row.created_at as Date,
+  }
+}
+
+function hydrateFailedJob(row: Record<string, unknown>): FailedJobRecord {
+  return {
+    id: Number(row.id),
+    queue: row.queue as string,
+    job: row.job as string,
+    payload: parsePayload(row.payload),
+    error: row.error as string,
+    failedAt: row.failed_at as Date,
+  }
+}

package/src/queue/worker.ts

@@ -0,0 +1,221 @@
+import Queue, { hydrateJob } from './queue.ts'
+import Emitter from '@stravigor/kernel/events/emitter'
+import type { JobRecord, JobMeta } from './queue.ts'
+
+export interface WorkerOptions {
+  queue?: string
+  sleep?: number
+}
+
+/**
+ * Processes jobs from the queue.
+ *
+ * Uses `SELECT ... FOR UPDATE SKIP LOCKED` for safe concurrent polling.
+ * Supports job timeouts, exponential/linear backoff for retries,
+ * and graceful shutdown on SIGINT/SIGTERM.
+ *
+ * @example
+ * const worker = new Worker({ queue: 'emails', sleep: 500 })
+ * await worker.start() // blocks until worker.stop() is called
+ */
+export default class Worker {
+  private running = false
+  private processing = false
+  private queue: string
+  private sleep: number
+
+  constructor(options: WorkerOptions = {}) {
+    this.queue = options.queue ?? Queue.config.default
+    this.sleep = options.sleep ?? Queue.config.sleep
+  }
+
+  /** Start the worker loop. Blocks until stop() is called. */
+  async start(): Promise<void> {
+    this.running = true
+
+    const onSignal = () => this.stop()
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+
+    let pollCount = 0
+
+    try {
+      while (this.running) {
+        // Periodically release stale jobs (every 60 cycles)
+        if (pollCount % 60 === 0) {
+          await this.releaseStaleJobs()
+        }
+        pollCount++
+
+        const job = await this.fetchNext()
+        if (job) {
+          this.processing = true
+          await this.process(job)
+          this.processing = false
+        } else {
+          await Bun.sleep(this.sleep)
+        }
+      }
+    } finally {
+      process.off('SIGINT', onSignal)
+      process.off('SIGTERM', onSignal)
+    }
+  }
+
+  /** Signal the worker to stop after the current job completes. */
+  stop(): void {
+    this.running = false
+  }
+
+  /** Whether the worker is currently processing a job. */
+  get busy(): boolean {
+    return this.processing
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Fetch the next available job using FOR UPDATE SKIP LOCKED.
+   * Atomically reserves it by setting reserved_at and incrementing attempts.
+   */
+  private async fetchNext(): Promise<JobRecord | null> {
+    const sql = Queue.db.sql
+
+    const rows = await sql.begin(async (tx: any) => {
+      const result = await tx`
+        SELECT * FROM "_strav_jobs"
+        WHERE "queue" = ${this.queue}
+          AND "available_at" <= NOW()
+          AND "reserved_at" IS NULL
+        ORDER BY "available_at" ASC
+        LIMIT 1
+        FOR UPDATE SKIP LOCKED
+      `
+      if (result.length === 0) return []
+
+      const job = result[0] as Record<string, unknown>
+      await tx`
+        UPDATE "_strav_jobs"
+        SET "reserved_at" = NOW(), "attempts" = "attempts" + 1
+        WHERE "id" = ${job.id}
+      `
+      return [{ ...job, attempts: (job.attempts as number) + 1 }]
+    })
+
+    return rows.length > 0 ? hydrateJob(rows[0] as Record<string, unknown>) : null
+  }
+
+  /** Process a single job: run handler, handle success/failure. */
+  private async process(job: JobRecord): Promise<void> {
+    const handler = Queue.handlers.get(job.job)
+
+    if (!handler) {
+      await this.fail(job, new Error(`No handler registered for job "${job.job}"`))
+      return
+    }
+
+    const meta: JobMeta = {
+      id: job.id,
+      queue: job.queue,
+      job: job.job,
+      attempts: job.attempts,
+      maxAttempts: job.maxAttempts,
+    }
+
+    const start = performance.now()
+
+    try {
+      await Promise.race([
+        Promise.resolve(handler(job.payload, meta)),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error(`Job "${job.job}" timed out after ${job.timeout}ms`)),
+            job.timeout
+          )
+        ),
+      ])
+      await this.complete(job)
+
+      if (Emitter.listenerCount('queue:processed') > 0) {
+        const duration = performance.now() - start
+        Emitter.emit('queue:processed', {
+          job: job.job,
+          id: job.id,
+          queue: job.queue,
+          duration,
+        }).catch(() => {})
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error))
+      if (job.attempts >= job.maxAttempts) {
+        await this.fail(job, err)
+
+        if (Emitter.listenerCount('queue:failed') > 0) {
+          const duration = performance.now() - start
+          Emitter.emit('queue:failed', {
+            job: job.job,
+            id: job.id,
+            queue: job.queue,
+            error: err.message,
+            duration,
+          }).catch(() => {})
+        }
+      } else {
+        await this.release(job)
+      }
+    }
+  }
+
+  /** Delete a completed job. */
+  private async complete(job: JobRecord): Promise<void> {
+    await Queue.db.sql`DELETE FROM "_strav_jobs" WHERE "id" = ${job.id}`
+  }
+
+  /** Move a job to the failed_jobs table and delete from jobs. */
+  private async fail(job: JobRecord, error: Error): Promise<void> {
+    const sql = Queue.db.sql
+    await sql.begin(async (tx: any) => {
+      await tx`
+        INSERT INTO "_strav_failed_jobs" ("queue", "job", "payload", "error")
+        VALUES (${job.queue}, ${job.job}, ${JSON.stringify(job.payload)}, ${error.message})
+      `
+      await tx`DELETE FROM "_strav_jobs" WHERE "id" = ${job.id}`
+    })
+  }
+
+  /** Release a job back to the queue with incremented backoff delay. */
+  private async release(job: JobRecord): Promise<void> {
+    const delay = this.backoffDelay(job.attempts)
+    const availableAt = new Date(Date.now() + delay)
+
+    await Queue.db.sql`
+      UPDATE "_strav_jobs"
+      SET "reserved_at" = NULL, "available_at" = ${availableAt}
+      WHERE "id" = ${job.id}
+    `
+  }
+
+  /** Calculate backoff delay in ms based on attempt number. */
+  backoffDelay(attempts: number): number {
+    if (Queue.config.retryBackoff === 'linear') {
+      return attempts * 5_000
+    }
+    // Exponential: 2^attempts * 1000, with jitter
+    const base = Math.pow(2, attempts) * 1000
+    const jitter = Math.random() * 1000
+    return base + jitter
+  }
+
+  /** Release jobs that have been reserved for too long (crashed workers). */
+  private async releaseStaleJobs(): Promise<void> {
+    await Queue.db.sql`
+      UPDATE "_strav_jobs"
+      SET "reserved_at" = NULL
+      WHERE "reserved_at" IS NOT NULL
+        AND "queue" = ${this.queue}
+        AND "reserved_at" < NOW() - MAKE_INTERVAL(secs => "timeout" * 2.0 / 1000)
+    `
+  }
+}

package/src/scheduler/cron.ts

@@ -0,0 +1,146 @@
+/**
+ * Minimal 5-field cron expression parser.
+ *
+ * Supports: `*`, exact (`5`), range (`1-5`), list (`1,3,5`),
+ * step (`*​/10`), and range+step (`1-30/5`).
+ *
+ * Fields: minute (0–59), hour (0–23), day-of-month (1–31),
+ * month (1–12), day-of-week (0–6, 0 = Sunday).
+ */
+
+export interface CronExpression {
+  minute: number[]
+  hour: number[]
+  dayOfMonth: number[]
+  month: number[]
+  dayOfWeek: number[]
+}
+
+const FIELD_RANGES: [number, number][] = [
+  [0, 59], // minute
+  [0, 23], // hour
+  [1, 31], // day of month
+  [1, 12], // month
+  [0, 6], // day of week
+]
+
+// Parse a 5-field cron string into expanded numeric arrays.
+export function parseCron(expression: string): CronExpression {
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new Error(
+      `Invalid cron expression "${expression}": expected 5 fields, got ${parts.length}`
+    )
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts.map((part, i) =>
+    parseField(part, FIELD_RANGES[i]![0], FIELD_RANGES[i]![1])
+  )
+
+  return {
+    minute: minute!,
+    hour: hour!,
+    dayOfMonth: dayOfMonth!,
+    month: month!,
+    dayOfWeek: dayOfWeek!,
+  }
+}
+
+/**
+ * Check if a Date matches a parsed cron expression.
+ *
+ * Standard cron rule: if both day-of-month and day-of-week are restricted
+ * (not wildcards), either match satisfies the condition.
+ */
+export function cronMatches(cron: CronExpression, date: Date): boolean {
+  const minute = date.getUTCMinutes()
+  const hour = date.getUTCHours()
+  const dayOfMonth = date.getUTCDate()
+  const month = date.getUTCMonth() + 1
+  const dayOfWeek = date.getUTCDay()
+
+  if (!cron.minute.includes(minute)) return false
+  if (!cron.hour.includes(hour)) return false
+  if (!cron.month.includes(month)) return false
+
+  // Standard cron: day-of-month and day-of-week are OR'd when both are restricted
+  const domRestricted = cron.dayOfMonth.length < 31
+  const dowRestricted = cron.dayOfWeek.length < 7
+
+  if (domRestricted && dowRestricted) {
+    return cron.dayOfMonth.includes(dayOfMonth) || cron.dayOfWeek.includes(dayOfWeek)
+  }
+
+  if (!cron.dayOfMonth.includes(dayOfMonth)) return false
+  if (!cron.dayOfWeek.includes(dayOfWeek)) return false
+
+  return true
+}
+
+/**
+ * Compute the next Date (UTC) after `after` that matches the expression.
+ * Searches up to 2 years ahead to prevent infinite loops.
+ */
+export function nextCronDate(cron: CronExpression, after: Date): Date {
+  const date = new Date(after.getTime())
+  // Advance to the next whole minute
+  date.setUTCSeconds(0, 0)
+  date.setUTCMinutes(date.getUTCMinutes() + 1)
+
+  const limit = after.getTime() + 2 * 365 * 24 * 60 * 60 * 1000
+
+  while (date.getTime() <= limit) {
+    if (cronMatches(cron, date)) return date
+    date.setUTCMinutes(date.getUTCMinutes() + 1)
+  }
+
+  throw new Error('Could not find next matching date within 2 years')
+}
+
+// ---------------------------------------------------------------------------
+// Field parsing
+// ---------------------------------------------------------------------------
+
+function parseField(field: string, min: number, max: number): number[] {
+  const values = new Set<number>()
+
+  for (const part of field.split(',')) {
+    const stepMatch = part.match(/^(.+)\/(\d+)$/)
+
+    if (stepMatch) {
+      const [, rangePart, stepStr] = stepMatch
+      const step = parseInt(stepStr!, 10)
+      if (step <= 0) throw new Error(`Invalid step value: ${stepStr}`)
+
+      const [start, end] = rangePart === '*' ? [min, max] : parseRange(rangePart!, min, max)
+      for (let i = start; i <= end; i += step) {
+        values.add(i)
+      }
+    } else if (part === '*') {
+      for (let i = min; i <= max; i++) values.add(i)
+    } else if (part.includes('-')) {
+      const [start, end] = parseRange(part, min, max)
+      for (let i = start; i <= end; i++) values.add(i)
+    } else {
+      const n = parseInt(part, 10)
+      if (isNaN(n) || n < min || n > max) {
+        throw new Error(`Invalid cron value "${part}": must be ${min}–${max}`)
+      }
+      values.add(n)
+    }
+  }
+
+  return [...values].sort((a, b) => a - b)
+}
+
+function parseRange(part: string, min: number, max: number): [number, number] {
+  const [startStr, endStr] = part.split('-')
+  const start = parseInt(startStr!, 10)
+  const end = parseInt(endStr!, 10)
+
+  if (isNaN(start) || isNaN(end) || start < min || end > max || start > end) {
+    throw new Error(`Invalid cron range "${part}": must be within ${min}–${max}`)
+  }
+
+  return [start, end]
+}

package/src/scheduler/index.ts

@@ -0,0 +1,8 @@
+export { default as Scheduler } from './scheduler.ts'
+export { Schedule } from './schedule.ts'
+export { default as SchedulerRunner } from './runner.ts'
+export { parseCron, cronMatches, nextCronDate } from './cron.ts'
+export type { CronExpression } from './cron.ts'
+export { TimeUnit } from './schedule.ts'
+export type { TaskHandler } from './schedule.ts'
+export type { RunnerOptions } from './runner.ts'

package/src/scheduler/runner.ts

@@ -0,0 +1,116 @@
+import Scheduler from './scheduler.ts'
+import type { Schedule } from './schedule.ts'
+
+export interface RunnerOptions {
+  /** Timezone for schedule evaluation. @default 'UTC' */
+  timezone?: string
+}
+
+/**
+ * Long-running scheduler loop.
+ *
+ * Aligns to minute boundaries (standard cron behaviour), checks which
+ * tasks are due, and executes them concurrently. Supports graceful
+ * shutdown via SIGINT/SIGTERM and per-task overlap prevention.
+ *
+ * @example
+ * const runner = new SchedulerRunner()
+ * await runner.start() // blocks until runner.stop()
+ */
+export default class SchedulerRunner {
+  private running = false
+  private active = new Set<string>()
+
+  /** Start the scheduler loop. Blocks until stop() is called. */
+  async start(): Promise<void> {
+    this.running = true
+
+    const onSignal = () => this.stop()
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+
+    try {
+      while (this.running) {
+        await this.sleepUntilNextMinute()
+        if (!this.running) break
+
+        const now = new Date()
+        const due = Scheduler.due(now)
+
+        if (due.length > 0) {
+          await this.runAll(due)
+        }
+      }
+
+      // Wait for active tasks to finish before exiting
+      if (this.active.size > 0) {
+        await this.waitForActive()
+      }
+    } finally {
+      process.off('SIGINT', onSignal)
+      process.off('SIGTERM', onSignal)
+    }
+  }
+
+  /** Signal the runner to stop after the current tick completes. */
+  stop(): void {
+    this.running = false
+  }
+
+  /** Number of tasks currently executing. */
+  get activeCount(): number {
+    return this.active.size
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /** Sleep until the start of the next minute (XX:XX:00.000). */
+  private async sleepUntilNextMinute(): Promise<void> {
+    const now = Date.now()
+    const nextMinute = Math.ceil(now / 60_000) * 60_000
+    const delay = nextMinute - now
+
+    // Minimum 1s, maximum 60s — avoid sleeping 0ms on exact boundaries
+    const ms = Math.max(1_000, Math.min(delay, 60_000))
+    await Bun.sleep(ms)
+  }
+
+  /** Execute all due tasks concurrently. */
+  private async runAll(tasks: Schedule[]): Promise<void> {
+    const promises: Promise<void>[] = []
+
+    for (const task of tasks) {
+      if (task.preventsOverlap && this.active.has(task.name)) {
+        continue
+      }
+
+      promises.push(this.runTask(task))
+    }
+
+    await Promise.allSettled(promises)
+  }
+
+  /** Execute a single task with overlap tracking and error handling. */
+  private async runTask(task: Schedule): Promise<void> {
+    this.active.add(task.name)
+    try {
+      await task.handler()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.error(`[scheduler] Task "${task.name}" failed: ${message}`)
+    } finally {
+      this.active.delete(task.name)
+    }
+  }
+
+  /** Wait for all active tasks to complete (for graceful shutdown). */
+  private async waitForActive(): Promise<void> {
+    const maxWait = 30_000
+    const start = Date.now()
+    while (this.active.size > 0 && Date.now() - start < maxWait) {
+      await Bun.sleep(100)
+    }
+  }
+}

package/src/scheduler/schedule.ts

@@ -0,0 +1,262 @@
+import { parseCron, cronMatches } from './cron.ts'
+import type { CronExpression } from './cron.ts'
+
+export type TaskHandler = () => void | Promise<void>
+
+export enum TimeUnit {
+  Minutes = 'minutes',
+  Hours = 'hours',
+  Days = 'days',
+}
+
+const DAY_NAMES: Record<string, number> = {
+  sunday: 0,
+  sun: 0,
+  monday: 1,
+  mon: 1,
+  tuesday: 2,
+  tue: 2,
+  wednesday: 3,
+  wed: 3,
+  thursday: 4,
+  thu: 4,
+  friday: 5,
+  fri: 5,
+  saturday: 6,
+  sat: 6,
+}
+
+/**
+ * A scheduled task definition with a fluent configuration API.
+ *
+ * @example
+ * new Schedule('cleanup', handler).dailyAt('02:30').withoutOverlapping()
+ */
+export class Schedule {
+  readonly name: string
+  readonly handler: TaskHandler
+
+  private _cron: CronExpression | null = null
+  private _noOverlap = false
+
+  private _sporadicMin: number | null = null
+  private _sporadicMax: number | null = null
+  private _sporadicUnit: TimeUnit | null = null
+  private _nextRunAt: Date | null = null
+
+  constructor(name: string, handler: TaskHandler) {
+    this.name = name
+    this.handler = handler
+  }
+
+  // ── Raw cron ──────────────────────────────────────────────────────────────
+
+  /** Set a raw 5-field cron expression. */
+  cron(expression: string): this {
+    this._cron = parseCron(expression)
+    return this
+  }
+
+  // ── Minute-based ──────────────────────────────────────────────────────────
+
+  /** Run every minute. */
+  everyMinute(): this {
+    return this.cron('* * * * *')
+  }
+
+  /** Run every 2 minutes. */
+  everyTwoMinutes(): this {
+    return this.cron('*/2 * * * *')
+  }
+
+  /** Run every 5 minutes. */
+  everyFiveMinutes(): this {
+    return this.cron('*/5 * * * *')
+  }
+
+  /** Run every 10 minutes. */
+  everyTenMinutes(): this {
+    return this.cron('*/10 * * * *')
+  }
+
+  /** Run every 15 minutes. */
+  everyFifteenMinutes(): this {
+    return this.cron('*/15 * * * *')
+  }
+
+  /** Run every 30 minutes. */
+  everyThirtyMinutes(): this {
+    return this.cron('*/30 * * * *')
+  }
+
+  // ── Hourly ────────────────────────────────────────────────────────────────
+
+  /** Run once per hour at minute 0. */
+  hourly(): this {
+    return this.cron('0 * * * *')
+  }
+
+  /** Run once per hour at the given minute. */
+  hourlyAt(minute: number): this {
+    return this.cron(`${minute} * * * *`)
+  }
+
+  // ── Daily ─────────────────────────────────────────────────────────────────
+
+  /** Run once per day at midnight. */
+  daily(): this {
+    return this.cron('0 0 * * *')
+  }
+
+  /** Run once per day at the given time (HH:MM). */
+  dailyAt(time: string): this {
+    const [hour, minute] = parseTime(time)
+    return this.cron(`${minute} ${hour} * * *`)
+  }
+
+  /** Run twice per day at the given hours (minute 0). */
+  twiceDaily(hour1: number, hour2: number): this {
+    return this.cron(`0 ${hour1},${hour2} * * *`)
+  }
+
+  // ── Weekly ────────────────────────────────────────────────────────────────
+
+  /** Run once per week on Sunday at midnight. */
+  weekly(): this {
+    return this.cron('0 0 * * 0')
+  }
+
+  /** Run once per week on the given day and optional time. */
+  weeklyOn(day: string | number, time?: string): this {
+    const dow = typeof day === 'string' ? dayToNumber(day) : day
+    const [hour, minute] = time ? parseTime(time) : [0, 0]
+    return this.cron(`${minute} ${hour} * * ${dow}`)
+  }
+
+  // ── Monthly ───────────────────────────────────────────────────────────────
+
+  /** Run once per month on the 1st at midnight. */
+  monthly(): this {
+    return this.cron('0 0 1 * *')
+  }
+
+  /** Run once per month on the given day and optional time. */
+  monthlyOn(day: number, time?: string): this {
+    const [hour, minute] = time ? parseTime(time) : [0, 0]
+    return this.cron(`${minute} ${hour} ${day} * *`)
+  }
+
+  // ── Sporadic ──────────────────────────────────────────────────────────────
+
+  /**
+   * Run at random intervals between `min` and `max` in the given unit.
+   * Simulates human-like, non-periodic scheduling.
+   *
+   * @example
+   * Scheduler.task('scrape', handler).sporadically(5, 30, TimeUnit.Minutes)
+   */
+  sporadically(min: number, max: number, unit: TimeUnit): this {
+    if (min < 0 || max < 0) {
+      throw new Error('sporadically: min and max must be non-negative')
+    }
+    if (min >= max) {
+      throw new Error('sporadically: min must be less than max')
+    }
+
+    this._sporadicMin = min
+    this._sporadicMax = max
+    this._sporadicUnit = unit
+    this._cron = null
+    this._nextRunAt = this.computeNextRun(new Date())
+    return this
+  }
+
+  // ── Options ───────────────────────────────────────────────────────────────
+
+  /** Prevent overlapping runs within this process. */
+  withoutOverlapping(): this {
+    this._noOverlap = true
+    return this
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  /** Check if this task is due at the given Date (evaluated in UTC). */
+  isDue(now: Date): boolean {
+    if (this._sporadicMin !== null) {
+      if (!this._nextRunAt) return false
+      if (now >= this._nextRunAt) {
+        this._nextRunAt = this.computeNextRun(now)
+        return true
+      }
+      return false
+    }
+
+    if (!this._cron) return false
+    return cronMatches(this._cron, now)
+  }
+
+  /** Whether overlap prevention is enabled. */
+  get preventsOverlap(): boolean {
+    return this._noOverlap
+  }
+
+  /** The parsed cron expression (for testing/debugging). */
+  get expression(): CronExpression | null {
+    return this._cron
+  }
+
+  /** The next scheduled run time (for sporadic schedules). */
+  get nextRunAt(): Date | null {
+    return this._nextRunAt
+  }
+
+  /** Compute the next random run time from a reference point. */
+  private computeNextRun(from: Date): Date {
+    const ms = unitToMs(this._sporadicUnit!)
+    const minMs = this._sporadicMin! * ms
+    const maxMs = this._sporadicMax! * ms
+    const delay = minMs + Math.random() * (maxMs - minMs)
+    return new Date(from.getTime() + delay)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseTime(time: string): [number, number] {
+  const parts = time.split(':')
+  if (parts.length !== 2) {
+    throw new Error(`Invalid time format "${time}": expected HH:MM`)
+  }
+  const hour = parseInt(parts[0]!, 10)
+  const minute = parseInt(parts[1]!, 10)
+  if (isNaN(hour) || isNaN(minute) || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new Error(`Invalid time "${time}": hour must be 0–23, minute must be 0–59`)
+  }
+  return [hour, minute]
+}
+
+function unitToMs(unit: TimeUnit): number {
+  switch (unit) {
+    case TimeUnit.Minutes:
+      return 60_000
+    case TimeUnit.Hours:
+      return 3_600_000
+    case TimeUnit.Days:
+      return 86_400_000
+  }
+}
+
+function dayToNumber(day: string): number {
+  const n = DAY_NAMES[day.toLowerCase()]
+  if (n === undefined) {
+    throw new Error(
+      `Invalid day name "${day}": expected one of ${Object.keys(DAY_NAMES)
+        .filter((_, i) => i % 2 === 0)
+        .join(', ')}`
+    )
+  }
+  return n
+}

package/src/scheduler/scheduler.ts

@@ -0,0 +1,47 @@
+import { Schedule } from './schedule.ts'
+import type { TaskHandler } from './schedule.ts'
+
+/**
+ * Static task registry for periodic jobs.
+ *
+ * No DI, no database — tasks are registered in code and evaluated
+ * in-memory by the {@link SchedulerRunner}.
+ *
+ * @example
+ * Scheduler.task('cleanup:sessions', async () => {
+ *   await db.sql`DELETE FROM "_strav_sessions" WHERE "expires_at" < NOW()`
+ * }).hourly()
+ *
+ * Scheduler.task('reports:daily', () => generateDailyReport()).dailyAt('02:00')
+ */
+export default class Scheduler {
+  private static _tasks: Schedule[] = []
+
+  /**
+   * Register a periodic task. Returns the {@link Schedule} for fluent configuration.
+   *
+   * @example
+   * Scheduler.task('prune-cache', () => cache.flush()).everyFifteenMinutes()
+   */
+  static task(name: string, handler: TaskHandler): Schedule {
+    const schedule = new Schedule(name, handler)
+    Scheduler._tasks.push(schedule)
+    return schedule
+  }
+
+  /** All registered tasks. */
+  static get tasks(): readonly Schedule[] {
+    return Scheduler._tasks
+  }
+
+  /** Return tasks that are due at the given time (defaults to now, UTC). */
+  static due(now?: Date): Schedule[] {
+    const date = now ?? new Date()
+    return Scheduler._tasks.filter(t => t.isDue(date))
+  }
+
+  /** Clear all registered tasks. For testing. */
+  static reset(): void {
+    Scheduler._tasks = []
+  }
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}