@karibsen/eponyme 0.2.0 → 0.4.0

package/README.md

@@ -559,6 +559,49 @@ ${entries.map(entry => `  <url><loc>https://example.com${entry.loc}</loc>${entry
 })
 ```
 
+## Caching
+
+Published content is the same for every visitor, so it is cached at three levels. The
+defaults suit a content site and can be tuned or switched off:
+
+```ts
+export default defineNuxtConfig({
+  eponyme: {
+    prismaClient: '~~/server/utils/prisma',
+    cacheSeconds: 5,          // server instance
+    browserCacheSeconds: 30,  // visitor's browser
+    cdnCacheSeconds: 300,     // CDN or edge
+  },
+})
+```
+
+| Option | Who holds the copy | Purgeable |
+|---|---|---|
+| `cacheSeconds` | The server instance, in memory | Yes — cleared on every write |
+| `browserCacheSeconds` | The visitor's browser | **No** |
+| `cdnCacheSeconds` | The CDN | Yes — see below |
+
+`browserCacheSeconds` is what makes a client-side navigation instant: the browser answers
+from its own cache instead of crossing the network. It is also the one window nobody can
+shorten. A visitor holding a copy keeps it until it expires, publication or not, which is
+why the default is deliberately small. Set it to `0` if a publication must be visible
+immediately to everyone; navigation then costs a round trip again.
+
+The CDN window can be long because it can be purged, and `eponyme:entry:published` is the
+place to do it:
+
+```ts
+nitroApp.hooks.hook('eponyme:entry:published', async ({ name, collection }) => {
+  await purgeCdnCache(collection ? `/${collection.name}/${collection.slug}` : `/${name}`)
+})
+```
+
+**Only published content is ever cached.** Drafts, historical versions, `raw=1` reads,
+submissions, the trash, the user list and the session route all answer `no-store`. That is
+enforced by a server middleware that marks every Eponyme route uncacheable, which the few
+public ones override — so a route added later is private until someone decides otherwise,
+rather than public until someone remembers.
+
 ## Forms
 
 Use `form()` for public forms. A form owns a schema, its own routes and its anti-abuse
@@ -668,10 +711,43 @@ Two protections apply to the public submission route:
 - a **body size limit**, 64 KB by default, configurable with `maxBodyBytes`. An oversized
   body is refused with `413` before it is parsed.
 
-A captcha is not part of the module. A public form is a normal POST route, so adding
-Turnstile, hCaptcha or anything else is done in the host application: render the widget
-on the page, send its token, and verify it in your own handler before calling
-`validateEponymeForm()`.
+### Captcha
+
+Set `captcha: true` on the form, then install an adapter — Eponyme defines the contract
+but ships no provider:
+
+```bash
+pnpm add @karibsen/eponyme-captcha
+```
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@karibsen/eponyme', '@karibsen/eponyme-captcha'],
+  eponymeCaptcha: { siteKey: '<your-turnstile-site-key>' },
+})
+```
+
+Render the widget and bind its token; `useEponymeForm` sends it alongside the fields and
+the server verifies it before validating anything:
+
+```vue
+<script setup lang="ts">
+const { captchaToken, requiresCaptcha, submit } = useEponymeForm('contact')
+</script>
+
+<template>
+  <NuxtTurnstile v-if="requiresCaptcha" v-model="captchaToken" />
+</template>
+```
+
+**It fails closed.** Without an adapter, a form declaring `captcha: true` answers `500`
+rather than accepting submissions unprotected. A rejected token answers `422` with a
+`_form` error; the provider's reason stays in the server log, since telling a bot which
+check it failed only helps it.
+
+Writing an adapter for another provider means supplying a `name` and an
+`async verify(token, { ip })` returning `{ success, reason? }`, then pointing the
+`#eponyme/captcha` alias at it.
 
 Rate limiting and file uploads are not implemented yet.
 
@@ -730,7 +806,7 @@ a trash move leaves the entry itself untouched.
 
 ## Current status
 
-Eponyme is at version `0.1.1`. It is ready for controlled projects and production pilots. A few workflows still need hardening before a broad public release:
+Eponyme is at version `0.4.0`. It is ready for controlled projects and production pilots. A few workflows still need hardening before a broad public release:
 
 - Client revision tokens for long-running concurrent edits: the current `updatedAt` check protects overlapping writes within one request, not two editors who loaded the same older revision. A deletion is not guarded by a revision either
 - Retention controls for the trash: entries stay there until someone empties it

package/dist/eponyme.mjs

@@ -31,7 +31,8 @@ function form(options) {
     // Storing a submission has to be an explicit decision, so `custom` is the default.
     submission: { mode: options.submission?.mode ?? "custom" },
     honeypot,
-    maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+    maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+    captcha: options.captcha ?? false
   };
 }
 

package/dist/module.d.mts

@@ -20,6 +20,24 @@ interface ModuleOptions {
         /** Fixed lifetime of an authenticated session. */
         sessionDurationDays?: number;
     };
+    /**
+     * How long a server instance may reuse content it has already read, in seconds.
+     * A save clears what it changed on its own instance, so this only bounds how long
+     * another instance can still serve the previous content. `0` disables the cache.
+     */
+    cacheSeconds?: number;
+    /**
+     * How long a browser may reuse published content, in seconds. This is what makes a
+     * client-side navigation instant, and it is the one window nobody can purge: a visitor
+     * who already holds a copy keeps it until it expires. Keep it short. `0` disables it.
+     */
+    browserCacheSeconds?: number;
+    /**
+     * How long a CDN may reuse published content, in seconds. A CDN can be purged — the
+     * `eponyme:entry:published` hook is the place to do it — so this can be generous.
+     * `0` disables it.
+     */
+    cdnCacheSeconds?: number;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@karibsen/eponyme",
   "configKey": "eponyme",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -15,7 +15,10 @@ const module$1 = defineNuxtModule({
     colorPresets: [],
     auth: {
       sessionDurationDays: 7
-    }
+    },
+    cacheSeconds: 5,
+    browserCacheSeconds: 30,
+    cdnCacheSeconds: 300
   },
   moduleDependencies: {
     "@nuxt/icon": {
@@ -70,6 +73,11 @@ const module$1 = defineNuxtModule({
     nuxt.options.runtimeConfig.eponymeAuth = {
       sessionDurationDays: options.auth?.sessionDurationDays ?? 7
     };
+    nuxt.options.runtimeConfig.eponymeContent = {
+      cacheSeconds: options.cacheSeconds ?? 5,
+      browserCacheSeconds: options.browserCacheSeconds ?? 30,
+      cdnCacheSeconds: options.cdnCacheSeconds ?? 300
+    };
     const preparing = Boolean(nuxt.options._prepare);
     if (!options.prismaClient) {
       if (!preparing) throw new Error(`${pc.red("[Eponyme]")} eponyme.prismaClient is required.`);
@@ -130,6 +138,7 @@ Note that '~/' points at ${nuxt.options.srcDir}, so a server module needs '~~/'.
     nuxt.options.alias["#eponyme/prisma"] = prismaPath;
     const variablesPath = await findPath(resolve(nuxt.options.rootDir, "eponyme.variables.ts"));
     nuxt.options.alias["#eponyme/variables"] = variablesPath ?? resolver.resolve("./runtime/utils/empty-variables");
+    nuxt.options.alias["#eponyme/captcha"] ??= resolver.resolve("./runtime/utils/no-captcha");
     addTypeTemplate({
       filename: "types/eponyme-config.d.ts",
       getContents: () => `declare module '#eponyme/config' {
@@ -140,8 +149,13 @@ declare module '#eponyme/variables' {
   const variables: typeof import(${JSON.stringify(nuxt.options.alias["#eponyme/variables"])})['default']
   export default variables
 }
+declare module '#eponyme/captcha' {
+  const verifier: import('${resolver.resolve("./runtime/types/captcha")}').EponymeCaptchaVerifier
+  export default verifier
+}
 `
     });
+    addServerHandler({ middleware: true, handler: resolver.resolve("./runtime/server/middleware/eponyme-no-store") });
     addServerHandler({ route: "/api/eponyme/**", handler: resolver.resolve("./runtime/server/api/eponyme/[name].get") });
     addServerHandler({ route: "/api/eponyme/**", method: "patch", handler: resolver.resolve("./runtime/server/api/eponyme/[name].patch") });
     addServerHandler({ route: "/api/eponyme-statuses", handler: resolver.resolve("./runtime/server/api/eponyme-statuses.get") });

package/dist/runtime/composables/useEponyme.js

@@ -10,9 +10,10 @@ export function useEponyme(name, options = {}) {
   const saving = ref(false);
   const requestFetch = useRequestFetch();
   const cacheKey = `eponyme:${name}:${version}${options.raw ? ":raw" : ""}`;
+  const fetchCache = version === "published" && !options.raw ? void 0 : "no-store";
   const { data: response, pending: loading, error, refresh: load } = useAsyncData(
     cacheKey,
-    () => requestFetch(`/api/eponyme/${name}`, { query: { version, raw: options.raw ? 1 : void 0 }, cache: "no-store" }),
+    () => requestFetch(`/api/eponyme/${name}`, { query: { version, raw: options.raw ? 1 : void 0 }, cache: fetchCache }),
     { getCachedData: cacheDuringHydrationOnly }
   );
   const data = computed(() => response.value?.data);

package/dist/runtime/composables/useEponymeCollection.js

@@ -15,7 +15,8 @@ export function useEponymeCollection(name, options = {}) {
     // The options belong in the key, otherwise two differently sorted calls to the
     // same collection would share one cache entry.
     `eponyme:collection:public:${name}:${options.take ?? ""}:${options.skip ?? ""}:${options.orderBy ?? ""}:${options.order ?? ""}`,
-    () => requestFetch(`/api/eponyme-collections/${name}`, { query, cache: "no-store" }),
+    // Always the published listing, which is publicly cacheable: the browser cache may answer it.
+    () => requestFetch(`/api/eponyme-collections/${name}`, { query }),
     { getCachedData: cacheDuringHydrationOnly }
   );
   const entries = computed(() => result.data.value?.entries ?? []);
@@ -37,7 +38,11 @@ export function useEponymeCollectionEntry(name, slug, options = {}) {
   const requestFetch = useRequestFetch();
   const result = useAsyncData(
     `eponyme:collection-entry:${name}:${slug}:${version}`,
-    () => requestFetch(`/api/eponyme/${name}/${encodeURIComponent(slug)}`, { query: { version }, cache: "no-store" }),
+    () => requestFetch(`/api/eponyme/${name}/${encodeURIComponent(slug)}`, {
+      query: { version },
+      // A draft or a historical version must never be stored, whatever the server says.
+      cache: version === "published" ? void 0 : "no-store"
+    }),
     { getCachedData: cacheDuringHydrationOnly }
   );
   if (import.meta.client) useEventListener(window, "focus", () => void result.refresh());

package/dist/runtime/composables/useEponymeForm.d.ts

@@ -24,6 +24,10 @@ export interface UseEponymeFormResult<Data extends Record<string, unknown>> {
     submitted: Ref<boolean>;
     /** Name of the trap field to render hidden, or `false` when disabled. */
     honeypot: string | false;
+    /** True when the form declares `captcha: true`; render a widget and fill `captchaToken`. */
+    requiresCaptcha: boolean;
+    /** Bind this to the captcha widget, for example `<NuxtTurnstile v-model="captchaToken" />`. */
+    captchaToken: Ref<string>;
     submit: () => Promise<boolean>;
     reset: () => void;
 }

package/dist/runtime/composables/useEponymeForm.js

@@ -10,12 +10,14 @@ function resolveForm(name) {
   if (!definition) throw new Error(`[Eponyme] Unknown form "${name}". Declare it with form() in eponyme.config.ts.`);
   return definition;
 }
+const CAPTCHA_TOKEN_KEY = "_eponyme_captcha";
 export function useEponymeForm(name, options = {}) {
   const definition = resolveForm(name);
   const requestFetch = useRequestFetch();
   const serverErrors = ref({});
   const pending = ref(false);
   const submitted = ref(false);
+  const captchaToken = ref("");
   const values = ref(createDefaultEponymeData(definition.fields));
   const validation = useEponymeValidation(definition.fields, values, ref({}), { serverErrors });
   const fields = computed(() => Object.entries(definition.fields).map(([fieldName, fieldDefinition]) => ({
@@ -33,6 +35,7 @@ export function useEponymeForm(name, options = {}) {
     values.value = createDefaultEponymeData(definition.fields);
     serverErrors.value = {};
     submitted.value = false;
+    captchaToken.value = "";
     validation.reset();
   }
   async function submit() {
@@ -49,7 +52,9 @@ export function useEponymeForm(name, options = {}) {
           console.warn(`[Eponyme] Form "${name}" is managed, so its onSubmit handler is ignored.`);
         await requestFetch(`/api/eponyme-forms/${name}`, {
           method: "POST",
-          body: values.value
+          // The token travels beside the fields, never as one of them: it is
+          // transport, and the schema only knows about declared fields.
+          body: definition.captcha ? { ...values.value, [CAPTCHA_TOKEN_KEY]: captchaToken.value } : values.value
         });
       }
       submitted.value = true;
@@ -72,6 +77,8 @@ export function useEponymeForm(name, options = {}) {
     pending,
     submitted,
     honeypot: definition.honeypot,
+    requiresCaptcha: definition.captcha,
+    captchaToken,
     submit,
     reset
   };

package/dist/runtime/server/api/eponyme/[name].get.js

@@ -1,6 +1,7 @@
-import { createError, defineEventHandler, getQuery, getRequestURL, setResponseHeader } from "h3";
+import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.js";
+import { setEponymePublicCache } from "../../utils/eponyme-cache.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 function readVersion(raw) {
   if (raw === "draft") return "draft";
@@ -11,12 +12,11 @@ export default defineEventHandler(async (event) => {
   const name = decodeURIComponent(getRequestURL(event).pathname.replace(/^\/api\/eponyme\//, ""));
   const requestedVersion = getQuery(event).version;
   const version = readVersion(requestedVersion);
-  if (version !== "published") {
-    await requireEponymeUser(event);
-    setResponseHeader(event, "Cache-Control", "no-store");
-  }
+  const raw = Boolean(getQuery(event).raw);
+  if (version !== "published") await requireEponymeUser(event);
+  else if (!raw) setEponymePublicCache(event);
   const result = name ? await useEponymeService().getResult(name, version) : void 0;
   if (!result) throw createError({ statusCode: 404, statusMessage: "Eponyme entry not found." });
-  const data = getQuery(event).raw ? result.data : interpolateEponymeContent(result.data);
+  const data = raw ? result.data : interpolateEponymeContent(result.data);
   return requestedVersion ? { ...result, data } : { data };
 });

package/dist/runtime/server/api/eponyme-collections/[path].get.js

@@ -1,6 +1,7 @@
 import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.js";
+import { setEponymePublicCache } from "../../utils/eponyme-cache.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 const MAX_TAKE = 200;
 function readCount(raw, min, max) {
@@ -14,6 +15,7 @@ export default defineEventHandler(async (event) => {
   const query = getQuery(event);
   const version = query.version === "draft" ? "draft" : "published";
   if (version === "draft") await requireEponymeUser(event);
+  else if (!query.raw) setEponymePublicCache(event);
   if (!name) throw createError({ statusCode: 404, statusMessage: "Eponyme collection not found." });
   const service = useEponymeService();
   const orderBy = query.orderBy === void 0 || query.orderBy === "" ? void 0 : String(query.orderBy);

package/dist/runtime/server/api/eponyme-forms/[path].post.js

@@ -1,6 +1,7 @@
 import { createError, defineEventHandler, getRequestHeader, readRawBody, setResponseHeader, setResponseStatus } from "h3";
 import { useEponymeFormService } from "../../services/eponyme-form-service.js";
 import { readEponymeFormRoute } from "../../utils/form-route.js";
+import { CAPTCHA_TOKEN_KEY, isEponymeCaptchaConfigured, verifyEponymeCaptcha } from "../../utils/eponyme-captcha.js";
 import { callEponymeBlockingHook, callEponymeHook } from "../../utils/eponyme-hooks.js";
 export default defineEventHandler(async (event) => {
   const route = readEponymeFormRoute(event);
@@ -26,6 +27,20 @@ export default defineEventHandler(async (event) => {
     setResponseStatus(event, 201);
     return { submitted: true };
   }
+  if (definition.captcha) {
+    if (!isEponymeCaptchaConfigured()) {
+      throw createError({
+        statusCode: 500,
+        statusMessage: `Form "${route.name}" requires a captcha but no adapter is installed. Add one, such as @karibsen/eponyme-captcha.`
+      });
+    }
+    const token = payload && typeof payload === "object" ? payload[CAPTCHA_TOKEN_KEY] : void 0;
+    const result2 = await verifyEponymeCaptcha(event, token);
+    if (!result2.success) {
+      setResponseStatus(event, 422);
+      return { errors: { _form: ["Captcha verification failed. Please try again."] } };
+    }
+  }
   const validated = service.validate(route.name, payload);
   if (validated && "errors" in validated) {
     setResponseStatus(event, 422);

package/dist/runtime/server/api/eponyme-sitemap.get.js

@@ -1,5 +1,7 @@
 import { defineEventHandler } from "h3";
+import { setEponymePublicCache } from "../utils/eponyme-cache.js";
 import { getEponymeSitemapEntries } from "../utils/eponyme-sitemap.js";
-export default defineEventHandler(async () => {
+export default defineEventHandler(async (event) => {
+  setEponymePublicCache(event);
   return { entries: await getEponymeSitemapEntries() };
 });

package/dist/runtime/server/middleware/eponyme-no-store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Every Eponyme route is uncacheable until it says otherwise.
+ *
+ * The routes that may be cached are a short, deliberate list — published content, the
+ * collection listings, the sitemap — and each calls `setEponymePublicCache` to override
+ * this. Everything else carries sessions, drafts, trashed entries, form submissions or
+ * the user list, and none of it may ever be stored by a browser or a CDN.
+ *
+ * Written as a default rather than as a header on each handler so that the dangerous
+ * direction is the one that takes effort: a route added later is private until someone
+ * decides otherwise, instead of public until someone remembers.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, void>;
+export default _default;

package/dist/runtime/server/middleware/eponyme-no-store.js

@@ -0,0 +1,6 @@
+import { defineEventHandler, getRequestURL } from "h3";
+import { setEponymePrivateCache } from "../utils/eponyme-cache.js";
+export default defineEventHandler((event) => {
+  if (!getRequestURL(event).pathname.startsWith("/api/eponyme")) return;
+  setEponymePrivateCache(event);
+});

package/dist/runtime/server/services/eponyme-form-store.d.ts

@@ -1,6 +1,5 @@
 import type { EponymeConfig, EponymeFormDefinitionBase } from '../../types/index.js';
 import { type ValidationErrors } from '../../utils/validate-eponyme-data.js';
-/** Kept here rather than imported, so the store stays free of H3 imports. */
 type DateValue = Date | string;
 export interface EponymeFormSubmission {
     id: string;

package/dist/runtime/server/services/eponyme-form-store.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { getEponymeForms } from "../../utils/get-eponyme-schemas.js";
 import { validateEponymeData } from "../../utils/validate-eponyme-data.js";
+const CAPTCHA_TOKEN_KEY = "_eponyme_captcha";
 const DEFAULT_PER_PAGE = 25;
 const MAX_PER_PAGE = 100;
 export class EponymeFormService {
@@ -36,7 +37,7 @@ export class EponymeFormService {
     if (!payload || typeof payload !== "object" || Array.isArray(payload))
       return { errors: { _form: ["Body must be an object."] } };
     const input = payload;
-    const { [definition.honeypot || ""]: _honeypot, ...rest } = input;
+    const { [definition.honeypot || ""]: _honeypot, [CAPTCHA_TOKEN_KEY]: _captcha, ...rest } = input;
     const unknownKeys = Object.keys(rest).filter((key) => !(key in definition.fields));
     if (unknownKeys.length)
       return { errors: Object.fromEntries(unknownKeys.map((key) => [key, ["Unknown field."]])) };

package/dist/runtime/server/services/eponyme-service.js

@@ -1,8 +1,15 @@
 import eponymeConfig from "#eponyme/config";
 import prisma from "#eponyme/prisma";
+import { useRuntimeConfig } from "nitropack/runtime";
 import { EponymeService } from "./eponyme-store.js";
 export { EponymeService } from "./eponyme-store.js";
-const eponymeService = new EponymeService(eponymeConfig, prisma);
+let eponymeService;
 export function useEponymeService() {
+  if (!eponymeService) {
+    const contentConfig = useRuntimeConfig().eponymeContent;
+    eponymeService = new EponymeService(eponymeConfig, prisma, {
+      cacheSeconds: contentConfig?.cacheSeconds ?? 5
+    });
+  }
   return eponymeService;
 }

package/dist/runtime/server/services/eponyme-store.d.ts

@@ -209,17 +209,51 @@ export declare class EponymeService {
     private readonly client;
     private readonly schemas;
     private readonly collections;
-    constructor(config: EponymeConfig, client: PrismaEponymeClient);
+    /** Entries a read has already persisted the normalized shape for, so it only attempts it once. */
+    private readonly healedByRead;
+    /**
+     * Read-path cache of normalized rows, so a page that reads the same entry from a
+     * singleton, a listing and a layout pays one round trip instead of one per read.
+     * Writers never read from it, so the `updatedAt` they lock on always comes from the
+     * database and a stale key can never turn into a spurious conflict.
+     */
+    private readonly cache;
+    private readonly cacheMs;
+    constructor(config: EponymeConfig, client: PrismaEponymeClient, options?: {
+        cacheSeconds?: number;
+    });
+    private cached;
+    /**
+     * Drops what a write to `name` invalidates: the entry itself, and the listing of the
+     * collection that contains it, whose row set just changed.
+     */
+    private invalidate;
     getSchema(name: string): EponymeSchema | undefined;
     getCollection(name: string): EponymeCollectionDefinitionBase | undefined;
     private getCollectionEntry;
-    /** Reconcile every configured eponyme at application startup. */
+    /** Reconcile every configured eponyme at application startup. This is the one place that heals. */
     syncAll(): Promise<void>;
     private reconcile;
     private createState;
     private normalizeState;
-    /** Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token. */
+    /**
+     * A singleton row is created on first read, but only when it is genuinely missing.
+     * An `upsert` would send a write on every read instead, and each one costs a database
+     * round trip on the critical path of a public page.
+     */
+    private loadSingletonRow;
+    /**
+     * Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token.
+     *
+     * `heal` persists the normalized state when it differs from what is stored. It has to stay on for
+     * writers, because healing moves `updatedAt` and so decides the lock token they are about to compare.
+     *
+     * `cache` is only ever set for published content. Draft reads serve the preview panel, which has to
+     * show a save immediately, and they come from the dashboard rather than from a public page — so
+     * there is nothing to gain by caching them and a stale preview to lose.
+     */
     private loadRow;
+    private readRow;
     private loadState;
     /**
      * Writes a new state only if the row still carries the `updatedAt` we read.
@@ -227,6 +261,12 @@ export declare class EponymeService {
      * instead of silently discarding their changes.
      */
     private writeState;
+    /**
+     * The live rows of a collection, shared by the public listing and the sitemap so both
+     * read them once. The trash and the export deliberately query around it: one wants the
+     * rows this filter excludes, the other must not see a cached view of the content.
+     */
+    private liveCollectionRows;
     get(name: string, version?: EponymeVersionSelector): Promise<Record<string, unknown> | undefined>;
     getResult(name: string, version?: EponymeVersionSelector): Promise<EponymeResult | undefined>;
     /** Content as it was in a given version, for previewing without restoring it. */

package/dist/runtime/server/services/eponyme-store.js

@@ -7,13 +7,44 @@ import { applyPreviewSlug } from "../../utils/preview.js";
 import { validateEponymeData, validateEponymePatch } from "../../utils/validate-eponyme-data.js";
 export const COLLECTION_METADATA_KEYS = ["updatedAt", "publishedAt", "title", "slug"];
 export class EponymeService {
-  constructor(config, client) {
+  constructor(config, client, options = {}) {
     this.client = client;
     this.schemas = getEponymeSchemas(config);
     this.collections = getEponymeCollections(config);
+    this.cacheMs = Math.max(0, options.cacheSeconds ?? 5) * 1e3;
   }
   schemas;
   collections;
+  /** Entries a read has already persisted the normalized shape for, so it only attempts it once. */
+  healedByRead = /* @__PURE__ */ new Set();
+  /**
+   * Read-path cache of normalized rows, so a page that reads the same entry from a
+   * singleton, a listing and a layout pays one round trip instead of one per read.
+   * Writers never read from it, so the `updatedAt` they lock on always comes from the
+   * database and a stale key can never turn into a spurious conflict.
+   */
+  cache = /* @__PURE__ */ new Map();
+  cacheMs;
+  cached(key, load) {
+    if (!this.cacheMs) return load();
+    const hit = this.cache.get(key);
+    if (hit && hit.expires > Date.now()) return hit.value;
+    const pending = load().catch((error) => {
+      this.cache.delete(key);
+      throw error;
+    });
+    this.cache.set(key, { value: pending, expires: Date.now() + this.cacheMs });
+    return pending;
+  }
+  /**
+   * Drops what a write to `name` invalidates: the entry itself, and the listing of the
+   * collection that contains it, whose row set just changed.
+   */
+  invalidate(name) {
+    this.cache.delete(`row:${name}`);
+    const collection = this.getCollectionEntry(name)?.name;
+    if (collection) this.cache.delete(`rows:${collection}`);
+  }
   getSchema(name) {
     return this.schemas[name] ?? this.getCollectionEntry(name)?.definition.fields;
   }
@@ -28,9 +59,9 @@ export class EponymeService {
       if (slug && !slug.includes("/")) return { name: collectionName, slug, definition };
     }
   }
-  /** Reconcile every configured eponyme at application startup. */
+  /** Reconcile every configured eponyme at application startup. This is the one place that heals. */
   async syncAll() {
-    await Promise.all(Object.keys(this.schemas).map((name) => this.loadState(name)));
+    await Promise.all(Object.keys(this.schemas).map((name) => this.loadState(name, { heal: true })));
   }
   reconcile(schema, value, mode) {
     const persisted = value && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -66,20 +97,50 @@ export class EponymeService {
       }
     };
   }
-  /** Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token. */
-  async loadRow(name) {
+  /**
+   * A singleton row is created on first read, but only when it is genuinely missing.
+   * An `upsert` would send a write on every read instead, and each one costs a database
+   * round trip on the critical path of a public page.
+   */
+  async loadSingletonRow(name, schema) {
+    const row = await this.client.eponyme.findUnique({ where: { name } });
+    if (row) return row;
+    try {
+      return await this.client.eponyme.create({ data: { name, data: this.createState(schema) } });
+    } catch (error) {
+      if (isPrismaError(error, "P2002")) return await this.client.eponyme.findUnique({ where: { name } });
+      throw error;
+    }
+  }
+  /**
+   * Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token.
+   *
+   * `heal` persists the normalized state when it differs from what is stored. It has to stay on for
+   * writers, because healing moves `updatedAt` and so decides the lock token they are about to compare.
+   *
+   * `cache` is only ever set for published content. Draft reads serve the preview panel, which has to
+   * show a save immediately, and they come from the dashboard rather than from a public page — so
+   * there is nothing to gain by caching them and a stale preview to lose.
+   */
+  async loadRow(name, { heal = false, cache = false } = {}) {
+    if (!cache || heal) return await this.readRow(name, heal);
+    return await this.cached(`row:${name}`, () => this.readRow(name, false));
+  }
+  async readRow(name, heal) {
     const schema = this.getSchema(name);
     if (!schema) return void 0;
-    const defaults = this.createState(schema);
-    const row = this.getCollectionEntry(name) ? await this.client.eponyme.findUnique({ where: { name } }) : await this.client.eponyme.upsert({ where: { name }, create: { name, data: defaults }, update: {} });
+    const row = this.getCollectionEntry(name) ? await this.client.eponyme.findUnique({ where: { name } }) : await this.loadSingletonRow(name, schema);
     if (!row || row.deletedAt) return void 0;
     const state = this.normalizeState(schema, row.data);
     if (sameData(state, row.data)) return { state, updatedAt: row.updatedAt };
+    if (!heal && this.healedByRead.has(name)) return { state, updatedAt: row.updatedAt };
+    this.healedByRead.add(name);
     const healed = await this.client.eponyme.update({ where: { name }, data: { data: state } });
+    this.invalidate(name);
     return { state, updatedAt: healed.updatedAt ?? row.updatedAt };
   }
-  async loadState(name) {
-    return (await this.loadRow(name))?.state;
+  async loadState(name, options = {}) {
+    return (await this.loadRow(name, options))?.state;
   }
   /**
    * Writes a new state only if the row still carries the `updatedAt` we read.
@@ -88,19 +149,38 @@ export class EponymeService {
    */
   async writeState(name, next, expectedUpdatedAt) {
     const data = next;
-    if (!expectedUpdatedAt) {
-      await this.client.eponyme.update({ where: { name }, data: { data } });
-      return true;
+    try {
+      if (!expectedUpdatedAt) {
+        await this.client.eponyme.update({ where: { name }, data: { data } });
+        return true;
+      }
+      const { count } = await this.client.eponyme.updateMany({ where: { name, updatedAt: expectedUpdatedAt }, data: { data } });
+      return count > 0;
+    } finally {
+      this.invalidate(name);
     }
-    const { count } = await this.client.eponyme.updateMany({ where: { name, updatedAt: expectedUpdatedAt }, data: { data } });
-    return count > 0;
+  }
+  /**
+   * The live rows of a collection, shared by the public listing and the sitemap so both
+   * read them once. The trash and the export deliberately query around it: one wants the
+   * rows this filter excludes, the other must not see a cached view of the content.
+   */
+  async liveCollectionRows(name, cache = false) {
+    const load = () => this.client.eponyme.findMany({
+      where: { name: { startsWith: `${name}/` }, deletedAt: null },
+      orderBy: [
+        { updatedAt: "desc" },
+        { name: "asc" }
+      ]
+    });
+    return cache ? await this.cached(`rows:${name}`, load) : await load();
   }
   async get(name, version = "published") {
     return (await this.getResult(name, version))?.data;
   }
   async getResult(name, version = "published") {
     if (typeof version === "number") return this.getVersionResult(name, version);
-    const state = await this.loadState(name);
+    const state = await this.loadState(name, { cache: version === "published" });
     if (!state) return void 0;
     if (version === "published" && this.getCollectionEntry(name) && !state.__eponyme.publishedAt) return void 0;
     return {
@@ -138,25 +218,20 @@ export class EponymeService {
   async listCollection(name, version = "published", query = {}) {
     const definition = this.collections[name];
     if (!definition) return void 0;
-    const rows = await this.client.eponyme.findMany({
-      where: { name: { startsWith: `${name}/` }, deletedAt: null },
-      orderBy: [
-        { updatedAt: "desc" },
-        { name: "asc" }
-      ]
-    });
-    const entries = await Promise.all(rows.filter((row) => !row.name.slice(name.length + 1).includes("/")).map(async (row) => {
+    const rows = await this.liveCollectionRows(name, version === "published");
+    const entries = rows.flatMap((row) => {
       const slug = row.name.slice(name.length + 1);
-      const result = await this.getResult(row.name, version);
-      return {
+      if (!slug || slug.includes("/")) return [];
+      const state = this.normalizeState(definition.fields, row.data);
+      return [{
         slug,
-        title: String(result?.data[definition.titleField] || slug),
-        data: result?.data ?? {},
-        status: version === "published" ? "published" : result?.status ?? "draft",
-        publishedAt: result?.publishedAt ?? null,
+        title: String(state.__eponyme[version][definition.titleField] || slug),
+        data: state.__eponyme[version],
+        status: version === "published" ? "published" : state.__eponyme.status,
+        publishedAt: state.__eponyme.publishedAt,
         updatedAt: row.updatedAt ? new Date(row.updatedAt).toISOString() : null
-      };
-    }));
+      }];
+    });
     const visible = version === "draft" ? entries : entries.filter((entry) => entry.publishedAt);
     const sorted = query.orderBy ? sortCollectionEntries(visible, query.orderBy, query.order ?? "desc") : visible;
     const skip = Math.max(0, Math.trunc(query.skip ?? 0) || 0);
@@ -181,13 +256,7 @@ export class EponymeService {
       }
       if (!path.includes(":slug"))
         throw new Error(`[Eponyme] previewPaths.${name} must include ":slug" to generate collection sitemap URLs.`);
-      const rows = await this.client.eponyme.findMany({
-        where: { name: { startsWith: `${name}/` }, deletedAt: null },
-        orderBy: [
-          { updatedAt: "desc" },
-          { name: "asc" }
-        ]
-      });
+      const rows = await this.liveCollectionRows(name, true);
       return rows.flatMap((row) => {
         const slug = row.name.slice(name.length + 1);
         if (!slug || slug.includes("/")) return [];
@@ -288,6 +357,7 @@ export class EponymeService {
       if (!options.dryRun) {
         const data = state;
         await this.client.eponyme.upsert({ where: { name: entry.name }, create: { name: entry.name, data }, update: { data } });
+        this.invalidate(entry.name);
         await this.client.eponymeVersion.create({
           data: {
             entryName: entry.name,
@@ -330,6 +400,7 @@ export class EponymeService {
     };
     try {
       await this.client.eponyme.create({ data: { name: entryName, data: state } });
+      this.invalidate(entryName);
     } catch (error) {
       if (isPrismaError(error, "P2002")) return await this.slugTakenError(definition, entryName) ?? { errors: { [definition.slugField]: ["This slug is already in use."] } };
       throw error;
@@ -357,6 +428,7 @@ export class EponymeService {
       where: { name, deletedAt: null },
       data: { deletedAt: /* @__PURE__ */ new Date() }
     });
+    this.invalidate(name);
     return count > 0;
   }
   async restoreCollectionEntry(name) {
@@ -365,6 +437,7 @@ export class EponymeService {
       where: { name, deletedAt: { not: null } },
       data: { deletedAt: null }
     });
+    this.invalidate(name);
     return count > 0;
   }
   /** Definitive: `onDelete: Cascade` takes the entry's whole history with it. */
@@ -374,6 +447,7 @@ export class EponymeService {
     if (!row?.deletedAt) return false;
     try {
       await this.client.eponyme.delete({ where: { name } });
+      this.invalidate(name);
     } catch (error) {
       if (isPrismaError(error, "P2025")) return false;
       throw error;
@@ -410,7 +484,7 @@ export class EponymeService {
   async patch(name, payload, action = "publish", actorId) {
     const schema = this.getSchema(name);
     if (!schema) return void 0;
-    const row = await this.loadRow(name);
+    const row = await this.loadRow(name, { heal: true });
     if (!row) return void 0;
     const { state, updatedAt } = row;
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) return { errors: { _form: ["Body must be an object."] } };
@@ -467,7 +541,7 @@ export class EponymeService {
     if (!schema) return void 0;
     const version = await this.client.eponymeVersion.findUnique({ where: { id: versionId } });
     if (!version || version.entryName !== name) return void 0;
-    const current = await this.loadRow(name);
+    const current = await this.loadRow(name, { heal: true });
     if (!current) return void 0;
     const state = this.normalizeState(schema, version.data);
     if (!await this.writeState(name, state, current.updatedAt)) return { conflict: true };

package/dist/runtime/server/utils/eponyme-cache.d.ts

@@ -0,0 +1,16 @@
+import type { H3Event } from 'h3';
+/**
+ * Published content is identical for every visitor, so both the browser and the CDN may
+ * hold on to it. The two windows are deliberately different:
+ *
+ * - `s-maxage` is the CDN's, and a CDN can be purged — `eponyme:entry:published` is the
+ *   hook to do it from, so this one can afford to be long.
+ * - `max-age` is the browser's, and a browser cache cannot be purged by anyone. Whatever
+ *   it holds is served until it expires, publication or not, which is why it stays short.
+ */
+export declare function setEponymePublicCache(event: H3Event): void;
+/**
+ * Drafts and historical versions are unreleased material. `no-store` rather than
+ * `no-cache`: nothing may keep a copy at all, not even one it promises to revalidate.
+ */
+export declare function setEponymePrivateCache(event: H3Event): void;

package/dist/runtime/server/utils/eponyme-cache.js

@@ -0,0 +1,20 @@
+import { setResponseHeader } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+const STALE_WHILE_REVALIDATE_FACTOR = 12;
+export function setEponymePublicCache(event) {
+  const config = useRuntimeConfig().eponymeContent;
+  const browser = Math.max(0, Math.trunc(config?.browserCacheSeconds ?? 30));
+  const cdn = Math.max(0, Math.trunc(config?.cdnCacheSeconds ?? 300));
+  if (!browser && !cdn) {
+    setResponseHeader(event, "Cache-Control", "no-cache");
+    return;
+  }
+  setResponseHeader(
+    event,
+    "Cache-Control",
+    `public, max-age=${browser}, s-maxage=${cdn}, stale-while-revalidate=${cdn * STALE_WHILE_REVALIDATE_FACTOR}`
+  );
+}
+export function setEponymePrivateCache(event) {
+  setResponseHeader(event, "Cache-Control", "no-store");
+}

package/dist/runtime/server/utils/eponyme-captcha.d.ts

@@ -0,0 +1,6 @@
+import type { H3Event } from 'h3';
+import type { EponymeCaptchaResult, EponymeCaptchaVerifier } from '../../types/captcha.js';
+export declare const CAPTCHA_TOKEN_KEY = "_eponyme_captcha";
+export declare function eponymeCaptchaVerifier(): EponymeCaptchaVerifier;
+export declare function isEponymeCaptchaConfigured(): boolean;
+export declare function verifyEponymeCaptcha(event: H3Event, token: unknown): Promise<EponymeCaptchaResult>;

package/dist/runtime/server/utils/eponyme-captcha.js

@@ -0,0 +1,14 @@
+import { getRequestIP } from "h3";
+import captchaVerifier from "#eponyme/captcha";
+export const CAPTCHA_TOKEN_KEY = "_eponyme_captcha";
+export function eponymeCaptchaVerifier() {
+  return captchaVerifier;
+}
+export function isEponymeCaptchaConfigured() {
+  return eponymeCaptchaVerifier().name !== "none";
+}
+export async function verifyEponymeCaptcha(event, token) {
+  if (typeof token !== "string" || !token.trim())
+    return { success: false, reason: "Missing captcha token." };
+  return eponymeCaptchaVerifier().verify(token, { ip: getRequestIP(event, { xForwardedFor: true }) });
+}

package/dist/runtime/types/captcha.d.ts

@@ -0,0 +1,16 @@
+export interface EponymeCaptchaResult {
+    success: boolean;
+    /** Provider-specific reason, surfaced in server logs rather than to the visitor. */
+    reason?: string;
+}
+/**
+ * Verifies the token a visitor's captcha widget produced. Implemented by an adapter
+ * package such as `@karibsen/eponyme-captcha`; the core ships none, so a project
+ * without an adapter simply has no captcha.
+ */
+export interface EponymeCaptchaVerifier {
+    name: string;
+    verify: (token: string, context: {
+        ip?: string;
+    }) => Promise<EponymeCaptchaResult>;
+}

package/dist/runtime/types/eponyme-config.d.ts

@@ -16,3 +16,10 @@ declare module '#eponyme/variables' {
   const variables: EponymeVariables
   export default variables
 }
+
+declare module '#eponyme/captcha' {
+  import type { EponymeCaptchaVerifier } from './captcha'
+
+  const verifier: EponymeCaptchaVerifier
+  export default verifier
+}

package/dist/runtime/types/eponyme.d.ts

@@ -42,6 +42,8 @@ export interface EponymeFormOptions<T extends EponymeFormSchema = EponymeFormSch
     honeypot?: string | false;
     /** In bytes. */
     maxBodyBytes?: number;
+    /** Requires a valid captcha token. Needs an adapter such as `@karibsen/eponyme-captcha`. */
+    captcha?: boolean;
 }
 export interface EponymeFormDefinitionBase {
     __eponymeForm: true;
@@ -51,6 +53,7 @@ export interface EponymeFormDefinitionBase {
     submission: Required<EponymeFormSubmissionOptions>;
     honeypot: string | false;
     maxBodyBytes: number;
+    captcha: boolean;
 }
 export interface EponymeFormDefinition<T extends EponymeFormSchema = EponymeFormSchema> extends EponymeFormDefinitionBase {
     fields: T;

package/dist/runtime/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './auth.js';
 export * from './eponyme.js';
 export * from './field.js';
+export * from './captcha.js';
 export * from './variables.js';

package/dist/runtime/types/index.js

@@ -1,4 +1,5 @@
 export * from "./auth.js";
 export * from "./eponyme.js";
 export * from "./field.js";
+export * from "./captcha.js";
 export * from "./variables.js";

package/dist/runtime/utils/no-captcha.d.ts

@@ -0,0 +1,7 @@
+import type { EponymeCaptchaVerifier } from '../types/captcha.js';
+/**
+ * Stands in when no adapter is installed. It never claims success, so a form that
+ * requires a captcha refuses submissions rather than silently accepting them all.
+ */
+declare const verifier: EponymeCaptchaVerifier;
+export default verifier;

package/dist/runtime/utils/no-captcha.js

@@ -0,0 +1,5 @@
+const verifier = {
+  name: "none",
+  verify: async () => ({ success: false, reason: "No captcha adapter is installed." })
+};
+export default verifier;

package/dist/runtime/utils/variables.d.ts

@@ -14,5 +14,12 @@ export declare function summariseEponymeVariables(custom?: EponymeVariables): Ar
  * than blanked, so a typo shows up on the page instead of silently deleting text.
  */
 export declare function interpolateEponymeText(text: string, variables: Record<string, string>): string;
-/** Walks strings nested in objects and arrays, leaving every other value alone. */
+/**
+ * Walks strings nested in objects and arrays, leaving every other value alone.
+ *
+ * A branch containing no `{{ name }}` is returned as-is rather than rebuilt, so content
+ * without variables — which is most of it — costs no copy. The result therefore shares
+ * structure with its input and must be treated as read-only, which is already true of
+ * everything the read routes return.
+ */
 export declare function interpolateEponymeValue<T>(value: T, variables: Record<string, string>): T;

package/dist/runtime/utils/variables.js

@@ -42,11 +42,24 @@ export function interpolateEponymeText(text, variables) {
 }
 export function interpolateEponymeValue(value, variables) {
   if (typeof value === "string") return interpolateEponymeText(value, variables);
-  if (Array.isArray(value)) return value.map((item) => interpolateEponymeValue(item, variables));
+  if (Array.isArray(value)) {
+    let changed = false;
+    const next = value.map((item) => {
+      const interpolated = interpolateEponymeValue(item, variables);
+      if (interpolated !== item) changed = true;
+      return interpolated;
+    });
+    return changed ? next : value;
+  }
   if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, nested]) => [key, interpolateEponymeValue(nested, variables)])
-    );
+    let changed = false;
+    const next = {};
+    for (const [key, nested] of Object.entries(value)) {
+      const interpolated = interpolateEponymeValue(nested, variables);
+      if (interpolated !== nested) changed = true;
+      next[key] = interpolated;
+    }
+    return changed ? next : value;
   }
   return value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karibsen/eponyme",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",