better-supabase 0.13.0 → 0.15.0

package/dist/define-DFBnQyYg.d.ts

@@ -0,0 +1,1255 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, p as ThrowMapper, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { t as StandardSchemaV1 } from "./standard-DBV730sF.js";
+import { Bt as Executor, Ct as ApplyExtension, Ft as RequestContext, It as WithExtension, K as Insert, O as AnyFunctions, St as AnyPlugin, Tt as ExtensionOf, Z as PrimaryKeyValue, a as CountMode, at as Schema, dt as TableMeta, ht as Update, it as Row, k as AnyModels, m as Operation, mt as UniqueWhere, nt as Relations, ot as SchemaMeta, pt as UniqueKeyName, st as Simplify, tt as RelationTypes, ut as TableKey } from "./types-DFdg_4yN.js";
+import { a as EventHandler, c as MutationNotice, d as RpcNotice, o as EventHub, s as EventName } from "./events-vcqenSYU.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { k as StorageApi, n as Bucket, r as BucketClient } from "./bucket-CiNi8sIw.js";
+import { h as FilterQuery } from "./filter-query-BXLs72G9.js";
+import { a as PostgrestPlan, i as PostgrestCompileOptions } from "./postgrest-z-T0l23T.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/core/cache.d.ts
+/**
+ * What a mutation changed: a table, the primary keys of its rows and the
+ * tenant.
+ */
+interface CacheTarget {
+  /** App key of the table. */
+  readonly table: string;
+  /**
+   * App keys of every table whose cached reads are now stale: `table`, plus
+   * tables whose foreign keys cascade or set a value when `table` rows are
+   * deleted. Invalidate every read that touched one of them.
+   */
+  readonly tables: readonly string[];
+  /** Primary keys of the changed rows; composite keys are joined with `,`. */
+  readonly ids: readonly string[];
+  readonly tenant?: string;
+}
+/**
+ * Invalidates cached reads after a mutation. First-party adapters:
+ * `nextCache()` (Next.js cache tags) and `queryCache(client)` (TanStack Query).
+ * Attach one with `betterSupabase.cache(adapter)`; prove custom ones with
+ * `testCacheAdapter`.
+ */
+interface CacheAdapter {
+  readonly name: string;
+  invalidate(target: CacheTarget): void | Promise<void>;
+}
+/** Primary key of a row as a string, or `undefined` when it isn't returned. */
+declare function rowKey(table: TableMeta, row: Readonly<Record<string, unknown>>): string | undefined;
+declare function cacheTargetOf(meta: SchemaMeta, notice: MutationNotice): CacheTarget;
+/** One target per table an RPC changes; RPCs report no row ids. */
+declare function rpcCacheTargets(meta: SchemaMeta, notice: RpcNotice): CacheTarget[];
+interface MemoryCache extends CacheAdapter {
+  readonly invalidated: readonly CacheTarget[];
+  clear(): void;
+}
+/** Records invalidations. For tests and for checking what a mutation touches. */
+declare function memoryCache(): MemoryCache;
+//#endregion
+//#region src/core/db-buckets.d.ts
+/** Buckets registered with `betterSupabase.buckets()`, by key. */
+type BucketRegistry = Readonly<Record<string, Bucket<any, any, any>>>;
+/** `db.$buckets`: one connected client per registered bucket. */
+type BucketsHelper<B> = unknown extends B ? unknown : {
+  /**
+   * The registered buckets, connected to `db.$storage`. They run as the
+   * same caller as the `Db` and keep the tenant guard. Created on first
+   * read and reused for this `Db`.
+   */
+  readonly $buckets: { readonly [K in keyof B]: B[K] extends Bucket<infer P, infer Id, infer V> ? BucketClient<P, Id, V> : never; };
+};
+//#endregion
+//#region src/ir/args.d.ts
+interface BaseOps<V> {
+  readonly eq?: V;
+  readonly neq?: V;
+  readonly in?: readonly NonNullable<V>[];
+  readonly notIn?: readonly NonNullable<V>[];
+  readonly isNull?: boolean;
+  readonly not?: FieldFilter<V>;
+}
+interface ComparableOps<V> {
+  readonly gt?: V;
+  readonly gte?: V;
+  readonly lt?: V;
+  readonly lte?: V;
+}
+interface TextOps {
+  /** SQL LIKE pattern. `%` and `_` are wildcards. */
+  readonly like?: string;
+  /** Case-insensitive LIKE pattern. */
+  readonly ilike?: string;
+  /**
+   * Case-insensitive equality; `%`, `_` and backslashes in the value match
+   * themselves.
+   */
+  readonly ieq?: string;
+  /** POSIX regular expression (`~`). */
+  readonly match?: string;
+  /** Case-insensitive POSIX regular expression (`~*`). */
+  readonly imatch?: string;
+  /** Case-insensitive substring match; wildcards in the value are escaped. */
+  readonly contains?: string;
+  readonly startsWith?: string;
+  readonly endsWith?: string;
+  /**
+   * Full-text search (`websearch_to_tsquery`). `config` is a text search
+   * configuration name such as `english` or `pg_catalog.dutch`; anything else
+   * is an `invalid_request` error.
+   */
+  readonly search?: string | {
+    readonly query: string;
+    readonly config?: string;
+  };
+}
+interface ArrayOps<E> {
+  /** The array contains every given element. */
+  readonly hasEvery?: readonly E[];
+  /** The array shares at least one element with the given ones. */
+  readonly hasSome?: readonly E[];
+  /** The array contains the element. */
+  readonly has?: E;
+  /** The array is a subset of the given elements. */
+  readonly containedBy?: readonly E[];
+}
+interface JsonOps<V> {
+  /**
+   * Jsonb `@>`: the value contains the given structure. An array matches a JSON
+   * array holding every given element (`[{ "type": "image" }]`).
+   */
+  readonly contains?: Partial<V> | Record<string, unknown> | readonly unknown[];
+}
+type JsonText = string | number | boolean;
+/**
+ * Compares the text at a path inside a json column (`column->a->>b`). Numbers
+ * and booleans compare as their text; `isNull` and `eq: null` match a missing
+ * key and JSON `null`.
+ */
+interface JsonPathOps {
+  /** Keys from the column down; a number-like key indexes an array. */
+  readonly path: readonly [string, ...string[]];
+  readonly eq?: JsonText | null;
+  readonly neq?: JsonText | null;
+  readonly in?: readonly JsonText[];
+  readonly notIn?: readonly JsonText[];
+  readonly isNull?: boolean;
+  /** Text comparison, so `"10" < "9"`; store numbers you compare in a column. */
+  readonly gt?: string;
+  readonly gte?: string;
+  readonly lt?: string;
+  readonly lte?: string;
+  readonly like?: string;
+  readonly ilike?: string;
+  /**
+   * Case-insensitive equality; `%`, `_` and backslashes in the value match
+   * themselves.
+   */
+  readonly ieq?: string;
+  readonly match?: string;
+  readonly imatch?: string;
+}
+type OpsFor<V> = [NonNullable<V>] extends [string] ? BaseOps<V> & ComparableOps<V> & TextOps : [NonNullable<V>] extends [number | bigint] ? BaseOps<V> & ComparableOps<V> : [NonNullable<V>] extends [boolean] ? BaseOps<V> : [NonNullable<V>] extends [readonly (infer E)[]] ? BaseOps<V> & ArrayOps<E> : (BaseOps<V> & JsonOps<NonNullable<V>>) | JsonPathOps;
+/** A value (equality, or `null` for `is null`) or an operator object. */
+type FieldFilter<V> = V | OpsFor<V>;
+type RelationFilter<M extends AnyModels, R> = R extends {
+  readonly table: infer X extends keyof M;
+  readonly kind: "many";
+} ? {
+  /** At least one related row matches. `{}` means at least one exists. */
+  readonly some?: WhereInput<M, X>;
+  /** No related row matches. `{}` means none exist. */
+  readonly none?: WhereInput<M, X>;
+  /** Every related row matches (vacuously true without related rows). */
+  readonly every?: WhereInput<M, X>;
+} : R extends {
+  readonly table: infer X extends keyof M;
+  readonly nullable: infer N;
+} ? WhereInput<M, X> | (N extends true ? null : never) | {
+  readonly is?: WhereInput<M, X> | (N extends true ? null : never);
+  readonly isNot?: WhereInput<M, X> | (N extends true ? null : never);
+} : never;
+type WhereInput<M extends AnyModels, T extends keyof M> = { readonly [K in keyof Row<M, T>]?: FieldFilter<Row<M, T>[K]>; } & { readonly [R in keyof Relations<M, T>]?: RelationFilter<M, Relations<M, T>[R]>; } & {
+  readonly AND?: WhereInput<M, T> | readonly WhereInput<M, T>[];
+  readonly OR?: readonly WhereInput<M, T>[];
+  readonly NOT?: WhereInput<M, T>;
+};
+/**
+ * What a read's `where` takes: the object form, or a filter tree from ReUI's
+ * Filters (`FilterQuery` from `better-supabase/list`), checked against the
+ * table's columns.
+ */
+type WhereArg<M extends AnyModels, T extends keyof M> = WhereInput<M, T> | FilterQuery;
+/**
+ * A `where` you build one statement at a time: `const where:
+ * MutableWhere<Models, "customers"> = {}; if (status) where.status = status;`.
+ * The generated module exports it per table as `WhereOf<"customers">`.
+ */
+type MutableWhere<M extends AnyModels, T extends keyof M> = { -readonly [K in keyof WhereInput<M, T>]?: WhereInput<M, T>[K]; };
+type SortDirection = "asc" | "desc";
+type SortSpec = SortDirection | {
+  readonly direction: SortDirection;
+  readonly nulls?: "first" | "last";
+};
+/**
+ * The columns of one table, each with a sort direction. `undefined` is allowed
+ * so a ternary between two objects (`?: undefined` after TypeScript merges the
+ * branches) passes `exactOptionalPropertyTypes`.
+ */
+type ColumnOrderBy<M extends AnyModels, T extends keyof M> = { readonly [K in keyof Row<M, T>]?: SortSpec | undefined; };
+/**
+ * Columns of the table, and of its to-one relations one level down: `{
+ * organization: { name: "asc" } }` sorts by the related row's name.
+ */
+type OrderByInput<M extends AnyModels, T extends keyof M> = ColumnOrderBy<M, T> & { readonly [R in keyof Relations<M, T>]?: RelationOrderBy<M, Relations<M, T>[R]>; };
+type RelationOrderBy<M extends AnyModels, R> = R extends {
+  readonly kind: "one";
+  readonly table: infer X extends keyof M;
+} ? ColumnOrderBy<M, X> : never;
+type OrderByArg<M extends AnyModels, T extends keyof M> = OrderByInput<M, T> | readonly OrderByInput<M, T>[];
+/** Sorts by the table's own columns only (includes, aggregates). */
+type ColumnOrderByArg<M extends AnyModels, T extends keyof M> = ColumnOrderBy<M, T> | readonly ColumnOrderBy<M, T>[];
+type SelectArg<M extends AnyModels, T extends keyof M> = readonly Extract<keyof Row<M, T>, string>[];
+interface IncludeArgs<M extends AnyModels, T extends keyof M> {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  readonly where?: WhereInput<M, T>;
+  readonly orderBy?: ColumnOrderByArg<M, T>;
+  readonly limit?: number;
+  /** Only return parent rows that have a matching related row. */
+  readonly required?: boolean;
+}
+type IncludeArg<M extends AnyModels, T extends keyof M> = { readonly [R in keyof Relations<M, T>]?: true | IncludeArgs<M, Extract<TargetOf<Relations<M, T>[R]>, keyof M>>; } & {
+  /** Counts related rows: `_count: { notes: true }` returns `_count.notes`. */
+  readonly _count?: CountArg<M, T>;
+} & { readonly [K in MeasureKey]?: RelationMeasureArg<M, T>; };
+type NumericKey<M extends AnyModels, T extends keyof M> = { [K in keyof Row<M, T>]: [NonNullable<Row<M, T>[K]>] extends [number | bigint | string] ? K : never; }[keyof Row<M, T>];
+type MeasureKey = "_sum" | "_avg" | "_min" | "_max";
+/** Columns to aggregate: `{ amount: true }`. */
+type MeasureArg<M extends AnyModels, T extends keyof M> = { readonly [K in keyof Row<M, T>]?: true; };
+/** `_sum` and `_avg` take number (and numeric-as-string) columns only. */
+type NumericMeasureArg<M extends AnyModels, T extends keyof M> = { readonly [K in NumericKey<M, T>]?: true; };
+/**
+ * Relation aggregates check numeric columns at runtime, to keep includes cheap
+ * to type.
+ */
+type RelationMeasureArg<M extends AnyModels, T extends keyof M> = { readonly [R in ManyRelations<M, T>]?: MeasureArg<M, Extract<TargetOf<Relations<M, T>[R]>, keyof M>>; };
+type ManyRelations<M extends AnyModels, T extends keyof M> = { [R in keyof Relations<M, T>]: Relations<M, T>[R] extends {
+  readonly kind: "many";
+} ? R : never; }[keyof Relations<M, T>];
+type CountArg<M extends AnyModels, T extends keyof M> = { readonly [R in ManyRelations<M, T>]?: true | {
+  readonly where?: WhereInput<M, Extract<TargetOf<Relations<M, T>[R]>, keyof M>>;
+}; };
+type TargetOf<R> = R extends {
+  readonly table: infer X;
+} ? X : never;
+/** Per-call request settings every repository method takes. */
+interface RequestArgs {
+  readonly signal?: AbortSignal;
+  /**
+   * Fails the call with a `timeout` error after this many milliseconds,
+   * composed with `signal` (`AbortSignal.any`). Replaces the connection's
+   * `timeout`. SQL executors only check it before the statement starts.
+   */
+  readonly timeout?: number;
+  /**
+   * Postgrest-js retries of idempotent requests (reads) on network errors, 503
+   * and 520; `false` turns them off for this call. Writes are never retried.
+   * SQL executors ignore it.
+   */
+  readonly retry?: boolean;
+}
+interface ReadArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  /** Related counts go inside `include`: `include: { _count: { notes: true } }`. */
+  readonly _count?: never;
+  /** Related aggregates go inside `include`; `aggregate()` aggregates the table. */
+  readonly _sum?: never;
+  readonly _avg?: never;
+  readonly _min?: never;
+  readonly _max?: never;
+}
+interface ListArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M, T> {
+  readonly where?: WhereArg<M, T>;
+  readonly orderBy?: OrderByArg<M, T>;
+  readonly limit?: number;
+  readonly offset?: number;
+}
+/** `get()` options. */
+interface GetArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M, T> {
+  /** Resolve to `null` instead of a `not_found` error when no row matches. */
+  readonly optional?: boolean;
+}
+interface CountArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  readonly where?: WhereArg<M, T>;
+  readonly mode?: "exact" | "planned" | "estimated";
+}
+interface AggregateArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  readonly where?: WhereArg<M, T>;
+  /** One result per distinct combination; without it, one result. */
+  readonly groupBy?: SelectArg<M, T>;
+  /** The number of rows (per group). */
+  readonly _count?: true;
+  readonly _sum?: NumericMeasureArg<M, T>;
+  readonly _avg?: NumericMeasureArg<M, T>;
+  readonly _min?: MeasureArg<M, T>;
+  readonly _max?: MeasureArg<M, T>;
+  /** Sorts groups by `groupBy` columns, `_count` and measures. */
+  readonly orderBy?: AggregateOrderByArg<M, T>;
+  readonly limit?: number;
+  readonly offset?: number;
+}
+/**
+ * Sorts `aggregate()` groups: `{ _count: "desc" }`, `{ _sum: { amount: "desc" }
+ * }` or a `groupBy` column.
+ */
+type AggregateOrderBy<M extends AnyModels, T extends keyof M> = ColumnOrderBy<M, T> & {
+  readonly _count?: SortSpec;
+  readonly _sum?: { readonly [K in NumericKey<M, T>]?: SortSpec; };
+  readonly _avg?: { readonly [K in NumericKey<M, T>]?: SortSpec; };
+  readonly _min?: ColumnOrderBy<M, T>;
+  readonly _max?: ColumnOrderBy<M, T>;
+};
+type AggregateOrderByArg<M extends AnyModels, T extends keyof M> = AggregateOrderBy<M, T> | readonly AggregateOrderBy<M, T>[];
+type SelectPart<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly select: readonly (infer K)[];
+} ? Pick<Row<M, T>, Extract<K, keyof Row<M, T>>> : Row<M, T>;
+/**
+ * `required: true` drops parents without the related row, so it is never
+ * `null`.
+ */
+type RelationPayload<M extends AnyModels, R, V> = R extends RelationTypes ? R["kind"] extends "many" ? Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V>[] : R["nullable"] extends true ? V extends {
+  readonly required: true;
+} ? Payload<M, Extract<R["table"], keyof M>, V> : Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V> | null : Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V> : never;
+type IncludePart<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly include: infer I;
+} ? { -readonly [R in keyof I & keyof Relations<M, T>]: RelationPayload<M, Relations<M, T>[R], I[R]>; } & CountPart<I> & ([keyof I & MeasureKey] extends [never] ? unknown : RelationMeasures<M, T, I>) : unknown;
+type CountPart<I> = I extends {
+  readonly _count: infer C;
+} ? {
+  _count: { -readonly [R in keyof C]: number; };
+} : unknown;
+/**
+ * `_avg` is a number; `_sum` keeps exact `bigint` and `string` (numeric)
+ * columns; `_min`/`_max` have the column's type. All are `null` without rows.
+ */
+type MeasureValue<K extends MeasureKey, V> = K extends "_avg" ? number | null : K extends "_sum" ? [NonNullable<V>] extends [bigint] ? bigint | null : [NonNullable<V>] extends [string] ? string | null : number | null : NonNullable<V> | null;
+type MeasuresOf<M extends AnyModels, T extends keyof M, C, K extends MeasureKey> = { -readonly [P in keyof C & keyof Row<M, T>]: MeasureValue<K, Row<M, T>[P]>; };
+type RelationMeasures<M extends AnyModels, T extends keyof M, I> = { -readonly [K in keyof I & MeasureKey]: { -readonly [R in keyof I[K] & keyof Relations<M, T>]: MeasuresOf<M, Extract<TargetOf<Relations<M, T>[R]>, keyof M>, I[K][R], K>; }; };
+type RootMeasures<M extends AnyModels, T extends keyof M, A, K extends MeasureKey> = A extends { readonly [P in K]: infer C; } ? { [P in K]: MeasuresOf<M, T, C, K>; } : unknown;
+/** One aggregate result: the `groupBy` columns, `_count` and each measure. */
+type AggregateRow<M extends AnyModels, T extends keyof M, A> = Simplify<(A extends {
+  readonly groupBy: readonly (infer K)[];
+} ? Pick<Row<M, T>, Extract<K, keyof Row<M, T>>> : unknown) & (A extends {
+  readonly _count: true;
+} ? {
+  _count: number;
+} : unknown) & RootMeasures<M, T, A, "_sum"> & RootMeasures<M, T, A, "_avg"> & RootMeasures<M, T, A, "_min"> & RootMeasures<M, T, A, "_max">>;
+/** `aggregate()` returns one row per group with `groupBy`, else one row. */
+type AggregateResult<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly groupBy: readonly unknown[];
+} ? AggregateRow<M, T, A>[] : AggregateRow<M, T, A>;
+/** The row type returned for read arguments `A` on table `T`. */
+type Payload<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly include: unknown;
+} ? Simplify<SelectPart<M, T, A> & IncludePart<M, T, A>> : A extends {
+  readonly select: readonly unknown[];
+} ? Simplify<SelectPart<M, T, A>> : Row<M, T>;
+//#endregion
+//#region src/core/spec.d.ts
+type ReadMethod = "list" | "page" | "get" | "count" | "aggregate";
+declare const resultType: unique symbol;
+/**
+ * A read, described as plain JSON: build it with `betterSupabase.spec`, run it
+ * with `db.$run(spec)`, send it from a Server Component to the client, or hand
+ * it to `/query` and `/next`. Args never carry a `signal`.
+ */
+interface QuerySpec<T extends string = string, K extends ReadMethod = ReadMethod, R = unknown> {
+  readonly v: 1;
+  readonly table: T;
+  readonly method: K;
+  /** Positional arguments of the repository method. */
+  readonly args: readonly unknown[];
+  /** Type-only: the result `db.$run(spec)` resolves to. */
+  readonly [resultType]?: R;
+}
+/** The result type of a `QuerySpec`. */
+type InferResult<S> = S extends QuerySpec<string, ReadMethod, infer R> ? R : never;
+type NoSignal<A> = Omit<A, "signal">;
+interface TableSpecs<M extends AnyModels, T extends TableKey<M>, E> {
+  list<const A extends NoSignal<ListArgs<M, T>> & FindExt<E, M, T>>(args?: A): QuerySpec<T, "list", Payload<M, T, A>[]>;
+  page<const A extends NoSignal<OffsetPageArgs<M, T> | OffsetRangeArgs<M, T> | CursorPageArgs<M, T>> & FindExt<E, M, T>>(args: A): QuerySpec<T, "page", PageOf<M, T, A>>;
+  get<const A extends NoSignal<GetArgs<M, T>> & FindExt<E, M, T>>(key: GetKey<M, T>, args?: A): QuerySpec<T, "get", A extends {
+    readonly optional: true;
+  } ? Payload<M, T, A> | null : Payload<M, T, A>>;
+  count(args?: NoSignal<CountArgs<M, T>> & FindExt<E, M, T>): QuerySpec<T, "count", number>;
+  aggregate<const A extends NoSignal<AggregateArgs<M, T>> & FindExt<E, M, T>>(args: A): QuerySpec<T, "aggregate", AggregateResult<M, T, A>>;
+}
+type Specs<M extends AnyModels, E> = { readonly [T in TableKey<M>]: TableSpecs<M, T, E>; };
+declare function isQuerySpec(value: unknown): value is QuerySpec;
+/**
+ * App keys of every table a spec reads: its table, included relations and
+ * relations used in `where`. Queries keyed by a spec go stale when any of them
+ * changes. Invalid arguments yield just the spec's table; running the spec
+ * reports the error.
+ */
+declare function specTables(meta: SchemaMeta, spec: QuerySpec): string[];
+//#endregion
+//#region src/core/read-set.d.ts
+type ScalarParamType = "uuid" | "text" | "bool" | "int2" | "int4" | "int8" | "float4" | "float8" | "numeric" | "date" | "timestamp" | "timestamptz";
+/**
+ * The Postgres type of a read-set parameter. `[]` types take an array. Name
+ * enums and domains with their schema (`public.note_kind`): the function runs
+ * with an empty `search_path`.
+ */
+type ReadSetParamType = ScalarParamType | `${ScalarParamType}[]` | `${string}.${string}`;
+type ReadSetParamTypes = Readonly<Record<string, ReadSetParamType>>;
+type ScalarValue<T> = T extends "int2" | "int4" | "int8" | "float4" | "float8" | "numeric" ? number : T extends "bool" ? boolean : string;
+/** The value a parameter of type `T` takes. */
+type ReadSetParamValue<T> = T extends `${infer E}[]` ? readonly ScalarValue<E>[] : ScalarValue<T>;
+type ReadSetParams<P extends ReadSetParamTypes> = { readonly [K in keyof P]: ReadSetParamValue<P[K]>; };
+/**
+ * Placeholders for the caller's identity, the third argument of a read set's
+ * builder. The function reads them in the database, so callers can't pass
+ * someone else's.
+ */
+interface ReadSetAuth {
+  /**
+   * The caller's user id: `auth.uid()` in the function, the JWT `sub` claim
+   * otherwise.
+   */
+  readonly uid: string;
+}
+type ReadSetRole = "anon" | "authenticated";
+/**
+ * Named reads that run together: one `stable` function over PostgREST (a single
+ * GET), one transaction over SQL. Build it with `defineReadSet`, run it with
+ * `db.$many(readSet, params)`.
+ */
+interface ReadSet<N extends string = string, P extends ReadSetParamTypes = ReadSetParamTypes, S extends Readonly<Record<string, QuerySpec>> = Readonly<Record<string, QuerySpec>>> {
+  readonly kind: "read-set";
+  readonly name: N;
+  /** The database function `better-supabase gen` writes for this set. */
+  readonly functionName: `rs_${N}`;
+  readonly params: P;
+  /** Roles granted execute on the function. */
+  readonly roles: readonly ReadSetRole[];
+  /** The reads, with placeholders where parameters go. */
+  readonly specs: S;
+  readonly definition: BetterSupabase;
+}
+/** What `db.$many(readSet, params)` resolves to. */
+type ReadSetResult<S> = S extends ReadSet<string, ReadSetParamTypes, infer Q> ? { readonly [K in keyof Q]: InferResult<Q[K]>; } : never;
+/** The parameters `db.$many(readSet, params)` takes. */
+type InferReadSetParams<S> = S extends ReadSet<string, infer P> ? ReadSetParams<P> : never;
+interface ReadSetOptions<P extends ReadSetParamTypes> {
+  readonly params?: P;
+  /** Roles that may call the function. Defaults to `['authenticated']`. */
+  readonly roles?: readonly ReadSetRole[];
+}
+/**
+ * Registers reads that run as one round trip:
+ *
+ * ```ts
+ * export const appChrome = defineReadSet(
+ *   betterSupabase,
+ *   "app_chrome",
+ *   { params: { userId: "uuid" } },
+ *   (s, p) => ({
+ *     unread: s.notifications.count({
+ *       where: { userId: p.userId, readAt: null },
+ *     }),
+ *     me: s.profiles.get({ where: { id: p.userId } }, { optional: true }),
+ *   }),
+ * );
+ * ```
+ *
+ * `p` holds placeholders, not values: pass them straight into `where` (or
+ * `in`), where the function reads them from its `p jsonb` argument.
+ */
+declare function defineReadSet<M extends AnyModels, D, F extends AnyFunctions, E, const N extends string, const P extends ReadSetParamTypes, const S extends Readonly<Record<string, QuerySpec>>>(betterSupabase: BetterSupabase<M, D, F, E>, name: N, options: ReadSetOptions<P>, build: (specs: Specs<M, E>, params: ReadSetParams<P>, auth: ReadSetAuth) => S): ReadSet<N, P, S>;
+declare function isReadSet(value: unknown): value is ReadSet;
+/** App keys of every table the set reads. */
+declare function readSetTables(set: ReadSet, meta?: SchemaMeta): string[];
+//#endregion
+//#region src/core/search.d.ts
+/** `db.$search(table, args)`: the `k` rows nearest to `vector`. */
+type SearchArgs<M extends AnyModels, T extends keyof M> = Pick<ListArgs<M, T>, "select" | "include" | "where" | "signal"> & {
+  /**
+   * The query embedding, as numbers or pgvector text (`'[0.1,0.2]'`). Leave it
+   * out (or pass `null`) with `text` on a `hybrid` entry to rank by full-text
+   * search alone, such as when the embedding call failed.
+   */
+  readonly vector?: readonly number[] | string | null;
+  /** Rows to return. Defaults to 10. */
+  readonly k?: number;
+  /**
+   * Values for the entry's `prefilter` columns, applied before ranking: a value
+   * or a list (`null` matches a null column).
+   */
+  readonly filter?: Readonly<Record<string, unknown>>;
+  /** The text query a `hybrid` entry ranks with full-text search. */
+  readonly text?: string;
+  /** Adds `$score` to each row: the entry's similarity, fused and boosted. */
+  readonly score?: boolean;
+};
+/** What `db.$search` adds to each row with `score: true`. */
+type SearchScore<A> = A extends {
+  readonly score: true;
+} ? {
+  readonly $score: number;
+} : unknown;
+//#endregion
+//#region src/core/stats.d.ts
+/** Database work for one request (or one `db`). */
+interface DbStats {
+  /** Executor calls: repository operations and RPCs. */
+  readonly calls: number;
+  /**
+   * Sequential rounds. A wave starts when a call begins while nothing else is
+   * in flight, so `Promise.all` of three reads is one wave.
+   */
+  readonly waves: number;
+  /** App keys of the tables read or written, and `name()` for RPCs. */
+  readonly tables: readonly string[];
+  /** From the first call's start to the last call's end. */
+  readonly ms: number;
+}
+declare const EMPTY_STATS: DbStats;
+/**
+ * Counts calls and waves. A recorder with a `parent` also reports to it, so a
+ * request-wide recorder sees every scope's calls.
+ */
+declare class StatsRecorder {
+  #private;
+  constructor(parent?: StatsRecorder, now?: () => number);
+  /** Records a call to `table`; the returned function ends it. */
+  begin(table: string): () => void;
+  /** The totals so far. */
+  snapshot(): DbStats;
+}
+/** Wraps an executor so every call is recorded. */
+declare function recordStats(executor: Executor, recorder: StatsRecorder): Executor;
+//#endregion
+//#region src/core/repository-types.d.ts
+type FindExt<E, M extends AnyModels, T extends keyof M> = ApplyExtension<E, M, T, "findArgs">;
+type DeleteExt<E, M extends AnyModels, T extends keyof M> = ApplyExtension<E, M, T, "deleteArgs">;
+interface WriteArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M, T> {
+  /** `false` skips `RETURNING` (needed when RLS hides the written row). */
+  readonly returning?: boolean;
+  /**
+   * Keep caller-supplied values for columns that `updatedAtExtension()`,
+   * `createdByExtension()` and `trashExtension()` fill (imports, backfills).
+   * Without it they are refused.
+   */
+  readonly override?: boolean;
+}
+interface UpdateArgs<M extends AnyModels, T extends keyof M> extends WriteArgs<M, T> {
+  /**
+   * More conditions the row must meet, such as a tenant or a status. A row with
+   * this key that does not match returns `not_found`, in one request.
+   */
+  readonly where?: WhereInput<M, T>;
+  /**
+   * Optimistic concurrency: the update only applies when the row still matches.
+   * Plain values mean equality; operators work as in `where`. A mismatch
+   * returns a `stale` error, found with a second request.
+   */
+  readonly expect?: WhereInput<M, T>;
+}
+/**
+ * The result of a many-row write by its `returning` option. Each case of
+ * `returning` (`true`, `false`, absent) picks rows or `{ count }`, and a
+ * widened `boolean` gives both. `Default` is what an absent option means:
+ * `true` for `create` and `upsert` with an array, `false` for `update` and
+ * `delete` with a filter.
+ */
+type ManyOutcome<M extends AnyModels, T extends keyof M, A, Default extends boolean> = ReturningOption<A> extends (infer R) ? R extends true ? Payload<M, T, A>[] : R extends false ? {
+  count: number;
+} : Default extends true ? Payload<M, T, A>[] : {
+  count: number;
+} : never;
+type ReturningOption<A> = "returning" extends keyof A ? A["returning" & keyof A] : undefined;
+/**
+ * `update({ where })` and `delete({ where })` return the rows with `returning:
+ * true`.
+ */
+type ManyResult<M extends AnyModels, T extends keyof M, A> = ManyOutcome<M, T, A, false>;
+/** A filter that picks several rows for `update` and `delete`. */
+interface RowFilter<M extends AnyModels, T extends keyof M> {
+  readonly where: WhereInput<M, T>;
+}
+/** What `get()` takes: a primary key, a unique key or a filter. */
+type GetKey<M extends AnyModels, T extends keyof M> = PrimaryKeyValue<M, T> | UniqueWhere<M, T> | RowFilter<M, T>;
+/** Options of `update({ where })` and `delete({ where })`. */
+interface ManyWriteArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  /** Return the written rows instead of `{ count }`. */
+  readonly returning?: boolean;
+  /** The columns to return with `returning: true`. */
+  readonly select?: ReadArgs<M, T>["select"];
+  /** Related rows to return with `returning: true`. */
+  readonly include?: ReadArgs<M, T>["include"];
+  /**
+   * The most rows the call may change. When `where` matches more, the call
+   * fails with `max_affected` and changes nothing. Over PostgREST it needs
+   * PostgREST 13 or later (`Prefer: max-affected`).
+   */
+  readonly maxAffected?: number;
+  /** How `{ count }` is counted over PostgREST. Defaults to `exact`. */
+  readonly count?: CountMode;
+}
+/** Options of `create` and `upsert` with an array of rows. */
+interface WriteManyArgs<M extends AnyModels, T extends keyof M> extends WriteArgs<M, T> {
+  /**
+   * Columns some rows leave out become `null` instead of their column default.
+   * Defaults to `false`, so a left-out column takes its default.
+   */
+  readonly defaultToNull?: boolean;
+  /**
+   * How `{ count }` is counted over PostgREST with `returning: false`. Defaults
+   * to `exact`.
+   */
+  readonly count?: CountMode;
+}
+type ConflictTarget<M extends AnyModels, T extends keyof M> = "primaryKey" | UniqueKeyName<M, T> | readonly Extract<keyof Row<M, T>, string>[];
+interface UpsertArgs<M extends AnyModels, T extends keyof M> extends WriteArgs<M, T> {
+  /** Unique constraint name or column list. Defaults to the primary key. */
+  readonly onConflict?: ConflictTarget<M, T>;
+  /** Keep the existing row instead of updating it (`ON CONFLICT DO NOTHING`). */
+  readonly ignoreDuplicates?: boolean;
+}
+type DeleteArgs = RequestArgs;
+/** Options of `upsert` with an array of rows. */
+interface UpsertManyArgs<M extends AnyModels, T extends keyof M> extends UpsertArgs<M, T>, WriteManyArgs<M, T> {}
+type Returned<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly returning: false;
+} ? null : Payload<M, T, A>;
+type OffsetPageArgs<M extends AnyModels, T extends keyof M> = Omit<ListArgs<M, T>, "limit" | "offset"> & {
+  /** 1-based page number. Defaults to 1. */
+  readonly page?: number;
+  readonly size: number;
+  /** Also count all matching rows. */
+  readonly count?: CountMode;
+  /** Shorthand for `count: "exact"`. */
+  readonly withCount?: boolean;
+  readonly offset?: never;
+  readonly limit?: never;
+};
+type OffsetRangeArgs<M extends AnyModels, T extends keyof M> = Omit<ListArgs<M, T>, "limit" | "offset"> & {
+  /** Rows to skip before the page. */
+  readonly offset: number;
+  readonly limit: number;
+  /** Also count all matching rows. */
+  readonly count?: CountMode;
+  /** Shorthand for `count: "exact"`. */
+  readonly withCount?: boolean;
+  readonly page?: never;
+  readonly size?: never;
+};
+type CursorPageArgs<M extends AnyModels, T extends keyof M> = Omit<ListArgs<M, T>, "limit" | "offset"> & {
+  /** Cursor from the previous page, or `null` for the first page. */
+  readonly after: string | null;
+  readonly size: number;
+  /**
+   * Also count every row matching `where` (ignoring the cursor) and return it
+   * as `total`. The first page reads it from the page request; later pages cost
+   * one more request.
+   */
+  readonly withCount?: boolean;
+};
+interface OffsetPage<R, Counted extends boolean = false> {
+  readonly items: R[];
+  readonly page: {
+    readonly number: number;
+    readonly size: number;
+    readonly total: Counted extends true ? number : number | null;
+    readonly pages: Counted extends true ? number : number | null;
+    readonly hasMore: boolean;
+  };
+}
+interface CursorPage<R> {
+  readonly items: R[];
+  readonly nextCursor: string | null;
+  readonly hasMore: boolean;
+}
+/** A cursor page that was asked for a count. */
+type CountedCursorPage<R> = CursorPage<R> & {
+  readonly total: number;
+};
+type IsCounted<A> = A extends {
+  readonly withCount: true;
+} ? true : A extends {
+  readonly count: "exact" | "planned" | "estimated";
+} ? true : false;
+type PageOf<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly after: unknown;
+} ? IsCounted<A> extends true ? CountedCursorPage<Payload<M, T, A>> : CursorPage<Payload<M, T, A>> : IsCounted<A> extends true ? OffsetPage<Payload<M, T, A>, true> : OffsetPage<Payload<M, T, A>>;
+interface Repository<M extends AnyModels, T extends TableKey<M>, E = unknown> {
+  readonly $tableName: T;
+  readonly $meta: TableMeta;
+  /** The rows matching `where`, ordered by `orderBy` or the primary key. */
+  list<const A extends ListArgs<M, T> & FindExt<E, M, T>>(args?: A): AsyncResult<Payload<M, T, A>[]>;
+  /**
+   * One page of rows: by page number (`page`, `size`), by offset (`offset`,
+   * `limit`) or by cursor (`after`, `size`).
+   */
+  page<const A extends (OffsetPageArgs<M, T> | OffsetRangeArgs<M, T> | CursorPageArgs<M, T>) & FindExt<E, M, T>>(args: A): AsyncResult<PageOf<M, T, A>>;
+  /**
+   * The row with this primary key, these values for one unique key (`{ email
+   * }`, `{ organizationId, slug }`), or the one row matching `{ where }`. No
+   * row is a `not_found` error, or `null` with `optional: true`; several rows
+   * matching `{ where }` are a `multiple_rows` error.
+   */
+  get<const A extends GetArgs<M, T> & FindExt<E, M, T>>(key: GetKey<M, T>, args?: A): AsyncResult<A extends {
+    readonly optional: true;
+  } ? Payload<M, T, A> | null : Payload<M, T, A>>;
+  count(args?: CountArgs<M, T> & FindExt<E, M, T>): AsyncResult<number>;
+  /**
+   * Counts, sums, averages, minimums and maximums in one request, grouped by
+   * `groupBy` columns. Needs `pgrst.db_aggregates_enabled` over PostgREST.
+   */
+  aggregate<const A extends AggregateArgs<M, T> & FindExt<E, M, T>>(args: A): AsyncResult<AggregateResult<M, T, A>>;
+  /** Inserts one row, or several in one request when given an array. */
+  /** Inserts one row, or several in one request when given an array. */
+  create<const A extends WriteArgs<M, T> = {}>(data: Insert<M, T>, args?: A): AsyncResult<Returned<M, T, A>>;
+  create<const A extends WriteManyArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): AsyncResult<ManyOutcome<M, T, A, true>>;
+  /**
+   * Updates the row with this key, or every row matching `{ where }`. A filter
+   * that matches no rows by construction (empty, or every value `undefined`)
+   * fails with `invalid_request` unless `allowAll` is `true`.
+   */
+  update(filter: RowFilter<M, T>, patch: Update<M, T>): AsyncResult<{
+    count: number;
+  }>;
+  update<const A extends ManyWriteArgs<M, T> & {
+    /** Update every visible row when `where` filters nothing. */
+    readonly allowAll?: boolean;
+  } & FindExt<E, M, T>>(filter: RowFilter<M, T>, patch: NoInfer<Update<M, T>>, args: A): AsyncResult<ManyResult<M, T, A>>;
+  update<const A extends UpdateArgs<M, T> = {}>(id: PrimaryKeyValue<M, T>, patch: Update<M, T>, args?: A): AsyncResult<Returned<M, T, A>>;
+  /** Inserts or updates one row, or several when given an array. */
+  upsert<const A extends UpsertArgs<M, T> = {}>(data: Insert<M, T>, args?: A): AsyncResult<A extends {
+    readonly ignoreDuplicates: true;
+  } ? Returned<M, T, A> | null : Returned<M, T, A>>;
+  upsert<const A extends UpsertManyArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): AsyncResult<ManyOutcome<M, T, A, true>>;
+  /**
+   * Deletes the row with this key (`not_found` when no visible row has it), or
+   * every row matching `{ where }`, which must filter rows.
+   */
+  delete(filter: RowFilter<M, T>): AsyncResult<{
+    count: number;
+  }>;
+  delete<const A extends ManyWriteArgs<M, T> & DeleteExt<E, M, T> & FindExt<E, M, T>>(filter: RowFilter<M, T>, args: A): AsyncResult<ManyResult<M, T, A>>;
+  delete(id: PrimaryKeyValue<M, T>, args?: DeleteArgs & DeleteExt<E, M, T>): AsyncResult<void>;
+  /** Adds methods built on this repository. */
+  extend<X extends object>(build: (base: this) => X): this & X;
+}
+type RepositoryOf<M extends AnyModels, T extends TableKey<M>, E> = Repository<M, T, E> & ApplyExtension<E, M, T, "methods">;
+interface RpcOptions<R> extends RequestArgs {
+  /**
+   * Validates the return value after decoding, so the schema sees the
+   * configured casing and codecs; the result carries its output type.
+   */
+  readonly returns?: StandardSchemaV1<unknown, R>;
+  readonly schema?: string;
+  /**
+   * Return what PostgREST sent, with database names and no codecs. Rows of a
+   * table or a `returns table (...)` record are decoded like reads otherwise.
+   */
+  readonly raw?: boolean;
+}
+type RpcArgs<F extends AnyFunctions, N extends keyof F> = Record<never, never> extends F[N]["Args"] ? [args?: F[N]["Args"]] : [args: F[N]["Args"]];
+type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
+/** Names generated as a union of `{ Args; Returns }`, one per overload. */
+type OverloadedName<F extends AnyFunctions> = { [K in keyof F]: true extends IsUnion<F[K]> ? K : never; }[keyof F] & string;
+type PlainName<F extends AnyFunctions> = Exclude<Extract<keyof F, string>, OverloadedName<F>>;
+/** Overloaded names with an overload that a call without arguments matches. */
+type NoArgName<F extends AnyFunctions> = { [K in OverloadedName<F>]: Record<never, never> extends F[K]["Args"] ? K : never; }[OverloadedName<F>];
+/**
+ * Property names without index signatures (`Record<PropertyKey, never>` has
+ * none).
+ */
+type KnownKeys<T> = keyof { [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: 0; };
+type RequiredKeys<T> = { [K in keyof T]-?: Record<never, never> extends Pick<T, K> ? never : K; }[keyof T];
+/**
+ * The overloads PostgREST can pick for arguments `A`: every name in `A` is an
+ * argument, and every argument without a default is in `A`. Overloads with the
+ * same names stay a union, since the call can't tell them apart.
+ */
+type MatchingOverload<O, A> = A extends unknown ? O extends {
+  readonly Args: infer OA;
+} ? [Exclude<keyof A, KnownKeys<OA>>] extends [never] ? [Exclude<RequiredKeys<OA>, keyof A>] extends [never] ? O : never : never : never : never;
+type OverloadReturns<O, A> = [MatchingOverload<O, A>] extends [never] ? O extends {
+  readonly Returns: infer R;
+} ? R : never : MatchingOverload<O, A> extends {
+  readonly Returns: infer R;
+} ? R : never;
+/**
+ * `A` when its names pick an overload, with a name that no overload takes typed
+ * `never`, and `never` when the names mix overloads.
+ */
+type OverloadArgs<O extends {
+  readonly Args: unknown;
+}, A> = A & NoInfer<[MatchingOverload<O, A>] extends [never] ? never : { readonly [K in Exclude<keyof A, O extends {
+  readonly Args: infer OA;
+} ? KnownKeys<OA> : never>]: never; }>;
+type RawRpcOptions = Omit<RpcOptions<unknown>, "returns" | "raw"> & {
+  readonly raw: true;
+};
+interface DbHelpers<M extends AnyModels, F extends AnyFunctions, E, C, B = unknown> {
+  /** The underlying client (supabase-js), for anything the repository lacks. */
+  readonly $client: C;
+  /**
+   * Storage as the same caller: `connect()`'s `storage` option, or the client's
+   * `storage`. Pass it to `bucket.connect()` and the blocks, so Storage follows
+   * whatever the `Db` runs as. Throws when the connection has neither, such as
+   * a bare `Executor`.
+   */
+  readonly $storage: StorageApi;
+  readonly $executor: Executor;
+  readonly $context: RequestContext;
+  /**
+   * Calls a database function with typed arguments. Rows of a table or a
+   * `returns table (...)` record come back in the configured casing, with
+   * codecs applied; `raw: true` returns them as PostgREST sent them.
+   */
+  $rpc<N extends PlainName<F>>(name: N, ...rest: [...RpcArgs<F, N>, options: RawRpcOptions]): AsyncResult<unknown>;
+  $rpc<N extends PlainName<F>, R = F[N]["Returns"]>(name: N, ...rest: [...RpcArgs<F, N>, options?: RpcOptions<R>]): AsyncResult<R>;
+  /**
+   * An overloaded function: the arguments match one overload, and the result is
+   * the return type of the overloads with those argument names.
+   */
+  $rpc<N extends OverloadedName<F>, const A extends F[N]["Args"]>(name: N, args: OverloadArgs<F[N], A>, options: RawRpcOptions): AsyncResult<unknown>;
+  $rpc<N extends OverloadedName<F>, const A extends F[N]["Args"], R = OverloadReturns<F[N], A>>(name: N, args: OverloadArgs<F[N], A>, options?: RpcOptions<R>): AsyncResult<R>;
+  $rpc<N extends NoArgName<F>>(name: N): AsyncResult<OverloadReturns<F[N], Record<never, never>>>;
+  /** Same connection with more context (for example a tenant). */
+  $with(context: RequestContext): Db<M, F, E, C, B>;
+  /**
+   * Same connection without plugins: no tenant scoping, soft-delete filters,
+   * timestamps, rules or executor wrappers. For migrations and admin tools.
+   * `keep` names plugins to leave installed, such as tracing (`keep:
+   * ["otel"]`); a name that isn't installed throws a `TypeError`.
+   */
+  $withoutPlugins(options?: {
+    readonly keep?: readonly string[];
+  }): Db<M, F, unknown, C, B>;
+  /**
+   * The repository for a table named at runtime (MCP tools, admin screens).
+   * Throws a `TypeError` for unknown names.
+   */
+  $table<T extends TableKey<M>>(name: T): RepositoryOf<M, T, E>;
+  /** Calls, waves, tables and time for everything run through this `db`. */
+  $stats(): DbStats;
+  /** Runs a `QuerySpec` built with `betterSupabase.spec`. */
+  $run<S extends QuerySpec<TableKey<M>>>(spec: S, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<InferResult<S>>;
+  /**
+   * Runs a read set as one round trip: a single GET to its function over
+   * PostgREST, one transaction over SQL. Query plugins don't apply; RLS does.
+   */
+  $many<S extends ReadSet>(readSet: S, params: InferReadSetParams<S>, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<ReadSetResult<S>>;
+  /**
+   * Runs specs together: in parallel over PostgREST, in one transaction when
+   * the executor has `batch`. Fails with the first error.
+   */
+  $many<const S extends readonly QuerySpec<TableKey<M>>[]>(specs: S, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<{ -readonly [K in keyof S]: InferResult<S[K]>; }>;
+  /**
+   * The `k` rows nearest to `vector`, nearest first, through the
+   * `search_<table>` function of the `vector-search` SQL module. RLS applies
+   * inside the search; `where` filters the `k` rows it returns.
+   */
+  $search<T extends TableKey<M>, const A extends SearchArgs<M, T>>(table: T, args: A): AsyncResult<(Payload<M, T, A> & SearchScore<A>)[]>;
+}
+type Db<M extends AnyModels, F extends AnyFunctions, E, C, B = unknown> = { readonly [T in TableKey<M>]: RepositoryOf<M, T, E>; } & DbHelpers<M, F, E, C, B> & BucketsHelper<BucketsOf<B>> & BlocksHelper<BlockClientsOf<B>, TableKey<M>>;
+//#endregion
+//#region src/core/db-blocks.d.ts
+/**
+ * What `betterSupabase.blocks()` takes: the `BlockSet` that `defineBlocks`
+ * returns. The core reads it structurally, so it imports no block code.
+ */
+interface DbBlockSource {
+  /** The keys in `blocks.generated.ts` of the instances that have a client. */
+  readonly instances: readonly string[];
+  /**
+   * One instance's client over `db`: its calls run through `db`'s executor and
+   * act in `db.$context.tenant`.
+   */
+  client(db: object, key: string, options: {
+    readonly events: EventHub;
+  }): unknown;
+  /** Calls a function in the API schema that the blocks are wrapped in. */
+  call(db: object, fn: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+  /**
+   * What one instance's client serves, for `defineApi`: its methods and the
+   * input schemas of its entities. `undefined` when the client can't be built
+   * without a database.
+   */
+  describe?(key: string): BlockInstanceSurface | undefined;
+  /**
+   * Types only, never set: the clients by property, which `BlockSetClients`
+   * reads.
+   */
+  readonly $clients?: object;
+}
+/** One block instance's client, as `DbBlockSource.describe` reports it. */
+interface BlockInstanceSurface {
+  /** The block's name, such as `comments`. */
+  readonly block: string;
+  /** The client's async methods: contract verbs and domain verbs. */
+  readonly methods: readonly string[];
+  /** The methods of each sub-client, such as `chats` on ai-chat. */
+  readonly members: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Standard Schemas (with Standard JSON Schema) of what the client takes, by
+   * entity key: `input` for create, `change` for update, `listFilter` for
+   * list.
+   */
+  readonly schemas: Readonly<Record<string, {
+    readonly input?: unknown;
+    readonly change?: unknown;
+    readonly listFilter?: unknown;
+  }>>;
+}
+/** The clients a `DbBlockSource` puts on every `Db`, by property. */
+type BlockSetClients<S> = S extends {
+  readonly $clients?: infer K;
+} ? NonNullable<K> : object;
+/**
+ * What a definition registers beyond its schema: `buckets()` and `blocks()`.
+ * The `Db` type reads it for `$buckets` and the block instances.
+ */
+interface DbExtras {
+  readonly buckets?: BucketRegistry;
+  readonly blocks?: object;
+}
+/** `B` with `key` set to `value`. */
+type WithExtra<B, K extends keyof DbExtras, V> = Omit<unknown extends B ? object : B, K> & { readonly [P in K]: V; };
+/** The buckets in `B`, a definition's `DbExtras`. */
+type BucketsOf<B> = B extends {
+  readonly buckets: infer R;
+} ? R : unknown;
+/** The block clients in `B`, a definition's `DbExtras`. */
+type BlockClientsOf<B> = B extends {
+  readonly blocks: infer K;
+} ? K : unknown;
+/**
+ * Each block instance on a `Db`, under its key in camel case (`db.tags`,
+ * `db.leadScoring`) unless a table `T` holds that property, and always under
+ * `db.$blocks`, plus `$api` for the API schema's other functions.
+ */
+type BlocksHelper<K, T extends PropertyKey = never> = unknown extends K ? unknown : Omit<K, T> & {
+  /** Every block instance, including those whose property a table holds. */
+  readonly $blocks: K;
+  /**
+   * Calls `fn` in the API schema the blocks are wrapped in, as the `Db`'s
+   * caller. Resolves to the function's result and rejects with the raw
+   * database error.
+   */
+  $api(fn: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+};
+/**
+ * The `Db` a definition connects in the browser: what `bsb.db` holds and what
+ * the generated data hooks read (`DbOf<typeof betterSupabase>`).
+ */
+type DbOf<T> = T extends BetterSupabase<infer M, infer _D, infer F, infer E, infer _C, infer _P, infer B> ? Db<M, F, E, SupabaseClient, B> : never;
+//#endregion
+//#region src/core/define-types.d.ts
+interface SupabaseOptions {
+  /** Set by `betterSupabase.buckets()`; read by `db.$buckets`. */
+  readonly buckets?: BucketRegistry;
+  /** Set by `betterSupabase.blocks()`; read by the block instances on a `Db`. */
+  readonly blocks?: DbBlockSource;
+  /**
+   * Clock used by plugins (timestamps, soft delete) and for the `time` of block
+   * events on `betterSupabase.events`. Pass it to `createQueue` too.
+   */
+  readonly now?: () => Temporal.Instant;
+  /**
+   * The `Temporal` namespace, for runtimes without a global one (Hermes, Node 24)
+   * when patching `globalThis` is not an option: `import { Temporal } from
+   * 'temporal-polyfill'`. Defaults to `globalThis.Temporal`.
+   */
+  readonly temporal?: typeof Temporal;
+  /** Extra error mappers, run before plugin mappers. */
+  readonly errors?: readonly ErrorMapper[];
+  /**
+   * Receives errors from event handlers, hooks and cache adapters. Defaults to
+   * `console`.
+   */
+  readonly logger?: Logger;
+  /**
+   * Debug records on `logger` for every query, database error, session refresh
+   * and auth resolution: table, operation, outcome, timing and row count, never
+   * tokens, row values, filters or error messages. Off by default; with it off,
+   * no handler runs.
+   */
+  readonly diagnostics?: boolean;
+  /**
+   * RPCs that change tables, keyed by function name. Prefer
+   * `betterSupabase.defineRpc()`.
+   */
+  readonly rpc?: Readonly<Record<string, RpcDefinition>>;
+  /** Builds the error `.orThrow()` throws. Prefer `betterSupabase.mapError()`. */
+  readonly throwAs?: ThrowMapper;
+  /**
+   * Validates verified JWT claims on the server. Prefer
+   * `betterSupabase.claims()`, which also types them.
+   */
+  readonly claims?: StandardSchemaV1;
+  /**
+   * Parses `user_metadata` into `session.profile`. Prefer
+   * `betterSupabase.userMetadata()`, which also types it.
+   */
+  readonly userMetadata?: StandardSchemaV1;
+  /**
+   * PostgREST's `db-max-rows`: the most rows one read returns. An unbounded
+   * `list` that returns this many sets `truncated` on the `query` event and
+   * logs a warning once per table. Defaults to 1000, the hosted default.
+   */
+  readonly maxRows?: number;
+  /**
+   * The longest query string one PostgREST read sends, like supabase-js
+   * `db.urlLengthLimit`. Longer reads are split along their longest `in` list.
+   * Defaults to 6000 characters, or the client's `db.urlLengthLimit` when that
+   * is lower.
+   */
+  readonly urlLengthLimit?: number;
+  /**
+   * The PostgREST version the app talks to, as in `postgrestVersion` in the
+   * better-supabase config. `maxAffected` needs 13 or later, and fails with
+   * `invalid_request` before any request on an older version. Defaults to
+   * `"13"`.
+   */
+  readonly postgrestVersion?: string;
+}
+interface ConnectOptions {
+  /** Also records this connection's calls into a request-wide recorder. */
+  readonly stats?: StatsRecorder;
+  /**
+   * Runs operations instead of the client's own executor, while `$client` stays
+   * the client (e.g. routing reads to a replica).
+   */
+  readonly executor?: Executor;
+  /**
+   * Fails each repository call and `$rpc` after this many milliseconds with a
+   * `timeout` error. A call's own `timeout` replaces it.
+   */
+  readonly timeout?: number;
+  /**
+   * Postgrest-js retries of idempotent requests for this connection; a call's
+   * own `retry` replaces it. Defaults to the client's setting.
+   */
+  readonly retry?: boolean;
+  /**
+   * Storage that runs as the same caller, as `db.$storage`. Defaults to the
+   * client's `storage`; pass it when connecting an `Executor`, such as direct
+   * Postgres as a user.
+   */
+  readonly storage?: StorageApi;
+}
+interface RpcDefinition {
+  /**
+   * App keys of the tables the function writes; their cached reads are
+   * invalidated on success.
+   */
+  readonly invalidates: readonly string[];
+}
+//#endregion
+//#region src/core/postgrest-executor.d.ts
+/**
+ * Anything with `schema(name).from(table)` or `from(table)`: a supabase-js
+ * `SupabaseClient` or a bare `PostgrestClient`.
+ */
+interface PostgrestClientLike {
+  from(relation: never): unknown;
+  schema?(schema: never): unknown;
+  rpc?(fn: never, args?: never): unknown;
+}
+interface PostgrestExecutorOptions extends PostgrestCompileOptions {
+  /**
+   * The longest query string a read may send, in characters. A longer read is
+   * split along its longest `in` list into reads that fit, or fails with
+   * `invalid_request` when it can't be split. Defaults to 6000, below the 8 KB
+   * request line the Supabase API gateway and common proxies accept, or to the
+   * client's `db.urlLengthLimit` when that is lower.
+   */
+  readonly urlLengthLimit?: number;
+  /**
+   * Aborts each request after this many milliseconds with a `timeout` error. A
+   * call's own `timeout` replaces it. Off by default.
+   */
+  readonly timeout?: number;
+  /**
+   * Postgrest-js retries of idempotent requests (GET and HEAD) on network
+   * errors, 503 and 520. A call's own `retry` replaces it. Defaults to the
+   * client's setting, which is on.
+   */
+  readonly retry?: boolean;
+  /**
+   * When set, `rpc()` fails with an `unsupported` error carrying this message
+   * and sends no request: the backend has no database functions (Supabase Lite
+   * on SQLite).
+   */
+  readonly rpcUnavailable?: string;
+}
+/** Executes IR operations through a supabase-js client. */
+declare function postgrestExecutor(client: PostgrestClientLike, options?: PostgrestExecutorOptions): Executor;
+/** The compiled plan for an operation; useful for debugging and tests. */
+declare function explainPostgrest(op: Operation, options?: PostgrestCompileOptions): PostgrestPlan;
+//#endregion
+//#region src/core/define.d.ts
+/**
+ * The isomorphic definition of your data layer: schema plus plugins. Holds no
+ * secrets and no connection; `connect()` binds it to a client per request.
+ */
+declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F extends AnyFunctions = AnyFunctions, E = unknown, C = unknown, P = unknown, B = unknown> {
+  #private;
+  readonly schema: Schema<M, D, F>;
+  readonly plugins: readonly AnyPlugin[];
+  readonly events: EventHub;
+  readonly options: SupabaseOptions;
+  constructor(schema: Schema<M, D, F>, plugins?: readonly AnyPlugin[], options?: SupabaseOptions, events?: EventHub);
+  get meta(): SchemaMeta;
+  /**
+   * The `Temporal` this definition uses: the `temporal` option, else the
+   * global.
+   */
+  get temporal(): typeof Temporal | undefined;
+  /** The schema set by `claims()`; its output types `session.claims`. */
+  get claimsSchema(): StandardSchemaV1<unknown, C> | undefined;
+  /** The schema set by `userMetadata()`; its output types `session.profile`. */
+  get userMetadataSchema(): StandardSchemaV1<unknown, P> | undefined;
+  /**
+   * Returns a new instance whose servers validate verified JWT claims (custom
+   * access token hook output) with `schema`, and whose sessions are typed by
+   * it. A token that fails it resolves to `{ kind: 'invalid', reason: 'claims'
+   * }`.
+   *
+   * ```ts
+   * const betterSupabase = defineSupabase(schema).claims(
+   *   z.object({ tenant_id: z.uuid() }),
+   * );
+   * ```
+   */
+  claims<S extends StandardSchemaV1>(schema: S): BetterSupabase<M, D, F, E, StandardSchemaV1.InferOutput<S>, P, B>;
+  /**
+   * Returns a new instance whose sessions parse `user_metadata` with `schema`
+   * into a typed `session.profile`. Users can change their metadata with
+   * `auth.updateUser()`, so a failure only leaves `profile` undefined (with one
+   * warning), and no authorization code reads it. It is for display only:
+   * roles, memberships, the tenant and entitlements come from the verified
+   * claims, never from `profile`.
+   *
+   * ```ts
+   * const betterSupabase = defineSupabase(schema).userMetadata(
+   *   z.object({ display_name: z.string() }),
+   * );
+   * ```
+   */
+  userMetadata<S extends StandardSchemaV1>(schema: S): BetterSupabase<M, D, F, E, C, StandardSchemaV1.InferOutput<S>, B>;
+  /**
+   * Returns a new instance whose `.orThrow()` throws `mapper(error)` instead of
+   * a `DbException`, and whose results `toBetterResult` maps the same way.
+   * Results themselves keep their `DbError`.
+   *
+   * ```ts
+   * const betterSupabase = defineSupabase(schema).mapError(
+   *   (error) => new AppError(error),
+   * );
+   * ```
+   */
+  mapError(mapper: (error: DbError) => unknown): BetterSupabase<M, D, F, E, C, P, B>;
+  /**
+   * Returns a new instance whose `db.$buckets` has one client per bucket,
+   * connected to `db.$storage` so Storage runs as the same caller.
+   *
+   * ```ts
+   * const betterSupabase = defineSupabase(schema).buckets({ logos, avatars });
+   * betterSupabase.connect(client).$buckets.logos.signedUrl({ ... });
+   * ```
+   */
+  buckets<const R extends BucketRegistry>(registered: R): BetterSupabase<M, D, F, E, C, P, WithExtra<B, "buckets", R>>;
+  /**
+   * Returns a new instance whose every `Db` has the installed block instances
+   * as properties, under their keys in camel case. Each client runs as the
+   * `Db`'s caller and acts in its organization (`db.$context.tenant`), so app
+   * code passes neither a transport nor an organization.
+   *
+   * ```ts
+   * export const betterSupabase = defineSupabase(schema).blocks(
+   *   defineBlocks(blockConfig, blocks),
+   * );
+   * const db = await bsb.db();
+   * await db.tags.list({ kind: "customer" });
+   * ```
+   */
+  blocks<const S extends DbBlockSource>(set: S): BetterSupabase<M, D, F, E, C, P, WithExtra<B, "blocks", BlockSetClients<S>>>;
+  /**
+   * Builds serializable `QuerySpec`s with the same arguments and result types
+   * as the repository: `betterSupabase.spec.customers.list({ select: ['id']
+   * })`.
+   */
+  get spec(): Specs<M, E>;
+  /**
+   * App keys of every table a spec reads; mutations of any of them make it
+   * stale.
+   */
+  tablesOf(spec: QuerySpec): string[];
+  /**
+   * Returns a new instance with the plugin appended. A plugin with the name of
+   * an extension the schema installed replaces it, so
+   * `.use(membershipsExtension({ resolve }))` swaps the organization resolver.
+   * Any other name installed twice throws.
+   */
+  use<Q extends AnyPlugin>(plugin: Q): BetterSupabase<M, D, F, WithExtension<E, ExtensionOf<Q>>, C, P, B>;
+  /**
+   * Declares the tables an RPC writes, so cache adapters and live queries
+   * invalidate them after it succeeds.
+   *
+   * ```ts
+   * betterSupabase.defineRpc("archive_customer", {
+   *   invalidates: ["customers", "notes"],
+   * });
+   * ```
+   */
+  defineRpc(name: Extract<keyof F, string>, options: {
+    readonly invalidates: readonly TableKey<M>[];
+  }): BetterSupabase<M, D, F, E, C, P, B>;
+  /** Observes queries, mutations, errors, auth and refreshes. */
+  on<K extends EventName>(name: K, handler: EventHandler<K>): () => void;
+  /**
+   * Invalidates `adapter` after every mutation in this runtime. Returns a
+   * function that detaches it. Adapter failures are logged, never thrown.
+   */
+  cache(adapter: CacheAdapter): () => void;
+  /**
+   * Binds the definition to a supabase-js client (or any `Executor`) and a
+   * request context. Cheap: call it once per request.
+   */
+  connect<C extends PostgrestClientLike>(client: C, context?: RequestContext, options?: ConnectOptions): Db<M, F, E, C, B>;
+  connect(executor: Executor, context?: RequestContext, options?: ConnectOptions): Db<M, F, E, undefined, B>;
+  /**
+   * The `postgrestExecutor` options this definition implies (`urlLengthLimit`,
+   * `postgrestVersion`), for adapters that build their own executor and should
+   * chunk reads the same way.
+   */
+  executorOptions(): PostgrestExecutorOptions;
+}
+/**
+ * Creates the data-layer definition from the generated `schema`, with the
+ * repository extensions of the installed blocks (organization scope, trash,
+ * `created_by` and `updated_at` stamps, write validation) already in place.
+ *
+ * ```ts
+ * export const betterSupabase = defineSupabase(schema).use(guards());
+ * ```
+ */
+declare function defineSupabase<M extends AnyModels, D, F extends AnyFunctions, E = unknown>(schema: Schema<M, D, F, string, E>, options?: SupabaseOptions): BetterSupabase<M, D, F, E>;
+//#endregion
+export { SearchScore as $, MemoryCache as $t, OffsetRangeArgs as A, IncludeArg as At, RowFilter as B, Payload as Bt, GetKey as C, AggregateRow as Ct, NoArgName as D, CountArgs as Dt, ManyWriteArgs as E, CountArg as Et, PlainName as F, MeasureKey as Ft, UpsertManyArgs as G, SortDirection as Gt, RpcOptions as H, RelationMeasureArg as Ht, RawRpcOptions as I, MutableWhere as It, DbStats as J, WhereInput as Jt, WriteArgs as K, SortSpec as Kt, Repository as L, NumericMeasureArg as Lt, OverloadReturns as M, JsonPathOps as Mt, OverloadedName as N, ListArgs as Nt, OffsetPage as O, FieldFilter as Ot, PageOf as P, MeasureArg as Pt, SearchArgs as Q, CacheTarget as Qt, RepositoryOf as R, OrderByArg as Rt, FindExt as S, AggregateResult as St, ManyResult as T, ColumnOrderByArg as Tt, UpdateArgs as U, RequestArgs as Ut, RpcArgs as V, ReadArgs as Vt, UpsertArgs as W, SelectArg as Wt, StatsRecorder as X, BucketsHelper as Xt, EMPTY_STATS as Y, BucketRegistry as Yt, recordStats as Z, CacheAdapter as Zt, CursorPageArgs as _, isQuerySpec as _t, explainPostgrest as a, ReadSetParamTypes as at, DeleteArgs as b, AggregateOrderBy as bt, RpcDefinition as c, ReadSetResult as ct, BlocksHelper as d, readSetTables as dt, cacheTargetOf as en, InferReadSetParams as et, DbBlockSource as f, InferResult as ft, CursorPage as g, TableSpecs as gt, ConflictTarget as h, Specs as ht, PostgrestExecutorOptions as i, ReadSetParamType as it, OverloadArgs as j, IncludeArgs as jt, OffsetPageArgs as k, GetArgs as kt, SupabaseOptions as l, defineReadSet as lt, DbOf as m, ReadMethod as mt, defineSupabase as n, rowKey as nn, ReadSetAuth as nt, postgrestExecutor as o, ReadSetParamValue as ot, DbExtras as p, QuerySpec as pt, WriteManyArgs as q, WhereArg as qt, PostgrestClientLike as r, rpcCacheTargets as rn, ReadSetOptions as rt, ConnectOptions as s, ReadSetParams as st, BetterSupabase as t, memoryCache as tn, ReadSet as tt, BlockInstanceSurface as u, isReadSet as ut, Db as v, specTables as vt, ManyOutcome as w, ColumnOrderBy as wt, DeleteExt as x, AggregateOrderByArg as xt, DbHelpers as y, AggregateArgs as yt, Returned as z, OrderByInput as zt };