better-supabase 0.14.0 → 0.15.0

package/dist/lint/index.js

@@ -1,5 +1,239 @@
+import { t as DbException } from "../db-exception-Lngc1W49.js";
+import { n as dbError } from "../errors-BVFgt8BZ.js";
+import { t as lookupOf } from "../lookup-BaP5bI27.js";
+import { r as definePlugin } from "../plugin-AKwwe2gF.js";
+import { t as simplify } from "../simplify-DDO0j0LI.js";
+import { o as tenantFrom, s as tenantPathsFor } from "../claims-Bp9My7XP.js";
+//#region src/lint/guards.ts
+/** Catches data-exposure and correctness mistakes; everything else off. */
+function safeGuards() {
+	return {
+		noAdminInBrowser: "error",
+		noDeleteWithoutWhere: "error",
+		noSensitiveSelect: "error",
+		requireTenantContext: "error"
+	};
+}
+/** `safeGuards()` plus performance warnings. */
+function recommendedGuards() {
+	return {
+		...safeGuards(),
+		noUnboundedList: "warn",
+		maxLimit: ["warn", 1e3],
+		requireOrderByForCursor: "warn",
+		maxIncludeDepth: ["warn", 3],
+		storagePathColumns: "warn"
+	};
+}
+/** Every rule as an error. */
+function strictGuards() {
+	return {
+		...safeGuards(),
+		noUnboundedList: "error",
+		maxLimit: ["error", 1e3],
+		requireOrderByForCursor: "error",
+		maxIncludeDepth: ["error", 3],
+		storagePathColumns: "error",
+		requireMaxAffected: ["error", 1e3]
+	};
+}
+function levelOf(setting) {
+	if (setting === void 0) return "off";
+	return typeof setting === "string" ? setting : setting[0];
+}
+function optionOf(setting, fallback) {
+	return Array.isArray(setting) ? setting[1] : fallback;
+}
+const depths = /* @__PURE__ */ new WeakMap();
+function includeDepth(selection) {
+	let depth = depths.get(selection);
+	if (depth === void 0) {
+		depth = computeIncludeDepth(selection);
+		depths.set(selection, depth);
+	}
+	return depth;
+}
+function computeIncludeDepth(selection) {
+	let depth = 0;
+	for (const include of selection.includes) if (include.count !== void 0 || include.aggregate !== void 0) depth = Math.max(depth, 1);
+	else depth = Math.max(depth, 1 + includeDepth(include.selection));
+	return depth;
+}
+const sensitiveByTable = /* @__PURE__ */ new WeakMap();
+function sensitiveOf(table) {
+	let sensitive = sensitiveByTable.get(table);
+	if (!sensitive) {
+		sensitive = new Set(lookupOf(table).entries.filter(([, column]) => column.sensitive).map(([, column]) => column.db));
+		sensitiveByTable.set(table, sensitive);
+	}
+	return sensitive;
+}
+function sensitiveColumns(selection, table) {
+	const found = [];
+	const sensitive = sensitiveOf(table);
+	if (sensitive.size > 0) {
+		for (const column of selection.columns) if (sensitive.has(column.column)) found.push(`${table.key}.${column.column}`);
+		for (const measure of selection.aggregate?.measures ?? []) if (sensitive.has(measure.column)) found.push(`${table.key}.${measure.column}`);
+	}
+	for (const include of selection.includes) found.push(...sensitiveColumns(include.selection, include.target));
+	return found;
+}
+function isBrowser() {
+	return globalThis.window !== void 0 && globalThis.document !== void 0;
+}
+const TEXT_TYPES = /* @__PURE__ */ new Set([
+	"text",
+	"varchar",
+	"bpchar"
+]);
+const STORAGE_URL = /\/storage\/v1\/(?:object|render\/image)\/(?:public|sign|authenticated)\//;
+const templatesBySchema = /* @__PURE__ */ new WeakMap();
+/**
+* Bucket templates specific enough to identify a path: some literal text
+* besides `/`.
+*/
+function bucketTemplates(schema) {
+	let templates = templatesBySchema.get(schema);
+	if (!templates) {
+		templates = Object.values(schema.buckets ?? {}).flatMap((bucket) => typeof bucket.path === "string" ? [bucket.path] : bucket.path).filter((path) => path.replaceAll(/\{[^}]*\}|\//g, "").length > 0).map((path) => new RegExp(`^${path.split(/(\{[^}]*\})/).map((part, index) => index % 2 === 0 ? part.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&") : part.startsWith("{...") ? "[^/]+(?:/[^/]+)*" : "[^/]+").join("")}$`));
+		templatesBySchema.set(schema, templates);
+	}
+	return templates;
+}
+const urlColumnsByTable = /* @__PURE__ */ new WeakMap();
+/** Scalar text columns named `*_url`, the only ones the rule inspects. */
+function urlColumns(table) {
+	let columns = urlColumnsByTable.get(table);
+	if (!columns) {
+		columns = lookupOf(table).entries.map(([, column]) => column).filter((column) => column.db.endsWith("_url") && !column.array && TEXT_TYPES.has(column.type));
+		urlColumnsByTable.set(table, columns);
+	}
+	return columns;
+}
+function storedObjectColumn(op, schema) {
+	const rows = op.kind === "insert" ? op.rows : op.kind === "update" ? [op.set] : [];
+	if (rows.length === 0) return;
+	for (const column of urlColumns(op.table)) {
+		if (!rows.some((row) => column.db in row)) continue;
+		const path = `${column.db.slice(0, -4)}_path`;
+		if (column.storage !== void 0) return `"${column.db}" holds paths in bucket "${column.storage}"; name it "${path}"`;
+		if (rows.some((row) => {
+			const value = row[column.db];
+			return typeof value === "string" && (STORAGE_URL.test(value) || bucketTemplates(schema).some((template) => template.test(value)));
+		})) return `"${column.db}" is given a storage object; store its path in "${path}" and build URLs with signedUrl() or renderUrl()`;
+	}
+}
+const primaryColumnsByTable = /* @__PURE__ */ new WeakMap();
+/**
+* `true` when `where` holds `pk = value` for every primary key column: one row
+* at most.
+*/
+function pinsPrimaryKey(table, where) {
+	if (!where || table.primaryKey.length === 0) return false;
+	let columns = primaryColumnsByTable.get(table);
+	if (!columns) {
+		columns = table.primaryKey.map((name) => table.columns[name]?.db ?? name);
+		primaryColumnsByTable.set(table, columns);
+	}
+	const pinned = /* @__PURE__ */ new Set();
+	const visit = (condition) => {
+		if (condition.kind === "and") for (const item of condition.items) visit(item);
+		else if (condition.kind === "column" && condition.op === "eq" && condition.path === void 0) pinned.add(condition.column);
+	};
+	visit(where);
+	return columns.every((column) => pinned.has(column));
+}
+function checks(rules) {
+	const maxLimit = optionOf(rules.maxLimit, 1e3);
+	const maxDepth = optionOf(rules.maxIncludeDepth, 3);
+	const maxAffected = optionOf(rules.requireMaxAffected, 1e3);
+	return {
+		noUnboundedList: (op) => op.kind === "select" && op.single === void 0 && !op.head && op.limit === void 0 && op.selection.aggregate === void 0 ? "list without limit reads every visible row" : void 0,
+		maxLimit: (op) => {
+			if (op.kind !== "select" || op.limit === void 0) return;
+			const limit = op.lookAhead === true ? op.limit - 1 : op.limit;
+			return limit > maxLimit ? `limit ${limit} is above the maximum of ${maxLimit}` : void 0;
+		},
+		requireOrderByForCursor: (op) => op.kind === "select" && !op.head && op.unpaged !== true && op.source === void 0 && op.orderBy.length === 0 && (op.offset !== void 0 || op.limit !== void 0 && op.limit > 1) ? "paging without orderBy returns rows in no stable order" : void 0,
+		maxIncludeDepth: (op) => {
+			const max = maxDepth;
+			const selection = op.kind === "select" ? op.selection : op.returning;
+			const depth = selection ? includeDepth(selection) : 0;
+			return depth > max ? `includes nest ${depth} levels deep (maximum ${max})` : void 0;
+		},
+		requireTenantContext: (op, { context, schema }) => {
+			if (!op.table.flags.tenant || context.actor?.kind === "service") return;
+			const claim = optionOf(rules.requireTenantContext, void 0);
+			const paths = tenantPathsFor(claim, schema);
+			if (tenantFrom(context, paths) !== void 0) return;
+			return `"${op.table.key}" is tenant-scoped but the request has no tenant (context.tenant or claim ${paths.map((path) => `"${path}"`).join(" or ")})`;
+		},
+		noAdminInBrowser: (_op, { context }) => context.actor?.kind === "service" && isBrowser() ? "a service-role connection is running in a browser" : void 0,
+		noSensitiveSelect: (op, { options }) => {
+			if (options["sensitive"] === true || op.kind !== "select") return;
+			const columns = sensitiveColumns(op.selection, op.table);
+			return columns.length > 0 ? `reads sensitive column(s) ${columns.join(", ")}; pass { sensitive: true } to allow` : void 0;
+		},
+		noDeleteWithoutWhere: (op) => op.kind === "delete" && simplify(op.where) === true ? "delete without where removes every visible row" : void 0,
+		requireMaxAffected: (op) => {
+			if (op.kind !== "update" && op.kind !== "delete") return;
+			if (op.maxAffected === void 0) return pinsPrimaryKey(op.table, op.where) ? void 0 : `${op.kind} by filter without maxAffected can change every row its where matches`;
+			return op.maxAffected > maxAffected ? `maxAffected ${op.maxAffected} is above the maximum of ${maxAffected}` : void 0;
+		},
+		storagePathColumns: (op, { schema }) => storedObjectColumn(op, schema)
+	};
+}
+function defaultReport(violation) {
+	if (violation.level === "warn") console.warn(`[better-supabase] ${violation.rule} (${violation.table}): ${violation.message}`);
+}
+/**
+* Runtime query guards, checked before each request is built:
+*
+* ```ts
+* defineSupabase(schema).use(guards({ rules: recommendedGuards() }));
+* ```
+*
+* Runs first (`enforce: 'first'`) so it sees the query as written, before
+* tenant or soft-delete filters are added. Pair with the static
+* `better-supabase/lint` plugin to catch the same mistakes in the editor.
+*/
+function guards(options = {}) {
+	const set = options.rules ?? recommendedGuards();
+	const report = options.report ?? defaultReport;
+	const all = checks(set);
+	const active = Object.keys(all).flatMap((rule) => {
+		const level = levelOf(set[rule]);
+		return level === "off" ? [] : [{
+			rule,
+			level,
+			check: all[rule]
+		}];
+	});
+	return definePlugin({
+		name: "guards",
+		enforce: "first",
+		scopes: [],
+		transformQuery(op, hook) {
+			for (const { rule, level, check } of active) {
+				const message = check(op, hook);
+				if (message === void 0) continue;
+				const violation = {
+					rule,
+					level,
+					table: op.table.key,
+					operation: op.kind,
+					message
+				};
+				report(violation);
+				if (level === "error") throw new DbException(dbError("invalid_request", `${rule}: ${message}`, { table: op.table.key }));
+			}
+			return op;
+		}
+	});
+}
+//#endregion
 //#region src/lint/index.ts
-const DOCS = "https://bettersupabase.com/docs/plugins/lint";
+const DOCS = "https://bettersupabase.com/docs/repository/lint";
 function methodName(node) {
 	const callee = node.callee;
 	if (callee.type !== "MemberExpression") return;
@@ -7,7 +241,7 @@ function methodName(node) {
 	if (member.computed || member.property.type !== "Identifier") return;
 	return member.property.name;
 }
-/** `users` in `db.users.findMany(...)`. */
+/** `users` in `db.users.list(...)`. */
 function receiverName(node) {
 	const callee = node.callee;
 	if (callee.object.type !== "MemberExpression") return;
@@ -29,8 +263,8 @@ function keyName(property) {
 * The call's first argument as a map of literal keys, `{}` when the call has no
 * arguments, or `undefined` when it cannot be read statically.
 */
-function argsOf(node) {
-	const [first] = node.arguments;
+function argsOf(node, index = 0) {
+	const first = node.arguments[index];
 	if (first === void 0) return /* @__PURE__ */ new Map();
 	if (first.type !== "ObjectExpression") return;
 	const keys = /* @__PURE__ */ new Map();
@@ -61,11 +295,20 @@ function rule(description, name, messages, create, schema = []) {
 		create
 	};
 }
-const FIND_METHODS = /* @__PURE__ */ new Set([
-	"findMany",
-	"findFirst",
-	"paginate"
-]);
+const READ_METHODS = /* @__PURE__ */ new Set(["list", "page"]);
+/** Where `update` and `delete` take their options, after the key and the patch. */
+const OPTIONS_INDEX = {
+	update: 2,
+	delete: 1
+};
+/** The `where` of an `update({ where }, ...)` or `delete({ where })` call. */
+function filterWhere(node) {
+	const method = methodName(node);
+	return method === "update" || method === "delete" ? argsOf(node)?.get("where") : void 0;
+}
+function isEmptyObject(node) {
+	return node?.type === "ObjectExpression" && node.properties.length === 0;
+}
 /** Whether `node` calls `escapeLike(...)`, imported bare or through a namespace. */
 function isEscapeLike(node) {
 	if (node.type !== "CallExpression") return false;
@@ -113,27 +356,26 @@ function largeTables(snapshot) {
 	return snapshot.extras.tables.filter((table) => table.large === true).map((table) => `${table.schema}.${table.name}`);
 }
 const rules = {
-	"no-unbounded-find-many": rule("Require a limit on findMany", "no-unbounded-find-many", { unbounded: "findMany without limit reads every visible row." }, (context) => ({ CallExpression(node) {
-		if (methodName(node) !== "findMany") return;
+	"no-unbounded-list": rule("Require a limit on list", "no-unbounded-list", { unbounded: "list without limit reads every visible row." }, (context) => ({ CallExpression(node) {
+		if (methodName(node) !== "list") return;
 		const args = argsOf(node);
 		if (args && !args.has("limit")) context.report({
 			node,
 			messageId: "unbounded"
 		});
 	} })),
-	"no-delete-many-without-where": rule("Require where on deleteMany", "no-delete-many-without-where", { missing: "deleteMany without where removes every visible row." }, (context) => ({ CallExpression(node) {
-		if (methodName(node) !== "deleteMany") return;
-		const args = argsOf(node);
-		if (args && !args.has("where")) context.report({
+	"no-empty-where": rule("Require a filtering where on update and delete", "no-empty-where", { empty: "{{method}} with an empty where changes every visible row." }, (context) => ({ CallExpression(node) {
+		if (isEmptyObject(filterWhere(node))) context.report({
 			node,
-			messageId: "missing"
+			messageId: "empty",
+			data: { method: methodName(node) ?? "" }
 		});
 	} })),
 	"max-limit": rule("Cap literal limits", "max-limit", { tooLarge: "limit {{limit}} is above the maximum of {{max}}." }, (context) => {
 		const max = context.options[0]?.max ?? 1e3;
 		return { CallExpression(node) {
 			const method = methodName(node);
-			if (method === void 0 || !FIND_METHODS.has(method)) return;
+			if (method === void 0 || !READ_METHODS.has(method)) return;
 			const limit = numberOf(argsOf(node)?.get("limit"));
 			if (limit !== void 0 && limit > max) context.report({
 				node,
@@ -153,18 +395,18 @@ const rules = {
 		additionalProperties: false
 	}]),
 	"require-order-by": rule("Require orderBy when paging with offset", "require-order-by", { unordered: "offset without orderBy returns rows in no stable order." }, (context) => ({ CallExpression(node) {
-		if (methodName(node) !== "findMany") return;
+		if (methodName(node) !== "list") return;
 		const args = argsOf(node);
 		if (args?.has("offset") && !args.has("orderBy")) context.report({
 			node,
 			messageId: "unordered"
 		});
 	} })),
-	"unbounded-read": rule("Require limit or paginate on large tables", "unbounded-read", { unbounded: "findMany on {{table}} without limit returns at most db-max-rows rows and drops the rest; add limit or use paginate()." }, (context) => {
+	"unbounded-read": rule("Require limit or page on large tables", "unbounded-read", { unbounded: "list on {{table}} without limit returns at most db-max-rows rows and drops the rest; add limit or use page()." }, (context) => {
 		const option = context.options[0];
 		const large = new Set((option?.tables ?? []).map(tableKey));
 		return { CallExpression(node) {
-			if (methodName(node) !== "findMany") return;
+			if (methodName(node) !== "list") return;
 			const table = receiverName(node);
 			if (table === void 0) return;
 			if (!option?.strict && !large.has(tableKey(table))) return;
@@ -186,15 +428,15 @@ const rules = {
 		},
 		additionalProperties: false
 	}]),
-	"require-max-affected": rule("Require maxAffected on updateMany and deleteMany", "require-max-affected", {
+	"require-max-affected": rule("Require maxAffected on update and delete by filter", "require-max-affected", {
 		missing: "{{method}} without maxAffected can change every row its where matches.",
 		tooLarge: "maxAffected {{value}} is above the maximum of {{max}}."
 	}, (context) => {
 		const max = context.options[0]?.max ?? 1e3;
 		return { CallExpression(node) {
 			const method = methodName(node);
-			if (method !== "updateMany" && method !== "deleteMany") return;
-			const args = argsOf(node);
+			if (method === void 0 || filterWhere(node) === void 0) return;
+			const args = argsOf(node, OPTIONS_INDEX[method]);
 			if (!args) return;
 			const bound = args.get("maxAffected");
 			if (bound === void 0) {
@@ -238,8 +480,8 @@ const plugin = {
 	configs: { recommended: {
 		plugins: {},
 		rules: {
-			"better-supabase/no-delete-many-without-where": "error",
-			"better-supabase/no-unbounded-find-many": "warn",
+			"better-supabase/no-empty-where": "error",
+			"better-supabase/no-unbounded-list": "warn",
 			"better-supabase/max-limit": "warn",
 			"better-supabase/require-order-by": "warn",
 			"better-supabase/unbounded-read": "warn",
@@ -249,4 +491,4 @@ const plugin = {
 };
 plugin.configs.recommended.plugins["better-supabase"] = plugin;
 //#endregion
-export { plugin as default, plugin, largeTables, rules };
+export { plugin as default, plugin, guards, largeTables, recommendedGuards, rules, safeGuards, strictGuards };

package/dist/list/index.d.ts

@@ -1,4 +1,4 @@
-import { _ as FilterRule, a as FilterDateValue, b as encodeFilterQuery, c as FilterFieldLabels, f as FilterNode, g as FilterRelativeDate, h as FilterQuery, i as FilterCombinator, l as FilterFieldType, m as FilterOperatorSpec, n as FILTER_OPERATOR_LABELS, o as FilterField, p as FilterOperatorArity, r as FilterClock, s as FilterFieldInfo, t as FILTER_OPERATORS, u as FilterGroupNode, v as ListFilterConfig, y as decodeFilterQuery } from "../filter-query-o3b_GuyC.js";
-import { _ as UNSET, a as ListExtra, c as ListParseOptions, d as ListQuery, f as ListQueryConfig, g as ParserSpec, h as OpenApiParameter, i as ListDefinition, l as ListParseResult, m as ListSearchParams, n as FacetCounts, o as ListPage, p as ListQueryInput, r as FacetInfo, s as ListPagination, t as FacetCountFields, u as ListParsers, v as defineListQuery } from "../list-query-BtluNnYk.js";
-import { n as FilterRecordField, r as evaluateFilterQuery, t as FilterEvaluation } from "../filter-evaluate-C3i2bGfk.js";
-export { FILTER_OPERATORS, FILTER_OPERATOR_LABELS, type FacetCountFields, type FacetCounts, type FacetInfo, type FilterClock, type FilterCombinator, type FilterDateValue, type FilterEvaluation, type FilterField, type FilterFieldInfo, type FilterFieldLabels, type FilterFieldType, type FilterGroupNode, type FilterNode, type FilterOperatorArity, type FilterOperatorSpec, type FilterQuery, type FilterRecordField, type FilterRelativeDate, type FilterRule, type ListDefinition, type ListExtra, type ListFilterConfig, type ListPage, type ListPagination, type ListParseOptions, type ListParseResult, type ListParsers, type ListQuery, type ListQueryConfig, type ListQueryInput, type ListSearchParams, type OpenApiParameter, type ParserSpec, UNSET, decodeFilterQuery, defineListQuery, encodeFilterQuery, evaluateFilterQuery };
+import { _ as FilterRule, a as FilterDateValue, b as encodeFilterQuery, c as FilterFieldLabels, d as FilterLimits, f as FilterNode, g as FilterRelativeDate, h as FilterQuery, i as FilterCombinator, l as FilterFieldType, m as FilterOperatorSpec, n as FILTER_OPERATOR_LABELS, o as FilterField, p as FilterOperatorArity, r as FilterClock, s as FilterFieldInfo, t as FILTER_OPERATORS, u as FilterGroupNode, v as ListFilterConfig, y as decodeFilterQuery } from "../filter-query-BXLs72G9.js";
+import { _ as UNSET, a as ListExtra, c as ListParseOptions, d as ListQuery, f as ListQueryConfig, g as ParserSpec, h as OpenApiParameter, i as ListDefinition, l as ListParseResult, m as ListSearchParams, n as FacetCounts, o as ListPage, p as ListQueryInput, r as FacetInfo, s as ListPagination, t as FacetCountFields, u as ListParsers, v as defineListQuery } from "../list-query-BDVutLFr.js";
+import { n as FilterRecordField, r as evaluateFilterQuery, t as FilterEvaluation } from "../filter-evaluate-CPxeae5X.js";
+export { FILTER_OPERATORS, FILTER_OPERATOR_LABELS, type FacetCountFields, type FacetCounts, type FacetInfo, type FilterClock, type FilterCombinator, type FilterDateValue, type FilterEvaluation, type FilterField, type FilterFieldInfo, type FilterFieldLabels, type FilterFieldType, type FilterGroupNode, type FilterLimits, type FilterNode, type FilterOperatorArity, type FilterOperatorSpec, type FilterQuery, type FilterRecordField, type FilterRelativeDate, type FilterRule, type ListDefinition, type ListExtra, type ListFilterConfig, type ListPage, type ListPagination, type ListParseOptions, type ListParseResult, type ListParsers, type ListQuery, type ListQueryConfig, type ListQueryInput, type ListSearchParams, type OpenApiParameter, type ParserSpec, UNSET, decodeFilterQuery, defineListQuery, encodeFilterQuery, evaluateFilterQuery };

package/dist/list/index.js

@@ -1,4 +1,4 @@
-import { n as FILTER_OPERATOR_LABELS, o as decodeFilterQuery, s as encodeFilterQuery, t as FILTER_OPERATORS } from "../filter-query-D4ZSwbcJ.js";
-import { n as defineListQuery, t as UNSET } from "../list-query-CuS1w2Af.js";
-import { t as evaluateFilterQuery } from "../filter-evaluate-CRDXv0Dl.js";
+import { n as FILTER_OPERATOR_LABELS, o as decodeFilterQuery, s as encodeFilterQuery, t as FILTER_OPERATORS } from "../filter-query-DMoKo82_.js";
+import { n as defineListQuery, t as UNSET } from "../list-query-BKy2zBaT.js";
+import { t as evaluateFilterQuery } from "../filter-evaluate-w1XOIUOL.js";
 export { FILTER_OPERATORS, FILTER_OPERATOR_LABELS, UNSET, decodeFilterQuery, defineListQuery, encodeFilterQuery, evaluateFilterQuery };

package/dist/list-query-BDVutLFr.d.ts

@@ -0,0 +1,222 @@
+import { D as ValidationIssue, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { O as AnyFunctions, a as CountMode, it as Row, k as AnyModels, ut as TableKey } from "./types-DFdg_4yN.js";
+import { At as IncludeArg, Bt as Payload, Jt as WhereInput, O as OffsetPage, R as RepositoryOf, Rt as OrderByArg, S as FindExt, Wt as SelectArg, _ as CursorPageArgs, g as CursorPage, k as OffsetPageArgs, t as BetterSupabase } from "./define-DFBnQyYg.js";
+import { c as FilterFieldLabels, h as FilterQuery, o as FilterField, r as FilterClock, s as FilterFieldInfo, v as ListFilterConfig } from "./filter-query-BXLs72G9.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/list/list-query.d.ts
+/** Facet value meaning "not set": filters with `is null`. */
+declare const UNSET = "__unset__";
+type Column<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string>;
+type TextColumn<M extends AnyModels, T extends keyof M> = { [K in Column<M, T>]: [NonNullable<Row<M, T>[K]>] extends [string] ? K : never; }[Column<M, T>];
+/** `offset` pages by number; `cursor` continues after the last row (keyset). */
+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 per facet that
+   * runs next to the page: one wave. Needs PostgREST aggregates.
+   */
+  readonly facetCounts?: C;
+  /**
+   * 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>[] | {
+    readonly fts: Column<M, T>;
+    readonly config?: string;
+  };
+  /**
+   * Filterable columns by URL key. Values are validated against enums and CHECK
+   * unions.
+   */
+  readonly facets?: { readonly [K in F]: Column<M, T>; };
+  /**
+   * Fields a filter tree (ReUI Filters' `FilterQuery`) may name, by field id.
+   * Each has a type and, optionally, the subset of its operators to allow.
+   */
+  readonly filters?: Readonly<Record<string, ListFilterConfig<Column<M, T>>>>;
+  /** Most nested group levels in a filter tree, the root included. Defaults to 4. */
+  readonly maxFilterDepth?: number;
+  /** Most rules in a filter tree. Defaults to 50. */
+  readonly maxFilterRules?: number;
+  /** Named orderings. Add a unique column last for stable pages. */
+  readonly sorts: { readonly [K in S]: OrderByArg<M, T>; };
+  readonly defaultSort: NoInfer<S>;
+  /**
+   * `cursor` takes an `after` cursor instead of `page` and returns
+   * `nextCursor`: the cost of a page stays the same however deep it is, and
+   * rows inserted meanwhile don't shift it. Defaults to `cursor`; `offset`
+   * takes `page` and returns `total` and `pageCount`.
+   */
+  readonly pagination?: P;
+  /** Defaults to 50. */
+  readonly pageSize?: number;
+  /** Defaults to 200. */
+  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;
+  readonly sort: S;
+  /** 1-based. Always 1 with cursor pagination. */
+  readonly page: number;
+  /** Cursor pagination: the `nextCursor` of the previous page. */
+  readonly after?: string;
+  readonly size: number;
+  readonly facets: { readonly [K in F]?: readonly string[]; };
+  /** The checked filter tree, without unfinished rules and empty groups. */
+  readonly filter?: FilterQuery;
+  /** The IANA time zone date filters resolve in, from `parse`'s options. */
+  readonly timeZone?: string;
+}
+/** Typed input (JSON APIs, actions, MCP tools). Everything is optional. */
+interface ListQueryInput<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort?: S;
+  readonly page?: number;
+  readonly after?: string;
+  readonly size?: number;
+  readonly facets?: { readonly [K in F]?: readonly string[]; };
+  readonly filter?: FilterQuery;
+}
+/** URL input: `URLSearchParams` or a Next.js `searchParams` record. */
+type ListSearchParams = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+type ListParseResult<S extends string, F extends string> = {
+  readonly ok: true;
+  readonly value: ListQuery<S, F>;
+  readonly issues?: undefined;
+} | {
+  readonly ok: false;
+  readonly value?: undefined;
+  readonly issues: readonly ValidationIssue[];
+};
+interface ParserSpec<V> {
+  parse(value: string): V | null;
+  serialize(value: V): string;
+  /** Equality for object values, which nuqs uses to skip URL updates. */
+  eq?(a: V, b: V): boolean;
+}
+interface OpenApiParameter {
+  readonly name: string;
+  readonly in: "query";
+  readonly required: false;
+  readonly description: string;
+  readonly schema: Readonly<Record<string, unknown>>;
+  readonly style?: "form";
+  readonly explode?: boolean;
+}
+interface ListParseOptions {
+  /**
+   * IANA time zone that date filters resolve in, such as the request's.
+   * Defaults to `UTC`.
+   */
+  readonly timeZone?: string;
+}
+interface FacetInfo {
+  readonly key: string;
+  readonly column: string;
+  readonly nullable: boolean;
+  /** Allowed values when the column is an enum or CHECK union. */
+  readonly values?: readonly string[];
+}
+/** 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 = "cursor"> = ([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>;
+  /** 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 = "cursor"> {
+  readonly table: T;
+  readonly pagination: P;
+  readonly defaults: ListQuery<S, F>;
+  readonly facets: readonly FacetInfo[];
+  /** The checked `filters` config. */
+  readonly filters: readonly FilterFieldInfo[];
+  /** Validates typed input or URL params. Also a Standard Schema (`schema`). */
+  parse(input: ListQueryInput<S, F> | ListSearchParams | undefined, options?: ListParseOptions): ListParseResult<S, F>;
+  /** `FilterField` objects for ReUI Filters, with labels you can translate. */
+  filterFields(labels?: FilterFieldLabels): FilterField[];
+  /**
+   * The repository `where` of the query's filter tree; relative dates resolve
+   * against `clock.now`.
+   */
+  filterWhere(query: ListQuery<S, F>, clock?: Pick<FilterClock, "now">): WhereInput<M, T> | undefined;
+  readonly schema: StandardSchemaV1<ListQueryInput<S, F> | ListSearchParams | undefined, ListQuery<S, F>>;
+  /** URL params, leaving out defaults. */
+  toSearchParams(query: Partial<ListQuery<S, F>>): URLSearchParams;
+  /**
+   * `{ parse, serialize }` per URL key, for routers and nuqs
+   * (`list.nuqs(createParser)`).
+   */
+  readonly parsers: ListParsers<S, F>;
+  nuqs<P>(createParser: (spec: ParserSpec<unknown>) => P): { readonly [K in keyof ListParsers<S, F>]: P; };
+  /**
+   * Repository arguments: `where`, `orderBy`, `size`, and `page` and `count` or
+   * `after`.
+   */
+  args(query: ListQuery<S, F>, clock?: Pick<FilterClock, "now">): [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 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. */
+  readonly openapi: readonly OpenApiParameter[];
+  /** JSON Schema of the typed input, e.g. for MCP tool arguments. */
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+interface ListExtra<M extends AnyModels, T extends keyof M> {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  readonly where?: WhereInput<M, T>;
+  /** Overrides the config's `count` for this run. */
+  readonly count?: CountMode;
+}
+type ListParsers<S extends string, F extends string> = {
+  readonly q: ParserSpec<string>;
+  readonly sort: ParserSpec<S>;
+  readonly page: ParserSpec<number>;
+  readonly after: ParserSpec<string>;
+  readonly size: ParserSpec<number>;
+  /**
+   * The filter tree as base64url JSON, when the list has `filters`; `parse`
+   * checks it.
+   */
+  readonly filter?: ParserSpec<FilterQuery>;
+} & { readonly [K in F]: ParserSpec<readonly string[]>; };
+/**
+ * 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",
+ *   },
+ * );
+ * ```
+ */
+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 = "cursor">(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 { UNSET as _, ListExtra as a, ListParseOptions as c, ListQuery as d, ListQueryConfig as f, ParserSpec as g, OpenApiParameter as h, ListDefinition as i, ListParseResult as l, ListSearchParams as m, FacetCounts as n, ListPage as o, ListQueryInput as p, FacetInfo as r, ListPagination as s, FacetCountFields as t, ListParsers as u, defineListQuery as v };