@fishka/express 0.9.5 → 0.9.7

package/dist/esm/http-status-codes.js

@@ -0,0 +1,224 @@
+/** The request has succeeded (200) */
+export const HTTP_OK = 200;
+/** The request has been fulfilled, and a new resource is created (201) */
+export const HTTP_CREATED = 201;
+/** The request has been accepted for processing, but the processing is not yet complete (202) */
+export const HTTP_ACCEPTED = 202;
+/** The server successfully processed the request, and is not returning any content (204) */
+export const HTTP_NO_CONTENT = 204;
+/** The request has been successfully processed, but is returning no content (205) */
+export const HTTP_RESET_CONTENT = 205;
+/** The server is delivering only part of the resource due to a range header sent by the client (206) */
+export const HTTP_PARTIAL_CONTENT = 206;
+/** The IM used the server processed a request successfully, but the response is transformed (226) */
+export const HTTP_IM_USED = 226;
+/** The resource has been moved permanently to a new URL (301) */
+export const HTTP_MOVED_PERMANENTLY = 301;
+/** The resource is available at a different URL (302) */
+export const HTTP_FOUND = 302;
+/** The resource has not been modified since the last request (304) */
+export const HTTP_NOT_MODIFIED = 304;
+/** The server could not understand the request due to invalid syntax (400) */
+export const HTTP_BAD_REQUEST = 400;
+/** The client must authenticate itself to get the requested response (401) */
+export const HTTP_UNAUTHORIZED = 401;
+/** The client does not have access rights to the content (403) */
+export const HTTP_FORBIDDEN = 403;
+/** The server cannot find the requested resource (404) */
+export const HTTP_NOT_FOUND = 404;
+/** The request method is known by the server but is not supported by the target resource (405) */
+export const HTTP_METHOD_NOT_ALLOWED = 405;
+/** The client must authenticate using a proxy (407) */
+export const HTTP_PROXY_AUTHENTICATION_REQUIRED = 407;
+/** The server timed out waiting for the request (408) */
+export const HTTP_REQUEST_TIMEOUT = 408;
+/** The request conflicts with the current state of the server (409) */
+export const HTTP_CONFLICT = 409;
+/** The resource requested is no longer available and will not be available again (410) */
+export const HTTP_GONE = 410;
+/** The request does not meet the preconditions that the server requires (412) */
+export const HTTP_PRECONDITION_FAILED = 412;
+/** The client sent a request that is too large for the server to process (413) */
+export const HTTP_PAYLOAD_TOO_LARGE = 413;
+/** The URI requested by the client is too long for the server to process (414) */
+export const HTTP_URI_TOO_LONG = 414;
+/** The media format of the requested data is not supported by the server (415) */
+export const HTTP_UNSUPPORTED_MEDIA_TYPE = 415;
+/** The range specified by the client cannot be fulfilled (416) */
+export const HTTP_RANGE_NOT_SATISFIABLE = 416;
+/** The expectation given in the request header could not be met by the server (417) */
+export const HTTP_EXPECTATION_FAILED = 417;
+/** The server refuses to brew coffee because it is a teapot (418) - an Easter egg from RFC 2324 */
+export const HTTP_IM_A_TEAPOT = 418;
+/** The request was well-formed but was unable to be followed due to semantic errors (422) */
+export const HTTP_UNPROCESSABLE_ENTITY = 422;
+/** The resource that is being accessed is locked (423) */
+export const HTTP_LOCKED = 423;
+/** The resource requested is dependent on another resource that has failed (424) */
+export const HTTP_FAILED_DEPENDENCY = 424;
+/** The server is unwilling to risk processing a request that might be replayed (425) */
+export const HTTP_TOO_EARLY = 425;
+/** The client needs to upgrade its protocol (426) */
+export const HTTP_UPGRADE_REQUIRED = 426;
+/** The server requires the request to be conditional (428) */
+export const HTTP_PRECONDITION_REQUIRED = 428;
+/** The client has sent too many requests in a given amount of time (429) */
+export const HTTP_TOO_MANY_REQUESTS = 429;
+/** The request header fields are too large (431) */
+export const HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431;
+/** The client closed the connection with the server before the request was completed (444) */
+export const HTTP_CONNECTION_CLOSED_WITHOUT_RESPONSE = 444;
+/** The client requested an unavailable legal action (451) */
+export const HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451;
+/** The server encountered an internal error and was unable to complete the request (500) */
+export const HTTP_INTERNAL_SERVER_ERROR = 500;
+/** The request method is not supported by the server and cannot be handled (501) */
+export const HTTP_NOT_IMPLEMENTED = 501;
+/** The server, while acting as a gateway or proxy, received an invalid response from the upstream server (502) */
+export const HTTP_BAD_GATEWAY = 502;
+/** The server is not ready to handle the request, typically due to temporary overload or maintenance (503) */
+export const HTTP_SERVICE_UNAVAILABLE = 503;
+/** The server, while acting as a gateway or proxy, did not get a response in time from the upstream server (504) */
+export const HTTP_GATEWAY_TIMEOUT = 504;
+/**
+ * An object containing common HTTP status codes.
+ * These constants can be used to improve code readability and maintainability.
+ * @deprecated Use individual HTTP_* constants for better tree-shaking
+ */
+export const HttpStatusCode = {
+    /** The request has succeeded (200) */
+    OK: HTTP_OK,
+    /** The request has been fulfilled, and a new resource is created (201) */
+    CREATED: HTTP_CREATED,
+    /** The request has been accepted for processing, but the processing is not yet complete (202) */
+    ACCEPTED: HTTP_ACCEPTED,
+    /** The server successfully processed the request, and is not returning any content (204) */
+    NO_CONTENT: HTTP_NO_CONTENT,
+    /** The request has been successfully processed, but is returning no content (205) */
+    RESET_CONTENT: HTTP_RESET_CONTENT,
+    /** The server is delivering only part of the resource due to a range header sent by the client (206) */
+    PARTIAL_CONTENT: HTTP_PARTIAL_CONTENT,
+    /** The IM used the server processed a request successfully, but the response is transformed (226) */
+    IM_USED: HTTP_IM_USED,
+    /** The resource has been moved permanently to a new URL (301) */
+    MOVED_PERMANENTLY: HTTP_MOVED_PERMANENTLY,
+    /** The resource is available at a different URL (302) */
+    FOUND: HTTP_FOUND,
+    /** The resource has not been modified since the last request (304) */
+    NOT_MODIFIED: HTTP_NOT_MODIFIED,
+    /** The server could not understand the request due to invalid syntax (400) */
+    BAD_REQUEST: HTTP_BAD_REQUEST,
+    /** The client must authenticate itself to get the requested response (401) */
+    UNAUTHORIZED: HTTP_UNAUTHORIZED,
+    /** The client does not have access rights to the content (403) */
+    FORBIDDEN: HTTP_FORBIDDEN,
+    /** The server cannot find the requested resource (404) */
+    NOT_FOUND: HTTP_NOT_FOUND,
+    /** The request method is known by the server but is not supported by the target resource (405) */
+    METHOD_NOT_ALLOWED: HTTP_METHOD_NOT_ALLOWED,
+    /** The client must authenticate using a proxy (407) */
+    PROXY_AUTHENTICATION_REQUIRED: HTTP_PROXY_AUTHENTICATION_REQUIRED,
+    /** The server timed out waiting for the request (408) */
+    REQUEST_TIMEOUT: HTTP_REQUEST_TIMEOUT,
+    /** The request conflicts with the current state of the server (409) */
+    CONFLICT: HTTP_CONFLICT,
+    /** The resource requested is no longer available and will not be available again (410) */
+    GONE: HTTP_GONE,
+    /** The request does not meet the preconditions that the server requires (412) */
+    PRECONDITION_FAILED: HTTP_PRECONDITION_FAILED,
+    /** The client sent a request that is too large for the server to process (413) */
+    PAYLOAD_TOO_LARGE: HTTP_PAYLOAD_TOO_LARGE,
+    /** The URI requested by the client is too long for the server to process (414) */
+    URI_TOO_LONG: HTTP_URI_TOO_LONG,
+    /** The media format of the requested data is not supported by the server (415) */
+    UNSUPPORTED_MEDIA_TYPE: HTTP_UNSUPPORTED_MEDIA_TYPE,
+    /** The range specified by the client cannot be fulfilled (416) */
+    RANGE_NOT_SATISFIABLE: HTTP_RANGE_NOT_SATISFIABLE,
+    /** The expectation given in the request header could not be met by the server (417) */
+    EXPECTATION_FAILED: HTTP_EXPECTATION_FAILED,
+    /** The server refuses to brew coffee because it is a teapot (418) - an Easter egg from RFC 2324 */
+    IM_A_TEAPOT: HTTP_IM_A_TEAPOT,
+    /** The request was well-formed but was unable to be followed due to semantic errors (422) */
+    UNPROCESSABLE_ENTITY: HTTP_UNPROCESSABLE_ENTITY,
+    /** The resource that is being accessed is locked (423) */
+    LOCKED: HTTP_LOCKED,
+    /** The resource requested is dependent on another resource that has failed (424) */
+    FAILED_DEPENDENCY: HTTP_FAILED_DEPENDENCY,
+    /** The server is unwilling to risk processing a request that might be replayed (425) */
+    TOO_EARLY: HTTP_TOO_EARLY,
+    /** The client needs to upgrade its protocol (426) */
+    UPGRADE_REQUIRED: HTTP_UPGRADE_REQUIRED,
+    /** The server requires the request to be conditional (428) */
+    PRECONDITION_REQUIRED: HTTP_PRECONDITION_REQUIRED,
+    /** The client has sent too many requests in a given amount of time (429) */
+    TOO_MANY_REQUESTS: HTTP_TOO_MANY_REQUESTS,
+    /** The request header fields are too large (431) */
+    REQUEST_HEADER_FIELDS_TOO_LARGE: HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE,
+    /** The client closed the connection with the server before the request was completed (444) */
+    CONNECTION_CLOSED_WITHOUT_RESPONSE: HTTP_CONNECTION_CLOSED_WITHOUT_RESPONSE,
+    /** The client requested an unavailable legal action (451) */
+    UNAVAILABLE_FOR_LEGAL_REASONS: HTTP_UNAVAILABLE_FOR_LEGAL_REASONS,
+    /** The server encountered an internal error and was unable to complete the request (500) */
+    INTERNAL_SERVER_ERROR: HTTP_INTERNAL_SERVER_ERROR,
+    /** The request method is not supported by the server and cannot be handled (501) */
+    NOT_IMPLEMENTED: HTTP_NOT_IMPLEMENTED,
+    /** The server, while acting as a gateway or proxy, received an invalid response from the upstream server (502) */
+    BAD_GATEWAY: HTTP_BAD_GATEWAY,
+    /** The server is not ready to handle the request, typically due to temporary overload or maintenance (503) */
+    SERVICE_UNAVAILABLE: HTTP_SERVICE_UNAVAILABLE,
+    /** The server, while acting as a gateway or proxy, did not get a response in time from the upstream server (504) */
+    GATEWAY_TIMEOUT: HTTP_GATEWAY_TIMEOUT,
+};
+/**
+ * Returns the reason phrase corresponding to the given HTTP status code.
+ * This is useful for converting status codes into human-readable messages.
+ *
+ * @param statusCode - The HTTP status code for which to get the reason phrase.
+ * @returns The reason phrase associated with the given status code, or "Unknown Status Code" if the status code is not recognized.
+ */
+export const getHttpStatusCodeReasonPhrase = (statusCode) => {
+    const phrases = {
+        200: 'OK',
+        201: 'Created',
+        202: 'Accepted',
+        204: 'No Content',
+        205: 'Reset Content',
+        206: 'Partial Content',
+        226: 'IM Used',
+        301: 'Moved Permanently',
+        302: 'Found',
+        304: 'Not Modified',
+        400: 'Bad Request',
+        401: 'Unauthorized',
+        403: 'Forbidden',
+        404: 'Not Found',
+        405: 'Method Not Allowed',
+        407: 'Proxy Authentication Required',
+        408: 'Request Timeout',
+        409: 'Conflict',
+        410: 'Gone',
+        412: 'Precondition Failed',
+        413: 'Payload Too Large',
+        414: 'URI Too Long',
+        415: 'Unsupported Media Type',
+        416: 'Range Not Satisfiable',
+        417: 'Expectation Failed',
+        418: "I'm a teapot",
+        422: 'Unprocessable Entity',
+        423: 'Locked',
+        424: 'Failed Dependency',
+        425: 'Too Early',
+        426: 'Upgrade Required',
+        428: 'Precondition Required',
+        429: 'Too Many Requests',
+        431: 'Request Header Fields Too Large',
+        444: 'Connection Closed Without Response',
+        451: 'Unavailable For Legal Reasons',
+        500: 'Internal Server Error',
+        501: 'Not Implemented',
+        502: 'Bad Gateway',
+        503: 'Service Unavailable',
+        504: 'Gateway Timeout',
+    };
+    return phrases[statusCode] || 'Unknown Status Code';
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,15 @@
+export * from './api.types';
+export * from './auth/auth-strategy';
+export * from './auth/auth.types';
+export * from './auth/auth.utils';
+export * from './auth/bearer-auth-strategy';
+export * from './config';
+export * from './error-handling';
+export * from './http-status-codes';
+export * from './rate-limit/in-memory-rate-limiter';
+export * from './rate-limit/rate-limit.types';
+export * from './route-table';
+export * from './router';
+export * from './thread-local/thread-local-storage';
+export * from './thread-local/thread-local-storage-middleware';
+export * from './utils/express.utils';

package/dist/esm/index.js

@@ -5,7 +5,7 @@ export * from './auth/auth.utils';
 export * from './auth/bearer-auth-strategy';
 export * from './config';
 export * from './error-handling';
-export * from './http.types';
+export * from './http-status-codes';
 export * from './rate-limit/in-memory-rate-limiter';
 export * from './rate-limit/rate-limit.types';
 export * from './route-table';

package/dist/esm/rate-limit/in-memory-rate-limiter.d.ts

@@ -0,0 +1,35 @@
+import { ExpressFunction } from '../utils/express.utils';
+import { RateLimitConfig, RateLimitResult } from './rate-limit.types';
+/**
+ * In-memory rate limiter using sliding window counter.
+ * Tracks request counts per key with time-based window expiration.
+ */
+declare class InMemoryRateLimiter {
+    private readonly limits;
+    private readonly points;
+    private readonly durationMs;
+    constructor(points: number, durationSeconds: number);
+    /**
+     * Try to consume points from the rate limit.
+     * Returns result if successful, throws if limit exceeded.
+     *
+     * @param key - Unique identifier for the client (e.g., IP address)
+     * @returns Rate limit result with remaining points and ms until reset
+     * @throws RateLimitResult if limit exceeded
+     */
+    consume(key: string): RateLimitResult;
+}
+/**
+ * Creates a rate limiter middleware using in-memory implementation.
+ *
+ * Separate limiters are used for read (GET) and write (POST/PATCH/PUT/DELETE) requests.
+ *
+ * @param config - Rate limit configuration
+ * @returns Express middleware function
+ */
+export declare function createRateLimiterMiddleware(config: RateLimitConfig): Promise<ExpressFunction>;
+/**
+ * Export the in-memory limiter class for advanced use cases where
+ * you might want direct control over rate limit management.
+ */
+export { InMemoryRateLimiter };

package/dist/esm/rate-limit/rate-limit.d.ts

@@ -0,0 +1,19 @@
+import { ExpressResponse } from '../utils/express.utils';
+import { RateLimitResult } from './rate-limit.types';
+/**
+ * Adds rate limit state headers to the response.
+ * See https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
+ *
+ * Headers added:
+ * - X-RateLimit-Limit: Server's quota for requests in the time window
+ * - X-RateLimit-Remaining: Remaining quota in the current window
+ * - X-RateLimit-Reset: Time remaining in the current window (in seconds)
+ * - X-RateLimit-Policy: Quota policies associated with the client
+ * @Internal
+ */
+export declare function addRateLimitHeaders(res: ExpressResponse, result: RateLimitResult, limitPoints: number, duration: number): ExpressResponse;
+/**
+ * Converts milliseconds to seconds, rounding up.
+ * @Internal
+ */
+export declare function msToSeconds(ms: number): number;

package/dist/esm/rate-limit/rate-limit.types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Configuration for rate limiting.
+ */
+export interface RateLimitConfig {
+    /** Rate limit points per time window */
+    points: {
+        read: number;
+        write: number;
+    };
+    /** Duration of the rate limit window in seconds */
+    duration: number;
+    /** Key prefix for rate limit data (optional, defaults to 'rate_limit') */
+    keyPrefix?: string;
+    /** Paths that should bypass rate limiting (default: ['/v1', '/health']) */
+    rateLimitWhitelist?: string[];
+}
+/**
+ * Simple in-memory rate limiter result.
+ */
+export interface RateLimitResult {
+    remainingPoints: number;
+    msBeforeNext: number;
+}

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

@@ -0,0 +1,23 @@
+import { ExpressApplication } from './utils/express.utils';
+import { DeleteEndpoint, GetEndpoint, PatchEndpoint, PostEndpoint, PutEndpoint, RequestContext, ResponseOrValue } from './router';
+/**
+ * Helper utility for organizing and mounting routes.
+ * Provides a fluent interface for registering multiple handlers.
+ */
+export declare class RouteTable {
+    private readonly app;
+    constructor(app: ExpressApplication);
+    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;
+}
+/**
+ * Factory function to create a new route table.
+ * @param app Express application instance
+ * @returns RouteTable instance with fluent API
+ */
+export declare function createRouteTable(app: ExpressApplication): RouteTable;

package/dist/esm/router.d.ts

@@ -0,0 +1,110 @@
+import { Assertion, ObjectAssertion } from '@fishka/assertions';
+import { ApiResponse, UrlTokensValidator } from './api.types';
+import { AuthUser } from './auth/auth.types';
+import { ExpressApplication, ExpressRequest, ExpressResponse } from './utils/express.utils';
+/** Express API allows handlers to return response in the raw form. */
+export type ResponseOrValue<ResponseEntity> = ApiResponse<ResponseEntity> | ResponseEntity;
+/**
+ * Generic middleware hook for endpoint execution.
+ * Allows custom logic like transaction management, authorization checks, etc.
+ */
+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> {
+    /** Parsed and validated request body (for POST/PATCH/PUT handlers). */
+    body: Body;
+    /** Express Request object. */
+    req: ExpressRequest;
+    /** Express Response object. */
+    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;
+    };
+    /**
+     * Generic state storage for middleware to attach data.
+     * Allows middleware to pass information to handlers and other middleware.
+     */
+    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;
+    /** Optional middleware to execute before the handler. */
+    middlewares?: Array<EndpointMiddleware>;
+    /** Handler function. */
+    run: (ctx: Context) => Promise<ResponseOrValue<Result>>;
+}
+/** Descriptor for GET list routes. */
+export type GetListEndpoint<ResultElementType = unknown> = EndpointBase<RequestContext, Array<ResultElementType>>;
+/** Descriptor for GET routes. */
+export type GetEndpoint<Result = unknown> = EndpointBase<RequestContext, Result>;
+/** Descriptor for POST routes. */
+export interface PostEndpoint<Body = unknown, Result = unknown> extends EndpointBase<RequestContext<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 = unknown, Result = unknown> = PostEndpoint<Body, Result>;
+/** Same as PUT. While PUT is used for the whole object update, PATCH is used for a partial update. */
+export type PatchEndpoint<Body = unknown, Result = unknown> = PutEndpoint<Body, Result>;
+/** Descriptor for DELETE routes. */
+export type DeleteEndpoint = EndpointBase<RequestContext, void>;
+/** Union type for all route registration info objects. */
+export type RouteRegistrationInfo = ({
+    method: 'get';
+    route: GetEndpoint | GetListEndpoint;
+} | {
+    method: 'post';
+    route: PostEndpoint;
+} | {
+    method: 'patch';
+    route: PatchEndpoint;
+} | {
+    method: 'put';
+    route: PutEndpoint;
+} | {
+    method: 'delete';
+    route: DeleteEndpoint;
+}) & {
+    path: string;
+};
+/**
+ * Registers a GET route.
+ */
+export declare const mountGet: (app: ExpressApplication, path: string, endpoint: GetEndpoint | GetListEndpoint) => void;
+/**
+ * Registers a POST route.
+ */
+export declare const mountPost: <Body, Result>(app: ExpressApplication, path: string, endpoint: PostEndpoint<Body, Result>) => void;
+/**
+ * Registers a PATCH route.
+ */
+export declare const mountPatch: <Body, Result>(app: ExpressApplication, path: string, endpoint: PatchEndpoint<Body, Result>) => void;
+/**
+ * Registers a PUT route.
+ */
+export declare const mountPut: <Body, Result>(app: ExpressApplication, path: string, endpoint: PutEndpoint<Body, Result>) => void;
+/**
+ * Registers a DELETE route.
+ */
+export declare const mountDelete: (app: ExpressApplication, path: string, endpoint: DeleteEndpoint) => void;
+/**
+ * Mounts a route with the given method, endpoint, and path.
+ */
+export declare function mount(app: ExpressApplication, { method, route, path }: RouteRegistrationInfo): void;

package/dist/esm/router.js

@@ -1,7 +1,7 @@
 import { assertTruthy, callValueAssertion, getMessageFromError, validateObject, } from '@fishka/assertions';
 import * as url from 'url';
-import { HttpError, URL_PARAMETER_INFO } from './api.types';
-import { BAD_REQUEST_STATUS, OK_STATUS } from './http.types';
+import { HttpError, URL_PARAMETER_INFO, assertHttp } from './api.types';
+import { HTTP_BAD_REQUEST, HTTP_OK } from './http-status-codes';
 import { catchRouteErrors } from './error-handling';
 import { getRequestLocalStorage } from './thread-local/thread-local-storage';
 import { wrapAsApiResponse } from './utils/conversion.utils';
@@ -61,7 +61,7 @@ function createRouteHandler(method, endpoint) {
         if (tls?.requestId) {
             response.requestId = tls.requestId;
         }
-        response.status = response.status || OK_STATUS;
+        response.status = response.status || HTTP_OK;
         res.status(response.status);
         res.send(response);
     };
@@ -77,12 +77,12 @@ function validateUrlParameters(req, { $path, $query, }) {
             // Run Global Validation if registered.
             const globalValidator = URL_PARAMETER_INFO[key]?.validator;
             if (globalValidator) {
-                callValueAssertion(value, globalValidator, `${BAD_REQUEST_STATUS}`);
+                callValueAssertion(value, globalValidator, `${HTTP_BAD_REQUEST}`);
             }
             // Run Local Validation.
             const validator = $path?.[key];
             if (validator) {
-                callValueAssertion(value, validator, `${BAD_REQUEST_STATUS}`);
+                callValueAssertion(value, validator, `${HTTP_BAD_REQUEST}`);
             }
         }
         const parsedUrl = url.parse(req.url, true);
@@ -94,16 +94,16 @@ function validateUrlParameters(req, { $path, $query, }) {
                 // 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, `${BAD_REQUEST_STATUS}`);
+                callValueAssertion(value, globalValidator, `${HTTP_BAD_REQUEST}`);
             }
             const validator = $query?.[key];
             if (validator) {
-                callValueAssertion(value, validator, `${BAD_REQUEST_STATUS}`);
+                callValueAssertion(value, validator, `${HTTP_BAD_REQUEST}`);
             }
         }
     }
     catch (error) {
-        throw new HttpError(BAD_REQUEST_STATUS, getMessageFromError(error));
+        throw new HttpError(HTTP_BAD_REQUEST, getMessageFromError(error));
     }
 }
 /**
@@ -136,23 +136,23 @@ async function executeBodyEndpoint(route, req, res) {
         // Handle validation based on whether validator is an object or function
         if (typeof validator === 'function') {
             // It's a ValueAssertion (function)
-            callValueAssertion(apiRequest, validator, `${BAD_REQUEST_STATUS}: request body`);
+            callValueAssertion(apiRequest, validator, `${HTTP_BAD_REQUEST}: request body`);
         }
         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 error = validateObject(apiRequest, objectValidator, `${BAD_REQUEST_STATUS}: request body`, {
+            const errorMessage = validateObject(apiRequest, objectValidator, `${HTTP_BAD_REQUEST}: request body`, {
                 failOnUnknownFields: !isEmptyValidator,
             });
-            assertTruthy(!error, error);
+            assertHttp(!errorMessage, HTTP_BAD_REQUEST, errorMessage || 'Request body validation failed');
         }
     }
     catch (error) {
         if (error instanceof HttpError)
             throw error;
-        throw new HttpError(BAD_REQUEST_STATUS, getMessageFromError(error));
+        throw new HttpError(HTTP_BAD_REQUEST, getMessageFromError(error));
     }
     const requestContext = newRequestContext(apiRequest, req, res);
     validateUrlParameters(req, { $path: route.$path, $query: route.$query });

package/dist/esm/thread-local/thread-local-storage-middleware.d.ts

@@ -0,0 +1,9 @@
+import { ExpressFunction } from '../utils/express.utils';
+/**
+ * Creates middleware that initializes thread-local storage for each request.
+ * Automatically generates a unique request ID and makes it available throughout
+ * the request lifecycle.
+ *
+ * @returns Express middleware function
+ */
+export declare function createTlsMiddleware(): ExpressFunction;

package/dist/esm/thread-local/thread-local-storage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Thread-local storage data for per-request context.
+ * Stores information that should be available throughout the request lifecycle.
+ */
+export interface ThreadLocalData {
+    /** Unique request identifier */
+    requestId: string;
+    /** Additional custom fields can be stored */
+    [key: string]: unknown;
+}
+/**
+ * Gets all thread-local data for the current request context.
+ * Returns undefined if called outside an async context managed by API.
+ * @Internal
+ */
+export declare function getRequestLocalStorage(): ThreadLocalData | undefined;
+/**
+ * Executes a callback within a request context with the given thread-local data.
+ * Used by middleware to set up the context for handlers.
+ * @Internal
+ * @param data - Thread-local data to establish
+ * @param callback - Function to execute within the context
+ * @returns Result of the callback
+ */
+export declare function runWithRequestTlsData<T>(data: ThreadLocalData, callback: () => Promise<T>): Promise<T>;

package/dist/esm/utils/conversion.utils.d.ts

@@ -0,0 +1,14 @@
+import { ApiResponse } from '../api.types';
+/**
+ * Converts JS timestamp or date to ISO 8601 format (without milliseconds).
+ * Example: "2012-07-20T01:19:13Z".
+ * @Internal
+ */
+export declare function toApiDateString(value: number | Date): string;
+/**
+ * Wraps the response into the correct API form.
+ * Add necessary fields, like 'requestId'.
+ * If the response is already in the correct form, returns it as-is.
+ * @Internal
+ */
+export declare function wrapAsApiResponse<T = unknown>(apiResponseOrResultValue: T | ApiResponse<T>): ApiResponse<T>;

package/dist/esm/utils/express.utils.d.ts

@@ -0,0 +1,7 @@
+import express from 'express';
+/** Shortcut for express.* types with no namespace: so the type can be found/imported by IDE. */
+export type ExpressRequest = express.Request;
+export type ExpressResponse = express.Response;
+export type ExpressNextFunction = express.NextFunction;
+export type ExpressApplication = express.Application;
+export type ExpressFunction = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fishka/express",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Express.js extension with built-in validation, and type safety",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

package/dist/cjs/http.types.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOO_MANY_REQUESTS_STATUS = exports.OK_STATUS = exports.NOT_FOUND_STATUS = exports.FORBIDDEN_STATUS = exports.UNAUTHORIZED_STATUS = exports.BAD_REQUEST_STATUS = exports.INTERNAL_ERROR_STATUS = void 0;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.INTERNAL_ERROR_STATUS = 500;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.BAD_REQUEST_STATUS = 400;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.UNAUTHORIZED_STATUS = 401;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.FORBIDDEN_STATUS = 403;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.NOT_FOUND_STATUS = 404;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.OK_STATUS = 200;
-/**
- * Common HTTP status codes as numbers.
- * @Internal
- */
-exports.TOO_MANY_REQUESTS_STATUS = 429;