bunderstack 0.16.0 → 0.17.0-beta.2

package/src/jobs/define.ts

@@ -1,14 +1,13 @@
 // 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
@@ -33,7 +32,7 @@ export type TickResult = {
 }
 
 /**
- * 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 = {
@@ -71,8 +70,8 @@ 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, … */
@@ -232,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> {
@@ -260,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/queue.ts

@@ -5,8 +5,8 @@ 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(
@@ -23,7 +23,11 @@ export async function enqueueJob(
   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 ? def.input.parse(input) : null
+  const parsed = isCron
+    ? null
+    : def.input
+      ? validateStandardSchema(def.input, input, `job "${name}" input`)
+      : null
   const t = jobsTableFor(db)
   const now = Date.now()
   const runAt =

package/src/jobs/worker.ts

@@ -12,6 +12,7 @@ import type {
 } from './define'
 
 import { jobsTableFor } from '../internal-tables'
+import { validateStandardSchema } from '../standard-schema'
 import { parseCron } from './cron'
 import { backoffMs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './define'
 import { enqueueJob } from './queue'
@@ -73,7 +74,9 @@ export function createJobRunner(deps: {
       return { scheduledFor: new Date(Number(row.runAt)) }
     }
     const raw = JSON.parse(row.payloadJson)
-    return def.input ? def.input.parse(raw) : undefined
+    return def.input
+      ? validateStandardSchema(def.input, raw, 'job payload')
+      : undefined
   }
 
   /**

package/src/list-query.ts

@@ -21,18 +21,28 @@ import type { AnyDb } from './dialect'
 
 import { ErrorCode, ListQueryError } from './errors'
 
-/** Caps both `?limit=` and the number of values in a comma-separated `IN` filter. */
+/** Caps both `?limit=` and the number of values in an `IN` filter. */
 export const MAX_LIST_LIMIT = 200
 
-export const RESERVED_LIST_PARAMS = new Set([
-  'limit',
-  'offset',
-  'sort',
-  'order',
-  'q',
-  'cursor',
-  'count',
-])
+/** Default page size when a request omits `limit`. */
+export const DEFAULT_LIST_LIMIT = 20
+
+/**
+ * What a list procedure accepts. Shape and column types are enforced by the
+ * generated input schema, so by the time these params arrive they are already
+ * validated and coerced — this module only applies policy (defaults, the limit
+ * cap, cursor rules).
+ */
+export type ListParamsInput = {
+  limit?: number
+  offset?: number
+  cursor?: string
+  sort?: string
+  order?: SortOrder
+  q?: string
+  count?: boolean
+  filters?: Record<string, unknown>
+}
 
 export type ParsedListParams = {
   limit: number
@@ -81,76 +91,22 @@ function isCursorPayload(value: unknown): value is CursorPayload {
   )
 }
 
-function parseBoolean(value: string | undefined): boolean {
-  if (!value) return false
-  const v = value.toLowerCase()
-  return v === 'true' || v === '1'
-}
-
-function parseLimit(raw: string | undefined): number {
-  if (raw === undefined || raw === '') return 20
-  const n = Number(raw)
-  if (!Number.isInteger(n) || n < 1) {
-    throw new ListQueryError(
-      `limit must be an integer between 1 and ${MAX_LIST_LIMIT}`,
-    )
-  }
-  return Math.min(n, MAX_LIST_LIMIT)
-}
-
-function parseOffset(raw: string | undefined): number {
-  if (raw === undefined || raw === '') return 0
-  const n = Number(raw)
-  if (!Number.isInteger(n) || n < 0) {
-    throw new ListQueryError('offset must be a non-negative integer')
-  }
-  return n
-}
-
-function parseOrder(raw: string | undefined): SortOrder {
-  if (!raw || raw === 'asc') return 'asc'
-  if (raw === 'desc') return 'desc'
-  throw new ListQueryError('order must be "asc" or "desc"')
-}
-
-export function parseListParams(
-  url: URL,
+/**
+ * Applies list policy to already-validated input: defaults, the limit cap, and
+ * the rules a schema cannot express (cursor excludes offset, and a cursor must
+ * agree with the sort it was minted for).
+ */
+export function resolveListParams(
+  input: ListParamsInput,
   access: ResolvedTableAccess,
 ): ParsedListParams {
-  const params = url.searchParams
-  const limit = parseLimit(params.get('limit') ?? undefined)
-  const cursor = params.get('cursor')?.trim() || undefined
-  const hasOffset = params.has('offset') && params.get('offset') !== ''
-  const offset = hasOffset
-    ? parseOffset(params.get('offset') ?? undefined)
-    : undefined
-
-  if (cursor && hasOffset) {
+  const cursor = input.cursor?.trim() || undefined
+  if (cursor && input.offset !== undefined) {
     throw new ListQueryError('cursor and offset cannot be used together')
   }
 
-  const sort = params.get('sort')?.trim() || access.defaultSort.column
-  const order = params.has('order')
-    ? parseOrder(params.get('order') ?? undefined)
-    : params.has('sort')
-      ? 'asc'
-      : access.defaultSort.order
-
-  if (!access.sortableColumns.includes(sort)) {
-    throw new ListQueryError(`sort column "${sort}" is not allowed`)
-  }
-
-  const filters: Record<string, unknown> = {}
-  for (const [key, value] of params.entries()) {
-    if (RESERVED_LIST_PARAMS.has(key)) continue
-    if (!access.filterableColumns.includes(key)) {
-      throw new ListQueryError(`filter column "${key}" is not allowed`)
-    }
-    filters[key] = value === 'null' ? null : value
-  }
-
-  const q = params.get('q')?.trim().slice(0, 100) ?? ''
-  const count = parseBoolean(params.get('count') ?? undefined)
+  const sort = input.sort ?? access.defaultSort.column
+  const order = input.order ?? (input.sort ? 'asc' : access.defaultSort.order)
 
   if (cursor) {
     const decoded = decodeCursor(cursor)
@@ -163,14 +119,14 @@ export function parseListParams(
   }
 
   return {
-    limit,
-    offset: cursor ? undefined : (offset ?? 0),
+    limit: Math.min(input.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT),
+    offset: cursor ? undefined : (input.offset ?? 0),
     sort,
     order,
-    q,
+    q: input.q?.trim() ?? '',
     cursor,
-    count,
-    filters,
+    count: input.count ?? false,
+    filters: input.filters ?? {},
   }
 }
 
@@ -191,41 +147,20 @@ function buildSearchWhere(
   return conditions.length ? or(...conditions) : undefined
 }
 
-function coerceFilterValue(
+/**
+ * Cursors carry their sort value as JSON, so a date column arrives as a string
+ * and has to be rebuilt. Filter values need no such repair — the generated
+ * input schema already types them.
+ */
+function coerceCursorValue(
   table: Parameters<typeof getTableColumns>[0],
   columnName: string,
-  raw: unknown,
+  raw: string | number | null,
 ): unknown {
   if (raw === null) return null
   const col = getTableColumns(table)[columnName]
-  if (!col) return raw
-
-  const dataType = col.dataType
-  if (
-    dataType === 'number' ||
-    dataType === 'integer' ||
-    dataType === 'bigint'
-  ) {
-    const n = Number(raw)
-    if (Number.isNaN(n)) {
-      throw new ListQueryError(`filter "${columnName}" must be a number`)
-    }
-    return n
-  }
-  if (dataType === 'boolean') {
-    const s = String(raw).toLowerCase()
-    if (s === 'true' || s === '1') return true
-    if (s === 'false' || s === '0') return false
-    throw new ListQueryError(`filter "${columnName}" must be a boolean`)
-  }
-  if (dataType === 'date') {
-    const d = new Date(raw as string | number)
-    if (Number.isNaN(d.getTime())) {
-      throw new ListQueryError(`filter "${columnName}" must be a valid date`)
-    }
-    return d
-  }
-  return String(raw)
+  if (col?.dataType === 'date') return new Date(raw)
+  return raw
 }
 
 function buildFilterWhere(
@@ -235,32 +170,14 @@ function buildFilterWhere(
   const columns = getTableColumns(table)
   const conditions: SQL[] = []
 
-  for (const [name, raw] of Object.entries(filters)) {
+  for (const [name, value] of Object.entries(filters)) {
     const col = columns[name]
-    if (!col) continue
-
-    if (raw === null) {
-      conditions.push(sql`${col} IS NULL`)
-      continue
-    }
-
-    // `?column=a,b,c` — TypeIDs and other filterable values never contain
-    // commas, so this is a safe, zero-syntax way to do `column IN (...)`.
-    if (typeof raw === 'string' && raw.includes(',')) {
-      const parts = raw.split(',').filter((p) => p.length > 0)
-      if (parts.length > MAX_LIST_LIMIT) {
-        throw new ListQueryError(
-          `filter "${name}" accepts at most ${MAX_LIST_LIMIT} comma-separated values`,
-        )
-      }
-      const values = parts.map((p) => coerceFilterValue(table, name, p))
-      conditions.push(inArray(col, values))
-      continue
-    }
+    if (!col || value === undefined) continue
 
-    const value = coerceFilterValue(table, name, raw)
     if (value === null) {
       conditions.push(sql`${col} IS NULL`)
+    } else if (Array.isArray(value)) {
+      if (value.length) conditions.push(inArray(col, value))
     } else {
       conditions.push(eq(col, value))
     }
@@ -301,7 +218,7 @@ function buildCursorWhere(
 ): SQL {
   const columns = getTableColumns(table)
   const sortCol = columns[sortColName]!
-  const sortValue = coerceFilterValue(table, sortColName, cursor.v)
+  const sortValue = coerceCursorValue(table, sortColName, cursor.v)
 
   if (order === 'desc') {
     return or(

package/src/manifest.ts

@@ -1,5 +1,7 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
 import { getTableName, isTable } from 'drizzle-orm'
-import { z, type ZodType } from 'zod'
+import * as v from 'valibot'
 
 import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
@@ -12,6 +14,10 @@ import {
   bunderstackJobs,
 } from './internal-tables'
 import { parseCron } from './jobs/cron'
+import {
+  StandardSchemaValidationError,
+  validateStandardSchema,
+} from './standard-schema'
 
 export type ManifestEnvVar = {
   key: string
@@ -43,95 +49,77 @@ export type BunderstackManifest = {
   }
 }
 
-const nonEmpty = z.string().min(1)
-const migrationDirectory = nonEmpty.refine(
-  (value) =>
-    value.startsWith('/') ||
-    (!value.includes('\\') &&
-      value.split('/').every((part) => part !== '..' && part !== '')),
-  {
-    message:
-      'migrationsDirectory must be an absolute path or a relative path without traversal',
-  },
+const nonEmpty = v.pipe(v.string(), v.minLength(1))
+const migrationDirectory = v.pipe(
+  nonEmpty,
+  v.check(
+    (value) =>
+      value.startsWith('/') ||
+      (!value.includes('\\') &&
+        value.split('/').every((part) => part !== '..' && part !== '')),
+    'migrationsDirectory must be an absolute path or 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 manifestSchema = z
-  .object({
-    version: z.literal(3),
-    database: z
-      .object({
-        dialect: z.enum(['sqlite', 'pg']),
-        migrationsDirectory: migrationDirectory,
-        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.boolean() }).strict(),
-    environment: z.array(
-      z
-        .object({
-          key: nonEmpty,
-          required: z.boolean(),
-          scope: z.enum(['server', 'client']),
-        })
-        .strict(),
+const manifestSchema = v.strictObject({
+  version: v.literal(3),
+  database: v.strictObject({
+    dialect: v.picklist(['sqlite', 'pg']),
+    migrationsDirectory: migrationDirectory,
+    tables: v.array(
+      v.strictObject({
+        exportName: nonEmpty,
+        physicalName: nonEmpty,
+        system: v.boolean(),
+      }),
     ),
-    background: z
-      .object({
-        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()
+  }),
+  storage: v.strictObject({
+    defaultBucket: nonEmpty,
+    buckets: v.array(
+      v.strictObject({
+        name: nonEmpty,
+        visibility: v.picklist(['public', 'private']),
+      }),
+    ),
+  }),
+  realtime: v.strictObject({ required: v.boolean() }),
+  environment: v.array(
+    v.strictObject({
+      key: nonEmpty,
+      required: v.boolean(),
+      scope: v.picklist(['server', 'client']),
+    }),
+  ),
+  background: v.strictObject({
+    jobs: v.array(v.strictObject({ name: nonEmpty })),
+    cron: v.array(
+      v.strictObject({
+        name: nonEmpty,
+        schedule: cronSchedule,
+        timezone: v.literal('UTC'),
+      }),
+    ),
+    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)))
@@ -161,14 +149,19 @@ function describeTables(schema: Record<string, unknown>) {
 }
 
 function describeSection(
-  section: Record<string, ZodType> | undefined,
+  section: Record<string, StandardSchemaV1> | undefined,
   scope: ManifestEnvVar['scope'],
 ): ManifestEnvVar[] {
-  return Object.entries(section ?? {}).map(([key, schema]) => ({
-    key,
-    required: !schema.safeParse(undefined).success,
-    scope,
-  }))
+  return Object.entries(section ?? {}).map(([key, schema]) => {
+    let required = false
+    try {
+      validateStandardSchema(schema, undefined, 'env')
+    } catch (error) {
+      if (!(error instanceof StandardSchemaValidationError)) throw error
+      required = true
+    }
+    return { key, required, scope }
+  })
 }
 
 function systemTables() {
@@ -192,7 +185,11 @@ function systemTables() {
 }
 
 export function parseManifest(value: unknown): BunderstackManifest {
-  const manifest = manifestSchema.parse(value) as BunderstackManifest
+  const manifest = validateStandardSchema(
+    manifestSchema,
+    value,
+    'manifest',
+  ) as BunderstackManifest
   rejectDuplicates(
     'database physical table',
     manifest.database.tables.map((entry) => entry.physicalName),

package/src/rate-limit.ts

@@ -54,7 +54,7 @@ export function createRateLimiter(
       return new Response(
         JSON.stringify({
           error: 'Too many requests',
-          code: 'RATE_LIMITED',
+          code: 'TOO_MANY_REQUESTS',
         }),
         {
           status: 429,

package/src/realtime/facade.ts

@@ -1,6 +1,14 @@
-import { getTableName, type InferSelectModel, type Table } from 'drizzle-orm'
+import {
+  getTableName,
+  isTable,
+  type InferSelectModel,
+  type Table,
+} from 'drizzle-orm'
 
-import type { RealtimeAction, RealtimeBroker } from './index'
+import type {
+  RealtimeAction,
+  RealtimePublisher,
+} from './publisher'
 
 export type RealtimeTransport = 'disabled' | 'memory' | 'redis'
 
@@ -22,31 +30,45 @@ export interface RealtimeFacade<
   ): Promise<void>
 }
 
+/**
+ * One name for a table everywhere: events, subscriptions, and the CRUD router
+ * all use the schema key. Pass the schema so a key like `creditBalances` is not
+ * published as its SQL name `credit_balances` — clients subscribe with the key
+ * they call procedures with. Without a schema, the SQL name is the only name
+ * available and is used as-is.
+ */
 export function createRealtimeFacade<TSchema extends Record<string, unknown>>(
-  broker?: RealtimeBroker,
-  transport: RealtimeTransport = broker ? 'memory' : 'disabled',
+  publisher?: RealtimePublisher,
+  transport: RealtimeTransport = publisher ? 'memory' : 'disabled',
+  schema?: TSchema,
 ): RealtimeFacade<TSchema> {
-  if (!broker && transport !== 'disabled') {
+  if (!publisher && transport !== 'disabled') {
     throw new Error(
-      '[bunderstack] an enabled realtime transport requires a broker',
+      '[bunderstack] an enabled realtime transport requires a publisher',
     )
   }
-  if (broker && transport === 'disabled') {
+  if (publisher && transport === 'disabled') {
     throw new Error(
-      '[bunderstack] a realtime broker cannot use the disabled transport',
+      '[bunderstack] a realtime publisher cannot use the disabled transport',
     )
   }
 
+  const keyByTableName = new Map<string, string>()
+  for (const [key, value] of Object.entries(schema ?? {})) {
+    if (isTable(value)) keyByTableName.set(getTableName(value), key)
+  }
+
   return {
-    enabled: broker !== undefined,
+    enabled: publisher !== undefined,
     transport,
     async publish(table, action, record) {
-      if (!broker) return
-      await broker.publish(
-        getTableName(table),
+      if (!publisher) return
+      const tableName = getTableName(table)
+      await publisher.publish('change', {
+        table: keyByTableName.get(tableName) ?? tableName,
         action,
-        record as unknown as Record<string, unknown>,
-      )
+        record: record as unknown as Record<string, unknown>,
+      })
     },
   }
 }