bunderstack 0.16.0 → 0.17.0-beta.2

package/src/crud-operations.ts

@@ -0,0 +1,478 @@
+import {
+  eq,
+  getTableColumns,
+  getTableName,
+  isTable,
+  type Table,
+} from 'drizzle-orm'
+
+import type { AnyDb } from './dialect'
+import type { RealtimeFacade } from './realtime/facade'
+
+import {
+  checkAccess,
+  rowMatchesScope,
+  sanitizeWriteBody,
+  stampScope,
+  tableEntryForName,
+  type AccessUser,
+  type ResolvedAccess,
+  type ScopeMap,
+  type ScopeResolver,
+} from './access'
+import {
+  BunderstackError,
+  ErrorCode,
+  ListQueryError,
+  type BunderstackErrorCode,
+  type ErrorCodeValue,
+} from './errors'
+import {
+  lookupIdempotency,
+  resolveIdempotencyConfig,
+  storeIdempotency,
+  type IdempotencyConfig,
+} from './idempotency'
+import {
+  executeList,
+  resolveListParams,
+  type ListParamsInput,
+  type ListResult,
+} from './list-query'
+import { buildScopeWhere } from './scope'
+
+export interface CrudExecutionContext {
+  request: Request
+  user: AccessUser | null
+  session: { activeOrganizationId: string | null }
+}
+
+function errorCodeForStatus(status: number): BunderstackErrorCode {
+  if (status === 401) return 'UNAUTHORIZED'
+  if (status === 403) return 'FORBIDDEN'
+  if (status === 404) return 'NOT_FOUND'
+  if (status === 409) return 'CONFLICT'
+  if (status === 413) return 'PAYLOAD_TOO_LARGE'
+  if (status === 429) return 'TOO_MANY_REQUESTS'
+  return 'BAD_REQUEST'
+}
+
+export class CrudOperationError extends BunderstackError {
+  constructor(
+    status: number,
+    readonly legacyCode: ErrorCodeValue,
+    message: string,
+    details?: unknown,
+  ) {
+    const code = errorCodeForStatus(status)
+    super(
+      code,
+      message,
+      legacyCode === code
+        ? details
+        : {
+            code: legacyCode,
+            ...(details === undefined ? {} : { details }),
+          },
+    )
+    this.name = 'CrudOperationError'
+  }
+}
+
+export type CrudOperationsDeps<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  schema: TSchema
+  db: AnyDb
+  access: ResolvedAccess
+  idempotency?: boolean | IdempotencyConfig
+  realtime?: RealtimeFacade<TSchema>
+}
+
+export type CreateResult =
+  | { type: 'created'; status: 201; record: Record<string, unknown> }
+  | {
+      type: 'replay'
+      status: number
+      body: string
+      record: Record<string, unknown>
+    }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isUniqueConstraintError(error: unknown): boolean {
+  const seen = new Set<unknown>()
+  let current = error
+
+  while (isRecord(current) && !seen.has(current)) {
+    seen.add(current)
+    const code = current['code']
+    if (
+      code === '23505' ||
+      code === 'SQLITE_CONSTRAINT_UNIQUE' ||
+      code === 'SQLITE_CONSTRAINT_PRIMARYKEY'
+    ) {
+      return true
+    }
+
+    const message = current['message']
+    if (
+      typeof message === 'string' &&
+      (/duplicate key value violates unique constraint/i.test(message) ||
+        /unique constraint failed/i.test(message))
+    ) {
+      return true
+    }
+
+    current = current['cause']
+  }
+
+  return false
+}
+
+function coerceId(rawId: string | number): string | number {
+  if (typeof rawId === 'number') return rawId
+  return isNaN(Number(rawId)) ? rawId : Number(rawId)
+}
+
+export function createCrudOperations<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+>(deps: CrudOperationsDeps<TSchema>) {
+  const { schema, db, access, realtime } = deps
+  const idempotency = resolveIdempotencyConfig(deps.idempotency)
+
+  const scopeFor = (
+    resolver: ScopeResolver | undefined,
+    ctx: {
+      user: AccessUser | null
+      session: { activeOrganizationId: string | null }
+      request: Request
+      row?: Record<string, unknown>
+      body?: Record<string, unknown>
+    },
+  ): ScopeMap | undefined => (resolver ? resolver(ctx) : undefined)
+
+  function resolveTable(tableName: string) {
+    const table = Object.values(schema).find(
+      (t) => isTable(t) && getTableName(t) === tableName,
+    ) as Table | undefined
+    if (!table) {
+      throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+    }
+    const tableAccess = tableEntryForName(access, tableName)
+    if (!tableAccess || !tableAccess.enabled) {
+      throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+    }
+    const idCol = getTableColumns(table)['id']
+    if (!idCol) {
+      throw new CrudOperationError(
+        400,
+        ErrorCode.BAD_REQUEST,
+        `Table ${tableName} has no id column`,
+      )
+    }
+    return { table, tableAccess, idCol }
+  }
+
+  return {
+    async list(
+      tableName: string,
+      params: ListParamsInput | undefined,
+      ctx: CrudExecutionContext,
+    ): Promise<ListResult<Record<string, unknown>>> {
+      const { table, tableAccess, idCol } = resolveTable(tableName)
+
+      const denied = await checkAccess(
+        tableAccess.list,
+        ctx,
+        tableAccess.ownerColumn,
+      )
+      if (!denied.allowed) {
+        throw new CrudOperationError(
+          denied.status === 401 ? 401 : 403,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+        )
+      }
+
+      try {
+        const resolved = resolveListParams(params ?? {}, tableAccess)
+        const scope = scopeFor(tableAccess.readScope, ctx)
+        const scopeWhere = scope ? buildScopeWhere(table, scope) : undefined
+        return await executeList(
+          db,
+          table,
+          tableAccess,
+          resolved,
+          idCol,
+          scopeWhere,
+        )
+      } catch (err) {
+        if (err instanceof ListQueryError) {
+          throw new CrudOperationError(400, err.code, err.message, err.details)
+        }
+        throw err
+      }
+    },
+
+    async get(
+      tableName: string,
+      rawId: string | number,
+      ctx: CrudExecutionContext,
+    ): Promise<Record<string, unknown>> {
+      const { table, tableAccess, idCol } = resolveTable(tableName)
+      const id = coerceId(rawId)
+
+      const rows = await db
+        .select()
+        .from(table)
+        .where(eq(idCol, id))
+      if (!rows[0]) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+      const row = rows[0] as Record<string, unknown>
+
+      const denied = await checkAccess(
+        tableAccess.get,
+        { ...ctx, row },
+        tableAccess.ownerColumn,
+      )
+      if (!denied.allowed) {
+        throw new CrudOperationError(
+          denied.status === 401 ? 401 : 403,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+        )
+      }
+
+      const scope = scopeFor(tableAccess.readScope, ctx)
+      if (scope && !rowMatchesScope(row, scope)) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+
+      return row
+    },
+
+    async create(
+      tableName: string,
+      body: unknown,
+      rawBody: string | undefined,
+      idempotencyKey: string | undefined,
+      ctx: CrudExecutionContext,
+    ): Promise<CreateResult> {
+      const { table, tableAccess } = resolveTable(tableName)
+
+      const denied = await checkAccess(
+        tableAccess.create,
+        ctx,
+        tableAccess.ownerColumn,
+      )
+      if (!denied.allowed) {
+        throw new CrudOperationError(
+          denied.status === 401 ? 401 : 403,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+        )
+      }
+
+      if (!isRecord(body)) {
+        throw new CrudOperationError(
+          400,
+          ErrorCode.BAD_REQUEST,
+          'Invalid JSON body',
+        )
+      }
+
+      const trimmedKey = idempotencyKey?.trim()
+      const effectiveRawBody = rawBody ?? JSON.stringify(body)
+
+      if (idempotency && trimmedKey) {
+        const lookup = await lookupIdempotency(
+          db,
+          tableName,
+          trimmedKey,
+          effectiveRawBody,
+          idempotency,
+        )
+        if (lookup.type === 'conflict') {
+          throw new CrudOperationError(
+            409,
+            ErrorCode.IDEMPOTENCY_CONFLICT,
+            'Idempotency key reused with different body',
+          )
+        }
+        if (lookup.type === 'replay') {
+          return {
+            type: 'replay',
+            status: lookup.status,
+            body: lookup.response,
+            record: JSON.parse(lookup.response) as Record<string, unknown>,
+          }
+        }
+      }
+
+      const values = sanitizeWriteBody(
+        body,
+        tableAccess,
+        'create',
+        ctx.user?.id ?? null,
+      )
+
+      const scope = scopeFor(tableAccess.writeScope, { ...ctx, body })
+      const stamped = scope ? stampScope(values, scope) : values
+
+      let rows: Record<string, unknown>[]
+      try {
+        rows = await db.insert(table).values(stamped).returning()
+      } catch (error) {
+        if (isUniqueConstraintError(error)) {
+          throw new CrudOperationError(
+            409,
+            ErrorCode.CONFLICT,
+            'Record already exists',
+          )
+        }
+        throw error
+      }
+      const created = rows[0] as Record<string, unknown>
+      void realtime?.publish(table as never, 'create', created as never)
+
+      if (idempotency && trimmedKey) {
+        await storeIdempotency(
+          db,
+          tableName,
+          trimmedKey,
+          effectiveRawBody,
+          201,
+          created,
+          idempotency,
+        )
+      }
+
+      return {
+        type: 'created',
+        status: 201,
+        record: created,
+      }
+    },
+
+    async update(
+      tableName: string,
+      rawId: string | number,
+      body: unknown,
+      ctx: CrudExecutionContext,
+    ): Promise<Record<string, unknown>> {
+      const { table, tableAccess, idCol } = resolveTable(tableName)
+      const id = coerceId(rawId)
+
+      const existing = await db
+        .select()
+        .from(table)
+        .where(eq(idCol, id))
+      if (!existing[0]) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+      const existingRow = existing[0] as Record<string, unknown>
+
+      const readScope = scopeFor(tableAccess.readScope, ctx)
+      if (readScope && !rowMatchesScope(existingRow, readScope)) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+
+      const denied = await checkAccess(
+        tableAccess.update,
+        { ...ctx, row: existingRow },
+        tableAccess.ownerColumn,
+      )
+      if (!denied.allowed) {
+        throw new CrudOperationError(
+          denied.status === 401 ? 401 : 403,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+        )
+      }
+
+      if (!isRecord(body)) {
+        throw new CrudOperationError(
+          400,
+          ErrorCode.BAD_REQUEST,
+          'Invalid JSON body',
+        )
+      }
+
+      const values = sanitizeWriteBody(
+        body,
+        tableAccess,
+        'update',
+        ctx.user?.id ?? null,
+      )
+
+      if (Object.keys(values).length === 0) {
+        throw new CrudOperationError(
+          400,
+          ErrorCode.BAD_REQUEST,
+          'No writable fields to update',
+        )
+      }
+
+      const writeScope = scopeFor(tableAccess.writeScope, { ...ctx, body })
+      const stamped = writeScope ? stampScope(values, writeScope) : values
+
+      const rows = await db
+        .update(table)
+        .set(stamped)
+        .where(eq(idCol, id))
+        .returning()
+
+      if (!rows[0]) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+      const updated = rows[0] as Record<string, unknown>
+      void realtime?.publish(table as never, 'update', updated as never)
+      return updated
+    },
+
+    async delete(
+      tableName: string,
+      rawId: string | number,
+      ctx: CrudExecutionContext,
+    ): Promise<void> {
+      const { table, tableAccess, idCol } = resolveTable(tableName)
+      const id = coerceId(rawId)
+
+      const existing = await db
+        .select()
+        .from(table)
+        .where(eq(idCol, id))
+      if (!existing[0]) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+      const existingRow = existing[0] as Record<string, unknown>
+
+      const readScope = scopeFor(tableAccess.readScope, ctx)
+      if (readScope && !rowMatchesScope(existingRow, readScope)) {
+        throw new CrudOperationError(404, ErrorCode.NOT_FOUND, 'Not found')
+      }
+
+      const denied = await checkAccess(
+        tableAccess.delete,
+        { ...ctx, row: existingRow },
+        tableAccess.ownerColumn,
+      )
+      if (!denied.allowed) {
+        throw new CrudOperationError(
+          denied.status === 401 ? 401 : 403,
+          ErrorCode.FORBIDDEN,
+          'Forbidden',
+        )
+      }
+
+      await db.delete(table).where(eq(idCol, id))
+      void realtime?.publish(table as never, 'delete', existingRow as never)
+    },
+  }
+}
+
+export type CrudOperations = ReturnType<typeof createCrudOperations>

package/src/dialect.ts

@@ -10,7 +10,7 @@ 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
+ * The public surface (`app.db`, API context) keeps full per-dialect typing via
  * `DbFor` in db.ts.
  */
 export type AnyDb = {

package/src/email/smtp.ts

@@ -1,6 +1,6 @@
 import nodemailer from 'nodemailer'
 
-import type { EmailAdapter, EmailMessage } from '../email'
+import type { EmailAdapter } from '../email'
 
 type SmtpTransport = {
   sendMail(message: Record<string, unknown>): Promise<{ messageId?: string }>

package/src/env.ts

@@ -1,11 +1,16 @@
-// src/env.ts — env validation. Browser-safe: imports zod only.
-import { z, type ZodType } from 'zod'
+// src/env.ts — env validation. Browser-safe: type-only Standard Schema import.
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+import {
+  StandardSchemaValidationError,
+  validateStandardSchema,
+} from './standard-schema'
 
 export const CLIENT_PREFIX = 'PUBLIC_' as const
 
 export type EnvConfigInput = {
-  server?: Record<string, ZodType>
-  client?: Record<string, ZodType>
+  server?: Record<string, StandardSchemaV1>
+  client?: Record<string, StandardSchemaV1>
   /** Explicit value source for client vars (e.g. Vite's import.meta.env). */
   runtimeEnv?: Record<string, unknown>
 }
@@ -27,8 +32,8 @@ export type BaseEnv = {
 }
 
 type InferVars<T> =
-  T extends Record<string, ZodType>
-    ? { [K in keyof T]: z.output<T[K]> }
+  T extends Record<string, StandardSchemaV1>
+    ? { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]> }
     : unknown
 
 // Non-distributive so `ValidatedEnv<undefined>` is BaseEnv, not `never`.
@@ -62,7 +67,7 @@ export type ValidateEnvOptions = {
 const DEV_AUTH_SECRET = 'dev-secret-change-in-prod'
 
 function validateSection(
-  section: Record<string, ZodType> | undefined,
+  section: Record<string, StandardSchemaV1> | undefined,
   kind: 'server' | 'client',
   source: Record<string, unknown>,
   issues: string[],
@@ -82,12 +87,13 @@ function validateSection(
       )
       continue
     }
-    const result = schema.safeParse(source[key])
-    if (result.success) {
-      out[key] = result.data
-    } else {
-      for (const issue of result.error.issues) {
-        issues.push(`${key}: ${issue.message}`)
+    try {
+      out[key] = validateStandardSchema(schema, source[key], 'env')
+    } catch (error) {
+      if (!(error instanceof StandardSchemaValidationError)) throw error
+      for (const issue of error.issues) {
+        const path = issue.path.map(String).join('.')
+        issues.push(`${key}${path ? `.${path}` : ''}: ${issue.message}`)
       }
     }
   }

package/src/errors.ts

@@ -1,46 +1,118 @@
-import type { Context } from 'hono'
-import type { ContentfulStatusCode } from 'hono/utils/http-status'
+import {
+  COMMON_ERROR_STATUS_MAP,
+  ORPCError,
+  os,
+  type ErrorMap,
+} from '@orpc/server'
+import * as v from 'valibot'
 
+import { StandardSchemaValidationError } from './standard-schema'
+
+/**
+ * Every code we raise is one oRPC already knows, so handlers derive the HTTP
+ * status from `COMMON_ERROR_STATUS_MAP` on their own and clients can use the
+ * standard `isDefinedError` helpers. Do not add a code oRPC has no status for —
+ * it would silently answer 500.
+ */
+export const BUNDERSTACK_ERROR_CODES = [
+  'BAD_REQUEST',
+  'UNAUTHORIZED',
+  'FORBIDDEN',
+  'NOT_FOUND',
+  'CONFLICT',
+  'PAYLOAD_TOO_LARGE',
+  'TOO_MANY_REQUESTS',
+] as const satisfies readonly (keyof typeof COMMON_ERROR_STATUS_MAP)[]
+
+export type BunderstackErrorCode = (typeof BUNDERSTACK_ERROR_CODES)[number]
+
+function errorDataSchema<const TCode extends BunderstackErrorCode>(
+  code: TCode,
+) {
+  return v.strictObject({
+    code: v.literal(code),
+    details: v.optional(v.unknown()),
+  })
+}
+
+export const BUNDERSTACK_ERRORS = {
+  BAD_REQUEST: { data: errorDataSchema('BAD_REQUEST') },
+  UNAUTHORIZED: { data: errorDataSchema('UNAUTHORIZED') },
+  FORBIDDEN: { data: errorDataSchema('FORBIDDEN') },
+  NOT_FOUND: { data: errorDataSchema('NOT_FOUND') },
+  CONFLICT: { data: errorDataSchema('CONFLICT') },
+  PAYLOAD_TOO_LARGE: { data: errorDataSchema('PAYLOAD_TOO_LARGE') },
+  TOO_MANY_REQUESTS: { data: errorDataSchema('TOO_MANY_REQUESTS') },
+} as const satisfies ErrorMap
+
+export class BunderstackError extends Error {
+  readonly status: number
+
+  constructor(
+    readonly code: BunderstackErrorCode,
+    message: string,
+    readonly details?: unknown,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+    this.name = 'BunderstackError'
+    this.status = COMMON_ERROR_STATUS_MAP[code]
+  }
+}
+
+export const mapBunderstackErrors = os
+  .errors(BUNDERSTACK_ERRORS)
+  .middleware(async ({ next }) => {
+    try {
+      return await next()
+    } catch (error) {
+      const mapped =
+        error instanceof StandardSchemaValidationError
+          ? new BunderstackError(
+              'BAD_REQUEST',
+              error.message,
+              error.issues,
+              { cause: error },
+            )
+          : error
+      if (!(mapped instanceof BunderstackError)) throw error
+
+      throw new ORPCError(mapped.code, {
+        message: mapped.message,
+        data:
+          mapped.details === undefined
+            ? { code: mapped.code }
+            : { code: mapped.code, details: mapped.details },
+        cause: mapped,
+      })
+    }
+  })
+
+/**
+ * Sub-codes carried in `data.details.code` when the oRPC code alone loses
+ * information the client may want to branch on. Codes that duplicate an oRPC
+ * code are suppressed as redundant, see {@link CrudOperationError}.
+ */
 export const ErrorCode = {
-  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  BAD_REQUEST: 'BAD_REQUEST',
   FORBIDDEN: 'FORBIDDEN',
   NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
   INVALID_CURSOR: 'INVALID_CURSOR',
-  RATE_LIMITED: 'RATE_LIMITED',
+  TOO_MANY_REQUESTS: 'TOO_MANY_REQUESTS',
   IDEMPOTENCY_REPLAY: 'IDEMPOTENCY_REPLAY',
   IDEMPOTENCY_CONFLICT: 'IDEMPOTENCY_CONFLICT',
 } as const
 
 export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode]
 
-export type ApiErrorBody = {
-  error: string
-  code?: ErrorCodeValue
-  details?: unknown
-}
-
-export function apiError(
-  c: Context,
-  code: ErrorCodeValue,
-  message: string,
-  status: ContentfulStatusCode,
-  details?: unknown,
-) {
-  const body: ApiErrorBody = {
-    error: message,
-    code,
-    ...(details ? { details } : {}),
-  }
-  return c.json(body, status)
-}
-
 export class ListQueryError extends Error {
   readonly code: ErrorCodeValue
   readonly details?: unknown
 
   constructor(
     message: string,
-    code: ErrorCodeValue = ErrorCode.VALIDATION_ERROR,
+    code: ErrorCodeValue = ErrorCode.BAD_REQUEST,
     details?: unknown,
   ) {
     super(message)