bunderstack 0.16.0 → 0.17.0-beta.2

package/README.md

@@ -1,164 +1,51 @@
 # bunderstack
 
-A batteries-included backend framework for Bun. Point it at a Drizzle schema
-and get CRUD APIs, auth, file storage, realtime, typed custom endpoints
-(tRPC), email, and validated env — all from a single config object and a
-single `Request → Response` handler.
+The server package for Bunderstack's unified, type-safe oRPC backend.
 
 ```sh
-bun add bunderstack better-auth drizzle-orm hono zod @libsql/client
+bun add bunderstack better-auth drizzle-orm valibot @libsql/client
 ```
 
 ```ts
 import { createBunderstack } from 'bunderstack'
 import { libsql } from 'bunderstack/database/libsql'
+import * as v from 'valibot'
 import * as schema from './schema'
 
-const app = await createBunderstack({
+export const app = await createBunderstack({
   schema,
-  database: {
-    adapter: libsql(),
-    url: 'file:./data.db',
-  },
-  auth: { emailAndPassword: { enabled: true } },
-  access: {
-    posts: { ownerColumn: 'userId', list: 'public', create: 'authenticated' },
-  },
+  database: { adapter: libsql(), url: 'file:./data.db' },
+  access: { posts: { crud: true } },
+  realtime: true,
+  api: (o) => ({
+    ping: o.public
+      .route({ method: 'GET', path: '/api/ping' })
+      .input(v.optional(v.object({})))
+      .handler(() => ({ ok: true })),
+  }),
 })
 
 Bun.serve({ fetch: app.handler })
+export type App = typeof app
 ```
 
-Full documentation and examples:
-[github.com/kirill-dev-pro/bunderstack](https://github.com/kirill-dev-pro/bunderstack)
+CRUD, custom procedures, webhooks, file buckets, health, and the Publisher
+event iterator form one router. Validation accepts Standard Schema; internal
+generated schemas use Valibot. OpenAPI is opt-in with `openapi: true`.
 
-## Platform deployment contract
-
-Deployment platforms (like Bunderhost) integrate with any bunderstack app
-through env vars alone — no code changes required.
-
-### Overrides (beat code-level config)
-
-| Var                                                                 | Effect                                                                                          |
-| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `BUNDERSTACK_DATABASE_URL`                                          | Database URL; wins over `database.url` in code                                                  |
-| `BUNDERSTACK_DATABASE_AUTH_TOKEN`                                   | Auth token for the database                                                                     |
-| `BUNDERSTACK_S3_ENDPOINT`                                           | Forces ALL buckets onto this S3 backend (code-level `local`/per-bucket `s3` blocks are ignored) |
-| `BUNDERSTACK_S3_BUCKET`                                             | Physical bucket name (logical buckets become key prefixes)                                      |
-| `BUNDERSTACK_S3_ACCESS_KEY_ID` / `BUNDERSTACK_S3_SECRET_ACCESS_KEY` | Credentials                                                                                     |
-| `BUNDERSTACK_S3_REGION`                                             | Region (default `auto`)                                                                         |
-| `BUNDERSTACK_S3_PUBLIC_URL`                                         | Public base URL for `visibility: 'public'` buckets                                              |
-
-Plain `DATABASE_URL` / `S3_*` vars keep their usual role: fallbacks that
-code-level config wins over.
-
-### Committed deployment blueprint
-
-Generate a deterministic, provider-neutral declaration that a host can read
-without importing the application at deploy time. Version 1 supports TanStack
-Start apps and records database tables and migration mode, storage buckets,
-environment requirements, realtime, jobs, cron, and maintenance schedules.
-
-```sh
-bunx bunderstack blueprint
-bunx bunderstack blueprint --check
-```
-
-The command imports `src/bunderstack.ts` by default (or
-`package.json#bunderstack.entry`) with `BUNDERSTACK_INTROSPECT=1`, so it never
-opens external database, storage, or realtime connections. Commit the generated
-`bunderstack.blueprint.yaml`; CI should run the `--check` form. The public
-`bunderstack/blueprint` module exposes the strict parser and conversion helpers
-for hosts and other tooling.
-
-Real database clients belong to the app. Call `await app.close()` when a
-standalone process or test is finished; it closes the real libSQL, PGlite,
-postgres.js, or Bun SQL client selected by `database.adapter`. Introspection
-mocks own no client, so there is nothing to close for that database path.
-
-### Background runtime
-
-Declaring jobs does not start a worker. Queue jobs (`j.job()`) are processed by
-an explicit worker process:
-
-```ts
-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
-process-local memory broker and is suitable only when the worker is embedded
-with `app.startWorker()`.
-
-Since 0.9.0, `app.runWorker()` rejects that unsafe combination by default. If
-queue handlers never publish realtime events, acknowledge the process-local
-behavior with `app.runWorker({ allowProcessLocalRealtime: true })`.
-
-Inspect the active runtime with `app.realtime.transport` (`'disabled'`,
-`'memory'`, or `'redis'`). The generated blueprint declares only whether
-realtime is required; the host chooses its shared transport and injects its
-runtime configuration.
-
-```ts
-const app = await createBunderstack({
-  // ...
-  realtime: { redis: process.env.REDIS_URL! },
-})
-```
-
-```bash
-REDIS_URL=redis://localhost:6379 bun src/server.ts
-REDIS_URL=redis://localhost:6379 bun src/worker.ts
-```
-
-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
-
-Generated CRUD publishes automatically. Writes made directly through `app.db`
-or `ctx.db` are explicit: publish the complete row returned by Drizzle after the
-write commits.
+Generated CRUD writes publish automatically. After a custom write commits,
+publish its complete returned row with:
 
 ```ts
-const [avatar] = await ctx.db
-  .update(schema.avatars)
-  .set({ status: 'completed' })
-  .where(eq(schema.avatars.id, avatarId))
-  .returning()
-
-await ctx.realtime.publish(schema.avatars, 'update', avatar)
+await context.realtime.publish(schema.posts, 'update', post)
 ```
 
-The same typed facade is available as `app.realtime`, in tRPC context, and in
-queue-job and cron context. Passing the Drizzle table makes a table-name typo a
-type error and constrains the record to that table's select model.
-
-Publish after an enclosing transaction resolves, not from inside it. The full
-row is required because realtime access filtering may inspect its `id`, owner,
-or read-scope columns. Subscriber access checks, Redis fan-out, and replay are
-applied automatically by the existing broker. When server realtime is not
-configured, `realtime.enabled` is `false` and `publish()` is a no-op.
+Use the in-memory Publisher for one process or configure
+`realtime: { redis: process.env.REDIS_URL! }` for multi-process delivery and
+replay. Deployment metadata is generated with `bunx bunderstack blueprint`.
 
-## Shipping TypeScript source
-
-This package publishes raw TypeScript (`exports` point at `.ts` files). Bun
-consumes it natively. If a Node-based bundler or SSR server processes it,
-make sure the package is bundled rather than externalized — e.g. in Vite:
-
-```ts
-ssr: {
-  noExternal: [/^bunderstack/]
-}
-```
+See the [workspace documentation](../../README.md) for webhooks, clients,
+storage, collections, lifecycle, and complete examples.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bunderstack",
-  "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.",
+  "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",
     "better-auth",
@@ -9,9 +9,9 @@
     "crud",
     "drizzle",
     "framework",
-    "hono",
+    "orpc",
     "realtime",
-    "trpc"
+    "typesafe"
   ],
   "homepage": "https://github.com/kirill-dev-pro/bunderstack#readme",
   "license": "MIT",
@@ -26,6 +26,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*.types.ts",
     "README.md",
     "LICENSE"
   ],
@@ -47,9 +48,9 @@
     "./typeid/pg": "./src/typeid-pg.ts",
     "./env": "./src/env.ts",
     "./blueprint": "./src/blueprint.ts",
-    "./trpc": "./src/trpc.ts",
     "./cron": "./src/cron.ts",
-    "./email/smtp": "./src/email/smtp.ts"
+    "./email/smtp": "./src/email/smtp.ts",
+    "./api": "./src/api/types.ts"
   },
   "scripts": {
     "test": "bun test",
@@ -59,32 +60,41 @@
     "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "superjson": "^2.2.0",
+    "@standard-schema/spec": "1.1.0",
+    "valibot": "1.4.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": ">=0.3.0",
     "@libsql/client": ">=0.14.0",
-    "@trpc/server": "^11.0.0",
+    "@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",
     "@types/nodemailer": "^6",
     "better-auth": "^1.0.0",
     "drizzle-kit": "^0.30.0",
     "drizzle-orm": "^0.45.0",
-    "hono": "^4.0.0",
-    "zod": "^4.4.3"
+    "drizzle-valibot": "0.4.2"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.3.0",
     "@libsql/client": ">=0.14.0",
-    "@trpc/server": "^11.0.0",
+    "@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",
     "better-auth": "^1.0.0",
     "drizzle-kit": "^0.30.0",
     "drizzle-orm": "^0.45.0",
-    "hono": "^4.0.0",
+    "drizzle-valibot": "0.4.2",
     "nodemailer": ">=6 <10",
     "postgres": ">=3.4.0",
-    "typescript": ">=5",
-    "zod": "^4.4.3"
+    "typescript": ">=5"
   },
   "peerDependenciesMeta": {
     "@electric-sql/pglite": {

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 = {
@@ -65,6 +55,8 @@ export type TableAccessInput = {
   create?: OperationRule
   update?: OperationRule
   delete?: OperationRule
+  /** Explicit write allowlist. Entries override matching system-readonly
+   * defaults such as `updatedAt`; `id` remains immutable on update. */
   writableColumns?: string[]
   readonlyColumns?: string[]
   /** Columns matched by `?q=` on list — opt-in; omitted columns are never searched. */
@@ -174,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}"`,
@@ -187,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}"`,
@@ -208,6 +190,7 @@ function resolveDefaults(
   columns: string[],
 ): Omit<ResolvedTableAccess, 'tableKey' | 'tableName' | 'enabled'> {
   const listAccess = resolveListAccess(input, columns)
+  const explicitlyWritable = new Set(input.writableColumns ?? [])
   return {
     ownerColumn,
     list: input.list ?? 'public',
@@ -217,7 +200,9 @@ function resolveDefaults(
     delete: input.delete ?? (ownerColumn ? 'owner' : 'deny'),
     writableColumns: input.writableColumns,
     readonlyColumns: [
-      ...DEFAULT_READONLY,
+      ...DEFAULT_READONLY.filter(
+        (column) => column === 'id' || !explicitlyWritable.has(column),
+      ),
       ...(input.readonlyColumns ?? []),
       ...(ownerColumn ? [ownerColumn] : []),
     ],

package/src/api/builder.ts

@@ -0,0 +1,52 @@
+import { os, type AnyRouter } from '@orpc/server'
+
+import type { ApiContext } from './context'
+
+import {
+  BUNDERSTACK_ERRORS,
+  BunderstackError,
+  mapBunderstackErrors,
+} from '../errors'
+export type { ProtectedContextAdditions } from './types'
+
+export function createApiBuilder<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnv = Record<string, unknown>,
+>() {
+  const base = os
+    .$context<ApiContext<TSchema, TEnv>>()
+    .errors(BUNDERSTACK_ERRORS)
+    .use(mapBunderstackErrors)
+
+  const protectedProc = base.use(async ({ context, next }) => {
+    const session = await context.getSession()
+    if (!session.user) {
+      throw new BunderstackError('UNAUTHORIZED', 'Authentication required')
+    }
+    return next({
+      context: {
+        user: session.user,
+        session: {
+          activeOrganizationId: session.activeOrganizationId,
+        },
+      },
+    })
+  })
+
+  return {
+    public: base,
+    protected: protectedProc,
+    webhook: base,
+  }
+}
+
+export type BunderstackApiBuilder<
+  TSchema extends Record<string, unknown>,
+  TEnv = Record<string, unknown>,
+> = ReturnType<typeof createApiBuilder<TSchema, TEnv>>
+
+export type ApiFactory<
+  TSchema extends Record<string, unknown>,
+  TEnv,
+  TCustomApiRouter extends AnyRouter,
+> = (builder: BunderstackApiBuilder<TSchema, TEnv>) => TCustomApiRouter

package/src/api/context.ts

@@ -0,0 +1,83 @@
+import type { AccessUser, AuthSessionResolver } from '../access'
+import type { DbFor } from '../db'
+import type { EmailFacade } from '../email'
+import type { AuthInstance, StorageFacade } from '../index'
+import type { JobsRuntimeFacade } from '../jobs/define'
+import type { RealtimeFacade } from '../realtime/facade'
+
+import { resolveSession } from '../access'
+
+export interface ApiContextDeps<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnv = Record<string, unknown>,
+> {
+  db: DbFor<TSchema>
+  env: TEnv
+  storage: StorageFacade
+  email: EmailFacade
+  jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
+  auth: AuthInstance
+  authResolver?: AuthSessionResolver
+}
+
+export interface ApiContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnv = Record<string, unknown>,
+> {
+  db: DbFor<TSchema>
+  env: TEnv
+  storage: StorageFacade
+  email: EmailFacade
+  jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
+  auth: AuthInstance
+  request: Request
+  resHeaders: Headers
+  getRawBody: () => Promise<string>
+  getSession: () => Promise<{
+    user: AccessUser | null
+    activeOrganizationId: string | null
+  }>
+}
+
+export function createApiContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnv = Record<string, unknown>,
+>(
+  deps: ApiContextDeps<TSchema, TEnv>,
+  request: Request,
+): ApiContext<TSchema, TEnv> {
+  // Reserve the body stream before a transport codec consumes `request`.
+  const rawBodyRequest = request.clone()
+  let rawBodyPromise: Promise<string> | undefined
+  let sessionPromise:
+    | Promise<{ user: AccessUser | null; activeOrganizationId: string | null }>
+    | undefined
+
+  const getSession = () => {
+    if (!sessionPromise) {
+      sessionPromise = resolveSession(deps.authResolver, request.headers)
+    }
+    return sessionPromise
+  }
+
+  const getRawBody = () => {
+    if (!rawBodyPromise) rawBodyPromise = rawBodyRequest.text()
+    return rawBodyPromise
+  }
+
+  return {
+    db: deps.db,
+    env: deps.env,
+    storage: deps.storage,
+    email: deps.email,
+    jobs: deps.jobs,
+    realtime: deps.realtime,
+    auth: deps.auth,
+    request,
+    resHeaders: new Headers(),
+    getRawBody,
+    getSession,
+  }
+}