better-supabase 0.7.1 → 0.9.0

package/dist/timing-BMCWgpdZ.js

@@ -0,0 +1,92 @@
+import { defineMiddleware } from "@supabase/middleware";
+//#region src/server/entries/timing.ts
+/** The header `withDbStats` sets: `calls;waves;ms`, what `expectDbBudget` reads. */
+const DB_CALLS_HEADER = "x-bs-db-calls";
+/** `calls;waves;ms`, the value of the stats header. */
+function formatDbStats(stats) {
+	return `${stats.calls};${stats.waves};${stats.ms}`;
+}
+/** Parses the stats header back into numbers, or `undefined` when it is malformed. */
+function parseDbStats(value) {
+	if (!value) return;
+	const [calls, waves, ms] = value.split(";").map(Number);
+	if (calls === void 0 || waves === void 0 || ms === void 0 || [
+		calls,
+		waves,
+		ms
+	].some(Number.isNaN)) return;
+	return {
+		calls,
+		waves,
+		ms
+	};
+}
+function withHeaders(response, edit) {
+	const headers = new Headers(response.headers);
+	edit(headers);
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+}
+const TOKEN = /[^!#$%&'*+\-.^_`|~0-9A-Za-z]/g;
+function metric(name, dur, description) {
+	const desc = description === void 0 ? "" : `;desc="${description.replaceAll(/["\\]/g, "")}"`;
+	return `${name.replaceAll(TOKEN, "_")};dur=${dur.toFixed(1)}${desc}`;
+}
+/**
+* Entry contributing `ctx.timing`, and adding `Server-Timing` to the
+* response: `bs;dur=<ms>` for everything after it, plus the metrics handlers
+* add with `ctx.timing.add()` or `measure()`. Put it first, so it times the
+* whole request. Browsers show it in the network panel.
+*/
+function withServerTiming(now = () => performance.now()) {
+	return defineMiddleware({
+		key: "timing",
+		run: () => async function* run() {
+			const started = now();
+			const metrics = [];
+			const response = yield { timing: {
+				add: (name, dur, description) => {
+					metrics.push(metric(name, dur, description));
+				},
+				async measure(name, fn) {
+					const start = now();
+					try {
+						return await fn();
+					} finally {
+						metrics.push(metric(name, now() - start));
+					}
+				}
+			} };
+			const total = metric("bs", now() - started);
+			return withHeaders(response, (headers) => {
+				headers.append("server-timing", [total, ...metrics].join(", "));
+			});
+		}
+	})();
+}
+/**
+* Entry adding the request's database totals to the response, after the
+* handler ran: `x-bs-db-calls: calls;waves;ms`, which `expectDbBudget(response)`
+* reads, and a `bs-db` `Server-Timing` metric. Put it
+* after `withBetterSupabase`, which contributes `ctx.bs`.
+*/
+function withDbStats(options = {}) {
+	const header = options.header ?? "x-bs-db-calls";
+	return defineMiddleware({
+		key: "dbStats",
+		run: () => async function* run(_request, ctx) {
+			const dbStats = () => ctx.bs.stats();
+			const response = yield { dbStats };
+			const stats = dbStats();
+			return withHeaders(response, (headers) => {
+				headers.set(header, formatDbStats(stats));
+				headers.append("server-timing", metric("bs-db", stats.ms, `${stats.calls} calls, ${stats.waves} waves`));
+			});
+		}
+	})();
+}
+//#endregion
+export { withServerTiming as i, parseDbStats as n, withDbStats as r, DB_CALLS_HEADER as t };

package/dist/topic-ByDz9edV.js

@@ -0,0 +1,542 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-BlgnMB0H.js";
+import { a as tenantClaimPaths } from "./claims-PqzCxaTD.js";
+import { t as refreshRealtimeAuth } from "./auth-CdBKt0CS.js";
+import { a as sqlString, i as sqlIdent, n as parseTemplate, r as slug, t as claimSql } from "./template-DdgYjIZ5.js";
+import { t as allowedSubscribers } from "./subscribers-Cq--DL1E.js";
+import { t as joinTopic } from "./channels-C-GCoNLd.js";
+import { t as toApp } from "./casing-DdFWEtqr.js";
+import { a as isScopeName, i as fillTemplate, o as resolveProviderSql, r as accessCheck } from "./access-sql-DUSSMaC3.js";
+import { t as topicStatus } from "./realtime-status-D2dw1hOE.js";
+//#region src/realtime/fan-out.ts
+/** Runs the policy, then `send` for each subscriber it keeps, one at a time. */
+function fanOutTopic(fallback, options, send) {
+	return AsyncResult.from(async () => {
+		const policy = options.policy ?? fallback ?? options.server?.authorization?.delivery?.subscribers;
+		if (policy === void 0 && options.server?.authorization !== void 0 && typeof options.source.subject === "string") return err(dbError("forbidden", "An event with a subject needs a subscriber policy under an authorization provider, such as subjectReaders(transport)", { hint: "REALTIME_SUBSCRIBER_POLICY_REQUIRED" }));
+		const checked = await allowedSubscribers(policy, options.source, options.subscribers);
+		if (!checked.ok) return err(dbError("forbidden", "The subscriber policy failed, so the event went to no one", { hint: "REALTIME_SUBSCRIBER_POLICY_FAILED" }));
+		const allowed = new Set(checked.allowed);
+		const sent = [];
+		const failed = [];
+		for (const subscriber of checked.allowed) {
+			const result = await send(subscriber);
+			if (result.ok) sent.push(subscriber);
+			else failed.push({
+				subscriber,
+				error: result.error
+			});
+		}
+		return ok({
+			sent,
+			skipped: options.subscribers.filter((subscriber) => !allowed.has(subscriber)),
+			failed
+		});
+	});
+}
+//#endregion
+//#region src/realtime/topic-sql.ts
+const segmentSql = (index) => `split_part((select realtime.topic()), ':', ${String(index)})`;
+/**
+* The receive condition for a topic's instance permission. With the
+* provider's `permitted` template it asks about the instance in the topic
+* (`{permission}`, `{id}` and `{tenant}` as text, `{resource}` as a text
+* literal, `{scope}` unquoted). Without one it falls back to the access
+* contract's tenant check, `tenant_ids_with(permission)` on the tenant
+* segment, and a topic without a tenant segment is refused.
+*/
+function topicPermissionSql(input) {
+	const { where, key, tenantSegment } = input;
+	const tenant = tenantSegment === void 0 ? void 0 : segmentSql(tenantSegment);
+	if (input.permitted !== void 0) {
+		if (!isScopeName(input.scope)) throw new TypeError(`${where}: invalid permission scope "${input.scope}"`);
+		return `coalesce((${fillTemplate(`${where} authorization.functions.permitted`, input.permitted, {
+			permission: sqlString(key),
+			id: segmentSql(input.idSegment),
+			tenant: tenant ?? "null::text",
+			resource: sqlString(input.resource),
+			scope: input.scope
+		})}), false)`;
+	}
+	if (tenant === void 0) throw new TypeError(`${where}: permission "${key}" needs the authorization provider's \`permitted\` template, or a tenant segment for the tenant check`);
+	return accessCheck(where, {}, key, tenant);
+}
+function columnSql(meta, column, where) {
+	const db = meta.columns[column]?.db;
+	if (!db) throw new TypeError(`defineTopic: no column for ${where} on "${meta.key}" ("${column}")`);
+	return sqlIdent(db);
+}
+/** A trigger value as SQL on `rec`, with one subquery per lookup. */
+function triggerValueSql(tables, meta, value, where, depth = 0) {
+	if (typeof value === "string") return `rec.${columnSql(meta, value, where)}`;
+	const joined = tables[value.from];
+	if (!joined) throw new TypeError(`defineTopic: unknown table "${value.from}" for ${where}`);
+	const key = value.key ?? (joined.primaryKey.length === 1 ? joined.primaryKey[0] : void 0);
+	if (key === void 0) throw new TypeError(`defineTopic: "${value.from}" has no single-column primary key; name its key for ${where}`);
+	const alias = `j${String(depth)}`;
+	const via = triggerValueSql(tables, meta, value.via, where, depth + 1);
+	return `(select ${alias}.${columnSql(joined, value.select, where)} from ${sqlIdent(joined.schema)}.${sqlIdent(joined.name)} ${alias} where ${alias}.${columnSql(joined, key, where)} = ${via} limit 1)`;
+}
+/** The event name: one for every operation, one per operation, or the operation. */
+function eventSql(event) {
+	if (event === void 0) return "tg_op";
+	if (typeof event === "string") return sqlString(event);
+	const cases = Object.entries(event).filter((entry) => entry[1] !== void 0).map(([operation, name]) => ` when ${sqlString(operation.toUpperCase())} then ${sqlString(name)}`);
+	return cases.length === 0 ? "tg_op" : `case tg_op${cases.join("")} else tg_op end`;
+}
+//#endregion
+//#region src/realtime/topic-trigger.ts
+/** Marks a generated function that sends whole rows on purpose (doctor reads it). */
+const ROW_PAYLOAD_MARKER = "better-supabase: payload row";
+/** The primary key as `jsonb`, read from the catalog when the table's key isn't known. */
+const CATALOG_ID_SQL = "(select case when count(*) = 1 then (array_agg(r.j -> a.attname::text))[1] else jsonb_object_agg(a.attname, r.j -> a.attname::text) end from pg_catalog.pg_index i join pg_catalog.pg_attribute a on a.attrelid = i.indrelid and a.attnum = any(i.indkey::int2[]) cross join (select to_jsonb(rec) as j) as r where i.indrelid = tg_relid and i.indisprimary)";
+/** The primary key as `jsonb` from known database columns. */
+function idSql(columns) {
+	if (columns.length === 0) return "null::jsonb";
+	if (columns.length === 1) return `to_jsonb(rec.${sqlIdent(columns[0] ?? "")})`;
+	return `jsonb_build_object(${columns.map((column) => `${sqlString(column)}, rec.${sqlIdent(column)}`).join(", ")})`;
+}
+function topicSql(template) {
+	return template.split(/(\{[^}]+\})/).filter(Boolean).map((part) => {
+		const param = /^\{(.+)\}$/.exec(part)?.[1];
+		return param === void 0 ? sqlString(part) : `(vals ->> ${sqlString(param)})`;
+	}).join(" || ");
+}
+function payloadSql(payload) {
+	switch (payload.kind) {
+		case "keys": return `jsonb_build_object('operation', tg_op, 'schema', tg_table_schema, 'table', tg_table_name, 'id', ${payload.id}, 'values', vals)`;
+		case "row": return "jsonb_build_object('old_record', old, 'record', new, 'operation', tg_op, 'table', tg_table_name, 'schema', tg_table_schema)";
+		case "custom": return payload.sql;
+		default: throw new TypeError(`unknown payload ${String(payload)}`);
+	}
+}
+/**
+* A function and row trigger that send one row change to each topic. A
+* topic with a null value is skipped; one with a value topics don't allow
+* is skipped with a warning, so the write still commits.
+*/
+function triggerFunctionSql(input) {
+	const fn = `${sqlIdent(input.functionSchema)}.${sqlIdent(input.functionName)}`;
+	const payload = payloadSql(input.payload);
+	const sends = input.topics.flatMap((topic) => {
+		const entries = Object.entries(topic.values);
+		const vals = entries.length === 0 ? "'{}'::jsonb" : `jsonb_build_object(${entries.map(([param, value]) => `${sqlString(param)}, (${value})::text`).join(", ")})`;
+		return [
+			`  -- ${topic.template}`,
+			`  vals := ${vals};`,
+			"  select e.key, e.value into bad from jsonb_each_text(vals) as e",
+			"    where e.value is null or e.value !~ '^[\\w.@+=-]+$'",
+			"    order by e.value is null desc limit 1;",
+			"  if not found then",
+			`    perform realtime.send(${payload}, ${input.event}, ${topicSql(topic.template)}, ${String(topic.private)});`,
+			"  elsif bad.value is not null then",
+			`    raise warning 'skipped the broadcast on %: topic value % of %.%.% contains characters topics do not allow', ${sqlString(topic.template)}, bad.value, tg_table_schema, tg_table_name, bad.key;`,
+			"  end if;"
+		];
+	});
+	return [
+		`-- better-supabase: broadcast ${input.subject} changes to ${input.topics.map((topic) => topic.template).join(", ")}`,
+		`create schema if not exists ${sqlIdent(input.functionSchema)};`,
+		`create or replace function ${fn}()`,
+		"returns trigger",
+		"language plpgsql",
+		"security definer",
+		"set search_path = ''",
+		"as $$",
+		"declare",
+		"  rec record;",
+		"  vals jsonb;",
+		"  bad record;",
+		"begin",
+		"  if tg_when <> 'AFTER' then",
+		"    raise exception '% runs after the write; as a % trigger it would cancel the write', tg_name, lower(tg_when)",
+		"      using errcode = '39P01';",
+		"  end if;",
+		"  if tg_op = 'DELETE' then rec := old; else rec := new; end if;",
+		...sends,
+		"  return null;",
+		"end;",
+		"$$;",
+		`revoke execute on function ${fn}() from public, anon, authenticated;`,
+		...input.payload.kind === "row" ? [`comment on function ${fn}() is ${sqlString(ROW_PAYLOAD_MARKER)};`] : [],
+		"",
+		`drop trigger if exists ${sqlIdent(input.triggerName)} on ${input.target};`,
+		`create trigger ${sqlIdent(input.triggerName)} after ${input.events} on ${input.target}`,
+		`  for each row execute function ${fn}();`,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/realtime/topic.ts
+const splitTable = (table) => table.includes(".") ? [table.slice(0, table.indexOf(".")), table.slice(table.indexOf(".") + 1)] : ["public", table];
+const VALUE = /^[\w.@+=-]+$/;
+const snakeCase = (name) => name.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+function validateValue(_name, value) {
+	return VALUE.test(value) ? void 0 : "contains characters topics do not allow";
+}
+async function validate(schema, value) {
+	if (!schema) return {
+		ok: true,
+		value
+	};
+	const result = await schema["~standard"].validate(value);
+	if (result.issues) return {
+		ok: false,
+		issues: result.issues.map((issue) => ({
+			message: issue.message,
+			...issue.path ? { path: issue.path.map((part) => typeof part === "object" ? part.key : part) } : {}
+		}))
+	};
+	return {
+		ok: true,
+		value: result.value
+	};
+}
+function sendError(status, message) {
+	if (status === 401) return dbError("unauthorized", message);
+	if (status === 403) return dbError("forbidden", message);
+	if (status === 429 || status >= 500 || status === 0) return dbError("network", message, status ? { status } : {});
+	return dbError("invalid_request", message, { status });
+}
+/**
+* A typed Realtime broadcast topic: names from a template, RLS policies for
+* private channels, row-change triggers, and disposable subscriptions.
+*
+* ```ts
+* export const notifications = defineTopic('organization:{organizationId}:notifications:{userId}', {
+*   events: { created: v.object({ id: v.string(), title: v.string() }) },
+* });
+* using sub = notifications.subscribe(supabase, { organizationId, userId }, { created: (n) => toast(n.title) });
+* ```
+*/
+function defineTopic(template, options = {}) {
+	const parsed = parseTemplate(template, ":", validateValue);
+	const literal = template.replaceAll(/\{[^}]+\}/g, " ");
+	const name = slug(options.name ?? literal) || "topic";
+	const isPrivate = options.private ?? true;
+	const schemas = options.events ?? {};
+	const hasPresence = options.presence !== void 0 && options.presence !== false;
+	const presenceSchema = typeof options.presence === "object" ? options.presence : void 0;
+	const segment = (param, kind) => {
+		const index = parsed.segmentOf(param);
+		if (index === void 0) throw new TypeError(`defineTopic: the ${kind} check needs {${param}} as a whole segment in "${template}"`);
+		return index;
+	};
+	const checks = [];
+	const access = options.access;
+	const tenantParam = options.tenant === false ? void 0 : options.tenant?.param ?? "organizationId";
+	const accessChecksFor = (functions) => {
+		if (!access) return;
+		const where = `defineTopic(${template})`;
+		const target = resolveProviderSql(where, access, functions);
+		const id = access.scope === "platform" ? void 0 : `split_part((select realtime.topic()), ':', ${String(access.segment ?? segment(tenantParam ?? "organizationId", "access"))})`;
+		const receive = accessCheck(where, target, access.receive, id);
+		return {
+			receive,
+			send: access.send === void 0 ? receive : accessCheck(where, target, access.send, id)
+		};
+	};
+	const fixedChecks = access?.sql === "provider" ? void 0 : accessChecksFor();
+	if (!access && tenantParam && (options.tenant || parsed.params.includes(tenantParam))) {
+		const tenant = options.tenant === false ? {} : options.tenant ?? {};
+		const expression = tenant.sql ?? claimSql(tenant.claim ?? tenantClaimPaths());
+		checks.push(`split_part((select realtime.topic()), ':', ${String(segment(tenantParam, "tenant"))}) = (${expression})`);
+	}
+	const ownerParam = options.owner === false ? void 0 : options.owner?.param ?? "userId";
+	if (ownerParam && (options.owner || parsed.params.includes(ownerParam))) checks.push(`split_part((select realtime.topic()), ':', ${String(segment(ownerParam, "owner"))}) = (select auth.uid())::text`);
+	const permission = typeof options.permission === "string" ? { key: options.permission } : options.permission;
+	const permissionTarget = (() => {
+		if (permission === void 0) return;
+		const key = permission.key;
+		if (key === "") throw new TypeError(`defineTopic(${template}): the permission is empty`);
+		const param = permission.param ?? parsed.params.at(-1);
+		if (param === void 0) throw new TypeError(`defineTopic(${template}): permission "${key}" needs a placeholder for the instance id`);
+		return {
+			key,
+			idSegment: segment(param, "permission"),
+			tenantSegment: tenantParam === void 0 ? void 0 : parsed.segmentOf(tenantParam),
+			resource: permission.resource ?? key.split(".")[0] ?? key,
+			scope: permission.scope ?? "tenant"
+		};
+	})();
+	const topicOf = (values) => parsed.build(values);
+	const triggerStatement = (table, trigger) => {
+		const where = `defineTopic(${template}).trigger`;
+		const tables = trigger.betterSupabase?.meta.tables;
+		const meta = tables?.[table];
+		if (tables && !meta) throw new TypeError(`defineTopic: unknown table "${table}"`);
+		const [schema, relation] = meta ? [meta.schema, meta.name] : splitTable(table);
+		const target = `${sqlIdent(schema)}.${sqlIdent(relation)}`;
+		const triggerName = `bs_broadcast_${name}`;
+		const extra = trigger.topics ?? [];
+		const { payload } = trigger;
+		const events = (trigger.events ?? [
+			"insert",
+			"update",
+			"delete"
+		]).join(" or ");
+		const checkKeys = (params, given, topic) => {
+			for (const key of Object.keys(given ?? {})) if (!params.includes(key)) throw new TypeError(`${where}: "${key}" is not a placeholder of ${topic}`);
+		};
+		checkKeys(parsed.params, trigger.values, template);
+		if (!meta && extra.length === 0 && typeof trigger.event !== "object" && (payload === void 0 || typeof payload === "string")) {
+			const columns = trigger.values ?? {};
+			const sqlTemplate = template.replaceAll(/\{([^}]+)\}/g, (_, param) => {
+				const column = columns[param] ?? snakeCase(param);
+				if (typeof column !== "string") throw new TypeError(`${where}: a lookup for {${param}} needs betterSupabase`);
+				if (/[{}=]/.test(column)) throw new TypeError(`${where}: the column for {${param}} can't contain braces or =`);
+				return column === param ? `{${param}}` : `{${param}=${column}}`;
+			});
+			const args = [sqlString(sqlTemplate), sqlString(trigger.event ?? "")];
+			if (!isPrivate || payload === "row") args.push(sqlString(isPrivate ? "" : "false"));
+			if (payload === "row") args.push(sqlString("row"));
+			return [
+				`-- better-supabase: broadcast ${schema}.${relation} changes to ${template}`,
+				`drop trigger if exists ${sqlIdent(triggerName)} on ${target};`,
+				`create trigger ${sqlIdent(triggerName)} after ${events} on ${target}`,
+				`  for each row execute function better_supabase.broadcast_topic(${args.join(", ")});`,
+				""
+			].join("\n");
+		}
+		const valueSql = (value, label) => {
+			if (tables && meta) return triggerValueSql(tables, meta, value, label);
+			if (typeof value !== "string") throw new TypeError(`${where}: a lookup for ${label} needs betterSupabase`);
+			return `rec.${sqlIdent(value)}`;
+		};
+		const topicValues = (params, given, topic) => Object.fromEntries(params.map((param) => {
+			const value = given?.[param] ?? (meta ? void 0 : snakeCase(param));
+			if (value === void 0) throw new TypeError(`defineTopic: no column for {${param}} of ${topic} on "${table}"`);
+			return [param, valueSql(value, `{${param}}`)];
+		}));
+		const topics = [{
+			template,
+			private: isPrivate,
+			values: topicValues(parsed.params, trigger.values, template)
+		}, ...extra.map((each) => {
+			checkKeys(each.topic.params, each.values, each.topic.template);
+			return {
+				template: each.topic.template,
+				private: each.topic.private,
+				values: topicValues(each.topic.params, each.values, each.topic.template)
+			};
+		})];
+		const payloadSql = payload === void 0 || payload === "keys" ? {
+			kind: "keys",
+			id: meta ? idSql(meta.primaryKey.map((key) => meta.columns[key]?.db ?? key)) : CATALOG_ID_SQL
+		} : payload === "row" ? { kind: "row" } : {
+			kind: "custom",
+			sql: `jsonb_build_object(${Object.entries(payload).map(([key, value]) => `${sqlString(key)}, ${typeof value === "object" && "sql" in value ? `(${value.sql.replaceAll("{row}", "rec")})` : valueSql(value, `payload.${key}`)}`).join(", ")})`
+		};
+		return triggerFunctionSql({
+			subject: meta ? meta.name : `${schema}.${relation}`,
+			functionSchema: trigger.functionSchema ?? "better_supabase",
+			functionName: `bs_broadcast_${name}_${slug(schema)}_${slug(relation)}`,
+			triggerName,
+			target,
+			events,
+			event: eventSql(trigger.event),
+			topics,
+			payload: payloadSql
+		});
+	};
+	const api = {
+		template,
+		name,
+		params: parsed.params,
+		private: isPrivate,
+		presence: hasPresence,
+		presenceSchema,
+		events: schemas,
+		clientSend: options.send ?? false,
+		permission: permission?.key,
+		status: topicStatus({ private: isPrivate }),
+		topic: topicOf,
+		match: (topic) => parsed.match(topic),
+		sql(sqlOptions) {
+			const accessChecks = access?.sql === "provider" ? accessChecksFor(sqlOptions?.functions) : fixedChecks;
+			const extensions = hasPresence ? "('broadcast', 'presence')" : "('broadcast')";
+			const permissionCheck = permissionTarget === void 0 ? void 0 : topicPermissionSql({
+				where: `defineTopic(${template})`,
+				...permissionTarget,
+				permitted: sqlOptions?.functions?.permitted
+			});
+			const condition = (extra) => [
+				`(select realtime.topic()) ~ ${sqlString(parsed.sqlPattern)}`,
+				`realtime.messages.extension in ${extensions}`,
+				...checks,
+				...extra === void 0 ? [] : [extra],
+				...permissionCheck === void 0 ? [] : [permissionCheck]
+			].join("\n    and ");
+			const lines = [`-- better-supabase: topic ${template}`];
+			const policies = [[
+				"receive",
+				"select",
+				"using",
+				condition(accessChecks?.receive)
+			]];
+			if (options.send || hasPresence || access?.send !== void 0) policies.push([
+				"send",
+				"insert",
+				"with check",
+				condition(accessChecks?.send)
+			]);
+			for (const [suffix, command, clause, check] of policies) {
+				const policy = sqlIdent(`bs_topic_${name}_${suffix}`);
+				lines.push(`drop policy if exists ${policy} on realtime.messages;`, `create policy ${policy} on realtime.messages for ${command} to authenticated\n  ${clause} (\n    ${check}\n  );`);
+			}
+			return `${lines.join("\n")}\n`;
+		},
+		triggerSql(betterSupabase, table, trigger) {
+			return triggerStatement(table, {
+				...trigger,
+				betterSupabase
+			});
+		},
+		trigger(table, trigger) {
+			return triggerStatement(table, trigger ?? {});
+		},
+		subscribe(client, values, handlers, given) {
+			const topic = topicOf(values);
+			const table = handlers;
+			const subscribeOptions = given ?? {};
+			let members = [];
+			let syncs = 0;
+			const sync = async (state) => {
+				const run = ++syncs;
+				const checked = await Promise.all(Object.entries(state).flatMap(([key, metas]) => metas.map(async ({ presence_ref: _ref, ...meta }) => ({
+					key,
+					meta,
+					checked: await validate(presenceSchema, meta)
+				}))));
+				if (run !== syncs) return;
+				const valid = [];
+				for (const each of checked) if (each.checked.ok) valid.push({
+					key: each.key,
+					state: each.checked.value
+				});
+				else subscribeOptions.onInvalid?.({
+					event: "presence",
+					payload: each.meta,
+					topic
+				}, each.checked.issues);
+				members = valid;
+				subscribeOptions.onPresence?.(valid);
+			};
+			const subscriber = {
+				onStatus: subscribeOptions.onStatus,
+				receive: (message) => {
+					const handler = table[message.event] ?? table["*"];
+					if (!handler) return;
+					validate(schemas[message.event], message.payload).then((checked) => {
+						if (checked.ok) handler(checked.value, message);
+						else subscribeOptions.onInvalid?.(message, checked.issues);
+					});
+				},
+				...hasPresence ? { sync: (state) => void sync(state) } : {}
+			};
+			const { shared, leave } = joinTopic(client, topic, isPrivate, subscribeOptions.self ?? false, hasPresence, subscriber);
+			let closed = false;
+			const unsubscribe = async () => {
+				if (closed) return;
+				closed = true;
+				await leave();
+			};
+			const presenceCall = (action, run) => AsyncResult.from(async () => {
+				if (closed) return err(dbError("invalid_request", `Presence ${action} after unsubscribe on ${topic}`));
+				try {
+					await shared.ready;
+				} catch (cause) {
+					return err(dbError("network", `Presence ${action} on ${topic}: the join failed`, { details: cause instanceof Error ? cause.message : String(cause) }));
+				}
+				const answer = await run();
+				return answer === "ok" ? ok(void 0) : err(dbError("network", `Presence ${action} ${answer} on ${topic}`));
+			});
+			const subscription = {
+				topic,
+				channel: shared.channel,
+				ready: shared.ready,
+				unsubscribe,
+				[Symbol.dispose]: () => void unsubscribe(),
+				[Symbol.asyncDispose]: unsubscribe
+			};
+			return hasPresence ? {
+				...subscription,
+				track: (state) => AsyncResult.from(async () => {
+					const checked = await validate(presenceSchema, state);
+					if (!checked.ok) return err(dbError("validation", `Invalid presence state for ${topic}`, { issues: checked.issues }));
+					return presenceCall("track", async () => {
+						shared.tracker = subscriber;
+						return shared.channel.track(checked.value);
+					});
+				}),
+				untrack: () => presenceCall("untrack", async () => {
+					if (shared.tracker === subscriber) shared.tracker = void 0;
+					return shared.channel.untrack();
+				}),
+				members: () => members
+			} : subscription;
+		},
+		send(client, values, event, payload) {
+			return AsyncResult.from(async () => {
+				const topic = topicOf(values);
+				const checked = await validate(schemas[event], payload);
+				if (!checked.ok) return err(dbError("validation", `Invalid payload for ${event}`, { issues: checked.issues }));
+				const open = client.getChannels().some((existing) => existing.topic === `realtime:${topic}`);
+				if (isPrivate && !open) await refreshRealtimeAuth(client);
+				const channel = client.channel(topic, { config: { private: isPrivate } });
+				try {
+					const response = await channel.httpSend(event, checked.value);
+					return response.success ? ok(void 0) : err(sendError(response.status, response.error));
+				} finally {
+					if (!open) await client.removeChannel(channel);
+				}
+			});
+		},
+		fanOut(client, fanOutOptions) {
+			return fanOutTopic(options.subscribers, fanOutOptions, (subscriber) => api.send(client, fanOutOptions.values(subscriber), fanOutOptions.event, fanOutOptions.payload));
+		}
+	};
+	return api;
+}
+/**
+* Reads a broadcast trigger's default message (`payload: "keys"`). Returns
+* `null` for messages about other tables or with another shape.
+*/
+function rowKeys(betterSupabase, table, message) {
+	const meta = betterSupabase.meta.tables[table];
+	const payload = message.payload;
+	if (!meta || typeof payload !== "object" || payload === null) return null;
+	const fields = { ...payload };
+	const { operation, schema, values } = fields;
+	if (fields["table"] !== meta.name || schema !== void 0 && schema !== meta.schema || operation !== "INSERT" && operation !== "UPDATE" && operation !== "DELETE" || !("id" in fields)) return null;
+	const strings = {};
+	if (typeof values === "object" && values !== null) {
+		for (const [key, value] of Object.entries(values)) if (typeof value === "string") strings[key] = value;
+	}
+	return {
+		operation,
+		schema: meta.schema,
+		table: meta.name,
+		id: fields["id"],
+		values: strings
+	};
+}
+/**
+* Reads a `payload: "row"` message as an app-cased row change. Returns
+* `null` for messages about other tables.
+*/
+function rowChange(betterSupabase, table, message) {
+	const meta = betterSupabase.meta.tables[table];
+	const payload = message.payload;
+	if (!meta || !payload || payload.table !== meta.name || payload.schema && payload.schema !== meta.schema) return null;
+	const operation = payload.operation ?? message.event;
+	if (operation !== "INSERT" && operation !== "UPDATE" && operation !== "DELETE") return null;
+	return {
+		operation,
+		table,
+		record: payload.record ? toApp(meta, payload.record) : null,
+		oldRecord: payload.old_record ? toApp(meta, payload.old_record) : null
+	};
+}
+//#endregion
+export { rowChange as n, rowKeys as r, defineTopic as t };