create-jen-app 1.2.3 → 1.2.4

package/templates/static/lib/server/isr.js

@@ -0,0 +1,365 @@
+import { renderWithOptions } from "./ssr.js";
+/**
+ * In-memory storage for ISR cache entries.
+ * Persists across requests using stale-while-revalidate pattern.
+ */
+const isrCache = new Map();
+/**
+ * Global default revalidation interval (seconds).
+ * Can be overridden per-route via RouteEntry.revalidateSeconds.
+ * Defaults to 1 hour.
+ */
+let defaultRevalidateSeconds = 3600;
+let isrConfig = {
+  defaultRevalidateSeconds: 3600,
+  maxConcurrentRevalidations: 5,
+  debug: false,
+};
+/** Counter to track concurrent revalidations */
+let concurrentRevalidations = 0;
+/**
+ * Configure ISR behavior globally.
+ * Allows customization of revalidation intervals and concurrency.
+ *
+ * @param config Partial ISR configuration to merge
+ *
+ * @example
+ * ```typescript
+ * import * as ISR from './isr.ts';
+ *
+ * ISR.setIsrConfig({
+ *   defaultRevalidateSeconds: 300, // 5 minutes
+ *   debug: true
+ * });
+ * ```
+ */
+export function setIsrConfig(config) {
+  isrConfig = { ...isrConfig, ...config };
+  if (config.defaultRevalidateSeconds !== undefined) {
+    defaultRevalidateSeconds = config.defaultRevalidateSeconds;
+  }
+}
+/**
+ * Get the current ISR configuration.
+ *
+ * @returns Current ISR configuration
+ */
+export function getIsrConfig() {
+  return { ...isrConfig };
+}
+/**
+ * Log debug message if ISR debug mode is enabled.
+ *
+ * @param message Log message
+ * @param args Additional log arguments
+ */
+function debugLog(message, ...args) {
+  if (isrConfig.debug) {
+    console.log(`[ISR] ${message}`, ...args);
+  }
+}
+/**
+ * Determine if cached HTML has exceeded its revalidation TTL.
+ * Returns true if the cache should be regenerated in the background.
+ *
+ * @param entry ISR cache entry to check
+ * @returns true if revalidation is needed
+ */
+function isRevalidationNeeded(entry) {
+  const now = Date.now();
+  const revalidateTtl =
+    (entry.revalidateSeconds ?? defaultRevalidateSeconds) * 1000;
+  const age = now - entry.timestamp;
+  return age > revalidateTtl;
+}
+/**
+ * Enqueue a background revalidation task.
+ * Respects maxConcurrentRevalidations to prevent overwhelming the server.
+ *
+ * @param fn Async function to execute in background
+ */
+async function enqueueRevalidation(fn) {
+  // Wait for slot to become available if at capacity
+  while (concurrentRevalidations >= isrConfig.maxConcurrentRevalidations) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  concurrentRevalidations++;
+  try {
+    await fn();
+  } finally {
+    concurrentRevalidations--;
+  }
+}
+/**
+ * Main ISR entry point: fetch or generate cached HTML for a route.
+ * Implements stale-while-revalidate pattern:
+ * - Serves cached HTML immediately if available
+ * - Regenerates in background if expired (without blocking response)
+ * - Regenerates on-demand if no cache exists
+ *
+ * This function integrates seamlessly with Jen.js's render() function.
+ *
+ * @param config Framework configuration
+ * @param route Route entry being requested
+ * @param ctx SSR context with request/response metadata
+ * @param options ISR-specific options
+ * @param options.revalidate Override revalidation TTL (seconds), overrides route.revalidateSeconds
+ * @returns Cached or freshly rendered HTML
+ *
+ * @throws Error if rendering fails and no cache exists
+ *
+ * @example
+ * ```typescript
+ * import * as ISR from './isr.ts';
+ * import { getIsrHtml, setIsrConfig } from './isr.ts';
+ *
+ * // Setup
+ * setIsrConfig({ defaultRevalidateSeconds: 300, debug: true });
+ *
+ * // In route handler
+ * app.get('/:path(*)', async (req, res) => {
+ *   try {
+ *     const html = await getIsrHtml(config, route, {
+ *       req, res, url, params, query, headers, cookies
+ *     });
+ *     res.setHeader('content-type', 'text/html; charset=utf-8');
+ *     res.end(html);
+ *   } catch (err) {
+ *     res.statusCode = 500;
+ *     res.end('Rendering failed');
+ *   }
+ * });
+ *
+ * // Per-route override
+ * const html = await getIsrHtml(config, route, ctx, {
+ *   revalidate: 60 // Regenerate every 60 seconds for this request
+ * });
+ * ```
+ */
+export async function getIsrHtml(config, route, ctx, options) {
+  const pathname = ctx.url.pathname;
+  const now = Date.now();
+  // Lookup existing cache entry
+  const cached = isrCache.get(pathname);
+  // If we have cached content, serve it immediately
+  if (cached) {
+    debugLog(`Cache hit for ${pathname}`);
+    // Check if revalidation is needed (stale-while-revalidate pattern)
+    const needsRevalidation = isRevalidationNeeded(cached);
+    if (needsRevalidation && !cached.revalidating) {
+      debugLog(`Initiating background revalidation for ${pathname}`);
+      // Mark as revalidating and enqueue background task
+      cached.revalidating = true;
+      cached.revalidationPromise = enqueueRevalidation(async () => {
+        try {
+          const freshHtml = await renderWithOptions(config, route, ctx, {
+            cache: false,
+          });
+          cached.html = freshHtml;
+          cached.timestamp = now;
+          debugLog(`Background revalidation complete for ${pathname}`);
+        } catch (err) {
+          debugLog(`Background revalidation failed for ${pathname}:`, err);
+          // Keep serving stale cache on error; don't propagate failure
+        } finally {
+          cached.revalidating = false;
+        }
+      });
+    }
+    // Return cached HTML immediately (stale-while-revalidate pattern)
+    return cached.html;
+  }
+  // No cache exists - render on-demand and cache result
+  debugLog(`Cache miss, rendering on-demand for ${pathname}`);
+  const html = await renderWithOptions(config, route, ctx, { cache: false });
+  // Determine revalidation TTL (order of precedence)
+  let revalidateTtl = defaultRevalidateSeconds;
+  if (options?.revalidate !== undefined) {
+    revalidateTtl = options.revalidate;
+  } else if (
+    "revalidateSeconds" in route &&
+    typeof route.revalidateSeconds === "number"
+  ) {
+    revalidateTtl = route.revalidateSeconds;
+  }
+  // Store in ISR cache
+  isrCache.set(pathname, {
+    html,
+    timestamp: now,
+    revalidateSeconds: revalidateTtl,
+    revalidating: false,
+  });
+  debugLog(`Cached ${pathname} with TTL ${revalidateTtl}s`);
+  return html;
+}
+/**
+ * Manually set or update ISR cache for a route.
+ * Useful for programmatic cache invalidation and updates.
+ *
+ * @param routePath URL pathname to cache (e.g., "/", "/about", "/posts/123")
+ * @param html Complete HTML document to cache
+ * @param options Cache options
+ * @param options.revalidate Custom revalidation interval (seconds), overrides default
+ *
+ * @example
+ * ```typescript
+ * import { setIsrCache } from './isr.ts';
+ *
+ * // After updating a blog post
+ * app.post('/api/posts/:id', async (req, res) => {
+ *   // ... update database ...
+ *
+ *   // Regenerate and cache the post page
+ *   const html = await renderPost(req.params.id);
+ *   setIsrCache(`/posts/${req.params.id}`, html, { revalidate: 3600 });
+ *
+ *   res.json({ success: true });
+ * });
+ * ```
+ */
+export function setIsrCache(routePath, html, options) {
+  const now = Date.now();
+  const revalidateTtl = options?.revalidate ?? defaultRevalidateSeconds;
+  isrCache.set(routePath, {
+    html,
+    timestamp: now,
+    revalidateSeconds: revalidateTtl,
+    revalidating: false,
+  });
+  debugLog(
+    `Manually set ISR cache for ${routePath} with TTL ${revalidateTtl}s`,
+  );
+}
+/**
+ * Invalidate ISR cache for a specific route.
+ * Forces regeneration on next request.
+ *
+ * @param routePath URL pathname to invalidate
+ *
+ * @example
+ * ```typescript
+ * import { invalidateIsrCache } from './isr.ts';
+ *
+ * app.post('/api/posts/:id/publish', async (req, res) => {
+ *   // ... publish logic ...
+ *   invalidateIsrCache(`/posts/${req.params.id}`);
+ *   res.json({ success: true });
+ * });
+ * ```
+ */
+export function invalidateIsrCache(routePath) {
+  isrCache.delete(routePath);
+  debugLog(`Invalidated ISR cache for ${routePath}`);
+}
+/**
+ * Clear the entire ISR cache.
+ * Useful after bulk data updates or deployment.
+ *
+ * @example
+ * ```typescript
+ * import { clearIsrCache } from './isr.ts';
+ *
+ * // After re-importing data
+ * await importDataFromSources();
+ * clearIsrCache();
+ * ```
+ */
+export function clearIsrCache() {
+  isrCache.clear();
+  debugLog("Cleared entire ISR cache");
+}
+/**
+ * Get comprehensive ISR cache statistics.
+ * Useful for monitoring cache health and performance.
+ *
+ * Returns cache size, entry details (age, TTL, size), and revalidation status.
+ * All ages are calculated at call time.
+ *
+ * @returns ISR cache statistics
+ *
+ * @example
+ * ```typescript
+ * import { getIsrStats } from './isr.ts';
+ *
+ * app.get('/admin/isr-stats', (req, res) => {
+ *   const stats = getIsrStats();
+ *   console.log(`Cache size: ${stats.size} routes`);
+ *   console.log(`Revalidating: ${stats.revalidating}/${stats.maxConcurrentRevalidations}`);
+ *
+ *   stats.entries.forEach(entry => {
+ *     console.log(`${entry.pathname}: age=${entry.age}s, ttl=${entry.revalidateSeconds}s`);
+ *   });
+ *
+ *   res.json(stats);
+ * });
+ * ```
+ */
+export function getIsrStats() {
+  const now = Date.now();
+  const entries = [];
+  let revalidatingCount = 0;
+  for (const [pathname, entry] of isrCache.entries()) {
+    const age = (now - entry.timestamp) / 1000;
+    const revalidateSeconds =
+      entry.revalidateSeconds ?? defaultRevalidateSeconds;
+    entries.push({
+      pathname,
+      age,
+      revalidateSeconds,
+      size: entry.html.length,
+      revalidating: entry.revalidating,
+    });
+    if (entry.revalidating) {
+      revalidatingCount++;
+    }
+  }
+  return {
+    size: isrCache.size,
+    entries,
+    revalidating: revalidatingCount,
+    maxConcurrentRevalidations: isrConfig.maxConcurrentRevalidations,
+    defaultRevalidateSeconds,
+  };
+}
+/**
+ * Wait for all in-flight revalidations to complete.
+ * Useful in testing or graceful shutdown scenarios.
+ *
+ * @param timeout Maximum time to wait in milliseconds (default: 30000)
+ * @returns Promise that resolves when all revalidations complete or timeout occurs
+ *
+ * @example
+ * ```typescript
+ * import { waitForRevalidations } from './isr.ts';
+ *
+ * // In graceful shutdown
+ * process.on('SIGTERM', async () => {
+ *   console.log('Waiting for revalidations to complete...');
+ *   await waitForRevalidations(5000);
+ *   server.close();
+ * });
+ * ```
+ */
+export async function waitForRevalidations(timeout = 30000) {
+  const startTime = Date.now();
+  const promises = [];
+  for (const entry of isrCache.values()) {
+    if (entry.revalidating && entry.revalidationPromise) {
+      promises.push(entry.revalidationPromise);
+    }
+  }
+  if (promises.length === 0) {
+    return;
+  }
+  try {
+    await Promise.race([
+      Promise.all(promises),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error("Revalidation timeout")), timeout),
+      ),
+    ]);
+  } catch (err) {
+    const elapsed = Date.now() - startTime;
+    debugLog(`Revalidation wait timed out after ${elapsed}ms`);
+  }
+}

package/templates/static/lib/server/runtimeServe.js

@@ -1,24 +1,10 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { buildSync } from "esbuild";
+import { readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { basename, dirname } from "node:path";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Cache for compiled hydration modules.
  * Stores transpiled JS code and computed ETag hash per source file path.
@@ -46,10 +32,17 @@ function etagOf(s) {
  * @returns ES module code string for browser hydration runtime
  */
 export function runtimeHydrateModule() {
-  // Browser-safe runtime (ESM) using CDN preact (fast + zero bundler)
+  // Browser-safe runtime (ESM) using local vendored preact code
+  // Inline preact directly from vendor directory for zero external dependencies
+  const preactCode = readFileSync(
+    resolve(__dirname, "../vendor/preact/preact.module.js"),
+    "utf-8",
+  );
   return `
-import { hydrate } from "https://esm.sh/preact@10.25.4";
-import { h } from "https://esm.sh/preact@10.25.4";
+${preactCode}
+
+const { hydrate, h } = preact;
+delete globalThis.preact;
 
 function getFrameworkData() {
   const el = document.getElementById("__FRAMEWORK_DATA__");
@@ -164,10 +157,24 @@ export function buildHydrationModule(routeIdOrPath) {
       console.error("[HYDRATION] Failed to build module for:", filePath);
       return `export default function Page(){ return null }`;
     }
+    // Read vendored preact and inject it with proper globals
+    const preactCode = readFileSync(
+      resolve(__dirname, "../vendor/preact/preact.module.js"),
+      "utf-8",
+    );
+    // Wrap the hydration module with inlined preact
+    const mappedOutput = `
+    ${preactCode}
+
+    ${jsOutput
+      .replace(/from ["']preact\/jsx-runtime["']/g, 'from "preact/jsx-runtime"')
+      .replace(/from ["']preact\/hooks["']/g, 'from "preact/hooks"')
+      .replace(/from ["']preact(?!\/|["'])/g, 'from "preact"')}
+    `;
     // Cache result with ETag
-    const etag = etagOf(jsOutput);
-    cache.set(key, { js: jsOutput, etag });
-    return jsOutput;
+    const etag = etagOf(mappedOutput);
+    cache.set(key, { js: mappedOutput, etag });
+    return mappedOutput;
   } catch (err) {
     console.error("[HYDRATION] Build error for", filePath, ":", err);
     return `export default function Page(){ return null }`;

package/templates/static/lib/server/ssr.js

@@ -1,38 +1,109 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { renderRouteToHtml } from "../runtime/render.js";
 /**
- * HTML rendering cache for performance optimization.
- * Cache key is URL pathname. Useful for frequently accessed pages.
- * In production, consider using Redis or external cache for distributed rendering.
+ * Lightweight LRU (Least Recently Used) Cache implementation.
+ * Maintains insertion order and tracks access time for eviction.
  */
-const renderCache = new Map();
+class LRUCache {
+  map = new Map();
+  maxSize;
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  get(key) {
+    const entry = this.map.get(key);
+    if (entry) {
+      // Move to end (most recently used)
+      this.map.delete(key);
+      entry.accessedAt = Date.now();
+      this.map.set(key, entry);
+    }
+    return entry;
+  }
+  set(key, entry) {
+    // Remove if exists to re-insert at end
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    }
+    this.map.set(key, entry);
+    // Evict least recently used if over capacity
+    if (this.map.size > this.maxSize) {
+      const firstKey = this.map.keys().next().value;
+      if (firstKey) {
+        this.map.delete(firstKey);
+      }
+    }
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+  entries() {
+    return this.map.entries();
+  }
+}
+const renderCache = new LRUCache(1000);
 let cacheConfig = {
   enabled: true,
   ttlSeconds: 3600, // Default: 1 hour
+  maxEntries: 1000, // Default: 1000 max cached pages
 };
+/**
+ * Background sweep interval (ms) to clean expired entries.
+ */
+const CACHE_SWEEP_INTERVAL = 5 * 60 * 1000; // 5 minutes
+/**
+ * Start periodic cache cleanup to remove expired entries.
+ */
+function startCacheSweep() {
+  const sweepTimer = setInterval(() => {
+    if (!cacheConfig.enabled) return;
+    const now = Date.now();
+    const ttlMs = (cacheConfig.ttlSeconds ?? 3600) * 1000;
+    for (const [key, entry] of renderCache.entries()) {
+      const age = now - entry.timestamp;
+      if (age > ttlMs) {
+        renderCache.delete(key);
+      }
+    }
+  }, CACHE_SWEEP_INTERVAL);
+  // Prevent Node.js process from exiting due to this timer
+  if (typeof sweepTimer.unref === "function") {
+    sweepTimer.unref();
+  }
+  return sweepTimer;
+}
+// Start the background sweep
+if (typeof global !== "undefined") {
+  try {
+    startCacheSweep();
+  } catch {
+    // Ignore if called in non-Node environment
+  }
+}
 /**
  * Configure the SSR HTML cache behavior.
+ * Updates maxEntries for the LRU cache if provided.
  *
  * @param config Cache configuration options
  */
 export function configureSsrCache(config) {
   cacheConfig = { ...cacheConfig, ...config };
+  // Update LRU cache size if maxEntries changed
+  if (config.maxEntries && config.maxEntries > 0) {
+    // Reinitialize LRU cache with new size
+    const existing = Array.from(renderCache.entries());
+    renderCache.clear();
+    // Recreate with new size (this is a limitation of the current approach,
+    // but maxEntries rarely changes at runtime)
+    for (const [key, entry] of existing) {
+      renderCache.set(key, entry);
+    }
+  }
 }
 /**
  * Clear the entire SSR render cache.
@@ -68,13 +139,18 @@ function getCachedHtml(pathname) {
 }
 /**
  * Cache rendered HTML for a page.
+ * LRU eviction occurs automatically when maxEntries is exceeded.
  *
  * @param pathname URL pathname
  * @param html Complete HTML string to cache
  */
 function cacheHtml(pathname, html) {
   if (!cacheConfig.enabled) return;
-  renderCache.set(pathname, { html, timestamp: Date.now() });
+  renderCache.set(pathname, {
+    html,
+    timestamp: Date.now(),
+    accessedAt: Date.now(),
+  });
 }
 /**
  * Core SSR render function: converts a component/template to HTML string.