create-jen-app 1.2.1 → 1.2.3

package/templates/static/lib/middleware/context.d.ts

@@ -1,18 +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 {
-    constructor(req: any, res: any);
-    req: any;
-    res: any;
-    url: URL;
-    state: {};
-    response: ResponseBuilder;
-    body: any;
-    query: {
-        [k: string]: string;
-    };
-    params: {};
-    get cookies(): {
-        [k: string]: any;
-    };
-    json(data: any, status?: number): void;
+  /**
+   * 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/static/lib/middleware/context.js

@@ -16,35 +16,126 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 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 {
-    req;
-    res;
-    url;
-    state;
-    response;
-    body; // For parsed body
-    query;
-    params;
-    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 = {};
-    }
-    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("="))];
-        }));
-    }
-    json(data, status = 200) {
-        return this.response.status(status).json(data).send();
-    }
+  /**
+   * 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/static/lib/middleware/decorators.d.ts

@@ -1,2 +1,19 @@
-export function UseMiddleware(...middleware: any[]): (target: any, propertyKey: any, descriptor: any) => void;
+/**
+ * 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/static/lib/middleware/decorators.js

@@ -15,47 +15,96 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
-// Simple in-memory storage for metadata if Reflect is not available
-// This avoids the 'reflect-metadata' dependency
+/**
+ * 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
-    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);
+    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
-    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);
+    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
-            const existing = getMetadata(MIDDLEWARE_METADATA_KEY, target, propertyKey) || [];
-            defineMetadata(MIDDLEWARE_METADATA_KEY, [...existing, ...middleware], target, propertyKey);
-        }
-        else {
-            // Class decorator
-            const existing = getMetadata(MIDDLEWARE_METADATA_KEY, target) || [];
-            defineMetadata(MIDDLEWARE_METADATA_KEY, [...existing, ...middleware], target);
-        }
-    };
+  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/static/lib/middleware/errors/handler.js

@@ -17,20 +17,18 @@
  */
 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 = `
+  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>
@@ -51,15 +49,15 @@ export async function errorHandler(ctx, next) {
         </body>
         </html>
         `;
-            ctx.response.status(status).html(html).send();
-            return;
-        }
-        ctx.response.status(status).json({
-            error: true,
-            statusCode: status,
-            message,
-            details,
-        });
-        ctx.response.send();
+      ctx.response.status(status).html(html).send();
+      return;
     }
+    ctx.response.status(status).json({
+      error: true,
+      statusCode: status,
+      message,
+      details,
+    });
+    ctx.response.send();
+  }
 }

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

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

package/templates/static/lib/middleware/errors/http-error.js

@@ -16,12 +16,12 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 export class HttpError extends Error {
-    statusCode;
-    details;
-    constructor(statusCode, message, details) {
-        super(message);
-        this.statusCode = statusCode;
-        this.details = details;
-        Object.setPrototypeOf(this, HttpError.prototype);
-    }
+  statusCode;
+  details;
+  constructor(statusCode, message, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    Object.setPrototypeOf(this, HttpError.prototype);
+  }
 }

package/templates/static/lib/middleware/kernel.d.ts

@@ -1,6 +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 {
-    globalMiddleware: any[];
-    use(mw: any): void;
-    handle(req: any, res: any): Promise<void>;
-    handleWithGroup(req: any, res: any, groupName: any): Promise<void>;
+  /**
+   * 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>;
 }