bunderstack-sync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirill Chuprov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# bunderstack-sync
+
+TanStack DB collections synced live to a
+[bunderstack](https://github.com/kirill-dev-pro/bunderstack) backend:
+optimistic mutations with SSE-driven realtime sync.
+
+```sh
+bun add bunderstack-sync
+```
+
+Full documentation and examples:
+[github.com/kirill-dev-pro/bunderstack](https://github.com/kirill-dev-pro/bunderstack)
+
+## Shipping TypeScript source
+
+This package publishes raw TypeScript (`exports` point at `.ts` files). Bun
+consumes it natively. If a Node-based bundler or SSR server processes it,
+make sure the package is bundled rather than externalized — e.g. in Vite:
+
+```ts
+ssr: {
+  noExternal: [/^bunderstack/]
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "bunderstack-sync",
+  "version": "0.1.0",
+  "description": "TanStack DB collections synced live to a bunderstack backend: optimistic mutations with SSE-driven realtime sync.",
+  "keywords": [
+    "bun",
+    "bunderstack",
+    "optimistic",
+    "realtime",
+    "sse",
+    "sync",
+    "tanstack-db"
+  ],
+  "homepage": "https://github.com/kirill-dev-pro/bunderstack#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kirill-dev-pro/bunderstack.git",
+    "directory": "packages/bunderstack-sync"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "bunderstack": "0.1.0",
+    "bunderstack-query": "0.1.0"
+  },
+  "devDependencies": {
+    "@tanstack/db": "^0.6.13",
+    "@tanstack/query-core": "^5.101.1",
+    "@tanstack/query-db-collection": "^1.0.45",
+    "@tanstack/react-query": "^5.101.1",
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/db": "^0.6.0",
+    "@tanstack/query-db-collection": "^1.0.0",
+    "@tanstack/react-query": "^5.101.0",
+    "typescript": "^5"
+  }
+}

package/src/collection.ts

@@ -0,0 +1,301 @@
+import { createCollection } from '@tanstack/db'
+import { queryCollectionOptions } from '@tanstack/query-db-collection'
+import type { QueryClient } from '@tanstack/react-query'
+import {
+  createTableClient,
+  MAX_LIST_LIMIT,
+  type TableClient,
+} from 'bunderstack-query'
+
+export type TableCollectionConfig = {
+  tableName: string
+  baseUrl: string
+  fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  queryClient: QueryClient
+  /** Rows the default `.collection` syncs per fetch. Defaults to 100. For
+   * feed-shaped tables that need real pagination use `scopedCollection`. */
+  limit?: number
+}
+
+export type ScopedFilterValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly (string | number)[]
+
+export type ScopedCollectionOptions = {
+  /** Equality filters, e.g. `{ replyToId: null }` — columns must be in the
+   * table's `filterableColumns` server-side. */
+  filter?: Record<string, ScopedFilterValue>
+  sort?: string
+  order?: 'asc' | 'desc'
+  /** Rows per underlying request; clamped to the server cap (200). */
+  pageSize?: number
+  /** Window size on first load and default `loadMore` step. Defaults to 20. */
+  initialCount?: number
+}
+
+function matchesFilter(
+  record: Record<string, unknown>,
+  filter: Record<string, ScopedFilterValue>,
+): boolean {
+  for (const [col, expected] of Object.entries(filter)) {
+    const actual = record[col]
+    if (expected === null) {
+      if (actual != null) return false
+    } else if (Array.isArray(expected)) {
+      if (!expected.map(String).includes(String(actual))) return false
+    } else if (String(actual) !== String(expected)) return false
+  }
+  return true
+}
+
+/** Deterministic serialization for cache keys (object key order ignored). */
+function stableKey(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stableKey).join(',')}]`
+  const entries = Object.entries(value as Record<string, unknown>)
+    .sort(([a], [b]) => (a < b ? -1 : 1))
+    .map(([k, v]) => `${JSON.stringify(k)}:${stableKey(v)}`)
+  return `{${entries.join(',')}}`
+}
+
+export function createTableCollection<
+  TRow extends { id: string | number },
+  TCreate = Partial<TRow>,
+  TUpdate = Partial<TRow>,
+>(config: TableCollectionConfig) {
+  const table = createTableClient<TRow, TCreate, TUpdate>({
+    tableName: config.tableName,
+    baseUrl: config.baseUrl,
+    fetch: config.fetch,
+  })
+
+  const collection = createCollection(
+    queryCollectionOptions<TRow>({
+      queryKey: [config.tableName, 'collection'],
+      queryFn: async () => {
+        const page = await table.list({ limit: config.limit ?? 100 })
+        return page.items
+      },
+      queryClient: config.queryClient,
+      getKey: (item) => item.id,
+      onInsert: async ({ transaction }) => {
+        const mutation = transaction.mutations[0]!
+        // Pass the client-generated `id` through as-is. TanStack DB's
+        // optimistic insert keys the local row by this `id` (via `getKey`),
+        // and this matches `sanitizeWriteBody`'s default on the server: a
+        // client-supplied `id` on create is accepted unless the table's
+        // access config sets an explicit `writableColumns` allowlist that
+        // excludes `id`. Apps that DO restrict it that way will see the
+        // server regenerate the id, and the optimistic entry's key will get
+        // swapped once the synced row comes back — a known, narrower
+        // trade-off in that uncommon case, not the default.
+        await table.create(mutation.modified as unknown as Partial<TCreate>)
+      },
+      onUpdate: async ({ transaction }) => {
+        const mutation = transaction.mutations[0]!
+        await table.update(
+          mutation.key as string | number,
+          mutation.changes as unknown as TUpdate,
+        )
+      },
+      onDelete: async ({ transaction }) => {
+        const mutation = transaction.mutations[0]!
+        await table.delete(mutation.key as string | number)
+      },
+    }),
+  )
+
+  type Collection = typeof collection
+
+  // Scoped/byIds collections register here so realtime events fan out to
+  // every live view of this table, filtered client-side by each view's
+  // own predicate (broadcasts are already access-filtered server-side).
+  const registry: {
+    collection: Collection
+    matches: (record: Record<string, unknown>) => boolean
+    refetch: () => Promise<void>
+  }[] = []
+
+  const scopedCache = new Map<string, ScopedCollection>()
+
+  type ScopedCollection = {
+    collection: Collection
+    /** Grow the window by `count` (default initialCount) and refetch in place. */
+    loadMore: (count?: number) => Promise<void>
+    /** Whether the server reported rows beyond the window (as of last fetch). */
+    hasMore: () => boolean
+    /** Current desired window size. */
+    size: () => number
+  }
+
+  function scopedCollection(
+    options: ScopedCollectionOptions = {},
+  ): ScopedCollection {
+    const pageSize = Math.min(
+      options.pageSize ?? MAX_LIST_LIMIT,
+      MAX_LIST_LIMIT,
+    )
+    const initialCount = options.initialCount ?? 20
+    const filter = options.filter ?? {}
+    const cacheKey = stableKey({
+      filter,
+      sort: options.sort ?? null,
+      order: options.order ?? null,
+      pageSize,
+      initialCount,
+    })
+    const cached = scopedCache.get(cacheKey)
+    if (cached) return cached
+
+    let desiredCount = initialCount
+    let serverHasMore = false
+
+    const scoped = createCollection(
+      queryCollectionOptions<TRow>({
+        queryKey: [config.tableName, 'scoped', cacheKey],
+        queryFn: async () => {
+          // Growing window: walk cursor pages (each ≤ the server cap) until
+          // the current desired count is collected or the table runs out.
+          // The collection stays stable across loadMore — refetching in
+          // place only ever adds rows, so already-rendered items never
+          // unmount (no scroll jumps or zero-item flashes).
+          const items: TRow[] = []
+          let cursor: string | undefined
+          let more = false
+          while (items.length < desiredCount) {
+            const remaining = Math.min(pageSize, desiredCount - items.length)
+            const page = await table.list({
+              ...filter,
+              ...(options.sort ? { sort: options.sort } : {}),
+              ...(options.order ? { order: options.order } : {}),
+              cursorMode: true,
+              limit: remaining,
+              ...(cursor ? { cursor } : {}),
+            })
+            items.push(...page.items)
+            more = Boolean(page.hasMore && page.nextCursor)
+            if (!more) break
+            cursor = page.nextCursor
+          }
+          serverHasMore = more
+          return items.slice(0, desiredCount)
+        },
+        queryClient: config.queryClient,
+        getKey: (item) => item.id,
+      }),
+    )
+
+    const entry: ScopedCollection = {
+      collection: scoped,
+      loadMore: async (count) => {
+        desiredCount += count ?? initialCount
+        await scoped.utils.refetch()
+      },
+      hasMore: () => serverHasMore,
+      size: () => desiredCount,
+    }
+    registry.push({
+      collection: scoped,
+      matches: (record) => matchesFilter(record, filter),
+      refetch: async () => {
+        await scoped.utils.refetch()
+      },
+    })
+    scopedCache.set(cacheKey, entry)
+    return entry
+  }
+
+  const byIdsCache = new Map<string, Collection>()
+
+  function collectionByIds(
+    ids: readonly TRow['id'][],
+    options: { column?: string } = {},
+  ): Collection {
+    const column = options.column ?? 'id'
+    const unique = Array.from(new Set(ids.map(String))).sort()
+    const cacheKey = `${column}:${unique.join(',')}`
+    const cached = byIdsCache.get(cacheKey)
+    if (cached) return cached
+
+    const idSet = new Set(unique)
+    const byIds = createCollection(
+      queryCollectionOptions<TRow>({
+        queryKey: [config.tableName, 'byIds', column, unique],
+        queryFn: async () => {
+          if (unique.length === 0) return []
+          const items: TRow[] = []
+          // Chunked at the server's IN-filter cap so any id set works.
+          for (let i = 0; i < unique.length; i += MAX_LIST_LIMIT) {
+            const chunk = unique.slice(i, i + MAX_LIST_LIMIT)
+            const page = await table.list({
+              [column]: chunk,
+              limit: chunk.length,
+            })
+            items.push(...page.items)
+          }
+          return items
+        },
+        queryClient: config.queryClient,
+        getKey: (item) => item.id,
+      }),
+    )
+    registry.push({
+      collection: byIds,
+      matches: (record) => idSet.has(String(record[column])),
+      refetch: async () => {
+        await byIds.utils.refetch()
+      },
+    })
+    byIdsCache.set(cacheKey, byIds)
+    return byIds
+  }
+
+  function applyRealtimeEvent(
+    action: 'create' | 'update' | 'delete',
+    record: Record<string, unknown>,
+  ) {
+    const id = record['id'] as string | number
+    const apply = (
+      target: Collection,
+      matches: (record: Record<string, unknown>) => boolean,
+    ) => {
+      // Collections that never started syncing (no subscribers yet) can't
+      // accept manual writes — and don't need to: their first sync fetches
+      // fresh data anyway.
+      if (target.status !== 'ready') return
+      if (action === 'delete' || !matches(record)) {
+        if (target.get(id) !== undefined) target.utils.writeDelete(id)
+      } else {
+        target.utils.writeUpsert(record as unknown as TRow)
+      }
+    }
+    apply(collection, () => true)
+    for (const entry of registry) apply(entry.collection, entry.matches)
+  }
+
+  /** Refetch the base collection plus every scoped/byIds view (gap recovery). */
+  async function refetchAll() {
+    await Promise.all([
+      collection.utils.refetch(),
+      ...registry.map((entry) => entry.refetch()),
+    ])
+  }
+
+  return {
+    collection,
+    table: table as TableClient<TRow, TCreate, TUpdate>,
+    scopedCollection,
+    collectionByIds,
+    applyRealtimeEvent,
+    refetchAll,
+  }
+}
+
+export type TableCollection<
+  TRow extends { id: string | number },
+  TCreate = Partial<TRow>,
+  TUpdate = Partial<TRow>,
+> = ReturnType<typeof createTableCollection<TRow, TCreate, TUpdate>>

package/src/index.ts

@@ -0,0 +1,139 @@
+import type { QueryClient } from '@tanstack/react-query'
+import {
+  createBunderstackQueryClient,
+  type FilesQueryClient,
+  BunderstackApiError,
+  type InferSelect,
+  type InferInsert,
+  type UploadedFile,
+} from 'bunderstack-query'
+
+import { createTableCollection, type TableCollection } from './collection'
+import { createSyncRealtimeClient } from './realtime-sync'
+import type { CreateFor, RowFor } from './sync-client'
+
+type BaseOptions = {
+  baseUrl?: string
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  queryClient: QueryClient
+}
+
+type SyncTablesClient<
+  TSchema extends Record<string, unknown>,
+  TTable extends keyof TSchema & string,
+> = {
+  [K in TTable]: TableCollection<
+    RowFor<TSchema, K>,
+    CreateFor<TSchema, K>,
+    Partial<RowFor<TSchema, K>>
+  >
+}
+
+export function createBunderstackSyncClient<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+>() {
+  return {
+    with<
+      const TTables extends readonly (keyof TSchema & string)[],
+      const TBuckets extends readonly string[],
+    >(
+      options: BaseOptions & {
+        tables: TTables
+        buckets: TBuckets
+        /** Subscribe these tables to live SSE updates. Defaults to true in
+         * the browser, false during SSR. */
+        realtime?: boolean
+      },
+    ) {
+      const baseUrl = options.baseUrl ?? '/api'
+      const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+
+      const tablesClient: Record<
+        string,
+        ReturnType<typeof createTableCollection>
+      > = {}
+      for (const tableKey of options.tables) {
+        tablesClient[tableKey] = createTableCollection({
+          tableName: tableKey,
+          baseUrl,
+          fetch: fetchFn,
+          queryClient: options.queryClient,
+        })
+      }
+
+      const filesClient: FilesQueryClient<TBuckets[number]> =
+        createBunderstackQueryClient<TSchema>().withFiles({
+          baseUrl,
+          fetch: fetchFn,
+          buckets: options.buckets,
+          queryClient: options.queryClient,
+        })
+
+      // Realtime needs a browser-side persistent connection; default off in SSR.
+      const realtime =
+        !(options.realtime ?? typeof window !== 'undefined')
+          ? undefined
+          : createSyncRealtimeClient({
+              baseUrl,
+              queryClient: options.queryClient,
+              // `createSyncRealtimeClient` expects the ambient `typeof fetch`
+              // (which includes Bun's `preconnect` static), while our public
+              // options accept any plain fetch-shaped function — the two
+              // signatures are otherwise call-compatible.
+              fetch: fetchFn as typeof fetch,
+              // Individual collections are typed against their own row shape
+              // (inferred from `createTableCollection`'s constraint since
+              // this loop can't carry a per-key TRow), which is narrower
+              // than `SyncableCollection`'s `unknown`-typed utils. Safe here
+              // because `realtime-sync.ts` only ever passes server-decoded
+              // records through, matching each collection's own row shape.
+              collections: Object.fromEntries(
+                Object.entries(tablesClient).map(([k, v]) => [
+                  k,
+                  v.collection,
+                ]),
+              ) as unknown as NonNullable<
+                Parameters<typeof createSyncRealtimeClient>[0]['collections']
+              >,
+            })
+
+      return {
+        ...tablesClient,
+        ...filesClient,
+        realtime,
+      } as unknown as SyncTablesClient<TSchema, TTables[number]> &
+        FilesQueryClient<TBuckets[number]> & {
+          realtime: typeof realtime
+        }
+    },
+  }
+}
+
+export { createSyncClient } from './sync-client'
+export type {
+  BunderstackSyncClient,
+  CreateFor,
+  RowFor,
+  SyncClientOptions,
+} from './sync-client'
+export { createTableCollection } from './collection'
+export type {
+  ScopedCollectionOptions,
+  ScopedFilterValue,
+  TableCollection,
+  TableCollectionConfig,
+} from './collection'
+export { createSyncRealtimeClient } from './realtime-sync'
+export type { SyncRealtimeConfig, SyncRealtimeTarget } from './realtime-sync'
+
+// Re-export bunderstack-query types and utilities for convenience
+export { BunderstackApiError, MAX_LIST_LIMIT } from 'bunderstack-query'
+export type {
+  AnyBunderstackApp,
+  InferBuckets,
+  InferInsert,
+  InferSchema,
+  InferSelect,
+  InferTables,
+  UploadedFile,
+} from 'bunderstack-query'

package/src/realtime-sync.ts

@@ -0,0 +1,72 @@
+import { createRealtimeClient, type RealtimeEvent } from 'bunderstack-query'
+import type { QueryClient } from '@tanstack/react-query'
+
+type SyncableCollection = {
+  utils: {
+    writeUpsert: (item: unknown) => void
+    writeDelete: (key: unknown) => void
+    refetch: () => Promise<void>
+  }
+}
+
+/** A table bundle the resolver mode routes events into (see collection.ts). */
+export type SyncRealtimeTarget = {
+  applyRealtimeEvent: (
+    action: 'create' | 'update' | 'delete',
+    record: Record<string, unknown>,
+  ) => void
+  refetchAll: () => Promise<void>
+}
+
+export type SyncRealtimeConfig = {
+  baseUrl: string
+  queryClient: QueryClient
+  fetch?: typeof fetch
+  /** Static map of table name -> the collection that table's rows sync into. */
+  collections?: Record<string, SyncableCollection>
+  /** Lazy lookup: resolve a table's target at event time (proxy clients that
+   * can't enumerate tables upfront). Takes precedence over `collections`. */
+  resolve?: (table: string) => SyncRealtimeTarget | undefined
+  /** All materialized targets — used for gap recovery in resolver mode. */
+  resolveAll?: () => Iterable<SyncRealtimeTarget>
+}
+
+export function createSyncRealtimeClient(config: SyncRealtimeConfig) {
+  const staticCollections = config.collections ?? {}
+  const tables = Object.keys(staticCollections)
+
+  return createRealtimeClient({
+    baseUrl: config.baseUrl,
+    queryClient: config.queryClient,
+    tables,
+    fetch: config.fetch,
+    applyEvent: (evt: RealtimeEvent) => {
+      if (config.resolve) {
+        config.resolve(evt.table)?.applyRealtimeEvent(evt.action, evt.record)
+        return
+      }
+      const collection = staticCollections[evt.table]
+      if (!collection) return
+      if (evt.action === 'delete') {
+        collection.utils.writeDelete(evt.record['id'])
+      } else {
+        collection.utils.writeUpsert(evt.record)
+      }
+    },
+    onGap: () => {
+      if (config.resolveAll) {
+        for (const target of config.resolveAll()) {
+          target.refetchAll().catch((err) => {
+            console.error('bunderstack-sync: gap-recovery refetch failed', err)
+          })
+        }
+        return
+      }
+      for (const collection of Object.values(staticCollections)) {
+        collection.utils.refetch().catch((err) => {
+          console.error('bunderstack-sync: gap-recovery refetch failed', err)
+        })
+      }
+    },
+  })
+}

package/src/sync-client.ts

@@ -0,0 +1,127 @@
+import type { QueryClient } from '@tanstack/react-query'
+import {
+  attachBucketMutationOptions,
+  createBucketClient,
+  lazyRecord,
+  type AnyBunderstackApp,
+  type FilesQueryClient,
+  type InferBuckets,
+  type InferInsert,
+  type InferSchema,
+  type InferSelect,
+  type InferTables,
+} from 'bunderstack-query'
+
+import { createTableCollection, type TableCollection } from './collection'
+import {
+  createSyncRealtimeClient,
+  type SyncRealtimeTarget,
+} from './realtime-sync'
+
+export type RowFor<
+  TSchema extends Record<string, unknown>,
+  K extends keyof TSchema,
+> = [InferSelect<TSchema[K]>] extends [never]
+  ? { id: string | number }
+  : InferSelect<TSchema[K]> extends { id: string | number }
+  ? InferSelect<TSchema[K]>
+  : { id: string | number }
+
+export type CreateFor<
+  TSchema extends Record<string, unknown>,
+  K extends keyof TSchema,
+> = [InferInsert<TSchema[K]>] extends [never]
+  ? Partial<RowFor<TSchema, K>>
+  : InferInsert<TSchema[K]>
+
+export type SyncClientOptions = {
+  baseUrl?: string
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  queryClient: QueryClient
+  /** Live SSE updates. Defaults to true in the browser, false during SSR. */
+  realtime?: boolean
+}
+
+export type BunderstackSyncClient<TApp extends AnyBunderstackApp> = {
+  [K in InferTables<TApp>]: TableCollection<
+    RowFor<InferSchema<TApp>, K>,
+    CreateFor<InferSchema<TApp>, K>,
+    Partial<RowFor<InferSchema<TApp>, K>>
+  >
+} & FilesQueryClient<InferBuckets<TApp>> & {
+    realtime: ReturnType<typeof createSyncRealtimeClient> | undefined
+  }
+
+/**
+ * Fully typed sync client inferred from the server app. Tables (with their
+ * collections and scoped/byIds views) and buckets materialize lazily on
+ * first property access — no runtime table/bucket lists, and the app is
+ * referenced as a type only, so no server code lands in the bundle.
+ * Realtime events fan out to whichever collections have materialized.
+ *
+ * @example
+ * import type { App } from './bunderstack'   // type-only import
+ * const api = createSyncClient<App>({ queryClient })
+ * api.posts.collection; api.posts.scopedCollection({ filter: { replyToId: null } })
+ */
+export function createSyncClient<TApp extends AnyBunderstackApp>(
+  options: SyncClientOptions,
+): BunderstackSyncClient<TApp> {
+  const baseUrl = options.baseUrl ?? '/api'
+  const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+
+  // Realtime only needs the fan-out surface, so the map stays row-type-agnostic.
+  const materialized = new Map<string, SyncRealtimeTarget>()
+  const tables = lazyRecord((tableName) => {
+    const bundle = createTableCollection({
+      tableName,
+      baseUrl,
+      fetch: fetchFn,
+      queryClient: options.queryClient,
+    })
+    materialized.set(tableName, bundle)
+    return bundle
+  })
+
+  const files = lazyRecord((bucket) => {
+    const bucketClient = createBucketClient({ bucket, baseUrl, fetch: fetchFn })
+    return {
+      ...bucketClient,
+      ...attachBucketMutationOptions(bucketClient, options.queryClient),
+    }
+  })
+
+  // Realtime needs a browser-side persistent connection; default off in SSR.
+  const realtimeEnabled = options.realtime ?? typeof window !== 'undefined'
+  const realtime = realtimeEnabled
+    ? createSyncRealtimeClient({
+        baseUrl,
+        queryClient: options.queryClient,
+        // Our public options accept any plain fetch-shaped function, while
+        // the realtime client expects the ambient `typeof fetch` (which
+        // includes Bun's `preconnect` static) — call-compatible otherwise.
+        fetch: fetchFn as typeof fetch,
+        resolve: (table) => materialized.get(table),
+        resolveAll: () => materialized.values(),
+      })
+    : undefined
+
+  return new Proxy({} as BunderstackSyncClient<TApp>, {
+    get(_target, prop) {
+      if (typeof prop !== 'string') return undefined
+      if (prop === 'files') return files
+      if (prop === 'realtime') return realtime
+      if (
+        prop === 'then' ||
+        prop === 'toJSON' ||
+        prop === 'constructor' ||
+        prop === '$$typeof'
+      )
+        return undefined
+      return (tables as Record<string, unknown>)[prop]
+    },
+    has(_target, prop) {
+      return typeof prop === 'string'
+    },
+  }) as BunderstackSyncClient<TApp>
+}