emdash 0.36.0 → 0.38.0

package/src/database/repositories/plugin-storage.ts

@@ -10,23 +10,71 @@
 import type { Kysely, RawBuilder } from "kysely";
 import { sql } from "kysely";
 
+import {
+	assertStorageKey,
+	assertStorageRevision,
+	serializeConditionalValue,
+} from "../../plugins/conditional-storage.js";
 import {
 	buildWhereClause,
 	validateWhereClause,
 	validateOrderByClause,
 	getIndexedFields,
 	jsonOrderExtract,
+	StorageQueryError,
+	isInFilter,
+	StorageSerializationError,
 } from "../../plugins/storage-query.js";
+import { parseStorageUpdate } from "../../plugins/storage-update.js";
 import type {
 	StorageCollection,
 	QueryOptions,
 	PaginatedResult,
 	WhereClause,
+	UpdateIfResult,
+	VersionedValue,
+	ConditionalWriteResult,
+	ConditionalDeleteResult,
 } from "../../plugins/types.js";
+import { pluginDataWriteExpr, pluginDataUpdateGuard } from "../dialect-helpers.js";
 import { withTransaction } from "../transaction.js";
 import type { Database } from "../types.js";
 import { encodeCursor, decodeCursor } from "./types.js";
 
+/**
+ * SQLSTATEs a losing concurrent `updateIf` writer can abort with.
+ *
+ * `40001` (serialization_failure) is raised only above READ COMMITTED, where
+ * the loser cannot re-evaluate its guard against a newer snapshot. `40P01`
+ * (deadlock_detected) is not tied to isolation level: it needs only two
+ * transactions taking row locks in opposite order, which a caller reaches at
+ * READ COMMITTED by wrapping several `updateIf` calls in one transaction.
+ */
+const SERIALIZATION_SQLSTATES = new Set(["40001", "40P01"]);
+
+function errSqlState(err: unknown): string | undefined {
+	if (typeof err !== "object" || err === null) return undefined;
+	const code = (err as { code?: unknown }).code;
+	if (typeof code === "string") return code;
+	const cause = (err as { cause?: unknown }).cause;
+	if (typeof cause === "object" && cause !== null) {
+		const causeCode = (cause as { code?: unknown }).code;
+		if (typeof causeCode === "string") return causeCode;
+	}
+	return undefined;
+}
+
+export function mapSerializationFailure(err: unknown): unknown {
+	const sqlState = errSqlState(err);
+	if (sqlState !== undefined && SERIALIZATION_SQLSTATES.has(sqlState)) {
+		return new StorageSerializationError(
+			"Storage write must be retried. Restart the transaction before retrying when using an explicit transaction.",
+			{ cause: err, sqlState },
+		);
+	}
+	return err;
+}
+
 /**
  * Interleave a `?`-placeholder SQL string with its params into a single
  * boolean raw expression. Used as a WHERE predicate directly — wrapping it
@@ -52,6 +100,19 @@ function rawWhereExpr(sqlText: string, params: unknown[]): RawBuilder<boolean> {
  *
  * Implements the StorageCollection interface for a specific plugin and collection.
  */
+/**
+ * Rank a sort expression so NULLs get a deterministic position.
+ *
+ * A missing key in a schemaless document extracts as NULL, which sorts
+ * differently per dialect (SQLite first, Postgres last) and makes every
+ * comparison against it UNKNOWN. Sorting on this rank ahead of the value puts
+ * NULLs in the same place on both dialects and keeps the seek operands
+ * non-NULL.
+ */
+function nullRank(expr: RawBuilder<unknown>): RawBuilder<number> {
+	return sql`(case when ${expr} is null then 1 else 0 end)`;
+}
+
 export class PluginStorageRepository<T = unknown> implements StorageCollection<T> {
 	private indexedFields: Set<string>;
 
@@ -87,6 +148,7 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 	async put(id: string, data: T): Promise<void> {
 		const now = new Date().toISOString();
 		const jsonData = JSON.stringify(data);
+		const revision = crypto.randomUUID();
 
 		await this.db
 			.insertInto("_plugin_storage")
@@ -95,18 +157,85 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 				collection: this.collection,
 				id,
 				data: jsonData,
+				revision,
 				created_at: now,
 				updated_at: now,
 			})
 			.onConflict((oc) =>
 				oc.columns(["plugin_id", "collection", "id"]).doUpdateSet({
 					data: jsonData,
+					revision,
 					updated_at: now,
 				}),
 			)
 			.execute();
 	}
 
+	async getVersioned(id: string): Promise<VersionedValue<T> | null> {
+		assertStorageKey(id);
+		const row = await this.db
+			.selectFrom("_plugin_storage")
+			.select(["data", "revision"])
+			.where("plugin_id", "=", this.pluginId)
+			.where("collection", "=", this.collection)
+			.where("id", "=", id)
+			.executeTakeFirst();
+		if (!row) return null;
+		return { value: JSON.parse(row.data), revision: row.revision };
+	}
+
+	async compareAndSet(
+		id: string,
+		expectedRevision: string | null,
+		data: T,
+	): Promise<ConditionalWriteResult> {
+		assertStorageKey(id);
+		if (expectedRevision !== null) assertStorageRevision(expectedRevision);
+		const jsonData = serializeConditionalValue(data);
+		const revision = crypto.randomUUID();
+		const now = new Date().toISOString();
+		const row =
+			expectedRevision === null
+				? await this.db
+						.insertInto("_plugin_storage")
+						.values({
+							plugin_id: this.pluginId,
+							collection: this.collection,
+							id,
+							data: jsonData,
+							revision,
+							created_at: now,
+							updated_at: now,
+						})
+						.onConflict((oc) => oc.columns(["plugin_id", "collection", "id"]).doNothing())
+						.returning("revision")
+						.executeTakeFirst()
+				: await this.db
+						.updateTable("_plugin_storage")
+						.set({ data: jsonData, revision, updated_at: now })
+						.where("plugin_id", "=", this.pluginId)
+						.where("collection", "=", this.collection)
+						.where("id", "=", id)
+						.where("revision", "=", expectedRevision)
+						.returning("revision")
+						.executeTakeFirst();
+		return row ? { applied: true, revision: row.revision } : { applied: false };
+	}
+
+	async compareAndDelete(id: string, expectedRevision: string): Promise<ConditionalDeleteResult> {
+		assertStorageKey(id);
+		assertStorageRevision(expectedRevision);
+		const row = await this.db
+			.deleteFrom("_plugin_storage")
+			.where("plugin_id", "=", this.pluginId)
+			.where("collection", "=", this.collection)
+			.where("id", "=", id)
+			.where("revision", "=", expectedRevision)
+			.returning("id")
+			.executeTakeFirst();
+		return { applied: row !== undefined };
+	}
+
 	/**
 	 * Delete a document
 	 */
@@ -171,6 +300,7 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 		await withTransaction(this.db, async (trx) => {
 			for (const item of items) {
 				const jsonData = JSON.stringify(item.data);
+				const revision = crypto.randomUUID();
 				await trx
 					.insertInto("_plugin_storage")
 					.values({
@@ -178,12 +308,14 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 						collection: this.collection,
 						id: item.id,
 						data: jsonData,
+						revision,
 						created_at: now,
 						updated_at: now,
 					})
 					.onConflict((oc) =>
 						oc.columns(["plugin_id", "collection", "id"]).doUpdateSet({
 							data: jsonData,
+							revision,
 							updated_at: now,
 						}),
 					)
@@ -234,24 +366,75 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 			query = query.where(rawWhereExpr(whereResult.sql, whereResult.params));
 		}
 
+		const orderEntries = Object.entries(orderBy);
+		const orderDirections = new Set(orderEntries.map(([, direction]) => direction));
+		const descending = orderEntries.length > 0 && orderEntries[0][1] === "desc";
+
+		// A missing key in a schemaless document extracts as NULL, and NULL sorts
+		// differently per dialect (SQLite first, Postgres last) and makes any
+		// comparison against it UNKNOWN. Rank nulls explicitly so both the sort and
+		// the seek agree on where they sit, on either dialect, and so no comparison
+		// operand is ever NULL.
+		const sortExpr = (field: string): RawBuilder<unknown> =>
+			sql`${sql.raw(jsonOrderExtract(this.db, field))}`;
+
 		// Handle cursor-based pagination — throws on invalid cursor.
 		if (cursor) {
 			const decoded = decodeCursor(cursor);
-			query = query.where(({ eb }) =>
-				eb(sql`(created_at, id)`, ">", sql`(${decoded.orderValue}, ${decoded.id})`),
-			);
+			if (orderEntries.length === 0) {
+				query = query.where(({ eb }) =>
+					eb(sql`(created_at, id)`, ">", sql`(${decoded.orderValue}, ${decoded.id})`),
+				);
+			} else {
+				if (orderDirections.size > 1) {
+					throw new StorageQueryError(
+						"Cursor pagination requires every orderBy field to share one direction.",
+						Object.keys(orderBy).join(", "),
+						"Sort every field the same way, or page without a cursor.",
+					);
+				}
+				const op = descending ? sql`<` : sql`>`;
+				// The cursor row's sort values, recomputed with the same expression
+				// rather than carried in the cursor, so nothing is bound as a literal
+				// and neither dialect has to coerce a JSON value to compare it.
+				const cursorExpr = (field: string): RawBuilder<unknown> =>
+					sql`(select ${sql.raw(jsonOrderExtract(this.db, field))} from _plugin_storage where plugin_id = ${this.pluginId} and collection = ${this.collection} and id = ${decoded.id})`;
+
+				const fields = orderEntries.map(([field]) => {
+					const own = sortExpr(field);
+					const theirs = cursorExpr(field);
+					return {
+						equal: sql`(${nullRank(own)} = ${nullRank(theirs)} and (${nullRank(own)} = 1 or ${own} = ${theirs}))`,
+						after: sql`(${nullRank(own)} ${op} ${nullRank(theirs)} or (${nullRank(own)} = ${nullRank(theirs)} and ${nullRank(own)} = 0 and ${own} ${op} ${theirs}))`,
+					};
+				});
+
+				// Lexicographic seek: ties on every earlier field, then strictly after
+				// on this one; finally all fields tied and strictly after on id.
+				const terms = fields.map(
+					(_, k) =>
+						sql`(${sql.join([...fields.slice(0, k).map((f) => f.equal), fields[k].after], sql` and `)})`,
+				);
+				terms.push(
+					sql`(${sql.join([...fields.map((f) => f.equal), sql`id ${op} ${decoded.id}`], sql` and `)})`,
+				);
+				query = query.where(sql<boolean>`(${sql.join(terms, sql` or `)})`);
+			}
 		}
 
 		// Build ORDER BY using sql template
-		if (Object.keys(orderBy).length > 0) {
-			for (const [field, direction] of Object.entries(orderBy)) {
+		if (orderEntries.length > 0) {
+			for (const [field, direction] of orderEntries) {
+				const dir = direction === "desc" ? sql`desc` : sql`asc`;
+				const expr = sortExpr(field);
+				// Null rank first so NULL placement is identical on both dialects.
+				query = query.orderBy(sql`${nullRank(expr)} ${dir}`);
 				// Order over the jsonb-native value on Postgres so numeric fields sort
 				// numerically, not lexically. See pluginDataOrderExpr.
-				const extract = jsonOrderExtract(this.db, field);
-				const orderExpr =
-					direction === "desc" ? sql`${sql.raw(extract)} desc` : sql`${sql.raw(extract)} asc`;
-				query = query.orderBy(orderExpr);
+				query = query.orderBy(sql`${expr} ${dir}`);
 			}
+			// Total order, so a page boundary can never fall inside a group of ties.
+			query = query.orderBy("id", descending ? "desc" : "asc");
 		} else {
 			// Default ordering for consistent pagination
 			query = query.orderBy("created_at", "asc").orderBy("id", "asc");
@@ -307,6 +490,47 @@ export class PluginStorageRepository<T = unknown> implements StorageCollection<T
 		// Number() because the pg driver returns COUNT(*) (bigint) as a string.
 		return Number(result?.count ?? 0);
 	}
+
+	async updateIf(id: string, args: unknown): Promise<UpdateIfResult<T>> {
+		if (typeof id !== "string") throw new TypeError("Storage ID must be a string");
+		const { where, setEntries, deltaEntries } = parseStorageUpdate(args);
+
+		// Defensive empty-`in` guard: an empty `in: []` matches nothing. The shared
+		// where-translation would emit invalid `IN ()`; short-circuit to a no-op
+		// (matches nothing → applied:false) BEFORE building any SQL.
+		for (const value of Object.values(where)) {
+			if (isInFilter(value) && value.in.length === 0) {
+				return { applied: false };
+			}
+		}
+
+		const now = new Date().toISOString();
+		const dataExpr = pluginDataWriteExpr(this.db, setEntries, deltaEntries);
+
+		let query = this.db
+			.updateTable("_plugin_storage")
+			.set({ data: dataExpr, updated_at: now })
+			.where("plugin_id", "=", this.pluginId)
+			.where("collection", "=", this.collection)
+			.where("id", "=", id)
+			.where(pluginDataUpdateGuard(this.db, deltaEntries));
+
+		const whereResult = buildWhereClause(this.db, where);
+		if (whereResult.sql) {
+			query = query.where(rawWhereExpr(whereResult.sql, whereResult.params));
+		}
+
+		let row: { data: string } | undefined;
+		try {
+			row = await query.returning("data").executeTakeFirst();
+		} catch (err) {
+			throw mapSerializationFailure(err);
+		}
+		if (!row) return { applied: false };
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- JSON.parse returns any; generic callers provide T
+		const data = JSON.parse(row.data) as T;
+		return { applied: true, data };
+	}
 }
 
 /**

package/src/database/repositories/redirect.ts

@@ -1,6 +1,7 @@
 import { sql, type Kysely } from "kysely";
 import { ulid } from "ulidx";
 
+import { interpolateUrlPattern } from "../../i18n/resolve.js";
 import {
 	compilePattern,
 	matchPattern,
@@ -359,13 +360,23 @@ export class RedirectRepository {
 		newSlug: string,
 		contentId: string,
 		urlPattern: string | null,
+		oldPublishedAt?: string | null,
+		newPublishedAt?: string | null,
 	): Promise<Redirect | null> {
-		const oldUrl = urlPattern
-			? urlPattern.replace("{slug}", oldSlug).replace("{id}", contentId)
-			: `/${collection}/${oldSlug}`;
-		const newUrl = urlPattern
-			? urlPattern.replace("{slug}", newSlug).replace("{id}", contentId)
-			: `/${collection}/${newSlug}`;
+		const oldUrl = interpolateUrlPattern({
+			pattern: urlPattern,
+			collection,
+			slug: oldSlug,
+			id: contentId,
+			date: oldPublishedAt,
+		});
+		const newUrl = interpolateUrlPattern({
+			pattern: urlPattern,
+			collection,
+			slug: newSlug,
+			id: contentId,
+			date: newPublishedAt,
+		});
 
 		// A redirect from a URL to itself would make the page unreachable
 		if (oldUrl === newUrl) return null;

package/src/database/repositories/taxonomy.ts

@@ -749,7 +749,15 @@ export class TaxonomyRepository {
 	async clearEntryTerms(collection: string, entryId: string): Promise<number> {
 		const entryGroup = await this.resolveEntryTranslationGroup(collection, entryId);
 		if (!entryGroup) return 0;
+		return this.clearEntryGroupTerms(collection, entryGroup);
+	}
 
+	/**
+	 * Remove every term assignment held by an entry translation group. Takes the
+	 * group rather than an entry id, so it still works after the group's last
+	 * row has been deleted.
+	 */
+	async clearEntryGroupTerms(collection: string, entryGroup: string): Promise<number> {
 		const result = await this.db
 			.deleteFrom("content_taxonomies")
 			.where("collection", "=", collection)

package/src/database/repositories/types.ts

@@ -34,7 +34,10 @@ export interface UpdateContentInput {
 	slug?: string | null;
 	publishedAt?: string | null;
 	scheduledAt?: string | null;
+	/** Entry owner (`ec_{collection}.author_id`). */
 	authorId?: string | null;
+	/** Revision author, separate from entry ownership. */
+	revisionAuthorId?: string | null;
 	primaryBylineId?: string | null;
 }
 
@@ -64,13 +67,14 @@ export interface BylineSummary {
 	avatarMediaId: string | null;
 	/**
 	 * The avatar media's storage key, folded in by a LEFT JOIN on the
-	 * `media` table during content byline hydration. Non-null only when the
-	 * byline has an avatar AND was loaded through the content-credit hydration
-	 * path (`getContentBylines` / `getContentBylinesMany`, i.e. the
-	 * `entry.data.bylines` populated by `getEmDashCollection` / `getEmDashEntry`).
-	 * The plain byline finders (`findById`, `findBySlug`, …) leave it null.
+	 * `media` table. Populated by the content-credit hydration path
+	 * (`getContentBylines` / `getContentBylinesMany`, i.e. the
+	 * `entry.data.bylines` populated by `getEmDashCollection` /
+	 * `getEmDashEntry`) and by the single-row finders (`findById`,
+	 * `findBySlug`, `findByUserId`, `findByUserIds`). `findMany` doesn't
+	 * join media, so it leaves this null.
 	 *
-	 * Lets list pages build a direct storage URL for an author avatar without a
+	 * Lets a page build a direct storage URL for an author avatar without a
 	 * per-byline `MediaRepository.findById`, avoiding an N+1 when many distinct
 	 * authors appear on one page.
 	 *
@@ -86,7 +90,7 @@ export interface BylineSummary {
 	 * same media join as `avatarStorageKey`. Lets a renderer paint a blurred
 	 * placeholder while the full avatar loads, with no extra media lookup.
 	 * Null when the byline has no avatar, the media row has no blurhash, or the
-	 * byline was loaded through a finder that doesn't join media.
+	 * byline came from `findMany`, which doesn't join media.
 	 */
 	avatarBlurhash?: string | null;
 	/**

package/src/database/types.ts

@@ -396,6 +396,7 @@ export interface DeviceCodeTable {
 export interface OptionTable {
 	name: string;
 	value: string; // JSON
+	revision: Generated<string>;
 }
 
 export interface AuditLogTable {
@@ -433,12 +434,14 @@ export interface CollectionTable {
 	date_field: string | null; // field slug (datetime) for the admin list Date column (NULL = default)
 	url_pattern: string | null; // URL pattern with {slug} placeholder (e.g. "/blog/{slug}")
 	routable: Generated<number>; // 0 or 1 — published entries require a slug when enabled
-	hidden: Generated<number>; // 0 or 1 — omit the auto-generated admin sidebar entry
+	hidden: Generated<number>; // 0 or 1 — omit the auto-generated sidebar entry and dashboard quick action
 	sort_order: number | null; // explicit admin sidebar position; NULL = alphabetical fallback
+	nav_group: string | null; // admin sidebar folder label; NULL = inline
 	comments_enabled: Generated<number>; // 0 or 1
 	comments_moderation: Generated<string>; // 'all' | 'first_time' | 'none'
 	comments_closed_after_days: Generated<number>; // 0 = never close
 	comments_auto_approve_users: Generated<number>; // 0 or 1
+	edit_locking: Generated<number>; // 0 or 1; take an edit lock when an entry is opened
 	created_at: Generated<string>;
 	updated_at: Generated<string>;
 }
@@ -482,6 +485,7 @@ export interface PluginStorageTable {
 	collection: string;
 	id: string;
 	data: string; // JSON
+	revision: Generated<string>;
 	created_at: Generated<string>;
 	updated_at: Generated<string>;
 }
@@ -686,6 +690,7 @@ export interface Database {
 	_emdash_relations: RelationTable;
 	_emdash_content_references: ContentReferenceTable;
 	_emdash_rate_limits: RateLimitTable;
+	_emdash_entry_locks: EntryLockTable;
 }
 
 export type MediaRow = {
@@ -860,3 +865,12 @@ export interface RateLimitTable {
 	window: string; // ISO timestamp truncated to window size
 	count: number;
 }
+
+export interface EntryLockTable {
+	collection: string;
+	entry_id: string; // ID in the ec_* table
+	user_id: string;
+	token: string; // identifies the holder's editing session, one per tab
+	acquired_at: string; // ISO 8601 with milliseconds
+	expires_at: string; // ISO 8601 with milliseconds
+}

package/src/db/adapters.ts

@@ -199,7 +199,14 @@ export interface PostgresConfig {
 	user?: string;
 	password?: string;
 	ssl?: boolean;
-	pool?: { min?: number; max?: number };
+	pool?: {
+		min?: number;
+		max?: number;
+		/** Maximum time to wait for a connection, in milliseconds. Uses the pg default when omitted. */
+		connectionTimeoutMillis?: number;
+		/** Time before an idle client is closed, in milliseconds. Uses the pg default when omitted. */
+		idleTimeoutMillis?: number;
+	};
 	migrationConnectionStringEnv?: string;
 }
 

package/src/db/postgres.ts

@@ -11,6 +11,26 @@ import { Pool } from "pg";
 import { FailFastPostgresDialect } from "../database/pg-migration-lock.js";
 import type { PostgresConfig } from "./adapters.js";
 
+const URL_PATTERN = /[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+/g;
+const CREDENTIAL_PATTERN = /\b(auth|credential|key|password|secret|signature|token)\s*[=:]\s*\S+/gi;
+const ERROR_CODE_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+
+function redactPoolErrorMessage(message: string): string {
+	return message
+		.replace(URL_PATTERN, "[REDACTED_URL]")
+		.replace(CREDENTIAL_PATTERN, "$1=[REDACTED]")
+		.replaceAll(/[\r\n\t]/g, " ")
+		.slice(0, 1_000);
+}
+
+function logPoolError(error: Error): void {
+	// pg attaches the failed client to this error, which can contain connection credentials.
+	const code = "code" in error && typeof error.code === "string" ? error.code : undefined;
+	const safeCode = code && ERROR_CODE_PATTERN.test(code) ? ` (${code})` : "";
+	const message = redactPoolErrorMessage(error.message) || "Unknown error";
+	console.error(`[emdash] PostgreSQL idle client error${safeCode}: ${message}`);
+}
+
 /**
  * Create a PostgreSQL dialect from config
  */
@@ -25,7 +45,10 @@ export function createDialect(config: PostgresConfig): PostgresDialect {
 		ssl: config.ssl,
 		min: config.pool?.min ?? 0,
 		max: config.pool?.max ?? 10,
+		connectionTimeoutMillis: config.pool?.connectionTimeoutMillis,
+		idleTimeoutMillis: config.pool?.idleTimeoutMillis,
 	});
+	pool.on("error", logPoolError);
 
 	// Fail-fast migration locking instead of Kysely's blocking advisory
 	// lock — see pg-migration-lock.ts (#1744).