better-supabase 0.5.0 → 0.6.0

package/dist/list/index.js

@@ -1,445 +1,2 @@
-//#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"
-]);
-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 cursor = config.pagination === "cursor";
-	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"]
-		});
-		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
-			}
-		};
-	}
-	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"]),
-				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({
-			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 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);
-		const paging = cursor ? { after: query.after ?? null } : {
-			page: query.page,
-			count: config.count ?? "exact"
-		};
-		return {
-			...filter ? { where: filter } : {},
-			orderBy: config.sorts[query.sort],
-			size: query.size,
-			...paging
-		};
-	}
-	/** 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,
-		after: {
-			parse: (value) => value || null,
-			serialize: (value) => value
-		},
-		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;
-	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
-			}
-		},
-		...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 jsonSchema = {
-		type: "object",
-		additionalProperties: false,
-		properties: {
-			...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 ?? "offset",
-		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.after) params.set("after", query.after);
-			if (query.size !== void 0 && query.size > 0 && 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,
-				...cursor ? {} : { 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,
-		jsonSchema
-	};
-}
-//#endregion
+import { n as defineListQuery, t as UNSET } from "../list-query-gl808ac1.js";
 export { UNSET, defineListQuery };

package/dist/{index-fag8VJZ2.d.ts → list-query-BRt-zDF7.d.ts}

@@ -1,6 +1,7 @@
-import { P as TableKey, k as Row, n as AnyFunctions, r as AnyModels } from "./types-Dnf_wRDz.js";
-import { I as CountMode, a as AsyncResult, w as ValidationIssue } from "./executor-BunPOO-k.js";
-import { C as FindExt, Ct as WhereInput, O as RepositoryOf, T as OffsetPageArgs, _ as CursorPage, dt as IncludeArg, gt as OrderByArg, t as BetterSupabase, v as CursorPageArgs, vt as Payload, w as OffsetPage, xt as SelectArg } from "./define-Bp_BZa5h.js";
+import { E as ValidationIssue, t as AsyncResult } from "./result-D7y2fT87.js";
+import { L as TableKey, M as Row, a as AnyModels, i as AnyFunctions } from "./types-6BdhkmZe.js";
+import { l as CountMode } from "./executor-DvsBbNBS.js";
+import { At as OrderByArg, Ct as IncludeArg, D as OffsetPage, It as SelectArg, M as RepositoryOf, Mt as Payload, O as OffsetPageArgs, t as BetterSupabase, v as CursorPage, w as FindExt, y as CursorPageArgs, zt as WhereInput } from "./define-CJJkkr1-.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/list/list-query.d.ts
 /** Facet value meaning "not set": filters with `is null`. */
@@ -11,11 +12,11 @@ type TextColumn<M extends AnyModels, T extends keyof M> = { [K in Column<M, T>]:
 type ListPagination = "offset" | "cursor";
 interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends string, F extends string, C extends boolean = boolean, P extends ListPagination = ListPagination> {
   /**
-   * Also count rows per facet value, with one grouped aggregate that runs
-   * next to the page: 2 calls, 1 wave. Needs PostgREST aggregates.
+   * Also count rows per facet value, with one grouped aggregate per facet
+   * that runs next to the page: one wave. Needs PostgREST aggregates.
    */
   readonly facetCounts?: C;
-  /** How the page total is counted. Defaults to `'exact'`. */
+  /** How the page total is counted. Defaults to `'planned'`, the planner's estimate. */
   readonly count?: CountMode;
   /** Text columns matched case-insensitively (OR), or a full-text column. */
   readonly search?: readonly TextColumn<M, T>[] | {
@@ -39,6 +40,11 @@ interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends stri
   readonly maxPageSize?: number;
   /** Defaults to 200 characters. */
   readonly maxSearchLength?: number;
+  /**
+   * Most values counted per facet; a facet with more lists its key in
+   * `facetCountsTruncated`. Defaults to 100.
+   */
+  readonly facetLimit?: number;
 }
 interface ListQuery<S extends string, F extends string> {
   readonly q?: string;
@@ -93,11 +99,13 @@ interface FacetInfo {
 /** Rows per facet value, keyed by facet and then by value (`UNSET` for empty). */
 type FacetCounts<F extends string> = { readonly [K in F]: Readonly<Record<string, number>>; };
 /** A page of a list; with `facetCounts: true`, also the counts per facet value. */
-type ListPage<R, F extends string, C extends boolean, P extends ListPagination = "offset"> = ([P] extends ["cursor"] ? CursorPage<R> : OffsetPage<R>) & ([C] extends [true] ? {
+type ListPage<R, F extends string, C extends boolean, P extends ListPagination = "offset"> = ([P] extends ["cursor"] ? CursorPage<R> : OffsetPage<R>) & ([C] extends [true] ? FacetCountFields<F> : [C] extends [false] ? unknown : Partial<FacetCountFields<F>>);
+/** The facet fields of a page with `facetCounts: true`. */
+interface FacetCountFields<F extends string> {
   readonly facetCounts: FacetCounts<F>;
-} : [C] extends [false] ? unknown : {
-  readonly facetCounts?: FacetCounts<F>;
-});
+  /** Facets with more values than `facetLimit`, whose counts are cut. */
+  readonly facetCountsTruncated: readonly F[];
+}
 interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extends string, F extends string, C extends boolean = false, P extends ListPagination = "offset"> {
   readonly table: T;
   readonly pagination: P;
@@ -115,7 +123,7 @@ interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extend
   args(query: ListQuery<S, F>): [P] extends ["cursor"] ? CursorPageArgs<M, T> : OffsetPageArgs<M, T>;
   /**
    * Runs the list against a table, merging your `select`, `include`, `where`
-   * and `count`. One request, plus one for `facetCounts`, always one wave.
+   * and `count`. One request, plus one per facet for `facetCounts`, always one wave.
    */
   run<const A extends ListExtra<M, T> & FindExt<E, M, T>>(db: { readonly [K in T]: RepositoryOf<M, K, E>; }, query: ListQuery<S, F>, extra?: A): AsyncResult<ListPage<Payload<M, T, A>, F, C, P>>;
   /** OpenAPI 3.1 query parameters. */
@@ -153,4 +161,4 @@ type ListParsers<S extends string, F extends string> = {
  */
 declare function defineListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>, const S extends string, const F extends string = never, const C extends boolean = false, const P extends ListPagination = "offset">(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, config: ListQueryConfig<M, T, S, F, C, P>): ListDefinition<M, T, E, S, F, C, P>;
 //#endregion
-export { ListPage as a, ListParsers as c, ListQueryInput as d, ListSearchParams as f, defineListQuery as g, UNSET as h, ListExtra as i, ListQuery as l, ParserSpec as m, FacetInfo as n, ListPagination as o, OpenApiParameter as p, ListDefinition as r, ListParseResult as s, FacetCounts as t, ListQueryConfig as u };
+export { defineListQuery as _, ListExtra as a, ListParseResult as c, ListQueryConfig as d, ListQueryInput as f, UNSET as g, ParserSpec as h, ListDefinition as i, ListParsers as l, OpenApiParameter as m, FacetCounts as n, ListPage as o, ListSearchParams as p, FacetInfo as r, ListPagination as s, FacetCountFields as t, ListQuery as u };