@ressjs/vite-router 0.5.0 → 0.6.0-experimental.0

package/dist/config/watch.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedConfig } from './types';
+/**
+ * Recarga de la configuración en desarrollo.
+ *
+ * Se observa la carpeta `config/`: cualquiera de sus capas, no sólo la del modo
+ * activo, porque `default` y `local` también participan de la fusión.
+ */
+/**
+ * Claves que se pueden aplicar sin reiniciar.
+ *
+ * Todas se consultan al atender una petición, así que la siguiente ya ve el
+ * valor nuevo.
+ */
+export declare const HOT_KEYS: readonly ["redirects", "rewrites", "headers", "trailingSlash"];
+/**
+ * Claves que exigen reiniciar, y por qué.
+ *
+ * El framework lo dice nombrando la clave en vez de aplicar la mitad de la
+ * configuración: media configuración aplicada es un estado que nadie declaró y
+ * que produce errores que no se corresponden con ningún archivo.
+ */
+export declare const RESTART_REASONS: Record<string, string>;
+/** Qué claves de primer nivel cambiaron entre dos configuraciones resueltas. */
+export declare function changedKeys(previous: ResolvedConfig, next: ResolvedConfig): string[];
+/** El motivo del reinicio, o nada si todo lo que cambió se aplica en caliente. */
+export declare function restartReason(changed: readonly string[]): string | undefined;
+/** ¿Este archivo es una capa de configuración del proyecto? */
+export declare function isConfigLayer(file: string, root: string): boolean;
+export interface WatchConfigOptions {
+    root: string;
+    mode: string;
+    /** La configuración vigente, para comparar contra la nueva. */
+    current: () => ResolvedConfig;
+    /** Qué hacer con la configuración nueva cuando se puede aplicar en caliente. */
+    onReload: (config: ResolvedConfig) => void;
+    /** Qué hacer cuando hace falta reiniciar. Por defecto, pedírselo a Vite. */
+    onRestart?: (reason: string) => void;
+    log?: (message: string) => void;
+}
+/** Conecta el observador de Vite con la carpeta de configuración. */
+export declare function watchConfig(server: any, options: WatchConfigOptions): void;

package/dist/config/watch.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESTART_REASONS = exports.HOT_KEYS = void 0;
+exports.changedKeys = changedKeys;
+exports.restartReason = restartReason;
+exports.isConfigLayer = isConfigLayer;
+exports.watchConfig = watchConfig;
+const config_1 = require("@ressjs/config");
+const load_1 = require("./load");
+/**
+ * Recarga de la configuración en desarrollo.
+ *
+ * Se observa la carpeta `config/`: cualquiera de sus capas, no sólo la del modo
+ * activo, porque `default` y `local` también participan de la fusión.
+ */
+/**
+ * Claves que se pueden aplicar sin reiniciar.
+ *
+ * Todas se consultan al atender una petición, así que la siguiente ya ve el
+ * valor nuevo.
+ */
+// `security` no está acá: se carga y se valida, pero el pipeline de petición
+// todavía no la lee (ver el comentario en `config/types.ts`), así que no hay
+// nada que reaplicar en caliente cuando cambia.
+exports.HOT_KEYS = ['redirects', 'rewrites', 'headers', 'trailingSlash'];
+/**
+ * Claves que exigen reiniciar, y por qué.
+ *
+ * El framework lo dice nombrando la clave en vez de aplicar la mitad de la
+ * configuración: media configuración aplicada es un estado que nadie declaró y
+ * que produce errores que no se corresponden con ningún archivo.
+ */
+exports.RESTART_REASONS = {
+    basePath: 'cambia la URL bajo la que se sirve todo, incluidos los artefactos ya emitidos',
+    extensions: 'cambia qué archivos son páginas, y eso redefine el catálogo de entradas',
+    platform: 'redefine los ejes de plataforma, y con ellos las variantes que se construyen',
+    publicEnv: 'las variables se reemplazan en tiempo de build, no al atender una petición',
+    assets: 'el índice de artefactos se arma una vez, con el prefijo vigente al arrancar',
+    dev: 'son opciones del servidor de desarrollo, que ya está escuchando',
+    // F-033: `beforeRouter`/`afterRouter` se montan una vez, al construir la
+    // aplicación de servidor. Tratar su cambio como aplicable en caliente
+    // dejaría un "recargado" en el log sin ningún efecto real.
+    server: 'los middlewares de la vía de escape se montan una sola vez, al construir el servidor',
+};
+/** Qué claves de primer nivel cambiaron entre dos configuraciones resueltas. */
+function changedKeys(previous, next) {
+    const keys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+    const changed = [];
+    for (const key of keys) {
+        const a = stable(previous[key]);
+        const b = stable(next[key]);
+        if (a !== b)
+            changed.push(key);
+    }
+    return changed.sort();
+}
+/**
+ * Serialización estable para comparar.
+ *
+ * Las claves de un objeto se ordenan: dos configuraciones equivalentes escritas
+ * en distinto orden no son un cambio, y tratarlas como tal reiniciaría el
+ * servidor por nada.
+ */
+function stable(value) {
+    if (typeof value === 'function')
+        return `fn:${String(value)}`;
+    if (value === undefined)
+        return 'undefined';
+    return JSON.stringify(value, (_key, inner) => {
+        if (typeof inner === 'function')
+            return `fn:${String(inner)}`;
+        if (inner && typeof inner === 'object' && !Array.isArray(inner)) {
+            return Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return inner;
+    });
+}
+/** El motivo del reinicio, o nada si todo lo que cambió se aplica en caliente. */
+function restartReason(changed) {
+    for (const key of changed) {
+        const reason = exports.RESTART_REASONS[key];
+        if (reason)
+            return `\`${key}\`: ${reason}`;
+    }
+    return undefined;
+}
+/** ¿Este archivo es una capa de configuración del proyecto? */
+function isConfigLayer(file, root) {
+    const normalized = file.replace(/\\/g, '/');
+    const base = root.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (!normalized.startsWith(base + '/'))
+        return false;
+    const relative = normalized.slice(base.length + 1);
+    return /^config\/[^/]+$/.test(relative) || /^config\.[^/]+$/.test(relative);
+}
+/** Conecta el observador de Vite con la carpeta de configuración. */
+function watchConfig(server, options) {
+    const log = options.log ?? ((message) => console.log(message));
+    const restart = options.onRestart ??
+        ((reason) => {
+            log(`[ress] Reiniciando: ${reason}`);
+            void server?.restart?.();
+        });
+    const onChange = async (file) => {
+        if (!isConfigLayer(file, options.root))
+            return;
+        // Lo resuelto se descarta entero: la fusión depende de todas las capas, así
+        // que un cambio en cualquiera de ellas invalida el resultado.
+        (0, config_1.invalidateConfig)();
+        let next;
+        try {
+            next = await (0, load_1.loadConfig)(options.root, options.mode);
+        }
+        catch (error) {
+            // Un archivo a medio escribir no tiene que voltear el servidor: se informa
+            // y se sigue con la configuración anterior hasta que vuelva a guardarse.
+            log(`[ress] La configuración no se pudo cargar: ${error.message}`);
+            return;
+        }
+        const changed = changedKeys(options.current(), next);
+        if (changed.length === 0)
+            return;
+        const reason = restartReason(changed);
+        if (reason)
+            return restart(reason);
+        options.onReload(next);
+        log(`[ress] Configuración recargada: ${changed.join(', ')}`);
+    };
+    for (const event of ['add', 'change', 'unlink']) {
+        server?.watcher?.on(event, (file) => void onChange(file));
+    }
+}

package/dist/fs/module-extensions.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Qué extensiones acepta el framework, declarado una sola vez.
+ *
+ * Antes cada punto del pipeline tenía su propia idea: el descubrimiento globeaba
+ * `.tsx` y `.jsx`, el render exigía `.tsx` y lanzaba con cualquier otra cosa, y
+ * la carga en producción ramificaba por extensión. El resultado era que un
+ * proyecto en JavaScript descubría sus páginas y reventaba al renderizarlas.
+ *
+ * Ninguna función de este módulo toca el sistema de archivos: son puras sobre
+ * cadenas, y por eso se pueden probar sin montar un proyecto.
+ */
+export declare const SCRIPT_EXTENSIONS: readonly [".tsx", ".ts", ".jsx", ".js"];
+export type ScriptExtension = (typeof SCRIPT_EXTENSIONS)[number];
+export interface ExtensionPolicy {
+    /** Extensiones válidas para un archivo de página. */
+    page: readonly ScriptExtension[];
+    /** Extensiones válidas para un archivo de middleware. */
+    middleware: readonly ScriptExtension[];
+    /** Extensión que produce el build. Siempre una sola. */
+    compiled: '.js';
+    /** Sufijos que se ignoran aunque la extensión coincida. */
+    ignoredSuffixes: readonly string[];
+}
+export declare const DEFAULT_EXTENSION_POLICY: ExtensionPolicy;
+/** `['.tsx','.ts']` → `{tsx,ts}`, la forma que entiende un glob. */
+export declare function globBrace(extensions: readonly ScriptExtension[]): string;
+export declare function pageGlob(policy: ExtensionPolicy, pagesDir?: string): string;
+export declare function middlewareGlobs(policy: ExtensionPolicy, pagesDir?: string): string[];
+/**
+ * La extensión de un archivo, si es una de las que el framework reconoce.
+ *
+ * Se compara en minúsculas: en macOS y Windows un `Index.TSX` es el mismo
+ * archivo, y rechazarlo por la capitalización sería un fallo incomprensible.
+ */
+export declare function scriptExtensionOf(file: string): ScriptExtension | undefined;
+export declare function isIgnoredModule(file: string, policy?: ExtensionPolicy): boolean;
+/**
+ * El archivo sin su extensión.
+ *
+ * Lanza en vez de devolver el path intacto: un archivo que llegó hasta acá sin
+ * una extensión reconocida es un error de configuración, y devolverlo tal cual
+ * lo convertiría en un fallo más adelante y más difícil de ubicar.
+ */
+export declare function stripScriptExtension(file: string): string;
+export declare function isPageFile(file: string, policy?: ExtensionPolicy): boolean;
+/**
+ * La ruta que un archivo de middleware protege.
+ *
+ * `pokedex/middlewares.tsx` protege `/pokedex`; `home/index.middlewares.js`
+ * protege `/home/index`. Antes esto se derivaba con una expresión que sólo
+ * recortaba `.ts` y `.js`, así que un middleware `.tsx` producía una ruta con la
+ * extensión adentro y no coincidía con ninguna página: no corría, y sin aviso.
+ */
+export declare function middlewareRoute(file: string, pagesDir?: string): string;
+export declare function isMiddlewareFile(file: string, policy?: ExtensionPolicy): boolean;
+/**
+ * Identificador de una página, sin su extensión ni el prefijo del directorio.
+ *
+ * Es la clave que comparten el catálogo de variantes y el manifest de rutas, así
+ * que dos archivos que sólo difieren en la extensión producen el mismo: es lo
+ * que permite detectar que ambos existen.
+ */
+export declare function pageIdOf(file: string, pagesDir?: string): string;
+/**
+ * Dónde queda un módulo después de compilarse.
+ *
+ * El build emite siempre `.js`, cualquiera sea la extensión de origen, y sanea
+ * los corchetes de los parámetros porque no pueden formar parte de un nombre de
+ * archivo en todos los sistemas.
+ */
+export declare function toCompiledPath(file: string, policy?: ExtensionPolicy, pagesDir?: string): string;
+/**
+ * Dos archivos que producen la misma página son ambiguos.
+ *
+ * Cuál gana dependería del orden en que el sistema de archivos los devolvió, y
+ * ese orden cambia entre sistemas. Mejor fallar al arrancar nombrando los dos.
+ */
+export declare function assertNoModuleCollision(files: readonly string[], pagesDir?: string, options?: {
+    strict?: boolean;
+}): void;
+export declare function setExtensionPolicy(policy: ExtensionPolicy): void;
+export declare function getExtensionPolicy(): ExtensionPolicy;

package/dist/fs/module-extensions.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Qué extensiones acepta el framework, declarado una sola vez.
+ *
+ * Antes cada punto del pipeline tenía su propia idea: el descubrimiento globeaba
+ * `.tsx` y `.jsx`, el render exigía `.tsx` y lanzaba con cualquier otra cosa, y
+ * la carga en producción ramificaba por extensión. El resultado era que un
+ * proyecto en JavaScript descubría sus páginas y reventaba al renderizarlas.
+ *
+ * Ninguna función de este módulo toca el sistema de archivos: son puras sobre
+ * cadenas, y por eso se pueden probar sin montar un proyecto.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXTENSION_POLICY = exports.SCRIPT_EXTENSIONS = void 0;
+exports.globBrace = globBrace;
+exports.pageGlob = pageGlob;
+exports.middlewareGlobs = middlewareGlobs;
+exports.scriptExtensionOf = scriptExtensionOf;
+exports.isIgnoredModule = isIgnoredModule;
+exports.stripScriptExtension = stripScriptExtension;
+exports.isPageFile = isPageFile;
+exports.middlewareRoute = middlewareRoute;
+exports.isMiddlewareFile = isMiddlewareFile;
+exports.pageIdOf = pageIdOf;
+exports.toCompiledPath = toCompiledPath;
+exports.assertNoModuleCollision = assertNoModuleCollision;
+exports.setExtensionPolicy = setExtensionPolicy;
+exports.getExtensionPolicy = getExtensionPolicy;
+exports.SCRIPT_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+exports.DEFAULT_EXTENSION_POLICY = {
+    page: exports.SCRIPT_EXTENSIONS,
+    middleware: exports.SCRIPT_EXTENSIONS,
+    compiled: '.js',
+    // Un `.d.ts` declara tipos: nunca es un módulo que se pueda ejecutar.
+    ignoredSuffixes: ['.d.ts'],
+};
+/** `['.tsx','.ts']` → `{tsx,ts}`, la forma que entiende un glob. */
+function globBrace(extensions) {
+    if (extensions.length === 0) {
+        throw new Error('[ress] La política de extensiones quedó vacía. ' +
+            `Declará al menos una de: ${exports.SCRIPT_EXTENSIONS.join(', ')}.`);
+    }
+    const bare = extensions.map((e) => e.slice(1));
+    return bare.length === 1 ? bare[0] : `{${bare.join(',')}}`;
+}
+function pageGlob(policy, pagesDir = 'app/pages') {
+    return `${pagesDir.replace(/\\/g, '/')}/**/*.${globBrace(policy.page)}`;
+}
+function middlewareGlobs(policy, pagesDir = 'app/pages') {
+    const ext = globBrace(policy.middleware);
+    const normalizedPagesDir = pagesDir.replace(/\\/g, '/');
+    return [`${normalizedPagesDir}/**/middlewares.${ext}`, `${normalizedPagesDir}/**/*.middlewares.${ext}`];
+}
+/**
+ * La extensión de un archivo, si es una de las que el framework reconoce.
+ *
+ * Se compara en minúsculas: en macOS y Windows un `Index.TSX` es el mismo
+ * archivo, y rechazarlo por la capitalización sería un fallo incomprensible.
+ */
+function scriptExtensionOf(file) {
+    const lower = file.toLowerCase();
+    // De más larga a más corta: `.tsx` termina en `x`, no en `.ts`, pero el orden
+    // deja explícito que la comparación no es ambigua.
+    return exports.SCRIPT_EXTENSIONS.find((ext) => lower.endsWith(ext));
+}
+function isIgnoredModule(file, policy = exports.DEFAULT_EXTENSION_POLICY) {
+    const lower = file.toLowerCase();
+    return policy.ignoredSuffixes.some((suffix) => lower.endsWith(suffix.toLowerCase()));
+}
+/**
+ * El archivo sin su extensión.
+ *
+ * Lanza en vez de devolver el path intacto: un archivo que llegó hasta acá sin
+ * una extensión reconocida es un error de configuración, y devolverlo tal cual
+ * lo convertiría en un fallo más adelante y más difícil de ubicar.
+ */
+function stripScriptExtension(file) {
+    const ext = scriptExtensionOf(file);
+    if (!ext) {
+        throw new Error(`[ress] "${file}" no tiene una extensión que el framework reconozca. ` +
+            `Válidas: ${exports.SCRIPT_EXTENSIONS.join(', ')}.`);
+    }
+    return file.slice(0, -ext.length);
+}
+/**
+ * Archivos que viven junto a las páginas sin ser una.
+ *
+ * Hace falta desde que la política acepta `.ts` y `.js`: un archivo suelto ahí
+ * es casi siempre un ayudante —un cliente de API, un tipo compartido, un test— y
+ * tomarlo por una ruta produce una URL que existe y falla al renderizar, porque
+ * no exporta ningún componente.
+ */
+const NOT_A_PAGE = /(^|\/)middlewares\.[^.]+$|\.(middlewares|test|spec)\.[^.]+$|(^|\/)_/;
+function isPageFile(file, policy = exports.DEFAULT_EXTENSION_POLICY) {
+    if (isIgnoredModule(file, policy))
+        return false;
+    if (NOT_A_PAGE.test('/' + normalize(file)))
+        return false;
+    const ext = scriptExtensionOf(file);
+    return ext !== undefined && policy.page.includes(ext);
+}
+/**
+ * La ruta que un archivo de middleware protege.
+ *
+ * `pokedex/middlewares.tsx` protege `/pokedex`; `home/index.middlewares.js`
+ * protege `/home/index`. Antes esto se derivaba con una expresión que sólo
+ * recortaba `.ts` y `.js`, así que un middleware `.tsx` producía una ruta con la
+ * extensión adentro y no coincidía con ninguna página: no corría, y sin aviso.
+ */
+function middlewareRoute(file, pagesDir = 'app/pages') {
+    const relative = stripScriptExtension(relativeToPages(file, pagesDir));
+    return '/' + relative.replace(/\.middlewares$/, '').replace(/\/?middlewares$/, '');
+}
+function isMiddlewareFile(file, policy = exports.DEFAULT_EXTENSION_POLICY) {
+    if (isIgnoredModule(file, policy))
+        return false;
+    const ext = scriptExtensionOf(file);
+    if (!ext || !policy.middleware.includes(ext))
+        return false;
+    const name = normalize(file).split('/').pop() ?? '';
+    return name.startsWith('middlewares.') || name.includes('.middlewares.');
+}
+/**
+ * Identificador de una página, sin su extensión ni el prefijo del directorio.
+ *
+ * Es la clave que comparten el catálogo de variantes y el manifest de rutas, así
+ * que dos archivos que sólo difieren en la extensión producen el mismo: es lo
+ * que permite detectar que ambos existen.
+ */
+function pageIdOf(file, pagesDir = 'app/pages') {
+    const relative = relativeToPages(file, pagesDir);
+    return stripScriptExtension(relative);
+}
+/**
+ * Dónde queda un módulo después de compilarse.
+ *
+ * El build emite siempre `.js`, cualquiera sea la extensión de origen, y sanea
+ * los corchetes de los parámetros porque no pueden formar parte de un nombre de
+ * archivo en todos los sistemas.
+ */
+function toCompiledPath(file, policy = exports.DEFAULT_EXTENSION_POLICY, pagesDir = 'app/pages') {
+    // `stripScriptExtension` lanza si no reconoce la extensión, que es lo correcto:
+    // devolver el nombre intacto producía `foo.mjs` → `foo.mjs.js`, un artefacto
+    // que no existe y cuyo fallo aparece recién al importarlo en producción.
+    const relative = stripScriptExtension(relativeToPages(file, pagesDir));
+    return relative.replace(/\[([^\]]+)\]/g, '_$1_') + policy.compiled;
+}
+/**
+ * Dos archivos que producen la misma página son ambiguos.
+ *
+ * Cuál gana dependería del orden en que el sistema de archivos los devolvió, y
+ * ese orden cambia entre sistemas. Mejor fallar al arrancar nombrando los dos.
+ */
+function assertNoModuleCollision(files, pagesDir = 'app/pages', options = {}) {
+    const byId = new Map();
+    for (const file of files) {
+        const id = pageIdOf(file, pagesDir);
+        const previous = byId.get(id);
+        if (previous) {
+            const message = `[ress] "${previous}" y "${file}" definen la misma página. ` +
+                'Cuál gana dependería del orden del sistema de archivos, que cambia entre ' +
+                'sistemas operativos. Dejá uno solo.';
+            // Al construir es un error; en desarrollo se avisa y se sigue con el
+            // primero, para no dejar el servidor caído mientras alguien renombra.
+            if (options.strict)
+                throw new Error(message);
+            console.warn(`${message}\nPor ahora responde "${previous}".`);
+            continue;
+        }
+        byId.set(id, file);
+    }
+}
+/** Los separadores de Windows se normalizan: el resto del framework usa `/`. */
+function normalize(file) {
+    return file.replace(/\\/g, '/');
+}
+function relativeToPages(file, pagesDir) {
+    const normalized = normalize(file);
+    const marker = normalize(pagesDir).replace(/\/$/, '') + '/';
+    const index = normalized.indexOf(marker);
+    return index === -1 ? normalized.replace(/^\//, '') : normalized.slice(index + marker.length);
+}
+/**
+ * Política vigente del proceso.
+ *
+ * El descubrimiento corre en varios lugares que no reciben opciones —el
+ * catálogo, el escaneo de rutas, la carga de middlewares—, así que el plugin la
+ * fija una vez al resolver la configuración y todos leen la misma.
+ */
+let current = exports.DEFAULT_EXTENSION_POLICY;
+function setExtensionPolicy(policy) {
+    current = policy;
+}
+function getExtensionPolicy() {
+    return current;
+}

package/dist/helpers/html-generator.d.ts

@@ -1,14 +1,31 @@
-import { PlatformInfo } from '../platform';
+import { type PlatformInfo } from '../platform';
+import { type SecurityContext } from '../security';
+import type { AssetIndex, VariantCatalog } from '../variants/types';
+export { resolvePageAssets } from '@ressjs/assets';
+/**
+ * Qué archivos servirle a esta plataforma: elige la variante y busca sus artefactos.
+ *
+ * Son dos consultas en memoria. El catálogo ya está armado y los artefactos ya
+ * están indexados desde que arrancó el servidor, así que servir una página no
+ * toca el sistema de archivos ni escribe nada.
+ *
+ * Si la variante elegida no tiene artefactos construidos, responde los de la
+ * base antes que no responder nada.
+ */
 export interface HTMLGenerationContext {
     template: string;
     rendered: any;
     page: any;
-    manifest: any;
     platform: string;
     isProduction: boolean;
     platformInfo: PlatformInfo | null;
     serverSideResult?: any;
+    catalog?: VariantCatalog;
+    assets?: AssetIndex;
+    /** Request-scoped links prepared before rendering (and overridable by middleware). */
+    styles?: {
+        js: string;
+        css: string[];
+    };
 }
-export declare function generateClientScript(pageFile: string, platformInfo: PlatformInfo | null, manifest: any, isProduction: boolean): Promise<string | null>;
-export declare function generateClientCSS(pageFile: string, platformInfo: PlatformInfo | null, manifest: any, isProduction: boolean): string;
-export declare function generateCompleteHTML(context: HTMLGenerationContext): Promise<string>;
+export declare function generateCompleteHTML(context: HTMLGenerationContext, security?: SecurityContext): Promise<string>;