create-jen-app 1.2.2 → 1.2.4

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

@@ -0,0 +1,295 @@
+import { renderRouteToHtml } from "../runtime/render.js";
+/**
+ * Lightweight LRU (Least Recently Used) Cache implementation.
+ * Maintains insertion order and tracks access time for eviction.
+ */
+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.
+ * Useful in development or when data has changed.
+ */
+export function clearSsrCache() {
+  renderCache.clear();
+}
+/**
+ * Clear a specific cached page by URL pathname.
+ *
+ * @param pathname URL pathname to invalidate
+ */
+export function invalidateSsrCache(pathname) {
+  renderCache.delete(pathname);
+}
+/**
+ * Get cached HTML for a page if it exists and hasn't expired.
+ *
+ * @param pathname URL pathname
+ * @returns Cached HTML string, or null if not cached/expired
+ */
+function getCachedHtml(pathname) {
+  if (!cacheConfig.enabled) return null;
+  const cached = renderCache.get(pathname);
+  if (!cached) return null;
+  const age = (Date.now() - cached.timestamp) / 1000;
+  if (age > cacheConfig.ttlSeconds) {
+    renderCache.delete(pathname);
+    return null;
+  }
+  return cached.html;
+}
+/**
+ * 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(),
+    accessedAt: Date.now(),
+  });
+}
+/**
+ * Core SSR render function: converts a component/template to HTML string.
+ * This is the main entry point for server-side rendering in Jen.js.
+ *
+ * Handles:
+ * 1. Cache lookup for performance
+ * 2. Module compilation (TS/JSX/Vue/Svelte → JS)
+ * 3. Route middleware execution
+ * 4. Loader function invocation (getServerSideProps pattern)
+ * 5. Component rendering to HTML string
+ * 6. Head management and hydration script injection
+ * 7. HTML caching for subsequent requests
+ *
+ * @param config Framework configuration
+ * @param route Route entry being rendered
+ * @param ctx Complete SSR context with request/response and metadata
+ * @returns Complete HTML document as a string
+ * @throws Error if rendering fails
+ *
+ * @example
+ * ```typescript
+ * const html = await render(config, route, {
+ *   req, res, url, params, query, headers, cookies
+ * });
+ * res.setHeader("content-type", "text/html; charset=utf-8");
+ * res.end(html);
+ * ```
+ */
+export async function render(config, route, ctx) {
+  const pathname = ctx.url.pathname;
+  // Check cache first
+  const cached = getCachedHtml(pathname);
+  if (cached) {
+    return cached;
+  }
+  // Render the page
+  const html = await renderRouteToHtml({
+    config,
+    route,
+    req: ctx.req,
+    res: ctx.res,
+    url: ctx.url,
+    params: ctx.params,
+    query: ctx.query,
+    headers: ctx.headers,
+    cookies: ctx.cookies,
+  });
+  // Cache for next request
+  cacheHtml(pathname, html);
+  return html;
+}
+/**
+ * Advanced SSR render with optional caching control.
+ * Allows per-request cache bypass for revalidation.
+ *
+ * @param config Framework configuration
+ * @param route Route entry being rendered
+ * @param ctx Complete SSR context
+ * @param options Render options
+ * @param options.cache Whether to use/update cache (default: true)
+ * @returns Complete HTML document
+ *
+ * @example
+ * ```typescript
+ * const html = await renderWithOptions(config, route, ctx, {
+ *   cache: false // Bypass cache for this request
+ * });
+ * ```
+ */
+export async function renderWithOptions(config, route, ctx, options = {}) {
+  const { cache = true } = options;
+  const pathname = ctx.url.pathname;
+  // Check cache if enabled
+  if (cache) {
+    const cached = getCachedHtml(pathname);
+    if (cached) return cached;
+  }
+  // Render the page
+  const html = await renderRouteToHtml({
+    config,
+    route,
+    req: ctx.req,
+    res: ctx.res,
+    url: ctx.url,
+    params: ctx.params,
+    query: ctx.query,
+    headers: ctx.headers,
+    cookies: ctx.cookies,
+  });
+  // Cache if enabled
+  if (cache) {
+    cacheHtml(pathname, html);
+  }
+  return html;
+}
+/**
+ * Manual HTML rendering of a component to string (no full document).
+ * Useful when you need just the component HTML without head/body wrapper.
+ *
+ * This is a low-level API primarily for internal use.
+ * For typical routing, use render() instead.
+ *
+ * @param config Framework configuration
+ * @param route Route to render
+ * @param ctx SSR context
+ * @returns Just the component body HTML (no <!doctype>, no <head>, no hydration)
+ */
+export async function renderComponentToString(config, route, ctx) {
+  // For now, we render the full HTML and extract the body
+  const html = await renderRouteToHtml({
+    config,
+    route,
+    req: ctx.req,
+    res: ctx.res,
+    url: ctx.url,
+    params: ctx.params,
+    query: ctx.query,
+    headers: ctx.headers,
+    cookies: ctx.cookies,
+  });
+  // Extract body content
+  const bodyMatch = html.match(/<div id="app">([\s\S]*?)<\/div>/);
+  return bodyMatch ? bodyMatch[1] : "";
+}
+/**
+ * Get cache statistics for monitoring and debugging.
+ *
+ * @returns Cache statistics
+ */
+export function getSsrCacheStats() {
+  return {
+    size: renderCache.size,
+    enabled: cacheConfig.enabled,
+    ttlSeconds: cacheConfig.ttlSeconds,
+    entries: Array.from(renderCache.entries()).map(([key, value]) => ({
+      pathname: key,
+      age: (Date.now() - value.timestamp) / 1000,
+      size: value.html.length,
+    })),
+  };
+}

package/templates/static/lib/server-actions/handler.js

@@ -0,0 +1,180 @@
+import { log } from "../shared/log.js";
+/**
+ * Creates a ServerActionContext from request/response objects.
+ * Handles body parsing, header extraction, and cookie parsing.
+ */
+export async function createServerActionContext(opts) {
+  const { req, res, url, params = {}, headers, cookies } = opts;
+  // Parse request body based on content type
+  const body = await parseRequestBody(req);
+  // Extract method
+  const method = (req.method ?? "GET").toUpperCase();
+  // Extract query parameters
+  const query = {};
+  for (const [k, v] of url.searchParams.entries()) {
+    query[k] = v;
+  }
+  return {
+    req,
+    res,
+    url,
+    method,
+    body,
+    query,
+    params,
+    headers,
+    cookies,
+    data: {},
+    validate(input, schema) {
+      const errors = {};
+      let success = true;
+      for (const [fieldName, rules] of Object.entries(schema)) {
+        const value = input[fieldName];
+        for (const rule of rules) {
+          const error = rule.validate(value);
+          if (error) {
+            errors[fieldName] = error;
+            success = false;
+            break; // Stop at first error for this field
+          }
+        }
+      }
+      return { success, errors };
+    },
+    stream() {
+      // Set headers for streaming response
+      if (!res.headersSent) {
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/x-ndjson; charset=utf-8");
+        res.setHeader("transfer-encoding", "chunked");
+      }
+      return {
+        write(data) {
+          const line = typeof data === "string" ? data : JSON.stringify(data);
+          res.write(line + "\n");
+        },
+        writeJSON(data) {
+          res.write(JSON.stringify(data) + "\n");
+        },
+        close() {
+          if (!res.writableEnded) {
+            res.end();
+          }
+        },
+      };
+    },
+  };
+}
+/**
+ * Parse request body from IncomingMessage.
+ * Handles JSON and form data content types.
+ */
+async function parseRequestBody(req) {
+  const method = (req.method ?? "GET").toUpperCase();
+  // Methods without bodies per HTTP spec
+  if (method === "GET" || method === "HEAD") {
+    return null;
+  }
+  // Read all body chunks
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.from(chunk));
+  }
+  if (chunks.length === 0) {
+    return null;
+  }
+  const raw = Buffer.concat(chunks).toString("utf8");
+  const contentType = (req.headers["content-type"] ?? "").toString();
+  // Parse JSON
+  if (contentType.includes("application/json")) {
+    try {
+      return JSON.parse(raw);
+    } catch (err) {
+      log.warn(`Failed to parse JSON body: ${err}`);
+      return { __raw: raw };
+    }
+  }
+  // Parse form data
+  if (contentType.includes("application/x-www-form-urlencoded")) {
+    const data = {};
+    const params = new URLSearchParams(raw);
+    for (const [k, v] of params.entries()) {
+      data[k] = v;
+    }
+    return data;
+  }
+  // Parse multipart form data (basic support)
+  if (contentType.includes("multipart/form-data")) {
+    // For now, return raw. Full multipart parsing requires a library
+    return { __raw: raw };
+  }
+  // Default: return as raw
+  return { __raw: raw };
+}
+/**
+ * Execute a server action handler with the given context.
+ * Handles validation, error handling, and response serialization.
+ */
+export async function executeServerAction(opts) {
+  const { handler, ctx, validation } = opts;
+  try {
+    // Run validation if schema provided
+    if (validation) {
+      const validationResult = ctx.validate(ctx.body, validation);
+      if (!validationResult.success) {
+        ctx.res.statusCode = 400;
+        ctx.res.setHeader("content-type", "application/json; charset=utf-8");
+        ctx.res.end(
+          JSON.stringify({
+            success: false,
+            errors: validationResult.errors,
+            message: "Validation failed",
+          }),
+        );
+        return;
+      }
+    }
+    // Execute the handler
+    const result = await handler(ctx);
+    // If response already sent (streaming), don't double-send
+    if (ctx.res.writableEnded) {
+      return;
+    }
+    // Handle Response object
+    if (result instanceof Response) {
+      ctx.res.statusCode = result.status;
+      result.headers.forEach((v, k) => ctx.res.setHeader(k, v));
+      const buf = Buffer.from(await result.arrayBuffer());
+      ctx.res.end(buf);
+      return;
+    }
+    // Serialize as JSON
+    ctx.res.statusCode = 200;
+    ctx.res.setHeader("content-type", "application/json; charset=utf-8");
+    if (result === null || result === undefined) {
+      ctx.res.end(JSON.stringify({ success: true, data: null }));
+    } else if (typeof result === "string") {
+      ctx.res.end(JSON.stringify({ success: true, data: result }));
+    } else {
+      ctx.res.end(JSON.stringify({ success: true, ...result }));
+    }
+  } catch (err) {
+    // Error response
+    log.error(`Server action error: ${err.message}`);
+    if (!ctx.res.headersSent) {
+      ctx.res.statusCode = 500;
+      ctx.res.setHeader("content-type", "application/json; charset=utf-8");
+    }
+    if (!ctx.res.writableEnded) {
+      ctx.res.end(
+        JSON.stringify({
+          success: false,
+          message: "Internal server error",
+          ...(process.env.NODE_ENV === "development" && {
+            error: err.message,
+          }),
+        }),
+      );
+    }
+  }
+}

package/templates/static/lib/server-actions/index.js

@@ -0,0 +1,19 @@
+// Validators
+export {
+  required,
+  minLength,
+  maxLength,
+  email,
+  url,
+  pattern,
+  range,
+  custom,
+  enumValue,
+  type,
+} from "./validators.js";
+// Scanning and routing
+export { scanServerActions, matchServerAction } from "./scan.js";
+// Handler and context creation
+export { createServerActionContext, executeServerAction } from "./handler.js";
+// Middleware factory
+export { createServerActionsMiddleware } from "./middleware.js";

package/templates/static/lib/server-actions/middleware.js

@@ -0,0 +1,146 @@
+import { pathToFileURL } from "node:url";
+import esbuild from "esbuild";
+import { basename, join } from "node:path";
+import { log } from "../shared/log.js";
+import { headersToObject, parseCookies } from "../core/http.js";
+import { scanServerActions, matchServerAction } from "./scan.js";
+import { createServerActionContext, executeServerAction } from "./handler.js";
+/** Cache directory for transpiled server actions. */
+const actionsCacheDir = join(
+  process.cwd(),
+  "node_modules",
+  ".jen",
+  "actions-cache",
+);
+/**
+ * Transpile a TypeScript server action file to JavaScript.
+ * Uses esbuild to convert TS → JS and output as ESM.
+ */
+async function transpileServerAction(filePath) {
+  const outfile = join(
+    actionsCacheDir,
+    basename(filePath).replace(/\.ts$/, `.${Date.now()}.mjs`),
+  );
+  await esbuild.build({
+    entryPoints: [filePath],
+    outfile,
+    format: "esm",
+    platform: "node",
+    target: "es2022",
+    bundle: false,
+    external: ["preact", "preact-render-to-string", "jenjs"],
+    write: true,
+  });
+  return outfile;
+}
+/**
+ * Load a server action module and extract its configuration and handler.
+ */
+async function loadServerActionModule(filePath) {
+  let moduleUrl = filePath;
+  // Transpile TypeScript to JavaScript if needed
+  if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
+    moduleUrl = await transpileServerAction(filePath);
+  }
+  try {
+    // Cache-busting query param for dev mode
+    const mod = await import(
+      pathToFileURL(moduleUrl).href + `?t=${Date.now()}`
+    );
+    return mod.default ? { default: mod.default, ...mod } : mod;
+  } catch (err) {
+    log.error(`Failed to load server action: ${err.message}`);
+    throw new Error(`Failed to load server action module: ${err.message}`);
+  }
+}
+/**
+ * Create a middleware that handles server actions.
+ * Scans the actions directory and routes requests to action handlers.
+ *
+ * Routes server action requests to /actions/* endpoints and executes them
+ * with validation, error handling, and streaming support.
+ */
+export async function createServerActionsMiddleware(opts) {
+  const { config } = opts;
+  // Scan actions directory once at startup
+  const actions = scanServerActions(config);
+  log.info(`Server actions discovered: ${actions.length}`);
+  for (const a of actions) {
+    log.info(`  ${a.actionPath} (${a.name})`);
+  }
+  // Cache loaded action modules
+  const moduleCache = new Map();
+  return async (ctx, next) => {
+    // Only handle /actions/* requests
+    if (!ctx.url.pathname.startsWith("/actions/")) {
+      return next();
+    }
+    // Extract action path (remove /actions prefix)
+    const actionPath = ctx.url.pathname.slice("/actions".length);
+    // Match against discovered actions
+    const match = matchServerAction(actions, actionPath);
+    if (!match) {
+      ctx.res.statusCode = 404;
+      ctx.res.setHeader("content-type", "application/json; charset=utf-8");
+      ctx.res.end(
+        JSON.stringify({ success: false, message: "Action not found" }),
+      );
+      return;
+    }
+    const { action, params } = match;
+    try {
+      // Load action module (use cache to avoid reloading)
+      let actionModule = moduleCache.get(action.id);
+      if (!actionModule) {
+        actionModule = await loadServerActionModule(action.filePath);
+        moduleCache.set(action.id, actionModule);
+      }
+      // Extract configuration
+      const metadata = actionModule.metadata || {};
+      const validation = actionModule.validation;
+      const handler = actionModule.default;
+      if (!handler || typeof handler !== "function") {
+        ctx.res.statusCode = 500;
+        ctx.res.setHeader("content-type", "application/json; charset=utf-8");
+        ctx.res.end(
+          JSON.stringify({
+            success: false,
+            message: "Invalid action: no handler exported",
+          }),
+        );
+        return;
+      }
+      // Create action context
+      const reqHeaders = headersToObject(ctx.req.headers);
+      const cookies = parseCookies(ctx.req);
+      const actionCtx = await createServerActionContext({
+        req: ctx.req,
+        res: ctx.res,
+        url: ctx.url,
+        params,
+        headers: reqHeaders,
+        cookies,
+      });
+      // Execute server action
+      await executeServerAction({
+        handler,
+        ctx: actionCtx,
+        validation,
+      });
+    } catch (err) {
+      log.error(`Server action error: ${err.message}`);
+      if (!ctx.res.headersSent) {
+        ctx.res.statusCode = 500;
+        ctx.res.setHeader("content-type", "application/json; charset=utf-8");
+      }
+      if (!ctx.res.writableEnded) {
+        ctx.res.end(
+          JSON.stringify({
+            success: false,
+            message: "Internal server error",
+          }),
+        );
+      }
+    }
+  };
+}