emdash 0.21.0 → 0.22.0

package/src/object-cache/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Object cache types
+ *
+ * The object cache is an optional, distributed read-through cache that sits
+ * *beneath* the per-request cache (`requestCached`) and *above* the database.
+ * Query results (content entries, settings, menus, taxonomies) are stored in a
+ * fast key/value store (Cloudflare KV, or an in-isolate memory store for Node)
+ * so repeat reads across requests and isolates skip the database entirely.
+ *
+ * Backends only ever deal in strings — serialization (including `Date`
+ * preservation) is handled by the core read-through layer in `./codec.ts`, so
+ * every backend behaves identically.
+ */
+
+/**
+ * A pluggable object-cache backend.
+ *
+ * Implementations must be safe to call concurrently and should never throw on
+ * cache misses — `get` returns `null` for a miss. A backend that throws (e.g.
+ * a transient KV error) degrades gracefully: the read-through layer treats a
+ * thrown `get` as a miss and a thrown `set` as a no-op, so the database
+ * remains the source of truth.
+ */
+export interface ObjectCacheBackend {
+	/** Return the stored string for `key`, or `null` on a miss. */
+	get(key: string): Promise<string | null>;
+	/**
+	 * Store `value` under `key`.
+	 *
+	 * @param ttlSeconds Optional time-to-live in seconds. Backends that don't
+	 *   support TTLs may ignore it, but distributed backends (KV) should honor
+	 *   it so orphaned, epoch-busted keys are eventually reclaimed.
+	 */
+	set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+	/** Remove `key`. Idempotent — deleting a missing key is not an error. */
+	delete(key: string): Promise<void>;
+}
+
+/**
+ * Serializable descriptor for an object-cache backend.
+ *
+ * Mirrors {@link import("../storage/types.js").StorageDescriptor}: `entrypoint`
+ * is a module specifier resolved at build time that exports a
+ * {@link CreateObjectCacheBackendFn} named `createObjectCache`; `config` is the
+ * plain, serializable runtime config passed to it.
+ */
+export interface ObjectCacheDescriptor {
+	/** Module path exporting a `createObjectCache` function. */
+	entrypoint: string;
+	/** Serializable config passed to `createObjectCache` at runtime. */
+	config: ObjectCacheRuntimeConfig;
+}
+
+/**
+ * Runtime config shared by every backend, plus backend-specific keys.
+ *
+ * The read-through layer reads `defaultTtl`, `revalidate`, and `keyPrefix`;
+ * individual backends read their own keys (e.g. the KV backend reads
+ * `binding`).
+ */
+export interface ObjectCacheRuntimeConfig {
+	/**
+	 * Default time-to-live for cached entries, in seconds.
+	 *
+	 * Invalidation works by epoch comparison, not key deletion: a stale value
+	 * is detected on read (its stored epoch no longer matches) and overwritten
+	 * in place under the same key. The TTL is just a backstop that reclaims
+	 * keys that are never read again.
+	 *
+	 * @default 3600 (1 hour)
+	 */
+	defaultTtl?: number;
+	/**
+	 * How long (milliseconds) an isolate may reuse a cached namespace epoch
+	 * before re-reading it from the backend.
+	 *
+	 * After a write bumps a namespace's epoch, an isolate keeps serving the
+	 * previous epoch's keys until its cached epoch expires after this window. It
+	 * is only part of the cross-isolate staleness: a distributed backend adds its
+	 * own propagation delay (KV's edge cache is eventually consistent, up to
+	 * ~60s), so on KV the effective window is that propagation plus this value.
+	 * Only anonymous visitors are affected — preview and edit requests bypass the
+	 * cache.
+	 *
+	 * Set to `0` to re-read the epoch on every query (strongest freshness, more
+	 * backend reads).
+	 *
+	 * @default 1000
+	 */
+	revalidate?: number;
+	/**
+	 * Prefix applied to every cache key. Lets multiple EmDash sites share one
+	 * KV namespace without colliding.
+	 *
+	 * @default "em"
+	 */
+	keyPrefix?: string;
+	/**
+	 * Maximum time (milliseconds) to wait for a single backend read before
+	 * treating it as a cache miss and falling back to the database.
+	 *
+	 * Guards against a backend operation that stalls without resolving or
+	 * rejecting (e.g. a cold cross-region KV read, or one queued behind the
+	 * Workers simultaneous-connection limit), which would otherwise hang the
+	 * request. A timed-out read degrades to a miss; the database remains the
+	 * source of truth.
+	 *
+	 * Set to `0` to disable the timeout (not recommended on Cloudflare).
+	 *
+	 * @default 2000
+	 */
+	timeout?: number;
+	/** Backend-specific keys (e.g. the KV binding name). */
+	[key: string]: unknown;
+}
+
+/**
+ * Factory signature exported as `createObjectCache` from a backend entrypoint.
+ *
+ * Each backend accesses its own resources directly: the KV backend imports
+ * bindings from `cloudflare:workers`; the memory backend uses an in-isolate
+ * map.
+ */
+export type CreateObjectCacheBackendFn = (config: ObjectCacheRuntimeConfig) => ObjectCacheBackend;

package/src/plugins/adapt-sandbox-entry.ts

@@ -278,7 +278,11 @@ export function adaptSandboxEntry(
 		};
 	}
 
-	// Build admin config from descriptor
+	// Build admin config from descriptor.
+	// Portable Text blocks and field widgets are declarative (Block Kit), so they
+	// are forwarded for standard/sandboxed plugins just like pages and widgets —
+	// the admin editor consumes them from the manifest. Only the site-side render
+	// component (`componentsEntry`) stays native-only.
 	const admin: PluginAdminConfig = {};
 	if (descriptor.adminPages) {
 		admin.pages = descriptor.adminPages;
@@ -286,6 +290,12 @@ export function adaptSandboxEntry(
 	if (descriptor.adminWidgets) {
 		admin.widgets = descriptor.adminWidgets;
 	}
+	if (descriptor.portableTextBlocks) {
+		admin.portableTextBlocks = descriptor.portableTextBlocks;
+	}
+	if (descriptor.fieldWidgets) {
+		admin.fieldWidgets = descriptor.fieldWidgets;
+	}
 
 	return {
 		id: pluginId,

package/src/query.ts

@@ -27,6 +27,11 @@
 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 {
+	cachedQuery,
+	contentNamespaces,
+	invalidateSchemaObjectCache,
+} from "./object-cache/index.js";
 import { requestCached } from "./request-cache.js";
 import { getRequestContext } from "./request-context.js";
 import { isMissingTableError } from "./utils/db-errors.js";
@@ -327,13 +332,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 +551,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 +733,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 +842,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 && 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
 		}
-		// Entry not found or not visible in this locale — try next
+		return { entry: null, isPreview: false, cacheHint: {} };
+	};
+
+	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;
 }
 
 /**
@@ -972,9 +1146,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/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 },
 		),
 	);