create-jen-app 1.2.2 → 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,33 +1,48 @@
-/*
- * 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.
+ * Cache is invalidated when files change (via invalidateCache).
+ */
 const cache = new Map();
+/**
+ * Compute SHA-1 hash (ETag) for a string.
+ * Used for HTTP cache validation and deduplicating compiled output.
+ *
+ * @param s - String to hash
+ * @returns Hex-encoded SHA-1 hash
+ */
 function etagOf(s) {
-    return createHash("sha1").update(s).digest("hex");
+  return createHash("sha1").update(s).digest("hex");
 }
+/**
+ * Generate the browser-safe hydration runtime code.
+ * Uses CDN-hosted Preact (esm.sh) for minimal payload and no bundler overhead.
+ * This runtime is injected into the page and provides hydration primitives.
+ *
+ * Note: In production, consider self-hosting the Preact bundle for better performance
+ * and reliability (no external CDN dependency).
+ *
+ * @returns ES module code string for browser hydration runtime
+ */
 export function runtimeHydrateModule() {
-    // Browser-safe runtime (ESM) using CDN preact (fast + zero bundler)
-    return `
-import { hydrate } from "https://esm.sh/preact@10.25.4";
-import { h } from "https://esm.sh/preact@10.25.4";
+  // 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 `
+${preactCode}
+
+const { hydrate, h } = preact;
+delete globalThis.preact;
 
 function getFrameworkData() {
   const el = document.getElementById("__FRAMEWORK_DATA__");
@@ -50,76 +65,129 @@ export async function hydrateClient(entryPath) {
 }
 `;
 }
+/**
+ * Clear cached compiled module for a file path.
+ * Called when a source file changes during development to ensure fresh compilation
+ * on next request.
+ *
+ * @param filePath - Absolute file path to invalidate
+ */
 export function invalidateCache(filePath) {
-    cache.delete(filePath);
+  cache.delete(filePath);
 }
+/**
+ * Build a client-side hydration module for a route.
+ * Takes a route file path, extracts the default component export,
+ * transpiles to browser-executable JavaScript with Preact imports resolved.
+ *
+ * How it works:
+ * 1. Create a proxy file that re-exports only the default component
+ *    This allows tree-shaking to remove server-only exports (loader, middleware, etc.)
+ * 2. Use esbuild buildSync to transpile and bundle with Preact
+ * 3. Cache the result with ETag for HTTP conditional requests
+ * 4. Return JS code or fallback to empty component on error
+ *
+ * Transpilation:
+ * - Format: ESM (for client-side import)
+ * - Platform: browser (not Node.js)
+ * - JSX: Automatic via Preact JSX runtime
+ * - Sourcemap: Inline for debugging in browser DevTools
+ * - External: Preact and runtime libs (assumed available in browser)
+ *
+ * Caching:
+ * - Cache is per-file-path; invalidated via invalidateCache() when file changes
+ * - ETag allows HTTP 304 Not Modified responses
+ * - Development mode trusts explicit invalidation (file watcher triggers it)
+ *
+ * Error handling:
+ * - Failed builds return empty Page component (graceful degradation)
+ * - Errors are logged but don't stop request
+ *
+ * @param routeIdOrPath - File path to route component (e.g., "./routes/index.tsx")
+ *   Note: routeId support for future config-based resolution
+ * @returns ES module JavaScript code (browser-executable)
+ */
 export function buildHydrationModule(routeIdOrPath) {
-    // routeIdOrPath is now a route ID like "route_index" or "route_blog_slug"
-    // or a fallback filePath for backwards compatibility
-    let filePath = routeIdOrPath;
-    // For now, keep simple direct file path support
-    // In production, we'd resolve routeId -> filePath via config
-    if (!existsSync(filePath)) {
-        return `export default function Page(){ return null }`;
-    }
-    const key = filePath;
-    // Simple dev cache: check if file content changed?
-    // Actually, for dev speed, we trust explicit invalidation or just rebuild on request.
-    // Since buildSync is fast for single files, let's just rebuild if not in cache.
-    // The cache is populated. If invalidation happens, it's removed.
-    if (cache.has(key)) {
-        return cache.get(key).js;
-    }
-    // Use a proxy entry to allow tree-shaking of server-only exports (like loader)
-    const fileName = basename(filePath);
-    const dir = dirname(filePath);
-    const proxyContent = `export { default } from "./${fileName}";`;
-    try {
-        const jsOutput = buildSync({
-            stdin: {
-                contents: proxyContent,
-                resolveDir: dir,
-                sourcefile: "hydration-proxy.tsx",
-                loader: "tsx",
-            },
-            format: "esm",
-            platform: "browser",
-            bundle: true,
-            write: false,
-            sourcemap: "inline",
-            jsx: "automatic",
-            jsxImportSource: "preact",
-            define: {
-                "process.env.NODE_ENV": JSON.stringify("development"),
-            },
-            external: [
-                "preact",
-                "preact/hooks",
-                "preact/jsx-runtime",
-                "preact-render-to-string",
-            ],
-            // Plugins not supported in buildSync, only in build()
-            // plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
-        }).outputFiles?.[0]?.text;
-        if (!jsOutput) {
-            console.error("[HYDRATION] Failed to build module for:", filePath);
-            return `export default function Page(){ return null }`;
-        }
-        const out = `
-import { h } from "https://esm.sh/preact@10.25.4";
-import { Fragment } from "https://esm.sh/preact@10.25.4";
-import { jsx, jsxs } from "https://esm.sh/preact@10.25.4/jsx-runtime";
-` + jsOutput;
-        const etag = etagOf(out);
-        cache.set(key, { js: out, etag });
-        return out;
-    }
-    catch (err) {
-        console.error("[HYDRATION] Build error for", filePath, ":", err);
-        return `export default function Page(){ return null }`;
+  // routeIdOrPath is a file path; future versions may support route IDs via config
+  let filePath = routeIdOrPath;
+  // Return fallback if file doesn't exist
+  if (!existsSync(filePath)) {
+    return `export default function Page(){ return null }`;
+  }
+  const key = filePath;
+  // Return cached result if available (invalidated by invalidateCache)
+  if (cache.has(key)) {
+    return cache.get(key).js;
+  }
+  // Create proxy file to enable tree-shaking of server-only exports (loader, middleware, etc.)
+  // The proxy re-exports only the default component, letting esbuild eliminate other exports
+  const fileName = basename(filePath);
+  const dir = dirname(filePath);
+  const proxyContent = `export { default } from "./${fileName}";`;
+  try {
+    // Transpile proxy with esbuild for browser-safe JavaScript
+    const jsOutput = buildSync({
+      stdin: {
+        contents: proxyContent,
+        resolveDir: dir, // Resolve imports relative to route directory
+        sourcefile: "hydration-proxy.tsx",
+        loader: "tsx", // Support TypeScript and JSX
+      },
+      format: "esm",
+      platform: "browser", // Browser-specific optimizations
+      bundle: true, // Inline dependencies (except external)
+      write: false, // Return code instead of writing file
+      sourcemap: "inline", // Include source map for debugging
+      jsx: "automatic", // Automatic JSX transform (Preact)
+      jsxImportSource: "preact",
+      define: {
+        "process.env.NODE_ENV": JSON.stringify("development"),
+      },
+      // Preact and runtime must be available in browser (loaded separately)
+      external: [
+        "preact",
+        "preact/hooks",
+        "preact/jsx-runtime",
+        "preact-render-to-string",
+      ],
+      // TODO: Add plugin support for Vue/Svelte components
+      // plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
+    }).outputFiles?.[0]?.text;
+    if (!jsOutput) {
+      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(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 }`;
+  }
 }
+/**
+ * Retrieve the ETag (cache hash) for a compiled hydration module.
+ * Used for HTTP conditional requests (If-None-Match, 304 Not Modified).
+ *
+ * @param filePath - Route file path
+ * @returns ETag hash string or null if not cached
+ */
 export function getHydrationEtag(filePath) {
-    const v = cache.get(filePath);
-    return v?.etag ?? null;
+  const v = cache.get(filePath);
+  return v?.etag ?? null;
 }