create-jen-app 1.2.3 → 1.2.4

package/templates/ssr-isr/lib/build-tools/build-site.js

@@ -0,0 +1,36 @@
+// Site build utilities
+// Migrated from Python src/python/build.py
+import { copyFileSync, rmSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "../shared/log.js";
+function copyDir(src, dst) {
+  if (!readdirSync(src, { withFileTypes: true }).length) return;
+  mkdirSync(dst, { recursive: true });
+  for (const file of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, file.name);
+    const dstPath = join(dst, file.name);
+    if (file.isDirectory()) {
+      copyDir(srcPath, dstPath);
+    } else {
+      copyFileSync(srcPath, dstPath);
+    }
+  }
+}
+export async function buildSite(opts = {}) {
+  log.info("Building site...");
+  const srcDir = "site";
+  const distDir = "dist";
+  // Clean dist
+  try {
+    rmSync(distDir, { recursive: true, force: true });
+  } catch {}
+  // Copy assets
+  copyDir(srcDir, distDir);
+  log.info(`Copied ${srcDir} → ${distDir}`);
+  // Minify if requested
+  if (opts.minify) {
+    log.info("Minifying assets...");
+    // Placeholder: integrate image/font minifiers
+  }
+  log.info("Build complete.");
+}

package/templates/ssr-isr/lib/cache/index.js

@@ -0,0 +1,10 @@
+/**
+ * Cache layer module providing two implementations:
+ * - MemoryCache: In-memory Map-based cache for single-process deployments.
+ * - RedisCache: API contract for distributed caching (requires external redis library).
+ *
+ * Choose MemoryCache for development/testing or single-instance production.
+ * Choose RedisCache for multi-process or distributed environments (must install redis separately).
+ */
+export * from "./memory";
+export * from "./redis";

package/templates/ssr-isr/lib/cache/memory.js

@@ -0,0 +1,40 @@
+/**
+ * In-memory cache implementation using a JavaScript Map.
+ * Stores key-value pairs with optional time-to-live (TTL) expiration.
+ * Useful for development, testing, or single-process deployments.
+ * Not suitable for multi-process environments (values isolated per process).
+ * Note: Expired entries are deleted asynchronously via setTimeout; memory is not
+ * compacted if clear() or delete() are never called on expired keys.
+ */
+export class MemoryCache {
+  /** Internal store mapping cache keys to arbitrary values. */
+  store = new Map();
+  /**
+   * Store a value in cache with optional time-to-live.
+   * If TTL is specified, the entry is automatically deleted after ttlMs milliseconds.
+   * @param key - Cache key identifier.
+   * @param value - Value to store (can be any type; recommend serializable for consistency).
+   * @param ttlMs - Time-to-live in milliseconds. If omitted, entry persists until delete() or process restart.
+   */
+  set(key, value, ttlMs) {
+    this.store.set(key, value);
+    if (ttlMs) setTimeout(() => this.store.delete(key), ttlMs);
+  }
+  /**
+   * Retrieve a value from cache.
+   * Returns undefined if key does not exist or has expired.
+   * @param key - Cache key identifier.
+   * @returns Stored value or undefined if not found.
+   */
+  get(key) {
+    return this.store.get(key);
+  }
+  /**
+   * Remove a value from cache.
+   * Safe to call on non-existent keys (no-op).
+   * @param key - Cache key identifier.
+   */
+  delete(key) {
+    this.store.delete(key);
+  }
+}

package/templates/ssr-isr/lib/cache/redis.js

@@ -0,0 +1,61 @@
+/**
+ * Placeholder Redis cache implementation.
+ * The framework does not include the Redis library; users must install it separately.
+ * This class provides the API contract; actual implementation requires external redis library.
+ * Install with: npm install redis
+ *
+ * Usage example:
+ *   import { RedisCache } from "jenjs";
+ *   const cache = new RedisCache();
+ *   await cache.connect();
+ *   await cache.set("key", { data: "value" }, 3600);
+ *   const val = await cache.get("key");
+ *
+ * Suitable for distributed/multi-process deployments where shared cache is needed.
+ */
+export class RedisCache {
+  /**
+   * Connect to Redis server.
+   * Requires external redis library to be installed.
+   * @throws Always throws if called without external library.
+   */
+  async connect() {
+    throw new Error(
+      "Redis implementation requires external library. Install: npm install redis",
+    );
+  }
+  /**
+   * Store a value in Redis with optional time-to-live.
+   * @param key - Cache key identifier.
+   * @param value - Value to store (should be serializable to JSON).
+   * @param ttlSec - Time-to-live in seconds. If omitted, key persists indefinitely.
+   * @throws Always throws if called without external library.
+   */
+  async set(key, value, ttlSec) {
+    throw new Error(
+      "Redis implementation requires external library. Install: npm install redis",
+    );
+  }
+  /**
+   * Retrieve a value from Redis.
+   * @param key - Cache key identifier.
+   * @returns Stored value or undefined if key does not exist.
+   * @throws Always throws if called without external library.
+   */
+  async get(key) {
+    throw new Error(
+      "Redis implementation requires external library. Install: npm install redis",
+    );
+  }
+  /**
+   * Delete a value from Redis.
+   * Safe to call on non-existent keys (no-op in Redis).
+   * @param key - Cache key identifier.
+   * @throws Always throws if called without external library.
+   */
+  async delete(key) {
+    throw new Error(
+      "Redis implementation requires external library. Install: npm install redis",
+    );
+  }
+}

package/templates/ssr-isr/lib/cli/banner.js

@@ -0,0 +1,28 @@
+// Stylized CLI Banner for Jen.js
+// Matches the visual style requested (Purple/Cyan gradient feel)
+const RES = "\x1b[0m";
+const PURPLE = "\x1b[38;2;200;128;255m"; // #C880FF
+const CYAN = "\x1b[38;2;86;194;201m"; // #56C2C9
+const GRAY = "\x1b[90m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+export function printBanner(port, env, version = "1.0.0") {
+  // Clear screen mostly
+  // console.log("\x1b[2J\x1b[3J\x1b[H");
+  console.log();
+  console.log(`  ${PURPLE}       __               ${CYAN}   _     ${RES}`);
+  console.log(`  ${PURPLE}      / /__  ____       ${CYAN}  (_)____${RES}`);
+  console.log(`  ${PURPLE} __  / / _ \/ __ \      ${CYAN} / / ___/${RES}`);
+  console.log(
+    `  ${PURPLE}/ /_/ /  __/ / / /${GRAY}_____${CYAN}/ / (__  )${RES}`,
+  );
+  console.log(`  ${PURPLE}\____/\___/_/ /_/${GRAY}_____/${CYAN}_/____/ ${RES}`);
+  console.log();
+  console.log(`  ${GRAY}Jen.js Framework ${DIM}v${version}${RES}`);
+  console.log();
+  console.log(
+    `  ${GRAY}➜${RES}  ${BOLD}Local:${RES}   ${CYAN}http://localhost:${port}/${RES}`,
+  );
+  console.log(`  ${GRAY}➜${RES}  ${BOLD}Mode:${RES}    ${PURPLE}${env}${RES}`);
+  console.log();
+}

package/templates/ssr-isr/lib/cli/templates/ssg/jen.config.js

@@ -0,0 +1,32 @@
+const config = {
+  siteDir: "site",
+  distDir: "dist",
+  routes: {
+    fileExtensions: [".tsx", ".jsx", ".ts", ".js"],
+    routeFilePattern: /^\((.+)\)\.(t|j)sx?$/,
+    enableIndexFallback: true,
+  },
+  rendering: {
+    defaultMode: "ssg",
+    defaultRevalidateSeconds: 60,
+  },
+  assets: {
+    publicDir: "site/assets",
+    cacheControl: "public, max-age=31536000, immutable",
+  },
+  inject: {
+    head: [
+      `<meta charset="utf-8">`,
+      `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+    ],
+    bodyEnd: [],
+  },
+  css: {
+    globalScss: "site/styles/global.scss",
+  },
+  server: {
+    port: 3000,
+    hostname: "0.0.0.0",
+  },
+};
+export default config;

package/templates/ssr-isr/lib/cli/templates/ssg/site/index.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+export default function Home() {
+  return _jsxs("div", {
+    children: [
+      _jsx("h1", { children: "Welcome to My SSG App" }),
+      _jsx("p", { children: "This page was generated from the SSG template." }),
+    ],
+  });
+}

package/templates/ssr-isr/lib/cli/templates/ssr/jen.config.js

@@ -0,0 +1,32 @@
+const config = {
+  siteDir: "site",
+  distDir: "dist",
+  routes: {
+    fileExtensions: [".tsx", ".jsx", ".ts", ".js"],
+    routeFilePattern: /^\((.+)\)\.(t|j)sx?$/,
+    enableIndexFallback: true,
+  },
+  rendering: {
+    defaultMode: "ssr",
+    defaultRevalidateSeconds: 60,
+  },
+  assets: {
+    publicDir: "site/assets",
+    cacheControl: "public, max-age=31536000, immutable",
+  },
+  inject: {
+    head: [
+      `<meta charset="utf-8">`,
+      `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+    ],
+    bodyEnd: [],
+  },
+  css: {
+    globalScss: "site/styles/global.scss",
+  },
+  server: {
+    port: 3000,
+    hostname: "0.0.0.0",
+  },
+};
+export default config;

package/templates/ssr-isr/lib/cli/templates/ssr/site/index.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+export default function Home() {
+  return _jsxs("div", {
+    children: [
+      _jsx("h1", { children: "Welcome to My SSR App" }),
+      _jsx("p", { children: "This page is rendered on the server." }),
+    ],
+  });
+}

package/templates/ssr-isr/lib/compilers/esbuild-plugins.js

@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+import { createVueCompiler } from "./vue.js";
+import { createSvelteCompiler } from "./svelte.js";
+const vueCache = new Map();
+const svelteCache = new Map();
+export function vueEsbuildPlugin() {
+  const compiler = createVueCompiler();
+  return {
+    name: "vue",
+    setup(build) {
+      build.onLoad({ filter: /\.vue$/ }, async (args) => {
+        try {
+          // Check cache
+          if (vueCache.has(args.path)) {
+            return {
+              contents: vueCache.get(args.path),
+              loader: "js",
+            };
+          }
+          const source = readFileSync(args.path, "utf-8");
+          const result = compiler.compile(source, {
+            filename: args.path,
+            id: args.path.replace(/[^a-z0-9]/gi, "_"),
+          });
+          if (result.error) {
+            return {
+              errors: [
+                {
+                  text: `Vue compilation failed: ${result.error}`,
+                  location: { file: args.path, line: 1, column: 0 },
+                },
+              ],
+            };
+          }
+          vueCache.set(args.path, result.code);
+          return {
+            contents: result.code,
+            loader: "js",
+          };
+        } catch (err) {
+          return {
+            errors: [
+              {
+                text: `Vue plugin error: ${String(err)}`,
+                location: { file: args.path, line: 1, column: 0 },
+              },
+            ],
+          };
+        }
+      });
+    },
+  };
+}
+export function svelteEsbuildPlugin() {
+  const compiler = createSvelteCompiler();
+  return {
+    name: "svelte",
+    setup(build) {
+      build.onLoad({ filter: /\.svelte$/ }, async (args) => {
+        try {
+          // Check cache
+          if (svelteCache.has(args.path)) {
+            return {
+              contents: svelteCache.get(args.path),
+              loader: "js",
+            };
+          }
+          const source = readFileSync(args.path, "utf-8");
+          const result = compiler.compile(source, {
+            filename: args.path,
+            dev: process.env.NODE_ENV !== "production",
+          });
+          if (result.error) {
+            return {
+              errors: [
+                {
+                  text: `Svelte compilation failed: ${result.error}`,
+                  location: { file: args.path, line: 1, column: 0 },
+                },
+              ],
+            };
+          }
+          svelteCache.set(args.path, result.code);
+          return {
+            contents: result.code,
+            loader: "js",
+          };
+        } catch (err) {
+          return {
+            errors: [
+              {
+                text: `Svelte plugin error: ${String(err)}`,
+                location: { file: args.path, line: 1, column: 0 },
+              },
+            ],
+          };
+        }
+      });
+    },
+  };
+}
+export function invalidateVueCache(filePath) {
+  vueCache.delete(filePath);
+}
+export function invalidateSvelteCache(filePath) {
+  svelteCache.delete(filePath);
+}
+export function clearAllCompilerCaches() {
+  vueCache.clear();
+  svelteCache.clear();
+}

package/templates/ssr-isr/lib/compilers/svelte.js

@@ -0,0 +1,44 @@
+import { compile as svelteCompile } from "svelte/compiler";
+import { log } from "../shared/log.js";
+export class SvelteCompiler {
+  compile(source, options) {
+    try {
+      const filename = options.filename || "component.svelte";
+      const result = svelteCompile(source, {
+        filename,
+        dev: options.dev ?? false,
+        css: "injected", // Inject CSS at runtime instead of extracting
+        preserveComments: !options.minified,
+        preserveWhitespace: !options.minified,
+      });
+      if (result.warnings && result.warnings.length > 0) {
+        result.warnings.forEach((w) => {
+          log.warn(`[Svelte] ${filename}: ${w.message}`);
+        });
+      }
+      // Build module code
+      let code = result.js.code;
+      // If CSS is generated, inject it
+      if (result.css && result.css.code.trim()) {
+        const escapedCss = result.css.code
+          .replace(/"/g, '\\"')
+          .replace(/\n/g, "\\n");
+        code += `
+if (typeof window !== 'undefined') {
+  const style = document.createElement('style');
+  style.textContent = "${escapedCss}";
+  document.head.appendChild(style);
+}
+`;
+      }
+      return { code };
+    } catch (err) {
+      const message = err.message || String(err);
+      log.error(`[Svelte] Compilation error: ${message}`);
+      return { code: "", error: message };
+    }
+  }
+}
+export function createSvelteCompiler() {
+  return new SvelteCompiler();
+}

package/templates/ssr-isr/lib/compilers/vue.js

@@ -0,0 +1,90 @@
+import {
+  parse,
+  compileScript,
+  compileTemplate,
+  compileStyle,
+} from "@vue/compiler-sfc";
+import { log } from "../shared/log.js";
+export class VueCompiler {
+  compile(source, options) {
+    try {
+      const filename = options.filename || "component.vue";
+      const id = options.id || filename.replace(/[^a-z0-9]/gi, "_");
+      // Parse SFC
+      const parseResult = parse(source, { filename });
+      const descriptor = parseResult.descriptor;
+      let scriptCode = "";
+      let templateCode = "";
+      let styleCode = "";
+      // Compile script
+      if (descriptor.script || descriptor.scriptSetup) {
+        const scriptCompiled = compileScript(descriptor, {
+          id,
+          isProd: options.minified ?? false,
+        });
+        scriptCode = scriptCompiled.content;
+      }
+      // Compile template
+      if (descriptor.template) {
+        const templateCompiled = compileTemplate({
+          source: descriptor.template.content,
+          filename,
+          id,
+          compilerOptions: {
+            isCustomElement: (tag) => tag.startsWith("custom-"),
+          },
+        });
+        if (templateCompiled.errors.length > 0) {
+          return {
+            code: "",
+            error: `Template compilation error: ${templateCompiled.errors.join(", ")}`,
+          };
+        }
+        templateCode = templateCompiled.code;
+      }
+      // Compile styles (scoped)
+      if (descriptor.styles.length > 0) {
+        descriptor.styles.forEach((style, idx) => {
+          const styleCompiled = compileStyle({
+            source: style.content,
+            filename,
+            id,
+            scoped: style.scoped ?? false,
+          });
+          if (styleCompiled.errors.length > 0) {
+            log.warn(
+              `Style compilation warning at style[${idx}]: ${styleCompiled.errors.join(", ")}`,
+            );
+          }
+          styleCode += styleCompiled.code + "\n";
+        });
+      }
+      // Inject styles at runtime
+      let injectStyle = "";
+      if (styleCode.trim()) {
+        const escapedStyle = styleCode
+          .replace(/"/g, '\\"')
+          .replace(/\n/g, "\\n");
+        injectStyle = `
+const style = document.createElement('style');
+style.textContent = "${escapedStyle}";
+document.head.appendChild(style);
+`;
+      }
+      // Build final module
+      const finalCode = `
+${scriptCode || "export default {}"}
+${templateCode}
+${injectStyle}
+`;
+      return { code: finalCode };
+    } catch (err) {
+      const message = err.message || String(err);
+      log.error(`[Vue] Compilation error: ${message}`);
+      return { code: "", error: message };
+    }
+  }
+}
+export function createVueCompiler() {
+  return new VueCompiler();
+}

package/templates/ssr-isr/lib/core/http.js

@@ -0,0 +1,71 @@
+/**
+ * Parses the HTTP Cookie header into an object of name-value pairs.
+ *
+ * Cookie format (RFC 6265):
+ * - Multiple cookies separated by semicolons
+ * - Each cookie is name=value with optional whitespace
+ * - Cookie values are URL-encoded and must be decoded
+ *
+ * Edge cases handled:
+ * - Missing or empty Cookie header returns empty object
+ * - Whitespace is trimmed from names and values
+ * - Values may contain equals signs (split only on first =)
+ * - Empty names or values are filtered out
+ * - Values are URL-decoded to handle special characters
+ *
+ * @param req Node.js IncomingMessage with headers property
+ *
+ * @returns Object with cookie names as keys and decoded values
+ *
+ * @example
+ * // Header: "sessionId=abc123; theme=dark; path=/admin"
+ * // Returns: { sessionId: "abc123", theme: "dark", path: "/admin" }
+ *
+ * // Header missing or empty
+ * // Returns: {}
+ */
+export function parseCookies(req) {
+  const cookie = req.headers.cookie;
+  if (!cookie) return {};
+  const out = {};
+  for (const part of cookie.split(";")) {
+    const [k, ...rest] = part.trim().split("=");
+    const trimmedName = k.trim();
+    const trimmedValue = rest.join("=").trim();
+    if (trimmedName && trimmedValue) {
+      out[trimmedName] = decodeURIComponent(trimmedValue);
+    }
+  }
+  return out;
+}
+/**
+ * Converts Node.js headers object to a flat string-valued object.
+ *
+ * Header normalization:
+ * - Node.js headers may have array values (for multiple headers with same name)
+ * - Arrays are joined with comma-space to follow HTTP spec (RFC 2822)
+ * - Non-array string values are kept as-is
+ * - Header names are already lowercased by Node.js
+ *
+ * Motivation:
+ * Application code typically expects headers as a flat object with string values,
+ * not Node.js's mixed types. This normalizes the data structure for consistency.
+ *
+ * @param headers The headers object from IncomingMessage.headers
+ *
+ * @returns Flat object with header names (lowercase) as keys and string values
+ *
+ * @example
+ * // Input (from Node.js):
+ * { accept: "text/html", "accept-encoding": ["gzip", "deflate"], "content-type": "application/json" }
+ * // Output:
+ * { accept: "text/html", "accept-encoding": "gzip, deflate", "content-type": "application/json" }
+ */
+export function headersToObject(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (Array.isArray(v)) out[k] = v.join(", ");
+    else if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}

package/templates/ssr-isr/lib/core/middleware-hooks.js

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+}
+/**
+ * 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) {
+      /**
+       * 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;
+    }
+  }
+}