emdash 0.40.0 → 0.41.0

package/src/references/field-map.ts

@@ -0,0 +1,115 @@
+/**
+ * The reference fields a collection carries, for the public query path.
+ *
+ * `referenceFieldConstraints` (api/handlers) answers the write question — how
+ * many entries may a field select, and is it required. Rendering asks a
+ * different one: which collection do I load, and which end of the relation am I
+ * standing on. Both read the same rows; keeping them apart keeps the render
+ * path off the relation table, which the constraints map has to read for its
+ * limits.
+ */
+
+import { sql, type Kysely } from "kysely";
+
+import { jsonExtractExpr } from "../database/dialect-helpers.js";
+import type { Database } from "../database/types.js";
+import { getDb } from "../loader.js";
+import { cachedQuery, CacheNamespace } from "../object-cache/index.js";
+import { requestCached } from "../request-cache.js";
+import { isMissingTableError } from "../utils/db-errors.js";
+
+/** One reference field, as a render needs it. */
+export interface ReferenceFieldBinding {
+	/** Field slug — the key a caller names a selection under. */
+	slug: string;
+	/** Relation slug the field binds to. */
+	relation: string;
+	/**
+	 * The relation's id, read in the same statement as the binding. Rendering
+	 * pages the link table by id, so carrying it here is what keeps a field's
+	 * cost at one link read rather than a slug lookup and then the read.
+	 */
+	relationId: string;
+	/** Which end of the relation this field's own collection sits on. */
+	side: "parent" | "child";
+	/** The collection at the other end. */
+	targetCollection: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function loadBindings(
+	db: Kysely<Database>,
+	collection: string,
+): Promise<ReferenceFieldBinding[]> {
+	// The relation's id joins in here rather than being looked up per field at
+	// render time: the field stores a slug, but the link table is keyed by id.
+	const relationSlug = jsonExtractExpr(db, "validation", "relation");
+	let rows: { slug: string; validation: string | null; relation_id: string | null }[];
+	try {
+		const result = await sql<{
+			slug: string;
+			validation: string | null;
+			relation_id: string | null;
+		}>`
+			SELECT f.slug AS slug, f.validation AS validation, r.id AS relation_id
+			FROM ${sql.ref("_emdash_fields")} AS f
+			INNER JOIN ${sql.ref("_emdash_collections")} AS c ON c.id = f.collection_id
+			LEFT JOIN ${sql.ref("_emdash_relations")} AS r ON r.slug = ${sql.raw(relationSlug)}
+			WHERE c.slug = ${collection} AND f.type = 'reference'
+		`.execute(db);
+		rows = result.rows;
+	} catch (error) {
+		if (isMissingTableError(error)) return [];
+		throw error;
+	}
+
+	const bindings: ReferenceFieldBinding[] = [];
+	for (const row of rows) {
+		if (!row.validation) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(row.validation);
+		} catch {
+			continue;
+		}
+		if (!isRecord(parsed)) continue;
+		const { relation, targetCollection } = parsed;
+		// A field with neither is unbound: it keeps its own column, and its value
+		// is already in `data`. There is nothing to resolve. Nor is there when the
+		// named relation is gone — the join leaves no id to page by.
+		if (typeof relation !== "string" || typeof targetCollection !== "string") continue;
+		if (!row.relation_id) continue;
+		bindings.push({
+			slug: row.slug,
+			relation,
+			relationId: row.relation_id,
+			targetCollection,
+			side: parsed.relationSide === "child" ? "child" : "parent",
+		});
+	}
+	return bindings;
+}
+
+/**
+ * Every bound reference field on `collection`, by field slug.
+ *
+ * Cached twice over: once per request, and once in the schema object-cache
+ * namespace, which a schema edit already bumps. A render that asks for
+ * references therefore pays for this lookup at most once per isolate between
+ * schema changes, and a render that asks for none never issues it.
+ */
+export function getReferenceFieldMap(
+	collection: string,
+): Promise<Map<string, ReferenceFieldBinding>> {
+	return requestCached(`reference-field-map:${collection}`, async () => {
+		const bindings = await cachedQuery({
+			namespace: CacheNamespace.SCHEMA,
+			key: `reference-field-map:${collection}`,
+			load: async () => loadBindings(await getDb(), collection),
+		});
+		return new Map(bindings.map((binding) => [binding.slug, binding]));
+	});
+}

package/src/references/resolve.ts

@@ -0,0 +1,160 @@
+/**
+ * Resolve an entry's reference selections to loadable entries, for the public
+ * query path.
+ *
+ * The cost is bounded and predictable: one link read per selected field, then
+ * one entry read per *distinct* target collection — never one per link. A
+ * caller that selects no fields issues nothing at all, which is what keeps
+ * references off the logged-out hot path of every render that does not ask for
+ * them.
+ */
+
+import { RelationRepository } from "../database/repositories/relation.js";
+import { RevisionRepository } from "../database/repositories/revision.js";
+import { getFallbackChain, isI18nEnabled } from "../i18n/config.js";
+import { getDb, loadEntriesByGroups, type LoadedEntry } from "../loader.js";
+import { getReferenceFieldMap } from "./field-map.js";
+import {
+	pageStagedGroups,
+	readStagedReferences,
+	REFERENCE_PAGE_LIMIT,
+	REFERENCE_PAGE_MAX_LIMIT,
+	type PageOfGroups,
+} from "./staged.js";
+import type { ReferenceQuery, ReferenceSelection } from "./types.js";
+
+/** One reference field's resolved page, before the query layer wraps the entries. */
+export interface ResolvedReferencePage {
+	/** The collection the entries belong to — what the `edit` proxy is scoped to. */
+	collection: string;
+	entries: LoadedEntry[];
+	nextCursor?: string;
+}
+
+export interface ResolveReferencesOptions {
+	/** The collection the selecting entry belongs to. */
+	collection: string;
+	/** The selecting entry's own translation group. */
+	entryGroup: string;
+	/** The locale the parent resolved to, used to pick each target's variant. */
+	locale: string | null;
+	/** The selecting entry's draft revision, when it has one. */
+	draftRevisionId?: string;
+	/**
+	 * Whether this render may see unpublished content. It decides both halves of
+	 * draft visibility: whether a pending selection staged in the draft revision
+	 * replaces the published one, and whether an unpublished target resolves at
+	 * all.
+	 */
+	serveDrafts: boolean;
+	/** The fields to resolve, by field slug. */
+	selection: ReferenceSelection;
+}
+
+function pageOptions(query: ReferenceQuery): { limit: number; cursor?: string } {
+	if (query === true) return { limit: REFERENCE_PAGE_LIMIT };
+	const requested = query.limit ?? REFERENCE_PAGE_LIMIT;
+	return {
+		limit: Math.min(Math.max(requested, 1), REFERENCE_PAGE_MAX_LIMIT),
+		cursor: query.cursor,
+	};
+}
+
+function localeChainFor(locale: string | null): string[] {
+	if (locale === null) return [];
+	return isI18nEnabled() ? getFallbackChain(locale) : [locale];
+}
+
+export async function resolveReferencePages(
+	options: ResolveReferencesOptions,
+): Promise<Record<string, ResolvedReferencePage>> {
+	const fieldMap = await getReferenceFieldMap(options.collection);
+	const requested = Object.entries(options.selection).filter(
+		(entry): entry is [string, ReferenceQuery] => entry[1] !== undefined && fieldMap.has(entry[0]),
+	);
+	if (requested.length === 0) return {};
+
+	const db = await getDb();
+	const relations = new RelationRepository(db);
+
+	const staged =
+		options.serveDrafts && options.draftRevisionId
+			? readStagedReferences(
+					(await new RevisionRepository(db).findById(options.draftRevisionId))?.data,
+				)
+			: undefined;
+
+	// Phase one: each field's page of translation groups, in selection order.
+	// Concurrent, like phase two — the fields are independent, and awaiting them
+	// in turn would make N fields N sequential round trips.
+	const pages = new Map(
+		await Promise.all(
+			requested.map(async ([slug, query]): Promise<[string, PageOfGroups]> => {
+				const binding = fieldMap.get(slug)!;
+				const page = pageOptions(query);
+
+				const stagedGroups = staged?.[slug];
+				if (stagedGroups) return [slug, pageStagedGroups(stagedGroups, page)];
+
+				const links =
+					binding.side === "child"
+						? await relations.getParentsPageById(binding.relationId, options.entryGroup, page)
+						: await relations.getChildrenPageById(binding.relationId, options.entryGroup, page);
+				return [
+					slug,
+					{
+						groups: links.items.map((link) =>
+							binding.side === "child" ? link.parentGroup : link.childGroup,
+						),
+						nextCursor: links.nextCursor,
+					},
+				];
+			}),
+		),
+	);
+
+	// Phase two: one entry read per distinct target collection, however many
+	// fields point at it.
+	const groupsByCollection = new Map<string, Set<string>>();
+	for (const [slug, page] of pages) {
+		const target = fieldMap.get(slug)!.targetCollection;
+		const groups = groupsByCollection.get(target) ?? new Set<string>();
+		for (const group of page.groups) groups.add(group);
+		groupsByCollection.set(target, groups);
+	}
+
+	const localeChain = localeChainFor(options.locale);
+	const variantsByCollection = new Map<string, Map<string, LoadedEntry>>();
+	await Promise.all(
+		Array.from(groupsByCollection, async ([collection, groups]) => {
+			const loaded = await loadEntriesByGroups(collection, [...groups], {
+				publishedOnly: !options.serveDrafts,
+				localeChain,
+			});
+			const byGroup = new Map<string, LoadedEntry>();
+			for (const entry of loaded) {
+				const group = entry.data.translationGroup;
+				if (typeof group === "string") byGroup.set(group, entry);
+			}
+			variantsByCollection.set(collection, byGroup);
+		}),
+	);
+
+	// Phase three: rebuild each field in link order. A group with no surviving
+	// variant — deleted, or unpublished for a render that may not see drafts —
+	// drops out, exactly as a dangling link does.
+	const resolved: Record<string, ResolvedReferencePage> = {};
+	for (const [slug, page] of pages) {
+		const collection = fieldMap.get(slug)!.targetCollection;
+		const byGroup = variantsByCollection.get(collection);
+		const entries: LoadedEntry[] = [];
+		for (const group of page.groups) {
+			const variant = byGroup?.get(group);
+			if (variant) entries.push(variant);
+		}
+		resolved[slug] = page.nextCursor
+			? { collection, entries, nextCursor: page.nextCursor }
+			: { collection, entries };
+	}
+	return resolved;
+}

package/src/references/staged.ts

@@ -0,0 +1,117 @@
+/**
+ * The shape a pending reference selection takes inside a draft revision, and how
+ * to read and page it.
+ *
+ * Nothing here touches the database, which is what lets both the write side
+ * (`api/handlers/staged-references.ts`, which promotes and validates a staged
+ * selection) and the read side (the entry read, the edge routes, the public
+ * query resolver) share it without importing each other.
+ */
+
+import {
+	decodeCursor,
+	encodeCursor,
+	STAGED_CURSOR_MARKER,
+} from "../database/repositories/types.js";
+
+/**
+ * Where a collection that keeps drafts stages a pending reference selection: in
+ * the draft revision's data, beside `_slug`. The leading underscore is what
+ * keeps it out of the column writer, the loaded entry's `data`, and the publish
+ * promotion loop, all of which already skip `_`-prefixed keys.
+ *
+ * The link table holds the live selection only.
+ */
+export const STAGED_REFERENCES_KEY = "_references";
+
+/**
+ * A staged selection, by field slug, holding `translation_group` values rather
+ * than entry ids: an edge names a thing, not one locale's row of it, so the
+ * group is what the link table stores and what survives an entry being
+ * translated or re-slugged between saving and publishing. The save resolves ids
+ * to groups so publication has nothing left that can fail to resolve.
+ *
+ * Order is significant on the parent side, where it becomes `sort_order`.
+ */
+export type StagedReferences = Record<string, string[]>;
+
+/** Default page size for one reference field, matching the list endpoints. */
+export const REFERENCE_PAGE_LIMIT = 50;
+/** Hard ceiling, matching the list endpoints. */
+export const REFERENCE_PAGE_MAX_LIMIT = 100;
+
+/** One field's page of translation groups, before the entries are loaded. */
+export interface PageOfGroups {
+	groups: string[];
+	nextCursor?: string;
+}
+
+/**
+ * Page a staged selection, which is a list in memory rather than a table.
+ *
+ * The cursor anchors on the last group of the previous page rather than on its
+ * index: the editor can reorder or drop entries between one page and the next,
+ * and an index would then silently skip or repeat. An anchor that is no longer
+ * in the selection means the entries it pointed past are gone, so the walk ends.
+ */
+export function pageStagedGroups(
+	groups: string[],
+	options: { limit?: number; cursor?: string } = {},
+): PageOfGroups {
+	const limit = Math.min(
+		Math.max(options.limit ?? REFERENCE_PAGE_LIMIT, 1),
+		REFERENCE_PAGE_MAX_LIMIT,
+	);
+
+	let start = 0;
+	if (options.cursor) {
+		const decoded = decodeCursor(options.cursor);
+		// A cursor from the link table anchors on an edge row id, which is not a
+		// group and would match nothing. That happens when a preview session opens
+		// mid-pagination over the published selection, so restart the field rather
+		// than handing back an empty page that reads as "no more".
+		if (decoded.orderValue === STAGED_CURSOR_MARKER) {
+			const index = groups.indexOf(decoded.id);
+			if (index === -1) return { groups: [] };
+			start = index + 1;
+		}
+	}
+
+	const page = groups.slice(start, start + limit);
+	const last = page.at(-1);
+	const nextCursor =
+		last && start + page.length < groups.length
+			? encodeCursor(STAGED_CURSOR_MARKER, last)
+			: undefined;
+	return { groups: page, nextCursor };
+}
+
+function isGroupList(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+/** The staged selection inside a revision's data, if it carries one. */
+export function readStagedReferences(
+	data: Record<string, unknown> | undefined,
+): StagedReferences | undefined {
+	const staged = data?.[STAGED_REFERENCES_KEY];
+	if (typeof staged !== "object" || staged === null || Array.isArray(staged)) return undefined;
+
+	const result: StagedReferences = {};
+	for (const [fieldSlug, groups] of Object.entries(staged)) {
+		if (isGroupList(groups)) result[fieldSlug] = groups;
+	}
+	return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/**
+ * Fold a save's selections into whatever the previous draft staged. A save that
+ * names one reference field must not drop another field's pending selection, so
+ * fields absent from `incoming` keep their staged value.
+ */
+export function mergeStagedReferences(
+	base: Record<string, unknown> | undefined,
+	incoming: StagedReferences,
+): StagedReferences {
+	return { ...readStagedReferences(base), ...incoming };
+}

package/src/references/types.ts

@@ -0,0 +1,16 @@
+/**
+ * How much of one reference field's selection a render wants.
+ *
+ * `true` is the first page at the default limit — the common case, where a
+ * field holds one entry or a handful. The object form is for a field that can
+ * hold many, and for walking past the first page with the cursor the previous
+ * page returned.
+ */
+export type ReferenceQuery = true | { limit?: number; cursor?: string };
+
+/**
+ * The selection a caller opts into, by field slug. A field mapped to
+ * `undefined` is not requested, so a render can name one conditionally without
+ * building the object in two branches.
+ */
+export type ReferenceSelection = Record<string, ReferenceQuery | undefined>;