better-supabase 0.8.0 → 0.9.0

package/dist/define-DxHHbNEb.d.ts

@@ -0,0 +1,1005 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, p as ThrowMapper, t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { A as Relations, B as TableMeta, E as PrimaryKeyValue, F as Simplify, H as UniqueKeyName, M as Row, N as Schema, P as SchemaMeta, U as UniqueWhere, W as Update, a as AnyModels, i as AnyFunctions, k as RelationTypes, x as Insert, z as TableKey } from "./types-YfwpIE-d.js";
+import { l as CountMode, r as Executor, v as Operation } from "./executor-DoE-5iM8.js";
+import { a as EventHandler, c as MutationNotice, d as RpcNotice, o as EventHub, s as EventName } from "./events-CTreRrgP.js";
+import { a as ExtensionOf, h as WithExtension, m as RequestContext, n as AnyPlugin, r as ApplyExtension } from "./plugin-CDLJRFFg.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { t as StorageApi } from "./storage-api-Cx-1iWBd.js";
+import { a as PostgrestPlan, i as PostgrestCompileOptions } from "./postgrest-Cw9Bs5gm.js";
+//#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/define-types.d.ts
+interface SupabaseOptions {
+  /**
+   * Clock used by plugins (timestamps, soft delete) and for the `time` of
+   * block events on `betterSupabase.events`. Pass it to `createJobs` 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
+   * `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;
+  /**
+   * 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/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;
+  /** 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;
+  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>;
+};
+/**
+ * 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. */
+type ColumnOrderBy<M extends AnyModels, T extends keyof M> = { readonly [K in keyof Row<M, T>]?: SortSpec; };
+/**
+ * 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>;
+}
+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 FindOnlyArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M, T> {
+  readonly where: WhereInput<M, T>;
+}
+interface CountArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  readonly where?: WhereInput<M, T>;
+  readonly mode?: "exact" | "planned" | "estimated";
+}
+interface AggregateArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  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 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 = "findMany" | "findFirst" | "findOnly" | "findUnique" | "findById" | "count" | "aggregate" | "exists" | "paginate";
+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> {
+  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>;
+  findOnly<const A extends NoSignal<FindOnlyArgs<M, T>> & FindExt<E, M, T>>(args: A): QuerySpec<T, "findOnly", 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> | OffsetRangeArgs<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]>; };
+/**
+ * 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.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>>>(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<FindManyArgs<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/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 `timestamps()`, `actor()`
+   * and `softDelete()` 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>;
+}
+/** `updateMany` and `deleteMany` return the written rows with `returning: true`. */
+type ManyResult<M extends AnyModels, T extends keyof M, A> = A extends {
+  readonly returning: true;
+} ? Payload<M, T, A>[] : {
+  count: number;
+};
+interface ManyReturningArgs<M extends AnyModels, T extends keyof M> extends RequestArgs {
+  readonly where: WhereInput<M, T>;
+  /** 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;
+}
+/** `createMany` and `upsertMany` options. */
+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;
+/** `upsertMany` options. */
+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<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;
+  readonly offset?: never;
+  readonly limit?: never;
+};
+type OffsetRangeArgs<M extends AnyModels, T extends keyof M> = Omit<FindManyArgs<M, T>, "limit" | "offset"> & {
+  /** Rows to skip before the page. */
+  readonly offset: number;
+  readonly limit: number;
+  /** Also count all matching rows. */
+  readonly count?: CountMode;
+  readonly page?: never;
+  readonly size?: never;
+};
+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 $tableName: 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 one row matching `where`, or `null` when none does, like supabase-js
+   * `maybeSingle()`. Several matching rows are a `multiple_rows` error, so
+   * a filter that should pick one row never reads an arbitrary one.
+   */
+  findOnly<const A extends FindOnlyArgs<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?: RequestArgs & {
+    readonly where?: WhereInput<M, T>;
+  } & FindExt<E, M, T>): AsyncResult<boolean>;
+  paginate<const A extends (OffsetPageArgs<M, T> | OffsetRangeArgs<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 WriteManyArgs<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>>;
+  /**
+   * Fails with `invalid_request` when `where` filters no rows (it is empty or
+   * every value is `undefined`), unless `allowAll` is `true`.
+   */
+  updateMany<const A extends ManyReturningArgs<M, T> & {
+    readonly data: Update<M, T>;
+    /** Update every visible row when `where` filters nothing. */
+    readonly allowAll?: boolean;
+  } & FindExt<E, M, T>>(args: A): AsyncResult<ManyResult<M, T, A>>;
+  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 UpsertManyArgs<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<const A extends ManyReturningArgs<M, T> & DeleteExt<E, M, T> & FindExt<E, M, T>>(args: A): AsyncResult<ManyResult<M, T, A>>;
+  /** 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> {
+  /** 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>;
+  /**
+   * 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>;
+  /**
+   * 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> = { 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 `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/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> {
+  #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>;
+  /**
+   * 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>>;
+  /**
+   * 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>;
+  /**
+   * Builds serializable `QuerySpec`s with the same arguments and result types
+   * as the repository: `betterSupabase.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<Q extends AnyPlugin>(plugin: Q): BetterSupabase<M, D, F, WithExtension<E, ExtensionOf<Q>>, C, P>;
+  /**
+   * 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>;
+  /** 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>;
+  /**
+   * 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`.
+ *
+ * ```ts
+ * export const betterSupabase = defineSupabase(schema).use(timestamps()).use(softDelete());
+ * ```
+ */
+declare function defineSupabase<M extends AnyModels, D, F extends AnyFunctions>(schema: Schema<M, D, F>, options?: SupabaseOptions): BetterSupabase<M, D, F>;
+//#endregion
+export { ReadSetParams as $, OverloadedName as A, NumericMeasureArg as At, UpsertArgs as B, WhereInput as Bt, ManyReturningArgs as C, FindOnlyArgs as Ct, OffsetRangeArgs as D, MeasureArg as Dt, OffsetPageArgs as E, JsonPathOps as Et, RepositoryOf as F, RelationMeasureArg as Ft, SearchScore as G, EMPTY_STATS as Gt, WriteArgs as H, RpcDefinition as Ht, Returned as I, RequestArgs as It, ReadSetAuth as J, InferReadSetParams as K, StatsRecorder as Kt, RpcArgs as L, SelectArg as Lt, PlainName as M, OrderByInput as Mt, RawRpcOptions as N, Payload as Nt, OverloadArgs as O, MeasureKey as Ot, Repository as P, ReadArgs as Pt, ReadSetParamValue as Q, RpcOptions as R, SortDirection as Rt, ManyResult as S, FindManyArgs as St, OffsetPage as T, IncludeArgs as Tt, WriteManyArgs as U, SupabaseOptions as Ut, UpsertManyArgs as V, ConnectOptions as Vt, SearchArgs as W, DbStats as Wt, ReadSetParamType as X, ReadSetOptions as Y, ReadSetParamTypes as Z, Db as _, ColumnOrderByArg as _t, explainPostgrest as a, QuerySpec as at, DeleteExt as b, FieldFilter as bt, CacheTarget as c, TableSpecs as ct, memoryCache as d, AggregateArgs as dt, ReadSetResult as et, rowKey as f, AggregateOrderBy as ft, CursorPageArgs as g, ColumnOrderBy as gt, CursorPage as h, AggregateRow as ht, PostgrestExecutorOptions as i, InferResult as it, PageOf as j, OrderByArg as jt, OverloadReturns as k, MutableWhere as kt, MemoryCache as l, isQuerySpec as lt, ConflictTarget as m, AggregateResult as mt, defineSupabase as n, isReadSet as nt, postgrestExecutor as o, ReadMethod as ot, rpcCacheTargets as p, AggregateOrderByArg as pt, ReadSet as q, recordStats as qt, PostgrestClientLike as r, readSetTables as rt, CacheAdapter as s, Specs as st, BetterSupabase as t, defineReadSet as tt, cacheTargetOf as u, specTables as ut, DbHelpers as v, CountArg as vt, NoArgName as w, IncludeArg as wt, FindExt as x, FindFirstArgs as xt, DeleteArgs as y, CountArgs as yt, UpdateArgs as z, SortSpec as zt };