bunderstack 0.17.0-beta.0 → 0.17.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.17.0-beta.0",
+  "version": "0.17.0-beta.2",
   "description": "Batteries-included backend framework for Bun: type-safe oRPC APIs, auth, storage, realtime, jobs, email, and validated env from one config.",
   "keywords": [
     "backend",
@@ -26,6 +26,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*.types.ts",
     "README.md",
     "LICENSE"
   ],
@@ -66,8 +67,9 @@
   "devDependencies": {
     "@electric-sql/pglite": ">=0.3.0",
     "@libsql/client": ">=0.14.0",
-    "@orpc/openapi": "2.0.0-beta.26",
     "@orpc/bun": "2.0.0-beta.26",
+    "@orpc/json-schema": "2.0.0-beta.26",
+    "@orpc/openapi": "2.0.0-beta.26",
     "@orpc/publisher": "2.0.0-beta.26",
     "@orpc/server": "2.0.0-beta.26",
     "@orpc/valibot": "2.0.0-beta.26",
@@ -80,8 +82,9 @@
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.3.0",
     "@libsql/client": ">=0.14.0",
-    "@orpc/openapi": "2.0.0-beta.26",
     "@orpc/bun": "2.0.0-beta.26",
+    "@orpc/json-schema": "2.0.0-beta.26",
+    "@orpc/openapi": "2.0.0-beta.26",
     "@orpc/publisher": "2.0.0-beta.26",
     "@orpc/server": "2.0.0-beta.26",
     "@orpc/valibot": "2.0.0-beta.26",

package/src/access.ts

@@ -38,16 +38,6 @@ export type ScopeResolver = (ctx: AccessContext) => ScopeMap
 
 export type CrudOperation = 'list' | 'get' | 'create' | 'update' | 'delete'
 
-const RESERVED_LIST_PARAMS = new Set([
-  'limit',
-  'offset',
-  'sort',
-  'order',
-  'q',
-  'cursor',
-  'count',
-])
-
 export type SortOrder = 'asc' | 'desc'
 
 export type DefaultSort = {
@@ -176,11 +166,6 @@ function resolveListAccess(
 
   const filterableColumns = input.filterableColumns ?? []
   for (const col of filterableColumns) {
-    if (RESERVED_LIST_PARAMS.has(col)) {
-      throw new Error(
-        `[bunderstack] filterableColumns cannot include reserved query param "${col}"`,
-      )
-    }
     if (!columns.includes(col)) {
       throw new Error(
         `[bunderstack] filterableColumns references unknown column "${col}"`,
@@ -189,11 +174,6 @@ function resolveListAccess(
   }
 
   for (const col of sortableColumns) {
-    if (RESERVED_LIST_PARAMS.has(col)) {
-      throw new Error(
-        `[bunderstack] sortableColumns cannot include reserved query param "${col}"`,
-      )
-    }
     if (!columns.includes(col)) {
       throw new Error(
         `[bunderstack] sortableColumns references unknown column "${col}"`,

package/src/api/crud-router.ts

@@ -19,6 +19,7 @@ import {
   type TableAccessInput,
 } from '../access'
 import { createCrudOperations, type CrudOperations } from '../crud-operations'
+import { MAX_LIST_LIMIT } from '../list-query'
 import { createApiBuilder } from './builder'
 
 export type CrudApiRouterOptions<
@@ -37,6 +38,40 @@ function strictObject<TEntries extends v.ObjectEntries>(schema: {
 
 type CrudInsert<TTable extends Table> = Partial<TTable['$inferInsert']>
 
+/** A filter accepts one value (`=`), a list (`IN`), or null (`IS NULL`). */
+export type ListFilterValue<T> = T | readonly T[] | null | 'null'
+
+export type ListFilters<
+  TTable extends Table,
+  TFilterable extends string,
+> = {
+  [K in Extract<keyof TTable['$inferSelect'], TFilterable>]?: ListFilterValue<
+    TTable['$inferSelect'][K]
+  >
+}
+
+/**
+ * The `list` input as callers see it. Filter columns and sortable columns come
+ * from the table's `access` entry, so `filters` autocompletes to real columns
+ * and rejects wrong value types at compile time.
+ */
+export type ListInputFor<
+  TTable extends Table,
+  TFilterable extends string,
+  TSortable extends string,
+> =
+  | {
+      limit?: number
+      offset?: number
+      cursor?: string
+      sort?: TSortable
+      order?: 'asc' | 'desc'
+      q?: string
+      count?: boolean
+      filters?: ListFilters<TTable, TFilterable>
+    }
+  | undefined
+
 export type BuildTableCrudProceduresArgs<
   TSchema extends Record<string, unknown>,
   TTable extends Table,
@@ -50,6 +85,8 @@ export type BuildTableCrudProceduresArgs<
 export function buildTableCrudProcedures<
   TSchema extends Record<string, unknown>,
   TTable extends Table,
+  TFilterable extends string = string,
+  TSortable extends string = string,
 >(args: BuildTableCrudProceduresArgs<TSchema, TTable>) {
   const { table, operations, builder, access } = args
   const name = getTableName(table)
@@ -89,24 +126,52 @@ export function buildTableCrudProcedures<
     body: strictObject(updateBodySchema),
   })
 
-  const listQuerySchema = v.optional(
-    v.strictObject({
-      limit: v.optional(
+  // One filter field per allowed column, typed by the column itself: a scalar
+  // for `=`, a list for `IN`, and `null` for `IS NULL`. Query strings are
+  // coerced to these types by SmartCoercionHandlerPlugin, so REST and RPC share
+  // one contract and nothing has to re-read the raw URL.
+  const selectEntries = createSelectSchema(table).entries as Record<
+    string,
+    v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>
+  >
+  const filterEntries: v.ObjectEntries = {}
+  for (const column of access.filterableColumns) {
+    const base = selectEntries[column]
+    if (!base) continue
+    filterEntries[column] = v.optional(
+      v.union([
+        // `?filters[col]=null` — a query string cannot carry a real null.
         v.pipe(
-          v.union([v.string(), v.number()]),
-          v.transform(Number),
-          v.number(),
+          v.literal('null'),
+          v.transform(() => null),
         ),
-      ),
-      offset: v.optional(v.number()),
+        base,
+        v.pipe(v.array(base), v.maxLength(MAX_LIST_LIMIT)),
+        v.null(),
+      ]),
+    )
+  }
+
+  // Built from runtime column lists, so the schema's own inferred type cannot
+  // name the columns; the cast restates it with the literals the caller's
+  // `access` config carries. Runtime shape and this type are the same object.
+  const listQuerySchema = v.optional(
+    v.strictObject({
+      limit: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+      offset: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
       cursor: v.optional(v.string()),
-      sort: v.optional(v.string()),
+      sort: v.optional(v.picklist(access.sortableColumns)),
       order: v.optional(v.picklist(['asc', 'desc'])),
-      q: v.optional(v.string()),
+      q: v.optional(v.pipe(v.string(), v.maxLength(100))),
       count: v.optional(v.boolean()),
-      filters: v.optional(v.record(v.string(), v.unknown())),
+      // Always present, even with no filterable columns: clients send `{}`.
+      filters: v.optional(v.strictObject(filterEntries)),
     }),
-  )
+  ) as unknown as v.GenericSchema<
+    ListInputFor<TTable, TFilterable, TSortable>,
+    ListInputFor<TTable, TFilterable, TSortable>
+  >
+
 
   const listOutputSchema = v.strictObject({
     items: v.array(selectSchema),
@@ -138,16 +203,7 @@ export function buildTableCrudProcedures<
         user: session.user,
         session: { activeOrganizationId: session.activeOrganizationId },
       }
-      const { filters, count, ...query } = input ?? {}
-      const result = await operations.list(
-        name,
-        {
-          ...query,
-          ...(filters ?? {}),
-          ...(count === undefined ? {} : { count: String(count) }),
-        },
-        execCtx,
-      )
+      const result = await operations.list(name, input ?? {}, execCtx)
       return {
         ...result,
         items: result.items as TTable['$inferSelect'][],
@@ -273,8 +329,17 @@ export function buildTableCrudProcedures<
   }
 }
 
-export type TableCrudProcedures<TTable extends Table> = ReturnType<
-  typeof buildTableCrudProcedures<Record<string, unknown>, TTable>
+export type TableCrudProcedures<
+  TTable extends Table,
+  TFilterable extends string = string,
+  TSortable extends string = string,
+> = ReturnType<
+  typeof buildTableCrudProcedures<
+    Record<string, unknown>,
+    TTable,
+    TFilterable,
+    TSortable
+  >
 >
 
 export function buildCrudApiRouter<

package/src/api/types.ts

@@ -49,13 +49,34 @@ export type ExposedApiTables<TSchema, TAccess> = [TAccess] extends [undefined]
           DisabledKeys<TAccess> | (keyof TAccess & string)
         >
 
+/**
+ * Column allowlists declared in `access` reach the client as literal unions, so
+ * `list` can type `filters` and `sort` per table. Tables that declare nothing
+ * get `never` filters and `'id'` sorting, matching the runtime defaults.
+ */
+type FilterableOf<TAccess, K extends string> = K extends keyof TAccess
+  ? TAccess[K] extends { filterableColumns: readonly (infer F extends string)[] }
+    ? F
+    : never
+  : never
+
+type SortableOf<TAccess, K extends string> = K extends keyof TAccess
+  ? TAccess[K] extends { sortableColumns: readonly (infer S extends string)[] }
+    ? S
+    : 'id'
+  : 'id'
+
 export type CrudApiRouterFor<
   TSchema extends Record<string, unknown>,
   TAccess = undefined,
 > = {
   [K in ExposedApiTables<TSchema, TAccess> as TSchema[K] extends Table
     ? K
-    : never]: TableCrudProcedures<Extract<TSchema[K], Table>>
+    : never]: TableCrudProcedures<
+    Extract<TSchema[K], Table>,
+    FilterableOf<TAccess, K>,
+    SortableOf<TAccess, K>
+  >
 }
 
 type IsProcedure<T> = T extends { '~orpc': unknown } ? true : false

package/src/crud-operations.ts

@@ -17,7 +17,6 @@ import {
   tableEntryForName,
   type AccessUser,
   type ResolvedAccess,
-  type ResolvedTableAccess,
   type ScopeMap,
   type ScopeResolver,
 } from './access'
@@ -34,7 +33,12 @@ import {
   storeIdempotency,
   type IdempotencyConfig,
 } from './idempotency'
-import { executeList, parseListParams, type ListResult } from './list-query'
+import {
+  executeList,
+  resolveListParams,
+  type ListParamsInput,
+  type ListResult,
+} from './list-query'
 import { buildScopeWhere } from './scope'
 
 export interface CrudExecutionContext {
@@ -49,8 +53,8 @@ function errorCodeForStatus(status: number): BunderstackErrorCode {
   if (status === 404) return 'NOT_FOUND'
   if (status === 409) return 'CONFLICT'
   if (status === 413) return 'PAYLOAD_TOO_LARGE'
-  if (status === 429) return 'RATE_LIMITED'
-  return 'VALIDATION_ERROR'
+  if (status === 429) return 'TOO_MANY_REQUESTS'
+  return 'BAD_REQUEST'
 }
 
 export class CrudOperationError extends BunderstackError {
@@ -165,7 +169,7 @@ export function createCrudOperations<
     if (!idCol) {
       throw new CrudOperationError(
         400,
-        ErrorCode.VALIDATION_ERROR,
+        ErrorCode.BAD_REQUEST,
         `Table ${tableName} has no id column`,
       )
     }
@@ -175,7 +179,7 @@ export function createCrudOperations<
   return {
     async list(
       tableName: string,
-      paramsInput: URL | Record<string, unknown> | undefined,
+      params: ListParamsInput | undefined,
       ctx: CrudExecutionContext,
     ): Promise<ListResult<Record<string, unknown>>> {
       const { table, tableAccess, idCol } = resolveTable(tableName)
@@ -193,29 +197,15 @@ export function createCrudOperations<
         )
       }
 
-      let urlObj: URL
-      if (paramsInput instanceof URL) {
-        urlObj = paramsInput
-      } else {
-        urlObj = new URL(ctx.request.url || 'http://localhost')
-        if (paramsInput) {
-          for (const [k, v] of Object.entries(paramsInput)) {
-            if (v !== undefined && v !== null) {
-              urlObj.searchParams.set(k, String(v))
-            }
-          }
-        }
-      }
-
       try {
-        const params = parseListParams(urlObj, tableAccess)
+        const resolved = resolveListParams(params ?? {}, tableAccess)
         const scope = scopeFor(tableAccess.readScope, ctx)
         const scopeWhere = scope ? buildScopeWhere(table, scope) : undefined
         return await executeList(
           db,
           table,
           tableAccess,
-          params,
+          resolved,
           idCol,
           scopeWhere,
         )
@@ -290,7 +280,7 @@ export function createCrudOperations<
       if (!isRecord(body)) {
         throw new CrudOperationError(
           400,
-          ErrorCode.VALIDATION_ERROR,
+          ErrorCode.BAD_REQUEST,
           'Invalid JSON body',
         )
       }
@@ -407,7 +397,7 @@ export function createCrudOperations<
       if (!isRecord(body)) {
         throw new CrudOperationError(
           400,
-          ErrorCode.VALIDATION_ERROR,
+          ErrorCode.BAD_REQUEST,
           'Invalid JSON body',
         )
       }
@@ -422,7 +412,7 @@ export function createCrudOperations<
       if (Object.keys(values).length === 0) {
         throw new CrudOperationError(
           400,
-          ErrorCode.VALIDATION_ERROR,
+          ErrorCode.BAD_REQUEST,
           'No writable fields to update',
         )
       }

package/src/email/smtp.ts

@@ -1,6 +1,6 @@
 import nodemailer from 'nodemailer'
 
-import type { EmailAdapter, EmailMessage } from '../email'
+import type { EmailAdapter } from '../email'
 
 type SmtpTransport = {
   sendMail(message: Record<string, unknown>): Promise<{ messageId?: string }>

package/src/errors.ts

@@ -1,30 +1,31 @@
-import { ORPCError, os, type ErrorMap } from '@orpc/server'
+import {
+  COMMON_ERROR_STATUS_MAP,
+  ORPCError,
+  os,
+  type ErrorMap,
+} from '@orpc/server'
 import * as v from 'valibot'
 
 import { StandardSchemaValidationError } from './standard-schema'
 
+/**
+ * Every code we raise is one oRPC already knows, so handlers derive the HTTP
+ * status from `COMMON_ERROR_STATUS_MAP` on their own and clients can use the
+ * standard `isDefinedError` helpers. Do not add a code oRPC has no status for —
+ * it would silently answer 500.
+ */
 export const BUNDERSTACK_ERROR_CODES = [
-  'VALIDATION_ERROR',
+  'BAD_REQUEST',
   'UNAUTHORIZED',
   'FORBIDDEN',
   'NOT_FOUND',
   'CONFLICT',
   'PAYLOAD_TOO_LARGE',
-  'RATE_LIMITED',
-] as const
+  'TOO_MANY_REQUESTS',
+] as const satisfies readonly (keyof typeof COMMON_ERROR_STATUS_MAP)[]
 
 export type BunderstackErrorCode = (typeof BUNDERSTACK_ERROR_CODES)[number]
 
-export const BUNDERSTACK_ERROR_STATUS_MAP = {
-  VALIDATION_ERROR: 400,
-  UNAUTHORIZED: 401,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  CONFLICT: 409,
-  PAYLOAD_TOO_LARGE: 413,
-  RATE_LIMITED: 429,
-} as const satisfies Record<BunderstackErrorCode, number>
-
 function errorDataSchema<const TCode extends BunderstackErrorCode>(
   code: TCode,
 ) {
@@ -35,13 +36,13 @@ function errorDataSchema<const TCode extends BunderstackErrorCode>(
 }
 
 export const BUNDERSTACK_ERRORS = {
-  VALIDATION_ERROR: { data: errorDataSchema('VALIDATION_ERROR') },
+  BAD_REQUEST: { data: errorDataSchema('BAD_REQUEST') },
   UNAUTHORIZED: { data: errorDataSchema('UNAUTHORIZED') },
   FORBIDDEN: { data: errorDataSchema('FORBIDDEN') },
   NOT_FOUND: { data: errorDataSchema('NOT_FOUND') },
   CONFLICT: { data: errorDataSchema('CONFLICT') },
   PAYLOAD_TOO_LARGE: { data: errorDataSchema('PAYLOAD_TOO_LARGE') },
-  RATE_LIMITED: { data: errorDataSchema('RATE_LIMITED') },
+  TOO_MANY_REQUESTS: { data: errorDataSchema('TOO_MANY_REQUESTS') },
 } as const satisfies ErrorMap
 
 export class BunderstackError extends Error {
@@ -55,7 +56,7 @@ export class BunderstackError extends Error {
   ) {
     super(message, options)
     this.name = 'BunderstackError'
-    this.status = BUNDERSTACK_ERROR_STATUS_MAP[code]
+    this.status = COMMON_ERROR_STATUS_MAP[code]
   }
 }
 
@@ -68,7 +69,7 @@ export const mapBunderstackErrors = os
       const mapped =
         error instanceof StandardSchemaValidationError
           ? new BunderstackError(
-              'VALIDATION_ERROR',
+              'BAD_REQUEST',
               error.message,
               error.issues,
               { cause: error },
@@ -87,14 +88,18 @@ export const mapBunderstackErrors = os
     }
   })
 
-/** @deprecated Legacy internal error codes retained for list-query compatibility. */
+/**
+ * Sub-codes carried in `data.details.code` when the oRPC code alone loses
+ * information the client may want to branch on. Codes that duplicate an oRPC
+ * code are suppressed as redundant, see {@link CrudOperationError}.
+ */
 export const ErrorCode = {
-  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  BAD_REQUEST: 'BAD_REQUEST',
   FORBIDDEN: 'FORBIDDEN',
   NOT_FOUND: 'NOT_FOUND',
   CONFLICT: 'CONFLICT',
   INVALID_CURSOR: 'INVALID_CURSOR',
-  RATE_LIMITED: 'RATE_LIMITED',
+  TOO_MANY_REQUESTS: 'TOO_MANY_REQUESTS',
   IDEMPOTENCY_REPLAY: 'IDEMPOTENCY_REPLAY',
   IDEMPOTENCY_CONFLICT: 'IDEMPOTENCY_CONFLICT',
 } as const
@@ -107,7 +112,7 @@ export class ListQueryError extends Error {
 
   constructor(
     message: string,
-    code: ErrorCodeValue = ErrorCode.VALIDATION_ERROR,
+    code: ErrorCodeValue = ErrorCode.BAD_REQUEST,
     details?: unknown,
   ) {
     super(message)

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { AnyRouter as AnyORPCRouter } from '@orpc/server'
 // src/index.ts
 
+import { SmartCoercionHandlerPlugin } from '@orpc/json-schema'
 import { OpenAPIGenerator, OpenAPIGeneratorError } from '@orpc/openapi'
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { RPCHandler } from '@orpc/server/fetch'
@@ -9,7 +10,6 @@ import { ValibotToJsonSchemaConverter } from '@orpc/valibot'
 import type { TableAccessInput } from './access'
 import type {
   CrudApiRouterFor,
-  ExposedApiTables,
   MergeApiRouterTypes,
   UnifiedApiRouter,
 } from './api/types'
@@ -36,8 +36,6 @@ import { buildApiRouter } from './api/router'
 import { buildStorageApiRouter } from './api/storage-router'
 import {
   buildApiRegistry,
-  mergeApiRoutersStrict,
-  normalizeApiPath,
   normalizeForeignOpenAPISpec,
 } from './api/registry'
 import {
@@ -51,7 +49,6 @@ import { createDb } from './db'
 import { detectDialect } from './dialect'
 import { createEmail, emailProviderTag, type EmailFacade } from './email'
 import { validateEnv, type EnvConfigInput, type ValidatedEnv } from './env'
-import { BUNDERSTACK_ERROR_STATUS_MAP } from './errors'
 import { buildHandler } from './handler'
 import { withInternalTables } from './internal-tables'
 import {
@@ -348,6 +345,7 @@ export async function createBunderstack<
     const realtime = createRealtimeFacade<TSchema>(
       publisher,
       runtimeRealtimeTransport,
+      options.schema,
     )
     const registry = createBucketStorages(config.storage)
     const storageOperations = createStorageOperations({
@@ -410,7 +408,7 @@ export async function createBunderstack<
     // ordinary cron now, so it inherits retries, timeout and onFailed.
     const resolvedDefs: JobsDefs | undefined = storageConfigured
       ? {
-          ...(jobsDefs ?? {}),
+          ...jobsDefs,
           'bunderstack:storage-sweep': {
             kind: 'cron',
             schedule: '0 4 * * *',
@@ -546,11 +544,13 @@ export async function createBunderstack<
       ]),
     })
 
+    const valibotConverter = new ValibotToJsonSchemaConverter()
+
     const combinedOpenAPISpec = options.openapi
       ? mergeOpenAPISpecs({
           nativeSpec: await new OpenAPIGenerator({
             converters: [
-              new ValibotToJsonSchemaConverter(),
+              valibotConverter,
               {
                 condition: (schema: any) =>
                   Boolean(
@@ -571,13 +571,22 @@ export async function createBunderstack<
       : undefined
 
     const openapiHandler = new OpenAPIHandler(nativeRouter, {
-      errorStatusMap: BUNDERSTACK_ERROR_STATUS_MAP,
+      // Query strings and form bodies are strings; this coerces them to the
+      // types each procedure's input schema declares, so schemas stay honest
+      // (`v.number()`, not a string-union pipe) and REST matches RPC.
+      plugins: [
+        new SmartCoercionHandlerPlugin({ converters: [valibotConverter] }),
+      ],
       customErrorResponseBodyEncoder: (error: any) => ({
         error: error.message,
         code: error.data?.code ?? error.code,
+        // oRPC reports schema failures as `data.issues`; forwarding them tells
+        // the client which field was rejected instead of just "invalid".
         ...(error.data?.details !== undefined
           ? { details: error.data.details }
-          : {}),
+          : error.data?.issues !== undefined
+            ? { details: error.data.issues }
+            : {}),
       }),
       fetchInterceptors: [
         async (options) => {
@@ -806,6 +815,9 @@ export type {
 
 export { createApiBuilder } from './api/builder'
 export type { BunderstackApiBuilder, ApiFactory } from './api/builder'
+// Needed to declare shared middleware over the app's context, e.g.
+// `os.$context<ApiContext<typeof schema>>().middleware(...)`.
+export type { ApiContext } from './api/context'
 export type {
   CrudApiRouterFor,
   ExposedApiTables,

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/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,4 +1,9 @@
-import { getTableName, type InferSelectModel, type Table } from 'drizzle-orm'
+import {
+  getTableName,
+  isTable,
+  type InferSelectModel,
+  type Table,
+} from 'drizzle-orm'
 
 import type {
   RealtimeAction,
@@ -25,9 +30,17 @@ 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>>(
   publisher?: RealtimePublisher,
   transport: RealtimeTransport = publisher ? 'memory' : 'disabled',
+  schema?: TSchema,
 ): RealtimeFacade<TSchema> {
   if (!publisher && transport !== 'disabled') {
     throw new Error(
@@ -40,13 +53,19 @@ export function createRealtimeFacade<TSchema extends Record<string, unknown>>(
     )
   }
 
+  const keyByTableName = new Map<string, string>()
+  for (const [key, value] of Object.entries(schema ?? {})) {
+    if (isTable(value)) keyByTableName.set(getTableName(value), key)
+  }
+
   return {
     enabled: publisher !== undefined,
     transport,
     async publish(table, action, record) {
       if (!publisher) return
+      const tableName = getTableName(table)
       await publisher.publish('change', {
-        table: getTableName(table),
+        table: keyByTableName.get(tableName) ?? tableName,
         action,
         record: record as unknown as Record<string, unknown>,
       })

package/src/realtime/filter.ts

@@ -33,7 +33,11 @@ export async function* filterRealtimeChanges(
   const getSession = () => (sessionPromise ??= options.getSession())
 
   for await (const change of source) {
-    const entry = tableEntryForName(options.access, change.table)
+    // Events name tables by schema key; the SQL-name lookup stays as a fallback
+    // for publishers outside the CRUD path that only know the physical name.
+    const entry =
+      options.access.get(change.table) ??
+      tableEntryForName(options.access, change.table)
     if (!entry?.enabled) continue
 
     const recordId = change.record.id

package/src/storage/operations.ts

@@ -187,7 +187,7 @@ export function createStorageOperations(options: StorageOperationsOptions) {
 
       if (!matchMime(file.type, bucket.upload?.accept)) {
         throw new BunderstackError(
-          'VALIDATION_ERROR',
+          'BAD_REQUEST',
           `Content type ${file.type || '(none)'} not allowed`,
         )
       }
@@ -255,7 +255,7 @@ export function createStorageOperations(options: StorageOperationsOptions) {
         await adapter.delete(fileId)
         await deleteFileMetaRow(db, fileId)
         throw new BunderstackError(
-          validation ? 'VALIDATION_ERROR' : 'PAYLOAD_TOO_LARGE',
+          validation ? 'BAD_REQUEST' : 'PAYLOAD_TOO_LARGE',
           message,
         )
       }
@@ -308,7 +308,7 @@ export function createStorageOperations(options: StorageOperationsOptions) {
       if (spec) {
         if (!bucket.transforms) {
           throw new BunderstackError(
-            'VALIDATION_ERROR',
+            'BAD_REQUEST',
             'Transforms not enabled for this bucket',
           )
         }

package/src/api/api-types.types.ts

@@ -1,106 +0,0 @@
-import type { InferRouterInputs, InferRouterOutputs } from '@orpc/server'
-
-import { pgTable, text } from 'drizzle-orm/pg-core'
-import * as v from 'valibot'
-
-import type { ExposedApiTables } from './types'
-
-import { pglite } from '../database/pglite'
-import { createBunderstack } from '../index'
-
-type Equal<A, B> =
-  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
-    ? true
-    : false
-type Expect<T extends true> = T
-
-const posts = pgTable('posts', {
-  id: text('id').primaryKey(),
-  title: text('title').notNull(),
-})
-
-const privateNotes = pgTable('private_notes', {
-  id: text('id').primaryKey(),
-  content: text('content').notNull(),
-})
-
-const ownedPosts = pgTable('owned_posts', {
-  id: text('id').primaryKey(),
-  userId: text('user_id').notNull(),
-})
-
-type ImplicitTables = ExposedApiTables<
-  { posts: typeof posts; ownedPosts: typeof ownedPosts },
-  undefined
->
-type _ImplicitAccessHidesUnownedTable = Expect<
-  Equal<'posts' extends ImplicitTables ? true : false, false>
->
-type _ImplicitAccessIncludesConventionTable = Expect<
-  Equal<'ownedPosts' extends ImplicitTables ? true : false, true>
->
-
-const typedApp = await createBunderstack({
-  schema: { posts, privateNotes },
-  database: { adapter: pglite() },
-  processEnv: {
-    DATABASE_URL: 'memory://',
-    BUNDERSTACK_ROLE: 'web',
-  },
-  access: {
-    posts: { crud: true, list: 'public', create: 'public' },
-    privateNotes: { crud: false },
-  },
-  api: (o) => ({
-    stats: o.protected
-      .input(v.object({ period: v.picklist(['day', 'week']) }))
-      .output(
-        v.object({ period: v.picklist(['day', 'week']), userId: v.string() }),
-      )
-      .handler(async ({ input, context }) => {
-        const _userId: string = context.user.id
-        const _db = context.db
-        const _env = context.env
-        return {
-          period: input.period,
-          userId: context.user.id,
-        }
-      }),
-  }),
-})
-
-type Api = NonNullable<typeof typedApp.$inferClient>['api']
-
-type _HasPosts = Expect<Equal<'posts' extends keyof Api ? true : false, true>>
-type _HidesPrivateNotes = Expect<
-  Equal<'privateNotes' extends keyof Api ? true : false, false>
->
-type _HasStats = Expect<Equal<'stats' extends keyof Api ? true : false, true>>
-
-type PostsInputs = InferRouterInputs<Api>['posts']
-type PostsOutputs = InferRouterOutputs<Api>['posts']
-type IsAny<T> = 0 extends 1 & T ? true : false
-type ExpectedUpdateInput = {
-  params: { id: string }
-  query?: Record<string, unknown>
-  headers?: Record<string, unknown>
-  body: { title?: string }
-}
-
-type _CreateInput = Expect<
-  Equal<
-    PostsInputs['create'],
-    Partial<typeof posts.$inferInsert>
-  >
->
-type _GetInput = Expect<Equal<PostsInputs['get'], { id: string }>>
-type _UpdateInputToExpected = Expect<
-  PostsInputs['update'] extends ExpectedUpdateInput ? true : false
->
-type _ExpectedToUpdateInput = Expect<
-  ExpectedUpdateInput extends PostsInputs['update'] ? true : false
->
-type _ListItems = Expect<
-  Equal<PostsOutputs['list']['items'], Array<{ id: string; title: string }>>
->
-type _GetOutputIsTyped = Expect<Equal<IsAny<PostsOutputs['get']>, false>>