better-supabase 0.5.0 → 0.6.0

package/dist/{define-Bp_BZa5h.d.ts → define-CJJkkr1-.d.ts}

@@ -1,10 +1,12 @@
 /// <reference lib="esnext.temporal" />
-import { A as Schema, D as RelationTypes, F as TableMeta, L as UniqueKeyName, M as Simplify, O as Relations, P as TableKey, R as UniqueWhere, _ as Insert, j as SchemaMeta, k as Row, n as AnyFunctions, r as AnyModels, w as PrimaryKeyValue, z as Update } from "./types-Dnf_wRDz.js";
-import { I as CountMode, S as ErrorMapper, U as Operation, _ as DbError, a as AsyncResult, d as ThrowMapper, r as Executor } from "./executor-BunPOO-k.js";
-import { E as Logger, a as EventHub, i as EventHandler, o as EventName, s as MutationNotice, u as RpcNotice } from "./events-aIO7vsIk.js";
-import { _ as WithExtension, a as ExtensionOf, g as RequestContext, n as AnyPlugin, r as ApplyExtension } from "./plugin-o144f322.js";
-import { t as StandardSchemaV1 } from "./standard-J4YgMOLm.js";
-import { i as PostgrestPlan } from "./postgrest-CruYKAvV.js";
+import { b as DbError, p as ThrowMapper, t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { A as Relations, B as UniqueKeyName, E as PrimaryKeyValue, F as Simplify, H as Update, L as TableKey, M as Row, N as Schema, P as SchemaMeta, R as TableMeta, V as UniqueWhere, a as AnyModels, i as AnyFunctions, k as RelationTypes, x as Insert } from "./types-6BdhkmZe.js";
+import { l as CountMode, r as Executor, v as Operation } from "./executor-DvsBbNBS.js";
+import { a as ExtensionOf, h as WithExtension, m as RequestContext, n as AnyPlugin, r as ApplyExtension } from "./plugin-FGY8UhYm.js";
+import { a as EventHub, i as EventHandler, o as EventName, s as MutationNotice, u as RpcNotice } from "./events-DWDhx77e.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-CYsm7xpT.js";
+import { a as PostgrestPlan, i as PostgrestCompileOptions } from "./postgrest-BLVdEnfe.js";
 //#region src/ir/args.d.ts
 interface BaseOps<V> {
   readonly eq?: V;
@@ -25,11 +27,19 @@ interface TextOps {
   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`). */
+  /**
+   * 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;
@@ -46,10 +56,37 @@ interface ArrayOps<E> {
   readonly containedBy?: readonly E[];
 }
 interface JsonOps<V> {
-  /** jsonb `@>`: the value contains the given structure. */
-  readonly contains?: Partial<V> | Record<string, unknown>;
+  /**
+   * 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 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>>;
+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 {
@@ -74,18 +111,37 @@ type WhereInput<M extends AnyModels, T extends keyof M> = { readonly [K in keyof
   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 OrderByInput<M extends AnyModels, T extends keyof M> = { readonly [K in keyof Row<M, T>]?: SortDirection | {
+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?: OrderByArg<M, T>;
+  readonly orderBy?: ColumnOrderByArg<M, T>;
   readonly limit?: number;
   /** Only return parent rows that have a matching related row. */
   readonly required?: boolean;
@@ -111,10 +167,25 @@ type CountArg<M extends AnyModels, T extends keyof M> = { readonly [R in ManyRel
 type TargetOf<R> = R extends {
   readonly table: infer X;
 } ? X : never;
-interface ReadArgs<M extends AnyModels, T extends keyof M> {
+/** 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>;
-  readonly signal?: AbortSignal;
 }
 interface FindManyArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M, T> {
   readonly where?: WhereInput<M, T>;
@@ -123,12 +194,14 @@ interface FindManyArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<
   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> {
+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";
-  readonly signal?: AbortSignal;
 }
-interface AggregateArgs<M extends AnyModels, T extends keyof M> {
+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>;
@@ -138,16 +211,30 @@ interface AggregateArgs<M extends AnyModels, T extends keyof M> {
   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>;
+  /** Sorts groups by `groupBy` columns, `_count` and measures. */
+  readonly orderBy?: AggregateOrderByArg<M, T>;
   readonly limit?: number;
   readonly offset?: number;
-  readonly signal?: AbortSignal;
 }
+/**
+ * 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>;
-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 ? 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;
+/** `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;
@@ -184,7 +271,7 @@ type Payload<M extends AnyModels, T extends keyof M, A> = A extends {
 } ? Simplify<SelectPart<M, T, A>> : Row<M, T>;
 //#endregion
 //#region src/core/spec.d.ts
-type ReadMethod = "findMany" | "findFirst" | "findUnique" | "findById" | "count" | "aggregate" | "exists" | "paginate";
+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
@@ -206,6 +293,7 @@ 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>;
@@ -215,7 +303,7 @@ interface TableSpecs<M extends AnyModels, T extends TableKey<M>, E> {
   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>>;
+  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;
@@ -240,6 +328,15 @@ type ScalarValue<T> = T extends "int2" | "int4" | "int8" | "float4" | "float8" |
 /** 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
@@ -285,7 +382,7 @@ interface ReadSetOptions<P extends ReadSetParamTypes> {
  * `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>) => S): ReadSet<N, P, S>;
+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[];
@@ -293,11 +390,30 @@ declare function readSetTables(set: ReadSet, meta?: SchemaMeta): string[];
 //#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;
+  /**
+   * 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`). */
@@ -344,10 +460,49 @@ interface WriteArgs<M extends AnyModels, T extends keyof M> extends ReadArgs<M,
 }
 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.
+   * 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 expect?: Partial<Row<M, T>>;
+  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> {
@@ -356,9 +511,9 @@ interface UpsertArgs<M extends AnyModels, T extends keyof M> extends WriteArgs<M
   /** Keep the existing row instead of updating it (`ON CONFLICT DO NOTHING`). */
   readonly ignoreDuplicates?: boolean;
 }
-interface DeleteArgs {
-  readonly signal?: AbortSignal;
-}
+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>;
@@ -368,6 +523,17 @@ type OffsetPageArgs<M extends AnyModels, T extends keyof M> = Omit<FindManyArgs<
   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. */
@@ -397,6 +563,12 @@ interface Repository<M extends AnyModels, T extends TableKey<M>, E = unknown> {
   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`.
@@ -412,66 +584,119 @@ interface Repository<M extends AnyModels, T extends TableKey<M>, E = unknown> {
    * `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?: {
+  exists(args?: RequestArgs & {
     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>>;
+  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 WriteArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): AsyncResult<A extends {
+  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>>;
-  updateMany(args: {
-    readonly where: WhereInput<M, T>;
+  /**
+   * 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>;
-    readonly signal?: AbortSignal;
-  } & FindExt<E, M, T>): AsyncResult<{
-    count: number;
-  }>;
+    /** 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 UpsertArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): AsyncResult<A extends {
+  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(args: {
-    readonly where: WhereInput<M, T>;
-    readonly signal?: AbortSignal;
-  } & DeleteExt<E, M, T> & FindExt<E, M, T>): AsyncResult<{
-    count: number;
-  }>;
+  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> {
-  readonly signal?: AbortSignal;
-  /** Validates the return value; the result carries the schema's output type. */
+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;
   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>;
+  /**
+   * 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(): Db<M, F, unknown, C>;
+  $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.
@@ -499,10 +724,10 @@ interface DbHelpers<M extends AnyModels, F extends AnyFunctions, E, C> {
   }): 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
+   * `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>[]>;
+  $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
@@ -553,18 +778,53 @@ interface PostgrestClientLike {
   schema?(schema: never): unknown;
   rpc?(fn: never, args?: never): unknown;
 }
-declare function postgrestExecutor(client: PostgrestClientLike): Executor;
+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;
+}
+/** 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): PostgrestPlan;
+declare function explainPostgrest(op: Operation, options?: PostgrestCompileOptions): PostgrestPlan;
 //#endregion
 //#region src/core/define.d.ts
 interface SupabaseOptions {
   /** Clock used by plugins (timestamps, soft delete). */
   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()`. */
@@ -579,6 +839,20 @@ interface SupabaseOptions {
    * 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. */
@@ -588,6 +862,16 @@ interface ConnectOptions {
    * 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;
 }
 interface RpcDefinition {
   /** App keys of the tables the function writes; their cached reads are invalidated on success. */
@@ -605,6 +889,8 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
   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`. */
@@ -675,6 +961,12 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
    */
   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`.
@@ -685,4 +977,4 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
  */
 declare function defineSupabase<M extends AnyModels, D, F extends AnyFunctions>(schema: Schema<M, D, F>, options?: SupabaseOptions): 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, SupabaseOptions 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, RpcDefinition 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 };
+export { ReadSetResult as $, PageOf as A, OrderByArg as At, DbStats as B, DeleteExt as C, IncludeArg as Ct, OffsetPage as D, MeasureKey as Dt, ManyReturningArgs as E, MeasureArg as Et, UpdateArgs as F, RequestArgs as Ft, InferReadSetParams as G, StatsRecorder as H, UpsertArgs as I, SelectArg as It, ReadSetOptions as J, ReadSet as K, UpsertManyArgs as L, SortDirection as Lt, RepositoryOf as M, Payload as Mt, Returned as N, ReadArgs as Nt, OffsetPageArgs as O, MutableWhere as Ot, RpcOptions as P, RelationMeasureArg as Pt, ReadSetParams as Q, WriteArgs as R, SortSpec as Rt, DeleteArgs as S, FindOnlyArgs as St, ManyResult as T, JsonPathOps as Tt, recordStats as U, EMPTY_STATS as V, SearchArgs as W, ReadSetParamTypes as X, ReadSetParamType as Y, ReadSetParamValue as Z, ConflictTarget as _, CountArg as _t, defineSupabase as a, ReadMethod as at, Db as b, FindFirstArgs as bt, explainPostgrest as c, isQuerySpec as ct, CacheTarget as d, AggregateOrderBy as dt, defineReadSet as et, MemoryCache as f, AggregateOrderByArg as ft, rpcCacheTargets as g, ColumnOrderByArg as gt, rowKey as h, ColumnOrderBy as ht, SupabaseOptions as i, QuerySpec as it, Repository as j, OrderByInput as jt, OffsetRangeArgs as k, NumericMeasureArg as kt, postgrestExecutor as l, specTables as lt, memoryCache as m, AggregateRow as mt, ConnectOptions as n, readSetTables as nt, PostgrestClientLike as o, Specs as ot, cacheTargetOf as p, AggregateResult as pt, ReadSetAuth as q, RpcDefinition as r, InferResult as rt, PostgrestExecutorOptions as s, TableSpecs as st, BetterSupabase as t, isReadSet as tt, CacheAdapter as u, AggregateArgs as ut, CursorPage as v, CountArgs as vt, FindExt as w, IncludeArgs as wt, DbHelpers as x, FindManyArgs as xt, CursorPageArgs as y, FieldFilter as yt, WriteManyArgs as z, WhereInput as zt };