emdash 0.21.0 → 0.23.0

package/src/query.ts

@@ -26,9 +26,21 @@
 
 import { encodeCursor } from "./database/repositories/types.js";
 import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./i18n/config.js";
-import { CURSOR_RAW_VALUES, type WhereRange, type WhereValue } from "./loader.js";
+import {
+	CURSOR_RAW_VALUES,
+	FOLDED_BYLINES,
+	FOLDED_TERMS,
+	type WhereRange,
+	type WhereValue,
+} from "./loader.js";
+import {
+	cachedQuery,
+	contentNamespaces,
+	invalidateSchemaObjectCache,
+} from "./object-cache/index.js";
 import { requestCached } from "./request-cache.js";
 import { getRequestContext } from "./request-context.js";
+import type { TaxonomyTerm } from "./taxonomies/types.js";
 import { isMissingTableError } from "./utils/db-errors.js";
 import {
 	createEditable,
@@ -327,13 +339,61 @@ export async function getEmDashCollection<T extends string, D = InferCollectionD
 	// pagination contract.
 	const bucketed = bucketFilter(filter);
 	const cached = await requestCached(collectionCacheKey(type, bucketed.fetchFilter), () =>
-		getEmDashCollectionUncached<T, D>(type, bucketed.fetchFilter),
+		loadCollectionCached<T, D>(type, bucketed.fetchFilter),
 	);
 	return bucketed.requestedLimit === undefined
 		? cached
 		: sliceCollectionResult(cached, bucketed.requestedLimit, filter?.orderBy);
 }
 
+/** Shape of a cached collection snapshot (entries reduced to JSON-safe form). */
+interface CachedCollectionValue {
+	entries: unknown[];
+	nextCursor?: string;
+	cacheHint: CacheHint;
+}
+
+/**
+ * Distributed (L2) read-through around {@link getEmDashCollectionUncached}.
+ *
+ * Caches a JSON-safe snapshot keyed by collection + filter + effective locale,
+ * folding the shared `bylines`/`taxonomies` epochs into the key so renaming an
+ * author or term invalidates affected lists. Errors are never cached.
+ */
+async function loadCollectionCached<T extends string, D = InferCollectionData<T>>(
+	type: T,
+	filter?: CollectionFilter,
+): Promise<CollectionResult<D>> {
+	const snapshot = await cachedQuery<ContentSnapshot<CachedCollectionValue>>({
+		namespace: contentNamespaces(type),
+		key: `collection:${collectionCacheKey(type, filter)}|loc=${effectiveLocaleKey(filter)}`,
+		load: async () => {
+			const result = await getEmDashCollectionUncached<T, D>(type, filter);
+			if (result.error) {
+				return { ok: false, error: result.error, cacheHint: result.cacheHint };
+			}
+			return {
+				ok: true,
+				value: {
+					entries: result.entries.map(entrySnapshot),
+					nextCursor: result.nextCursor,
+					cacheHint: result.cacheHint,
+				},
+			};
+		},
+		cacheable: (snap) => snap.ok,
+	});
+
+	if (!snapshot.ok) {
+		return { entries: [], error: snapshot.error, cacheHint: snapshot.cacheHint };
+	}
+	return {
+		entries: snapshot.value.entries.map((entry) => reviveEntry<D>(entry)),
+		nextCursor: snapshot.value.nextCursor,
+		cacheHint: snapshot.value.cacheHint,
+	};
+}
+
 /**
  * Threshold for limit bucketing. Page templates routinely render small
  * "recent posts" widgets at limits 3-8; rounding those up to a single
@@ -498,6 +558,66 @@ function stableOrder(value: Record<string, unknown>): Record<string, unknown> {
 	return ordered;
 }
 
+// ── Object-cache (L2) serialization for content reads ───────────────────────
+//
+// Content entries can't be stored verbatim: each carries a non-serializable
+// `edit` proxy (a function) and a non-enumerable `CURSOR_RAW_VALUES` symbol on
+// `data` (raw date strings used to reproduce the loader's pagination cursor).
+// We reduce each entry to a JSON-safe snapshot before caching — copying the
+// cursor-raw values into an enumerable field and dropping `edit` — then rebuild
+// the symbol and re-attach a no-op `edit` on the way out. The object cache's
+// codec preserves `Date` instances, so timestamps survive the round-trip.
+//
+// L2 is only consulted for anonymous, non-preview, non-edit requests (see
+// `shouldBypass` in object-cache), where `edit` is always the no-op variant —
+// so dropping and recreating it is lossless.
+
+/** Enumerable field carrying the {@link CURSOR_RAW_VALUES} payload in snapshots. */
+const CURSOR_RAW_FIELD = "__emdashCursorRaw";
+
+/** Result wrapper distinguishing a cached error from a cacheable success. */
+type ContentSnapshot<S> =
+	| { ok: true; value: S }
+	| { ok: false; error?: Error; cacheHint: CacheHint };
+
+function entrySnapshot<D>(entry: ContentEntry<D>): Record<string, unknown> {
+	const data = entryData(entry);
+	const rawCursor = Reflect.get(data, CURSOR_RAW_VALUES);
+	// Drop the `edit` function; copy enumerable data + the cursor-raw values.
+	const { edit: _edit, ...rest } = entry as ContentEntry<D> & { edit?: unknown };
+	return {
+		...rest,
+		data: { ...data, [CURSOR_RAW_FIELD]: rawCursor ?? {} },
+	};
+}
+
+function reviveEntry<D>(raw: unknown): ContentEntry<D> {
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- snapshot shape produced by entrySnapshot
+	const entry = raw as Record<string, unknown>;
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- snapshot `data` is always a record
+	const data: Record<string, unknown> = { ...(entry.data as Record<string, unknown>) };
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- snapshot field written by entrySnapshot
+	const rawCursor = (data[CURSOR_RAW_FIELD] as Record<string, string> | undefined) ?? {};
+	delete data[CURSOR_RAW_FIELD];
+	Object.defineProperty(data, CURSOR_RAW_VALUES, {
+		value: rawCursor,
+		enumerable: false,
+		configurable: false,
+		writable: false,
+	});
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- rebuilt to the ContentEntry shape with a no-op edit proxy
+	return { ...entry, data, edit: createNoop() } as ContentEntry<D>;
+}
+
+/** Resolve the effective locale used by content reads, for the L2 cache key. */
+function effectiveLocaleKey(filter?: { locale?: string }): string {
+	const ctx = getRequestContext();
+	const i18nConfig = getI18nConfig();
+	return (
+		filter?.locale ?? ctx?.locale ?? (isI18nEnabled() ? i18nConfig!.defaultLocale : undefined) ?? ""
+	);
+}
+
 async function getEmDashCollectionUncached<T extends string, D = InferCollectionData<T>>(
 	type: T,
 	filter?: CollectionFilter,
@@ -620,6 +740,14 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 		return isPublished || !!isScheduledAndReady;
 	}
 
+	/** True when an entry is scheduled to become visible at a future time. */
+	function isPendingScheduled(entry: ContentEntry<D>): boolean {
+		const data = entryData(entry);
+		if (dataStr(data, "status") !== "scheduled") return false;
+		const scheduledAt = dataDate(data, "scheduledAt");
+		return scheduledAt !== undefined && scheduledAt.getTime() > Date.now();
+	}
+
 	// Build the fallback chain: [requestedLocale, fallback1, ..., defaultLocale]
 	// When i18n is disabled or no locale requested, just use a single-element chain
 	const localeChain =
@@ -721,27 +849,80 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 		return { entry: null, isPreview: serveDrafts, cacheHint: {} };
 	}
 
-	// Normal mode: try each locale in the fallback chain, only return published content
-	for (let i = 0; i < localeChain.length; i++) {
-		const locale = localeChain[i];
-		const fallbackLocale = i > 0 ? locale : undefined;
+	// Normal mode: try each locale in the fallback chain, only return published
+	// content. The full resolution (fallback chain + visibility + byline/term
+	// hydration) is wrapped in the distributed L2 cache, keyed by the requested
+	// locale. Preview/edit requests took the `serveDrafts` branch above and
+	// never reach here; the object cache additionally bypasses them.
+	// A scheduled entry becomes visible on a future clock tick, not on a write,
+	// so an L2 snapshot taken before its time would keep it hidden past go-live
+	// (until the publish sweep bumps the epoch or the TTL lapses). Mark such a
+	// resolution time-sensitive and skip caching it.
+	let timeSensitive = false;
+
+	const resolveNormal = async (): Promise<EntryResult<D>> => {
+		for (let i = 0; i < localeChain.length; i++) {
+			const locale = localeChain[i];
+			const fallbackLocale = i > 0 ? locale : undefined;
+
+			const { entry, error, cacheHint } = await getLiveEntry(COLLECTION_NAME, { type, id, locale });
+			if (error) {
+				return { entry: null, error, isPreview: false, cacheHint: {} };
+			}
 
-		const { entry, error, cacheHint } = await getLiveEntry(COLLECTION_NAME, { type, id, locale });
-		if (error) {
-			return { entry: null, error, isPreview: false, cacheHint: {} };
+			if (entry && isVisible(entry)) {
+				return successResult(wrapEntry(entry), {
+					isPreview: false,
+					fallbackLocale,
+					cacheHint: cacheHint ?? {},
+				});
+			}
+			if (entry && isPendingScheduled(entry)) {
+				timeSensitive = true;
+			}
+			// Entry not found or not visible in this locale — try next
 		}
+		return { entry: null, isPreview: false, cacheHint: {} };
+	};
 
-		if (entry && isVisible(entry)) {
-			return successResult(wrapEntry(entry), {
-				isPreview: false,
-				fallbackLocale,
-				cacheHint: cacheHint ?? {},
-			});
-		}
-		// Entry not found or not visible in this locale — try next
+	const snapshot = await cachedQuery<ContentSnapshot<CachedEntryValue>>({
+		namespace: contentNamespaces(type),
+		key: `entry:${id}|loc=${requestedLocale ?? ""}`,
+		load: async () => {
+			const result = await resolveNormal();
+			if (result.error) {
+				return { ok: false, error: result.error, cacheHint: result.cacheHint };
+			}
+			return {
+				ok: true,
+				value: {
+					entry: result.entry ? entrySnapshot(result.entry) : null,
+					isPreview: result.isPreview,
+					fallbackLocale: result.fallbackLocale,
+					cacheHint: result.cacheHint,
+				},
+			};
+		},
+		cacheable: (snap) => snap.ok && !timeSensitive,
+	});
+
+	if (!snapshot.ok) {
+		return { entry: null, error: snapshot.error, isPreview: false, cacheHint: snapshot.cacheHint };
 	}
+	return {
+		entry: snapshot.value.entry ? reviveEntry<D>(snapshot.value.entry) : null,
+		isPreview: snapshot.value.isPreview,
+		fallbackLocale: snapshot.value.fallbackLocale,
+		cacheHint: snapshot.value.cacheHint,
+	};
+}
 
-	return { entry: null, isPreview: false, cacheHint: {} };
+/** Shape of a cached single-entry snapshot. */
+interface CachedEntryValue {
+	entry: Record<string, unknown> | null;
+	isPreview: boolean;
+	fallbackLocale?: string;
+	cacheHint: CacheHint;
 }
 
 /**
@@ -756,6 +937,67 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 async function hydrateEntryBylines<D>(type: string, entries: ContentEntry<D>[]): Promise<void> {
 	if (entries.length === 0) return;
 
+	// Fast path: bylines were folded into the content query. Parse the JSON
+	// (no extra round trip) for the common case — explicit credits, no byline
+	// custom fields, no author fallback. The query path below handles the rest:
+	//  - author fallback (entry has authorId but no explicit credit), and
+	//  - custom byline fields (can't be expressed in the folded subquery).
+	if (entries.every((e) => FOLDED_BYLINES in entryData(e))) {
+		const parsed = entries.map((entry) => {
+			const data = entryData(entry);
+			const folded = Reflect.get(data, FOLDED_BYLINES);
+			const rows = Array.isArray(folded) ? folded : [];
+			const credits = rows
+				.map((raw) => {
+					const b = raw?.byline ?? {};
+					return {
+						roleLabel: raw?.roleLabel ?? null,
+						sortOrder: Number(raw?.sortOrder ?? 0),
+						source: "explicit" as const,
+						byline: { ...b, isGuest: Boolean(b.isGuest), customFields: {} },
+					};
+				})
+				.toSorted((a, b) => a.sortOrder - b.sortOrder);
+			return { data, credits };
+		});
+
+		// Fall back to the full query path when the fold can't be trusted to be
+		// complete: an entry with a byline reference (explicit primary, or an
+		// author for the author-fallback) but no folded credits — e.g. a credit
+		// in a different locale than the row, which the locale-correlated subquery
+		// skips, or the author-fallback path which the fold doesn't express.
+		let needsQueryPath = parsed.some(
+			(p) =>
+				p.credits.length === 0 &&
+				(dataStr(p.data, "authorId") !== "" || dataStr(p.data, "primaryBylineId") !== ""),
+		);
+		let hasCustomFields = false;
+		if (!needsQueryPath) {
+			try {
+				const { getDb } = await import("./loader.js");
+				const db = await getDb();
+				const { getBylineFieldDefs } = await import("./bylines/field-defs-cache.js");
+				hasCustomFields = (await getBylineFieldDefs(db)).length > 0;
+			} catch (error) {
+				// A missing table is expected pre-migration and means there are no
+				// custom fields — the fold's values are complete. Any other error
+				// (lock-init failure, dialect error) means the probe can't be
+				// trusted, so fall back to the query path rather than risk serving
+				// folded bylines with empty customFields.
+				if (!isMissingTableError(error)) needsQueryPath = true;
+			}
+		}
+
+		if (!needsQueryPath && !hasCustomFields) {
+			for (const p of parsed) {
+				p.data.bylines = p.credits;
+				p.data.byline = p.credits[0]?.byline ?? null;
+			}
+			return;
+		}
+		// Fall through to the full query path for fallback / custom-field cases.
+	}
+
 	try {
 		const { getBylinesForEntries } = await import("./bylines/index.js");
 
@@ -831,6 +1073,45 @@ async function hydrateEntryTerms<D>(
 ): Promise<void> {
 	if (entries.length === 0) return;
 
+	// Fast path: terms were folded into the content query. Group the JSON and
+	// skip the separate content_taxonomies query.
+	if (entries.every((e) => FOLDED_TERMS in entryData(e))) {
+		const perEntry: Array<{ entryId: string; byTaxonomy: Record<string, TaxonomyTerm[]> }> = [];
+		for (const entry of entries) {
+			const data = entryData(entry);
+			const folded = Reflect.get(data, FOLDED_TERMS);
+			const rows = Array.isArray(folded) ? folded : [];
+			const grouped: Record<string, TaxonomyTerm[]> = {};
+			for (const r of rows) {
+				const name = String(r?.name);
+				(grouped[name] ??= []).push({
+					id: r?.id,
+					name,
+					slug: r?.slug,
+					label: r?.label,
+					parentId: r?.parent_id ?? undefined,
+					children: [],
+					locale: r?.locale,
+					translationGroup: r?.translation_group,
+				});
+			}
+			// Match getAllTermsForEntries' ORDER BY label (dropped from the
+			// aggregate since SQLite and Postgres order it differently).
+			for (const [name, arr] of Object.entries(grouped)) {
+				grouped[name] = arr.toSorted((a, b) => String(a.label).localeCompare(String(b.label)));
+			}
+			data.terms = grouped;
+			const entryId = dataStr(data, "id");
+			if (entryId) perEntry.push({ entryId, byTaxonomy: grouped });
+		}
+		// Prime the per-entry request cache (wildcard + present taxonomies) so
+		// subsequent getEntryTerms(...) calls in this render hit the cache instead
+		// of issuing an N+1 query. No DB lookup — purely from the folded data.
+		const { primeFoldedEntryTerms } = await import("./taxonomies/index.js");
+		primeFoldedEntryTerms(type, perEntry, { locale });
+		return;
+	}
+
 	try {
 		const { getAllTermsForEntries } = await import("./taxonomies/index.js");
 
@@ -972,9 +1253,14 @@ let cachedUrlPatterns: CachedPattern[] | null = null;
 /**
  * Invalidate the cached URL patterns used by resolveEmDashPath.
  * Call when collection URL patterns change (schema updates).
+ *
+ * Also busts the distributed schema cache (collection metadata such as
+ * `commentsEnabled`, `supports`, fields read by `getCollectionInfo`), since
+ * every schema-mutation path already routes through here.
  */
 export function invalidateUrlPatternCache(): void {
 	cachedUrlPatterns = null;
+	invalidateSchemaObjectCache();
 }
 
 /**

package/src/schema/query.ts

@@ -8,6 +8,7 @@ import type { Kysely } from "kysely";
 
 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 { SchemaRegistry } from "./registry.js";
 import type { Collection } from "./types.js";
@@ -26,10 +27,16 @@ import type { Collection } from "./types.js";
  * ```
  */
 export async function getCollectionInfo(slug: string): Promise<Collection | null> {
-	return requestCached(`collection-info:${slug}`, async () => {
-		const db = await getDb();
-		return getCollectionInfoWithDb(db, slug);
-	});
+	return requestCached(`collection-info:${slug}`, () =>
+		cachedQuery({
+			namespace: CacheNamespace.SCHEMA,
+			key: `collection-info:${slug}`,
+			load: async () => {
+				const db = await getDb();
+				return getCollectionInfoWithDb(db, slug);
+			},
+		}),
+	);
 }
 
 /**

package/src/schema/zod-generator.ts

@@ -268,8 +268,10 @@ export function validateContent(
  * Generate TypeScript interface from field definitions
  * Used by CLI `emdash types` to generate types
  */
-export function generateTypeScript(collection: CollectionWithFields): string {
-	const interfaceName = getInterfaceName(collection);
+export function generateTypeScript(
+	collection: CollectionWithFields,
+	interfaceName: string = getInterfaceName(collection),
+): string {
 	const lines: string[] = [];
 
 	lines.push(`export interface ${interfaceName} {`);
@@ -324,9 +326,14 @@ export function generateTypesFile(collections: CollectionWithFields[]): string {
 	lines.push(`import type { ${imports.join(", ")} } from "emdash";`);
 	lines.push(``);
 
+	// Singularizing the slug can map two distinct slugs to the same name
+	// (e.g. `book` and `books` both -> `Book`), so resolve collisions up front
+	// to keep every interface identifier unique within the file.
+	const interfaceNames = uniqueInterfaceNames(collections);
+
 	// Generate individual interfaces
 	for (const collection of collections) {
-		lines.push(generateTypeScript(collection));
+		lines.push(generateTypeScript(collection, interfaceNames.get(collection.slug)));
 		lines.push(``);
 	}
 
@@ -334,8 +341,7 @@ export function generateTypesFile(collections: CollectionWithFields[]): string {
 	lines.push(`declare module "emdash" {`);
 	lines.push(`  interface EmDashCollections {`);
 	for (const collection of collections) {
-		const interfaceName = getInterfaceName(collection);
-		lines.push(`    ${collection.slug}: ${interfaceName};`);
+		lines.push(`    ${collection.slug}: ${interfaceNames.get(collection.slug)};`);
 	}
 	lines.push(`  }`);
 	lines.push(`}`);
@@ -427,7 +433,8 @@ function pascalCase(str: string): string {
 }
 
 /**
- * Simple singularization - handles common cases
+ * Naive singularization for slug-derived interface names. Handles the common
+ * English plural endings; intentionally simple, not a full inflector.
  */
 function singularize(str: string): string {
 	if (str.endsWith("ies")) {
@@ -446,8 +453,46 @@ function singularize(str: string): string {
 }
 
 /**
- * Get the interface name for a collection
+ * Get the interface name for a collection.
+ *
+ * Derived from the slug, not the human label. Slugs are constrained to
+ * `/^[a-z][a-z0-9_]*$/`, so PascalCasing one always yields a valid TS
+ * identifier; labels are arbitrary and user-controlled (punctuation, spaces,
+ * duplicates across collections), which produced syntactically invalid or
+ * duplicate interface names. The slug is singularized first because the
+ * interface describes a single entry, not the collection (`posts` -> `Post`).
+ *
+ * Singularization can map two distinct slugs onto the same name, so callers
+ * generating more than one interface must dedupe -- see `uniqueInterfaceNames`.
  */
 function getInterfaceName(collection: CollectionWithFields): string {
-	return pascalCase(collection.labelSingular || singularize(collection.slug));
+	return pascalCase(singularize(collection.slug));
+}
+
+/**
+ * Resolve interface names for a set of collections, guaranteeing each is
+ * unique within the file. Collisions (from singularization or PascalCasing
+ * collapsing distinct slugs) get a numeric suffix in collection order, so the
+ * generated `.d.ts` never declares two interfaces with the same identifier.
+ *
+ * The suffix is chosen against the set of names already emitted, not a
+ * per-base counter, so a generated name can't collide with another slug's
+ * base name (e.g. slugs `book`, `books`, `book2`: `books` -> `Book2` would
+ * clash with `book2`, so it advances to `Book3`).
+ */
+export function uniqueInterfaceNames(collections: CollectionWithFields[]): Map<string, string> {
+	const used = new Set<string>();
+	const names = new Map<string, string>();
+	for (const collection of collections) {
+		const base = getInterfaceName(collection);
+		let name = base;
+		let suffix = 2;
+		while (used.has(name)) {
+			name = `${base}${suffix}`;
+			suffix++;
+		}
+		used.add(name);
+		names.set(collection.slug, name);
+	}
+	return names;
 }

package/src/settings/index.ts

@@ -12,7 +12,11 @@ import { MediaRepository } from "../database/repositories/media.js";
 import { OptionsRepository } from "../database/repositories/options.js";
 import type { Database } from "../database/types.js";
 import { getDb } from "../loader.js";
+import { cachedQuery, invalidateObjectCache } from "../object-cache/index.js";
 import { peekRequestCache, requestCached } from "../request-cache.js";
+
+/** Object-cache namespace for site settings. */
+const SETTINGS_CACHE_NAMESPACE = "settings";
 import type { Storage } from "../storage/types.js";
 import {
 	createSingleFlightCache,
@@ -61,6 +65,8 @@ const settingsCache: SingleFlightCache<Partial<SiteSettings>> =
  */
 export function invalidateSiteSettingsCache(): void {
 	invalidateSingleFlightCache(settingsCache);
+	// Cross-isolate invalidation for the optional distributed object cache.
+	invalidateObjectCache(SETTINGS_CACHE_NAMESPACE);
 }
 
 /**
@@ -210,14 +216,21 @@ export async function getSiteSettingWithDb<K extends SiteSettingKey>(
 export function getSiteSettings(): Promise<Partial<SiteSettings>> {
 	// requestCached dedupes within a single request; singleFlightCached
 	// coalesces across requests and caches the resolved value for the
-	// global scope's lifetime without ever sharing an awaitable promise.
+	// global scope's lifetime without ever sharing an awaitable promise. The
+	// distributed object cache (cachedQuery) sits beneath both, backing cold
+	// isolates without a database round-trip.
 	return requestCached("siteSettings", () =>
 		singleFlightCached(
 			settingsCache,
-			async () => {
-				const db = await getDb();
-				return getSiteSettingsWithDb(db);
-			},
+			() =>
+				cachedQuery({
+					namespace: SETTINGS_CACHE_NAMESPACE,
+					key: "all",
+					load: async () => {
+						const db = await getDb();
+						return getSiteSettingsWithDb(db);
+					},
+				}),
 			{ anchor: (promise) => after(() => promise), ownerTimeoutMs: 30_000 },
 		),
 	);