@iprokit/service/lib/http/server.d.ts

Powering distributed systems with simplicity and speed.

/**
 * @iProKit/Service
 * Copyright (c) 2019-2025 Rutvik Katuri / iProTechs
 * SPDX-License-Identifier: Apache-2.0
 */
/// <reference types="node" />
/// <reference types="node" />
import http from 'http';
import { ParsedUrlQuery } from 'querystring';
import { Method, RequestHeaders, ResponseHeaders } from './definitions';
/**
 * `Server` binds to an IP address and port number, listening for incoming HTTP client connections.
 * Manages registered routes to handle various HTTP methods and dispatches requests to the appropriate route handlers.
 */
export default class Server extends http.Server implements IServer {
    /**
     * Unique identifier of the server.
     */
    readonly identifier: string;
    /**
     * Routes registered on the server.
     */
    readonly routes: Array<Route>;
    /**
     * Creates an instance of HTTP `Server`.
     *
     * @param identifier unique identifier of the server.
     */
    constructor(identifier: string);
    /**
     * [Method?] is handled by `dispatch` function.
     */
    private onRequest;
    /**
     * Recursively loop through the routes to find and execute its handler.
     *
     * @param routeIndex index of the current route being processed.
     * @param stackIndex index of the current stack being processed.
     * @param handlerIndex index of the current handler being processed.
     * @param routes routes to be processed.
     * @param request incoming request.
     * @param response outgoing response.
     * @param unwind function called once the processed routes unwind.
     */
    private dispatch;
    get: (path: string, ...handlers: Array<RequestHandler>) => this;
    post: (path: string, ...handlers: Array<RequestHandler>) => this;
    put: (path: string, ...handlers: Array<RequestHandler>) => this;
    patch: (path: string, ...handlers: Array<RequestHandler>) => this;
    delete: (path: string, ...handlers: Array<RequestHandler>) => this;
    all: (path: string, ...handlers: Array<RequestHandler>) => this;
    mount: (path: string, ...routers: Array<IRouter>) => this;
}
/**
 * Interface for the HTTP `Server`.
 */
export interface IServer extends IRouter {
}
/**
 * Registers routes that handle HTTP requests.
 * Once mounted, HTTP requests are dispatched to the appropriate registered routes.
 */
export declare class Router implements IRouter {
    /**
     * Routes registered.
     */
    readonly routes: Array<Route>;
    /**
     * Creates an instance of `Router`.
     */
    constructor();
    get: (path: string, ...handlers: Array<RequestHandler>) => this;
    post: (path: string, ...handlers: Array<RequestHandler>) => this;
    put: (path: string, ...handlers: Array<RequestHandler>) => this;
    patch: (path: string, ...handlers: Array<RequestHandler>) => this;
    delete: (path: string, ...handlers: Array<RequestHandler>) => this;
    all: (path: string, ...handlers: Array<RequestHandler>) => this;
    mount: (path: string, ...routers: Array<IRouter>) => this;
    /**
     * Applies properties of `IRouter` interface to the provided instance,
     * enabling registration of routes.
     *
     * @param instance instance to which the `IRouter` properties are applied.
     */
    static applyProperties<I extends IRouter>(instance: I): void;
    /**
     * Registers an individual HTTP endpoint for a specific HTTP method.
     *
     * @param instance router instance where the endpoint will be registered.
     * @param method HTTP method for the endpoint.
     */
    private static registerEndpoint;
    /**
     * Registers a stack of routes.
     *
     * @param instance router instance where the stack will be registered.
     */
    private static registerStack;
    /**
     * Transforms the path by removing the trailing slash, except for the root path.
     *
     * @param path path containing trailing slash.
     */
    private static transformTrailingSlash;
    /**
     * Transforms wildcard characters (*) in the path to regex-compatible format.
     *
     * @param path path containing wildcards.
     */
    private static transformWildcard;
    /**
     * Transforms optional parameters in the path to regex-compatible format.
     *
     * @param path path containing required parameters.
     */
    private static transformRequiredParams;
    /**
     * Transforms required parameters in the path to regex-compatible format.
     *
     * @param path path containing optional parameters.
     */
    private static transformOptionalParams;
}
/**
 * Interface for the `Router`.
 */
export interface IRouter {
    /**
     * Routes registered.
     */
    routes: Array<Route>;
    /**
     * Registers a route for handling GET requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    get: (path: string, ...handlers: Array<RequestHandler>) => this;
    /**
     * Registers a route for handling POST requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    post: (path: string, ...handlers: Array<RequestHandler>) => this;
    /**
     * Registers a route for handling PUT requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    put: (path: string, ...handlers: Array<RequestHandler>) => this;
    /**
     * Registers a route for handling PATCH requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    patch: (path: string, ...handlers: Array<RequestHandler>) => this;
    /**
     * Registers a route for handling DELETE requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    delete: (path: string, ...handlers: Array<RequestHandler>) => this;
    /**
     * Registers a route for handling ALL requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    all: (path: string, ...handlers: Array<RequestHandler>) => this;
    /**
     * Mounts multiple routers.
     *
     * @param path path pattern.
     * @param routers routers to mount.
     */
    mount: (path: string, ...routers: Array<IRouter>) => this;
}
/**
 * Union of `Stack` and `Endpoint`.
 */
export type Route = Stack | Endpoint;
/**
 * Represents a group of routes.
 */
export interface Stack {
    /**
     * Path pattern of the stack.
     */
    path: string;
    /**
     * Compiled regular expression to match path pattern of the stack.
     */
    regExp: RegExp;
    /**
     * Routes registered in the stack.
     */
    routes: Array<Array<Route>>;
}
/**
 * Represents a endpoint.
 */
export interface Endpoint {
    /**
     * HTTP method of the endpoint.
     */
    method: Method;
    /**
     * Path pattern of the endpoint.
     */
    path: string;
    /**
     * Compiled regular expression to match path pattern of the endpoint.
     */
    regExp: RegExp;
    /**
     * List of parameter names extracted from the endpoint's path pattern.
     */
    paramKeys: Array<string>;
    /**
     * Request handler functions of the endpoint.
     */
    handlers: Array<RequestHandler>;
}
/**
 * Request handler.
 */
export type RequestHandler = (request: ServerRequest, response: ServerResponse, next: NextFunction) => void;
/**
 * Next function.
 */
export type NextFunction = () => void;
/**
 * Represents an HTTP server request.
 */
export interface ServerRequest extends http.IncomingMessage {
    /**
     * Request headers.
     */
    headers: RequestHeaders;
    /**
     * Path portion of the URL.
     */
    path: string;
    /**
     * Parameters extracted from the URL.
     */
    params: Record<string, string | undefined>;
    /**
     * Query parameters.
     */
    query: ParsedUrlQuery;
    /**
     * Matched endpoint.
     */
    endpoint: Endpoint;
}
/**
 * Represents an HTTP server response.
 */
export interface ServerResponse extends http.ServerResponse {
    /**
     * Response headers.
     */
    headers: ResponseHeaders;
}