better-supabase 0.0.0 → 0.1.0

package/dist/react/server.d.ts

@@ -0,0 +1,13 @@
+import { t as AuthSession } from "../view-B0ltUmTi.js";
+import { n as SessionProviderProps, t as SessionProvider } from "../session-C3osL21k.js";
+import { a as BrowserLike, d as useAuth, f as useBroadcast, h as useSupabase, i as BroadcastOptions, l as LiveQueryHookOptions, m as useLiveQuery, n as BetterSupabaseProvider, o as ClaimsOf, r as BetterSupabaseProviderProps, t as BetterHooks } from "../index-Hf8PP9sP.js";
+//#region src/react/server.d.ts
+/** The `react-server` build of `useSession`: await `next.session()` instead. */
+export declare const useSession: <C = unknown>() => AuthSession<C>;
+/**
+ * The `react-server` build of `createHooks`: importing a module that creates
+ * hooks is safe on the server, calling a hook there throws.
+ */
+export declare function createHooks<B extends BrowserLike>(): BetterHooks<B>;
+//#endregion
+export { type AuthSession, type BetterHooks, BetterSupabaseProvider, type BetterSupabaseProviderProps, type BroadcastOptions, type BrowserLike, type ClaimsOf, type LiveQueryHookOptions, SessionProvider, type SessionProviderProps, useAuth, useBroadcast, useLiveQuery, useSupabase };

package/dist/react/server.js

@@ -0,0 +1,25 @@
+import { i as useBroadcast, o as useLiveQuery, r as useAuth, s as useSupabase, t as BetterSupabaseProvider } from "../react-CrOvrnIP.js";
+import { SessionProvider } from "./session.js";
+//#region src/react/server.ts
+function clientOnly(name) {
+	return () => {
+		throw new Error(`better-supabase: ${name}() runs in Client Components only. In Server Components use \`next.server()\` or \`db.$run(spec)\`.`);
+	};
+}
+/** The `react-server` build of `useSession`: await `next.session()` instead. */
+const useSession = clientOnly("useSession");
+/**
+* The `react-server` build of `createHooks`: importing a module that creates
+* hooks is safe on the server, calling a hook there throws.
+*/
+function createHooks() {
+	return {
+		useDb: clientOnly("useDb"),
+		useQueries: clientOnly("useQueries"),
+		useSupabase: clientOnly("useSupabase"),
+		useAuth: clientOnly("useAuth"),
+		useSession: clientOnly("useSession")
+	};
+}
+//#endregion
+export { BetterSupabaseProvider, SessionProvider, createHooks, useAuth, useBroadcast, useLiveQuery, useSession, useSupabase };

package/dist/react/session.d.ts

@@ -0,0 +1,2 @@
+import { n as SessionProviderProps, r as useSession, t as SessionProvider } from "../session-C3osL21k.js";
+export { SessionProvider, SessionProviderProps, useSession };

package/dist/react/session.js

@@ -0,0 +1,3 @@
+"use client";
+import { n as useSession, t as SessionProvider } from "../session-CD-3orO_.js";
+export { SessionProvider, useSession };

package/dist/react-CrOvrnIP.js

@@ -0,0 +1,241 @@
+import { t as invalidateTables } from "./invalidate-DbxuL2jL.js";
+import { n as liveQuery, t as liveCount } from "./live-D8rV1Ldw.js";
+import { n as useSession } from "./session-CD-3orO_.js";
+import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+//#region src/react/index.ts
+const BrowserContext = createContext(null);
+const LOADING = {
+	status: "loading",
+	user: null,
+	claims: null
+};
+/** Provides the browser client to the hooks. */
+function BetterSupabaseProvider(props) {
+	const { browser, queryClient } = props;
+	const user = useRef(void 0);
+	useEffect(() => browser.auth.subscribe(() => {
+		const snapshot = browser.auth.current();
+		if (snapshot.status === "loading") return;
+		const id = snapshot.user?.id ?? null;
+		if (user.current !== void 0 && user.current !== id) queryClient?.removeQueries({ queryKey: ["bs"] });
+		user.current = id;
+	}), [browser, queryClient]);
+	const value = useMemo(() => ({
+		browser,
+		queryClient
+	}), [browser, queryClient]);
+	return createElement(BrowserContext.Provider, { value }, props.children);
+}
+function useBrowserContext() {
+	const value = useContext(BrowserContext);
+	if (!value) throw new Error("better-supabase: wrap your app in <BetterSupabaseProvider browser={browser}>");
+	return value;
+}
+function useBrowser() {
+	return useBrowserContext().browser;
+}
+/** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
+function useAuth() {
+	const browser = useBrowser();
+	return useSyncExternalStore(browser.auth.subscribe, browser.auth.current, () => LOADING);
+}
+function useSupabase() {
+	return useBrowser().supabase;
+}
+/**
+* Hooks typed for your schema.
+*
+* ```ts
+* export const { useDb, useQueries, useAuth } = createHooks<typeof browser>();
+* ```
+*/
+function createHooks() {
+	return {
+		useDb() {
+			const browser = useBrowser();
+			useAuth();
+			return browser.db;
+		},
+		useQueries() {
+			const browser = useBrowser();
+			useAuth();
+			return browser.queries;
+		},
+		useSupabase,
+		useAuth,
+		useSession
+	};
+}
+/**
+* Subscribes to a topic while mounted. Pass `null` values to pause. It
+* resubscribes when the topic or the signed-in user changes.
+*
+* ```ts
+* useBroadcast(customersTopic, orgId ? { orgId } : null, {}, { invalidate: ['customers'] });
+* ```
+*/
+function useBroadcast(topic, values, handlers, options) {
+	const { browser, queryClient } = useBrowserContext();
+	const auth = useAuth();
+	const [status, setStatus] = useState("closed");
+	const latest = useRef({
+		handlers,
+		options
+	});
+	latest.current = {
+		handlers,
+		options
+	};
+	const name = values ? topic.topic(values) : null;
+	const userId = auth.user?.id ?? null;
+	if (options?.invalidate && !queryClient) throw new Error("better-supabase: useBroadcast({ invalidate }) needs <BetterSupabaseProvider queryClient={...}>");
+	useEffect(() => {
+		if (!name || auth.status === "loading") return void 0;
+		const matched = topic.match(name);
+		if (!matched) return void 0;
+		const forward = (payload, message) => {
+			const current = latest.current;
+			const table = current.handlers;
+			(table?.[message.event] ?? table?.["*"])?.(payload, message);
+			const invalidate = current.options?.invalidate;
+			if (!invalidate || !queryClient) return;
+			if (typeof invalidate !== "function") {
+				invalidateTables(queryClient, invalidate);
+				return;
+			}
+			for (const queryKey of invalidate(message)) queryClient.invalidateQueries({ queryKey });
+		};
+		const subscription = topic.subscribe(browser.supabase, matched, { "*": forward }, {
+			...latest.current.options?.self === void 0 ? {} : { self: latest.current.options.self },
+			onStatus: setStatus,
+			onInvalid: (message, issues) => latest.current.options?.onInvalid?.(message, issues)
+		});
+		return () => {
+			subscription.unsubscribe();
+			setStatus("closed");
+		};
+	}, [
+		browser,
+		topic,
+		name,
+		userId,
+		auth.status,
+		queryClient
+	]);
+	return status;
+}
+function claimedTenant(auth) {
+	if (auth.status !== "signed-in") return void 0;
+	const top = auth.claims["org_id"];
+	if (typeof top === "string") return top;
+	const app = auth.claims["app_metadata"];
+	return typeof app?.["org_id"] === "string" ? app["org_id"] : void 0;
+}
+/**
+* Keeps a query fresh: invalidates every cached query that read a table the
+* spec touches whenever one of them changes. Pass `null` to pause. It
+* resubscribes when the spec, tenant or user changes.
+*
+* ```ts
+* const spec = sb.spec.customers.findMany({ include: { notes: true } });
+* const { data } = useQuery(q.$spec(spec));
+* useLiveQuery(spec);
+* ```
+*/
+function useLiveQuery(spec, options = {}) {
+	const { browser, queryClient } = useBrowserContext();
+	const auth = useAuth();
+	const [status, setStatus] = useState("closed");
+	if (spec && !queryClient) throw new Error("better-supabase: useLiveQuery needs <BetterSupabaseProvider queryClient={...}>");
+	const key = spec ? JSON.stringify(spec) : null;
+	const tenant = options.tenant ?? claimedTenant(auth);
+	const userId = auth.user?.id ?? null;
+	const debounceMs = options.debounceMs;
+	useEffect(() => {
+		if (!key || !queryClient || auth.status === "loading") return void 0;
+		const live = liveQuery(browser.sb, browser.supabase, JSON.parse(key), {
+			onChange: (tables) => void invalidateTables(queryClient, tables),
+			onStatus: setStatus,
+			...tenant === void 0 ? {} : { tenant },
+			...debounceMs === void 0 ? {} : { debounceMs }
+		});
+		return () => {
+			live.unsubscribe();
+		};
+	}, [
+		browser,
+		queryClient,
+		key,
+		tenant,
+		userId,
+		auth.status,
+		debounceMs
+	]);
+	return status;
+}
+/**
+* A count that stays current: refetches only the `count` spec (a HEAD
+* request) after each debounced change to a table it reads, and after the
+* channel rejoins. Takes a spec or a `next.liveCount()` seed; pass `null` to
+* pause. Doesn't need a `QueryClient`.
+*
+* ```tsx
+* const { count } = useLiveCount(seed); // seed = await next.liveCount(spec)
+* ```
+*/
+function useLiveCount(source, options = {}) {
+	const { browser } = useBrowserContext();
+	const auth = useAuth();
+	const seed = source && "spec" in source ? source : void 0;
+	const spec = seed ? seed.spec : source;
+	const initial = seed?.count ?? options.initial;
+	const [state, setState] = useState({
+		key: null,
+		count: void 0,
+		error: void 0
+	});
+	const [status, setStatus] = useState("closed");
+	const key = spec ? JSON.stringify(spec) : null;
+	const tenant = options.tenant ?? claimedTenant(auth);
+	const userId = auth.user?.id ?? null;
+	const debounceMs = options.debounceMs;
+	const hasInitial = initial !== void 0;
+	useEffect(() => {
+		if (!key || auth.status === "loading") return void 0;
+		const live = liveCount(browser.sb, browser.supabase, browser.db, JSON.parse(key), {
+			immediate: !hasInitial,
+			onCount: (count) => setState({
+				key,
+				count,
+				error: void 0
+			}),
+			onError: (error) => setState((previous) => ({
+				key,
+				count: previous.key === key ? previous.count : void 0,
+				error
+			})),
+			onStatus: setStatus,
+			...tenant === void 0 ? {} : { tenant },
+			...debounceMs === void 0 ? {} : { debounceMs }
+		});
+		return () => {
+			live.unsubscribe();
+		};
+	}, [
+		browser,
+		key,
+		tenant,
+		userId,
+		auth.status,
+		debounceMs,
+		hasInitial
+	]);
+	const fresh = state.key === key;
+	return {
+		count: fresh && state.count !== void 0 ? state.count : initial,
+		status,
+		error: fresh ? state.error : void 0
+	};
+}
+//#endregion
+export { useLiveCount as a, useBroadcast as i, createHooks as n, useLiveQuery as o, useAuth as r, useSupabase as s, BetterSupabaseProvider as t };

package/dist/read-set-DhX2d04c.js

@@ -0,0 +1,216 @@
+import { r as IrBuilder, u as tableMeta } from "./simplify-oHiDKRVQ.js";
+import { n as touchedTables } from "./tables-rZxRxNPW.js";
+//#region src/core/spec.ts
+const READ_METHODS = [
+	"findMany",
+	"findFirst",
+	"findUnique",
+	"findById",
+	"count",
+	"aggregate",
+	"exists",
+	"paginate"
+];
+function createSpecs(meta) {
+	const specs = {};
+	for (const table of Object.keys(meta.tables)) {
+		const methods = {};
+		for (const method of READ_METHODS) methods[method] = (...args) => ({
+			v: 1,
+			table,
+			method,
+			args: trimUndefined(args)
+		});
+		specs[table] = methods;
+	}
+	return specs;
+}
+function trimUndefined(args) {
+	const out = [...args];
+	while (out.length > 0 && out.at(-1) === void 0) out.pop();
+	return out;
+}
+function isQuerySpec(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const spec = value;
+	return spec.v === 1 && typeof spec.table === "string" && READ_METHODS.includes(spec.method) && Array.isArray(spec.args);
+}
+/** The argument object of a spec's method (`findById` takes it second). */
+function specOptions(spec) {
+	const value = spec.method === "findById" ? spec.args[1] : spec.args[0];
+	return typeof value === "object" && value !== null ? value : void 0;
+}
+const builders = /* @__PURE__ */ new WeakMap();
+/**
+* App keys of every table a spec reads: its table, included relations and
+* relations used in `where`. Queries keyed by a spec go stale when any of
+* them changes. Invalid arguments yield just the spec's table; running the
+* spec reports the error.
+*/
+function specTables(meta, spec) {
+	try {
+		return readTables(meta, spec);
+	} catch {
+		return [spec.table];
+	}
+}
+function readTables(meta, spec) {
+	let builder = builders.get(meta);
+	if (!builder) {
+		builder = new IrBuilder(meta);
+		builders.set(meta, builder);
+	}
+	const table = tableMeta(meta, spec.table);
+	const args = specOptions(spec);
+	const counts = spec.method === "count" || spec.method === "exists" || spec.method === "aggregate";
+	return touchedTables({
+		kind: "select",
+		table,
+		selection: counts ? {
+			columns: [],
+			includes: []
+		} : builder.selection(table, args?.["select"], args?.["include"]),
+		where: builder.where(table, args?.["where"]),
+		orderBy: [],
+		limit: void 0,
+		offset: void 0,
+		count: void 0,
+		head: counts,
+		single: void 0
+	});
+}
+//#endregion
+//#region src/core/read-set.ts
+const NAME = /^[a-z][a-z0-9_]{0,59}$/;
+const PARAM = /^[a-z_][a-z0-9_]*$/i;
+const TYPE = /^(?:[a-z_][a-z0-9_]*\.)?[a-z_][a-z0-9_]*(?:\[\])?$/;
+/** `jsonb_build_object` takes at most 100 arguments. */
+const MAX_ENTRIES = 50;
+/** Placeholders are `NUL bs:<name> NUL`: no real parameter value holds a NUL. */
+const NUL = String.fromCharCode(0);
+const SENTINEL = new RegExp(`${NUL}bs:([a-z_][a-z0-9_]*)${NUL}`, "gi");
+const EXACT = new RegExp(`^${NUL}bs:([a-z_][a-z0-9_]*)${NUL}$`, "i");
+function sentinel(name) {
+	return `${NUL}bs:${name}${NUL}`;
+}
+/**
+* Registers reads that run as one round trip:
+*
+* ```ts
+* export const appChrome = defineReadSet(
+*   sb,
+*   'app_chrome',
+*   { params: { userId: 'uuid' } },
+*   (s, p) => ({
+*     unread: s.notifications.count({ where: { userId: p.userId, readAt: null } }),
+*     me: s.profiles.findFirst({ where: { id: p.userId } }),
+*   }),
+* );
+* ```
+*
+* `p` holds placeholders, not values: pass them straight into `where` (or
+* `in`), where the function reads them from its `p jsonb` argument.
+*/
+function defineReadSet(sb, name, options, build) {
+	if (!NAME.test(name)) throw new TypeError(`better-supabase: read set name "${name}" must be snake_case and at most 60 characters`);
+	const params = options.params ?? {};
+	const placeholders = {};
+	for (const [key, type] of Object.entries(params)) {
+		if (!PARAM.test(key)) throw new TypeError(`better-supabase: read set "${name}" has an invalid parameter name "${key}"`);
+		if (!TYPE.test(type)) throw new TypeError(`better-supabase: read set "${name}" parameter "${key}" has an invalid type "${type}"`);
+		placeholders[key] = type.endsWith("[]") ? [sentinel(key)] : sentinel(key);
+	}
+	const specs = build(sb.spec, placeholders);
+	const entries = Object.entries(specs);
+	if (entries.length === 0 || entries.length > MAX_ENTRIES) throw new TypeError(`better-supabase: read set "${name}" needs between 1 and ${MAX_ENTRIES} reads`);
+	for (const [key, spec] of entries) if (!isQuerySpec(spec)) throw new TypeError(`better-supabase: read set "${name}" entry "${key}" is not a spec from sb.spec`);
+	return {
+		kind: "read-set",
+		name,
+		functionName: `rs_${name}`,
+		params,
+		roles: options.roles ?? ["authenticated"],
+		specs,
+		definition: sb
+	};
+}
+function isReadSet(value) {
+	return typeof value === "object" && value !== null && value.kind === "read-set" && typeof value.name === "string";
+}
+/** A parameter a string or array carries, if it is exactly a placeholder. */
+function placeholderOf(value) {
+	if (typeof value === "string") {
+		const match = EXACT.exec(value);
+		return match ? {
+			name: match[1],
+			array: false
+		} : void 0;
+	}
+	if (Array.isArray(value) && value.length === 1) {
+		const inner = placeholderOf(value[0]);
+		return inner && !inner.array ? {
+			name: inner.name,
+			array: true
+		} : inner;
+	}
+}
+/** Splits a string around the placeholders inside it. */
+function splitPlaceholders(value) {
+	const parts = [];
+	let last = 0;
+	for (const match of value.matchAll(SENTINEL)) {
+		if (match.index > last) parts.push({ text: value.slice(last, match.index) });
+		parts.push({ param: match[1] });
+		last = match.index + match[0].length;
+	}
+	if (last < value.length) parts.push({ text: value.slice(last) });
+	return parts;
+}
+function hasPlaceholder(value) {
+	return value.includes(`${NUL}bs:`);
+}
+/** Whether any string inside `value` is (or holds) a placeholder. */
+function containsPlaceholder(value) {
+	if (typeof value === "string") return hasPlaceholder(value);
+	if (Array.isArray(value)) return value.some(containsPlaceholder);
+	if (typeof value === "object" && value !== null) return Object.values(value).some(containsPlaceholder);
+	return false;
+}
+/** Missing or wrongly typed parameters, as messages. */
+function checkParams(set, values) {
+	const problems = [];
+	for (const [key, type] of Object.entries(set.params)) {
+		const value = values?.[key];
+		if (value === void 0 || value === null) problems.push(`missing parameter "${key}"`);
+		else if (type.endsWith("[]") !== Array.isArray(value)) problems.push(`parameter "${key}" must be ${type.endsWith("[]") ? "an array" : "a single value"}`);
+	}
+	return problems;
+}
+/** The specs with every placeholder replaced by its value. */
+function bindParams(set, values) {
+	const bind = (value) => {
+		const placeholder = placeholderOf(value);
+		if (placeholder) return values[placeholder.name];
+		if (typeof value === "string") {
+			if (!hasPlaceholder(value)) return value;
+			return splitPlaceholders(value).map((part) => "text" in part ? part.text : String(values[part.param] ?? "")).join("");
+		}
+		if (Array.isArray(value)) return value.map(bind);
+		if (typeof value === "object" && value !== null) {
+			if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+			return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, bind(entry)]));
+		}
+		return value;
+	};
+	return Object.fromEntries(Object.entries(set.specs).map(([key, spec]) => [key, {
+		...spec,
+		args: spec.args.map(bind)
+	}]));
+}
+/** App keys of every table the set reads. */
+function readSetTables(set, meta) {
+	const schema = meta ?? set.definition.meta;
+	return [...new Set(Object.values(set.specs).flatMap((spec) => specTables(schema, spec)))];
+}
+//#endregion
+export { hasPlaceholder as a, readSetTables as c, isQuerySpec as d, specTables as f, defineReadSet as i, splitPlaceholders as l, checkParams as n, isReadSet as o, containsPlaceholder as r, placeholderOf as s, bindParams as t, createSpecs as u };

package/dist/realtime/index.d.ts

@@ -0,0 +1,3 @@
+import { n as TemplateValues, t as TemplateParams } from "../template-mbvlysOo.js";
+import { C as defineTopic, S as TriggerOptions, _ as TopicEvent, a as LiveSource, b as TopicOptions, c as liveQuery, d as RealtimeClient, f as RowChange, g as Topic, h as SubscriptionStatus, i as LiveQueryOptions, l as liveTopic, m as Subscription, n as LiveCountOptions, o as LiveSubscription, p as SubscribeOptions, r as LiveCountSeed, s as liveCount, t as CountRunner, u as EventSchemas, v as TopicHandlers, w as rowChange, x as TopicPayload, y as TopicMessage } from "../live-6b9i72Ux.js";
+export { type CountRunner, EventSchemas, type LiveCountOptions, type LiveCountSeed, type LiveQueryOptions, type LiveSource, type LiveSubscription, RealtimeClient, RowChange, SubscribeOptions, Subscription, SubscriptionStatus, type TemplateParams, type TemplateValues, Topic, TopicEvent, TopicHandlers, TopicMessage, TopicOptions, TopicPayload, TriggerOptions, defineTopic, liveCount, liveQuery, liveTopic, rowChange };