better-supabase 0.10.0 → 0.12.0

package/dist/testing/index.js

@@ -1,27 +1,27 @@
 import { t as DbException } from "../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../errors-8i6tSICm.js";
+import { n as dbError } from "../errors-BV1SKTVs.js";
 import { d as temporalText } from "../temporal-CB5Fpo5d.js";
-import { t as temporal } from "../temporal-required-DqRzr7i0.js";
-import { a as ok } from "../result-COkvI9t5.js";
-import { t as BetterSupabase } from "../define-CMcokcZz.js";
+import { t as temporal } from "../temporal-required-nfZ87U-0.js";
+import { a as ok } from "../result-DIeYscA3.js";
+import { t as BetterSupabase } from "../define-Bu1v781m.js";
 import { t as isList } from "../guards-6F2bCtQR.js";
-import { a as toBase64Url, r as fromBase64, t as base64ToText } from "../base64-BmeCBgGo.js";
-import { o as resolveConfig } from "../config-CkyahUjo.js";
-import { a as isScopeName, c as templateFunctions, l as templatePlaceholders, n as TEMPLATE_PLACEHOLDERS, s as scopeProblems, u as templateProblems } from "../access-sql-DUSSMaC3.js";
+import { a as toBase64Url, r as fromBase64, t as base64ToText } from "../base64-D4aqdnDR.js";
+import { o as resolveConfig } from "../config-NQmw_wsk.js";
+import { a as isScopeName, c as templateFunctions, l as templatePlaceholders, n as TEMPLATE_PLACEHOLDERS, s as scopeProblems, u as templateProblems } from "../access-sql-CTJPHjCL.js";
 import { i as seedLite, n as loadLite, r as migrateLite, t as LITE_INSTALL } from "../runtime-BOXURhEW.js";
 import { ENV_VARIABLES } from "../env/index.js";
 import { t as defineController } from "../controller-D6NyNrlZ.js";
 import "../replicas-BvIL4_jL.js";
-import { a as tenantCredentialRef } from "../provider-DKh2xFZb.js";
-import { n as rawError } from "../block-transport-G4t1umrR.js";
-import { t as postgresExecutor } from "../executor-aKUo_Xyb.js";
-import { i as requestOf, n as checkPermission, r as defineAuthorizer } from "../authorizer-dVVN05Un.js";
+import { a as tenantCredentialRef } from "../provider-C-Ti38J6.js";
+import { n as rawError } from "../block-transport-J7ZepTq2.js";
+import { t as postgresExecutor } from "../executor-CxGQiQN_.js";
+import { i as requestOf, n as checkPermission, r as defineAuthorizer } from "../authorizer-B3yyCVUF.js";
 import { n as parseDbStats } from "../timing-BMCWgpdZ.js";
 import { t as mailHeaders } from "../delivery-B1mKaOen.js";
 import { toCloudEvents } from "../events/index.js";
 import { d as money, l as isRate } from "../money-95Rff2vT.js";
-import { t as SHIPPING_LINE } from "../tax-DZDpMMRw.js";
-import { t as buildApiModel } from "../build-Cm0T5MVG.js";
+import { t as SHIPPING_LINE } from "../tax-wm9g2mD2.js";
+import { t as buildApiModel } from "../build-CT6SPZkI.js";
 import { timestamps } from "../plugins/timestamps/index.js";
 import { softDelete } from "../plugins/soft-delete/index.js";
 import { tenant } from "../plugins/tenant/index.js";
@@ -185,7 +185,12 @@ async function signLocalJwt(claims, path) {
 //#region src/testing/as-user.ts
 /** The local CLI stack's default JWT secret. */
 const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long";
-function env$1(...names) {
+const internals = /* @__PURE__ */ new WeakMap();
+/** The pool and identity behind a user from `asUser`, or `undefined` for any other object. */
+function internalsOf(user) {
+	return internals.get(user);
+}
+function env$2(...names) {
 	if (typeof process === "undefined") return;
 	for (const name of names) {
 		const value = process.env[name];
@@ -204,7 +209,7 @@ async function signFor(stack, url, claims) {
 		case "ES256": return signTestJwtWithKey(stack.signingKey ?? await localSigningKey(stack.signingKeysPath), claims);
 		case "HS256":
 			if (!LOCAL_HOSTS.has(new URL(url).hostname)) throw new TypeError(`asUser signs HS256 tokens only for a local stack, not ${url}. Use the ES256 key from \`better-supabase keys\`.`);
-			return signTestJwt(stack.jwtSecret ?? env$1("SUPABASE_JWT_SECRET") ?? "super-secret-jwt-token-with-at-least-32-characters-long", claims);
+			return signTestJwt(stack.jwtSecret ?? env$2("SUPABASE_JWT_SECRET") ?? "super-secret-jwt-token-with-at-least-32-characters-long", claims);
 		default: throw new TypeError(`asUser: unknown alg "${String(alg)}"`);
 	}
 }
@@ -220,8 +225,8 @@ async function signFor(stack, url, claims) {
 * ```
 */
 async function asUser(betterSupabase, claims, stack = {}) {
-	const url = stack.url ?? env$1(...ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
-	const publishableKey = stack.publishableKey ?? env$1(...ENV_VARIABLES.publishableKey, "SUPABASE_ANON_KEY");
+	const url = stack.url ?? env$2(...ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
+	const publishableKey = stack.publishableKey ?? env$2(...ENV_VARIABLES.publishableKey, "SUPABASE_ANON_KEY");
 	if (!publishableKey) throw new TypeError("asUser needs publishableKey or $SUPABASE_PUBLISHABLE_KEY. Run `better-supabase env` to write it to .env.local.");
 	const token = await signFor(stack, url, claims);
 	const full = {
@@ -239,15 +244,24 @@ async function asUser(betterSupabase, claims, stack = {}) {
 	};
 	const supabase = createClient(url, publishableKey, {
 		accessToken: () => Promise.resolve(token),
+		tracePropagation: stack.tracePropagation ?? false,
 		...stack.fetch ? { global: { fetch: stack.fetch } } : {}
 	});
-	return {
+	const user = {
 		token,
 		claims: full,
+		context,
 		supabase,
 		db: betterSupabase.connect(supabase, context),
 		sql: stack.postgres ? betterSupabase.connect(postgresExecutor(stack.postgres.asUser(full)), context) : void 0
 	};
+	internals.set(user, {
+		connect: (client) => betterSupabase.connect(postgresExecutor(client), context),
+		postgres: stack.postgres,
+		claims: full,
+		context
+	});
+	return user;
 }
 //#endregion
 //#region src/testing/lite.ts
@@ -499,6 +513,224 @@ async function expectInstant(page, expectation) {
 	});
 }
 //#endregion
+//#region src/testing/seed.ts
+const SEED = Symbol.for("better-supabase.seed");
+function isSeed(value) {
+	return typeof value === "object" && value !== null && SEED in value;
+}
+const quote = (text) => `'${text.replaceAll("'", "''")}'`;
+function arrayLiteral(values) {
+	return `{${values.map((value) => {
+		if (value === null) return "NULL";
+		if (Array.isArray(value)) return arrayLiteral(value);
+		return `"${(temporalText(value) ?? String(value)).replaceAll(/[\\"]/g, "\\$&")}"`;
+	}).join(",")}}`;
+}
+function literal(value, column, where) {
+	if (value === null) return "null";
+	if (column.json) return quote(JSON.stringify(value));
+	if (Array.isArray(value)) return quote(arrayLiteral(value));
+	const temporalValue = temporalText(value);
+	if (temporalValue !== void 0) return quote(temporalValue);
+	const kind = typeof value;
+	switch (kind) {
+		case "string": return quote(value);
+		case "boolean":
+		case "bigint": return String(value);
+		case "number":
+			if (!Number.isFinite(value)) throw new TypeError(`${where}: ${String(value)} is not a finite number`);
+			return String(value);
+		case "object":
+		case "function":
+		case "symbol":
+		case "undefined": throw new TypeError(`${where}: unsupported value of type ${kind}`);
+		default: throw new TypeError(`${where}: unsupported value of type ${String(kind)}`);
+	}
+}
+const ident = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
+/** Parents first (by forward relations), otherwise in the order given. */
+function order(meta, keys) {
+	const sorted = [];
+	const visiting = /* @__PURE__ */ new Set();
+	const visit = (key) => {
+		if (sorted.includes(key) || visiting.has(key)) return;
+		visiting.add(key);
+		for (const relation of Object.values(meta.tables[key]?.relations ?? {})) if (relation.direction === "forward" && relation.table !== key && keys.includes(relation.table)) visit(relation.table);
+		visiting.delete(key);
+		sorted.push(key);
+	};
+	for (const key of keys) visit(key);
+	return sorted;
+}
+function statement(table, rows) {
+	const entries = Object.entries(rows);
+	if (entries.length === 0) return;
+	const columns = [];
+	for (const [, row] of entries) for (const [key, value] of Object.entries(row)) {
+		if (value === void 0 || columns.includes(key)) continue;
+		const column = table.columns[key];
+		if (!column) throw new TypeError(`seed ${table.key}: unknown column "${key}"`);
+		if (column.generated) throw new TypeError(`seed ${table.key}: "${key}" is a generated column`);
+		columns.push(key);
+	}
+	const values = entries.map(([name, row]) => {
+		return `  (${columns.map((key) => row[key] === void 0 ? "default" : literal(row[key], table.columns[key], `seed ${table.key}.${name}.${key}`)).join(", ")})`;
+	});
+	return `insert into ${`${ident(table.schema)}.${ident(table.name)}`} (${columns.map((key) => ident(table.columns[key].db)).join(", ")}) values\n${values.join(",\n")}\non conflict do nothing;`;
+}
+/**
+* Typed fixtures shared by `supabase/seeds` and your tests. Rows use app
+* casing and Insert types; `better-supabase seed` renders them to SQL.
+*
+* ```ts
+* export const seed = defineSeed(betterSupabase, {
+*   organizations: { acme: { id: ACME, name: 'Acme' } },
+*   customers: { first: { organizationId: ACME, name: 'First customer' } },
+* });
+* ```
+*/
+function defineSeed(betterSupabase, fixtures) {
+	const meta = betterSupabase.meta;
+	const statements = () => {
+		const keys = Object.keys(fixtures).filter((key) => fixtures[key] !== void 0);
+		for (const key of keys) {
+			const table = meta.tables[key];
+			if (!table) throw new TypeError(`seed: unknown table "${key}"`);
+			if (table.kind === "view") throw new TypeError(`seed: "${key}" is a view`);
+		}
+		return order(meta, keys).flatMap((key) => {
+			const sql = statement(meta.tables[key], fixtures[key]);
+			return sql ? [sql] : [];
+		});
+	};
+	return {
+		[SEED]: true,
+		rows: fixtures,
+		statements,
+		sql: () => statements().join("\n\n"),
+		async insert(sql) {
+			for (const text of statements()) await sql.queryRaw(text);
+		}
+	};
+}
+//#endregion
+//#region src/testing/scope.ts
+function env$1(names) {
+	if (typeof process === "undefined") return;
+	for (const name of names) {
+		const value = process.env[name];
+		if (value) return value;
+	}
+}
+/**
+* Fresh rows for one test, so tests that run at the same time never share
+* data. It creates a new tenant id, inserts the fixtures that `build` returns
+* through the service role (RLS and plugins don't apply), and hands back the
+* inserted rows. Call `cleanup()` in `afterEach` (or `await using`) to delete
+* them. A user from `asUser` then reads them over PostgREST like any other.
+*
+* ```ts
+* const scope = await scopedSeed(
+*   betterSupabase,
+*   ({ tenant, id }) => ({
+*     customers: { first: { organizationId: tenant, name: `first-${id()}` } },
+*   }),
+*   { tenant: { table: 'organizations', row: (id) => ({ id, name: id, slug: id }) } },
+* );
+* const alice = await asUser(betterSupabase, { sub: aliceId, tenant_id: scope.tenant });
+* expect(await alice.db.customers.count().orThrow()).toBe(1);
+* await scope.cleanup();
+* ```
+*/
+async function scopedSeed(betterSupabase, build, options = {}) {
+	const stack = options.stack ?? {};
+	const url = stack.url ?? env$1(ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
+	const secretKey = stack.secretKey ?? env$1(ENV_VARIABLES.secretKey);
+	if (!secretKey) throw new TypeError("scopedSeed needs stack.secretKey or $SUPABASE_SECRET_KEY to insert rows.");
+	const bare = new BetterSupabase(betterSupabase.schema);
+	const admin = bare.connect(createClient(url, secretKey, { auth: {
+		persistSession: false,
+		autoRefreshToken: false
+	} }));
+	const tenant = crypto.randomUUID();
+	const fixtures = build({
+		tenant,
+		id: () => crypto.randomUUID()
+	});
+	const cleanup = [];
+	const insert = async (table, row) => {
+		const repository = admin[table];
+		if (!repository) throw new TypeError(`scopedSeed: unknown table "${table}"`);
+		const result = await repository.create(row);
+		if (!result.ok) throw new Error(`scopedSeed ${table}: ${result.error.message}`);
+		const meta = bare.meta.tables[table];
+		const created = result.data;
+		if (meta && meta.primaryKey.length > 0) {
+			const where = Object.fromEntries(meta.primaryKey.map((column) => [column, created[column]]));
+			cleanup.push(() => repository.deleteMany({ where }));
+		}
+		return created;
+	};
+	const remove = async () => {
+		const pending = cleanup.splice(0).reverse();
+		let failure;
+		for (const run of pending) try {
+			await run();
+		} catch (error) {
+			failure ??= error;
+		}
+		if (failure !== void 0) throw failure instanceof Error ? failure : new Error(String(failure));
+	};
+	const rows = {};
+	try {
+		if (options.tenant) await insert(options.tenant.table, options.tenant.row(tenant));
+		const byTable = fixtures;
+		for (const key of order(bare.meta, Object.keys(byTable).filter((name) => byTable[name] !== void 0))) {
+			rows[key] = {};
+			for (const [name, row] of Object.entries(byTable[key] ?? {})) rows[key][name] = await insert(key, row);
+		}
+	} catch (error) {
+		await remove().catch(() => void 0);
+		throw error;
+	}
+	return {
+		tenant,
+		rows,
+		cleanup: remove,
+		[Symbol.asyncDispose]: remove
+	};
+}
+/** The error `withRollback` throws to end its transaction; never reaches callers. */
+var Rollback = class extends Error {};
+/**
+* Runs `fn` as the user over direct Postgres inside one transaction and
+* always rolls it back, so the test leaves no rows behind. `fn` gets the same
+* repositories as `user.sql`. Only the `sql` path rolls back: `user.db` talks
+* to PostgREST over HTTP and commits on its own.
+*
+* ```ts
+* const alice = await asUser(betterSupabase, claims, { postgres });
+* await withRollback(alice, async (db) => {
+*   await db.customers.create({ organizationId, name: 'Temp' }).orThrow();
+*   expect(await db.customers.count().orThrow()).toBe(1);
+* });
+* ```
+*/
+async function withRollback(user, fn) {
+	const internal = internalsOf(user);
+	if (!internal?.postgres) throw new TypeError("withRollback needs a user from asUser(betterSupabase, claims, { postgres }): it rolls back over direct Postgres, not PostgREST.");
+	let outcome;
+	try {
+		await internal.postgres.transaction(async (client) => {
+			outcome = { value: await fn(internal.connect(client)) };
+			throw new Rollback("rollback");
+		}, { claims: internal.claims });
+	} catch (error) {
+		if (!(error instanceof Rollback) || !outcome) throw error;
+	}
+	return outcome.value;
+}
+//#endregion
 //#region src/testing/conformance.ts
 /** Thrown by a conformance kit when any check fails. Lists every failure, not just the first. */
 var ConformanceError = class extends Error {
@@ -957,107 +1189,6 @@ const supabaseInvalidClaimFixtures = {
 	}
 };
 //#endregion
-//#region src/testing/seed.ts
-const SEED = Symbol.for("better-supabase.seed");
-function isSeed(value) {
-	return typeof value === "object" && value !== null && SEED in value;
-}
-const quote = (text) => `'${text.replaceAll("'", "''")}'`;
-function arrayLiteral(values) {
-	return `{${values.map((value) => {
-		if (value === null) return "NULL";
-		if (Array.isArray(value)) return arrayLiteral(value);
-		return `"${(temporalText(value) ?? String(value)).replaceAll(/[\\"]/g, "\\$&")}"`;
-	}).join(",")}}`;
-}
-function literal(value, column, where) {
-	if (value === null) return "null";
-	if (column.json) return quote(JSON.stringify(value));
-	if (Array.isArray(value)) return quote(arrayLiteral(value));
-	const temporalValue = temporalText(value);
-	if (temporalValue !== void 0) return quote(temporalValue);
-	const kind = typeof value;
-	switch (kind) {
-		case "string": return quote(value);
-		case "boolean":
-		case "bigint": return String(value);
-		case "number":
-			if (!Number.isFinite(value)) throw new TypeError(`${where}: ${String(value)} is not a finite number`);
-			return String(value);
-		case "object":
-		case "function":
-		case "symbol":
-		case "undefined": throw new TypeError(`${where}: unsupported value of type ${kind}`);
-		default: throw new TypeError(`${where}: unsupported value of type ${String(kind)}`);
-	}
-}
-const ident = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
-/** Parents first (by forward relations), otherwise in the order given. */
-function order(meta, keys) {
-	const sorted = [];
-	const visiting = /* @__PURE__ */ new Set();
-	const visit = (key) => {
-		if (sorted.includes(key) || visiting.has(key)) return;
-		visiting.add(key);
-		for (const relation of Object.values(meta.tables[key]?.relations ?? {})) if (relation.direction === "forward" && relation.table !== key && keys.includes(relation.table)) visit(relation.table);
-		visiting.delete(key);
-		sorted.push(key);
-	};
-	for (const key of keys) visit(key);
-	return sorted;
-}
-function statement(table, rows) {
-	const entries = Object.entries(rows);
-	if (entries.length === 0) return;
-	const columns = [];
-	for (const [, row] of entries) for (const [key, value] of Object.entries(row)) {
-		if (value === void 0 || columns.includes(key)) continue;
-		const column = table.columns[key];
-		if (!column) throw new TypeError(`seed ${table.key}: unknown column "${key}"`);
-		if (column.generated) throw new TypeError(`seed ${table.key}: "${key}" is a generated column`);
-		columns.push(key);
-	}
-	const values = entries.map(([name, row]) => {
-		return `  (${columns.map((key) => row[key] === void 0 ? "default" : literal(row[key], table.columns[key], `seed ${table.key}.${name}.${key}`)).join(", ")})`;
-	});
-	return `insert into ${`${ident(table.schema)}.${ident(table.name)}`} (${columns.map((key) => ident(table.columns[key].db)).join(", ")}) values\n${values.join(",\n")}\non conflict do nothing;`;
-}
-/**
-* Typed fixtures shared by `supabase/seeds` and your tests. Rows use app
-* casing and Insert types; `better-supabase seed` renders them to SQL.
-*
-* ```ts
-* export const seed = defineSeed(betterSupabase, {
-*   organizations: { acme: { id: ACME, name: 'Acme' } },
-*   customers: { first: { organizationId: ACME, name: 'First customer' } },
-* });
-* ```
-*/
-function defineSeed(betterSupabase, fixtures) {
-	const meta = betterSupabase.meta;
-	const statements = () => {
-		const keys = Object.keys(fixtures).filter((key) => fixtures[key] !== void 0);
-		for (const key of keys) {
-			const table = meta.tables[key];
-			if (!table) throw new TypeError(`seed: unknown table "${key}"`);
-			if (table.kind === "view") throw new TypeError(`seed: "${key}" is a view`);
-		}
-		return order(meta, keys).flatMap((key) => {
-			const sql = statement(meta.tables[key], fixtures[key]);
-			return sql ? [sql] : [];
-		});
-	};
-	return {
-		[SEED]: true,
-		rows: fixtures,
-		statements,
-		sql: () => statements().join("\n\n"),
-		async insert(sql) {
-			for (const text of statements()) await sql.queryRaw(text);
-		}
-	};
-}
-//#endregion
 //#region src/testing/kits/executor.ts
 const recorder = (ops) => ({
 	name: "recorder",
@@ -3955,4 +4086,4 @@ const actCases = {
 	]
 };
 //#endregion
-export { ConformanceError, LOCAL_JWT_SECRET, PROBE_INITIAL, actCases, asUser, createTestSigner, defineSeed, expectDbBudget, expectInstant, expectTenantIsolation, isSeed, liteStack, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, staticAuthorizer, supabaseClaimFixtures, supabaseInvalidClaimFixtures, testAdapter, testAiTaskRunner, testAuthResolver, testAuthorizationHooks, testAuthorizationProvider, testAuthorizer, testBlockTransportMiddleware, testBuilderStarter, testCacheAdapter, testChatState, testControllerBinding, testCredentialProvider, testDeliveryTransport, testDocumentFormat, testEmbedder, testEveDocumentBackend, testEventSink, testExecutor, testGenerator, testGraphCompiler, testIncomingDestination, testNotificationChannel, testPaymentProvider, testPlugin, testQueueBackend, testStreamStore, testSupportSessionStore, testTaxProvider, testWebhookSecretStore, testWebhookSigner, testWebhookTransport };
+export { ConformanceError, LOCAL_JWT_SECRET, PROBE_INITIAL, actCases, asUser, createTestSigner, defineSeed, expectDbBudget, expectInstant, expectTenantIsolation, isSeed, liteStack, localAuth, localSigningKey, scopedSeed, signLocalJwt, signTestJwt, signTestJwtWithKey, staticAuthorizer, supabaseClaimFixtures, supabaseInvalidClaimFixtures, testAdapter, testAiTaskRunner, testAuthResolver, testAuthorizationHooks, testAuthorizationProvider, testAuthorizer, testBlockTransportMiddleware, testBuilderStarter, testCacheAdapter, testChatState, testControllerBinding, testCredentialProvider, testDeliveryTransport, testDocumentFormat, testEmbedder, testEveDocumentBackend, testEventSink, testExecutor, testGenerator, testGraphCompiler, testIncomingDestination, testNotificationChannel, testPaymentProvider, testPlugin, testQueueBackend, testStreamStore, testSupportSessionStore, testTaxProvider, testWebhookSecretStore, testWebhookSigner, testWebhookTransport, withRollback };

package/dist/{topic-Dgs-eSYQ.d.ts → topic-DAY_HOX2.d.ts}

@@ -1,10 +1,10 @@
-import { E as ValidationIssue, b as DbError, t as AsyncResult } from "./result-Cj3yWhjH.js";
-import { M as Row, a as AnyModels, i as AnyFunctions, r as AccessTopicPolicy, z as TableKey } from "./types-BO8lVTun.js";
-import { t as AuthorizationFunctions } from "./authorization-CdJRoZgV.js";
+import { D as ValidationIssue, b as DbError, t as AsyncResult } from "./result-BREt7qOh.js";
+import { B as TableKey, N as Row, a as AnyModels, i as AnyFunctions, r as AccessTopicPolicy } from "./types-BrpW5ixT.js";
+import { t as AuthorizationFunctions } from "./authorization-ClWBcXJi.js";
 import { t as RealtimeStatus } from "./realtime-status-DcsO00Gw.js";
-import { J as TemplateValues, q as TemplateParams } from "./storage-api-B4Ib2Zpo.js";
-import { t as BetterSupabase } from "./define-DXTC706J.js";
-import { g as SubscriberPolicy, h as SubscriberEvent, i as AuthorizationHooks, m as Subscriber } from "./authorization-hooks-Do5djkpz.js";
+import { D as TemplateParams, O as TemplateValues } from "./bucket-BbePDVwc.js";
+import { t as BetterSupabase } from "./define-DYZnvAbs.js";
+import { g as SubscriberPolicy, h as SubscriberEvent, i as AuthorizationHooks, m as Subscriber } from "./authorization-hooks-WDQMKIsc.js";
 import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/realtime/fan-out.d.ts
@@ -234,6 +234,13 @@ interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends strin
   }>>;
   /** More topics the row change goes to, each with its own values. */
   readonly topics?: readonly TriggerTopic<TriggerValue<M, T>>[];
+  /**
+   * Send an UPDATE only when one of these columns changed. Inserts and
+   * deletes always send.
+   */
+  readonly when?: {
+    readonly changed: readonly Extract<keyof Row<M, T>, string>[];
+  };
 }
 interface TopicTriggerLookup {
   readonly from: string;
@@ -259,6 +266,13 @@ interface TopicTriggerOptions<P extends string> extends TriggerCommonOptions {
   }>>;
   /** More topics the row change goes to, each with its own values. */
   readonly topics?: readonly TriggerTopic<TopicTriggerValue>[];
+  /**
+   * Send an UPDATE only when one of these columns (database names)
+   * changed. Inserts and deletes always send.
+   */
+  readonly when?: {
+    readonly changed: readonly string[];
+  };
 }
 /** A row change sent with `payload: "row"`. */
 interface RowChange<R> {

package/dist/{topic-DB-1YTMj.js → topic-mee21pux.js}

@@ -1,8 +1,8 @@
-import { n as dbError } from "./errors-8i6tSICm.js";
-import { a as ok, r as err, t as AsyncResult } from "./result-COkvI9t5.js";
+import { n as dbError } from "./errors-BV1SKTVs.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-DIeYscA3.js";
 import { a as tenantClaimPaths } from "./claims-PqzCxaTD.js";
-import { a as sqlString, i as sqlIdent, n as parseTemplate, r as slug, t as claimSql } from "./template-DdgYjIZ5.js";
-import { a as isScopeName, i as fillTemplate, o as resolveProviderSql, r as accessCheck } from "./access-sql-DUSSMaC3.js";
+import { a as sqlString, i as sqlIdent, n as parseTemplate, r as slug, t as claimSql } from "./template-Dw3dTmKe.js";
+import { a as isScopeName, i as fillTemplate, o as resolveProviderSql, r as accessCheck } from "./access-sql-CTJPHjCL.js";
 import { t as refreshRealtimeAuth } from "./auth-CdBKt0CS.js";
 import { t as allowedSubscribers } from "./subscribers-Cq--DL1E.js";
 import { t as joinTopic } from "./channels-C-GCoNLd.js";
@@ -86,13 +86,55 @@ function rawLookupTarget(value) {
 		select: sqlIdent(value.select)
 	};
 }
-/** A trigger value as SQL on `rec`, with one subquery per lookup. */
-function triggerValueSql(tables, meta, value, where, depth = 0) {
+/**
+* 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 alias = `j${String(depth)}`;
-	const via = triggerValueSql(tables, meta, value.via, where, depth + 1);
-	return `(select ${alias}.${target.select} from ${target.relation} ${alias} where ${alias}.${target.key} = ${via} limit 1)`;
+	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) {
@@ -103,6 +145,9 @@ function eventSql(event) {
 }
 //#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. */
@@ -134,7 +179,16 @@ function payloadSql(payload) {
 */
 function triggerFunctionSql(input) {
 	const fn = `${sqlIdent(input.functionSchema)}.${sqlIdent(input.functionName)}`;
-	const payload = payloadSql(input.payload);
+	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(", ")})`;
@@ -164,12 +218,17 @@ function triggerFunctionSql(input) {
 		"  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;",
@@ -179,7 +238,7 @@ function triggerFunctionSql(input) {
 		"",
 		`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}();`,
+		`  for each row${input.changed?.when ? ` when (${input.changed.sql})` : ""} execute function ${fn}();`,
 		""
 	].join("\n");
 }
@@ -294,17 +353,23 @@ function defineTopic(template, options = {}) {
 		const triggerName = `bs_broadcast_${name}`;
 		const extra = trigger.topics ?? [];
 		const { payload } = trigger;
-		const events = (trigger.events ?? [
+		const operations = trigger.events ?? [
 			"insert",
 			"update",
 			"delete"
-		]).join(" or ");
+		];
+		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")) {
+		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 =`);
@@ -317,11 +382,12 @@ function defineTopic(template, options = {}) {
 				`-- 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(", ")});`,
+				`  for each row${changed ? ` when (${changed.sql})` : ""} execute function better_supabase.broadcast_topic(${args.join(", ")});`,
 				""
 			].join("\n");
 		}
-		const valueSql = (value, label) => triggerValueSql(tables, meta, value, label);
+		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}"`);
@@ -355,7 +421,9 @@ function defineTopic(template, options = {}) {
 			events,
 			event: eventSql(trigger.event),
 			topics,
-			payload: payloadSql
+			payload: payloadSql,
+			lookups: lookups.list,
+			...changed ? { changed } : {}
 		});
 	};
 	const api = {