better-supabase 0.0.0 → 0.1.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-6b9i72Ux.d.ts

@@ -0,0 +1,180 @@
+import { E as SchemaMeta, k as TableKey, n as AnyModels, t as AnyFunctions, w as Row } from "./types-C2fslP1z.js";
+import { b as ValidationIssue, o as Result, p as DbError, t as AsyncResult } from "./result-CTkCZ6JA.js";
+import { Z as QuerySpec, t as BetterSupabase } from "./define-CTfWw-SS.js";
+import { n as TemplateValues, t as TemplateParams } from "./template-mbvlysOo.js";
+import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/realtime/index.d.ts
+type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
+interface TopicOptions<E extends EventSchemas> {
+  /** Name used for generated policies and functions. Defaults to the template's literal parts. */
+  readonly name?: string;
+  /** Payload schemas per event. Incoming and outgoing payloads are validated. */
+  readonly events?: E;
+  /** Private channels are authorized by `realtime.messages` policies. Defaults to `true`. */
+  readonly private?: boolean;
+  /**
+   * Tenant check for the generated policy. Defaults to `{orgId}` against
+   * `org_id` / `app_metadata.org_id` when the template has `{orgId}`.
+   */
+  readonly tenant?: false | {
+    readonly param?: string;
+    readonly claim?: string | readonly string[];
+    readonly sql?: string;
+  };
+  /** Owner check. Defaults to `{userId}` against `auth.uid()` when the template has `{userId}`. */
+  readonly owner?: false | {
+    readonly param?: string;
+  };
+  /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
+  readonly send?: boolean;
+  /** Also authorize presence. Defaults to `false`. */
+  readonly presence?: boolean;
+}
+interface TopicMessage {
+  readonly event: string;
+  readonly payload: unknown;
+  readonly topic: string;
+}
+type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
+type Input<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> : unknown;
+type TopicHandlers<E extends EventSchemas> = [keyof E] extends [never] ? {
+  readonly [event: string]: ((payload: unknown, message: TopicMessage) => void) | undefined;
+} : { readonly [K in keyof E & string]?: (payload: Output<E[K]>, message: TopicMessage) => void; } & {
+  readonly "*"?: (payload: unknown, message: TopicMessage) => void;
+};
+type TopicEvent<E extends EventSchemas> = [keyof E] extends [never] ? string : keyof E & string;
+type TopicPayload<E extends EventSchemas, K extends string> = [keyof E] extends [never] ? unknown : Input<E[K]>;
+type SubscriptionStatus = "joining" | "subscribed" | "closed" | "error";
+interface SubscribeOptions {
+  /** Receive your own broadcasts. */
+  readonly self?: boolean;
+  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
+  /** Called when a payload fails its event schema. The handler is skipped. */
+  readonly onInvalid?: (message: TopicMessage, issues: readonly ValidationIssue[]) => void;
+}
+interface Subscription extends Disposable, AsyncDisposable {
+  readonly topic: string;
+  readonly channel: RealtimeChannel;
+  /** Resolves once joined; rejects if the join is refused or times out. */
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+type RealtimeClient = Pick<SupabaseClient, "channel" | "removeChannel" | "realtime">;
+interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends string> {
+  /** Column that fills each placeholder. */
+  readonly values: { readonly [K in TemplateParams<P>]: Extract<keyof Row<M, T>, string>; };
+  /** Defaults to all three. */
+  readonly events?: readonly ("insert" | "update" | "delete")[];
+  /** Schema for the generated function. Defaults to `public`. */
+  readonly functionSchema?: string;
+}
+interface RowChange<R> {
+  readonly operation: "INSERT" | "UPDATE" | "DELETE";
+  readonly table: string;
+  readonly record: R | null;
+  readonly oldRecord: Partial<R> | null;
+}
+interface Topic<P extends string, E extends EventSchemas> {
+  readonly template: P;
+  readonly name: string;
+  readonly params: readonly TemplateParams<P>[];
+  readonly private: boolean;
+  topic(values: TemplateValues<P>): string;
+  match(topic: string): TemplateValues<P> | null;
+  /** `realtime.messages` policies for this topic. Idempotent. */
+  sql(): string;
+  /** A trigger that broadcasts row changes (`realtime.broadcast_changes`) to this topic. */
+  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(sb: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
+  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: TopicHandlers<E>, options?: SubscribeOptions): Subscription;
+  /** Sends over HTTP, without joining the channel. */
+  send<K extends TopicEvent<E>>(client: RealtimeClient, values: TemplateValues<P>, event: K, payload: TopicPayload<E, K>): AsyncResult<void>;
+}
+/**
+ * A typed Realtime broadcast topic: names from a template, RLS policies for
+ * private channels, row-change triggers, and disposable subscriptions.
+ *
+ * ```ts
+ * export const notifications = defineTopic('org:{orgId}:notifications:{userId}', {
+ *   events: { created: v.object({ id: v.string(), title: v.string() }) },
+ * });
+ * using sub = notifications.subscribe(supabase, { orgId, userId }, { created: (n) => toast(n.title) });
+ * ```
+ */
+declare function defineTopic<const P extends string, const E extends EventSchemas = Record<never, never>>(template: P, options?: TopicOptions<E>): Topic<P, E>;
+/**
+ * Reads a `realtime.broadcast_changes` message as an app-cased row change.
+ * Returns `null` for messages about other tables.
+ */
+declare function rowChange<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(sb: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
+//#endregion
+//#region src/realtime/live.d.ts
+/** What `liveQuery` needs from `sb`: metadata and the tables a spec reads. */
+interface LiveSource {
+  readonly meta: SchemaMeta;
+  tablesOf(spec: QuerySpec): string[];
+}
+interface LiveQueryOptions {
+  /** Called once per burst of changes, with the app keys of the tables that changed. */
+  readonly onChange: (tables: readonly string[]) => void;
+  /** Tenant value for tables scoped by a tenant column (`realtime-tables` topics). */
+  readonly tenant?: string;
+  /** Waits this long after the last change before calling `onChange`. Defaults to 100 ms. */
+  readonly debounceMs?: number;
+  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
+}
+interface LiveSubscription extends Disposable, AsyncDisposable {
+  /** App keys of the watched tables. */
+  readonly tables: readonly string[];
+  /** Tables the query reads that don't broadcast changes (not in `realtime.tables`). */
+  readonly unwatched: readonly string[];
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+/**
+ * A count from the server plus the spec to keep it live on the client:
+ * `next.liveCount(spec)` makes one, `useLiveCount(seed)` reads it. `count`
+ * is `null` when the server read failed; the client then fetches it.
+ */
+interface LiveCountSeed<T extends string = string> {
+  readonly spec: QuerySpec<T, "count", number>;
+  readonly count: number | null;
+}
+/** Topic a `realtime-tables` trigger broadcasts on: `bs:t:<schema>.<table>[:<tenant>]`. */
+declare function liveTopic(meta: SchemaMeta, table: string, tenant?: string): string;
+/**
+ * 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() });
+ * ```
+ */
+declare function liveQuery(sb: LiveSource, client: RealtimeClient, spec: QuerySpec | readonly string[], options: LiveQueryOptions): LiveSubscription;
+/** What `liveCount` runs the spec with: a `db` from `sb.connect()` or `createBrowser()`. */
+interface CountRunner {
+  $run(spec: QuerySpec): PromiseLike<Result<unknown>>;
+}
+interface LiveCountOptions extends Omit<LiveQueryOptions, "onChange"> {
+  readonly onCount: (count: number) => void;
+  /** A failed refetch; the previous count stays valid. */
+  readonly onError?: (error: DbError) => void;
+  /** Count right away. Defaults to `true`; pass `false` when you have a seed. */
+  readonly immediate?: boolean;
+}
+/**
+ * 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),
+ * });
+ * ```
+ */
+declare function liveCount(sb: LiveSource, client: RealtimeClient, db: CountRunner, spec: QuerySpec<string, "count", number>, options: LiveCountOptions): LiveSubscription;
+//#endregion
+export { defineTopic as C, TriggerOptions as S, TopicEvent as _, LiveSource as a, TopicOptions as b, liveQuery as c, RealtimeClient as d, RowChange as f, Topic as g, SubscriptionStatus as h, LiveQueryOptions as i, liveTopic as l, Subscription as m, LiveCountOptions as n, LiveSubscription as o, SubscribeOptions as p, LiveCountSeed as r, liveCount as s, CountRunner as t, EventSchemas as u, TopicHandlers as v, rowChange as w, TopicPayload as x, TopicMessage as y };