@karibsen/eponyme 0.2.0 → 0.3.0

package/README.md

@@ -668,10 +668,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 +763,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.3.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,12 @@ 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;
 }
 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.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -15,7 +15,8 @@ const module$1 = defineNuxtModule({
     colorPresets: [],
     auth: {
       sessionDurationDays: 7
-    }
+    },
+    cacheSeconds: 5
   },
   moduleDependencies: {
     "@nuxt/icon": {
@@ -70,6 +71,9 @@ const module$1 = defineNuxtModule({
     nuxt.options.runtimeConfig.eponymeAuth = {
       sessionDurationDays: options.auth?.sessionDurationDays ?? 7
     };
+    nuxt.options.runtimeConfig.eponymeContent = {
+      cacheSeconds: options.cacheSeconds ?? 5
+    };
     const preparing = Boolean(nuxt.options._prepare);
     if (!options.prismaClient) {
       if (!preparing) throw new Error(`${pc.red("[Eponyme]")} eponyme.prismaClient is required.`);
@@ -130,6 +134,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,6 +145,10 @@ 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({ route: "/api/eponyme/**", handler: resolver.resolve("./runtime/server/api/eponyme/[name].get") });

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-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/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-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.3.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",