vanilla-jet 1.3.2 → 1.4.1

package/.github/workflows/deploy.yml

@@ -5,38 +5,45 @@ on:
     branches:
       - main
 
+permissions:
+  id-token: write
+  contents: write
+
 jobs:
   release:
     name: Publish
     runs-on: ubuntu-latest
-    environment: rep
 
     steps:
     - name: Check out the repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Setup Node.js
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
-        node-version: '16'
-        registry-url: 'https://registry.npmjs.org/'
+        node-version: '24'
+        registry-url: 'https://registry.npmjs.org'
 
     - name: Install dependencies
-      run: npm install
+      run: npm ci
+
+    - name: Build
+      run: npm run build --if-present
+
+    - name: Test
+      run: npm test
 
     - name: Publish to npm
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       run: npm publish
 
     - name: Configure git identity
       run: |
-        git config --global user.email "actions@github.com"
-        git config --global user.name "GitHub Actions"
+        git config user.email "actions@github.com"
+        git config user.name "GitHub Actions"
 
     - name: Get version from package.json
       id: get_version
-      run: echo "::set-output name=version::$(node -p "require('./package.json').version")"
+      run: echo "version=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"
 
     - name: Check if tag exists
       run: |

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable project changes are documented in this file.
+
+The format follows a structure inspired by Keep a Changelog and semantic versioning.
+
+## [1.4.1] - 2026-02-19
+
+### Highlights (v1.4.1)
+
+- Completed HU 2.1 (`Fast path de estaticos en Node`).
+- Optimized static serving in `framework/router.js`:
+  - Added warm-path static resolution cache (`route + accept-encoding`) to avoid repeated candidate resolution work.
+  - Added bounded metadata revalidation window for conditional requests to reduce repeated `fs.stat` pressure.
+  - Consolidated static header assembly and reused mime header maps.
+  - Kept stream-based delivery for large assets and tuned `createReadStream` chunk size.
+- Added reproducible local benchmark:
+  - New script: `npm run benchmark:static`.
+  - New guide: `docs/benchmark-static.md`.
+
+### Compatibility notes (v1.4.1)
+
+- No public API changes.
+- Preserves static conditional caching (`304`) and precompressed negotiation fallback.
+- No intended behavior changes for dynamic routes.
+
+## [1.3.6] - 2026-02-19
+
+### Highlights (v1.3.6)
+
+- Fixed protected directory typo in `framework/router.js`: `node_mudules` -> `node_modules`.
+- Fixed stability issues in `framework/dipper.js`:
+  - `includeAnimations()` now calls the existing `includeAnimation()`.
+  - `dequeueStyle()` and `dequeueScript()` now read `item.requires` correctly.
+  - Dependency dequeue now runs only when explicitly requested (`dependencies === true`).
+- Fixed `package.json` recursive `test` script to avoid infinite loop and keep `npm test` stable.
+- Completed HU 1.4 hardening milestone and updated roadmap tracking.
+
+### Compatibility notes (v1.3.6)
+
+- No public API changes.
+- No route contract changes.
+- This patch only hardens runtime behavior and developer workflow reliability.
+
+## [1.3.5] - 2026-02-19
+
+### Highlights (v1.3.5)
+
+- Added safe precompressed fallback in `response.render()` for HTML templates: `.br` (when enabled and accepted) -> `.gz` (when accepted) -> original HTML.
+- Wired `Response` to server profile options, so HTML negotiation follows `settings.profile.enable_precompressed_negotiation`.
+- Added `Vary: Accept-Encoding` for negotiated HTML responses and support for `Accept-Encoding` quality params.
+- Updated documentation and roadmap status for HU 1.3.
+
+## [1.3.4] - 2026-02-19
+
+### Highlights (v1.3.4)
+
+- Added optional static precompressed negotiation flag: `settings.profile.enable_precompressed_negotiation`.
+- Static files now resolve safely with fallback chain: `.br` (when enabled and accepted) -> `.gz` (when accepted) -> original file.
+- Static compression negotiation now handles `Accept-Encoding` values with quality params (for example `gzip;q=1.0`).
+- `Vary: Accept-Encoding` is set for negotiated static responses.
+
+## [1.3.3] - 2026-02-18
+
+### Added
+
+- Static metadata in-memory cache in `framework/router.js` (`size`, `lastModified`, `etag`) to reduce repeated filesystem work.
+- Conditional request handling for static files using `If-None-Match` and `If-Modified-Since`.
+- Static response headers: `ETag`, `Last-Modified`, and `Cache-Control: no-cache, must-revalidate`.
+
+### Changed
+
+- Static files can now return `304 Not Modified` when validators match, reducing transfer for repeated requests.
+- Conditional requests force metadata refresh before deciding `304`, so clients can still see new content without hard reload.
+
+### Compatibility notes
+
+- No route or filename contract changes.
+- No impact on dynamic endpoints behavior.
+
+## [1.3.2] - 2026-02-18
+
+### Current documented state
+
+- Released version `1.3.2` of `vanilla-jet`.
+- The framework exports `Server` from `index.js` for simple integration in Node.js projects.
+- Includes a Gulp-based build pipeline for:
+  - JavaScript minification and concatenation.
+  - LESS/CSS compilation and minification.
+  - HTML template compilation with Nunjucks.
+  - Generation of compressed `.gz` artifacts.
+- Includes HTTP server and optional HTTPS server (self-managed certificates) in `framework/server.js`.
+- Includes internal router with Backbone-style route support (`:param`, `*splat`, optional segments).
+- Includes resource utilities (scripts, styles, meta tags, sentry, environment) in `framework/dipper.js`.
+
+### Compatibility note
+
+- This version keeps the historical behavior expected by existing projects.
+- Future improvements are planned with backward compatibility in mind. See `ROADMAP_INTEGRAL.md`.
+
+[1.3.3]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.3
+[1.3.2]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.2
+[1.3.4]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.4
+[1.3.5]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.5
+[1.3.6]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.6
+[1.4.1]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.4.1

package/README.md

@@ -1,6 +1,142 @@
-<p align="center">
-  <img src="https://github.com/nalancer08/App-Builders/blob/master/Logos/logo_monocromatico_horizontal_.png">
-</p>
-
 # VanillaJet
-NodeJS framework to create apps with jQuery or VueJS over a SPA (Single Page Application), the framework helps to create the server and add dependencia, includes router and server side functions as routes (internal API).
+
+Node.js framework for building SPA applications with a JS/CSS/HTML build pipeline, HTTP/HTTPS server, internal router, and template rendering utilities.
+
+![VanillaJet logo](https://github.com/nalancer08/App-Builders/blob/master/Logos/logo_monocromatico_horizontal_.png)
+
+## Current version
+
+- Version: `1.4.1`
+- Changelog: see [`CHANGELOG.md`](./CHANGELOG.md)
+- Improvement plan (performance and backward compatibility): see `ROADMAP_INTEGRAL.md`
+
+## Requirements
+
+- Node.js `>=16` recommended
+- npm `>=8`
+
+## Installation
+
+```bash
+npm install vanilla-jet
+```
+
+If you are working in this local repository:
+
+```bash
+npm install
+```
+
+## Quick start
+
+### 1) Export the server from your project
+
+```js
+const { Server } = require('vanilla-jet');
+```
+
+### 2) Define endpoints (classes)
+
+Each endpoint should expose a `name` and register routes with the router in the constructor.
+
+```js
+class AppEndpoint {
+  constructor(router) {
+    this.name = 'AppEndpoint';
+    router.addRoute('get', '/', 'AppEndpoint.index');
+  }
+
+  index(request, response) {
+    response.setBody('Hello VanillaJet');
+    response.respond();
+  }
+}
+```
+
+### 3) Start the server
+
+```js
+const { Server } = require('vanilla-jet');
+const Config = require('./config');
+
+new Server(Config, [AppEndpoint]).start();
+```
+
+## Available commands
+
+From this repository:
+
+- `npm run setup`: generates a base `vanillaJet.package.json` if it does not exist.
+- `npm run dev`: build + watcher for development.
+- `npm run build:qa`: build for QA.
+- `npm run build:staging`: build for staging.
+- `npm run build:prod`: build for production.
+- `npm run benchmark:static`: runs reproducible static serving benchmark (cold/warm).
+
+As CLI (`bin.js`):
+
+- `npx vanilla-jet setup`
+- `npx vanilla-jet dev`
+- `npx vanilla-jet build`
+
+## Expected consumer project structure
+
+VanillaJet expects a structure similar to:
+
+- `assets/pages/home.html`
+- `assets/templates/**/*.html`
+- `assets/scripts/**/*.js`
+- `assets/styles/less/admin.less`
+- `public/` (compiled output)
+- `config.js`
+- `vanillaJet.package.json`
+
+## Build pipeline (summary)
+
+- Minifies JS and concatenates into `public/scripts/vanilla.min.js`
+- Compiles LESS and generates `public/styles/app.min.css`
+- Compiles templates and generates `public/pages/home.html`
+- Generates `.gz` versions of JS/CSS/HTML for compressed delivery
+
+## Compression negotiation (optional)
+
+You can enable precompressed static negotiation from `settings.profile`:
+
+```js
+module.exports = {
+  settings: {
+    profile: {
+      // Enables priority: .br -> .gz -> original file
+      enable_precompressed_negotiation: true
+    }
+  }
+};
+```
+
+Behavior details:
+
+- Default (`false`): keeps existing gzip behavior for supported static assets.
+- Enabled (`true`): if client accepts Brotli, server tries `.br` first.
+- Safe fallback: if `.br` or `.gz` does not exist, server serves the original file.
+- HTML rendering (`response.render`) also uses safe runtime fallback for precompressed templates (`.br`/`.gz`/original).
+
+## Static performance notes (HU 2.1)
+
+Static serving includes a warm-path optimization focused on Node runtime latency:
+
+- Reuses static resolution for repeated requests (`route + accept-encoding`).
+- Reduces repeated metadata refresh with bounded revalidation windows.
+- Keeps streaming strategy for large assets (`fs.createReadStream`) with tuned chunk size.
+- Preserves conditional cache behavior (`ETag`/`Last-Modified` + `304`) and precompressed fallback contract.
+
+Benchmark guide:
+
+- [`docs/benchmark-static.md`](./docs/benchmark-static.md)
+
+## Additional documentation
+
+- Router: `docs/router.md`
+- Benchmark: [`docs/benchmark-static.md`](./docs/benchmark-static.md)
+- Version history: [`CHANGELOG.md`](./CHANGELOG.md)
+- Roadmap and improvements: `ROADMAP_INTEGRAL.md`
+- Deployment templates (nginx + docker): `docs/deployment/`

package/ROADMAP_INTEGRAL.md

@@ -0,0 +1,256 @@
+# ROADMAP INTEGRAL - VanillaJet
+
+Documento canonico de planeacion por epicas e historias.
+Cada historia incluye su ciclo completo: fases, tareas, entregables, metricas, criterios y documentacion.
+
+## Objetivo
+
+- Maximizar performance de serving estatico sobre Node sin romper compatibilidad.
+- Acelerar el pipeline de compilacion en tiempo real (watch/recompile) para DX diaria.
+- Mejorar flujo `dev` con apertura automatica de navegador y live reload estable.
+
+## Reglas de ejecucion
+
+- Retrocompatibilidad primero.
+- Cambios sensibles con flags.
+- Todo cambio con medicion antes/despues.
+- Entregas pequenas y reversibles.
+
+---
+
+## EPIC 1 - Estabilidad base
+
+### HU 1.1 - Cache metadata + 304 (completada `v1.3.3`)
+
+#### Fases
+- F1: cache metadata.
+- F2: validacion condicional.
+- F3: no-regresion.
+
+#### Tareas
+- Cache `size/mtime/etag`.
+- Soporte `If-None-Match` y `If-Modified-Since`.
+
+#### Entregables
+- `framework/router.js` actualizado.
+
+#### Metricas
+- Menor latencia y menor I/O en estaticos repetidos.
+
+#### Criterios
+- `304` correcto.
+- Sin impacto en dinamico.
+
+#### Documentacion
+- `CHANGELOG.md`.
+
+### HU 1.2 - Negociacion `br/gz` estaticos (completada `v1.3.4`)
+
+#### Fases
+- F1: flag opt-in.
+- F2: fallback seguro.
+- F3: validacion.
+
+#### Tareas
+- `.br -> .gz -> original`.
+- `Vary: Accept-Encoding`.
+
+#### Entregables
+- `framework/router.js`.
+
+#### Metricas
+- Menor transferencia en cliente.
+
+#### Criterios
+- Fallback sin 404.
+
+#### Documentacion
+- `README.md`, `CHANGELOG.md`.
+
+### HU 1.3 - Fallback precompressed HTML (completada `v1.3.5`)
+
+#### Fases
+- F1: fallback runtime HTML.
+- F2: pruebas de ausencia de artefactos.
+- F3: release.
+
+#### Tareas
+- Resolver `.br/.gz/original` en `render`.
+
+#### Entregables
+- `framework/response.js`.
+
+#### Metricas
+- Menor peso de HTML inicial.
+
+#### Criterios
+- Sin errores por artefactos faltantes.
+
+#### Documentacion
+- `README.md`, `CHANGELOG.md`.
+
+### HU 1.4 - Hardening de bugs conocidos (completada `v1.3.6`)
+
+#### Fases
+- F1: correccion.
+- F2: smoke tests.
+- F3: patch release.
+
+#### Tareas
+- [x] `node_mudules -> node_modules`.
+- [x] fixes en `dipper`.
+- [x] fix script `test`.
+
+#### Entregables
+- Patch de estabilidad.
+
+#### Metricas
+- Menos errores silenciosos en runtime/build.
+
+#### Criterios
+- [x] `npm test` estable.
+
+#### Documentacion
+- `CHANGELOG.md` con nota de compatibilidad.
+
+---
+
+## EPIC 2 - Performance Node + DX de compilacion (foco actual)
+
+### HU 2.1 - Fast path de estaticos en Node (completada `v1.4.1`)
+
+#### Fases
+- F1: profiling de request estatico.
+- F2: optimizacion de lectura/respuesta.
+- F3: validacion de no-regresion.
+
+#### Tareas
+- [x] Optimizar resolucion de archivo y headers para evitar trabajo repetido.
+- [x] Revisar estrategia de `fs`/stream para minimizar latencia en assets grandes.
+- [x] Agregar benchmark local reproducible (cold/warm cache).
+
+#### Entregables
+- [x] Patch de performance en `framework/router.js`.
+- [x] Script de benchmark local documentado.
+
+#### Metricas
+- p95 de estaticos >= 20% mejor en escenario warm.
+- Menor uso de CPU en serving concurrente.
+
+#### Criterios
+- [x] Sin romper cache condicional (`304`) ni negociacion precompressed.
+- [x] Sin impacto en rutas dinamicas.
+
+#### Documentacion
+- [x] `README.md` + `CHANGELOG.md` + guia de benchmark.
+
+### HU 2.2 - Recompile en tiempo real mas rapido (pendiente)
+
+#### Fases
+- F1: baseline de tiempos por tarea de build.
+- F2: optimizacion incremental.
+- F3: validacion en proyecto consumidor.
+
+#### Tareas
+- Reducir trabajo redundante en `gulpfile.js` (globs, minify y concatenacion).
+- Mejorar estrategia de watch para recompilar solo lo tocado.
+- Medir tiempo de recompile por tipo de cambio (JS, LESS, HTML).
+
+#### Entregables
+- Pipeline `dev` optimizado y medido.
+
+#### Metricas
+- Recompile JS >= 35% mas rapido.
+- Recompile LESS >= 30% mas rapido.
+
+#### Criterios
+- Output final equivalente al flujo actual.
+- Sin cambios obligatorios en estructura de proyectos consumidores.
+
+#### Documentacion
+- `README.md` + `CHANGELOG.md`.
+
+---
+
+## EPIC 3 - Developer Experience en `dev`
+
+### HU 3.1 - Runner `dev` con navegador auto-open + live reload estable (pendiente)
+
+#### Fases
+- F1: contrato de ejecucion unificado.
+- F2: implementacion runner.
+- F3: validacion en Mac/Windows/Linux.
+
+#### Tareas
+- Abrir navegador automaticamente al iniciar `dev`.
+- Disparar live reload al terminar recompile de assets/templates.
+- Mantener modo fallback para entornos sin navegador.
+
+#### Entregables
+- Nuevo flujo `npm run dev` mas simple para consumidores.
+
+#### Metricas
+- Tiempo a primer render local menor.
+- Menos pasos manuales de arranque en onboarding.
+
+#### Criterios
+- Reload confiable tras cada recompile exitoso.
+- Sin romper el modo actual para usuarios legacy.
+
+#### Documentacion
+- `README.md` + `CHANGELOG.md` + guia de migracion de scripts.
+
+---
+
+## EPIC 4 - Hardening operativo del runtime Node
+
+### HU 4.1 - Observabilidad y protecciones de runtime (pendiente)
+
+#### Fases
+- F1: logging y metricas base.
+- F2: alarmas y limites.
+- F3: guia operativa.
+
+#### Tareas
+- Estandarizar logs de serving estatico y errores.
+- Exponer metricas clave (latencia/errores/cache hits).
+- Documentar manejo de picos y rollback.
+
+#### Entregables
+- Guia de operacion y checklist de hardening.
+
+#### Documentacion
+- `docs/` + `README.md`.
+
+### HU 4.2 - Paquete de referencia para despliegue Node (pendiente)
+
+#### Fases
+- F1: templates de entorno.
+- F2: validacion en staging.
+- F3: guia final.
+
+#### Tareas
+- Definir variables, puertos y recomendaciones de cache.
+- Incluir ejemplo de despliegue reproducible para consumidores.
+
+#### Entregables
+- Template de despliegue y guia de puesta en marcha.
+
+#### Documentacion
+- `docs/` + `README.md`.
+
+---
+
+## Secuencia oficial de ejecucion
+
+1. HU 1.4
+2. HU 2.1
+3. HU 2.2
+4. HU 3.1
+5. HU 4.1
+6. HU 4.2
+
+## Estado global
+
+- Completado: HU 1.1, HU 1.2, HU 1.3, HU 1.4, HU 2.1.
+- Pendiente: HU 2.2, HU 3.1, HU 4.1, HU 4.2.

package/docs/benchmark-static.md

@@ -0,0 +1,45 @@
+# Static serving benchmark guide
+
+This benchmark measures static file serving in two reproducible scenarios:
+
+- Warm cache latency/throughput with stable keep-alive traffic.
+- Cold cache latency by forcing metadata/resolution misses on each request.
+
+## Run
+
+```bash
+npm run benchmark:static
+```
+
+## Optional tuning variables
+
+You can override defaults with environment variables:
+
+- `BENCH_PORT` (default: `3199`)
+- `BENCH_FILE_SIZE_KB` (default: `512`)
+- `BENCH_TOTAL_REQUESTS` (default: `2000`)
+- `BENCH_COLD_ITERATIONS` (default: `300`)
+
+Example:
+
+```bash
+BENCH_TOTAL_REQUESTS=4000 BENCH_COLD_ITERATIONS=600 npm run benchmark:static
+```
+
+## Output
+
+The script reports for warm and cold scenarios:
+
+- request count
+- average latency
+- `p50`, `p95`, `p99`
+- max latency
+- requests per second
+
+It also prints warm `p95` improvement vs cold.
+
+## Notes for consistent results
+
+- Close heavy apps before running benchmarks.
+- Run at least 3 times and compare medians.
+- Keep the same `BENCH_*` values before/after a performance patch.

package/docs/deployment/Dockerfile.app.example

@@ -0,0 +1,19 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install dependencies first for better layer cache
+COPY package*.json ./
+RUN npm ci
+
+# Copy app source
+COPY . .
+
+# Build command should generate static output under /app/public
+# Replace with your app build script (for example: npm run build:vite)
+RUN npm run build:vite || npm run build:prod
+
+EXPOSE 8080
+
+# Replace with your actual backend start command
+CMD ["node", "index.js"]

package/docs/deployment/docker-compose.nginx-node.example.yml

@@ -0,0 +1,23 @@
+version: "3.9"
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: docs/deployment/Dockerfile.app.example
+    container_name: vanillajet-app
+    environment:
+      - PORT=8080
+    expose:
+      - "8080"
+
+  nginx:
+    image: nginx:1.27-alpine
+    container_name: vanillajet-nginx
+    depends_on:
+      - app
+    ports:
+      - "80:80"
+    volumes:
+      - ./public:/app/public:ro
+      - ./docs/deployment/nginx.default.conf.example:/etc/nginx/conf.d/default.conf:ro

package/docs/deployment/nginx.default.conf.example

@@ -0,0 +1,36 @@
+server {
+    listen 80;
+    server_name _;
+
+    # Build output served directly by nginx
+    root /app/public;
+    index pages/home.html;
+
+    # API and dynamic routes handled by VanillaJet backend
+    location /api/ {
+        proxy_pass http://app:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Static assets with long cache
+    location ~* \.(?:css|js|png|jpg|jpeg|gif|svg|webp|ico|ttf|otf|woff|woff2)$ {
+        try_files $uri =404;
+        expires 30d;
+        add_header Cache-Control "public, max-age=2592000, immutable";
+    }
+
+    # HTML should revalidate frequently
+    location ~* \.html$ {
+        try_files $uri =404;
+        add_header Cache-Control "no-cache, must-revalidate";
+    }
+
+    # SPA fallback to main page
+    location / {
+        try_files $uri $uri/ /pages/home.html;
+    }
+}