better-supabase 0.0.0 → 0.1.0

package/dist/define-QGkq04oe.js

@@ -0,0 +1,1068 @@
+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-oHiDKRVQ.js";
+import { i as or, 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-rZxRxNPW.js";
+import { r as orderPlugins } from "./plugin-BqR6wKMB.js";
+import { a as postgrestExecutor, n as StatsRecorder, r as recordStats } from "./stats-3iy8u3_P.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-DhX2d04c.js";
+import { t as validate } from "./standard-FUi3Z3-7.js";
+//#region src/core/batch.ts
+/**
+* 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.
+*/
+function batchingExecutor(base, readers) {
+	let running = readers;
+	const queue = [];
+	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) => {
+			items.forEach((item, index) => {
+				item.resolve(results[index] ?? err(toDbError(/* @__PURE__ */ new Error(`Executor "${base.name}" returned too few results`))));
+			});
+		}, (cause) => {
+			for (const item of items) item.resolve(err(toDbError(cause)));
+		});
+	};
+	return {
+		executor: {
+			name: base.name,
+			execute: (op, context) => new Promise((resolve) => {
+				queue.push({
+					op,
+					context,
+					resolve
+				});
+				flush();
+			}),
+			...base.rpc ? { rpc: base.rpc.bind(base) } : {}
+		},
+		done: () => {
+			running -= 1;
+			flush();
+		}
+	};
+}
+//#endregion
+//#region src/core/cache.ts
+/** Primary key of a row as a string, or `undefined` when it isn't returned. */
+function rowKey(table, row) {
+	if (table.primaryKey.length === 0) return void 0;
+	const parts = table.primaryKey.map((column) => row[column]);
+	if (parts.some((part) => part === void 0 || part === null)) return void 0;
+	return parts.map(String).join(",");
+}
+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;
+	return {
+		table: notice.table,
+		tables: notice.kind === "delete" ? invalidationTargets(meta, notice.table) : [notice.table],
+		ids,
+		...tenant === void 0 ? {} : { tenant }
+	};
+}
+/** One target per table an RPC changes; RPCs report no row ids. */
+function rpcCacheTargets(meta, notice) {
+	const tenant = notice.context.tenant;
+	return notice.invalidates.map((table) => ({
+		table,
+		tables: invalidationTargets(meta, table),
+		ids: [],
+		...tenant === void 0 ? {} : { tenant }
+	}));
+}
+/** Records invalidations. For tests and for checking what a mutation touches. */
+function memoryCache() {
+	const invalidated = [];
+	return {
+		name: "memory",
+		invalidated,
+		invalidate: (target) => {
+			invalidated.push(target);
+		},
+		clear: () => {
+			invalidated.length = 0;
+		}
+	};
+}
+//#endregion
+//#region src/core/logger.ts
+const log = (method) => (message, fields) => {
+	if (fields === void 0) console[method](`better-supabase: ${message}`);
+	else console[method](`better-supabase: ${message}`, fields);
+};
+/** The default: `console`, with a `better-supabase:` prefix. */
+const consoleLogger = {
+	debug: log("debug"),
+	info: log("info"),
+	warn: log("warn"),
+	error: log("error")
+};
+const noop = () => {};
+const silentLogger = {
+	debug: noop,
+	info: noop,
+	warn: noop,
+	error: noop
+};
+//#endregion
+//#region src/core/events.ts
+/**
+* Observers only: a handler that throws is reported to the logger and never
+* changes a result.
+*/
+var EventHub = class {
+	#handlers = /* @__PURE__ */ new Map();
+	logger;
+	constructor(logger = consoleLogger) {
+		this.logger = logger;
+	}
+	on(name, handler) {
+		let set = this.#handlers.get(name);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.#handlers.set(name, set);
+		}
+		set.add(handler);
+		return () => {
+			set.delete(handler);
+		};
+	}
+	has(name) {
+		return (this.#handlers.get(name)?.size ?? 0) > 0;
+	}
+	emit(name, event) {
+		const set = this.#handlers.get(name);
+		if (!set) return;
+		for (const handler of set) try {
+			handler(event);
+		} catch (cause) {
+			this.logger.error(`"${name}" handler threw`, { cause });
+		}
+	}
+};
+//#endregion
+//#region src/core/cursor.ts
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+	const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+/** Opaque, URL-safe keyset cursor. */
+function encodeCursor(values) {
+	return toBase64Url(encoder.encode(JSON.stringify(values)));
+}
+function decodeCursor(cursor) {
+	try {
+		const parsed = JSON.parse(decoder.decode(fromBase64Url(cursor)));
+		return Array.isArray(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/core/repository.ts
+const KNOWN_KEYS = /* @__PURE__ */ new Set([
+	"select",
+	"include",
+	"where",
+	"orderBy",
+	"limit",
+	"offset",
+	"signal",
+	"returning",
+	"expect",
+	"onConflict",
+	"ignoreDuplicates",
+	"page",
+	"size",
+	"count",
+	"after",
+	"mode",
+	"data",
+	"groupBy",
+	"_count",
+	"_sum",
+	"_avg",
+	"_min",
+	"_max"
+]);
+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;
+}
+function signalOf(args) {
+	const signal = args?.signal;
+	return signal instanceof AbortSignal ? signal : void 0;
+}
+function mutationKind(op) {
+	if (op.kind === "insert") return op.onConflict ? "upsert" : "insert";
+	return op.kind;
+}
+/** Runs operations through plugins, the executor and the event hub. */
+var OperationRunner = class {
+	runtime;
+	constructor(runtime) {
+		this.runtime = runtime;
+	}
+	hookArgs(table, options) {
+		return {
+			table,
+			schema: this.runtime.meta,
+			context: this.runtime.context,
+			options,
+			now: this.runtime.now
+		};
+	}
+	async run(op, options, signal) {
+		const { runtime } = this;
+		const hook = this.hookArgs(op.table, options);
+		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;
+			}
+		} catch (cause) {
+			if (cause instanceof DbException) return this.fail(op.table, cause.error);
+			throw cause;
+		}
+		const started = performance.now();
+		const context = signal ? {
+			signal,
+			errorMappers: runtime.errorMappers
+		} : { errorMappers: runtime.errorMappers };
+		const executed = await runtime.executor.execute(current, context);
+		const selection = current.kind === "select" ? current.selection : current.returning;
+		const result = executed.ok && selection && needsDecoding(selection) ? ok({
+			...executed.data,
+			rows: decodeRows(selection, executed.data.rows)
+		}) : executed;
+		const rows = result.ok ? result.data.rows.length : 0;
+		const truncated = current.kind === "select" && current.limit === void 0 && current.single === void 0 && !current.head && rows >= runtime.maxRows;
+		if (truncated && !runtime.truncatedTables.has(op.table.key)) {
+			runtime.truncatedTables.add(op.table.key);
+			runtime.events.logger.warn(`a read on ${op.table.key} returned ${rows} rows, the maxRows cap; add a limit or use paginate()`, {
+				table: op.table.key,
+				maxRows: runtime.maxRows
+			});
+		}
+		if (runtime.events.has("query")) runtime.events.emit("query", {
+			table: op.table.key,
+			operation: current.kind,
+			ok: result.ok,
+			durationMs: performance.now() - started,
+			rows,
+			truncated
+		});
+		if (!result.ok) return this.fail(op.table, result.error);
+		if (current.kind !== "select") await this.afterMutation(current, result.data);
+		return result;
+	}
+	async afterMutation(op, data) {
+		const { runtime } = this;
+		const event = {
+			table: op.table,
+			kind: mutationKind(op),
+			rows: data.rows,
+			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 });
+			}
+		}
+		runtime.events.emit("mutation", {
+			table: op.table.key,
+			kind: event.kind,
+			rows: event.rows,
+			context: event.context
+		});
+	}
+	fail(table, error) {
+		const withTable = error.table ? error : {
+			...error,
+			table: table.key
+		};
+		this.runtime.events.emit("error", {
+			table: table.key,
+			error: withTable
+		});
+		return err(withTable);
+	}
+};
+/** Creates the runtime repository object for one table. */
+function createRepository(runner, table) {
+	const { builder } = runner.runtime;
+	const selection = (args) => builder.selection(table, args?.select, args?.include);
+	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,
+		count: void 0,
+		head: false,
+		single: void 0,
+		...patch
+	});
+	const returning = (args) => args?.returning === false ? void 0 : selection(args);
+	const run = (op, args) => runner.run(op, optionsOf(args), signalOf(args));
+	const notFound = () => runner.fail(table, dbError("not_found", `No ${table.key} row matched`));
+	const base = {
+		$table: 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"
+					}))
+				};
+				const result = await run(ordered, args);
+				return result.ok ? ok(result.data.rows) : result;
+			});
+		},
+		findFirst(args) {
+			return AsyncResult.from(async () => {
+				const result = await run(selectOp(args, { limit: 1 }), args);
+				return result.ok ? ok(result.data.rows[0] ?? null) : result;
+			});
+		},
+		findUnique(args) {
+			return AsyncResult.from(async () => {
+				const op = selectOp(args, {
+					where: builder.uniqueKey(table, args.where),
+					limit: 1
+				});
+				const result = await run(op, args);
+				return result.ok ? ok(result.data.rows[0] ?? null) : result;
+			});
+		},
+		findById(id, args) {
+			return AsyncResult.from(async () => {
+				const op = selectOp(args, {
+					where: builder.primaryKey(table, id),
+					limit: 1
+				});
+				const result = await run(op, args);
+				if (!result.ok) return result;
+				const row = result.data.rows[0];
+				return row ? ok(row) : notFound();
+			});
+		},
+		count(args) {
+			return AsyncResult.from(async () => {
+				const mode = args?.mode;
+				const op = selectOp({ where: args?.where }, {
+					selection: {
+						columns: [],
+						includes: []
+					},
+					count: mode === "planned" || mode === "estimated" ? mode : "exact",
+					head: true
+				});
+				const result = await run(op, args);
+				return result.ok ? ok(result.data.count ?? 0) : result;
+			});
+		},
+		aggregate(args) {
+			return AsyncResult.from(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 op = selectOp({
+					where: args.where,
+					limit: args.limit,
+					offset: args.offset
+				}, {
+					selection: aggregation,
+					orderBy
+				});
+				const result = await run(op, args);
+				if (!result.ok) return result;
+				if (args.groupBy !== void 0) return ok(result.data.rows);
+				return ok(result.data.rows[0] ?? decodeRows(aggregation, [{}])[0] ?? {});
+			});
+		},
+		exists(args) {
+			return AsyncResult.from(async () => {
+				const columns = table.primaryKey.slice(0, 1).map((alias) => builder.selectColumn(table, alias));
+				const op = selectOp({ where: args?.where }, {
+					selection: {
+						columns,
+						includes: []
+					},
+					limit: 1
+				});
+				const result = await run(op, args);
+				return result.ok ? ok(result.data.rows.length > 0) : result;
+			});
+		},
+		paginate(args) {
+			return AsyncResult.from(async () => "after" in args ? cursorPage(args) : offsetPage(args));
+		},
+		create(data, args) {
+			return AsyncResult.from(async () => {
+				const op = insertOp([data], args, void 0);
+				const result = await run(op, args);
+				if (!result.ok) return result;
+				return ok(args?.returning === false ? null : result.data.rows[0] ?? null);
+			});
+		},
+		createMany(rows, args) {
+			return AsyncResult.from(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;
+				return ok(args?.returning === false ? { count: result.data.count ?? rows.length } : result.data.rows);
+			});
+		},
+		update(id, patch, args) {
+			return AsyncResult.from(async () => {
+				const key = builder.primaryKey(table, id);
+				const expect = args?.expect ? builder.where(table, args.expect) : void 0;
+				const op = {
+					kind: "update",
+					table,
+					set: builder.row(table, patch, "update"),
+					where: and(key, expect),
+					returning: returning(args)
+				};
+				const result = await run(op, args);
+				if (!result.ok) return result;
+				if ((op.returning ? result.data.rows.length : result.data.count ?? 0) === 0) {
+					if (!expect) return notFound();
+					const exists = await run(selectOp(void 0, {
+						where: key,
+						selection: {
+							columns: [],
+							includes: []
+						},
+						count: "exact",
+						head: true
+					}), args);
+					if (exists.ok && (exists.data.count ?? 0) > 0) return runner.fail(table, dbError("stale", `The ${table.key} row changed since it was read`));
+					return notFound();
+				}
+				return ok(op.returning ? result.data.rows[0] ?? null : null);
+			});
+		},
+		updateMany(args) {
+			return AsyncResult.from(async () => {
+				const op = {
+					kind: "update",
+					table,
+					set: builder.row(table, args.data, "update"),
+					where: builder.where(table, args.where),
+					returning: void 0
+				};
+				const result = await run(op, args);
+				return result.ok ? ok({ count: result.data.count ?? 0 }) : result;
+			});
+		},
+		upsert(data, args) {
+			return AsyncResult.from(async () => {
+				const op = insertOp([data], args, conflictColumns(args?.onConflict));
+				const result = await run(op, args);
+				if (!result.ok) return result;
+				return ok(args?.returning === false ? null : result.data.rows[0] ?? null);
+			});
+		},
+		upsertMany(rows, args) {
+			return AsyncResult.from(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);
+				if (!result.ok) return result;
+				return ok(args?.returning === false ? { count: result.data.count ?? rows.length } : result.data.rows);
+			});
+		},
+		delete(id, args) {
+			return AsyncResult.from(async () => {
+				const op = {
+					kind: "delete",
+					table,
+					where: builder.primaryKey(table, id),
+					returning: builder.selection(table, table.primaryKey, void 0)
+				};
+				const result = await run(op, args);
+				if (!result.ok) return result;
+				return (result.data.count ?? result.data.rows.length) === 0 ? notFound() : ok(void 0);
+			});
+		},
+		deleteMany(args) {
+			return AsyncResult.from(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({
+					kind: "delete",
+					table,
+					where,
+					returning: void 0
+				}, args);
+				return result.ok ? ok({ count: result.data.count ?? 0 }) : result;
+			});
+		}
+	};
+	function insertOp(rows, args, conflict) {
+		return {
+			kind: "insert",
+			table,
+			rows: rows.map((row) => builder.row(table, row)),
+			returning: returning(args),
+			onConflict: conflict ? {
+				columns: conflict,
+				action: args?.ignoreDuplicates === true ? "ignore" : "update"
+			} : void 0,
+			defaultToNull: false
+		};
+	}
+	function conflictColumns(target) {
+		if (target === void 0 || target === "primaryKey") return table.primaryKey.map((name) => builder.column(table, name));
+		if (typeof target === "string") {
+			const columns = table.uniqueKeys[target];
+			if (!columns) invalidRequest(`Unknown unique key "${target}" on "${table.key}"`, table.key);
+			return columns.map((name) => builder.column(table, name));
+		}
+		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) {
+		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 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 op = selectOp(args, {
+			limit: size + 1,
+			offset: (number - 1) * size,
+			count: count === "exact" || count === "planned" || count === "estimated" ? count : void 0
+		});
+		const result = await run(op, args);
+		if (!result.ok) return result;
+		const rows = result.data.rows;
+		const total = result.data.count;
+		return ok({
+			items: rows.slice(0, size),
+			page: {
+				number,
+				size,
+				total,
+				pages: total === null ? null : Math.max(1, Math.ceil(total / size)),
+				hasMore: rows.length > size
+			}
+		});
+	}
+	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 { selection: withSort, added } = ensureColumns(selection(args), orderBy);
+		let after;
+		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);
+		}
+		const op = selectOp(args, {
+			selection: withSort,
+			where: and(builder.where(table, args.where), after),
+			orderBy,
+			limit: size + 1,
+			offset: void 0
+		});
+		const result = await run(op, args);
+		if (!result.ok) return result;
+		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;
+		return ok({
+			items: added.length > 0 ? rows.map((row) => strip(row, added)) : rows,
+			nextCursor,
+			hasMore
+		});
+	}
+	function withTieBreaker(orderBy) {
+		const terms = [...orderBy];
+		for (const name of table.primaryKey) {
+			const column = builder.column(table, name);
+			if (!terms.some((term) => term.column === column)) terms.push({
+				column,
+				direction: terms[0]?.direction ?? "asc"
+			});
+		}
+		return terms;
+	}
+	function ensureColumns(base, orderBy) {
+		const columns = [...base.columns];
+		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;
+			columns.push({
+				alias,
+				column: term.column
+			});
+			added.push(alias);
+		}
+		return {
+			selection: {
+				columns,
+				includes: base.includes
+			},
+			added
+		};
+	}
+	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];
+	return copy;
+}
+/** `(a, b) > (x, y)` for mixed directions, as an OR of ANDs. */
+function keysetCondition(orderBy, values) {
+	const branches = orderBy.map((term, index) => {
+		const equal = orderBy.slice(0, index).map((prev, prevIndex) => ({
+			kind: "column",
+			column: prev.column,
+			op: "eq",
+			value: values[prevIndex]
+		}));
+		const step = {
+			kind: "column",
+			column: term.column,
+			op: term.direction === "asc" ? "gt" : "lt",
+			value: values[index]
+		};
+		return and(...equal, step) ?? step;
+	});
+	return or(...branches);
+}
+//#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(",")}]`;
+}
+//#endregion
+//#region src/core/define.ts
+function isExecutor(value) {
+	return typeof value === "object" && value !== null && typeof value.execute === "function" && typeof value.name === "string";
+}
+/**
+* The isomorphic definition of your data layer: schema plus plugins. Holds no
+* secrets and no connection; `connect()` binds it to a client per request.
+*/
+var BetterSupabase = class BetterSupabase {
+	schema;
+	plugins;
+	events;
+	options;
+	constructor(schema, plugins = [], options = {}, events = new EventHub(options.logger)) {
+		this.schema = schema;
+		this.plugins = orderPlugins(plugins);
+		this.options = options;
+		this.events = events;
+	}
+	get meta() {
+		return this.schema.meta;
+	}
+	/** The schema set by `claims()`; its output types `session.claims`. */
+	get claimsSchema() {
+		return this.options.claims;
+	}
+	/**
+	* Returns a new instance whose servers validate verified JWT claims (custom
+	* access token hook output) with `schema`, and whose sessions are typed by it.
+	* A token that fails it resolves to `{ kind: 'invalid', reason: 'claims' }`.
+	*
+	* ```ts
+	* const sb = defineSupabase(schema).claims(z.object({ tenant_id: z.uuid() }));
+	* ```
+	*/
+	claims(schema) {
+		return new BetterSupabase(this.schema, this.plugins, {
+			...this.options,
+			claims: schema
+		}, this.events);
+	}
+	/**
+	* Returns a new instance whose `.orThrow()` throws `mapper(error)` instead
+	* of a `DbException`, and whose results `toBetterResult` maps the same way.
+	* Results themselves keep their `DbError`.
+	*
+	* ```ts
+	* const sb = defineSupabase(schema).mapError((error) => new AppError(error));
+	* ```
+	*/
+	mapError(mapper) {
+		return new BetterSupabase(this.schema, this.plugins, {
+			...this.options,
+			throwAs: mapper
+		}, this.events);
+	}
+	#specs;
+	#truncatedTables = /* @__PURE__ */ new Set();
+	/**
+	* Builds serializable `QuerySpec`s with the same arguments and result types
+	* as the repository: `sb.spec.customers.findMany({ select: ['id'] })`.
+	*/
+	get spec() {
+		this.#specs ??= createSpecs(this.meta);
+		return this.#specs;
+	}
+	/** App keys of every table a spec reads; mutations of any of them make it stale. */
+	tablesOf(spec) {
+		return specTables(this.meta, spec);
+	}
+	/** 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);
+	}
+	/**
+	* Declares the tables an RPC writes, so cache adapters and live queries
+	* invalidate them after it succeeds.
+	*
+	* ```ts
+	* sb.defineRpc('archive_customer', { invalidates: ['customers', 'notes'] });
+	* ```
+	*/
+	defineRpc(name, options) {
+		for (const table of options.invalidates) if (!this.meta.tables[table]) throw new TypeError(`better-supabase: defineRpc("${name}") invalidates unknown table "${table}"`);
+		return new BetterSupabase(this.schema, this.plugins, {
+			...this.options,
+			rpc: {
+				...this.options.rpc,
+				[name]: options
+			}
+		}, this.events);
+	}
+	/** Observes queries, mutations, errors, auth and refreshes. */
+	on(name, handler) {
+		return this.events.on(name, handler);
+	}
+	/**
+	* Invalidates `adapter` after every mutation in this runtime. Returns a
+	* function that detaches it. Adapter failures are logged, never thrown.
+	*/
+	cache(adapter) {
+		const report = (cause, table) => {
+			this.events.logger.error(`cache adapter "${adapter.name}" failed`, {
+				cause,
+				table
+			});
+		};
+		const invalidate = (target) => {
+			try {
+				const pending = adapter.invalidate(target);
+				if (pending) pending.catch((cause) => report(cause, target.table));
+			} catch (cause) {
+				report(cause, target.table);
+			}
+		};
+		const offMutation = this.on("mutation", (notice) => {
+			invalidate(cacheTargetOf(this.meta, notice));
+		});
+		const offRpc = this.on("rpc", (notice) => {
+			for (const target of rpcCacheTargets(this.meta, notice)) invalidate(target);
+		});
+		return () => {
+			offMutation();
+			offRpc();
+		};
+	}
+	connect(source, context = {}, options = {}) {
+		const client = isExecutor(source) ? void 0 : source;
+		const base = options.executor ?? (isExecutor(source) ? source : postgrestExecutor(source));
+		const recorder = new StatsRecorder(options.stats);
+		return this.#db(client, base, context, this.plugins, recorder);
+	}
+	#db(client, base, context, plugins, recorder, events = this.events) {
+		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 runner = new OperationRunner({
+			meta: this.meta,
+			builder: new IrBuilder(this.meta),
+			executor,
+			plugins,
+			context,
+			events,
+			errorMappers,
+			now: this.options.now ?? (() => /* @__PURE__ */ new Date()),
+			maxRows: this.options.maxRows ?? 1e3,
+			truncatedTables: this.#truncatedTables
+		});
+		const db = {
+			$client: client,
+			$executor: executor,
+			$context: context,
+			$rpc: (name, ...rest) => rpc(executor, errorMappers, name, rest).map((data) => {
+				const registered = this.options.rpc?.[name];
+				if (registered) this.events.emit("rpc", {
+					name,
+					invalidates: registered.invalidates,
+					context
+				});
+				return data;
+			}),
+			$with: (extra) => this.#db(client, base, {
+				...context,
+				...extra
+			}, plugins, recorder),
+			$withoutPlugins: () => this.#db(client, base, context, [], recorder),
+			$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(", ")}`);
+				return db[name];
+			},
+			$run: (spec, options) => runSpec(db, spec, options?.signal),
+			$many: (target, ...rest) => {
+				if (isReadSet(target)) {
+					const [values, options] = rest;
+					return readSet(target, values, options?.signal);
+				}
+				const [options] = rest;
+				if (!Array.isArray(target)) return AsyncResult.err(dbError("invalid_request", "db.$many() expects an array of specs or a read set"));
+				return many(target, options?.signal, true);
+			},
+			$search: (name, args) => AsyncResult.from(async () => {
+				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 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 }));
+				const { builder } = runner.runtime;
+				const op = {
+					kind: "select",
+					table,
+					selection: builder.selection(table, args.select, args.include),
+					where: builder.where(table, args.where),
+					orderBy: [],
+					limit: k,
+					offset: void 0,
+					count: void 0,
+					head: false,
+					single: void 0,
+					source: {
+						schema: table.schema,
+						name: `search_${table.name}`,
+						args: {
+							query,
+							k
+						}
+					}
+				};
+				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;
+			})
+		};
+		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`));
+			const active = usePlugins ? plugins : [];
+			const batch = base.batch?.bind(base);
+			const batching = batch && specs.length > 1 ? batchingExecutor({
+				...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 results = await Promise.all(specs.map(async (spec) => {
+				try {
+					return await runSpec(target, spec, signal);
+				} finally {
+					batching?.done();
+				}
+			}));
+			const data = [];
+			for (const result of results) {
+				if (!result.ok) return result;
+				data.push(result.data);
+			}
+			return ok(data);
+		});
+		const readSet = (set, values, signal) => AsyncResult.from(async () => {
+			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 ?? {});
+			if (base.batch || !executor.rpc) {
+				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]])));
+			}
+			const called = await executor.rpc(set.functionName, { p: values ?? {} }, {
+				schema: "public",
+				get: true,
+				errorMappers,
+				...signal ? { signal } : {}
+			});
+			if (!called.ok) return called;
+			return this.#decodeReadSet(client, context, set, bound, called.data);
+		});
+		const throwAs = this.options.throwAs;
+		if (throwAs) for (const name of [
+			"$rpc",
+			"$run",
+			"$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;
+	}
+	/**
+	* Decodes what a read-set function returned (`{ [key]: { rows, count } }`)
+	* by running each spec against those rows, so casing, codecs and
+	* aggregates come out exactly as from `db.$run`.
+	*/
+	async #decodeReadSet(client, context, set, specs, data) {
+		const payload = data ?? {};
+		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: async (op) => {
+					if (op.kind === "select" && op.single) {
+						if (rows.length > 1) return err(dbError("multiple_rows", `Expected one ${op.table.key} row`));
+						if (rows.length === 0 && op.single === "one") return err(dbError("not_found", `No ${op.table.key} row matched`));
+					}
+					return ok({
+						rows,
+						count: entry.count ?? null
+					});
+				}
+			}, context, [], new StatsRecorder(), new EventHub(this.events.logger)), spec, void 0);
+			if (!result.ok) return result;
+			out[key] = result.data;
+		}
+		return ok(out);
+	}
+	#repository(runner, key, table, plugins) {
+		const repository = createRepository(runner, table);
+		for (const plugin of plugins) {
+			const methods = plugin.repository?.({
+				table,
+				base: repository
+			});
+			if (!methods) continue;
+			for (const [name, method] of Object.entries(methods)) {
+				if (name in repository) throw new TypeError(`better-supabase: plugin "${plugin.name}" redefines "${key}.${name}"`);
+				repository[name] = method;
+			}
+		}
+		repository.extend = (build) => ({
+			...repository,
+			...build(repository)
+		});
+		return repository;
+	}
+};
+function mapThrows(method, throwAs) {
+	return function(...args) {
+		const value = method.apply(this, args);
+		return value instanceof AsyncResult ? withErrorMapper(value, throwAs) : value;
+	};
+}
+function runSpec(db, spec, signal) {
+	if (!isQuerySpec(spec)) return AsyncResult.err(dbError("invalid_request", "db.$run() expects a QuerySpec from sb.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)"));
+	const args = [...spec.args];
+	if (signal) {
+		const index = spec.method === "findById" ? 1 : 0;
+		args[index] = {
+			...args[index],
+			signal
+		};
+	}
+	return method(...args);
+}
+function rpc(executor, errorMappers, 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 context = {
+			schema: options?.schema ?? "public",
+			errorMappers,
+			...options?.signal ? { signal: options.signal } : {}
+		};
+		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`);
+		return checked.ok ? ok(checked.data) : checked;
+	});
+}
+/**
+* Creates the data-layer definition from the generated `schema`.
+*
+* ```ts
+* export const sb = defineSupabase(schema).use(timestamps()).use(softDelete());
+* ```
+*/
+function defineSupabase(schema, options) {
+	return new BetterSupabase(schema, [], options);
+}
+//#endregion
+export { EventHub as a, cacheTargetOf as c, rpcCacheTargets as d, encodeCursor as i, memoryCache as l, defineSupabase as n, consoleLogger as o, decodeCursor as r, silentLogger as s, BetterSupabase as t, rowKey as u };