bunderstack-query 0.1.0

package/src/lazy-client.ts

@@ -0,0 +1,136 @@
+import type { AnyRouter } from '@trpc/server'
+import type { TRPCOptionsProxy } from '@trpc/tanstack-react-query'
+
+import { QueryClient } from '@tanstack/react-query'
+import { createTRPCClient, httpBatchLink } from '@trpc/client'
+import { createTRPCOptionsProxy } from '@trpc/tanstack-react-query'
+import superjson from 'superjson'
+
+import type {
+  AnyBunderstackApp,
+  InferBuckets,
+  InferSchema,
+  InferTables,
+  InferTrpcRouter,
+} from './infer'
+import type { FilesQueryClient, TableQueryOptionsForKey } from './types'
+
+import {
+  attachBucketMutationOptions,
+  createBucketClient,
+} from './bucket-client'
+import { attachMutationOptions } from './mutation-options'
+import { createTableClient } from './table-client'
+
+export type ClientOptions = {
+  baseUrl?: string
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  queryClient?: QueryClient
+}
+
+export type BunderstackClient<TApp extends AnyBunderstackApp> = {
+  [K in InferTables<TApp>]: TableQueryOptionsForKey<InferSchema<TApp>, K>
+} & FilesQueryClient<InferBuckets<TApp>> &
+  ([InferTrpcRouter<TApp>] extends [never]
+    ? unknown
+    : { trpc: TRPCOptionsProxy<InferTrpcRouter<TApp>> })
+
+/** Props a lazy Proxy must not materialize (await/introspection probes). */
+const PROXY_SKIP = new Set<string>([
+  'then',
+  'toJSON',
+  'constructor',
+  '$$typeof',
+])
+
+/**
+ * Record whose values are created on first property access and cached, so
+ * repeated reads return the same instance. Keys are open-ended — the caller's
+ * type layer constrains which keys are valid. Note `Object.keys()` on the
+ * result is empty by design.
+ */
+export function lazyRecord<T>(create: (key: string) => T): Record<string, T> {
+  const cache = new Map<string, T>()
+  return new Proxy({} as Record<string, T>, {
+    get(_target, prop) {
+      if (typeof prop !== 'string' || PROXY_SKIP.has(prop)) return undefined
+      let value = cache.get(prop)
+      if (value === undefined) {
+        value = create(prop)
+        cache.set(prop, value)
+      }
+      return value
+    },
+    has(_target, prop) {
+      return typeof prop === 'string' && !PROXY_SKIP.has(prop)
+    },
+  })
+}
+
+/**
+ * Fully typed client inferred from the server app — tables and buckets come
+ * from `typeof app`, materialized lazily on first property access. No
+ * runtime table/bucket lists, and no server code in the bundle (the app is
+ * referenced as a type only).
+ *
+ * @example
+ * import type { App } from './bunderstack'   // type-only import
+ * const api = createClient<App>({ queryClient })
+ * api.posts.list(); api.files.images.upload(file)
+ */
+export function createClient<TApp extends AnyBunderstackApp>(
+  options: ClientOptions = {},
+): BunderstackClient<TApp> {
+  const baseUrl = options.baseUrl ?? '/api'
+  const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+
+  const files = lazyRecord((bucket) => {
+    const bucketClient = createBucketClient({ bucket, baseUrl, fetch: fetchFn })
+    return {
+      ...bucketClient,
+      ...attachBucketMutationOptions(bucketClient, options.queryClient),
+    }
+  })
+
+  const tables = lazyRecord((tableName) => {
+    const tableClient = createTableClient({
+      tableName,
+      baseUrl,
+      fetch: fetchFn,
+    })
+    return {
+      ...tableClient,
+      ...attachMutationOptions(tableClient, options.queryClient),
+    }
+  })
+
+  // Lazily built so apps without a trpc router pay nothing.
+  let trpcProxy: unknown
+  const getTrpc = () => {
+    trpcProxy ??= createTRPCOptionsProxy({
+      client: createTRPCClient<AnyRouter>({
+        links: [
+          httpBatchLink({
+            url: `${baseUrl}/trpc`,
+            transformer: superjson,
+            fetch: fetchFn,
+          }),
+        ],
+      }),
+      queryClient: options.queryClient ?? new QueryClient(),
+    })
+    return trpcProxy
+  }
+
+  return new Proxy({} as BunderstackClient<TApp>, {
+    get(_target, prop) {
+      if (typeof prop !== 'string' || PROXY_SKIP.has(prop)) return undefined
+      if (prop === 'files') return files
+      if (prop === 'trpc') return getTrpc()
+      return (tables as Record<string, unknown>)[prop]
+    },
+    has(_target, prop) {
+      return typeof prop === 'string' && !PROXY_SKIP.has(prop)
+    },
+  }) as BunderstackClient<TApp>
+}

package/src/mutation-options.ts

@@ -0,0 +1,73 @@
+import type { QueryClient, UseMutationOptions } from '@tanstack/react-query'
+
+import type { TableClient } from './table-client'
+
+export type TableMutationOptions<TRow, TCreate, TUpdate> = {
+  createMutation: (
+    options?: Omit<
+      UseMutationOptions<TRow, Error, Partial<TCreate>>,
+      'mutationFn'
+    >,
+  ) => UseMutationOptions<TRow, Error, Partial<TCreate>>
+  updateMutation: (
+    options?: Omit<
+      UseMutationOptions<TRow, Error, { id: string | number; data: TUpdate }>,
+      'mutationFn'
+    >,
+  ) => UseMutationOptions<TRow, Error, { id: string | number; data: TUpdate }>
+  deleteMutation: (
+    options?: Omit<
+      UseMutationOptions<void, Error, string | number>,
+      'mutationFn'
+    >,
+  ) => UseMutationOptions<void, Error, string | number>
+}
+
+export function attachMutationOptions<TRow, TCreate, TUpdate>(
+  table: TableClient<TRow, TCreate, TUpdate>,
+  queryClient?: QueryClient,
+): TableMutationOptions<TRow, TCreate, TUpdate> {
+  const invalidate = () => {
+    if (queryClient)
+      void queryClient.invalidateQueries({ queryKey: table.keys.all })
+  }
+
+  return {
+    createMutation(options = {}) {
+      const { onSuccess, ...rest } = options
+      return {
+        mutationFn: (data: Partial<TCreate>) => table.create(data),
+        onSuccess: (data, variables, context, mutation) => {
+          invalidate()
+          onSuccess?.(data, variables, context, mutation)
+        },
+        ...rest,
+      }
+    },
+    updateMutation(options = {}) {
+      const { onSuccess, ...rest } = options
+      return {
+        mutationFn: ({ id, data }: { id: string | number; data: TUpdate }) =>
+          table.update(id, data),
+        onSuccess: (data, variables, context, mutation) => {
+          invalidate()
+          if (queryClient)
+            void queryClient.setQueryData(table.keys.detail(variables.id), data)
+          onSuccess?.(data, variables, context, mutation)
+        },
+        ...rest,
+      }
+    },
+    deleteMutation(options = {}) {
+      const { onSuccess, ...rest } = options
+      return {
+        mutationFn: (id: string | number) => table.delete(id),
+        onSuccess: (data, variables, context, mutation) => {
+          invalidate()
+          onSuccess?.(data, variables, context, mutation)
+        },
+        ...rest,
+      }
+    },
+  }
+}

package/src/react.tsx

@@ -0,0 +1,16 @@
+/**
+ * @deprecated Import from `bunderstack-query` directly — `createBunderstackQueryClient` accepts `queryClient`.
+ */
+export {
+  createBunderstackQueryClient,
+  createBunderstackQueryClient as createBunderstackReactQueryClient,
+  BunderstackApiError,
+} from './index'
+export type {
+  BunderstackQueryClient,
+  BunderstackQueryClient as BunderstackReactQueryClient,
+  Paginated,
+  ListParams,
+  InferSelect,
+  InferInsert,
+} from './types'

package/src/realtime-client.ts

@@ -0,0 +1,251 @@
+import type { QueryClient } from '@tanstack/query-core'
+
+import { createTableClient } from './table-client'
+
+// ---------------------------------------------------------------------------
+// Transport choice: custom fetch + ReadableStream SSE reader (NOT EventSource).
+//
+// Why not native EventSource?
+//  - Its reconnect is opaque and browser-throttled. Backgrounded/throttled tabs
+//    are exactly where it stalls — the failure we are fixing (tab stops updating
+//    until you interact with it).
+//  - We cannot run our own heartbeat watchdog, backoff, or force a reconnect on
+//    `visibilitychange` with EventSource.
+//
+// Why the custom reader?
+//  - We own reconnect (explicit backoff), a heartbeat watchdog (no bytes within
+//    ~1.5x keepalive => tear down + reconnect), and visibility-driven reconnect.
+//
+// Cost / when to reconsider: more code than `new EventSource(url)`, and we must
+// parse SSE frames ourselves. If real-world testing shows native EventSource is
+// adequate, the previous implementation was: `new EventSource(`${root}/realtime`,
+// { withCredentials: true })` with `es.onmessage` doing the same `apply()` and a
+// `postSubscribe` on the connect frame. Swap the connect loop below back to that.
+// ---------------------------------------------------------------------------
+
+export type RealtimeEvent = {
+  eventId: number
+  action: 'create' | 'update' | 'delete'
+  table: string
+  record: Record<string, unknown>
+}
+
+export type RealtimeStatus = 'connecting' | 'open' | 'reconnecting' | 'closed'
+
+export type RealtimeClientConfig = {
+  baseUrl: string
+  queryClient: QueryClient
+  tables: string[]
+  fetch?: typeof fetch
+  /**
+   * How often the server sends a keepalive ping (milliseconds). Defaults to 30 000.
+   *
+   * INVARIANT: this value MUST be >= the server's `realtime.keepaliveMs`.
+   * The client watchdog fires at ~1.5× keepaliveMs; if this is set lower than
+   * the server's interval, the watchdog reconnects before the server's ping
+   * arrives and causes a reconnect storm.
+   */
+  keepaliveMs?: number
+  onStatus?: (s: RealtimeStatus) => void
+  /**
+   * Override how an event is applied to local state. Defaults to patching
+   * the TanStack Query cache (setQueryData on detail key + invalidateQueries
+   * on the list key). Set this to integrate with a different local store
+   * (e.g. a TanStack DB collection's direct-write API).
+   */
+  applyEvent?: (evt: RealtimeEvent) => void
+  /**
+   * Override full-resync-on-gap behavior. Defaults to invalidating every
+   * subscribed table's list query.
+   */
+  onGap?: () => void
+}
+
+export function createRealtimeClient(config: RealtimeClientConfig) {
+  const { baseUrl, queryClient, tables } = config
+  const fetchFn = config.fetch ?? fetch
+  const keepaliveMs = config.keepaliveMs ?? 30000
+  const root = baseUrl.replace(/\/$/, '')
+
+  const keysByTable = new Map(
+    tables.map((t) => [
+      t,
+      createTableClient({ tableName: t, baseUrl: root, fetch: fetchFn }).keys,
+    ]),
+  )
+
+  let clientId: string | null = null
+  let lastTopics: string[] = []
+  let lastEventId: number | null = null
+  let closed = false
+  let abort: AbortController | null = null
+  let backoff = 1000
+  let watchdog: ReturnType<typeof setTimeout> | null = null
+  let backoffTimer: ReturnType<typeof setTimeout> | null = null
+
+  function setStatus(s: RealtimeStatus) {
+    config.onStatus?.(s)
+  }
+
+  function apply(evt: RealtimeEvent) {
+    if (typeof evt.eventId === 'number') lastEventId = evt.eventId
+    // A custom applyEvent owns routing entirely — lazy clients can't
+    // enumerate tables upfront, so don't gate on the static list.
+    if (config.applyEvent) {
+      config.applyEvent(evt)
+      return
+    }
+    const keys = keysByTable.get(evt.table)
+    if (!keys) return
+    const id = evt.record['id'] as string | number
+    if (evt.action === 'delete')
+      queryClient.removeQueries({ queryKey: keys.detail(id) })
+    else queryClient.setQueryData(keys.detail(id), evt.record)
+    queryClient.invalidateQueries({ queryKey: keys.lists() })
+  }
+
+  function invalidateAllSubscribed() {
+    if (config.onGap) {
+      config.onGap()
+      return
+    }
+    for (const t of tables) {
+      const keys = keysByTable.get(t)
+      if (keys) queryClient.invalidateQueries({ queryKey: keys.lists() })
+    }
+  }
+
+  async function postSubscribe(topics: string[]) {
+    if (!clientId) return
+    const res = await fetchFn(`${root}/realtime`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        clientId,
+        subscriptions: topics,
+        since: lastEventId,
+      }),
+    })
+    const body = (await res.json().catch(() => ({}))) as { gap?: boolean }
+    if (body.gap) invalidateAllSubscribed()
+  }
+
+  function armWatchdog() {
+    if (watchdog) clearTimeout(watchdog)
+    // No bytes (event or `: ping`) within 1.5x keepalive => assume dead, reconnect.
+    watchdog = setTimeout(
+      () => {
+        abort?.abort()
+      },
+      Math.round(keepaliveMs * 1.5),
+    )
+  }
+
+  function handleFrame(frame: string) {
+    armWatchdog()
+    // Comment lines (": ping") are liveness only.
+    const dataLines = frame.split('\n').filter((l) => l.startsWith('data:'))
+    if (!dataLines.length) return
+    const json = dataLines.map((l) => l.slice(5).trim()).join('\n')
+    let data: unknown
+    try {
+      data = JSON.parse(json)
+    } catch {
+      return
+    }
+    if (
+      data &&
+      typeof data === 'object' &&
+      'clientId' in data &&
+      (data as any).clientId
+    ) {
+      clientId = (data as any).clientId
+      if (lastTopics.length) void postSubscribe(lastTopics)
+      return
+    }
+    apply(data as RealtimeEvent)
+  }
+
+  async function connectLoop() {
+    while (!closed) {
+      abort = new AbortController()
+      setStatus(clientId ? 'reconnecting' : 'connecting')
+      try {
+        const res = await fetchFn(`${root}/realtime`, {
+          credentials: 'include',
+          headers: { Accept: 'text/event-stream' },
+          signal: abort.signal,
+        })
+        if (!res.body) throw new Error('no body')
+        setStatus('open')
+        backoff = 1000
+        armWatchdog()
+        const reader = res.body.getReader()
+        const decoder = new TextDecoder()
+        let buf = ''
+        for (;;) {
+          const { value, done } = await reader.read()
+          if (done) break
+          buf += decoder.decode(value, { stream: true })
+          let idx: number
+          while ((idx = buf.indexOf('\n\n')) !== -1) {
+            const frame = buf.slice(0, idx)
+            buf = buf.slice(idx + 2)
+            handleFrame(frame)
+          }
+        }
+      } catch {
+        /* fallthrough to reconnect */
+      }
+      if (watchdog) {
+        clearTimeout(watchdog)
+        watchdog = null
+      }
+      if (closed) break
+      // Reconnect with jittered backoff (cap 30s). lastEventId drives replay.
+      const wait = Math.min(backoff, 30000) * (0.5 + Math.random())
+      backoff = Math.min(backoff * 2, 30000)
+      await new Promise<void>((r) => {
+        backoffTimer = setTimeout(r, wait)
+      })
+      backoffTimer = null
+    }
+    setStatus('closed')
+  }
+
+  // Refocus => force an immediate reconnect + catch-up (no waiting on backoff).
+  const onVisible = () => {
+    if (closed) return
+    if (document.visibilityState === 'visible') {
+      backoff = 1000
+      abort?.abort()
+    }
+  }
+  if (typeof document !== 'undefined')
+    document.addEventListener('visibilitychange', onVisible)
+
+  void connectLoop()
+
+  return {
+    async subscribe(topics: string[]) {
+      lastTopics = topics
+      await postSubscribe(topics)
+    },
+    close() {
+      closed = true
+      if (watchdog) {
+        clearTimeout(watchdog)
+        watchdog = null
+      }
+      if (backoffTimer) {
+        clearTimeout(backoffTimer)
+        backoffTimer = null
+      }
+      if (typeof document !== 'undefined')
+        document.removeEventListener('visibilitychange', onVisible)
+      abort?.abort()
+      setStatus('closed')
+    },
+  }
+}

package/src/table-client.ts

@@ -0,0 +1,145 @@
+import type { ListParams, Paginated } from './types'
+
+import { BunderstackApiError } from './errors'
+
+/**
+ * Server-side cap on any single list request — mirrors MAX_LIST_LIMIT in
+ * packages/bunderstack/src/list-query.ts (parity enforced by test).
+ */
+export const MAX_LIST_LIMIT = 200
+
+const RESERVED_LIST_PARAMS = new Set([
+  'limit',
+  'offset',
+  'sort',
+  'order',
+  'q',
+  'cursor',
+  'count',
+  'cursorMode',
+])
+
+export type TableClientConfig = {
+  tableName: string
+  baseUrl: string
+  fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+}
+
+async function parseError(res: Response): Promise<BunderstackApiError> {
+  const body = await res.json().catch(() => ({}))
+  const message =
+    typeof body === 'object' &&
+    body !== null &&
+    'error' in body &&
+    typeof body.error === 'string'
+      ? body.error
+      : `Request failed (${res.status})`
+  return new BunderstackApiError(message, res.status, body)
+}
+
+export function createTableClient<
+  TRow,
+  TCreate = Partial<TRow>,
+  TUpdate = Partial<TRow>,
+>(config: TableClientConfig) {
+  const { tableName, baseUrl, fetch: fetchFn } = config
+  const root = `${baseUrl.replace(/\/$/, '')}/${tableName}`
+
+  const keys = {
+    all: [tableName] as const,
+    lists: () => [tableName, 'list'] as const,
+    list: (params: ListParams) => [tableName, 'list', params] as const,
+    details: () => [tableName, 'detail'] as const,
+    detail: (id: string | number) => [tableName, 'detail', id] as const,
+  }
+
+  async function request<T>(path: string, init?: RequestInit): Promise<T> {
+    const res = await fetchFn(`${root}${path}`, {
+      credentials: 'include',
+      ...init,
+      headers: {
+        ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
+        ...init?.headers,
+      },
+    })
+
+    if (!res.ok) throw await parseError(res)
+    if (res.status === 204) return undefined as T
+    return res.json() as Promise<T>
+  }
+
+  const list = (params: ListParams = {}) => {
+    const qs = new URLSearchParams()
+
+    if (params.limit !== undefined) qs.set('limit', String(params.limit))
+    if (params.offset !== undefined) qs.set('offset', String(params.offset))
+    if (params.sort) qs.set('sort', params.sort)
+    if (params.order) qs.set('order', params.order)
+    if (params.q?.trim()) qs.set('q', params.q.trim())
+    if (params.cursor) qs.set('cursor', params.cursor)
+    if (params.count) qs.set('count', 'true')
+
+    for (const [key, value] of Object.entries(params)) {
+      if (RESERVED_LIST_PARAMS.has(key)) continue
+      if (value === undefined) continue
+      qs.set(key, value === null ? 'null' : String(value))
+    }
+
+    if (!qs.has('limit')) qs.set('limit', '20')
+    if (!qs.has('offset') && !qs.has('cursor') && !params.cursorMode) {
+      qs.set('offset', '0')
+    }
+
+    return request<Paginated<TRow>>(`?${qs}`)
+  }
+
+  const listInfiniteQuery = (params: ListParams = {}) => {
+    const {
+      offset: _offset,
+      cursor: _cursor,
+      cursorMode: _cursorMode,
+      ...base
+    } = params
+    return {
+      queryKey: [...keys.list(params), 'infinite'] as const,
+      queryFn: ({ pageParam }: { pageParam: string | undefined }) =>
+        list({
+          ...base,
+          cursorMode: true,
+          ...(pageParam ? { cursor: pageParam } : {}),
+        }),
+      initialPageParam: undefined as string | undefined,
+      getNextPageParam: (lastPage: Paginated<TRow>) =>
+        lastPage.nextCursor ?? undefined,
+    }
+  }
+
+  const get = (id: string | number) => request<TRow>(`/${id}`)
+
+  return {
+    keys,
+    list,
+    get,
+    create: (data: Partial<TCreate>) =>
+      request<TRow>('', { method: 'POST', body: JSON.stringify(data) }),
+    update: (id: string | number, data: TUpdate) =>
+      request<TRow>(`/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
+    delete: (id: string | number) =>
+      request<void>(`/${id}`, { method: 'DELETE' }),
+    listQuery: (params: ListParams = {}) => ({
+      queryKey: keys.list(params),
+      queryFn: () => list(params),
+    }),
+    listInfiniteQuery,
+    getQuery: (id: string | number) => ({
+      queryKey: keys.detail(id),
+      queryFn: () => get(id),
+    }),
+  }
+}
+
+export type TableClient<
+  TRow,
+  TCreate = Partial<TRow>,
+  TUpdate = Partial<TRow>,
+> = ReturnType<typeof createTableClient<TRow, TCreate, TUpdate>>