@stravigor/core 0.1.0

package/src/queue/queue.ts

@@ -0,0 +1,338 @@
+import { inject } from '../core/inject.ts'
+import Configuration from '../config/configuration.ts'
+import Database from '../database/database.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+
+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"
+    `
+
+    return Number((rows[0] as Record<string, unknown>).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,197 @@
+import Queue, { hydrateJob } from './queue.ts'
+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,
+    }
+
+    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)
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error))
+      if (job.attempts >= job.maxAttempts) {
+        await this.fail(job, err)
+      } 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,140 @@
+/**
+ * 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,7 @@
+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 type { TaskHandler } from './schedule.ts'
+export type { RunnerOptions } from './runner.ts'