create-jen-app 1.2.2 → 1.2.3

package/templates/static/lib/middleware/kernel.js

@@ -18,22 +18,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 {
-    globalMiddleware = [];
-    constructor() { }
-    use(mw) {
-        this.globalMiddleware.push(mw);
-    }
-    async handle(req, res) {
-        const ctx = new Context(req, res);
-        const fn = Pipeline.compose(this.globalMiddleware);
-        await fn(ctx, async () => { });
-    }
-    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 () => { });
-    }
+  /**
+   * 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/static/lib/middleware/pipeline.d.ts

@@ -1,4 +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 {
-    static compose(middleware: any): (context: any, next: any) => any;
-    static resolveMiddleware(mw: any): any;
+  /**
+   * 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;
 }

package/templates/static/lib/middleware/pipeline.js

@@ -15,53 +15,151 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
+/**
+ * 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 {
-    static compose(middleware) {
-        if (!Array.isArray(middleware))
-            throw new TypeError("Middleware stack must be an array!");
-        const handlers = middleware.map((mw) => this.resolveMiddleware(mw));
-        return function (context, next) {
-            let index = -1;
-            function dispatch(i) {
-                if (i <= index)
-                    return Promise.reject(new Error("next() called multiple times"));
-                index = i;
-                let fn = handlers[i];
-                if (i === handlers.length) {
-                    fn = next;
-                }
-                if (!fn)
-                    return Promise.resolve();
-                try {
-                    return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
-                }
-                catch (err) {
-                    return Promise.reject(err);
-                }
-            }
-            return dispatch(0);
-        };
-    }
-    static resolveMiddleware(mw) {
-        if (typeof mw === "function") {
-            // Check if it's a class constructor (has prototype.handle)
-            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, assume it's a simple function middleware
-                    return mw;
-                }
-            }
-            return mw;
+  /**
+   * 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);
         }
-        if (typeof mw === "object" && mw !== null && "handle" in mw) {
-            return mw.handle.bind(mw);
+      }
+      /**
+       * 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;
         }
-        throw new TypeError("Middleware must be a function, a class constructor, or an object with a handle() method");
+      }
+      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/static/lib/middleware/registry.d.ts

@@ -1,10 +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;
-    static get(): any;
-    middleware: Map<any, any>;
-    groups: Map<any, any>;
-    register(name: any, mw: any): void;
-    get(name: any): any;
-    group(groupName: any, middlewareNames: any): void;
-    getGroup(groupName: any): any;
+  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/static/lib/middleware/registry.js

@@ -15,27 +15,88 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
+/**
+ * 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;
-    middleware = new Map();
-    groups = new Map();
-    constructor() { }
-    static get() {
-        if (!this.instance)
-            this.instance = new MiddlewareRegistry();
-        return this.instance;
-    }
-    register(name, mw) {
-        this.middleware.set(name, mw);
-    }
-    get(name) {
-        return this.middleware.get(name);
-    }
-    group(groupName, middlewareNames) {
-        this.groups.set(groupName, middlewareNames);
-    }
-    getGroup(groupName) {
-        const names = this.groups.get(groupName) || [];
-        return names.map((n) => this.get(n)).filter((m) => !!m);
-    }
+  // 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/static/lib/middleware/response.d.ts

@@ -1,13 +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 {
-    constructor(res: any);
-    statusCode: number;
-    headers: {};
-    body: null;
-    res: any;
-    status(code: any): this;
-    header(key: any, value: any): this;
-    json(data: any): this;
-    html(html: any): this;
-    text(text: any): this;
-    send(): void;
+  /**
+   * 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;
 }