@ressjs/vite-router 0.5.2 → 0.6.0-rc.0

package/dist/isr/capture.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureResponse = void 0;
+exports.runCaptured = runCaptured;
+exports.headerDelta = headerDelta;
+exports.varyFields = varyFields;
+exports.seedFrom = seedFrom;
+const node_events_1 = require("node:events");
+const node_http_1 = require("node:http");
+const dispatcher_1 = require("../routes/dispatcher");
+/** Cabeceras que describen el transporte de una respuesta, no su contenido. */
+const TRANSPORT_HEADERS = new Set([
+    'content-length',
+    'content-encoding',
+    'transfer-encoding',
+    'connection',
+    'keep-alive',
+    'date',
+    'etag',
+    'x-ress-cache',
+]);
+const normalize = (value) => Array.isArray(value) ? value.map(String) : String(value);
+/**
+ * Una respuesta sin socket.
+ *
+ * Implementa la parte de `express.Response` que usan el pipeline de render y
+ * `getServerSideProps`, y nada la conecta con la respuesta real: una generación
+ * en segundo plano no puede escribirle a un cliente que ya recibió su documento.
+ * La compresión tampoco la toca, así que lo que queda capturado es el HTML tal
+ * como lo produjo la página.
+ */
+class CaptureResponse extends node_events_1.EventEmitter {
+    req;
+    onEnd;
+    statusCode = 200;
+    statusMessage = '';
+    locals = {};
+    #headers = new Map();
+    #chunks = [];
+    #ended = false;
+    constructor(req, seed = {}, onEnd) {
+        super();
+        this.req = req;
+        this.onEnd = onEnd;
+        for (const [name, value] of Object.entries(seed))
+            this.setHeader(name, value);
+    }
+    get headersSent() { return this.#ended; }
+    get writableEnded() { return this.#ended; }
+    get finished() { return this.#ended; }
+    setHeader(name, value) {
+        this.#headers.set(name.toLowerCase(), { name, value: normalize(value) });
+        return this;
+    }
+    getHeader(name) { return this.#headers.get(name.toLowerCase())?.value; }
+    getHeaders() {
+        return Object.fromEntries([...this.#headers].map(([key, { value }]) => [key, value]));
+    }
+    getHeaderNames() { return [...this.#headers.keys()]; }
+    hasHeader(name) { return this.#headers.has(name.toLowerCase()); }
+    removeHeader(name) { this.#headers.delete(name.toLowerCase()); }
+    set(field, value) {
+        if (typeof field === 'object') {
+            for (const [name, v] of Object.entries(field))
+                this.setHeader(name, v);
+            return this;
+        }
+        return this.setHeader(field, value);
+    }
+    header(field, value) { return this.set(field, value); }
+    get(name) { return this.getHeader(name); }
+    append(name, value) {
+        const previous = this.getHeader(name);
+        const values = [
+            ...(previous === undefined ? [] : Array.isArray(previous) ? previous : [previous]),
+            ...(Array.isArray(value) ? value.map(String) : [String(value)]),
+        ];
+        return this.setHeader(name, values.length === 1 ? values[0] : values);
+    }
+    vary(field) {
+        const current = String(this.getHeader('Vary') ?? '');
+        const present = new Set(current.split(',').map((f) => f.trim().toLowerCase()).filter(Boolean));
+        if (present.has('*') || present.has(field.toLowerCase()))
+            return this;
+        return this.setHeader('Vary', current ? `${current}, ${field}` : field);
+    }
+    status(code) { this.statusCode = code; return this; }
+    sendStatus(code) { return this.status(code).type('text/plain').send(node_http_1.STATUS_CODES[code] ?? String(code)); }
+    type(value) {
+        const full = value.includes('/') ? value : value === 'html' ? 'text/html; charset=utf-8' : value === 'json' ? 'application/json; charset=utf-8' : `text/${value}`;
+        return this.setHeader('Content-Type', full);
+    }
+    contentType(value) { return this.type(value); }
+    location(url) { return this.setHeader('Location', url); }
+    redirect(statusOrUrl, maybeUrl) {
+        const [status, url] = typeof statusOrUrl === 'number' ? [statusOrUrl, maybeUrl ?? '/'] : [302, statusOrUrl];
+        this.status(status).location(url).end();
+    }
+    cookie(name, value, options = {}) {
+        const serialized = typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value);
+        const attrs = [
+            `${name}=${encodeURIComponent(serialized)}`,
+            `Path=${options.path ?? '/'}`,
+            ...(options.maxAge !== undefined ? [`Max-Age=${Math.floor(options.maxAge / 1000)}`] : []),
+            ...(options.httpOnly ? ['HttpOnly'] : []),
+            ...(options.secure ? ['Secure'] : []),
+            ...(options.sameSite ? [`SameSite=${options.sameSite}`] : []),
+        ];
+        return this.append('Set-Cookie', attrs.join('; '));
+    }
+    clearCookie(name, options = {}) {
+        return this.append('Set-Cookie', `${name}=; Path=${options.path ?? '/'}; Expires=Thu, 01 Jan 1970 00:00:00 GMT`);
+    }
+    writeHead(status, headers) {
+        this.status(status);
+        if (headers)
+            this.set(headers);
+        return this;
+    }
+    flushHeaders() { }
+    write(chunk) {
+        if (!this.#ended && chunk !== undefined && chunk !== null)
+            this.#chunks.push(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk));
+        return true;
+    }
+    end(chunk) {
+        if (this.#ended)
+            return this;
+        if (typeof chunk !== 'function')
+            this.write(chunk);
+        this.#ended = true;
+        this.emit('finish');
+        this.emit('close');
+        this.onEnd?.(this);
+        return this;
+    }
+    send(body) {
+        if (body !== null && typeof body === 'object' && !Buffer.isBuffer(body))
+            return this.json(body);
+        if (!this.hasHeader('Content-Type')) {
+            this.setHeader('Content-Type', Buffer.isBuffer(body) ? 'application/octet-stream' : 'text/html; charset=utf-8');
+        }
+        return this.end(body);
+    }
+    json(body) {
+        if (!this.hasHeader('Content-Type'))
+            this.setHeader('Content-Type', 'application/json; charset=utf-8');
+        return this.end(JSON.stringify(body));
+    }
+    /** Lo que se escribió, sin las cabeceras de transporte. */
+    snapshot() {
+        const headers = this.getHeaders();
+        for (const name of TRANSPORT_HEADERS)
+            delete headers[name];
+        return { status: this.statusCode, headers, body: this.#chunks.join('') };
+    }
+}
+exports.CaptureResponse = CaptureResponse;
+/**
+ * Ejecuta la cadena de render contra una respuesta sintética.
+ *
+ * Resuelve con lo capturado; con `null` si la cadena terminó sin responder
+ * (la ruta la atiende otro); rechaza con el error que la cadena propagó.
+ */
+function runCaptured(chain, req, seed) {
+    return new Promise((resolve, reject) => {
+        const res = new CaptureResponse(req, seed, (done) => resolve(done.snapshot()));
+        req.res = res;
+        (0, dispatcher_1.runMiddlewareChain)(chain, req, res, ((error) => {
+            if (res.writableEnded)
+                return;
+            if (error)
+                reject(error);
+            else
+                resolve(null);
+        }));
+    });
+}
+/**
+ * Lo que la generación agregó o cambió respecto de la semilla.
+ *
+ * La semilla son las cabeceras que la respuesta real ya tenía —las de los
+ * middlewares—, y esas se recalculan en cada petición: guardarlas congelaría las
+ * de un visitante para todos. De `Vary` se guardan sólo los campos nuevos.
+ */
+function headerDelta(seed, produced) {
+    const delta = {};
+    for (const [name, value] of Object.entries(produced)) {
+        if (TRANSPORT_HEADERS.has(name))
+            continue;
+        const before = seed[name];
+        if (name === 'vary') {
+            const known = new Set(varyFields(before).map((field) => field.toLowerCase()));
+            const added = varyFields(value).filter((field) => !known.has(field.toLowerCase()));
+            if (added.length)
+                delta.vary = added.join(', ');
+            continue;
+        }
+        if (before === undefined || String(before) !== String(value))
+            delta[name] = value;
+    }
+    return delta;
+}
+function varyFields(value) {
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value.join(',') : value)
+        .split(',')
+        .map((field) => field.trim())
+        .filter(Boolean);
+}
+/** Las cabeceras de la respuesta real, normalizadas, sin cookies. */
+function seedFrom(res) {
+    const seed = {};
+    for (const [name, value] of Object.entries(res.getHeaders())) {
+        const key = name.toLowerCase();
+        if (value === undefined || key === 'set-cookie' || TRANSPORT_HEADERS.has(key))
+            continue;
+        seed[key] = normalize(value);
+    }
+    return seed;
+}

package/dist/isr/handler.d.ts

@@ -0,0 +1,49 @@
+import type { Request, RequestHandler } from 'express';
+import type { ResolvedIsrConfig } from '../config/types';
+import type { RouteEntry } from '../routes/types';
+import { type RequestPlatform } from './key';
+import { type MemoryIsrStore } from './store';
+import type { ResolvedPageRendering } from './types';
+/** Lo que el router comparte con todos los manejadores ISR. */
+export interface IsrRuntime {
+    store: MemoryIsrStore;
+    options: ResolvedIsrConfig;
+    /** En desarrollo sólo con `isr.dev`: si no, se genera en cada petición. */
+    cacheEnabled: boolean;
+    buildId: string;
+    /** La política de contenido lleva nonce: cambia qué se le dice a una CDN. */
+    usesNonce: boolean;
+    isProduction: boolean;
+    /** El `Cache-Control` de HTML por defecto, para cuando una entrada deja de declararse compartible. */
+    htmlCacheControl: string;
+    resolvePlatform(req: Request): RequestPlatform;
+}
+export interface IsrHandlerOptions {
+    entry: RouteEntry;
+    /** La del export estático. `getServerSideProps` puede cambiarla en cada generación. */
+    rendering: ResolvedPageRendering;
+    /** `getServerSideProps` y render: lo único que la caché evita ejecutar. */
+    render: readonly RequestHandler[];
+    /** La ruta tiene middlewares de carpeta: una CDN no los correría. */
+    hasMiddlewares?: boolean;
+    runtime: IsrRuntime;
+}
+/**
+ * El manejador de render de una página.
+ *
+ * Va después de los middlewares de carpeta, que corren siempre con la petición
+ * real: si protegen la ruta, un acierto no los saltea. Lo que reemplaza es sólo
+ * `getServerSideProps` y el render.
+ *
+ * El modo de la ruta es el de su última generación. Empieza con el del export
+ * estático; si `getServerSideProps` devuelve otro, la ruta lo adopta desde la
+ * petición siguiente. Así una página puede declararse ISR desde cualquiera de
+ * los dos lugares: la caché se consulta antes de ejecutar nada, de modo que la
+ * primera petición de una ruta que sólo lo declara en `getServerSideProps`
+ * corre como SSR y es la que lo descubre.
+ *
+ * En modo ISR, `getServerSideProps` y el render se ejecutan contra una
+ * petición pública y una respuesta sintética. MISS, STALE y desarrollo
+ * recorren ese mismo camino.
+ */
+export declare function createIsrHandler({ entry, rendering, render, runtime, hasMiddlewares }: IsrHandlerOptions): RequestHandler;

package/dist/isr/handler.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIsrHandler = createIsrHandler;
+const dispatcher_1 = require("../routes/dispatcher");
+const capture_1 = require("./capture");
+const key_1 = require("./key");
+const preview_1 = require("./preview");
+const public_request_1 = require("./public-request");
+const response_1 = require("./response");
+const store_1 = require("./store");
+/**
+ * El manejador de render de una página.
+ *
+ * Va después de los middlewares de carpeta, que corren siempre con la petición
+ * real: si protegen la ruta, un acierto no los saltea. Lo que reemplaza es sólo
+ * `getServerSideProps` y el render.
+ *
+ * El modo de la ruta es el de su última generación. Empieza con el del export
+ * estático; si `getServerSideProps` devuelve otro, la ruta lo adopta desde la
+ * petición siguiente. Así una página puede declararse ISR desde cualquiera de
+ * los dos lugares: la caché se consulta antes de ejecutar nada, de modo que la
+ * primera petición de una ruta que sólo lo declara en `getServerSideProps`
+ * corre como SSR y es la que lo descubre.
+ *
+ * En modo ISR, `getServerSideProps` y el render se ejecutan contra una
+ * petición pública y una respuesta sintética. MISS, STALE y desarrollo
+ * recorren ese mismo camino.
+ */
+function createIsrHandler({ entry, rendering, render, runtime, hasMiddlewares = false }) {
+    const { store } = runtime;
+    // Una CDN no corre los middlewares de ress.js. Si la ruta tiene alguno, puede
+    // estar decidiendo quién ve la página; declararla compartible dejaría a la
+    // CDN servirle a cualquiera lo que guardó de alguien autorizado.
+    const { sharedCache } = runtime.options;
+    const shareable = sharedCache === 'always' || (sharedCache === 'auto' && !hasMiddlewares);
+    const sharedCacheControl = (config) => shareable ? (0, response_1.isrCacheControl)(config, runtime.usesNonce) : undefined;
+    const warned = new Set();
+    let current = rendering;
+    const warnOnce = (id, message) => {
+        if (runtime.isProduction || warned.has(id))
+            return;
+        warned.add(id);
+        console.warn(message);
+    };
+    return async (req, res, next) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            return (0, dispatcher_1.runMiddlewareChain)(render, req, res, next);
+        }
+        if ((0, preview_1.isPreviewRequest)(req, runtime.options.previewSecret)) {
+            res.setHeader('X-Ress-Cache', 'BYPASS');
+            res.setHeader('Cache-Control', 'private, no-store');
+            return (0, dispatcher_1.runMiddlewareChain)(render, req, res, next);
+        }
+        // SSR con la petición real. Si su `getServerSideProps` declara otro modo,
+        // la ruta lo adopta desde la próxima petición.
+        if (current.mode !== 'isr')
+            return runLive(req, res, next);
+        const dropped = Object.keys(res.locals ?? {});
+        if (dropped.length) {
+            warnOnce(`locals:${dropped.join(',')}`, `[ress] ${entry.pattern} es ISR: estas claves de res.locals no llegan a la página, ` +
+                `porque su HTML se comparte entre visitantes: ${dropped.join(', ')}.`);
+        }
+        const platform = req.ressPlatform ?? runtime.resolvePlatform(req);
+        const { pathname } = new URL(req.url, 'http://ress.invalid');
+        const routeRendering = current;
+        const cacheControl = sharedCacheControl(routeRendering);
+        const origin = (0, public_request_1.requestOrigin)(req);
+        const { search, query } = (0, key_1.canonicalSearch)(req.url, routeRendering.searchParams);
+        const url = pathname + search;
+        const seed = (0, capture_1.seedFrom)(res);
+        const generate = async () => {
+            const publicReq = (0, public_request_1.createPublicRequest)(req, {
+                url,
+                query,
+                platform,
+                origin,
+                // La plataforma llega resuelta en `req.ressPlatform`, que es lo que
+                // separa la clave. El User-Agent crudo permitiría personalizar por
+                // navegador un HTML que se comparte entre todos los de esa plataforma.
+                includeUserAgent: false,
+            });
+            const generationSeed = cacheControl && seed['cache-control'] === undefined
+                ? { ...seed, 'cache-control': cacheControl }
+                : seed;
+            const full = await (0, capture_1.runCaptured)(render, publicReq, generationSeed);
+            if (!full)
+                return null;
+            const generated = publicReq.ressPageRendering ?? routeRendering;
+            current = generated;
+            const delta = (0, capture_1.headerDelta)(seed, full.headers);
+            // `getServerSideProps` pudo cambiar los plazos de esta entrada: lo que se
+            // le dice a una CDN tiene que coincidir, salvo que la página haya puesto
+            // su propio `Cache-Control`.
+            if (generated !== routeRendering && cacheControl && full.headers['cache-control'] === cacheControl) {
+                const recalculated = sharedCacheControl(generated) ?? runtime.htmlCacheControl;
+                delta['cache-control'] = recalculated;
+                full.headers['cache-control'] = recalculated;
+            }
+            // Una CDN sólo puede guardar HTML que es igual para cualquier
+            // plataforma. ress.js separa por plataforma en su propia caché, pero la
+            // CDN no: en vez de pedirle que separe con `Vary` —muchas lo ignoran en
+            // HTML y, las que no, fragmentan la caché—, una página que depende de la
+            // plataforma simplemente no se le declara compartible. Depende si leyó
+            // una cabecera de plataforma o si tiene variantes (su `Vary` lo dice).
+            const dependsOnPlatform = (0, public_request_1.publicRequestUsage)(publicReq).readsPlatform || (0, capture_1.varyFields)(delta.vary).length > 0;
+            const ours = [cacheControl, sharedCacheControl(generated)].includes(full.headers['cache-control']);
+            if (dependsOnPlatform && ours && (0, response_1.isSharedCacheControl)(full.headers['cache-control'])) {
+                delta['cache-control'] = runtime.htmlCacheControl;
+                full.headers['cache-control'] = runtime.htmlCacheControl;
+            }
+            const verdict = generated.mode === 'isr'
+                ? (0, response_1.cacheability)(full, delta)
+                : { ok: false, reason: `getServerSideProps declaró renderingMode: '${generated.mode}'` };
+            if (!verdict.ok && generated.mode === 'isr') {
+                warnOnce(`uncacheable:${verdict.reason}`, `[ress] ${entry.pattern} es ISR pero no se guarda: ${verdict.reason}.`);
+            }
+            return {
+                template: (0, response_1.normalizeForCache)({ status: full.status, headers: delta, body: full.body }),
+                verdict,
+                rendering: generated,
+                committed: false,
+            };
+        };
+        // La generación pública se hizo sin cookies ni credenciales: si la página
+        // resultó ser SSR, esa respuesta no le sirve a este visitante. Se descarta
+        // la entrada de esta URL y se atiende con la petición real.
+        const declaredSsr = (generation) => generation.rendering.mode !== 'isr';
+        const serve = (generation, state) => (0, response_1.applyCaptured)(res, (0, response_1.materialize)(generation.template), state);
+        if (!runtime.cacheEnabled) {
+            let generation;
+            try {
+                generation = await generate();
+            }
+            catch (error) {
+                return next(error);
+            }
+            if (!generation)
+                return next();
+            if (declaredSsr(generation))
+                return runLive(req, res, next);
+            return serve(generation, 'BYPASS');
+        }
+        const key = (0, key_1.cacheKey)(runtime.buildId, (0, key_1.platformKeyOf)(platform), `${origin.protocol}://${origin.host}${url}`);
+        // Varias peticiones pueden esperar la misma generación: la primera que la
+        // recibe la guarda. Lo que devuelve una generación abandonada por tiempo no
+        // llega acá, así que nunca se guarda.
+        const commit = (generation) => {
+            if (generation.committed || !generation.verdict.ok)
+                return;
+            generation.committed = true;
+            store.set({
+                ...generation.template,
+                key,
+                generatedAt: Date.now(),
+                revalidateMs: generation.rendering.revalidateMs,
+                expireMs: generation.rendering.expireMs,
+                bytes: Buffer.byteLength(generation.template.body),
+            });
+        };
+        const lookup = store.lookup(key);
+        if (lookup.state === 'fresh')
+            return (0, response_1.applyCaptured)(res, (0, response_1.materialize)(lookup.entry), 'HIT');
+        if (lookup.state === 'stale') {
+            (0, response_1.applyCaptured)(res, (0, response_1.materialize)(lookup.entry), 'STALE');
+            if (store.inFlight(key))
+                return;
+            store.run(key, generate).then((generation) => {
+                if (generation?.verdict.ok)
+                    return commit(generation);
+                if (generation && declaredSsr(generation))
+                    return store.delete(key);
+                const reason = generation && !generation.verdict.ok ? generation.verdict.reason : 'la cadena no respondió';
+                console.error(`[ress] La regeneración ISR de ${(0, store_1.readableKey)(key)} no produjo una entrada válida (${reason}); se conserva la anterior.`);
+            }, (error) => {
+                console.error(`[ress] Falló la regeneración ISR de ${(0, store_1.readableKey)(key)}; se conserva la anterior.`, error);
+            });
+            return;
+        }
+        // Sin entrada, o más vieja que el techo: se genera antes de responder.
+        let generation;
+        try {
+            generation = await store.run(key, generate);
+        }
+        catch (error) {
+            if (lookup.state === 'expired')
+                store.delete(key);
+            return next(error);
+        }
+        if (!generation)
+            return next();
+        if (declaredSsr(generation)) {
+            store.delete(key);
+            return runLive(req, res, next);
+        }
+        commit(generation);
+        serve(generation, 'MISS');
+    };
+    function runLive(req, res, next) {
+        // `ressPageRendering` sólo existe si `getServerSideProps` devolvió campos
+        // de render; si no, la ruta conserva el modo que tenía.
+        res.once('finish', () => {
+            if (req.ressPageRendering)
+                current = req.ressPageRendering;
+        });
+        (0, dispatcher_1.runMiddlewareChain)(render, req, res, next);
+    }
+}

package/dist/isr/key.d.ts

@@ -0,0 +1,26 @@
+import type { PlatformInfo } from '../platform';
+export interface RequestPlatform {
+    platform: string;
+    platformInfo: PlatformInfo | null;
+}
+/**
+ * La búsqueda que forma parte de la identidad de la página.
+ *
+ * Sólo sobreviven los parámetros declarados, ordenados por nombre; los valores
+ * repetidos conservan su orden porque `?tag=a&tag=b` y `?tag=b&tag=a` pueden
+ * significar cosas distintas. Lo no declarado desaparece: un `utm_source` no
+ * crea una entrada nueva ni llega a la página.
+ */
+export declare function canonicalSearch(url: string, allowed: readonly string[]): {
+    search: string;
+    query: Record<string, string | string[]>;
+};
+/**
+ * La plataforma como componente de la clave.
+ *
+ * Se usa la información completa y no sólo el nombre corto: el documento puede
+ * llevar la plataforma serializada, y dos clientes que se describen distinto no
+ * pueden compartir ese documento.
+ */
+export declare function platformKeyOf({ platform, platformInfo }: RequestPlatform): string;
+export declare function cacheKey(buildId: string, platformKey: string, pathWithSearch: string): string;

package/dist/isr/key.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalSearch = canonicalSearch;
+exports.platformKeyOf = platformKeyOf;
+exports.cacheKey = cacheKey;
+/**
+ * La búsqueda que forma parte de la identidad de la página.
+ *
+ * Sólo sobreviven los parámetros declarados, ordenados por nombre; los valores
+ * repetidos conservan su orden porque `?tag=a&tag=b` y `?tag=b&tag=a` pueden
+ * significar cosas distintas. Lo no declarado desaparece: un `utm_source` no
+ * crea una entrada nueva ni llega a la página.
+ */
+function canonicalSearch(url, allowed) {
+    if (allowed.length === 0)
+        return { search: '', query: {} };
+    const params = new URL(url, 'http://ress.invalid').searchParams;
+    const kept = new URLSearchParams();
+    const query = {};
+    for (const name of [...allowed].sort()) {
+        const values = params.getAll(name);
+        if (values.length === 0)
+            continue;
+        for (const value of values)
+            kept.append(name, value);
+        query[name] = values.length === 1 ? values[0] : values;
+    }
+    const search = kept.toString();
+    return { search: search ? `?${search}` : '', query };
+}
+/**
+ * La plataforma como componente de la clave.
+ *
+ * Se usa la información completa y no sólo el nombre corto: el documento puede
+ * llevar la plataforma serializada, y dos clientes que se describen distinto no
+ * pueden compartir ese documento.
+ */
+function platformKeyOf({ platform, platformInfo }) {
+    if (!platformInfo)
+        return platform;
+    const { source: _deprecated, ...info } = platformInfo;
+    return JSON.stringify(sortKeys({
+        platform,
+        ...info,
+        capabilities: [...info.capabilities].sort(),
+    }));
+}
+function cacheKey(buildId, platformKey, pathWithSearch) {
+    return `${buildId}\0${platformKey}\0${pathWithSearch}`;
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, sortKeys(value[key])]));
+}

package/dist/isr/page-config.d.ts

@@ -0,0 +1,17 @@
+import type { PageRenderingConfig, ResolvedPageRendering } from './types';
+/** Una configuración de página que no se puede usar, con todos sus problemas juntos. */
+export declare class PageConfigError extends Error {
+    readonly file: string;
+    readonly problems: string[];
+    constructor(file: string, problems: string[]);
+}
+/**
+ * Valida la parte de render de `pageConfig` y la lleva a las unidades del runtime.
+ *
+ * Se acumulan todos los problemas antes de fallar, igual que la configuración
+ * del proyecto: corregir de a uno y reiniciar es una forma lenta de perder la tarde.
+ * `revalidate`, `expire` y `searchParams` se admiten con `ssr` y no tienen
+ * efecto: el export estático puede fijar los plazos y dejar que
+ * `getServerSideProps` decida el modo, sin que eso sea un error.
+ */
+export declare function resolvePageRendering(config: PageRenderingConfig | undefined, file: string): ResolvedPageRendering;

package/dist/isr/page-config.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageConfigError = void 0;
+exports.resolvePageRendering = resolvePageRendering;
+const MODES = ['ssr', 'isr'];
+/** Una configuración de página que no se puede usar, con todos sus problemas juntos. */
+class PageConfigError extends Error {
+    file;
+    problems;
+    constructor(file, problems) {
+        super(`[ress] ${file}: pageConfig tiene ${problems.length === 1 ? 'un problema' : `${problems.length} problemas`}:\n` +
+            problems.map((p) => `  · ${p}`).join('\n'));
+        this.file = file;
+        this.problems = problems;
+        this.name = 'PageConfigError';
+    }
+}
+exports.PageConfigError = PageConfigError;
+const isPositiveInteger = (value) => typeof value === 'number' && Number.isInteger(value) && value > 0;
+/**
+ * Valida la parte de render de `pageConfig` y la lleva a las unidades del runtime.
+ *
+ * Se acumulan todos los problemas antes de fallar, igual que la configuración
+ * del proyecto: corregir de a uno y reiniciar es una forma lenta de perder la tarde.
+ * `revalidate`, `expire` y `searchParams` se admiten con `ssr` y no tienen
+ * efecto: el export estático puede fijar los plazos y dejar que
+ * `getServerSideProps` decida el modo, sin que eso sea un error.
+ */
+function resolvePageRendering(config, file) {
+    const { renderingMode, revalidate, expire, hydrate, searchParams } = config ?? {};
+    const problems = [];
+    if (renderingMode !== undefined && !MODES.includes(renderingMode)) {
+        problems.push(`\`renderingMode\` sólo acepta 'ssr' o 'isr'; se recibió ${JSON.stringify(renderingMode)}.`);
+    }
+    const mode = renderingMode === 'isr' ? 'isr' : 'ssr';
+    if (revalidate !== undefined && revalidate !== false && !isPositiveInteger(revalidate)) {
+        problems.push(revalidate === 0
+            ? '`revalidate: 0` no es válido: una página que no se cachea usa renderingMode: \'ssr\'.'
+            : '`revalidate` tiene que ser un entero de segundos mayor que cero, o `false`.');
+    }
+    if (expire !== undefined) {
+        if (!isPositiveInteger(expire)) {
+            problems.push('`expire` tiene que ser un entero de segundos mayor que cero.');
+        }
+        else if (typeof revalidate !== 'number') {
+            problems.push('`expire` requiere un `revalidate` numérico: sin plazo de frescura no hay entrada vencida que acotar.');
+        }
+        else if (expire <= revalidate) {
+            problems.push(`\`expire\` (${expire}) tiene que ser mayor que \`revalidate\` (${revalidate}).`);
+        }
+    }
+    if (hydrate !== undefined && typeof hydrate !== 'boolean') {
+        problems.push('`hydrate` tiene que ser un booleano.');
+    }
+    if (searchParams !== undefined &&
+        (!Array.isArray(searchParams) || searchParams.some((name) => typeof name !== 'string' || !name))) {
+        problems.push('`searchParams` tiene que ser una lista de nombres de parámetro no vacíos.');
+    }
+    if (problems.length)
+        throw new PageConfigError(file, problems);
+    const seconds = typeof revalidate === 'number' ? revalidate : false;
+    return {
+        mode,
+        hydrate: hydrate !== false,
+        revalidate: seconds,
+        ...(expire !== undefined ? { expire } : {}),
+        revalidateMs: seconds === false ? null : seconds * 1000,
+        expireMs: expire === undefined ? null : expire * 1000,
+        searchParams: [...new Set(searchParams ?? [])].sort(),
+    };
+}

package/dist/isr/preview.d.ts

@@ -0,0 +1,5 @@
+import type { Request } from 'express';
+export declare const PREVIEW_HEADER = "x-ress-preview";
+export declare const PREVIEW_COOKIE = "__ress_preview";
+/** ¿La petición trae el secreto de vista previa? Sin secreto configurado, nunca. */
+export declare function isPreviewRequest(req: Request, secret: string | undefined): boolean;