create-jen-app 1.2.2 → 1.2.4

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

@@ -0,0 +1,105 @@
+/**
+ * Request context object passed through the middleware chain.
+ * Wraps Node.js req/res objects and provides helper methods and parsed request data.
+ * Each middleware receives this context and can read/modify its properties.
+ *
+ * The context enables:
+ * - Access to parsed URL, query params, route params, cookies, headers
+ * - Convenient response building methods (json(), headers())
+ * - State storage for passing data between middlewares
+ * - Request body parsing and caching
+ */
+export class Context {
+  /**
+   * Initializes a request context from Node.js request and response objects.
+   * Parses the URL, extracts query parameters, and initializes helpers.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   */
+  constructor(req: any, res: any);
+  /**
+   * Raw Node.js IncomingMessage request object.
+   * Contains method, url, headers, socket, etc.
+   */
+  req: any;
+  /**
+   * Raw Node.js ServerResponse response object.
+   * Used to send response data back to the client.
+   */
+  res: any;
+  /**
+   * Parsed URL object with scheme, host, pathname, search, searchParams, etc.
+   * Automatically constructed from req.url and req.headers.host.
+   *
+   * @example ctx.url.pathname for "/posts/42", ctx.url.searchParams for query parsing
+   */
+  url: URL;
+  /**
+   * Shared state object for middleware to store data.
+   * Useful for passing values between middlewares in the chain without response headers.
+   *
+   * @example ctx.state.userId = 42; // Set in auth middleware, read in handler
+   */
+  state: {};
+  /**
+   * ResponseBuilder instance for fluent response building.
+   * Use ctx.response.status().json() or ctx.response.header() to build responses.
+   * Alternatively, use ctx.json() shortcut for quick JSON responses.
+   */
+  response: ResponseBuilder;
+  /**
+   * Parsed request body cache.
+   * Set by body parser middleware if request has a body.
+   * Can be null if no body parser ran or if the request has no body.
+   */
+  body: any;
+  /**
+   * Query string parameters as an object.
+   * Automatically parsed from ctx.url.searchParams on construction.
+   * Keys and values are always strings.
+   *
+   * @example For URL "/posts?sort=date&limit=10", yields { sort: "date", limit: "10" }
+   */
+  query: {
+    [k: string]: string;
+  };
+  /**
+   * Route parameters extracted from the URL path.
+   * Set by route matching middleware based on dynamic route patterns.
+   * Empty object initially; populated when a route matches.
+   *
+   * @example For route "/posts/:id" matching "/posts/42", yields { id: "42" }
+   */
+  params: {};
+  /**
+   * Getter that parses and caches cookies from the request.
+   * Parses the Cookie header into an object of name-value pairs.
+   * Values are automatically decoded using decodeURIComponent.
+   * Memoization is implicit; called fresh each time.
+   *
+   * @returns Object with cookie names as keys and values as cookie values
+   *
+   * @example
+   * const sessionId = ctx.cookies.sessionId;  // Get a cookie value
+   * // For header "sessionId=abc123; theme=dark" yields { sessionId: "abc123", theme: "dark" }
+   */
+  get cookies(): {
+    [k: string]: any;
+  };
+  /**
+   * Convenience method to send a JSON response.
+   * Combines ctx.response.status().json().send() into a single call.
+   *
+   * @param data Object to serialize as JSON and send
+   * @param status HTTP status code; defaults to 200 (OK)
+   *
+   * @returns Result of response.send() (undefined if response is sent)
+   *
+   * @example
+   * ctx.json({ success: true }, 201);
+   * ctx.json({ error: "Not found" }, 404);
+   */
+  json(data: any, status?: number): void;
+}
+import { ResponseBuilder } from "./response.js";

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

@@ -0,0 +1,124 @@
+import { ResponseBuilder } from "./response.js";
+/**
+ * Request context object passed through the middleware chain.
+ * Wraps Node.js req/res objects and provides helper methods and parsed request data.
+ * Each middleware receives this context and can read/modify its properties.
+ *
+ * The context enables:
+ * - Access to parsed URL, query params, route params, cookies, headers
+ * - Convenient response building methods (json(), headers())
+ * - State storage for passing data between middlewares
+ * - Request body parsing and caching
+ */
+export class Context {
+  /**
+   * Raw Node.js IncomingMessage request object.
+   * Contains method, url, headers, socket, etc.
+   */
+  req;
+  /**
+   * Raw Node.js ServerResponse response object.
+   * Used to send response data back to the client.
+   */
+  res;
+  /**
+   * Parsed URL object with scheme, host, pathname, search, searchParams, etc.
+   * Automatically constructed from req.url and req.headers.host.
+   *
+   * @example ctx.url.pathname for "/posts/42", ctx.url.searchParams for query parsing
+   */
+  url;
+  /**
+   * Shared state object for middleware to store data.
+   * Useful for passing values between middlewares in the chain without response headers.
+   *
+   * @example ctx.state.userId = 42; // Set in auth middleware, read in handler
+   */
+  state;
+  /**
+   * ResponseBuilder instance for fluent response building.
+   * Use ctx.response.status().json() or ctx.response.header() to build responses.
+   * Alternatively, use ctx.json() shortcut for quick JSON responses.
+   */
+  response;
+  /**
+   * Parsed request body cache.
+   * Set by body parser middleware if request has a body.
+   * Can be null if no body parser ran or if the request has no body.
+   */
+  body;
+  /**
+   * Query string parameters as an object.
+   * Automatically parsed from ctx.url.searchParams on construction.
+   * Keys and values are always strings.
+   *
+   * @example For URL "/posts?sort=date&limit=10", yields { sort: "date", limit: "10" }
+   */
+  query;
+  /**
+   * Route parameters extracted from the URL path.
+   * Set by route matching middleware based on dynamic route patterns.
+   * Empty object initially; populated when a route matches.
+   *
+   * @example For route "/posts/:id" matching "/posts/42", yields { id: "42" }
+   */
+  params;
+  /**
+   * Initializes a request context from Node.js request and response objects.
+   * Parses the URL, extracts query parameters, and initializes helpers.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   */
+  constructor(req, res) {
+    this.req = req;
+    this.res = res;
+    this.url = new URL(
+      req.url ?? "/",
+      `http://${req.headers.host || "localhost"}`,
+    );
+    this.state = {};
+    this.response = new ResponseBuilder(res);
+    this.body = null;
+    this.query = Object.fromEntries(this.url.searchParams);
+    this.params = {};
+  }
+  /**
+   * Getter that parses and caches cookies from the request.
+   * Parses the Cookie header into an object of name-value pairs.
+   * Values are automatically decoded using decodeURIComponent.
+   * Memoization is implicit; called fresh each time.
+   *
+   * @returns Object with cookie names as keys and values as cookie values
+   *
+   * @example
+   * const sessionId = ctx.cookies.sessionId;  // Get a cookie value
+   * // For header "sessionId=abc123; theme=dark" yields { sessionId: "abc123", theme: "dark" }
+   */
+  get cookies() {
+    const header = this.req.headers.cookie;
+    if (!header) return {};
+    return Object.fromEntries(
+      header.split(";").map((c) => {
+        const [key, ...v] = c.trim().split("=");
+        return [key, decodeURIComponent(v.join("="))];
+      }),
+    );
+  }
+  /**
+   * Convenience method to send a JSON response.
+   * Combines ctx.response.status().json().send() into a single call.
+   *
+   * @param data Object to serialize as JSON and send
+   * @param status HTTP status code; defaults to 200 (OK)
+   *
+   * @returns Result of response.send() (undefined if response is sent)
+   *
+   * @example
+   * ctx.json({ success: true }, 201);
+   * ctx.json({ error: "Not found" }, 404);
+   */
+  json(data, status = 200) {
+    return this.response.status(status).json(data).send();
+  }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Class or method decorator for attaching middleware to handlers.
+ * Allows declaring middleware dependencies declaratively on class definitions or methods.
+ * Middleware is merged with existing middleware if applied multiple times.
+ *
+ * @param middleware Middleware functions to attach.
+ * @returns A decorator function compatible with class or method decoration.
+ *
+ * @example
+ * @UseMiddleware(authMiddleware, corsMiddleware)
+ * class UserController {
+ *   @UseMiddleware(rateLimitMiddleware)
+ *   async getUsers(ctx) { ... }
+ * }
+ */
+export function UseMiddleware(
+  ...middleware: any[]
+): (target: any, propertyKey: any, descriptor: any) => void;
+export const MIDDLEWARE_METADATA_KEY: unique symbol;

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

@@ -0,0 +1,93 @@
+/**
+ * Metadata storage for decorator information.
+ * Provides a fallback when Reflect.metadata is not available.
+ * This avoids adding the reflect-metadata dependency for basic decorator support.
+ *
+ * Uses WeakMap for automatic cleanup when target objects are garbage collected.
+ */
+const MetadataStorage = new WeakMap();
+/**
+ * Retrieves metadata attached to a target via decorators.
+ * Uses the Reflect API if available; otherwise falls back to WeakMap storage.
+ *
+ * @param key The metadata key (usually a Symbol).
+ * @param target The class or object to get metadata from.
+ * @param propertyKey Optional property name for method/property-level metadata.
+ * @returns The metadata value, or undefined if not found.
+ */
+function getMetadata(key, target, propertyKey) {
+  // Use native Reflect API if available for better compatibility.
+  // @ts-ignore
+  if (typeof Reflect !== "undefined" && Reflect.getMetadata) {
+    // @ts-ignore
+    return Reflect.getMetadata(key, target, propertyKey);
+  }
+  const targetMap = MetadataStorage.get(target);
+  if (!targetMap) return undefined;
+  const mapKey = propertyKey ? `${String(key)}:${String(propertyKey)}` : key;
+  return targetMap.get(mapKey);
+}
+/**
+ * Stores metadata on a target for use by decorators.
+ * Uses the Reflect API if available; otherwise falls back to WeakMap storage.
+ *
+ * @param key The metadata key (usually a Symbol).
+ * @param value The value to store.
+ * @param target The class or object to attach metadata to.
+ * @param propertyKey Optional property name for method/property-level metadata.
+ */
+function defineMetadata(key, value, target, propertyKey) {
+  // Use native Reflect API if available for better compatibility.
+  // @ts-ignore
+  if (typeof Reflect !== "undefined" && Reflect.defineMetadata) {
+    // @ts-ignore
+    return Reflect.defineMetadata(key, value, target, propertyKey);
+  }
+  let targetMap = MetadataStorage.get(target);
+  if (!targetMap) {
+    targetMap = new Map();
+    MetadataStorage.set(target, targetMap);
+  }
+  const mapKey = propertyKey ? `${String(key)}:${String(propertyKey)}` : key;
+  targetMap.set(mapKey, value);
+}
+// Unique symbol to store middleware metadata on classes and methods.
+export const MIDDLEWARE_METADATA_KEY = Symbol("jen:middleware");
+/**
+ * Class or method decorator for attaching middleware to handlers.
+ * Allows declaring middleware dependencies declaratively on class definitions or methods.
+ * Middleware is merged with existing middleware if applied multiple times.
+ *
+ * @param middleware Middleware functions to attach.
+ * @returns A decorator function compatible with class or method decoration.
+ *
+ * @example
+ * @UseMiddleware(authMiddleware, corsMiddleware)
+ * class UserController {
+ *   @UseMiddleware(rateLimitMiddleware)
+ *   async getUsers(ctx) { ... }
+ * }
+ */
+export function UseMiddleware(...middleware) {
+  return function (target, propertyKey, descriptor) {
+    if (descriptor) {
+      // Method decorator: attach middleware to a specific method.
+      const existing =
+        getMetadata(MIDDLEWARE_METADATA_KEY, target, propertyKey) || [];
+      defineMetadata(
+        MIDDLEWARE_METADATA_KEY,
+        [...existing, ...middleware],
+        target,
+        propertyKey,
+      );
+    } else {
+      // Class decorator: attach middleware to all methods in the class.
+      const existing = getMetadata(MIDDLEWARE_METADATA_KEY, target) || [];
+      defineMetadata(
+        MIDDLEWARE_METADATA_KEY,
+        [...existing, ...middleware],
+        target,
+      );
+    }
+  };
+}

package/templates/ssr-isr/lib/middleware/errors/handler.js

@@ -0,0 +1,46 @@
+import { HttpError } from "./http-error.js";
+export async function errorHandler(ctx, next) {
+  try {
+    await next();
+  } catch (err) {
+    const status = err instanceof HttpError ? err.statusCode : 500;
+    const message = err.message || "Internal Server Error";
+    const details = err instanceof HttpError ? err.details : undefined;
+    console.error(`Error processing request: ${message}`, err);
+    // Check if response is already sent
+    if (ctx.res.writableEnded) return;
+    const accept = ctx.req.headers.accept || "";
+    if (accept.includes("text/html")) {
+      const html = `
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <title>Error ${status}</title>
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <style>
+                body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; line-height: 1.5; }
+                h1 { color: #e11d48; border-bottom: 1px solid #eee; padding-bottom: 0.5rem; }
+                pre { background: #f4f4f5; padding: 1rem; border-radius: 0.5rem; overflow-x: auto; }
+            </style>
+        </head>
+        <body>
+            <h1>Error ${status}</h1>
+            <p><strong>${message}</strong></p>
+            ${details ? `<details><summary>Details</summary><pre>${JSON.stringify(details, null, 2)}</pre></details>` : ""}
+            <hr style="margin-top: 2rem; border: 0; border-top: 1px solid #eee;">
+            <p style="color: #666; font-size: 0.875rem;">Jen.js Framework</p>
+        </body>
+        </html>
+        `;
+      ctx.response.status(status).html(html).send();
+      return;
+    }
+    ctx.response.status(status).json({
+      error: true,
+      statusCode: status,
+      message,
+      details,
+    });
+    ctx.response.send();
+  }
+}

package/templates/ssr-isr/lib/middleware/errors/http-error.d.ts

@@ -0,0 +1,5 @@
+export class HttpError extends Error {
+  constructor(statusCode: any, message: any, details: any);
+  statusCode: any;
+  details: any;
+}

package/templates/ssr-isr/lib/middleware/errors/http-error.js

@@ -0,0 +1,10 @@
+export class HttpError extends Error {
+  statusCode;
+  details;
+  constructor(statusCode, message, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    Object.setPrototypeOf(this, HttpError.prototype);
+  }
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Core HTTP request handler that manages middleware execution and request context.
+ *
+ * The Kernel implements a middleware pipeline pattern:
+ * 1. Receives Node.js req and res objects
+ * 2. Wraps them in a Context object with helper methods and properties
+ * 3. Composes registered middlewares into a callable pipeline
+ * 4. Executes the pipeline with the context for request processing
+ *
+ * Middlewares can:
+ * - Access/modify request and response via ctx.req, ctx.res, ctx.response
+ * - Read/set cookies, headers, query params, route params
+ * - Store and retrieve shared state in ctx.state
+ * - Call ctx.response.json() or other response builders
+ * - Control flow via next() to continue to next middleware
+ */
+export class Kernel {
+  /**
+   * Array of global middleware functions that run for every request.
+   * Middlewares are stored in order of registration (use() calls).
+   * Executed sequentially in Pipeline.compose().
+   */
+  globalMiddleware: any[];
+  /**
+   * Registers a middleware function to run for all requests.
+   * Middleware can be a function, a class constructor, or an object with handle() method.
+   *
+   * @param mw Middleware function: (ctx, next) => Promise<void>
+   *           Or class with: new MyMiddleware().handle(ctx, next)
+   *
+   * @example
+   * kernel.use(async (ctx, next) => {
+   *   console.log(`${ctx.req.method} ${ctx.url.pathname}`);
+   *   await next();
+   * });
+   */
+  use(mw: any): void;
+  /**
+   * Processes an HTTP request through the global middleware pipeline.
+   * Creates a Context wrapping the request/response, composes middlewares, and executes them.
+   *
+   * @param req Node.js IncomingMessage (HTTP request object)
+   * @param res Node.js ServerResponse (HTTP response object)
+   *
+   * @returns Promise that resolves when middleware chain completes
+   *
+   * @example
+   * const server = createServer((req, res) => {
+   *   kernel.handle(req, res);
+   * });
+   */
+  handle(req: any, res: any): Promise<void>;
+  /**
+   * Processes a request through global middleware plus a registered middleware group.
+   * Retrieves middleware from the registry by group name and composes them with global middleware.
+   * Useful for route-specific or feature-specific middleware chains.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   * @param groupName Name of the middleware group registered in MiddlewareRegistry
+   *
+   * @returns Promise that resolves when complete middleware chain executes
+   *
+   * @example
+   * // Given a group named "apiMiddleware" with auth and logging
+   * await kernel.handleWithGroup(req, res, "apiMiddleware");
+   */
+  handleWithGroup(req: any, res: any, groupName: any): Promise<void>;
+}

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

@@ -0,0 +1,85 @@
+import { Pipeline } from "./pipeline.js";
+import { MiddlewareRegistry } from "./registry.js";
+import { Context } from "./context.js";
+/**
+ * Core HTTP request handler that manages middleware execution and request context.
+ *
+ * The Kernel implements a middleware pipeline pattern:
+ * 1. Receives Node.js req and res objects
+ * 2. Wraps them in a Context object with helper methods and properties
+ * 3. Composes registered middlewares into a callable pipeline
+ * 4. Executes the pipeline with the context for request processing
+ *
+ * Middlewares can:
+ * - Access/modify request and response via ctx.req, ctx.res, ctx.response
+ * - Read/set cookies, headers, query params, route params
+ * - Store and retrieve shared state in ctx.state
+ * - Call ctx.response.json() or other response builders
+ * - Control flow via next() to continue to next middleware
+ */
+export class Kernel {
+  /**
+   * Array of global middleware functions that run for every request.
+   * Middlewares are stored in order of registration (use() calls).
+   * Executed sequentially in Pipeline.compose().
+   */
+  globalMiddleware = [];
+  constructor() {}
+  /**
+   * Registers a middleware function to run for all requests.
+   * Middleware can be a function, a class constructor, or an object with handle() method.
+   *
+   * @param mw Middleware function: (ctx, next) => Promise<void>
+   *           Or class with: new MyMiddleware().handle(ctx, next)
+   *
+   * @example
+   * kernel.use(async (ctx, next) => {
+   *   console.log(`${ctx.req.method} ${ctx.url.pathname}`);
+   *   await next();
+   * });
+   */
+  use(mw) {
+    this.globalMiddleware.push(mw);
+  }
+  /**
+   * Processes an HTTP request through the global middleware pipeline.
+   * Creates a Context wrapping the request/response, composes middlewares, and executes them.
+   *
+   * @param req Node.js IncomingMessage (HTTP request object)
+   * @param res Node.js ServerResponse (HTTP response object)
+   *
+   * @returns Promise that resolves when middleware chain completes
+   *
+   * @example
+   * const server = createServer((req, res) => {
+   *   kernel.handle(req, res);
+   * });
+   */
+  async handle(req, res) {
+    const ctx = new Context(req, res);
+    const fn = Pipeline.compose(this.globalMiddleware);
+    await fn(ctx, async () => {});
+  }
+  /**
+   * Processes a request through global middleware plus a registered middleware group.
+   * Retrieves middleware from the registry by group name and composes them with global middleware.
+   * Useful for route-specific or feature-specific middleware chains.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   * @param groupName Name of the middleware group registered in MiddlewareRegistry
+   *
+   * @returns Promise that resolves when complete middleware chain executes
+   *
+   * @example
+   * // Given a group named "apiMiddleware" with auth and logging
+   * await kernel.handleWithGroup(req, res, "apiMiddleware");
+   */
+  async handleWithGroup(req, res, groupName) {
+    const ctx = new Context(req, res);
+    const registry = MiddlewareRegistry.get();
+    const groupMw = registry.getGroup(groupName);
+    const fn = Pipeline.compose([...this.globalMiddleware, ...groupMw]);
+    await fn(ctx, async () => {});
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * 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: any): (context: any, next: any) => any;
+  /**
+   * 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: any): any;
+}