bunderstack 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Batteries-included backend framework for Bun: CRUD APIs, auth, file storage, realtime, tRPC, email, and validated env from a single Drizzle schema and config object.",
   "keywords": [
     "backend",

package/src/config.ts

@@ -40,6 +40,8 @@ export const BunderstackOptionsSchema = z.object({
   email: z.unknown().optional(),
   // Loose: a tRPC router or builder callback. Resolved in createBunderstack.
   trpc: z.unknown().optional(),
+  // Loose: holds handler functions and zod schemas. Resolved in createBunderstack.
+  jobs: z.unknown().optional(),
   rateLimit: z
     .union([
       z.boolean(),
@@ -80,7 +82,7 @@ export type BunderstackConfig<
   TEnv extends EnvConfigInput | undefined = EnvConfigInput | undefined,
 > = Omit<
   z.input<typeof BunderstackOptionsSchema>,
-  'schema' | 'access' | 'auth' | 'storage' | 'env' | 'email' | 'trpc'
+  'schema' | 'access' | 'auth' | 'storage' | 'env' | 'email' | 'trpc' | 'jobs'
 > & {
   schema: TSchema
   access?: TAccess
@@ -90,7 +92,8 @@ export type BunderstackConfig<
   email?: EmailConfigInput
   // `trpc` is intentionally NOT declared here: createBunderstack intersects
   // its own inference-friendly `trpc` declaration (router | builder callback)
-  // so the callback's `t` parameter gets contextual typing.
+  // so the callback's `t` parameter gets contextual typing. `jobs` follows the
+  // same pattern (defs map | builder callback receiving `j`).
   rateLimit?: boolean | RateLimitConfig
   idempotency?: boolean | IdempotencyConfig
   realtime?:

package/src/index.ts

@@ -22,6 +22,18 @@ import { buildCrudRouter } from './crud'
 import { createDb } from './db'
 import { buildHandler } from './handler'
 import { withInternalTables } from './internal-tables'
+import {
+  createJobsBuilder,
+  createJobRunner,
+  enqueueJob,
+  validateJobsDefs,
+} from './jobs/index'
+import type {
+  BunderstackJobsBuilder,
+  EnqueueOptions,
+  JobsDefs,
+  JobsFacade,
+} from './jobs/index'
 import {
   PROVISION_INTERNALS,
   type WithProvisionInternals,
@@ -40,6 +52,8 @@ type AuthInstance = ReturnType<typeof createAuth>
 const DEFAULT_PENDING_TTL_MS = 30 * 60_000
 /** How often the auto-started orphan sweep runs. */
 const SWEEP_INTERVAL_MS = 10 * 60_000
+/** How often the in-process job worker polls for claimable jobs. */
+const JOBS_POLL_INTERVAL_MS = 1000
 
 /**
  * Public storage facade exposed as `app.storage`. Object-level operations live
@@ -73,6 +87,7 @@ export type BunderstackApp<
   TBuckets extends string = string,
   TEnv extends EnvConfigInput | undefined = undefined,
   TRouter = undefined,
+  TJobsDefs extends JobsDefs | undefined = undefined,
 > = {
   handler: (req: Request) => Promise<Response>
   db: DbFor<TSchema>
@@ -85,6 +100,8 @@ export type BunderstackApp<
   env: ValidatedEnv<TEnv>
   /** Email facade; always present — send() throws when email isn't configured. */
   email: EmailFacade
+  /** Job queue facade; always present — enqueue throws when jobs aren't configured. */
+  jobs: JobsFacade<TJobsDefs extends JobsDefs ? TJobsDefs : Record<never, never>>
   /** Deploy-time introspection: what this app needs provisioned. */
   manifest: BunderstackManifest
   /**
@@ -102,7 +119,11 @@ export type BunderstackApp<
 // Overloads: the builder-callback form and the prebuilt-router/none form are
 // separate signatures so the callback's `t` parameter gets contextual typing
 // and the router type lands on `$inferClient` without conditional-type
-// inference (which breaks under contextual return types).
+// inference (which breaks under contextual return types). `jobs` needs the
+// same split against BOTH trpc forms — a union parameter type (`TJobsDefs |
+// (callback => TJobsDefs)`) defeats inference (TS widens TJobsDefs to its
+// constraint when a function literal could match either union arm) — hence
+// four overloads covering the trpc × jobs option cross product.
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -110,12 +131,47 @@ export function createBunderstack<
   const TStorage extends StorageConfigInput | undefined = undefined,
   const TEnv extends EnvConfigInput | undefined = undefined,
   TRouter extends AnyRouter = AnyRouter,
+  const TJobsDefs extends JobsDefs | undefined = undefined,
 >(
   options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
     /** Builder callback receiving the pre-wired `t` instance. */
     trpc: (t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => TRouter
+    /** Builder callback receiving the pre-wired `j` instance. */
+    jobs: (j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs
+  },
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
+export function createBunderstack<
+  TSchema extends Record<string, unknown>,
+  const TAccess extends Record<string, TableAccessInput> | undefined =
+    undefined,
+  const TStorage extends StorageConfigInput | undefined = undefined,
+  const TEnv extends EnvConfigInput | undefined = undefined,
+  TRouter extends AnyRouter = AnyRouter,
+  const TJobsDefs extends JobsDefs | undefined = undefined,
+>(
+  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
+    /** Builder callback receiving the pre-wired `t` instance. */
+    trpc: (t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => TRouter
+    /** Prebuilt job definitions (escape hatch for multi-file setups). */
+    jobs?: TJobsDefs
+  },
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
+export function createBunderstack<
+  TSchema extends Record<string, unknown>,
+  const TAccess extends Record<string, TableAccessInput> | undefined =
+    undefined,
+  const TStorage extends StorageConfigInput | undefined = undefined,
+  const TEnv extends EnvConfigInput | undefined = undefined,
+  TRouter extends AnyRouter | undefined = undefined,
+  const TJobsDefs extends JobsDefs | undefined = undefined,
+>(
+  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
+    /** Prebuilt tRPC router (escape hatch for multi-file setups). */
+    trpc?: TRouter
+    /** Builder callback receiving the pre-wired `j` instance. */
+    jobs: (j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs
   },
-): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>>
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -123,12 +179,15 @@ export function createBunderstack<
   const TStorage extends StorageConfigInput | undefined = undefined,
   const TEnv extends EnvConfigInput | undefined = undefined,
   TRouter extends AnyRouter | undefined = undefined,
+  const TJobsDefs extends JobsDefs | undefined = undefined,
 >(
   options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
     /** Prebuilt tRPC router (escape hatch for multi-file setups). */
     trpc?: TRouter
+    /** Prebuilt job definitions (escape hatch for multi-file setups). */
+    jobs?: TJobsDefs
   },
-): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>>
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
 export async function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -140,9 +199,19 @@ export async function createBunderstack<
     trpc?:
       | AnyRouter
       | ((t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => AnyRouter)
+    jobs?:
+      | JobsDefs
+      | ((j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => JobsDefs)
   },
 ): Promise<
-  BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, AnyRouter | undefined>
+  BunderstackApp<
+    TSchema,
+    TAccess,
+    BucketNamesOf<TStorage>,
+    TEnv,
+    AnyRouter | undefined,
+    JobsDefs | undefined
+  >
 > {
   const dialect = detectDialect(options.schema)
   // Env is validated FIRST: the app refuses to boot on missing/invalid vars,
@@ -271,6 +340,42 @@ export async function createBunderstack<
     void sweepOrphans(registry, db, DEFAULT_PENDING_TTL_MS).catch(() => {})
   }, SWEEP_INTERVAL_MS)
   sweepTimer.unref?.()
+  const jobsDefs: JobsDefs | undefined = options.jobs
+    ? typeof options.jobs === 'function'
+      ? options.jobs(createJobsBuilder<TSchema, ValidatedEnv<TEnv>>())
+      : (options.jobs as JobsDefs)
+    : undefined
+  if (jobsDefs) validateJobsDefs(jobsDefs)
+  const jobRunner = jobsDefs
+    ? createJobRunner({
+        db,
+        defs: jobsDefs,
+        ctx: { db: userDb, env, email, storage },
+      })
+    : undefined
+  const jobs = {
+    async enqueue(name: string, input?: unknown, opts?: EnqueueOptions) {
+      if (!jobsDefs) {
+        throw new Error(
+          '[bunderstack] no jobs configured — add a `jobs` key to createBunderstack',
+        )
+      }
+      const result = await enqueueJob(db, jobsDefs, name, input, opts)
+      // Wake the local worker so same-process jobs start without poll latency.
+      if (jobRunner && !introspect) void jobRunner.tick().catch(() => {})
+      return result
+    },
+    tick(now?: number) {
+      return jobRunner ? jobRunner.tick(now) : Promise.resolve()
+    },
+  }
+  if (jobRunner) jobRunner.setJobsFacade(jobs)
+  if (jobRunner && !introspect) {
+    const jobsTimer = setInterval(() => {
+      void jobRunner.tick().catch(() => {})
+    }, JOBS_POLL_INTERVAL_MS)
+    jobsTimer.unref?.()
+  }
   const trpcRouter: AnyRouter | undefined =
     typeof options.trpc === 'function'
       ? options.trpc(createTRPC<TSchema, ValidatedEnv<TEnv>>())
@@ -286,6 +391,7 @@ export async function createBunderstack<
             user: await resolveAccessUser(authResolver, req.headers),
             env,
             email,
+            jobs,
             req,
           }),
         })
@@ -304,7 +410,8 @@ export async function createBunderstack<
     TAccess,
     BucketNamesOf<TStorage>,
     TEnv,
-    AnyRouter | undefined
+    AnyRouter | undefined,
+    JobsDefs | undefined
   > = {
     handler,
     // Internal tables live on the runtime db but stay out of the public type.
@@ -314,6 +421,10 @@ export async function createBunderstack<
     router,
     env,
     email,
+    // Runtime facade is untyped (JobsRuntimeFacade); the generic-typed field
+    // narrows `enqueue` per-app from the declared job defs — same relationship
+    // as `userDb` above.
+    jobs: jobs as never,
     trpcRouter,
     manifest: buildManifest({
       schema: options.schema,
@@ -321,6 +432,7 @@ export async function createBunderstack<
       storage: config.storage,
       envConfig: options.env as EnvConfigInput | undefined,
       realtime: Boolean(config.realtime),
+      jobs: jobsDefs,
     }),
   }
 
@@ -349,7 +461,7 @@ export type {
 export { validateEnv, createClientEnv, BunderstackEnvError } from './env'
 export type { EnvConfigInput, BaseEnv, ValidatedEnv } from './env'
 export { buildManifest } from './manifest'
-export type { BunderstackManifest, ManifestEnvVar } from './manifest'
+export type { BunderstackManifest, ManifestEnvVar, ManifestJob } from './manifest'
 export { createEmail } from './email'
 export type {
   EmailMessage,
@@ -359,6 +471,16 @@ export type {
 } from './email'
 export { createTRPC } from './trpc'
 export type { BunderstackTRPC, TRPCContext } from './trpc'
+export { createJobsBuilder } from './jobs/index'
+export type {
+  BunderstackJobsBuilder,
+  EnqueueOptions,
+  JobContext,
+  JobDefinition,
+  JobsDefs,
+  JobsFacade,
+  JobsRuntimeFacade,
+} from './jobs/index'
 export {
   defineAccess,
   validateAndResolveAccess,

package/src/internal-tables-pg.ts

@@ -8,6 +8,7 @@ import {
   pgTable,
   primaryKey,
   text,
+  uniqueIndex,
 } from 'drizzle-orm/pg-core'
 
 export const bunderstackFilesPg = pgTable(
@@ -43,3 +44,25 @@ export const bunderstackIdempotencyPg = pgTable(
   },
   (t) => [primaryKey({ columns: [t.key, t.tableName] })],
 )
+
+export const bunderstackJobsPg = pgTable(
+  '_bunderstack_jobs',
+  {
+    id: text('id').primaryKey(),
+    type: text('type').notNull(),
+    payloadJson: text('payload_json').notNull(),
+    status: text('status').notNull(),
+    attempts: integer('attempts').notNull().default(0),
+    runAt: bigint('run_at', { mode: 'number' }).notNull(),
+    lockedUntil: bigint('locked_until', { mode: 'number' }),
+    dedupeKey: text('dedupe_key'),
+    lastError: text('last_error'),
+    createdAt: bigint('created_at', { mode: 'number' }).notNull(),
+    finishedAt: bigint('finished_at', { mode: 'number' }),
+  },
+  (t) => [
+    index('bjq_claim').on(t.status, t.runAt),
+    index('bjq_type_status').on(t.type, t.status),
+    uniqueIndex('bjq_dedupe').on(t.type, t.dedupeKey),
+  ],
+)

package/src/internal-tables.ts

@@ -6,12 +6,14 @@ import {
   primaryKey,
   sqliteTable,
   text,
+  uniqueIndex,
 } from 'drizzle-orm/sqlite-core'
 
 import { detectDialect } from './dialect'
 import {
   bunderstackFilesPg,
   bunderstackIdempotencyPg,
+  bunderstackJobsPg,
 } from './internal-tables-pg'
 
 export const bunderstackFiles = sqliteTable(
@@ -48,19 +50,45 @@ export const bunderstackIdempotency = sqliteTable(
   (t) => [primaryKey({ columns: [t.key, t.tableName] })],
 )
 
+export const bunderstackJobs = sqliteTable(
+  '_bunderstack_jobs',
+  {
+    id: text('id').primaryKey(),
+    type: text('type').notNull(),
+    payloadJson: text('payload_json').notNull(),
+    status: text('status').notNull(), // pending | running | succeeded | failed
+    attempts: integer('attempts').notNull().default(0),
+    runAt: integer('run_at').notNull(),
+    lockedUntil: integer('locked_until'),
+    dedupeKey: text('dedupe_key'),
+    lastError: text('last_error'),
+    createdAt: integer('created_at').notNull(),
+    finishedAt: integer('finished_at'),
+  },
+  (t) => [
+    index('bjq_claim').on(t.status, t.runAt),
+    index('bjq_type_status').on(t.type, t.status),
+    // NULL dedupe keys are distinct in both dialects, so keyless jobs never collide.
+    uniqueIndex('bjq_dedupe').on(t.type, t.dedupeKey),
+  ],
+)
+
 export const INTERNAL_TABLES = {
   bunderstackFiles,
   bunderstackIdempotency,
+  bunderstackJobs,
 } as const
 
 export const INTERNAL_TABLE_NAMES: ReadonlySet<string> = new Set([
   'bunderstack_file_meta',
   '_bunderstack_idempotency',
+  '_bunderstack_jobs',
 ])
 
 export const INTERNAL_TABLES_PG = {
   bunderstackFiles: bunderstackFilesPg,
   bunderstackIdempotency: bunderstackIdempotencyPg,
+  bunderstackJobs: bunderstackJobsPg,
 } as const
 
 // Both dialect twins count as "ours" for the re-export identity check.
@@ -70,6 +98,7 @@ const INTERNAL_TABLE_CANDIDATES = new Map<string, readonly unknown[]>([
     getTableName(bunderstackIdempotency),
     [bunderstackIdempotency, bunderstackIdempotencyPg],
   ],
+  [getTableName(bunderstackJobs), [bunderstackJobs, bunderstackJobsPg]],
 ])
 
 /** Internal file-meta table matching the db's dialect. */
@@ -82,6 +111,11 @@ export function idempotencyTableFor(db: unknown) {
   return is(db, PgDatabase) ? bunderstackIdempotencyPg : bunderstackIdempotency
 }
 
+/** Internal jobs table matching the db's dialect. */
+export function jobsTableFor(db: unknown) {
+  return is(db, PgDatabase) ? bunderstackJobsPg : bunderstackJobs
+}
+
 export function withInternalTables<TSchema extends Record<string, unknown>>(
   schema: TSchema,
 ): TSchema & typeof INTERNAL_TABLES {

package/src/jobs/cron.ts

@@ -0,0 +1,87 @@
+// src/jobs/cron.ts — minimal 5-field cron parser, UTC, minute granularity.
+// Supports: * , lists (a,b) , ranges (a-b) , steps (*/n, a-b/n, a/n). No
+// month/day names, no seconds field, no @-shortcuts — YAGNI for v1.
+
+export type CronField = { any: boolean; values: ReadonlySet<number> }
+
+export type ParsedCron = {
+  minute: CronField
+  hour: CronField
+  dayOfMonth: CronField
+  month: CronField
+  dayOfWeek: CronField
+}
+
+const PART_RE = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/
+
+function parseField(
+  spec: string,
+  min: number,
+  max: number,
+  expr: string,
+): CronField {
+  if (spec === '*') return { any: true, values: new Set() }
+  const values = new Set<number>()
+  for (const part of spec.split(',')) {
+    const m = PART_RE.exec(part)
+    if (!m) throw new Error(`[bunderstack] invalid cron "${expr}": "${part}"`)
+    const step = m[2] !== undefined ? Number(m[2]) : 1
+    let lo: number
+    let hi: number
+    if (m[1] === '*') {
+      lo = min
+      hi = max
+    } else if (m[1]!.includes('-')) {
+      const [a, b] = m[1]!.split('-')
+      lo = Number(a)
+      hi = Number(b)
+    } else {
+      lo = Number(m[1])
+      // "5/15" means "starting at 5, every 15" per cron convention.
+      hi = step > 1 ? max : lo
+    }
+    if (step < 1 || lo < min || hi > max || lo > hi) {
+      throw new Error(`[bunderstack] invalid cron "${expr}": "${part}"`)
+    }
+    for (let v = lo; v <= hi; v += step) values.add(v)
+  }
+  return { any: false, values }
+}
+
+export function parseCron(expr: string): ParsedCron {
+  const parts = expr.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new Error(
+      `[bunderstack] invalid cron "${expr}": expected 5 fields (minute hour day-of-month month day-of-week)`,
+    )
+  }
+  const dow = parseField(parts[4]!, 0, 7, expr)
+  return {
+    minute: parseField(parts[0]!, 0, 59, expr),
+    hour: parseField(parts[1]!, 0, 23, expr),
+    dayOfMonth: parseField(parts[2]!, 1, 31, expr),
+    month: parseField(parts[3]!, 1, 12, expr),
+    // 7 is an alias for Sunday (0).
+    dayOfWeek: dow.any
+      ? dow
+      : { any: false, values: new Set([...dow.values].map((v) => v % 7)) },
+  }
+}
+
+function inField(field: CronField, value: number): boolean {
+  return field.any || field.values.has(value)
+}
+
+/** Whether the minute containing `epochMs` matches, evaluated in UTC. */
+export function cronMatches(cron: ParsedCron, epochMs: number): boolean {
+  const d = new Date(epochMs)
+  if (!inField(cron.minute, d.getUTCMinutes())) return false
+  if (!inField(cron.hour, d.getUTCHours())) return false
+  if (!inField(cron.month, d.getUTCMonth() + 1)) return false
+  const domOk = inField(cron.dayOfMonth, d.getUTCDate())
+  const dowOk = inField(cron.dayOfWeek, d.getUTCDay())
+  // Standard cron rule: when BOTH day fields are restricted, either may match.
+  return !cron.dayOfMonth.any && !cron.dayOfWeek.any
+    ? domOk || dowOk
+    : domOk && dowOk
+}

package/src/jobs/define.ts

@@ -0,0 +1,171 @@
+// src/jobs/define.ts — job definition types and the typed builder.
+// `createJobsBuilder` mirrors `createTRPC`: it exists purely to carry
+// TSchema/TEnvResult typing into inline callbacks and extracted files.
+import type { ZodType } from 'zod'
+
+import type { DbFor } from '../db'
+import type { EmailFacade } from '../email'
+import type { StorageFacade } from '../index'
+
+import { parseCron } from './cron'
+
+export const DEFAULT_RETRIES = 3
+export const DEFAULT_TIMEOUT_MS = 60_000
+
+export type EnqueueOptions = {
+  /** Collapse duplicate enqueues; see spec for cron vs non-cron lifetime. */
+  dedupeKey?: string
+  /** Milliseconds from now until the job becomes claimable. */
+  delay?: number
+  /** Absolute time the job becomes claimable; wins over `delay`. */
+  runAt?: Date | number
+}
+
+/**
+ * The untyped runtime facade. Handler ctx and tRPC ctx expose this shape;
+ * `app.jobs` narrows `enqueue` to the declared job names/payloads.
+ */
+export type JobsRuntimeFacade = {
+  enqueue(
+    name: string,
+    input?: unknown,
+    opts?: EnqueueOptions,
+  ): Promise<{ id: string }>
+  /** Run one poll cycle deterministically (tests). `now` defaults to Date.now(). */
+  tick(now?: number): Promise<void>
+}
+
+export type JobContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = {
+  db: DbFor<TSchema>
+  env: TEnvResult
+  email: EmailFacade
+  storage: StorageFacade
+  jobs: JobsRuntimeFacade
+}
+
+export type JobDefinition<
+  TInput,
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = {
+  /** zod schema for the payload; parsed at enqueue AND before the handler runs. */
+  input?: ZodType<TInput>
+  /** Attempts after the first failure. Default 3 (so 4 total attempts). */
+  retries?: number
+  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */
+  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }
+  /** Max simultaneous `running` rows of this type, enforced cross-replica. */
+  concurrency?: number
+  /** Lease duration in ms; an expired lease sends the job back to pending. */
+  timeout?: number
+  /** 5-field UTC cron expression. Cron jobs cannot declare `input`. */
+  cron?: string
+  handler: (
+    input: TInput,
+    ctx: JobContext<TSchema, TEnvResult>,
+  ) => Promise<void> | void
+  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */
+  onFailed?: (
+    input: TInput,
+    error: Error,
+    ctx: JobContext<TSchema, TEnvResult>,
+  ) => Promise<void> | void
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyJobDefinition = JobDefinition<any, any, any>
+export type JobsDefs = Record<string, AnyJobDefinition>
+
+/** Throws when a definition is unusable. Safe to call more than once. */
+export function validateJobsDefs(defs: JobsDefs): void {
+  for (const [name, def] of Object.entries(defs)) {
+    if (typeof def.handler !== 'function') {
+      throw new Error(`[bunderstack] job "${name}" has no handler`)
+    }
+    if (def.cron !== undefined) {
+      parseCron(def.cron) // throws with a clear message on invalid expressions
+      if (def.input !== undefined) {
+        throw new Error(
+          `[bunderstack] job "${name}": cron jobs cannot declare input (nothing enqueues a payload for a schedule)`,
+        )
+      }
+    }
+    if (def.retries !== undefined && (def.retries < 0 || !Number.isInteger(def.retries))) {
+      throw new Error(`[bunderstack] job "${name}": retries must be a non-negative integer`)
+    }
+    if (def.concurrency !== undefined && (def.concurrency < 1 || !Number.isInteger(def.concurrency))) {
+      throw new Error(`[bunderstack] job "${name}": concurrency must be a positive integer`)
+    }
+    if (def.timeout !== undefined && def.timeout <= 0) {
+      throw new Error(`[bunderstack] job "${name}": timeout must be positive`)
+    }
+  }
+}
+
+/** Delay in ms before retry `attempt` (1-based = the attempt that just failed). */
+export function backoffMs(def: AnyJobDefinition, attempt: number): number {
+  const b = def.backoff
+  if (typeof b === 'function') return b(attempt)
+  const baseMs = b?.baseMs ?? 1000
+  const factor = b?.factor ?? 2
+  return baseMs * factor ** (attempt - 1)
+}
+
+/**
+ * Build the `j` instance bunderstack hands to the config's `jobs` builder
+ * callback (and exports for multi-file job setups).
+ */
+export function createJobsBuilder<
+  TSchema extends Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+>() {
+  return {
+    /** Identity with inference: pins TInput from the zod schema. */
+    job<TInput = undefined>(
+      def: JobDefinition<TInput, TSchema, TEnvResult>,
+    ): JobDefinition<TInput, TSchema, TEnvResult> {
+      return def
+    },
+    /** Identity with validation: returns the defs map, typed. */
+    define<TDefs extends JobsDefs>(defs: TDefs): TDefs {
+      validateJobsDefs(defs)
+      return defs
+    },
+  }
+}
+
+/** Type of the `j` instance — for builder callbacks declared in separate files. */
+export type BunderstackJobsBuilder<
+  TSchema extends Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = ReturnType<typeof createJobsBuilder<TSchema, TEnvResult>>
+
+// Infers TInput from the JobDefinition's own type argument rather than
+// pattern-matching the (optional, so union-with-undefined) `input` property —
+// `TDef extends { input: ZodType<infer I> }` fails structurally because
+// `input?: ZodType<TInput>` desugars to `ZodType<TInput> | undefined`, which
+// can never satisfy a required-property pattern.
+type JobInputOf<TDef> = TDef extends JobDefinition<infer TInput, any, any>
+  ? TInput
+  : undefined
+
+/**
+ * `app.jobs`: `enqueue` narrowed to declared names + payloads. `Omit`s the
+ * runtime facade's loose `enqueue` first — intersecting two same-named
+ * methods instead would make TS treat them as overloaded, so the loose
+ * `(name: string, ...)` signature would still accept any name.
+ */
+export type JobsFacade<TDefs extends JobsDefs> = Omit<
+  JobsRuntimeFacade,
+  'enqueue'
+> & {
+  enqueue<K extends keyof TDefs & string>(
+    name: K,
+    ...rest: JobInputOf<TDefs[K]> extends undefined
+      ? [input?: undefined, opts?: EnqueueOptions]
+      : [input: JobInputOf<TDefs[K]>, opts?: EnqueueOptions]
+  ): Promise<{ id: string }>
+}

package/src/jobs/index.ts

@@ -0,0 +1,20 @@
+// src/jobs/index.ts — module surface consumed by createBunderstack.
+export {
+  createJobsBuilder,
+  validateJobsDefs,
+  DEFAULT_RETRIES,
+  DEFAULT_TIMEOUT_MS,
+} from './define'
+export type {
+  AnyJobDefinition,
+  BunderstackJobsBuilder,
+  EnqueueOptions,
+  JobContext,
+  JobDefinition,
+  JobsDefs,
+  JobsFacade,
+  JobsRuntimeFacade,
+} from './define'
+export { enqueueJob } from './queue'
+export { createJobRunner } from './worker'
+export { parseCron, cronMatches } from './cron'

package/src/jobs/queue.ts

@@ -0,0 +1,57 @@
+// src/jobs/queue.ts — durable enqueue with constraint-backed dedupe.
+import { and, eq } from 'drizzle-orm'
+
+import type { AnyDb } from '../dialect'
+import type { EnqueueOptions, JobsDefs } from './define'
+
+import { jobsTableFor } from '../internal-tables'
+import { generate } from '../typeid'
+
+export async function enqueueJob(
+  db: AnyDb,
+  defs: JobsDefs,
+  name: string,
+  input: unknown,
+  opts: EnqueueOptions = {},
+): Promise<{ id: string }> {
+  const def = defs[name]
+  if (!def) throw new Error(`[bunderstack] unknown job type "${name}"`)
+  // Fail fast: a bad payload should throw at the call site, not in the worker.
+  const parsed = def.input ? def.input.parse(input) : null
+  const t = jobsTableFor(db)
+  const now = Date.now()
+  const runAt =
+    opts.runAt !== undefined
+      ? new Date(opts.runAt).getTime()
+      : now + (opts.delay ?? 0)
+
+  // Two rounds cover the race where the deduping row reaches a terminal state
+  // (clearing its key) between our failed insert and our read.
+  for (let round = 0; round < 2; round++) {
+    const id = generate('job')
+    const insertedRows = await db
+      .insert(t)
+      .values({
+        id,
+        type: name,
+        payloadJson: JSON.stringify(parsed),
+        status: 'pending',
+        attempts: 0,
+        runAt,
+        dedupeKey: opts.dedupeKey ?? null,
+        createdAt: now,
+      })
+      .onConflictDoNothing({ target: [t.type, t.dedupeKey] })
+      .returning({ id: t.id })
+    if (insertedRows[0]) return { id: String(insertedRows[0].id) }
+    const existing = await db
+      .select({ id: t.id })
+      .from(t)
+      .where(and(eq(t.type, name), eq(t.dedupeKey, opts.dedupeKey ?? '')))
+      .limit(1)
+    if (existing[0]) return { id: String(existing[0].id) }
+  }
+  throw new Error(
+    `[bunderstack] enqueue of "${name}" lost a dedupe race twice — please retry`,
+  )
+}

package/src/jobs/worker.ts

@@ -0,0 +1,290 @@
+// src/jobs/worker.ts — the in-process worker. One `tick()` is a full cycle:
+// recover expired leases → schedule cron slots → reap old succeeded rows →
+// claim and run claimable jobs (awaiting handlers, so tests drive `tick()`
+// deterministically with an injected `now`). Multiple replicas run the same
+// loop safely: claims are atomic and cron slots dedupe on a unique index.
+import { and, eq, inArray, is, isNotNull, lt, lte, sql } from 'drizzle-orm'
+import { PgDatabase } from 'drizzle-orm/pg-core'
+
+import type { AnyDb } from '../dialect'
+import type {
+  AnyJobDefinition,
+  JobsDefs,
+  JobsRuntimeFacade,
+} from './define'
+import type { ParsedCron } from './cron'
+
+import { jobsTableFor } from '../internal-tables'
+import { cronMatches, parseCron } from './cron'
+import { backoffMs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './define'
+import { enqueueJob } from './queue'
+
+const CLAIM_BATCH = 10
+const SUCCEEDED_RETENTION_MS = 24 * 60 * 60 * 1000
+
+type JobRow = {
+  id: string
+  type: string
+  payloadJson: string
+  attempts: number
+}
+
+function toError(err: unknown): Error {
+  return err instanceof Error ? err : new Error(String(err))
+}
+
+function maxAttempts(def: AnyJobDefinition): number {
+  return 1 + (def.retries ?? DEFAULT_RETRIES)
+}
+
+/** Terminal-status column patch: non-cron jobs release their dedupe key. */
+function terminalPatch(def: AnyJobDefinition | undefined) {
+  return def?.cron ? {} : { dedupeKey: null }
+}
+
+export function createJobRunner(deps: {
+  db: AnyDb
+  defs: JobsDefs
+  /** Handler ctx WITHOUT `jobs`; the facade is injected via setJobsFacade. */
+  ctx: Record<string, unknown>
+}) {
+  const { db, defs } = deps
+  const t = jobsTableFor(db)
+  const ctx = { ...deps.ctx } as Record<string, unknown>
+  const crons = new Map<string, ParsedCron>()
+  for (const [name, def] of Object.entries(defs)) {
+    if (def.cron) crons.set(name, parseCron(def.cron))
+  }
+
+  async function fireOnFailed(
+    def: AnyJobDefinition,
+    payloadJson: string,
+    error: Error,
+  ) {
+    if (!def.onFailed) return
+    let input: unknown
+    try {
+      const raw = JSON.parse(payloadJson)
+      input = def.input ? def.input.parse(raw) : undefined
+    } catch {
+      input = undefined // payload unusable; the hook still gets the error
+    }
+    try {
+      await def.onFailed(input, error, ctx as never)
+    } catch (hookErr) {
+      console.error('[bunderstack] onFailed hook threw:', hookErr)
+    }
+  }
+
+  /** running rows whose lease expired → pending (or failed when exhausted). */
+  async function recoverExpiredLeases(now: number) {
+    const expired: (JobRow & { lastError: string | null })[] = await db
+      .select({
+        id: t.id,
+        type: t.type,
+        payloadJson: t.payloadJson,
+        attempts: t.attempts,
+        lastError: t.lastError,
+      })
+      .from(t)
+      .where(
+        and(eq(t.status, 'running'), isNotNull(t.lockedUntil), lt(t.lockedUntil, now)),
+      )
+    for (const row of expired) {
+      const def = defs[row.type]
+      const error = new Error('lease expired (worker crashed or timed out)')
+      if (!def) {
+        await db
+          .update(t)
+          .set({
+            status: 'failed',
+            finishedAt: now,
+            lockedUntil: null,
+            lastError: `unknown job type "${row.type}"`,
+            dedupeKey: null,
+          })
+          .where(eq(t.id, row.id))
+        continue
+      }
+      if (Number(row.attempts) >= maxAttempts(def)) {
+        await db
+          .update(t)
+          .set({
+            status: 'failed',
+            finishedAt: now,
+            lockedUntil: null,
+            lastError: error.message,
+            ...terminalPatch(def),
+          })
+          .where(eq(t.id, row.id))
+        await fireOnFailed(def, row.payloadJson, error)
+      } else {
+        await db
+          .update(t)
+          .set({
+            status: 'pending',
+            lockedUntil: null,
+            runAt: now + backoffMs(def, Number(row.attempts)),
+            lastError: error.message,
+          })
+          .where(eq(t.id, row.id))
+      }
+    }
+  }
+
+  /** Enqueue the current minute's slot for every cron definition. */
+  async function scheduleCronSlots(now: number) {
+    const minute = Math.floor(now / 60_000) * 60_000
+    for (const [name, cron] of crons) {
+      if (!cronMatches(cron, minute)) continue
+      // The unique (type, dedupe_key) index collapses concurrent replicas'
+      // enqueues of the same slot into one row.
+      await enqueueJob(db, defs, name, undefined, {
+        dedupeKey: `cron:${name}:${minute}`,
+        runAt: minute,
+      })
+    }
+  }
+
+  async function reapSucceeded(now: number) {
+    await db
+      .delete(t)
+      .where(
+        and(
+          eq(t.status, 'succeeded'),
+          lt(t.finishedAt, now - SUCCEEDED_RETENTION_MS),
+        ),
+      )
+  }
+
+  /** Atomically claim up to `limit` runnable jobs of one type. */
+  async function claim(
+    type: string,
+    limit: number,
+    now: number,
+    leaseUntil: number,
+  ): Promise<JobRow[]> {
+    const pendingIds = db
+      .select({ id: t.id })
+      .from(t)
+      .where(and(eq(t.type, type), eq(t.status, 'pending'), lte(t.runAt, now)))
+      .orderBy(t.runAt)
+      .limit(limit)
+    // PG: lock the selected rows so concurrent replicas skip them. SQLite's
+    // single-writer model makes the one-statement UPDATE atomic on its own.
+    const sub = is(db, PgDatabase)
+      ? (pendingIds as unknown as { for: (m: string, o: object) => typeof pendingIds })
+          .for('update', { skipLocked: true })
+      : pendingIds
+    const rows: JobRow[] = await db
+      .update(t)
+      .set({
+        status: 'running',
+        lockedUntil: leaseUntil,
+        attempts: sql`${t.attempts} + 1`,
+      })
+      .where(and(inArray(t.id, sub), eq(t.status, 'pending')))
+      .returning({
+        id: t.id,
+        type: t.type,
+        payloadJson: t.payloadJson,
+        attempts: t.attempts,
+      })
+    return rows
+  }
+
+  // `now` is the tick's injected clock: retry runAt math uses it so tests can
+  // drive backoff deterministically. finishedAt uses the real clock (a handler
+  // may run long past the tick's start).
+  async function runJob(row: JobRow, def: AnyJobDefinition, now: number) {
+    let input: unknown
+    try {
+      const raw = JSON.parse(row.payloadJson)
+      input = def.input ? def.input.parse(raw) : undefined
+    } catch (err) {
+      // Stored payload no longer parses (schema drift): retrying can't help.
+      const e = toError(err)
+      await db
+        .update(t)
+        .set({
+          status: 'failed',
+          finishedAt: Date.now(),
+          lockedUntil: null,
+          lastError: e.message,
+          ...terminalPatch(def),
+        })
+        .where(eq(t.id, row.id))
+      await fireOnFailed(def, row.payloadJson, e)
+      return
+    }
+    try {
+      await def.handler(input, ctx as never)
+      await db
+        .update(t)
+        .set({
+          status: 'succeeded',
+          finishedAt: Date.now(),
+          lockedUntil: null,
+          ...terminalPatch(def),
+        })
+        .where(eq(t.id, row.id))
+    } catch (err) {
+      const e = toError(err)
+      if (Number(row.attempts) < maxAttempts(def)) {
+        await db
+          .update(t)
+          .set({
+            status: 'pending',
+            lockedUntil: null,
+            runAt: now + backoffMs(def, Number(row.attempts)),
+            lastError: e.message,
+          })
+          .where(eq(t.id, row.id))
+      } else {
+        await db
+          .update(t)
+          .set({
+            status: 'failed',
+            finishedAt: Date.now(),
+            lockedUntil: null,
+            lastError: e.message,
+            ...terminalPatch(def),
+          })
+          .where(eq(t.id, row.id))
+        await fireOnFailed(def, row.payloadJson, e)
+      }
+    }
+  }
+
+  async function runClaimable(now: number) {
+    const work: Promise<void>[] = []
+    for (const [type, def] of Object.entries(defs)) {
+      let limit = CLAIM_BATCH
+      if (def.concurrency !== undefined) {
+        const runningRows = await db
+          .select({ id: t.id })
+          .from(t)
+          .where(and(eq(t.type, type), eq(t.status, 'running')))
+        const capacity = def.concurrency - runningRows.length
+        if (capacity <= 0) continue
+        limit = Math.min(limit, capacity)
+      }
+      const leaseUntil = now + (def.timeout ?? DEFAULT_TIMEOUT_MS)
+      const claimed = await claim(type, limit, now, leaseUntil)
+      for (const row of claimed) work.push(runJob(row, def, now))
+    }
+    await Promise.all(work)
+  }
+
+  return {
+    async tick(now: number = Date.now()) {
+      await recoverExpiredLeases(now)
+      await scheduleCronSlots(now)
+      await reapSucceeded(now)
+      await runClaimable(now)
+    },
+    setJobsFacade(f: JobsRuntimeFacade) {
+      ctx.jobs = f
+    },
+  }
+}

package/src/manifest.ts

@@ -6,9 +6,11 @@ import type { ZodType } from 'zod'
 
 import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
+import type { JobsDefs } from './jobs/define'
 import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
 
 export type ManifestEnvVar = { key: string; required: boolean }
+export type ManifestJob = { name: string; cron?: string }
 
 export type BunderstackManifest = {
   dialect: Dialect
@@ -17,6 +19,7 @@ export type BunderstackManifest = {
   buckets: { name: string; visibility: ResolvedBucket['visibility'] }[]
   realtime: boolean
   env: { server: ManifestEnvVar[]; client: ManifestEnvVar[] }
+  jobs: ManifestJob[]
 }
 
 function describeSection(
@@ -34,6 +37,7 @@ export function buildManifest(args: {
   storage: ResolvedStorageBuckets
   envConfig: EnvConfigInput | undefined
   realtime: boolean
+  jobs: JobsDefs | undefined
 }): BunderstackManifest {
   return {
     dialect: args.dialect,
@@ -48,5 +52,8 @@ export function buildManifest(args: {
       server: describeSection(args.envConfig?.server),
       client: describeSection(args.envConfig?.client),
     },
+    jobs: Object.entries(args.jobs ?? {}).map(([name, def]) =>
+      def.cron !== undefined ? { name, cron: def.cron } : { name },
+    ),
   }
 }

package/src/schema-export-pg.ts

@@ -3,4 +3,5 @@
 export {
   bunderstackFilesPg as bunderstackFiles,
   bunderstackIdempotencyPg as bunderstackIdempotency,
+  bunderstackJobsPg as bunderstackJobs,
 } from './internal-tables-pg'

package/src/schema-export.ts

@@ -1,4 +1,5 @@
 export {
   bunderstackFiles,
   bunderstackIdempotency,
+  bunderstackJobs,
 } from './internal-tables'

package/src/trpc.ts

@@ -5,6 +5,7 @@ import superjson from 'superjson'
 import type { AccessUser } from './access'
 import type { DbFor } from './db'
 import type { EmailFacade } from './email'
+import type { JobsRuntimeFacade } from './jobs/index'
 
 export type TRPCContext<
   TSchema extends Record<string, unknown>,
@@ -14,6 +15,7 @@ export type TRPCContext<
   user: AccessUser | null
   env: TEnvResult
   email: EmailFacade
+  jobs: JobsRuntimeFacade
   req: Request
 }