create-jen-app 1.2.2 → 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.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 {
+  static instance: any;
+  /**
+   * 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(): any;
+  middleware: Map<any, any>;
+  groups: Map<any, any>;
+  /**
+   * 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: any, mw: any): void;
+  /**
+   * 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: any): any;
+  /**
+   * 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: any, middlewareNames: any): void;
+  /**
+   * 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: any): any;
+}

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.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 {
+  /**
+   * Initializes a ResponseBuilder with the given ServerResponse.
+   *
+   * @param res The Node.js ServerResponse object to write to.
+   */
+  constructor(res: any);
+  statusCode: number;
+  headers: {};
+  body: null;
+  res: any;
+  /**
+   * 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: any): 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: any, value: any): 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: any): 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: any): 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: any): 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(): void;
+}

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/ssr-isr/lib/native/bundle.d.ts

@@ -0,0 +1,24 @@
+import esbuild from "esbuild";
+export interface BundlerOptions {
+  entryPoint: string;
+  outdir?: string;
+  format?: "esm" | "cjs" | "iife";
+  minify?: boolean;
+  sourcemap?: boolean;
+}
+export declare function bundle(opts: BundlerOptions): Promise<
+  esbuild.BuildResult<{
+    entryPoints: string[];
+    outdir: string;
+    format: "esm" | "iife" | "cjs";
+    minify: boolean;
+    sourcemap: boolean;
+    platform: "browser";
+    target: string;
+    logLevel: "info";
+  }>
+>;
+export declare function bundleAssets(
+  assetsDir: string,
+  outdir: string,
+): Promise<void>;

package/templates/ssr-isr/lib/native/bundle.js

@@ -0,0 +1,22 @@
+// Native bundler (C++ stub)
+// High-performance bundler for assets and code
+// Currently: esbuild wrapper (use native C++ bundler in production)
+import esbuild from "esbuild";
+export async function bundle(opts) {
+  const result = await esbuild.build({
+    entryPoints: [opts.entryPoint],
+    outdir: opts.outdir || "dist",
+    format: opts.format || "esm",
+    minify: opts.minify ?? false,
+    sourcemap: opts.sourcemap ?? false,
+    platform: "browser",
+    target: "es2022",
+    logLevel: "info",
+  });
+  return result;
+}
+export async function bundleAssets(assetsDir, outdir) {
+  // Copy assets with optional optimization
+  console.log(`[BUNDLER] Packaging assets from ${assetsDir} to ${outdir}`);
+  // Implementation: use native bundler for CSS/image optimization
+}

package/templates/ssr-isr/lib/native/dev-server.d.ts

@@ -0,0 +1,13 @@
+export interface DevServerOptions {
+  port?: number;
+  hostname?: string;
+  root?: string;
+}
+export declare function startDevServer(
+  opts?: DevServerOptions,
+): Promise<
+  import("node:http").Server<
+    typeof import("node:http").IncomingMessage,
+    typeof import("node:http").ServerResponse
+  >
+>;

package/templates/ssr-isr/lib/native/dev-server.js

@@ -0,0 +1,23 @@
+// Native dev server (Rust stub)
+// Provides high-performance development server
+// Currently: TypeScript implementation (use Bun or esbuild-serve in production)
+import { createServer } from "node:http";
+export async function startDevServer(opts = {}) {
+  const port = opts.port || 5173;
+  const hostname = opts.hostname || "0.0.0.0";
+  const root = opts.root || process.cwd();
+  const server = createServer((req, res) => {
+    res.writeHead(200, { "content-type": "text/plain" });
+    res.end(
+      "TypeScript dev server stub (replace with Rust native build in production)\n",
+    );
+  });
+  server.listen(port, hostname, () => {
+    console.log(`[DEV SERVER] Listening on http://${hostname}:${port}`);
+  });
+  return server;
+}
+// Export default for direct execution
+if (import.meta.url === `file://${process.argv[1]}`) {
+  startDevServer();
+}

package/templates/{static → ssr-isr}/lib/native/index.d.ts

@@ -7,24 +7,24 @@ export type { StyleCompilerOptions } from "./style-compiler.js";
 export { optimize, optimizeImages, minifyHTML } from "./optimizer.js";
 export type { OptimizerOptions } from "./optimizer.js";
 export declare const NATIVE_MODULES: {
-    devServer: {
-        name: string;
-        status: string;
-        implementation: string;
-    };
-    bundler: {
-        name: string;
-        status: string;
-        implementation: string;
-    };
-    styleCompiler: {
-        name: string;
-        status: string;
-        implementation: string;
-    };
-    optimizer: {
-        name: string;
-        status: string;
-        implementation: string;
-    };
+  devServer: {
+    name: string;
+    status: string;
+    implementation: string;
+  };
+  bundler: {
+    name: string;
+    status: string;
+    implementation: string;
+  };
+  styleCompiler: {
+    name: string;
+    status: string;
+    implementation: string;
+  };
+  optimizer: {
+    name: string;
+    status: string;
+    implementation: string;
+  };
 };

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

@@ -0,0 +1,33 @@
+// Native modules entry point
+// Provides high-performance implementations
+// Note: These are TypeScript stubs. In production, replace with native Rust/C++ bindings.
+export { startDevServer } from "./dev-server.js";
+export { bundle, bundleAssets } from "./bundle.js";
+export { compileScss, compileCSS, watchStyles } from "./style-compiler.js";
+export { optimize, optimizeImages, minifyHTML } from "./optimizer.js";
+// Native module status
+export const NATIVE_MODULES = {
+  devServer: {
+    name: "dev-server",
+    status: "stub",
+    implementation: "TypeScript",
+  },
+  bundler: {
+    name: "bundler",
+    status: "stub",
+    implementation: "esbuild wrapper",
+  },
+  styleCompiler: {
+    name: "style-compiler",
+    status: "stub",
+    implementation: "TypeScript",
+  },
+  optimizer: {
+    name: "optimizer",
+    status: "stub",
+    implementation: "TypeScript",
+  },
+};
+console.log(
+  "[NATIVE MODULES] Loaded (TypeScript stubs - replace with native bindings in production)",
+);