bunderstack 0.1.0 → 0.3.0

package/README.md

@@ -27,6 +27,39 @@ Bun.serve({ fetch: app.handler })
 Full documentation and examples:
 [github.com/kirill-dev-pro/bunderstack](https://github.com/kirill-dev-pro/bunderstack)
 
+## 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.
+
+### 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`:
+
+```ts
+process.env.BUNDERSTACK_INTROSPECT = '1'
+const { app } = await import('./src/bunderstack')
+console.log(JSON.stringify(app.manifest))
+// { dialect, tables, defaultBucket, buckets, realtime, env: { server, client } }
+```
+
 ## 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.1.0",
+  "version": "0.3.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,8 +33,11 @@
   "exports": {
     ".": "./src/index.ts",
     "./access": "./src/access.ts",
+    "./provision": "./src/provision.ts",
     "./schema": "./src/schema-export.ts",
+    "./schema/pg": "./src/schema-export-pg.ts",
     "./typeid": "./src/typeid.ts",
+    "./typeid/pg": "./src/typeid-pg.ts",
     "./env": "./src/env.ts",
     "./trpc": "./src/trpc.ts"
   },
@@ -45,25 +48,42 @@
     "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "@libsql/client": "^0.14.0",
     "@trpc/server": "^11.0.0",
     "better-auth": "^1.0.0",
-    "drizzle-orm": "^0.45.0",
     "hono": "^4.0.0",
     "superjson": "^2.2.0",
     "zod": "^4.4.3"
   },
+  "devDependencies": {
+    "@electric-sql/pglite": ">=0.3.0",
+    "@libsql/client": ">=0.14.0",
+    "drizzle-kit": "^0.30.0",
+    "drizzle-orm": "^0.45.0"
+  },
   "peerDependencies": {
+    "@electric-sql/pglite": ">=0.3.0",
+    "@libsql/client": ">=0.14.0",
     "drizzle-kit": "^0.30.0",
+    "drizzle-orm": "^0.45.0",
     "nodemailer": "^6",
+    "postgres": ">=3.4.0",
     "typescript": "^5"
   },
   "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    },
     "drizzle-kit": {
       "optional": true
     },
     "nodemailer": {
       "optional": true
+    },
+    "postgres": {
+      "optional": true
     }
   }
 }

package/src/auth.ts

@@ -1,20 +1,18 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 // src/auth.ts
 import { betterAuth } from 'better-auth'
 import { drizzleAdapter } from 'better-auth/adapters/drizzle'
 
 import type { BetterAuthConfig } from './config'
 import type { AuthSessionResolver } from './access'
+import type { AnyDb, Dialect } from './dialect'
 import type { EmailFacade } from './email'
 
-export function createAuth(
-  db: LibSQLDatabase<Record<string, unknown>>,
-  cfg: BetterAuthConfig,
-) {
+export function createAuth(db: AnyDb, cfg: BetterAuthConfig, dialect: Dialect) {
   return betterAuth({
     ...cfg,
-    database: drizzleAdapter(db, { provider: 'sqlite' }),
+    database: drizzleAdapter(db as Parameters<typeof drizzleAdapter>[0], {
+      provider: dialect === 'pg' ? 'pg' : 'sqlite',
+    }),
   })
 }
 

package/src/config.ts

@@ -24,7 +24,11 @@ export const BunderstackOptionsSchema = z.object({
   schema: z.record(z.string(), z.unknown()),
   access: z.record(z.string(), z.any()).optional(),
   database: z
-    .object({ url: z.string().optional(), authToken: z.string().optional() })
+    .object({
+      url: z.string().optional(),
+      authToken: z.string().optional(),
+      migrations: z.string().optional(),
+    })
     .optional(),
   auth: z.record(z.string(), z.unknown()).optional(),
   // Loose: bucket access/scope hold functions that can't survive strict zod
@@ -99,7 +103,7 @@ export type BunderstackConfig<
 }
 
 export type ResolvedConfig = {
-  database: { url: string; authToken?: string }
+  database: { url: string; authToken?: string; migrations: string }
   auth: BetterAuthConfig
   storage: ResolvedStorageBuckets
   realtime?:
@@ -114,6 +118,12 @@ export type ResolvedConfig = {
 export function resolveConfig<TSchema extends Record<string, unknown>>(
   options: BunderstackConfig<TSchema>,
   env?: BaseEnv,
+  // Platform-injected overrides (Bunderhost & co.) beat code-level config so
+  // apps with hardcoded local urls deploy unchanged.
+  platformSource: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
 ): ResolvedConfig {
   const parsed = BunderstackOptionsSchema.parse(options)
   // Self-validate when the caller didn't pass a pre-validated env, so
@@ -123,8 +133,15 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
 
   return {
     database: {
-      url: parsed.database?.url ?? resolvedEnv.DATABASE_URL,
-      authToken: parsed.database?.authToken ?? resolvedEnv.DATABASE_AUTH_TOKEN,
+      url:
+        platformSource['BUNDERSTACK_DATABASE_URL'] ??
+        parsed.database?.url ??
+        resolvedEnv.DATABASE_URL,
+      authToken:
+        platformSource['BUNDERSTACK_DATABASE_AUTH_TOKEN'] ??
+        parsed.database?.authToken ??
+        resolvedEnv.DATABASE_AUTH_TOKEN,
+      migrations: parsed.database?.migrations ?? './migrations',
     },
     auth: (() => {
       const authInput = options.auth ?? {}
@@ -133,7 +150,7 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
         secret: authInput.secret ?? resolvedEnv.AUTH_SECRET,
       }
     })(),
-    storage: resolveBuckets(options.storage),
+    storage: resolveBuckets(options.storage, platformSource),
     realtime: parsed.realtime,
   }
 }

package/src/crud.ts

@@ -1,8 +1,7 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import { eq, getTableColumns, getTableName, isTable } from 'drizzle-orm'
 import { Hono } from 'hono'
 
+import type { AnyDb } from './dialect'
 import type { RealtimeBroker } from './realtime/index'
 
 import {
@@ -61,7 +60,7 @@ async function enforce(
 
 export function buildCrudRouter<TSchema extends Record<string, unknown>>(
   schema: TSchema,
-  db: LibSQLDatabase<TSchema>,
+  db: AnyDb,
   options: CrudRouterOptions,
 ): Hono {
   const router = new Hono()

package/src/db.ts

@@ -1,10 +1,103 @@
-import { createClient } from '@libsql/client'
-import { drizzle } from 'drizzle-orm/libsql'
+// 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'
 
-export function createDb<TSchema extends Record<string, unknown>>(
+import { mkdir } from 'node:fs/promises'
+
+import type { Dialect } from './dialect'
+
+export type Driver = 'libsql' | 'pglite' | 'bun-sql' | 'postgres-js'
+
+/** Per-dialect public db type, computed from the schema's table brands. */
+export type DbFor<TSchema extends Record<string, unknown>> = [
+  Extract<TSchema[keyof TSchema], PgTable>,
+] extends [never]
+  ? LibSQLDatabase<TSchema>
+  : PgDatabase<PgQueryResultHKT, TSchema>
+
+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 },
-) {
-  const client = createClient({ url: cfg.url, authToken: cfg.authToken })
-  return drizzle(client, { schema })
+  cfg: { url: string; authToken?: string; dialect: Dialect },
+): Promise<{ db: DbFor<TSchema>; driver: Driver }> {
+  if (cfg.dialect === 'sqlite') {
+    if (PG_SERVER_RE.test(cfg.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'
+      )
+      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 })
+  }
+  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).',
+  )
+  return {
+    db: drizzle(dataDir, { schema }) as unknown as DbFor<TSchema>,
+    driver: 'pglite',
+  }
 }

package/src/dialect.ts

@@ -0,0 +1,38 @@
+// src/dialect.ts — schema-driven dialect detection. Imports only dialect-core
+// drizzle entrypoints (no drivers), safe in every module graph.
+import { is } from 'drizzle-orm'
+import { PgTable } from 'drizzle-orm/pg-core'
+import { SQLiteTable } from 'drizzle-orm/sqlite-core'
+
+export type Dialect = 'sqlite' | 'pg'
+
+/**
+ * Minimal structural view of a drizzle db shared by both dialects. Internal
+ * modules run dynamic tables (Record<string, unknown> schemas) where drizzle's
+ * generics add no safety, so they accept this instead of a per-dialect union.
+ * The public surface (`app.db`, tRPC ctx) keeps full per-dialect typing via
+ * `DbFor` in db.ts.
+ */
+export type AnyDb = {
+  select: (...args: any[]) => any
+  insert: (...args: any[]) => any
+  update: (...args: any[]) => any
+  delete: (...args: any[]) => any
+}
+
+/** Classify a schema by its table brands. Mixed dialects are a config error. */
+export function detectDialect(schema: Record<string, unknown>): Dialect {
+  let pgKey: string | undefined
+  let sqliteKey: string | undefined
+  for (const [key, value] of Object.entries(schema)) {
+    if (is(value, PgTable)) pgKey ??= key
+    else if (is(value, SQLiteTable)) sqliteKey ??= key
+  }
+  if (pgKey !== undefined && sqliteKey !== undefined) {
+    throw new Error(
+      `[bunderstack] schema mixes dialects: "${pgKey}" is a Postgres table while "${sqliteKey}" is a SQLite table. ` +
+        'Define every table with the same dialect (drizzle-orm/pg-core or drizzle-orm/sqlite-core).',
+    )
+  }
+  return pgKey !== undefined ? 'pg' : 'sqlite'
+}

package/src/env.ts

@@ -49,6 +49,8 @@ export type ValidateEnvOptions = {
   emailProvider?: string
   /** Value source; defaults to process.env. Tests pass this explicitly. */
   source?: Record<string, string | undefined>
+  /** Dialect-aware DATABASE_URL fallback; createBunderstack passes it. */
+  defaultDatabaseUrl?: string
 }
 
 const DEV_AUTH_SECRET = 'dev-secret-change-in-prod'
@@ -96,7 +98,8 @@ export function validateEnv<TEnv extends EnvConfigInput | undefined>(
 
   const base: BaseEnv = {
     NODE_ENV: source.NODE_ENV,
-    DATABASE_URL: source.DATABASE_URL ?? 'file:./data.db',
+    DATABASE_URL:
+      source.DATABASE_URL ?? options.defaultDatabaseUrl ?? 'file:./data.db',
     DATABASE_AUTH_TOKEN: source.DATABASE_AUTH_TOKEN,
     AUTH_SECRET: source.AUTH_SECRET ?? DEV_AUTH_SECRET,
     REDIS_URL: source.REDIS_URL,
@@ -117,7 +120,10 @@ export function validateEnv<TEnv extends EnvConfigInput | undefined>(
   validateSection(envConfig?.server, 'server', source, issues, userVars)
   validateSection(envConfig?.client, 'client', source, issues, userVars)
 
-  if (issues.length > 0) throw new BunderstackEnvError(issues)
+  // Introspection (Bunderhost builder) imports the app declaration to read
+  // its manifest; missing user env must not kill the boot there.
+  const lenient = source.BUNDERSTACK_INTROSPECT === '1'
+  if (issues.length > 0 && !lenient) throw new BunderstackEnvError(issues)
   return { ...base, ...userVars } as ValidatedEnv<TEnv>
 }
 

package/src/idempotency.ts

@@ -1,9 +1,9 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import { and, eq, lt } from 'drizzle-orm'
 import { createHash } from 'node:crypto'
 
-import { bunderstackIdempotency } from './internal-tables'
+import type { AnyDb } from './dialect'
+
+import { idempotencyTableFor } from './internal-tables'
 
 export type IdempotencyConfig = {
   ttlMs?: number
@@ -21,34 +21,28 @@ export type IdempotencyLookup =
   | { type: 'proceed' }
 
 export async function lookupIdempotency(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   tableName: string,
   key: string,
   body: string,
   config: IdempotencyConfig,
 ): Promise<IdempotencyLookup> {
+  const t = idempotencyTableFor(db)
   const now = Date.now()
 
   // TTL sweep: drop expired rows before reading.
-  await db
-    .delete(bunderstackIdempotency)
-    .where(lt(bunderstackIdempotency.expiresAt, now))
+  await db.delete(t).where(lt(t.expiresAt, now))
 
   const bodyHash = hashBody(body)
   const rows = await db
     .select({
-      bodyHash: bunderstackIdempotency.bodyHash,
-      status: bunderstackIdempotency.status,
-      response: bunderstackIdempotency.response,
-      expiresAt: bunderstackIdempotency.expiresAt,
+      bodyHash: t.bodyHash,
+      status: t.status,
+      response: t.response,
+      expiresAt: t.expiresAt,
     })
-    .from(bunderstackIdempotency)
-    .where(
-      and(
-        eq(bunderstackIdempotency.key, key),
-        eq(bunderstackIdempotency.tableName, tableName),
-      ),
-    )
+    .from(t)
+    .where(and(eq(t.key, key), eq(t.tableName, tableName)))
     .limit(1)
 
   const row = rows[0]
@@ -64,7 +58,7 @@ export async function lookupIdempotency(
 }
 
 export async function storeIdempotency(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   tableName: string,
   key: string,
   body: string,
@@ -72,13 +66,14 @@ export async function storeIdempotency(
   response: unknown,
   config: IdempotencyConfig,
 ): Promise<void> {
+  const t = idempotencyTableFor(db)
   const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS
   const expiresAt = Date.now() + ttlMs
   const bodyHash = hashBody(body)
   const responseText = JSON.stringify(response)
 
   await db
-    .insert(bunderstackIdempotency)
+    .insert(t)
     .values({
       key,
       tableName,
@@ -88,7 +83,7 @@ export async function storeIdempotency(
       expiresAt,
     })
     .onConflictDoUpdate({
-      target: [bunderstackIdempotency.key, bunderstackIdempotency.tableName],
+      target: [t.key, t.tableName],
       set: { bodyHash, status, response: responseText, expiresAt },
     })
 }