feat(http): enhance type safety and extend route context

- Refactor HttpKernel and related interfaces to support generic contexts.
- Add typed query parameters, route params, and state to IContext.
- Introduce HttpMethod type for stricter HTTP method validation.
- Update RouteBuilder and middleware to handle generic contexts.
- Improve test cases to verify compatibility with new types.

Signed-off-by: Max P. <Mail@MPassarello.de>

src/Interfaces/IHttpKernel.ts

@@ -1,33 +1,50 @@
+import { IContext } from './IContext.ts';
 import { IRouteBuilder } from './IRouteBuilder.ts';
 import { IRouteDefinition } from './IRouteDefinition.ts';
 
 /**
- * Defines the core interface for the HTTP kernel, responsible for route registration,
- * middleware orchestration, and request dispatching.
+ * Defines the core interface for an HTTP kernel instance, responsible for
+ * registering routes, orchestrating middleware pipelines, and dispatching
+ * incoming HTTP requests to the appropriate handler.
+ *
+ * The kernel operates on a generic `IContext` type, which encapsulates the
+ * request, typed state, route parameters, and query parameters for each request.
+ *
+ * @template TContext The default context type for all registered routes and handlers.
  */
-export interface IHttpKernel {
+export interface IHttpKernel<TContext extends IContext = IContext> {
     /**
-     * Registers a new route with a static path pattern or a dynamic matcher.
+     * Registers a new route using a static path or custom matcher.
      *
-     * This method accepts both conventional route definitions (with path templates)
-     * and advanced matcher-based routes for flexible URL structures.
+     * Returns a route builder that allows chaining middleware and assigning a final handler.
+     * This method is context-generic, allowing temporary overrides for specific routes
+     * if their context differs from the kernel-wide default.
      *
-     * Returns a route builder that allows chaining middleware and assigning a handler.
+     * @template _TContext Optional context override for the specific route being registered.
+     *                     Defaults to the kernel's generic `TContext`.
      *
-     * @param definition - A static or dynamic route definition, including the HTTP method
-     *                     and either a path pattern or custom matcher function.
-     * @returns A builder interface to attach middleware and define the handler.
+     * @param definition - A route definition containing the HTTP method and either a path
+     *                     pattern (e.g., `/users/:id`) or a custom matcher function.
+     * @returns A fluent builder interface for attaching middleware and setting the handler.
      */
-    route(definition: IRouteDefinition): IRouteBuilder;
+    route<_TContext extends IContext = TContext>(
+        definition: IRouteDefinition,
+    ): IRouteBuilder; // IRouteBuilder<_TContext>
 
     /**
-     * Handles an incoming HTTP request by matching it against registered routes,
-     * executing any associated middleware in order, and invoking the final route handler.
+     * Handles an incoming HTTP request by matching it to a route, executing its middleware,
+     * and invoking the final handler. Automatically populates route parameters (`ctx.params`),
+     * query parameters (`ctx.query`), and initializes an empty mutable state (`ctx.state`).
      *
-     * This method serves as the main entry point to integrate with `Deno.serve`.
+     * This method is typically passed directly to `Deno.serve()` as the request handler.
      *
-     * @param request - The incoming HTTP request object.
+     * @template _TContext Optional override for the context type of the current request.
+     *                     Useful for testing or simulated requests. Defaults to the kernel’s `TContext`.
+     *
+     * @param request - The incoming HTTP request to dispatch.
      * @returns A promise resolving to the final HTTP response.
      */
-    handle(request: Request): Promise<Response>;
+    handle<_TContext extends IContext = TContext>(
+        request: Request,
+    ): Promise<Response>;
 }