@fishka/express 0.9.5 → 0.9.6

package/dist/cjs/api.types.d.ts

@@ -0,0 +1,51 @@
+import { ValueAssertion } from '@fishka/assertions';
+export type UrlTokensValidator = Record<string, ValueAssertion<string>>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(status: number, message: string, details?: Record<string, unknown> | undefined);
+}
+export interface ApiResponse<ResponseEntity = unknown> {
+    /** Result of the call. A single entity for non-paginated ${by-id} requests or an array for list queries. */
+    result: ResponseEntity;
+    /**
+     * Unique ID of the request.
+     * Automatically added to every API response.
+     * May be passed via 'x-request-id' header from client.
+     */
+    requestId?: string;
+    /**
+     * Response status code. Same as HTTP response status.
+     * Default: 200 for successful responses or 500 for internal server errors.
+     */
+    status?: number;
+    /** Optional error message. */
+    error?: string;
+    /** Optional structured error details. */
+    details?: Record<string, unknown>;
+    /** Offset in the result set. Save as 'offset' query parameter. */
+    offset?: number;
+    /** Number of results requested. Same as 'limit' query parameter. */
+    limit?: number;
+}
+/** Converts an API response value into a standardized ApiResponse structure. */
+export declare function response<T = unknown>(result: T): ApiResponse<T>;
+/** Globally identified URL (path or query) parameter info. */
+export interface UrlParameterInfo {
+    /** Optional global validator for this parameter. */
+    validator?: ValueAssertion<string>;
+    /** Description for documentation. */
+    description?: string;
+}
+/**
+ * Default documentation and validation for URL parameters.
+ * @Internal
+ */
+export declare const URL_PARAMETER_INFO: Record<string, UrlParameterInfo>;
+/** Registers a new URL parameter. */
+export declare function registerUrlParameter(name: string, info: UrlParameterInfo): void;
+/**
+ * Asserts that the value is a registered URL parameter name.
+ * @Internal
+ */
+export declare function assertUrlParameter(name: unknown): asserts name is string;

package/dist/cjs/auth/auth-strategy.d.ts

@@ -0,0 +1,42 @@
+import { ExpressRequest } from '../utils/express.utils';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Basic authentication strategy using username/password validation.
+ * Parses HTTP Basic Authorization header and validates credentials.
+ *
+ * Example usage:
+ * ```
+ * const strategy = new BasicAuthStrategy(
+ *   async (username, password) => {
+ *     const user = await db.users.findByUsername(username);
+ *     if (user && await bcrypt.compare(password, user.hash)) {
+ *       return user;
+ *     }
+ *     return null;
+ *   }
+ * );
+ * ```
+ */
+export declare class BasicAuthStrategy<User extends AuthUser = AuthUser> implements AuthStrategy<{
+    username: string;
+    password: string;
+}, User> {
+    private readonly verifyFn;
+    constructor(verifyFn: (username: string, password: string) => Promise<User | null>);
+    /**
+     * Extracts username and password from Basic auth header.
+     * Expected format: "Basic base64(username:password)"
+     * Returns undefined if header is missing or not Basic.
+     */
+    extractCredentials(req: ExpressRequest): {
+        username: string;
+        password: string;
+    } | undefined;
+    /**
+     * Validates the extracted credentials using the provided validation function.
+     */
+    validateCredentials({ username, password }: {
+        username: string;
+        password: string;
+    }): Promise<User>;
+}

package/dist/cjs/auth/auth.types.d.ts

@@ -0,0 +1,42 @@
+import { ExpressRequest } from '../utils/express.utils';
+/**
+ * Interface representing the authenticated user.
+ * Users of the library should use module augmentation to add fields to this interface.
+ *
+ * Example:
+ * ```ts
+ * declare module '@fishka/express' {
+ *   interface AuthUser {
+ *     id: string;
+ *     roles: string[];
+ *   }
+ * }
+ * ```
+ */
+export interface AuthUser {
+}
+/**
+ * Generic authentication strategy interface.
+ * Allows users to implement custom authentication logic.
+ *
+ * @template Credentials - The type of credentials extracted from the request
+ * @template User - The type of the authenticated user/entity
+ */
+export interface AuthStrategy<Credentials = unknown, User extends AuthUser = AuthUser> {
+    /**
+     * Extracts credentials from the Express request.
+     * This might parse Authorization headers, cookies, API keys, etc.
+     *
+     * @param req - Express request object
+     * @returns Extracted credentials, or undefined if not found/applicable
+     */
+    extractCredentials(req: ExpressRequest): Credentials | undefined;
+    /**
+     * Validates the extracted credentials and returns the authenticated user/entity.
+     *
+     * @param credentials - Credentials to validate
+     * @returns Authenticated user/entity
+     * @throws Error if credentials are invalid
+     */
+    validateCredentials(credentials: Credentials): Promise<User>;
+}

package/dist/cjs/auth/auth.utils.d.ts

@@ -0,0 +1,31 @@
+import { EndpointMiddleware, RequestContext } from '../router';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Creates a middleware that enforces authentication using the provided strategy.
+ * The authenticated user is stored in the context under the 'authUser' key.
+ *
+ * @template User - Type of the authenticated user
+ * @param strategy - Authentication strategy to use
+ * @param onSuccess - Optional callback to process authenticated user
+ * @returns a middleware that enforces authentication
+ */
+export declare function createAuthMiddleware<User extends AuthUser = AuthUser>(strategy: AuthStrategy<unknown, User>, onSuccess?: (user: User, context: RequestContext) => void): EndpointMiddleware;
+/**
+ * Extracts the authenticated user from the request context.
+ * Throws if the user is not present (i.e., authentication was not performed).
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user
+ * @throws Error if user is not found in context
+ */
+export declare function getAuthUser<User extends AuthUser = AuthUser>(context: RequestContext): User;
+/**
+ * Safely extracts the authenticated user from the request context.
+ * Returns undefined if the user is not present.
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user, or undefined if not found
+ */
+export declare function tryGetAuthUser<User extends AuthUser = AuthUser>(context: RequestContext): User | undefined;

package/dist/cjs/auth/bearer-auth-strategy.d.ts

@@ -0,0 +1,38 @@
+import { ExpressRequest } from '../utils/express.utils';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Bearer authentication strategy (commonly used for JWTs).
+ * Extracts the token from the 'Authorization: Bearer <token>' header.
+ *
+ * The validation logic is delegated to the `verifyFn`, which can:
+ * - Validate a JWT signature locally.
+ * - Call an external API/website to verify the token (Introspection/UserInfo).
+ *
+ * Example usage:
+ * ```ts
+ * const strategy = new BearerAuthStrategy(async (token) => {
+ *   // Call external website to validate
+ *   const response = await fetch('https://auth.example.com/verify', {
+ *     headers: { Authorization: `Bearer ${token}` }
+ *   });
+ *   if (!response.ok) return null;
+ *   return await response.json();
+ * });
+ * ```
+ */
+export declare class BearerAuthStrategy<User extends AuthUser = AuthUser> implements AuthStrategy<string, User> {
+    private readonly verifyFn;
+    /**
+     * @param verifyFn Function to validate the token. Returns the user if valid, or null if invalid.
+     */
+    constructor(verifyFn: (token: string) => Promise<User | null>);
+    /**
+     * Extracts the Bearer token from the Authorization header.
+     * Returns undefined if the header is missing or not a Bearer token.
+     */
+    extractCredentials(req: ExpressRequest): string | undefined;
+    /**
+     * Validates the extracted token using the provided verification function.
+     */
+    validateCredentials(token: string): Promise<User>;
+}

package/dist/cjs/config.d.ts

@@ -0,0 +1,23 @@
+export interface GlobalExpressApiConfig {
+    /**
+     * Whether to trust and use the request ID from the request header.
+     * If true, the middleware will look for 'x-request-id' and use it.
+     * If false, a new UUID will always be generated.
+     * Default: true
+     */
+    trustRequestIdHeader: boolean;
+}
+/**
+ * Configure global @fishka/express settings.
+ * @param config Partial configuration to merge with current settings
+ */
+export declare function configureExpressApi(config: Partial<GlobalExpressApiConfig>): void;
+/**
+ * Get current Express API configuration.
+ */
+export declare function getExpressApiConfig(): GlobalExpressApiConfig;
+/**
+ * Reset API configuration to defaults.
+ * Useful for testing.
+ */
+export declare function resetExpressApiConfig(): void;

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

@@ -0,0 +1,9 @@
+import { NextFunction } from 'express';
+import { ExpressFunction, ExpressRequest, ExpressResponse } from './utils/express.utils';
+/** Catches all kinds of unprocessed exceptions thrown from a single route. */
+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.
+ */
+export declare function catchAllMiddleware(error: unknown, _: ExpressRequest, res: ExpressResponse, next: NextFunction): Promise<void>;

package/dist/cjs/http.types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const INTERNAL_ERROR_STATUS = 500;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const BAD_REQUEST_STATUS = 400;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const UNAUTHORIZED_STATUS = 401;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const FORBIDDEN_STATUS = 403;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const NOT_FOUND_STATUS = 404;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const OK_STATUS = 200;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const TOO_MANY_REQUESTS_STATUS = 429;

package/dist/cjs/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.types';
+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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/dist/esm/api.types.d.ts

@@ -0,0 +1,51 @@
+import { ValueAssertion } from '@fishka/assertions';
+export type UrlTokensValidator = Record<string, ValueAssertion<string>>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(status: number, message: string, details?: Record<string, unknown> | undefined);
+}
+export interface ApiResponse<ResponseEntity = unknown> {
+    /** Result of the call. A single entity for non-paginated ${by-id} requests or an array for list queries. */
+    result: ResponseEntity;
+    /**
+     * Unique ID of the request.
+     * Automatically added to every API response.
+     * May be passed via 'x-request-id' header from client.
+     */
+    requestId?: string;
+    /**
+     * Response status code. Same as HTTP response status.
+     * Default: 200 for successful responses or 500 for internal server errors.
+     */
+    status?: number;
+    /** Optional error message. */
+    error?: string;
+    /** Optional structured error details. */
+    details?: Record<string, unknown>;
+    /** Offset in the result set. Save as 'offset' query parameter. */
+    offset?: number;
+    /** Number of results requested. Same as 'limit' query parameter. */
+    limit?: number;
+}
+/** Converts an API response value into a standardized ApiResponse structure. */
+export declare function response<T = unknown>(result: T): ApiResponse<T>;
+/** Globally identified URL (path or query) parameter info. */
+export interface UrlParameterInfo {
+    /** Optional global validator for this parameter. */
+    validator?: ValueAssertion<string>;
+    /** Description for documentation. */
+    description?: string;
+}
+/**
+ * Default documentation and validation for URL parameters.
+ * @Internal
+ */
+export declare const URL_PARAMETER_INFO: Record<string, UrlParameterInfo>;
+/** Registers a new URL parameter. */
+export declare function registerUrlParameter(name: string, info: UrlParameterInfo): void;
+/**
+ * Asserts that the value is a registered URL parameter name.
+ * @Internal
+ */
+export declare function assertUrlParameter(name: unknown): asserts name is string;

package/dist/esm/auth/auth-strategy.d.ts

@@ -0,0 +1,42 @@
+import { ExpressRequest } from '../utils/express.utils';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Basic authentication strategy using username/password validation.
+ * Parses HTTP Basic Authorization header and validates credentials.
+ *
+ * Example usage:
+ * ```
+ * const strategy = new BasicAuthStrategy(
+ *   async (username, password) => {
+ *     const user = await db.users.findByUsername(username);
+ *     if (user && await bcrypt.compare(password, user.hash)) {
+ *       return user;
+ *     }
+ *     return null;
+ *   }
+ * );
+ * ```
+ */
+export declare class BasicAuthStrategy<User extends AuthUser = AuthUser> implements AuthStrategy<{
+    username: string;
+    password: string;
+}, User> {
+    private readonly verifyFn;
+    constructor(verifyFn: (username: string, password: string) => Promise<User | null>);
+    /**
+     * Extracts username and password from Basic auth header.
+     * Expected format: "Basic base64(username:password)"
+     * Returns undefined if header is missing or not Basic.
+     */
+    extractCredentials(req: ExpressRequest): {
+        username: string;
+        password: string;
+    } | undefined;
+    /**
+     * Validates the extracted credentials using the provided validation function.
+     */
+    validateCredentials({ username, password }: {
+        username: string;
+        password: string;
+    }): Promise<User>;
+}

package/dist/esm/auth/auth.types.d.ts

@@ -0,0 +1,42 @@
+import { ExpressRequest } from '../utils/express.utils';
+/**
+ * Interface representing the authenticated user.
+ * Users of the library should use module augmentation to add fields to this interface.
+ *
+ * Example:
+ * ```ts
+ * declare module '@fishka/express' {
+ *   interface AuthUser {
+ *     id: string;
+ *     roles: string[];
+ *   }
+ * }
+ * ```
+ */
+export interface AuthUser {
+}
+/**
+ * Generic authentication strategy interface.
+ * Allows users to implement custom authentication logic.
+ *
+ * @template Credentials - The type of credentials extracted from the request
+ * @template User - The type of the authenticated user/entity
+ */
+export interface AuthStrategy<Credentials = unknown, User extends AuthUser = AuthUser> {
+    /**
+     * Extracts credentials from the Express request.
+     * This might parse Authorization headers, cookies, API keys, etc.
+     *
+     * @param req - Express request object
+     * @returns Extracted credentials, or undefined if not found/applicable
+     */
+    extractCredentials(req: ExpressRequest): Credentials | undefined;
+    /**
+     * Validates the extracted credentials and returns the authenticated user/entity.
+     *
+     * @param credentials - Credentials to validate
+     * @returns Authenticated user/entity
+     * @throws Error if credentials are invalid
+     */
+    validateCredentials(credentials: Credentials): Promise<User>;
+}

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

@@ -0,0 +1,31 @@
+import { EndpointMiddleware, RequestContext } from '../router';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Creates a middleware that enforces authentication using the provided strategy.
+ * The authenticated user is stored in the context under the 'authUser' key.
+ *
+ * @template User - Type of the authenticated user
+ * @param strategy - Authentication strategy to use
+ * @param onSuccess - Optional callback to process authenticated user
+ * @returns a middleware that enforces authentication
+ */
+export declare function createAuthMiddleware<User extends AuthUser = AuthUser>(strategy: AuthStrategy<unknown, User>, onSuccess?: (user: User, context: RequestContext) => void): EndpointMiddleware;
+/**
+ * Extracts the authenticated user from the request context.
+ * Throws if the user is not present (i.e., authentication was not performed).
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user
+ * @throws Error if user is not found in context
+ */
+export declare function getAuthUser<User extends AuthUser = AuthUser>(context: RequestContext): User;
+/**
+ * Safely extracts the authenticated user from the request context.
+ * Returns undefined if the user is not present.
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user, or undefined if not found
+ */
+export declare function tryGetAuthUser<User extends AuthUser = AuthUser>(context: RequestContext): User | undefined;

package/dist/esm/auth/bearer-auth-strategy.d.ts

@@ -0,0 +1,38 @@
+import { ExpressRequest } from '../utils/express.utils';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Bearer authentication strategy (commonly used for JWTs).
+ * Extracts the token from the 'Authorization: Bearer <token>' header.
+ *
+ * The validation logic is delegated to the `verifyFn`, which can:
+ * - Validate a JWT signature locally.
+ * - Call an external API/website to verify the token (Introspection/UserInfo).
+ *
+ * Example usage:
+ * ```ts
+ * const strategy = new BearerAuthStrategy(async (token) => {
+ *   // Call external website to validate
+ *   const response = await fetch('https://auth.example.com/verify', {
+ *     headers: { Authorization: `Bearer ${token}` }
+ *   });
+ *   if (!response.ok) return null;
+ *   return await response.json();
+ * });
+ * ```
+ */
+export declare class BearerAuthStrategy<User extends AuthUser = AuthUser> implements AuthStrategy<string, User> {
+    private readonly verifyFn;
+    /**
+     * @param verifyFn Function to validate the token. Returns the user if valid, or null if invalid.
+     */
+    constructor(verifyFn: (token: string) => Promise<User | null>);
+    /**
+     * Extracts the Bearer token from the Authorization header.
+     * Returns undefined if the header is missing or not a Bearer token.
+     */
+    extractCredentials(req: ExpressRequest): string | undefined;
+    /**
+     * Validates the extracted token using the provided verification function.
+     */
+    validateCredentials(token: string): Promise<User>;
+}

package/dist/esm/config.d.ts

@@ -0,0 +1,23 @@
+export interface GlobalExpressApiConfig {
+    /**
+     * Whether to trust and use the request ID from the request header.
+     * If true, the middleware will look for 'x-request-id' and use it.
+     * If false, a new UUID will always be generated.
+     * Default: true
+     */
+    trustRequestIdHeader: boolean;
+}
+/**
+ * Configure global @fishka/express settings.
+ * @param config Partial configuration to merge with current settings
+ */
+export declare function configureExpressApi(config: Partial<GlobalExpressApiConfig>): void;
+/**
+ * Get current Express API configuration.
+ */
+export declare function getExpressApiConfig(): GlobalExpressApiConfig;
+/**
+ * Reset API configuration to defaults.
+ * Useful for testing.
+ */
+export declare function resetExpressApiConfig(): void;

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

@@ -0,0 +1,9 @@
+import { NextFunction } from 'express';
+import { ExpressFunction, ExpressRequest, ExpressResponse } from './utils/express.utils';
+/** Catches all kinds of unprocessed exceptions thrown from a single route. */
+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.
+ */
+export declare function catchAllMiddleware(error: unknown, _: ExpressRequest, res: ExpressResponse, next: NextFunction): Promise<void>;

package/dist/esm/http.types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const INTERNAL_ERROR_STATUS = 500;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const BAD_REQUEST_STATUS = 400;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const UNAUTHORIZED_STATUS = 401;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const FORBIDDEN_STATUS = 403;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const NOT_FOUND_STATUS = 404;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const OK_STATUS = 200;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export declare const TOO_MANY_REQUESTS_STATUS = 429;

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.types';
+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/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/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.6",
   "description": "Express.js extension with built-in validation, and type safety",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",