bunderstack 0.7.0 → 0.9.0

package/README.md

@@ -6,15 +6,20 @@ and get CRUD APIs, auth, file storage, realtime, typed custom endpoints
 single `Request → Response` handler.
 
 ```sh
-bun add bunderstack
+bun add bunderstack better-auth drizzle-orm hono zod @libsql/client
 ```
 
 ```ts
 import { createBunderstack } from 'bunderstack'
+import { libsql } from 'bunderstack/database/libsql'
 import * as schema from './schema'
 
 const app = await createBunderstack({
   schema,
+  database: {
+    adapter: libsql(),
+    url: 'file:./data.db',
+  },
   auth: { emailAndPassword: { enabled: true } },
   access: {
     posts: { ownerColumn: 'userId', list: 'public', create: 'authenticated' },
@@ -34,15 +39,15 @@ 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 |
+| 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.
@@ -50,8 +55,9 @@ code-level config wins over.
 ### Introspection
 
 Set `BUNDERSTACK_INTROSPECT=1` and import the app declaration: the boot is
-guaranteed offline (in-memory database, no Redis) and missing user env vars
-don't throw. Then read `app.manifest`:
+guaranteed offline (the selected adapter returns its `drizzle.mock({ schema })`
+database, no Redis) and missing user env vars don't throw. Then read
+`app.manifest`:
 
 ```ts
 process.env.BUNDERSTACK_INTROSPECT = '1'
@@ -60,6 +66,11 @@ console.log(JSON.stringify(app.manifest))
 // { version: 2, dialect, tables, tableMap, systemTables, background, ... }
 ```
 
+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
@@ -71,6 +82,28 @@ import { app } from './bunderstack'
 await app.runWorker()
 ```
 
+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()`.
+
+`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 })`.
+
+```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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -33,6 +33,10 @@
   "exports": {
     ".": "./src/index.ts",
     "./access": "./src/access.ts",
+    "./database/bun-sql": "./src/database/bun-sql.ts",
+    "./database/libsql": "./src/database/libsql.ts",
+    "./database/pglite": "./src/database/pglite.ts",
+    "./database/postgres-js": "./src/database/postgres-js.ts",
     "./provision": "./src/provision.ts",
     "./schema": "./src/schema-export.ts",
     "./schema/pg": "./src/schema-export-pg.ts",
@@ -40,7 +44,8 @@
     "./typeid/pg": "./src/typeid-pg.ts",
     "./env": "./src/env.ts",
     "./trpc": "./src/trpc.ts",
-    "./cron": "./src/cron.ts"
+    "./cron": "./src/cron.ts",
+    "./email/smtp": "./src/email/smtp.ts"
   },
   "scripts": {
     "test": "bun test",
@@ -49,26 +54,31 @@
     "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "@trpc/server": "^11.0.0",
-    "better-auth": "^1.0.0",
-    "hono": "^4.0.0",
-    "superjson": "^2.2.0",
-    "zod": "^4.4.3"
+    "superjson": "^2.2.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": ">=0.3.0",
     "@libsql/client": ">=0.14.0",
+    "@trpc/server": "^11.0.0",
+    "@types/nodemailer": "^6",
+    "better-auth": "^1.0.0",
     "drizzle-kit": "^0.30.0",
-    "drizzle-orm": "^0.45.0"
+    "drizzle-orm": "^0.45.0",
+    "hono": "^4.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.3.0",
     "@libsql/client": ">=0.14.0",
+    "@trpc/server": "^11.0.0",
+    "better-auth": "^1.0.0",
     "drizzle-kit": "^0.30.0",
     "drizzle-orm": "^0.45.0",
-    "nodemailer": "^6",
+    "hono": "^4.0.0",
+    "nodemailer": ">=6 <10",
     "postgres": ">=3.4.0",
-    "typescript": "^5"
+    "typescript": ">=5",
+    "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
     "@electric-sql/pglite": {
@@ -85,6 +95,9 @@
     },
     "postgres": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   }
 }

package/src/config.ts

@@ -3,12 +3,12 @@ import { betterAuth } from 'better-auth'
 import { z } from 'zod'
 
 import type { TableAccessInput } from './access'
+import type { DatabaseAdapter } from './database/adapter'
+import type { EmailConfigInput } from './email'
 import type { IdempotencyConfig } from './idempotency'
 import type { RateLimitConfig } from './rate-limit'
 
 import { validateEnv, type BaseEnv, type EnvConfigInput } from './env'
-import type { EmailConfigInput } from './email'
-
 import {
   resolveBuckets,
   type ResolvedStorageBuckets,
@@ -22,9 +22,10 @@ export type BetterAuthConfig = Omit<
 
 export const BunderstackOptionsSchema = z.object({
   schema: z.record(z.string(), z.unknown()),
-  access: z.record(z.string(), z.any()).optional(),
+  access: z.record(z.string(), z.unknown()).optional(),
   database: z
     .object({
+      adapter: z.unknown(),
       url: z.string().optional(),
       authToken: z.string().optional(),
       migrations: z.string().optional(),
@@ -82,10 +83,24 @@ export type BunderstackConfig<
   TEnv extends EnvConfigInput | undefined = EnvConfigInput | undefined,
 > = Omit<
   z.input<typeof BunderstackOptionsSchema>,
-  'schema' | 'access' | 'auth' | 'storage' | 'env' | 'email' | 'trpc' | 'jobs'
+  | 'schema'
+  | 'access'
+  | 'auth'
+  | 'storage'
+  | 'env'
+  | 'email'
+  | 'trpc'
+  | 'jobs'
+  | 'database'
 > & {
   schema: TSchema
   access?: TAccess
+  database: {
+    adapter: DatabaseAdapter
+    url?: string
+    authToken?: string
+    migrations?: string
+  }
   auth?: BetterAuthConfig
   storage?: TStorage
   env?: TEnv
@@ -106,7 +121,12 @@ export type BunderstackConfig<
 }
 
 export type ResolvedConfig = {
-  database: { url: string; authToken?: string; migrations: string }
+  database: {
+    adapter: DatabaseAdapter
+    url: string
+    authToken?: string
+    migrations: string
+  }
   auth: BetterAuthConfig
   storage: ResolvedStorageBuckets
   realtime?:
@@ -134,12 +154,22 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
   const resolvedEnv =
     env ?? validateEnv(options.env as EnvConfigInput | undefined)
 
+  const adapter = options.database?.adapter
+  if (!adapter) {
+    throw new Error('[bunderstack] database.adapter is required')
+  }
+
+  const defaultUrl =
+    adapter.dialect === 'sqlite' ? 'file:./data.db' : 'file:./data.pglite'
+
   return {
     database: {
+      adapter,
       url:
         platformSource['BUNDERSTACK_DATABASE_URL'] ??
         parsed.database?.url ??
-        resolvedEnv.DATABASE_URL,
+        resolvedEnv.DATABASE_URL ??
+        defaultUrl,
       authToken:
         platformSource['BUNDERSTACK_DATABASE_AUTH_TOKEN'] ??
         parsed.database?.authToken ??

package/src/database/adapter.ts

@@ -0,0 +1,26 @@
+import type { DbFor, Driver } from '../db'
+import type { AnyDb, Dialect } from '../dialect'
+
+export type DatabaseConnection = {
+  url: string
+  authToken?: string
+}
+
+export type DatabaseConnectOptions = { introspect: boolean }
+
+export type DatabaseConnectionResult<TSchema extends Record<string, unknown>> =
+  {
+    db: DbFor<TSchema>
+    close?: () => void | Promise<void>
+  }
+
+export type DatabaseAdapter = {
+  readonly dialect: Dialect
+  readonly driver: Driver
+  connect<TSchema extends Record<string, unknown>>(
+    schema: TSchema,
+    connection: DatabaseConnection,
+    options: DatabaseConnectOptions,
+  ): Promise<DatabaseConnectionResult<TSchema>>
+  migrate(db: AnyDb, migrationsFolder: string): Promise<void>
+}

package/src/database/bun-sql.ts

@@ -0,0 +1,23 @@
+import { drizzle } from 'drizzle-orm/bun-sql'
+import { migrate } from 'drizzle-orm/bun-sql/migrator'
+
+import type { DatabaseAdapter } from './adapter'
+
+export function bunSql(): DatabaseAdapter {
+  return {
+    dialect: 'pg',
+    driver: 'bun-sql',
+    async connect(schema, { url }, { introspect }) {
+      if (introspect) return { db: drizzle.mock({ schema }) as never }
+
+      if (!url.startsWith('postgres://') && !url.startsWith('postgresql://')) {
+        throw new Error('[bunderstack] bunSql adapter requires a Postgres URL')
+      }
+      const db = drizzle(url, { schema })
+      return { db: db as never, close: () => db.$client.close() }
+    },
+    async migrate(db, migrationsFolder) {
+      await migrate(db as never, { migrationsFolder })
+    },
+  }
+}

package/src/database/libsql.ts

@@ -0,0 +1,28 @@
+import { drizzle } from 'drizzle-orm/libsql'
+import { migrate } from 'drizzle-orm/libsql/migrator'
+
+import type { DatabaseAdapter } from './adapter'
+
+export function libsql(): DatabaseAdapter {
+  return {
+    dialect: 'sqlite',
+    driver: 'libsql',
+    async connect(schema, connection, { introspect }) {
+      if (introspect) return { db: drizzle.mock({ schema }) as never }
+
+      if (
+        connection.url.startsWith('postgres://') ||
+        connection.url.startsWith('postgresql://')
+      ) {
+        throw new Error(
+          '[bunderstack] libsql adapter cannot connect to a Postgres URL',
+        )
+      }
+      const db = drizzle({ connection, schema })
+      return { db: db as never, close: () => db.$client.close() }
+    },
+    async migrate(db, migrationsFolder) {
+      await migrate(db as never, { migrationsFolder })
+    },
+  }
+}

package/src/database/pglite.ts

@@ -0,0 +1,33 @@
+import { drizzle } from 'drizzle-orm/pglite'
+import { migrate } from 'drizzle-orm/pglite/migrator'
+import { mkdir } from 'node:fs/promises'
+
+import type { DatabaseAdapter } from './adapter'
+
+const rawPath = (url: string) =>
+  url.startsWith('file:') ? url.slice('file:'.length) : url
+
+export function pglite(): DatabaseAdapter {
+  return {
+    dialect: 'pg',
+    driver: 'pglite',
+    async connect(schema, { url }, { introspect }) {
+      if (introspect) return { db: drizzle.mock({ schema }) as never }
+
+      if (url.startsWith('postgres://') || url.startsWith('postgresql://')) {
+        throw new Error(
+          '[bunderstack] pglite adapter cannot connect to a Postgres URL',
+        )
+      }
+      const raw = rawPath(url)
+      const dataDir = raw === ':memory:' ? 'memory://' : raw
+      if (!dataDir.startsWith('memory://'))
+        await mkdir(dataDir, { recursive: true })
+      const db = drizzle(dataDir, { schema })
+      return { db: db as never, close: () => db.$client.close() }
+    },
+    async migrate(db, migrationsFolder) {
+      await migrate(db as never, { migrationsFolder })
+    },
+  }
+}

package/src/database/postgres-js.ts

@@ -0,0 +1,33 @@
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { migrate } from 'drizzle-orm/postgres-js/migrator'
+
+import type {
+  DatabaseAdapter,
+  DatabaseConnection,
+  DatabaseConnectOptions,
+} from './adapter'
+
+export function postgresJs(): DatabaseAdapter {
+  return {
+    dialect: 'pg',
+    driver: 'postgres-js',
+    async connect<TSchema extends Record<string, unknown>>(
+      schema: TSchema,
+      { url }: DatabaseConnection,
+      { introspect }: DatabaseConnectOptions,
+    ) {
+      if (introspect) return { db: drizzle.mock({ schema }) as never }
+
+      if (!url.startsWith('postgres://') && !url.startsWith('postgresql://')) {
+        throw new Error(
+          '[bunderstack] postgresJs adapter requires a Postgres URL',
+        )
+      }
+      const db = drizzle<TSchema>({ connection: url, schema })
+      return { db: db as never, close: () => db.$client.end() }
+    },
+    async migrate(db, migrationsFolder) {
+      await migrate(db as never, { migrationsFolder })
+    },
+  }
+}

package/src/db.ts

@@ -1,11 +1,11 @@
-// src/db.ts — dialect/driver dispatch. Every driver module loads via dynamic
-// import so the driver packages stay optional peers; the ignore comments keep
-// bundlers (vite/nitro, webpack) from resolving them at build time.
 import type { LibSQLDatabase } from 'drizzle-orm/libsql'
 import type { PgDatabase, PgQueryResultHKT, PgTable } from 'drizzle-orm/pg-core'
 
-import { mkdir } from 'node:fs/promises'
-
+import type {
+  DatabaseAdapter,
+  DatabaseConnection,
+  DatabaseConnectionResult,
+} from './database/adapter'
 import type { Dialect } from './dialect'
 
 export type Driver = 'libsql' | 'pglite' | 'bun-sql' | 'postgres-js'
@@ -20,84 +20,42 @@ export type DbFor<TSchema extends Record<string, unknown>> = [
 const PG_SERVER_RE = /^postgres(ql)?:\/\//
 const LIBSQL_REMOTE_RE = /^(libsql|wss?|https?):\/\//
 
-/** Exported for testing the missing-package error wrapping in isolation. */
-export async function importDriver<T>(specifier: string, hint: string): Promise<T> {
-  try {
-    return (await import(
-      /* @vite-ignore */ /* webpackIgnore: true */ specifier
-    )) as T
-  } catch (cause) {
-    throw new Error(`[bunderstack] ${hint}`, { cause })
-  }
-}
-
-export async function createDb<TSchema extends Record<string, unknown>>(
-  schema: TSchema,
-  cfg: { url: string; authToken?: string; dialect: Dialect },
-): Promise<{ db: DbFor<TSchema>; driver: Driver }> {
-  if (cfg.dialect === 'sqlite') {
-    if (PG_SERVER_RE.test(cfg.url)) {
+export function validateDatabaseUrl(url: string, dialect: Dialect) {
+  if (dialect === 'sqlite') {
+    if (PG_SERVER_RE.test(url)) {
       throw new Error(
         '[bunderstack] DATABASE_URL is a Postgres URL but the schema uses sqliteTable. ' +
           'Define the schema with drizzle-orm/pg-core, or point DATABASE_URL at a SQLite database.',
       )
     }
-    const { drizzle } = await importDriver<typeof import('drizzle-orm/libsql')>(
-      'drizzle-orm/libsql',
-      'SQLite support requires @libsql/client, which is not installed.\n' +
-        '  Run `bun add @libsql/client`.',
-    )
-    const db = drizzle({
-      connection: { url: cfg.url, authToken: cfg.authToken },
-      schema,
-    })
-    return { db: db as unknown as DbFor<TSchema>, driver: 'libsql' }
-  }
-
-  if (LIBSQL_REMOTE_RE.test(cfg.url)) {
-    throw new Error(
-      '[bunderstack] DATABASE_URL looks like a libsql/Turso URL but the schema uses pgTable. ' +
-        'Set DATABASE_URL=postgres://… (or leave it unset for local PGlite).',
-    )
-  }
-
-  if (PG_SERVER_RE.test(cfg.url)) {
-    if (typeof Bun !== 'undefined') {
-      const { drizzle } = await import(
-        /* @vite-ignore */ /* webpackIgnore: true */ 'drizzle-orm/bun-sql'
+  } else if (dialect === 'pg') {
+    if (LIBSQL_REMOTE_RE.test(url)) {
+      throw new Error(
+        '[bunderstack] DATABASE_URL looks like a libsql/Turso URL but the schema uses pgTable. ' +
+          'Set DATABASE_URL=postgres://… (or leave it unset for local PGlite).',
       )
-      return {
-        db: drizzle(cfg.url, { schema }) as unknown as DbFor<TSchema>,
-        driver: 'bun-sql',
-      }
-    }
-    const { drizzle } = await importDriver<
-      typeof import('drizzle-orm/postgres-js')
-    >(
-      'drizzle-orm/postgres-js',
-      'Postgres on Node requires the `postgres` driver, which is not installed.\n' +
-        '  Run `npm install postgres`. (Under Bun the built-in Bun.sql is used instead.)',
-    )
-    return {
-      db: drizzle(cfg.url, { schema }) as unknown as DbFor<TSchema>,
-      driver: 'postgres-js',
     }
   }
+}
 
-  // Local PGlite: `file:<dir>`, a bare path, `:memory:`, or `memory://`.
-  const raw = cfg.url.startsWith('file:') ? cfg.url.slice('file:'.length) : cfg.url
-  const dataDir = raw === ':memory:' ? 'memory://' : raw
-  if (!dataDir.startsWith('memory://')) {
-    await mkdir(dataDir, { recursive: true })
+export async function createDb<TSchema extends Record<string, unknown>>(
+  schema: TSchema,
+  cfg: DatabaseConnection & {
+    adapter: DatabaseAdapter
+    dialect: Dialect
+    introspect?: boolean
+  },
+): Promise<DatabaseConnectionResult<TSchema> & { driver: Driver }> {
+  if (cfg.adapter.dialect !== cfg.dialect) {
+    throw new Error(
+      `[bunderstack] database adapter dialect ${cfg.adapter.dialect} does not match ${cfg.dialect} schema`,
+    )
   }
-  const { drizzle } = await importDriver<typeof import('drizzle-orm/pglite')>(
-    'drizzle-orm/pglite',
-    'Local Postgres development requires PGlite, which is not installed.\n' +
-      '  Run `bun add -d @electric-sql/pglite` — bunderstack runs an embedded Postgres in ./data.pglite.\n' +
-      '  In production set DATABASE_URL=postgres://… (PGlite is not needed there).',
+  if (!cfg.introspect) validateDatabaseUrl(cfg.url, cfg.dialect)
+  const result = await cfg.adapter.connect(
+    schema,
+    { url: cfg.url, authToken: cfg.authToken },
+    { introspect: cfg.introspect ?? false },
   )
-  return {
-    db: drizzle(dataDir, { schema }) as unknown as DbFor<TSchema>,
-    driver: 'pglite',
-  }
+  return { ...result, driver: cfg.adapter.driver }
 }

package/src/email/smtp.ts

@@ -0,0 +1,45 @@
+import nodemailer from 'nodemailer'
+
+import type { EmailAdapter, EmailMessage } from '../email'
+
+type SmtpTransport = {
+  sendMail(message: Record<string, unknown>): Promise<{ messageId?: string }>
+}
+
+export function createSmtpAdapter(
+  options: { url: string },
+  createTransport: (url: string) => SmtpTransport = (url) =>
+    nodemailer.createTransport(url) as SmtpTransport,
+): EmailAdapter {
+  const toArray = (v: string | string[] | undefined) =>
+    v === undefined ? undefined : Array.isArray(v) ? v : [v]
+
+  let transportPromise: Promise<{
+    sendMail(opts: Record<string, unknown>): Promise<{ messageId?: string }>
+  }> | null = null
+
+  const getTransport = () => {
+    transportPromise ??= Promise.resolve(createTransport(options.url))
+    return transportPromise
+  }
+
+  return {
+    async send(msg) {
+      const transport = await getTransport()
+      const info = await transport.sendMail({
+        from: msg.from,
+        to: toArray(msg.to)!.join(', '),
+        subject: msg.subject,
+        html: msg.html,
+        text: msg.text,
+        replyTo: msg.replyTo,
+        cc: toArray(msg.cc)?.join(', '),
+        bcc: toArray(msg.bcc)?.join(', '),
+      })
+      return { id: info.messageId }
+    },
+  }
+}
+
+export const smtp = (options: { url: string }): EmailAdapter =>
+  createSmtpAdapter(options)