create-jen-app 1.2.3 → 1.2.4

package/templates/static/lib/core/feature-guard.js

@@ -0,0 +1,136 @@
+import { isFeatureEnabled } from "./features.js";
+/**
+ * Feature guard errors provide helpful context when code tries to use disabled features.
+ * Includes the feature name and guidance on how to enable it.
+ */
+export class FeatureDisabledError extends Error {
+  feature;
+  constructor(feature, context) {
+    const msg =
+      `Feature "${feature}" is not enabled. ` +
+      `Enable it in jen.config.ts with: features: { ${feature}: true }${context ? ` (${context})` : ""}`;
+    super(msg);
+    this.feature = feature;
+    this.name = "FeatureDisabledError";
+  }
+}
+/**
+ * Feature configuration errors indicate invalid feature configuration.
+ */
+export class FeatureConfigError extends Error {
+  feature;
+  constructor(feature, details) {
+    super(`Invalid configuration for feature "${feature}": ${details}`);
+    this.feature = feature;
+    this.name = "FeatureConfigError";
+  }
+}
+/**
+ * Validates that a feature is enabled before execution.
+ * Throws helpful error if feature is disabled.
+ *
+ * Use in feature module entry points to prevent disabled features from running.
+ *
+ * @param features Resolved feature configuration
+ * @param feature Feature name to validate
+ * @param context Optional context (e.g., function name) for error message
+ * @throws FeatureDisabledError if feature is not enabled
+ *
+ * @example
+ * export function setupApiRoutes(features: ResolvedFeatures) {
+ *   guardFeature(features, "api", "API route handling");
+ *   // ... API setup code
+ * }
+ */
+export function guardFeature(features, feature, context) {
+  if (!isFeatureEnabled(features, feature)) {
+    throw new FeatureDisabledError(feature, context);
+  }
+}
+/**
+ * Guards multiple features, throwing if any are disabled.
+ * Useful for features that depend on other features.
+ *
+ * @example
+ * export function setupAdvancedMiddleware(features: ResolvedFeatures) {
+ *   guardFeatures(features, ["middleware", "cache"], "Advanced middleware");
+ *   // ... code that uses both features
+ * }
+ */
+export function guardFeatures(features, required, context) {
+  const missing = required.filter((f) => !isFeatureEnabled(features, f));
+  if (missing.length > 0) {
+    const list = missing.join(", ");
+    throw new Error(
+      `Features required: ${list}. ` +
+        `Enable them in jen.config.ts${context ? ` (${context})` : ""}`,
+    );
+  }
+}
+/**
+ * Type guard that narrows feature type based on enabled status.
+ * Allows TypeScript to enforce feature availability at compile time.
+ *
+ * @example
+ * if (isFeatureAvailable(features, "api")) {
+ *   // TypeScript knows "api" is enabled here
+ *   const result = handleApiRequest(...);
+ * }
+ */
+export function isFeatureAvailable(features, feature) {
+  return isFeatureEnabled(features, feature);
+}
+/**
+ * Wraps a function to guard against disabled features.
+ * Returns a function that checks feature before execution.
+ *
+ * @example
+ * export const setupCache = guardedFunction("cache", (features) => {
+ *   // This only runs if cache feature is enabled
+ * });
+ */
+export function guardedFunction(feature, fn, context) {
+  return (...args) => {
+    const features = args[0];
+    guardFeature(features, feature, context);
+    return fn(...args);
+  };
+}
+/**
+ * Async version of guardedFunction for async handlers.
+ */
+export function guardedAsyncFunction(feature, fn, context) {
+  return async (...args) => {
+    const features = args[0];
+    guardFeature(features, feature, context);
+    return fn(...args);
+  };
+}
+/**
+ * Creates a feature validation middleware.
+ * Checks if required feature is enabled before processing request.
+ *
+ * @example
+ * app.use(featureMiddleware("api", (ctx, next) => {
+ *   // Only runs if api feature is enabled
+ *   return handleApiRequest(ctx);
+ * }));
+ */
+export function createFeatureMiddleware(feature, context) {
+  return (features) => {
+    guardFeature(features, feature, context);
+  };
+}
+/**
+ * Validates feature configuration against a schema.
+ */
+export function validateFeatureConfig(feature, config, validator) {
+  if (!validator) return;
+  const result = validator.validate(config);
+  if (!result.valid) {
+    throw new FeatureConfigError(
+      feature,
+      result.errors?.join("; ") || "Invalid configuration",
+    );
+  }
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Feature System for Jen.js
+ *
+ * Allows optional features to be enabled/disabled at build time.
+ * Disabled features are completely tree-shaken, adding zero runtime overhead.
+ *
+ * Features are configured in jen.config.ts and enabled/disabled individually.
+ * Each feature must be explicitly enabled for its code to be included in the bundle.
+ */
+/**
+ * Default features enabled when none specified.
+ * Minimal set to maintain backward compatibility.
+ * Users should explicitly enable features they use.
+ */
+export const DEFAULT_FEATURES = {
+  api: false,
+  middleware: false,
+  markdown: false,
+  imageOpt: false,
+  env: true, // Environment variables needed by default
+  cache: false,
+  streaming: false,
+  auth: false,
+  graphql: false,
+  db: false,
+  i18n: false,
+  jdb: false,
+  compilers: false,
+  import: false,
+};
+/**
+ * Validates and normalizes user feature configuration.
+ * Ensures all features have explicit enabled/disabled status.
+ *
+ * @param userConfig User-provided feature config from jen.config.ts
+ * @returns Resolved features with all present and validated
+ */
+export function resolveFeatures(userConfig) {
+  const resolved = { ...DEFAULT_FEATURES };
+  if (!userConfig) return resolved;
+  for (const [key, value] of Object.entries(userConfig)) {
+    if (!(key in DEFAULT_FEATURES)) {
+      console.warn(
+        `⚠️  Unknown feature: "${key}". Valid features are: ${Object.keys(DEFAULT_FEATURES).join(", ")}`,
+      );
+      continue;
+    }
+    // Support boolean shorthand and object with enabled property
+    const isEnabled =
+      typeof value === "boolean" ? value : value?.enabled !== false;
+    resolved[key] = isEnabled;
+  }
+  return resolved;
+}
+/**
+ * Returns list of enabled feature names.
+ */
+export function getEnabledFeatures(resolved) {
+  return Object.entries(resolved)
+    .filter(([, enabled]) => enabled)
+    .map(([name]) => name);
+}
+/**
+ * Returns list of disabled feature names.
+ */
+export function getDisabledFeatures(resolved) {
+  return Object.entries(resolved)
+    .filter(([, enabled]) => !enabled)
+    .map(([name]) => name);
+}
+/**
+ * Checks if a specific feature is enabled.
+ */
+export function isFeatureEnabled(resolved, feature) {
+  return resolved[feature] ?? false;
+}
+/**
+ * Runtime assertion that a feature is enabled.
+ * Throws helpful error if feature is disabled.
+ */
+export function requireFeature(resolved, feature, context) {
+  if (!isFeatureEnabled(resolved, feature)) {
+    const msg =
+      `Feature "${feature}" is not enabled. ` +
+      `Enable it in jen.config.ts: features: { ${feature}: true }${context ? ` (${context})` : ""}`;
+    throw new Error(msg);
+  }
+}
+/**
+ * Creates build metadata for introspection and debugging.
+ */
+export function createBuildMetadata(resolved, config) {
+  return {
+    buildTime: new Date().toISOString(),
+    enabledFeatures: getEnabledFeatures(resolved),
+    disabledFeatures: getDisabledFeatures(resolved),
+    config,
+  };
+}

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

@@ -1,20 +1,3 @@
-/*
- * 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/>.
- */
 /**
  * Parses the HTTP Cookie header into an object of name-value pairs.
  *

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

@@ -0,0 +1,10 @@
+/**
+ * Nested layouts system for Jen.js
+ * Provides automatic parent-child layout relationships with inheritance and overrides.
+ */
+export { scanLayouts, buildLayoutHierarchy } from "./scan.js";
+export {
+  resolveLayoutStack,
+  renderWithLayoutStack,
+  collectLayoutHeads,
+} from "./render.js";

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;