better-supabase 0.3.0 → 0.5.0

package/dist/{define-DF341GDj.js → define-cNKzqwL_.js}

@@ -1,15 +1,18 @@
-import { n as dbError, t as DbException } from "./errors-Bl3rkOzo.js";
-import { a as invalidRequest, c as needsDecoding, o as decodeRows, r as IrBuilder, s as encodeValue } from "./simplify-LakqK1vH.js";
-import { n as nowInstant } from "./temporal-BwshQk0W.js";
+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 { 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 { i as ok, n as err, o as toDbError, s as withErrorMapper, t as AsyncResult } from "./result-DWXatkd6.js";
-import { t as invalidationTargets } from "./tables-Dhha3BXM.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 { t as invalidationTargets } from "./tables-Cb-3_VWc.js";
 import { t as consoleLogger } from "./logger-glM28NVN.js";
-import { r as orderPlugins } from "./plugin-BqR6wKMB.js";
-import { a as postgrestExecutor, n as StatsRecorder, r as recordStats } from "./stats-D78UQ8Yu.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-D0qBcboM.js";
-import { a as toBase64Url, t as base64ToText } from "./base64-CQeB1eSf.js";
-import { t as validate } from "./standard-FUi3Z3-7.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 { a as toBase64Url, t as base64ToText } from "./base64-D2gsioCY.js";
+import { t as validate } from "./standard-D7r6dMUu.js";
 //#region src/core/batch.ts
 /**
 * Holds operations until each of `readers` has either submitted one or
@@ -60,8 +63,9 @@ function rowKey(table, row) {
 }
 function cacheTargetOf(meta, notice) {
 	const table = meta.tables[notice.table];
-	const ids = table ? [...new Set(notice.rows.flatMap((row) => rowKey(table, row) ?? []))] : [];
-	const tenant = notice.context.tenant;
+	const rows = notice.rows.length > 0 ? notice.rows : notice.keys ?? [];
+	const ids = table ? [...new Set(rows.flatMap((row) => rowKey(table, row) ?? []))] : [];
+	const tenant = notice.tenant ?? notice.context.tenant;
 	return {
 		table: notice.table,
 		tables: notice.kind === "delete" ? invalidationTargets(meta, notice.table) : [notice.table],
@@ -95,12 +99,19 @@ function memoryCache() {
 }
 //#endregion
 //#region src/core/events.ts
+/** More handlers than this for one event usually means a missing unsubscribe. */
+const HANDLER_WARNING = 50;
+function isDevelopment() {
+	return typeof process !== "undefined" && process.env["NODE_ENV"] !== "production";
+}
 /**
 * Observers only: a handler that throws is reported to the logger and never
 * changes a result.
 */
 var EventHub = class {
 	#handlers = /* @__PURE__ */ new Map();
+	#warned = /* @__PURE__ */ new Set();
+	#pending = /* @__PURE__ */ new Set();
 	logger;
 	constructor(logger = consoleLogger) {
 		this.logger = logger;
@@ -112,6 +123,10 @@ var EventHub = class {
 			this.#handlers.set(name, set);
 		}
 		set.add(handler);
+		if (set.size > HANDLER_WARNING && !this.#warned.has(name) && isDevelopment()) {
+			this.#warned.add(name);
+			this.logger.warn(`${set.size} "${name}" handlers are registered; call the function on() returns to remove one you no longer need`);
+		}
 		return () => {
 			set.delete(handler);
 		};
@@ -119,6 +134,24 @@ var EventHub = class {
 	has(name) {
 		return (this.#handlers.get(name)?.size ?? 0) > 0;
 	}
+	/**
+	* Keeps async work a handler started (a sink send) until it settles, so
+	* adapters can hand it to `after()` or `waitUntil`. Its outcome is ignored:
+	* handlers report their own failures.
+	*/
+	track(work) {
+		const settled = Promise.resolve(work).then(() => void 0, () => void 0);
+		this.#pending.add(settled);
+		settled.then(() => this.#pending.delete(settled));
+	}
+	/** Whether tracked work is still running. */
+	get pending() {
+		return this.#pending.size > 0;
+	}
+	/** Resolves once the work tracked so far has settled. Never rejects. */
+	async settled() {
+		await Promise.all(this.#pending);
+	}
 	emit(name, event) {
 		const set = this.#handlers.get(name);
 		if (!set) return;
@@ -130,6 +163,99 @@ var EventHub = class {
 	}
 };
 //#endregion
+//#region src/ir/codec.ts
+/** Whether decoding `selection` changes anything, so plain reads skip the walk. */
+function needsDecoding(selection) {
+	let needs = decodes.get(selection);
+	if (needs === void 0) {
+		needs = computeNeedsDecoding(selection);
+		decodes.set(selection, needs);
+	}
+	return needs;
+}
+const decodes = /* @__PURE__ */ new WeakMap();
+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) {
+	if (Array.isArray(value)) {
+		const first = value[0];
+		return Number(first?.count ?? 0);
+	}
+	return Number(value ?? 0);
+}
+function measureOf(measure, value) {
+	if (value === void 0 || value === null) return null;
+	return measure.codec ? decodeScalar(measure.codec, value) : value;
+}
+/** Adds `value` under `row[key][name]`, next to what is already there. */
+function fold(row, folded, key, name, value) {
+	let target = folded.get(key);
+	if (!target) {
+		target = { ...row[key] };
+		folded.set(key, target);
+		row[key] = target;
+	}
+	target[name] = value;
+}
+const droppedKeys = /* @__PURE__ */ new WeakMap();
+/** Wire keys that decoding folds into `_count`, `_sum` and the rest. */
+function droppedOf(selection) {
+	let dropped = droppedKeys.get(selection);
+	if (!dropped) {
+		dropped = /* @__PURE__ */ new Set([...selection.aggregate?.measures.map((measure) => measure.key) ?? [], ...selection.includes.filter((include) => include.count !== void 0 || include.aggregate !== void 0).map((include) => include.alias)]);
+		droppedKeys.set(selection, dropped);
+	}
+	return dropped;
+}
+function decodeRow(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];
+	const folded = /* @__PURE__ */ new Map();
+	for (const column of selection.columns) {
+		if (!column.codec || !(column.alias in out)) continue;
+		try {
+			out[column.alias] = decodeValue(column.codec, out[column.alias]);
+		} catch (cause) {
+			if (!(cause instanceof DbException) || cause.error.kind !== "invalid_value") throw cause;
+			throw new DbException(dbError("invalid_value", `${column.alias}: ${cause.error.message}`, { column: column.alias }));
+		}
+	}
+	if (selection.aggregate) {
+		if (selection.aggregate.count) out["_count"] = countOf(out["_count"]);
+		for (const measure of selection.aggregate.measures) {
+			const value = row[measure.key];
+			fold(out, folded, `_${measure.fn}`, measure.alias, measureOf(measure, value));
+		}
+	}
+	for (const include of selection.includes) {
+		const value = row[include.alias];
+		if (include.count !== void 0) {
+			if (!(include.alias in row)) continue;
+			fold(out, folded, "_count", include.count, countOf(value));
+			continue;
+		}
+		if (include.aggregate !== void 0) {
+			if (!(include.alias in row)) continue;
+			const inner = Array.isArray(value) ? value[0] : value;
+			const measures = {};
+			for (const measure of include.selection.aggregate?.measures ?? []) measures[measure.alias] = measureOf(measure, inner?.[measure.key]);
+			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);
+	}
+	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));
+}
+//#endregion
 //#region src/core/cursor.ts
 /** Opaque, URL-safe keyset cursor. */
 function encodeCursor(values) {
@@ -170,16 +296,69 @@ const KNOWN_KEYS = /* @__PURE__ */ new Set([
 	"_min",
 	"_max"
 ]);
+const NO_OPTIONS = Object.freeze({});
 function optionsOf(args) {
-	if (!args) return {};
-	const options = {};
-	for (const [key, value] of Object.entries(args)) if (!KNOWN_KEYS.has(key)) options[key] = value;
-	return options;
+	if (!args) return NO_OPTIONS;
+	let options;
+	for (const key in args) if (!KNOWN_KEYS.has(key) && Object.hasOwn(args, key)) (options ??= {})[key] = args[key];
+	return options ?? NO_OPTIONS;
+}
+const hooksByPlugins = /* @__PURE__ */ new WeakMap();
+function hooksOf(plugins) {
+	let hooks = hooksByPlugins.get(plugins);
+	if (!hooks) {
+		hooks = {
+			transformQuery: plugins.filter((plugin) => plugin.transformQuery),
+			beforeMutation: plugins.filter((plugin) => plugin.beforeMutation),
+			afterMutation: plugins.filter((plugin) => plugin.afterMutation)
+		};
+		hooksByPlugins.set(plugins, hooks);
+	}
+	return hooks;
+}
+function isThenable(value) {
+	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
 function signalOf(args) {
 	const signal = args?.["signal"];
 	return signal instanceof AbortSignal ? signal : void 0;
 }
+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;
@@ -187,8 +366,10 @@ function mutationKind(op) {
 /** Runs operations through plugins, the executor and the event hub. */
 var OperationRunner = class {
 	runtime;
+	#hooks;
 	constructor(runtime) {
 		this.runtime = runtime;
+		this.#hooks = hooksOf(runtime.plugins);
 	}
 	hookArgs(table, options) {
 		return {
@@ -201,20 +382,27 @@ var OperationRunner = class {
 	}
 	async run(op, options, signal) {
 		const { runtime } = this;
-		const hook = this.hookArgs(op.table, options);
+		const hooks = this.#hooks;
 		let current = op;
-		try {
-			for (const plugin of runtime.plugins) if (plugin.transformQuery) current = plugin.transformQuery(current, hook);
-			if (current.kind !== "select") {
-				let mutation = current;
-				for (const plugin of runtime.plugins) if (plugin.beforeMutation) mutation = await plugin.beforeMutation(mutation, hook);
-				current = mutation;
+		if (hooks.transformQuery.length > 0 || hooks.beforeMutation.length > 0) {
+			const hook = this.hookArgs(op.table, options);
+			try {
+				for (const plugin of hooks.transformQuery) current = plugin.transformQuery(current, hook);
+				if (current.kind !== "select") {
+					let mutation = current;
+					for (const plugin of hooks.beforeMutation) {
+						const next = plugin.beforeMutation(mutation, hook);
+						mutation = isThenable(next) ? await next : next;
+					}
+					current = mutation;
+				}
+			} catch (cause) {
+				if (cause instanceof DbException) return this.fail(op.table, cause.error);
+				throw cause;
 			}
-		} catch (cause) {
-			if (cause instanceof DbException) return this.fail(op.table, cause.error);
-			throw cause;
 		}
-		const started = performance.now();
+		const timed = runtime.events.has("query");
+		const started = timed ? performance.now() : 0;
 		const context = signal ? {
 			signal,
 			errorMappers: runtime.errorMappers
@@ -225,7 +413,7 @@ var OperationRunner = class {
 		if (executed.ok && selection && needsDecoding(selection)) try {
 			result = ok({
 				...executed.data,
-				rows: decodeRows(selection, executed.data.rows)
+				rows: decodeRows(selection, executed.data.rows, true)
 			});
 		} catch (cause) {
 			if (cause instanceof DbException) return this.fail(op.table, cause.error);
@@ -240,7 +428,7 @@ var OperationRunner = class {
 				maxRows: runtime.maxRows
 			});
 		}
-		if (runtime.events.has("query")) runtime.events.emit("query", {
+		if (timed) runtime.events.emit("query", {
 			table: op.table.key,
 			operation: current.kind,
 			ok: result.ok,
@@ -249,29 +437,40 @@ var OperationRunner = class {
 			truncated
 		});
 		if (!result.ok) return this.fail(op.table, result.error);
-		if (current.kind !== "select") await this.afterMutation(current, result.data);
+		if (current.kind !== "select") await this.afterMutation(op, current, result.data);
 		return result;
 	}
-	async afterMutation(op, data) {
+	async afterMutation(requested, op, data) {
 		const { runtime } = this;
+		const plugins = this.#hooks.afterMutation;
+		const listening = runtime.events.has("mutation");
+		if (plugins.length === 0 && !listening) return;
+		const kind = mutationKind(op);
+		const rows = cloneRows(data.rows);
+		const keys = keysOf(op, rows);
+		const tenant = tenantOf(runtime.context);
 		const event = {
 			table: op.table,
-			kind: mutationKind(op),
-			rows: data.rows,
+			kind,
+			intent: requested.kind === "delete" && op.kind === "update" ? "softDelete" : kind,
+			rows,
+			...keys ? { keys } : {},
+			...tenant === void 0 ? {} : { tenant },
 			context: runtime.context
 		};
-		for (const plugin of runtime.plugins) {
-			if (!plugin.afterMutation) continue;
-			try {
-				await plugin.afterMutation(event);
-			} catch (cause) {
-				runtime.events.logger.error(`plugin "${plugin.name}" afterMutation threw`, { cause });
-			}
+		for (const plugin of plugins) try {
+			const pending = plugin.afterMutation(event);
+			if (isThenable(pending)) await pending;
+		} catch (cause) {
+			runtime.events.logger.error(`plugin "${plugin.name}" afterMutation threw`, { cause });
 		}
-		runtime.events.emit("mutation", {
+		if (listening) runtime.events.emit("mutation", {
 			table: op.table.key,
 			kind: event.kind,
+			...event.intent ? { intent: event.intent } : {},
 			rows: event.rows,
+			...event.keys ? { keys: event.keys } : {},
+			...event.tenant === void 0 ? {} : { tenant: event.tenant },
 			context: event.context
 		});
 	}
@@ -280,16 +479,27 @@ var OperationRunner = class {
 			...error,
 			table: table.key
 		};
-		this.runtime.events.emit("error", {
+		if (this.runtime.events.has("error")) this.runtime.events.emit("error", {
 			table: table.key,
 			error: withTable
 		});
 		return err(withTable);
 	}
 };
+const sensitiveByTable = /* @__PURE__ */ new WeakMap();
+/** Database names of the table's `config.sensitive` columns. */
+function sensitiveColumnsOf(table) {
+	let sensitive = sensitiveByTable.get(table);
+	if (!sensitive) {
+		sensitive = new Set(lookupOf(table).entries.filter(([, column]) => column.sensitive).map(([, column]) => column.db));
+		sensitiveByTable.set(table, sensitive);
+	}
+	return sensitive;
+}
 /** Creates the runtime repository object for one table. */
 function createRepository(runner, table) {
 	const { builder } = runner.runtime;
+	const sensitiveDb = sensitiveColumnsOf(table);
 	const selection = (args) => builder.selection(table, args?.["select"], args?.["include"]);
 	const selectOp = (args, patch = {}) => ({
 		kind: "select",
@@ -304,21 +514,34 @@ function createRepository(runner, table) {
 		single: void 0,
 		...patch
 	});
-	const returning = (args) => args?.["returning"] === false ? void 0 : selection(args);
+	/** Writes return every column but the sensitive ones unless they are asked for. */
+	const returning = (args) => {
+		if (args?.["returning"] === false) return void 0;
+		const all = selection(args);
+		if (args?.["select"] !== void 0 || args?.["sensitive"] === true) return all;
+		const columns = all.columns.filter((entry) => !sensitiveDb.has(entry.column));
+		return columns.length === all.columns.length ? all : {
+			...all,
+			columns
+		};
+	};
 	const run = (op, args) => runner.run(op, optionsOf(args), signalOf(args));
+	let primaryOrder;
+	/** `primaryKey` holds app names; order terms take database names. */
+	const defaultOrder = () => primaryOrder ??= table.primaryKey.map((name) => ({
+		column: builder.column(table, name),
+		direction: "asc"
+	}));
 	const notFound = () => runner.fail(table, dbError("not_found", `No ${table.key} row matched`));
 	const base = {
-		$table: table.key,
+		$tableName: table.key,
 		$meta: table,
 		findMany(args) {
 			return AsyncResult.from(async () => {
 				const op = selectOp(args);
 				const ordered = op.orderBy.length > 0 || table.primaryKey.length === 0 ? op : {
 					...op,
-					orderBy: table.primaryKey.map((column) => ({
-						column,
-						direction: "asc"
-					}))
+					orderBy: defaultOrder()
 				};
 				const result = await run(ordered, args);
 				return result.ok ? ok(result.data.rows) : result;
@@ -538,8 +761,11 @@ function createRepository(runner, table) {
 		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"));
 		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,
 			count: count === "exact" || count === "planned" || count === "estimated" ? count : void 0
 		});
@@ -567,13 +793,15 @@ function createRepository(runner, table) {
 		if (typeof args["after"] === "string") {
 			const values = decodeCursor(args["after"]);
 			if (!values || values.length !== orderBy.length) return runner.fail(table, dbError("invalid_request", "Invalid cursor"));
-			after = keysetCondition(orderBy, values, (name) => Object.values(table.columns).find((meta) => meta.db === name)?.nullable ?? true);
+			const { byDb } = lookupOf(table);
+			after = keysetCondition(orderBy, values, (name) => byDb.get(name)?.[1].nullable ?? true);
 		}
 		const op = selectOp(args, {
 			selection: withSort,
 			where: and(builder.where(table, args["where"]), after),
 			orderBy,
 			limit: size + 1,
+			lookAhead: true,
 			offset: void 0
 		});
 		const result = await run(op, args);
@@ -581,7 +809,8 @@ function createRepository(runner, table) {
 		const rows = result.data.rows.slice(0, size);
 		const hasMore = result.data.rows.length > size;
 		const last = rows.at(-1);
-		const nextCursor = hasMore && last ? encodeCursor(orderBy.map((term) => encodeValue(last[aliasOf(withSort, term.column)]))) : null;
+		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;
 		return ok({
 			items: added.length > 0 ? rows.map((row) => strip(row, added)) : rows,
 			nextCursor,
@@ -601,14 +830,17 @@ function createRepository(runner, table) {
 	}
 	function ensureColumns(base, orderBy) {
 		const columns = [...base.columns];
+		const selected = new Set(columns.map((entry) => entry.column));
+		const { byDb } = lookupOf(table);
 		const added = [];
 		for (const term of orderBy) {
-			if (columns.some((entry) => entry.column === term.column)) continue;
-			const alias = Object.entries(table.columns).find(([, meta]) => meta.db === term.column)?.[0] ?? term.column;
+			if (selected.has(term.column)) continue;
+			const alias = byDb.get(term.column)?.[0] ?? term.column;
 			columns.push({
 				alias,
 				column: term.column
 			});
+			selected.add(term.column);
 			added.push(alias);
 		}
 		return {
@@ -621,12 +853,9 @@ function createRepository(runner, table) {
 	}
 	return base;
 }
-function aliasOf(selection, column) {
-	return selection.columns.find((entry) => entry.column === column)?.alias ?? column;
-}
 function strip(row, keys) {
-	const copy = { ...row };
-	for (const key of keys) delete copy[key];
+	const copy = {};
+	for (const key in row) if (!keys.includes(key) && Object.hasOwn(row, key)) copy[key] = row[key];
 	return copy;
 }
 /**
@@ -644,13 +873,21 @@ function byKey(rows, columns) {
 		const b = String(right);
 		return a < b ? -1 : a > b ? 1 : 0;
 	};
-	return [...rows].sort((left, right) => {
-		for (const column of columns) {
-			const order = compare(left[column], right[column]);
+	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);
 }
 /**
 * The rows after the cursor `values` in `orderBy` order, as an OR of ANDs:
@@ -716,7 +953,7 @@ var BetterSupabase = class BetterSupabase {
 	* A token that fails it resolves to `{ kind: 'invalid', reason: 'claims' }`.
 	*
 	* ```ts
-	* const sb = defineSupabase(schema).claims(z.object({ tenant_id: z.uuid() }));
+	* const betterSupabase = defineSupabase(schema).claims(z.object({ tenant_id: z.uuid() }));
 	* ```
 	*/
 	claims(schema) {
@@ -734,7 +971,7 @@ var BetterSupabase = class BetterSupabase {
 	* the verified claims, never from `profile`.
 	*
 	* ```ts
-	* const sb = defineSupabase(schema).userMetadata(z.object({ display_name: z.string() }));
+	* const betterSupabase = defineSupabase(schema).userMetadata(z.object({ display_name: z.string() }));
 	* ```
 	*/
 	userMetadata(schema) {
@@ -749,7 +986,7 @@ var BetterSupabase = class BetterSupabase {
 	* Results themselves keep their `DbError`.
 	*
 	* ```ts
-	* const sb = defineSupabase(schema).mapError((error) => new AppError(error));
+	* const betterSupabase = defineSupabase(schema).mapError((error) => new AppError(error));
 	* ```
 	*/
 	mapError(mapper) {
@@ -760,9 +997,14 @@ var BetterSupabase = class BetterSupabase {
 	}
 	#specs;
 	#truncatedTables = /* @__PURE__ */ new Set();
+	/** A hub without listeners, for decoding read-set results. */
+	#decodeEvents;
+	/** One getter per table, shared by every db this instance connects. */
+	#tables;
+	#errorMappers = /* @__PURE__ */ new WeakMap();
 	/**
 	* Builds serializable `QuerySpec`s with the same arguments and result types
-	* as the repository: `sb.spec.customers.findMany({ select: ['id'] })`.
+	* as the repository: `betterSupabase.spec.customers.findMany({ select: ['id'] })`.
 	*/
 	get spec() {
 		this.#specs ??= createSpecs(this.meta);
@@ -783,7 +1025,7 @@ var BetterSupabase = class BetterSupabase {
 	* invalidate them after it succeeds.
 	*
 	* ```ts
-	* sb.defineRpc('archive_customer', { invalidates: ['customers', 'notes'] });
+	* betterSupabase.defineRpc('archive_customer', { invalidates: ['customers', 'notes'] });
 	* ```
 	*/
 	defineRpc(name, options) {
@@ -842,10 +1084,10 @@ var BetterSupabase = class BetterSupabase {
 		let executor = base;
 		for (const plugin of plugins) if (plugin.wrapExecutor) executor = plugin.wrapExecutor(executor);
 		executor = recordStats(executor, recorder);
-		const errorMappers = [...this.options.errors ?? [], ...plugins.flatMap((plugin) => plugin.mapError ? [plugin.mapError] : [])];
+		const errorMappers = this.#errorMappersFor(plugins);
 		const runner = new OperationRunner({
 			meta: this.meta,
-			builder: new IrBuilder(this.meta),
+			builder: builderFor(this.meta),
 			executor,
 			plugins,
 			context,
@@ -855,7 +1097,13 @@ var BetterSupabase = class BetterSupabase {
 			maxRows: this.options.maxRows ?? 1e3,
 			truncatedTables: this.#truncatedTables
 		});
-		const db = {
+		const db = Object.create(this.#tablePrototype());
+		dbStates.set(db, {
+			runner,
+			plugins,
+			repositories: /* @__PURE__ */ new Map()
+		});
+		Object.assign(db, {
 			$client: client,
 			$executor: executor,
 			$context: context,
@@ -923,10 +1171,10 @@ var BetterSupabase = class BetterSupabase {
 					hint: `Add "${table.schema}.${table.name}" to vectorSearch in better-supabase.config.ts and run \`better-supabase sql sync\`.`
 				}) : result;
 			})
-		};
+		});
 		const many = (specs, signal, usePlugins) => AsyncResult.from(async () => {
 			const invalid = specs.findIndex((spec) => !isQuerySpec(spec));
-			if (invalid !== -1) return err(dbError("invalid_request", `db.$many() entry ${invalid} is not a QuerySpec from sb.spec`));
+			if (invalid !== -1) return err(dbError("invalid_request", `db.$many() entry ${invalid} is not a QuerySpec from betterSupabase.spec`));
 			const active = usePlugins ? plugins : [];
 			const batch = base.batch?.bind(base);
 			const batching = batch && specs.length > 1 ? batchingExecutor({
@@ -974,21 +1222,6 @@ var BetterSupabase = class BetterSupabase {
 			"$many",
 			"$search"
 		]) db[name] = mapThrows(db[name], throwAs);
-		for (const [key, table] of Object.entries(this.meta.tables)) {
-			let repository;
-			Object.defineProperty(db, key, {
-				enumerable: true,
-				get: () => {
-					if (!repository) {
-						repository = this.#repository(runner, key, table, plugins);
-						if (throwAs) {
-							for (const [name, method] of Object.entries(repository)) if (typeof method === "function" && name !== "extend") repository[name] = mapThrows(method, throwAs);
-						}
-					}
-					return repository;
-				}
-			});
-		}
 		return db;
 	}
 	/**
@@ -1015,12 +1248,45 @@ var BetterSupabase = class BetterSupabase {
 						count: entry.count ?? null
 					}));
 				}
-			}, context, [], new StatsRecorder(), new EventHub(this.events.logger)), spec, void 0);
+			}, context, [], new StatsRecorder(), this.#decodeEvents ??= new EventHub(this.events.logger)), spec, void 0);
 			if (!result.ok) return result;
 			out[key] = result.data;
 		}
 		return ok(out);
 	}
+	#errorMappersFor(plugins) {
+		let mappers = this.#errorMappers.get(plugins);
+		if (!mappers) {
+			mappers = [...this.options.errors ?? [], ...plugins.flatMap((plugin) => plugin.mapError ? [plugin.mapError] : [])];
+			this.#errorMappers.set(plugins, mappers);
+		}
+		return mappers;
+	}
+	#tablePrototype() {
+		if (this.#tables) return this.#tables;
+		const tables = {};
+		const throwAs = this.options.throwAs;
+		const build = (state, key) => {
+			let repository = state.repositories.get(key);
+			if (repository) return repository;
+			const table = this.meta.tables[key];
+			repository = this.#repository(state.runner, key, table, state.plugins);
+			if (throwAs) {
+				for (const [name, method] of Object.entries(repository)) if (typeof method === "function" && name !== "extend") repository[name] = mapThrows(method, throwAs);
+			}
+			state.repositories.set(key, repository);
+			return repository;
+		};
+		for (const key of Object.keys(this.meta.tables)) Object.defineProperty(tables, key, {
+			enumerable: true,
+			get() {
+				const state = dbStates.get(this);
+				return state ? build(state, key) : void 0;
+			}
+		});
+		this.#tables = tables;
+		return tables;
+	}
 	#repository(runner, key, table, plugins) {
 		const repository = createRepository(runner, table);
 		for (const plugin of plugins) {
@@ -1041,6 +1307,7 @@ var BetterSupabase = class BetterSupabase {
 		return repository;
 	}
 };
+const dbStates = /* @__PURE__ */ new WeakMap();
 function mapThrows(method, throwAs) {
 	return function(...args) {
 		const value = method.apply(this, args);
@@ -1048,7 +1315,7 @@ function mapThrows(method, throwAs) {
 	};
 }
 function runSpec(db, spec, signal) {
-	if (!isQuerySpec(spec)) return AsyncResult.err(dbError("invalid_request", "db.$run() expects a QuerySpec from sb.spec"));
+	if (!isQuerySpec(spec)) return AsyncResult.err(dbError("invalid_request", "db.$run() expects a QuerySpec from betterSupabase.spec"));
 	const method = db[spec.table]?.[spec.method];
 	if (!method) return AsyncResult.err(dbError("invalid_request", `Unknown table "${spec.table}" in QuerySpec`));
 	if (containsPlaceholder(spec.args)) return AsyncResult.err(dbError("invalid_request", "This spec comes from a read set and still holds placeholders; run it with db.$many(readSet, params)"));
@@ -1081,11 +1348,11 @@ function rpc(executor, errorMappers, name, rest) {
 * Creates the data-layer definition from the generated `schema`.
 *
 * ```ts
-* export const sb = defineSupabase(schema).use(timestamps()).use(softDelete());
+* export const betterSupabase = defineSupabase(schema).use(timestamps()).use(softDelete());
 * ```
 */
 function defineSupabase(schema, options) {
 	return new BetterSupabase(schema, [], options);
 }
 //#endregion
-export { EventHub as a, rowKey as c, encodeCursor as i, rpcCacheTargets as l, defineSupabase as n, cacheTargetOf as o, decodeCursor as r, memoryCache as s, BetterSupabase as t };
+export { decodeRows as a, memoryCache as c, encodeCursor as i, rowKey as l, defineSupabase as n, EventHub as o, decodeCursor as r, cacheTargetOf as s, BetterSupabase as t, rpcCacheTargets as u };