bunderstack 0.15.2 → 0.17.0-beta.0

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:
+Generated CRUD writes publish automatically. After a custom write commits,
+publish its complete returned row with:
 
 ```ts
-import { app } from './bunderstack'
-
-await app.runWorker()
+await context.realtime.publish(schema.posts, 'update', post)
 ```
 
-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()`.
+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`.
 
-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 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).
-
-### 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.
-
-```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)
-```
-
-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.
-
-## 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.15.2",
-  "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.0",
+  "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",
@@ -47,43 +47,51 @@
     "./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",
+    "typecheck": "tsc --noEmit",
     "dev": "bun --hot ../../examples/standalone/server.ts",
     "db:push": "drizzle-kit push",
     "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/openapi": "2.0.0-beta.26",
+    "@orpc/bun": "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/openapi": "2.0.0-beta.26",
+    "@orpc/bun": "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

@@ -65,6 +65,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. */
@@ -103,6 +105,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',
@@ -190,6 +210,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',
@@ -199,7 +220,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/api-types.types.ts

@@ -0,0 +1,106 @@
+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>>

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,
+  }
+}