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

package/dist/routes/dispatcher.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDispatcher = createDispatcher;
+exports.runMiddlewareChain = runMiddlewareChain;
+/**
+ * Un único punto de entrada para todas las rutas.
+ *
+ * El modelo anterior registraba una ruta de Express por página, lo que obligaba
+ * a traducir cada patrón a la sintaxis de Express —que no puede expresar un
+ * catch-all opcional ni un grupo— y dejaba la precedencia en manos del orden de
+ * registro. Acá el manifest decide, y Express sólo ve un middleware.
+ *
+ * Las cadenas se construyen una vez, no por petición. `chains` se reemplaza
+ * entero cuando el manifest cambia en desarrollo, de modo que una petición nunca
+ * ve una mezcla de dos versiones.
+ */
+function createDispatcher(getState) {
+    return async (req, res, next) => {
+        const { manifest, chains } = getState();
+        const match = manifest.match(req.path ?? req.url ?? '/');
+        // Sin match no es un 404 todavía: puede haber middlewares detrás que sepan
+        // atenderla, y decidirlo acá les quitaría la oportunidad.
+        if (!match)
+            return next();
+        const chain = chains.get(match.entry.pageId);
+        if (!chain)
+            return next();
+        req.ressParams = match.params;
+        req.params = match.params;
+        req.ressRoute = match.entry;
+        runMiddlewareChain(chain, req, res, next);
+    };
+}
+/**
+ * Ejecuta la cadena respetando el contrato de Express.
+ *
+ * Cada middleware decide si sigue: `next()` avanza, `next(error)` corta y
+ * propaga. Un throw síncrono se convierte en `next(error)` para que no quede una
+ * petición colgada.
+ */
+function runMiddlewareChain(chain, req, res, done) {
+    let index = 0;
+    const step = (error) => {
+        if (error)
+            return done(error);
+        const handler = chain[index++];
+        if (!handler)
+            return done();
+        // Un middleware asíncrono puede llamar a `next()` y rechazar después. Sin
+        // esta guarda, el rechazo volvería a entrar a la cadena sobre una respuesta
+        // que ya se envió, y el fallo sería un ERR_HTTP_HEADERS_SENT en vez de la
+        // página de error.
+        let advanced = false;
+        const once = (err) => {
+            if (advanced)
+                return;
+            advanced = true;
+            step(err);
+        };
+        try {
+            const result = handler(req, res, once);
+            if (result instanceof Promise)
+                result.catch(once);
+        }
+        catch (err) {
+            once(err);
+        }
+    };
+    step();
+}

package/dist/routes/manifest.d.ts

@@ -0,0 +1,17 @@
+import { type RouteManifest, type RouteManifestData } from './types';
+/**
+ * El manifest ya indexado.
+ *
+ * Las rutas estáticas —la mayoría de un proyecto— se resuelven con una consulta
+ * a un mapa. Sólo las que tienen parámetros recorren la lista, y ya viene
+ * ordenada por precedencia, así que la primera que matchea es la que gana.
+ */
+export declare function createRouteManifest(data: RouteManifestData): RouteManifest;
+export declare function serializeRouteManifest(data: RouteManifestData): string;
+/**
+ * Lee un manifest emitido por el build.
+ *
+ * La versión se comprueba a propósito: un manifest de un formato anterior
+ * produciría fallos de ruteo difíciles de atribuir, y el mensaje dice qué hacer.
+ */
+export declare function loadRouteManifest(raw: string): RouteManifest;

package/dist/routes/manifest.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouteManifest = createRouteManifest;
+exports.serializeRouteManifest = serializeRouteManifest;
+exports.loadRouteManifest = loadRouteManifest;
+const match_1 = require("./match");
+const types_1 = require("./types");
+/**
+ * El manifest ya indexado.
+ *
+ * Las rutas estáticas —la mayoría de un proyecto— se resuelven con una consulta
+ * a un mapa. Sólo las que tienen parámetros recorren la lista, y ya viene
+ * ordenada por precedencia, así que la primera que matchea es la que gana.
+ */
+function createRouteManifest(data) {
+    const entries = data.entries;
+    const byPageId = new Map(entries.map((e) => [e.pageId, e]));
+    const staticIndex = new Map();
+    for (const entry of entries) {
+        if (entry.segments.every((s) => s.kind === 'static')) {
+            staticIndex.set(`${entry.kind} ${entry.pattern}`, entry);
+        }
+    }
+    return {
+        entries,
+        middlewares: data.middlewares,
+        match(pathname, options = {}) {
+            const kinds = options.kinds ?? ['page'];
+            const clean = '/' + pathname.split('?')[0].split('#')[0].split('/').filter(Boolean).join('/');
+            for (const kind of kinds) {
+                const exact = staticIndex.get(`${kind} ${clean}`);
+                if (exact)
+                    return { entry: exact, params: {} };
+            }
+            return (0, match_1.matchEntries)(entries, pathname, options);
+        },
+        get: (pageId) => byPageId.get(pageId),
+        byKind: (kind) => entries.filter((e) => e.kind === kind),
+    };
+}
+function serializeRouteManifest(data) {
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Lee un manifest emitido por el build.
+ *
+ * La versión se comprueba a propósito: un manifest de un formato anterior
+ * produciría fallos de ruteo difíciles de atribuir, y el mensaje dice qué hacer.
+ */
+function loadRouteManifest(raw) {
+    const data = JSON.parse(raw);
+    if (data.version !== types_1.ROUTE_MANIFEST_VERSION) {
+        throw new Error(`[ress] El manifest de rutas es de la versión ${data.version} y este ress.js espera la ` +
+            `${types_1.ROUTE_MANIFEST_VERSION}. Volvé a construir el proyecto.`);
+    }
+    // Un manifest de build sin la lista de middlewares arrancaría sin ellos. Si
+    // falta, el build está incompleto: mejor no arrancar.
+    if (!Array.isArray(data.middlewares)) {
+        throw new Error('[ress] El manifest de rutas no registra los middlewares del build. Volvé a construir el proyecto.');
+    }
+    return createRouteManifest(data);
+}

package/dist/routes/match.d.ts

@@ -0,0 +1,20 @@
+import type { MatchOptions, RouteEntry, RouteMatch, RouteSegment } from './types';
+/**
+ * Parte una URL en segmentos.
+ *
+ * Se descartan la consulta y el fragmento, y la barra final no distingue: `/about`
+ * y `/about/` son la misma ruta.
+ */
+export declare function splitPath(pathname: string): string[];
+/**
+ * ¿Esta ruta atiende esta URL?
+ *
+ * Sin expresiones regulares: se recorre segmento a segmento. Una regex construida
+ * a partir de un patrón es difícil de auditar y fácil de romper con un carácter
+ * que había que escapar — y el modelo anterior tenía justamente ese defecto:
+ * `/page1` matcheaba `/page1/cualquier/cosa` porque su regex no exigía consumir
+ * la URL entera.
+ */
+export declare function matchSegments(segments: readonly RouteSegment[], parts: readonly string[]): Record<string, string | string[]> | undefined;
+/** La primera entrada que atiende esta URL, recorriendo en orden de precedencia. */
+export declare function matchEntries(entries: readonly RouteEntry[], pathname: string, options?: MatchOptions): RouteMatch | undefined;

package/dist/routes/match.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitPath = splitPath;
+exports.matchSegments = matchSegments;
+exports.matchEntries = matchEntries;
+/**
+ * Parte una URL en segmentos.
+ *
+ * Se descartan la consulta y el fragmento, y la barra final no distingue: `/about`
+ * y `/about/` son la misma ruta.
+ */
+function splitPath(pathname) {
+    const clean = pathname.split('?')[0].split('#')[0];
+    return clean.split('/').filter(Boolean);
+}
+/**
+ * ¿Esta ruta atiende esta URL?
+ *
+ * Sin expresiones regulares: se recorre segmento a segmento. Una regex construida
+ * a partir de un patrón es difícil de auditar y fácil de romper con un carácter
+ * que había que escapar — y el modelo anterior tenía justamente ese defecto:
+ * `/page1` matcheaba `/page1/cualquier/cosa` porque su regex no exigía consumir
+ * la URL entera.
+ */
+function matchSegments(segments, parts) {
+    const params = {};
+    let index = 0;
+    for (const segment of segments) {
+        if (segment.kind === 'catchAll' || segment.kind === 'optionalCatchAll') {
+            const rest = parts.slice(index).map(decode);
+            // Un catch-all obligatorio necesita al menos un segmento; el opcional
+            // acepta ninguno y entrega una lista vacía.
+            if (segment.kind === 'catchAll' && rest.length === 0)
+                return undefined;
+            params[segment.value] = rest;
+            return params;
+        }
+        const part = parts[index];
+        if (part === undefined)
+            return undefined;
+        if (segment.kind === 'static') {
+            if (part !== segment.value)
+                return undefined;
+        }
+        else {
+            params[segment.value] = decode(part);
+        }
+        index++;
+    }
+    // La URL tiene que quedar consumida entera: lo que sobra no lo atiende esta ruta.
+    return index === parts.length ? params : undefined;
+}
+function decode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        // Una secuencia de escape inválida no es motivo para fallar la petición: el
+        // valor crudo es lo que el cliente pidió.
+        return value;
+    }
+}
+/** La primera entrada que atiende esta URL, recorriendo en orden de precedencia. */
+function matchEntries(entries, pathname, options = {}) {
+    const kinds = options.kinds ?? ['page'];
+    const parts = splitPath(pathname);
+    for (const entry of entries) {
+        if (!kinds.includes(entry.kind))
+            continue;
+        const params = matchSegments(entry.segments, parts);
+        if (params)
+            return { entry, params };
+    }
+    return undefined;
+}

package/dist/routes/module.d.ts

@@ -0,0 +1,14 @@
+import type { RouteEntry } from './types';
+export interface ResolveServerModuleContext {
+    root: string;
+    isProduction: boolean;
+    /** Directorio del build SSR, relativo a `root` o absoluto. */
+    serverOutDir: string;
+}
+/**
+ * Resuelve el módulo de una entrada desde la identidad que registró el build.
+ *
+ * En producción no se vuelve a derivar un nombre desde `sourceFile`: esa regla
+ * se rompe apenas el bundler cambia un nombre, agrega un hash o mueve un chunk.
+ */
+export declare function resolveServerModule(entry: Pick<RouteEntry, 'pageId' | 'server'>, context: ResolveServerModuleContext): string;

package/dist/routes/module.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveServerModule = resolveServerModule;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Resuelve el módulo de una entrada desde la identidad que registró el build.
+ *
+ * En producción no se vuelve a derivar un nombre desde `sourceFile`: esa regla
+ * se rompe apenas el bundler cambia un nombre, agrega un hash o mueve un chunk.
+ */
+function resolveServerModule(entry, context) {
+    if (!context.isProduction)
+        return entry.server.devId;
+    const chunk = entry.server.buildChunk;
+    if (!chunk) {
+        throw new Error(`[ress] La entrada "${entry.pageId}" no tiene módulo de servidor compilado. ` +
+            'Volvé a construir el proyecto.');
+    }
+    const outDir = node_path_1.default.resolve(context.root, context.serverOutDir);
+    const target = node_path_1.default.resolve(outDir, chunk);
+    const relative = node_path_1.default.relative(outDir, target);
+    if (relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(relative)) {
+        throw new Error(`[ress] El chunk de servidor de "${entry.pageId}" queda fuera del directorio de build: ` +
+            `"${chunk}".`);
+    }
+    return target;
+}

package/dist/routes/parse.d.ts

@@ -0,0 +1,31 @@
+import type { RouteEntryKind, RouteSegment } from './types';
+/**
+ * Convierte la ubicación de un archivo en un patrón de ruta.
+ *
+ * Notación:
+ *
+ * | En el archivo | En la URL |
+ * |---|---|
+ * | `users/perfil.tsx` | `/users/perfil` |
+ * | `users/index.tsx` | `/users` |
+ * | `users/[id].tsx` | `/users/:id` |
+ * | `docs/[...slug].tsx` | `/docs/` y todo lo que siga |
+ * | `shop/[[...filtros]].tsx` | `/shop` y todo lo que siga |
+ * | `(marketing)/about.tsx` | `/about` — el grupo no aporta segmento |
+ */
+export interface ParsedRoute {
+    pattern: string;
+    segments: RouteSegment[];
+    paramNames: string[];
+    groups: string[];
+}
+export declare function parseRoutePattern(sourceFile: string, pagesDir?: string): ParsedRoute;
+/**
+ * Identificador estable de una página.
+ *
+ * Es la misma clave que usa el catálogo de variantes de F-016, para que las dos
+ * estructuras hablen del mismo objeto sin traducir nada entre ellas.
+ */
+export declare function pageIdFromFile(sourceFile: string, pagesDir?: string): string;
+/** Qué clase de entrada es, según dónde vive el archivo. */
+export declare function classifyEntry(sourceFile: string, pagesDir?: string): RouteEntryKind;

package/dist/routes/parse.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRoutePattern = parseRoutePattern;
+exports.pageIdFromFile = pageIdFromFile;
+exports.classifyEntry = classifyEntry;
+const EXTENSION = /\.(tsx|ts|jsx|js|mts|mjs)$/;
+function parseRoutePattern(sourceFile, pagesDir = 'app/pages') {
+    const relative = stripPagesDir(sourceFile, pagesDir).replace(EXTENSION, '');
+    const segments = [];
+    const paramNames = [];
+    const groups = [];
+    const parts = relative.split('/').filter(Boolean);
+    for (const [index, raw] of parts.entries()) {
+        // Un grupo organiza archivos sin aparecer en la URL.
+        if (raw.startsWith('(') && raw.endsWith(')')) {
+            groups.push(raw.slice(1, -1));
+            continue;
+        }
+        // `index` nombra la ruta de su carpeta, así que no aporta segmento propio.
+        if (raw === 'index' && index === parts.length - 1)
+            continue;
+        const segment = parseSegment(raw, sourceFile);
+        // Todo lo que siga a un catch-all sería inalcanzable: el catch-all ya
+        // consumió el resto de la URL.
+        const previous = segments[segments.length - 1];
+        if (previous && (previous.kind === 'catchAll' || previous.kind === 'optionalCatchAll')) {
+            throw new Error(`[ress] "${sourceFile}" pone un segmento después de "[...${previous.value}]". ` +
+                'Un catch-all consume el resto de la URL, así que nada que lo siga puede alcanzarse.');
+        }
+        if (segment.kind !== 'static') {
+            if (paramNames.includes(segment.value)) {
+                throw new Error(`[ress] "${sourceFile}" usa el parámetro "${segment.value}" dos veces. ` +
+                    'Cada parámetro tiene que tener un nombre distinto para poder leerse.');
+            }
+            paramNames.push(segment.value);
+        }
+        segments.push(segment);
+    }
+    return { pattern: toPattern(segments), segments, paramNames, groups };
+}
+function parseSegment(raw, sourceFile) {
+    const open = raw.indexOf('[');
+    const close = raw.lastIndexOf(']');
+    if (open === -1 && close === -1)
+        return { kind: 'static', value: raw };
+    if (open !== 0 || close !== raw.length - 1) {
+        throw new Error(`[ress] "${sourceFile}" tiene corchetes desbalanceados o mezclados con texto en "${raw}". ` +
+            'Un segmento con parámetro se escribe entero entre corchetes: [id], [...slug], [[...slug]].');
+    }
+    const inner = raw.slice(1, -1);
+    // `[[...slug]]` — el doble corchete lo vuelve opcional.
+    if (inner.startsWith('[') && inner.endsWith(']')) {
+        const name = requireName(inner.slice(1, -1).replace(/^\.\.\./, ''), raw, sourceFile);
+        if (!inner.slice(1, -1).startsWith('...')) {
+            throw new Error(`[ress] "${sourceFile}" escribe "${raw}" con doble corchete pero sin "...". ` +
+                'El doble corchete es para un catch-all opcional: [[...slug]].');
+        }
+        return { kind: 'optionalCatchAll', value: name };
+    }
+    if (inner.startsWith('...')) {
+        return { kind: 'catchAll', value: requireName(inner.slice(3), raw, sourceFile) };
+    }
+    return { kind: 'dynamic', value: requireName(inner, raw, sourceFile) };
+}
+function requireName(name, raw, sourceFile) {
+    if (!name) {
+        throw new Error(`[ress] "${sourceFile}" declara el parámetro "${raw}" sin nombre. ` +
+            'Sin nombre no hay forma de leer su valor desde la página.');
+    }
+    return name;
+}
+function toPattern(segments) {
+    if (segments.length === 0)
+        return '/';
+    return ('/' +
+        segments
+            .map((s) => {
+            if (s.kind === 'static')
+                return s.value;
+            if (s.kind === 'dynamic')
+                return `[${s.value}]`;
+            if (s.kind === 'catchAll')
+                return `[...${s.value}]`;
+            return `[[...${s.value}]]`;
+        })
+            .join('/'));
+}
+/**
+ * Identificador estable de una página.
+ *
+ * Es la misma clave que usa el catálogo de variantes de F-016, para que las dos
+ * estructuras hablen del mismo objeto sin traducir nada entre ellas.
+ */
+function pageIdFromFile(sourceFile, pagesDir = 'app/pages') {
+    return stripPagesDir(sourceFile, pagesDir)
+        .replace(EXTENSION, '')
+        .replace(/\//g, '__')
+        .replace(/\[([^\]]+)\]/g, '_$1_');
+}
+/** Qué clase de entrada es, según dónde vive el archivo. */
+function classifyEntry(sourceFile, pagesDir = 'app/pages') {
+    const relative = stripPagesDir(sourceFile, pagesDir);
+    if (relative.startsWith('api/'))
+        return 'api';
+    if (/(^|\/)_error(\.|\/)|(^|\/)error\//.test(relative))
+        return 'error';
+    return 'page';
+}
+function stripPagesDir(sourceFile, pagesDir) {
+    const normalized = sourceFile.replace(/\\/g, '/');
+    const marker = pagesDir.replace(/\\/g, '/').replace(/\/$/, '') + '/';
+    const index = normalized.indexOf(marker);
+    return index === -1 ? normalized.replace(/^\//, '') : normalized.slice(index + marker.length);
+}

package/dist/routes/rank.d.ts

@@ -0,0 +1,12 @@
+import type { RouteEntry, RouteSegment } from './types';
+/** Clave de comparación de una ruta: la especificidad de cada segmento, en orden. */
+export declare function computeRank(segments: readonly RouteSegment[]): number[];
+/**
+ * Orden en que se prueban las rutas.
+ *
+ * Se compara segmento a segmento; el primero que difiere decide. A igual
+ * especificidad gana la más larga —describe más de la URL— y, si aún empatan, el
+ * orden alfabético del patrón, para que el resultado no dependa de en qué orden
+ * el sistema de archivos devolvió los nombres.
+ */
+export declare function compareEntries(a: RouteEntry, b: RouteEntry): number;

package/dist/routes/rank.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRank = computeRank;
+exports.compareEntries = compareEntries;
+/**
+ * Cuán específico es cada tipo de segmento. Menor gana.
+ *
+ * Un literal describe una sola URL; un parámetro, todas las de su posición; un
+ * catch-all, todas las que empiecen igual. Ordenar por esto es lo que hace que
+ * `/users/nuevo` gane sobre `/users/[id]` sin que nadie declare la prioridad.
+ */
+const KIND_RANK = {
+    static: 0,
+    dynamic: 1,
+    catchAll: 2,
+    optionalCatchAll: 3,
+};
+/** Clave de comparación de una ruta: la especificidad de cada segmento, en orden. */
+function computeRank(segments) {
+    return segments.map((s) => KIND_RANK[s.kind]);
+}
+/**
+ * Orden en que se prueban las rutas.
+ *
+ * Se compara segmento a segmento; el primero que difiere decide. A igual
+ * especificidad gana la más larga —describe más de la URL— y, si aún empatan, el
+ * orden alfabético del patrón, para que el resultado no dependa de en qué orden
+ * el sistema de archivos devolvió los nombres.
+ */
+function compareEntries(a, b) {
+    const length = Math.min(a.rank.length, b.rank.length);
+    for (let i = 0; i < length; i++) {
+        if (a.rank[i] !== b.rank[i])
+            return a.rank[i] - b.rank[i];
+    }
+    if (a.rank.length !== b.rank.length) {
+        const [corta, larga] = a.rank.length < b.rank.length ? [a, b] : [b, a];
+        const extra = larga.rank[corta.rank.length];
+        // Un catch-all opcional puede no consumir nada, así que la ruta que lo lleva
+        // atiende también todo lo que atiende la corta: es la más general de las dos.
+        // Sin esto, `/users/[id]/[[...rest]]` se probaría antes que `/users/[id]` y
+        // esta última quedaría inalcanzable.
+        if (extra === KIND_RANK.optionalCatchAll)
+            return corta === a ? -1 : 1;
+        // En cualquier otro caso, la más larga describe más de la URL.
+        return b.rank.length - a.rank.length;
+    }
+    return a.pattern.localeCompare(b.pattern);
+}

package/dist/routes/router.d.ts

@@ -0,0 +1,54 @@
+import { Router, type RequestHandler } from 'express';
+import { type MiddlewareInfo, type PageModule } from '../helpers/middlewares';
+import { type IsrRuntime } from '../isr/handler';
+import type { ModuleLoader } from '../runtime/module-loader';
+import type { RouteEntry, RouteManifest } from './types';
+export interface ChainContext {
+    moduleLoader?: ModuleLoader;
+    /**
+     * Middlewares que registró el build. Si están, la cadena se arma con ellos y
+     * no se busca en el sistema de archivos; `buildRouterState` los toma del
+     * manifest.
+     */
+    middlewares?: readonly MiddlewareInfo[];
+    renderOptions: {
+        enablePlatformDetection: boolean;
+        renderFunction?: (options: {
+            url: string;
+            platform: string;
+            req: any;
+        }) => Promise<string>;
+        viteConfig: unknown;
+        security: unknown;
+    };
+    /** Caché incremental. Sin ella, una página `isr` se comporta como `ssr`. */
+    isr?: IsrRuntime;
+}
+/**
+ * La cadena de middlewares de una entrada.
+ *
+ * Es el cuerpo que estaba duplicado entre los dos constructores de router del
+ * modelo anterior: lo que hace un middleware de carpeta, `getServerSideProps` y
+ * el render, en ese orden. Tenerlo una vez es lo que garantiza que los dos
+ * caminos se comporten igual.
+ */
+export declare function buildChain(entry: RouteEntry, ctx: ChainContext, preloaded?: PageModule | null): Promise<RequestHandler[]>;
+export interface RessRouterState {
+    manifest: RouteManifest;
+    chains: Map<string, RequestHandler[]>;
+}
+/**
+ * Construye el estado de ruteo: el manifest más la cadena de cada entrada.
+ *
+ * Se arma entero y se devuelve entero, de modo que reemplazarlo en desarrollo
+ * sea una sola asignación y ninguna petición vea una mezcla de dos versiones.
+ */
+export declare function buildRouterState(manifest: RouteManifest, ctx: ChainContext): Promise<RessRouterState>;
+/**
+ * El router de páginas.
+ *
+ * Un solo despachador para todas las rutas y un solo manejador de errores, que
+ * sabe qué ruta falló porque el despachador lo dejó en la petición. El modelo
+ * anterior registraba un manejador por página.
+ */
+export declare function createPageRouter(getState: () => RessRouterState, ctx: ChainContext): Router;