@tetherto/dev-websites-core 0.3.4 → 0.3.6

package/README.md

@@ -2,22 +2,24 @@
 
 Shared CMS, SEO, i18n, utils, UI, and analytics primitives for WDK / QVAC / PEAR / MDK websites.
 
-| Import | Contents |
-| --- | --- |
-| `@tetherto/dev-websites-core/cms` | Payload `buildCmsConfig`, stock collections, access, Lexical, media I/O |
-| `@tetherto/dev-websites-core/cms/google-oauth` | Google admin login handlers (`google-auth-library` peer) |
-| `@tetherto/dev-websites-core/seo` | `createMetadataFactory`, `getSiteUrl`, `getOgBackgroundDataUrl` |
-| `@tetherto/dev-websites-core/i18n` | `Languages` / `LanguageLabel` |
-| `@tetherto/dev-websites-core/utils` | `createLogger`, `toPlainValue`, `stripShikiPreBackground` |
-| `@tetherto/dev-websites-core/analytics` | `GtmLoader`, `createTrackedLink` (optional `@next/third-parties` peer) |
-| `@tetherto/dev-websites-core/ui` | UI primitives (`Button`, `Dialog`, `Pagination`, `Tooltip`, …) + `cn` |
-| `@tetherto/dev-websites-core/ui/google-oauth` | Payload `GoogleOAuthButton` (Tailwind classes; source `dist` from Payload CSS) |
-| `@tetherto/dev-websites-core/ui/a11y` | `focusRingClassName`, `VisuallyHidden` |
-| `@tetherto/dev-websites-core/ui/carousel` | `Carousel` (+ optional `embla-carousel-react` peer) |
-| `@tetherto/dev-websites-core/ui/theme.css` | One-shot: tokens + Tailwind v4 `@theme` preset |
-| `@tetherto/dev-websites-core/ui/theme/tokens.css` | CSS variables (HSL channels) |
-| `@tetherto/dev-websites-core/ui/theme/preset.css` | Tailwind v4 `@theme` map |
-| `@tetherto/dev-websites-core/ui/theme/preset` | JS Tailwind preset for `tailwind.config.ts` |
+| Import                                            | Contents                                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `@tetherto/dev-websites-core/cms`                 | Payload `buildCmsConfig`, stock collections, access, Lexical, media I/O        |
+| `@tetherto/dev-websites-core/cache`               | Mongo `cacheHandler` factory plus Payload revalidation helpers                 |
+| `@tetherto/dev-websites-core/cache/handler`       | Default Next `cacheHandler` (reads `MONGODB_URI`)                              |
+| `@tetherto/dev-websites-core/cms/google-oauth`    | Google admin login handlers (`google-auth-library` peer)                       |
+| `@tetherto/dev-websites-core/seo`                 | `createMetadataFactory`, `getSiteUrl`, `getOgBackgroundDataUrl`                |
+| `@tetherto/dev-websites-core/i18n`                | `Languages` / `LanguageLabel`                                                  |
+| `@tetherto/dev-websites-core/utils`               | `createLogger`, `toPlainValue`, `stripShikiPreBackground`                      |
+| `@tetherto/dev-websites-core/analytics`           | `GtmLoader`, `createTrackedLink` (optional `@next/third-parties` peer)         |
+| `@tetherto/dev-websites-core/ui`                  | UI primitives (`Button`, `Dialog`, `Pagination`, `Tooltip`, …) + `cn`          |
+| `@tetherto/dev-websites-core/ui/google-oauth`     | Payload `GoogleOAuthButton` (Tailwind classes; source `dist` from Payload CSS) |
+| `@tetherto/dev-websites-core/ui/a11y`             | `focusRingClassName`, `VisuallyHidden`                                         |
+| `@tetherto/dev-websites-core/ui/carousel`         | `Carousel` (+ optional `embla-carousel-react` peer)                            |
+| `@tetherto/dev-websites-core/ui/theme.css`        | One-shot: tokens + Tailwind v4 `@theme` preset                                 |
+| `@tetherto/dev-websites-core/ui/theme/tokens.css` | CSS variables (HSL channels)                                                   |
+| `@tetherto/dev-websites-core/ui/theme/preset.css` | Tailwind v4 `@theme` map                                                       |
+| `@tetherto/dev-websites-core/ui/theme/preset`     | JS Tailwind preset for `tailwind.config.ts`                                    |
 
 ### Install
 
@@ -160,7 +162,7 @@ export default {
   theme: {
     extend: {
       colors: {
-        accent: { DEFAULT: 'hsl(var(--color-text-action) / <alpha-value>)', /* … */ },
+        accent: { DEFAULT: 'hsl(var(--color-text-action) / <alpha-value>)' /* … */ },
         // …
       },
     },
@@ -206,7 +208,7 @@ Registered by `buildCmsConfig` in this order. Disable or extend any of them via
 
 Changelog stock ships shared fields only; site-specific body / GitHub /
 `relatedBlock` fields go in `overrides.fields`. Revalidation hooks go in
-`overrides.hooks` (site-owned, e.g. `src/lib/cache`) — hook arrays are **appended**
+`overrides.hooks` (from `@tetherto/dev-websites-core/cache`) — hook arrays are **appended**
 to stock hooks, not replaced.
 
 Draft collections enable Payload `schedulePublish`. `buildCmsConfig` starts
@@ -214,6 +216,52 @@ Draft collections enable Payload `schedulePublish`. `buildCmsConfig` starts
 process (`next start` / Docker). Override or disable via `payload.jobs`. This
 is not for serverless hosts.
 
+### Cache handler
+
+`@tetherto/dev-websites-core/cache/handler` backs Next's ISR / route / fetch
+cache with Mongo so every pod of a deployment shares one cache instead of a
+per-instance filesystem. It reads `MONGODB_URI`, keeps one client (reused
+across dev reloads), and exports the class Next constructs with `new Handler(ctx)`.
+
+```ts
+// next.config.ts
+cacheHandler: require.resolve('@tetherto/dev-websites-core/cache/handler'),
+cacheMaxMemorySize: 0,
+outputFileTracingIncludes: {
+  '/*': ['./node_modules/@tetherto/dev-websites-core/dist/cache/**/*'],
+},
+```
+
+`createMongoCacheHandler({ clientPromise })` is the same class for a site that
+already owns a client. Any object matching `MongoCacheClient` works (a real
+`MongoClient` is assignable).
+
+`/cache` also exports the Payload revalidation helpers
+(`safeRevalidatePath`, `safeRevalidateTag`, `shouldSkipRevalidate`,
+`createPublishedSlugRevalidateHooks`, `createAlwaysRevalidateHooks`,
+`createBlogRevalidators`, `createChangelogRevalidators`). Import those from
+`@tetherto/dev-websites-core/cache` — not from the handler entry, which
+connects to Mongo on load.
+
+Defaults: database `next_cache`, collection `fetch_cache`, 7-day TTL refreshed
+on every write, page keys scoped by `.next/BUILD_ID`. Override with `dbName`,
+`collectionName`, `entryTtlSeconds`, `buildId`.
+
+Behaviour worth knowing:
+
+- `get()` returns rows of any age so Next can serve stale while it revalidates.
+  Expiry is Next's decision, not the handler's.
+- Page and route keys are prefixed with the build id, because rendered HTML
+  embeds chunk filenames that 404 after a deploy. Fetch keys are content
+  hashes and stay shared across builds.
+- Non-2xx page/route responses are never written, and poisoned rows from
+  earlier writes are deleted on read (`shouldSkipCacheWrite` is exported).
+  Without this, a scanner hitting unknown ISR slugs rewrites a 404 row on
+  every request.
+- Page tags fall back to the `x-next-cache-tags` header, since Next only passes
+  `ctx.tags` for fetch entries — without it `revalidateTag` cannot purge
+  rendered HTML.
+
 ### Peer dependencies
 
 CMS / Next (required for `/cms` consumers):
@@ -230,17 +278,18 @@ UI (required for `/ui` consumers):
 Read from `process.env` at runtime by the package — **set them in the consuming
 site's environment** (`.env` / hosting / CI); `@tetherto/dev-websites-core` never defines them.
 
-| Variable                                      | Used by                                           | Notes                                                                                          |
-| --------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `AWS_S3_BUCKET`                               | `media`, `createS3MediaPlugin`, `readMediaBuffer` | When set, media reads/writes go to S3; otherwise disk (`<cwd>/media`).                         |
-| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | S3 access                                         | Optional; falls back to the default AWS credential chain.                                      |
-| `AWS_S3_REGION`                               | S3 access                                         | Defaults to `us-east-1`.                                                                       |
+| Variable                                      | Used by                                           | Notes                                                                                           |
+| --------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `AWS_S3_BUCKET`                               | `media`, `createS3MediaPlugin`, `readMediaBuffer` | When set, media reads/writes go to S3; otherwise disk (`<cwd>/media`).                          |
+| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | S3 access                                         | Optional; falls back to the default AWS credential chain.                                       |
+| `AWS_S3_REGION`                               | S3 access                                         | Defaults to `us-east-1`.                                                                        |
 | `AWS_S3_ENDPOINT`                             | S3 access                                         | Optional custom endpoint (S3-compatible stores on QVAC / PEAR). Omit on WDK for default AWS S3. |
-| `AWS_S3_FORCE_PATH_STYLE`                     | S3 access                                         | Set to `true` when the custom endpoint requires path-style addressing.                         |
-| `NEXT_PUBLIC_SITE_URL`                        | `getSiteUrl`                                      | Public origin; trailing slash trimmed. Warns in production if this and `VERCEL_URL` are unset. |
-| `VERCEL_URL`                                  | `getSiteUrl`                                      | Fallback origin on Vercel when `NEXT_PUBLIC_SITE_URL` is unset.                                |
-| `LOG_LEVEL`                                   | `createLogger`                                    | `debug` \| `info` \| `warn` \| `error`. Defaults to `info` in production, `debug` otherwise.   |
-| `NEXT_PHASE`                                  | `requireEnvAtRuntime`                             | Build phases skip the required-env check (no DB connection).                                   |
+| `AWS_S3_FORCE_PATH_STYLE`                     | S3 access                                         | Set to `true` when the custom endpoint requires path-style addressing.                          |
+| `NEXT_PUBLIC_SITE_URL`                        | `getSiteUrl`                                      | Public origin; trailing slash trimmed. Warns in production if this and `VERCEL_URL` are unset.  |
+| `VERCEL_URL`                                  | `getSiteUrl`                                      | Fallback origin on Vercel when `NEXT_PUBLIC_SITE_URL` is unset.                                 |
+| `LOG_LEVEL`                                   | `createLogger`                                    | `debug` \| `info` \| `warn` \| `error`. Defaults to `info` in production, `debug` otherwise.    |
+| `MONGODB_URI`                                 | `cache/handler`                                   | Required when the default cache handler is loaded.                                              |
+| `NEXT_PHASE`                                  | `requireEnvAtRuntime`                             | Build phases skip the required-env check (no DB connection).                                    |
 
 Hard-required vars (e.g. `PAYLOAD_SECRET`, `MONGODB_URI`) should be read via
 `requireEnvAtRuntime(name)` — it logs and throws at runtime when the var is

package/dist/cache/handler.d.mts

@@ -0,0 +1,51 @@
+//#region src/cache/types.d.ts
+/**
+ * A cache entry as Next hands it to `set()`. Only the fields this handler reads
+ * are named; `kind` is `'APP_PAGE'`, `'APP_ROUTE'`, `'PAGES'`, `'FETCH'`, or
+ * `'IMAGE'`, and the rest of the payload is stored verbatim.
+ */
+type CachedValue = {
+  kind?: string;
+  status?: number;
+  html?: string;
+  headers?: Record<string, string | undefined>;
+  /** Stored as a plain object; Next iterates it as a Map, so `get()` rebuilds one. */
+  segmentData?: Record<string, unknown> | Map<string, unknown>;
+  [key: string]: unknown;
+};
+type CachedEntry = {
+  lastModified?: number;
+  value: CachedValue | null;
+};
+/** The `ctx` Next passes to `set()`; only `tags` is meaningful here. */
+type CacheSetContext = {
+  tags?: string[];
+};
+//#endregion
+//#region src/cache/createMongoCacheHandler.d.ts
+type MongoCacheHandler = {
+  get(key: string): Promise<CachedEntry | null>;
+  set(key: string, value: CachedValue | null, ctx?: CacheSetContext): Promise<void>;
+  delete(key: string): Promise<void>;
+  resetRequestCache(): void;
+  revalidateTag(tags: string | string[], durations?: unknown): Promise<void>;
+};
+/**
+ * Next instantiates the configured handler with `new Handler(ctx)`, so the
+ * factory returns a class rather than an instance.
+ */
+type MongoCacheHandlerConstructor = new (ctx?: unknown) => MongoCacheHandler;
+//#endregion
+//#region src/cache/handler.d.ts
+/**
+ * Default Next.js `cacheHandler`. Point `cacheHandler` in `next.config` at
+ * `@tetherto/dev-websites-core/cache/handler`. Reads `MONGODB_URI` itself so
+ * sites do not ship their own handler or Mongo client.
+ *
+ * Kept off the `/cache` barrel: importing the revalidation helpers must not
+ * open a database connection.
+ */
+declare const _default: MongoCacheHandlerConstructor;
+//#endregion
+export { _default as default };
+//# sourceMappingURL=handler.d.mts.map

package/dist/cache/handler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.mts","names":[],"sources":["../../src/cache/types.ts","../../src/cache/createMongoCacheHandler.ts","../../src/cache/handler.ts"],"mappings":";;;;;;KAgCY;EACV;EACA;EACA;EACA,UAAU;;EAEV,cAAc,0BAA0B;GACvC;;KAWS;EACV;EACA,OAAO;;;KAIG;EACV;;;;KCtBU;EACV,IAAI,cAAc,QAAQ;EAC1B,IAAI,aAAa,OAAO,oBAAoB,MAAM,kBAAkB;EACpE,OAAO,cAAc;EACrB;EACA,cAAc,yBAAyB,sBAAsB;;;;;;KAOnD,oCAAoC,kBAAkB"}

package/dist/cache/handler.mjs

@@ -0,0 +1,178 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { MongoClient } from "mongodb";
+//#region src/cache/shouldSkipCacheWrite.ts
+/**
+* ISR pages with `dynamicParams = true` still render for unknown paths, call
+* `notFound()`, and Next then asks the handler to persist the 404. Scanners
+* hitting junk URLs rewrite that row on every request and bloat the cache
+* collection and the Mongo oplog, so non-success page/route responses are
+* never stored.
+*
+* `FETCH` entries are unaffected: Next nests their upstream status under
+* `value.data.status`, not the top-level `status` read here.
+*/
+function shouldSkipCacheWrite(value) {
+	if (!value || typeof value !== "object") return false;
+	const status = value.status;
+	if (typeof status === "number" && (status < 200 || status >= 400)) return true;
+	if (typeof value.html === "string" && value.html.includes("id=\"__next_error__\"")) return true;
+	return false;
+}
+//#endregion
+//#region src/cache/createMongoCacheHandler.ts
+const DEFAULT_DB_NAME = "next_cache";
+const DEFAULT_COLLECTION_NAME = "fetch_cache";
+/**
+* `get()` deliberately returns rows of any age so Next can serve them stale
+* while it revalidates, which means nothing expires on its own. Mongo drops a
+* row this long after its last write; anything still in use is rewritten by
+* revalidation far sooner, so only paths nobody requests anymore fall out.
+*/
+const DEFAULT_ENTRY_TTL_SECONDS = 604800;
+function readBuildId() {
+	try {
+		return readFileSync(path.join(process.cwd(), ".next", "BUILD_ID"), "utf8").trim();
+	} catch {
+		return "development";
+	}
+}
+/**
+* Next only passes `ctx.tags` for fetch entries. Page and route entries carry
+* theirs — including the `_N_T_<path>` tag behind `revalidatePath` — in the
+* response headers, so without this fallback `revalidateTag` can never purge
+* rendered HTML and CMS edits wait out the route's full revalidate window.
+*/
+function resolveTags(value, ctx) {
+	if (ctx?.tags?.length) return ctx.tags;
+	const header = value?.headers?.["x-next-cache-tags"];
+	return typeof header === "string" ? header.split(",").filter(Boolean) : [];
+}
+/**
+* Mongo-backed `cacheHandler` for Next's ISR / route / fetch cache, so every
+* instance of a deployment shares one cache instead of a per-pod filesystem.
+*
+* Sites normally point `cacheHandler` at `@tetherto/dev-websites-core/cache/handler`,
+* which builds the client from `MONGODB_URI`. Use this factory when the site
+* already owns a client and wants to pass it in.
+*
+* Wire it with `cacheMaxMemorySize: 0`, and include
+* `node_modules/@tetherto/dev-websites-core/dist/cache` in
+* `outputFileTracingIncludes` so the standalone server can load the handler.
+*/
+function createMongoCacheHandler(options) {
+	const { clientPromise, dbName = DEFAULT_DB_NAME, collectionName = DEFAULT_COLLECTION_NAME, entryTtlSeconds = DEFAULT_ENTRY_TTL_SECONDS } = options;
+	/**
+	* Rendered HTML embeds the chunk filenames of the build that produced it, so
+	* an entry left by a previous build loads but never hydrates — its chunks are
+	* gone (404). Page keys are therefore scoped per build, while instances of
+	* the same build keep sharing them.
+	*
+	* During `next build` `.next/BUILD_ID` does not exist yet, which is safe
+	* because Next writes prerenders to disk and never calls `set()` for page
+	* entries during the build.
+	*/
+	const buildId = options.buildId ?? readBuildId();
+	/**
+	* Page and route entries are keyed by pathname; fetch entries are keyed by a
+	* content hash and stay shared across builds, so upstream data survives a
+	* deploy.
+	*/
+	const scopeKey = (key) => key.startsWith("/") ? `${buildId}${key}` : key;
+	let indexPromise;
+	const getCollection = async () => {
+		const collection = (await clientPromise).db(dbName).collection(collectionName);
+		indexPromise ??= Promise.all([
+			collection.createIndex({ key: 1 }, { unique: true }),
+			collection.createIndex({ tags: 1 }),
+			collection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 })
+		]).catch(() => {});
+		await indexPromise;
+		return collection;
+	};
+	return class MongoCacheHandlerImpl {
+		/**
+		* Returns the entry whatever its age. Next compares `lastModified` against
+		* the route's own revalidate window and decides itself whether to serve it
+		* as fresh, serve it stale while refreshing in the background, or
+		* re-render. Dropping stale rows here turns every expiry into a blocking
+		* render.
+		*/
+		async get(key) {
+			const collection = await getCollection();
+			const scoped = scopeKey(key);
+			const entry = await collection.findOne({ key: scoped });
+			if (!entry) return null;
+			if (shouldSkipCacheWrite(entry.value)) {
+				await collection.deleteOne({ key: scoped });
+				return null;
+			}
+			const value = entry.value ?? null;
+			const segmentData = value?.segmentData;
+			return {
+				lastModified: entry.lastModified,
+				value: segmentData && !(segmentData instanceof Map) ? {
+					...value,
+					segmentData: new Map(Object.entries(segmentData))
+				} : value
+			};
+		}
+		async set(key, value, ctx) {
+			if (shouldSkipCacheWrite(value)) return;
+			const collection = await getCollection();
+			const scoped = scopeKey(key);
+			const now = Date.now();
+			await collection.updateOne({ key: scoped }, { $set: {
+				key: scoped,
+				value,
+				lastModified: now,
+				expiresAt: new Date(now + entryTtlSeconds * 1e3),
+				tags: resolveTags(value, ctx)
+			} }, { upsert: true });
+		}
+		async delete(key) {
+			await (await getCollection()).deleteOne({ key: scopeKey(key) });
+		}
+		resetRequestCache() {}
+		async revalidateTag(tags, _durations) {
+			const list = typeof tags === "string" ? [tags] : tags;
+			if (!list?.length) return;
+			await (await getCollection()).deleteMany({ tags: { $in: list } });
+		}
+	};
+}
+//#endregion
+//#region src/cache/createMongoClient.ts
+const options = { promoteBuffers: true };
+/**
+* One Mongo client for the cache handler. In development the promise lives on
+* `globalThis` so hot reload does not open a new connection on every compile.
+*
+* `promoteBuffers` makes BSON Binary come back as Node `Buffer`, which is what
+* Next stores for route and image cache entries.
+*/
+function createMongoClientPromise() {
+	const uri = process.env.MONGODB_URI;
+	if (!uri) throw new Error("Missing MONGODB_URI");
+	if (process.env.NODE_ENV === "development") {
+		const globalForMongo = globalThis;
+		globalForMongo._mongoClientPromise ??= new MongoClient(uri, options).connect();
+		return globalForMongo._mongoClientPromise;
+	}
+	return new MongoClient(uri, options).connect();
+}
+//#endregion
+//#region src/cache/handler.ts
+/**
+* Default Next.js `cacheHandler`. Point `cacheHandler` in `next.config` at
+* `@tetherto/dev-websites-core/cache/handler`. Reads `MONGODB_URI` itself so
+* sites do not ship their own handler or Mongo client.
+*
+* Kept off the `/cache` barrel: importing the revalidation helpers must not
+* open a database connection.
+*/
+var handler_default = createMongoCacheHandler({ clientPromise: createMongoClientPromise() });
+//#endregion
+export { handler_default as default };
+
+//# sourceMappingURL=handler.mjs.map

package/dist/cache/handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.mjs","names":[],"sources":["../../src/cache/shouldSkipCacheWrite.ts","../../src/cache/createMongoCacheHandler.ts","../../src/cache/createMongoClient.ts","../../src/cache/handler.ts"],"sourcesContent":["import type { CachedValue } from './types.js'\n\n/**\n * ISR pages with `dynamicParams = true` still render for unknown paths, call\n * `notFound()`, and Next then asks the handler to persist the 404. Scanners\n * hitting junk URLs rewrite that row on every request and bloat the cache\n * collection and the Mongo oplog, so non-success page/route responses are\n * never stored.\n *\n * `FETCH` entries are unaffected: Next nests their upstream status under\n * `value.data.status`, not the top-level `status` read here.\n */\nexport function shouldSkipCacheWrite(value: CachedValue | null | undefined): boolean {\n  if (!value || typeof value !== 'object') return false\n\n  const status = value.status\n  if (typeof status === 'number' && (status < 200 || status >= 400)) return true\n\n  if (typeof value.html === 'string' && value.html.includes('id=\"__next_error__\"')) {\n    return true\n  }\n\n  return false\n}\n","import { readFileSync } from 'node:fs'\nimport path from 'node:path'\n\nimport { shouldSkipCacheWrite } from './shouldSkipCacheWrite.js'\n\nimport type {\n  CacheSetContext,\n  CachedEntry,\n  CachedValue,\n  MongoCacheClient,\n  MongoCacheCollection,\n} from './types.js'\n\nconst DEFAULT_DB_NAME = 'next_cache'\nconst DEFAULT_COLLECTION_NAME = 'fetch_cache'\n\n/**\n * `get()` deliberately returns rows of any age so Next can serve them stale\n * while it revalidates, which means nothing expires on its own. Mongo drops a\n * row this long after its last write; anything still in use is rewritten by\n * revalidation far sooner, so only paths nobody requests anymore fall out.\n */\nconst DEFAULT_ENTRY_TTL_SECONDS = 60 * 60 * 24 * 7\n\nexport type MongoCacheHandlerOptions = {\n  /** Connected client, owned by the consuming app so this package needs no driver. */\n  clientPromise: Promise<MongoCacheClient>\n  dbName?: string\n  collectionName?: string\n  /** TTL applied on every write. Defaults to 7 days. */\n  entryTtlSeconds?: number\n  /** Overrides the build id read from `.next/BUILD_ID`. */\n  buildId?: string\n}\n\nexport type MongoCacheHandler = {\n  get(key: string): Promise<CachedEntry | null>\n  set(key: string, value: CachedValue | null, ctx?: CacheSetContext): Promise<void>\n  delete(key: string): Promise<void>\n  resetRequestCache(): void\n  revalidateTag(tags: string | string[], durations?: unknown): Promise<void>\n}\n\n/**\n * Next instantiates the configured handler with `new Handler(ctx)`, so the\n * factory returns a class rather than an instance.\n */\nexport type MongoCacheHandlerConstructor = new (ctx?: unknown) => MongoCacheHandler\n\nfunction readBuildId(): string {\n  try {\n    return readFileSync(path.join(process.cwd(), '.next', 'BUILD_ID'), 'utf8').trim()\n  } catch {\n    return 'development'\n  }\n}\n\n/**\n * Next only passes `ctx.tags` for fetch entries. Page and route entries carry\n * theirs — including the `_N_T_<path>` tag behind `revalidatePath` — in the\n * response headers, so without this fallback `revalidateTag` can never purge\n * rendered HTML and CMS edits wait out the route's full revalidate window.\n */\nfunction resolveTags(value: CachedValue | null | undefined, ctx?: CacheSetContext): string[] {\n  if (ctx?.tags?.length) return ctx.tags\n\n  const header = value?.headers?.['x-next-cache-tags']\n  return typeof header === 'string' ? header.split(',').filter(Boolean) : []\n}\n\n/**\n * Mongo-backed `cacheHandler` for Next's ISR / route / fetch cache, so every\n * instance of a deployment shares one cache instead of a per-pod filesystem.\n *\n * Sites normally point `cacheHandler` at `@tetherto/dev-websites-core/cache/handler`,\n * which builds the client from `MONGODB_URI`. Use this factory when the site\n * already owns a client and wants to pass it in.\n *\n * Wire it with `cacheMaxMemorySize: 0`, and include\n * `node_modules/@tetherto/dev-websites-core/dist/cache` in\n * `outputFileTracingIncludes` so the standalone server can load the handler.\n */\nexport function createMongoCacheHandler(\n  options: MongoCacheHandlerOptions\n): MongoCacheHandlerConstructor {\n  const {\n    clientPromise,\n    dbName = DEFAULT_DB_NAME,\n    collectionName = DEFAULT_COLLECTION_NAME,\n    entryTtlSeconds = DEFAULT_ENTRY_TTL_SECONDS,\n  } = options\n\n  /**\n   * Rendered HTML embeds the chunk filenames of the build that produced it, so\n   * an entry left by a previous build loads but never hydrates — its chunks are\n   * gone (404). Page keys are therefore scoped per build, while instances of\n   * the same build keep sharing them.\n   *\n   * During `next build` `.next/BUILD_ID` does not exist yet, which is safe\n   * because Next writes prerenders to disk and never calls `set()` for page\n   * entries during the build.\n   */\n  const buildId = options.buildId ?? readBuildId()\n\n  /**\n   * Page and route entries are keyed by pathname; fetch entries are keyed by a\n   * content hash and stay shared across builds, so upstream data survives a\n   * deploy.\n   */\n  const scopeKey = (key: string): string => (key.startsWith('/') ? `${buildId}${key}` : key)\n\n  // Next builds a fresh handler per request, so this has to live outside the\n  // class to stay a one-off instead of an extra round-trip on every read.\n  let indexPromise: Promise<unknown> | undefined\n\n  const getCollection = async (): Promise<MongoCacheCollection> => {\n    const client = await clientPromise\n    const collection = client.db(dbName).collection(collectionName)\n\n    indexPromise ??= Promise.all([\n      collection.createIndex({ key: 1 }, { unique: true }),\n      // `revalidateTag` deletes by `{ tags: { $in } }`; without this it COLLSCANs.\n      collection.createIndex({ tags: 1 }),\n      collection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }),\n    ]).catch(() => {})\n    await indexPromise\n\n    return collection\n  }\n\n  return class MongoCacheHandlerImpl implements MongoCacheHandler {\n    /**\n     * Returns the entry whatever its age. Next compares `lastModified` against\n     * the route's own revalidate window and decides itself whether to serve it\n     * as fresh, serve it stale while refreshing in the background, or\n     * re-render. Dropping stale rows here turns every expiry into a blocking\n     * render.\n     */\n    async get(key: string): Promise<CachedEntry | null> {\n      const collection = await getCollection()\n      const scoped = scopeKey(key)\n      const entry = await collection.findOne({ key: scoped })\n      if (!entry) return null\n\n      // Heals rows written before error responses were skipped.\n      if (shouldSkipCacheWrite(entry.value)) {\n        await collection.deleteOne({ key: scoped })\n        return null\n      }\n\n      const value = entry.value ?? null\n      const segmentData = value?.segmentData\n\n      return {\n        lastModified: entry.lastModified,\n        value:\n          segmentData && !(segmentData instanceof Map)\n            ? { ...value, segmentData: new Map(Object.entries(segmentData)) }\n            : value,\n      }\n    }\n\n    async set(key: string, value: CachedValue | null, ctx?: CacheSetContext): Promise<void> {\n      if (shouldSkipCacheWrite(value)) return\n\n      const collection = await getCollection()\n      const scoped = scopeKey(key)\n      const now = Date.now()\n\n      await collection.updateOne(\n        { key: scoped },\n        {\n          $set: {\n            key: scoped,\n            value,\n            lastModified: now,\n            expiresAt: new Date(now + entryTtlSeconds * 1000),\n            tags: resolveTags(value, ctx),\n          },\n        },\n        { upsert: true }\n      )\n    }\n\n    async delete(key: string): Promise<void> {\n      const collection = await getCollection()\n      await collection.deleteOne({ key: scopeKey(key) })\n    }\n\n    resetRequestCache(): void {}\n\n    async revalidateTag(tags: string | string[], _durations?: unknown): Promise<void> {\n      const list = typeof tags === 'string' ? [tags] : tags\n      if (!list?.length) return\n\n      const collection = await getCollection()\n      await collection.deleteMany({ tags: { $in: list } })\n    }\n  }\n}\n","import { MongoClient, type MongoClientOptions } from 'mongodb'\n\nconst options: MongoClientOptions = { promoteBuffers: true }\n\ntype GlobalWithMongo = typeof globalThis & {\n  _mongoClientPromise?: Promise<MongoClient>\n}\n\n/**\n * One Mongo client for the cache handler. In development the promise lives on\n * `globalThis` so hot reload does not open a new connection on every compile.\n *\n * `promoteBuffers` makes BSON Binary come back as Node `Buffer`, which is what\n * Next stores for route and image cache entries.\n */\nexport function createMongoClientPromise(): Promise<MongoClient> {\n  const uri = process.env.MONGODB_URI\n  if (!uri) {\n    throw new Error('Missing MONGODB_URI')\n  }\n\n  if (process.env.NODE_ENV === 'development') {\n    const globalForMongo = globalThis as GlobalWithMongo\n    globalForMongo._mongoClientPromise ??= new MongoClient(uri, options).connect()\n    return globalForMongo._mongoClientPromise\n  }\n\n  return new MongoClient(uri, options).connect()\n}\n","import { createMongoCacheHandler } from './createMongoCacheHandler.js'\nimport { createMongoClientPromise } from './createMongoClient.js'\n\n/**\n * Default Next.js `cacheHandler`. Point `cacheHandler` in `next.config` at\n * `@tetherto/dev-websites-core/cache/handler`. Reads `MONGODB_URI` itself so\n * sites do not ship their own handler or Mongo client.\n *\n * Kept off the `/cache` barrel: importing the revalidation helpers must not\n * open a database connection.\n */\nexport default createMongoCacheHandler({ clientPromise: createMongoClientPromise() })\n"],"mappings":"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"}

package/dist/cache/index.d.mts

@@ -0,0 +1,170 @@
+import { CollectionAfterChangeHook, CollectionAfterDeleteHook, PayloadRequest } from "payload";
+//#region src/cache/types.d.ts
+/**
+ * Structural subset of the `mongodb` driver that the cache handler needs.
+ *
+ * Declaring it here instead of importing from `mongodb` keeps the driver out of
+ * the `/cache` entry, so revalidation helpers can be imported without loading it.
+ * A real `MongoClient` is assignable to `MongoCacheClient`.
+ */
+type MongoCacheClient = {
+  db(name: string): {
+    collection(name: string): MongoCacheCollection;
+  };
+};
+type MongoCacheFilter = Record<string, unknown>;
+type MongoCacheCollection = {
+  findOne(filter: MongoCacheFilter): Promise<MongoCacheRow | null>;
+  updateOne(filter: MongoCacheFilter, update: MongoCacheFilter, options: {
+    upsert: boolean;
+  }): Promise<unknown>;
+  deleteOne(filter: MongoCacheFilter): Promise<unknown>;
+  deleteMany(filter: MongoCacheFilter): Promise<unknown>;
+  createIndex(spec: Record<string, number>, options?: Record<string, unknown>): Promise<unknown>;
+};
+/**
+ * A cache entry as Next hands it to `set()`. Only the fields this handler reads
+ * are named; `kind` is `'APP_PAGE'`, `'APP_ROUTE'`, `'PAGES'`, `'FETCH'`, or
+ * `'IMAGE'`, and the rest of the payload is stored verbatim.
+ */
+type CachedValue = {
+  kind?: string;
+  status?: number;
+  html?: string;
+  headers?: Record<string, string | undefined>;
+  /** Stored as a plain object; Next iterates it as a Map, so `get()` rebuilds one. */
+  segmentData?: Record<string, unknown> | Map<string, unknown>;
+  [key: string]: unknown;
+};
+type MongoCacheRow = {
+  key?: string;
+  lastModified?: number;
+  tags?: string[];
+  value?: CachedValue | null;
+  [key: string]: unknown;
+};
+type CachedEntry = {
+  lastModified?: number;
+  value: CachedValue | null;
+};
+/** The `ctx` Next passes to `set()`; only `tags` is meaningful here. */
+type CacheSetContext = {
+  tags?: string[];
+};
+//#endregion
+//#region src/cache/createMongoCacheHandler.d.ts
+type MongoCacheHandlerOptions = {
+  /** Connected client, owned by the consuming app so this package needs no driver. */
+  clientPromise: Promise<MongoCacheClient>;
+  dbName?: string;
+  collectionName?: string;
+  /** TTL applied on every write. Defaults to 7 days. */
+  entryTtlSeconds?: number;
+  /** Overrides the build id read from `.next/BUILD_ID`. */
+  buildId?: string;
+};
+type MongoCacheHandler = {
+  get(key: string): Promise<CachedEntry | null>;
+  set(key: string, value: CachedValue | null, ctx?: CacheSetContext): Promise<void>;
+  delete(key: string): Promise<void>;
+  resetRequestCache(): void;
+  revalidateTag(tags: string | string[], durations?: unknown): Promise<void>;
+};
+/**
+ * Next instantiates the configured handler with `new Handler(ctx)`, so the
+ * factory returns a class rather than an instance.
+ */
+type MongoCacheHandlerConstructor = new (ctx?: unknown) => MongoCacheHandler;
+/**
+ * Mongo-backed `cacheHandler` for Next's ISR / route / fetch cache, so every
+ * instance of a deployment shares one cache instead of a per-pod filesystem.
+ *
+ * Sites normally point `cacheHandler` at `@tetherto/dev-websites-core/cache/handler`,
+ * which builds the client from `MONGODB_URI`. Use this factory when the site
+ * already owns a client and wants to pass it in.
+ *
+ * Wire it with `cacheMaxMemorySize: 0`, and include
+ * `node_modules/@tetherto/dev-websites-core/dist/cache` in
+ * `outputFileTracingIncludes` so the standalone server can load the handler.
+ */
+declare function createMongoCacheHandler(options: MongoCacheHandlerOptions): MongoCacheHandlerConstructor;
+//#endregion
+//#region src/cache/shouldSkipCacheWrite.d.ts
+/**
+ * ISR pages with `dynamicParams = true` still render for unknown paths, call
+ * `notFound()`, and Next then asks the handler to persist the 404. Scanners
+ * hitting junk URLs rewrite that row on every request and bloat the cache
+ * collection and the Mongo oplog, so non-success page/route responses are
+ * never stored.
+ *
+ * `FETCH` entries are unaffected: Next nests their upstream status under
+ * `value.data.status`, not the top-level `status` read here.
+ */
+declare function shouldSkipCacheWrite(value: CachedValue | null | undefined): boolean;
+//#endregion
+//#region src/cache/shouldSkipRevalidate.d.ts
+/**
+ * Standalone scripts (e.g. seed) pass `context: { disableRevalidate: true }`
+ * through the Payload Local API so collection hooks can skip cache invalidation —
+ * `revalidatePath` throws outside an active Next.js request context.
+ */
+declare function shouldSkipRevalidate(req: PayloadRequest | undefined): boolean;
+//#endregion
+//#region src/cache/safeRevalidatePath.d.ts
+declare function safeRevalidatePath(path: string, type?: 'layout' | 'page'): void;
+declare function safeRevalidateTag(tag: string, profile: 'max'): void;
+//#endregion
+//#region src/cache/createPublishedSlugRevalidateHooks.d.ts
+type PublishedSlugRevalidateHandlers = {
+  onPublishedSlugs: (slugs: Iterable<string>) => void;
+  onPublishedList?: () => void;
+};
+/**
+ * Payload hooks that revalidate when a draft/published doc with a `slug` changes.
+ * Skips when `req.context.disableRevalidate` is set (seeds).
+ */
+declare function createPublishedSlugRevalidateHooks(handlers: PublishedSlugRevalidateHandlers): {
+  afterChange: CollectionAfterChangeHook;
+  afterDelete: CollectionAfterDeleteHook;
+};
+/** Hooks that always call `onChange` (e.g. categories / tags that affect listings). */
+declare function createAlwaysRevalidateHooks(onChange: () => void): {
+  afterChange: CollectionAfterChangeHook;
+  afterDelete: CollectionAfterDeleteHook;
+};
+//#endregion
+//#region src/cache/createPathRevalidators.d.ts
+type BlogRevalidatorPaths = {
+  /** e.g. `(slug, locale) => \`/${locale}/blog/${slug}\`` — concrete URL, no `type` */
+  post: (slug: string, locale: string) => string;
+  /** Route pattern including route groups, e.g. `/[locale]/(marketing)/blog/[slug]` */
+  postDynamic: string;
+  list: string;
+  serverSitemap?: string;
+  sitemap?: string;
+  llms?: string;
+};
+type BlogRevalidators = {
+  revalidatePost: (slugs: Iterable<string>) => void;
+  revalidateList: () => void;
+  revalidateAllSurfaces: () => void;
+};
+declare function createBlogRevalidators(locales: readonly string[], paths: BlogRevalidatorPaths): BlogRevalidators;
+type ChangelogRevalidatorPaths = {
+  detail: (slug: string, locale: string) => string;
+  detailDynamic: string;
+  list: string;
+  rss?: string;
+  serverSitemap?: string;
+  sitemap?: string;
+  llms?: string;
+};
+type ChangelogRevalidators = {
+  revalidateEntry: (slugs: Iterable<string>) => void;
+  revalidateList: () => void;
+  revalidateAllSurfaces: () => void;
+};
+declare function createChangelogRevalidators(locales: readonly string[], paths: ChangelogRevalidatorPaths): ChangelogRevalidators;
+//#endregion
+export { type BlogRevalidatorPaths, type BlogRevalidators, type CacheSetContext, type CachedEntry, type CachedValue, type ChangelogRevalidatorPaths, type ChangelogRevalidators, type MongoCacheClient, type MongoCacheCollection, type MongoCacheFilter, type MongoCacheHandler, type MongoCacheHandlerConstructor, type MongoCacheHandlerOptions, type MongoCacheRow, type PublishedSlugRevalidateHandlers, createAlwaysRevalidateHooks, createBlogRevalidators, createChangelogRevalidators, createMongoCacheHandler, createPublishedSlugRevalidateHooks, safeRevalidatePath, safeRevalidateTag, shouldSkipCacheWrite, shouldSkipRevalidate };
+//# sourceMappingURL=index.d.mts.map

package/dist/cache/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/cache/types.ts","../../src/cache/createMongoCacheHandler.ts","../../src/cache/shouldSkipCacheWrite.ts","../../src/cache/shouldSkipRevalidate.ts","../../src/cache/safeRevalidatePath.ts","../../src/cache/createPublishedSlugRevalidateHooks.ts","../../src/cache/createPathRevalidators.ts"],"mappings":";;;;;;;;;KAOY;EACV,GAAG;IACD,WAAW,eAAe;;;KAIlB,mBAAmB;KAEnB;EACV,QAAQ,QAAQ,mBAAmB,QAAQ;EAC3C,UACE,QAAQ,kBACR,QAAQ,kBACR;IAAW;MACV;EACH,UAAU,QAAQ,mBAAmB;EACrC,WAAW,QAAQ,mBAAmB;EACtC,YAAY,MAAM,wBAAwB,UAAU,0BAA0B;;;;;;;KAQpE;EACV;EACA;EACA;EACA,UAAU;;EAEV,cAAc,0BAA0B;GACvC;;KAGS;EACV;EACA;EACA;EACA,QAAQ;GACP;;KAGS;EACV;EACA,OAAO;;;KAIG;EACV;;;;KCjCU;;EAEV,eAAe,QAAQ;EACvB;EACA;;EAEA;;EAEA;;KAGU;EACV,IAAI,cAAc,QAAQ;EAC1B,IAAI,aAAa,OAAO,oBAAoB,MAAM,kBAAkB;EACpE,OAAO,cAAc;EACrB;EACA,cAAc,yBAAyB,sBAAsB;;;;;;KAOnD,oCAAoC,kBAAkB;;;;;;;;;;;;;iBAmClD,wBACd,SAAS,2BACR;;;;;;;;;;;;;iBCxEa,qBAAqB,OAAO;;;;;;;;iBCL5B,qBAAqB,KAAK;;;iBCsB1B,mBAAmB,cAAc;iBAUjC,kBAAkB,aAAa;;;KCnCnC;EACV,mBAAmB,OAAO;EAC1B;;;;;;iBAOc,mCAAmC,UAAU;EAC3D,aAAa;EACb,aAAa;;;iBA8BC,4BAA4B;EAC1C,aAAa;EACb,aAAa;;;;KC7CH;;EAEV,OAAO,cAAc;;EAErB;EACA;EACA;EACA;EACA;;KAGU;EACV,iBAAiB,OAAO;EACxB;EACA;;iBAGc,uBACd,4BACA,OAAO,uBACN;KA4BS;EACV,SAAS,cAAc;EACvB;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV,kBAAkB,OAAO;EACzB;EACA;;iBAGc,4BACd,4BACA,OAAO,4BACN"}