bunderstack 0.15.2 → 0.17.0-beta.0

package/src/blueprint.ts

@@ -1,9 +1,10 @@
+import * as v from 'valibot'
 import { parse, stringify } from 'yaml'
-import { z } from 'zod'
 
 import type { BunderstackManifest } from './manifest'
 
 import { parseCron } from './jobs/cron'
+import { validateStandardSchema } from './standard-schema'
 
 export type MigrationMode = 'migrations' | 'push'
 
@@ -26,119 +27,97 @@ export type BunderstackBlueprint = {
   }
 }
 
-const nonEmpty = z.string().min(1)
-const relativePath = nonEmpty.refine(
-  (value) =>
-    !value.startsWith('/') &&
-    !value.includes('\\') &&
-    value.split('/').every((part) => part !== '' && part !== '..'),
-  { message: 'entry must be a relative path without traversal' },
+const nonEmpty = v.pipe(v.string(), v.minLength(1))
+const relativePath = v.pipe(
+  nonEmpty,
+  v.check(
+    (value) =>
+      !value.startsWith('/') &&
+      !value.includes('\\') &&
+      value.split('/').every((part) => part !== '' && part !== '..'),
+    'entry must be a relative path without traversal',
+  ),
 )
-const cronSchedule = nonEmpty.refine(
-  (value) => {
+const cronSchedule = v.pipe(
+  nonEmpty,
+  v.check((value) => {
     try {
       parseCron(value)
       return true
     } catch {
       return false
     }
-  },
-  { message: 'invalid cron schedule' },
+  }, 'invalid cron schedule'),
 )
 
-const blueprintSchema = z
-  .object({
-    version: z.literal(1),
-    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(),
-          })
-          .strict(),
-      })
-      .strict(),
-    bunderstack: z
-      .object({ entry: relativePath, manifestVersion: z.literal(3) })
-      .strict(),
-    resources: z
-      .object({
-        database: z
-          .object({
-            dialect: z.enum(['sqlite', 'pg']),
-            migrationsDirectory: relativePath,
-            migrationMode: z.enum(['migrations', 'push']),
-            tables: z.array(
-              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(),
-            ),
-          })
-          .strict(),
-        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(),
+const blueprintSchema = v.strictObject({
+  version: v.literal(1),
+  generator: v.strictObject({
+    name: v.literal('bunderstack'),
+    version: nonEmpty,
+  }),
+  application: v.strictObject({
+    framework: v.literal('tanstack-start'),
+    scripts: v.strictObject({
+      build: v.literal('build'),
+      start: v.literal('start'),
+      worker: v.optional(v.literal('worker')),
+    }),
+  }),
+  bunderstack: v.strictObject({
+    entry: relativePath,
+    manifestVersion: v.literal(3),
+  }),
+  resources: v.strictObject({
+    database: v.strictObject({
+      dialect: v.picklist(['sqlite', 'pg']),
+      migrationsDirectory: relativePath,
+      migrationMode: v.picklist(['migrations', 'push']),
+      tables: v.array(
+        v.strictObject({
+          exportName: nonEmpty,
+          physicalName: nonEmpty,
+          system: v.boolean(),
+        }),
+      ),
+    }),
+    storage: v.strictObject({
+      defaultBucket: nonEmpty,
+      buckets: v.array(
+        v.strictObject({
+          name: nonEmpty,
+          visibility: v.picklist(['public', 'private']),
+        }),
+      ),
+    }),
+    realtime: v.optional(v.strictObject({ required: v.literal(true) })),
+  }),
+  environment: v.array(
+    v.strictObject({
+      key: nonEmpty,
+      required: v.boolean(),
+      scope: v.picklist(['server', 'client']),
+    }),
+  ),
+  background: v.strictObject({
+    worker: v.strictObject({ required: v.boolean() }),
+    jobs: v.array(v.strictObject({ name: nonEmpty })),
+    cron: v.array(
+      v.strictObject({
+        name: nonEmpty,
+        schedule: cronSchedule,
+        timezone: v.literal('UTC'),
+      }),
     ),
-    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(),
-        ),
-        maintenance: z.array(
-          z
-            .object({
-              name: z.literal('storage-sweep'),
-              schedule: cronSchedule,
-              timezone: z.literal('UTC'),
-            })
-            .strict(),
-        ),
-      })
-      .strict(),
-  })
-  .strict()
+    maintenance: v.array(
+      v.strictObject({
+        name: v.literal('storage-sweep'),
+        schedule: cronSchedule,
+        timezone: v.literal('UTC'),
+      }),
+    ),
+  }),
+})
 
 function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
   return [...entries].sort((left, right) => key(left).localeCompare(key(right)))
@@ -154,7 +133,11 @@ function rejectDuplicates(collection: string, values: readonly string[]): void {
 }
 
 export function parseBlueprint(value: unknown): BunderstackBlueprint {
-  const blueprint = blueprintSchema.parse(value) as BunderstackBlueprint
+  const blueprint = validateStandardSchema(
+    blueprintSchema,
+    value,
+    'blueprint',
+  ) as BunderstackBlueprint
   rejectDuplicates(
     'database physical table',
     blueprint.resources.database.tables.map((entry) => entry.physicalName),

package/src/config.ts

@@ -1,14 +1,16 @@
 // src/config.ts
 import { betterAuth } from 'better-auth'
-import { z } from 'zod'
+import * as v from 'valibot'
 
+import type { AnyRouter } from '@orpc/server'
 import type { AuthSessionResolver, TableAccessInput } from './access'
+import type { BunderstackApiBuilder } from './api/builder'
 import type { DatabaseAdapter } from './database/adapter'
 import type { EmailConfigInput } from './email'
 import type { IdempotencyConfig } from './idempotency'
 import type { RateLimitConfig } from './rate-limit'
 
-import { validateEnv, type BaseEnv, type EnvConfigInput } from './env'
+import { validateEnv, type BaseEnv, type EnvConfigInput, type ValidatedEnv } from './env'
 import {
   resolveBuckets,
   type ResolvedStorageBuckets,
@@ -20,56 +22,38 @@ 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(),
-  rateLimit: z
-    .union([
-      z.boolean(),
-      z.object({
-        windowMs: z.number().optional(),
-        max: z.number().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 = v.object({
+  rateLimit: v.optional(
+    v.union([
+      v.boolean(),
+      v.object({
+        windowMs: v.optional(v.number()),
+        max: v.optional(v.number()),
       }),
-    ])
-    .optional(),
-  idempotency: z
-    .union([z.boolean(), z.object({ ttlMs: z.number().optional() })])
-    .optional(),
-  realtime: z
-    .union([
-      z.boolean(),
-      z.object({
-        keepaliveMs: z.number().optional(),
-        bufferSize: z.number().optional(),
-        redis: z
-          .union([
-            z.string(),
-            z.object({ url: z.string(), token: z.string().optional() }),
-          ])
-          .optional(),
+    ]),
+  ),
+  idempotency: v.optional(
+    v.union([v.boolean(), v.object({ ttlMs: v.optional(v.number()) })]),
+  ),
+  realtime: v.optional(
+    v.union([
+      v.boolean(),
+      v.object({
+        bufferSize: v.optional(v.number()),
+        resumeSeconds: v.optional(v.number()),
+        redis: v.optional(
+          v.union([
+            v.string(),
+            v.object({ url: v.string(), token: v.optional(v.string()) }),
+          ]),
+        ),
       }),
-    ])
-    .optional(),
+    ]),
+  ),
+  openapi: v.optional(v.boolean()),
 })
 
 export type BunderstackConfig<
@@ -81,19 +65,8 @@ 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'
-> & {
+  TCustomApiRouter extends AnyRouter | undefined = AnyRouter | undefined,
+> = {
   schema: TSchema
   access?: TAccess
   database: {
@@ -104,24 +77,35 @@ export type BunderstackConfig<
   }
   auth?: BetterAuthConfig
   /**
-   * Reuse an application-owned session reader for CRUD, realtime, storage,
-   * and tRPC while keeping Bunderstack's auth handler available.
+   * Reuse an application-owned session reader for the unified API while
+   * keeping Bunderstack's auth handler available.
    */
   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`).
+  /**
+   * Unified oRPC API builder callback.
+   */
+  api?: (
+    builder: BunderstackApiBuilder<TSchema, ValidatedEnv<TEnv>>,
+  ) => TCustomApiRouter
   rateLimit?: boolean | RateLimitConfig
   idempotency?: boolean | IdempotencyConfig
+  /** Generate and serve `/api/openapi.json`. Disabled by default. */
+  openapi?: boolean
   realtime?:
     | boolean
     | {
-        keepaliveMs?: number
         bufferSize?: number
+        resumeSeconds?: number
         redis?: string | { url: string; token?: string }
       }
 }
@@ -138,14 +122,26 @@ export type ResolvedConfig = {
   realtime?:
     | boolean
     | {
-        keepaliveMs?: number
         bufferSize?: number
+        resumeSeconds?: number
         redis?: string | { url: string; token?: string }
       }
 }
 
-export function resolveConfig<TSchema extends Record<string, unknown>>(
-  options: BunderstackConfig<TSchema>,
+export function resolveConfig<
+  TSchema extends Record<string, unknown>,
+  TAccess extends Record<string, TableAccessInput> | undefined = undefined,
+  TStorage extends StorageConfigInput | undefined = undefined,
+  TEnv extends EnvConfigInput | undefined = undefined,
+  TCustomApiRouter extends AnyRouter | undefined = undefined,
+>(
+  options: BunderstackConfig<
+    TSchema,
+    TAccess,
+    TStorage,
+    TEnv,
+    TCustomApiRouter
+  >,
   env?: BaseEnv,
   // Platform-injected overrides (Bunderhost & co.) beat code-level config so
   // apps with hardcoded local urls deploy unchanged.
@@ -154,7 +150,7 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
     string | undefined
   >,
 ): ResolvedConfig {
-  const parsed = BunderstackOptionsSchema.parse(options)
+  const parsed = v.parse(RuntimeOptionsSchema, options)
   // Self-validate when the caller didn't pass a pre-validated env, so
   // resolveConfig stays usable standalone.
   const resolvedEnv =
@@ -173,14 +169,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'