refactor(core): enhance HttpKernel pipeline and matcher system with full context and error handling

BREAKING CHANGE: `parseQuery` utility removed; `IRouteMatcher` now includes query parsing; `RouteBuilder.middleware` and `handle` are now strictly typed per builder instance.

- Add `isHandler` and `isMiddleware` runtime type guards for validation in `HttpKernel`.
- Introduce `createEmptyContext` for constructing default context objects.
- Support custom HTTP error handlers (`404`, `500`) via `IHttpKernelConfig.httpErrorHandlers`.
- Default error handlers return meaningful HTTP status text (e.g., "Not Found").
- Replace legacy `parseQuery` logic with integrated query extraction via `createRouteMatcher`.

- Strongly type `RouteBuilder.middleware()` and `.handle()` methods without generic overrides.
- Simplify `HttpKernel.handle()` and `executePipeline()` through precise control flow and validation.
- Remove deprecated `registerRoute.ts` and `HttpKernelConfig.ts` in favor of colocated type exports.

- Add tests for integrated query parsing in `createRouteMatcher`.
- Improve error handling tests: middleware/handler validation, double `next()` call, thrown exceptions.
- Replace `assertRejects` with plain response code checks (via updated error handling).

- Removed `parseQuery.ts` and all related tests — query parsing is now built into route matching.
- `IRouteMatcher` signature changed to return `{ params, query }` instead of only `params`.
- `HttpKernelConfig` now uses `DeepPartial` and includes `httpErrorHandlers`.
- `RouteBuilder`'s generics are simplified for better DX and improved type safety.

This refactor improves clarity, test coverage, and runtime safety of the request lifecycle while reducing boilerplate and eliminating duplicated query handling logic.

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

src/Types/DeepPartial.ts

@@ -0,0 +1,4 @@
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]>
+        : T[P];
+};

src/Types/HttpErrorHandler.ts

@@ -0,0 +1,28 @@
+import { IContext } from '../Interfaces/mod.ts';
+
+/**
+ * Defines a handler function for errors that occur during the execution
+ * of middleware or route handlers within the HTTP kernel.
+ *
+ * This function receives both the request context and the thrown error,
+ * and is responsible for producing an appropriate HTTP `Response`.
+ *
+ * Typical use cases include:
+ * - Mapping known error types to specific HTTP status codes.
+ * - Generating structured error responses (e.g. JSON error payloads).
+ * - Logging errors centrally with request metadata.
+ *
+ * The handler may return the response synchronously or asynchronously.
+ *
+ * @template TContext - The specific request context type, allowing typed access to route parameters,
+ *                      query parameters, and per-request state when formatting error responses.
+ *
+ * @param context - The active request context at the time the error occurred.
+ * @param error - The exception or error that was thrown during request processing.
+ *
+ * @returns A `Response` object or a `Promise` resolving to one, to be sent to the client.
+ */
+export type HttpErrorHandler<TContext extends IContext = IContext> = (
+    context?: Partial<TContext>,
+    error?: Error,
+) => Promise<Response> | Response;

src/Types/HttpStatusCode.ts

@@ -0,0 +1,189 @@
+// Informational responses
+/** Indicates that the request was received and the client can continue. */
+export const HTTP_100_CONTINUE = 100;
+/** The server is switching protocols as requested by the client. */
+export const HTTP_101_SWITCHING_PROTOCOLS = 101;
+/** The server has received and is processing the request, but no response is available yet. */
+export const HTTP_102_PROCESSING = 102;
+
+// Successful responses
+/** The request has succeeded. */
+export const HTTP_200_OK = 200;
+/** The request has succeeded and a new resource has been created as a result. */
+export const HTTP_201_CREATED = 201;
+/** The request has been accepted for processing, but the processing is not complete. */
+export const HTTP_202_ACCEPTED = 202;
+/** The server has successfully fulfilled the request and there is no content to send. */
+export const HTTP_204_NO_CONTENT = 204;
+
+// Redirection messages
+/** The resource has been moved permanently to a new URI. */
+export const HTTP_301_MOVED_PERMANENTLY = 301;
+/** The resource resides temporarily under a different URI. */
+export const HTTP_302_FOUND = 302;
+/** Indicates that the resource has not been modified since the last request. */
+export const HTTP_304_NOT_MODIFIED = 304;
+
+// Client error responses
+/** The server could not understand the request due to invalid syntax. */
+export const HTTP_400_BAD_REQUEST = 400;
+/** The request requires user authentication. */
+export const HTTP_401_UNAUTHORIZED = 401;
+/** The server understood the request but refuses to authorize it. */
+export const HTTP_403_FORBIDDEN = 403;
+/** The server cannot find the requested resource. */
+export const HTTP_404_NOT_FOUND = 404;
+/** The request method is known by the server but is not supported by the target resource. */
+export const HTTP_405_METHOD_NOT_ALLOWED = 405;
+/** The request could not be completed due to a conflict with the current state of the resource. */
+export const HTTP_409_CONFLICT = 409;
+/** The server understands the content type but was unable to process the contained instructions. */
+export const HTTP_422_UNPROCESSABLE_ENTITY = 422;
+/** The user has sent too many requests in a given amount of time. */
+export const HTTP_429_TOO_MANY_REQUESTS = 429;
+
+// Server error responses
+/** The server encountered an unexpected condition that prevented it from fulfilling the request. */
+export const HTTP_500_INTERNAL_SERVER_ERROR = 500;
+/** The server does not support the functionality required to fulfill the request. */
+export const HTTP_501_NOT_IMPLEMENTED = 501;
+/** The server, while acting as a gateway or proxy, received an invalid response from the upstream server. */
+export const HTTP_502_BAD_GATEWAY = 502;
+/** The server is not ready to handle the request, often due to maintenance or overload. */
+export const HTTP_503_SERVICE_UNAVAILABLE = 503;
+/** The server is acting as a gateway and cannot get a response in time. */
+export const HTTP_504_GATEWAY_TIMEOUT = 504;
+
+/**
+ * A constant list of supported HTTP status codes used by this application.
+ *
+ * These constants are grouped by category and used to construct the union type `HttpStatusCode`.
+ */
+export const validHttpStatusCodes = [
+    // Informational
+    HTTP_100_CONTINUE,
+    HTTP_101_SWITCHING_PROTOCOLS,
+    HTTP_102_PROCESSING,
+
+    // Successful
+    HTTP_200_OK,
+    HTTP_201_CREATED,
+    HTTP_202_ACCEPTED,
+    HTTP_204_NO_CONTENT,
+
+    // Redirection
+    HTTP_301_MOVED_PERMANENTLY,
+    HTTP_302_FOUND,
+    HTTP_304_NOT_MODIFIED,
+
+    // Client Errors
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_403_FORBIDDEN,
+    HTTP_404_NOT_FOUND,
+    HTTP_405_METHOD_NOT_ALLOWED,
+    HTTP_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_429_TOO_MANY_REQUESTS,
+
+    // Server Errors
+    HTTP_500_INTERNAL_SERVER_ERROR,
+    HTTP_501_NOT_IMPLEMENTED,
+    HTTP_502_BAD_GATEWAY,
+    HTTP_503_SERVICE_UNAVAILABLE,
+    HTTP_504_GATEWAY_TIMEOUT,
+] as const;
+
+/**
+ * A constant list of HTTP error codes that are commonly used in the application.
+ */
+export const validHttpErrorCodes = [
+    // Client Errors
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_403_FORBIDDEN,
+    HTTP_404_NOT_FOUND,
+    HTTP_405_METHOD_NOT_ALLOWED,
+    HTTP_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_429_TOO_MANY_REQUESTS,
+
+    // Server Errors
+    HTTP_500_INTERNAL_SERVER_ERROR,
+    HTTP_501_NOT_IMPLEMENTED,
+    HTTP_502_BAD_GATEWAY,
+    HTTP_503_SERVICE_UNAVAILABLE,
+    HTTP_504_GATEWAY_TIMEOUT,
+] as const;
+
+/**
+ * Maps each supported HTTP status code to its standard status message.
+ *
+ * Useful for logging, diagnostics, or building custom error responses.
+ */
+export const HttpStatusTextMap: Record<
+    typeof validHttpStatusCodes[number],
+    string
+> = {
+    [HTTP_100_CONTINUE]: 'Continue',
+    [HTTP_101_SWITCHING_PROTOCOLS]: 'Switching Protocols',
+    [HTTP_102_PROCESSING]: 'Processing',
+
+    [HTTP_200_OK]: 'OK',
+    [HTTP_201_CREATED]: 'Created',
+    [HTTP_202_ACCEPTED]: 'Accepted',
+    [HTTP_204_NO_CONTENT]: 'No Content',
+
+    [HTTP_301_MOVED_PERMANENTLY]: 'Moved Permanently',
+    [HTTP_302_FOUND]: 'Found',
+    [HTTP_304_NOT_MODIFIED]: 'Not Modified',
+
+    [HTTP_400_BAD_REQUEST]: 'Bad Request',
+    [HTTP_401_UNAUTHORIZED]: 'Unauthorized',
+    [HTTP_403_FORBIDDEN]: 'Forbidden',
+    [HTTP_404_NOT_FOUND]: 'Not Found',
+    [HTTP_405_METHOD_NOT_ALLOWED]: 'Method Not Allowed',
+    [HTTP_409_CONFLICT]: 'Conflict',
+    [HTTP_422_UNPROCESSABLE_ENTITY]: 'Unprocessable Entity',
+    [HTTP_429_TOO_MANY_REQUESTS]: 'Too Many Requests',
+
+    [HTTP_500_INTERNAL_SERVER_ERROR]: 'Internal Server Error',
+    [HTTP_501_NOT_IMPLEMENTED]: 'Not Implemented',
+    [HTTP_502_BAD_GATEWAY]: 'Bad Gateway',
+    [HTTP_503_SERVICE_UNAVAILABLE]: 'Service Unavailable',
+    [HTTP_504_GATEWAY_TIMEOUT]: 'Gateway Timeout',
+};
+
+/**
+ * A union type representing commonly used HTTP status codes.
+ *
+ * This type ensures consistency between runtime and type-level status code handling.
+ *
+ * Example:
+ * ```ts
+ * const status: HttpStatusCode = 404; // ✅ valid
+ * const status: HttpStatusCode = 418; // ❌ Type error (unless added to list)
+ * ```
+ */
+export type HttpStatusCode = typeof validHttpStatusCodes[number];
+
+/**
+ * Type guard to check whether a given value is a valid HTTP status code.
+ *
+ * This is useful for validating numeric values received from external input,
+ * ensuring they conform to known HTTP semantics.
+ *
+ * Example:
+ * ```ts
+ * if (isHttpStatusCode(value)) {
+ *   // value is now typed as HttpStatusCode
+ * }
+ * ```
+ *
+ * @param value - The numeric value to check.
+ * @returns `true` if the value is a recognized HTTP status code, otherwise `false`.
+ */
+export function isHttpStatusCode(value: unknown): value is HttpStatusCode {
+    return typeof value === 'number' &&
+        validHttpStatusCodes.includes(value as HttpStatusCode);
+}

src/Types/Params.ts

@@ -7,4 +7,4 @@
  * All values are strings and should be considered read-only, as they are
  * extracted by the router and should not be modified by application code.
  */
-export type Params = Record<string, string>;
+export type Params = Record<string, string | undefined>;

src/Types/__tests__/HttpMethod.test.ts

@@ -0,0 +1,40 @@
+import { assertEquals } from 'https://deno.land/std/assert/mod.ts';
+import { isHttpMethod, validHttpMethods } from '../HttpMethod.ts';
+
+Deno.test('isHttpMethod: returns true for all valid methods', () => {
+    for (const method of validHttpMethods) {
+        const result = isHttpMethod(method);
+        assertEquals(result, true, `Expected "${method}" to be valid`);
+    }
+});
+
+Deno.test('isHttpMethod: returns false for lowercase or unknown strings', () => {
+    const invalid = [
+        'get',
+        'post',
+        'FETCH',
+        'TRACE',
+        'CONNECT',
+        'INVALID',
+        '',
+        ' ',
+    ];
+
+    for (const method of invalid) {
+        const result = isHttpMethod(method);
+        assertEquals(result, false, `Expected "${method}" to be invalid`);
+    }
+});
+
+Deno.test('isHttpMethod: returns false for non-string inputs', () => {
+    const invalidInputs = [null, undefined, 123, {}, [], true, Symbol('GET')];
+
+    for (const input of invalidInputs) {
+        const result = isHttpMethod(input);
+        assertEquals(
+            result,
+            false,
+            `Expected non-string input to be invalid: ${String(input)}`,
+        );
+    }
+});

src/Types/__tests__/HttpStatusCode.test.ts

@@ -0,0 +1,35 @@
+// src/Types/__tests__/HttpStatusCode.test.ts
+import { assertEquals } from 'https://deno.land/std@0.204.0/assert/mod.ts';
+import { isHttpStatusCode, validHttpStatusCodes } from '../HttpStatusCode.ts';
+
+Deno.test('isHttpStatusCode: returns true for all valid status codes', () => {
+    for (const code of validHttpStatusCodes) {
+        assertEquals(
+            isHttpStatusCode(code),
+            true,
+            `Expected ${code} to be valid`,
+        );
+    }
+});
+
+Deno.test('isHttpStatusCode: returns false for invalid status codes', () => {
+    const invalidInputs = [99, 600, 1234, -1, 0, 999];
+    for (const val of invalidInputs) {
+        assertEquals(
+            isHttpStatusCode(val),
+            false,
+            `Expected ${val} to be invalid`,
+        );
+    }
+});
+
+Deno.test('isHttpStatusCode: returns false for non-numeric values', () => {
+    const invalid = ['200', null, undefined, {}, [], true];
+    for (const val of invalid) {
+        assertEquals(
+            isHttpStatusCode(val),
+            false,
+            `Expected ${val} to be invalid`,
+        );
+    }
+});

src/Types/mod.ts

@@ -1,9 +1,41 @@
 // deno-coverage-ignore-file
 
+export type { DeepPartial } from './DeepPartial.ts';
+export type { HttpErrorHandler } from './HttpErrorHandler.ts';
 export { isHttpMethod, validHttpMethods } from './HttpMethod.ts';
 export type { HttpMethod } from './HttpMethod.ts';
+export {
+    HTTP_100_CONTINUE,
+    HTTP_101_SWITCHING_PROTOCOLS,
+    HTTP_102_PROCESSING,
+    HTTP_200_OK,
+    HTTP_201_CREATED,
+    HTTP_202_ACCEPTED,
+    HTTP_204_NO_CONTENT,
+    HTTP_301_MOVED_PERMANENTLY,
+    HTTP_302_FOUND,
+    HTTP_304_NOT_MODIFIED,
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_403_FORBIDDEN,
+    HTTP_404_NOT_FOUND,
+    HTTP_405_METHOD_NOT_ALLOWED,
+    HTTP_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_429_TOO_MANY_REQUESTS,
+    HTTP_500_INTERNAL_SERVER_ERROR,
+    HTTP_501_NOT_IMPLEMENTED,
+    HTTP_502_BAD_GATEWAY,
+    HTTP_503_SERVICE_UNAVAILABLE,
+    HTTP_504_GATEWAY_TIMEOUT,
+    HttpStatusTextMap,
+    isHttpStatusCode,
+    validHttpErrorCodes,
+    validHttpStatusCodes,
+} from './HttpStatusCode.ts';
+export type { HttpStatusCode } from './HttpStatusCode.ts';
 export type { Params } from './Params.ts';
 export type { Query } from './Query.ts';
+export type { RegisterRoute } from './RegisterRoute.ts';
 export type { ResponseDecorator } from './ResponseDecorator.ts';
 export type { State } from './State.ts';
-export type { RegisterRoute } from './registerRoute.ts';