better-supabase 0.0.0 → 0.1.0

package/dist/define-CTfWw-SS.d.ts

@@ -0,0 +1,662 @@
+import { A as TableMeta, C as Relations, D as Simplify, E as SchemaMeta, M as UniqueKeyName, N as UniqueWhere, P as Update, S as RelationShape, T as Schema, h as Insert, k as TableKey, n as AnyModels, t as AnyFunctions, w as Row, y as PrimaryKeyValue } from "./types-C2fslP1z.js";
+import { g as Operation, l as CountMode, r as Executor } from "./executor-Bazhgsgq.js";
+import { p as DbError, s as ThrowMapper, t as AsyncResult, v as ErrorMapper } from "./result-CTkCZ6JA.js";
+import { a as EventHub, f as Logger, i as EventHandler, o as EventName, s as MutationNotice, u as RpcNotice } from "./events-2OJsVG_d.js";
+import { a as ExtensionOf, g as WithExtension, h as RequestContext, n as AnyPlugin, r as ApplyExtension } from "./plugin-HvGqCurB.js";
+import { t as StandardSchemaV1 } from "./standard-CyhRzctb.js";
+import { i as PostgrestPlan } from "./postgrest-Dm-vhY6R.js";
+//#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 substring match; wildcards in the value are escaped. */
+  readonly contains?: string;
+  readonly startsWith?: string;
+  readonly endsWith?: string;
+  /** Full-text search (`websearch_to_tsquery`). */
+  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. */
+  readonly contains?: Partial<V> | Record<string, unknown>;
+}
+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>>;
+/** 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>;
+};
+type SortDirection = "asc" | "desc";
+type OrderByInput<M extends AnyModels, T extends keyof M> = { readonly [K in keyof Row<M, T>]?: SortDirection | {
+  readonly direction: SortDirection;
+  readonly nulls?: "first" | "last";
+}; };
+type OrderByArg<M extends AnyModels, T extends keyof M> = OrderByInput<M, T> | readonly OrderByInput<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?: OrderByArg<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;
+interface ReadArgs<M extends AnyModels, T extends keyof M> {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  readonly signal?: AbortSignal;
+}
+interface FindManyArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M, T> {
+  readonly where?: WhereInput<M, T>;
+  readonly orderBy?: OrderByArg<M, T>;
+  readonly limit?: number;
+  readonly offset?: number;
+}
+type FindFirstArgs<M extends AnyModels, T extends keyof M> = Omit<FindManyArgs<M, T>, "limit">;
+interface CountArgs<M extends AnyModels, T extends keyof M> {
+  readonly where?: WhereInput<M, T>;
+  readonly mode?: "exact" | "planned" | "estimated";
+  readonly signal?: AbortSignal;
+}
+interface AggregateArgs<M extends AnyModels, T extends keyof M> {
+  readonly where?: WhereInput<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; only `groupBy` columns. */
+  readonly orderBy?: OrderByArg<M, T>;
+  readonly limit?: number;
+  readonly offset?: number;
+  readonly signal?: AbortSignal;
+}
+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>;
+type RelationPayload<M extends AnyModels, R, V> = R extends RelationShape ? R["kind"] extends "many" ? Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V>[] : R["nullable"] extends true ? 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> = Simplify<SelectPart<M, T, A> & IncludePart<M, T, A>>;
+//#endregion
+//#region src/core/spec.d.ts
+type ReadMethod = "findMany" | "findFirst" | "findUnique" | "findById" | "count" | "aggregate" | "exists" | "paginate";
+declare const resultType: unique symbol;
+/**
+ * A read, described as plain JSON: build it with `sb.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> {
+  findMany<const A extends NoSignal<FindManyArgs<M, T>> & FindExt<E, M, T>>(args?: A): QuerySpec<T, "findMany", Payload<M, T, A>[]>;
+  findFirst<const A extends NoSignal<FindFirstArgs<M, T>> & FindExt<E, M, T>>(args?: A): QuerySpec<T, "findFirst", Payload<M, T, A> | null>;
+  findUnique<const A extends NoSignal<ReadArgs<M, T>> & {
+    readonly where: UniqueWhere<M, T>;
+  } & FindExt<E, M, T>>(args: A): QuerySpec<T, "findUnique", Payload<M, T, A> | null>;
+  findById<const A extends NoSignal<ReadArgs<M, T>> & FindExt<E, M, T>>(id: PrimaryKeyValue<M, T>, args?: A): QuerySpec<T, "findById", 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>>;
+  exists(args?: {
+    readonly where?: WhereInput<M, T>;
+  } & FindExt<E, M, T>): QuerySpec<T, "exists", boolean>;
+  paginate<const A extends NoSignal<OffsetPageArgs<M, T> | CursorPageArgs<M, T>> & FindExt<E, M, T>>(args: A): QuerySpec<T, "paginate", PageOf<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]>; };
+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(
+ *   sb,
+ *   'app_chrome',
+ *   { params: { userId: 'uuid' } },
+ *   (s, p) => ({
+ *     unread: s.notifications.count({ where: { userId: p.userId, readAt: null } }),
+ *     me: s.profiles.findFirst({ where: { id: p.userId } }),
+ *   }),
+ * );
+ * ```
+ *
+ * `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>>>(sb: BetterSupabase<M, D, F, E>, name: N, options: ReadSetOptions<P>, build: (specs: Specs<M, E>, params: ReadSetParams<P>) => 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<FindManyArgs<M, T>, "select" | "include" | "where" | "signal"> & {
+  /** The query embedding, as numbers or pgvector text (`'[0.1,0.2]'`). */
+  readonly vector: readonly number[] | string;
+  /** Rows to return. Defaults to 10. */
+  readonly k?: number;
+};
+//#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;
+}
+interface UpdateArgs<M extends AnyModels, T extends keyof M> extends WriteArgs<M, T> {
+  /**
+   * Optimistic concurrency: the update only applies when these columns still
+   * have these values. A mismatch returns a `stale` error.
+   */
+  readonly expect?: Partial<Row<M, T>>;
+}
+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;
+}
+interface DeleteArgs {
+  readonly signal?: AbortSignal;
+}
+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<FindManyArgs<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;
+};
+type CursorPageArgs<M extends AnyModels, T extends keyof M> = Omit<FindManyArgs<M, T>, "limit" | "offset"> & {
+  /** Cursor from the previous page, or `null` for the first page. */
+  readonly after: string | null;
+  readonly size: number;
+};
+interface OffsetPage<R> {
+  readonly items: R[];
+  readonly page: {
+    readonly number: number;
+    readonly size: number;
+    readonly total: number | null;
+    readonly pages: number | null;
+    readonly hasMore: boolean;
+  };
+}
+interface CursorPage<R> {
+  readonly items: R[];
+  readonly nextCursor: string | null;
+  readonly hasMore: boolean;
+}
+type PageOf<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly after: unknown;
+} ? CursorPage<Payload<M, T, A>> : OffsetPage<Payload<M, T, A>>;
+interface Repository<M extends AnyModels, T extends TableKey<M>, E = unknown> {
+  readonly $table: T;
+  readonly $meta: TableMeta;
+  findMany<const A extends FindManyArgs<M, T> & FindExt<E, M, T>>(args?: A): AsyncResult<Payload<M, T, A>[]>;
+  findFirst<const A extends FindFirstArgs<M, T> & FindExt<E, M, T>>(args?: A): AsyncResult<Payload<M, T, A> | null>;
+  /**
+   * The row with these values for the primary key or one named unique key
+   * (`{ email }`, `{ organizationId, slug }`), or `null`.
+   */
+  findUnique<const A extends ReadArgs<M, T> & {
+    readonly where: UniqueWhere<M, T>;
+  } & FindExt<E, M, T>>(args: A): AsyncResult<Payload<M, T, A> | null>;
+  /** Returns a `not_found` error when no visible row has this key. */
+  findById<const A extends ReadArgs<M, T> & FindExt<E, M, T>>(id: PrimaryKeyValue<M, T>, args?: A): AsyncResult<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>>;
+  exists(args?: {
+    readonly where?: WhereInput<M, T>;
+    readonly signal?: AbortSignal;
+  } & FindExt<E, M, T>): AsyncResult<boolean>;
+  paginate<const A extends (OffsetPageArgs<M, T> | CursorPageArgs<M, T>) & FindExt<E, M, T>>(args: A): AsyncResult<PageOf<M, T, A>>;
+  create<const A extends WriteArgs<M, T> = {}>(data: Insert<M, T>, args?: A): AsyncResult<Returned<M, T, A>>;
+  createMany<const A extends WriteArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): AsyncResult<A extends {
+    readonly returning: false;
+  } ? {
+    count: number;
+  } : Payload<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>>;
+  updateMany(args: {
+    readonly where: WhereInput<M, T>;
+    readonly data: Update<M, T>;
+    readonly signal?: AbortSignal;
+  } & FindExt<E, M, T>): AsyncResult<{
+    count: number;
+  }>;
+  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>>;
+  upsertMany<const A extends UpsertArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): AsyncResult<A extends {
+    readonly returning: false;
+  } ? {
+    count: number;
+  } : Payload<M, T, A>[]>;
+  /** Returns a `not_found` error when no visible row has this key. */
+  delete(id: PrimaryKeyValue<M, T>, args?: DeleteArgs & DeleteExt<E, M, T>): AsyncResult<void>;
+  deleteMany(args: {
+    readonly where: WhereInput<M, T>;
+    readonly signal?: AbortSignal;
+  } & DeleteExt<E, M, T> & FindExt<E, M, T>): AsyncResult<{
+    count: number;
+  }>;
+  /** 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> {
+  readonly signal?: AbortSignal;
+  /** Validates the return value; the result carries the schema's output type. */
+  readonly returns?: StandardSchemaV1<unknown, R>;
+  readonly schema?: string;
+}
+type RpcArgs<F extends AnyFunctions, N extends keyof F> = Record<never, never> extends F[N]["Args"] ? [args?: F[N]["Args"]] : [args: F[N]["Args"]];
+interface DbHelpers<M extends AnyModels, F extends AnyFunctions, E, C> {
+  /** The underlying client (supabase-js), for anything the repository lacks. */
+  readonly $client: C;
+  readonly $executor: Executor;
+  readonly $context: RequestContext;
+  /** Calls a database function with typed arguments. */
+  $rpc<N extends Extract<keyof F, string>, R = F[N]["Returns"]>(name: N, ...rest: [...RpcArgs<F, N>, options?: RpcOptions<R>]): AsyncResult<R>;
+  /** Same connection with more context (for example a tenant). */
+  $with(context: RequestContext): Db<M, F, E, C>;
+  /**
+   * Same connection without plugins: no tenant scoping, soft-delete filters,
+   * timestamps, rules or executor wrappers. For migrations and admin tools.
+   */
+  $withoutPlugins(): Db<M, F, unknown, C>;
+  /**
+   * 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 `sb.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 kit 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>[]>;
+}
+type Db<M extends AnyModels, F extends AnyFunctions, E, C> = { readonly [T in TableKey<M>]: RepositoryOf<M, T, E>; } & DbHelpers<M, F, E, C>;
+//#endregion
+//#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 `sb.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/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;
+}
+declare function postgrestExecutor(client: PostgrestClientLike): Executor;
+/** The compiled plan for an operation; useful for debugging and tests. */
+declare function explainPostgrest(op: Operation): PostgrestPlan;
+//#endregion
+//#region src/core/define.d.ts
+interface DefineSupabaseOptions {
+  /** Clock used by plugins (timestamps, soft delete). */
+  readonly now?: () => Date;
+  /** 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;
+  /** RPCs that change tables, keyed by function name. Prefer `sb.defineRpc()`. */
+  readonly rpc?: Readonly<Record<string, RpcDefinition>>;
+  /** Builds the error `.orThrow()` throws. Prefer `sb.mapError()`. */
+  readonly throwAs?: ThrowMapper;
+  /** Validates verified JWT claims on the server. Prefer `sb.claims()`, which also types them. */
+  readonly claims?: StandardSchemaV1;
+  /**
+   * PostgREST's `db-max-rows`: the most rows one read returns. An unbounded
+   * `findMany` 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;
+}
+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;
+}
+interface RpcDefinition {
+  /** App keys of the tables the function writes; their cached reads are invalidated on success. */
+  readonly invalidates: readonly string[];
+}
+/**
+ * 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> {
+  #private;
+  readonly schema: Schema<M, D, F>;
+  readonly plugins: readonly AnyPlugin[];
+  readonly events: EventHub;
+  readonly options: DefineSupabaseOptions;
+  constructor(schema: Schema<M, D, F>, plugins?: readonly AnyPlugin[], options?: DefineSupabaseOptions, events?: EventHub);
+  get meta(): SchemaMeta;
+  /** The schema set by `claims()`; its output types `session.claims`. */
+  get claimsSchema(): StandardSchemaV1<unknown, C> | 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 sb = defineSupabase(schema).claims(z.object({ tenant_id: z.uuid() }));
+   * ```
+   */
+  claims<S extends StandardSchemaV1>(schema: S): BetterSupabase<M, D, F, E, StandardSchemaV1.InferOutput<S>>;
+  /**
+   * 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 sb = defineSupabase(schema).mapError((error) => new AppError(error));
+   * ```
+   */
+  mapError(mapper: (error: DbError) => unknown): BetterSupabase<M, D, F, E, C>;
+  /**
+   * Builds serializable `QuerySpec`s with the same arguments and result types
+   * as the repository: `sb.spec.customers.findMany({ 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. */
+  use<P extends AnyPlugin>(plugin: P): BetterSupabase<M, D, F, WithExtension<E, ExtensionOf<P>>, C>;
+  /**
+   * Declares the tables an RPC writes, so cache adapters and live queries
+   * invalidate them after it succeeds.
+   *
+   * ```ts
+   * sb.defineRpc('archive_customer', { invalidates: ['customers', 'notes'] });
+   * ```
+   */
+  defineRpc(name: Extract<keyof F, string>, options: {
+    readonly invalidates: readonly TableKey<M>[];
+  }): BetterSupabase<M, D, F, E, C>;
+  /** 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>;
+  connect(executor: Executor, context?: RequestContext, options?: ConnectOptions): Db<M, F, E, undefined>;
+}
+/**
+ * Creates the data-layer definition from the generated `schema`.
+ *
+ * ```ts
+ * export const sb = defineSupabase(schema).use(timestamps()).use(softDelete());
+ * ```
+ */
+declare function defineSupabase<M extends AnyModels, D, F extends AnyFunctions>(schema: Schema<M, D, F>, options?: DefineSupabaseOptions): BetterSupabase<M, D, F>;
+//#endregion
+export { Specs as $, RpcOptions as A, ReadSet as B, FindExt as C, WhereInput as Ct, Repository as D, PageOf as E, EMPTY_STATS as F, ReadSetParams as G, ReadSetParamType as H, StatsRecorder as I, isReadSet as J, ReadSetResult as K, recordStats as L, UpsertArgs as M, WriteArgs as N, RepositoryOf as O, DbStats as P, ReadMethod as Q, SearchArgs as R, DeleteExt as S, SortDirection as St, OffsetPageArgs as T, ReadSetParamTypes as U, ReadSetOptions as V, ReadSetParamValue as W, InferResult as X, readSetTables as Y, QuerySpec as Z, CursorPage as _, OrderByInput as _t, defineSupabase as a, AggregateRow as at, DbHelpers as b, RelationMeasureArg as bt, postgrestExecutor as c, FieldFilter as ct, MemoryCache as d, IncludeArg as dt, TableSpecs as et, cacheTargetOf as f, IncludeArgs as ft, ConflictTarget as g, OrderByArg as gt, rpcCacheTargets as h, NumericMeasureArg as ht, RpcDefinition as i, AggregateResult as it, UpdateArgs as j, Returned as k, CacheAdapter as l, FindFirstArgs as lt, rowKey as m, MeasureKey as mt, ConnectOptions as n, specTables as nt, PostgrestClientLike as o, CountArg as ot, memoryCache as p, MeasureArg as pt, defineReadSet as q, DefineSupabaseOptions as r, AggregateArgs as rt, explainPostgrest as s, CountArgs as st, BetterSupabase as t, isQuerySpec as tt, CacheTarget as u, FindManyArgs as ut, CursorPageArgs as v, Payload as vt, OffsetPage as w, DeleteArgs as x, SelectArg as xt, Db as y, ReadArgs as yt, InferReadSetParams as z };