vanilla-jet 1.4.2 → 1.5.0

package/.scripts/generate_packages_json.js

@@ -41,7 +41,6 @@ async function createFileIfnotExists(content) {
 // -- Helpers
 function processCwd() {
     return process.cwd()
-        .replace('/.grunt', '')
         .replace('/.scripts', '');
 }
 

package/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable project changes are documented in this file.
 
 The format follows a structure inspired by Keep a Changelog and semantic versioning.
 
+## [1.5.0] - 2026-06-27
+
+### Added
+
+- **Service worker support (opt-in)** — `settings.profile.enable_service_worker`.
+  - `framework/sw.template.js`: generic cache-first worker (precache + on-demand prefixes).
+  - `scripts/generate_sw.js` + Gulp task `generateServiceWorker`: generates `public/sw.js` at build time.
+    - Precache list = core bundles (`app.min.css`, `vanilla.min.js`, `core/vanillaJet.min.js`) + LOCAL resources enqueued by the Dipper + `service_worker.precache` extras (existing files only).
+    - Cache name is content-pinned (md5 of `path:size-mtime`), so any asset change rotates the cache; `activate()` purges stale caches.
+    - Matches use `{ ignoreSearch: true }` to stay compatible with fingerprinted (`?v=`) asset URLs.
+  - `framework/router.js`: serves `/sw.js` from root scope with `Service-Worker-Allowed: /` and `Cache-Control: no-cache` when enabled.
+  - `framework/dipper.js`: `includeServiceWorker()` inline registration helper (web-only; honors `window.__VJ_DISABLE_SW__` to opt out and tear down inside native WebViews).
+  - Config knobs: `service_worker.precache`, `service_worker.on_demand_prefixes`, `service_worker.cache_prefix`.
+
+### Fixed
+
+- **Build-time environment injection regression (backward compatibility):** `scripts/compile_html.js`
+  again resolves the build environment (passed by Gulp via `--env`, forwarded as argv) and reads
+  `settings[env]`, restoring correct `api_url`/`environment` injection (`includeEnvironment()`). The 1.4.x
+  rewrite read a literal `settings['profile']` and also rendered the page content as a template name,
+  producing `API_URL="undefined"` and `template not found` for 1.3.x-shaped configs. `gulpfile.js` now
+  forwards `--env` to both `compile_html.js` and `generate_sw.js`.
+- **Broken dependency removed:** dropped `zlib@1.0.5` from `dependencies`. The framework uses Node's
+  built-in `zlib` (core modules take precedence), and the npm package has a native `node-waf` build step
+  that fails on modern Node — it broke `npm install`/`npm ci` for consumers. Pure dead weight.
+- **CLI build commands regression (backward compatibility):** `bin.js` again handles
+  `build:qa`, `build:staging` and `build:prod` (they map to `gulp build --env <env>`). 1.3.x consumers
+  call `npx vanilla-jet build:<env>`; the 1.4.x CLI had dropped these, so the build silently did nothing.
+- **Profile resolution regression (backward compatibility):** `framework/server.js` now resolves
+  `settings[options.profile] || settings['profile']`. Legacy consumers (1.3.x) that key settings by the
+  active profile name (e.g. `qa`, `production`) again receive their profile options instead of `{}`.
+- **PaaS port binding:** server now honors `process.env.PORT` (Cloud Run / Heroku) before `settings.profile.port`.
+- **Ephemeral port (`port: 0`) preserved:** port selection uses a nullish check instead of `|| 8080`, so a
+  deliberate `0` binds an ephemeral port instead of falling back to `8080`.
+
+### Testing
+
+- Added a real test harness (`test/`, `node --test`, no new deps) wired to `npm test`:
+  router, dipper, config-shape resolution, static serving (`200`/`304`/`404`), and service worker
+  generation + serving.
+
+### Compatibility notes
+
+- Service worker is **off by default**; existing apps are unaffected until they opt in.
+- Profile-resolution fix is backward compatible with both the legacy and the nested config shapes.
+
+## [1.4.3] - 2026-02-19
+
+### Removed
+
+- Grunt build artifacts: removed `.grunt/` folder, `build_styles_task.js`, and `compile_html.js`.
+- Build pipeline now uses only Gulp; template compilation moved to `scripts/compile_html.js`.
+
+### Changed
+
+- `gulpfile.js`: `compileTemplates` now invokes `node scripts/compile_html.js` instead of `.grunt/compile_html.js`.
+- `framework/dipper.js`, `.scripts/generate_packages_json.js`: removed `.grunt` references from `processCwd` helpers.
+
+### Fixed
+
+- **Reliability under rapid reloads (F5)**: server no longer stops responding after repeated refreshes.
+  - Removed `fs.watch` per static file (`staticFileWatchers`); could exhaust resources with prolonged use.
+  - Added fallback to `404` for routes without a handled static extension (avoids hanging requests).
+  - Destroy file streams when client disconnects (`res.on('close')`) to avoid orphaned streams.
+  - Applied same stream cleanup in `response.render()` for HTML template delivery.
+- Added defensive server timeouts: `requestTimeout`, `headersTimeout`, `keepAliveTimeout` (configurable via `settings.profile`).
+
+### Compatibility notes
+
+- No public API changes.
+- Build output and route behavior unchanged; only internal reliability improvements.
+
 ## [1.4.2] - 2026-02-19
 
 ### Changed
@@ -112,4 +184,5 @@ The format follows a structure inspired by Keep a Changelog and semantic version
 [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.2]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.4.2
+[1.4.3]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.4.3
 [1.4.1]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.4.1

package/README.md

@@ -6,7 +6,7 @@ Node.js framework for building SPA applications with a JS/CSS/HTML build pipelin
 
 ## Current version
 
-- Version: `1.4.2`
+- Version: `1.4.3`
 - Changelog: see [`CHANGELOG.md`](./CHANGELOG.md)
 - Improvement plan (performance and backward compatibility): see `ROADMAP_INTEGRAL.md`
 
@@ -93,6 +93,8 @@ VanillaJet expects a structure similar to:
 
 ## Build pipeline (summary)
 
+Gulp-based pipeline (no Grunt):
+
 - 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`

package/bin.js

@@ -28,4 +28,29 @@ switch (args[0]) {
       console.error('Error executing gulp:', error.message);
     }
     break;
+
+  // Environment-specific builds (restored for 1.3.x consumer compatibility).
+  case 'build:qa':
+    try {
+      execSync('npx gulp build --env qa', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
+
+  case 'build:staging':
+    try {
+      execSync('npx gulp build --env staging', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
+
+  case 'build:prod':
+    try {
+      execSync('npx gulp build --env production', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
 }

package/framework/dipper.js

@@ -385,6 +385,37 @@ Dipper.prototype.includeManifest = function() {
 	return tagString;
 }
 
+/**
+ * Inline registration for the VanillaJet service worker.
+ * Returns '' unless settings.profile.enable_service_worker is true.
+ * Web-only by design: a consumer running inside a native WebView can set
+ * `window.__VJ_DISABLE_SW__ = true` before this runs to opt out and tear down
+ * any previously installed worker (WebViews get no benefit and stuck SWs are
+ * hard to recover there).
+ */
+Dipper.prototype.includeServiceWorker = function() {
+
+	const obj = this;
+	if (!obj.options || !obj.options.enable_service_worker) {
+		return '';
+	}
+
+	return `
+		<script>
+			(function () {
+				if (!('serviceWorker' in navigator)) { return; }
+				if (window.__VJ_DISABLE_SW__) {
+					navigator.serviceWorker.getRegistration()
+						.then(function (registration) { if (registration) { registration.unregister(); } })
+						.catch(function (error) { console.error(error); });
+					return;
+				}
+				navigator.serviceWorker.register('/sw.js')
+					.catch(function (error) { console.error(error); });
+			})();
+		</script>`;
+}
+
 /**
  * Setup Sentry for error reporting on production and qa environments.
  */
@@ -545,7 +576,6 @@ Dipper.prototype.includeEnvironment = function() {
 Dipper.prototype.processCwd = function() {
 
 	let cwd = process.cwd()
-		.replace('/.grunt', '')
 		.replace('/.scripts', '')
 		.replace('/node_modules', '')
 		.replace('/vanilla-jet', '');

package/framework/response.js

@@ -111,6 +111,11 @@ class Response {
       fileStream.on('error', () => {
         obj.error404();
       });
+      obj.res.on('close', () => {
+        if (!obj.res.writableEnded) {
+          fileStream.destroy();
+        }
+      });
       fileStream.pipe(obj.res);
     });
 	}

package/framework/router.js

@@ -19,7 +19,6 @@ class Router {
     this.staticBasePath = this.cwd.replace('core/framework', '');
     this.staticMetadataCache = new Map();
     this.staticResolutionCache = new Map();
-    this.staticFileWatchers = new Map();
     this.staticStreamChunkSize = 128 * 1024;
     this.mimes = {
       'png': 'image/png',
@@ -42,6 +41,7 @@ class Router {
     this.compressionMimes = [ 'css', 'js' ];
     this.compressionFiles = [ 'vanilla.min.js', 'app.min.css' ];
     this.enablePrecompressedNegotiation = Boolean(server?.options?.enable_precompressed_negotiation);
+    this.enableServiceWorker = Boolean(server?.options?.enable_service_worker);
 	}
 
 	routeToRegExp(route) {
@@ -100,10 +100,15 @@ class Router {
 					}
 				});
 
+				// -- Service worker: served from root scope so it can control the whole origin
+				if (!handled && !isMatch && obj.enableServiceWorker && request.path === '/sw.js') {
+					return obj.serveServiceWorker(res);
+				}
+
 				// -- Check static files
 				if (!handled && !isMatch) {
 
-					let ext = path.extname(request.path).replace('.', ''), 
+					let ext = path.extname(request.path).replace('.', ''),
             extHandled = false, 
             extHeader = {};
 					
@@ -149,12 +154,18 @@ class Router {
                 res.writeHead(500);
                 res.end('Server Error');
               });
+              res.on('close', () => {
+                if (!res.writableEnded) {
+                  fileStream.destroy();
+                }
+              });
 
               res.writeHead(200, staticHeaders);
               fileStream.pipe(res);
-              res.on('close', () => {});
             });
-					}
+					} else {
+            return obj.onNotFound(response);
+          }
 				}
 			}
 		}), handled = false;
@@ -181,7 +192,6 @@ class Router {
       };
 
       obj.staticMetadataCache.set(filename, metadata);
-      obj.watchStaticFile(filename);
       callback(null, metadata);
     });
   }
@@ -310,41 +320,6 @@ class Router {
     });
   }
 
-  watchStaticFile(filename) {
-    let obj = this;
-    if (obj.staticFileWatchers.has(filename)) {
-      return;
-    }
-
-    try {
-      let watcher = fs.watch(filename, (eventType) => {
-        obj.staticMetadataCache.delete(filename);
-        obj.staticResolutionCache.clear();
-        if (eventType === 'rename') {
-          let renamedWatcher = obj.staticFileWatchers.get(filename);
-          if (renamedWatcher) {
-            renamedWatcher.close();
-          }
-          obj.staticFileWatchers.delete(filename);
-        }
-      });
-
-      watcher.on('error', () => {
-        obj.staticMetadataCache.delete(filename);
-        obj.staticResolutionCache.clear();
-        let activeWatcher = obj.staticFileWatchers.get(filename);
-        if (activeWatcher) {
-          activeWatcher.close();
-        }
-        obj.staticFileWatchers.delete(filename);
-      });
-
-      obj.staticFileWatchers.set(filename, watcher);
-    } catch (err) {
-      // If watch cannot be created, keep runtime behavior and continue.
-    }
-  }
-
   isNotModified(req, metadata) {
     let ifNoneMatch = req.headers['if-none-match'];
     if (ifNoneMatch) {
@@ -400,6 +375,35 @@ class Router {
 		return this.defaultRoute;
 	}
 
+	serveServiceWorker(res) {
+		let obj = this;
+		let filename = path.join(obj.staticBasePath, 'public', 'sw.js');
+		fs.stat(filename, (err, stats) => {
+			if (err || !stats.isFile()) {
+				res.writeHead(404);
+				return res.end();
+			}
+			res.writeHead(200, {
+				'Content-Type': 'text/javascript; charset=utf-8',
+				// Allow the SW (served at /sw.js) to control the entire origin.
+				'Service-Worker-Allowed': '/',
+				// Keep the SW script itself fresh so updates roll out promptly.
+				'Cache-Control': 'no-cache'
+			});
+			let stream = fs.createReadStream(filename);
+			stream.on('error', () => {
+				res.writeHead(500);
+				res.end('Server Error');
+			});
+			res.on('close', () => {
+				if (!res.writableEnded) {
+					stream.destroy();
+				}
+			});
+			stream.pipe(res);
+		});
+	}
+
 	onNotFound(response) {
 		response.setStatus(404);
 		response.respond();

package/framework/server.js

@@ -23,16 +23,23 @@ class Server {
 
 	init(options, endpoints) {
 
-		let obj = this, 
-			settings = options.settings, 
-			opts = settings['profile'] || {}, 
-			shared = settings['shared'] || {}, 
+		let obj = this,
+			settings = options.settings,
+			// Resolve the active profile. Legacy consumers key settings by the active
+			// profile name (settings[options.profile], e.g. 'qa'); newer ones expose a
+			// single nested 'profile' object. Support both for backward compatibility.
+			opts = settings[options.profile] || settings['profile'] || {},
+			shared = settings['shared'] || {},
 			security = settings['security'] || {};
 
 		_.defaults(opts, {
 			https_server: false,
 			wsServer: false,
-      enable_precompressed_negotiation: false
+      enable_precompressed_negotiation: false,
+      enable_service_worker: false,
+      request_timeout_ms: 30000,
+      headers_timeout_ms: 35000,
+      keep_alive_timeout_ms: 5000
 		});
 		obj.options = opts;
 
@@ -67,8 +74,11 @@ class Server {
 	}
 
 	start() {
+		let boundPort = (this.httpx && this.httpx.address && this.httpx.address())
+			? this.httpx.address().port
+			: (process.env.PORT || this.options.port || 8080);
 		this.log('__________________  VanillaJet Server started  ___________________');
-		this.log(` >           Running on 0.0.0.0:${this.options.port}/           < `);
+		this.log(` >           Running on 0.0.0.0:${boundPort}/           < `);
 		this.log('------------------------------------------------------------------');
 	}
 
@@ -91,7 +101,16 @@ class Server {
     }
 
     // -- Set the port
-    obj.httpx.listen(obj.options.port || 8080);
+    obj.httpx.requestTimeout = Number(obj.options.request_timeout_ms) || 30000;
+    obj.httpx.headersTimeout = Number(obj.options.headers_timeout_ms) || 35000;
+    obj.httpx.keepAliveTimeout = Number(obj.options.keep_alive_timeout_ms) || 5000;
+    // Honor process.env.PORT first so PaaS runtimes (Cloud Run, Heroku, …) that
+    // inject the listening port at runtime work without config changes. Use a
+    // nullish check so a deliberate port 0 (ephemeral) is preserved.
+    let port = (process.env.PORT !== undefined && process.env.PORT !== '')
+      ? process.env.PORT
+      : (obj.options.port !== undefined && obj.options.port !== null ? obj.options.port : 8080);
+    obj.httpx.listen(port);
   }
 
 	log(value) {

package/framework/sw.template.js

@@ -0,0 +1,82 @@
+/**
+ * VanillaJet service worker template.
+ *
+ * This file is NOT used as-is. The build (scripts/generate_sw.js) replaces the
+ * __PLACEHOLDERS__ below with values derived from the compiled assets and the
+ * consumer config, and writes the result to public/sw.js.
+ *
+ * Strategy: cache-first for a pinned set of local bundles/styles/plugins and an
+ * on-demand cache for prefixes (animations, images). The cache name is pinned to
+ * a content hash of the precached assets, so a rebuild that changes any asset
+ * produces a new cache and activate() purges the stale ones. Because VanillaJet
+ * fingerprints asset URLs (`?v=size-mtime`), matches use { ignoreSearch: true }
+ * so a cache entry keeps serving across version query changes within the cache.
+ */
+
+const CACHE_NAME = '__CACHE_NAME__';
+const CACHE_PREFIX = '__CACHE_PREFIX__';
+const PRECACHE_ASSETS = __PRECACHE_ASSETS__;
+const ON_DEMAND_PREFIXES = __ON_DEMAND_PREFIXES__;
+
+const MATCH_OPTIONS = { ignoreSearch: true };
+
+function isCacheable(pathname) {
+	return (
+		PRECACHE_ASSETS.includes(pathname) ||
+		ON_DEMAND_PREFIXES.some((prefix) => pathname.startsWith(prefix))
+	);
+}
+
+globalThis.addEventListener('install', (event) => {
+	event.waitUntil(
+		caches.open(CACHE_NAME).then((cache) =>
+			Promise.allSettled(PRECACHE_ASSETS.map((asset) => cache.add(asset))).then((results) => {
+				results.forEach((result, i) => {
+					if (result.status === 'rejected') {
+						console.error('SW precache failed: ' + PRECACHE_ASSETS[i], result.reason);
+					}
+				});
+			})
+		)
+	);
+	event.waitUntil(globalThis.skipWaiting());
+});
+
+globalThis.addEventListener('activate', (event) => {
+	event.waitUntil(
+		caches.keys().then((keys) =>
+			Promise.all(
+				keys
+					.filter((k) => k.startsWith(CACHE_PREFIX) && k !== CACHE_NAME)
+					.map((k) => caches.delete(k))
+			)
+		)
+	);
+	event.waitUntil(globalThis.clients.claim());
+});
+
+globalThis.addEventListener('fetch', (event) => {
+	const { request } = event;
+	if (request.method !== 'GET') return;
+
+	const url = new URL(request.url);
+	if (url.origin !== globalThis.location.origin || !isCacheable(url.pathname)) return;
+
+	// Cache-first: assets are immutable within a version (CACHE_NAME is content-pinned
+	// and activate() purges old caches on bump), so a cache hit never needs
+	// revalidation — skip the network entirely to save bandwidth on slow links.
+	event.respondWith(
+		caches.open(CACHE_NAME).then((cache) =>
+			cache.match(request, MATCH_OPTIONS).then((cached) => {
+				if (cached) return cached;
+
+				return fetch(request).then((response) => {
+					// waitUntil keeps the SW alive until the write finishes, so the asset
+					// is actually cached even if the SW is terminated right after.
+					if (response.ok) event.waitUntil(cache.put(request, response.clone()));
+					return response;
+				});
+			})
+		)
+	);
+});

package/gulpfile.js

@@ -24,6 +24,11 @@ function getCwd() {
 const base = getCwd();
 const cssOrigin = `${getCwd()}/assets/styles/less/admin.less`;
 
+// Build environment (passed via `gulp build --env <env>`). Forwarded to the
+// HTML/SW generators so they resolve the matching profile (api_url, etc).
+const argv = minimist(process.argv.slice(2));
+const buildEnv = argv.env || 'development';
+
 // Clean tasks
 function cleanBuildJS() {
   return del([`${getCwd()}/public/scripts/vanilla.min.js`], { force: true });
@@ -113,7 +118,13 @@ function compressCss() {
 // Template compilation
 function compileTemplates() {
   return gulp.src('.')
-    .pipe(shell([`node .grunt/compile_html.js`]));
+    .pipe(shell([`node scripts/compile_html.js ${buildEnv}`]));
+}
+
+// Service worker generation (opt-in via settings.profile.enable_service_worker)
+function generateServiceWorker() {
+  return gulp.src('.')
+    .pipe(shell([`node scripts/generate_sw.js ${buildEnv}`]));
 }
 
 // Watch task
@@ -124,7 +135,8 @@ function watchFiles(cb) {
   watch([`${base}/assets/styles/less/**/*.less`], gulp.series(
     buildLess,
     compressCss,
-    compileTemplates
+    compileTemplates,
+    generateServiceWorker
   ));
 
   // Watch HTML files
@@ -140,7 +152,8 @@ function watchFiles(cb) {
     concatJs,
     cleanMinified,
     compressJs,
-    compileTemplates
+    compileTemplates,
+    generateServiceWorker
   ));
   
   cb();
@@ -154,7 +167,8 @@ const build = gulp.series(
   cleanMinified,
   buildLess,
   compileTemplates,
-  gulp.parallel(compressJs, compressCss)
+  gulp.parallel(compressJs, compressCss),
+  generateServiceWorker
 );
 
 const dev = gulp.series(
@@ -171,6 +185,7 @@ exports.concatJs = concatJs;
 exports.compressJs = compressJs;
 exports.compressCss = compressCss;
 exports.compileTemplates = compileTemplates;
+exports.generateServiceWorker = generateServiceWorker;
 exports.build = build;
 exports.dev = dev;
 exports.default = dev;