@strav/queue 0.4.31 → 1.0.0-alpha.4

package/src/console/scheduler_work.ts

@@ -0,0 +1,32 @@
+/**
+ * `bun strav scheduler:work` — run the minute-tick scheduler loop.
+ *
+ * Long-running; SIGINT / SIGTERM aborts the loop, which (per Scheduler's
+ * semantics) returns within one tick.
+ */
+
+import { Command, ExitCode } from '@strav/cli'
+import { Scheduler } from '../scheduler.ts'
+
+export class SchedulerWork extends Command {
+  static signature = 'scheduler:work'
+  static description = 'Run the scheduler tick loop until interrupted.'
+
+  override async execute(): Promise<number> {
+    const scheduler = this.app.resolve(Scheduler)
+    const controller = new AbortController()
+    const sigint = () => controller.abort()
+    const sigterm = () => controller.abort()
+    process.once('SIGINT', sigint)
+    process.once('SIGTERM', sigterm)
+
+    this.info(`Scheduler started (${scheduler.all().length} entries).`)
+    try {
+      await scheduler.run(controller.signal)
+      return ExitCode.Success
+    } finally {
+      process.off('SIGINT', sigint)
+      process.off('SIGTERM', sigterm)
+    }
+  }
+}

package/src/cron.ts

@@ -0,0 +1,194 @@
+/**
+ * `CronExpression` — parses a 5-field cron string + matches it against
+ * a `Date`.
+ *
+ * Fields, in order:
+ *   1. minute        (0–59)
+ *   2. hour          (0–23)
+ *   3. day-of-month  (1–31)
+ *   4. month         (1–12)
+ *   5. day-of-week   (0–6, Sunday = 0)
+ *
+ * Per-field syntax:
+ *   - `*`         — any value
+ *   - `N`         — exactly N
+ *   - `A-B`       — every value in `[A, B]` inclusive
+ *   - `A,B,C`     — list of values (each item is itself one of the
+ *                   above forms)
+ *   - `*\/N`      — every Nth value across the full range
+ *   - `A-B/N`     — every Nth value across `[A, B]`
+ *
+ * Time zone: matches against the UTC components of the `Date` —
+ * `.getUTCMinutes()` / `.getUTCHours()` / etc. Predictable across
+ * machines; apps that need wall-clock scheduling translate by hand at
+ * the call site (or supply a `Date` already shifted to local).
+ *
+ * Name aliases (`jan` / `mon` / etc.) are not supported in V1; use
+ * numbers.
+ */
+
+const FIELDS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day-of-month', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'day-of-week', min: 0, max: 6 },
+] as const
+
+export class CronExpression {
+  /** The expanded set of acceptable values per field — `Set<number>` × 5. */
+  private readonly fields: ReadonlyArray<ReadonlySet<number>>
+
+  constructor(public readonly expression: string) {
+    const parts = expression.trim().split(/\s+/)
+    if (parts.length !== 5) {
+      throw new Error(
+        `CronExpression: expected 5 space-separated fields, got ${parts.length}: "${expression}"`,
+      )
+    }
+    this.fields = parts.map((part, i) => {
+      const spec = FIELDS[i] as (typeof FIELDS)[number]
+      return parseField(part, spec.min, spec.max, spec.name)
+    })
+  }
+
+  /** True iff `date`'s UTC components fall within every field's accepted set. */
+  matches(date: Date): boolean {
+    const minute = date.getUTCMinutes()
+    const hour = date.getUTCHours()
+    const dayOfMonth = date.getUTCDate()
+    // JS months are 0–11; cron is 1–12.
+    const month = date.getUTCMonth() + 1
+    const dayOfWeek = date.getUTCDay()
+
+    return (
+      (this.fields[0] as ReadonlySet<number>).has(minute) &&
+      (this.fields[1] as ReadonlySet<number>).has(hour) &&
+      (this.fields[2] as ReadonlySet<number>).has(dayOfMonth) &&
+      (this.fields[3] as ReadonlySet<number>).has(month) &&
+      (this.fields[4] as ReadonlySet<number>).has(dayOfWeek)
+    )
+  }
+}
+
+/** Parse one field. Handles `,` lists by recursing on each segment. */
+function parseField(part: string, min: number, max: number, label: string): ReadonlySet<number> {
+  if (part === '') {
+    throw new Error(`CronExpression: empty ${label} field.`)
+  }
+  const out = new Set<number>()
+  for (const segment of part.split(',')) {
+    parseSegment(segment, min, max, label, out)
+  }
+  return out
+}
+
+/** Parse a single segment: `*`, `N`, `A-B`, `*\/N`, `A-B/N`. */
+function parseSegment(segment: string, min: number, max: number, label: string, into: Set<number>) {
+  // Step syntax: split off `/N` if present.
+  let baseSegment = segment
+  let step = 1
+  const slashIdx = segment.indexOf('/')
+  if (slashIdx !== -1) {
+    baseSegment = segment.slice(0, slashIdx)
+    const stepText = segment.slice(slashIdx + 1)
+    const parsed = Number.parseInt(stepText, 10)
+    if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== stepText) {
+      throw new Error(`CronExpression: bad step in ${label} "${segment}".`)
+    }
+    step = parsed
+  }
+
+  let start: number
+  let end: number
+  if (baseSegment === '*') {
+    start = min
+    end = max
+  } else if (baseSegment.includes('-')) {
+    const [aText, bText] = baseSegment.split('-')
+    if (aText === undefined || bText === undefined) {
+      throw new Error(`CronExpression: bad range in ${label} "${segment}".`)
+    }
+    const a = Number.parseInt(aText, 10)
+    const b = Number.parseInt(bText, 10)
+    if (
+      !Number.isInteger(a) ||
+      !Number.isInteger(b) ||
+      String(a) !== aText ||
+      String(b) !== bText
+    ) {
+      throw new Error(`CronExpression: bad range in ${label} "${segment}".`)
+    }
+    start = a
+    end = b
+  } else {
+    const n = Number.parseInt(baseSegment, 10)
+    if (!Number.isInteger(n) || String(n) !== baseSegment) {
+      throw new Error(`CronExpression: bad value in ${label} "${segment}".`)
+    }
+    start = n
+    end = n
+  }
+
+  if (start < min || end > max) {
+    throw new Error(`CronExpression: ${label} value out of range [${min}, ${max}]: "${segment}".`)
+  }
+  if (start > end) {
+    throw new Error(`CronExpression: ${label} range start > end: "${segment}".`)
+  }
+
+  for (let v = start; v <= end; v += step) {
+    into.add(v)
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public helpers — convenience constructors for the common cadences.
+// Apps reaching beyond these use `cron(expression)` directly.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Every minute — `* * * * *`. */
+export function everyMinute(): CronExpression {
+  return new CronExpression('* * * * *')
+}
+
+/** Every N minutes — emits a cron expression with `*\/N` in the minute field. Throws on non-positive N. */
+export function everyMinutes(n: number): CronExpression {
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`everyMinutes: expected a positive integer, got ${n}.`)
+  }
+  return new CronExpression(`*/${n} * * * *`)
+}
+
+/** Top of every hour — `0 * * * *`. */
+export function hourly(): CronExpression {
+  return new CronExpression('0 * * * *')
+}
+
+/** Midnight UTC daily — `0 0 * * *`. */
+export function daily(): CronExpression {
+  return new CronExpression('0 0 * * *')
+}
+
+/** Daily at a specific UTC time — `dailyAt('14:30')` → `30 14 * * *`. */
+export function dailyAt(time: string): CronExpression {
+  const match = time.match(/^(\d{1,2}):(\d{2})$/)
+  if (!match) {
+    throw new Error(`dailyAt: expected HH:MM (24-hour), got "${time}".`)
+  }
+  const hour = Number.parseInt(match[1] as string, 10)
+  const minute = Number.parseInt(match[2] as string, 10)
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new Error(`dailyAt: time out of range "${time}".`)
+  }
+  return new CronExpression(`${minute} ${hour} * * *`)
+}
+
+/**
+ * Escape hatch for non-trivial schedules — accepts any valid 5-field cron
+ * expression. Apps that want weekly / monthly / "Mondays at 9" etc. use
+ * this directly.
+ */
+export function cron(expression: string): CronExpression {
+  return new CronExpression(expression)
+}

package/src/database_queue.ts

@@ -0,0 +1,177 @@
+/**
+ * `DatabaseQueue` — Postgres-backed `Queue` driver.
+ *
+ * Persists each `dispatch` / `dispatchLater` as a `_strav_jobs` row;
+ * Workers (next M3 slice) `SELECT FOR UPDATE SKIP LOCKED` to claim
+ * available rows and run `handle()`.
+ *
+ * **Queue-until-commit semantics.** When `dispatch()` is called inside
+ * a `UnitOfWork.run(...)` or `TenantManager.withTenant(...)` scope, the
+ * driver routes the INSERT through the ambient transaction's executor
+ * (read from `transactionalStorage`). The new row commits + rolls back
+ * atomically with the surrounding transaction:
+ *
+ *   - If the transaction COMMITs, the queue row is visible to Workers.
+ *     The dispatched job runs.
+ *   - If the transaction ROLLBACKs, the row never existed. The job is
+ *     dropped.
+ *
+ * This is exactly the spec's M3 spike ("flush queue on commit; drop
+ * on rollback") — Postgres's transactional atomicity gives us the
+ * semantic for free; no deferred-callback machinery needed.
+ *
+ * Outside a transactional scope, `dispatch` writes against
+ * `this.db` directly (auto-commit).
+ *
+ * `dispatchSync` bypasses persistence entirely — instantiates the Job
+ * via the container and runs `handle()` in-process, just like
+ * `SyncQueue.dispatchSync`. The caller's session continues without a
+ * Worker ever seeing the work.
+ */
+
+import {
+  currentTransactionalContext,
+  type Database,
+  type DatabaseExecutor,
+  type PostgresDatabase,
+} from '@strav/database'
+import { type Container, type Logger, ulid } from '@strav/kernel'
+import type { JobClass, JobContext, PayloadOf } from './job.ts'
+import { jobSchema } from './job_schema.ts'
+import type { DispatchLaterOptions, DispatchOptions, Queue } from './queue.ts'
+
+export interface DatabaseQueueOptions {
+  /** Postgres pool used for INSERTs outside an ambient transaction. */
+  db: PostgresDatabase | Database
+  /**
+   * Container used to construct Job instances for `dispatchSync`. The
+   * Worker (separate slice) also goes through the container, so the
+   * same `@inject()`-driven wiring resolves consistently.
+   */
+  container: Container
+  /** Optional Logger attached to `dispatchSync` `JobContext.log`. Default: no-op. */
+  logger?: Logger
+  /** Default `max_attempts` when neither the JobClass nor `DispatchOptions` specifies one. Default `3`. */
+  defaultAttempts?: number
+  /** Default queue name when neither the JobClass nor `DispatchOptions` specifies one. Default `'default'`. */
+  defaultQueue?: string
+}
+
+export class DatabaseQueue implements Queue {
+  private readonly db: Database
+  private readonly container: Container
+  private readonly logger: Logger
+  private readonly defaultAttempts: number
+  private readonly defaultQueue: string
+
+  constructor(opts: DatabaseQueueOptions) {
+    this.db = opts.db
+    this.container = opts.container
+    this.logger = opts.logger ?? createNoopLogger()
+    this.defaultAttempts = opts.defaultAttempts ?? 3
+    this.defaultQueue = opts.defaultQueue ?? 'default'
+  }
+
+  async dispatch<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchOptions,
+  ): Promise<string> {
+    return this.insertJob(jobClass, payload, /* delaySeconds */ 0, opts)
+  }
+
+  async dispatchLater<TJob extends JobClass>(
+    at: Date | number,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchLaterOptions,
+  ): Promise<string> {
+    const delaySeconds = computeDelaySeconds(at)
+    return this.insertJob(jobClass, payload, delaySeconds, opts)
+  }
+
+  async dispatchSync<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+  ): Promise<void> {
+    const jobId = ulid()
+    const job = this.container.make(jobClass)
+    const ctx: JobContext = {
+      jobId,
+      attempt: 1,
+      payload,
+      // SyncQueue parity — dispatchSync runs to completion in one tick;
+      // a never-aborted signal keeps handlers written against the
+      // production contract working unchanged.
+      signal: new AbortController().signal,
+      log: this.logger,
+    }
+    await job.handle(ctx)
+  }
+
+  /**
+   * Single INSERT path shared by `dispatch` + `dispatchLater`. Reads
+   * the ambient transactional context — when present, the INSERT
+   * routes through `ctx.tx` so the row is part of the surrounding
+   * transaction's atomicity guarantee.
+   */
+  private async insertJob<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    delaySeconds: number,
+    opts: DispatchOptions | undefined,
+  ): Promise<string> {
+    const jobId = ulid()
+    const queue = opts?.queue ?? jobClass.queue ?? this.defaultQueue
+    const maxAttempts = opts?.attempts ?? jobClass.maxAttempts ?? this.defaultAttempts
+
+    const executor: DatabaseExecutor = currentTransactionalContext()?.tx ?? this.db
+    // `available_at` is computed in Postgres so the queue's notion of
+    // "now" is the DB clock — the only clock the Worker reads.
+    // Mixing wall-clock from the dispatcher with DB-clock from the
+    // Worker invites skew bugs.
+    const availableAtFragment =
+      delaySeconds > 0 ? `now() + interval '${delaySeconds} seconds'` : 'now()'
+    await executor.execute(
+      `INSERT INTO ${quoteIdent(jobSchema.name)} (
+        "id", "queue", "job_name", "payload", "attempts", "max_attempts", "available_at", "created_at", "updated_at"
+      ) VALUES (
+        $1, $2, $3, $4::jsonb, 0, $5, ${availableAtFragment}, now(), now()
+      )`,
+      [jobId, queue, jobClass.jobName, JSON.stringify(payload), maxAttempts],
+    )
+    return jobId
+  }
+}
+
+/** Normalize `at` (Date | seconds-from-now) → seconds-from-now ≥ 0. */
+function computeDelaySeconds(at: Date | number): number {
+  if (typeof at === 'number') {
+    if (at < 0) {
+      throw new Error(`DatabaseQueue.dispatchLater: delay must be non-negative, got ${at}.`)
+    }
+    return at
+  }
+  // `at` is a Date — past values clamp to 0 (immediately available).
+  const deltaMs = at.getTime() - Date.now()
+  return Math.max(0, Math.ceil(deltaMs / 1000))
+}
+
+/** Single-quote-aware identifier quoter for the schema table name. */
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+/** Bare Logger that drops every call — same shape as SyncQueue's. */
+function createNoopLogger(): Logger {
+  const noop = () => undefined
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    trace: noop,
+    child: () => createNoopLogger(),
+  } as unknown as Logger
+}

package/src/failed_jobs_schema.ts

@@ -0,0 +1,37 @@
+/**
+ * `strav_failed_jobs` schema — terminal failure dead-letter table.
+ *
+ * When `Worker.processOne()` exhausts a job's `max_attempts`, the row
+ * moves from `strav_jobs` to `strav_failed_jobs` in a single
+ * transaction — INSERT here, DELETE there. Apps inspect this table
+ * to triage what blew up; the `queue:retry` / `queue:flush` console
+ * commands (lands with `@strav/cli` in M4) operate on these rows.
+ *
+ * Columns:
+ *   - `id` (char(26), ULID PK) — fresh per failure, not the original
+ *     job id (the original is gone with the row).
+ *   - `queue` (varchar(64)) — copied from `strav_jobs.queue`.
+ *   - `job_name` (varchar(128)) — copied from `strav_jobs.job_name`.
+ *   - `payload` (jsonb) — copied verbatim so retries can replay it.
+ *   - `exception` (text) — the thrown error, serialized via
+ *     `error.stack ?? String(error)`. Long; not indexed.
+ *   - `attempts` (integer) — how many total attempts the job got
+ *     before terminal failure.
+ *   - `failed_at` (timestamptz) — wall-clock time of the move.
+ *   - `created_at` / `updated_at` — provided by `t.timestamps()`.
+ *
+ * Not `tenanted: true` — same system-level scope as `strav_jobs`.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const failedJobsSchema = defineSchema('strav_failed_jobs', Archetype.Entity, (t) => {
+  t.id()
+  t.string('queue').max(64)
+  t.string('job_name').max(128)
+  t.json<unknown>('payload')
+  t.text('exception')
+  t.integer('attempts')
+  t.timestamp('failed_at')
+  t.timestamps()
+})

package/src/index.ts

@@ -1,3 +1,62 @@
-export * from './queue/index.ts'
-export * from './scheduler/index.ts'
-export * from './providers/index.ts'
+// Public API of @strav/queue.
+//
+// V1 ships:
+//   - Job + JobContext + JobClass + PayloadOf — the unit of work + types.
+//   - JobRegistry + Bun.Glob auto-discovery + isJobClass type-guard.
+//   - Queue interface with dispatch / dispatchLater / dispatchSync.
+//   - SyncQueue — in-process synchronous driver for tests + single-process dev.
+//   - DatabaseQueue — Postgres-backed driver with queue-until-commit semantics
+//     via @strav/database's transactional ALS.
+//   - jobSchema — the `strav_jobs` Schema apps register + migrate.
+//   - Worker — consumer side: SELECT FOR UPDATE SKIP LOCKED poll loop,
+//     attempt counter, exponential backoff with jitter, per-attempt
+//     timeout, graceful shutdown via AbortSignal.
+//   - CronExpression + helpers (everyMinute / everyMinutes / hourly /
+//     daily / dailyAt / cron) — 5-field cron with UTC-based matching.
+//   - Scheduler + schedulerRunsSchema — recurring dispatch with optional
+//     onOneServer advisory lock (built on TenantManager.withLock).
+//
+//   - failedJobsSchema — the `strav_failed_jobs` dead-letter table.
+//     Worker moves terminal failures here atomically (INSERT + DELETE
+//     in one tx).
+//
+// Still deferred (waiting on @strav/cli — M4):
+//   - queue:retry / queue:flush console commands (re-enqueue / drop
+//     failed rows in bulk).
+
+export {
+  QueueConsoleProvider,
+  QueueFailed,
+  QueueFlush,
+  QueueRetry,
+  QueueWork,
+  SchedulerList,
+  SchedulerRun,
+  SchedulerWork,
+} from './console/index.ts'
+export {
+  CronExpression,
+  cron,
+  daily,
+  dailyAt,
+  everyMinute,
+  everyMinutes,
+  hourly,
+} from './cron.ts'
+export { DatabaseQueue, type DatabaseQueueOptions } from './database_queue.ts'
+export { failedJobsSchema } from './failed_jobs_schema.ts'
+export {
+  Job,
+  type JobClass,
+  type JobConfig,
+  type JobContext,
+  type JobFailedContext,
+  type PayloadOf,
+} from './job.ts'
+export { isJobClass, JobRegistry } from './job_registry.ts'
+export { jobSchema } from './job_schema.ts'
+export type { DispatchLaterOptions, DispatchOptions, Queue } from './queue.ts'
+export { type ScheduleOptions, Scheduler, type SchedulerOptions } from './scheduler.ts'
+export { schedulerRunsSchema } from './scheduler_runs_schema.ts'
+export { SyncQueue, type SyncQueueOptions } from './sync_queue.ts'
+export { type JobResult, Worker, type WorkerOptions } from './worker.ts'

package/src/job.ts

@@ -0,0 +1,153 @@
+/**
+ * `Job` — the unit of background work.
+ *
+ * Subclasses declare a stable `static jobName` (the wire identifier the
+ * `JobRegistry` uses to route a serialized payload back to a class) and
+ * implement `handle(ctx)`. The Worker constructs jobs through the
+ * container so `@inject()`-marked subclasses get their dependencies
+ * resolved the usual way; the payload arrives as JSON on the
+ * `JobContext`.
+ *
+ * Configuration overrides (max attempts, backoff, timeout, queue name)
+ * are static on the subclass. The Worker reads them per-attempt — see
+ * the `JobConfig` interface below.
+ *
+ * ```ts
+ * @inject()
+ * class SendWelcomeEmail extends Job<{ userId: string }> {
+ *   static override readonly jobName = 'mail.welcome'
+ *
+ *   constructor(
+ *     private readonly users: UserRepository,
+ *     private readonly mail: MailManager,
+ *   ) {
+ *     super()
+ *   }
+ *
+ *   async handle(ctx: JobContext<{ userId: string }>): Promise<void> {
+ *     const user = await this.users.findOrFail(ctx.payload.userId)
+ *     await this.mail.send(new WelcomeEmail(user))
+ *   }
+ * }
+ * ```
+ */
+
+import type { Logger } from '@strav/kernel'
+
+/**
+ * Per-invocation context passed to `Job.handle(ctx)`. Workers populate
+ * every field — testing harnesses can build one by hand.
+ */
+export interface JobContext<TPayload = unknown> {
+  /** Stable id assigned at dispatch (typically a ULID). */
+  jobId: string
+  /** 1-based attempt counter. `attempt === 1` is the first run. */
+  attempt: number
+  /** The deserialized payload. */
+  payload: TPayload
+  /**
+   * Cancellation signal. Aborted when the Worker's shutdown grace
+   * period elapses or the job exceeds its `timeout`. Handlers that
+   * loop / stream should check `ctx.signal.aborted` and bail.
+   */
+  signal: AbortSignal
+  /**
+   * Job-scoped logger — prebound with `jobId` + `jobName` + `attempt`.
+   * Standard Logger surface (`debug`/`info`/`warn`/`error`).
+   */
+  log: Logger
+}
+
+/**
+ * Optional retry hook context — same shape as `JobContext` plus the
+ * error that caused the failure.
+ */
+export interface JobFailedContext<TPayload = unknown> extends JobContext<TPayload> {
+  /** The thrown value from the failed attempt. Already wrapped by the kernel error stack. */
+  error: unknown
+}
+
+/**
+ * The `static` config shape a Job subclass may set. Every field is
+ * optional — the Worker falls back to driver defaults when omitted.
+ */
+export interface JobConfig {
+  /** Total attempts (including the first). Default: driver-configured, typically 3. */
+  maxAttempts?: number
+  /**
+   * Backoff in seconds for `attempt` (1-based). The Worker calls this
+   * AFTER a failed attempt to schedule the next try. Default: exponential
+   * with jitter (driver-configured).
+   */
+  backoff?(attempt: number): number
+  /** Per-attempt time limit (seconds). Default: driver-configured. */
+  timeout?: number
+  /** Named queue to dispatch onto. Default: `'default'`. */
+  queue?: string
+}
+
+/**
+ * The abstract Job base class. Subclasses implement `handle` and set
+ * `static jobName`. Other static fields are optional configuration —
+ * see {@link JobConfig}.
+ *
+ * Generic parameter `TPayload` is the shape the dispatcher serializes
+ * and the handler deserializes. Workers JSON.stringify/parse it
+ * verbatim — keep it serializable (no Dates without a custom revival
+ * step, no class instances).
+ */
+export abstract class Job<TPayload = unknown> {
+  /**
+   * Stable wire identifier mapping this class in the JobRegistry.
+   * Subclasses MUST override. Convention: `<package>.<verb>` or
+   * `<resource>.<verb>` (`mail.welcome`, `user.cleanup`).
+   *
+   * The base class declares an empty string so type-checking holds;
+   * `JobRegistry.register()` rejects classes that didn't override.
+   */
+  static readonly jobName: string = ''
+
+  // Optional static configuration. Declared on the base so subclasses
+  // can shadow with `static override readonly <field> = <value>` under
+  // `noImplicitOverride`. The Worker reads these per-attempt; omitted
+  // fields fall back to driver defaults. Mirrors the {@link JobConfig}
+  // interface — the interface drives `JobClass`'s typing, the static
+  // fields here drive the override-friendly inheritance shape.
+  static readonly maxAttempts?: number
+  static readonly backoff?: (attempt: number) => number
+  static readonly timeout?: number
+  static readonly queue?: string
+
+  /** The handler. Workers call this once they've constructed the job + built the context. */
+  abstract handle(context: JobContext<TPayload>): Promise<void>
+
+  /**
+   * Optional failure hook. Fires when an attempt throws AND there are
+   * still retries left; also fires once on the FINAL failure (so apps
+   * can route to a dead-letter, post a Slack message, etc.). The Worker
+   * runs this in a try/catch — a throw from `failed()` is logged but
+   * doesn't change the retry decision.
+   */
+  failed?(context: JobFailedContext<TPayload>): Promise<void>
+}
+
+/**
+ * Constructor reference for a Job subclass. The Worker / Queue store
+ * these in the registry, look them up by `jobName`, and instantiate
+ * via the container.
+ */
+export interface JobClass<TPayload = unknown> extends JobConfig {
+  // biome-ignore lint/suspicious/noExplicitAny: ctor params are decided per-subclass; the @inject() flow resolves them.
+  new (...args: any[]): Job<TPayload>
+  readonly jobName: string
+}
+
+/**
+ * Helper type: extract the payload type from a `JobClass`.
+ *
+ * ```ts
+ * type WelcomePayload = PayloadOf<typeof SendWelcomeEmail>
+ * // → { userId: string }
+ * ```
+ */
+export type PayloadOf<T> = T extends JobClass<infer P> ? P : never