create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/core/layouts/render.js

@@ -0,0 +1,158 @@
+import { h } from "preact";
+import { pathToFileURL } from "node:url";
+import esbuild from "esbuild";
+import { join } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+import {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+} from "../../compilers/esbuild-plugins.js";
+/**
+ * Resolves the cache directory path for compiled layout modules.
+ * Similar to route module caching to avoid repeated compilation.
+ *
+ * @param filePath The absolute path to the original layout file
+ * @returns The absolute path to the cached compiled output file
+ */
+function getCachePath(filePath) {
+  const cacheDir = join(process.cwd(), "node_modules", ".jen", "cache");
+  if (!existsSync(cacheDir)) {
+    mkdirSync(cacheDir, { recursive: true });
+  }
+  const flatName = filePath.replace(/[\\/:]/g, "_").replace(/^_+/, "");
+  return join(cacheDir, flatName + ".layout.mjs");
+}
+/**
+ * Loads and compiles a layout module from file.
+ * Handles TypeScript/JSX/Vue/Svelte transpilation.
+ *
+ * @param filePath The absolute path to the layout file
+ * @returns The imported LayoutModule
+ * @throws Error if compilation or import fails
+ */
+async function loadLayoutModule(filePath) {
+  let moduleUrl = filePath;
+  const ext = filePath.slice(-4).toLowerCase();
+  const requiresTranspile = [".tsx", ".ts", ".vue", ".svelte"].some((e) =>
+    filePath.toLowerCase().endsWith(e),
+  );
+  if (requiresTranspile) {
+    const outfile = getCachePath(filePath);
+    await esbuild.build({
+      entryPoints: [filePath],
+      outfile,
+      format: "esm",
+      platform: "node",
+      target: "es2022",
+      bundle: true,
+      external: ["preact", "preact-render-to-string", "jenjs"],
+      write: true,
+      plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
+    });
+    moduleUrl = outfile;
+  }
+  let mod;
+  try {
+    mod = await import(pathToFileURL(moduleUrl).href + "?t=" + Date.now());
+  } catch (err) {
+    throw new Error(
+      `Failed to import layout module ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  // Validate that default export exists
+  if (!mod.default) {
+    throw new Error(
+      `Layout module ${filePath} does not export a default component`,
+    );
+  }
+  return mod;
+}
+/**
+ * Resolves the complete layout stack for a route.
+ * Loads all applicable layouts, merges their configuration, and prepares them for rendering.
+ *
+ * Configuration is merged from root to leaf, with child configurations overriding parent values.
+ *
+ * @param layoutEntries All layout entries applicable to this route (from buildLayoutHierarchy)
+ * @returns Resolved layout stack with modules and merged configuration
+ * @throws Error if any layout file fails to load
+ */
+export async function resolveLayoutStack(layoutEntries) {
+  const modules = [];
+  let mergedConfig = {};
+  // Load and process layouts in order (root to leaf)
+  for (const entry of layoutEntries) {
+    const mod = await loadLayoutModule(entry.filePath);
+    modules.push(mod);
+    // Merge configuration (child overrides parent)
+    if (mod.layout) {
+      mergedConfig = {
+        ...mergedConfig,
+        ...mod.layout,
+      };
+    }
+  }
+  return {
+    modules,
+    config: mergedConfig,
+  };
+}
+/**
+ * Renders a component wrapped in a layout hierarchy.
+ * Composes all layouts from root to leaf, passing the child content down the tree.
+ *
+ * The composition works as:
+ * RootLayout wraps (BlogLayout wraps (PageLayout wraps (PageComponent)))
+ *
+ * Each layout receives:
+ * - children: The rendered output from the child layout or page component
+ * - data: Data passed from page loader
+ * - params: URL parameters
+ * - query: Query string parameters
+ *
+ * @param layoutStack The resolved layout stack
+ * @param pageComponent The Preact component to render as the deepest child
+ * @param props Props to pass through the layout hierarchy (data, params, query)
+ * @returns Preact VNode representing the composed layout tree
+ */
+export function renderWithLayoutStack(layoutStack, pageComponent, props) {
+  // Start with the page component as the innermost content
+  let content = h(pageComponent, props);
+  // Wrap with layouts from deepest to root (reverse order)
+  for (let i = layoutStack.modules.length - 1; i >= 0; i--) {
+    const layoutMod = layoutStack.modules[i];
+    const Layout = layoutMod.default;
+    // Pass children and props to each layout
+    content = h(Layout, {
+      children: content,
+      ...props,
+    });
+  }
+  return content;
+}
+/**
+ * Collects all Head components from the layout stack.
+ * Head components are rendered in order from root to leaf, allowing layouts
+ * to contribute to document head (meta tags, title, links, etc.).
+ *
+ * @param layoutStack The resolved layout stack
+ * @param pageHeadComponent Optional Head component from the page
+ * @param props Props to pass to Head components
+ * @returns Array of rendered Head VNodes
+ */
+export function collectLayoutHeads(layoutStack, pageHeadComponent, props) {
+  const heads = [];
+  // Collect heads from layouts (root to leaf)
+  for (const layoutMod of layoutStack.modules) {
+    if (layoutMod.Head) {
+      const headNode = h(layoutMod.Head, props);
+      heads.push(headNode);
+    }
+  }
+  // Page head comes last
+  if (pageHeadComponent) {
+    const headNode = h(pageHeadComponent, props);
+    heads.push(headNode);
+  }
+  return heads;
+}

package/templates/static/lib/core/layouts/scan.js

@@ -0,0 +1,112 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, sep, dirname } from "node:path";
+/**
+ * Recursively walks a directory and returns all file paths.
+ * Used to discover all layout files in the siteDir.
+ *
+ * @param dir Directory path to walk
+ * @returns Flat array of all file paths found
+ */
+function walk(dir) {
+  const out = [];
+  try {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name);
+      const st = statSync(p);
+      if (st.isDirectory()) out.push(...walk(p));
+      else out.push(p);
+    }
+  } catch {
+    // Ignore errors reading directories
+  }
+  return out;
+}
+/**
+ * Normalizes filesystem path separators to forward slashes.
+ * Ensures consistent path format across Windows and Unix systems.
+ *
+ * @param p Path with possibly mixed separators
+ * @returns Path with forward slashes only
+ */
+function normalizeSlashes(p) {
+  return p.split(sep).join("/");
+}
+/**
+ * Scans the configured siteDir for layout files and returns an ordered list.
+ * Layout files must be named (layout).tsx, (layout).ts, (layout).jsx, or (layout).js
+ * and are discovered at any directory level within siteDir.
+ *
+ * Layouts are automatically discovered and organized by their directory depth,
+ * allowing for automatic hierarchy building based on file structure.
+ *
+ * @param config Framework configuration with siteDir and route patterns
+ * @returns Array of LayoutEntry objects, sorted by depth (root layout first)
+ */
+export function scanLayouts(config) {
+  const siteRoot = join(process.cwd(), config.siteDir);
+  const files = walk(siteRoot);
+  const layouts = [];
+  for (const abs of files) {
+    const rel = normalizeSlashes(relative(siteRoot, abs));
+    // Check if this is a layout file with correct extension
+    const extMatch = config.routes.fileExtensions.some((ext) =>
+      rel.endsWith(`(layout)${ext}`),
+    );
+    if (!extMatch) continue;
+    // Get the directory containing this layout file
+    const dirPath = normalizeSlashes(dirname(rel));
+    const depth = dirPath === "." ? 0 : dirPath.split("/").length;
+    layouts.push({
+      id: `layout_${rel.replaceAll("/", "_").replace(/\.\w+$/, "")}`,
+      filePath: abs,
+      depth,
+      dirPath: dirPath === "." ? "" : dirPath,
+    });
+  }
+  // Sort by depth (root/shallowest first)
+  layouts.sort((a, b) => a.depth - b.depth);
+  return layouts;
+}
+/**
+ * Builds the layout hierarchy for a given route path.
+ * Finds all parent layouts that should apply to this route by tracing
+ * the directory structure from root down to the route's directory.
+ *
+ * Example: For route "pages/blog/post/(post).tsx", returns layouts at:
+ * - (layout).tsx (root)
+ * - pages/(layout).tsx (if exists)
+ * - pages/blog/(layout).tsx (if exists)
+ *
+ * @param layoutEntries All discovered layout entries (from scanLayouts)
+ * @param routePath The filesystem path of the route file
+ * @returns Array of LayoutEntry objects in order (root to leaf)
+ */
+export function buildLayoutHierarchy(layoutEntries, routePath, siteDir) {
+  // Get the directory containing the route
+  const routeDir = dirname(routePath);
+  // Normalize path relative to siteDir
+  const siteRoot = join(process.cwd(), siteDir);
+  const relRouteDir = normalizeSlashes(relative(siteRoot, routeDir));
+  // Split the route directory into segments
+  const segments = relRouteDir === "." ? [] : relRouteDir.split("/");
+  // Find applicable layouts by checking each level of the hierarchy
+  const applicable = [];
+  // Check root layout first
+  const rootLayout = layoutEntries.find(
+    (l) => l.depth === 0 && l.dirPath === "",
+  );
+  if (rootLayout) {
+    applicable.push(rootLayout);
+  }
+  // Check layouts at each level
+  for (let i = 1; i <= segments.length; i++) {
+    const dirPath = segments.slice(0, i).join("/");
+    const layout = layoutEntries.find(
+      (l) => l.dirPath === dirPath && l.depth === i,
+    );
+    if (layout) {
+      applicable.push(layout);
+    }
+  }
+  return applicable;
+}

package/templates/static/lib/core/layouts/types.js

@@ -0,0 +1 @@
+export {};

package/templates/static/lib/core/lifecycle.js

@@ -0,0 +1,129 @@
+import { log } from "../shared/log.js";
+/**
+ * Lifecycle manager for graceful shutdown of the HTTP server.
+ * Tracks active requests and ensures they complete before closing.
+ * Handles signal interrupts (SIGTERM, SIGINT) gracefully.
+ */
+export class GracefulShutdown {
+  activeRequests = new Set();
+  isShuttingDown = false;
+  shutdownTimeout = 30000; // 30s timeout for graceful shutdown
+  signalHandlers = [];
+  /**
+   * Tracks an incoming request.
+   * Call this when a request begins.
+   */
+  trackRequest(req) {
+    this.activeRequests.add(req);
+  }
+  /**
+   * Untrack a request when it completes.
+   * Call this when a request ends.
+   */
+  releaseRequest(req) {
+    this.activeRequests.delete(req);
+  }
+  /**
+   * Get the count of active requests still in flight.
+   */
+  getActiveRequestCount() {
+    return this.activeRequests.size;
+  }
+  /**
+   * Check if shutdown is in progress.
+   */
+  isShuttingDown_() {
+    return this.isShuttingDown;
+  }
+  /**
+   * Wait for all active requests to complete, with timeout.
+   * Useful before closing server resources.
+   *
+   * @returns Promise that resolves when all requests complete or timeout
+   */
+  async waitForActiveRequests() {
+    const startTime = Date.now();
+    const pollInterval = 100; // ms
+    return new Promise((resolve) => {
+      const poll = () => {
+        if (this.activeRequests.size === 0) {
+          log.info(
+            `[Graceful Shutdown] All ${this.activeRequests.size} requests completed`,
+          );
+          resolve();
+          return;
+        }
+        const elapsed = Date.now() - startTime;
+        if (elapsed > this.shutdownTimeout) {
+          log.warn(
+            `[Graceful Shutdown] Timeout after ${elapsed}ms with ${this.activeRequests.size} requests still active`,
+          );
+          resolve();
+          return;
+        }
+        setTimeout(poll, pollInterval);
+      };
+      poll();
+    });
+  }
+  /**
+   * Handle shutdown signal (SIGTERM or SIGINT).
+   * Prevents accepting new requests and waits for in-flight ones.
+   *
+   * @param signal Signal name that was received
+   * @param onClose Callback to execute when ready to close server
+   */
+  async handleShutdownSignal(signal, onClose) {
+    if (this.isShuttingDown) {
+      log.warn(`[Graceful Shutdown] Already shutting down, ignoring ${signal}`);
+      return;
+    }
+    this.isShuttingDown = true;
+    log.warn(
+      `[Graceful Shutdown] ${signal} received, starting graceful shutdown`,
+    );
+    log.info(
+      `[Graceful Shutdown] ${this.activeRequests.size} active request(s)`,
+    );
+    // Wait for active requests to complete
+    await this.waitForActiveRequests();
+    // Close server resources
+    log.info("[Graceful Shutdown] Closing server resources");
+    await onClose();
+    log.info("[Graceful Shutdown] Clean shutdown complete");
+  }
+  /**
+   * Register signal handlers for graceful shutdown.
+   * Handles SIGTERM and SIGINT.
+   *
+   * @param onClose Callback to execute when closing resources
+   */
+  registerSignalHandlers(onClose) {
+    const handleSignal = async (signal) => {
+      await this.handleShutdownSignal(signal, onClose);
+      process.exit(0);
+    };
+    // Handle both SIGTERM (terminate) and SIGINT (Ctrl+C)
+    process.on("SIGTERM", () => handleSignal("SIGTERM"));
+    process.on("SIGINT", () => handleSignal("SIGINT"));
+    log.info("[Graceful Shutdown] Signal handlers registered");
+  }
+  /**
+   * Clean up signal handlers.
+   * Useful for cleanup in tests or when you need to unregister.
+   */
+  unregisterSignalHandlers() {
+    process.removeAllListeners("SIGTERM");
+    process.removeAllListeners("SIGINT");
+  }
+  /**
+   * Set the timeout for graceful shutdown (in milliseconds).
+   * Default is 30s.
+   *
+   * @param timeoutMs Timeout in milliseconds
+   */
+  setShutdownTimeout(timeoutMs) {
+    this.shutdownTimeout = timeoutMs;
+  }
+}
+export default GracefulShutdown;

package/templates/static/lib/core/loader-schema.js

@@ -0,0 +1,81 @@
+/**
+ * Type-safe loader data schema pattern.
+ * Ensures loader return type matches component props type at compile time.
+ *
+ * @example
+ * ```typescript
+ * type PageData = { posts: Post[]; count: number };
+ *
+ * export const loader = defineLoader<PageData>(async (ctx) => {
+ *   return {
+ *     posts: await fetchPosts(),
+ *     count: 42,
+ *   };
+ * });
+ *
+ * export default function Page({ data }: { data: PageData }) {
+ *   return <div>{data.count} posts</div>;
+ * }
+ * ```
+ */
+export function defineLoader(handler) {
+  return async (ctx) => {
+    const result = handler(ctx);
+    return Promise.resolve(result);
+  };
+}
+/**
+ * Validates that loader data matches expected schema.
+ * Runtime check to catch type mismatches in development.
+ *
+ * @example
+ * ```typescript
+ * const data = validateLoaderData(result, { posts: 'array', count: 'number' });
+ * ```
+ */
+export function validateLoaderData(data, schema) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error(`Expected object, got ${typeof data}`);
+  }
+  const obj = data;
+  for (const [key, type] of Object.entries(schema)) {
+    const value = obj[key];
+    // Determine actual type (arrays are objects, so treat both as "object")
+    let actualType = typeof value;
+    if (value === null) {
+      actualType = "object"; // null is typeof 'object' in JavaScript
+    } else if (Array.isArray(value)) {
+      actualType = type === "array" ? "array" : "object";
+    }
+    if (actualType !== type) {
+      throw new Error(
+        `Loader data mismatch: expected ${key} to be ${type}, got ${actualType}`,
+      );
+    }
+  }
+  return obj;
+}
+/**
+ * Middleware data schema for type-safe middleware → loader flow.
+ *
+ * @example
+ * ```typescript
+ * type MiddlewareData = { userId: number; isAdmin: boolean };
+ * type PageData = { user: User; canDelete: boolean };
+ *
+ * export const middleware = defineMiddleware<MiddlewareData>(async (ctx) => {
+ *   return { userId: 42, isAdmin: true };
+ * });
+ *
+ * export const loader = defineLoader<PageData>(async (ctx) => {
+ *   const { userId, isAdmin } = ctx.data as MiddlewareData;
+ *   return { user: await getUser(userId), canDelete: isAdmin };
+ * });
+ * ```
+ */
+export function defineMiddleware(handler) {
+  return async (ctx) => {
+    const result = handler(ctx);
+    return Promise.resolve(result);
+  };
+}

package/templates/static/lib/core/middleware-hooks.js

@@ -1,69 +1,97 @@
-/*
- * 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/>.
- */
 /**
- * Note: Route module types (middleware, hydrate fields) are defined in core/types.ts
- * This module just provides the middleware execution primitives.
+ * Type definitions note:
+ * Route module types (middleware field, hydrate field) are defined in core/types.ts.
+ * This module provides the middleware execution engine and context object.
  */
 /**
- * Create middleware context from request.
- * Called by server before rendering route.
+ * Creates a middleware context object from request data.
+ * Called by the renderer before executing route middleware.
+ *
+ * Initializes:
+ * - All request data (req, res, url, params, query, headers, cookies)
+ * - Empty data object for middleware to populate
+ * - Helper methods (status, setHeader, redirect, json) as chainable methods
+ *
+ * @param opts Configuration with raw request data
+ * @param opts.req Node.js IncomingMessage
+ * @param opts.res Node.js ServerResponse
+ * @param opts.url Parsed URL from request
+ * @param opts.params Route parameters from URL path
+ * @param opts.query Query string parameters
+ * @param opts.headers Normalized headers object
+ * @param opts.cookies Parsed cookies from Cookie header
+ *
+ * @returns Initialized RouteMiddlewareContext ready for middleware execution
  */
 export function createRouteMiddlewareContext(opts) {
-    const ctx = {
-        ...opts,
-        data: {},
-        status: function (code) {
-            this.res.statusCode = code;
-            return this;
-        },
-        setHeader: function (key, value) {
-            this.res.setHeader(key, value);
-            return this;
-        },
-        redirect: function (url, statusCode = 302) {
-            this.res.statusCode = statusCode;
-            this.res.setHeader("location", url);
-            this.res.end();
-            throw new Error("__REDIRECT__");
-        },
-        json: function (data, statusCode = 200) {
-            this.res.statusCode = statusCode;
-            this.res.setHeader("content-type", "application/json; charset=utf-8");
-            this.res.end(JSON.stringify(data));
-            throw new Error("__JSON__");
-        },
-    };
-    return ctx;
+  const ctx = {
+    ...opts,
+    data: {},
+    status: function (code) {
+      this.res.statusCode = code;
+      return this;
+    },
+    setHeader: function (key, value) {
+      this.res.setHeader(key, value);
+      return this;
+    },
+    redirect: function (url, statusCode = 302) {
+      this.res.statusCode = statusCode;
+      this.res.setHeader("location", url);
+      this.res.end();
+      throw new Error("__REDIRECT__");
+    },
+    json: function (data, statusCode = 200) {
+      this.res.statusCode = statusCode;
+      this.res.setHeader("content-type", "application/json; charset=utf-8");
+      this.res.end(JSON.stringify(data));
+      throw new Error("__JSON__");
+    },
+  };
+  return ctx;
 }
 /**
- * Execute route middlewares in sequence.
- * If any middleware calls redirect() or json(), it throws and stops execution.
+ * Executes an array of route middleware sequentially for a route.
+ *
+ * Execution model:
+ * 1. Iterates through middlewares in order
+ * 2. Each middleware is awaited (even if synchronous)
+ * 3. Middleware can populate ctx.data for use by loader and page
+ * 4. If middleware calls ctx.redirect() or ctx.json(), error is caught and re-thrown
+ * 5. Other errors are propagated immediately
+ *
+ * Control flow:
+ * - Normal completion: all middlewares finish and function returns
+ * - Early exit: middleware calls ctx.redirect() or ctx.json()
+ * - Error: middleware throws or ctx.redirect()/json() throws sentinel error
+ *
+ * Side effects:
+ * - Response headers, status, and body may be sent by middleware
+ * - ctx.data may be modified by middleware
+ * - Should only be called in server context (SSR); not during SSG build
+ *
+ * @param middlewares Array of middleware functions to execute
+ * @param ctx RouteMiddlewareContext created by createRouteMiddlewareContext()
+ *
+ * @returns Promise that resolves if all middlewares complete normally
+ * @throws Error with message "__REDIRECT__" if middleware calls ctx.redirect()
+ * @throws Error with message "__JSON__" if middleware calls ctx.json()
+ * @throws Error from middleware if it throws
  */
 export async function executeRouteMiddleware(middlewares, ctx) {
-    for (const mw of middlewares) {
-        try {
-            await mw(ctx);
-        }
-        catch (err) {
-            if (err.message === "__REDIRECT__" || err.message === "__JSON__") {
-                throw err;
-            }
-            throw err;
-        }
+  for (const mw of middlewares) {
+    try {
+      await mw(ctx);
+    } catch (err) {
+      /**
+       * Sentinel errors from ctx.redirect() and ctx.json() are re-thrown
+       * to signal that the response was already sent.
+       * Other errors propagate normally for error handling middleware.
+       */
+      if (err.message === "__REDIRECT__" || err.message === "__JSON__") {
+        throw err;
+      }
+      throw err;
     }
+  }
 }