create-jen-app 1.2.3 → 1.2.4

package/templates/ssr-isr/lib/middleware/pipeline.js

@@ -0,0 +1,148 @@
+/**
+ * Middleware composition and execution engine.
+ * Composes multiple middleware functions into a single callable function.
+ * Supports functions, class constructors, and objects with handle() methods.
+ *
+ * The Pipeline implements the "cascade" or "onion" middleware pattern:
+ * - Middlewares are executed sequentially in order
+ * - Each middleware receives a next() function to pass control to the next handler
+ * - Execution returns through each middleware in reverse order
+ * - Early termination is possible by not calling next()
+ *
+ * @example
+ * const middlewares = [
+ *   (ctx, next) => { console.log("1 start"); next().then(() => console.log("1 end")); },
+ *   (ctx, next) => { console.log("2 start"); next().then(() => console.log("2 end")); },
+ * ];
+ * // Logs: "1 start", "2 start", "2 end", "1 end" (onion pattern)
+ */
+export class Pipeline {
+  /**
+   * Composes an array of middleware into a single callable function.
+   * The composed function accepts (context, finalNext) and executes middlewares in sequence.
+   *
+   * Middleware resolution:
+   * - Functions are passed through as-is
+   * - Class constructors (functions with prototype.handle) are instantiated and their handle() bound
+   * - Objects with handle() methods have handle() bound to them
+   *
+   * @param middleware Array of middleware to compose
+   * @returns Composed function: async (context, next) => Promise<void>
+   *
+   * @throws {TypeError} If middleware is not an array
+   * @throws {TypeError} If a middleware is not a function, class, or object with handle()
+   *
+   * @example
+   * const composed = Pipeline.compose([authMiddleware, loggingMiddleware]);
+   * await composed(ctx, () => console.log("done"));
+   */
+  static compose(middleware) {
+    if (!Array.isArray(middleware))
+      throw new TypeError("Middleware stack must be an array!");
+    /**
+     * Resolve each middleware to a callable function.
+     * Handles functions, class constructors, and objects with handle() methods.
+     */
+    const handlers = middleware.map((mw) => this.resolveMiddleware(mw));
+    /**
+     * Returns the composed middleware function that executes the pipeline.
+     * Uses the dispatch() pattern to enforce single-next-call and maintain order.
+     *
+     * @param context Request context object passed to each middleware
+     * @param next Final handler called after all middlewares
+     * @returns Promise that resolves when entire pipeline completes
+     */
+    return function (context, next) {
+      /**
+       * Tracks the current dispatch index to detect "next() called multiple times".
+       * This prevents middleware from accidentally calling next() twice,
+       * which would cause handlers to execute in wrong order.
+       */
+      let index = -1;
+      /**
+       * Dispatches (executes) the middleware at index i.
+       * Enforces that next() can only be called once by checking index increment.
+       *
+       * @param i Index of the middleware to execute
+       * @returns Promise from the middleware or final next() handler
+       */
+      function dispatch(i) {
+        if (i <= index)
+          return Promise.reject(new Error("next() called multiple times"));
+        index = i;
+        let fn = handlers[i];
+        /**
+         * If we've exhausted all middlewares, call the final next() handler.
+         * This allows code after Pipeline.compose() to run.
+         */
+        if (i === handlers.length) {
+          fn = next;
+        }
+        if (!fn) return Promise.resolve();
+        try {
+          /**
+           * Execute the middleware function, passing:
+           * - context: the request context object
+           * - dispatch.bind(null, i + 1): the next() function for chaining
+           *
+           * Promise.resolve() wraps non-promise returns for consistency.
+           */
+          return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
+        } catch (err) {
+          return Promise.reject(err);
+        }
+      }
+      /**
+       * Start the pipeline at the first middleware (index 0).
+       */
+      return dispatch(0);
+    };
+  }
+  /**
+   * Resolves a middleware to a callable (context, next) => Promise function.
+   * Supports three forms:
+   * 1. Function: Used directly
+   * 2. Class constructor with handle() method: Instantiated and bound
+   * 3. Object with handle() method: handle() method is bound
+   *
+   * @param mw Middleware in one of the above forms
+   * @returns Callable (context, next) => Promise function
+   *
+   * @throws {TypeError} If mw is not a recognized middleware type
+   */
+  static resolveMiddleware(mw) {
+    if (typeof mw === "function") {
+      /**
+       * Check if this is a class constructor with a handle() method.
+       * Constructors have a prototype property with methods defined on it.
+       */
+      if (
+        "prototype" in mw &&
+        mw.prototype &&
+        typeof mw.prototype.handle === "function"
+      ) {
+        try {
+          const instance = new mw();
+          return instance.handle.bind(instance);
+        } catch (e) {
+          /**
+           * If instantiation fails (constructor requires params),
+           * assume it's a simple function middleware and use it directly.
+           */
+          return mw;
+        }
+      }
+      return mw;
+    }
+    /**
+     * Check for object with handle() method.
+     * Useful for class instances or middleware objects.
+     */
+    if (typeof mw === "object" && mw !== null && "handle" in mw) {
+      return mw.handle.bind(mw);
+    }
+    throw new TypeError(
+      "Middleware must be a function, a class constructor, or an object with a handle() method",
+    );
+  }
+}

package/templates/ssr-isr/lib/middleware/registry.js

@@ -0,0 +1,85 @@
+/**
+ * Global registry for named middleware and middleware groups.
+ * Enables reusable middleware composition patterns where middlewares are registered once
+ * and then referenced by name in groups or applied globally.
+ *
+ * The registry follows the singleton pattern to maintain a single shared instance
+ * throughout the application lifecycle.
+ *
+ * @example
+ * const registry = MiddlewareRegistry.get();
+ * registry.register('auth', authMiddleware);
+ * registry.register('logger', loggingMiddleware);
+ * registry.group('api', ['auth', 'logger']);
+ * // Later, get the group to apply to routes
+ * const apiMw = registry.getGroup('api'); // [authMiddleware, loggingMiddleware]
+ */
+export class MiddlewareRegistry {
+  // Singleton instance shared across the application.
+  static instance;
+  // Map of named middleware functions.
+  middleware = new Map();
+  // Map of middleware group definitions (groups contain names of registered middleware).
+  groups = new Map();
+  constructor() {}
+  /**
+   * Gets or creates the singleton registry instance.
+   * All calls to this method return the same instance, ensuring a single registry.
+   *
+   * @returns The singleton MiddlewareRegistry instance.
+   */
+  static get() {
+    if (!this.instance) this.instance = new MiddlewareRegistry();
+    return this.instance;
+  }
+  /**
+   * Registers a middleware function with a name.
+   * Named middleware can be referenced in groups or applied individually.
+   *
+   * @param name Unique identifier for the middleware.
+   * @param mw The middleware function to register.
+   *
+   * @example
+   * registry.register('cors', corsMiddleware);
+   */
+  register(name, mw) {
+    this.middleware.set(name, mw);
+  }
+  /**
+   * Retrieves a registered middleware by name.
+   *
+   * @param name The name of the middleware to retrieve.
+   * @returns The middleware function, or undefined if not found.
+   */
+  get(name) {
+    return this.middleware.get(name);
+  }
+  /**
+   * Defines a group of middleware by names.
+   * Groups allow composing multiple middleware into a named set that can be applied together.
+   *
+   * @param groupName The name of the group.
+   * @param middlewareNames Array of registered middleware names to include in the group.
+   *
+   * @example
+   * registry.group('secure', ['auth', 'rateLimit', 'securityHeaders']);
+   */
+  group(groupName, middlewareNames) {
+    this.groups.set(groupName, middlewareNames);
+  }
+  /**
+   * Retrieves all middleware functions in a named group.
+   * Resolves group names to actual middleware functions.
+   * Skips missing middleware names gracefully.
+   *
+   * @param groupName The name of the group to retrieve.
+   * @returns Array of middleware functions in the group (in order).
+   *
+   * @example
+   * const middlewares = registry.getGroup('secure'); // [authFn, rateLimitFn, securityHeadersFn]
+   */
+  getGroup(groupName) {
+    const names = this.groups.get(groupName) || [];
+    return names.map((n) => this.get(n)).filter((m) => !!m);
+  }
+}

package/templates/ssr-isr/lib/middleware/response.js

@@ -0,0 +1,107 @@
+/**
+ * Fluent builder for constructing HTTP responses.
+ * Provides a chainable API for setting status codes, headers, body, and content type.
+ * Delegates actual response sending to the underlying Node.js ServerResponse.
+ *
+ * This builder is used in the Context to provide convenient response composition
+ * without manually managing headers and response state.
+ *
+ * @example
+ * ctx.response
+ *   .status(201)
+ *   .header('X-Custom', 'value')
+ *   .json({ id: 123, name: 'Alice' })
+ *   .send();
+ */
+export class ResponseBuilder {
+  // HTTP status code to send (default 200 OK).
+  statusCode = 200;
+  // Header key-value pairs to include in the response.
+  headers = {};
+  // Response body content (string, Buffer, or null for empty body).
+  body = null;
+  // The underlying Node.js ServerResponse object.
+  res;
+  /**
+   * Initializes a ResponseBuilder with the given ServerResponse.
+   *
+   * @param res The Node.js ServerResponse object to write to.
+   */
+  constructor(res) {
+    this.res = res;
+  }
+  /**
+   * Sets the HTTP status code for the response.
+   *
+   * @param code The HTTP status code (e.g., 200, 404, 500).
+   * @returns This ResponseBuilder instance for method chaining.
+   */
+  status(code) {
+    this.statusCode = code;
+    return this;
+  }
+  /**
+   * Adds an HTTP response header.
+   * Multiple calls with the same key overwrite previous values.
+   *
+   * @param key The header name.
+   * @param value The header value.
+   * @returns This ResponseBuilder instance for method chaining.
+   */
+  header(key, value) {
+    this.headers[key] = value;
+    return this;
+  }
+  /**
+   * Sets the response body to a JSON-serialized object and sets Content-Type header.
+   * Automatically sets Content-Type to application/json.
+   *
+   * @param data The object to serialize as JSON.
+   * @returns This ResponseBuilder instance for method chaining.
+   */
+  json(data) {
+    this.header("Content-Type", "application/json");
+    this.body = JSON.stringify(data);
+    return this;
+  }
+  /**
+   * Sets the response body to HTML content and sets Content-Type header.
+   * Automatically sets Content-Type to text/html.
+   *
+   * @param html The HTML string to send.
+   * @returns This ResponseBuilder instance for method chaining.
+   */
+  html(html) {
+    this.header("Content-Type", "text/html");
+    this.body = html;
+    return this;
+  }
+  /**
+   * Sets the response body to plain text and sets Content-Type header.
+   * Automatically sets Content-Type to text/plain.
+   *
+   * @param text The plain text string to send.
+   * @returns This ResponseBuilder instance for method chaining.
+   */
+  text(text) {
+    this.header("Content-Type", "text/plain");
+    this.body = text;
+    return this;
+  }
+  /**
+   * Sends the response to the client.
+   * Writes the status code, headers, and body to the underlying ServerResponse.
+   * Does nothing if the response has already been sent (writableEnded is true).
+   *
+   * @returns Void. The underlying res.end() return value is not propagated.
+   */
+  send() {
+    if (this.res.writableEnded) return;
+    this.res.writeHead(this.statusCode, this.headers);
+    if (this.body !== null && this.body !== undefined) {
+      this.res.end(this.body);
+    } else {
+      this.res.end();
+    }
+  }
+}

package/templates/ssr-isr/lib/middleware/types.d.ts

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

package/templates/ssr-isr/lib/middleware/types.js

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

package/templates/ssr-isr/lib/middleware/utils/matcher.js

@@ -0,0 +1,13 @@
+export function matchPath(pattern, path) {
+  if (pattern === "*") return true;
+  if (pattern === path) return true;
+  // Basic glob: * matches anything
+  const regexString =
+    "^" +
+    pattern
+      .replace(/[.+?^${}()|[\\]/g, "\\$&") // escape regex characters
+      .replace(/\*/g, ".*") +
+    "$"; // convert * to .*
+  const regex = new RegExp(regexString);
+  return regex.test(path);
+}

package/templates/{static → ssr-isr}/lib/native/bundle.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/>.
- */
 // Native bundler (C++ stub)
 // High-performance bundler for assets and code
 // Currently: esbuild wrapper (use native C++ bundler in production)

package/templates/{static → ssr-isr}/lib/native/dev-server.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/>.
- */
 // Native dev server (Rust stub)
 // Provides high-performance development server
 // Currently: TypeScript implementation (use Bun or esbuild-serve in production)

package/templates/{static → ssr-isr}/lib/native/index.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/>.
- */
 // Native modules entry point
 // Provides high-performance implementations
 // Note: These are TypeScript stubs. In production, replace with native Rust/C++ bindings.

package/templates/{static → ssr-isr}/lib/native/optimizer.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/>.
- */
 export async function optimize(opts) {
   console.log(`[OPTIMIZER] Optimizing ${opts.files.length} files`);
   // Placeholder: simulated optimization results

package/templates/ssr-isr/lib/native/style-compiler.js

@@ -0,0 +1,19 @@
+export async function compileScss(opts) {
+  // Placeholder: returns CSS placeholder
+  console.log(`[STYLE COMPILER] Compiling SCSS: ${opts.input}`);
+  const css = `
+    /* SCSS compiled from: ${opts.input} */
+    /* Note: Full SCSS compilation requires dart-sass or native Rust implementation */
+    body { margin: 0; padding: 0; }
+  `;
+  return css;
+}
+export async function compileCSS(input, minify = false) {
+  console.log(`[STYLE COMPILER] Processing CSS: ${input}`);
+  // Placeholder: returns input CSS
+  return input;
+}
+export async function watchStyles(input, output, onChange) {
+  // Placeholder watcher
+  console.log(`[STYLE COMPILER] Watching: ${input}`);
+}

package/templates/ssr-isr/lib/plugin/loader.js

@@ -0,0 +1,36 @@
+// Plugin loader
+// Migrated from Python src/python/plugins.py
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { log } from "../shared/log.js";
+const PLUGIN_DIR = "src/plugin/plugins";
+export async function runPlugins(event = "build") {
+  log.info(`Running plugins (${event})...`);
+  try {
+    const files = readdirSync(PLUGIN_DIR);
+    for (const file of files) {
+      if (!file.endsWith(".ts") && !file.endsWith(".js")) continue;
+      const pluginPath = join(process.cwd(), PLUGIN_DIR, file);
+      const pluginUrl = pathToFileURL(pluginPath).href;
+      try {
+        const module = await import(pluginUrl);
+        const plugin = module.default;
+        if (!plugin) continue;
+        log.info(`  Loading plugin: ${plugin.name}`);
+        if (event === "build" && plugin.onBuild) {
+          await plugin.onBuild();
+        } else if (event === "serve" && plugin.onServe) {
+          await plugin.onServe();
+        } else if (event === "deploy" && plugin.onDeploy) {
+          await plugin.onDeploy();
+        }
+      } catch (err) {
+        log.error(`  Plugin error: ${file} - ${String(err)}`);
+      }
+    }
+    log.info("Plugins executed.");
+  } catch (err) {
+    log.warn(`Plugin directory not found: ${PLUGIN_DIR}`);
+  }
+}

package/templates/ssr-isr/lib/runtime/client-runtime.js

@@ -0,0 +1,25 @@
+/**
+ * Retrieve framework data injected by the server into the page HTML.
+ * The server embeds loader result data, route params, and query parameters
+ * into a hidden DOM element with id "__FRAMEWORK_DATA__" as JSON.
+ *
+ * This data is passed to page components during hydration as props.
+ * Returns null if the element does not exist or JSON is malformed,
+ * allowing graceful degradation without throwing errors.
+ *
+ * Usage:
+ *   const data = getFrameworkData();
+ *   // data = { data: {...}, params: {...}, query: {...} }
+ *
+ * @returns Framework data object { data, params, query } or null if not found.
+ */
+export function getFrameworkData() {
+  const el = document.getElementById("__FRAMEWORK_DATA__");
+  if (!el) return null;
+  try {
+    return JSON.parse(el.textContent || "null");
+  } catch {
+    // Silently return null if JSON is invalid; page hydrates with default props
+    return null;
+  }
+}

package/templates/ssr-isr/lib/runtime/hmr.js

@@ -0,0 +1,59 @@
+/**
+ * Client-side Hot Module Replacement (HMR) / Live Reload code.
+ * This script is injected into the browser during development mode.
+ *
+ * Features:
+ * - Establishes Server-Sent Events (SSE) connection to /__hmr endpoint
+ * - Listens for "reload" events (full page reload on route/component changes)
+ * - Listens for "style-update" events (CSS updates without full reload)
+ * - Automatically retries connection if lost
+ *
+ * The script uses IIFE (Immediately Invoked Function Expression) to avoid
+ * polluting the global scope.
+ *
+ * How it works:
+ * 1. Server watches file system for changes
+ * 2. On change, server sends SSE event to clients
+ * 3. Client receives event and either reloads or updates CSS
+ * 4. CSS updates use cache-busting query params to force fresh load
+ *
+ * Only injected in development mode; production builds do not include this.
+ */
+export const HMR_CLIENT_SCRIPT = `
+(function() {
+  console.log("[Jen.js] Connecting to HMR...");
+  const evt = new EventSource("/__hmr");
+
+  evt.onopen = () => console.log("[Jen.js] HMR Connected");
+
+  // Full page reload on route or component changes
+  evt.addEventListener("reload", () => {
+    console.log("[Jen.js] Reloading...");
+    window.location.reload();
+  });
+
+  // CSS-only reload without full page reload (faster UX for style-only changes)
+  evt.addEventListener("style-update", (e) => {
+    const file = JSON.parse(e.data).file; // e.g., "styles.css"
+    console.log("[Jen.js] Style update:", file);
+    
+    // Find matching link tags by pathname
+    const links = document.querySelectorAll('link[rel="stylesheet"]');
+    for (const link of links) {
+      const url = new URL(link.href);
+      if (url.pathname.endsWith(file)) {
+        // Force reload by updating cache-busting query param (timestamp)
+        url.searchParams.set("t", Date.now());
+        link.href = url.toString();
+        console.log("[Jen.js] Updated stylesheet:", file);
+      }
+    }
+  });
+
+  evt.onerror = () => {
+    // Connection closed; EventSource automatically retries
+    // (commented out: chatty in development; uncomment if needed for debugging)
+    // console.log("[Jen.js] HMR disconnected, retrying...");
+  };
+})();
+`;

package/templates/ssr-isr/lib/runtime/hydrate.js

@@ -0,0 +1,55 @@
+import { hydrate } from "preact";
+import { h } from "preact";
+import { getFrameworkData } from "./client-runtime.js";
+/**
+ * Hydrate a server-rendered page with client-side interactivity.
+ * This function is called once on page load in the browser.
+ * It attaches Preact event listeners and state management to existing DOM without re-rendering.
+ *
+ * Flow:
+ * 1. Retrieve framework data (loader result, route params, query) injected by server into page HTML
+ * 2. Dynamically import the route component module
+ * 3. Construct Preact component tree passing data as props
+ * 4. Attach to existing #app element (matches server-rendered HTML structure)
+ *
+ * Errors during hydration are logged but do not throw; the page remains functional
+ * with reduced interactivity if hydration fails.
+ *
+ * @param entryPath - Path to the route component module (e.g., "./routes/index.js")
+ *   This path is typically injected into the HTML as a script attribute by the server.
+ */
+export async function hydrateClient(entryPath) {
+  try {
+    // Retrieve loader data, params, and query injected into page HTML by server
+    const data = getFrameworkData();
+    // Dynamically import route component
+    const mod = await import(entryPath);
+    // Validate that route exports a default component
+    if (!mod.default) {
+      console.error(
+        `Failed to hydrate: route module does not export default component`,
+      );
+      return;
+    }
+    // Construct Preact VDOM tree with data as props
+    const Page = mod.default;
+    const app = h(Page, {
+      data: data?.data ?? null,
+      params: data?.params ?? {},
+      query: data?.query ?? {},
+    });
+    // Find root DOM element for hydration
+    const root = document.getElementById("app");
+    if (!root) {
+      console.error("Failed to hydrate: #app element not found in DOM");
+      return;
+    }
+    // Attach Preact to existing DOM tree without re-rendering
+    hydrate(app, root);
+  } catch (err) {
+    console.error(
+      "Hydration failed:",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}