bunderstack 0.6.0 → 0.7.0

package/README.md

@@ -79,6 +79,32 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.6.0",
+  "version": "0.7.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.",
   "keywords": [
     "backend",

package/src/crud.ts

@@ -2,7 +2,7 @@ import { eq, getTableColumns, getTableName, isTable } from 'drizzle-orm'
 import { Hono } from 'hono'
 
 import type { AnyDb } from './dialect'
-import type { RealtimeBroker } from './realtime/index'
+import type { RealtimeFacade } from './realtime/facade'
 
 import {
   checkAccess,
@@ -29,11 +29,13 @@ import {
 import { executeList, parseListParams } from './list-query'
 import { buildScopeWhere } from './scope'
 
-export type CrudRouterOptions = {
+export type CrudRouterOptions<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> = {
   auth?: AuthSessionResolver
   access: ResolvedAccess
   idempotency?: boolean | IdempotencyConfig
-  broker?: RealtimeBroker
+  realtime?: RealtimeFacade<TSchema>
 }
 
 function tableEntryForName(
@@ -63,10 +65,10 @@ async function enforce(
 export function buildCrudRouter<TSchema extends Record<string, unknown>>(
   schema: TSchema,
   db: AnyDb,
-  options: CrudRouterOptions,
+  options: CrudRouterOptions<TSchema>,
 ): Hono {
   const router = new Hono()
-  const { auth, access, broker } = options
+  const { auth, access, realtime } = options
   const idempotency = resolveIdempotencyConfig(options.idempotency)
 
   const scopeFor = (
@@ -243,7 +245,7 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const rows = await (db as any).insert(table).values(stamped).returning()
       const created = rows[0]
-      void broker?.publish(name, 'create', created as Record<string, unknown>)
+      void realtime?.publish(table as never, 'create', created as never)
 
       if (idempotency && idempotencyKey) {
         await storeIdempotency(
@@ -329,7 +331,7 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
       if (!rows[0]) {
         return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
       }
-      void broker?.publish(name, 'update', rows[0] as Record<string, unknown>)
+      void realtime?.publish(table as never, 'update', rows[0] as never)
       return c.json(rows[0])
     })
 
@@ -375,11 +377,7 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       await (db as any).delete(table).where(eq(idCol as any, id))
-      void broker?.publish(
-        name,
-        'delete',
-        existing[0] as Record<string, unknown>,
-      )
+      void realtime?.publish(table as never, 'delete', existing[0] as never)
       return new Response(null, { status: 204 })
     })
   }

package/src/email.ts

@@ -114,7 +114,7 @@ function createSmtpAdapter(
     sendMail(opts: Record<string, unknown>): Promise<{ messageId?: string }>
   }> | null = null
   const getTransport = () => {
-    transportPromise ??= import(specifier).then((mod) =>
+    transportPromise ??= import(/* @vite-ignore */ specifier).then((mod) =>
       (mod.default ?? mod).createTransport(smtpUrl),
     )
     return transportPromise

package/src/index.ts

@@ -49,6 +49,7 @@ import {
 } from './provision-internals'
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
+import { createRealtimeFacade, type RealtimeFacade } from './realtime/facade'
 import { deleteFileWithDerivatives } from './storage/delete'
 import { deleteFileMetaRow } from './storage/file-meta'
 import { createBucketStorages } from './storage/registry'
@@ -136,6 +137,8 @@ export type BunderstackApp<
   email: EmailFacade
   /** Job queue facade; always present — enqueue throws when jobs aren't configured. */
   jobs: JobsFacade<TJobsDefs extends JobsDefs ? TJobsDefs : Record<never, never>>
+  /** Typed custom row publication; enabled=false/no-op when realtime is off. */
+  realtime: RealtimeFacade<TSchema>
   startWorker(options?: AppStartWorkerOptions): Promise<WorkerHandle>
   /** Run a queue worker until aborted, then close the application. */
   runWorker(options?: AppRunWorkerOptions): Promise<void>
@@ -352,11 +355,12 @@ export async function createBunderstack<
           bufferSize: realtimeBufferSize,
         })
     : undefined
+  const realtime = createRealtimeFacade<TSchema>(broker)
   const crudRouter = buildCrudRouter(options.schema, userDb, {
     auth: authResolver,
     access: resolvedAccess,
     idempotency: options.idempotency,
-    broker,
+    realtime,
   })
   const realtimeRouter = broker
     ? buildRealtimeRouter(broker, {
@@ -397,7 +401,7 @@ export async function createBunderstack<
     ? createJobRunner({
         db,
         defs: jobsDefs,
-        ctx: { db: userDb, env, email, storage },
+        ctx: { db: userDb, env, email, storage, realtime },
       })
     : undefined
   const jobs = {
@@ -457,7 +461,7 @@ export async function createBunderstack<
         await runCronSlot({
           db,
           defs: jobsDefs!,
-          ctx: { db: userDb, env, email, storage },
+          ctx: { db: userDb, env, email, storage, realtime },
           name,
           slot,
           now: Date.now(),
@@ -504,6 +508,7 @@ export async function createBunderstack<
             env,
             email,
             jobs,
+            realtime,
             req,
           }),
         })
@@ -513,7 +518,7 @@ export async function createBunderstack<
       ? buildCronRouter({
           db,
           defs: jobsDefs ?? {},
-          ctx: { db: userDb, env, email, storage },
+          ctx: { db: userDb, env, email, storage, realtime },
           secret: env.BUNDERSTACK_CRON_SECRET,
           storage,
         })
@@ -544,6 +549,7 @@ export async function createBunderstack<
     router,
     env,
     email,
+    realtime,
     // Runtime facade is untyped (JobsRuntimeFacade); the generic-typed field
     // narrows `enqueue` per-app from the declared job defs — same relationship
     // as `userDb` above.
@@ -654,3 +660,6 @@ export type {
 } from './storage/buckets'
 // StorageFacade is declared+exported inline above.
 export type { TransformSpec } from './storage/thumbnails'
+
+export type { RealtimeAction } from './realtime/index'
+export type { RealtimeFacade, SchemaTable } from './realtime/facade'

package/src/jobs/define.ts

@@ -35,6 +35,8 @@ export type JobsRuntimeFacade = {
   tick(now?: number): Promise<void>
 }
 
+import type { RealtimeFacade } from '../realtime/facade'
+
 export type JobContext<
   TSchema extends Record<string, unknown> = Record<string, unknown>,
   TEnvResult = Record<string, unknown>,
@@ -44,6 +46,7 @@ export type JobContext<
   email: EmailFacade
   storage: StorageFacade
   jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
 }
 
 export type QueueJobDefinition<

package/src/realtime/facade.ts

@@ -0,0 +1,36 @@
+import { getTableName, type InferSelectModel, type Table } from 'drizzle-orm'
+
+import type { RealtimeAction, RealtimeBroker } from './index'
+
+export type SchemaTable<TSchema extends Record<string, unknown>> = Extract<
+  TSchema[keyof TSchema],
+  Table
+>
+
+export interface RealtimeFacade<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> {
+  readonly enabled: boolean
+
+  publish<TTable extends SchemaTable<TSchema>>(
+    table: TTable,
+    action: RealtimeAction,
+    record: InferSelectModel<TTable>,
+  ): Promise<void>
+}
+
+export function createRealtimeFacade<TSchema extends Record<string, unknown>>(
+  broker?: RealtimeBroker,
+): RealtimeFacade<TSchema> {
+  return {
+    enabled: broker !== undefined,
+    async publish(table, action, record) {
+      if (!broker) return
+      await broker.publish(
+        getTableName(table),
+        action,
+        record as unknown as Record<string, unknown>,
+      )
+    },
+  }
+}

package/src/trpc.ts

@@ -6,6 +6,7 @@ import type { AccessUser } from './access'
 import type { DbFor } from './db'
 import type { EmailFacade } from './email'
 import type { JobsRuntimeFacade } from './jobs/index'
+import type { RealtimeFacade } from './realtime/facade'
 
 export type TRPCContext<
   TSchema extends Record<string, unknown>,
@@ -16,6 +17,7 @@ export type TRPCContext<
   env: TEnvResult
   email: EmailFacade
   jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
   req: Request
 }