emdash 0.20.0 → 0.22.0

package/src/taxonomies/index.ts

@@ -13,6 +13,12 @@
 
 import { resolveLocale, resolveLocaleChain } from "../i18n/resolve.js";
 import { getDb } from "../loader.js";
+import {
+	cachedQuery,
+	CacheNamespace,
+	contentNamespace,
+	invalidateTaxonomyObjectCache,
+} from "../object-cache/index.js";
 import { peekRequestCache, requestCached, setRequestCacheEntry } from "../request-cache.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { isMissingTableError } from "../utils/db-errors.js";
@@ -23,10 +29,12 @@ export interface TaxonomyQueryOptions {
 }
 
 /**
- * No-op — kept for API compatibility.
+ * Invalidate cached taxonomy data in the distributed object cache (and any
+ * content that hydrates taxonomy terms). The legacy in-isolate term cache was
+ * removed, so this used to be a no-op; it now drives object-cache invalidation.
  */
 export function invalidateTermCache(): void {
-	// Intentionally empty.
+	invalidateTaxonomyObjectCache();
 }
 
 /**
@@ -36,13 +44,19 @@ export function invalidateTermCache(): void {
  */
 export async function getTaxonomyDefs(options: TaxonomyQueryOptions = {}): Promise<TaxonomyDef[]> {
 	const locale = resolveLocale(options.locale);
-	return requestCached(`taxonomy-defs:${locale ?? "*"}`, async () => {
-		const db = await getDb();
-		let query = db.selectFrom("_emdash_taxonomy_defs").selectAll();
-		if (locale !== undefined) query = query.where("locale", "=", locale);
-		const rows = await query.execute();
-		return rows.map(rowToTaxonomyDef);
-	});
+	return requestCached(`taxonomy-defs:${locale ?? "*"}`, () =>
+		cachedQuery({
+			namespace: CacheNamespace.TAXONOMIES,
+			key: `defs:${locale ?? "*"}`,
+			load: async () => {
+				const db = await getDb();
+				let query = db.selectFrom("_emdash_taxonomy_defs").selectAll();
+				if (locale !== undefined) query = query.where("locale", "=", locale);
+				const rows = await query.execute();
+				return rows.map(rowToTaxonomyDef);
+			},
+		}),
+	);
 }
 
 /**
@@ -106,50 +120,62 @@ export async function getTaxonomyTerms(
 	options: TaxonomyQueryOptions = {},
 ): Promise<TaxonomyTerm[]> {
 	const locale = resolveLocale(options.locale);
-	return requestCached(`taxonomy-terms:${taxonomyName}:${locale ?? "*"}`, async () => {
-		const db = await getDb();
+	return requestCached(`taxonomy-terms:${taxonomyName}:${locale ?? "*"}`, () =>
+		cachedQuery({
+			namespace: CacheNamespace.TAXONOMIES,
+			key: `terms:${taxonomyName}:${locale ?? "*"}`,
+			load: () => loadTaxonomyTerms(taxonomyName, locale, options),
+		}),
+	);
+}
 
-		const def = await getTaxonomyDef(taxonomyName, options);
-		if (!def) return [];
+async function loadTaxonomyTerms(
+	taxonomyName: string,
+	locale: string | undefined,
+	options: TaxonomyQueryOptions,
+): Promise<TaxonomyTerm[]> {
+	const db = await getDb();
 
-		let termsQuery = db
-			.selectFrom("taxonomies")
-			.selectAll()
-			.where("name", "=", taxonomyName)
-			.orderBy("label", "asc");
-		if (locale !== undefined) termsQuery = termsQuery.where("locale", "=", locale);
-		const rows = await termsQuery.execute();
-
-		// Counts are keyed by translation_group (what the pivot stores) and are
-		// locale-independent, so the aggregate is shared across every taxonomy
-		// rendered in this request (Categories + Tags widgets, etc.).
-		const counts = await getTaxonomyTermCounts();
-
-		const flatTerms: TaxonomyTermRow[] = rows.map((row) => ({
-			id: row.id,
-			name: row.name,
-			slug: row.slug,
-			label: row.label,
-			parent_id: row.parent_id,
-			data: row.data,
-			locale: row.locale,
-			translation_group: row.translation_group,
-		}));
-
-		if (def.hierarchical) return buildTree(flatTerms, counts);
-
-		return flatTerms.map((term) => ({
-			id: term.id,
-			name: term.name,
-			slug: term.slug,
-			label: term.label,
-			description: term.data ? JSON.parse(term.data).description : undefined,
-			children: [],
-			count: counts.get(term.translation_group ?? term.id) ?? 0,
-			locale: term.locale,
-			translationGroup: term.translation_group,
-		}));
-	});
+	const def = await getTaxonomyDef(taxonomyName, options);
+	if (!def) return [];
+
+	let termsQuery = db
+		.selectFrom("taxonomies")
+		.selectAll()
+		.where("name", "=", taxonomyName)
+		.orderBy("label", "asc");
+	if (locale !== undefined) termsQuery = termsQuery.where("locale", "=", locale);
+	const rows = await termsQuery.execute();
+
+	// Counts are keyed by translation_group (what the pivot stores) and are
+	// locale-independent, so the aggregate is shared across every taxonomy
+	// rendered in this request (Categories + Tags widgets, etc.).
+	const counts = await getTaxonomyTermCounts();
+
+	const flatTerms: TaxonomyTermRow[] = rows.map((row) => ({
+		id: row.id,
+		name: row.name,
+		slug: row.slug,
+		label: row.label,
+		parent_id: row.parent_id,
+		data: row.data,
+		locale: row.locale,
+		translation_group: row.translation_group,
+	}));
+
+	if (def.hierarchical) return buildTree(flatTerms, counts);
+
+	return flatTerms.map((term) => ({
+		id: term.id,
+		name: term.name,
+		slug: term.slug,
+		label: term.label,
+		description: term.data ? JSON.parse(term.data).description : undefined,
+		children: [],
+		count: counts.get(term.translation_group ?? term.id) ?? 0,
+		locale: term.locale,
+		translationGroup: term.translation_group,
+	}));
 }
 
 /**
@@ -183,8 +209,23 @@ export async function getTerm(
 	slug: string,
 	options: TaxonomyQueryOptions = {},
 ): Promise<TaxonomyTerm | null> {
-	const db = await getDb();
 	const chain = resolveLocaleChain(options.locale);
+	// Cached under the shared taxonomies epoch (bumped on any taxonomy / term
+	// assignment write). The `count` reflects content_taxonomies rows; a stale
+	// count after a bare content delete is bounded by the entry's TTL.
+	return cachedQuery({
+		namespace: CacheNamespace.TAXONOMIES,
+		key: `term:${taxonomyName}:${slug}:${chain.join(",")}`,
+		load: () => loadTerm(taxonomyName, slug, chain),
+	});
+}
+
+async function loadTerm(
+	taxonomyName: string,
+	slug: string,
+	chain: string[],
+): Promise<TaxonomyTerm | null> {
+	const db = await getDb();
 
 	let row: Awaited<ReturnType<ReturnType<typeof selectTerm>["executeTakeFirst"]>>;
 	const selectTerm = () =>
@@ -262,33 +303,46 @@ export function getEntryTerms(
 	options: TaxonomyQueryOptions = {},
 ): Promise<TaxonomyTerm[]> {
 	const locale = resolveLocale(options.locale);
+	// requestCached short-circuits to values primed by getAllTermsForEntries
+	// during entry hydration (same key shape). On a warm content-cache hit
+	// hydration doesn't run, so the inner cachedQuery serves this from KV
+	// instead of falling through to D1 on every request.
 	return requestCached(
 		`terms:${collection}:${entryId}:${taxonomyName ?? "*"}:${locale ?? "*"}`,
-		async () => {
-			const db = await getDb();
-
-			let query = db
-				.selectFrom("content_taxonomies")
-				.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
-				.selectAll("taxonomies")
-				.where("content_taxonomies.collection", "=", collection)
-				.where("content_taxonomies.entry_id", "=", entryId);
-
-			if (taxonomyName) query = query.where("taxonomies.name", "=", taxonomyName);
-			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
-
-			const rows = await query.execute();
-			return rows.map<TaxonomyTerm>((row) => ({
-				id: row.id,
-				name: row.name,
-				slug: row.slug,
-				label: row.label,
-				parentId: row.parent_id ?? undefined,
-				children: [],
-				locale: row.locale,
-				translationGroup: row.translation_group,
-			}));
-		},
+		() =>
+			cachedQuery({
+				namespace: [contentNamespace(collection), CacheNamespace.TAXONOMIES],
+				key: `entryTerms:${collection}:${entryId}:${taxonomyName ?? "*"}:${locale ?? "*"}`,
+				load: async () => {
+					const db = await getDb();
+
+					let query = db
+						.selectFrom("content_taxonomies")
+						.innerJoin(
+							"taxonomies",
+							"taxonomies.translation_group",
+							"content_taxonomies.taxonomy_id",
+						)
+						.selectAll("taxonomies")
+						.where("content_taxonomies.collection", "=", collection)
+						.where("content_taxonomies.entry_id", "=", entryId);
+
+					if (taxonomyName) query = query.where("taxonomies.name", "=", taxonomyName);
+					if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
+
+					const rows = await query.execute();
+					return rows.map<TaxonomyTerm>((row) => ({
+						id: row.id,
+						name: row.name,
+						slug: row.slug,
+						label: row.label,
+						parentId: row.parent_id ?? undefined,
+						children: [],
+						locale: row.locale,
+						translationGroup: row.translation_group,
+					}));
+				},
+			}),
 	);
 }
 
@@ -301,107 +355,125 @@ export async function getTermsForEntries(
 	taxonomyName: string,
 	options: TaxonomyQueryOptions = {},
 ): Promise<Map<string, TaxonomyTerm[]>> {
-	const result = new Map<string, TaxonomyTerm[]>();
 	const uniqueIds = [...new Set(entryIds)];
-	for (const id of uniqueIds) result.set(id, []);
-	if (uniqueIds.length === 0) return result;
-
+	if (uniqueIds.length === 0) return new Map();
 	const locale = resolveLocale(options.locale);
 	const localeKey = locale ?? "*";
 
-	// Entry-term hydration (getAllTermsForEntries -> primeEntryTermsCache)
-	// seeds the per-entry cache under the same key getEntryTerms uses:
-	// `terms:${collection}:${entryId}:${taxonomyName}:${localeKey}`, storing a
-	// TaxonomyTerm[] (including `[]` for entries with no terms). Satisfy those
-	// from cache and run the batched query only for the ids that missed.
-	const missedIds: string[] = [];
-	type CacheRead = { id: string; terms: TaxonomyTerm[] } | { id: string; miss: true };
-	const cacheReads: Array<Promise<CacheRead>> = [];
-	for (const id of uniqueIds) {
-		const cached = peekRequestCache<TaxonomyTerm[]>(
-			`terms:${collection}:${id}:${taxonomyName}:${localeKey}`,
-		);
-		if (cached) {
-			// A peeked promise can reject (e.g. a sibling getEntryTerms hit a
-			// missing table). Treat a rejection as a cache miss so the batched
-			// query path -- and its isMissingTableError guard below -- still runs,
-			// rather than propagating an uncaught error.
-			cacheReads.push(
-				cached.then(
-					(terms): CacheRead => ({ id, terms }),
-					(): CacheRead => ({ id, miss: true }),
-				),
+	// The query result is a Map, which JSON can't represent — cache it as an
+	// array of [entryId, terms] pairs and rebuild the Map on read.
+	const load = async (): Promise<Array<[string, TaxonomyTerm[]]>> => {
+		const result = new Map<string, TaxonomyTerm[]>();
+		for (const id of uniqueIds) result.set(id, []);
+
+		// Entry-term hydration (getAllTermsForEntries -> primeEntryTermsCache)
+		// seeds the per-entry cache under the same key getEntryTerms uses:
+		// `terms:${collection}:${entryId}:${taxonomyName}:${localeKey}`, storing a
+		// TaxonomyTerm[] (including `[]` for entries with no terms). Satisfy those
+		// from cache and run the batched query only for the ids that missed.
+		const missedIds: string[] = [];
+		type CacheRead = { id: string; terms: TaxonomyTerm[] } | { id: string; miss: true };
+		const cacheReads: Array<Promise<CacheRead>> = [];
+		for (const id of uniqueIds) {
+			const cached = peekRequestCache<TaxonomyTerm[]>(
+				`terms:${collection}:${id}:${taxonomyName}:${localeKey}`,
 			);
-		} else {
-			missedIds.push(id);
+			if (cached) {
+				// A peeked promise can reject (e.g. a sibling getEntryTerms hit a
+				// missing table). Treat a rejection as a cache miss so the batched
+				// query path -- and its isMissingTableError guard below -- still runs,
+				// rather than propagating an uncaught error.
+				cacheReads.push(
+					cached.then(
+						(terms): CacheRead => ({ id, terms }),
+						(): CacheRead => ({ id, miss: true }),
+					),
+				);
+			} else {
+				missedIds.push(id);
+			}
 		}
-	}
-	for (const read of await Promise.all(cacheReads)) {
-		if ("miss" in read) {
-			missedIds.push(read.id);
-			continue;
+		for (const read of await Promise.all(cacheReads)) {
+			if ("miss" in read) {
+				missedIds.push(read.id);
+				continue;
+			}
+			// Return a private copy. The cached array and its term objects are shared
+			// with getEntryTerms/getAllTermsForEntries (primeEntryTermsCache stores
+			// the same references), so a caller that mutates the result -- sorting in
+			// place, pushing into `children` -- must not poison the cache. The
+			// pre-cache implementation always returned freshly built arrays.
+			result.set(
+				read.id,
+				read.terms.map((t) => ({ ...t, children: [...t.children] })),
+			);
 		}
-		// Return a private copy. The cached array and its term objects are shared
-		// with getEntryTerms/getAllTermsForEntries (primeEntryTermsCache stores
-		// the same references), so a caller that mutates the result -- sorting in
-		// place, pushing into `children` -- must not poison the cache. The
-		// pre-cache implementation always returned freshly built arrays.
-		result.set(
-			read.id,
-			read.terms.map((t) => ({ ...t, children: [...t.children] })),
-		);
-	}
 
-	if (missedIds.length === 0) return result;
+		if (missedIds.length === 0) return [...result.entries()];
 
-	const db = await getDb();
+		const db = await getDb();
+		for (const chunk of chunks(missedIds, SQL_BATCH_SIZE)) {
+			let rows;
+			try {
+				let query = db
+					.selectFrom("content_taxonomies")
+					.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
+					.select([
+						"content_taxonomies.entry_id",
+						"taxonomies.id",
+						"taxonomies.name",
+						"taxonomies.slug",
+						"taxonomies.label",
+						"taxonomies.parent_id",
+						"taxonomies.locale",
+						"taxonomies.translation_group",
+					])
+					.where("content_taxonomies.collection", "=", collection)
+					.where("content_taxonomies.entry_id", "in", chunk)
+					.where("taxonomies.name", "=", taxonomyName)
+					// Match the order getAllTermsForEntries (the cache primer) uses, so
+					// cache-hit and DB-miss entries in one result are ordered consistently.
+					.orderBy("taxonomies.label", "asc");
+				if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
+				rows = await query.execute();
+			} catch (error) {
+				if (isMissingTableError(error)) return [...result.entries()];
+				throw error;
+			}
 
-	for (const chunk of chunks(missedIds, SQL_BATCH_SIZE)) {
-		let rows;
-		try {
-			let query = db
-				.selectFrom("content_taxonomies")
-				.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
-				.select([
-					"content_taxonomies.entry_id",
-					"taxonomies.id",
-					"taxonomies.name",
-					"taxonomies.slug",
-					"taxonomies.label",
-					"taxonomies.parent_id",
-					"taxonomies.locale",
-					"taxonomies.translation_group",
-				])
-				.where("content_taxonomies.collection", "=", collection)
-				.where("content_taxonomies.entry_id", "in", chunk)
-				.where("taxonomies.name", "=", taxonomyName)
-				// Match the order getAllTermsForEntries (the cache primer) uses, so
-				// cache-hit and DB-miss entries in one result are ordered consistently.
-				.orderBy("taxonomies.label", "asc");
-			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
-			rows = await query.execute();
-		} catch (error) {
-			if (isMissingTableError(error)) return result;
-			throw error;
+			for (const row of rows) {
+				const term: TaxonomyTerm = {
+					id: row.id,
+					name: row.name,
+					slug: row.slug,
+					label: row.label,
+					parentId: row.parent_id ?? undefined,
+					children: [],
+					locale: row.locale,
+					translationGroup: row.translation_group,
+				};
+				const terms = result.get(row.entry_id);
+				if (terms) terms.push(term);
+			}
 		}
 
-		for (const row of rows) {
-			const term: TaxonomyTerm = {
-				id: row.id,
-				name: row.name,
-				slug: row.slug,
-				label: row.label,
-				parentId: row.parent_id ?? undefined,
-				children: [],
-				locale: row.locale,
-				translationGroup: row.translation_group,
-			};
-			const terms = result.get(row.entry_id);
-			if (terms) terms.push(term);
-		}
-	}
+		return [...result.entries()];
+	};
 
-	return result;
+	// Key on the sorted unique ids. Bound the key length: very large batches
+	// (rare; they come from collection hydration, already served by the content
+	// cache) bypass the object cache rather than blow past KV's key limit.
+	const idKey = uniqueIds.toSorted().join(",");
+	const pairs =
+		idKey.length <= 256
+			? await cachedQuery({
+					namespace: [contentNamespace(collection), CacheNamespace.TAXONOMIES],
+					key: `termsForEntries:${collection}:${taxonomyName}:${locale ?? "*"}:${idKey}`,
+					load,
+				})
+			: await load();
+
+	return new Map(pairs);
 }
 
 /**

package/src/utils/{isolate-cache.ts → single-flight-cache.ts}

@@ -1,16 +1,21 @@
 /**
- * Isolate-lifetime async value cache with single-flight and poison-immunity.
+ * Global-scope async value cache with single-flight and poison-immunity.
  *
- * Built for the "compute once per isolate, read on every request" caches
- * (site settings, search-health verification, ...). These must coalesce
- * concurrent cold-isolate reads into one query — but the obvious way to do
- * that, caching the in-flight *promise* on an isolate-global and awaiting it
- * from later requests, is unsafe on workerd: if the request that created the
- * promise is cancelled mid-await (client disconnect, context teardown), its
- * continuation never runs, so the promise neither resolves nor rejects. Every
- * later request that awaits that shared promise then hangs until the isolate
- * is evicted (observed as 524s at the 100s wall, near-zero CPU). A `.catch`
- * that clears the cache doesn't help — a cancelled request doesn't reject.
+ * Built for the "compute once for the lifetime of the JS global scope, read
+ * on every request" caches (site settings, search-health verification, ...).
+ * That global scope is the process on Node and the isolate on Cloudflare
+ * Workers — this helper is platform-neutral; the hazard it defends against is
+ * specific to workerd but the cache itself is not.
+ *
+ * These caches must coalesce concurrent cold reads into one query — but the
+ * obvious way to do that, caching the in-flight *promise* on a global and
+ * awaiting it from later requests, is unsafe on workerd: if the request that
+ * created the promise is cancelled mid-await (client disconnect, context
+ * teardown), its continuation never runs, so the promise neither resolves nor
+ * rejects. Every later request that awaits that shared promise then hangs
+ * until the isolate is evicted (observed as 524s at the 100s wall, near-zero
+ * CPU). A `.catch`/`.finally` that clears the cache doesn't help — a cancelled
+ * request settles neither way.
  *
  * This cache stores the resolved *value* (not a promise) and coalesces via
  * `initWithLock`: one request becomes the owner and runs `fetch`, everyone
@@ -27,7 +32,7 @@
 
 import { createInitLock, type InitLock, initWithLock } from "./init-lock.js";
 
-export interface IsolateCache<T> {
+export interface SingleFlightCache<T> {
 	/** Last resolved value, valid only when `hasValue` is true. */
 	value: T | null;
 	/**
@@ -36,7 +41,7 @@ export interface IsolateCache<T> {
 	 * undefined" from "never fetched").
 	 */
 	hasValue: boolean;
-	/** Invalidation counter; bumped by `invalidateIsolateCache`. */
+	/** Invalidation counter; bumped by `invalidateSingleFlightCache`. */
 	version: number;
 	/** The `version` the cached value was fetched at. */
 	valueVersion: number;
@@ -44,16 +49,16 @@ export interface IsolateCache<T> {
 	lock: InitLock;
 }
 
-export function createIsolateCache<T>(): IsolateCache<T> {
+export function createSingleFlightCache<T>(): SingleFlightCache<T> {
 	return { value: null, hasValue: false, version: 0, valueVersion: -1, lock: createInitLock() };
 }
 
 /**
- * Force the next `isolateCachedAsync` call to refetch. An in-flight owner
+ * Force the next `singleFlightCached` call to refetch. An in-flight owner
  * fetched at the old version will not publish into the new version, so its
  * result is ignored by subsequent reads.
  */
-export function invalidateIsolateCache(cache: IsolateCache<unknown>): void {
+export function invalidateSingleFlightCache(cache: SingleFlightCache<unknown>): void {
 	cache.version++;
 	cache.hasValue = false;
 	cache.value = null;
@@ -75,7 +80,7 @@ export function invalidateIsolateCache(cache: IsolateCache<unknown>): void {
  */
 const RECLAIM_HEADROOM_MS = 5_000;
 
-export interface IsolateCachedOptions {
+export interface SingleFlightCachedOptions {
 	/**
 	 * Hand the in-flight fetch to the host's lifetime extender (waitUntil via
 	 * `after()`), so a cancelled originating request still drives it to
@@ -105,7 +110,7 @@ interface Box<T> {
 function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
 	return new Promise<T>((resolve, reject) => {
 		const timer = setTimeout(() => {
-			reject(new Error(`isolateCachedAsync: owner fetch exceeded ${ms}ms`));
+			reject(new Error(`singleFlightCached: owner fetch exceeded ${ms}ms`));
 		}, ms);
 		// Settle from the underlying promise (whichever wins the race with the
 		// timer), and always clear the timer so a resolved fetch doesn't leave
@@ -121,10 +126,10 @@ function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  * single-flight lock on a miss. Concurrent callers coalesce onto one fetch;
  * a cancelled owner cannot poison later callers (see file header).
  */
-export function isolateCachedAsync<T>(
-	cache: IsolateCache<T>,
+export function singleFlightCached<T>(
+	cache: SingleFlightCache<T>,
 	fetch: () => Promise<T>,
-	options: IsolateCachedOptions = {},
+	options: SingleFlightCachedOptions = {},
 ): Promise<T> {
 	// Capture the version once: a value published at this version satisfies
 	// this call; an invalidation that lands mid-fetch makes the published

package/src/virtual-modules.d.ts

@@ -65,6 +65,17 @@ declare module "virtual:emdash/storage" {
 	export const createStorage: ((config: Record<string, unknown>) => Storage) | undefined;
 }
 
+declare module "virtual:emdash/object-cache" {
+	import type {
+		CreateObjectCacheBackendFn,
+		ObjectCacheRuntimeConfig,
+	} from "./object-cache/types.js";
+
+	// Can be undefined if no object cache is configured.
+	export const createObjectCache: CreateObjectCacheBackendFn | undefined;
+	export const objectCacheConfig: ObjectCacheRuntimeConfig | undefined;
+}
+
 declare module "virtual:emdash/auth" {
 	import type { AuthResult } from "./auth/types.js";