better-supabase 0.8.0 → 0.10.0

package/dist/verify-C9D_jjsQ.js

@@ -0,0 +1,126 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { c as optionalTemporal, s as nowInstant } from "./temporal-CB5Fpo5d.js";
+import { n as temporalMissing } from "./temporal-required-DqRzr7i0.js";
+import { a as ok, r as err } from "./result-COkvI9t5.js";
+import { n as hmacHex, r as timingSafeEqual } from "./hmac-DCud0myt.js";
+import { a as unauthorized, n as header, r as replayed, s as verifyWebhook } from "./signatures-C9CGYZS1.js";
+import { t as toApp } from "./casing-DdFWEtqr.js";
+//#region src/blocks/webhooks/verify.ts
+/** Stripe signs with the endpoint secret's UTF-8 bytes, not its base64 decoding. */
+const stripeSignature = hmacHex;
+/** The `Stripe-Signature` header for `body`, for tests and local replays. */
+async function signStripeWebhook(secret, body, timestamp = nowInstant()) {
+	const seconds = String(Math.floor(timestamp.epochMilliseconds / 1e3));
+	return `t=${seconds},v1=${await stripeSignature(secret, `${seconds}.${body}`)}`;
+}
+/**
+* Verifies a `Stripe-Signature` header (`t=…,v1=…`) with the endpoint's
+* `whsec_…` secret and parses the event. Pass several secrets while rolling
+* the endpoint secret. Runs on WebCrypto, so it needs no `stripe` package.
+*/
+async function verifyStripeWebhook(input, secrets, options = {}) {
+	const value = header(input.headers, "stripe-signature");
+	if (!value) return err(unauthorized("WEBHOOK_MISSING_HEADERS", "Missing Stripe-Signature header"));
+	const parts = value.split(",").map((part) => {
+		const index = part.indexOf("=");
+		return [part.slice(0, index).trim(), part.slice(index + 1).trim()];
+	});
+	const timestamp = parts.find(([name]) => name === "t")?.[1] ?? "";
+	const offered = parts.filter(([name]) => name === "v1").map(([, sig]) => sig);
+	if (!/^\d+$/.test(timestamp)) return err(unauthorized("WEBHOOK_INVALID_TIMESTAMP", "Invalid webhook timestamp"));
+	const namespace = optionalTemporal();
+	if (namespace === void 0) return err(temporalMissing());
+	const seconds = Number(timestamp);
+	const now = (options.now?.() ?? namespace.Now.instant()).epochMilliseconds / 1e3;
+	if (Math.abs(now - seconds) > (options.tolerance ?? 300)) return err(unauthorized("WEBHOOK_TIMESTAMP_OUT_OF_RANGE", "Webhook timestamp is outside the tolerance"));
+	const body = input instanceof Request ? await input.text() : input.body;
+	let valid = false;
+	for (const secret of typeof secrets === "string" ? [secrets] : secrets) {
+		const expected = await stripeSignature(secret, `${timestamp}.${body}`);
+		for (const candidate of offered) if (timingSafeEqual(candidate, expected)) valid = true;
+	}
+	if (!valid) return err(unauthorized("WEBHOOK_INVALID_SIGNATURE", "Invalid webhook signature"));
+	let payload;
+	try {
+		payload = JSON.parse(body);
+	} catch {
+		return err(dbError("invalid_request", "Webhook body is not JSON"));
+	}
+	const id = typeof payload === "object" && payload !== null && "id" in payload ? String(payload.id) : "";
+	const replay = await replayed(options, id, namespace.Instant.fromEpochMilliseconds((seconds + (options.tolerance ?? 300)) * 1e3));
+	if (replay) return err(replay);
+	return ok({
+		id,
+		timestamp: namespace.Instant.fromEpochMilliseconds(seconds * 1e3),
+		payload,
+		body
+	});
+}
+/**
+* `createWebhookInbox({ source: 'stripe', verify: stripeInboxVerify(secret) })`:
+* stores Stripe events keyed by their event id.
+*/
+function stripeInboxVerify(secrets, options = {}) {
+	return async (request, body) => {
+		const verified = await verifyStripeWebhook({
+			headers: request.headers,
+			body
+		}, secrets, options);
+		return verified.ok ? ok({
+			id: verified.data.id,
+			payload: verified.data.payload
+		}) : verified;
+	};
+}
+/** Rejects a hook with a status and message Supabase Auth passes to the client. */
+function hookError(status, message) {
+	return { error: {
+		http_code: status,
+		message
+	} };
+}
+/**
+* A `(request) => Response` handler for a Supabase Auth hook: verifies the
+* Standard Webhooks signature, types the payload and serializes the answer.
+*
+* ```ts
+* export const POST = authHook('custom_access_token', env.AUTH_HOOK_SECRET, async ({ claims, user_id }) => ({
+*   claims: { ...claims, tenant_id: await organizationFor(user_id) },
+* }));
+* ```
+*/
+function authHook(_kind, secret, handler, options) {
+	return async (request) => {
+		const verified = await verifyWebhook(request, secret, options);
+		if (!verified.ok) return Response.json(hookError(verified.error.status, verified.error.message), { status: verified.error.status });
+		try {
+			const answer = await handler(verified.data.payload, verified.data);
+			const status = "error" in answer ? answer.error.http_code : 200;
+			return Response.json(answer, { status });
+		} catch (cause) {
+			console.error("better-supabase: auth hook failed", cause);
+			return Response.json(hookError(500, "Hook failed"), { status: 500 });
+		}
+	};
+}
+function isDatabaseWebhook(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const payload = value;
+	return (payload["type"] === "INSERT" || payload["type"] === "UPDATE" || payload["type"] === "DELETE") && typeof payload["table"] === "string" && typeof payload["schema"] === "string";
+}
+/**
+* Reads a database webhook payload for `table` as an app-cased change.
+* Returns `null` for other tables or payloads that aren't database webhooks.
+*/
+function databaseChange(betterSupabase, table, payload) {
+	const meta = betterSupabase.meta.tables[table];
+	if (!meta || !isDatabaseWebhook(payload) || payload.table !== meta.name || payload.schema !== meta.schema) return null;
+	return {
+		type: payload.type,
+		table,
+		record: payload.record ? toApp(meta, payload.record) : null,
+		oldRecord: payload.old_record ? toApp(meta, payload.old_record) : null
+	};
+}
+//#endregion
+export { signStripeWebhook as a, isDatabaseWebhook as i, databaseChange as n, stripeInboxVerify as o, hookError as r, verifyStripeWebhook as s, authHook as t };

package/dist/version-Bxj_xcUY.js

@@ -0,0 +1,4 @@
+//#region src/core/version.ts
+const VERSION = "0.10.0";
+//#endregion
+export { VERSION as t };

package/dist/view-DZ63nqwt.js

@@ -0,0 +1,105 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { a as invalidActorError, i as delegationOf, n as actorOf } from "./actor-KHDOKGb1.js";
+import { r as impersonatorOf } from "./impersonation-CDeCzZP6.js";
+//#region src/auth/mfa.ts
+/** The session's assurance level from its claims; anything but `aal2` reads as `aal1`. */
+function aalOf(claims) {
+	return claims["aal"] === "aal2" ? "aal2" : "aal1";
+}
+/** The `amr` claim as typed entries, skipping malformed ones. */
+function amrOf(claims) {
+	const amr = claims["amr"];
+	if (!Array.isArray(amr)) return [];
+	return amr.flatMap((entry) => {
+		if (typeof entry !== "object" || entry === null) return [];
+		const { method, timestamp, provider } = entry;
+		if (typeof method !== "string" || typeof timestamp !== "number") return [];
+		return [typeof provider === "string" ? {
+			method,
+			timestamp,
+			provider
+		} : {
+			method,
+			timestamp
+		}];
+	});
+}
+/**
+* `undefined` when a user session meets `required`; otherwise a `forbidden`
+* error with `required` and code `INSUFFICIENT_AAL`, for the client to start
+* an MFA challenge. Non-user sessions pass: `allow` decides about them.
+*/
+function checkAal(auth, required) {
+	if (required === "aal1" || auth.kind !== "user" || !("claims" in auth)) return;
+	if (aalOf(auth.claims) === "aal2") return;
+	return dbError("forbidden", "Verify a second factor to continue", {
+		code: "INSUFFICIENT_AAL",
+		required
+	});
+}
+//#endregion
+//#region src/auth/view.ts
+/** Whether the token belongs to an anonymous user (`signInAnonymously()`). */
+function isAnonymousUser(claims) {
+	return "is_anonymous" in claims && claims.is_anonymous === true;
+}
+/** Drops the token from an `AuthState`, leaving only serializable fields. */
+function toSession(auth) {
+	switch (auth.kind) {
+		case "user": {
+			const outcome = actorOf(auth.claims);
+			if (!outcome.ok) return {
+				kind: "invalid",
+				reason: "actor",
+				error: invalidActorError()
+			};
+			const impersonator = impersonatorOf(auth.claims);
+			const actor = outcome.actor;
+			const client = actor?.kind === "oauth-client" || actor?.kind === "agent" && delegationOf(auth.claims) !== void 0 ? actor : void 0;
+			const scopes = client ? delegationOf(auth.claims)?.scopes : void 0;
+			const delegation = client && (scopes || client.chain) ? {
+				scopes: scopes ?? [],
+				...client.chain ? { chain: client.chain } : {}
+			} : void 0;
+			return {
+				kind: "user",
+				user: auth.user,
+				claims: auth.claims,
+				expiresAt: auth.expiresAt,
+				...auth.profile === void 0 ? {} : { profile: auth.profile },
+				aal: aalOf(auth.claims),
+				anonymous: isAnonymousUser(auth.claims),
+				amr: amrOf(auth.claims),
+				...impersonator ? { impersonator } : {},
+				...actor ? { actor } : {},
+				...delegation ? { delegation } : {}
+			};
+		}
+		case "service": return {
+			kind: "service",
+			keyName: auth.keyName
+		};
+		case "apiKey": return {
+			kind: "apiKey",
+			keyId: auth.keyId,
+			name: auth.name,
+			...auth.organizationId ? { organizationId: auth.organizationId } : {},
+			...auth.userId ? { userId: auth.userId } : {},
+			scopes: auth.scopes,
+			...auth.createdAt ? { createdAt: Math.floor(auth.createdAt.epochMilliseconds / 1e3) } : {},
+			...auth.createdBy ? { createdBy: auth.createdBy } : {}
+		};
+		case "anon": return {
+			kind: "anon",
+			reason: auth.reason
+		};
+		case "invalid": return {
+			kind: "invalid",
+			reason: auth.reason,
+			error: auth.error
+		};
+		default: return auth;
+	}
+}
+//#endregion
+export { checkAal as a, amrOf as i, toSession as n, aalOf as r, isAnonymousUser as t };

package/dist/view-SuASaomx.d.ts

@@ -0,0 +1,90 @@
+import { b as DbError } from "./result-Cj3yWhjH.js";
+import { i as InvalidReason, r as AuthState } from "./resolve-7atr-wWr.js";
+import { a as SessionActor, o as SessionDelegation } from "./actor-BAhb-d1S.js";
+import { n as Impersonator } from "./impersonation-D5chOkrO.js";
+import { n as AmrEntry, t as Aal } from "./mfa-DtflCXEt.js";
+import { JWTClaims, UserClaims } from "@supabase/server";
+//#region src/auth/view.d.ts
+/**
+ * The verified caller as plain data: no token, no clients. Safe to return
+ * from a `'use cache: private'` function and to pass to Client Components.
+ */
+type AuthSession<C = unknown, P = unknown> = {
+  readonly kind: "user";
+  /**
+   * Read from the verified claims (`sub`, `email`, `role`,
+   * `app_metadata`, `user_metadata`), never from the user object in the
+   * cookie, so it is the same with `tokens-only` cookies. Call
+   * `auth.getUser()` when a flow must see a revoked or changed user.
+   */
+  readonly user: UserClaims;
+  /**
+   * The verified JWT payload, including custom access token hook claims,
+   * typed and validated by `betterSupabase.claims(schema)`.
+   */
+  readonly claims: JWTClaims & C;
+  /** Seconds since epoch, from the token's `exp`. */
+  readonly expiresAt: number | null;
+  /**
+   * `user_metadata` parsed by `betterSupabase.userMetadata(schema)`, for display.
+   * Absent without a schema or when the metadata fails it. Users
+   * write this data with `auth.updateUser()`: never base access on it.
+   */
+  readonly profile?: P;
+  /** `aal2` once the user verified a second factor in this session. */
+  readonly aal: Aal;
+  /**
+   * Signed in with `signInAnonymously()` (the `is_anonymous` claim). Guards
+   * refuse these users unless `allow` lists `'anonymous'`; `'anon'` means
+   * no session and never admits them.
+   */
+  readonly anonymous: boolean;
+  /** How the user signed in (`password`, `totp`, `sso/saml`, ...). */
+  readonly amr: readonly AmrEntry[];
+  /**
+   * Set when an admin acts as this user in a support session or an
+   * impersonated session (`act.kind`), for a banner. Matches `actor`.
+   */
+  readonly impersonator?: Impersonator;
+  /**
+   * Who acts for the user: an OAuth client or agent (`client_id`, or an
+   * `act` chain without `kind`), a support session or an impersonated
+   * session, read from the `act` and `client_id` claims.
+   */
+  readonly actor?: SessionActor;
+  /**
+   * The scopes the user granted an `oauth-client` actor (or an `agent`
+   * on a token with a `scope`), without the OpenID identity scopes in
+   * `IDENTITY_SCOPES`, plus its `act` chain. Never set for a support or
+   * impersonated session.
+   */
+  readonly delegation?: SessionDelegation;
+} | {
+  readonly kind: "service";
+  readonly keyName: string;
+} | {
+  readonly kind: "apiKey";
+  readonly keyId: string;
+  readonly name: string;
+  readonly organizationId?: string;
+  readonly userId?: string;
+  readonly scopes: readonly string[];
+  /** Seconds since epoch, when the key was created. */
+  readonly createdAt?: number;
+  /** The user who created the key. */
+  readonly createdBy?: string;
+} | {
+  readonly kind: "anon";
+  readonly reason: AnonReason;
+} | {
+  readonly kind: "invalid";
+  readonly reason: InvalidReason;
+  readonly error: DbError;
+};
+type AnonReason = Extract<AuthState, {
+  kind: "anon";
+}>["reason"];
+/** Drops the token from an `AuthState`, leaving only serializable fields. */
+declare function toSession<C, P>(auth: AuthState<C, P>): AuthSession<C, P>;
+//#endregion
+export { toSession as n, AuthSession as t };

package/dist/vue/index.d.ts

@@ -1,11 +1,11 @@
-import { b as DbError } from "../result-BchM1XZn.js";
-import { J as TemplateValues } from "../storage-api-CB7Zl1Ci.js";
-import { at as QuerySpec } from "../define-DmcfoNXB.js";
-import { t as AuthSnapshot } from "../bind-CQ5mPyX1.js";
-import { t as AuthSession } from "../view-TpXEUcVN.js";
-import { S as Topic, f as PresenceMember, u as EventSchemas, w as TopicHandlers, x as SubscriptionStatus } from "../index-BCHR4Ucl.js";
-import { t as SupportView } from "../support-view-scqMgtOo.js";
-import { a as BroadcastOptions, c as LiveCountHookOptions, d as PresenceHookOptions, f as PresenceTopic, i as ActionState, l as LiveCountSource, m as UseActionOptions, n as ActionInputOf, o as ClaimsOf, p as ProfileOf, r as ActionResultOf, s as ClientLike, t as fieldErrorsOf, u as LiveQueryHookOptions } from "../field-errors-DIe9XYWL.js";
+import { b as DbError } from "../result-Cj3yWhjH.js";
+import { J as TemplateValues } from "../storage-api-B4Ib2Zpo.js";
+import { at as QuerySpec } from "../define-DXTC706J.js";
+import { g as TopicHandlers, m as Topic, p as SubscriptionStatus, r as PresenceMember, t as EventSchemas } from "../topic-Dgs-eSYQ.js";
+import { t as AuthSnapshot } from "../bind-DkaP_0iS.js";
+import { t as AuthSession } from "../view-SuASaomx.js";
+import { a as BroadcastOptions, c as LiveCountHookOptions, d as PresenceHookOptions, f as PresenceTopic, i as ActionState, l as LiveCountSource, m as UseActionOptions, n as ActionInputOf, o as ClaimsOf, p as ProfileOf, r as ActionResultOf, s as ClientLike, t as fieldErrorsOf, u as LiveQueryHookOptions } from "../field-errors-nFnYWvB0.js";
+import { t as SupportView } from "../support-view-CznLe4jq.js";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { App, ComputedRef, MaybeRefOrGetter, Ref } from "vue";
 import { QueryClient } from "@tanstack/query-core";

package/dist/vue/index.js

@@ -1,10 +1,10 @@
 import { t as clearOnUserChange } from "../user-change-XzvgafU4.js";
-import { a as createActionRunner, c as liveKey, d as shownCount, f as startBroadcast, i as countSource, l as notJoined, m as startLiveQuery, n as assertInvalidateClient, o as joinPresence, p as startLiveCount, r as callerOf, s as keyed, t as NO_COUNT, u as plainCaller } from "../client-wxeTQFtB.js";
+import { a as createActionRunner, c as liveKey, d as shownCount, f as startBroadcast, i as countSource, l as notJoined, m as startLiveQuery, n as assertInvalidateClient, o as joinPresence, p as startLiveCount, r as callerOf, s as keyed, t as NO_COUNT, u as plainCaller } from "../client-CvITjt-9.js";
 import { t as supportOf } from "../support-view-g4YLBeqX.js";
 import { t as fieldErrorsOf } from "../field-errors-DZVRWRkf.js";
-import { computed, getCurrentInstance, getCurrentScope, inject, onMounted, onScopeDispose, provide, readonly, shallowRef, toValue, watch } from "vue";
+import { n as onClient, r as useContext, t as CLIENT } from "../context-D6ZMKc2L.js";
+import { computed, getCurrentScope, inject, onScopeDispose, provide, readonly, shallowRef, toValue, watch } from "vue";
 //#region src/vue/index.ts
-const CLIENT = Symbol("better-supabase");
 const SESSION = Symbol("better-supabase-session");
 /**
 * The Vue plugin: provides the client to the composables and, with a
@@ -31,19 +31,6 @@ function betterSupabase(client, options = {}) {
 		});
 	} };
 }
-function useContext() {
-	const context = inject(CLIENT, null);
-	if (!context) throw new Error("better-supabase: install the plugin with app.use(betterSupabase(bs))");
-	return context;
-}
-/**
-* Runs `start` on mount in a component, at once elsewhere (an effect
-* scope), and never during server rendering.
-*/
-function onClient(start) {
-	if (getCurrentInstance()) onMounted(start);
-	else start();
-}
 /** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
 function useAuth() {
 	return useContext().auth;

package/dist/vue-controller-C9tFzqAc.js

@@ -0,0 +1,32 @@
+import { n as onClient, r as useContext } from "./context-D6ZMKc2L.js";
+import { n as withEnv, t as blockEnv } from "./block-env-CBd_SoL5.js";
+import { getCurrentScope, onScopeDispose, shallowRef } from "vue";
+//#region src/blocks/vue-controller.ts
+/**
+* Makes a controller once and keeps `state` current. Its work starts on
+* mount (at once in an effect scope, never during server rendering), and the
+* controller is disposed with the component or scope.
+*/
+function useBlockController(create, options, usesEnv = true) {
+	const controller = create(withEnv(options, usesEnv ? () => blockEnv(useContext().client) : void 0));
+	const state = shallowRef(controller.getSnapshot());
+	let unsubscribe;
+	onClient(() => {
+		const sync = () => {
+			state.value = controller.getSnapshot();
+		};
+		unsubscribe = controller.subscribe(sync);
+		sync();
+	});
+	if (getCurrentScope()) onScopeDispose(() => {
+		unsubscribe?.();
+		controller.dispose();
+	});
+	return {
+		state,
+		actions: controller.actions,
+		controller
+	};
+}
+//#endregion
+export { useBlockController as t };

package/dist/vue-controller-D_ohttBZ.d.ts

@@ -0,0 +1,11 @@
+import { n as Controller } from "./controller-CCb9tHw_.js";
+import { ShallowRef } from "vue";
+//#region src/blocks/vue-controller.d.ts
+/** A block controller in a Vue component: `state` follows the controller. */
+interface VueController<S, A> {
+  readonly state: Readonly<ShallowRef<S>>;
+  readonly actions: A;
+  readonly controller: Controller<S, A>;
+}
+//#endregion
+export { VueController as t };

package/dist/watch-Blj1mQ9n.js

@@ -0,0 +1,139 @@
+import { r as isPlainObject } from "./clone-dN9XOL1K.js";
+import { r as err, s as toDbError } from "./result-COkvI9t5.js";
+//#region src/core/share.ts
+function sameValue(prev, next) {
+	if (Object.is(prev, next)) return true;
+	if (typeof prev !== "object" || typeof next !== "object") return false;
+	if (prev === null || next === null) return false;
+	return Object.getPrototypeOf(prev) === Object.getPrototypeOf(next) && !Array.isArray(prev) && !isPlainObject(prev) && "toJSON" in prev && typeof prev.toJSON === "function" && JSON.stringify(prev) === JSON.stringify(next);
+}
+function idOf(value) {
+	return isPlainObject(value) ? value["id"] : void 0;
+}
+/**
+* `next` with every part that equals `prev` replaced by `prev`'s object, so
+* unchanged rows keep their identity and `memo` skips them. Array items
+* match by their `id` when they have one (a reordered list keeps its rows),
+* else by position. Returns `prev` itself when nothing changed.
+*/
+function shareStructure(prev, next) {
+	if (sameValue(prev, next)) return prev;
+	if (Array.isArray(prev) && Array.isArray(next)) {
+		const before = prev;
+		const after = next;
+		const byId = /* @__PURE__ */ new Map();
+		for (const item of before) {
+			const id = idOf(item);
+			if (id !== void 0) byId.set(id, item);
+		}
+		let same = before.length === after.length;
+		const shared = after.map((item, index) => {
+			const id = idOf(item);
+			const value = shareStructure(id === void 0 ? before[index] : byId.get(id), item);
+			if (value !== before[index]) same = false;
+			return value;
+		});
+		return same ? prev : shared;
+	}
+	if (isPlainObject(prev) && isPlainObject(next)) {
+		const keys = Object.keys(next);
+		let same = keys.length === Object.keys(prev).length;
+		const shared = {};
+		for (const key of keys) {
+			const value = shareStructure(prev[key], next[key]);
+			if (!Object.hasOwn(prev, key) || value !== prev[key]) same = false;
+			shared[key] = value;
+		}
+		return same ? prev : shared;
+	}
+	return next;
+}
+//#endregion
+//#region src/powersync/watch.ts
+/**
+* Reruns a repository call whenever PowerSync reports a change to one of
+* `tables`: local writes and synced rows alike. The same call works with
+* lists, aggregates and single rows. Unchanged rows keep their identity
+* between runs, and a run that changes nothing calls no `onResult`. Returns
+* a function that stops it.
+*
+* ```ts
+* const stop = watch(powersync, () => customerList.run(db, query), {
+*   tables: ['customers'],
+*   onResult: (page) => render(page),
+* });
+* ```
+*/
+function watch(db, query, options) {
+	if (!db.onChange) throw new TypeError("better-supabase: watch() needs a PowerSync database with onChange()");
+	const refresh = options.refresh ?? {};
+	if (refresh.onReconnect && !db.registerListener) throw new TypeError("better-supabase: watch() refresh.onReconnect needs a PowerSync database with registerListener()");
+	const signal = options.signal;
+	if (signal?.aborted) return () => void 0;
+	const controller = new AbortController();
+	const stop = () => {
+		controller.abort();
+	};
+	signal?.addEventListener("abort", stop, { once: true });
+	let latest = 0;
+	let previous;
+	const sharing = options.structuralSharing ?? true;
+	const rerun = async () => {
+		latest += 1;
+		const run = latest;
+		let result;
+		try {
+			result = await query();
+		} catch (cause) {
+			result = err(toDbError(cause));
+		}
+		if (run !== latest || controller.signal.aborted) return;
+		if (sharing) {
+			const shared = shareStructure(previous, result);
+			if (shared === previous) return;
+			result = shared;
+		}
+		previous = result;
+		options.onResult(result);
+	};
+	rerun();
+	const unsubscribe = db.onChange({ onChange: rerun }, {
+		tables: [...options.tables],
+		signal: controller.signal,
+		...options.throttleMs === void 0 ? {} : { throttleMs: options.throttleMs }
+	});
+	const timer = refresh.everyMs === void 0 ? void 0 : setInterval(() => {
+		if (db.currentStatus?.connected === false) return;
+		rerun();
+	}, refresh.everyMs);
+	let connected = db.currentStatus?.connected ?? true;
+	const unlisten = refresh.onReconnect && db.registerListener ? db.registerListener({ statusChanged: (status) => {
+		const reconnected = status.connected && !connected;
+		connected = status.connected;
+		if (reconnected) rerun();
+	} }) : void 0;
+	const cleanup = () => {
+		clearInterval(timer);
+		unlisten?.();
+	};
+	controller.signal.addEventListener("abort", cleanup, { once: true });
+	return () => {
+		signal?.removeEventListener("abort", stop);
+		stop();
+		unsubscribe();
+	};
+}
+/**
+* The SQLite table names of app table keys (`customerTags` to
+* `customer_tags`). Pass the executor's `tableName` when it renames tables,
+* so `watch` listens to the names the queries read.
+*/
+function sqliteTables(betterSupabase, keys, options = {}) {
+	return keys.map((key) => {
+		const table = betterSupabase.meta.tables[key];
+		if (!table) throw new TypeError(`better-supabase: unknown table "${key}"`);
+		return options.tableName ? options.tableName(table) : table.name;
+	});
+}
+//#endregion
+export { watch as n, sqliteTables as t };

package/dist/watch-D1wwzZ04.d.ts

@@ -0,0 +1,84 @@
+import { b as DbError, f as Result } from "./result-Cj3yWhjH.js";
+import { P as SchemaMeta, a as AnyModels, i as AnyFunctions, z as TableKey } from "./types-BO8lVTun.js";
+import { t as BetterSupabase } from "./define-DXTC706J.js";
+import { i as ListDefinition } from "./list-query-DWJIiVz_.js";
+import { c as SqliteCompilerOptions, p as SqlitePlan, t as PowerSyncDatabaseLike } from "./executor-CIxyatuB.js";
+import { t as Compiler } from "./compiler-C6E3WwIi.js";
+//#region src/powersync/compiler.d.ts
+declare const sqliteCompiler: Compiler<SqlitePlan>;
+interface CheckSqliteOptions extends SqliteCompilerOptions {
+  /**
+   * Return every error instead of the first, one per distinct message. With
+   * a `fallback` executor, these are the reads that run on the server.
+   */
+  readonly all?: boolean;
+}
+/**
+ * Compiles every operation a list definition runs (the page, its count and
+ * the facet counts) for SQLite, without a database. Returns the first
+ * `unsupported` or `invalid_request` error, so a test or a dev build fails
+ * before a native screen does. With `all: true`, returns every error, an
+ * empty array when the whole list runs on SQLite.
+ *
+ * ```ts
+ * expect(await checkSqlite(betterSupabase, customerList)).toEqual({ ok: true, data: undefined });
+ * expect(await checkSqlite(betterSupabase, customerList, { all: true })).toEqual([]);
+ * ```
+ */
+declare function checkSqlite<M extends AnyModels, D, F extends AnyFunctions, E, T extends TableKey<M>, S extends string, Fa extends string, C extends boolean, P extends "offset" | "cursor">(betterSupabase: BetterSupabase<M, D, F, E>, list: ListDefinition<M, T, E, S, Fa, C, P>, options: CheckSqliteOptions & {
+  readonly all: true;
+}): Promise<readonly DbError[]>;
+declare function checkSqlite<M extends AnyModels, D, F extends AnyFunctions, E, T extends TableKey<M>, S extends string, Fa extends string, C extends boolean, P extends "offset" | "cursor">(betterSupabase: BetterSupabase<M, D, F, E>, list: ListDefinition<M, T, E, S, Fa, C, P>, options?: CheckSqliteOptions & {
+  readonly all?: false;
+}): Promise<Result<undefined>>;
+//#endregion
+//#region src/powersync/watch.d.ts
+interface WatchOptions<T> {
+  /** SQLite tables whose changes rerun the query (`sqliteTables()` maps app keys). */
+  readonly tables: readonly string[];
+  /** Called with the first result, then after every change to `tables`. */
+  readonly onResult: (result: Result<T>) => void;
+  readonly signal?: AbortSignal;
+  /** The least time between two runs. Defaults to PowerSync's 30 ms. */
+  readonly throttleMs?: number;
+  /**
+   * Keeps unchanged rows' object identity across runs and skips `onResult`
+   * when a run returns what the last one did. Defaults to true.
+   */
+  readonly structuralSharing?: boolean;
+  /**
+   * Reruns that don't wait for a local change, for reads that run on the
+   * executor's server `fallback`: `everyMs` reruns on an interval (skipped
+   * while PowerSync reports it is offline), and `onReconnect` reruns when
+   * PowerSync connects again. `onReconnect` needs `registerListener()`.
+   */
+  readonly refresh?: {
+    readonly everyMs?: number;
+    readonly onReconnect?: boolean;
+  };
+}
+/**
+ * Reruns a repository call whenever PowerSync reports a change to one of
+ * `tables`: local writes and synced rows alike. The same call works with
+ * lists, aggregates and single rows. Unchanged rows keep their identity
+ * between runs, and a run that changes nothing calls no `onResult`. Returns
+ * a function that stops it.
+ *
+ * ```ts
+ * const stop = watch(powersync, () => customerList.run(db, query), {
+ *   tables: ['customers'],
+ *   onResult: (page) => render(page),
+ * });
+ * ```
+ */
+declare function watch<T>(db: PowerSyncDatabaseLike, query: () => PromiseLike<Result<T>>, options: WatchOptions<T>): () => void;
+/**
+ * The SQLite table names of app table keys (`customerTags` to
+ * `customer_tags`). Pass the executor's `tableName` when it renames tables,
+ * so `watch` listens to the names the queries read.
+ */
+declare function sqliteTables(betterSupabase: {
+  readonly meta: SchemaMeta;
+}, keys: readonly string[], options?: SqliteCompilerOptions): string[];
+//#endregion
+export { checkSqlite as a, CheckSqliteOptions as i, sqliteTables as n, sqliteCompiler as o, watch as r, WatchOptions as t };