bunderstack-sync 0.16.0 → 0.17.0-beta.2

package/README.md

@@ -1,48 +1,41 @@
 # 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.
+Optimistic TanStack DB collections backed by Bunderstack's unified oRPC graph
+and Publisher realtime.
 
 ```sh
-bun add bunderstack-sync
+bun add bunderstack-sync @tanstack/db @tanstack/react-query
 ```
 
-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/]
-}
+import { QueryClient } from '@tanstack/react-query'
+import { createSyncClient } from 'bunderstack-sync'
+import type { App } from '../server/bunderstack'
+
+const queryClient = new QueryClient()
+const api = createSyncClient<App>({ queryClient })
+
+const allPosts = api.posts.collection
+const feed = api.posts.scopedCollection({
+  filters: { replyToId: null },
+  sort: 'createdAt',
+  order: 'desc',
+})
+
+await feed.loadMore()
+api.realtime?.close()
 ```
 
-Because `exports` point straight at source, your TypeScript and bundler
-resolve modules *inside this package's own directory* rather than a compiled
-`dist`. That makes a stray `node_modules/bunderstack-sync/node_modules/`
-uniquely dangerous: if one is ever present (e.g. left over from an earlier
-`link:`/`file:` dependency on a local checkout, then never cleaned up after
-switching to a registry version), both `tsc` and the bundler will resolve
-peer packages like `@tanstack/db`, `@tanstack/react-query`, or `react` from
-inside it instead of your app's own `node_modules`. Two copies of a
-context-carrying package means two separate module instances at runtime —
-collections, providers, or contexts from one copy become invisible to hooks
-from the other. If you hit unexplained "not found"/mismatched-type errors,
-check for nested `node_modules` under this package's install location before
-assuming it's an application bug:
+Collections map optimistic inserts, updates, and deletes directly to generated
+oRPC procedures. Every materialized view receives access-filtered row changes
+from `realtime.changes`; reconnects are handled by oRPC Publisher metadata.
 
-```sh
-find node_modules -path '*/bunderstack-sync/node_modules/@tanstack*'
-```
+This package publishes TypeScript source. Node-based SSR bundlers should bundle
+it instead of externalizing it; for Vite:
 
-A clean `rm -rf node_modules && bun install` removes any that a normal
-install wouldn't have produced on its own.
+```ts
+ssr: { noExternal: [/^bunderstack/] }
+```
 
 ## License
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "bunderstack-sync",
-  "version": "0.16.0",
-  "description": "TanStack DB collections synced live to a bunderstack backend: optimistic mutations with SSE-driven realtime sync.",
+  "version": "0.17.0-beta.2",
+  "description": "TanStack DB collections synchronized through Bunderstack's typed oRPC client and realtime iterator.",
   "keywords": [
     "bun",
     "bunderstack",
     "optimistic",
+    "orpc",
     "realtime",
-    "sse",
     "sync",
     "tanstack-db"
   ],
@@ -21,6 +21,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*.types.ts",
     "README.md",
     "LICENSE"
   ],
@@ -35,7 +36,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "bunderstack-query": "^0.16.0"
+    "bunderstack-query": "^0.17.0-beta.2"
   },
   "devDependencies": {
     "@tanstack/db": "0.6.16",

package/src/collection.ts

@@ -6,16 +6,47 @@ import {
   type StandardSchema,
 } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
-import {
-  createTableClient,
-  MAX_LIST_LIMIT,
-  type TableClient,
-} from 'bunderstack-query'
+
+import { createUpdateQueue } from './update-queue'
+const MAX_LIST_LIMIT = 200
+
+type TableListResult<TRow> = {
+  items: TRow[]
+  hasMore: boolean
+  nextCursor?: string
+  total?: number
+  limit?: number
+  offset?: number
+}
+
+type TableProcedures<TRow, TCreate, TUpdate> = {
+  list: {
+    call(input?: Record<string, unknown>): Promise<TableListResult<TRow>>
+  }
+  get: { call(input: { id: string }): Promise<TRow> }
+  create: { call(input: TCreate): Promise<TRow> }
+  update: {
+    call(input: {
+      params: { id: string }
+      query: {}
+      headers: {}
+      body: TUpdate
+    }): Promise<TRow>
+  }
+  delete: { call(input: { id: string }): Promise<void> }
+}
+
+export type DirectTableApi<TRow, TCreate, TUpdate> = {
+  list(input?: Record<string, unknown>): Promise<TableListResult<TRow>>
+  get(id: string | number): Promise<TRow>
+  create(input: TCreate): Promise<TRow>
+  update(id: string | number, input: TUpdate): Promise<TRow>
+  delete(id: string | number): Promise<void>
+}
 
 export type TableCollectionConfig = {
   tableName: string
-  baseUrl: string
-  fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  procedures: TableProcedures<any, any, any>
   queryClient: QueryClient
   /** Rows the default `.collection` syncs per fetch. Defaults to 100. For
    * feed-shaped tables that need real pagination use `scopedCollection`. */
@@ -31,8 +62,9 @@ export type ScopedFilterValue =
 
 export type ScopedCollectionOptions = {
   /** Equality filters, e.g. `{ replyToId: null }` — columns must be in the
-   * table's `filterableColumns` server-side. */
-  filter?: Record<string, ScopedFilterValue>
+   * table's `filterableColumns` server-side. Same name and shape as the
+   * `filters` accepted by the list procedure. */
+  filters?: Record<string, ScopedFilterValue>
   sort?: string
   order?: 'asc' | 'desc'
   /** Rows per underlying request; clamped to the server cap (200). */
@@ -43,9 +75,9 @@ export type ScopedCollectionOptions = {
 
 function matchesFilter(
   record: Record<string, unknown>,
-  filter: Record<string, ScopedFilterValue>,
+  filters: Record<string, ScopedFilterValue>,
 ): boolean {
-  for (const [col, expected] of Object.entries(filter)) {
+  for (const [col, expected] of Object.entries(filters)) {
     const actual = record[col]
     if (expected === null) {
       if (actual != null) return false
@@ -71,48 +103,98 @@ export function createTableCollection<
   TCreate = Partial<TRow>,
   TUpdate = Partial<TRow>,
 >(config: TableCollectionConfig) {
-  const table = createTableClient<TRow, TCreate, TUpdate>({
-    tableName: config.tableName,
-    baseUrl: config.baseUrl,
-    fetch: config.fetch,
-  })
+  const table = config.procedures as TableProcedures<TRow, TCreate, TUpdate>
+  const direct: DirectTableApi<TRow, TCreate, TUpdate> = {
+    list: (input = {}) => table.list.call(input),
+    get: (id) => table.get.call({ id: String(id) }),
+    create: (input) => table.create.call(input),
+    update: (id, input) =>
+      table.update.call({
+        params: { id: String(id) },
+        query: {},
+        headers: {},
+        body: input,
+      }),
+    delete: (id) => table.delete.call({ id: String(id) }),
+  }
 
   const collection = createCollection(
     queryCollectionOptions<TRow>({
       queryKey: [config.tableName, 'collection'],
       queryFn: async () => {
-        const page = await table.list({ limit: config.limit ?? 100 })
+        const page = await table.list.call({ 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>)
+        let reconciled = true
+        for (const mutation of transaction.mutations) {
+          // 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`.
+          const row = (await table.create.call(
+            mutation.modified as unknown as TCreate,
+          )) as TRow | undefined
+          // Apps that DO restrict it that way get a server-assigned id, which
+          // leaves the optimistic row keyed under the client's — `writeUpsert`
+          // can't retire that, so those fall back to the refetch.
+          if (row?.id != null && String(row.id) === String(mutation.key)) {
+            applyRealtimeEvent('create', row as Record<string, unknown>)
+          } else {
+            reconciled = false
+          }
+        }
+        return reconciled ? { refetch: false } : {}
       },
       onUpdate: async ({ transaction }) => {
-        const mutation = transaction.mutations[0]!
-        await table.update(
-          mutation.key as string | number,
-          mutation.changes as unknown as TUpdate,
+        await Promise.all(
+          transaction.mutations.map((mutation) =>
+            updateQueue.enqueue(
+              mutation.key as TRow['id'],
+              mutation.changes as Record<string, unknown>,
+            ),
+          ),
         )
+        return { refetch: false }
       },
       onDelete: async ({ transaction }) => {
-        const mutation = transaction.mutations[0]!
-        await table.delete(mutation.key as string | number)
+        for (const mutation of transaction.mutations) {
+          // Updates still queued for this row are superseded, and one already
+          // in flight must land before the DELETE or the two race.
+          await updateQueue.settle(mutation.key as TRow['id'])
+          await table.delete.call({ id: String(mutation.key) })
+          applyRealtimeEvent('delete', { id: mutation.key })
+        }
+        return { refetch: false }
       },
     }),
   )
 
+  // Cursor-shaped workloads call `update()` many times a second. The queue
+  // merges everything that piles up for a row while its request is in flight
+  // into a single follow-up, so request rate tracks RTT, not call rate.
+  const updateQueue = createUpdateQueue<TRow['id'], TRow>({
+    send: (id, changes) =>
+      table.update.call({
+        params: { id: String(id) },
+        query: {},
+        headers: {},
+        body: changes as unknown as TUpdate,
+      }),
+    onResult: async (row) => {
+      // `writeUpsert` writes the response whole, so mutation endpoints are
+      // contracted to return a full row. A body without an id can't be
+      // reconciled locally — fall back to the refetch rather than write it.
+      if ((row as TRow | undefined)?.id == null)
+        await collection.utils.refetch()
+      else applyRealtimeEvent('update', row as Record<string, unknown>)
+    },
+  })
+
   type Collection = typeof collection
 
   // Scoped/byIds collections register here so realtime events fan out to
@@ -144,9 +226,9 @@ export function createTableCollection<
       MAX_LIST_LIMIT,
     )
     const initialCount = options.initialCount ?? 20
-    const filter = options.filter ?? {}
+    const filters = options.filters ?? {}
     const cacheKey = stableKey({
-      filter,
+      filters,
       sort: options.sort ?? null,
       order: options.order ?? null,
       pageSize,
@@ -172,11 +254,10 @@ export function createTableCollection<
           let more = false
           while (items.length < desiredCount) {
             const remaining = Math.min(pageSize, desiredCount - items.length)
-            const page = await table.list({
-              ...filter,
+            const page = await table.list.call({
+              ...(Object.keys(filters).length ? { filters } : {}),
               ...(options.sort ? { sort: options.sort } : {}),
               ...(options.order ? { order: options.order } : {}),
-              cursorMode: true,
               limit: remaining,
               ...(cursor ? { cursor } : {}),
             })
@@ -204,7 +285,7 @@ export function createTableCollection<
     }
     registry.push({
       collection: scoped,
-      matches: (record) => matchesFilter(record, filter),
+      matches: (record) => matchesFilter(record, filters),
       refetch: async () => {
         await scoped.utils.refetch()
       },
@@ -235,8 +316,8 @@ export function createTableCollection<
           // 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,
+            const page = await table.list.call({
+              filters: { [column]: chunk },
               limit: chunk.length,
             })
             items.push(...page.items)
@@ -281,7 +362,7 @@ export function createTableCollection<
     for (const entry of registry) apply(entry.collection, entry.matches)
   }
 
-  /** Refetch the base collection plus every scoped/byIds view (gap recovery). */
+  /** Refetch the base collection plus every scoped/byIds view after reconnect. */
   async function refetchAll() {
     await Promise.all([
       collection.utils.refetch(),
@@ -291,7 +372,7 @@ export function createTableCollection<
 
   return {
     collection,
-    table: table as TableClient<TRow, TCreate, TUpdate>,
+    table: direct,
     scopedCollection,
     collectionByIds,
     applyRealtimeEvent,
@@ -322,7 +403,7 @@ export type TableCollection<
     Record<string, any>,
     StandardSchema<TRow>
   >
-  table: TableClient<TRow, TCreate, TUpdate>
+  table: DirectTableApi<TRow, TCreate, TUpdate>
   scopedCollection: (
     options?: ScopedCollectionOptions,
   ) => ScopedCollection<TRow>

package/src/index.ts

@@ -1,137 +1,7 @@
-import type { QueryClient } from '@tanstack/react-query'
-
-import {
-  createBunderstackQueryClient,
-  type FilesQueryClient,
-  BunderstackApiError,
-  type InferSelect,
-  type InferInsert,
-  type UploadedFile,
-} from 'bunderstack-query'
-
-import type { CreateFor, RowFor } from './sync-client'
-
-import { createTableCollection, type TableCollection } from './collection'
-import { createSyncRealtimeClient } from './realtime-sync'
-
-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 type { BunderstackSyncClient, CreateFor, RowFor, SyncClientOptions } from './sync-client'
 export { createTableCollection } from './collection'
-export type {
-  ScopedCollectionOptions,
-  ScopedFilterValue,
-  TableCollection,
-  TableCollectionConfig,
-} 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'
+export type { AnyBunderstackApp, InferBuckets, InferInsert, InferSchema, InferSelect, InferTables, UploadedFile } from 'bunderstack-query'

package/src/realtime-sync.ts

@@ -1,6 +1,9 @@
 import type { QueryClient } from '@tanstack/react-query'
-
-import { createRealtimeClient, type RealtimeEvent } from 'bunderstack-query'
+import {
+  syncRealtime,
+  type RealtimeQueryApi,
+  type RealtimeSyncHandle,
+} from 'bunderstack-query'
 
 type SyncableCollection = {
   utils: {
@@ -10,7 +13,6 @@ type SyncableCollection = {
   }
 }
 
-/** A table bundle the resolver mode routes events into (see collection.ts). */
 export type SyncRealtimeTarget = {
   applyRealtimeEvent: (
     action: 'create' | 'update' | 'delete',
@@ -20,54 +22,40 @@ export type SyncRealtimeTarget = {
 }
 
 export type SyncRealtimeConfig = {
-  baseUrl: string
+  api: RealtimeQueryApi
   queryClient: QueryClient
-  fetch?: typeof fetch
-  /** Static map of table name -> the collection that table's rows sync into. */
+  tables: string[]
   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>
+  retryMs?: number
 }
 
-export function createSyncRealtimeClient(config: SyncRealtimeConfig) {
-  const staticCollections = config.collections ?? {}
-  const tables = Object.keys(staticCollections)
-
-  return createRealtimeClient({
-    baseUrl: config.baseUrl,
+export function createSyncRealtimeClient(
+  config: SyncRealtimeConfig,
+): RealtimeSyncHandle {
+  const collections = config.collections ?? {}
+  return syncRealtime({
+    api: config.api,
     queryClient: config.queryClient,
-    tables,
-    fetch: config.fetch,
-    applyEvent: (evt: RealtimeEvent) => {
+    tables: config.tables,
+    retryMs: config.retryMs,
+    onChange: (event) => {
       if (config.resolve) {
-        config.resolve(evt.table)?.applyRealtimeEvent(evt.action, evt.record)
+        config.resolve(event.table)?.applyRealtimeEvent(event.action, event.record)
         return
       }
-      const collection = staticCollections[evt.table]
+      const collection = collections[event.table]
       if (!collection) return
-      if (evt.action === 'delete') {
-        collection.utils.writeDelete(evt.record['id'])
-      } else {
-        collection.utils.writeUpsert(evt.record)
-      }
+      if (event.action === 'delete') collection.utils.writeDelete(event.record['id'])
+      else collection.utils.writeUpsert(event.record)
     },
-    onGap: () => {
+    onReconnect: async () => {
       if (config.resolveAll) {
-        for (const target of config.resolveAll()) {
-          target.refetchAll().catch((err) => {
-            console.error('bunderstack-sync: gap-recovery refetch failed', err)
-          })
-        }
+        await Promise.all([...config.resolveAll()].map((target) => target.refetchAll()))
         return
       }
-      for (const collection of Object.values(staticCollections)) {
-        collection.utils.refetch().catch((err) => {
-          console.error('bunderstack-sync: gap-recovery refetch failed', err)
-        })
-      }
+      await Promise.all(Object.values(collections).map((collection) => collection.utils.refetch()))
     },
   })
 }

package/src/sync-client.ts

@@ -1,12 +1,8 @@
 import type { QueryClient } from '@tanstack/react-query'
-
 import {
-  attachBucketMutationOptions,
-  createBucketClient,
-  lazyRecord,
+  createClient,
   type AnyBunderstackApp,
-  type FilesQueryClient,
-  type InferBuckets,
+  type BunderstackClient,
   type InferInsert,
   type InferSchema,
   type InferSelect,
@@ -14,32 +10,27 @@ import {
 } from 'bunderstack-query'
 
 import { createTableCollection, type TableCollection } from './collection'
-import {
-  createSyncRealtimeClient,
-  type SyncRealtimeTarget,
-} from './realtime-sync'
+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 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 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>
+  fetch?: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Promise<Response>
   queryClient: QueryClient
-  /** Live SSE updates. Defaults to true in the browser, false during SSR. */
   realtime?: boolean
 }
 
@@ -49,80 +40,58 @@ export type BunderstackSyncClient<TApp extends AnyBunderstackApp> = {
     CreateFor<InferSchema<TApp>, K>,
     Partial<RowFor<InferSchema<TApp>, K>>
   >
-} & FilesQueryClient<InferBuckets<TApp>> & {
-    realtime: ReturnType<typeof createSyncRealtimeClient> | undefined
-  }
+} & {
+  files: BunderstackClient<TApp>['files']
+  realtime: { close(): void; subscribe(tables: string[]): Promise<void> } | 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 api = createClient<TApp>(options)
   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 realtimeHandles = new Map<string, { close(): void }>()
+  const tables = new Map<string, unknown>()
   const realtimeEnabled = options.realtime ?? typeof window !== 'undefined'
-  const realtime = realtimeEnabled
-    ? createSyncRealtimeClient({
-        baseUrl,
+
+  const result = new Proxy({} as BunderstackSyncClient<TApp>, {
+    get(_target, property) {
+      if (typeof property !== 'string') return undefined
+      if (property === 'files') return api.files
+      if (property === 'realtime') {
+        return realtimeEnabled
+          ? {
+              close: () => realtimeHandles.forEach((handle) => handle.close()),
+              subscribe: async (names: string[]) => {
+                for (const name of names) void (result as any)[name]
+              },
+            }
+          : undefined
+      }
+      if (['then', 'toJSON', 'constructor', '$$typeof'].includes(property)) return undefined
+      const cached = tables.get(property)
+      if (cached) return cached
+      const collection = createTableCollection({
+        tableName: property,
+        procedures: (api as any)[property],
         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'
+      tables.set(property, collection)
+      materialized.set(property, collection)
+      if (realtimeEnabled) {
+        realtimeHandles.set(
+          property,
+          createSyncRealtimeClient({
+            api: api as any,
+            queryClient: options.queryClient,
+            tables: [property],
+            resolve: (table) => materialized.get(table),
+            resolveAll: () => materialized.values(),
+          }),
+        )
+      }
+      return collection
     },
-  }) as BunderstackSyncClient<TApp>
+  })
+  return result
 }

package/src/update-queue.ts

@@ -0,0 +1,93 @@
+/** Per-key coalescing queue for high-frequency row updates.
+ *
+ * Cursor-shaped workloads call `collection.update()` many times a second. Sent
+ * one-for-one, each call is a request, a database write and a broadcast. This
+ * queue holds a single merged slot per row key: while a request is in flight,
+ * further updates for that key merge into the slot and go out as one follow-up
+ * once it lands. Request frequency settles at `min(update rate, 1/RTT)` without
+ * a tuned throttle constant, and the optimistic UI is untouched — only the
+ * network is coalesced.
+ */
+
+type Waiter = {
+  resolve: () => void
+  reject: (error: unknown) => void
+}
+
+type Slot = {
+  changes: Record<string, unknown>
+  waiters: Waiter[]
+  /** Promise of the running drain loop; never rejects. */
+  done: Promise<void> | null
+}
+
+export type UpdateQueueConfig<TKey, TRow> = {
+  /** Sends one merged batch of changes and resolves with the canonical row. */
+  send: (key: TKey, changes: Record<string, unknown>) => Promise<TRow>
+  /** Called with the server's row before the batch's waiters resolve. Awaited,
+   * so a handler that needs to recover (refetch) finishes first. */
+  onResult: (row: TRow) => void | Promise<void>
+}
+
+export type UpdateQueue<TKey> = {
+  /** Queues changes for `key`. Resolves once a request carrying them lands. */
+  enqueue: (key: TKey, changes: Record<string, unknown>) => Promise<void>
+  /** Drops changes still queued for `key` (resolving their waiters) and waits
+   * for any in-flight request to land. For operations that supersede pending
+   * updates and must not race them — a delete of the same row. */
+  settle: (key: TKey) => Promise<void>
+}
+
+export function createUpdateQueue<TKey, TRow>(
+  config: UpdateQueueConfig<TKey, TRow>,
+): UpdateQueue<TKey> {
+  const slots = new Map<TKey, Slot>()
+
+  async function drain(key: TKey, slot: Slot) {
+    while (Object.keys(slot.changes).length > 0) {
+      // Taking changes and waiters as one snapshot is what guarantees a waiter
+      // resolves only after a request that carried its own changes.
+      const changes = slot.changes
+      const waiters = slot.waiters
+      slot.changes = {}
+      slot.waiters = []
+      try {
+        await config.onResult(await config.send(key, changes))
+        for (const waiter of waiters) waiter.resolve()
+      } catch (error) {
+        // Replaying queued changes on top of a failed base would diverge from
+        // the server silently, so the whole key is rolled back instead.
+        const queued = slot.waiters
+        slot.changes = {}
+        slot.waiters = []
+        for (const waiter of [...waiters, ...queued]) waiter.reject(error)
+      }
+    }
+    slots.delete(key)
+  }
+
+  return {
+    enqueue(key, changes) {
+      let slot = slots.get(key)
+      if (!slot) {
+        slot = { changes: {}, waiters: [], done: null }
+        slots.set(key, slot)
+      }
+      Object.assign(slot.changes, changes)
+      const promise = new Promise<void>((resolve, reject) => {
+        slot!.waiters.push({ resolve, reject })
+      })
+      if (!slot.done) slot.done = drain(key, slot)
+      return promise
+    },
+    settle(key) {
+      const slot = slots.get(key)
+      if (!slot) return Promise.resolve()
+      const waiters = slot.waiters
+      slot.changes = {}
+      slot.waiters = []
+      for (const waiter of waiters) waiter.resolve()
+      return slot.done ?? Promise.resolve()
+    },
+  }
+}