@protobase/server 0.26.7 → 0.26.8

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/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/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/parse-query.js

@@ -1,8 +1,9 @@
-import { parseError } from "./rest-error.js";
 import { splitList, unquote } from "./split-list.js";
 import { parseFilter } from "./parse-filter.js";
 import { parseOrder } from "./parse-order.js";
 import { parseSelect } from "./parse-select.js";
+import { wholeNumber } from "./whole-number.js";
+import { parseEmbedParams, splitEmbedKey } from "./embed-params.js";
 //#region src/rest/parse-query.ts
 const reserved = /* @__PURE__ */ new Set([
 	"select",
@@ -12,10 +13,6 @@ const reserved = /* @__PURE__ */ new Set([
 	"on_conflict",
 	"columns"
 ]);
-const count = (name, text) => {
-	if (!/^\d+$/.test(text)) throw parseError(`"failed to parse ${name} (${text})"`, `${name} takes a whole number`);
-	return Number(text);
-};
 const names = (text) => splitList(text).map((name) => unquote(name.trim()));
 /** `Range: 2-4` or `Range: 5-`, in items; anything else asks for every row, as PostgREST takes it. */
 const rangeHeader = (header) => {
@@ -37,7 +34,8 @@ const intersect = (a, b) => {
 };
 /**
 * Parses a request's query parameters. The ones in `args` are a function's arguments, not filters. `select`, `order`,
-* `limit`, `offset`, `on_conflict` and `columns` count once, the first time; every other parameter is a filter.
+* `limit`, `offset`, `on_conflict` and `columns` count once, the first time; a parameter under an embed's path, such
+* as `comments.likes`, is the embed's (see `parseEmbedParams`); every other parameter is a filter.
 */
 const parseQuery = (params, rangeText = null, args = /* @__PURE__ */ new Set()) => {
 	const first = (name) => params.find(([key]) => key === name)?.[1];
@@ -46,13 +44,16 @@ const parseQuery = (params, rangeText = null, args = /* @__PURE__ */ new Set())
 	const order = first("order");
 	const onConflict = first("on_conflict");
 	const columns = first("columns");
+	const select = parseSelect(first("select"));
+	const own = params.filter(([key]) => !reserved.has(key) && !args.has(key));
 	const fromParams = {
-		offset: offset === void 0 ? 0 : count("offset", offset),
-		...limit !== void 0 && { limit: count("limit", limit) }
+		offset: offset === void 0 ? 0 : wholeNumber("offset", offset),
+		...limit !== void 0 && { limit: wholeNumber("limit", limit) }
 	};
 	return {
-		select: parseSelect(first("select")),
-		filters: params.filter(([key]) => !reserved.has(key) && !args.has(key)).map(([key, value]) => parseFilter(key, value)),
+		select,
+		filters: own.filter(([key]) => splitEmbedKey(key).path === void 0).map(([key, value]) => parseFilter(key, value)),
+		embedded: parseEmbedParams(own, select),
 		order: order === void 0 ? [] : parseOrder(order),
 		range: intersect(fromParams, rangeHeader(rangeText)),
 		...onConflict !== void 0 && { onConflict: names(onConflict) },

package/dist/rest/parse-select.js

@@ -3,10 +3,26 @@ import { parseFieldPath } from "./field-path.js";
 import { splitList } from "./split-list.js";
 //#region src/rest/parse-select.ts
 const typeName = /^[A-Za-z_][A-Za-z0-9_]*(\[\])?$/;
+const embedPattern = /^(?:([^:(!]+):(?!:))?([^!(]+)((?:![^!(]+)*)\(([\s\S]*)\)$/;
+const parseEmbed = (item) => {
+	const [, alias, nameText = "", modifiers = "", inner = ""] = embedPattern.exec(item) ?? [];
+	const name = nameText.trim();
+	if (!name || name.startsWith("...") || name.includes(".") || name === "count") throw restError(400, "PGRST100", `"${item}" spreads a resource or calls an aggregate, which /rest/v1 does not support yet`);
+	const flags = modifiers.split("!").slice(1).map((flag) => flag.trim());
+	const hint = flags.find((flag) => flag !== "inner" && flag !== "left");
+	return {
+		kind: "embed",
+		name,
+		...alias?.trim() && { alias: alias.trim() },
+		...hint !== void 0 && { hint },
+		inner: flags.includes("inner"),
+		select: inner.trim() === "" ? [] : splitList(inner).map(parseItem)
+	};
+};
 const parseItem = (text) => {
 	const item = text.trim();
 	if (item === "*") return { kind: "all" };
-	if (item.includes("(")) throw restError(400, "PGRST100", `"${item}" embeds a resource or calls an aggregate, which /rest/v1 does not support yet`);
+	if (item.includes("(")) return parseEmbed(item);
 	const aliased = /^([^:]+):(?!:)([\s\S]*)$/.exec(item);
 	const alias = aliased?.[1]?.trim();
 	const [fieldText = "", cast, ...more] = (aliased ? aliased[2] : item).split("::");
@@ -20,5 +36,7 @@ const parseItem = (text) => {
 };
 /** Parses `select`: items separated by commas, `*` for every column. Missing or empty, it is `*`. */
 const parseSelect = (text) => text === void 0 || text.trim() === "" ? [{ kind: "all" }] : splitList(text).map(parseItem);
+/** The name an embed goes by in a row and in the parameters that filter it: its alias, else its name. */
+const embedKey = (item) => item.alias ?? item.name;
 //#endregion
-export { parseSelect };
+export { embedKey, parseSelect };

package/dist/rest/read-rows.js

@@ -1,34 +1,36 @@
 import { whereSql } from "./filter-sql.js";
 import { orderSql, rangeSql, selectSql } from "./shape-sql.js";
+import { joinsSql } from "./embed-sql.js";
 import { sql } from "kysely";
 //#region src/rest/read-rows.ts
 /** The most rows a read returns, as Supabase's `db-max-rows` default. */
 const maxRows = 1e3;
-const plannedRows = async (trx, source, query) => {
-	const { rows } = await sql`explain (format json) select 1 from ${source.from}${whereSql(source.alias, query.filters)}`.execute(trx);
+const plannedRows = async (trx, source, filtered) => {
+	const { rows } = await sql`explain (format json) select 1 from ${source.from}${filtered}`.execute(trx);
 	return rows[0]["QUERY PLAN"][0].Plan["Plan Rows"];
 };
 /**
-* Reads the rows of `source` the query asks for: filtered, shaped by `select`, sorted, in its range and never more than
+* Reads the rows of `source` the query asks for: filtered, shaped by `shape` (its `select`, embeds resolved), sorted, in its range and never more than
 * `maxRows`, as one JSON array built by Postgres, so values reach the client exactly as Postgres writes them. `count`
 * counts the matching rows: `exact` by counting, `planned` by the planner's estimate, `estimated` by counting up to
-* `maxRows` and estimating beyond.
+* `maxRows` and estimating beyond. The rows an inner embed drops are not counted.
 */
-const readRows = async (trx, source, query, count) => {
+const readRows = async (trx, source, shape, query, count) => {
 	const where = whereSql(source.alias, query.filters);
+	const filtered = sql`${joinsSql(source.alias, shape.filter((item) => item.kind === "embed" && item.inner))}${where}`;
 	const range = {
 		offset: query.range.offset,
 		limit: Math.min(query.range.limit ?? 1e3, maxRows)
 	};
-	const columns = source.scalar ? sql`${sql.id(source.alias)} as pgrst_scalar` : selectSql(source.alias, query.select);
-	const rows = sql`select ${columns} from ${source.from}${where}${orderSql(source.alias, query.order)}${rangeSql(range)}`;
-	const counted = count === "exact" || count === "estimated" ? sql`(select count(*) from ${source.from}${where})` : sql`null::bigint`;
+	const columns = source.scalar ? sql`${sql.id(source.alias)} as pgrst_scalar` : selectSql(source.alias, shape);
+	const rows = sql`select ${columns} from ${source.from}${joinsSql(source.alias, shape)}${where}${orderSql(source.alias, query.order)}${rangeSql(range)}`;
+	const counted = count === "exact" || count === "estimated" ? sql`(select count(*) from ${source.from}${filtered})` : sql`null::bigint`;
 	const aggregate = source.scalar ? sql`json_agg(pgrst_rows.pgrst_scalar)` : sql`json_agg(pgrst_rows)`;
 	const { rows: [result] } = await sql`
     select coalesce(${aggregate}, '[]')::text as body, count(*) as page, ${counted} as total from (${rows}) as pgrst_rows
   `.execute(trx);
 	const exact = result.total === null ? void 0 : Number(result.total);
-	const total = count === "planned" || count === "estimated" && exact > 1e3 ? await plannedRows(trx, source, query) : exact;
+	const total = count === "planned" || count === "estimated" && exact > 1e3 ? await plannedRows(trx, source, filtered) : exact;
 	return {
 		body: result.body,
 		page: Number(result.page),

package/dist/rest/rest-routes.js

@@ -1,4 +1,5 @@
 import { HttpProblem } from "../problem.js";
+import { foreignKeyCache } from "./foreign-keys.js";
 import { restError, restErrorOf } from "./rest-error.js";
 import { errorResponse } from "./respond.js";
 import { rpcRoute } from "./rpc-route.js";
@@ -25,7 +26,7 @@ const restRoutes = ({ deps, caller, report }) => {
 		await next();
 	});
 	app.route("/", rpcRoute(deps));
-	app.route("/", tableRoutes(deps));
+	app.route("/", tableRoutes(deps, foreignKeyCache(deps.db)));
 	app.notFound(() => errorResponse(restError(404, "PGRST125", "Invalid path specified in request URL")));
 	return app;
 };

package/dist/rest/rest-scan.js

@@ -71,22 +71,34 @@ const suggestion = (table, read) => {
 	return `create index on ${table} (${column})`;
 };
 /**
-* The reads of a request no index of the table serves: each filtered field, by the kind of index its operator needs,
-* and the first sort field. A view or a foreign table has no indexes of its own and is not judged.
+* The reads of a request no index of the table serves: each column an embed joins on, which equals one value per
+* related row; each filtered field, by the kind of index its operator needs; and the first sort field. A view or a
+* foreign table has no indexes of its own and is not judged.
 */
-const uncoveredReads = (table, filters, order) => {
+const uncoveredReads = (table, filters, order, joined = []) => {
 	if (table.kind !== "table") return [];
-	const pinned = new Set(filters.flatMap(pinnedFields));
-	return [...filters.flatMap(filterReads), ...order[0] ? [{
-		field: order[0].field,
-		need: "btree",
-		use: "sort"
-	}] : []].filter((read) => !table.indexes.some((index) => serves(index, read, pinned)));
+	const pinned = /* @__PURE__ */ new Set([...joined, ...filters.flatMap(pinnedFields)]);
+	return [
+		...joined.map((column) => ({
+			field: {
+				column,
+				json: []
+			},
+			need: "equality",
+			use: "join"
+		})),
+		...filters.flatMap(filterReads),
+		...order[0] ? [{
+			field: order[0].field,
+			need: "btree",
+			use: "sort"
+		}] : []
+	].filter((read) => !table.indexes.some((index) => serves(index, read, pinned)));
 };
 /** The 400 error of a read no index serves, with the statement that adds one as its hint. */
 const scanRefusal = (table, read) => {
 	const tableName = table.schema ? `${quoted(table.schema)}.${quoted(table.name)}` : quoted(table.name);
-	const what = read.use === "sort" ? "Sorting by" : "Filtering on";
+	const what = read.use === "sort" ? "Sorting by" : read.use === "join" ? "Embedding through" : "Filtering on";
 	const index = read.need === "btree" || read.need === "equality" ? "an index" : read.need === "trigram" ? "a pg_trgm index" : read.need === "gist" ? "a GiST index" : "a GIN index";
 	return restError(400, "expensive-query", `${what} "${pathKey(read.field)}" needs ${index} that serves it`, null, suggestion(tableName, read));
 };

package/dist/rest/rpc-route.js

@@ -1,3 +1,4 @@
+import { restError } from "./rest-error.js";
 import { jsonType, onlyElement, pageResponse, wantsObject } from "./respond.js";
 import { callSource, chooseFunction, findFunctions } from "./functions.js";
 import { parsePrefer } from "./parse-prefer.js";
@@ -36,6 +37,10 @@ const call = async (deps, c) => {
 		const args = get ? Object.fromEntries(params.filter(([key]) => given.includes(key))) : body;
 		const source = callSource(chosen, args);
 		const query = parseQuery(params, c.req.header("range") ?? null, new Set(given));
+		const shape = query.select.map((item) => {
+			if (item.kind === "embed") throw restError(400, "PGRST100", `"${item.name}" embeds a resource in a function's rows, which /rest/v1 does not support yet`);
+			return item;
+		});
 		if (chosen.info.returns === "void") {
 			await sql`select 1 from ${source.from}`.execute(trx);
 			return new Response(null, {
@@ -44,7 +49,7 @@ const call = async (deps, c) => {
 			});
 		}
 		if (!chosen.info.set) {
-			const page = await readRows(trx, source, query);
+			const page = await readRows(trx, source, shape, query);
 			return new Response(onlyElement(page.body), {
 				status: 200,
 				headers: {
@@ -53,7 +58,7 @@ const call = async (deps, c) => {
 				}
 			});
 		}
-		return pageResponse(await readRows(trx, source, query, prefer.count), query.range.offset, object);
+		return pageResponse(await readRows(trx, source, shape, query, prefer.count), query.range.offset, object);
 	});
 };
 const rpcRoute = (deps) => {

package/dist/rest/shape-sql.js

@@ -1,16 +1,19 @@
 import { pathName } from "./field-path.js";
+import { lateralName } from "./embed-shape.js";
 import { fieldSql } from "./filter-sql.js";
 import { sql } from "kysely";
 //#region src/rest/shape-sql.ts
 /**
-* The select list of `select` on the rows of `source`: `*` its columns, a field under its alias, its JSON path's last
-* key or its column, cast when asked. Cast types are checked to be bare type names when parsed.
+* The select list of a shape on the rows of `source`: `*` its columns, a field under its alias, its JSON path's last
+* key or its column, cast when asked, and an embed's JSON from its lateral subquery (see `joinsSql`) under its key; an
+* embed of nothing shows nothing. Cast types are checked to be bare type names when parsed.
 */
-const selectSql = (source, items) => sql.join(items.map((item) => {
-	if (item.kind === "all") return sql`${sql.id(source)}.*`;
+const selectSql = (source, items) => sql.join(items.flatMap((item) => {
+	if (item.kind === "all") return [sql`${sql.id(source)}.*`];
+	if (item.kind === "embed") return item.shown ? [sql`${sql.id(lateralName(item))}.body as ${sql.id(item.key)}`] : [];
 	const value = fieldSql(source, item.field);
 	const cast = item.cast === void 0 ? value : sql`cast(${value} as ${sql.raw(item.cast)})`;
-	return sql`${cast} as ${sql.id(item.alias ?? pathName(item.field))}`;
+	return [sql`${cast} as ${sql.id(item.alias ?? pathName(item.field))}`];
 }));
 /** ` order by ...` for the terms; nothing without any. */
 const orderSql = (source, terms) => terms.length === 0 ? sql`` : sql` order by ${sql.join(terms.map((term) => sql`${fieldSql(source, term.field)}${sql.raw(term.direction ? ` ${term.direction}` : "")}${sql.raw(term.nulls ? ` nulls ${term.nulls}` : "")}`))}`;

package/dist/rest/table-routes.js

@@ -4,6 +4,7 @@ import { contentRange } from "./content-range.js";
 import { checkSingle, jsonType, objectType, onlyElement, pageResponse, wantsObject } from "./respond.js";
 import { parsePrefer } from "./parse-prefer.js";
 import { parseQuery } from "./parse-query.js";
+import { embedsOf, resolveShape } from "./embed-shape.js";
 import { readRows } from "./read-rows.js";
 import { asCaller, queryParams, readBody } from "./rest-context.js";
 import { scanRefusal, uncoveredReads } from "./rest-scan.js";
@@ -15,25 +16,56 @@ import { sql } from "kysely";
 * The resource whose table `name` is, in the `public` schema or the search path's: `/rest/v1` serves the tables the app
 * declares as resources, as PostgREST serves those of its exposed schema. Any other is 404 (PGRST205).
 */
+const servedEntry = (deps, name) => deps.registry.entries.find((one) => one.model.table.name === name && (one.model.table.schema ?? "public") === "public");
 const tableEntry = (deps, name) => {
-	const entry = deps.registry.entries.find((one) => one.model.table.name === name && (one.model.table.schema ?? "public") === "public");
+	const entry = servedEntry(deps, name);
 	if (!entry) throw restError(404, "PGRST205", `Could not find the table 'public.${name}' in the schema cache`);
 	return entry;
 };
+/** The select list of the query on rows of `entry`'s table, its embeds resolved through the foreign keys of served tables. */
+const shapeOf = async (deps, foreignKeys, entry, query) => {
+	if (!query.select.some((item) => item.kind === "embed")) return query.select;
+	const served = (name) => {
+		const target = servedEntry(deps, name);
+		return target && tableId(target.model);
+	};
+	return resolveShape({
+		foreignKeys: await foreignKeys(),
+		served,
+		embedded: query.embedded
+	}, entry.model.table.name, query.select);
+};
 const targetOf = (entry) => ({
 	table: tableId(entry.model),
 	alias: entry.model.table.name
 });
-/** Refuses filters and a sort no index serves, as the scan guard does on `/api/v1`; in `warn` mode, a warning header instead. */
-const scanCheck = async (deps, entry, filters, order) => {
+/**
+* Refuses filters and a sort no index serves, as the scan guard does on `/api/v1`, on the table and on every embedded
+* one, whose join columns need an index too; in `warn` mode, a warning header instead.
+*/
+const scanCheck = async (deps, entry, filters, order, shape = []) => {
 	if (deps.guard.mode === "off") return {};
-	const [first] = uncoveredReads(await deps.guard.indexesOf(entry), filters, order);
-	if (!first) return {};
-	const refusal = scanRefusal(entry.model.table, first);
-	if (deps.guard.mode === "warn") return { "X-Protobase-Warning": refusal.body.message };
-	throw refusal;
+	const reads = [{
+		entry,
+		filters,
+		order,
+		joined: []
+	}, ...embedsOf(shape).map((embed) => ({
+		entry: tableEntry(deps, embed.table),
+		filters: embed.params.filters,
+		order: embed.params.order,
+		joined: embed.relationship.join.map((pair) => pair.target)
+	}))];
+	for (const read of reads) {
+		const [first] = uncoveredReads(await deps.guard.indexesOf(read.entry), read.filters, read.order, read.joined);
+		if (!first) continue;
+		const refusal = scanRefusal(read.entry.model.table, first);
+		if (deps.guard.mode === "warn") return { "X-Protobase-Warning": refusal.body.message };
+		throw refusal;
+	}
+	return {};
 };
-const returningOf = (prefer, query) => prefer.return === "representation" ? { select: query.select } : void 0;
+const returningOf = (prefer, shape) => prefer.return === "representation" ? { shape } : void 0;
 const counted = (prefer, total) => prefer.count === void 0 ? void 0 : total;
 /** A write's response: the rows it returns when asked for, as an array or one object; else no body, with `emptyStatus`. */
 const writeResponse = (written, object, status, emptyStatus, range) => {
@@ -49,6 +81,10 @@ const writeResponse = (written, object, status, emptyStatus, range) => {
 		}
 	});
 };
+const withHeaders = (response, headers) => {
+	for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+	return response;
+};
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
 * The rows and columns of an insert's body: an object or an array of objects. The columns are `columns` when given,
@@ -69,24 +105,27 @@ const insertRowsOf = (body, query) => {
 		columns
 	};
 };
-const read = async (deps, c) => {
+const read = async (deps, foreignKeys, c) => {
 	const entry = tableEntry(deps, c.req.param("table"));
 	const query = parseQuery(queryParams(c), c.req.header("range") ?? null);
 	const prefer = parsePrefer(c.req.header("prefer") ?? null);
-	const warning = await scanCheck(deps, entry, query.filters, query.order);
+	const shape = await shapeOf(deps, foreignKeys, entry, query);
+	const warning = await scanCheck(deps, entry, query.filters, query.order, shape);
 	const alias = entry.model.table.name;
 	const source = {
 		from: sql`${tableId(entry.model)} as ${sql.id(alias)}`,
 		alias
 	};
-	const page = await asCaller(deps, c, true, (trx) => readRows(trx, source, query, prefer.count));
+	const page = await asCaller(deps, c, true, (trx) => readRows(trx, source, shape, query, prefer.count));
 	return pageResponse(page, query.range.offset, wantsObject(c.req.raw), warning);
 };
-const insert = async (deps, c) => {
+const insert = async (deps, foreignKeys, c) => {
 	const entry = tableEntry(deps, c.req.param("table"));
 	const query = parseQuery(queryParams(c));
 	const prefer = parsePrefer(c.req.header("prefer") ?? null);
 	const object = wantsObject(c.req.raw);
+	const shape = await shapeOf(deps, foreignKeys, entry, query);
+	const warning = await scanCheck(deps, entry, [], [], shape);
 	const { rows, columns } = insertRowsOf(await readBody(c), query);
 	if (columns.length === 0 && rows.length > 1) throw restError(400, "PGRST102", "Several rows without any column cannot be inserted at once");
 	if (rows.length === 0 && object) checkSingle(0);
@@ -101,55 +140,56 @@ const insert = async (deps, c) => {
 			defaults: prefer.missing === "default",
 			resolution: prefer.resolution,
 			conflict
-		}, returningOf(prefer, query));
+		}, returningOf(prefer, shape));
 		if (object) checkSingle(result.total);
 		return result;
 	});
 	const status = written.inserted === 0 ? 200 : 201;
-	return writeResponse(written, object, status, status, `*/${counted(prefer, written.total) ?? "*"}`);
+	return withHeaders(writeResponse(written, object, status, status, `*/${counted(prefer, written.total) ?? "*"}`), warning);
 };
-const update = async (deps, c) => {
+const update = async (deps, foreignKeys, c) => {
 	const entry = tableEntry(deps, c.req.param("table"));
 	const query = parseQuery(queryParams(c));
 	const prefer = parsePrefer(c.req.header("prefer") ?? null);
 	const object = wantsObject(c.req.raw);
 	const body = await readBody(c);
 	if (!isRecord(body)) throw restError(400, "PGRST102", "Empty or invalid json");
-	const warning = await scanCheck(deps, entry, query.filters, []);
+	const shape = await shapeOf(deps, foreignKeys, entry, query);
+	const warning = await scanCheck(deps, entry, query.filters, [], shape);
 	const written = Object.keys(body).length === 0 ? {
 		total: 0,
 		...prefer.return === "representation" && { body: "[]" }
 	} : await asCaller(deps, c, false, async (trx) => {
-		const result = await updateRows(trx, targetOf(entry), body, query.filters, returningOf(prefer, query));
+		const result = await updateRows(trx, targetOf(entry), body, query.filters, returningOf(prefer, shape));
 		if (object) checkSingle(result.total);
 		return result;
 	});
-	const response = writeResponse(written, object, 200, 204, contentRange(0, written.total, counted(prefer, written.total)));
-	for (const [name, value] of Object.entries(warning)) response.headers.set(name, value);
-	return response;
+	return withHeaders(writeResponse(written, object, 200, 204, contentRange(0, written.total, counted(prefer, written.total))), warning);
 };
-const remove = async (deps, c) => {
+const remove = async (deps, foreignKeys, c) => {
 	const entry = tableEntry(deps, c.req.param("table"));
 	const query = parseQuery(queryParams(c));
 	const prefer = parsePrefer(c.req.header("prefer") ?? null);
 	const object = wantsObject(c.req.raw);
-	const warning = await scanCheck(deps, entry, query.filters, []);
+	const shape = await shapeOf(deps, foreignKeys, entry, query);
+	const warning = await scanCheck(deps, entry, query.filters, [], shape);
 	const written = await asCaller(deps, c, false, async (trx) => {
-		const result = await deleteRows(trx, targetOf(entry), query.filters, returningOf(prefer, query));
+		const result = await deleteRows(trx, targetOf(entry), query.filters, returningOf(prefer, shape));
 		if (object) checkSingle(result.total);
 		return result;
 	});
-	const response = writeResponse(written, object, 200, 204, `*/${counted(prefer, written.total) ?? "*"}`);
-	for (const [name, value] of Object.entries(warning)) response.headers.set(name, value);
-	return response;
+	return withHeaders(writeResponse(written, object, 200, 204, `*/${counted(prefer, written.total) ?? "*"}`), warning);
 };
-/** `/rest/v1/<table>`: read with GET and HEAD, insert and upsert with POST, update with PATCH, delete with DELETE. */
-const tableRoutes = (deps) => {
+/**
+* `/rest/v1/<table>`: read with GET and HEAD, insert and upsert with POST, update with PATCH, delete with DELETE. Reads
+* and the rows a write returns embed related rows through `foreignKeys`.
+*/
+const tableRoutes = (deps, foreignKeys) => {
 	const app = new Hono();
-	app.get("/:table", (c) => read(deps, c));
-	app.post("/:table", (c) => insert(deps, c));
-	app.patch("/:table", (c) => update(deps, c));
-	app.delete("/:table", (c) => remove(deps, c));
+	app.get("/:table", (c) => read(deps, foreignKeys, c));
+	app.post("/:table", (c) => insert(deps, foreignKeys, c));
+	app.patch("/:table", (c) => update(deps, foreignKeys, c));
+	app.delete("/:table", (c) => remove(deps, foreignKeys, c));
 	return app;
 };
 //#endregion

package/dist/rest/whole-number.js

@@ -0,0 +1,9 @@
+import { parseError } from "./rest-error.js";
+//#region src/rest/whole-number.ts
+/** The whole number a `limit` or `offset` parameter named `name` gives. */
+const wholeNumber = (name, text) => {
+	if (!/^\d+$/.test(text)) throw parseError(`"failed to parse ${name} (${text})"`, `${name} takes a whole number`);
+	return Number(text);
+};
+//#endregion
+export { wholeNumber };

package/dist/rest/write-rows.js

@@ -1,5 +1,6 @@
 import { whereSql } from "./filter-sql.js";
 import { selectSql } from "./shape-sql.js";
+import { joinsSql } from "./embed-sql.js";
 import { sql } from "kysely";
 //#region src/rest/write-rows.ts
 const returningSql = (target, returning, upsert) => {
@@ -8,7 +9,7 @@ const returningSql = (target, returning, upsert) => {
 };
 const run = async (trx, target, payload, write, returning, upsert) => {
 	const inserted = upsert ? sql`(select count(*) from pgrst_source where pgrst_inserted)` : sql`null::bigint`;
-	const body = returning ? sql`(select coalesce(json_agg(pgrst_rows), '[]')::text from (select ${selectSql(target.alias, returning.select)} from (select (pgrst_source.pgrst_row).* from pgrst_source) as ${sql.id(target.alias)}) as pgrst_rows)` : sql`null::text`;
+	const body = returning ? sql`(select coalesce(json_agg(pgrst_rows), '[]')::text from (select ${selectSql(target.alias, returning.shape)} from (select (pgrst_source.pgrst_row).* from pgrst_source) as ${sql.id(target.alias)}${joinsSql(target.alias, returning.shape)}) as pgrst_rows)` : sql`null::text`;
 	const { rows: [result] } = await sql`
     with pgrst_payload as (select ${JSON.stringify(payload ?? null)}::json as body), pgrst_source as (${write}${returningSql(target, returning, upsert)})
     select (select count(*) from pgrst_source) as total, ${inserted} as inserted, ${body} as body

package/dist/view-access.js

@@ -3,6 +3,7 @@ import { cardPhotosErrors } from "./view-card-photos.js";
 import { cardFavoriteErrors } from "./view-card-favorite.js";
 import { searchesOfFor } from "./view-saved-search.js";
 import { relatedColumnErrors } from "./view-related-column.js";
+import { actionWhenFields } from "./view-action-when.js";
 import { conditionReadable, resolveFieldPath } from "@protobase/layout";
 import { addressErrors, chartFields, hrefPlaceholders, navRecentErrors, promptFields, pruneByShape, shapes, tableDisplay } from "@protobase/schema/internal";
 import { isRecordCondition } from "@protobase/schema";
@@ -258,12 +259,17 @@ const aiShape = (model) => shapes.map((run) => {
 	} : void 0;
 });
 const inputsShape = (models) => shapes.map((inputs) => inputs.every((input) => input.resource === void 0 || Object.hasOwn(models, input.resource)) ? inputs : void 0);
+const actionWhenShape = (model) => shapes.map((when) => actionWhenFields(when).every((name) => Object.hasOwn(model.fields, name)) ? when : void 0);
 const actionShape = (model, models, createPages) => shapes.object({
 	name: shapes.data,
 	label: shapes.data,
 	icon: shapes.data,
 	confirm: shapes.data,
 	bulk: shapes.data,
+	when: actionWhenShape(model),
+	otherwise: shapes.data,
+	reason: shapes.data,
+	variant: shapes.data,
 	run: shapes.oneOf({
 		update: shapes.object({
 			kind: shapes.data,
@@ -274,7 +280,11 @@ const actionShape = (model, models, createPages) => shapes.object({
 		ai: aiShape(model)
 	}),
 	inputs: inputsShape(models)
-}, { requires: ["run", "inputs"] });
+}, { requires: [
+	"run",
+	"inputs",
+	"when"
+] });
 const viewShape = (resource, model, models, prompted, createPages) => {
 	const nav = shapes.object({
 		hidden: shapes.data,

package/dist/view-action-when.js

@@ -0,0 +1,23 @@
+import { parseCondition } from "@protobase/layout";
+import { actionConditionError } from "@protobase/schema/internal";
+//#region src/view-action-when.ts
+/** The fields an action's `when` reads, or none when it has none or does not parse, which startup refuses. */
+const actionWhenFields = (when) => {
+	if (when === void 0) return [];
+	const parsed = parseCondition(when);
+	return parsed.ok ? parsed.paths : [];
+};
+/**
+* An action's `when` parses and reads only fields the record has: a list decides it for every row from the row alone,
+* so it follows no relation and counts no records. A view written as data is checked as the builder checks its options.
+*/
+const actionWhenErrors = (view, model) => view.actions.flatMap((action) => {
+	const option = actionConditionError(action);
+	if (option) return [`action "${action.name}": ${option}`];
+	if (action.when === void 0) return [];
+	const parsed = parseCondition(action.when);
+	if (!parsed.ok) return [`action "${action.name}": "when" is not a valid condition: ${parsed.message}`];
+	return parsed.paths.filter((path) => !Object.hasOwn(model.fields, path)).map((path) => `action "${action.name}": "when" names "${path}", but an action's condition reads only fields ${model.name} has`);
+});
+//#endregion
+export { actionWhenErrors, actionWhenFields };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.26.7",
+  "version": "0.26.8",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,9 +32,9 @@
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
     "@better-auth/sso": "^1.7.7",
-    "@protobase/layout": "0.26.7",
-    "@protobase/query": "0.26.7",
-    "@protobase/schema": "0.26.7",
+    "@protobase/layout": "0.26.8",
+    "@protobase/query": "0.26.8",
+    "@protobase/schema": "0.26.8",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",