bunderstack 0.16.0 → 0.17.0-beta.0

package/src/jobs/define.ts

@@ -1,14 +1,13 @@
 // src/jobs/define.ts — job definition types and the typed builder.
-// `createJobsBuilder` mirrors `createTRPC`: it exists purely to carry
+// `createJobsBuilder` exists purely to carry
 // TSchema/TEnvResult typing into inline callbacks and extracted files.
-import type { ZodType } from 'zod'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 import type { DbFor } from '../db'
 import type { EmailFacade } from '../email'
 import type { StorageFacade } from '../index'
 
 import { parseCron } from './cron'
-
 import { CRON_PREFIX, type CatchUp } from './slots'
 
 export const DEFAULT_RETRIES = 3
@@ -33,7 +32,7 @@ export type TickResult = {
 }
 
 /**
- * The untyped runtime facade. Handler ctx and tRPC ctx expose this shape;
+ * The untyped runtime facade. Job handlers and API context expose this shape;
  * `app.jobs` narrows `enqueue` to the declared job names/payloads.
  */
 export type JobsRuntimeFacade = {
@@ -71,8 +70,8 @@ export type QueueJobDefinition<
   TEnvResult = Record<string, unknown>,
 > = {
   kind: 'job'
-  /** zod schema for the payload; parsed at enqueue AND before the handler runs. */
-  input?: ZodType<TInput>
+  /** Standard Schema payload; parsed at enqueue AND before the handler runs. */
+  input?: StandardSchemaV1<unknown, TInput>
   /** Attempts after the first failure. Default 3 (so 4 total attempts). */
   retries?: number
   /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */
@@ -232,7 +231,7 @@ export function createJobsBuilder<
   TEnvResult = Record<string, unknown>,
 >() {
   return {
-    /** Identity with inference: pins TInput from the zod schema. */
+    /** Identity with inference: pins TInput from the schema output. */
     job<TInput = undefined>(
       def: Omit<QueueJobDefinition<TInput, TSchema, TEnvResult>, 'kind'>,
     ): QueueJobDefinition<TInput, TSchema, TEnvResult> {
@@ -260,9 +259,8 @@ export type BunderstackJobsBuilder<
 
 // Infers TInput from the JobDefinition's own type argument rather than
 // pattern-matching the (optional, so union-with-undefined) `input` property —
-// `TDef extends { input: ZodType<infer I> }` fails structurally because
-// `input?: ZodType<TInput>` desugars to `ZodType<TInput> | undefined`, which
-// can never satisfy a required-property pattern.
+// A required-property pattern fails structurally because `input` is optional,
+// so infer from the definition's own type argument instead.
 type JobInputOf<TDef> =
   TDef extends QueueJobDefinition<infer TInput, any, any> ? TInput : undefined
 

package/src/jobs/queue.ts

@@ -5,8 +5,8 @@ import type { AnyDb } from '../dialect'
 import type { EnqueueOptions, JobsDefs } from './define'
 
 import { jobsTableFor } from '../internal-tables'
+import { validateStandardSchema } from '../standard-schema'
 import { generate } from '../typeid'
-
 import { CRON_PREFIX } from './slots'
 
 export async function enqueueJob(
@@ -23,7 +23,11 @@ export async function enqueueJob(
   const isCron = def.kind === 'cron'
   const type = isCron ? `${CRON_PREFIX}${name}` : name
   // Cron slots carry no payload; queue jobs validate theirs at the call site.
-  const parsed = isCron ? null : def.input ? def.input.parse(input) : null
+  const parsed = isCron
+    ? null
+    : def.input
+      ? validateStandardSchema(def.input, input, `job "${name}" input`)
+      : null
   const t = jobsTableFor(db)
   const now = Date.now()
   const runAt =

package/src/jobs/worker.ts

@@ -12,6 +12,7 @@ import type {
 } from './define'
 
 import { jobsTableFor } from '../internal-tables'
+import { validateStandardSchema } from '../standard-schema'
 import { parseCron } from './cron'
 import { backoffMs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './define'
 import { enqueueJob } from './queue'
@@ -73,7 +74,9 @@ export function createJobRunner(deps: {
       return { scheduledFor: new Date(Number(row.runAt)) }
     }
     const raw = JSON.parse(row.payloadJson)
-    return def.input ? def.input.parse(raw) : undefined
+    return def.input
+      ? validateStandardSchema(def.input, raw, 'job payload')
+      : undefined
   }
 
   /**

package/src/manifest.ts

@@ -1,5 +1,7 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
 import { getTableName, isTable } from 'drizzle-orm'
-import { z, type ZodType } from 'zod'
+import * as v from 'valibot'
 
 import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
@@ -12,6 +14,10 @@ import {
   bunderstackJobs,
 } from './internal-tables'
 import { parseCron } from './jobs/cron'
+import {
+  StandardSchemaValidationError,
+  validateStandardSchema,
+} from './standard-schema'
 
 export type ManifestEnvVar = {
   key: string
@@ -43,95 +49,77 @@ export type BunderstackManifest = {
   }
 }
 
-const nonEmpty = z.string().min(1)
-const migrationDirectory = nonEmpty.refine(
-  (value) =>
-    value.startsWith('/') ||
-    (!value.includes('\\') &&
-      value.split('/').every((part) => part !== '..' && part !== '')),
-  {
-    message:
-      'migrationsDirectory must be an absolute path or a relative path without traversal',
-  },
+const nonEmpty = v.pipe(v.string(), v.minLength(1))
+const migrationDirectory = v.pipe(
+  nonEmpty,
+  v.check(
+    (value) =>
+      value.startsWith('/') ||
+      (!value.includes('\\') &&
+        value.split('/').every((part) => part !== '..' && part !== '')),
+    'migrationsDirectory must be an absolute path or a relative path without traversal',
+  ),
 )
-const cronSchedule = nonEmpty.refine(
-  (value) => {
+const cronSchedule = v.pipe(
+  nonEmpty,
+  v.check((value) => {
     try {
       parseCron(value)
       return true
     } catch {
       return false
     }
-  },
-  { message: 'invalid cron schedule' },
+  }, 'invalid cron schedule'),
 )
 
-const manifestSchema = z
-  .object({
-    version: z.literal(3),
-    database: z
-      .object({
-        dialect: z.enum(['sqlite', 'pg']),
-        migrationsDirectory: migrationDirectory,
-        tables: z.array(
-          z
-            .object({
-              exportName: nonEmpty,
-              physicalName: nonEmpty,
-              system: z.boolean(),
-            })
-            .strict(),
-        ),
-      })
-      .strict(),
-    storage: z
-      .object({
-        defaultBucket: nonEmpty,
-        buckets: z.array(
-          z
-            .object({
-              name: nonEmpty,
-              visibility: z.enum(['public', 'private']),
-            })
-            .strict(),
-        ),
-      })
-      .strict(),
-    realtime: z.object({ required: z.boolean() }).strict(),
-    environment: z.array(
-      z
-        .object({
-          key: nonEmpty,
-          required: z.boolean(),
-          scope: z.enum(['server', 'client']),
-        })
-        .strict(),
+const manifestSchema = v.strictObject({
+  version: v.literal(3),
+  database: v.strictObject({
+    dialect: v.picklist(['sqlite', 'pg']),
+    migrationsDirectory: migrationDirectory,
+    tables: v.array(
+      v.strictObject({
+        exportName: nonEmpty,
+        physicalName: nonEmpty,
+        system: v.boolean(),
+      }),
     ),
-    background: z
-      .object({
-        jobs: z.array(z.object({ name: nonEmpty }).strict()),
-        cron: z.array(
-          z
-            .object({
-              name: nonEmpty,
-              schedule: cronSchedule,
-              timezone: z.literal('UTC'),
-            })
-            .strict(),
-        ),
-        maintenance: z.array(
-          z
-            .object({
-              name: z.literal('storage-sweep'),
-              schedule: cronSchedule,
-              timezone: z.literal('UTC'),
-            })
-            .strict(),
-        ),
-      })
-      .strict(),
-  })
-  .strict()
+  }),
+  storage: v.strictObject({
+    defaultBucket: nonEmpty,
+    buckets: v.array(
+      v.strictObject({
+        name: nonEmpty,
+        visibility: v.picklist(['public', 'private']),
+      }),
+    ),
+  }),
+  realtime: v.strictObject({ required: v.boolean() }),
+  environment: v.array(
+    v.strictObject({
+      key: nonEmpty,
+      required: v.boolean(),
+      scope: v.picklist(['server', 'client']),
+    }),
+  ),
+  background: v.strictObject({
+    jobs: v.array(v.strictObject({ name: nonEmpty })),
+    cron: v.array(
+      v.strictObject({
+        name: nonEmpty,
+        schedule: cronSchedule,
+        timezone: v.literal('UTC'),
+      }),
+    ),
+    maintenance: v.array(
+      v.strictObject({
+        name: v.literal('storage-sweep'),
+        schedule: cronSchedule,
+        timezone: v.literal('UTC'),
+      }),
+    ),
+  }),
+})
 
 function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
   return [...entries].sort((left, right) => key(left).localeCompare(key(right)))
@@ -161,14 +149,19 @@ function describeTables(schema: Record<string, unknown>) {
 }
 
 function describeSection(
-  section: Record<string, ZodType> | undefined,
+  section: Record<string, StandardSchemaV1> | undefined,
   scope: ManifestEnvVar['scope'],
 ): ManifestEnvVar[] {
-  return Object.entries(section ?? {}).map(([key, schema]) => ({
-    key,
-    required: !schema.safeParse(undefined).success,
-    scope,
-  }))
+  return Object.entries(section ?? {}).map(([key, schema]) => {
+    let required = false
+    try {
+      validateStandardSchema(schema, undefined, 'env')
+    } catch (error) {
+      if (!(error instanceof StandardSchemaValidationError)) throw error
+      required = true
+    }
+    return { key, required, scope }
+  })
 }
 
 function systemTables() {
@@ -192,7 +185,11 @@ function systemTables() {
 }
 
 export function parseManifest(value: unknown): BunderstackManifest {
-  const manifest = manifestSchema.parse(value) as BunderstackManifest
+  const manifest = validateStandardSchema(
+    manifestSchema,
+    value,
+    'manifest',
+  ) as BunderstackManifest
   rejectDuplicates(
     'database physical table',
     manifest.database.tables.map((entry) => entry.physicalName),

package/src/realtime/facade.ts

@@ -1,6 +1,9 @@
 import { getTableName, type InferSelectModel, type Table } from 'drizzle-orm'
 
-import type { RealtimeAction, RealtimeBroker } from './index'
+import type {
+  RealtimeAction,
+  RealtimePublisher,
+} from './publisher'
 
 export type RealtimeTransport = 'disabled' | 'memory' | 'redis'
 
@@ -23,30 +26,30 @@ export interface RealtimeFacade<
 }
 
 export function createRealtimeFacade<TSchema extends Record<string, unknown>>(
-  broker?: RealtimeBroker,
-  transport: RealtimeTransport = broker ? 'memory' : 'disabled',
+  publisher?: RealtimePublisher,
+  transport: RealtimeTransport = publisher ? 'memory' : 'disabled',
 ): RealtimeFacade<TSchema> {
-  if (!broker && transport !== 'disabled') {
+  if (!publisher && transport !== 'disabled') {
     throw new Error(
-      '[bunderstack] an enabled realtime transport requires a broker',
+      '[bunderstack] an enabled realtime transport requires a publisher',
     )
   }
-  if (broker && transport === 'disabled') {
+  if (publisher && transport === 'disabled') {
     throw new Error(
-      '[bunderstack] a realtime broker cannot use the disabled transport',
+      '[bunderstack] a realtime publisher cannot use the disabled transport',
     )
   }
 
   return {
-    enabled: broker !== undefined,
+    enabled: publisher !== undefined,
     transport,
     async publish(table, action, record) {
-      if (!broker) return
-      await broker.publish(
-        getTableName(table),
+      if (!publisher) return
+      await publisher.publish('change', {
+        table: getTableName(table),
         action,
-        record as unknown as Record<string, unknown>,
-      )
+        record: record as unknown as Record<string, unknown>,
+      })
     },
   }
 }

package/src/realtime/filter.ts

@@ -0,0 +1,77 @@
+import { getEventMeta, withEventMeta } from '@orpc/server'
+
+import type {
+  AccessUser,
+  ResolvedAccess,
+} from '../access'
+import type { RealtimeChange } from './publisher'
+
+import {
+  checkAccess,
+  rowMatchesScope,
+  tableEntryForName,
+} from '../access'
+
+export interface FilterRealtimeChangesOptions {
+  subscriptions: readonly string[]
+  access: ResolvedAccess
+  request: Request
+  getSession: () => Promise<{
+    user: AccessUser | null
+    activeOrganizationId: string | null
+  }>
+}
+
+export async function* filterRealtimeChanges(
+  source: AsyncIterable<RealtimeChange>,
+  options: FilterRealtimeChangesOptions,
+): AsyncGenerator<RealtimeChange, void, void> {
+  const subscriptions = new Set(options.subscriptions)
+  let sessionPromise:
+    | ReturnType<FilterRealtimeChangesOptions['getSession']>
+    | undefined
+  const getSession = () => (sessionPromise ??= options.getSession())
+
+  for await (const change of source) {
+    const entry = tableEntryForName(options.access, change.table)
+    if (!entry?.enabled) continue
+
+    const recordId = change.record.id
+    if (
+      !subscriptions.has(change.table) &&
+      (recordId == null ||
+        !subscriptions.has(`${change.table}/${String(recordId)}`))
+    ) {
+      continue
+    }
+    if (entry.get === 'deny') continue
+
+    const needsSession = entry.get !== 'public' || entry.readScope !== undefined
+    const session = needsSession
+      ? await getSession()
+      : { user: null, activeOrganizationId: null }
+    const context = {
+      request: options.request,
+      user: session.user,
+      row: change.record,
+      session: { activeOrganizationId: session.activeOrganizationId },
+    }
+    if (!(await checkAccess(entry.get, context, entry.ownerColumn)).allowed) {
+      continue
+    }
+    if (
+      entry.readScope &&
+      !rowMatchesScope(change.record, entry.readScope(context))
+    ) {
+      continue
+    }
+
+    const projected: RealtimeChange = {
+      table: change.table,
+      action: change.action,
+      record: change.record,
+    }
+    const meta = getEventMeta(change)
+    yield meta ? withEventMeta(projected, meta) : projected
+  }
+}

package/src/realtime/heartbeat.ts

@@ -0,0 +1,80 @@
+export const REALTIME_HEARTBEAT_INTERVAL_MS = 5_000
+
+export type RealtimeHeartbeat = { type: 'heartbeat' }
+
+type SourceState<T> =
+  | { status: 'pending' }
+  | { status: 'ready'; result: IteratorResult<T> }
+  | { status: 'error'; error: unknown }
+
+/**
+ * Emits a transport-only event whenever the source has been idle for an
+ * interval. Heartbeats are deliberately not published, persisted, or assigned
+ * event IDs, so they do not affect replay and resume semantics.
+ */
+export async function* withRealtimeHeartbeat<T>(
+  source: AsyncIterable<T>,
+  options: { intervalMs?: number; signal?: AbortSignal },
+): AsyncGenerator<T | RealtimeHeartbeat, void, void> {
+  const intervalMs = Math.max(
+    1,
+    options.intervalMs ?? REALTIME_HEARTBEAT_INTERVAL_MS,
+  )
+  const iterator = source[Symbol.asyncIterator]()
+  let state: SourceState<T> = { status: 'pending' }
+  let wake: (() => void) | undefined
+  const getState = (): SourceState<T> => state
+
+  const requestNext = () => {
+    state = { status: 'pending' }
+    void iterator.next().then(
+      (result) => {
+        state = { status: 'ready', result }
+        wake?.()
+      },
+      (error: unknown) => {
+        state = { status: 'error', error }
+        wake?.()
+      },
+    )
+  }
+
+  requestNext()
+  try {
+    while (!options.signal?.aborted) {
+      let current = getState()
+      if (current.status === 'pending') {
+        await new Promise<void>((resolve) => {
+          let settled = false
+          const finish = () => {
+            if (settled) return
+            settled = true
+            clearTimeout(timer)
+            options.signal?.removeEventListener('abort', finish)
+            resolve()
+          }
+          const timer = setTimeout(finish, intervalMs)
+          options.signal?.addEventListener('abort', finish, { once: true })
+          wake = finish
+        })
+        wake = undefined
+
+        if (options.signal?.aborted) break
+        current = getState()
+        if (current.status === 'pending') {
+          yield { type: 'heartbeat' }
+          continue
+        }
+      }
+
+      if (current.status === 'error') throw current.error
+      if (current.result.done) break
+
+      yield current.result.value
+      requestNext()
+    }
+  } finally {
+    wake = undefined
+    await iterator.return?.()
+  }
+}

package/src/realtime/publisher.ts

@@ -0,0 +1,46 @@
+import type { Publisher } from '@orpc/publisher'
+import type { RedisClient } from 'bun'
+
+import { BunRedisPublisher } from '@orpc/bun'
+import { MemoryPublisher } from '@orpc/publisher/memory'
+
+export type RealtimeAction = 'create' | 'update' | 'delete'
+
+export interface RealtimeChange {
+  table: string
+  action: RealtimeAction
+  record: Record<string, unknown>
+}
+
+export interface RealtimeEvents extends Record<string, object> {
+  change: RealtimeChange
+}
+
+export type RealtimePublisher = Publisher<RealtimeEvents>
+
+export interface RealtimePublisherOptions {
+  maxBufferedEvents?: number
+  resumeSeconds?: number
+}
+
+export function createMemoryRealtimePublisher(
+  options: RealtimePublisherOptions = {},
+): RealtimePublisher {
+  return new MemoryPublisher<RealtimeEvents>({
+    maxBufferedEvents: options.maxBufferedEvents,
+    resume: { enabled: true, seconds: options.resumeSeconds ?? 300 },
+  })
+}
+
+export function createRedisRealtimePublisher(
+  redis: RedisClient,
+  subscriber: RedisClient | Promise<RedisClient>,
+  options: RealtimePublisherOptions & { prefix?: string } = {},
+): RealtimePublisher {
+  return new BunRedisPublisher<RealtimeEvents>(redis, {
+    subscriber,
+    prefix: options.prefix ?? 'bunderstack:',
+    maxBufferedEvents: options.maxBufferedEvents,
+    resume: { enabled: true, seconds: options.resumeSeconds ?? 300 },
+  })
+}

package/src/standard-schema.ts

@@ -0,0 +1,59 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+export type StandardSchema = StandardSchemaV1
+export type InferStandardOutput<TSchema extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<TSchema>
+
+export type StandardSchemaIssue = {
+  path: PropertyKey[]
+  message: string
+}
+
+export class StandardSchemaValidationError extends Error {
+  readonly issues: StandardSchemaIssue[]
+
+  constructor(label: string, issues: readonly StandardSchemaV1.Issue[]) {
+    const normalized = issues.map((issue) => ({
+      path: [...(issue.path ?? [])].map((segment) =>
+        typeof segment === 'object' ? segment.key : segment,
+      ),
+      message: issue.message,
+    }))
+    super(
+      normalized
+        .map((issue) => {
+          const path = issue.path.map(String).join('.')
+          return `${label}${path ? `.${path}` : ''}: ${issue.message}`
+        })
+        .join('\n'),
+    )
+    this.name = 'StandardSchemaValidationError'
+    this.issues = normalized
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof value.then === 'function'
+  )
+}
+
+export function validateStandardSchema<TSchema extends StandardSchemaV1>(
+  schema: TSchema,
+  value: unknown,
+  label: string,
+): StandardSchemaV1.InferOutput<TSchema> {
+  const result = schema['~standard'].validate(value)
+  if (isPromiseLike(result)) {
+    throw new Error(
+      `[bunderstack] ${label} schema validation must be synchronous`,
+    )
+  }
+  if (result.issues) {
+    throw new StandardSchemaValidationError(label, result.issues)
+  }
+  return result.value
+}

package/src/storage/index.ts

@@ -3,6 +3,14 @@ import { LocalStorageAdapter } from './local'
 import { S3StorageAdapter } from './s3'
 
 export type { LocalStorageAdapter, S3StorageAdapter }
+export { createStorageOperations } from './operations'
+export type {
+  PrepareUploadResult,
+  StorageDownload,
+  StorageExecutionContext,
+  StorageOperations,
+  StorageOperationsOptions,
+} from './operations'
 
 export interface PresignPutOptions {
   contentType?: string