@cogenta/render 0.1.0

package/dist/build/run-build.d.ts

@@ -0,0 +1,43 @@
+import { type BuildPlan, type PlanBuildInput } from './plan.js';
+import type { BuildRoute } from './requirements.js';
+import type { BuildTarget } from './targets.js';
+/**
+ * Running a planned build.
+ *
+ * The renderer is injected, and it receives **only the route** — never the
+ * target. That is not an oversight: it is what makes "the same content
+ * produces an equivalent result on the three targets" a property of the code
+ * rather than a promise in a document. A renderer that cannot see the target
+ * cannot branch on it, so the only difference between the three targets is
+ * *when* the render runs, never *what* it produces.
+ */
+export type RouteRenderer = (route: BuildRoute) => Promise<string> | string;
+export interface RunBuildInput extends PlanBuildInput {
+    readonly render: RouteRenderer;
+    /**
+     * Pages rendered at once during a prerender.
+     *
+     * A theme reads its content over HTTP (ADR-0016), so a prerender is mostly
+     * waiting on round trips; rendering one page at a time makes a thousand-page
+     * build a thousand sequential waits. Bounded rather than unbounded because
+     * the content API is a plain server and a thousand parallel reads is an
+     * outage, not a build.
+     */
+    readonly concurrency?: number | undefined;
+}
+export interface BuildResult {
+    readonly target: BuildTarget;
+    readonly plan: BuildPlan;
+    /** Paths rendered ahead of time, with their HTML. */
+    readonly pages: ReadonlyMap<string, string>;
+    /** Paths left to be rendered on request. Always empty on the static target. */
+    readonly onDemand: readonly string[];
+    readonly durationMs: number;
+    /**
+     * The HTML a visitor gets for `path`, through this target's production path:
+     * a file for a prerendered route, a render for an on-demand one.
+     */
+    serve(path: string): Promise<string>;
+}
+export declare function runBuild(input: RunBuildInput): Promise<BuildResult>;
+//# sourceMappingURL=run-build.d.ts.map

package/dist/build/run-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-build.d.ts","sourceRoot":"","sources":["../../src/build/run-build.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAa,MAAM,WAAW,CAAA;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C;;;;;;;;;GASG;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;AAE3E,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACrC;AAID,wBAAsB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAkDzE"}

package/dist/build/run-build.js

@@ -0,0 +1,73 @@
+import { CogentaError } from '@cogenta/core';
+import { planBuild } from './plan.js';
+const DEFAULT_CONCURRENCY = 8;
+export async function runBuild(input) {
+    const plan = planBuild(input);
+    const byPath = indexRoutes(input.routes);
+    const started = performance.now();
+    const pages = new Map();
+    const onDemand = [];
+    const toPrerender = [];
+    for (const planned of plan.routes) {
+        const route = byPath.get(planned.path);
+        if (route === undefined)
+            continue;
+        if (planned.mode === 'prerendered')
+            toPrerender.push(route);
+        else
+            onDemand.push(planned.path);
+    }
+    const concurrency = Math.max(1, input.concurrency ?? DEFAULT_CONCURRENCY);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(concurrency, toPrerender.length) }, async () => {
+        while (next < toPrerender.length) {
+            const route = toPrerender[next++];
+            if (route === undefined)
+                return;
+            pages.set(route.path, await input.render(route));
+        }
+    });
+    await Promise.all(workers);
+    const durationMs = performance.now() - started;
+    return {
+        target: plan.target.target,
+        plan,
+        pages,
+        onDemand,
+        durationMs,
+        serve: async (path) => {
+            const prerendered = pages.get(path);
+            if (prerendered !== undefined)
+                return prerendered;
+            const route = byPath.get(path);
+            if (route === undefined) {
+                throw new CogentaError({
+                    code: 'CONTENT_NOT_FOUND',
+                    message: `No route "${path}" in this build.`,
+                    hint: `The build produced ${plan.routes.length} route(s). Check the path, or the query that produced the route list.`,
+                    details: { path, target: plan.target.target },
+                });
+            }
+            return await input.render(route);
+        },
+    };
+}
+function indexRoutes(routes) {
+    const byPath = new Map();
+    for (const route of routes) {
+        if (byPath.has(route.path)) {
+            // Refused rather than resolved: two routes on one path means one of the
+            // two pages silently never ships, which is the class of bug this whole
+            // module exists to prevent.
+            throw new CogentaError({
+                code: 'CONTENT_ROUTE_INVALID',
+                message: `Two routes claim the path "${route.path}".`,
+                hint: 'A path is produced by exactly one route. Check for a duplicate slug, or for two collections routed to the same prefix.',
+                details: { path: route.path },
+            });
+        }
+        byPath.set(route.path, route);
+    }
+    return byPath;
+}
+//# sourceMappingURL=run-build.js.map

package/dist/build/run-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-build.js","sourceRoot":"","sources":["../../src/build/run-build.ts"],"names":[],"mappings":"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"}

package/dist/build/targets.d.ts

@@ -0,0 +1,47 @@
+import type { BlockRuntime } from '@cogenta/blocks';
+/**
+ * The three delivery targets of ADR-0004, as a build parameter.
+ *
+ * One theme codebase, three Astro adapters. The target is chosen at build
+ * time, never branched on inside a theme: a theme that renders differently
+ * "because it is the static build" would make the acceptance criterion — the
+ * same content produces an equivalent result on the three targets — unhold-
+ * able, and would put the delivery profile back into the theme where the two
+ * planes were meant to keep it out.
+ */
+export declare const BUILD_TARGETS: readonly ['static', 'node', 'edge'];
+export type BuildTarget = (typeof BUILD_TARGETS)[number];
+export interface TargetAdapter {
+    /** The Astro adapter this target is normally built with. */
+    readonly recommended: string;
+    readonly alternatives: readonly string[];
+}
+export interface TargetCapability {
+    readonly target: BuildTarget;
+    /** Human-readable, used in refusal messages read by someone tired. */
+    readonly label: string;
+    /** The runtime needs this target can honour (contract D, "Besoins runtime"). */
+    readonly satisfies: readonly BlockRuntime[];
+    /** What `astro.config` must declare as `output` for this target. */
+    readonly astroOutput: 'static' | 'server';
+    /** `null` for static: there is no adapter, there is a directory of files. */
+    readonly adapter: TargetAdapter | null;
+}
+/**
+ * What each target can actually do at request time.
+ *
+ * `static` satisfies `static` and nothing else — that is the whole point of a
+ * static build, and the reason the refusal below exists.
+ *
+ * `node` and `edge` both satisfy the three, because both have a request. The
+ * distinction between them is *where* the code runs, not whether a request
+ * exists: a block that needs the database at request time is served fine by an
+ * edge function calling the content API over HTTP (ADR-0016), which is exactly
+ * why "deploy it as an edge function" is one of the three ways out we offer.
+ */
+export declare const TARGET_CAPABILITIES: Readonly<Record<BuildTarget, TargetCapability>>;
+export declare function isBuildTarget(value: unknown): value is BuildTarget;
+/** Turns whatever the CLI or the configuration passed into a known target. */
+export declare function resolveTarget(target: string): TargetCapability;
+export declare function targetSatisfies(target: TargetCapability, runtime: BlockRuntime): boolean;
+//# sourceMappingURL=targets.d.ts.map

package/dist/build/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../src/build/targets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,YAAI,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAU,CAAA;AAEhE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAA;IAC3C,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAA;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;CACvC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAyB/E,CAAA;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAU9D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAExF"}

package/dist/build/targets.js

@@ -0,0 +1,69 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * The three delivery targets of ADR-0004, as a build parameter.
+ *
+ * One theme codebase, three Astro adapters. The target is chosen at build
+ * time, never branched on inside a theme: a theme that renders differently
+ * "because it is the static build" would make the acceptance criterion — the
+ * same content produces an equivalent result on the three targets — unhold-
+ * able, and would put the delivery profile back into the theme where the two
+ * planes were meant to keep it out.
+ */
+export const BUILD_TARGETS = ['static', 'node', 'edge'];
+/**
+ * What each target can actually do at request time.
+ *
+ * `static` satisfies `static` and nothing else — that is the whole point of a
+ * static build, and the reason the refusal below exists.
+ *
+ * `node` and `edge` both satisfy the three, because both have a request. The
+ * distinction between them is *where* the code runs, not whether a request
+ * exists: a block that needs the database at request time is served fine by an
+ * edge function calling the content API over HTTP (ADR-0016), which is exactly
+ * why "deploy it as an edge function" is one of the three ways out we offer.
+ */
+export const TARGET_CAPABILITIES = {
+    static: {
+        target: 'static',
+        label: 'static (HTML files on a CDN)',
+        satisfies: ['static'],
+        astroOutput: 'static',
+        adapter: null,
+    },
+    node: {
+        target: 'node',
+        label: 'Node SSR (a Node server rendering on request)',
+        satisfies: ['static', 'server', 'edge'],
+        astroOutput: 'server',
+        adapter: { recommended: '@astrojs/node', alternatives: [] },
+    },
+    edge: {
+        target: 'edge',
+        label: 'edge (functions at the CDN border)',
+        satisfies: ['static', 'server', 'edge'],
+        astroOutput: 'server',
+        adapter: {
+            recommended: '@astrojs/cloudflare',
+            alternatives: ['@astrojs/vercel', '@astrojs/netlify'],
+        },
+    },
+};
+export function isBuildTarget(value) {
+    return typeof value === 'string' && BUILD_TARGETS.includes(value);
+}
+/** Turns whatever the CLI or the configuration passed into a known target. */
+export function resolveTarget(target) {
+    if (!isBuildTarget(target)) {
+        throw new CogentaError({
+            code: 'BUILD_TARGET_UNKNOWN',
+            message: `"${target}" is not a build target.`,
+            hint: `Use one of: ${BUILD_TARGETS.join(', ')}.`,
+            details: { target, known: BUILD_TARGETS },
+        });
+    }
+    return TARGET_CAPABILITIES[target];
+}
+export function targetSatisfies(target, runtime) {
+    return target.satisfies.includes(runtime);
+}
+//# sourceMappingURL=targets.js.map

package/dist/build/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../src/build/targets.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAU,CAAA;AAsBhE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAoD;IAClF,MAAM,EAAE;QACN,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,8BAA8B;QACrC,SAAS,EAAE,CAAC,QAAQ,CAAC;QACrB,WAAW,EAAE,QAAQ;QACrB,OAAO,EAAE,IAAI;KACd;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,+CAA+C;QACtD,SAAS,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC;QACvC,WAAW,EAAE,QAAQ;QACrB,OAAO,EAAE,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,EAAE,EAAE;KAC5D;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,oCAAoC;QAC3C,SAAS,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC;QACvC,WAAW,EAAE,QAAQ;QACrB,OAAO,EAAE;YACP,WAAW,EAAE,qBAAqB;YAClC,YAAY,EAAE,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;SACtD;KACF;CACF,CAAA;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC1F,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,IAAI,MAAM,0BAA0B;YAC7C,IAAI,EAAE,eAAe,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAChD,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE;SAC1C,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAA;AACpC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAwB,EAAE,OAAqB;IAC7E,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AAC3C,CAAC"}

package/dist/cache/index.d.ts

@@ -0,0 +1,7 @@
+export type { PageRequest, RenderCache, RenderCacheOptions, RenderResult, } from './page-cache.js';
+export { createRenderCache, pageCacheKey } from './page-cache.js';
+export type { ReadRecorder } from './recorder.js';
+export { createReadRecorder, recordingContentClient, recordingRenderContext } from './recorder.js';
+export type { ContentChange } from './tags.js';
+export { collectionTag, entryTag, mediaTag, normalisePath, pathTag, tagsForChange, tagsForChanges, } from './tags.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,YAAY,GACb,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAClG,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EACL,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,OAAO,EACP,aAAa,EACb,cAAc,GACf,MAAM,WAAW,CAAA"}

package/dist/cache/index.js

@@ -0,0 +1,4 @@
+export { createRenderCache, pageCacheKey } from './page-cache.js';
+export { createReadRecorder, recordingContentClient, recordingRenderContext } from './recorder.js';
+export { collectionTag, entryTag, mediaTag, normalisePath, pathTag, tagsForChange, tagsForChanges, } from './tags.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEjE,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAElG,OAAO,EACL,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,OAAO,EACP,aAAa,EACb,cAAc,GACf,MAAM,WAAW,CAAA"}

package/dist/cache/page-cache.d.ts

@@ -0,0 +1,64 @@
+import { type CacheDriver, CogentaError, type Logger } from '@cogenta/core';
+import { type ReadRecorder } from './recorder.js';
+import { type ContentChange } from './tags.js';
+/**
+ * The render cache: a page in, the content it read out, tags in between.
+ *
+ * It takes a `CacheDriver` and never names one. Memory, file and Redis all
+ * implement `invalidateTags`, so the render cache is correct on all three and
+ * a site that has no Redis loses shared storage, not correctness (rule R1).
+ *
+ * Since ADR-0016 a theme reads over HTTP, so a miss costs a round trip per
+ * read. This cache is what pays that back: a hit costs one `get`.
+ */
+/** What identifies a rendered page. Anything that changes the HTML belongs here. */
+export interface PageRequest {
+    readonly locale: string;
+    readonly url: URL | string;
+    /**
+     * Extra discriminators — active skin, build target, device class. A page
+     * that varies on something absent from here is a page served wrong to half
+     * its readers, so hosts must declare every axis they vary on.
+     */
+    readonly variant?: Readonly<Record<string, string>> | undefined;
+}
+export interface RenderCacheOptions {
+    readonly cache: CacheDriver;
+    readonly logger?: Logger | undefined;
+    /** Seconds. Omitted means "until invalidated", which is the point of tags. */
+    readonly ttl?: number | undefined;
+    /** Key prefix. Bump it to drop every page without touching other cache users. */
+    readonly namespace?: string | undefined;
+    /** Called on every swallowed cache failure. Injected by hosts with alerting. */
+    readonly onError?: ((error: CogentaError) => void) | undefined;
+}
+export interface RenderResult<T> {
+    readonly value: T;
+    /** True when the value came from the cache and nothing was rendered. */
+    readonly cached: boolean;
+    /** Dependencies of the page. Read back from the entry on a hit. */
+    readonly tags: readonly string[];
+    readonly key: string;
+}
+export interface RenderCache {
+    /** The key a request maps to. Exposed so a host can purge one page by hand. */
+    keyFor(request: PageRequest): string;
+    render<T>(request: PageRequest, produce: (recorder: ReadRecorder) => Promise<T>): Promise<RenderResult<T>>;
+    /** Drops one page, whatever its dependencies. */
+    forget(request: PageRequest): Promise<void>;
+    /** Publication, unpublication, deletion. Throws if the cache refuses. */
+    invalidate(changes: ContentChange | readonly ContentChange[]): Promise<void>;
+    invalidateTags(tags: readonly string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function createRenderCache(options: RenderCacheOptions): RenderCache;
+/**
+ * The cache key of a page.
+ *
+ * Built from origin-independent parts — one site is one cache — and from the
+ * search string, because a query parameter that changes the HTML must change
+ * the key. Parameters are sorted so that `?a=1&b=2` and `?b=2&a=1` are one
+ * entry rather than two copies that expire independently.
+ */
+export declare function pageCacheKey(namespace: string, request: PageRequest): string;
+//# sourceMappingURL=page-cache.d.ts.map

package/dist/cache/page-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-cache.d.ts","sourceRoot":"","sources":["../../src/cache/page-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3E,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAA;AACrE,OAAO,EAAE,KAAK,aAAa,EAAiC,MAAM,WAAW,CAAA;AAE7E;;;;;;;;;GASG;AAEH,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;CAChE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CAC/D;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAA;IACpC,MAAM,CAAC,CAAC,EACN,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3B,iDAAiD;IACjD,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,yEAAyE;IACzE,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5E,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAgBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAqF1E;AAmCD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAY5E"}

package/dist/cache/page-cache.js

@@ -0,0 +1,128 @@
+import { CogentaError } from '@cogenta/core';
+import { createReadRecorder } from './recorder.js';
+import { normalisePath, tagsForChanges } from './tags.js';
+const DEFAULT_NAMESPACE = 'render';
+export function createRenderCache(options) {
+    const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+    const logger = options.logger;
+    const cache = options.cache;
+    /**
+     * A cache that throws is worse than no cache: it turns a slow page into a
+     * broken one. Every read and write is therefore swallowed, reported, and the
+     * render carries on as if the cache were empty.
+     *
+     * Invalidation is the deliberate exception, and it is handled outside this
+     * helper: a publish that silently failed to invalidate leaves stale pages up
+     * with nothing to notice it, so the caller must hear about it.
+     */
+    async function attempt(operation, key, run) {
+        try {
+            return await run();
+        }
+        catch (cause) {
+            const error = cacheFailure(operation, key, cause);
+            logger?.warn('render cache unavailable, serving without it', {
+                code: error.code,
+                operation,
+                key,
+            });
+            options.onError?.(error);
+            return undefined;
+        }
+    }
+    function keyFor(request) {
+        return pageCacheKey(namespace, request);
+    }
+    return {
+        keyFor,
+        render: async (request, produce) => {
+            const key = keyFor(request);
+            const hit = await attempt('get', key, () => cache.get(key));
+            if (hit !== undefined && hit !== null) {
+                return { value: hit.value, cached: true, tags: hit.tags, key };
+            }
+            // Outside `attempt`: a failing render is a real failure and must surface.
+            // Only the cache is allowed to fail quietly here.
+            const recorder = createReadRecorder();
+            const value = await produce(recorder);
+            const tags = recorder.tags();
+            await attempt('set', key, () => cache.set(key, { value, tags }, { tags, ...(options.ttl === undefined ? {} : { ttl: options.ttl }) }));
+            return { value, cached: false, tags, key };
+        },
+        forget: async (request) => {
+            const key = keyFor(request);
+            await attempt('delete', key, () => cache.delete(key));
+        },
+        invalidate: async (changes) => {
+            await invalidate(cache, tagsForChanges(asChanges(changes)));
+        },
+        invalidateTags: async (tags) => {
+            await invalidate(cache, tags);
+        },
+        clear: async () => {
+            await attempt('clear', namespace, () => cache.clear());
+        },
+    };
+}
+function isSingleChange(input) {
+    return !Array.isArray(input);
+}
+function asChanges(input) {
+    return isSingleChange(input) ? [input] : input;
+}
+async function invalidate(cache, tags) {
+    if (tags.length === 0)
+        return;
+    try {
+        await cache.invalidateTags(tags);
+    }
+    catch (cause) {
+        throw new CogentaError({
+            code: 'CACHE_FAILED',
+            message: `The render cache could not invalidate ${tags.length} tag(s) after a content change.`,
+            hint: 'Pages that embed this content will keep serving the old version until the cache is reachable again. Check the cache driver, then re-run the invalidation or clear the cache.',
+            cause,
+            details: { tags },
+        });
+    }
+}
+function cacheFailure(operation, key, cause) {
+    return new CogentaError({
+        code: 'CACHE_FAILED',
+        message: `The render cache failed to ${operation} "${key}".`,
+        hint: 'The page was rendered anyway. Check the cache driver — an unreachable cache costs latency, not correctness.',
+        cause,
+        details: { operation, key },
+    });
+}
+/**
+ * The cache key of a page.
+ *
+ * Built from origin-independent parts — one site is one cache — and from the
+ * search string, because a query parameter that changes the HTML must change
+ * the key. Parameters are sorted so that `?a=1&b=2` and `?b=2&a=1` are one
+ * entry rather than two copies that expire independently.
+ */
+export function pageCacheKey(namespace, request) {
+    const url = typeof request.url === 'string' ? parsePath(request.url) : request.url;
+    const search = sortedQuery(url.searchParams);
+    const parts = [namespace, 'page', request.locale, normalisePath(url.pathname) + search];
+    const variant = request.variant;
+    if (variant !== undefined) {
+        const entries = Object.entries(variant).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        for (const [name, value] of entries)
+            parts.push(`${name}=${value}`);
+    }
+    return parts.join('|');
+}
+/** A path, possibly with a query, and possibly a full URL. Base is irrelevant. */
+function parsePath(value) {
+    return new URL(value, 'https://page.invalid');
+}
+function sortedQuery(parameters) {
+    const pairs = [...parameters.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    if (pairs.length === 0)
+        return '';
+    return `?${pairs.map(([name, value]) => `${name}=${value}`).join('&')}`;
+}
+//# sourceMappingURL=page-cache.js.map

package/dist/cache/page-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-cache.js","sourceRoot":"","sources":["../../src/cache/page-cache.ts"],"names":[],"mappings":"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"}

package/dist/cache/recorder.d.ts

@@ -0,0 +1,49 @@
+import type { ContentClient, ResponseDependencies } from '../content/types.js';
+import type { RenderContext } from '../context/types.js';
+/**
+ * Collects, during a render, what the page actually read.
+ *
+ * This is the part that has to be automatic. A theme declaring its own
+ * dependencies is wrong the first time someone adds a `ctx.content.list()` and
+ * forgets to update the declaration — and the symptom is a page serving stale
+ * content for as long as the cache lives, which nobody notices until a reader
+ * complains. Wrapping the two doors to data (`ctx.content` and `ctx.image`)
+ * means the dependency set is a consequence of the render, not a claim about
+ * it.
+ */
+export interface ReadRecorder {
+    /** Tags accumulated so far. A fresh array on each call — never the live set. */
+    tags(): readonly string[];
+    recordEntry(id: string): void;
+    recordCollection(collection: string): void;
+    recordMedia(id: string): void;
+    recordPath(path: string): void;
+}
+/**
+ * Feeds a response's declared dependencies into a recorder.
+ *
+ * This is the other half of what `recordingContentClient` cannot see: server-
+ * side relation expansion inlines an author into an article without the
+ * author's id ever crossing the client as a request of its own, so wrapping
+ * `ContentClient` alone misses it. Wire this into the concrete HTTP client's
+ * `onDependencies` option (see `createContentClient`) and both halves land in
+ * the same set.
+ */
+export declare function recordDependencies(recorder: ReadRecorder, dependencies: ResponseDependencies): void;
+export declare function createReadRecorder(): ReadRecorder;
+/**
+ * A content client that records every read, and changes nothing else.
+ *
+ * Note what `list` records: the **collection**, on top of the entries it
+ * returned. Tagging only the returned entries is the classic mistake — the
+ * front page of a blog would then survive the publication of a new article,
+ * because that article was, by definition, not in the cached page. A list
+ * depends on the shape of the collection, not on the rows it happened to show.
+ */
+export declare function recordingContentClient(client: ContentClient, recorder: ReadRecorder): ContentClient;
+/**
+ * The render context a page is given while its dependencies are being
+ * collected. Same contract D surface, same behaviour; it only remembers.
+ */
+export declare function recordingRenderContext(context: RenderContext, recorder: ReadRecorder): RenderContext;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/cache/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/cache/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAIb,oBAAoB,EACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAA6B,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,IAAI,IAAI,SAAS,MAAM,EAAE,CAAA;IACzB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1C,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE,oBAAoB,GACjC,IAAI,CAIN;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAUjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,YAAY,GACrB,aAAa,CAuBf;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,YAAY,GACrB,aAAa,CASf"}

package/dist/cache/recorder.js

@@ -0,0 +1,77 @@
+import { collectionTag, entryTag, mediaTag, pathTag } from './tags.js';
+/**
+ * Feeds a response's declared dependencies into a recorder.
+ *
+ * This is the other half of what `recordingContentClient` cannot see: server-
+ * side relation expansion inlines an author into an article without the
+ * author's id ever crossing the client as a request of its own, so wrapping
+ * `ContentClient` alone misses it. Wire this into the concrete HTTP client's
+ * `onDependencies` option (see `createContentClient`) and both halves land in
+ * the same set.
+ */
+export function recordDependencies(recorder, dependencies) {
+    for (const id of dependencies.entries)
+        recorder.recordEntry(id);
+    for (const id of dependencies.media)
+        recorder.recordMedia(id);
+    for (const collection of dependencies.collections)
+        recorder.recordCollection(collection);
+}
+export function createReadRecorder() {
+    const tags = new Set();
+    return {
+        tags: () => [...tags],
+        recordEntry: (id) => void tags.add(entryTag(id)),
+        recordCollection: (collection) => void tags.add(collectionTag(collection)),
+        recordMedia: (id) => void tags.add(mediaTag(id)),
+        recordPath: (path) => void tags.add(pathTag(path)),
+    };
+}
+/**
+ * A content client that records every read, and changes nothing else.
+ *
+ * Note what `list` records: the **collection**, on top of the entries it
+ * returned. Tagging only the returned entries is the classic mistake — the
+ * front page of a blog would then survive the publication of a new article,
+ * because that article was, by definition, not in the cached page. A list
+ * depends on the shape of the collection, not on the rows it happened to show.
+ */
+export function recordingContentClient(client, recorder) {
+    return {
+        entry: async (collection, id) => {
+            // Recorded before awaiting, and whatever comes back: a page that renders
+            // "not found" for a missing entry must be dropped when that entry appears.
+            recorder.recordEntry(id);
+            return client.entry(collection, id);
+        },
+        byPath: async (path) => {
+            recorder.recordPath(path);
+            const entry = await client.byPath(path);
+            if (entry !== null)
+                recorder.recordEntry(entry.id);
+            return entry;
+        },
+        list: async (request) => {
+            recorder.recordCollection(request.collection);
+            const page = await client.list(request);
+            for (const item of page.items)
+                recorder.recordEntry(item.id);
+            return page;
+        },
+    };
+}
+/**
+ * The render context a page is given while its dependencies are being
+ * collected. Same contract D surface, same behaviour; it only remembers.
+ */
+export function recordingRenderContext(context, recorder) {
+    return {
+        ...context,
+        content: recordingContentClient(context.content, recorder),
+        image: (media, options) => {
+            recorder.recordMedia(media.id);
+            return context.image(media, options);
+        },
+    };
+}
+//# sourceMappingURL=recorder.js.map

package/dist/cache/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/cache/recorder.ts"],"names":[],"mappings":"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"}