@protobase/server 0.26.6 → 0.26.8

package/dist/admin-options.d.ts

@@ -14,9 +14,9 @@ export type AdminOptions = {
   /** Default `/api/v1`. */
   basePath?: string;
   /**
-   * The app's publishable and secret keys, with which supabase-js calls the Realtime-compatible `/realtime/v1` (see
-   * `ApiKeysOptions`); default `PROTOBASE_PUBLISHABLE_KEY` and `PROTOBASE_SECRET_KEY`. Without either, or with
-   * `false`, the app serves no `/realtime/v1`.
+   * The app's publishable and secret keys, with which supabase-js calls the PostgREST-compatible `/rest/v1` and the
+   * Realtime-compatible `/realtime/v1` (see `ApiKeysOptions`); default `PROTOBASE_PUBLISHABLE_KEY` and
+   * `PROTOBASE_SECRET_KEY`. Without either, or with `false`, the app serves neither.
    */
   apiKeys?: ApiKeysOptions | false;
   /** Applied to every request's transaction with SET LOCAL. Default 15000. */

package/dist/check-views.js

@@ -6,6 +6,7 @@ import { chartErrors } from "./view-chart.js";
 import { mapDisplayErrors, mapErrors } from "./view-map.js";
 import { relatedColumnErrors } from "./view-related-column.js";
 import { editableErrors } from "./view-editable.js";
+import { actionWhenErrors, actionWhenFields } from "./view-action-when.js";
 import { conditionProblems } from "@protobase/layout";
 import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, chartFields, datesErrors, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, layoutItems, linkActionError, promptError, promptFields, updateSetErrors, viewOfList } from "@protobase/schema/internal";
 import { isRecordCondition } from "@protobase/schema";
@@ -33,7 +34,7 @@ const sensitiveErrors = (view, model) => {
 		["a map", layoutItems(view.layout).flatMap((item) => item.kind === "map" ? [item.latitude, item.longitude] : [])],
 		["a gallery", layoutItems(view.layout).flatMap((item) => item.kind === "gallery" && item.image !== void 0 ? [item.image] : [])],
 		["the recent records", view.nav?.recent ? [view.nav.recent.status] : []],
-		["an action", view.actions.flatMap((action) => actionFields(action.run))]
+		["an action", view.actions.flatMap((action) => [...actionFields(action.run), ...actionWhenFields(action.when)])]
 	].flatMap(([place, names]) => [...new Set(names.filter(sensitive))].map((name) => `sensitive field "${name}" cannot be in ${place}`));
 };
 const valueLabelErrors = (view, model) => Object.entries(view.fields).flatMap(([name, hints]) => {
@@ -147,7 +148,7 @@ const listOfErrors = (model, name, models) => {
 * has a section, related section or sidebar whose `when` condition names what the app does not have, a related section or related list column, a cards display's or gallery's photos or a cards display's favorite button, a `listOf`, a "Save search" button or a
 * `searchesOf` that do not fit the resources, cards
 * displays of one list that name different photos, a chart per value that cannot group or add up its fields, a map that cannot show the
-* record's position or a map display that cannot find the records in its view, a board whose columns are no filterable enum, a calendar or timeline whose dates are no filterable date or timestamp fields, a link to an address the app does not have, an AI action that cannot write its field, action inputs that do not fit, or a create page that is not one of `pages`.
+* record's position or a map display that cannot find the records in its view, a board whose columns are no filterable enum, a calendar or timeline whose dates are no filterable date or timestamp fields, a link to an address the app does not have, an action whose `when` reads what the record does not have, an AI action that cannot write its field, action inputs that do not fit, or a create page that is not one of `pages`.
 */
 const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 	const models = Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model]));
@@ -191,6 +192,7 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...chart,
 			...linkErrors(view, model, models, pageNames, createPages),
 			...aiActionErrors(view, model),
+			...actionWhenErrors(view, model),
 			...inputErrors(view, models),
 			...createErrors(view, pageNames)
 		];

package/dist/create-admin.d.ts

@@ -60,7 +60,7 @@ export type CreateAdminInput = {
   formsDifficulty?: Difficulty;
   /** @internal The users comments name, mention and mail, which tests fake; from `auth` otherwise. */
   commentUsers?: CommentUsers;
-  /** @internal Verifies a user's token on `/realtime/v1` and gives its claims, which tests fake; those `/auth/v1` signs otherwise. */
+  /** @internal Verifies a user's token on `/rest/v1` and `/realtime/v1` and gives its claims, which tests fake; those `/auth/v1` signs otherwise. */
   verifyToken?: (token: string) => Promise<JWTPayload>;
   /**
    * The host's WebSocket upgrade, such as `@hono/node-server`'s, with which an app with keys and live resources serves

package/dist/create-admin.js

@@ -15,6 +15,7 @@ import { apiKeySettings } from "./api-keys/api-key-settings.js";
 import { apiKeyCaller } from "./api-keys/resolve-caller.js";
 import { jwtVerifier } from "./auth/jwt.js";
 import { realtimeApp } from "./realtime/realtime-app.js";
+import { restRoutes } from "./rest/rest-routes.js";
 import { readAppName } from "./app-name.js";
 import { goTruePath } from "./gotrue/keys.js";
 import { authBasePath } from "./better-auth/auth-base-path.js";
@@ -279,16 +280,22 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		report
 	});
 	if (appModels.some((model) => model.live)) app.route(systemPath || "/", guarded((live) => void live.route("/", liveRoutes(feed, (session) => visibleNotices(deps, session))), withAnonymous(authenticate, options.roles)));
-	if (upgradeWebSocket && (apiKeys.publishable || apiKeys.secret)) {
+	if (apiKeys.publishable || apiKeys.secret) {
 		const verify = verifyToken ?? (auth ? jwtVerifier(goTrueTokens({ auth })) : () => Promise.reject(unauthorized("This app signs no user tokens")));
-		app.route("/realtime/v1", realtimeApp({
+		const caller = apiKeyCaller({
+			keys: apiKeys,
+			verify
+		});
+		app.route("/rest/v1", restRoutes({
+			deps,
+			caller,
+			report
+		}));
+		if (upgradeWebSocket) app.route("/realtime/v1", realtimeApp({
 			deps,
 			feed,
 			upgradeWebSocket,
-			caller: apiKeyCaller({
-				keys: apiKeys,
-				verify
-			}),
+			caller,
 			report
 		}));
 	}

package/dist/jobs/busy-database.js

@@ -0,0 +1,18 @@
+//#region src/jobs/busy-database.ts
+/** pg-boss's database, counting its statements under way: `idle()` says whether none is, such as a worker's fetch. */
+const busyDatabase = (database) => {
+	let running = 0;
+	return {
+		db: { executeSql: async (text, values) => {
+			running++;
+			try {
+				return await database.executeSql(text, values);
+			} finally {
+				running--;
+			}
+		} },
+		idle: () => running === 0
+	};
+};
+//#endregion
+export { busyDatabase };

package/dist/jobs/runtime.js

@@ -4,6 +4,7 @@ import "./schedule.js";
 import { runJob, validatePayload } from "./run-job.js";
 import { platformMailer } from "../mail/platform-mailer.js";
 import { runInBackground } from "../background-work.js";
+import { busyDatabase } from "./busy-database.js";
 import { jobsDatabase } from "./database.js";
 import { queueOptions, queueSettingsDiffer, sendOptions, workOptions } from "./options.js";
 import { createSchedules } from "./schedules.js";
@@ -11,7 +12,7 @@ import { sql } from "kysely";
 import { PgBoss } from "pg-boss";
 //#region src/jobs/runtime.ts
 const createBoss = (db, work) => new PgBoss({
-	db: jobsDatabase(db),
+	db,
 	schema: jobsSchema,
 	migrate: false,
 	createSchema: false,
@@ -29,7 +30,8 @@ const createBoss = (db, work) => new PgBoss({
 */
 const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSeconds = 30, onError, now = () => /* @__PURE__ */ new Date(), mailer }) => {
 	const mail = mailer === void 0 ? platformMailer() : mailer || void 0;
-	const boss = createBoss(db, work);
+	const database = busyDatabase(jobsDatabase(db));
+	const boss = createBoss(database.db, work);
 	boss.on("error", onError);
 	await boss.start();
 	const schedules = createSchedules(boss, db, now);
@@ -111,9 +113,11 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
         or (j.state = 'active' and j.started_on + j.expire_seconds * interval '1s' > now()))`.execute(db);
 		return rows[0].count;
 	};
+	const settled = () => database.idle() && boss.getWipData().every((worker) => worker.count === 0);
 	const drain = async (seconds) => {
 		if (!work) throw new Error("This process runs no jobs, so it cannot drain them");
 		const deadline = Date.now() + seconds * 1e3;
+		const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 		for (;;) {
 			for (const worker of workers.values()) boss.notifyWorker(worker.id);
 			const remaining = await pending();
@@ -122,7 +126,8 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
 				remaining,
 				nextDue: await nextDue()
 			};
-			await new Promise((resolve) => setTimeout(resolve, 100));
+			await sleep(100);
+			while (!settled() && Date.now() < deadline) await sleep(10);
 		}
 	};
 	const wake = (name) => {

package/dist/rest/content-range.js

@@ -0,0 +1,14 @@
+import { restError } from "./rest-error.js";
+//#region src/rest/content-range.ts
+const contentRange = (offset, page, total) => `${page === 0 ? "*" : `${offset}-${offset + page - 1}`}/${total ?? "*"}`;
+/**
+* The status of a counted read: 206 when the page holds fewer rows than there are, 416 (PGRST103) when it starts past
+* them, else 200; uncounted, always 200.
+*/
+const rangeStatus = (offset, page, total) => {
+	if (total === void 0) return 200;
+	if (offset > total) throw restError(416, "PGRST103", "Requested range not satisfiable", `An offset of ${offset} was requested, but there are only ${total} rows.`).withHeaders({ "content-range": contentRange(offset, 0, total) });
+	return page < total ? 206 : 200;
+};
+//#endregion
+export { contentRange, rangeStatus };

package/dist/rest/embed-params.js

@@ -0,0 +1,64 @@
+import { restError } from "./rest-error.js";
+import { parseFilter } from "./parse-filter.js";
+import { parseOrder } from "./parse-order.js";
+import { embedKey } from "./parse-select.js";
+import { wholeNumber } from "./whole-number.js";
+//#region src/rest/embed-params.ts
+/**
+* The embed path a parameter's key is under, and its own name: `comments.author.username` is `username` under
+* `comments.author`, `comments.not.or` is `not.or` under `comments`. A key outside any embed has no path. A JSON path's
+* keys may hold dots, so only the part before its first arrow is split.
+*/
+const splitEmbedKey = (key) => {
+	const arrow = key.indexOf("->");
+	const head = arrow < 0 ? key : key.slice(0, arrow);
+	const tail = arrow < 0 ? "" : key.slice(arrow);
+	const segments = head.split(".");
+	const own = segments.length >= 2 && segments.at(-2) === "not" && /^(and|or)$/.test(segments.at(-1)) ? 2 : 1;
+	if (segments.length <= own) return { name: key };
+	return {
+		path: segments.slice(0, -own).join("."),
+		name: segments.slice(-own).join(".") + tail
+	};
+};
+/** The path of every embed of `select`, nested ones as `comments.author`, by the names they go by. */
+const embedPaths = (select, prefix = "") => select.flatMap((item) => {
+	if (item.kind !== "embed") return [];
+	const path = prefix + embedKey(item);
+	return [path, ...embedPaths(item.select, `${path}.`)];
+});
+/**
+* The parameters under an embed's path, by path: `comments.likes=gte.2` filters the comments, `comments.order`,
+* `comments.limit` and `comments.offset` sort and page them. A path no embed of `select` has is PGRST108.
+*/
+const parseEmbedParams = (params, select) => {
+	const known = new Set(embedPaths(select));
+	const byPath = /* @__PURE__ */ new Map();
+	for (const [key, value] of params) {
+		const { path, name } = splitEmbedKey(key);
+		if (path === void 0) continue;
+		if (!known.has(path)) {
+			const resource = path.split(".").at(-1);
+			throw restError(400, "PGRST108", `'${resource}' is not an embedded resource in this request`, null, `Verify that '${resource}' is included in the 'select' query parameter.`);
+		}
+		const embed = byPath.get(path) ?? {
+			filters: [],
+			order: [],
+			range: { offset: 0 }
+		};
+		byPath.set(path, embed);
+		if (name === "order") embed.order = parseOrder(value);
+		else if (name === "limit") embed.range = {
+			...embed.range,
+			limit: wholeNumber(key, value)
+		};
+		else if (name === "offset") embed.range = {
+			...embed.range,
+			offset: wholeNumber(key, value)
+		};
+		else embed.filters.push(parseFilter(name, value));
+	}
+	return byPath;
+};
+//#endregion
+export { parseEmbedParams, splitEmbedKey };

package/dist/rest/embed-shape.js

@@ -0,0 +1,42 @@
+import { embedKey } from "./parse-select.js";
+import { findRelationship } from "./find-relationship.js";
+//#region src/rest/embed-shape.ts
+const noParams = {
+	filters: [],
+	order: [],
+	range: { offset: 0 }
+};
+/**
+* Resolves the embeds of `select`, read from rows of `source`, to the relationships they go through, depth first:
+* PGRST200 or PGRST201 for an embed without one or with several.
+*/
+const resolveShape = (context, source, select) => {
+	let count = 0;
+	const resolve = (table, items, prefix) => items.map((item) => {
+		if (item.kind !== "embed") return item;
+		const from = context.served(item.name);
+		const relationship = findRelationship(from ? context.foreignKeys : [], table, item.name, item.hint);
+		const path = prefix + embedKey(item);
+		const alias = `${item.name}_${++count}`;
+		return {
+			kind: "embed",
+			key: embedKey(item),
+			table: item.name,
+			from,
+			alias,
+			relationship,
+			toOne: relationship.cardinality !== "one-to-many",
+			inner: item.inner,
+			shown: item.select.length > 0,
+			shape: resolve(item.name, item.select, `${path}.`),
+			params: context.embedded.get(path) ?? noParams
+		};
+	});
+	return resolve(source, select, "");
+};
+/** Every embed of the shape, nested ones included. */
+const embedsOf = (shape) => shape.flatMap((item) => item.kind === "embed" ? [item, ...embedsOf(item.shape)] : []);
+/** The name of the lateral subquery an embed's JSON comes from, as `body`. */
+const lateralName = (embed) => `pgrst_${embed.alias}`;
+//#endregion
+export { embedsOf, lateralName, resolveShape };

package/dist/rest/embed-sql.js

@@ -0,0 +1,24 @@
+import { lateralName } from "./embed-shape.js";
+import { filterSql } from "./filter-sql.js";
+import { orderSql, rangeSql, selectSql } from "./shape-sql.js";
+import { sql } from "kysely";
+//#region src/rest/embed-sql.ts
+const relatedRowsSql = (source, embed) => {
+	const related = embed.relationship.join.map((pair) => sql`${sql.id(embed.alias, pair.target)} = ${sql.id(source, pair.source)}`);
+	const where = sql.join([...related, ...embed.params.filters.map((filter) => filterSql(embed.alias, filter))], sql` and `);
+	const columns = selectSql(embed.alias, embed.shape);
+	return sql`select ${columns} from ${embed.from} as ${sql.id(embed.alias)}${joinsSql(embed.alias, embed.shape)} where ${where}${orderSql(embed.alias, embed.params.order)}${rangeSql(embed.params.range)}`;
+};
+const lateralSql = (source, embed) => {
+	const rows = relatedRowsSql(source, embed);
+	const body = embed.toOne ? sql`select row_to_json(pgrst_rows) as body from (${rows}) as pgrst_rows` : sql`select coalesce(json_agg(pgrst_rows), '[]') as body from (${rows}) as pgrst_rows${embed.inner ? sql` having count(*) > 0` : sql``}`;
+	return sql` ${sql.raw(embed.inner ? "inner" : "left")} join lateral (${body}) as ${sql.id(lateralName(embed))} on true`;
+};
+/**
+* The lateral joins that read the embeds of the shape for each row of `source`, which `selectSql` picks their JSON
+* from. They run in the same query as the caller, so the RLS policies of every embedded table apply. An inner embed's
+* join drops the rows without a related row.
+*/
+const joinsSql = (source, shape) => sql.join(shape.flatMap((item) => item.kind === "embed" ? [lateralSql(source, item)] : []), sql``);
+//#endregion
+export { joinsSql };

package/dist/rest/field-path.js

@@ -0,0 +1,25 @@
+import { parseError } from "./rest-error.js";
+//#region src/rest/field-path.ts
+/** Parses `column`, `column->key` or `column->a->>b`; `->` may not end it or follow a `->>`. */
+const parseFieldPath = (text) => {
+	const parts = text.trim().split(/(->>|->)/);
+	const column = parts[0].trim();
+	if (!column) throw parseError(`"${text}" names no column`);
+	const json = [];
+	for (let i = 1; i < parts.length; i += 2) {
+		const key = parts[i + 1].trim();
+		if (!key) throw parseError(`"${text}" ends in an arrow`);
+		json.push({
+			arrow: parts[i],
+			key: /^-?\d+$/.test(key) ? Number(key) : key
+		});
+	}
+	return {
+		column,
+		json
+	};
+};
+/** The name a JSON path's value goes by in a row: its last key, else the column. */
+const pathName = (path) => String(path.json.at(-1)?.key ?? path.column);
+//#endregion
+export { parseFieldPath, pathName };

package/dist/rest/filter-sql.js

@@ -0,0 +1,62 @@
+import { sql } from "kysely";
+//#region src/rest/filter-sql.ts
+/** A field of the row source named `source`: `"todos"."meta"->$1::text`. Every key is a parameter. */
+const fieldSql = (source, path) => path.json.reduce((value, step) => sql`(${value}${sql.raw(step.arrow)}${typeof step.key === "number" ? sql`${step.key}::integer` : sql`${step.key}::text`})`, sql`${sql.id(source, path.column)}`);
+const comparisons = {
+	eq: "=",
+	neq: "<>",
+	gt: ">",
+	gte: ">=",
+	lt: "<",
+	lte: "<=",
+	like: "like",
+	ilike: "ilike",
+	match: "~",
+	imatch: "~*",
+	isdistinct: "is distinct from",
+	cs: "@>",
+	cd: "<@",
+	ov: "&&",
+	sl: "<<",
+	sr: ">>",
+	nxr: "&<",
+	nxl: "&>",
+	adj: "-|-"
+};
+const tsQueries = {
+	fts: "to_tsquery",
+	plfts: "plainto_tsquery",
+	phfts: "phraseto_tsquery",
+	wfts: "websearch_to_tsquery"
+};
+const isTests = {
+	null: "is null",
+	not_null: "is not null",
+	true: "is true",
+	false: "is false",
+	unknown: "is unknown"
+};
+/** A Postgres array literal of the values, each quoted, so Postgres reads it as an array of the column's type. */
+const arrayLiteral = (values) => `{${values.map((value) => `"${value.replace(/[\\"]/g, "\\$&")}"`).join(",")}}`;
+const pattern = (operator, value) => operator === "like" || operator === "ilike" ? value.replaceAll("*", "%") : value;
+const conditionSql = (source, condition) => {
+	const field = fieldSql(source, condition.field);
+	const { operator, value } = condition;
+	if (operator === "in") return sql`${field} = any(${arrayLiteral(value)})`;
+	if (operator === "is") return sql`${field} ${sql.raw(isTests[value])}`;
+	const text = pattern(operator, value);
+	const tsQuery = tsQueries[operator];
+	if (tsQuery) return condition.language === void 0 ? sql`${field} @@ ${sql.raw(tsQuery)}(${text})` : sql`${field} @@ ${sql.raw(tsQuery)}(${condition.language}, ${text})`;
+	const comparison = sql.raw(comparisons[operator]);
+	if (condition.quantifier) return sql`${field} ${comparison} ${sql.raw(condition.quantifier)}(${text})`;
+	return sql`${field} ${comparison} ${text}`;
+};
+/** A filter as a condition on the rows of `source`; every value is a parameter, every name a quoted identifier. */
+const filterSql = (source, filter) => {
+	const condition = filter.kind === "condition" ? conditionSql(source, filter) : filter.args.length === 0 ? sql.raw(filter.kind === "and" ? "true" : "false") : sql`(${sql.join(filter.args.map((arg) => filterSql(source, arg)), sql.raw(` ${filter.kind} `))})`;
+	return filter.negated ? sql`not (${condition})` : condition;
+};
+/** ` where ...` for the filters, all of which hold; nothing without any. */
+const whereSql = (source, filters) => filters.length === 0 ? sql`` : sql` where ${sql.join(filters.map((filter) => filterSql(source, filter)), sql` and `)}`;
+//#endregion
+export { arrayLiteral, fieldSql, filterSql, whereSql };

package/dist/rest/find-relationship.js

@@ -0,0 +1,39 @@
+import { restError } from "./rest-error.js";
+//#region src/rest/find-relationship.ts
+const pairs = (sources, targets) => sources.map((source, i) => ({
+	source,
+	target: targets[i]
+}));
+/** The relationships from `source` to `target`: its foreign keys to `target`, and `target`'s foreign keys to it. */
+const relationshipsBetween = (keys, source, target) => [...keys.filter((key) => key.table === source && key.foreignTable === target).map((key) => ({
+	foreignKey: key,
+	cardinality: key.unique ? "one-to-one" : "many-to-one",
+	join: pairs(key.columns, key.foreignColumns)
+})), ...keys.filter((key) => key.foreignTable === source && key.table === target).map((key) => ({
+	foreignKey: key,
+	cardinality: key.unique ? "one-to-one" : "one-to-many",
+	join: pairs(key.foreignColumns, key.columns)
+}))];
+const matchesHint = (relationship, hint) => {
+	const { name, columns, foreignColumns } = relationship.foreignKey;
+	return name === hint || columns.length === 1 && (columns[0] === hint || foreignColumns[0] === hint);
+};
+const columnList = (table, columns) => `${table}(${columns.join(", ")})`;
+const ambiguity = (source, target, found) => restError(300, "PGRST201", `Could not embed because more than one relationship was found for '${source}' and '${target}'`, found.map((one) => ({
+	cardinality: one.cardinality,
+	embedding: `${source} with ${target}`,
+	relationship: `${one.foreignKey.name} using ${columnList(source, one.join.map((pair) => pair.source))} and ${columnList(target, one.join.map((pair) => pair.target))}`
+})), `Try changing '${target}' to one of the following: ${found.map((one) => `'${target}!${one.foreignKey.name}'`).join(", ")}. Find the desired relationship in the 'details' key.`);
+/**
+* The one relationship an embed of `target` in rows of `source` goes through, narrowed by its hint: PGRST200 when
+* there is none, PGRST201 when several remain.
+*/
+const findRelationship = (keys, source, target, hint) => {
+	const found = relationshipsBetween(keys, source, target).filter((one) => hint === void 0 || matchesHint(one, hint));
+	if (found.length === 1) return found[0];
+	if (found.length > 1) throw ambiguity(source, target, found);
+	const using = hint === void 0 ? "" : ` using the hint '${hint}'`;
+	throw restError(400, "PGRST200", `Could not find a relationship between '${source}' and '${target}' in the schema cache`, `Searched for a foreign key relationship between '${source}' and '${target}'${using} in the schema 'public', but no matches were found.`);
+};
+//#endregion
+export { findRelationship };

package/dist/rest/foreign-keys.js

@@ -0,0 +1,32 @@
+import { sql } from "kysely";
+//#region src/rest/foreign-keys.ts
+const readForeignKeys = async (db) => {
+	const { rows } = await sql`
+    select c.conname::text as name, s.relname::text as table, t.relname::text as "foreignTable",
+      array(select a.attname::text from unnest(c.conkey) with ordinality k(attnum, ord) join pg_attribute a on a.attrelid = c.conrelid and a.attnum = k.attnum order by k.ord) as columns,
+      array(select a.attname::text from unnest(c.confkey) with ordinality k(attnum, ord) join pg_attribute a on a.attrelid = c.confrelid and a.attnum = k.attnum order by k.ord) as "foreignColumns",
+      exists (select 1 from pg_constraint u where u.conrelid = c.conrelid and u.contype in ('p', 'u') and u.conkey @> c.conkey and u.conkey <@ c.conkey) as unique
+    from pg_constraint c
+    join pg_class s on s.oid = c.conrelid
+    join pg_class t on t.oid = c.confrelid
+    where c.contype = 'f' and s.relnamespace = 'public'::regnamespace and t.relnamespace = 'public'::regnamespace
+    order by c.conname
+  `.execute(db);
+	return rows;
+};
+/**
+* The foreign keys of the `public` schema, which `/rest/v1` embeds through, read from the catalog once and kept for the
+* process lifetime, as the scan guard keeps indexes: migrations run before a new version serves.
+*/
+const foreignKeyCache = (db) => {
+	let known;
+	return () => {
+		known ??= readForeignKeys(db).catch((error) => {
+			known = void 0;
+			throw error;
+		});
+		return known;
+	};
+};
+//#endregion
+export { foreignKeyCache };

package/dist/rest/functions.js

@@ -0,0 +1,92 @@
+import { restError } from "./rest-error.js";
+import { sql } from "kysely";
+//#region src/rest/functions.ts
+/** The functions of the `public` schema called `name`, every overload. */
+const findFunctions = async (db, name) => {
+	const { rows } = await sql`
+    select p.proname as name, p.proargnames as arg_names, p.proargmodes::text[] as arg_modes, p.pronargdefaults::int as defaults,
+      array(select format_type(t.oid, null) from unnest(p.proargtypes::oid[]) with ordinality as t(oid, i) order by t.i) as input_types,
+      format_type(p.prorettype, null) as returns, r.typtype as return_kind, p.proretset as set
+    from pg_proc p join pg_namespace n on n.oid = p.pronamespace join pg_type r on r.oid = p.prorettype
+    where n.nspname = 'public' and p.proname = ${name} and p.prokind = 'f'
+    order by p.oid
+  `.execute(db);
+	return rows.map((row) => {
+		const names = (row.arg_names ?? []).filter((_, i) => !row.arg_modes || [
+			"i",
+			"b",
+			"v"
+		].includes(row.arg_modes[i]));
+		const returns = row.returns === "void" ? "void" : row.return_kind === "c" || row.returns === "record" ? "row" : "scalar";
+		return {
+			name: row.name,
+			inputs: row.input_types.map((type, i) => ({
+				name: names[i] ?? "",
+				type
+			})),
+			defaults: row.defaults,
+			returns,
+			set: row.set
+		};
+	});
+};
+const takesBody = (info) => info.inputs.length === 1 && info.inputs[0].name === "" && ["json", "jsonb"].includes(info.inputs[0].type);
+const listed = (names) => [...names].sort().join(", ");
+/**
+* The overload a call with these argument names reaches: one whose inputs include every name and whose inputs without
+* a default are all given; else one that takes the body as its single unnamed json or jsonb argument. None is 404
+* (PGRST202) and more than one 300 (PGRST203), worded as PostgREST words them.
+*/
+const chooseFunction = (name, candidates, given) => {
+	const byName = candidates.filter((info) => {
+		const inputs = info.inputs.map((input) => input.name);
+		const required = inputs.slice(0, inputs.length - info.defaults);
+		return given.every((arg) => inputs.includes(arg)) && required.every((arg) => given.includes(arg));
+	});
+	const matches = byName.length > 0 ? byName.map((info) => ({
+		info,
+		by: "name",
+		args: info.inputs.map((input) => input.name).filter((arg) => given.includes(arg))
+	})) : candidates.filter(takesBody).map((info) => ({
+		info,
+		by: "body"
+	}));
+	if (matches.length === 1) return matches[0];
+	const signature = given.length === 0 ? `public.${name} without parameters` : `public.${name}(${listed(given)})`;
+	if (matches.length > 1) {
+		const overloads = matches.map((match) => `public.${name}(${match.info.inputs.map((input) => `${input.name} => ${input.type}`.trim()).join(", ")})`);
+		throw restError(300, "PGRST203", `Could not choose the best candidate function between: ${overloads.join(", ")}`, null, "Try renaming the parameters or the function itself in the database so function overloading can be resolved");
+	}
+	const searched = given.length === 0 ? `public.${name} without parameters` : `public.${name} with parameters ${listed(given)}`;
+	const hint = candidates[0] ? `Perhaps you meant to call the function public.${name}(${candidates[0].inputs.map((input) => input.name).join(", ")})` : null;
+	throw restError(404, "PGRST202", `Could not find the function ${signature} in the schema cache`, `Searched for the function ${searched} or with a single unnamed json/jsonb parameter, but no matches were found in the schema cache.`, hint);
+};
+/**
+* The call in FROM, its rows named after the function: arguments read by name from the JSON object `args` as the types
+* the catalog gives them, so Postgres converts them as it reads JSON into a row; or `args` itself as the one argument.
+* Types come from the catalog, never from the request.
+*/
+const callSource = (call, args) => {
+	const fn = sql.id("public", call.info.name);
+	const alias = call.info.name;
+	const scalar = call.info.returns !== "row";
+	if (call.by === "body") return {
+		from: sql`${fn}(cast(${JSON.stringify(args)} as ${sql.raw(call.info.inputs[0].type)})) as ${sql.id(alias)}`,
+		alias,
+		scalar
+	};
+	if (call.args.length === 0) return {
+		from: sql`${fn}() as ${sql.id(alias)}`,
+		alias,
+		scalar
+	};
+	const types = call.info.inputs.filter((input) => call.args.includes(input.name)).map((input) => sql`${sql.id(input.name)} ${sql.raw(input.type)}`);
+	const named = sql.join(call.args.map((arg) => sql`${sql.id(arg)} := pgrst_args.${sql.id(arg)}`));
+	return {
+		from: sql`json_to_record(${JSON.stringify(args)}::json) as pgrst_args(${sql.join(types)}) cross join lateral ${fn}(${named}) as ${sql.id(alias)}`,
+		alias,
+		scalar
+	};
+};
+//#endregion
+export { callSource, chooseFunction, findFunctions };