bunderstack 0.15.1 → 0.16.0

package/README.md

@@ -87,6 +87,10 @@ import { app } from './bunderstack'
 await app.runWorker()
 ```
 
+Most applications need none of this: background work runs in-process by
+default. Set `BUNDERSTACK_ROLE` to `web` or `worker` to split it across
+processes without changing code.
+
 If a queue handler calls `ctx.realtime.publish()`, the web and worker processes
 must share a realtime transport. Configure `REDIS_URL` (or
 `realtime: { redis: "redis://..." }`). `realtime: true` without Redis uses a
@@ -114,13 +118,9 @@ REDIS_URL=redis://localhost:6379 bun src/server.ts
 REDIS_URL=redis://localhost:6379 bun src/worker.ts
 ```
 
-Cron tasks (`j.cron()`) are delivered by the host to
-`POST /api/_bunderstack/cron/:name`; storage maintenance uses
-`POST /api/_bunderstack/maintenance/storage-sweep`. Production requires the
-injected `BUNDERSTACK_CRON_SECRET`. Use `await app.startCronScheduler()` only
-for local standalone development. `app.manifest.background` tells Bunderhost
-whether to deploy an always-on worker (queue jobs) or only HTTP-delivered cron
-(cron-only).
+Cron tasks (`j.cron()`) are materialized as job rows keyed by their slot, so
+they run through the same loop, retries, and timeouts as queue jobs. There is
+no separate cron process and no signed dispatch endpoint.
 
 ### Publishing custom writes to realtime
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.15.1",
+  "version": "0.16.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",
@@ -53,6 +53,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "typecheck": "tsc --noEmit",
     "dev": "bun --hot ../../examples/standalone/server.ts",
     "db:push": "drizzle-kit push",
     "db:migrate": "drizzle-kit migrate"

package/src/access.ts

@@ -103,6 +103,24 @@ export type ResolvedTableAccess = {
 
 export type ResolvedAccess = Map<string, ResolvedTableAccess>
 
+/**
+ * Look up a table's resolved access by its physical table name.
+ *
+ * `ResolvedAccess` is keyed by schema export name, not table name, so every
+ * consumer that starts from a physical name needs this scan. It lives here so
+ * CRUD, realtime, and route validation cannot drift apart on which tables they
+ * consider enabled.
+ */
+export function tableEntryForName(
+  access: ResolvedAccess,
+  tableName: string,
+): ResolvedTableAccess | undefined {
+  for (const entry of access.values()) {
+    if (entry.tableName === tableName) return entry
+  }
+  return undefined
+}
+
 const DEFAULT_READONLY = [
   'id',
   'createdAt',

package/src/blueprint-generator.ts

@@ -1,4 +1,11 @@
-import { mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import {
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
@@ -25,7 +32,9 @@ export type GenerateBlueprintResult = {
 
 export class BlueprintCheckError extends Error {
   constructor() {
-    super('bunderstack.blueprint.yaml is missing or stale; run `bunderstack blueprint`')
+    super(
+      'bunderstack.blueprint.yaml is missing or stale; run `bunderstack blueprint`',
+    )
     this.name = 'BlueprintCheckError'
   }
 }
@@ -44,7 +53,9 @@ function requireRelativePath(value: string, label: string): string {
     isAbsolute(normalized) ||
     normalized.split('/').some((part) => !part || part === '..')
   ) {
-    throw new Error(`[bunderstack] ${label} must be a relative path without traversal`)
+    throw new Error(
+      `[bunderstack] ${label} must be a relative path without traversal`,
+    )
   }
   return normalized
 }
@@ -52,27 +63,46 @@ function requireRelativePath(value: string, label: string): string {
 function resolveWithin(root: string, value: string, label: string): string {
   const path = resolve(root, requireRelativePath(value, label))
   const pathFromRoot = relative(root, path)
-  if (pathFromRoot === '..' || pathFromRoot.startsWith('../') || isAbsolute(pathFromRoot)) {
-    throw new Error(`[bunderstack] ${label} must stay within the application directory`)
+  if (
+    pathFromRoot === '..' ||
+    pathFromRoot.startsWith('../') ||
+    isAbsolute(pathFromRoot)
+  ) {
+    throw new Error(
+      `[bunderstack] ${label} must stay within the application directory`,
+    )
   }
   return path
 }
 
-function normalizeProjectPath(root: string, value: string, label: string): string {
+function normalizeProjectPath(
+  root: string,
+  value: string,
+  label: string,
+): string {
   if (!isAbsolute(value)) return requireRelativePath(value, label)
   const pathFromRoot = relative(root, resolve(value)) || '.'
   return requireRelativePath(pathFromRoot, label)
 }
 
-function requireScript(pkg: AppPackage, name: 'build' | 'start' | 'worker', required: boolean): boolean {
+function requireScript(
+  pkg: AppPackage,
+  name: 'build' | 'start' | 'worker',
+  required: boolean,
+): boolean {
   const value = pkg.scripts?.[name]
   if (typeof value === 'string' && value.trim()) return true
-  if (required) throw new Error(`[bunderstack] package.json requires a non-empty "${name}" script`)
+  if (required)
+    throw new Error(
+      `[bunderstack] package.json requires a non-empty "${name}" script`,
+    )
   return false
 }
 
 async function packageVersion(): Promise<string> {
-  const pkg = (await Bun.file(new URL('../package.json', import.meta.url)).json()) as { version: string }
+  const pkg = (await Bun.file(
+    new URL('../package.json', import.meta.url),
+  ).json()) as { version: string }
   return pkg.version
 }
 
@@ -84,28 +114,38 @@ export async function generateBlueprint(
   const pkg = JSON.parse(await readFile(packagePath, 'utf8')) as AppPackage
   const allDependencies = { ...pkg.dependencies, ...pkg.devDependencies }
   if (typeof allDependencies['@tanstack/react-start'] !== 'string') {
-    throw new Error('[bunderstack] package.json must depend on @tanstack/react-start')
+    throw new Error(
+      '[bunderstack] package.json must depend on @tanstack/react-start',
+    )
   }
   requireScript(pkg, 'build', true)
   requireScript(pkg, 'start', true)
 
   const configuredEntry = pkg.bunderstack?.entry
   const entry = requireRelativePath(
-    options.entry ?? (typeof configuredEntry === 'string' ? configuredEntry : 'src/bunderstack.ts'),
+    options.entry ??
+      (typeof configuredEntry === 'string'
+        ? configuredEntry
+        : 'src/bunderstack.ts'),
     'entry',
   )
   const entryPath = resolveWithin(directory, entry, 'entry')
   if (!(await Bun.file(entryPath).exists())) {
     throw new Error(`[bunderstack] entry does not exist: ${entry}`)
   }
-  const output = requireRelativePath(options.output ?? 'bunderstack.blueprint.yaml', 'output')
+  const output = requireRelativePath(
+    options.output ?? 'bunderstack.blueprint.yaml',
+    'output',
+  )
   const outputPath = resolveWithin(directory, output, 'output')
 
   const previousIntrospection = process.env.BUNDERSTACK_INTROSPECT
   process.env.BUNDERSTACK_INTROSPECT = '1'
   let app: { manifest?: unknown; close?: () => Promise<void> } | undefined
   try {
-    const module = (await import(`${pathToFileURL(entryPath).href}?blueprint=${Date.now()}`)) as {
+    const module = (await import(
+      `${pathToFileURL(entryPath).href}?blueprint=${Date.now()}`
+    )) as {
       app?: typeof app
     }
     app = module.app
@@ -123,7 +163,9 @@ export async function generateBlueprint(
       'meta',
       '_journal.json',
     )
-    const migrationMode = (await Bun.file(migrationJournal).exists()) ? 'migrations' : 'push'
+    const migrationMode = (await Bun.file(migrationJournal).exists())
+      ? 'migrations'
+      : 'push'
     const blueprint = blueprintFromManifest({
       manifest: {
         ...manifest,
@@ -134,12 +176,15 @@ export async function generateBlueprint(
       migrationMode,
     })
     const source = serializeBlueprint(blueprint)
-    const existing = (await Bun.file(outputPath).exists()) ? await Bun.file(outputPath).text() : undefined
+    const existing = (await Bun.file(outputPath).exists())
+      ? await Bun.file(outputPath).text()
+      : undefined
     if (options.check) {
       if (existing !== source) throw new BlueprintCheckError()
       return { path: outputPath, blueprint, source, changed: false }
     }
-    if (existing === source) return { path: outputPath, blueprint, source, changed: false }
+    if (existing === source)
+      return { path: outputPath, blueprint, source, changed: false }
     await mkdir(dirname(outputPath), { recursive: true })
     const temporary = `${outputPath}.${process.pid}.${Date.now()}.tmp`
     try {
@@ -151,7 +196,8 @@ export async function generateBlueprint(
     return { path: outputPath, blueprint, source, changed: true }
   } finally {
     await app?.close?.()
-    if (previousIntrospection === undefined) delete process.env.BUNDERSTACK_INTROSPECT
+    if (previousIntrospection === undefined)
+      delete process.env.BUNDERSTACK_INTROSPECT
     else process.env.BUNDERSTACK_INTROSPECT = previousIntrospection
   }
 }

package/src/blueprint.ts

@@ -1,9 +1,10 @@
 import { parse, stringify } from 'yaml'
 import { z } from 'zod'
 
-import { parseCron } from './jobs/cron'
 import type { BunderstackManifest } from './manifest'
 
+import { parseCron } from './jobs/cron'
+
 export type MigrationMode = 'migrations' | 'push'
 
 export type BunderstackBlueprint = {
@@ -48,12 +49,18 @@ const cronSchedule = nonEmpty.refine(
 const blueprintSchema = z
   .object({
     version: z.literal(1),
-    generator: z.object({ name: z.literal('bunderstack'), version: nonEmpty }).strict(),
+    generator: z
+      .object({ name: z.literal('bunderstack'), version: nonEmpty })
+      .strict(),
     application: z
       .object({
         framework: z.literal('tanstack-start'),
         scripts: z
-          .object({ build: z.literal('build'), start: z.literal('start'), worker: z.literal('worker').optional() })
+          .object({
+            build: z.literal('build'),
+            start: z.literal('start'),
+            worker: z.literal('worker').optional(),
+          })
           .strict(),
       })
       .strict(),
@@ -68,29 +75,65 @@ const blueprintSchema = z
             migrationsDirectory: relativePath,
             migrationMode: z.enum(['migrations', 'push']),
             tables: z.array(
-              z.object({ exportName: nonEmpty, physicalName: nonEmpty, system: z.boolean() }).strict(),
+              z
+                .object({
+                  exportName: nonEmpty,
+                  physicalName: nonEmpty,
+                  system: z.boolean(),
+                })
+                .strict(),
             ),
           })
           .strict(),
         storage: z
           .object({
             defaultBucket: nonEmpty,
-            buckets: z.array(z.object({ name: nonEmpty, visibility: z.enum(['public', 'private']) }).strict()),
+            buckets: z.array(
+              z
+                .object({
+                  name: nonEmpty,
+                  visibility: z.enum(['public', 'private']),
+                })
+                .strict(),
+            ),
           })
           .strict(),
-        realtime: z.object({ required: z.literal(true) }).strict().optional(),
+        realtime: z
+          .object({ required: z.literal(true) })
+          .strict()
+          .optional(),
       })
       .strict(),
     environment: z.array(
-      z.object({ key: nonEmpty, required: z.boolean(), scope: z.enum(['server', 'client']) }).strict(),
+      z
+        .object({
+          key: nonEmpty,
+          required: z.boolean(),
+          scope: z.enum(['server', 'client']),
+        })
+        .strict(),
     ),
     background: z
       .object({
         worker: z.object({ required: z.boolean() }).strict(),
         jobs: z.array(z.object({ name: nonEmpty }).strict()),
-        cron: z.array(z.object({ name: nonEmpty, schedule: cronSchedule, timezone: z.literal('UTC') }).strict()),
+        cron: z.array(
+          z
+            .object({
+              name: nonEmpty,
+              schedule: cronSchedule,
+              timezone: z.literal('UTC'),
+            })
+            .strict(),
+        ),
         maintenance: z.array(
-          z.object({ name: z.literal('storage-sweep'), schedule: cronSchedule, timezone: z.literal('UTC') }).strict(),
+          z
+            .object({
+              name: z.literal('storage-sweep'),
+              schedule: cronSchedule,
+              timezone: z.literal('UTC'),
+            })
+            .strict(),
         ),
       })
       .strict(),
@@ -104,29 +147,61 @@ function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
 function rejectDuplicates(collection: string, values: readonly string[]): void {
   const seen = new Set<string>()
   for (const value of values) {
-    if (seen.has(value)) throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
+    if (seen.has(value))
+      throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
     seen.add(value)
   }
 }
 
 export function parseBlueprint(value: unknown): BunderstackBlueprint {
   const blueprint = blueprintSchema.parse(value) as BunderstackBlueprint
-  rejectDuplicates('database physical table', blueprint.resources.database.tables.map((entry) => entry.physicalName))
-  rejectDuplicates('database export table', blueprint.resources.database.tables.map((entry) => entry.exportName))
-  rejectDuplicates('storage bucket', blueprint.resources.storage.buckets.map((entry) => entry.name))
-  rejectDuplicates('environment key', blueprint.environment.map((entry) => entry.key))
-  rejectDuplicates('background job', blueprint.background.jobs.map((entry) => entry.name))
-  rejectDuplicates('background cron', blueprint.background.cron.map((entry) => entry.name))
-  rejectDuplicates('background maintenance', blueprint.background.maintenance.map((entry) => entry.name))
-  if (!blueprint.resources.storage.buckets.some((bucket) => bucket.name === blueprint.resources.storage.defaultBucket)) {
-    throw new Error('[bunderstack] storage defaultBucket must be declared in storage buckets')
+  rejectDuplicates(
+    'database physical table',
+    blueprint.resources.database.tables.map((entry) => entry.physicalName),
+  )
+  rejectDuplicates(
+    'database export table',
+    blueprint.resources.database.tables.map((entry) => entry.exportName),
+  )
+  rejectDuplicates(
+    'storage bucket',
+    blueprint.resources.storage.buckets.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'environment key',
+    blueprint.environment.map((entry) => entry.key),
+  )
+  rejectDuplicates(
+    'background job',
+    blueprint.background.jobs.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background cron',
+    blueprint.background.cron.map((entry) => entry.name),
+  )
+  rejectDuplicates(
+    'background maintenance',
+    blueprint.background.maintenance.map((entry) => entry.name),
+  )
+  if (
+    !blueprint.resources.storage.buckets.some(
+      (bucket) => bucket.name === blueprint.resources.storage.defaultBucket,
+    )
+  ) {
+    throw new Error(
+      '[bunderstack] storage defaultBucket must be declared in storage buckets',
+    )
   }
   const workerRequired = blueprint.background.jobs.length > 0
   if (blueprint.background.worker.required !== workerRequired) {
-    throw new Error('[bunderstack] background worker.required must match declared queue jobs')
+    throw new Error(
+      '[bunderstack] background worker.required must match declared queue jobs',
+    )
   }
   if (Boolean(blueprint.application.scripts.worker) !== workerRequired) {
-    throw new Error('[bunderstack] application worker script must match declared queue jobs')
+    throw new Error(
+      '[bunderstack] application worker script must match declared queue jobs',
+    )
   }
   return blueprint
 }
@@ -143,27 +218,39 @@ export function blueprintFromManifest(args: {
     generator: { name: 'bunderstack', version: args.generatorVersion },
     application: {
       framework: 'tanstack-start',
-      scripts: { build: 'build', start: 'start', ...(workerRequired ? { worker: 'worker' } : {}) },
+      scripts: {
+        build: 'build',
+        start: 'start',
+        ...(workerRequired ? { worker: 'worker' } : {}),
+      },
     },
     bunderstack: { entry: args.entry, manifestVersion: 3 },
     resources: {
       database: {
         ...args.manifest.database,
         migrationMode: args.migrationMode,
-        tables: sortBy(args.manifest.database.tables, (entry) => entry.physicalName),
+        tables: sortBy(
+          args.manifest.database.tables,
+          (entry) => entry.physicalName,
+        ),
       },
       storage: {
         ...args.manifest.storage,
         buckets: sortBy(args.manifest.storage.buckets, (entry) => entry.name),
       },
-      ...(args.manifest.realtime.required ? { realtime: { required: true } } : {}),
+      ...(args.manifest.realtime.required
+        ? { realtime: { required: true } }
+        : {}),
     },
     environment: sortBy(args.manifest.environment, (entry) => entry.key),
     background: {
       worker: { required: workerRequired },
       jobs: sortBy(args.manifest.background.jobs, (entry) => entry.name),
       cron: sortBy(args.manifest.background.cron, (entry) => entry.name),
-      maintenance: sortBy(args.manifest.background.maintenance, (entry) => entry.name),
+      maintenance: sortBy(
+        args.manifest.background.maintenance,
+        (entry) => entry.name,
+      ),
     },
   })
 }
@@ -180,9 +267,15 @@ export function serializeBlueprint(value: BunderstackBlueprint): string {
     defaultStringType: 'PLAIN',
     lineWidth: 0,
   } as const
-  const source = stringify(parseBlueprintYaml(stringify(blueprint, options)), options)
-  return source.replace(/^(\s*schedule: )(.+)$/gm, (_match, prefix: string, value: string) => {
-    const schedule = value.startsWith('"') ? JSON.parse(value) : value
-    return `${prefix}${JSON.stringify(schedule)}`
-  })
+  const source = stringify(
+    parseBlueprintYaml(stringify(blueprint, options)),
+    options,
+  )
+  return source.replace(
+    /^(\s*schedule: )(.+)$/gm,
+    (_match, prefix: string, value: string) => {
+      const schedule = value.startsWith('"') ? JSON.parse(value) : value
+      return `${prefix}${JSON.stringify(schedule)}`
+    },
+  )
 }

package/src/cli.ts

@@ -25,11 +25,19 @@ export async function runCli(
     return 0
   }
   if (args[0] === '--version') {
-    io.stdout((await Bun.file(new URL('../package.json', import.meta.url)).json() as { version: string }).version)
+    io.stdout(
+      (
+        (await Bun.file(
+          new URL('../package.json', import.meta.url),
+        ).json()) as { version: string }
+      ).version,
+    )
     return 0
   }
   if (args[0] !== 'blueprint') {
-    io.stderr('Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]')
+    io.stderr(
+      'Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]',
+    )
     return 2
   }
   const options: GenerateBlueprintOptions = { directory: process.cwd() }

package/src/config.ts

@@ -20,29 +20,10 @@ export type BetterAuthConfig = Omit<
   'database'
 >
 
-export const BunderstackOptionsSchema = z.object({
-  schema: z.record(z.string(), z.unknown()),
-  access: z.record(z.string(), z.unknown()).optional(),
-  database: z
-    .object({
-      adapter: z.unknown(),
-      url: z.string().optional(),
-      authToken: z.string().optional(),
-      migrations: z.string().optional(),
-    })
-    .optional(),
-  auth: z.record(z.string(), z.unknown()).optional(),
-  // Loose: bucket access/scope hold functions that can't survive strict zod
-  // (mirrors how `access` is loose). Resolution happens in resolveBuckets.
-  storage: z.unknown().optional(),
-  // Loose: holds zod schemas. Validation happens in validateEnv.
-  env: z.unknown().optional(),
-  // Loose: provider may be a function/adapter. Resolution happens in createEmail.
-  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(),
+// Only the union-shaped options need runtime validation: they are the ones a
+// JavaScript caller can plausibly get wrong in a way that fails confusingly
+// downstream. Everything else is either typed-only or read raw from `options`.
+const RuntimeOptionsSchema = z.object({
   rateLimit: z
     .union([
       z.boolean(),
@@ -81,19 +62,7 @@ export type BunderstackConfig<
     | StorageConfigInput
     | undefined,
   TEnv extends EnvConfigInput | undefined = EnvConfigInput | undefined,
-> = Omit<
-  z.input<typeof BunderstackOptionsSchema>,
-  | 'schema'
-  | 'access'
-  | 'auth'
-  | 'authResolver'
-  | 'storage'
-  | 'env'
-  | 'email'
-  | 'trpc'
-  | 'jobs'
-  | 'database'
-> & {
+> = {
   schema: TSchema
   access?: TAccess
   database: {
@@ -110,11 +79,20 @@ export type BunderstackConfig<
   authResolver?: AuthSessionResolver
   storage?: TStorage
   env?: TEnv
+  /**
+   * Stand-in for `process.env`. Feeds both env validation and platform
+   * overrides, so tests and embedders have one injection point instead of
+   * three.
+   */
+  processEnv?: Record<string, string | undefined>
+  background?: { autoStart?: boolean }
   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. `jobs` follows the
-  // same pattern (defs map | builder callback receiving `j`).
+  /**
+   * Custom Hono routes, mounted at root ahead of bunderstack's own. Declared as
+   * a callback because routes in a separate file cannot import the app that is
+   * still being constructed — the same reason `trpc` takes a builder.
+   */
+  routes?: (ctx: never) => unknown
   rateLimit?: boolean | RateLimitConfig
   idempotency?: boolean | IdempotencyConfig
   realtime?:
@@ -154,7 +132,7 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
     string | undefined
   >,
 ): ResolvedConfig {
-  const parsed = BunderstackOptionsSchema.parse(options)
+  const parsed = RuntimeOptionsSchema.parse(options)
   // Self-validate when the caller didn't pass a pre-validated env, so
   // resolveConfig stays usable standalone.
   const resolvedEnv =
@@ -173,14 +151,14 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
       adapter,
       url:
         platformSource['BUNDERSTACK_DATABASE_URL'] ??
-        parsed.database?.url ??
+        options.database?.url ??
         resolvedEnv.DATABASE_URL ??
         defaultUrl,
       authToken:
         platformSource['BUNDERSTACK_DATABASE_AUTH_TOKEN'] ??
-        parsed.database?.authToken ??
+        options.database?.authToken ??
         resolvedEnv.DATABASE_AUTH_TOKEN,
-      migrations: parsed.database?.migrations ?? './migrations',
+      migrations: options.database?.migrations ?? './migrations',
     },
     auth: (() => {
       const authInput = options.auth ?? {}

package/src/cron.ts

@@ -1,2 +1,3 @@
 export { cronMatches, parseCron } from './jobs/cron'
-export { signScheduleRequest, verifyScheduleRequest } from './jobs/cron-auth'
+export { floorSlot, slotsDue, CRON_PREFIX, SLOT_MS } from './jobs/slots'
+export type { CatchUp } from './jobs/slots'