emdash 0.32.0 → 0.33.0

package/src/database/repositories/taxonomy.ts

@@ -3,6 +3,7 @@ import { ulid } from "ulidx";
 
 import { invalidateTaxonomyObjectCache } from "../../object-cache/index.js";
 import { isMissingTableError } from "../../utils/db-errors.js";
+import { withTransaction } from "../transaction.js";
 import type { Database, TaxonomyTable } from "../types.js";
 import { validateIdentifier } from "../validate.js";
 
@@ -29,6 +30,58 @@ const EMPTY_DENORM: PivotDenorm = {
 	created_at: null,
 };
 
+/** A member of one sibling group and the position it currently holds. */
+export interface SiblingPosition {
+	group: string;
+	position: number;
+}
+
+/**
+ * Translation groups per reorder `UPDATE`. Each costs three bound parameters —
+ * a CASE `WHEN`/`THEN` pair plus one slot in the `IN` list — which keeps a
+ * statement inside D1's 100-parameter ceiling.
+ */
+const GROUPS_PER_UPDATE = 32;
+
+/** Deal the listed groups back out over the slots they hold, in the order given. */
+function permuteWithinSlots(
+	listed: readonly string[],
+	occupied: readonly number[],
+): Map<string, number> {
+	const slots = occupied.toSorted((a, b) => a - b);
+	const target = new Map<string, number>();
+	listed.forEach((group, index) => {
+		const position = slots[index];
+		if (position !== undefined) target.set(group, position);
+	});
+	return target;
+}
+
+/**
+ * Renumber a whole sibling group 0..n-1, with the listed groups in the order
+ * given and every other member left in the place it already held.
+ *
+ * Works off each member's index in the sequence rather than its stored value,
+ * which is what lets it resolve positions that tie. The sort is stable, so
+ * tied members keep the order `siblings` arrives in — deterministic, but a
+ * listing that mixes locales breaks a tie on whichever locale's label sorts
+ * first, not on the order any one caller rendered.
+ */
+function renumberSiblings(
+	listed: readonly string[],
+	siblings: readonly SiblingPosition[],
+): Map<string, number> {
+	const sequence = siblings.toSorted((a, b) => a.position - b.position);
+	const wanted = new Set(listed);
+	const target = new Map<string, number>();
+	let next = 0;
+	sequence.forEach(({ group }, index) => {
+		const replacement = wanted.has(group) ? listed[next++] : undefined;
+		target.set(replacement ?? group, index);
+	});
+	return target;
+}
+
 export interface Taxonomy {
 	id: string;
 	name: string;
@@ -38,6 +91,11 @@ export interface Taxonomy {
 	data: Record<string, unknown> | null;
 	locale: string;
 	translationGroup: string | null;
+	/**
+	 * Position among siblings. Shared by every row of a `translation_group` —
+	 * a term sits in the same place in every locale it is translated into.
+	 */
+	sortOrder: number;
 }
 
 export interface CreateTaxonomyInput {
@@ -75,6 +133,12 @@ export interface FindOptions {
  * The repository does not resolve locale fallbacks on its own — callers supply
  * the locale they want. Runtime helpers and handlers use `getFallbackChain()`
  * from `i18n/config` when they need fallback behaviour.
+ *
+ * `sort_order` is per translation_group, not per row: every row sharing a
+ * translation_group carries the same value, so a term holds one position across
+ * all its locales. Sibling groups are keyed on the raw `parent_id` column, which
+ * is locale-agnostic for the same reason (it stores the parent's
+ * translation_group). Writes must preserve both invariants.
  */
 export class TaxonomyRepository {
 	constructor(private db: Kysely<Database>) {}
@@ -98,10 +162,17 @@ export class TaxonomyRepository {
 		const parentId = parentInput ? await this.resolveParentRef(parentInput) : null;
 
 		let translationGroup = id;
+		let sortOrder: number | null = null;
 		if (input.translationOf) {
 			const source = await this.findById(input.translationOf);
 			if (source?.translationGroup) translationGroup = source.translationGroup;
+			// A translation is the same term in another locale, so it takes the
+			// group's position — but only while it stays in the group that position
+			// belongs to. Landing under a different parent makes it a new member of
+			// that sibling group, and the source's position means nothing there.
+			if (source && source.parentId === parentId) sortOrder = source.sortOrder;
 		}
+		sortOrder ??= await this.nextSortOrder(input.name, parentId);
 
 		await this.db
 			.insertInto("taxonomies")
@@ -112,6 +183,7 @@ export class TaxonomyRepository {
 				label: input.label,
 				parent_id: parentId,
 				data: input.data ? JSON.stringify(input.data) : null,
+				sort_order: sortOrder,
 				// When omitted, the DB DEFAULT 'en' is used — keeps behaviour
 				// consistent with ContentRepository and lets higher layers
 				// supply an explicit locale from request context.
@@ -155,15 +227,18 @@ export class TaxonomyRepository {
 	/**
 	 * Get all terms for a taxonomy (e.g., all categories).
 	 *
-	 * `id asc` is a stable tiebreaker for terms that share a label. Without it
-	 * the SQL ordering is implementation-defined when labels match, which
-	 * breaks keyset pagination over `(label, id)`.
+	 * `sort_order` carries the manual order set from the admin; it is 0 for
+	 * terms nobody has reordered, so an untouched taxonomy still comes back
+	 * alphabetically. `id asc` is a stable tiebreaker for terms that share both
+	 * — without it the SQL ordering is implementation-defined when they match,
+	 * which breaks keyset pagination over `(label, id)`.
 	 */
 	async findByName(name: string, options: FindOptions = {}): Promise<Taxonomy[]> {
 		let query = this.db
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("name", "=", name)
+			.orderBy("sort_order", "asc")
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
 
@@ -196,6 +271,7 @@ export class TaxonomyRepository {
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("parent_id", "=", group)
+			.orderBy("sort_order", "asc")
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
 		if (locale !== undefined) query = query.where("locale", "=", locale);
@@ -222,28 +298,146 @@ export class TaxonomyRepository {
 		const existing = await this.findById(id);
 		if (!existing) return null;
 
+		// Per-row display fields. `parent_id` and `sort_order` are not here: both
+		// belong to the translation_group and are written across it below.
 		const updates: Record<string, unknown> = {};
 		if (input.slug !== undefined) updates.slug = input.slug;
 		if (input.label !== undefined) updates.label = input.label;
+		if (input.data !== undefined) updates.data = JSON.stringify(input.data);
+
+		const group: { parent_id?: string | null; sort_order?: number } = {};
 		if (input.parentId !== undefined) {
 			// Defense in depth: empty-string parentId means null (no parent).
 			// Otherwise persist the parent's translation_group (locale-agnostic),
 			// matching create() — see the note there.
-			updates.parent_id =
+			const parentId =
 				input.parentId === "" || input.parentId === null
 					? null
 					: await this.resolveParentRef(input.parentId);
+
+			if (parentId !== existing.parentId) {
+				group.parent_id = parentId;
+				// A position only means anything within one sibling group, so a term
+				// that changes parent is appended to the group it lands in.
+				group.sort_order = await this.nextSortOrder(existing.name, parentId);
+			}
 		}
-		if (input.data !== undefined) updates.data = JSON.stringify(input.data);
 
-		if (Object.keys(updates).length > 0) {
-			await this.db.updateTable("taxonomies").set(updates).where("id", "=", id).execute();
+		const hasRowUpdates = Object.keys(updates).length > 0;
+		const hasGroupUpdates = Object.keys(group).length > 0;
+		if (hasRowUpdates || hasGroupUpdates) {
+			await withTransaction(this.db, async (trx) => {
+				if (hasRowUpdates) {
+					await trx.updateTable("taxonomies").set(updates).where("id", "=", id).execute();
+				}
+				if (hasGroupUpdates) {
+					await trx
+						.updateTable("taxonomies")
+						.set(group)
+						.where("translation_group", "=", existing.translationGroup ?? existing.id)
+						.execute();
+				}
+			});
 			invalidateTaxonomyObjectCache();
 		}
 
 		return this.findById(id);
 	}
 
+	/**
+	 * Move `groups` (translation_groups, in the desired order) into the positions
+	 * those same groups already occupy, leaving every other member of the sibling
+	 * group where it is.
+	 *
+	 * `groups` may be a subset: a locale renders only the terms translated into
+	 * it, so an admin in `fr` often cannot name every member. A group left out
+	 * keeps its place, which is also what makes a stale list harmless.
+	 *
+	 * `siblings` is every member of the group with the position it holds, in a
+	 * listing's order — tied positions are resolved by that order, so pass it as
+	 * read. Groups already at their target are skipped, so one swap rewrites two
+	 * groups rather than the whole list.
+	 */
+	async reorder(groups: string[], siblings: readonly SiblingPosition[]): Promise<void> {
+		const current = new Map(siblings.map(({ group, position }) => [group, position]));
+
+		const listed: string[] = [];
+		const occupied: number[] = [];
+		for (const group of groups) {
+			const position = current.get(group);
+			if (position === undefined) continue;
+			listed.push(group);
+			occupied.push(position);
+		}
+		if (listed.length === 0) return;
+
+		// Tied positions have no distinct order to permute into, so the requested
+		// one would be dropped without a word. Renumbering is the only way to
+		// honour it, and it repairs the tie on the way through.
+		const target =
+			new Set(occupied).size === occupied.length
+				? permuteWithinSlots(listed, occupied)
+				: renumberSiblings(listed, siblings);
+
+		const changed = [...target].filter(([group, position]) => current.get(group) !== position);
+		if (changed.length === 0) return;
+
+		await this.applyPositions(changed);
+
+		invalidateTaxonomyObjectCache();
+	}
+
+	/**
+	 * Write one position per translation_group, GROUPS_PER_UPDATE at a time so
+	 * each statement stays inside D1's parameter ceiling.
+	 *
+	 * D1 has no transactions — `withTransaction` runs its callback bare there —
+	 * so a chunk is the unit that can't tear. A reorder spanning several chunks
+	 * can, and leaves ties, which the next reorder renumbers away.
+	 */
+	private async applyPositions(positions: readonly (readonly [string, number])[]): Promise<void> {
+		for (let index = 0; index < positions.length; index += GROUPS_PER_UPDATE) {
+			const chunk = positions.slice(index, index + GROUPS_PER_UPDATE);
+			// The CAST types the bound position. Postgres resolves a CASE whose THEN
+			// arms are all untyped parameters to text, then refuses to assign text to
+			// an integer column.
+			const arms = sql.join(
+				chunk.map(([group, position]) => sql`WHEN ${group} THEN CAST(${position} AS INTEGER)`),
+				sql` `,
+			);
+			const keys = sql.join(chunk.map(([group]) => sql`${group}`));
+			await sql`
+				UPDATE taxonomies
+				SET sort_order = CASE translation_group ${arms} END
+				WHERE translation_group IN (${keys})
+			`.execute(this.db);
+		}
+	}
+
+	/**
+	 * Position for a term joining a sibling group: one past the last member, or
+	 * 0 when the group is empty.
+	 *
+	 * Bounds are taken across every locale because a position belongs to the
+	 * translation_group, not to a row — a term translated into only one locale
+	 * still occupies its slot for all of them.
+	 */
+	private async nextSortOrder(name: string, parentId: string | null): Promise<number> {
+		let query = this.db
+			.selectFrom("taxonomies")
+			.select((eb) => eb.fn.max("sort_order").as("max"))
+			.where("name", "=", name);
+		query =
+			parentId === null
+				? query.where("parent_id", "is", null)
+				: query.where("parent_id", "=", parentId);
+
+		const bounds = await query.executeTakeFirst();
+		// Null only when the group is empty.
+		if (!bounds || bounds.max === null) return 0;
+		return bounds.max + 1;
+	}
+
 	async delete(id: string): Promise<boolean> {
 		const term = await this.findById(id);
 		if (!term) return false;
@@ -543,6 +737,7 @@ export class TaxonomyRepository {
 			data: row.data ? JSON.parse(row.data) : null,
 			locale: row.locale,
 			translationGroup: row.translation_group,
+			sortOrder: row.sort_order,
 		};
 	}
 }

package/src/database/repositories/types.ts

@@ -290,3 +290,10 @@ export class ScheduledNotDueError extends Error {
 		this.name = "ScheduledNotDueError";
 	}
 }
+
+export class ContentMutationConflictError extends Error {
+	constructor(message = "Content changed while the operation was in progress") {
+		super(message);
+		this.name = "ContentMutationConflictError";
+	}
+}

package/src/database/types.ts

@@ -13,6 +13,12 @@ export interface RevisionTable {
 	created_at: Generated<string>;
 }
 
+export interface RevisionPruneQueueTable {
+	collection: string;
+	entry_id: string;
+	revision_id: string;
+}
+
 export interface TaxonomyTable {
 	id: string;
 	name: string;
@@ -22,6 +28,9 @@ export interface TaxonomyTable {
 	data: string | null; // JSON
 	locale: Generated<string>; // e.g. 'en', 'es', 'fr'
 	translation_group: string | null; // shared across translations of the same term
+	// Manual order within a sibling group. 0 for terms that were never
+	// explicitly reordered, so listings fall back to alphabetical.
+	sort_order: Generated<number>;
 }
 
 export interface ContentTaxonomyTable {
@@ -302,9 +311,11 @@ export interface CollectionTable {
 	icon: string | null;
 	supports: string | null; // JSON array
 	source: string | null;
-	search_config: string | null; // JSON: { enabled: boolean, weights: Record<string, number> }
+	search_config: string | null; // JSON: SearchConfig
 	has_seo: number; // 0 or 1 — opt-in SEO fields for this collection
 	url_pattern: string | null; // URL pattern with {slug} placeholder (e.g. "/blog/{slug}")
+	hidden: Generated<number>; // 0 or 1 — omit the auto-generated admin sidebar entry
+	sort_order: number | null; // explicit admin sidebar position; NULL = alphabetical fallback
 	comments_enabled: Generated<number>; // 0 or 1
 	comments_moderation: Generated<string>; // 'all' | 'first_time' | 'none'
 	comments_closed_after_days: Generated<number>; // 0 = never close
@@ -500,6 +511,7 @@ export interface SectionTable {
 // Note: ec_* content tables are dynamic and not part of this type
 export interface Database {
 	revisions: RevisionTable;
+	_emdash_revision_prune_queue: RevisionPruneQueueTable;
 	taxonomies: TaxonomyTable;
 	content_taxonomies: ContentTaxonomyTable;
 	_emdash_taxonomy_defs: TaxonomyDefTable;

package/src/database/validate.ts

@@ -26,6 +26,13 @@ const GENERIC_IDENTIFIER_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
  */
 const PLUGIN_IDENTIFIER_PATTERN = /^[a-z][a-z0-9_-]*$/;
 
+/**
+ * Pattern for plugin storage collection names.
+ * Manifests declare these as free-form keys, so both cases and hyphens are
+ * allowed; the charset still excludes quotes, whitespace, and punctuation.
+ */
+const STORAGE_COLLECTION_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
 /**
  * Maximum length for SQL identifiers.
  * SQLite has no formal limit, but we cap at 128 for sanity.
@@ -136,3 +143,35 @@ export function validatePluginIdentifier(value: string, label = "plugin identifi
 		throw new IdentifierError(`${label} must match /^[a-z][a-z0-9_-]*$/ (got "${value}")`, value);
 	}
 }
+
+/**
+ * Validate a plugin storage collection name.
+ *
+ * Collections are declared as free-form manifest keys and stored as opaque
+ * text, so this is deliberately more permissive than `validateIdentifier`:
+ * `form-submissions` and `formSubmissions` are legitimate. The charset still
+ * rejects quotes and punctuation, keeping generated index names inert.
+ *
+ * @param value - The string to validate
+ * @param label - Human-readable label for error messages
+ * @throws {IdentifierError} If the value is not valid
+ */
+export function validateStorageCollectionName(value: string, label = "collection name"): void {
+	if (!value || typeof value !== "string") {
+		throw new IdentifierError(`${label} must be a non-empty string`, String(value));
+	}
+
+	if (value.length > MAX_IDENTIFIER_LENGTH) {
+		throw new IdentifierError(
+			`${label} must be ${MAX_IDENTIFIER_LENGTH} characters or less, got ${value.length}`,
+			value,
+		);
+	}
+
+	if (!STORAGE_COLLECTION_PATTERN.test(value)) {
+		throw new IdentifierError(
+			`${label} must match /^[a-zA-Z][a-zA-Z0-9_-]*$/ (got "${value}")`,
+			value,
+		);
+	}
+}

package/src/db/adapters.ts

@@ -48,6 +48,14 @@ export interface DatabaseDescriptor {
 	 * the middleware takes its default (singleton) path.
 	 */
 	supportsRequestScope?: boolean;
+	/**
+	 * When true, request middleware resolves the last content-namespace
+	 * invalidation timestamp and passes it to `createRequestScopedDb`.
+	 *
+	 * Keep this unset unless request routing depends on that timestamp: reading
+	 * it may require an object-cache backend round trip.
+	 */
+	needsLastContentWriteAt?: boolean;
 	/**
 	 * When true, the adapter's runtime entrypoint MUST export a named
 	 * `createCoalescingDialect` function. The runtime uses this fresh dialect

package/src/deferred-tasks.ts

@@ -0,0 +1,71 @@
+export interface DeferredTaskTracker {
+	settled: Promise<void>;
+	track<T>(promise: Promise<T>): Promise<T>;
+	settle(): void;
+}
+
+// Test database teardown uses this process-local registry to drain tasks that
+// run without request middleware. Keep it on globalThis so duplicated SSR
+// chunks and their test helpers observe the same task set.
+const DEFERRED_TASKS_KEY = Symbol.for("emdash:deferred-tasks");
+
+const deferredTasks: Set<Promise<unknown>> =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern
+	((globalThis as Record<symbol, unknown>)[DEFERRED_TASKS_KEY] as
+		| Set<Promise<unknown>>
+		| undefined) ??
+	(() => {
+		const tasks = new Set<Promise<unknown>>();
+		(globalThis as Record<symbol, unknown>)[DEFERRED_TASKS_KEY] = tasks;
+		return tasks;
+	})();
+
+export function trackDeferredTask<T>(promise: Promise<T>): Promise<T> {
+	let tracked!: Promise<T>;
+	tracked = promise.finally(() => deferredTasks.delete(tracked));
+	deferredTasks.add(tracked);
+	return tracked;
+}
+
+export async function waitForDeferredTasks(): Promise<void> {
+	while (deferredTasks.size > 0) {
+		await Promise.allSettled(deferredTasks);
+	}
+}
+
+export function createDeferredTaskTracker(onSettled: () => void): DeferredTaskTracker {
+	let pending = 0;
+	let responseSettled = false;
+	let completed = false;
+	let resolveSettled!: () => void;
+	const settled = new Promise<void>((resolve) => {
+		resolveSettled = resolve;
+	});
+
+	const completeIfSettled = () => {
+		if (completed || !responseSettled || pending > 0) return;
+		completed = true;
+		try {
+			onSettled();
+		} finally {
+			resolveSettled();
+		}
+	};
+
+	return {
+		settled,
+		track<T>(promise: Promise<T>): Promise<T> {
+			pending++;
+			return promise.finally(() => {
+				// A task may register another after() call before it settles. The
+				// counter therefore reaches zero only after the full task chain ends.
+				pending--;
+				completeIfSettled();
+			});
+		},
+		settle(): void {
+			responseSettled = true;
+			completeIfSettled();
+		},
+	};
+}