bunderstack 0.15.2 → 0.17.0-beta.0

package/src/internal-tables-pg.ts

@@ -67,20 +67,4 @@ export const bunderstackJobsPg = pgTable(
   ],
 )
 
-export const bunderstackCronRunsPg = pgTable(
-  '_bunderstack_cron_runs',
-  {
-    taskId: text('task_id').notNull(),
-    scheduledAt: bigint('scheduled_at', { mode: 'number' }).notNull(),
-    status: text('status').notNull(),
-    attempts: integer('attempts').notNull().default(0),
-    lockedUntil: bigint('locked_until', { mode: 'number' }),
-    lastError: text('last_error'),
-    startedAt: bigint('started_at', { mode: 'number' }),
-    finishedAt: bigint('finished_at', { mode: 'number' }),
-  },
-  (t) => [
-    primaryKey({ columns: [t.taskId, t.scheduledAt] }),
-    index('bcr_claim').on(t.status, t.lockedUntil),
-  ],
-)
+

package/src/internal-tables.ts

@@ -12,7 +12,6 @@ import {
 import { detectDialect } from './dialect'
 import {
   bunderstackFilesPg,
-  bunderstackCronRunsPg,
   bunderstackIdempotencyPg,
   bunderstackJobsPg,
 } from './internal-tables-pg'
@@ -74,43 +73,22 @@ export const bunderstackJobs = sqliteTable(
   ],
 )
 
-export const bunderstackCronRuns = sqliteTable(
-  '_bunderstack_cron_runs',
-  {
-    taskId: text('task_id').notNull(),
-    scheduledAt: integer('scheduled_at').notNull(),
-    status: text('status').notNull(),
-    attempts: integer('attempts').notNull().default(0),
-    lockedUntil: integer('locked_until'),
-    lastError: text('last_error'),
-    startedAt: integer('started_at'),
-    finishedAt: integer('finished_at'),
-  },
-  (t) => [
-    primaryKey({ columns: [t.taskId, t.scheduledAt] }),
-    index('bcr_claim').on(t.status, t.lockedUntil),
-  ],
-)
-
 export const INTERNAL_TABLES = {
   bunderstackFiles,
   bunderstackIdempotency,
   bunderstackJobs,
-  bunderstackCronRuns,
 } as const
 
 export const INTERNAL_TABLE_NAMES: ReadonlySet<string> = new Set([
   'bunderstack_file_meta',
   '_bunderstack_idempotency',
   '_bunderstack_jobs',
-  '_bunderstack_cron_runs',
 ])
 
 export const INTERNAL_TABLES_PG = {
   bunderstackFiles: bunderstackFilesPg,
   bunderstackIdempotency: bunderstackIdempotencyPg,
   bunderstackJobs: bunderstackJobsPg,
-  bunderstackCronRuns: bunderstackCronRunsPg,
 } as const
 
 // Both dialect twins count as "ours" for the re-export identity check.
@@ -121,10 +99,6 @@ const INTERNAL_TABLE_CANDIDATES = new Map<string, readonly unknown[]>([
     [bunderstackIdempotency, bunderstackIdempotencyPg],
   ],
   [getTableName(bunderstackJobs), [bunderstackJobs, bunderstackJobsPg]],
-  [
-    getTableName(bunderstackCronRuns),
-    [bunderstackCronRuns, bunderstackCronRunsPg],
-  ],
 ])
 
 /** Internal file-meta table matching the db's dialect. */
@@ -142,11 +116,6 @@ export function jobsTableFor(db: unknown) {
   return is(db, PgDatabase) ? bunderstackJobsPg : bunderstackJobs
 }
 
-/** Internal cron-run table matching the db's dialect. */
-export function cronRunsTableFor(db: unknown) {
-  return is(db, PgDatabase) ? bunderstackCronRunsPg : bunderstackCronRuns
-}
-
 export function withInternalTables<TSchema extends Record<string, unknown>>(
   schema: TSchema,
 ): TSchema & typeof INTERNAL_TABLES {

package/src/jobs/define.ts

@@ -1,13 +1,14 @@
 // src/jobs/define.ts — job definition types and the typed builder.
-// `createJobsBuilder` mirrors `createTRPC`: it exists purely to carry
+// `createJobsBuilder` exists purely to carry
 // TSchema/TEnvResult typing into inline callbacks and extracted files.
-import type { ZodType } from 'zod'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 import type { DbFor } from '../db'
 import type { EmailFacade } from '../email'
 import type { StorageFacade } from '../index'
 
 import { parseCron } from './cron'
+import { CRON_PREFIX, type CatchUp } from './slots'
 
 export const DEFAULT_RETRIES = 3
 export const DEFAULT_TIMEOUT_MS = 60_000
@@ -21,8 +22,17 @@ export type EnqueueOptions = {
   runAt?: Date | number
 }
 
+export type TickResult = {
+  /** Rows moved from pending to running this tick. */
+  claimed: number
+  /** Handlers that completed successfully. */
+  ran: number
+  /** Handlers that threw, whether or not they will be retried. */
+  failed: number
+}
+
 /**
- * The untyped runtime facade. Handler ctx and tRPC ctx expose this shape;
+ * The untyped runtime facade. Job handlers and API context expose this shape;
  * `app.jobs` narrows `enqueue` to the declared job names/payloads.
  */
 export type JobsRuntimeFacade = {
@@ -32,7 +42,7 @@ export type JobsRuntimeFacade = {
     opts?: EnqueueOptions,
   ): Promise<{ id: string }>
   /** Run one poll cycle deterministically (tests). `now` defaults to Date.now(). */
-  tick(now?: number): Promise<void>
+  tick(now?: number): Promise<TickResult>
 }
 
 import type { RealtimeFacade } from '../realtime/facade'
@@ -60,13 +70,13 @@ export type QueueJobDefinition<
   TEnvResult = Record<string, unknown>,
 > = {
   kind: 'job'
-  /** zod schema for the payload; parsed at enqueue AND before the handler runs. */
-  input?: ZodType<TInput>
+  /** Standard Schema payload; parsed at enqueue AND before the handler runs. */
+  input?: StandardSchemaV1<unknown, 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. */
+  /** Max simultaneous `running` rows of this type, enforced per worker. */
   concurrency?: number
   /** Lease duration in ms; an expired lease sends the job back to pending. */
   timeout?: number
@@ -91,10 +101,26 @@ export type CronDefinition<
 > = {
   kind: 'cron'
   schedule: TSchedule
+  /** 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 }
+  /** Lease duration in ms; an expired lease sends the slot back to pending. */
+  timeout?: number
+  /** How missed slots are handled on wake. Default 'latest'. */
+  catchUp?: CatchUp
+  /** How far back catch-up looks, in ms. Default 1 hour. */
+  catchUpWindow?: number
   handler: (
     invocation: CronInvocation,
     ctx: JobContext<TSchema, TEnvResult>,
   ) => Promise<void> | void
+  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */
+  onFailed?: (
+    invocation: CronInvocation,
+    error: Error,
+    ctx: JobContext<TSchema, TEnvResult>,
+  ) => Promise<void> | void
 }
 
 export type BackgroundDefinition =
@@ -111,6 +137,10 @@ export type JobDefinition<
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyJobDefinition = QueueJobDefinition<any, any, any>
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyBackgroundDefinition =
+  | QueueJobDefinition<any, any, any>
+  | CronDefinition<any, any, any>
 export type JobsDefs = BackgroundDefs
 
 export type QueueJobKeys<TDefs extends BackgroundDefs> = {
@@ -129,18 +159,38 @@ export function validateBackgroundDefs(defs: BackgroundDefs): void {
     if (typeof def.handler !== 'function') {
       throw new Error(`[bunderstack] background task "${name}" has no handler`)
     }
-    if (def.kind === 'cron') {
-      parseCron(def.schedule)
-      continue
+    if (def.kind === 'job' && name.startsWith(CRON_PREFIX)) {
+      throw new Error(
+        `[bunderstack] job "${name}": the "${CRON_PREFIX}" prefix is reserved for cron tasks`,
+      )
     }
     if (
       def.retries !== undefined &&
       (def.retries < 0 || !Number.isInteger(def.retries))
     ) {
       throw new Error(
-        `[bunderstack] job "${name}": retries must be a non-negative integer`,
+        `[bunderstack] background task "${name}": retries must be a non-negative integer`,
+      )
+    }
+    if (def.timeout !== undefined && def.timeout <= 0) {
+      throw new Error(
+        `[bunderstack] background task "${name}": timeout must be positive`,
       )
     }
+    if (def.kind === 'cron') {
+      parseCron(def.schedule)
+      if ((def as { concurrency?: number }).concurrency !== undefined) {
+        throw new Error(
+          `[bunderstack] cron "${name}": concurrency is not supported for cron tasks — slots are already unique`,
+        )
+      }
+      if (def.catchUpWindow !== undefined && def.catchUpWindow <= 0) {
+        throw new Error(
+          `[bunderstack] cron "${name}": catchUpWindow must be positive`,
+        )
+      }
+      continue
+    }
     if (
       def.concurrency !== undefined &&
       (def.concurrency < 1 || !Number.isInteger(def.concurrency))
@@ -149,22 +199,27 @@ export function validateBackgroundDefs(defs: BackgroundDefs): void {
         `[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`)
-    }
   }
 }
 
 /** @deprecated Use validateBackgroundDefs. */
 export const validateJobsDefs = validateBackgroundDefs
 
-/** Delay in ms before retry `attempt` (1-based = the attempt that just failed). */
-export function backoffMs(def: AnyJobDefinition, attempt: number): number {
+/**
+ * Delay in ms before retry `attempt` (1-based = the attempt that just failed).
+ * Jittered by ±20% so a shared outage does not retry every job in lockstep.
+ * A caller-supplied backoff function is returned verbatim — the caller owns it.
+ */
+export function backoffMs(
+  def: AnyBackgroundDefinition,
+  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)
+  const flat = baseMs * factor ** (attempt - 1)
+  return Math.round(flat * (0.8 + Math.random() * 0.4))
 }
 
 /**
@@ -176,7 +231,7 @@ export function createJobsBuilder<
   TEnvResult = Record<string, unknown>,
 >() {
   return {
-    /** Identity with inference: pins TInput from the zod schema. */
+    /** Identity with inference: pins TInput from the schema output. */
     job<TInput = undefined>(
       def: Omit<QueueJobDefinition<TInput, TSchema, TEnvResult>, 'kind'>,
     ): QueueJobDefinition<TInput, TSchema, TEnvResult> {
@@ -204,9 +259,8 @@ export type BunderstackJobsBuilder<
 
 // 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.
+// A required-property pattern fails structurally because `input` is optional,
+// so infer from the definition's own type argument instead.
 type JobInputOf<TDef> =
   TDef extends QueueJobDefinition<infer TInput, any, any> ? TInput : undefined
 

package/src/jobs/index.ts

@@ -25,19 +25,13 @@ export type {
 } from './define'
 export { enqueueJob } from './queue'
 export { createJobRunner } from './worker'
-export { runCronSlot, runScheduledSlot } from './cron-runner'
-export type { CronRunResult } from './cron-runner'
-export { buildCronRouter } from './cron-router'
-export { signScheduleRequest, verifyScheduleRequest } from './cron-auth'
 export { startJobWorker } from './runtime'
 export type {
   StartWorkerOptions,
   RunWorkerOptions,
   WorkerHandle,
 } from './runtime'
-export { startLocalCronScheduler } from './local-cron'
-export type {
-  LocalCronScheduler,
-  LocalCronSchedulerOptions,
-} from './local-cron'
 export { parseCron, cronMatches } from './cron'
+export { slotsDue, floorSlot, CRON_PREFIX, SLOT_MS } from './slots'
+export type { CatchUp } from './slots'
+export type { TickResult } from './define'

package/src/jobs/queue.ts

@@ -5,7 +5,9 @@ import type { AnyDb } from '../dialect'
 import type { EnqueueOptions, JobsDefs } from './define'
 
 import { jobsTableFor } from '../internal-tables'
+import { validateStandardSchema } from '../standard-schema'
 import { generate } from '../typeid'
+import { CRON_PREFIX } from './slots'
 
 export async function enqueueJob(
   db: AnyDb,
@@ -15,11 +17,17 @@ export async function enqueueJob(
   opts: EnqueueOptions = {},
 ): Promise<{ id: string }> {
   const def = defs[name]
-  if (!def || def.kind !== 'job') {
-    throw new Error(`[bunderstack] unknown queue job "${name}"`)
+  if (!def) {
+    throw new Error(`[bunderstack] unknown background task "${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 isCron = def.kind === 'cron'
+  const type = isCron ? `${CRON_PREFIX}${name}` : name
+  // Cron slots carry no payload; queue jobs validate theirs at the call site.
+  const parsed = isCron
+    ? null
+    : def.input
+      ? validateStandardSchema(def.input, input, `job "${name}" input`)
+      : null
   const t = jobsTableFor(db)
   const now = Date.now()
   const runAt =
@@ -35,7 +43,7 @@ export async function enqueueJob(
       .insert(t)
       .values({
         id,
-        type: name,
+        type,
         payloadJson: JSON.stringify(parsed),
         status: 'pending',
         attempts: 0,
@@ -49,7 +57,7 @@ export async function enqueueJob(
     const existing = await db
       .select({ id: t.id })
       .from(t)
-      .where(and(eq(t.type, name), eq(t.dedupeKey, opts.dedupeKey ?? '')))
+      .where(and(eq(t.type, type), eq(t.dedupeKey, opts.dedupeKey ?? '')))
       .limit(1)
     if (existing[0]) return { id: String(existing[0].id) }
   }

package/src/jobs/slots.ts

@@ -0,0 +1,52 @@
+// src/jobs/slots.ts — cron slot enumeration. Pure; no db, no clock reads.
+import { cronMatches, type ParsedCron } from './cron'
+
+/** Slot granularity. Every slot timestamp satisfies `slot % SLOT_MS === 0`. */
+export const SLOT_MS = 60_000
+
+/** Reserved job-type prefix for cron occurrences. */
+export const CRON_PREFIX = 'cron:'
+
+/** How far back either catch-up mode will look. */
+export const DEFAULT_CATCH_UP_WINDOW_MS = 60 * SLOT_MS
+
+export type CatchUp = 'latest' | 'all'
+
+/** Aligns `ms` down to its containing slot. */
+export function floorSlot(ms: number): number {
+  return Math.floor(ms / SLOT_MS) * SLOT_MS
+}
+
+/**
+ * Slots matching `cron` in the half-open range `(from, to]`, oldest first.
+ *
+ * `from` is exclusive so a stored watermark is never re-emitted. Both modes are
+ * clamped to `catchUpWindowMs` — without it a watermark far in the past would
+ * make this iterate unbounded minutes.
+ */
+export function slotsDue(args: {
+  cron: ParsedCron
+  from: number
+  to: number
+  catchUp?: CatchUp
+  catchUpWindowMs?: number
+}): number[] {
+  const catchUp = args.catchUp ?? 'latest'
+  const windowMs = args.catchUpWindowMs ?? DEFAULT_CATCH_UP_WINDOW_MS
+  const to = floorSlot(args.to)
+  const from = Math.max(floorSlot(args.from), to - windowMs)
+  if (to <= from) return []
+
+  if (catchUp === 'latest') {
+    for (let s = to; s > from; s -= SLOT_MS) {
+      if (cronMatches(args.cron, s)) return [s]
+    }
+    return []
+  }
+
+  const slots: number[] = []
+  for (let s = from + SLOT_MS; s <= to; s += SLOT_MS) {
+    if (cronMatches(args.cron, s)) slots.push(s)
+  }
+  return slots
+}