bunderstack-query 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,36 @@
+# bunderstack-query
+
+Typed client for [bunderstack](https://github.com/kirill-dev-pro/bunderstack)
+backends: tRPC client, TanStack Query option factories, realtime
+subscriptions, and React hooks.
+
+```sh
+bun add bunderstack-query
+```
+
+```ts
+import { createClient } from 'bunderstack-query'
+import type { App } from '../server/app'
+
+const client = createClient<App>({ baseUrl: '/api' })
+```
+
+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`/`.tsx`
+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-query",
+  "version": "0.1.0",
+  "description": "Typed client for bunderstack backends: tRPC client, TanStack Query option factories, realtime subscriptions, and React hooks.",
+  "keywords": [
+    "bun",
+    "bunderstack",
+    "client",
+    "react",
+    "realtime",
+    "tanstack-query",
+    "trpc"
+  ],
+  "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-query"
+  },
+  "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",
+    "./react": "./src/react.tsx"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@trpc/client": "^11.0.0",
+    "@trpc/server": "^11.0.0",
+    "@trpc/tanstack-react-query": "^11.0.0",
+    "bunderstack": "0.1.0",
+    "superjson": "^2.2.0"
+  },
+  "devDependencies": {
+    "@tanstack/query-core": "^5.101.1",
+    "@tanstack/react-query": "^5.101.1",
+    "@types/bun": "^1.3.14",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.0",
+    "typescript": "^5"
+  }
+}

package/src/bucket-client.ts

@@ -0,0 +1,215 @@
+import type { QueryClient, UseMutationOptions } from '@tanstack/react-query'
+
+import { BunderstackApiError } from './errors'
+
+export type UploadedFile = {
+  fileId: string
+  url: string
+  name: string
+}
+
+export type UploadMode = 'auto' | 'proxy' | 'presign'
+
+export type UploadOptions = {
+  mode?: UploadMode
+}
+
+export type FileTransformOptions = {
+  w?: number
+  h?: number
+  format?: 'webp' | 'jpeg' | 'png' | 'avif'
+}
+
+export type BucketClientConfig = {
+  bucket: string
+  baseUrl: string
+  fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+}
+
+type PresignResponse =
+  | {
+      mode: 'proxy'
+      uploadUrl: string
+    }
+  | {
+      mode: 'presign'
+      fileId: string
+      uploadUrl: string
+      method?: string
+      confirmUrl: string
+    }
+
+async function parseError(res: Response): Promise<BunderstackApiError> {
+  const body = await res.json().catch(() => ({}))
+  const message =
+    body &&
+    typeof body === 'object' &&
+    'error' in body &&
+    typeof body.error === 'string'
+      ? body.error
+      : `Request failed (${res.status})`
+  return new BunderstackApiError(message, res.status, body)
+}
+
+async function readJson<T>(res: Response): Promise<T> {
+  if (!res.ok) throw await parseError(res)
+  return res.json() as Promise<T>
+}
+
+function trimBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/$/, '')
+}
+
+function relativeId(bucket: string, idOrFileId: string): string {
+  const prefix = `${bucket}/`
+  return idOrFileId.startsWith(prefix)
+    ? idOrFileId.slice(prefix.length)
+    : idOrFileId
+}
+
+function encodeFilePath(idOrFileId: string): string {
+  return idOrFileId
+    .split('/')
+    .map((segment) =>
+      encodeURIComponent(decodeURIComponent(segment)).replace(/\./g, '%2E'),
+    )
+    .join('/')
+}
+
+function fileUrl(root: string, bucket: string, idOrFileId: string): string {
+  return `${root}/${encodeFilePath(relativeId(bucket, idOrFileId))}`
+}
+
+function contentTypeHeader(file: File): HeadersInit | undefined {
+  return file.type ? { 'Content-Type': file.type } : undefined
+}
+
+export function createBucketClient(config: BucketClientConfig) {
+  const { bucket, fetch: fetchFn } = config
+  const apiRoot = `${trimBaseUrl(config.baseUrl)}/files/${bucket}`
+  const keys = {
+    all: ['files', bucket] as const,
+  }
+
+  async function proxyUpload(file: File): Promise<UploadedFile> {
+    const body = new FormData()
+    body.append('file', file)
+    const res = await fetchFn(apiRoot, {
+      method: 'POST',
+      body,
+      credentials: 'include',
+    })
+    const uploaded = await readJson<{ fileId: string; url: string }>(res)
+    return { ...uploaded, url: url(uploaded.fileId), name: file.name }
+  }
+
+  async function presignUpload(file: File): Promise<UploadedFile> {
+    const presignRes = await fetchFn(`${apiRoot}/presign`, {
+      method: 'POST',
+      body: JSON.stringify({
+        filename: file.name,
+        contentType: file.type || undefined,
+      }),
+      credentials: 'include',
+      headers: { 'Content-Type': 'application/json' },
+    })
+    const presign = await readJson<PresignResponse>(presignRes)
+    if (presign.mode === 'proxy') return proxyUpload(file)
+
+    const uploadRes = await fetchFn(presign.uploadUrl, {
+      method: presign.method ?? 'PUT',
+      body: file,
+      headers: contentTypeHeader(file),
+    })
+    if (!uploadRes.ok) throw await parseError(uploadRes)
+
+    const confirmRes = await fetchFn(`${url(presign.fileId)}/confirm`, {
+      method: 'POST',
+      credentials: 'include',
+    })
+    const uploaded = await readJson<{ fileId: string; url: string }>(confirmRes)
+    return { ...uploaded, url: url(uploaded.fileId), name: file.name }
+  }
+
+  const upload = (file: File, options: UploadOptions = {}) =>
+    options.mode === 'presign' ? presignUpload(file) : proxyUpload(file)
+
+  const deleteFile = async (idOrFileId: string): Promise<void> => {
+    const res = await fetchFn(fileUrl(apiRoot, bucket, idOrFileId), {
+      method: 'DELETE',
+      credentials: 'include',
+    })
+    if (!res.ok) throw await parseError(res)
+  }
+
+  const url = (
+    idOrFileId: string,
+    transforms: FileTransformOptions = {},
+  ): string => {
+    const params = new URLSearchParams()
+    if (transforms.w !== undefined) params.set('w', String(transforms.w))
+    if (transforms.h !== undefined) params.set('h', String(transforms.h))
+    if (transforms.format) params.set('format', transforms.format)
+    const qs = params.toString()
+    return `${fileUrl(apiRoot, bucket, idOrFileId)}${qs ? `?${qs}` : ''}`
+  }
+
+  return {
+    keys,
+    upload,
+    delete: deleteFile,
+    url,
+  }
+}
+
+export type BucketClient = ReturnType<typeof createBucketClient>
+
+export type BucketMutationOptions = {
+  uploadMutation: (
+    options?: Omit<
+      UseMutationOptions<UploadedFile, Error, File, unknown>,
+      'mutationFn'
+    >,
+  ) => UseMutationOptions<UploadedFile, Error, File, unknown>
+  deleteMutation: (
+    options?: Omit<
+      UseMutationOptions<void, Error, string, unknown>,
+      'mutationFn'
+    >,
+  ) => UseMutationOptions<void, Error, string, unknown>
+}
+
+export function attachBucketMutationOptions(
+  bucketClient: BucketClient,
+  queryClient?: QueryClient,
+): BucketMutationOptions {
+  const invalidate = () => {
+    if (queryClient)
+      void queryClient.invalidateQueries({ queryKey: bucketClient.keys.all })
+  }
+
+  return {
+    uploadMutation(options = {}) {
+      const { onSuccess, ...rest } = options
+      return {
+        mutationFn: (file: File) => bucketClient.upload(file),
+        onSuccess: (data, variables, context, mutation) => {
+          invalidate()
+          onSuccess?.(data, variables, context, mutation)
+        },
+        ...rest,
+      }
+    },
+    deleteMutation(options = {}) {
+      const { onSuccess, ...rest } = options
+      return {
+        mutationFn: (id: string) => bucketClient.delete(id),
+        onSuccess: (data, variables, context, mutation) => {
+          invalidate()
+          onSuccess?.(data, variables, context, mutation)
+        },
+        ...rest,
+      }
+    },
+  }
+}

package/src/errors.ts

@@ -0,0 +1,18 @@
+export class BunderstackApiError extends Error {
+  readonly status: number
+  readonly body: unknown
+  readonly code?: string
+  readonly details?: unknown
+
+  constructor(message: string, status: number, body: unknown = undefined) {
+    super(message)
+    this.name = 'BunderstackApiError'
+    this.status = status
+    this.body = body
+    if (body && typeof body === 'object' && body !== null) {
+      const record = body as Record<string, unknown>
+      if (typeof record.code === 'string') this.code = record.code
+      if ('details' in record) this.details = record.details
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,248 @@
+import type { QueryClient } from '@tanstack/react-query'
+
+import {
+  validateAndResolveAccess,
+  type TableAccessInput,
+} from 'bunderstack/access'
+
+import type {
+  BunderstackQueryClient,
+  CrudTableKey,
+  FilesQueryClient,
+  InferInsert,
+  InferSelect,
+  TableQueryOptions,
+} from './types'
+
+import {
+  attachBucketMutationOptions,
+  createBucketClient,
+} from './bucket-client'
+import { attachMutationOptions } from './mutation-options'
+import { createTableClient } from './table-client'
+
+type BaseOptions = {
+  baseUrl?: string
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  queryClient?: QueryClient
+}
+
+function buildTableQueryOptions<
+  TSchema extends Record<string, unknown>,
+  K extends keyof TSchema & string,
+>(
+  _tableKey: K,
+  tableName: string,
+  table: TSchema[K] | undefined,
+  config: BaseOptions & {
+    baseUrl: string
+    fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  },
+): TableQueryOptions<
+  InferSelect<NonNullable<typeof table>>,
+  InferInsert<NonNullable<typeof table>>,
+  Partial<InferSelect<NonNullable<typeof table>>>
+> {
+  type Row = InferSelect<NonNullable<typeof table>>
+  type Create = InferInsert<NonNullable<typeof table>>
+  type Update = Partial<Row>
+
+  const client = createTableClient<Row, Create, Update>({
+    tableName,
+    baseUrl: config.baseUrl,
+    fetch: config.fetch,
+  })
+
+  return {
+    ...client,
+    ...attachMutationOptions(client, config.queryClient),
+  }
+}
+
+export function createBunderstackQueryClient<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+>() {
+  return {
+    /**
+     * Tables path: provide TSchema explicitly as a generic, TTables is inferred from the tuple.
+     * The schema is never imported as a value — safe for client bundles.
+     *
+     * @example
+     * import type * as schema from './schema'
+     * const api = createBunderstackQueryClient<typeof schema>()
+     *   .withTables({ queryClient, tables: ['posts', 'user'] as const })
+     */
+    withTables<const TTables extends readonly (keyof TSchema & string)[]>(
+      options: BaseOptions & { tables: TTables },
+    ): BunderstackQueryClient<TSchema, TTables[number]> {
+      const baseUrl = options.baseUrl ?? '/api'
+      const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+      const client = {} as BunderstackQueryClient<TSchema, TTables[number]>
+
+      for (const tableKey of options.tables) {
+        const tableClient = createTableClient({
+          tableName: tableKey,
+          baseUrl,
+          fetch: fetchFn,
+        })
+        ;(client as Record<string, unknown>)[tableKey] = {
+          ...tableClient,
+          ...attachMutationOptions(tableClient, options.queryClient),
+        }
+      }
+      return client
+    },
+
+    /**
+     * Schema path: TSchema is inferred from the schema value. Exposed tables are determined
+     * by access rules (auth tables excluded by default via CrudTableKey).
+     *
+     * @example
+     * import * as schema from './schema'
+     * const api = createBunderstackQueryClient()
+     *   .withSchema({ schema, queryClient })
+     */
+    withSchema<
+      S extends TSchema,
+      TAccess extends Record<string, TableAccessInput> | undefined = undefined,
+    >(
+      options: BaseOptions & { schema: S; access?: TAccess },
+    ): BunderstackQueryClient<S, CrudTableKey<S>> {
+      const baseUrl = options.baseUrl ?? '/api'
+      const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+      const client = {} as BunderstackQueryClient<S, CrudTableKey<S>>
+      const config = {
+        baseUrl,
+        fetch: fetchFn,
+        queryClient: options.queryClient,
+      }
+
+      const resolved = validateAndResolveAccess(options.schema, options.access)
+      for (const [tableKey, tableAccess] of resolved) {
+        if (!tableAccess.enabled) continue
+        ;(client as Record<string, unknown>)[tableKey] = buildTableQueryOptions(
+          tableKey as keyof S & string,
+          tableAccess.tableName,
+          options.schema[tableKey],
+          config,
+        )
+      }
+      return client
+    },
+
+    withFiles<const TBuckets extends readonly string[]>(
+      options: BaseOptions & { buckets: TBuckets },
+    ): FilesQueryClient<TBuckets[number]> {
+      const baseUrl = options.baseUrl ?? '/api'
+      const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+      const client: FilesQueryClient<TBuckets[number]> = {
+        files: {} as FilesQueryClient<TBuckets[number]>['files'],
+      }
+
+      for (const bucket of options.buckets) {
+        const bucketClient = createBucketClient({
+          bucket,
+          baseUrl,
+          fetch: fetchFn,
+        })
+        client.files[bucket as TBuckets[number]] = {
+          ...bucketClient,
+          ...attachBucketMutationOptions(bucketClient, options.queryClient),
+        }
+      }
+      return client
+    },
+
+    with<
+      const TTables extends readonly (keyof TSchema & string)[],
+      const TBuckets extends readonly string[],
+    >(
+      options: BaseOptions & { tables: TTables; buckets: TBuckets },
+    ): BunderstackQueryClient<TSchema, TTables[number]> &
+      FilesQueryClient<TBuckets[number]> {
+      const baseUrl = options.baseUrl ?? '/api'
+      const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis)
+      const tablesClient = {} as BunderstackQueryClient<
+        TSchema,
+        TTables[number]
+      >
+
+      for (const tableKey of options.tables) {
+        const tableClient = createTableClient({
+          tableName: tableKey,
+          baseUrl,
+          fetch: fetchFn,
+        })
+        ;(tablesClient as Record<string, unknown>)[tableKey] = {
+          ...tableClient,
+          ...attachMutationOptions(tableClient, options.queryClient),
+        }
+      }
+
+      const filesClient: FilesQueryClient<TBuckets[number]> = {
+        files: {} as FilesQueryClient<TBuckets[number]>['files'],
+      }
+      for (const bucket of options.buckets) {
+        const bucketClient = createBucketClient({
+          bucket,
+          baseUrl,
+          fetch: fetchFn,
+        })
+        filesClient.files[bucket as TBuckets[number]] = {
+          ...bucketClient,
+          ...attachBucketMutationOptions(bucketClient, options.queryClient),
+        }
+      }
+
+      return {
+        ...tablesClient,
+        ...filesClient,
+      }
+    },
+  }
+}
+
+export { createClient, lazyRecord } from './lazy-client'
+export type { BunderstackClient, ClientOptions } from './lazy-client'
+export { MAX_LIST_LIMIT } from './table-client'
+export type {
+  AnyBunderstackApp,
+  ClientCarrier,
+  ExposedTables,
+  InferBuckets,
+  InferSchema,
+  InferTables,
+  InferTrpcRouter,
+} from './infer'
+export { BunderstackApiError } from './errors'
+export type {
+  BunderstackQueryClient,
+  CreateClientOptions,
+  CrudTableKey,
+  ExposedTableKeys,
+  FilesQueryClient,
+  InferInsert,
+  InferSelect,
+  ListParams,
+  Paginated,
+  TableQueryOptions,
+  TableQueryOptionsForKey,
+  UseMutationOptions,
+} from './types'
+export {
+  createBucketClient,
+  attachBucketMutationOptions,
+} from './bucket-client'
+export type {
+  BucketClient,
+  BucketClientConfig,
+  BucketMutationOptions,
+  FileTransformOptions,
+  UploadedFile,
+  UploadMode,
+  UploadOptions,
+} from './bucket-client'
+export { createTableClient } from './table-client'
+export type { TableClient, TableClientConfig } from './table-client'
+export { createRealtimeClient } from './realtime-client'
+export type { RealtimeClientConfig, RealtimeEvent } from './realtime-client'

package/src/infer.ts

@@ -0,0 +1,81 @@
+import type { AnyRouter } from '@trpc/server'
+
+import type { AuthTableName, CrudTableKey, InferSelect } from './types'
+
+/** Shape of the `$inferClient` phantom `createBunderstack` puts on the app. */
+export type ClientCarrier = {
+  schema: Record<string, unknown>
+  access: unknown
+  buckets: string
+  // Optional: apps built before the trpc feature still match.
+  trpc?: unknown
+}
+
+export type AnyBunderstackApp = { $inferClient?: ClientCarrier | undefined }
+
+export type InferCarrier<TApp extends AnyBunderstackApp> = NonNullable<
+  TApp['$inferClient']
+>
+export type InferSchema<TApp extends AnyBunderstackApp> =
+  InferCarrier<TApp>['schema']
+export type InferBuckets<TApp extends AnyBunderstackApp> =
+  InferCarrier<TApp>['buckets']
+
+/** The app's tRPC router type, or `never` when it doesn't declare one. */
+export type InferTrpcRouter<TApp extends AnyBunderstackApp> =
+  InferCarrier<TApp>['trpc'] extends infer R
+    ? R extends AnyRouter
+      ? R
+      : never
+    : never
+
+type DisabledKeys<TAccess> = {
+  [K in keyof TAccess & string]: TAccess[K] extends { crud: false } ? K : never
+}[keyof TAccess & string]
+
+/** Tables with an explicit access entry (auth tables need exposeAuthTable). */
+type ExplicitKeys<TSchema, TAccess> = {
+  [K in keyof TAccess & keyof TSchema & string]: TAccess[K] extends {
+    crud: false
+  }
+    ? never
+    : K extends AuthTableName
+      ? TAccess[K] extends { exposeAuthTable: true }
+        ? K extends 'user'
+          ? K
+          : never
+        : never
+      : K
+}[keyof TAccess & keyof TSchema & string]
+
+/** Tables with a `userId` column get convention CRUD without an access entry. */
+type ConventionKeys<TSchema> = {
+  [K in keyof TSchema & string]: K extends AuthTableName
+    ? never
+    : InferSelect<TSchema[K]> extends { userId: unknown }
+      ? K
+      : never
+}[keyof TSchema & string]
+
+/**
+ * Type-level mirror of validateAndResolveAccess's exposure rules. Slightly
+ * permissive on edge cases (a wrongly-included table 404s at runtime, same
+ * as a hand-written tables tuple — never silently narrower).
+ */
+export type ExposedTables<TSchema extends Record<string, unknown>, TAccess> = [
+  TAccess,
+] extends [undefined]
+  ? CrudTableKey<TSchema>
+  :
+      | ExplicitKeys<TSchema, TAccess>
+      | Exclude<
+          ConventionKeys<TSchema>,
+          DisabledKeys<TAccess> | (keyof TAccess & string)
+        >
+
+export type InferTables<TApp extends AnyBunderstackApp> = ExposedTables<
+  InferSchema<TApp>,
+  InferCarrier<TApp>['access']
+> &
+  keyof InferSchema<TApp> &
+  string