vanilla-jet 1.4.3 → 1.5.1

package/scripts/generate_sw.js

@@ -0,0 +1,182 @@
+// Generates public/sw.js from framework/sw.template.js.
+//
+// Opt-in: only runs when the active profile sets `enable_service_worker: true`.
+// The precache list is derived from the compiled core assets, any LOCAL resources
+// the Dipper has enqueued, and the explicit `service_worker.precache` config.
+// The cache name is pinned to a content hash so any asset change rotates the cache.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const TEMPLATE_PATH = path.join(__dirname, '..', 'framework', 'sw.template.js');
+
+// Core bundles that every VanillaJet app ships; precached when present.
+const CORE_PRECACHE = [
+	'/public/styles/app.min.css',
+	'/public/scripts/vanilla.min.js',
+	'/public/scripts/core/vanillaJet.min.js'
+];
+
+const DEFAULT_ON_DEMAND_PREFIXES = ['/public/animations/', '/public/images/'];
+
+function processCwd() {
+	return process.cwd()
+		.replace('/scripts', '')
+		.replace('/gulp', '')
+		.replace('/node_modules/vanilla-jet', '');
+}
+
+const ENV_ALIASES = { dev: 'development', prod: 'production', 'build:qa': 'qa', 'build:staging': 'staging', 'build:prod': 'production' };
+
+function resolveEnv(config) {
+	let env = process.argv[2] || (config && config.profile) || 'development';
+	return ENV_ALIASES[env] || env;
+}
+
+function loadConfig(root) {
+	try {
+		const config = require(path.join(root, 'config.js'));
+		const settings = config.settings || {};
+		const env = resolveEnv(config);
+		const opts = settings[env] || settings[config.profile] || settings['profile'] || {};
+		return { opts, shared: settings['shared'] || {} };
+	} catch (err) {
+		return { opts: {}, shared: {} };
+	}
+}
+
+function slugify(value) {
+	return String(value || '')
+		.toLowerCase()
+		.trim()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/(^-|-$)/g, '') || 'vanillajet';
+}
+
+function stripQuery(url) {
+	const queryIndex = url.indexOf('?');
+	return queryIndex === -1 ? url : url.slice(0, queryIndex);
+}
+
+function isLocalPublicPath(url) {
+	return typeof url === 'string' && url.startsWith('/public/') && !url.startsWith('//');
+}
+
+// Source of truth = vanillaJet.package.json. We hydrate the Dipper and read its full
+// registry (coreDependencies + dependencies + styles), keeping every LOCAL resource.
+// This way the precache list is derived from the declared deps, with no raw paths in
+// the consumer config. Any failure falls back to core only.
+function deriveLocalAssets(root, opts, shared) {
+	try {
+		const Dipper = require('../framework/dipper.js');
+		const Functions = require('../framework/functions.js');
+		const dipper = new Dipper(opts, shared);
+		Functions.hydrate(dipper);
+
+		const assets = [];
+		const collect = (registry) => {
+			Object.keys(registry || {}).forEach((name) => {
+				const entry = registry[name];
+				if (entry && isLocalPublicPath(entry.resource)) {
+					assets.push(stripQuery(entry.resource));
+				}
+			});
+		};
+		collect(dipper.styles);
+		collect(dipper.scripts);
+		return assets;
+	} catch (err) {
+		return [];
+	}
+}
+
+function buildPrecacheList(root, opts, shared) {
+	const sw = opts.service_worker || {};
+	// `precache` = optional extras NOT declared in vanillaJet.package.json.
+	const configured = Array.isArray(sw.precache) ? sw.precache : [];
+	// `precache_exclude` = opt-out for declared-but-don't-cache assets (heavy/rare).
+	const exclude = (Array.isArray(sw.precache_exclude) ? sw.precache_exclude : []).map(stripQuery);
+
+	const candidates = CORE_PRECACHE
+		.concat(deriveLocalAssets(root, opts, shared))
+		.concat(configured)
+		.map(stripQuery)
+		.filter(isLocalPublicPath)
+		.filter((assetPath) => !exclude.includes(assetPath));
+
+	const seen = new Set();
+	const precache = [];
+	candidates.forEach((assetPath) => {
+		if (seen.has(assetPath)) return;
+		const absolute = path.join(root, assetPath.replace(/^\//, ''));
+		try {
+			if (fs.statSync(absolute).isFile()) {
+				seen.add(assetPath);
+				precache.push(assetPath);
+			}
+		} catch (err) {
+			// Missing file: skip it so the SW never precaches a 404.
+		}
+	});
+	return precache;
+}
+
+function computeCacheHash(root, precache) {
+	const hash = crypto.createHash('md5');
+	precache.forEach((assetPath) => {
+		const absolute = path.join(root, assetPath.replace(/^\//, ''));
+		try {
+			const stats = fs.statSync(absolute);
+			hash.update(`${assetPath}:${stats.size}-${Math.floor(stats.mtimeMs)}`);
+		} catch (err) {
+			hash.update(`${assetPath}:missing`);
+		}
+	});
+	return hash.digest('hex').slice(0, 12);
+}
+
+function main() {
+	const root = processCwd();
+	const { opts, shared } = loadConfig(root);
+
+	if (!opts.enable_service_worker) {
+		// Feature disabled: remove any previously generated SW so it stops controlling clients.
+		const existing = path.join(root, 'public', 'sw.js');
+		if (fs.existsSync(existing)) {
+			fs.unlinkSync(existing);
+			console.log('VanillaJet - service worker disabled; removed public/sw.js');
+		}
+		return;
+	}
+
+	const swOptions = opts.service_worker || {};
+	const baseSlug = slugify(swOptions.cache_prefix || shared.site_name || 'vanillajet');
+	// activate() purges every cache whose name starts with this base (and != current),
+	// so a rebuild rotates the cache AND legacy schemes (e.g. "<base>-<appVersion>") get cleaned up.
+	const cachePrefix = baseSlug;
+	const onDemandPrefixes = Array.isArray(swOptions.on_demand_prefixes)
+		? swOptions.on_demand_prefixes
+		: DEFAULT_ON_DEMAND_PREFIXES;
+
+	const precache = buildPrecacheList(root, opts, shared);
+	const cacheName = `${baseSlug}-sw-${computeCacheHash(root, precache)}`;
+
+	let template = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+	template = template
+		.replace(/__CACHE_NAME__/g, cacheName)
+		.replace(/__CACHE_PREFIX__/g, cachePrefix)
+		.replace('__PRECACHE_ASSETS__', JSON.stringify(precache, null, '\t'))
+		.replace('__ON_DEMAND_PREFIXES__', JSON.stringify(onDemandPrefixes, null, '\t'));
+
+	const publicDir = path.join(root, 'public');
+	fs.mkdirSync(publicDir, { recursive: true });
+	const outputPath = path.join(publicDir, 'sw.js');
+	fs.writeFileSync(outputPath, template, 'utf8');
+
+	console.log(`VanillaJet - service worker generated at public/sw.js (cache: ${cacheName}, ${precache.length} precached)`);
+}
+
+main();
+
+module.exports = main;

package/test/config.test.js

@@ -0,0 +1,47 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+
+const Server = require('../framework/server.js');
+const { waitForListening, closeServer } = require('./helpers.js');
+
+// Guards the profile-resolution regression: 1.3.x consumers key settings by the
+// active profile name (settings[options.profile]); the newer shape uses a single
+// nested 'profile'. Both must resolve to obj.options.
+const servers = [];
+
+async function boot(options) {
+  const server = new Server(options, []);
+  servers.push(server);
+  await waitForListening(server);
+  return server;
+}
+
+after(async () => {
+  for (const server of servers) {
+    await closeServer(server);
+  }
+});
+
+test('legacy config shape: settings keyed by active profile name', async () => {
+  const server = await boot({
+    profile: 'qa',
+    settings: {
+      qa: { port: 0, marker: 'legacy' },
+      development: { port: 0, marker: 'dev' },
+      shared: {},
+      security: {}
+    }
+  });
+  assert.equal(server.options.marker, 'legacy');
+});
+
+test('nested config shape: single profile object', async () => {
+  const server = await boot({
+    settings: {
+      profile: { port: 0, marker: 'nested' },
+      shared: {},
+      security: {}
+    }
+  });
+  assert.equal(server.options.marker, 'nested');
+});

package/test/dipper.test.js

@@ -0,0 +1,76 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const Dipper = require('../framework/dipper.js');
+
+// Dipper reads vanillaJet.package.json from cwd; when absent it degrades gracefully.
+function makeDipper() {
+  return new Dipper({}, { site_name: 'Test', description: 'desc' });
+}
+
+test('urlTo: normalizes local routes and leaves absolute URLs untouched', () => {
+  const dipper = makeDipper();
+  assert.equal(dipper.urlTo('foo/bar'), '/foo/bar');
+  assert.equal(dipper.urlTo('/already'), '/already');
+  assert.equal(dipper.urlTo('https://cdn.example.com/a.js'), 'https://cdn.example.com/a.js');
+  assert.equal(dipper.urlTo('//cdn.example.com/a.js'), '//cdn.example.com/a.js');
+});
+
+test('versionedUrl: fingerprints existing local files and passes through externals', () => {
+  const dipper = makeDipper();
+  // package.json exists at the repo root (cwd during `npm test`).
+  const versioned = dipper.versionedUrl('package.json');
+  assert.match(versioned, /^\/package\.json\?v=\d+-\d+$/);
+  assert.equal(
+    dipper.versionedUrl('https://cdn.example.com/a.js'),
+    'https://cdn.example.com/a.js'
+  );
+  // Non-existent local file keeps legacy behavior (no version param).
+  assert.equal(dipper.versionedUrl('does/not/exist.js'), '/does/not/exist.js');
+});
+
+test('registerScript + includeScript: renders a script tag, with defer when requested', () => {
+  const dipper = makeDipper();
+  dipper.registerScript('plain', '/public/scripts/plain.js');
+  assert.match(dipper.includeScript('plain'), /<script src="\/public\/scripts\/plain\.js"><\/script>/);
+
+  // signature: registerScript(name, url, requires, cdn, async, defer, ...)
+  dipper.registerScript('deferred', '/public/scripts/deferred.js', undefined, false, false, true);
+  assert.match(dipper.includeScript('deferred'), / defer/);
+});
+
+test('registerStyle + includeStyle: renders a stylesheet link', () => {
+  const dipper = makeDipper();
+  dipper.registerStyle('main', '/public/styles/app.min.css');
+  const tag = dipper.includeStyle('main');
+  assert.match(tag, /rel="stylesheet"/);
+  assert.match(tag, /href="\/public\/styles\/app\.min\.css"/);
+});
+
+test('includeServiceWorker: empty when disabled, registers when enabled', () => {
+  const disabled = new Dipper({}, {});
+  assert.equal(disabled.includeServiceWorker(), '');
+
+  const enabled = new Dipper({ enable_service_worker: true }, {});
+  const tag = enabled.includeServiceWorker();
+  assert.match(tag, /serviceWorker/);
+  assert.match(tag, /register\('\/sw\.js'\)/);
+  assert.match(tag, /__VJ_DISABLE_SW__/);
+});
+
+test('enqueue/dequeue: dependencies resolve and clear correctly', () => {
+  const dipper = makeDipper();
+  dipper.registerScript('dep', '/dep.js');
+  dipper.registerScript('main', '/main.js', ['dep']);
+
+  dipper.enqueueScript('main');
+  const enqueued = Object.keys(dipper.enqueued_scripts);
+  assert.ok(enqueued.includes('main'), 'main should be enqueued');
+  assert.ok(enqueued.includes('dep'), 'dependency should be enqueued transitively');
+
+  // Dequeue with dependencies flag clears both.
+  dipper.dequeueScript('main', true);
+  const remaining = Object.keys(dipper.enqueued_scripts);
+  assert.ok(!remaining.includes('main'));
+  assert.ok(!remaining.includes('dep'));
+});

package/test/helpers.js

@@ -0,0 +1,66 @@
+// Shared test utilities for the VanillaJet smoke harness.
+// No external dependencies: only Node built-ins + the framework under test.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Creates a throwaway workspace and writes the given files into it.
+ * @param {Object<string,string|Buffer>} files map of relative path -> content
+ * @returns {string} absolute path to the temp workspace
+ */
+function makeTempWorkspace(files) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vanillajet-test-'));
+  for (const [relativePath, content] of Object.entries(files || {})) {
+    const fullPath = path.join(dir, relativePath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, content);
+  }
+  return dir;
+}
+
+/** Removes a temp workspace created by makeTempWorkspace. */
+function removeWorkspace(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/** Builds the options object that `Server` expects. Use port 0 for an ephemeral port. */
+function serverOptions(port, profile) {
+  return {
+    settings: {
+      profile: Object.assign({ port: port, https_server: false }, profile || {}),
+      shared: {},
+      security: {}
+    }
+  };
+}
+
+/** Resolves once the server socket is actually listening. */
+function waitForListening(server) {
+  return new Promise((resolve) => {
+    if (server.httpx && server.httpx.listening) {
+      return resolve();
+    }
+    server.httpx.once('listening', resolve);
+  });
+}
+
+/** Returns the ephemeral port the server bound to. */
+function boundPort(server) {
+  return server.httpx.address().port;
+}
+
+/** Closes the server socket. */
+function closeServer(server) {
+  return new Promise((resolve) => server.httpx.close(() => resolve()));
+}
+
+module.exports = {
+  makeTempWorkspace,
+  removeWorkspace,
+  serverOptions,
+  waitForListening,
+  boundPort,
+  closeServer
+};

package/test/router.test.js

@@ -0,0 +1,58 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const Router = require('../framework/router.js');
+
+// Router only needs `server.options` for the precompressed flag.
+function makeRouter() {
+  return new Router({ options: { enable_precompressed_negotiation: false } });
+}
+
+test('routeToRegExp: named parameter captures the segment', () => {
+  const router = makeRouter();
+  const re = router.routeToRegExp('/users/:id');
+  assert.ok(re.test('/users/123'));
+  assert.equal('/users/abc'.match(re)[1], 'abc');
+  assert.ok(!re.test('/users'));
+  assert.ok(!re.test('/users/123/edit'));
+});
+
+test('routeToRegExp: optional segment matches with and without it', () => {
+  const router = makeRouter();
+  const re = router.routeToRegExp('/items(/:id)');
+  assert.ok(re.test('/items'));
+  assert.ok(re.test('/items/123'));
+  assert.ok(!re.test('/items/123/extra'));
+});
+
+test('routeToRegExp: splat matches any number of segments', () => {
+  const router = makeRouter();
+  const re = router.routeToRegExp('/files/*path');
+  assert.ok(re.test('/files/a'));
+  assert.ok(re.test('/files/a/b/c.txt'));
+});
+
+test('routeToRegExp: tolerates a trailing query string', () => {
+  const router = makeRouter();
+  const re = router.routeToRegExp('/search');
+  assert.ok(re.test('/search'));
+  assert.ok(re.test('/search?q=test'));
+});
+
+test('isProtectedFile: blocks framework/external/node_modules and top-level files', () => {
+  const router = makeRouter();
+  assert.equal(router.isProtectedFile('/framework/server.js'), true);
+  assert.equal(router.isProtectedFile('/node_modules/x/index.js'), true);
+  assert.equal(router.isProtectedFile('/external/lib.js'), true);
+  assert.equal(router.isProtectedFile('/favicon.ico'), true); // first-level file
+  assert.equal(router.isProtectedFile('/public/scripts/vanilla.min.js'), false);
+});
+
+test('supportsEncoding: honors q-values and array shape', () => {
+  const router = makeRouter();
+  assert.equal(router.supportsEncoding(['gzip'], 'gzip'), true);
+  assert.equal(router.supportsEncoding(['gzip;q=1.0'], 'gzip'), true);
+  assert.equal(router.supportsEncoding(['gzip;q=0'], 'gzip'), false);
+  assert.equal(router.supportsEncoding(['br'], 'gzip'), false);
+  assert.equal(router.supportsEncoding('not-an-array', 'gzip'), false);
+});

package/test/server.test.js

@@ -0,0 +1,103 @@
+const { test, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const Server = require('../framework/server.js');
+const {
+  makeTempWorkspace,
+  removeWorkspace,
+  serverOptions,
+  waitForListening,
+  boundPort,
+  closeServer
+} = require('./helpers.js');
+
+// A minimal endpoint. Handlers must return truthy to mark the request as handled.
+class PingEndpoint {
+  constructor(router) {
+    this.name = 'PingEndpoint';
+    router.addRoute('get', '/ping', 'PingEndpoint.ping');
+    router.addRoute('get', '/home', 'PingEndpoint.home');
+  }
+  ping(request, response) {
+    response.setBody('pong');
+    response.respond();
+    return true;
+  }
+  home(request, response) {
+    response.render(request, 'home.html');
+    return true;
+  }
+}
+
+let server;
+let workspace;
+let previousCwd;
+let baseUrl;
+
+before(async () => {
+  workspace = makeTempWorkspace({
+    'public/scripts/test.min.js': 'console.log("static asset");',
+    'public/pages/home.html': '<!doctype html><title>home</title><h1>HOME_OK</h1>'
+  });
+  previousCwd = process.cwd();
+  process.chdir(workspace);
+
+  server = new Server(serverOptions(0), [PingEndpoint]);
+  await waitForListening(server);
+  baseUrl = `http://127.0.0.1:${boundPort(server)}`;
+});
+
+after(async () => {
+  if (server) {
+    await closeServer(server);
+  }
+  process.chdir(previousCwd);
+  removeWorkspace(workspace);
+});
+
+test('dynamic route returns the endpoint body', async () => {
+  const res = await fetch(`${baseUrl}/ping`);
+  assert.equal(res.status, 200);
+  assert.equal(await res.text(), 'pong');
+});
+
+test('render() streams a precompiled page', async () => {
+  const res = await fetch(`${baseUrl}/home`);
+  assert.equal(res.status, 200);
+  assert.match(res.headers.get('content-type') || '', /text\/html/);
+  assert.match(await res.text(), /HOME_OK/);
+});
+
+test('static asset is served with caching validators', async () => {
+  const res = await fetch(`${baseUrl}/public/scripts/test.min.js`);
+  assert.equal(res.status, 200);
+  assert.match(res.headers.get('content-type') || '', /javascript/);
+  assert.ok(res.headers.get('etag'), 'ETag should be present');
+  assert.ok(res.headers.get('cache-control'), 'Cache-Control should be present');
+  assert.ok(res.headers.get('last-modified'), 'Last-Modified should be present');
+});
+
+test('conditional request returns 304 when ETag matches', async () => {
+  const first = await fetch(`${baseUrl}/public/scripts/test.min.js`);
+  const etag = first.headers.get('etag');
+  await first.arrayBuffer(); // drain
+  assert.ok(etag);
+
+  const second = await fetch(`${baseUrl}/public/scripts/test.min.js`, {
+    headers: { 'If-None-Match': etag }
+  });
+  assert.equal(second.status, 304);
+});
+
+test('missing static file returns 404', async () => {
+  const res = await fetch(`${baseUrl}/public/scripts/missing.js`);
+  await res.arrayBuffer();
+  assert.equal(res.status, 404);
+});
+
+test('protected path returns 404', async () => {
+  const res = await fetch(`${baseUrl}/framework/server.js`);
+  await res.arrayBuffer();
+  assert.equal(res.status, 404);
+});

package/test/service-worker.test.js

@@ -0,0 +1,118 @@
+const { test, before, after, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+const Server = require('../framework/server.js');
+const {
+  makeTempWorkspace,
+  removeWorkspace,
+  serverOptions,
+  waitForListening,
+  boundPort,
+  closeServer
+} = require('./helpers.js');
+
+const GENERATOR = path.join(__dirname, '..', 'framework', '..', 'scripts', 'generate_sw.js');
+
+const PUBLIC_FIXTURE = {
+  'public/styles/app.min.css': 'body{}',
+  'public/scripts/vanilla.min.js': 'console.log(1)',
+  'public/scripts/core/vanillaJet.min.js': 'console.log(2)'
+};
+
+describe('service worker generation', () => {
+  test('enabled: writes public/sw.js with cache name and core precache', () => {
+    const ws = makeTempWorkspace(Object.assign({}, PUBLIC_FIXTURE, {
+      'config.js':
+        "module.exports = { profile: 'qa', settings: { " +
+        "qa: { enable_service_worker: true, service_worker: { cache_prefix: 'testapp' } }, " +
+        "shared: { site_name: 'Test' }, security: {} } };"
+    }));
+    try {
+      execFileSync('node', [GENERATOR], { cwd: ws, stdio: 'pipe' });
+      const swPath = path.join(ws, 'public', 'sw.js');
+      assert.ok(fs.existsSync(swPath), 'sw.js should be generated');
+      const sw = fs.readFileSync(swPath, 'utf8');
+      assert.match(sw, /testapp-sw-[a-f0-9]{12}/, 'cache name should be content-pinned');
+      assert.match(sw, /\/public\/scripts\/vanilla\.min\.js/);
+      assert.match(sw, /\/public\/styles\/app\.min\.css/);
+      assert.ok(!sw.includes('__PRECACHE_ASSETS__'), 'no placeholders should remain');
+      assert.ok(!sw.includes('__CACHE_NAME__'), 'no placeholders should remain');
+    } finally {
+      removeWorkspace(ws);
+    }
+  });
+
+  test('disabled: does not generate sw.js', () => {
+    const ws = makeTempWorkspace(Object.assign({}, PUBLIC_FIXTURE, {
+      'config.js':
+        "module.exports = { profile: 'qa', settings: { qa: {}, shared: {}, security: {} } };"
+    }));
+    try {
+      execFileSync('node', [GENERATOR], { cwd: ws, stdio: 'pipe' });
+      assert.ok(!fs.existsSync(path.join(ws, 'public', 'sw.js')), 'sw.js must not exist when disabled');
+    } finally {
+      removeWorkspace(ws);
+    }
+  });
+});
+
+describe('service worker serving', () => {
+  let server;
+  let ws;
+  let previousCwd;
+  let baseUrl;
+
+  before(async () => {
+    ws = makeTempWorkspace({ 'public/sw.js': '/* sw */' });
+    previousCwd = process.cwd();
+    process.chdir(ws);
+    server = new Server(serverOptions(0, { enable_service_worker: true }), []);
+    await waitForListening(server);
+    baseUrl = `http://127.0.0.1:${boundPort(server)}`;
+  });
+
+  after(async () => {
+    if (server) await closeServer(server);
+    process.chdir(previousCwd);
+    removeWorkspace(ws);
+  });
+
+  test('GET /sw.js returns the worker with root scope header', async () => {
+    const res = await fetch(`${baseUrl}/sw.js`);
+    assert.equal(res.status, 200);
+    assert.match(res.headers.get('content-type') || '', /javascript/);
+    assert.equal(res.headers.get('service-worker-allowed'), '/');
+    assert.match(await res.text(), /sw/);
+  });
+});
+
+describe('service worker disabled at runtime', () => {
+  let server;
+  let ws;
+  let previousCwd;
+  let baseUrl;
+
+  before(async () => {
+    ws = makeTempWorkspace({ 'public/sw.js': '/* sw */' });
+    previousCwd = process.cwd();
+    process.chdir(ws);
+    server = new Server(serverOptions(0), []); // flag off
+    await waitForListening(server);
+    baseUrl = `http://127.0.0.1:${boundPort(server)}`;
+  });
+
+  after(async () => {
+    if (server) await closeServer(server);
+    process.chdir(previousCwd);
+    removeWorkspace(ws);
+  });
+
+  test('GET /sw.js is 404 when the feature is off', async () => {
+    const res = await fetch(`${baseUrl}/sw.js`);
+    await res.arrayBuffer();
+    assert.equal(res.status, 404);
+  });
+});