better-supabase 0.5.1 → 0.6.1

package/dist/{define-cNKzqwL_.js → define-B-TVjC25.js}

@@ -1,20 +1,41 @@
-import { t as cloneValue } from "./clone-BfgmLU90.js";
-import { n as dbError, t as DbException } from "./errors-DtwXa6b8.js";
-import { a as invalidRequest, r as builderFor } from "./simplify-_0oUKqCd.js";
+import { n as isPlainObject, t as cloneValue } from "./clone-BfgmLU90.js";
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as dbError } from "./errors-B11Duf73.js";
+import { n as invalidRequest, t as builderFor } from "./build-BXIzE6Xv.js";
 import { t as lookupOf } from "./lookup-BaP5bI27.js";
 import { i as or, n as column, r as not, t as and } from "./types-6cYK9pbJ.js";
-import { n as nowInstant } from "./temporal-CVlIV2DZ.js";
-import { n as decodeValue, r as encodeValue, t as decodeScalar } from "./wire-D2dT86vi.js";
-import { i as ok, n as err, o as toDbError, s as withErrorMapper, t as AsyncResult } from "./result-BKiliPY7.js";
+import { c as optionalTemporal, l as provideTemporal, s as nowInstant, u as providedTemporal } from "./temporal-BJGitm-h.js";
+import { i as encodeValue, n as decodeScalar, r as decodeValue } from "./wire-DtZQ4sdE.js";
+import { a as ok, c as withErrorMapper, r as err, s as toDbError, t as AsyncResult } from "./result-DzUbqgdW.js";
 import { t as invalidationTargets } from "./tables-Cb-3_VWc.js";
 import { t as consoleLogger } from "./logger-glM28NVN.js";
-import { i as orderPlugins, s as tenantOf } from "./plugin-DwARMuQp.js";
-import { a as postgrestExecutor, n as StatsRecorder, r as recordStats } from "./stats-Bqob3WqT.js";
-import { d as isQuerySpec, f as specTables, n as checkParams, o as isReadSet, r as containsPlaceholder, t as bindParams, u as createSpecs } from "./read-set-DQFt1N_Y.js";
+import { i as orderPlugins } from "./plugin-tfXW1-qO.js";
+import { t as simplify } from "./simplify-DDO0j0LI.js";
+import { a as postgrestExecutor, c as invalidTuning, l as tuningOf, n as StatsRecorder, o as NO_TUNING, r as recordStats, s as deadline } from "./stats-D_AD9GGu.js";
+import { d as isQuerySpec, f as specTables, n as checkParams, o as isReadSet, r as containsPlaceholder, t as bindParams, u as createSpecs } from "./read-set-DuKWC9Mj.js";
 import { a as toBase64Url, t as base64ToText } from "./base64-D2gsioCY.js";
-import { t as validate } from "./standard-D7r6dMUu.js";
+import { t as isList } from "./guards-BnzDvFrz.js";
+import { t as vectorLiteral } from "./search-CUWCRYKL.js";
+import { n as validate } from "./standard-BK0cqJ7y.js";
 //#region src/core/batch.ts
 /**
+* A signal that aborts once every reader's signal has, so one reader giving
+* up never cancels the operations of the others. `undefined` when a reader
+* has no signal.
+*/
+function allAborted(signals) {
+	const present = signals.filter((signal) => signal !== void 0);
+	if (present.length < signals.length) return void 0;
+	if (present.length === 1) return present[0];
+	const controller = new AbortController();
+	const check = () => {
+		if (present.every((signal) => signal.aborted)) controller.abort();
+	};
+	for (const signal of present) signal.addEventListener("abort", check, { once: true });
+	check();
+	return controller.signal;
+}
+/**
 * Holds operations until each of `readers` has either submitted one or
 * finished, then runs the held ones through `batch` together. A reader that
 * runs a second operation joins the next batch.
@@ -25,7 +46,16 @@ function batchingExecutor(base, readers) {
 	const flush = () => {
 		if (queue.length === 0 || queue.length < running) return;
 		const items = queue.splice(0);
-		base.batch(items.map((item) => item.op), items[0].context).then((results) => {
+		const { signal: _first, ...shared } = items[0].context;
+		const signal = allAborted(items.map((item) => item.context.signal));
+		const context = signal ? {
+			...shared,
+			signal
+		} : shared;
+		for (const item of items) item.context.signal?.addEventListener("abort", () => {
+			item.resolve(err(dbError("aborted", "The request was aborted")));
+		}, { once: true });
+		base.batch(items.map((item) => item.op), context).then((results) => {
 			items.forEach((item, index) => {
 				item.resolve(results[index] ?? err(toDbError(/* @__PURE__ */ new Error(`Executor "${base.name}" returned too few results`))));
 			});
@@ -99,6 +129,24 @@ function memoryCache() {
 }
 //#endregion
 //#region src/core/events.ts
+function deepFreeze(value) {
+	if (Array.isArray(value) || isPlainObject(value)) {
+		for (const item of Object.values(value)) deepFreeze(item);
+		Object.freeze(value);
+	}
+	return value;
+}
+/**
+* The `error` event for `error`: a frozen copy, so a handler can't change
+* the `DbError` the caller gets back (invariant 5).
+*/
+function errorEvent(error, table) {
+	const copy = deepFreeze(cloneValue(error));
+	return table === void 0 ? { error: copy } : {
+		table,
+		error: copy
+	};
+}
 /** More handlers than this for one event usually means a missing unsubscribe. */
 const HANDLER_WARNING = 50;
 function isDevelopment() {
@@ -163,6 +211,60 @@ var EventHub = class {
 	}
 };
 //#endregion
+//#region src/core/diagnostics.ts
+/**
+* Debug records for the `diagnostics` option, after the Supabase SDK
+* capability `client.observability.diagnostic_logging`
+* (`SPEC_PINS.supabaseSdkCapabilities`). Fields are names, kinds, counts and
+* timings only: never tokens, keys, row values, filters, query strings,
+* headers or database error messages, which can quote the data.
+*/
+function logDiagnostics(events) {
+	const logger = { debug(message, fields) {
+		try {
+			events.logger.debug(message, fields);
+		} catch {}
+	} };
+	events.on("query", (event) => {
+		logger.debug(`${event.operation} ${event.table} ${event.ok ? "ok" : "failed"} in ${String(Math.round(event.durationMs))}ms`, {
+			table: event.table,
+			operation: event.operation,
+			ok: event.ok,
+			durationMs: event.durationMs,
+			rows: event.rows,
+			truncated: event.truncated
+		});
+	});
+	events.on("error", ({ table, error }) => {
+		logger.debug(`${error.kind} error${table ? ` on ${table}` : ""}`, {
+			...table ? { table } : {},
+			kind: error.kind,
+			status: error.status,
+			...error.code ? { code: error.code } : {}
+		});
+	});
+	events.on("refresh", (event) => {
+		logger.debug(`session refresh ${event.ok ? "ok" : "failed"} in ${String(Math.round(event.durationMs))}ms`, {
+			ok: event.ok,
+			shared: event.shared,
+			durationMs: event.durationMs
+		});
+	});
+	events.on("auth", (event) => {
+		logger.debug(`auth from ${event.source}: ${event.ok ? "user" : event.reason ?? "no user"}`, {
+			source: event.source,
+			ok: event.ok,
+			...event.reason ? { reason: event.reason } : {}
+		});
+	});
+}
+/** The event hub of a new definition, with the diagnostic handlers when `diagnostics` is on. */
+function definitionEvents(options) {
+	const events = new EventHub(options.logger ?? consoleLogger);
+	if (options.diagnostics === true) logDiagnostics(events);
+	return events;
+}
+//#endregion
 //#region src/ir/codec.ts
 /** Whether decoding `selection` changes anything, so plain reads skip the walk. */
 function needsDecoding(selection) {
@@ -178,7 +280,7 @@ function computeNeedsDecoding(selection) {
 	return selection.aggregate !== void 0 || selection.columns.some((column) => column.codec !== void 0) || selection.includes.some((include) => include.count !== void 0 || include.aggregate !== void 0 || needsDecoding(include.selection));
 }
 /** PostgREST returns `[{ count }]` for a `(count)` embed; SQL returns the number. */
-function countOf(value) {
+function countOf$1(value) {
 	if (Array.isArray(value)) {
 		const first = value[0];
 		return Number(first?.count ?? 0);
@@ -209,7 +311,7 @@ function droppedOf(selection) {
 	}
 	return dropped;
 }
-function decodeRow(selection, row) {
+function decodeRow$1(selection, row) {
 	const dropped = droppedOf(selection);
 	const out = {};
 	for (const key in row) if (!dropped.has(key) && Object.hasOwn(row, key)) out[key] = row[key];
@@ -224,7 +326,7 @@ function decodeRow(selection, row) {
 		}
 	}
 	if (selection.aggregate) {
-		if (selection.aggregate.count) out["_count"] = countOf(out["_count"]);
+		if (selection.aggregate.count) out["_count"] = countOf$1(out["_count"]);
 		for (const measure of selection.aggregate.measures) {
 			const value = row[measure.key];
 			fold(out, folded, `_${measure.fn}`, measure.alias, measureOf(measure, value));
@@ -234,7 +336,7 @@ function decodeRow(selection, row) {
 		const value = row[include.alias];
 		if (include.count !== void 0) {
 			if (!(include.alias in row)) continue;
-			fold(out, folded, "_count", include.count, countOf(value));
+			fold(out, folded, "_count", include.count, countOf$1(value));
 			continue;
 		}
 		if (include.aggregate !== void 0) {
@@ -245,29 +347,175 @@ function decodeRow(selection, row) {
 			fold(out, folded, `_${include.aggregate.fn}`, include.aggregate.name, measures);
 			continue;
 		}
-		if (Array.isArray(value)) out[include.alias] = value.map((item) => decodeRow(include.selection, item));
-		else if (value && typeof value === "object") out[include.alias] = decodeRow(include.selection, value);
+		if (Array.isArray(value)) out[include.alias] = value.map((item) => decodeRow$1(include.selection, item));
+		else if (value && typeof value === "object") out[include.alias] = decodeRow$1(include.selection, value);
 	}
 	return out;
 }
 /** Applies column codecs to returned rows, including embedded relations. */
 function decodeRows(selection, rows, checked = false) {
 	if (!selection || !checked && !needsDecoding(selection)) return rows;
-	return rows.map((row) => decodeRow(selection, row));
+	return rows.map((row) => decodeRow$1(selection, row));
 }
 //#endregion
 //#region src/core/cursor.ts
+function isBound(value) {
+	return typeof value === "object" && value !== null && "s" in value && typeof value.s === "string" && "v" in value && Array.isArray(value.v);
+}
+function parse(cursor) {
+	try {
+		return JSON.parse(base64ToText(cursor));
+	} catch {
+		return;
+	}
+}
 /** Opaque, URL-safe keyset cursor. */
 function encodeCursor(values) {
 	return toBase64Url(JSON.stringify(values));
 }
+/** The values of a cursor from `encodeCursor` or from `paginate()`. */
 function decodeCursor(cursor) {
-	try {
-		const parsed = JSON.parse(base64ToText(cursor));
-		return Array.isArray(parsed) ? parsed : void 0;
-	} catch {
-		return;
+	const parsed = parse(cursor);
+	if (isList(parsed)) return [...parsed];
+	return isBound(parsed) ? parsed.v : void 0;
+}
+/** A short FNV-1a hash of `text`, enough to tell two sorts apart. */
+function sortKey(text) {
+	let hash = 2166136261;
+	for (let index = 0; index < text.length; index++) {
+		hash ^= text.codePointAt(index) ?? 0;
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36);
+}
+/** A `paginate()` cursor that only continues the sort `key` names. */
+function encodeBoundCursor(values, key) {
+	return toBase64Url(JSON.stringify({
+		s: key,
+		v: values
+	}));
+}
+/**
+* The values of a `paginate()` cursor made for the sort `key`. `sort` means
+* the cursor is valid but continues another sort or table.
+*/
+function decodeBoundCursor(cursor, key) {
+	const parsed = parse(cursor);
+	if (!isBound(parsed)) return { invalid: "cursor" };
+	return parsed.s === key ? { values: parsed.v } : { invalid: "sort" };
+}
+//#endregion
+//#region src/core/keyset.ts
+/**
+* The rows after the cursor `values` in `orderBy` order, as an OR of ANDs:
+* `a > x or (a = x and b > y)`. The SQL compiler sends that shape as the row
+* comparison `(a, b) > (x, y)`. Nulls sort where Postgres puts them: last
+* for `asc`, first for `desc`, unless the term says otherwise.
+*/
+function keysetCondition(orderBy, values, nullable) {
+	const isNull = (name) => column(name, "is", null);
+	const branches = orderBy.flatMap((term, index) => {
+		const value = values[index];
+		const nullsFirst = (term.nulls ?? (term.direction === "desc" ? "first" : "last")) === "first";
+		const after = column(term.column, term.direction === "asc" ? "gt" : "lt", value);
+		const step = value === null ? nullsFirst ? not(isNull(term.column)) : void 0 : nullsFirst || !nullable(term.column) ? after : or(after, isNull(term.column));
+		if (!step) return [];
+		const equal = orderBy.slice(0, index).map((prev, prevIndex) => values[prevIndex] === null ? isNull(prev.column) : column(prev.column, "eq", values[prevIndex]));
+		return [and(...equal, step) ?? step];
+	});
+	if (branches.length === 0) return column(orderBy[0]?.column ?? "", "in", []);
+	const after = or(...branches);
+	const [first] = orderBy;
+	if (orderBy.length < 2 || !first || values[0] === null || nullable(first.column)) return after;
+	const bound = column(first.column, first.direction === "asc" ? "gte" : "lte", values[0]);
+	return and(bound, after) ?? after;
+}
+//#endregion
+//#region src/core/row-keys.ts
+/** App-cased primary keys of `rows`, or of a `where` that pins the primary key. */
+function keysOf(op, rows) {
+	const { primaryKey } = op.table;
+	if (primaryKey.length === 0) return void 0;
+	const fromRows = rows.flatMap((row) => primaryKey.every((name) => row[name] !== void 0 && row[name] !== null) ? [Object.fromEntries(primaryKey.map((name) => [name, row[name]]))] : []);
+	if (fromRows.length > 0) return fromRows;
+	if (op.kind === "insert") return void 0;
+	return keysFromWhere(op.table, op.where);
+}
+function keysFromWhere(table, where) {
+	if (!where) return void 0;
+	const { byDb } = lookupOf(table);
+	const pinned = /* @__PURE__ */ new Map();
+	const items = [];
+	const flatten = (condition) => {
+		if (condition.kind === "and") condition.items.forEach(flatten);
+		else items.push(condition);
+	};
+	flatten(where);
+	for (const item of items) {
+		if (item.kind !== "column" || item.path) continue;
+		const app = byDb.get(item.column)?.[0];
+		if (app === void 0 || !table.primaryKey.includes(app)) continue;
+		if (item.op === "eq") pinned.set(app, [item.value]);
+		else if (item.op === "in" && Array.isArray(item.value)) pinned.set(app, item.value);
 	}
+	if (pinned.size !== table.primaryKey.length) return void 0;
+	const [first, ...rest] = table.primaryKey;
+	if (first === void 0) return void 0;
+	if (rest.length === 0) return (pinned.get(first) ?? []).map((value) => ({ [first]: value }));
+	if ([...pinned.values()].some((values) => values.length !== 1)) return void 0;
+	return [Object.fromEntries(table.primaryKey.map((name) => [name, pinned.get(name)?.[0]]))];
+}
+/**
+* Rows in conflict-key order, so concurrent upserts lock the same rows in
+* the same order instead of deadlocking.
+*/
+function byKey(rows, columns) {
+	const compare = (left, right) => {
+		if (left === right) return 0;
+		if (left === null || left === void 0) return 1;
+		if (right === null || right === void 0) return -1;
+		if (typeof left === "number" && typeof right === "number") return left - right;
+		if (typeof left === "bigint" && typeof right === "bigint") return left < right ? -1 : 1;
+		const a = String(left);
+		const b = String(right);
+		return a < b ? -1 : a > b ? 1 : 0;
+	};
+	const keyed = rows.map((row) => ({
+		row,
+		key: columns.map((column) => {
+			const value = row[column];
+			return typeof value === "object" && value !== null ? String(value) : value;
+		})
+	}));
+	keyed.sort((left, right) => {
+		for (let index = 0; index < columns.length; index++) {
+			const order = compare(left.key[index], right.key[index]);
+			if (order !== 0) return order;
+		}
+		return 0;
+	});
+	return keyed.map((entry) => entry.row);
+}
+//#endregion
+//#region src/core/write-args.ts
+const COUNT_MODES = /* @__PURE__ */ new Set([
+	"exact",
+	"planned",
+	"estimated"
+]);
+function isCountMode(value) {
+	return COUNT_MODES.has(value);
+}
+/** `maxAffected` from a call, or a message when it isn't a non-negative integer. */
+function maxAffectedOf(args) {
+	const value = args["maxAffected"];
+	if (value === void 0) return {};
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 ? { maxAffected: value } : { invalid: `"maxAffected" must be a non-negative integer, got ${String(value)}` };
+}
+/** The `count` mode a mutation asks for, when it names a valid one. */
+function countOf(args) {
+	const count = args?.["count"];
+	return isCountMode(count) ? { count } : {};
 }
 //#endregion
 //#region src/core/repository.ts
@@ -294,7 +542,11 @@ const KNOWN_KEYS = /* @__PURE__ */ new Set([
 	"_sum",
 	"_avg",
 	"_min",
-	"_max"
+	"_max",
+	"timeout",
+	"retry",
+	"maxAffected",
+	"defaultToNull"
 ]);
 const NO_OPTIONS = Object.freeze({});
 function optionsOf(args) {
@@ -326,39 +578,6 @@ function signalOf(args) {
 function cloneRows(rows) {
 	return rows.map((row) => cloneValue(row));
 }
-/** App-cased primary keys of `rows`, or of a `where` that pins the primary key. */
-function keysOf(op, rows) {
-	const { primaryKey } = op.table;
-	if (primaryKey.length === 0) return void 0;
-	const fromRows = rows.flatMap((row) => primaryKey.every((name) => row[name] !== void 0 && row[name] !== null) ? [Object.fromEntries(primaryKey.map((name) => [name, row[name]]))] : []);
-	if (fromRows.length > 0) return fromRows;
-	if (op.kind === "insert") return void 0;
-	return keysFromWhere(op.table, op.where);
-}
-function keysFromWhere(table, where) {
-	if (!where) return void 0;
-	const { byDb } = lookupOf(table);
-	const pinned = /* @__PURE__ */ new Map();
-	const items = [];
-	const flatten = (condition) => {
-		if (condition.kind === "and") condition.items.forEach(flatten);
-		else items.push(condition);
-	};
-	flatten(where);
-	for (const item of items) {
-		if (item.kind !== "column") continue;
-		const app = byDb.get(item.column)?.[0];
-		if (app === void 0 || !table.primaryKey.includes(app)) continue;
-		if (item.op === "eq") pinned.set(app, [item.value]);
-		else if (item.op === "in" && Array.isArray(item.value)) pinned.set(app, item.value);
-	}
-	if (pinned.size !== table.primaryKey.length) return void 0;
-	const [first, ...rest] = table.primaryKey;
-	if (first === void 0) return void 0;
-	if (rest.length === 0) return (pinned.get(first) ?? []).map((value) => ({ [first]: value }));
-	if ([...pinned.values()].some((values) => values.length !== 1)) return void 0;
-	return [Object.fromEntries(table.primaryKey.map((name) => [name, pinned.get(name)?.[0]]))];
-}
 function mutationKind(op) {
 	if (op.kind === "insert") return op.onConflict ? "upsert" : "insert";
 	return op.kind;
@@ -371,26 +590,42 @@ var OperationRunner = class {
 		this.runtime = runtime;
 		this.#hooks = hooksOf(runtime.plugins);
 	}
-	hookArgs(table, options) {
+	hookArgs(table, options, signal) {
 		return {
 			table,
 			schema: this.runtime.meta,
 			context: this.runtime.context,
 			options,
-			now: this.runtime.now
+			now: this.runtime.now,
+			...signal ? { signal } : {}
 		};
 	}
-	async run(op, options, signal) {
+	async run(op, options, signal, tuning = NO_TUNING) {
 		const { runtime } = this;
 		const hooks = this.#hooks;
+		if ("invalid" in tuning) return this.fail(op.table, dbError("invalid_request", tuning.invalid));
+		const { timeout, retry } = {
+			...runtime.tuning,
+			...tuning
+		};
+		const invalid = invalidTuning({
+			timeout,
+			retry
+		});
+		if (invalid) return this.fail(op.table, dbError("invalid_request", invalid));
 		let current = op;
 		if (hooks.transformQuery.length > 0 || hooks.beforeMutation.length > 0) {
-			const hook = this.hookArgs(op.table, options);
+			const hook = this.hookArgs(op.table, options, signal);
+			let active = "";
 			try {
-				for (const plugin of hooks.transformQuery) current = plugin.transformQuery(current, hook);
+				for (const plugin of hooks.transformQuery) {
+					active = `plugin "${plugin.name}" transformQuery`;
+					current = plugin.transformQuery(current, hook);
+				}
 				if (current.kind !== "select") {
 					let mutation = current;
 					for (const plugin of hooks.beforeMutation) {
+						active = `plugin "${plugin.name}" beforeMutation`;
 						const next = plugin.beforeMutation(mutation, hook);
 						mutation = isThenable(next) ? await next : next;
 					}
@@ -398,16 +633,16 @@ var OperationRunner = class {
 				}
 			} catch (cause) {
 				if (cause instanceof DbException) return this.fail(op.table, cause.error);
-				throw cause;
+				return this.fail(op.table, {
+					...toDbError(cause),
+					details: `${active} threw`
+				});
 			}
 		}
+		if (current.kind === "update" && Object.keys(current.set).length === 0) return this.fail(op.table, dbError("invalid_request", `The update on "${op.table.key}" sets no columns`));
 		const timed = runtime.events.has("query");
 		const started = timed ? performance.now() : 0;
-		const context = signal ? {
-			signal,
-			errorMappers: runtime.errorMappers
-		} : { errorMappers: runtime.errorMappers };
-		const executed = await runtime.executor.execute(current, context);
+		const executed = await this.#execute(current, signal, timeout, retry);
 		const selection = current.kind === "select" ? current.selection : current.returning;
 		let result = executed;
 		if (executed.ok && selection && needsDecoding(selection)) try {
@@ -437,10 +672,44 @@ var OperationRunner = class {
 			truncated
 		});
 		if (!result.ok) return this.fail(op.table, result.error);
-		if (current.kind !== "select") await this.afterMutation(op, current, result.data);
+		if (current.kind !== "select") await this.afterMutation(current, result.data);
 		return result;
 	}
-	async afterMutation(requested, op, data) {
+	/**
+	* Runs `op` without plugins or decoding, with the connection's timeout and
+	* retry, and fails on `table`: for reads the library makes itself, such
+	* as the scores of `db.$search({ score: true })`.
+	*/
+	async runInternal(op, table, signal) {
+		const { timeout, retry } = this.runtime.tuning ?? NO_TUNING;
+		const invalid = invalidTuning({
+			timeout,
+			retry
+		});
+		if (invalid) return this.fail(table, dbError("invalid_request", invalid));
+		const executed = await this.#execute(op, signal, timeout, retry);
+		return executed.ok ? executed : this.fail(table, {
+			...executed.error,
+			table: table.key
+		});
+	}
+	async #execute(op, signal, timeout, retry) {
+		const limit = deadline(signal, timeout);
+		const context = {
+			errorMappers: this.runtime.errorMappers,
+			...limit.signal ? { signal: limit.signal } : {},
+			...retry === void 0 ? {} : { retry }
+		};
+		let executed;
+		try {
+			executed = await this.runtime.executor.execute(op, context);
+		} finally {
+			limit.clear();
+		}
+		if (!executed.ok && limit.timedOut()) return err(dbError("timeout", `The request timed out after ${timeout} ms`));
+		return executed;
+	}
+	async afterMutation(op, data) {
 		const { runtime } = this;
 		const plugins = this.#hooks.afterMutation;
 		const listening = runtime.events.has("mutation");
@@ -448,11 +717,11 @@ var OperationRunner = class {
 		const kind = mutationKind(op);
 		const rows = cloneRows(data.rows);
 		const keys = keysOf(op, rows);
-		const tenant = tenantOf(runtime.context);
+		const { tenant } = runtime.context;
 		const event = {
 			table: op.table,
 			kind,
-			intent: requested.kind === "delete" && op.kind === "update" ? "softDelete" : kind,
+			intent: op.intent ?? kind,
 			rows,
 			...keys ? { keys } : {},
 			...tenant === void 0 ? {} : { tenant },
@@ -479,14 +748,13 @@ var OperationRunner = class {
 			...error,
 			table: table.key
 		};
-		if (this.runtime.events.has("error")) this.runtime.events.emit("error", {
-			table: table.key,
-			error: withTable
-		});
+		if (this.runtime.events.has("error")) this.runtime.events.emit("error", errorEvent(withTable, table.key));
 		return err(withTable);
 	}
 };
 const sensitiveByTable = /* @__PURE__ */ new WeakMap();
+const primaryOrders = /* @__PURE__ */ new WeakMap();
+const existsSelections = /* @__PURE__ */ new WeakMap();
 /** Database names of the table's `config.sensitive` columns. */
 function sensitiveColumnsOf(table) {
 	let sensitive = sensitiveByTable.get(table);
@@ -501,14 +769,20 @@ function createRepository(runner, table) {
 	const { builder } = runner.runtime;
 	const sensitiveDb = sensitiveColumnsOf(table);
 	const selection = (args) => builder.selection(table, args?.["select"], args?.["include"]);
+	const rowCount = (args, name) => {
+		const value = args?.[name];
+		if (value === void 0) return void 0;
+		if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) invalidRequest(`"${name}" must be a non-negative integer, not ${String(value)}`, table.key);
+		return value;
+	};
 	const selectOp = (args, patch = {}) => ({
 		kind: "select",
 		table,
 		selection: selection(args),
 		where: builder.where(table, args?.["where"]),
 		orderBy: builder.orderBy(table, args?.["orderBy"]),
-		limit: typeof args?.["limit"] === "number" ? args["limit"] : void 0,
-		offset: typeof args?.["offset"] === "number" ? args["offset"] : void 0,
+		limit: rowCount(args, "limit"),
+		offset: rowCount(args, "offset"),
 		count: void 0,
 		head: false,
 		single: void 0,
@@ -525,19 +799,34 @@ function createRepository(runner, table) {
 			columns
 		};
 	};
-	const run = (op, args) => runner.run(op, optionsOf(args), signalOf(args));
-	let primaryOrder;
+	const run = (op, args) => runner.run(op, optionsOf(args), signalOf(args), tuningOf(args));
 	/** `primaryKey` holds app names; order terms take database names. */
-	const defaultOrder = () => primaryOrder ??= table.primaryKey.map((name) => ({
-		column: builder.column(table, name),
-		direction: "asc"
-	}));
+	const defaultOrder = () => {
+		let order = primaryOrders.get(table);
+		if (!order) {
+			order = table.primaryKey.map((name) => ({
+				column: builder.column(table, name),
+				direction: "asc",
+				implicit: true
+			}));
+			primaryOrders.set(table, order);
+		}
+		return order;
+	};
 	const notFound = () => runner.fail(table, dbError("not_found", `No ${table.key} row matched`));
+	/** Arguments the builder rejects fail like any other error: with the table and an `error` event. */
+	const guarded = (work) => AsyncResult.from(async () => {
+		try {
+			return await work();
+		} catch (cause) {
+			return runner.fail(table, toDbError(cause));
+		}
+	});
 	const base = {
 		$tableName: table.key,
 		$meta: table,
 		findMany(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const op = selectOp(args);
 				const ordered = op.orderBy.length > 0 || table.primaryKey.length === 0 ? op : {
 					...op,
@@ -548,13 +837,24 @@ function createRepository(runner, table) {
 			});
 		},
 		findFirst(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const result = await run(selectOp(args, { limit: 1 }), args);
 				return result.ok ? ok(result.data.rows[0] ?? null) : result;
 			});
 		},
+		findOnly(args) {
+			return guarded(async () => {
+				const result = await run(selectOp(args, {
+					limit: 2,
+					unpaged: true
+				}), args);
+				if (!result.ok) return result;
+				if (result.data.rows.length > 1) return runner.fail(table, dbError("multiple_rows", `More than one ${table.key} row matched; findOnly expects at most one`));
+				return ok(result.data.rows[0] ?? null);
+			});
+		},
 		findUnique(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const op = selectOp(args, {
 					where: builder.uniqueKey(table, args["where"]),
 					limit: 1
@@ -564,7 +864,7 @@ function createRepository(runner, table) {
 			});
 		},
 		findById(id, args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const op = selectOp(args, {
 					where: builder.primaryKey(table, id),
 					limit: 1
@@ -576,7 +876,7 @@ function createRepository(runner, table) {
 			});
 		},
 		count(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const mode = args?.["mode"];
 				const op = selectOp({ where: args?.["where"] }, {
 					selection: {
@@ -591,12 +891,9 @@ function createRepository(runner, table) {
 			});
 		},
 		aggregate(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const aggregation = builder.aggregation(table, args);
-				const orderBy = builder.orderBy(table, args["orderBy"]);
-				const grouped = new Set(aggregation.columns.map((c) => c.column));
-				const loose = orderBy.find((term) => !grouped.has(term.column));
-				if (loose) return runner.fail(table, dbError("invalid_request", `aggregate on "${table.key}" can only sort by groupBy columns, not "${loose.column}"`));
+				const orderBy = builder.aggregateOrderBy(table, args["orderBy"], aggregation);
 				const op = selectOp({
 					where: args["where"],
 					limit: args["limit"],
@@ -612,13 +909,9 @@ function createRepository(runner, table) {
 			});
 		},
 		exists(args) {
-			return AsyncResult.from(async () => {
-				const columns = table.primaryKey.slice(0, 1).map((alias) => builder.selectColumn(table, alias));
+			return guarded(async () => {
 				const op = selectOp({ where: args?.["where"] }, {
-					selection: {
-						columns,
-						includes: []
-					},
+					selection: existsSelection(),
 					limit: 1
 				});
 				const result = await run(op, args);
@@ -626,10 +919,10 @@ function createRepository(runner, table) {
 			});
 		},
 		paginate(args) {
-			return AsyncResult.from(async () => "after" in args ? cursorPage(args) : offsetPage(args));
+			return guarded(async () => "after" in args ? cursorPage(args) : offsetPage(args));
 		},
 		create(data, args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const op = insertOp([data], args, void 0);
 				const result = await run(op, args);
 				if (!result.ok) return result;
@@ -637,7 +930,7 @@ function createRepository(runner, table) {
 			});
 		},
 		createMany(rows, args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				if (rows.length === 0) return ok(args?.["returning"] === false ? { count: 0 } : []);
 				const result = await run(insertOp(rows, args, void 0), args);
 				if (!result.ok) return result;
@@ -645,8 +938,8 @@ function createRepository(runner, table) {
 			});
 		},
 		update(id, patch, args) {
-			return AsyncResult.from(async () => {
-				const key = builder.primaryKey(table, id);
+			return guarded(async () => {
+				const key = and(builder.primaryKey(table, id), builder.where(table, args?.["where"]));
 				const expect = args?.["expect"] ? builder.where(table, args["expect"]) : void 0;
 				const op = {
 					kind: "update",
@@ -675,20 +968,28 @@ function createRepository(runner, table) {
 			});
 		},
 		updateMany(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
+				const where = builder.where(table, args["where"]);
+				if (simplify(where) === true && args["allowAll"] !== true) return runner.fail(table, dbError("invalid_request", "updateMany needs a \"where\" that filters rows; pass allowAll: true to update every row"));
+				const rows = args["returning"] === true;
+				const bound = maxAffectedOf(args);
+				if ("invalid" in bound) return runner.fail(table, dbError("invalid_request", bound.invalid));
 				const op = {
 					kind: "update",
 					table,
 					set: builder.row(table, args["data"], "update"),
-					where: builder.where(table, args["where"]),
-					returning: void 0
+					where,
+					returning: rows ? returning(args) : void 0,
+					...bound,
+					...countOf(args)
 				};
 				const result = await run(op, args);
-				return result.ok ? ok({ count: result.data.count ?? 0 }) : result;
+				if (!result.ok) return result;
+				return ok(rows ? result.data.rows : { count: result.data.count ?? 0 });
 			});
 		},
 		upsert(data, args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const op = insertOp([data], args, conflictColumns(args?.["onConflict"]));
 				const result = await run(op, args);
 				if (!result.ok) return result;
@@ -696,7 +997,7 @@ function createRepository(runner, table) {
 			});
 		},
 		upsertMany(rows, args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				if (rows.length === 0) return ok(args?.["returning"] === false ? { count: 0 } : []);
 				const op = insertOp(rows, args, conflictColumns(args?.["onConflict"]));
 				const result = await run(op, args);
@@ -705,7 +1006,7 @@ function createRepository(runner, table) {
 			});
 		},
 		delete(id, args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const op = {
 					kind: "delete",
 					table,
@@ -718,16 +1019,26 @@ function createRepository(runner, table) {
 			});
 		},
 		deleteMany(args) {
-			return AsyncResult.from(async () => {
+			return guarded(async () => {
 				const where = builder.where(table, args["where"]);
-				if (!where) return runner.fail(table, dbError("invalid_request", "deleteMany needs a non-empty \"where\""));
-				const result = await run({
+				if (!where || simplify(where) === true) return runner.fail(table, dbError("invalid_request", "deleteMany needs a \"where\" that filters rows"));
+				const rows = args["returning"] === true;
+				const bound = maxAffectedOf(args);
+				if ("invalid" in bound) return runner.fail(table, dbError("invalid_request", bound.invalid));
+				const op = {
 					kind: "delete",
 					table,
 					where,
-					returning: void 0
-				}, args);
-				return result.ok ? ok({ count: result.data.count ?? 0 }) : result;
+					returning: rows ? returning(args) : void 0,
+					...bound,
+					...countOf(args)
+				};
+				const result = await runner.run(op, rows ? {
+					...optionsOf(args),
+					returning: true
+				} : optionsOf(args), signalOf(args), tuningOf(args));
+				if (!result.ok) return result;
+				return ok(rows ? result.data.rows : { count: result.data.count ?? 0 });
 			});
 		}
 	};
@@ -742,9 +1053,27 @@ function createRepository(runner, table) {
 				columns: conflict,
 				action: args?.["ignoreDuplicates"] === true ? "ignore" : "update"
 			} : void 0,
-			defaultToNull: false
+			defaultToNull: args?.["defaultToNull"] === true,
+			...countOf(args)
 		};
 	}
+	/** One column is enough to see a row: the primary key, or the first non-sensitive column. */
+	function existsSelection() {
+		let found = existsSelections.get(table);
+		if (!found) {
+			const names = Object.keys(table.columns);
+			const alias = table.primaryKey[0] ?? names.find((name) => !table.columns[name]?.sensitive) ?? names[0];
+			found = {
+				columns: alias === void 0 ? [] : [{
+					alias,
+					column: builder.column(table, alias)
+				}],
+				includes: []
+			};
+			existsSelections.set(table, found);
+		}
+		return found;
+	}
 	function conflictColumns(target) {
 		if (target === void 0 || target === "primaryKey") return table.primaryKey.map((name) => builder.column(table, name));
 		if (typeof target === "string") {
@@ -755,18 +1084,39 @@ function createRepository(runner, table) {
 		if (Array.isArray(target)) return target.map((name) => builder.column(table, String(name)));
 		return invalidRequest(`Invalid onConflict on "${table.key}"`, table.key);
 	}
-	async function offsetPage(args) {
+	function pageWindow(args) {
+		if (args["offset"] !== void 0 || args["limit"] !== void 0) {
+			if (args["page"] !== void 0 || args["size"] !== void 0) return { invalid: "Pass \"offset\" and \"limit\" or \"page\" and \"size\"" };
+			const limit = Number(args["limit"]);
+			if (!Number.isInteger(limit) || limit < 1) return { invalid: "\"limit\" must be a positive integer" };
+			const offset = Number(args["offset"]);
+			if (!Number.isInteger(offset) || offset < 0) return { invalid: "\"offset\" must be a non-negative integer" };
+			return {
+				size: limit,
+				offset
+			};
+		}
 		const size = Number(args["size"]);
-		if (!Number.isInteger(size) || size < 1) return runner.fail(table, dbError("invalid_request", "\"size\" must be a positive integer"));
+		if (!Number.isInteger(size) || size < 1) return { invalid: "\"size\" must be a positive integer" };
 		const number = args["page"] === void 0 ? 1 : Number(args["page"]);
-		if (!Number.isInteger(number) || number < 1) return runner.fail(table, dbError("invalid_request", "\"page\" must be a positive integer"));
+		if (!Number.isInteger(number) || number < 1) return { invalid: "\"page\" must be a positive integer" };
+		return {
+			size,
+			offset: (number - 1) * size
+		};
+	}
+	async function offsetPage(args) {
+		const window = pageWindow(args);
+		if ("invalid" in window) return runner.fail(table, dbError("invalid_request", window.invalid));
+		const { size, offset } = window;
+		const number = Math.floor(offset / size) + 1;
 		const count = args["count"];
 		const orderBy = builder.orderBy(table, args["orderBy"]);
 		const op = selectOp(args, {
 			orderBy: orderBy.length > 0 || table.primaryKey.length === 0 ? orderBy : defaultOrder(),
 			limit: size + 1,
 			lookAhead: true,
-			offset: (number - 1) * size,
+			offset,
 			count: count === "exact" || count === "planned" || count === "estimated" ? count : void 0
 		});
 		const result = await run(op, args);
@@ -787,11 +1137,17 @@ function createRepository(runner, table) {
 	async function cursorPage(args) {
 		const size = Number(args["size"]);
 		if (!Number.isInteger(size) || size < 1) return runner.fail(table, dbError("invalid_request", "\"size\" must be a positive integer"));
-		const orderBy = withTieBreaker(builder.orderBy(table, args["orderBy"]));
+		const requested = builder.orderBy(table, args["orderBy"]);
+		const related = requested.find((term) => term.relation);
+		if (related) return runner.fail(table, dbError("invalid_request", `Cursor pages can't sort by the relation "${related.relation?.name}"; use an offset page`));
+		const orderBy = withTieBreaker(requested);
 		const { selection: withSort, added } = ensureColumns(selection(args), orderBy);
+		const sort = sortKey(`${table.key}|${orderBy.map((term) => `${term.column}.${term.direction}.${term.nulls ?? ""}`).join(",")}`);
 		let after;
 		if (typeof args["after"] === "string") {
-			const values = decodeCursor(args["after"]);
+			const decoded = decodeBoundCursor(args["after"], sort);
+			if ("invalid" in decoded && decoded.invalid === "sort") return runner.fail(table, dbError("invalid_request", "The cursor continues another orderBy; pass after: null to start the new order"));
+			const values = "values" in decoded ? decoded.values : void 0;
 			if (!values || values.length !== orderBy.length) return runner.fail(table, dbError("invalid_request", "Invalid cursor"));
 			const { byDb } = lookupOf(table);
 			after = keysetCondition(orderBy, values, (name) => byDb.get(name)?.[1].nullable ?? true);
@@ -810,7 +1166,7 @@ function createRepository(runner, table) {
 		const hasMore = result.data.rows.length > size;
 		const last = rows.at(-1);
 		const aliases = new Map(withSort.columns.map((entry) => [entry.column, entry.alias]));
-		const nextCursor = hasMore && last ? encodeCursor(orderBy.map((term) => encodeValue(last[aliases.get(term.column) ?? term.column]))) : null;
+		const nextCursor = hasMore && last ? encodeBoundCursor(orderBy.map((term) => encodeValue(last[aliases.get(term.column) ?? term.column])), sort) : null;
 		return ok({
 			items: added.length > 0 ? rows.map((row) => strip(row, added)) : rows,
 			nextCursor,
@@ -835,13 +1191,13 @@ function createRepository(runner, table) {
 		const added = [];
 		for (const term of orderBy) {
 			if (selected.has(term.column)) continue;
-			const alias = byDb.get(term.column)?.[0] ?? term.column;
-			columns.push({
-				alias,
+			const alias = byDb.get(term.column)?.[0];
+			columns.push(alias === void 0 ? {
+				alias: term.column,
 				column: term.column
-			});
+			} : builder.selectColumn(table, alias));
 			selected.add(term.column);
-			added.push(alias);
+			added.push(alias ?? term.column);
 		}
 		return {
 			selection: {
@@ -858,69 +1214,101 @@ function strip(row, keys) {
 	for (const key in row) if (!keys.includes(key) && Object.hasOwn(row, key)) copy[key] = row[key];
 	return copy;
 }
-/**
-* Rows in conflict-key order, so concurrent upserts lock the same rows in
-* the same order instead of deadlocking.
-*/
-function byKey(rows, columns) {
-	const compare = (left, right) => {
-		if (left === right) return 0;
-		if (left === null || left === void 0) return 1;
-		if (right === null || right === void 0) return -1;
-		if (typeof left === "number" && typeof right === "number") return left - right;
-		if (typeof left === "bigint" && typeof right === "bigint") return left < right ? -1 : 1;
-		const a = String(left);
-		const b = String(right);
-		return a < b ? -1 : a > b ? 1 : 0;
-	};
-	const keyed = rows.map((row) => ({
-		row,
-		key: columns.map((column) => {
-			const value = row[column];
-			return typeof value === "object" && value !== null ? String(value) : value;
-		})
-	}));
-	keyed.sort((left, right) => {
-		for (let index = 0; index < columns.length; index++) {
-			const order = compare(left.key[index], right.key[index]);
-			if (order !== 0) return order;
+//#endregion
+//#region src/core/rpc-result.ts
+const columnsByFunction = /* @__PURE__ */ new WeakMap();
+function columnsOf(meta, fn) {
+	const cached = columnsByFunction.get(fn);
+	if (cached !== void 0) return cached;
+	let columns = null;
+	const { result } = fn;
+	if (result && "table" in result) {
+		const table = meta.tables[result.table];
+		if (table) {
+			columns = /* @__PURE__ */ new Map();
+			for (const [db, [app, column]] of lookupOf(table).byDb) if (app !== db || column.codec) columns.set(db, [app, column.codec]);
 		}
-		return 0;
-	});
-	return keyed.map((entry) => entry.row);
+	} else if (result) columns = new Map(result.columns.map((column) => [column.db, [column.name ?? column.db, column.codec]]));
+	columnsByFunction.set(fn, columns);
+	return columns;
+}
+function decodeRow(columns, row) {
+	if (!isPlainObject(row)) return row;
+	const out = {};
+	for (const key in row) {
+		if (!Object.hasOwn(row, key)) continue;
+		const column = columns.get(key);
+		if (!column) {
+			out[key] = row[key];
+			continue;
+		}
+		const [app, codec] = column;
+		out[app] = codec ? decodeValue(codec, row[key]) : row[key];
+	}
+	return out;
 }
+const overloadMeta = /* @__PURE__ */ new WeakMap();
 /**
-* The rows after the cursor `values` in `orderBy` order, as an OR of ANDs:
-* `a > x or (a = x and b > y)`. The SQL compiler sends that shape as the row
-* comparison `(a, b) > (x, y)`. Nulls sort where Postgres puts them: last
-* for `asc`, first for `desc`, unless the term says otherwise.
+* The signature `$rpc` calls: PostgREST picks an overload by the argument
+* names, so a call matches the overload that has every name it passes and
+* every argument without a default. Undefined when the function is in
+* another schema or when no overload, or more than one, matches.
 */
-function keysetCondition(orderBy, values, nullable) {
-	const isNull = (name) => column(name, "is", null);
-	const branches = orderBy.flatMap((term, index) => {
-		const value = values[index];
-		const nullsFirst = (term.nulls ?? (term.direction === "desc" ? "first" : "last")) === "first";
-		const after = column(term.column, term.direction === "asc" ? "gt" : "lt", value);
-		const step = value === null ? nullsFirst ? not(isNull(term.column)) : void 0 : nullsFirst || !nullable(term.column) ? after : or(after, isNull(term.column));
-		if (!step) return [];
-		const equal = orderBy.slice(0, index).map((prev, prevIndex) => values[prevIndex] === null ? isNull(prev.column) : column(prev.column, "eq", values[prevIndex]));
-		return [and(...equal, step) ?? step];
-	});
-	return branches.length > 0 ? or(...branches) : column(orderBy[0]?.column ?? "", "in", []);
+function rpcFunction(meta, name, schema, args) {
+	const fn = meta.functions[name];
+	if (!fn || fn.schema !== schema) return void 0;
+	if (!fn.overloads) return fn;
+	const keys = Object.keys(args).filter((key) => args[key] !== void 0);
+	const matches = fn.overloads.filter((overload) => keys.every((key) => overload.args.some((arg) => arg.name === key)) && overload.args.every((arg) => arg.optional === true || keys.includes(arg.name)));
+	const [match] = matches;
+	if (!match || matches.length > 1) return void 0;
+	let resolved = overloadMeta.get(match);
+	if (!resolved) {
+		resolved = {
+			...match,
+			name: fn.name,
+			schema: fn.schema
+		};
+		overloadMeta.set(match, resolved);
+	}
+	return resolved;
 }
-//#endregion
-//#region src/core/search.ts
-/** pgvector's text form, or `undefined` for anything that isn't a finite vector. */
-function vectorLiteral(vector) {
-	if (typeof vector === "string") return /^\[[^\]]+\]$/.test(vector.trim()) ? vector.trim() : void 0;
-	if (vector.length === 0 || !vector.every(Number.isFinite)) return void 0;
-	return `[${vector.join(",")}]`;
+/**
+* The `$rpc` result in app form: rows of a table or a `returns table (...)`
+* record get the configured casing and codecs, like repository reads.
+* Scalars, json and calls without a known signature come back unchanged.
+*/
+function decodeRpcResult(meta, fn, data) {
+	if (!fn) return data;
+	const columns = columnsOf(meta, fn);
+	if (!columns || columns.size === 0) return data;
+	return Array.isArray(data) ? data.map((row) => decodeRow(columns, row)) : decodeRow(columns, data);
 }
 //#endregion
 //#region src/core/define.ts
 function isExecutor(value) {
 	return typeof value === "object" && value !== null && typeof value.execute === "function" && typeof value.name === "string";
 }
+/** No plugins, one shared array so the caches keyed on a plugin list hit. */
+const NO_PLUGINS = Object.freeze([]);
+/** The kept lists per installed list and `keep` names, so each is one stable array. */
+const keptLists = /* @__PURE__ */ new WeakMap();
+/** The installed plugins named in `keep`; a name that isn't installed throws, so a typo can't drop tracing silently. */
+function keptPlugins(plugins, keep) {
+	if (keep.length === 0) return NO_PLUGINS;
+	let byKeep = keptLists.get(plugins);
+	if (!byKeep) {
+		byKeep = /* @__PURE__ */ new Map();
+		keptLists.set(plugins, byKeep);
+	}
+	const key = keep.join("\0");
+	const cached = byKeep.get(key);
+	if (cached) return cached;
+	for (const name of keep) if (!plugins.some((plugin) => plugin.name === name)) throw new TypeError(`better-supabase: $withoutPlugins({ keep }) names "${name}", which is not installed. Installed: ${plugins.map((plugin) => plugin.name).join(", ") || "none"}`);
+	const kept = plugins.filter((plugin) => keep.includes(plugin.name));
+	byKeep.set(key, kept);
+	return kept;
+}
 /**
 * The isomorphic definition of your data layer: schema plus plugins. Holds no
 * secrets and no connection; `connect()` binds it to a client per request.
@@ -930,15 +1318,37 @@ var BetterSupabase = class BetterSupabase {
 	plugins;
 	events;
 	options;
-	constructor(schema, plugins = [], options = {}, events = new EventHub(options.logger)) {
+	constructor(schema, plugins = [], options = {}, events = definitionEvents(options)) {
+		const names = /* @__PURE__ */ new Set();
+		for (const plugin of plugins) {
+			if (plugin.apiVersion !== 1) throw new TypeError(`better-supabase: plugin "${plugin.name}" targets plugin API v${String(plugin.apiVersion)}; this version supports v1`);
+			if (names.has(plugin.name)) throw new TypeError(`better-supabase: plugin "${plugin.name}" is already installed`);
+			names.add(plugin.name);
+		}
 		this.schema = schema;
 		this.plugins = orderPlugins(plugins);
 		this.options = options;
 		this.events = events;
+		const { temporal } = options;
+		if (temporal !== void 0) {
+			const previous = providedTemporal();
+			if (previous !== void 0 && previous !== temporal) events.logger.warn("defineSupabase got a different `temporal` namespace than the one already provided; decoded rows, jobs and webhooks in this process now use the newer one. Pass the same namespace to every definition.");
+			provideTemporal(temporal);
+		}
 	}
 	get meta() {
 		return this.schema.meta;
 	}
+	/** The `now` option, else this definition's own `Temporal` clock. */
+	#now() {
+		const { now, temporal } = this.options;
+		if (now) return now;
+		return temporal ? () => temporal.Now.instant() : nowInstant;
+	}
+	/** The `Temporal` this definition uses: the `temporal` option, else the global. */
+	get temporal() {
+		return this.options.temporal ?? optionalTemporal();
+	}
 	/** The schema set by `claims()`; its output types `session.claims`. */
 	get claimsSchema() {
 		return this.options.claims;
@@ -1016,8 +1426,6 @@ var BetterSupabase = class BetterSupabase {
 	}
 	/** Returns a new instance with the plugin appended. */
 	use(plugin) {
-		if (plugin.apiVersion !== 1) throw new TypeError(`better-supabase: plugin "${plugin.name}" targets plugin API v${String(plugin.apiVersion)}; this version supports v1`);
-		if (this.plugins.some((existing) => existing.name === plugin.name)) throw new TypeError(`better-supabase: plugin "${plugin.name}" is already installed`);
 		return new BetterSupabase(this.schema, [...this.plugins, plugin], this.options, this.events);
 	}
 	/**
@@ -1076,11 +1484,41 @@ var BetterSupabase = class BetterSupabase {
 	}
 	connect(source, context = {}, options = {}) {
 		const client = isExecutor(source) ? void 0 : source;
-		const base = options.executor ?? (isExecutor(source) ? source : postgrestExecutor(source));
+		const base = options.executor ?? (isExecutor(source) ? source : postgrestExecutor(source, this.executorOptions()));
 		const recorder = new StatsRecorder(options.stats);
-		return this.#db(client, base, context, this.plugins, recorder);
+		const tuning = {
+			...options.timeout === void 0 ? {} : { timeout: options.timeout },
+			...options.retry === void 0 ? {} : { retry: options.retry }
+		};
+		return this.#db(client, base, context, this.plugins, recorder, tuning);
+	}
+	/**
+	* The `postgrestExecutor` options this definition implies
+	* (`urlLengthLimit`, `postgrestVersion`), for adapters that build their
+	* own executor and should chunk reads the same way.
+	*/
+	executorOptions() {
+		const { urlLengthLimit, postgrestVersion } = this.options;
+		return {
+			...urlLengthLimit === void 0 ? {} : { urlLengthLimit },
+			...postgrestVersion === void 0 ? {} : { postgrestVersion }
+		};
+	}
+	/** The caller's context with every plugin's `context` hook applied. */
+	#derive(given, plugins) {
+		let context = given;
+		for (const plugin of plugins) {
+			if (!plugin.context) continue;
+			try {
+				context = plugin.context(context, { schema: this.meta });
+			} catch (cause) {
+				this.events.logger.error(`plugin "${plugin.name}" context threw`, { cause });
+			}
+		}
+		return context;
 	}
-	#db(client, base, context, plugins, recorder, events = this.events) {
+	#db(client, base, given, plugins, recorder, tuning = {}, events = this.events) {
+		const context = this.#derive(given, plugins);
 		let executor = base;
 		for (const plugin of plugins) if (plugin.wrapExecutor) executor = plugin.wrapExecutor(executor);
 		executor = recordStats(executor, recorder);
@@ -1093,10 +1531,90 @@ var BetterSupabase = class BetterSupabase {
 			context,
 			events,
 			errorMappers,
-			now: this.options.now ?? nowInstant,
+			now: this.#now(),
 			maxRows: this.options.maxRows ?? 1e3,
-			truncatedTables: this.#truncatedTables
+			truncatedTables: this.#truncatedTables,
+			tuning
 		});
+		/**
+		* `db.$search({ score: true })`: the ranked ids and scores from
+		* `search_<table>_scores`, then those rows through the table (RLS and
+		* `where` apply), best first, each with `$score`.
+		*/
+		const scoredSearch = async (table, fnArgs, args, hint) => {
+			const [key, ...rest] = table.primaryKey;
+			if (key === void 0 || rest.length > 0) return err(dbError("invalid_request", "db.$search({ score: true }) needs a table with a one-column primary key", { table: table.key }));
+			const { builder } = runner.runtime;
+			const scoresTable = {
+				key: `${table.key}$scores`,
+				name: `search_${table.name}_scores`,
+				schema: table.schema,
+				kind: "view",
+				columns: {
+					id: {
+						db: "id",
+						type: "jsonb",
+						nullable: false,
+						hasDefault: false
+					},
+					score: {
+						db: "score",
+						type: "float8",
+						nullable: false,
+						hasDefault: false
+					}
+				},
+				primaryKey: [],
+				uniqueKeys: {},
+				relations: {},
+				flags: {}
+			};
+			const scored = await runner.runInternal({
+				kind: "select",
+				table: scoresTable,
+				selection: builder.selection(scoresTable, ["id", "score"], void 0),
+				where: void 0,
+				orderBy: [],
+				limit: void 0,
+				offset: void 0,
+				count: void 0,
+				head: false,
+				single: void 0,
+				source: {
+					schema: table.schema,
+					name: scoresTable.name,
+					args: fnArgs
+				}
+			}, table, args.signal);
+			if (!scored.ok) return err(hint(scored.error));
+			const ranked = scored.data.rows.flatMap((row) => row["score"] === void 0 || row["score"] === null ? [] : [{
+				id: row["id"],
+				score: Number(row["score"])
+			}]);
+			if (ranked.length === 0) return ok([]);
+			const byId = new Map(ranked.map((entry) => [String(entry.id), entry]));
+			const op = {
+				kind: "select",
+				table,
+				selection: builder.selection(table, args.select, args.include),
+				where: builder.where(table, { AND: [...args.where === void 0 ? [] : [args.where], { [key]: { in: ranked.map((entry) => entry.id) } }] }),
+				orderBy: [],
+				limit: ranked.length,
+				offset: void 0,
+				count: void 0,
+				head: false,
+				single: void 0
+			};
+			const result = await runner.run(op, {}, args.signal);
+			if (!result.ok) return result;
+			return ok(result.data.rows.flatMap((row) => {
+				const entry = byId.get(String(row[key]));
+				return entry ? [{
+					...row,
+					$score: entry.score
+				}] : [];
+			}).toSorted((a, b) => b.$score - a.$score));
+		};
 		const db = Object.create(this.#tablePrototype());
 		dbStates.set(db, {
 			runner,
@@ -1107,7 +1625,7 @@ var BetterSupabase = class BetterSupabase {
 			$client: client,
 			$executor: executor,
 			$context: context,
-			$rpc: (name, ...rest) => rpc(executor, errorMappers, name, rest).map((data) => {
+			$rpc: (name, ...rest) => rpc(this.schema.meta, executor, errorMappers, tuning, name, rest).map((data) => {
 				const registered = this.options.rpc?.[name];
 				if (registered) this.events.emit("rpc", {
 					name,
@@ -1115,12 +1633,15 @@ var BetterSupabase = class BetterSupabase {
 					context
 				});
 				return data;
+			}).mapError((error) => {
+				if (events.has("error")) events.emit("error", errorEvent(error));
+				return error;
 			}),
 			$with: (extra) => this.#db(client, base, {
-				...context,
+				...given,
 				...extra
-			}, plugins, recorder),
-			$withoutPlugins: () => this.#db(client, base, context, [], recorder),
+			}, plugins, recorder, tuning),
+			$withoutPlugins: (options) => this.#db(client, base, given, keptPlugins(plugins, options?.keep ?? []), recorder, tuning),
 			$stats: () => recorder.snapshot(),
 			$table: (name) => {
 				if (!Object.hasOwn(this.meta.tables, name)) throw new TypeError(`better-supabase: unknown table "${name}". Known: ${Object.keys(this.meta.tables).join(", ")}`);
@@ -1140,10 +1661,21 @@ var BetterSupabase = class BetterSupabase {
 				const table = Object.hasOwn(this.meta.tables, name) ? this.meta.tables[name] : void 0;
 				if (!table) return err(dbError("invalid_request", `db.$search(): unknown table "${name}"`));
 				if (!base.functionSources) return err(dbError("invalid_request", `db.$search() reads from a function; the ${base.name} executor doesn't support that`, { table: table.key }));
-				const query = vectorLiteral(args.vector);
+				const query = (args.vector === void 0 || args.vector === null) && args.text !== void 0 ? null : vectorLiteral(args.vector ?? []);
 				const k = args.k ?? 10;
-				if (query === void 0 || !Number.isInteger(k) || k < 1) return err(dbError("invalid_input", "db.$search() needs a vector of finite numbers and a positive integer k", { table: table.key }));
+				if (query === void 0 || !Number.isInteger(k) || k < 1) return err(dbError("invalid_input", "db.$search() needs a vector of finite numbers (or text alone on a hybrid entry) and a positive integer k", { table: table.key }));
 				const { builder } = runner.runtime;
+				const fnArgs = {
+					query,
+					k,
+					...args.filter === void 0 ? {} : { filter: args.filter },
+					...args.text === void 0 ? {} : { text_query: args.text }
+				};
+				const hint = (error) => error.code === "PGRST202" || error.code === "42883" ? {
+					...error,
+					hint: `Add "${table.schema}.${table.name}" to vectorSearch in better-supabase.config.ts (with prefilter or hybrid for filter and text) and run \`better-supabase sql sync\`.`
+				} : error;
+				if (args.score) return scoredSearch(table, fnArgs, args, hint);
 				const op = {
 					kind: "select",
 					table,
@@ -1158,18 +1690,12 @@ var BetterSupabase = class BetterSupabase {
 					source: {
 						schema: table.schema,
 						name: `search_${table.name}`,
-						args: {
-							query,
-							k
-						}
+						args: fnArgs
 					}
 				};
 				const result = await runner.run(op, {}, args.signal);
 				if (result.ok) return ok(result.data.rows);
-				return result.error.code === "PGRST202" || result.error.code === "42883" ? err({
-					...result.error,
-					hint: `Add "${table.schema}.${table.name}" to vectorSearch in better-supabase.config.ts and run \`better-supabase sql sync\`.`
-				}) : result;
+				return err(hint(result.error));
 			})
 		});
 		const many = (specs, signal, usePlugins) => AsyncResult.from(async () => {
@@ -1181,7 +1707,7 @@ var BetterSupabase = class BetterSupabase {
 				...base,
 				batch
 			}, specs.length) : void 0;
-			const target = batching ? this.#db(client, batching.executor, context, active, recorder) : usePlugins ? db : this.#db(client, base, context, [], recorder);
+			const target = batching ? this.#db(client, batching.executor, given, active, recorder, tuning) : usePlugins ? db : this.#db(client, base, given, NO_PLUGINS, recorder, tuning);
 			const results = await Promise.all(specs.map(async (spec) => {
 				try {
 					return await runSpec(target, spec, signal);
@@ -1200,8 +1726,9 @@ var BetterSupabase = class BetterSupabase {
 			const problems = checkParams(set, values);
 			if (problems.length > 0) return err(dbError("invalid_request", `db.$many(${set.name}): ${problems.join(", ")}`));
 			const keys = Object.keys(set.specs);
-			const bound = bindParams(set, values ?? {});
+			const { specs: bound, noCaller } = bindParams(set, values, context);
 			if (base.batch || !executor.rpc) {
+				if (noCaller) return err(noCaller);
 				const result = await many(keys.map((key) => bound[key]), signal, false);
 				if (!result.ok) return result;
 				return ok(Object.fromEntries(keys.map((key, i) => [key, result.data[i]])));
@@ -1231,24 +1758,28 @@ var BetterSupabase = class BetterSupabase {
 	*/
 	async #decodeReadSet(client, context, set, specs, data) {
 		const payload = data ?? {};
+		let rows = [];
+		let count = null;
+		const decoder = this.#db(client, {
+			name: "read-set",
+			execute: (op) => {
+				if (op.kind === "select" && op.single) {
+					if (rows.length > 1) return Promise.resolve(err(dbError("multiple_rows", `Expected one ${op.table.key} row`)));
+					if (rows.length === 0 && op.single === "one") return Promise.resolve(err(dbError("not_found", `No ${op.table.key} row matched`)));
+				}
+				return Promise.resolve(ok({
+					rows,
+					count
+				}));
+			}
+		}, context, NO_PLUGINS, new StatsRecorder(), {}, this.#decodeEvents ??= new EventHub(this.events.logger));
 		const out = {};
 		for (const [key, spec] of Object.entries(specs)) {
 			const entry = payload[key];
 			if (!entry) return err(dbError("unexpected", `${set.functionName}() returned no "${key}". Run \`better-supabase gen\` and migrate.`));
-			const rows = entry.rows ?? [];
-			const result = await runSpec(this.#db(client, {
-				name: "read-set",
-				execute: (op) => {
-					if (op.kind === "select" && op.single) {
-						if (rows.length > 1) return Promise.resolve(err(dbError("multiple_rows", `Expected one ${op.table.key} row`)));
-						if (rows.length === 0 && op.single === "one") return Promise.resolve(err(dbError("not_found", `No ${op.table.key} row matched`)));
-					}
-					return Promise.resolve(ok({
-						rows,
-						count: entry.count ?? null
-					}));
-				}
-			}, context, [], new StatsRecorder(), this.#decodeEvents ??= new EventHub(this.events.logger)), spec, void 0);
+			rows = entry.rows ?? [];
+			count = entry.count ?? null;
+			const result = await runSpec(decoder, spec, void 0);
 			if (!result.ok) return result;
 			out[key] = result.data;
 		}
@@ -1329,18 +1860,44 @@ function runSpec(db, spec, signal) {
 	}
 	return method(...args);
 }
-function rpc(executor, errorMappers, name, rest) {
+function rpc(meta, executor, errorMappers, defaults, name, rest) {
 	const [args, options] = rest;
 	return AsyncResult.from(async () => {
 		if (!executor.rpc) return err(dbError("invalid_request", `Executor "${executor.name}" does not support rpc()`));
+		const tuning = {
+			...defaults,
+			...options?.timeout === void 0 ? {} : { timeout: options.timeout },
+			...options?.retry === void 0 ? {} : { retry: options.retry }
+		};
+		const invalid = invalidTuning(tuning);
+		if (invalid) return err(dbError("invalid_request", invalid));
+		const limit = deadline(options?.signal, tuning.timeout);
+		const schema = options?.schema ?? "public";
+		const fn = rpcFunction(meta, name, schema, args ?? {});
 		const context = {
-			schema: options?.schema ?? "public",
+			schema,
 			errorMappers,
-			...options?.signal ? { signal: options.signal } : {}
+			...limit.signal ? { signal: limit.signal } : {},
+			...tuning.retry === void 0 ? {} : { retry: tuning.retry },
+			...fn ? { function: fn } : {}
 		};
-		const result = await executor.rpc(name, args ?? {}, context);
-		if (!result.ok || !options?.returns) return result;
-		const checked = await validate(options.returns, result.data, `${name}() result`);
+		let result;
+		try {
+			result = await executor.rpc(name, args ?? {}, context);
+		} finally {
+			limit.clear();
+		}
+		if (!result.ok && limit.timedOut()) return err(dbError("timeout", `The request timed out after ${tuning.timeout} ms`));
+		if (!result.ok) return result;
+		let data = result.data;
+		if (options?.raw !== true) try {
+			data = decodeRpcResult(meta, fn, data);
+		} catch (cause) {
+			if (cause instanceof DbException) return err(cause.error);
+			throw cause;
+		}
+		if (!options?.returns) return ok(data);
+		const checked = await validate(options.returns, data, `${name}() result`);
 		return checked.ok ? ok(checked.data) : checked;
 	});
 }