better-supabase 0.0.0 → 0.2.0

package/dist/list/index.js

@@ -0,0 +1,410 @@
+//#region src/list/index.ts
+/** Facet value meaning "not set": filters with `is null`. */
+const UNSET = "__unset__";
+const RESERVED = /* @__PURE__ */ new Set([
+	"q",
+	"sort",
+	"page",
+	"size"
+]);
+function first(value) {
+	return typeof value === "string" ? value : value?.[0];
+}
+function all(value) {
+	return (typeof value === "string" ? [value] : [...value ?? []]).flatMap((entry) => entry.split(",")).map((entry) => entry.trim()).filter(Boolean);
+}
+function isSearchParams(value) {
+	return value instanceof URLSearchParams || !("facets" in value && typeof value.facets === "object");
+}
+function readRecord(input) {
+	if (!(input instanceof URLSearchParams)) return input;
+	const out = {};
+	for (const [key, value] of input) (out[key] ??= []).push(value);
+	return out;
+}
+function toInt(raw) {
+	if (typeof raw === "number") return raw;
+	if (typeof raw !== "string" || !/^\d+$/.test(raw)) return NaN;
+	return Number(raw);
+}
+/**
+* A reusable list endpoint for one table: search, facets, sorts and
+* pagination, validated from URL params or typed input, with URL parsers,
+* OpenAPI parameters and a JSON Schema derived from the same definition.
+*
+* ```ts
+* export const customerList = defineListQuery(sb, 'customers', {
+*   search: ['name', 'kvk'],
+*   facets: { status: 'status' },
+*   sorts: { name: { name: 'asc' }, newest: [{ createdAt: 'desc' }, { id: 'asc' }] },
+*   defaultSort: 'newest',
+* });
+* ```
+*/
+function defineListQuery(sb, table, config) {
+	const meta = sb.meta.tables[table];
+	if (!meta) throw new TypeError(`defineListQuery: unknown table "${table}"`);
+	const pageSize = config.pageSize ?? 50;
+	const maxPageSize = config.maxPageSize ?? 200;
+	const maxSearch = config.maxSearchLength ?? 200;
+	const sortKeys = Object.keys(config.sorts);
+	const facetEntries = Object.entries(config.facets ?? {});
+	for (const [key, column] of facetEntries) {
+		if (RESERVED.has(key)) throw new TypeError(`defineListQuery: facet key "${key}" is reserved`);
+		if (!meta.columns[column]) throw new TypeError(`defineListQuery: unknown column "${table}.${column}"`);
+	}
+	if (!sortKeys.includes(config.defaultSort)) throw new TypeError(`defineListQuery: defaultSort "${config.defaultSort}" is not in sorts`);
+	const facets = facetEntries.map(([key, column]) => {
+		const columnMeta = meta.columns[column];
+		return {
+			key,
+			column,
+			nullable: columnMeta.nullable,
+			...columnMeta.enum ? { values: columnMeta.enum } : {}
+		};
+	});
+	const defaults = {
+		sort: config.defaultSort,
+		page: 1,
+		size: pageSize,
+		facets: {}
+	};
+	function normalize(raw) {
+		const issues = [];
+		let q;
+		if (raw.q !== void 0 && raw.q !== null) {
+			if (typeof raw.q !== "string") issues.push({
+				message: "Must be text",
+				path: ["q"]
+			});
+			else if (raw.q.trim().length > maxSearch) issues.push({
+				message: `At most ${String(maxSearch)} characters`,
+				path: ["q"]
+			});
+			else if (raw.q.trim()) q = raw.q.trim();
+		}
+		let sort = config.defaultSort;
+		if (raw.sort !== void 0 && raw.sort !== "") {
+			if (typeof raw.sort === "string" && sortKeys.includes(raw.sort)) sort = raw.sort;
+			else issues.push({
+				message: `Must be one of: ${sortKeys.join(", ")}`,
+				path: ["sort"]
+			});
+		}
+		const page = raw.page === void 0 || raw.page === "" ? 1 : toInt(raw.page);
+		if (page === void 0 || !Number.isInteger(page) || page < 1) issues.push({
+			message: "Must be a whole number of at least 1",
+			path: ["page"]
+		});
+		const size = raw.size === void 0 || raw.size === "" ? pageSize : toInt(raw.size);
+		if (size === void 0 || !Number.isInteger(size) || size < 1 || size > maxPageSize) issues.push({
+			message: `Must be a whole number from 1 to ${String(maxPageSize)}`,
+			path: ["size"]
+		});
+		const facetValues = {};
+		for (const facet of facets) {
+			const values = raw.facets[facet.key];
+			if (!values || values.length === 0) continue;
+			for (const value of values) if (!(value === "__unset__" ? facet.nullable : !facet.values || facet.values.includes(value))) issues.push({
+				message: value === "__unset__" ? "This filter cannot be empty" : `Must be one of: ${(facet.values ?? []).join(", ")}`,
+				path: ["facets", facet.key]
+			});
+			facetValues[facet.key] = [...new Set(values)];
+		}
+		if (issues.length > 0) return {
+			ok: false,
+			issues
+		};
+		return {
+			ok: true,
+			value: {
+				...q ? { q } : {},
+				sort,
+				page: page ?? 1,
+				size: size ?? pageSize,
+				facets: facetValues
+			}
+		};
+	}
+	function parse(input) {
+		if (input === void 0 || input === null) return {
+			ok: true,
+			value: defaults
+		};
+		if (typeof input !== "object") return {
+			ok: false,
+			issues: [{ message: "Expected an object or URL parameters" }]
+		};
+		if (isSearchParams(input)) {
+			const record = readRecord(input);
+			const facetValues = {};
+			for (const facet of facets) facetValues[facet.key] = all(record[facet.key]);
+			return normalize({
+				q: first(record["q"]),
+				sort: first(record["sort"]),
+				page: first(record["page"]),
+				size: first(record["size"]),
+				facets: facetValues
+			});
+		}
+		const typed = input;
+		const rawFacets = typed.facets ?? {};
+		for (const [key, value] of Object.entries(rawFacets)) if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) return {
+			ok: false,
+			issues: [{
+				message: "Must be a list of values",
+				path: ["facets", key]
+			}]
+		};
+		return normalize({
+			q: typed.q,
+			sort: typed.sort,
+			page: typed.page,
+			size: typed.size,
+			facets: rawFacets
+		});
+	}
+	function searchWhere(query) {
+		if (!query.q || !config.search) return void 0;
+		if (Array.isArray(config.search)) {
+			const columns = config.search;
+			if (columns.length === 0) return void 0;
+			return { OR: columns.map((column) => ({ [column]: { contains: query.q } })) };
+		}
+		const fts = config.search;
+		return { [fts.fts]: { search: fts.config ? {
+			query: query.q,
+			config: fts.config
+		} : query.q } };
+	}
+	function facetWhere(facet, values) {
+		if (!values || values.length === 0) return void 0;
+		const unset = values.includes(UNSET);
+		const set = values.filter((value) => value !== UNSET);
+		if (unset && set.length === 0) return { [facet.column]: null };
+		if (!unset) return { [facet.column]: { in: set } };
+		return { OR: [{ [facet.column]: { in: set } }, { [facet.column]: null }] };
+	}
+	function and(parts) {
+		const present = parts.filter((part) => part !== void 0);
+		if (present.length === 0) return void 0;
+		return present.length === 1 ? present[0] : { AND: present };
+	}
+	function where(query) {
+		return and([searchWhere(query), ...facets.map((facet) => facetWhere(facet, query.facets[facet.key]))]);
+	}
+	function args(query) {
+		const filter = where(query);
+		return {
+			...filter ? { where: filter } : {},
+			orderBy: config.sorts[query.sort],
+			page: query.page,
+			size: query.size,
+			count: config.count ?? "exact"
+		};
+	}
+	/** Whether a group's value passes the facet's selected values. */
+	function selects(value, selected) {
+		if (!selected || selected.length === 0) return true;
+		return value === null || value === void 0 ? selected.includes(UNSET) : selected.includes(String(value));
+	}
+	/**
+	* Per facet, rows per value under every other facet's selection: the
+	* usual faceted-search counts, where picking a value doesn't zero the
+	* other values of the same facet.
+	*/
+	function marginals(groups, query) {
+		const out = {};
+		for (const facet of facets) {
+			const counts = {};
+			for (const value of facet.values ?? []) counts[value] = 0;
+			for (const group of groups) {
+				if (!facets.every((other) => other === facet || selects(group[other.column], query.facets[other.key]))) continue;
+				const raw = group[facet.column];
+				const key = raw === null || raw === void 0 ? UNSET : String(raw);
+				counts[key] = (counts[key] ?? 0) + Number(group["_count"] ?? 0);
+			}
+			out[facet.key] = counts;
+		}
+		return out;
+	}
+	const listParser = {
+		parse: (value) => {
+			const values = all(value);
+			return values.length > 0 ? values : null;
+		},
+		serialize: (values) => values.join(",")
+	};
+	const intParser = {
+		parse: (value) => /^\d+$/.test(value) ? Number(value) : null,
+		serialize: String
+	};
+	const parsers = {
+		q: {
+			parse: (value) => value.trim() || null,
+			serialize: (value) => value
+		},
+		sort: {
+			parse: (value) => sortKeys.includes(value) ? value : null,
+			serialize: (value) => value
+		},
+		page: intParser,
+		size: intParser,
+		...Object.fromEntries(facets.map((facet) => [facet.key, listParser]))
+	};
+	const facetSchema = (facet) => ({
+		type: "array",
+		items: {
+			type: "string",
+			...facet.values ? { enum: [...facet.values, ...facet.nullable ? [UNSET] : []] } : {}
+		},
+		uniqueItems: true
+	});
+	const searchDescription = config.search ? Array.isArray(config.search) ? `Case-insensitive search in ${config.search.join(", ")}.` : "Full-text search (web search syntax)." : void 0;
+	return {
+		table,
+		defaults,
+		facets,
+		parse,
+		schema: { "~standard": {
+			version: 1,
+			vendor: "better-supabase",
+			validate(value) {
+				const result = parse(value);
+				return result.ok ? { value: result.value } : { issues: result.issues };
+			}
+		} },
+		toSearchParams(query) {
+			const params = new URLSearchParams();
+			if (query.q) params.set("q", query.q);
+			if (query.sort && query.sort !== config.defaultSort) params.set("sort", query.sort);
+			if (query.page && query.page !== 1) params.set("page", String(query.page));
+			if (query.size && query.size !== pageSize) params.set("size", String(query.size));
+			for (const facet of facets) {
+				const values = query.facets?.[facet.key];
+				if (values && values.length > 0) params.set(facet.key, values.join(","));
+			}
+			return params;
+		},
+		parsers,
+		nuqs: (createParser) => Object.fromEntries(Object.entries(parsers).map(([key, spec]) => [key, createParser(spec)])),
+		args,
+		run(db, query, extra) {
+			const base = args(query);
+			const { where: extraWhere, count, select: _select, include: _include, ...options } = extra ?? {};
+			const combined = and([extraWhere, base["where"]]);
+			const repository = db[table];
+			const page = repository.paginate({
+				...extra,
+				...base,
+				count: count ?? base["count"],
+				...combined ? { where: combined } : {}
+			});
+			if (!config.facetCounts) return page;
+			if (facets.length === 0) return page.map((data) => ({
+				...data,
+				facetCounts: {}
+			}));
+			const facetFilter = and([extraWhere, searchWhere(query)]);
+			const groups = repository.aggregate({
+				...options,
+				...facetFilter ? { where: facetFilter } : {},
+				groupBy: [...new Set(facets.map((facet) => facet.column))],
+				_count: true
+			});
+			return page.andThen((data) => groups.map((rows) => ({
+				...data,
+				facetCounts: marginals(rows, query)
+			})));
+		},
+		openapi: [
+			...searchDescription ? [{
+				name: "q",
+				in: "query",
+				required: false,
+				description: searchDescription,
+				schema: {
+					type: "string",
+					maxLength: maxSearch
+				}
+			}] : [],
+			{
+				name: "sort",
+				in: "query",
+				required: false,
+				description: `Ordering. Default \`${config.defaultSort}\`.`,
+				schema: {
+					type: "string",
+					enum: sortKeys,
+					default: config.defaultSort
+				}
+			},
+			{
+				name: "page",
+				in: "query",
+				required: false,
+				description: "1-based page number.",
+				schema: {
+					type: "integer",
+					minimum: 1,
+					default: 1
+				}
+			},
+			{
+				name: "size",
+				in: "query",
+				required: false,
+				description: "Page size.",
+				schema: {
+					type: "integer",
+					minimum: 1,
+					maximum: maxPageSize,
+					default: pageSize
+				}
+			},
+			...facets.map((facet) => ({
+				name: facet.key,
+				in: "query",
+				required: false,
+				description: `Filter on ${facet.column}. Comma-separated; any value matches.${facet.nullable ? ` \`${UNSET}\` matches empty.` : ""}`,
+				schema: facetSchema(facet),
+				style: "form",
+				explode: false
+			}))
+		],
+		jsonSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				...searchDescription ? { q: {
+					type: "string",
+					maxLength: maxSearch,
+					description: searchDescription
+				} } : {},
+				sort: {
+					type: "string",
+					enum: sortKeys,
+					default: config.defaultSort
+				},
+				page: {
+					type: "integer",
+					minimum: 1,
+					default: 1
+				},
+				size: {
+					type: "integer",
+					minimum: 1,
+					maximum: maxPageSize,
+					default: pageSize
+				},
+				...facets.length > 0 ? { facets: {
+					type: "object",
+					additionalProperties: false,
+					properties: Object.fromEntries(facets.map((facet) => [facet.key, facetSchema(facet)]))
+				} } : {}
+			}
+		}
+	};
+}
+//#endregion
+export { UNSET, defineListQuery };

package/dist/live-D8rV1Ldw.js

@@ -0,0 +1,168 @@
+import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
+//#region src/realtime/live.ts
+/** Topic a `realtime-tables` trigger broadcasts on: `bs:t:<schema>.<table>[:<tenant>]`. */
+function liveTopic(meta, table, tenant) {
+	const found = meta.tables[table];
+	if (!found) throw new TypeError(`better-supabase: unknown table "${table}"`);
+	const base = `bs:t:${found.schema}.${found.name}`;
+	if (!meta.realtime?.[table]?.tenant) return base;
+	if (tenant === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per tenant; pass \`tenant\` to watch it`);
+	return `${base}:${tenant}`;
+}
+const channels = /* @__PURE__ */ new WeakMap();
+function join(client, topic, listener) {
+	let byTopic = channels.get(client);
+	if (!byTopic) {
+		byTopic = /* @__PURE__ */ new Map();
+		channels.set(client, byTopic);
+	}
+	let shared = byTopic.get(topic);
+	if (!shared) {
+		const channel = client.channel(topic, { config: { private: true } });
+		const listeners = /* @__PURE__ */ new Set();
+		channel.on("broadcast", { event: "change" }, () => {
+			for (const notify of listeners) notify();
+		});
+		let joined = false;
+		const ready = (async () => {
+			await client.realtime.setAuth();
+			await new Promise((resolve, reject) => {
+				channel.subscribe((status, error) => {
+					switch (status) {
+						case REALTIME_SUBSCRIBE_STATES.SUBSCRIBED:
+							if (joined) for (const notify of listeners) notify();
+							joined = true;
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CLOSED:
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR:
+						case REALTIME_SUBSCRIBE_STATES.TIMED_OUT:
+							reject(error ?? /* @__PURE__ */ new Error(`Realtime ${status.toLowerCase()} on ${topic}`));
+							return;
+						default: reject(/* @__PURE__ */ new Error(`Unknown realtime status ${String(status)}`));
+					}
+				});
+			});
+		})();
+		ready.catch(() => void 0);
+		shared = {
+			channel,
+			listeners,
+			ready
+		};
+		byTopic.set(topic, shared);
+	}
+	const current = shared;
+	current.listeners.add(listener);
+	let left = false;
+	return {
+		ready: current.ready,
+		leave: async () => {
+			if (left) return;
+			left = true;
+			current.listeners.delete(listener);
+			if (current.listeners.size > 0) return;
+			byTopic.delete(topic);
+			await client.removeChannel(current.channel);
+		}
+	};
+}
+/**
+* Calls `onChange` when a table the spec reads changes, so you can refetch.
+* Needs the `realtime-tables` SQL module and the tables in
+* `realtime.tables`. Live queries on the same client share one channel per
+* table, so any number of them can run at once.
+*
+* ```ts
+* using live = liveQuery(sb, supabase, spec, { onChange: () => refetch() });
+* ```
+*/
+function liveQuery(sb, client, spec, options) {
+	const touched = Array.isArray(spec) ? spec : sb.tablesOf(spec);
+	const tables = touched.filter((table) => sb.meta.realtime?.[table]);
+	const unwatched = touched.filter((table) => !sb.meta.realtime?.[table]);
+	const debounceMs = options.debounceMs ?? 100;
+	const changed = /* @__PURE__ */ new Set();
+	let timer;
+	let closed = false;
+	const flush = () => {
+		timer = void 0;
+		if (closed || changed.size === 0) return;
+		const batch = [...changed];
+		changed.clear();
+		options.onChange(batch);
+	};
+	const memberships = tables.map((table) => join(client, liveTopic(sb.meta, table, options.tenant), () => {
+		changed.add(table);
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(flush, debounceMs);
+	}));
+	options.onStatus?.(tables.length === 0 ? "closed" : "joining");
+	const ready = Promise.all(memberships.map((member) => member.ready)).then(() => {
+		if (!closed && tables.length > 0) options.onStatus?.("subscribed");
+	}, (cause) => {
+		const error = cause instanceof Error ? cause : new Error(String(cause));
+		options.onStatus?.("error", error);
+		throw error;
+	});
+	ready.catch(() => void 0);
+	const unsubscribe = async () => {
+		if (closed) return;
+		closed = true;
+		if (timer !== void 0) clearTimeout(timer);
+		await Promise.all(memberships.map((member) => member.leave()));
+		options.onStatus?.("closed");
+	};
+	return {
+		tables,
+		unwatched,
+		ready,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+/**
+* Keeps a count current: runs the `count` spec (a HEAD request) now, after
+* each debounced change to a table it reads, and after the channel rejoins.
+* Responses that arrive out of order are dropped.
+*
+* ```ts
+* using live = liveCount(sb, supabase, db, sb.spec.notes.count(), {
+*   onCount: (count) => render(count),
+* });
+* ```
+*/
+function liveCount(sb, client, db, spec, options) {
+	let latest = 0;
+	let closed = false;
+	const refetch = () => {
+		const call = ++latest;
+		Promise.resolve(db.$run(spec)).then((result) => {
+			if (closed || call !== latest) return;
+			if (result.ok) options.onCount(result.data);
+			else options.onError?.(result.error);
+		});
+	};
+	const live = liveQuery(sb, client, spec, {
+		onChange: refetch,
+		...options.tenant === void 0 ? {} : { tenant: options.tenant },
+		...options.debounceMs === void 0 ? {} : { debounceMs: options.debounceMs },
+		...options.onStatus ? { onStatus: options.onStatus } : {}
+	});
+	if (options.immediate ?? true) refetch();
+	const unsubscribe = async () => {
+		closed = true;
+		await live.unsubscribe();
+	};
+	return {
+		...live,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+//#endregion
+export { liveQuery as n, liveTopic as r, liveCount as t };