better-supabase 0.14.0 → 0.15.0

package/dist/index-DLq69k3F.d.ts

@@ -0,0 +1,588 @@
+/// <reference lib="esnext.temporal" />
+import { n as DbException } from "./escape-like-PReMbEEU.js";
+import { f as Result, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { $ as RecordRef, K as Insert, O as AnyFunctions, Z as PrimaryKeyValue, ht as Update, k as AnyModels, ut as TableKey } from "./types-DFdg_4yN.js";
+import { o as EventHub } from "./events-vcqenSYU.js";
+import { A as OffsetRangeArgs, Bt as Payload, C as GetKey, Dt as CountArgs, K as WriteArgs, Nt as ListArgs, O as OffsetPage, S as FindExt, St as AggregateResult, U as UpdateArgs, W as UpsertArgs, Zt as CacheAdapter, _ as CursorPageArgs, b as DeleteArgs, ft as InferResult, g as CursorPage, k as OffsetPageArgs, kt as GetArgs, pt as QuerySpec, t as BetterSupabase, v as Db, x as DeleteExt, yt as AggregateArgs, z as Returned } from "./define-DFBnQyYg.js";
+import { n as DataEngine, r as DataEngineOptions } from "./data-engine-BWoz9lED.js";
+import { Dn as GeneratedBlocks, cn as RecordBindingResult, dn as RecordBindingWriteName, fn as RecordBindingWriteOutput, in as RecordBindingData, nn as AnyRecordBindingWrite, on as RecordBindingOptions, t as AnyBlock, tn as AnyRecordBinding, un as RecordBindingWriteInput } from "./define-block-BVcLQ3DF.js";
+import { t as BetterQueryMeta } from "./invalidate-DMp4eqfF.js";
+import { DataTag, InfiniteData, QueryClient, SkipToken } from "@tanstack/query-core";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/query/queries.d.ts
+type QueryKeyOf<T> = DataTag<readonly unknown[], T, DbException>;
+type QueryFnOf<T> = ((context: {
+  readonly signal: AbortSignal;
+}) => Promise<T>) | SkipToken;
+/**
+ * Options for `useQuery`, `createQuery`, `injectQuery`,
+ * `queryClient.fetchQuery` and `prefetchQuery`.
+ */
+interface QueryOptionsOf<T> {
+  readonly queryKey: QueryKeyOf<T>;
+  readonly queryFn: QueryFnOf<T>;
+  readonly meta: BetterQueryMeta;
+  readonly staleTime?: number;
+}
+/**
+ * Options for infinite queries over cursor (`string | null`) or offset
+ * (`number`) pages.
+ */
+interface InfiniteOptionsOf<P, Param> {
+  readonly queryKey: DataTag<readonly unknown[], InfiniteData<P>, DbException>;
+  readonly queryFn: (context: {
+    readonly signal: AbortSignal;
+    readonly pageParam: Param;
+  }) => Promise<P>;
+  readonly initialPageParam: Param;
+  readonly getNextPageParam: (last: P) => Param | undefined;
+  /**
+   * Set on numbered pages, so a window trimmed by `maxPages` can load
+   * backwards.
+   */
+  readonly getPreviousPageParam?: (first: P) => Param | undefined;
+  readonly maxPages?: number;
+  readonly meta: BetterQueryMeta;
+  readonly staleTime?: number;
+}
+interface InfiniteExtras {
+  /**
+   * Pages kept in the cache; older ones are dropped as new ones load. Keeps
+   * long feeds from holding every page in memory and refetching them all.
+   */
+  readonly maxPages?: number;
+}
+/** Options for `useMutation`. Invalidates every query that read a changed table. */
+interface MutationOptionsOf<V, R> {
+  readonly mutationKey: readonly unknown[];
+  readonly mutationFn: (variables: V) => Promise<R>;
+  readonly onSuccess: (data: R, variables: V, onMutateResult: unknown, context: {
+    readonly client: QueryClient;
+  }) => Promise<void>;
+}
+interface TableQueries<M extends AnyModels, T extends TableKey<M>, E> {
+  /** Prefix of every key for this table's own queries. */
+  readonly key: readonly ["bsb", T];
+  list<const A extends ListArgs<M, T> & FindExt<E, M, T>>(args?: A | SkipToken): QueryOptionsOf<Payload<M, T, A>[]>;
+  page<const A extends (OffsetPageArgs<M, T> | OffsetRangeArgs<M, T>) & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<OffsetPage<Payload<M, T, A>>>;
+  get<const A extends GetArgs<M, T> & FindExt<E, M, T>>(key: GetKey<M, T> | SkipToken, args?: A): QueryOptionsOf<A extends {
+    readonly optional: true;
+  } ? Payload<M, T, A> | null : Payload<M, T, A>>;
+  count(args?: (CountArgs<M, T> & FindExt<E, M, T>) | SkipToken): QueryOptionsOf<number>;
+  aggregate<const A extends AggregateArgs<M, T> & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<AggregateResult<M, T, A>>;
+  /** Cursor pages for `useInfiniteQuery`. */
+  infinite<const A extends Omit<CursorPageArgs<M, T>, "after"> & FindExt<E, M, T>>(args: A, options?: InfiniteExtras): InfiniteOptionsOf<CursorPage<Payload<M, T, A>>, string | null>;
+  /** Numbered pages for `useInfiniteQuery`, starting at `args.page` (default 1). */
+  infinitePages<const A extends OffsetPageArgs<M, T> & FindExt<E, M, T>>(args: A, options?: InfiniteExtras): InfiniteOptionsOf<OffsetPage<Payload<M, T, A>>, number>;
+  create<const A extends WriteArgs<M, T> = {}>(args?: A): MutationOptionsOf<Insert<M, T>, Returned<M, T, A>>;
+  update<const A extends UpdateArgs<M, T> = {}>(args?: A): MutationOptionsOf<{
+    readonly id: PrimaryKeyValue<M, T>;
+    readonly patch: Update<M, T>;
+  }, Returned<M, T, A>>;
+  upsert<const A extends UpsertArgs<M, T> = {}>(args?: A): MutationOptionsOf<Insert<M, T>, Returned<M, T, A>>;
+  delete(args?: DeleteArgs & DeleteExt<E, M, T>): MutationOptionsOf<PrimaryKeyValue<M, T>, void>;
+}
+type RpcArgsOf<F extends AnyFunctions, N extends keyof F> = F[N]["Args"];
+interface QueryHelpers<M extends AnyModels, F extends AnyFunctions> {
+  /** Prefix of every better-supabase key. */
+  readonly $key: readonly ["bsb"];
+  /**
+   * Query options for a `QuerySpec`, for example one sent from a Server
+   * Component.
+   */
+  $spec<S extends QuerySpec<TableKey<M>>>(spec: S | SkipToken): QueryOptionsOf<InferResult<S>>;
+  /** Fetches a spec into `queryClient` for server rendering and hydration. */
+  $prefetch(queryClient: QueryClient, spec: QuerySpec<TableKey<M>>): Promise<void>;
+  /**
+   * Query options for a database function. `tables` lists what it reads, for
+   * invalidation.
+   */
+  $rpc<N extends Extract<keyof F, string>>(name: N, args?: RpcArgsOf<F, N> | SkipToken, options?: {
+    readonly tables?: readonly TableKey<M>[];
+  }): QueryOptionsOf<F[N]["Returns"]>;
+  /**
+   * Mutation options for a database function; invalidates what
+   * `betterSupabase.defineRpc` declared.
+   */
+  $rpcMutation<N extends Extract<keyof F, string>>(name: N): MutationOptionsOf<RpcArgsOf<F, N>, F[N]["Returns"]>;
+}
+type BetterQueries<M extends AnyModels, E, F extends AnyFunctions = AnyFunctions> = { readonly [T in TableKey<M>]: TableQueries<M, T, E>; } & QueryHelpers<M, F>;
+interface QueriesOptions {
+  /**
+   * `staleTime` for every query option. Set it above zero when rendering on the
+   * server so hydrated data isn't refetched on mount.
+   */
+  readonly staleTime?: number;
+  /**
+   * Appended to every query key. Give each executor its own scope (`'local'`
+   * for PowerSync, for instance) when several share one QueryClient, so their
+   * results never land in the same cache entry. Invalidation by table still
+   * reaches every scope.
+   */
+  readonly scope?: string;
+}
+/**
+ * TanStack Query option factories for every table, framework-neutral: pass them
+ * to `useQuery` (React), `createQuery` (Svelte, Solid), `useQuery` (Vue) or
+ * `injectQuery` (Angular). Payload types flow into the cache, errors are
+ * `DbException`s, and mutations invalidate every query that read a changed
+ * table.
+ *
+ * ```ts
+ * const q = createQueries(betterSupabase, () => bsb.db);
+ * const { data } = useQuery(q.customers.list({ select: ["id", "name"] }));
+ * ```
+ */
+declare function createQueries<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, db: Db<M, F, E, unknown> | (() => Db<M, F, E, unknown>), options?: QueriesOptions): BetterQueries<M, E, F>;
+/** Invalidates every query that read a table in the target. */
+declare function queryCache(client: QueryClient): CacheAdapter;
+/**
+ * Invalidates affected queries for every mutation and declared RPC
+ * `betterSupabase` performs in this runtime.
+ */
+declare function invalidateOnMutation<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, client: QueryClient): () => void;
+//#endregion
+//#region src/query/user-change.d.ts
+/** The part of `createClient().auth` that `clearOnUserChange` reads. */
+interface UserChangeSource {
+  subscribe(listener: () => void): () => void;
+  current(): {
+    readonly status: string;
+    readonly user: {
+      readonly id: string;
+    } | null;
+    readonly claims?: Readonly<Record<string, unknown>> | null;
+  };
+}
+/**
+ * Resets every `['bsb', ...]` query when the caller changes: another user,
+ * signing out, or new claims for the same user (an organization switch, a role
+ * change). Mounted queries refetch, so no one sees the previous identity's
+ * rows. Returns the function that stops listening. `BetterSupabaseProvider`
+ * calls it for React; call it yourself with Vue, Solid, Svelte or Angular
+ * Query.
+ *
+ * Queries that fetched while the session was still loading ran as anon, so they
+ * are reset when a user arrives. Data already in the cache when loading started
+ * (hydrated from the server) stays.
+ *
+ * ```ts
+ * const stop = clearOnUserChange(queryClient, bsb.auth);
+ * ```
+ */
+declare function clearOnUserChange(queryClient: Pick<QueryClient, "resetQueries" | "getQueryCache">, auth: UserChangeSource): () => void;
+//#endregion
+//#region src/query/engine.d.ts
+/**
+ * The data hooks' engine on TanStack Query: their reads live in `queryClient`
+ * under `["bsb", <instance or table>, ...]`, so devtools, `staleTime` and
+ * `invalidateQueries` see them. `live` reads followed sources again when their
+ * tables change elsewhere.
+ *
+ * ```ts
+ * export const bsb = createClient(betterSupabase, {
+ *   engine: queryEngine(queryClient),
+ * });
+ * ```
+ */
+declare function queryEngine(queryClient: QueryClient, options?: DataEngineOptions): DataEngine;
+//#endregion
+//#region src/query/blocks.d.ts
+/** The first key part of every query, a table's or a block instance's. */
+declare const BLOCK_KEY = "bsb";
+/**
+ * Method name prefixes that read: these become query options, every other
+ * method becomes mutation options.
+ */
+declare const BLOCK_READ_PREFIXES: readonly ["can", "count", "find", "get", "has", "is", "list", "load", "preview", "read", "resolve", "search", "tree"];
+type ReadPrefix = (typeof BLOCK_READ_PREFIXES)[number];
+type AnyMethod = (...args: never[]) => PromiseLike<Result<unknown>>;
+type DataOf<F> = F extends ((...args: never[]) => PromiseLike<infer R>) ? R extends {
+  readonly ok: true;
+  readonly data: infer D;
+} ? D : never : never;
+/**
+ * What a block mutation takes: the one argument of a method with at most one
+ * parameter, else the arguments as a tuple.
+ */
+type BlockVariablesOf<F extends AnyMethod> = Parameters<F>["length"] extends 0 | 1 ? Parameters<F>[0] : Parameters<F>;
+type MethodKeys<C> = { readonly [K in keyof C]: C[K] extends AnyMethod ? K : never; }[keyof C] & string;
+/** The query or mutation options of one block method. */
+type BlockMethodQuery<K extends string, F extends AnyMethod> = K extends ReadPrefix | `${ReadPrefix}${Capitalize<string>}` ? (...args: Parameters<F> | [SkipToken]) => QueryOptionsOf<DataOf<F>> : () => MutationOptionsOf<BlockVariablesOf<F>, DataOf<F>>;
+/** Query and mutation options for one block client, by method. */
+type BlockClientQueries<C> = { readonly [K in MethodKeys<C>]: C[K] extends AnyMethod ? BlockMethodQuery<K, C[K]> : never; } & {
+  /** Prefix of every key for this block's queries. */
+  readonly $key: readonly [typeof BLOCK_KEY, string];
+};
+/** `blockQueries(clients)`: query and mutation options for each block. */
+type BlockQueries<C> = { readonly [K in keyof C & string]: BlockClientQueries<C[K]>; };
+/** The block clients `createBlocks` built, by key. */
+type BlockClients = Readonly<Record<string, object>>;
+/**
+ * Query options for each read method of each block client (`get*`, `list*`,
+ * `find*`, `search*` and the other `BLOCK_READ_PREFIXES`), keyed `["bsb",
+ * instance, method, ...args]` like table queries, and mutation options for
+ * every other method. A mutation makes its instance's queries stale, through
+ * the matcher table writes use (`invalidateTables`); `invalidateOnBlockEvents`
+ * does the same for block events. Renamed blocks (`renameBlock`) keep their
+ * renamed method names. A method that fails throws a `DbException`, like
+ * `createQueries`.
+ */
+declare function blockQueries<const C extends BlockClients>(clients: C, options?: QueriesOptions): BlockQueries<C>;
+/** What `invalidateOnBlockEvents` reads from each block. */
+interface BlockInvalidation {
+  readonly events: {
+    readonly types: readonly string[];
+  };
+  readonly invalidates?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Makes block queries stale when a block event arrives on `source.events`: the
+ * read methods the block's `invalidates` lists for the event, or every read
+ * method of the block when none lists it. Pass the blocks keyed like the
+ * clients given to `blockQueries` (`defineBlocks(...).blocks`). Returns a
+ * function that stops listening.
+ */
+declare function invalidateOnBlockEvents(queryClient: QueryClient, source: {
+  readonly events: EventHub;
+}, blocks: Readonly<Record<string, BlockInvalidation>>): () => void;
+//#endregion
+//#region src/blocks/permissions/permissions-controller.d.ts
+/**
+ * The caller's permission keys in one tenant, as `my_permissions` returned
+ * them. It is plain data, so a Server Component can pass it to the client.
+ */
+interface PermissionSet {
+  /** The organization the keys hold in. */
+  readonly tenant: string;
+  /**
+   * The keys the caller holds. Keys loaded without a list keep their wildcards
+   * (`*`, `invoices.*`) as the access model grants them.
+   */
+  readonly keys: readonly string[];
+}
+/** `{ edit: "customers.write" }` as `{ canEdit: boolean }`. */
+type PermissionFlags<M extends Readonly<Record<string, string>>> = { readonly [N in keyof M & string as `can${Capitalize<N>}`]: boolean; };
+/**
+ * Whether a granted key covers a wanted one: the same rule as the SQL
+ * `permission_matches`, where `*` grants every key and `prefix.*` every key
+ * under `prefix`.
+ */
+declare function permissionMatches(granted: string, wanted: string): boolean;
+/**
+ * Whether `set` holds `key`. UX only: RLS and the SQL functions check the key
+ * again.
+ *
+ * ```ts
+ * if (can(permissionSet, permissions.customers.write)) showEditButton();
+ * ```
+ */
+declare function can(set: PermissionSet | null | undefined, key: string): boolean;
+/**
+ * One `can<Name>` boolean per entry of `flags`, for a payload query that
+ * returns data and what the caller may do with it.
+ *
+ * ```ts
+ * permissionFlags(set, { edit: permissions.customers.write });
+ * // { canEdit: true }
+ * ```
+ */
+declare function permissionFlags<const M extends Readonly<Record<string, string>>>(set: PermissionSet | null | undefined, flags: M): PermissionFlags<M>;
+//#endregion
+//#region src/records/bindings.d.ts
+/** Block manifests by the key the app built them under, as `blockSet.blocks`. */
+type BindingBlocks = Readonly<Record<string, {
+  readonly sql: readonly string[];
+  readonly record?: AnyRecordBinding | undefined;
+}>>;
+/**
+ * Where bindings come from: the manifests (`blockSet.blocks`) and the clients
+ * built from them (`blockSet.create(...)`), keyed alike.
+ */
+interface BindingSource<B extends BindingBlocks> {
+  readonly blocks: B;
+  readonly clients: object;
+}
+/** The keys of the blocks that bind to a record. */
+type BindingName<B extends BindingBlocks> = { readonly [K in keyof B]: B[K] extends {
+  readonly record: AnyRecordBinding;
+} ? K & string : never; }[keyof B];
+/** The record binding of the block under key `N`. */
+type BindingOf<B extends BindingBlocks, N extends string> = N extends keyof B ? B[N] extends {
+  readonly record: infer R extends AnyRecordBinding;
+} ? R : never : never;
+/** The settled results of `loadBindings`, by binding name. */
+type LoadedBindings<B extends BindingBlocks, N extends string> = { readonly [K in N]: RecordBindingResult<RecordBindingData<BindingOf<B, K>>>; };
+/** The permission `loadBindings` asks `can` about. */
+interface BindingCheck {
+  /** The key of the block whose binding it is. */
+  readonly binding: string;
+  /** The SQL module whose permission keys `action` names. */
+  readonly module: string;
+  /** `read`, or the binding's `permissions.write` for a write. */
+  readonly action: string;
+}
+interface LoadBindingsOptions<B extends BindingBlocks, N extends string> {
+  /**
+   * Whether the caller may see a binding; a binding it can't is `hidden` and
+   * not loaded. Build it with `bindingCan`. Default: every binding loads and
+   * RLS decides what it returns.
+   */
+  readonly can?: (check: BindingCheck) => boolean;
+  /** Options for each binding's `load`, such as `{ comments: { limit: 20 } }`. */
+  readonly options?: { readonly [K in N]?: RecordBindingOptions<BindingOf<B, K>>; };
+}
+/**
+ * A `can` for `loadBindings` from the caller's `PermissionSet` and the
+ * `permissions` constant of `blocks.generated.ts`: a binding needs the key its
+ * module's action names there. An action with no key there is allowed, and RLS
+ * decides.
+ */
+declare function bindingCan(set: PermissionSet | null | undefined, permissions: Readonly<Record<string, Readonly<Record<string, string>>>>): (check: BindingCheck) => boolean;
+/**
+ * Loads a record's bindings in parallel, each one settled: `ok` with its rows,
+ * `error` with a `DbError`, or `hidden` when `can` says the caller can't read
+ * it, which never runs its query. It never throws.
+ *
+ * ```ts
+ * const { comments, tags } = await loadBindings(
+ *   { blocks: blockSet.blocks, clients: blocks },
+ *   { type: "customer", id },
+ *   ["comments", "tags"],
+ *   { can: bindingCan(permissionSet, permissions) },
+ * );
+ * ```
+ */
+declare function loadBindings<B extends BindingBlocks, const N extends BindingName<B>>(source: BindingSource<B>, subject: RecordRef, names: readonly N[], options?: LoadBindingsOptions<B, N>): Promise<LoadedBindings<B, N>>;
+/**
+ * How many rows a binding has for each of `subjects`, keyed by `subjectKey`
+ * (`type:id`), for a badge on each row of a list. A binding without `count`
+ * fails with `unsupported`.
+ */
+declare function countBinding<B extends BindingBlocks>(source: BindingSource<B>, name: BindingName<B>, subjects: readonly RecordRef[]): AsyncResult<Readonly<Record<string, number>>>;
+//#endregion
+//#region src/records/record-type.d.ts
+/** The binding blocks of a record type, keyed like `blockSet.blocks`. */
+type RecordTypeBlocks = Readonly<Record<string, AnyBlock>>;
+/** The `permissions` constant of `blocks.generated.ts`. */
+type RecordTypePermissions = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** A block whose client loads the caller's keys, such as the access block. */
+interface PermissionsBlock extends AnyBlock {
+  readonly create: ((options: never) => {
+    permissions(keys: readonly string[]): AsyncResult<PermissionSet>;
+  }) | undefined;
+}
+/** What `defineRecordType` takes. */
+interface RecordTypeSpec<T extends string, B extends RecordTypeBlocks> {
+  /** The subject type, such as `"customer"`. */
+  readonly type: T;
+  /** The blocks whose bindings the record page shows. */
+  readonly blocks: B;
+  /** `blockConfig` from `blocks.generated.ts`. */
+  readonly config?: GeneratedBlocks;
+  /**
+   * `permissions` from `blocks.generated.ts`, which maps each binding's actions
+   * to the keys the `can` flags check.
+   */
+  readonly permissions?: RecordTypePermissions;
+  /**
+   * The access block, which loads the caller's keys for the `can` flags.
+   * Without it every flag is `true` and RLS decides.
+   */
+  readonly access?: PermissionsBlock;
+}
+/**
+ * One record type's page: the blocks that bind to it, the writes each binding
+ * takes, and what the caller may do. `gen` writes one per record type to
+ * `records/<type>.ts` (`gen.recordTypes`); `bsb.record`, `recordQueries` and
+ * `createRecordProvider` take it.
+ */
+interface RecordType<T extends string = string, B extends RecordTypeBlocks = RecordTypeBlocks> extends RecordTypeSpec<T, B> {
+  /** The keys of the blocks that bind to the record. */
+  readonly bindings: readonly BindingName<B>[];
+}
+/** Describes one subject's record page from the blocks that own its bindings. */
+declare function defineRecordType<const T extends string, const B extends RecordTypeBlocks>(spec: RecordTypeSpec<T, B>): RecordType<T, B>;
+/** The record a record type's page shows. */
+declare function recordSubject<T extends string>(feature: {
+  readonly type: T;
+}, id: string): RecordRef<T>;
+/** The writes of the binding named `S`, by name. */
+type BindingWritesOf<B extends RecordTypeBlocks, S extends string> = RecordBindingWriteName<BindingOf<B, S>>;
+/** What the caller may do on each binding: `read` and one flag per write. */
+type RecordCan<B extends RecordTypeBlocks, N extends string> = { readonly [S in N]: {
+  readonly read: boolean;
+} & { readonly [W in BindingWritesOf<B, S>]: boolean; }; };
+interface WriteFound {
+  readonly key: string;
+  readonly module: string;
+  readonly write: AnyRecordBindingWrite;
+  readonly permission: string | undefined;
+}
+/** The block key, module and write that `binding.write` names. */
+declare function findBindingWrite(feature: Pick<RecordType, "blocks">, binding: string, write: string): WriteFound | undefined;
+/**
+ * The permission keys a record type's bindings check, for one
+ * `access.permissions(keys)` call.
+ */
+declare function recordPermissionKeys(feature: Pick<RecordType, "blocks" | "permissions"> & {
+  readonly bindings: readonly string[];
+}): readonly string[];
+/**
+ * What the caller may do on each of a record type's bindings, from its
+ * `PermissionSet`. A binding action with no key in `permissions` is allowed,
+ * and so is everything when `set` is `undefined` (no access block): RLS and
+ * each function's checks decide.
+ */
+declare function recordCan<B extends RecordTypeBlocks, N extends BindingName<B>>(feature: Pick<RecordType<string, B>, "blocks" | "permissions"> & {
+  readonly bindings: readonly N[];
+}, set: PermissionSet | null | undefined): RecordCan<B, N>;
+/** What a generated write takes: the record's id and the write's input. */
+interface RecordWriteInput<I> {
+  readonly id: string;
+  readonly input: I;
+}
+/** The input of one write of a record type's binding. */
+type RecordTypeWriteInput<B extends RecordTypeBlocks, S extends string, W extends string> = RecordBindingWriteInput<BindingOf<B, S>, W>;
+/** What one write of a record type's binding resolves to. */
+type RecordTypeWriteOutput<B extends RecordTypeBlocks, S extends string, W extends string> = RecordBindingWriteOutput<BindingOf<B, S>, W>;
+/**
+ * A Standard Schema for `{ id, input }`: a non-empty record id and the input
+ * `schema` validates, whose issues get the `input` path.
+ */
+declare function recordWriteInput<I>(schema: StandardSchemaV1<unknown, I>): StandardSchemaV1<unknown, RecordWriteInput<I>>;
+/** A Temporal value, from the runtime or a polyfill. */
+interface TemporalValue {
+  readonly [Symbol.toStringTag]: `Temporal.${string}`;
+  toString(): string;
+}
+/**
+ * `T` with every Temporal value as its ISO 8601 string, so it crosses the
+ * Server Component and Server Action boundary.
+ */
+type Plain<T> = T extends TemporalValue ? string : T extends readonly (infer U)[] ? Plain<U>[] : T extends ((...args: never) => unknown) ? T : T extends object ? { readonly [K in keyof T]: Plain<T[K]>; } : T;
+/**
+ * `value` with every Temporal value replaced by its ISO 8601 string, for data
+ * passed from a Server Component or returned from a Server Action.
+ */
+declare function plainData<T>(value: T): Plain<T>;
+/** A loaded binding with Temporal values as strings. */
+type PlainBinding<B extends RecordTypeBlocks, S extends string> = RecordBindingResult<Plain<RecordBindingData<BindingOf<B, S>>>>;
+/** A record type's loaded bindings, by name, with Temporal values as strings. */
+type PlainBindings<B extends RecordTypeBlocks, N extends string> = { readonly [S in N]: PlainBinding<B, S>; };
+//#endregion
+//#region src/query/records.d.ts
+/** The first key part of every record query. */
+declare const RECORD_KEY = "bsb-record";
+/** Query options for each binding of a record type, by binding name. */
+type RecordBindingQueries<B extends RecordTypeBlocks, N extends string> = { readonly [S in N]: (id: string | SkipToken, options?: RecordBindingOptions<BindingOf<B, S>>) => QueryOptionsOf<RecordBindingData<BindingOf<B, S>>>; };
+/** Mutation options for each write of each binding, by binding and write. */
+type RecordWriteMutations<B extends RecordTypeBlocks, N extends string> = { readonly [S in N]: { readonly [W in BindingWritesOf<B, S>]: (id: string) => MutationOptionsOf<RecordTypeWriteInput<B, S, W>, RecordTypeWriteOutput<B, S, W>>; }; };
+interface RecordQueries<T extends string, B extends RecordTypeBlocks, N extends string> {
+  /** Prefix of every key of this record type's queries. */
+  readonly $key: readonly [typeof RECORD_KEY, T];
+  /** The key of one record's queries, or of one of its bindings. */
+  key(id: string, binding?: N): readonly unknown[];
+  /** Query options per binding, keyed `["bsb-record", type, id, binding]`. */
+  readonly bindings: RecordBindingQueries<B, N>;
+  /**
+   * Mutation options per binding write; each one makes the binding's queries of
+   * that record stale.
+   */
+  readonly writes: RecordWriteMutations<B, N>;
+  /** What the caller may do on each binding, from the `access` client. */
+  can(): QueryOptionsOf<RecordCan<B, N>>;
+}
+interface RecordQueriesOptions extends QueriesOptions {
+  /**
+   * The access block's client, which loads the caller's keys for `can`. Without
+   * it every flag is `true` and RLS decides.
+   */
+  readonly access?: {
+    permissions(keys: readonly string[]): AsyncResult<PermissionSet>;
+  };
+}
+/**
+ * TanStack Query bindings of a generated record type, for apps that load
+ * records on the client (Vite, Expo, TanStack Start): query options per
+ * binding, mutation options per binding write, and the caller's `can` flags.
+ * Pass the block clients keyed like the record type's blocks, such as
+ * `blocks(supabase)` from `lib/blocks.ts`. A binding that fails throws a
+ * `DbException`, like `blockQueries`.
+ *
+ * ```ts
+ * const customer = recordQueries(customerRecord, clients);
+ * const comments = useQuery(customer.bindings.comments(id));
+ * const add = useMutation(customer.writes.comments.add(id));
+ * ```
+ */
+declare function recordQueries<T extends string, B extends RecordTypeBlocks, N extends BindingName<B>>(feature: RecordType<T, B> & {
+  readonly bindings: readonly N[];
+}, clients: object, options?: RecordQueriesOptions): RecordQueries<T, B, N>;
+/**
+ * Makes a record type's binding queries stale when a block event that the
+ * binding lists in `events` arrives on `source.events`, for every record of the
+ * record type. Returns a function that stops listening.
+ */
+declare function invalidateOnRecordEvents(queryClient: QueryClient, source: {
+  readonly events: EventHub;
+}, feature: Pick<RecordType, "blocks" | "type"> & {
+  readonly bindings: readonly string[];
+}): () => void;
+//#endregion
+//#region src/query/optimistic.d.ts
+/**
+ * A query whose cached data an optimistic update rewrites: any `q.<table>.*()`
+ * option.
+ */
+interface OptimisticTarget<T> {
+  readonly queryKey: QueryKeyOf<T>;
+}
+interface MutationContext {
+  readonly client: QueryClient;
+}
+/** What `onMutate` returns: the data each target held before the change. */
+interface OptimisticSnapshot {
+  readonly previous: readonly (readonly [queryKey: readonly unknown[], data: unknown])[];
+}
+/**
+ * `onMutate`, `onError` and `onSettled` for `useMutation`: spread them next to
+ * a mutation option, which keeps its `onSuccess` invalidation.
+ */
+interface OptimisticHandlers<V> {
+  onMutate(variables: V, context: MutationContext): Promise<OptimisticSnapshot>;
+  onError(error: Error, variables: V, snapshot: OptimisticSnapshot | undefined, context: MutationContext): void;
+  onSettled(data: unknown, error: Error | null, variables: V, snapshot: OptimisticSnapshot | undefined, context: MutationContext): Promise<void>;
+}
+type Targets<T> = OptimisticTarget<T> | readonly OptimisticTarget<T>[];
+type Keyed<R> = Extract<keyof R, string>;
+/**
+ * Optimistic updates for list queries (`list`), keyed by a row column (`id` by
+ * default):
+ *
+ * - `optimistic.create(list, (input) => row)` adds the row the input will make.
+ * - `optimistic.update(list)` merges `{ id, patch }` into the matching row.
+ * - `optimistic.remove(list)` drops the row whose key is the deleted id.
+ * - `optimistic(target, apply)` rewrites any cached data.
+ *
+ * ```ts
+ * const list = q.todos.list({ where: { done: false } });
+ * useMutation({ ...q.todos.update(), ...optimistic.update(list) });
+ * ```
+ */
+declare const optimistic: (<T, V>(targets: Targets<T>, apply: (current: T, variables: V) => T) => OptimisticHandlers<V>) & {
+  create<R, V>(targets: Targets<R[]>, toRow: (variables: V) => R, options?: {
+    readonly position?: "start" | "end";
+  }): OptimisticHandlers<V>;
+  update<R, K extends Keyed<R> = Keyed<R> & "id">(targets: Targets<R[]>, options?: {
+    readonly key?: K;
+  }): OptimisticHandlers<{
+    readonly id: R[K];
+    readonly patch: Partial<R>;
+  }>;
+  remove<R, K extends Keyed<R> = Keyed<R> & "id">(targets: Targets<R[]>, options?: {
+    readonly key?: K;
+  }): OptimisticHandlers<R[K]>;
+};
+//#endregion
+export { invalidateOnBlockEvents as $, BindingBlocks as A, PermissionFlags as B, defineRecordType as C, recordPermissionKeys as D, recordCan as E, LoadBindingsOptions as F, BLOCK_READ_PREFIXES as G, can as H, LoadedBindings as I, BlockInvalidation as J, BlockClientQueries as K, bindingCan as L, BindingName as M, BindingOf as N, recordSubject as O, BindingSource as P, blockQueries as Q, countBinding as R, RecordWriteInput as S, plainData as T, permissionFlags as U, PermissionSet as V, permissionMatches as W, BlockQueries as X, BlockMethodQuery as Y, BlockVariablesOf as Z, RecordTypeBlocks as _, RecordBindingQueries as a, InfiniteOptionsOf as at, RecordTypeWriteInput as b, RecordWriteMutations as c, QueryHelpers as ct, BindingWritesOf as d, TableQueries as dt, queryEngine as et, Plain as f, createQueries as ft, RecordType as g, RecordCan as h, optimistic as i, InfiniteExtras as it, BindingCheck as j, recordWriteInput as k, invalidateOnRecordEvents as l, QueryKeyOf as lt, PlainBindings as m, queryCache as mt, OptimisticSnapshot as n, clearOnUserChange as nt, RecordQueries as o, MutationOptionsOf as ot, PlainBinding as p, invalidateOnMutation as pt, BlockClients as q, OptimisticTarget as r, BetterQueries as rt, RecordQueriesOptions as s, QueriesOptions as st, OptimisticHandlers as t, UserChangeSource as tt, recordQueries as u, QueryOptionsOf as ut, RecordTypePermissions as v, findBindingWrite as w, RecordTypeWriteOutput as x, RecordTypeSpec as y, loadBindings as z };