@fishka/express 0.9.13 → 0.9.15

package/dist/esm/error-handling.d.ts

@@ -1,9 +1,78 @@
 import { NextFunction } from 'express';
 import { ExpressFunction, ExpressRequest, ExpressResponse } from './utils/express.utils';
-/** Catches all kinds of unprocessed exceptions thrown from a single route. */
+/**
+ * @Internal
+ * Wraps a route handler to catch and convert errors to API responses.
+ * Applied automatically to all routes registered via createRouteTable().
+ *
+ * Catches:
+ * - Errors thrown in validators ($path, $query, $body)
+ * - Errors thrown in the run() handler
+ * - Errors thrown in endpoint middlewares
+ *
+ * Logs errors to console (error level for 5xx).
+ */
 export declare function catchRouteErrors(fn: ExpressFunction): ExpressFunction;
 /**
- * Catches all errors in Express.js and is installed as global middleware.
- * Note that individual routes are wrapped with 'catchRouteErrors' middleware.
+ * Express error-handling middleware (4 parameters) for catching errors.
+ * Can be mounted at any level - global, path-specific, or router-specific.
+ *
+ * @example
+ * // Global
+ * app.use(catchAllMiddleware);
+ *
+ * // Path-specific
+ * app.use('/api', catchAllMiddleware);
+ *
+ * // Router-specific
+ * const router = express.Router();
+ * router.use(catchAllMiddleware);
+ *
+ * Catches:
+ * - Errors from Express middleware (passed via next(error))
+ * - JSON parsing errors (SyntaxError) - returns 400
+ * - Any errors that escape catchRouteErrors
+ *
+ * Note: Individual routes are already wrapped with catchRouteErrors(),
+ * so this middleware primarily catches middleware and parsing errors.
  */
 export declare function catchAllMiddleware(error: unknown, _: ExpressRequest, res: ExpressResponse, next: NextFunction): Promise<void>;
+/** Options for installProcessHandlers(). */
+export interface ProcessHandlersOptions {
+    /** Custom handler for uncaught exceptions. Called before default logging. */
+    onUncaughtException?: (error: Error) => void;
+    /** Custom handler for unhandled promise rejections. Called before default logging. */
+    onUnhandledRejection?: (reason: unknown) => void;
+    /** Async cleanup function called on shutdown signals. */
+    onShutdown?: () => Promise<void>;
+    /** Force exit timeout in ms if shutdown hangs. Default: 10000 */
+    shutdownTimeout?: number;
+    /** Signals to handle for graceful shutdown. Default: ['SIGTERM', 'SIGINT'] */
+    shutdownSignals?: NodeJS.Signals[];
+}
+/**
+ * Installs process-level handlers for errors and graceful shutdown.
+ * Call once at application startup, before app.listen().
+ *
+ * Error handling:
+ * - Uncaught exceptions (sync throws outside Express middleware)
+ * - Unhandled promise rejections (forgotten await, missing .catch())
+ *
+ * Graceful shutdown:
+ * - SIGTERM (Docker/K8s/systemd stop)
+ * - SIGINT (Ctrl+C)
+ * - Timeout protection (force exit if shutdown hangs)
+ * - Double-shutdown prevention
+ *
+ * @example
+ * installProcessHandlers({
+ *   onUncaughtException: (error) => sendToMonitoring(error),
+ *   onUnhandledRejection: (reason) => sendToMonitoring(reason),
+ *   onShutdown: async () => {
+ *     await database.close();
+ *     await server.close();
+ *   },
+ *   shutdownTimeout: 15000,
+ * });
+ */
+export declare function installProcessHandlers(options?: ProcessHandlersOptions): void;

package/dist/esm/error-handling.js

@@ -3,6 +3,12 @@ import { HttpError } from './api.types';
 import { HTTP_BAD_REQUEST, HTTP_INTERNAL_SERVER_ERROR } from './http-status-codes';
 import { getRequestLocalStorage } from './thread-local/thread-local-storage';
 import { wrapAsApiResponse } from './utils/conversion.utils';
+/**
+ * Converts any error into a standardized API response format.
+ * - HttpError: Uses the error's status code and message
+ * - Other errors: Returns 500 with the error message or 'Internal error'
+ * Attaches requestId from thread-local storage if available.
+ */
 function buildApiResponse(error) {
     const tls = getRequestLocalStorage();
     const requestId = tls?.requestId;
@@ -28,7 +34,18 @@ function buildApiResponse(error) {
     }
     return response;
 }
-/** Catches all kinds of unprocessed exceptions thrown from a single route. */
+/**
+ * @Internal
+ * Wraps a route handler to catch and convert errors to API responses.
+ * Applied automatically to all routes registered via createRouteTable().
+ *
+ * Catches:
+ * - Errors thrown in validators ($path, $query, $body)
+ * - Errors thrown in the run() handler
+ * - Errors thrown in endpoint middlewares
+ *
+ * Logs errors to console (error level for 5xx).
+ */
 export function catchRouteErrors(fn) {
     return async (req, res, next) => {
         try {
@@ -39,17 +56,33 @@ export function catchRouteErrors(fn) {
             if (apiResponse.status >= HTTP_INTERNAL_SERVER_ERROR) {
                 console.error(`catchRouteErrors: ${req.path}`, error);
             }
-            else {
-                console.log(`catchRouteErrors: ${req.path}`, error);
-            }
             res.status(apiResponse.status);
             res.send(apiResponse);
         }
     };
 }
 /**
- * Catches all errors in Express.js and is installed as global middleware.
- * Note that individual routes are wrapped with 'catchRouteErrors' middleware.
+ * Express error-handling middleware (4 parameters) for catching errors.
+ * Can be mounted at any level - global, path-specific, or router-specific.
+ *
+ * @example
+ * // Global
+ * app.use(catchAllMiddleware);
+ *
+ * // Path-specific
+ * app.use('/api', catchAllMiddleware);
+ *
+ * // Router-specific
+ * const router = express.Router();
+ * router.use(catchAllMiddleware);
+ *
+ * Catches:
+ * - Errors from Express middleware (passed via next(error))
+ * - JSON parsing errors (SyntaxError) - returns 400
+ * - Any errors that escape catchRouteErrors
+ *
+ * Note: Individual routes are already wrapped with catchRouteErrors(),
+ * so this middleware primarily catches middleware and parsing errors.
  */
 export async function catchAllMiddleware(error, _, res, next) {
     if (!error) {
@@ -59,9 +92,75 @@ export async function catchAllMiddleware(error, _, res, next) {
     // Report as critical. This kind of error should never happen.
     console.error('catchAllMiddleware:', getMessageFromError(error));
     const apiResponse = error instanceof SyntaxError // JSON body parsing error.
-        ? buildApiResponse(`${HTTP_BAD_REQUEST}: Failed to parse request: ${error.message}`)
+        ? buildApiResponse(new HttpError(HTTP_BAD_REQUEST, `Failed to parse request: ${error.message}`))
         : buildApiResponse(error);
     res.status(apiResponse.status);
     res.send(apiResponse);
 }
+/**
+ * Installs process-level handlers for errors and graceful shutdown.
+ * Call once at application startup, before app.listen().
+ *
+ * Error handling:
+ * - Uncaught exceptions (sync throws outside Express middleware)
+ * - Unhandled promise rejections (forgotten await, missing .catch())
+ *
+ * Graceful shutdown:
+ * - SIGTERM (Docker/K8s/systemd stop)
+ * - SIGINT (Ctrl+C)
+ * - Timeout protection (force exit if shutdown hangs)
+ * - Double-shutdown prevention
+ *
+ * @example
+ * installProcessHandlers({
+ *   onUncaughtException: (error) => sendToMonitoring(error),
+ *   onUnhandledRejection: (reason) => sendToMonitoring(reason),
+ *   onShutdown: async () => {
+ *     await database.close();
+ *     await server.close();
+ *   },
+ *   shutdownTimeout: 15000,
+ * });
+ */
+export function installProcessHandlers(options) {
+    // Error handlers
+    process.on('uncaughtException', (error) => {
+        options?.onUncaughtException?.(error);
+        console.error('CRITICAL - Uncaught Exception:', error);
+    });
+    process.on('unhandledRejection', (reason) => {
+        options?.onUnhandledRejection?.(reason);
+        console.error('CRITICAL - Unhandled Rejection:', reason);
+    });
+    // Graceful shutdown
+    const onShutdown = options?.onShutdown;
+    if (onShutdown) {
+        let isShuttingDown = false;
+        const signals = options?.shutdownSignals ?? ['SIGTERM', 'SIGINT'];
+        const timeout = options?.shutdownTimeout ?? 10000;
+        const shutdown = async (signal) => {
+            if (isShuttingDown)
+                return;
+            isShuttingDown = true;
+            console.log(`${signal} received, shutting down gracefully...`);
+            const timer = setTimeout(() => {
+                console.error('Shutdown timeout, forcing exit');
+                process.exit(1);
+            }, timeout);
+            try {
+                await onShutdown();
+                clearTimeout(timer);
+                process.exit(0);
+            }
+            catch (err) {
+                console.error('Shutdown error:', err);
+                clearTimeout(timer);
+                process.exit(1);
+            }
+        };
+        for (const signal of signals) {
+            process.on(signal, () => shutdown(signal));
+        }
+    }
+}
 //# sourceMappingURL=error-handling.js.map

package/dist/esm/error-handling.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-handling.js","sourceRoot":"","sources":["../../src/error-handling.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"error-handling.js","sourceRoot":"","sources":["../../src/error-handling.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -13,3 +13,4 @@ export * from './router';
 export * from './thread-local/thread-local-storage';
 export * from './thread-local/thread-local-storage-middleware';
 export * from './utils/express.utils';
+export * from './utils/type-validators';

package/dist/esm/index.js

@@ -13,4 +13,5 @@ export * from './router';
 export * from './thread-local/thread-local-storage';
 export * from './thread-local/thread-local-storage-middleware';
 export * from './utils/express.utils';
+export * from './utils/type-validators';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,qCAAqC,CAAC;AACpD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,qCAAqC,CAAC;AACpD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC"}

package/dist/esm/route-table.d.ts

@@ -1,3 +1,4 @@
+import { TypedValidatorMap } from './api.types';
 import { DeleteEndpoint, GetEndpoint, PatchEndpoint, PostEndpoint, PutEndpoint, RequestContext, ResponseOrValue } from './router';
 import { ExpressRouter } from './utils/express.utils';
 /**
@@ -7,13 +8,20 @@ import { ExpressRouter } from './utils/express.utils';
 export declare class RouteTable {
     private readonly app;
     constructor(app: ExpressRouter);
-    get<T>(path: string, endpoint: GetEndpoint<T> | GetEndpoint<T[]>): this;
-    get<T>(path: string, run: (ctx: RequestContext) => Promise<ResponseOrValue<T>>): this;
-    post<Body, Result>(path: string, endpoint: PostEndpoint<Body, Result>): this;
-    patch<Body, Result>(path: string, endpoint: PatchEndpoint<Body, Result>): this;
-    put<Body, Result>(path: string, endpoint: PutEndpoint<Body, Result>): this;
-    delete(path: string, endpoint: DeleteEndpoint): this;
-    delete(path: string, run: (ctx: RequestContext) => Promise<void>): this;
+    /** Register GET endpoint with full type inference for path/query params. */
+    get<Result, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap>(path: string, endpoint: GetEndpoint<Result, PathParams, QueryParams>): this;
+    /** Register GET endpoint with function shorthand. */
+    get<Result>(path: string, run: (ctx: RequestContext) => ResponseOrValue<Result> | Promise<ResponseOrValue<Result>>): this;
+    /** Register POST endpoint with full type inference for path/query params. */
+    post<Body, Result = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap>(path: string, endpoint: PostEndpoint<Body, Result, PathParams, QueryParams>): this;
+    /** Register PATCH endpoint with full type inference for path/query params. */
+    patch<Body, Result = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap>(path: string, endpoint: PatchEndpoint<Body, Result, PathParams, QueryParams>): this;
+    /** Register PUT endpoint with full type inference for path/query params. */
+    put<Body, Result = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap>(path: string, endpoint: PutEndpoint<Body, Result, PathParams, QueryParams>): this;
+    /** Register DELETE endpoint with full endpoint object. */
+    delete<PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap>(path: string, endpoint: DeleteEndpoint<PathParams, QueryParams>): this;
+    /** Register DELETE endpoint with function shorthand. */
+    delete(path: string, run: (ctx: RequestContext) => void | Promise<void>): this;
 }
 /**
  * Factory function to create a new route table.

package/dist/esm/route-table.js

@@ -12,14 +12,17 @@ export class RouteTable {
         mountGet(this.app, path, endpoint);
         return this;
     }
+    /** Register POST endpoint with full type inference for path/query params. */
     post(path, endpoint) {
         mountPost(this.app, path, endpoint);
         return this;
     }
+    /** Register PATCH endpoint with full type inference for path/query params. */
     patch(path, endpoint) {
         mountPatch(this.app, path, endpoint);
         return this;
     }
+    /** Register PUT endpoint with full type inference for path/query params. */
     put(path, endpoint) {
         mountPut(this.app, path, endpoint);
         return this;

package/dist/esm/route-table.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-table.js","sourceRoot":"","sources":["../../src/route-table.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,GAMT,MAAM,UAAU,CAAC;AAGlB;;;GAGG;AACH,MAAM,OAAO,UAAU;IACrB,YAA6B,GAAkB;QAAlB,QAAG,GAAH,GAAG,CAAe;IAAG,CAAC;IAInD,GAAG,CACD,IAAY,EACZ,aAAyG;QAEzG,MAAM,QAAQ,GAAG,OAAO,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;QAC9F,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAA0B,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAe,IAAY,EAAE,QAAoC;QACnE,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAe,IAAY,EAAE,QAAqC;QACrE,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAe,IAAY,EAAE,QAAmC;QACjE,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAID,MAAM,CAAC,IAAY,EAAE,aAAwE;QAC3F,MAAM,QAAQ,GAAG,OAAO,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;QAC9F,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAkB;IACjD,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"route-table.js","sourceRoot":"","sources":["../../src/route-table.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,GAMT,MAAM,UAAU,CAAC;AAGlB;;;GAGG;AACH,MAAM,OAAO,UAAU;IACrB,YAA6B,GAAkB;QAAlB,QAAG,GAAH,GAAG,CAAe;IAAG,CAAC;IAYnD,GAAG,CAKD,IAAY,EACZ,aAEyF;QAEzF,MAAM,QAAQ,GAAG,OAAO,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;QAC9F,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAgC,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAKF,IAAY,EAAE,QAA6D;QAC3E,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAA4C,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAKH,IAAY,EAAE,QAA8D;QAC5E,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAA6C,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4EAA4E;IAC5E,GAAG,CAKD,IAAY,EAAE,QAA4D;QAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAA2C,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IAWD,MAAM,CAIJ,IAAY,EACZ,aAAwG;QAExG,MAAM,QAAQ,GAAG,OAAO,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;QAC9F,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAA0B,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAkB;IACjD,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/esm/router.d.ts

@@ -1,5 +1,5 @@
 import { Assertion, ObjectAssertion } from '@fishka/assertions';
-import { ApiResponse, UrlTokensValidator } from './api.types';
+import { ApiResponse, InferValidated, TypedValidatorMap } from './api.types';
 import { AuthUser } from './auth/auth.types';
 import { ExpressRequest, ExpressResponse, ExpressRouter } from './utils/express.utils';
 /** Express API allows handlers to return a response in the raw form. */
@@ -10,7 +10,7 @@ export type ResponseOrValue<ResponseEntity> = ApiResponse<ResponseEntity> | Resp
  */
 export type EndpointMiddleware<Context = RequestContext> = (run: () => Promise<unknown>, context: Context) => Promise<unknown>;
 /** Generic request context passed to all handlers. Database-agnostic and extensible. */
-export interface RequestContext<Body = void> {
+export interface RequestContext<Body = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> {
     /** Parsed and validated request body (for POST/PATCH/PUT handlers). */
     body: Body;
     /** Express Request object. */
@@ -19,18 +19,10 @@ export interface RequestContext<Body = void> {
     res: ExpressResponse;
     /** Authenticated user (if any). Populated by auth middleware. */
     authUser?: AuthUser;
-    /**
-     * Generic parameter access with lazy validation.
-     * Provides type-safe access to URL path and query parameters.
-     */
-    params: {
-        get(key: string): string;
-        tryGet(key: string): string | undefined;
-    };
-    /** Query parameter access. */
-    query: {
-        get(key: string): string | undefined;
-    };
+    /** Validated path parameters (typed from $path validators). */
+    path: InferValidated<PathParams>;
+    /** Validated query parameters (typed from $query validators). */
+    query: InferValidated<QueryParams>;
     /**
      * Generic state storage for middleware to attach data.
      * Allows middleware to pass information to handlers and other middleware.
@@ -38,47 +30,47 @@ export interface RequestContext<Body = void> {
     state: Map<string, unknown>;
 }
 /** Base interface with common endpoint properties. */
-export interface EndpointBase<Context = RequestContext, Result = unknown> {
-    /** Path parameter validator. */
-    $path?: UrlTokensValidator;
-    /** Query parameter validator. */
-    $query?: UrlTokensValidator;
+export interface EndpointBase<PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap, Body = void, Result = unknown> {
+    /** Path parameter validators (typed). */
+    $path?: PathParams;
+    /** Query parameter validators (typed). */
+    $query?: QueryParams;
     /** Optional middleware to execute before the handler. */
     middlewares?: Array<EndpointMiddleware>;
-    /** Handler function. */
-    run: (ctx: Context) => Promise<ResponseOrValue<Result>>;
+    /** Handler function. Can be sync or async. */
+    run: (ctx: RequestContext<Body, PathParams, QueryParams>) => ResponseOrValue<Result> | Promise<ResponseOrValue<Result>>;
 }
 /** Descriptor for GET list routes. */
-export type GetListEndpoint<ResultElementType> = EndpointBase<RequestContext, Array<ResultElementType>>;
+export type GetListEndpoint<ResultElementType, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> = EndpointBase<PathParams, QueryParams, void, Array<ResultElementType>>;
 /** Descriptor for GET routes. */
-export type GetEndpoint<Result> = EndpointBase<RequestContext, Result>;
+export type GetEndpoint<Result, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> = EndpointBase<PathParams, QueryParams, void, Result>;
 /** Descriptor for POST routes. */
-export interface PostEndpoint<Body, Result = void> extends EndpointBase<RequestContext<Body>, Result> {
+export interface PostEndpoint<Body, Result = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> extends EndpointBase<PathParams, QueryParams, Body, Result> {
     /** Request body validator. */
     $body: Body extends object ? ObjectAssertion<Body> : Assertion<Body>;
 }
 /** Same as POST. Used for full object updates. */
-export type PutEndpoint<Body, Result = void> = PostEndpoint<Body, Result>;
+export type PutEndpoint<Body, Result = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> = PostEndpoint<Body, Result, PathParams, QueryParams>;
 /** Same as PUT. While PUT is used for the whole object update, PATCH is used for a partial update. */
-export type PatchEndpoint<Body, Result = void> = PutEndpoint<Body, Result>;
+export type PatchEndpoint<Body, Result = void, PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> = PutEndpoint<Body, Result, PathParams, QueryParams>;
 /** Descriptor for DELETE routes. */
-export type DeleteEndpoint = EndpointBase<RequestContext, void>;
+export type DeleteEndpoint<PathParams extends TypedValidatorMap = TypedValidatorMap, QueryParams extends TypedValidatorMap = TypedValidatorMap> = EndpointBase<PathParams, QueryParams, void, void>;
 /** Union type for all route registration info objects. */
 export type RouteRegistrationInfo = ({
     method: 'get';
-    route: GetEndpoint<unknown> | GetListEndpoint<unknown>;
+    endpoint: GetEndpoint<unknown> | GetListEndpoint<unknown>;
 } | {
     method: 'post';
-    route: PostEndpoint<unknown>;
+    endpoint: PostEndpoint<unknown>;
 } | {
     method: 'patch';
-    route: PatchEndpoint<unknown>;
+    endpoint: PatchEndpoint<unknown>;
 } | {
     method: 'put';
-    route: PutEndpoint<unknown>;
+    endpoint: PutEndpoint<unknown>;
 } | {
     method: 'delete';
-    route: DeleteEndpoint;
+    endpoint: DeleteEndpoint;
 }) & {
     path: string;
 };
@@ -93,4 +85,4 @@ export declare const mountPut: <Body, Result>(app: ExpressRouter, path: string,
 /** Registers a DELETE route. */
 export declare const mountDelete: (app: ExpressRouter, path: string, endpoint: DeleteEndpoint) => void;
 /** Mounts a route with the given method, endpoint, and path. */
-export declare function mount(app: ExpressRouter, { method, route, path }: RouteRegistrationInfo): void;
+export declare function mount(app: ExpressRouter, { method, endpoint, path }: RouteRegistrationInfo): void;

package/dist/esm/router.js

@@ -1,6 +1,6 @@
-import { callValueAssertion, getMessageFromError, validateObject, } from '@fishka/assertions';
+import { getMessageFromError, validateObject } from '@fishka/assertions';
 import * as url from 'url';
-import { assertHttp, HttpError, URL_PARAMETER_INFO } from './api.types';
+import { assertHttp, HttpError } from './api.types';
 import { catchRouteErrors } from './error-handling';
 import { HTTP_BAD_REQUEST, HTTP_OK } from './http-status-codes';
 import { getRequestLocalStorage } from './thread-local/thread-local-storage';
@@ -9,19 +9,19 @@ import { wrapAsApiResponse } from './utils/conversion.utils';
 // Internal implementation details
 // ============================================================================
 /** Registers a GET route. */
-export const mountGet = (app, path, endpoint) => mount(app, { method: 'get', route: endpoint, path });
+export const mountGet = (app, path, endpoint) => mount(app, { method: 'get', endpoint, path });
 /** Registers a POST route. */
-export const mountPost = (app, path, endpoint) => mount(app, { method: 'post', route: endpoint, path });
+export const mountPost = (app, path, endpoint) => mount(app, { method: 'post', endpoint: endpoint, path });
 /** Registers a PATCH route. */
-export const mountPatch = (app, path, endpoint) => mount(app, { method: 'patch', route: endpoint, path });
+export const mountPatch = (app, path, endpoint) => mount(app, { method: 'patch', endpoint: endpoint, path });
 /** Registers a PUT route. */
-export const mountPut = (app, path, endpoint) => mount(app, { method: 'put', route: endpoint, path });
+export const mountPut = (app, path, endpoint) => mount(app, { method: 'put', endpoint: endpoint, path });
 /** Registers a DELETE route. */
-export const mountDelete = (app, path, endpoint) => mount(app, { method: 'delete', route: endpoint, path });
+export const mountDelete = (app, path, endpoint) => mount(app, { method: 'delete', endpoint, path });
 /** Mounts a route with the given method, endpoint, and path. */
-export function mount(app, { method, route, path }) {
+export function mount(app, { method, endpoint, path }) {
     const fullPath = path.startsWith('/') ? path : `/${path}`;
-    const handler = createRouteHandler(method, route);
+    const handler = createRouteHandler(method, endpoint);
     app[method](fullPath, catchRouteErrors(handler));
 }
 /**
@@ -56,51 +56,46 @@ function createRouteHandler(method, endpoint) {
 }
 /**
  * @Internal
- * Validates request parameters using custom validators.
+ * Validates and builds typed path/query parameters using $path and $query validators.
  */
-function validateUrlParameters(req, { $path, $query, }) {
+function buildValidatedParams(req, $path, $query) {
+    const pathResult = {};
+    const queryResult = {};
     try {
-        for (const key in req.params) {
-            const value = req.params[key];
-            // Run Global Validation if registered.
-            const globalValidator = URL_PARAMETER_INFO[key]?.validator;
-            if (globalValidator) {
-                callValueAssertion(value, globalValidator, `${HTTP_BAD_REQUEST}`);
-            }
-            // Run Local Validation.
-            const validator = $path?.[key];
-            if (validator) {
-                callValueAssertion(value, validator, `${HTTP_BAD_REQUEST}`);
+        // Validate path params
+        if ($path) {
+            for (const [key, validator] of Object.entries($path)) {
+                const value = req.params[key];
+                pathResult[key] = validator(value);
             }
         }
-        const parsedUrl = url.parse(req.url, true);
-        for (const key in parsedUrl.query) {
-            const value = parsedUrl.query[key];
-            //  Global Validation if registered (also applies to query params if names match).
-            const globalValidator = URL_PARAMETER_INFO[key]?.validator;
-            if (globalValidator) {
-                // Query params can be string | string[] | undefined. Global validators usually expect string.
-                // We only validate if it's a single value or handle array in validator.
-                // For simplicity, we pass value as is (unknown) to assertion.
-                callValueAssertion(value, globalValidator, `${HTTP_BAD_REQUEST}`);
-            }
-            const validator = $query?.[key];
-            if (validator) {
-                callValueAssertion(value, validator, `${HTTP_BAD_REQUEST}`);
+        // Validate query params
+        if ($query) {
+            const parsedUrl = url.parse(req.url, true);
+            for (const [key, validator] of Object.entries($query)) {
+                const rawValue = parsedUrl.query[key];
+                const value = Array.isArray(rawValue) ? rawValue[0] : rawValue;
+                queryResult[key] = validator(value);
             }
         }
     }
     catch (error) {
+        if (error instanceof HttpError)
+            throw error;
         throw new HttpError(HTTP_BAD_REQUEST, getMessageFromError(error));
     }
+    return {
+        path: pathResult,
+        query: queryResult,
+    };
 }
 /**
  * @Internal
  * Runs GET handler with optional middleware.
  */
 async function executeGetEndpoint(route, req, res) {
-    const requestContext = newRequestContext(undefined, req, res);
-    validateUrlParameters(req, { $path: route.$path, $query: route.$query });
+    const validated = buildValidatedParams(req, route.$path, route.$query);
+    const requestContext = newRequestContext(undefined, req, res, validated.path, validated.query);
     return await executeWithMiddleware(() => route.run(requestContext), route.middlewares || [], requestContext);
 }
 /**
@@ -108,8 +103,8 @@ async function executeGetEndpoint(route, req, res) {
  * Runs DELETE handler with optional middleware.
  */
 async function executeDeleteEndpoint(route, req, res) {
-    const requestContext = newRequestContext(undefined, req, res);
-    validateUrlParameters(req, { $path: route.$path, $query: route.$query });
+    const validated = buildValidatedParams(req, route.$path, route.$query);
+    const requestContext = newRequestContext(undefined, req, res, validated.path, validated.query);
     await executeWithMiddleware(() => route.run(requestContext), route.middlewares || [], requestContext);
     return undefined;
 }
@@ -123,12 +118,11 @@ async function executeBodyEndpoint(route, req, res) {
     try {
         // Handle validation based on whether the validator is an object or function
         if (typeof validator === 'function') {
-            // It's a ValueAssertion (function)
-            callValueAssertion(apiRequest, validator, `${HTTP_BAD_REQUEST}: request body`);
+            // It's a ValueAssertion (function) - call it directly
+            validator(apiRequest);
         }
         else {
             // It's an ObjectAssertion - use validateObject
-            // We strictly assume it is an object because of the type definition (function | object)
             const objectValidator = validator;
             const isEmptyValidator = Object.keys(objectValidator).length === 0;
             const errorMessage = validateObject(apiRequest, objectValidator, `${HTTP_BAD_REQUEST}: request body`, {
@@ -142,9 +136,8 @@ async function executeBodyEndpoint(route, req, res) {
             throw error;
         throw new HttpError(HTTP_BAD_REQUEST, getMessageFromError(error));
     }
-    const requestContext = newRequestContext(apiRequest, req, res);
-    validateUrlParameters(req, { $path: route.$path, $query: route.$query });
-    requestContext.body = req.body;
+    const validated = buildValidatedParams(req, route.$path, route.$query);
+    const requestContext = newRequestContext(apiRequest, req, res, validated.path, validated.query);
     return await executeWithMiddleware(() => route.run(requestContext), (route.middlewares || []), requestContext);
 }
 /**
@@ -166,26 +159,13 @@ async function executeWithMiddleware(run, middlewares, context) {
  * @Internal
  * Creates a new RequestContext instance.
  */
-function newRequestContext(requestBody, req, res) {
+function newRequestContext(requestBody, req, res, validatedPath, validatedQuery) {
     return {
         body: requestBody,
         req,
         res,
-        params: {
-            get: (key) => {
-                const value = req.params[key];
-                assertHttp(value, HTTP_BAD_REQUEST, `Path parameter '${key}' not found`);
-                return value;
-            },
-            tryGet: (key) => req.params[key],
-        },
-        query: {
-            get: (key) => {
-                const parsedUrl = url.parse(req.url, true);
-                const value = parsedUrl.query[key];
-                return Array.isArray(value) ? value[0] : value;
-            },
-        },
+        path: validatedPath,
+        query: validatedQuery,
         state: new Map(),
     };
 }