better-supabase 0.8.0 → 0.10.0

package/dist/list-query-CBXNfJt4.js

@@ -0,0 +1,549 @@
+import { c as filterFieldsOf, d as toFilterFields, i as checkFilterQuery, l as filterJsonSchema, o as decodeFilterQuery, s as encodeFilterQuery, u as filterWhere } from "./filter-query-B3lhckKX.js";
+//#region src/list/list-query.ts
+/** Facet value meaning "not set": filters with `is null`. */
+const UNSET = "__unset__";
+const RESERVED = /* @__PURE__ */ new Set([
+	"q",
+	"sort",
+	"page",
+	"after",
+	"size"
+]);
+/** Longest `filter` URL parameter, in characters. */
+const MAX_FILTER_PARAM = 16384;
+function validTimeZone(timeZone) {
+	try {
+		return new Intl.DateTimeFormat("en", { timeZone }).resolvedOptions().timeZone !== "";
+	} catch {
+		return false;
+	}
+}
+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);
+}
+const isParamValue = (value) => value === void 0 || typeof value === "string" || Array.isArray(value) && value.every((entry) => typeof entry === "string");
+function isSearchParams(value) {
+	return value instanceof URLSearchParams || !("facets" in value && typeof value.facets === "object") && Object.values(value).every(isParamValue);
+}
+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(betterSupabase, 'customers', {
+*   search: ['name', 'kvk'],
+*   facets: { status: 'status' },
+*   sorts: { name: { name: 'asc' }, newest: [{ createdAt: 'desc' }, { id: 'asc' }] },
+*   defaultSort: 'newest',
+* });
+* ```
+*/
+function defineListQuery(betterSupabase, table, config) {
+	const meta = betterSupabase.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 facetLimit = config.facetLimit ?? 100;
+	const cursor = config.pagination !== "offset";
+	const sortKeys = Object.keys(config.sorts);
+	const facetEntries = Object.entries(config.facets ?? {});
+	const filterFields = filterFieldsOf(meta, config.filters ?? {});
+	const filtering = filterFields.length > 0;
+	const limits = {
+		maxDepth: config.maxFilterDepth ?? 4,
+		maxRules: config.maxFilterRules ?? 50,
+		maxValueLength: maxSearch,
+		maxValues: facetLimit
+	};
+	for (const [key, column] of facetEntries) {
+		if (RESERVED.has(key) || filtering && key === "filter") 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 filter;
+		if (raw.filter !== void 0 && raw.filter !== null) {
+			if (filtering) filter = checkFilterQuery(raw.filter, filterFields, limits, issues);
+			else issues.push({
+				message: "This list has no filters",
+				path: ["filter"]
+			});
+		}
+		if (raw.timeZone !== void 0 && !validTimeZone(raw.timeZone)) issues.push({
+			message: "Unknown time zone",
+			path: ["timeZone"]
+		});
+		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"]
+		});
+		else if (cursor && page !== 1) issues.push({
+			message: "This list pages with `after`, not `page`",
+			path: ["page"]
+		});
+		let after;
+		if (raw.after !== void 0 && raw.after !== "") {
+			if (cursor && typeof raw.after === "string") after = raw.after;
+			else issues.push({
+				message: cursor ? "Must be text" : "This list pages with `page`, not `after`",
+				path: ["after"]
+			});
+		}
+		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,
+				...after ? { after } : {},
+				size: size ?? pageSize,
+				facets: facetValues,
+				...filter ? { filter } : {},
+				...raw.timeZone === void 0 ? {} : { timeZone: raw.timeZone }
+			}
+		};
+	}
+	function parse(input, options = {}) {
+		const timeZone = options.timeZone;
+		if (input === void 0 || input === null) return timeZone === void 0 ? {
+			ok: true,
+			value: defaults
+		} : normalize({
+			facets: {},
+			timeZone
+		});
+		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]);
+			const encoded = filtering ? first(record["filter"]) : void 0;
+			let filter;
+			if (encoded !== void 0 && encoded !== "") {
+				filter = encoded.length > MAX_FILTER_PARAM ? void 0 : decodeFilterQuery(encoded);
+				if (filter === void 0) return {
+					ok: false,
+					issues: [{
+						message: "Must be a filter tree as base64url JSON",
+						path: ["filter"]
+					}]
+				};
+			}
+			return normalize({
+				filter,
+				timeZone,
+				q: first(record["q"]),
+				sort: first(record["sort"]),
+				page: first(record["page"]),
+				after: first(record["after"]),
+				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({
+			filter: typed.filter,
+			timeZone,
+			q: typed.q,
+			sort: typed.sort,
+			page: typed.page,
+			after: typed.after,
+			size: typed.size,
+			facets: rawFacets
+		});
+	}
+	function searchWhere(query) {
+		if (!query.q || !config.search) return;
+		if (Array.isArray(config.search)) {
+			const columns = config.search;
+			if (columns.length === 0) return;
+			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;
+		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;
+		return present.length === 1 ? present[0] : { AND: present };
+	}
+	function treeWhere(query, clock = {}) {
+		if (!query.filter || !filtering) return;
+		return filterWhere(query.filter, filterFields, {
+			...clock,
+			...query.timeZone === void 0 ? {} : { timeZone: query.timeZone }
+		});
+	}
+	function where(query, clock) {
+		return and([
+			searchWhere(query),
+			treeWhere(query, clock),
+			...facets.map((facet) => facetWhere(facet, query.facets[facet.key]))
+		]);
+	}
+	function args(query, clock) {
+		const filter = where(query, clock);
+		const paging = cursor ? { after: query.after ?? null } : {
+			page: query.page,
+			count: config.count ?? "planned"
+		};
+		return {
+			...filter ? { where: filter } : {},
+			orderBy: config.sorts[query.sort],
+			size: query.size,
+			...paging
+		};
+	}
+	/** Rows per value of one facet, from its grouped aggregate. */
+	function countsOf(facet, groups) {
+		const counts = {};
+		for (const value of facet.values ?? []) counts[value] = 0;
+		for (const group of groups) {
+			const raw = group[facet.column];
+			const key = raw === null || raw === void 0 ? UNSET : String(raw);
+			counts[key] = (counts[key] ?? 0) + Number(group["_count"] ?? 0);
+		}
+		return counts;
+	}
+	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,
+		after: {
+			parse: (value) => value || null,
+			serialize: (value) => value
+		},
+		size: intParser,
+		...filtering ? { filter: {
+			parse: (value) => {
+				const decoded = value.length > MAX_FILTER_PARAM ? void 0 : decodeFilterQuery(value);
+				return typeof decoded === "object" && decoded !== null && "type" in decoded && decoded.type === "group" ? decoded : null;
+			},
+			serialize: encodeFilterQuery,
+			eq: (a, b) => encodeFilterQuery(a) === encodeFilterQuery(b)
+		} } : {},
+		...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;
+	const 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
+			}
+		},
+		cursor ? {
+			name: "after",
+			in: "query",
+			required: false,
+			description: "`nextCursor` of the previous page. Leave it out for the first page.",
+			schema: { type: "string" }
+		} : {
+			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
+			}
+		},
+		...filtering ? [{
+			name: "filter",
+			in: "query",
+			required: false,
+			description: `A filter tree (ReUI Filters' FilterQuery) as base64url JSON. Fields: ${filterFields.map((field) => `${field.id} (${field.type})`).join(", ")}. At most ${String(limits.maxRules)} rules and ${String(limits.maxDepth)} levels.`,
+			schema: {
+				type: "string",
+				maxLength: MAX_FILTER_PARAM
+			}
+		}] : [],
+		...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
+		}))
+	];
+	const filterSchema = filtering ? filterJsonSchema(filterFields, limits) : void 0;
+	const jsonSchema = {
+		...filterSchema ? { $defs: filterSchema["$defs"] } : {},
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...filterSchema ? { filter: { $ref: "#/$defs/filterGroup" } } : {},
+			...searchDescription ? { q: {
+				type: "string",
+				maxLength: maxSearch,
+				description: searchDescription
+			} } : {},
+			sort: {
+				type: "string",
+				enum: sortKeys,
+				default: config.defaultSort
+			},
+			...cursor ? { after: { type: "string" } } : { 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)]))
+			} } : {}
+		}
+	};
+	return {
+		table,
+		pagination: config.pagination ?? "cursor",
+		defaults,
+		facets,
+		filters: filterFields,
+		parse,
+		filterFields: (labels) => toFilterFields(filterFields, labels),
+		filterWhere: (query, clock) => treeWhere(query, clock),
+		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.after) params.set("after", query.after);
+			if (query.size !== void 0 && query.size > 0 && query.size !== pageSize) params.set("size", String(query.size));
+			if (query.filter && query.filter.rules.length > 0) params.set("filter", encodeFilterQuery(query.filter));
+			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,
+				...cursor ? {} : { count: count ?? base["count"] },
+				...combined ? { where: combined } : {}
+			});
+			if (!config.facetCounts) return page;
+			if (facets.length === 0) return page.map((data) => ({
+				...data,
+				facetCounts: {},
+				facetCountsTruncated: []
+			}));
+			const search = searchWhere(query);
+			const tree = treeWhere(query);
+			const counted = facets.map((facet) => {
+				const filter = and([
+					extraWhere,
+					search,
+					tree,
+					...facets.map((other) => other === facet ? void 0 : facetWhere(other, query.facets[other.key]))
+				]);
+				return repository.aggregate({
+					...options,
+					...filter ? { where: filter } : {},
+					groupBy: [facet.column],
+					_count: true,
+					orderBy: [{ _count: "desc" }, { [facet.column]: "asc" }],
+					limit: facetLimit + 1
+				});
+			});
+			return page.andThen(async (data) => {
+				const results = await Promise.all(counted);
+				const facetCounts = {};
+				const truncated = [];
+				for (const [index, facet] of facets.entries()) {
+					const result = results[index];
+					if (!result.ok) return result;
+					const rows = result.data;
+					if (rows.length > facetLimit) truncated.push(facet.key);
+					facetCounts[facet.key] = countsOf(facet, rows.slice(0, facetLimit));
+				}
+				return {
+					ok: true,
+					data: {
+						...data,
+						facetCounts,
+						facetCountsTruncated: truncated
+					},
+					error: null
+				};
+			});
+		},
+		openapi,
+		jsonSchema
+	};
+}
+//#endregion
+export { defineListQuery as n, UNSET as t };