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

package/dist/plugin/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Plugin de ress.js para Vite.
+ *
+ * Único punto de entrada de configuración para un proyecto:
+ *
+ * ```ts
+ * import { defineConfig } from 'vite'
+ * import { ressPlugin } from '@ressjs/vite-router/plugin'
+ *
+ * export default defineConfig({ plugins: [ressPlugin()] })
+ * ```
+ */
+import { defineEnvironments, OUT_DIR } from './environments';
+import type { VariantCatalog } from '../variants/types';
+import { type ExtensionPolicy } from '../fs/module-extensions';
+import { type BuildOutputBundle } from './route-manifest';
+import { type SecurityOptions } from '../security';
+/**
+ * El tipo `Plugin` de Vite se declara estructuralmente en vez de importarse,
+ * para que este paquete no dependa del tipo en tiempo de compilación. Vite es
+ * una dependencia entre pares: el consumidor la aporta.
+ */
+export interface RessPlugin {
+    name: string;
+    /** Opcional: el guard de `@ressjs/config` sólo aporta `resolveId`. */
+    config?: (userConfig: unknown, env: {
+        command: string;
+        mode: string;
+    }) => Promise<unknown> | unknown;
+    resolveId?: (id: string, importer?: string, options?: unknown) => string | undefined | null;
+    load?: (id: string) => string | undefined;
+    configureServer?: (server: any) => void;
+    writeBundle?: (this: {
+        environment?: {
+            name?: string;
+        };
+    }, options: unknown, bundle: BuildOutputBundle) => Promise<void> | void;
+}
+export declare function getVariantCatalog(): VariantCatalog | undefined;
+export declare function refreshVariantCatalog(): Promise<VariantCatalog>;
+export interface RessPluginOptions {
+    security?: SecurityOptions;
+    /**
+     * Qué extensiones acepta el proyecto. Se fusiona sobre los defaults una vez al
+     * arrancar. F-008 la absorbe cuando exista el archivo de configuración.
+     */
+    extensions?: Partial<ExtensionPolicy>;
+}
+/**
+ * El plugin del framework.
+ *
+ * Devuelve dos: el propio y el guard que impide que `@ressjs/config` —valores de
+ * servidor, credenciales incluidas— termine en el paquete del navegador. El
+ * segundo no se agrega a mano justamente porque olvidarse es el modo de fallo que
+ * existe para evitar.
+ */
+export declare function ressPlugin(options?: RessPluginOptions): RessPlugin[];
+export declare function ressCorePlugin(options?: RessPluginOptions): RessPlugin;
+export { defineEnvironments, OUT_DIR };

package/dist/plugin/index.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Plugin de ress.js para Vite.
+ *
+ * Único punto de entrada de configuración para un proyecto:
+ *
+ * ```ts
+ * import { defineConfig } from 'vite'
+ * import { ressPlugin } from '@ressjs/vite-router/plugin'
+ *
+ * export default defineConfig({ plugins: [ressPlugin()] })
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUT_DIR = exports.defineEnvironments = void 0;
+exports.getVariantCatalog = getVariantCatalog;
+exports.refreshVariantCatalog = refreshVariantCatalog;
+exports.ressPlugin = ressPlugin;
+exports.ressCorePlugin = ressCorePlugin;
+const environments_1 = require("./environments");
+Object.defineProperty(exports, "defineEnvironments", { enumerable: true, get: function () { return environments_1.defineEnvironments; } });
+Object.defineProperty(exports, "OUT_DIR", { enumerable: true, get: function () { return environments_1.OUT_DIR; } });
+const pages_1 = require("../pages");
+const catalog_1 = require("../variants/catalog");
+const virtual_entries_1 = require("./virtual-entries");
+const scan_1 = require("../routes/scan");
+const middlewares_1 = require("../helpers/middlewares");
+const module_extensions_1 = require("../fs/module-extensions");
+const manifest_1 = require("../routes/manifest");
+const route_manifest_1 = require("./route-manifest");
+const security_1 = require("../security");
+const config_1 = require("@ressjs/config");
+const config_2 = require("../config");
+/**
+ * Catálogo vigente del proceso.
+ *
+ * Se arma una vez y lo comparten el build y el servidor: es lo que garantiza que
+ * las entradas que se construyen y las que se resuelven por petición salgan de la
+ * misma fuente.
+ */
+let current;
+function getVariantCatalog() {
+    return current;
+}
+async function refreshVariantCatalog() {
+    current = await (0, catalog_1.buildVariantCatalog)({ pages: (0, pages_1.getPages)() });
+    return current;
+}
+async function resolveInputs() {
+    const catalog = await refreshVariantCatalog();
+    return {
+        client: (0, virtual_entries_1.clientBuildInputs)(catalog),
+        ssr: (0, pages_1.getViteSSRInput)(),
+    };
+}
+/**
+ * El plugin del framework.
+ *
+ * Devuelve dos: el propio y el guard que impide que `@ressjs/config` —valores de
+ * servidor, credenciales incluidas— termine en el paquete del navegador. El
+ * segundo no se agrega a mano justamente porque olvidarse es el modo de fallo que
+ * existe para evitar.
+ */
+function ressPlugin(options = {}) {
+    return [ressCorePlugin(options), (0, config_1.configServerOnlyGuard)()];
+}
+function ressCorePlugin(options = {}) {
+    // Se recalcula en el hook `config`, después de `loadConfig`: hasta ese
+    // momento no se leyó `config.security`, así que acá sólo hay defaults.
+    let security = (0, security_1.resolveSecurityOptions)(options.security);
+    /** Raíz del proyecto según Vite; puede no ser el directorio de trabajo. */
+    let root = process.cwd();
+    let manifestWritten = false;
+    let extensions = { ...module_extensions_1.DEFAULT_EXTENSION_POLICY, ...options.extensions };
+    /** La configuración del proyecto, vigente desde el hook `config`. */
+    let config;
+    return {
+        name: 'ress',
+        /**
+         * Se aporta desde `config` y no desde `configResolved` para que la
+         * configuración del usuario se fusione encima siguiendo las reglas normales
+         * de Vite, en vez de ser sobrescrita por el framework.
+         */
+        async config(userConfig, env) {
+            // Se verifica acá, con la configuración del proyecto ya visible y antes de
+            // que el servidor escuche. Un aviso en la consola de un servidor de
+            // desarrollo no lo lee nadie; un error de arranque sí.
+            root = userConfig?.root ?? process.cwd();
+            // La configuración del proyecto se lee antes que nada: declara qué
+            // extensiones son código de usuario, bajo qué prefijo se sirve todo y qué
+            // variables llegan al navegador, y las tres decisiones condicionan lo que
+            // este hook devuelve.
+            config = await (0, config_2.loadConfig)(root, env?.mode ?? 'development');
+            extensions = { ...extensions, ...config.extensions };
+            // `config.security` es lo que declara el proyecto; sólo se pisa si quien
+            // arma el plugin aportó algo explícito.
+            security = (0, security_1.resolveSecurityOptions)(options.security ?? config.security);
+            await (0, config_2.writeProjectTypes)(root, config.platform);
+            // Se fija acá y no al construir el plugin: `current` es estado global del
+            // proceso, así que crear un objeto de plugin —dos configuraciones en un
+            // mismo proceso, un test que lo importa— reescribiría la política que leen
+            // el descubrimiento y el escaneo de rutas.
+            (0, module_extensions_1.setExtensionPolicy)(extensions);
+            if (env?.command === 'serve')
+                (0, security_1.assertDevServerHardening)(userConfig);
+            return {
+                ...(0, environments_1.defineEnvironments)(await resolveInputs()),
+                // Sólo al construir: en desarrollo el prefijo lo quita el pipeline de
+                // petición antes de que Vite vea la URL, así que su `base` sigue siendo
+                // `/`. Al construir sí tiene que quedar escrito en las referencias que
+                // los artefactos hacen entre sí.
+                ...(config.basePath && env?.command === 'build'
+                    ? { base: config.basePath + '/' }
+                    : {}),
+                // Sólo lo declarado en `publicEnv`. Lo demás no queda como `undefined`
+                // en el navegador: queda como código que nunca se generó.
+                ...(config.publicEnv.length
+                    ? { define: (0, config_2.publicEnvDefines)(config.publicEnv, { strict: env?.command === 'build' }) }
+                    : {}),
+                ...(env?.command === 'serve'
+                    ? { server: (0, security_1.devServerDefaults)(security.dev.allowedOrigins) }
+                    : {}),
+            };
+        },
+        /**
+         * Emite el manifest de rutas junto al build.
+         *
+         * Cargarlo en producción es lo que evita volver a recorrer el sistema de
+         * archivos en cada arranque para deducir algo que ya no puede cambiar.
+         *
+         * El hook corre una vez por entorno —cliente y servidor— y el manifest es
+         * el mismo para los dos, así que se escribe una sola vez.
+         */
+        async writeBundle(_options, bundle) {
+            // El cliente se construye primero, pero sólo el entorno SSR conoce los
+            // chunks que hay que registrar. Escribir durante el cliente dejaba un
+            // manifest válido en apariencia pero imposible de usar para cargar prod.
+            if (this.environment?.name !== 'ssr' || manifestWritten)
+                return;
+            manifestWritten = true;
+            const { writeFile, mkdir } = await import('node:fs/promises');
+            const path = await import('node:path');
+            const scanned = await (0, scan_1.scanRoutes)({
+                strict: true,
+                root,
+                pagesDir: path.join(root, 'app/pages'),
+            });
+            const data = (0, route_manifest_1.attachServerBuildChunks)({ ...scanned, middlewares: (0, middlewares_1.getMiddlewares)({ cwd: root }).map(middlewares_1.toMiddlewareEntry) }, bundle, root);
+            const target = path.resolve(root, environments_1.OUT_DIR.base);
+            await mkdir(target, { recursive: true });
+            await writeFile(path.join(target, 'route-manifest.json'), (0, manifest_1.serializeRouteManifest)(data), 'utf-8');
+            // Identifica este build. La caché incremental lo usa en la clave: un
+            // documento generado por otro build puede apuntar a artefactos que ya no
+            // existen, y la hidratación rota que produce no dice de dónde viene.
+            const { randomUUID } = await import('node:crypto');
+            await writeFile(path.join(target, environments_1.BUILD_ID_FILE), randomUUID(), 'utf-8');
+        },
+        resolveId(id) {
+            return (0, virtual_entries_1.resolveEntryId)(id);
+        },
+        load(id) {
+            const parsed = (0, virtual_entries_1.parseEntryId)(id);
+            if (!parsed || !current)
+                return undefined;
+            return (0, virtual_entries_1.generateEntryModule)(current, parsed.pageId, parsed.suffix);
+        },
+        /**
+         * Rearma el catálogo cuando cambia el **conjunto** de archivos, no su
+         * contenido: agregar o borrar una hoja de estilos cambia qué variantes
+         * declara una página, y eso tiene que reflejarse sin reiniciar. Los cambios
+         * de contenido los maneja la recarga en caliente de Vite.
+         */
+        configureServer(server) {
+            const declaresVariants = (file) => file.includes('app/pages/') || file.includes('app\\pages\\');
+            const rebuild = (file) => {
+                if (declaresVariants(file))
+                    void refreshVariantCatalog();
+            };
+            server.watcher?.on('add', rebuild);
+            server.watcher?.on('unlink', rebuild);
+            // Las dos superficies de configuración. Observar sólo `ress.config` dejaba
+            // mudo el cambio de una capa de `config/`.
+            if (config) {
+                (0, config_2.watchConfig)(server, {
+                    root,
+                    mode: server.config?.mode ?? 'development',
+                    current: () => config,
+                    onReload: (next) => {
+                        config = next;
+                    },
+                });
+            }
+        },
+    };
+}

package/dist/plugin/route-manifest.d.ts

@@ -0,0 +1,19 @@
+import type { RouteManifestData } from '../routes/types';
+export interface BuildOutputChunk {
+    type: 'chunk';
+    fileName: string;
+    facadeModuleId?: string | null;
+    isEntry?: boolean;
+}
+export interface BuildOutputAsset {
+    type: 'asset';
+    fileName: string;
+}
+export type BuildOutput = BuildOutputChunk | BuildOutputAsset;
+export type BuildOutputBundle = Record<string, BuildOutput>;
+/**
+ * Completa el manifest con los nombres que el bundler emitió realmente.
+ * `facadeModuleId` une cada chunk de entrada con su fuente sin adivinar reglas
+ * de nombres ni depender de cómo Rolldown sanee segmentos dinámicos.
+ */
+export declare function attachServerBuildChunks(data: RouteManifestData, bundle: BuildOutputBundle, root: string): RouteManifestData;

package/dist/plugin/route-manifest.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachServerBuildChunks = attachServerBuildChunks;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Completa el manifest con los nombres que el bundler emitió realmente.
+ * `facadeModuleId` une cada chunk de entrada con su fuente sin adivinar reglas
+ * de nombres ni depender de cómo Rolldown sanee segmentos dinámicos.
+ */
+function attachServerBuildChunks(data, bundle, root) {
+    const chunksBySource = new Map();
+    for (const output of Object.values(bundle)) {
+        if (output.type !== 'chunk' || !output.isEntry || !output.facadeModuleId)
+            continue;
+        const source = normalizeAbsolute(output.facadeModuleId, root);
+        chunksBySource.set(source, portableRelativeChunk(output.fileName));
+    }
+    const entries = data.entries.map((entry) => {
+        const source = normalizeAbsolute(entry.sourceFile, root);
+        const buildChunk = chunksBySource.get(source);
+        if (!buildChunk) {
+            throw new Error(`[ress] El build SSR no emitió un chunk de entrada para "${entry.sourceFile}" ` +
+                `(pageId "${entry.pageId}").`);
+        }
+        return { ...entry, server: { ...entry.server, buildChunk } };
+    });
+    // Los middlewares, igual que las páginas: producción los carga por el chunk
+    // registrado, sin volver a mirar las fuentes. Si el build no emitió uno, el
+    // manifest no se publica: un middleware sin chunk dejaría su ruta abierta.
+    const middlewares = data.middlewares?.map((middleware) => {
+        const buildChunk = chunksBySource.get(normalizeAbsolute(middleware.file, root));
+        if (!buildChunk) {
+            throw new Error(`[ress] El build SSR no emitió un chunk de entrada para el middleware "${middleware.file}".`);
+        }
+        return { ...middleware, server: { ...middleware.server, buildChunk } };
+    });
+    return { ...data, entries, ...(middlewares ? { middlewares } : {}) };
+}
+function normalizeAbsolute(file, root) {
+    const clean = file.replace(/[?#].*$/, '');
+    return node_path_1.default.resolve(root, clean).replace(/\\/g, '/');
+}
+function portableRelativeChunk(fileName) {
+    const normalized = fileName.replace(/\\/g, '/');
+    if (normalized.startsWith('/') ||
+        /^[A-Za-z]:\//.test(normalized) ||
+        normalized === '..' ||
+        normalized.startsWith('../')) {
+        throw new Error(`[ress] El build SSR produjo un nombre de chunk no portable: "${fileName}".`);
+    }
+    return normalized;
+}

package/dist/plugin/virtual-entries.d.ts

@@ -0,0 +1,26 @@
+import type { VariantCatalog } from '../variants/types';
+declare const PREFIX = "ress:entry";
+declare const RESOLVED: string;
+/** ¿Es el identificador de una entrada de build del catálogo? */
+export declare function isEntryId(id: string): boolean;
+export declare function resolveEntryId(id: string): string | undefined;
+/** Extrae página y variante del identificador. */
+export declare function parseEntryId(id: string): {
+    pageId: string;
+    suffix: string;
+} | undefined;
+/**
+ * Genera el módulo de hidratación de una página en una variante.
+ *
+ * Se escribe con `createElement` y no con JSX a propósito: así el módulo no
+ * depende de la transformación JSX ni de una extensión concreta, que es lo que
+ * permite que una página escrita en JavaScript se hidrate con el mismo código
+ * que una escrita en TypeScript.
+ */
+export declare function generateEntryModule(catalog: VariantCatalog, pageId: string, variantSuffix: string): string;
+/**
+ * Qué le pasa el framework al empaquetador como entradas del entorno de cliente:
+ * una por página y variante, cada una apuntando a su módulo virtual.
+ */
+export declare function clientBuildInputs(catalog: VariantCatalog): Record<string, string>;
+export { PREFIX as ENTRY_PREFIX, RESOLVED as ENTRY_RESOLVED_PREFIX };

package/dist/plugin/virtual-entries.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTRY_RESOLVED_PREFIX = exports.ENTRY_PREFIX = void 0;
+exports.isEntryId = isEntryId;
+exports.resolveEntryId = resolveEntryId;
+exports.parseEntryId = parseEntryId;
+exports.generateEntryModule = generateEntryModule;
+exports.clientBuildInputs = clientBuildInputs;
+const node_path_1 = __importDefault(require("node:path"));
+const catalog_1 = require("../variants/catalog");
+const PREFIX = 'ress:entry';
+exports.ENTRY_PREFIX = PREFIX;
+const RESOLVED = '\0' + PREFIX;
+exports.ENTRY_RESOLVED_PREFIX = RESOLVED;
+/** ¿Es el identificador de una entrada de build del catálogo? */
+function isEntryId(id) {
+    return id.startsWith(PREFIX) || id.startsWith(RESOLVED);
+}
+function resolveEntryId(id) {
+    return id.startsWith(PREFIX) ? '\0' + id : undefined;
+}
+/** Extrae página y variante del identificador. */
+function parseEntryId(id) {
+    if (!id.startsWith(RESOLVED))
+        return undefined;
+    const query = id.slice(RESOLVED.length + 1); // salta el '?'
+    const params = new URLSearchParams(query);
+    const pageId = params.get('page');
+    if (!pageId)
+        return undefined;
+    return { pageId, suffix: params.get('variant') ?? '' };
+}
+/**
+ * Genera el módulo de hidratación de una página en una variante.
+ *
+ * Se escribe con `createElement` y no con JSX a propósito: así el módulo no
+ * depende de la transformación JSX ni de una extensión concreta, que es lo que
+ * permite que una página escrita en JavaScript se hidrate con el mismo código
+ * que una escrita en TypeScript.
+ */
+function generateEntryModule(catalog, pageId, variantSuffix) {
+    const page = catalog.pagesById.get(pageId);
+    if (!page) {
+        throw new Error(`[ress] No hay ninguna página con el identificador "${pageId}".`);
+    }
+    const variant = catalog.variantsByPage
+        .get(pageId)
+        ?.find((v) => v.suffix === variantSuffix);
+    if (!variant) {
+        throw new Error(`[ress] La página "${pageId}" no declara la variante "${variantSuffix || '(base)'}".`);
+    }
+    const pageAbs = node_path_1.default.resolve(page.pageFile).replace(/\\/g, '/');
+    const styleImport = variant.styleFile
+        ? `import ${JSON.stringify(node_path_1.default.resolve(variant.styleFile).replace(/\\/g, '/'))};\n`
+        : '';
+    return `${styleImport}import { hydrateRoot } from "react-dom/client";
+import { StrictMode, createElement } from "react";
+import Page from ${JSON.stringify(pageAbs)};
+
+const props = window.__RESS_PROPS__ || {};
+const root = document.getElementById("root");
+
+if (root) {
+  hydrateRoot(root, createElement(StrictMode, null, createElement(Page, props)));
+}
+`;
+}
+/**
+ * Qué le pasa el framework al empaquetador como entradas del entorno de cliente:
+ * una por página y variante, cada una apuntando a su módulo virtual.
+ */
+function clientBuildInputs(catalog) {
+    return Object.fromEntries(catalog.buildEntries.map((entry) => [
+        (0, catalog_1.buildEntryNameFor)(entry.pageId, entry.variant.suffix),
+        entry.virtualId,
+    ]));
+}

package/dist/render.d.ts

@@ -1,18 +1,55 @@
 import { RequestHandler } from 'express';
+import type { ModuleLoader } from './runtime/module-loader';
+import type { ClientPropsPolicy } from './security';
+import { type CollectedHeadTag } from '@ressjs/assets';
 /**
  * RENDER MIDDLEWARE PARA EL ROUTER
+ *
+ * El render server se arma una sola vez por ruta, en la primera petición, y
+ * se reusa en las siguientes. Antes se creaba en cada `processRequest` sin
+ * `renderServer`, y `createRenderServer` barría `app/pages` con `fast-glob`
+ * en cada request: cien peticiones, cien globs síncronos contra el
+ * filesystem en producción.
+ *
+ * La primera petición espera a que `viteConfig` (que puede llegar como thunk
+ * en modo automático) esté resuelto, así que armar el render server recién
+ * ahí, y no al declarar el middleware, es lo que garantiza que ya tenga el
+ * `moduleLoader` correcto.
  */
 export declare function createRenderMiddleware(page: any, options: any): RequestHandler;
 export interface RenderOptions {
     url: string;
+    /**
+     * La página que el despachador ya resolvió. Obligatoria.
+     *
+     * Antes era opcional y, sin ella, el render la buscaba por URL con un
+     * criterio propio que no conoce grupos ni catch-all, escaneando `app/pages`
+     * en cada petición. Quien llamaba a `createRenderServer()` sólo con `url`
+     * tiene que pasar la página resuelta: `{ url, page: { route, file } }`.
+     */
+    page: {
+        route: string;
+        file: string;
+        pageId?: string;
+        abs?: string;
+    };
     props?: any;
+    /** Estado que dejaron los middlewares. Sólo viaja al cliente lo que la política declara. */
+    locals?: Record<string, unknown>;
+    /** `false`: la página no hidrata, así que no hay estado que calcular para el cliente. */
+    hydrate?: boolean;
 }
 export interface CreateRenderServerOptions {
-    vite?: any;
+    /** Cargador de módulos. Ausente en producción: se importa el artefacto compilado. */
+    moduleLoader?: ModuleLoader;
+    /** Qué claves del estado del servidor viajan al cliente. */
+    clientProps?: ClientPropsPolicy;
+    isProduction?: boolean;
 }
 export declare function createRenderServer(options?: CreateRenderServerOptions): (renderOptions: RenderOptions) => Promise<{
     html: string;
-    props: any;
+    props: Record<string, unknown>;
+    head: CollectedHeadTag[];
     route: string;
     page: string;
 }>;