better-supabase 0.13.0 → 0.15.0

package/dist/topic-ikV_pLTX.js

@@ -0,0 +1,643 @@
+import { n as dbError } from "./errors-BVFgt8BZ.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-ntFBW2p2.js";
+import { t as toApp } from "./casing-DdFWEtqr.js";
+import { a as tenantClaimPaths } from "./claims-Bp9My7XP.js";
+import { a as sqlString, i as sqlIdent, n as parseTemplate, r as slug, t as claimSql } from "./template-Drgg3v2J.js";
+import { a as isScopeName, i as fillTemplate, o as resolveProviderSql, r as accessCheck } from "./access-sql-B-MkVARa.js";
+import { t as refreshRealtimeAuth } from "./auth-DyF_LRxd.js";
+import { t as joinTopic } from "./channels-CfcFPuo_.js";
+import { t as allowedSubscribers } from "./subscribers-BvZxcd63.js";
+import { t as topicStatus } from "./realtime-status-asHvhiOh.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);
+}
+const splitTable = (table) => table.includes(".") ? [table.slice(0, table.indexOf(".")), table.slice(table.indexOf(".") + 1)] : ["public", table];
+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);
+}
+function lookupTarget(tables, 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}`);
+	return {
+		relation: `${sqlIdent(joined.schema)}.${sqlIdent(joined.name)}`,
+		key: columnSql(joined, key, where),
+		select: columnSql(joined, value.select, where)
+	};
+}
+function rawLookupTarget(value) {
+	const [schema, name] = splitTable(value.from);
+	return {
+		relation: `${sqlIdent(schema)}.${sqlIdent(name)}`,
+		key: sqlIdent(value.key ?? "id"),
+		select: sqlIdent(value.select)
+	};
+}
+/**
+* The lookups of one generated function. Each parent row is read once per
+* changed row, with every column the topics, values and payload need from it,
+* and a row comes before the rows that join through it.
+*/
+var TriggerLookups = class {
+	#byRow = /* @__PURE__ */ new Map();
+	add(target) {
+		const row = [
+			target.relation,
+			target.key,
+			target.via
+		].join("\0");
+		const known = this.#byRow.get(row);
+		if (known) {
+			if (!known.columns.includes(target.select)) known.columns.push(target.select);
+			return `${known.name}.${target.select}`;
+		}
+		const name = `lk_${String(this.#byRow.size)}`;
+		this.#byRow.set(row, {
+			name,
+			relation: target.relation,
+			key: target.key,
+			columns: [target.select],
+			via: target.via
+		});
+		return `${name}.${target.select}`;
+	}
+	get list() {
+		return [...this.#byRow.values()];
+	}
+};
+/** A trigger value as SQL on `rec`; each lookup becomes a variable in `lookups`. */
+function triggerValueSql(tables, meta, value, where, lookups) {
+	if (typeof value === "string") return `rec.${meta ? columnSql(meta, value, where) : sqlIdent(value)}`;
+	const target = tables && meta ? lookupTarget(tables, value, where) : rawLookupTarget(value);
+	const via = triggerValueSql(tables, meta, value.via, where, lookups);
+	return lookups.add({
+		...target,
+		via
+	});
+}
+/** The columns of `when.changed` as an `old`/`new` comparison. */
+function changedSql(meta, changed, where) {
+	if (changed.length === 0) throw new TypeError(`${where}: when.changed lists no columns`);
+	return changed.map((column) => {
+		const db = meta ? columnSql(meta, column, "when.changed") : sqlIdent(column);
+		return `old.${db} is distinct from new.${db}`;
+	}).join(" or ");
+}
+/** 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
+/** The start of the warning a delete raises when a lookup finds no row. */
+const LOOKUP_WARNING = "better-supabase: realtime lookup found no row";
+const LOOKUP_HINT = "The parent row was deleted in the same statement, such as a cascade, so the topic that reads it is skipped. Keep the topic value on the row itself, or add a topic trigger on the parent.";
+/**
+* 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 = input.payload.kind === "custom" ? "body" : payloadSql(input.payload);
+	const declarations = input.lookups.map((lookup) => `  ${lookup.name} record;`);
+	const reads = input.lookups.flatMap((lookup) => [
+		`  select ${lookup.columns.map((column) => `j.${column}`).join(", ")} into ${lookup.name} from ${lookup.relation} j where j.${lookup.key} = ${lookup.via} limit 1;`,
+		`  if not found and tg_op = 'DELETE' and ${lookup.via} is not null then`,
+		`    raise warning '${LOOKUP_WARNING} for a delete on %.%: no % row where % = %', tg_table_schema, tg_table_name, ${sqlString(lookup.relation)}, ${sqlString(lookup.key)}, ${lookup.via}`,
+		`      using hint = ${sqlString(LOOKUP_HINT)};`,
+		"  end if;"
+	]);
+	const early = input.changed && !input.changed.when ? [`  if tg_op = 'UPDATE' and not (${input.changed.sql}) then return null; end if;`] : [];
+	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;",
+		...input.payload.kind === "custom" ? ["  body jsonb;"] : [],
+		...declarations,
+		"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;",
+		...early,
+		"  if tg_op = 'DELETE' then rec := old; else rec := new; end if;",
+		...reads,
+		...input.payload.kind === "custom" ? [`  body := ${input.payload.sql};`] : [],
+		...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${input.changed?.when ? ` when (${input.changed.sql})` : ""} execute function ${fn}();`,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/realtime/topic.ts
+const columnsOnly = (values) => {
+	const columns = {};
+	for (const [param, value] of Object.entries(values ?? {})) {
+		if (typeof value === "object") return;
+		if (value !== void 0) columns[param] = value;
+	}
+	return columns;
+};
+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 = `bsb_broadcast_${name}`;
+		const extra = trigger.topics ?? [];
+		const { payload } = trigger;
+		const operations = trigger.events ?? [
+			"insert",
+			"update",
+			"delete"
+		];
+		const events = operations.join(" or ");
+		if (trigger.when && !operations.includes("update")) throw new TypeError(`${where}: when.changed filters updates, but events has no "update"`);
+		const changed = trigger.when ? {
+			sql: changedSql(meta, trigger.when.changed, where),
+			when: operations.length === 1
+		} : void 0;
+		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);
+		const columns = columnsOnly(trigger.values);
+		if (!meta && columns !== void 0 && extra.length === 0 && typeof trigger.event !== "object" && (payload === void 0 || typeof payload === "string") && (changed === void 0 || changed.when)) {
+			const sqlTemplate = template.replaceAll(/\{([^}]+)\}/g, (_, param) => {
+				const column = columns[param] ?? snakeCase(param);
+				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${changed ? ` when (${changed.sql})` : ""} execute function better_supabase.broadcast_topic(${args.join(", ")});`,
+				""
+			].join("\n");
+		}
+		const lookups = new TriggerLookups();
+		const valueSql = (value, label) => triggerValueSql(tables, meta, value, label, lookups);
+		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: `bsb_broadcast_${name}_${slug(schema)}_${slug(relation)}`,
+			triggerName,
+			target,
+			events,
+			event: eventSql(trigger.event),
+			topics,
+			payload: payloadSql,
+			lookups: lookups.list,
+			...changed ? { changed } : {}
+		});
+	};
+	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(`bsb_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) => {
+				syncs += 1;
+				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 };