@catbee/utils 0.0.8-rc.3 → 1.0.1

package/build/esm/servers/server.d.ts

@@ -1,255 +0,0 @@
-import express, { Express, Router } from 'express';
-import http from 'http';
-import https from 'https';
-import { ServerConfig, ServerHooks } from '../types/server';
-/**
- * Production-ready Express server with enterprise features.
- *
- * Core Features:
- * - Security: Helmet, CORS, rate limiting, timeouts
- * - Monitoring: Request logs, metrics, health checks
- * - Performance: Compression, caching, static files
- * - Reliability: Graceful shutdown, error handling
- * - Developer UX: OpenAPI docs, debugging tools
- * - Extensibility: Hooks, middleware, custom routes
- *
- * Designed for microservices and production workloads.
- * Includes K8s readiness probes and zero-downtime support.
- */
-export declare class ExpressServer {
-    /** Prometheus client registry for metrics collection */
-    private register;
-    /** HTTP server instance (null when not running) */
-    protected server: http.Server | https.Server | null;
-    /** Merged configuration with defaults applied */
-    protected config: ServerConfig;
-    /** User-defined lifecycle hooks */
-    protected hooks: ServerHooks;
-    /** Global API prefix (from config) */
-    protected globalPrefix: string;
-    /** Internal fallback router */
-    private rootRouter;
-    /** User-supplied router */
-    private externalRouter?;
-    /** Internal Express app instance */
-    private app;
-    /** Set of active WebSocket connections */
-    private connections;
-    /** Flag indicating if the server is shutting down */
-    private isShuttingDown;
-    /**
-     * Collection of registered health check functions.
-     * These are executed when the health check endpoint is accessed.
-     */
-    private healthChecks;
-    /** Prometheus metrics for monitoring */
-    private requestCounter?;
-    private routeTimings?;
-    private requestSizes?;
-    private clientIPs?;
-    /** Promise that resolves when initialization (middleware + routes) is complete */
-    private initPromise;
-    /**
-     * Initializes server with intelligent defaults and security best practices.
-     * All settings can be customized via config and hooks.
-     *
-     * Default Security:
-     * - Secure headers (Helmet)
-     * - Rate limiting
-     * - Request timeouts
-     * - Body size limits
-     * - CORS protection
-     *
-     * Default Monitoring:
-     * - Request/Response logging
-     * - Prometheus metrics
-     * - Health checks
-     * - Request tracing
-     */
-    constructor(config: Partial<ServerConfig>, hooks?: ServerHooks);
-    /**
-     * Execute a lifecycle hook safely with comprehensive error handling.
-     * Prevents hook failures from crashing the server while logging issues.
-     *
-     * @param hook Name of the lifecycle hook to execute
-     * @param args Arguments to pass to the hook function
-     */
-    private runHook;
-    /**
-     * Initialize the Express server with middleware and routes.
-     */
-    private initialize;
-    /**
-     * Configure and register all middlewares in the optimal order.
-     *
-     * Middleware Order (CRITICAL - don't change without understanding implications):
-     * 1.  Basic server configuration (trust proxy, x-powered-by)
-     * 2.  Request ID generation (for tracing)
-     * 3.  Request context setup (for logging correlation)
-     * 4.  Timeout protection (prevents hanging requests)
-     * 5.  Response time tracking (for performance monitoring)
-     * 6.  Request logging (after ID/context setup)
-     * 7.  Custom request hooks
-     * 8.  Security middleware (rate limiting, CORS, Helmet)
-     * 9.  Response compression
-     * 10. Static file serving
-     * 11. Request parsing (body parsing, cookies)
-     * 12. API documentation (OpenAPI)
-     * 13. Global headers
-     * 14. Custom response hooks
-     */
-    protected setupMiddleware(): Promise<void>;
-    /**
-     * Configure server routes and error handling.
-     * Sets up in following order:
-     *
-     * 1. Built-in routes (health, metrics)
-     * 2. Application routes
-     * 3. 404 handler
-     * 4. Error handler
-     */
-    protected setupRoutes(): Promise<void>;
-    /**
-     * Register a new health check function for monitoring service dependencies.
-     *
-     * Health checks are executed when the health endpoint is accessed and
-     * help determine if the service is ready to handle requests.
-     *
-     * Examples:
-     * - Database connectivity
-     * - External service availability
-     * - File system access
-     * - Memory/CPU usage checks
-     *
-     * @param name Unique identifier for the check (used in detailed responses)
-     * @param check Function returning boolean or Promise<boolean> indicating health
-     * @returns This instance for method chaining
-     */
-    registerHealthCheck(name: string, check: () => Promise<boolean> | boolean): this;
-    /**
-     * Get the underlying Express application instance.
-     * Use this for advanced Express features not exposed by this wrapper.
-     *
-     * @returns The raw Express app instance
-     */
-    getApp(): Express;
-    /**
-     * Get the active HTTP/HTTPS server instance.
-     * Returns null if the server is not currently running.
-     *
-     * @returns The HTTP/HTTPS server instance or null
-     */
-    getServer(): http.Server | https.Server | null;
-    /**
-     * Start the HTTP server and begin listening for requests.
-     *
-     * This method:
-     * - Executes beforeStart hooks
-     * - Binds to the configured host/port
-     * - Sets up error handling for startup failures
-     * - Executes afterStart hooks on success
-     * - Logs startup information
-     *
-     * @returns Promise resolving to the running HTTP server instance
-     * @throws Error if server fails to start or port is already in use
-     */
-    start(): Promise<http.Server | https.Server>;
-    /**
-     * Stop the HTTP server gracefully.
-     *
-     * This method:
-     * - Executes beforeStop hooks
-     * - Stops accepting new connections
-     * - Waits for existing connections to finish
-     * - Closes the server
-     * - Executes afterStop hooks
-     * - Logs shutdown information
-     *
-     * Graceful shutdown ensures:
-     * - No requests are dropped
-     * - Resources are properly cleaned up
-     * - Monitoring systems are notified
-     */
-    stop(force?: boolean): Promise<void>;
-    /**
-     * Enable graceful shutdown on OS signals for production deployment.
-     *
-     * This is essential for:
-     * - Container orchestration (Docker, Kubernetes)
-     * - Process managers (PM2, systemd)
-     * - Load balancer health checks
-     * - Zero-downtime deployments
-     *
-     * @param signals Array of process signals to listen for (default: SIGINT, SIGTERM)
-     */
-    enableGracefulShutdown(signals?: NodeJS.Signals[]): this;
-    /**
-     * Set an externally created base router.
-     * This will override the internal rootRouter.
-     */
-    setBaseRouter(router: Router): this;
-    /**
-     * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).
-     */
-    createRouter(prefix?: string): Router;
-    /**
-     * Register a new route handler with support for multiple HTTP methods.
-     * The route is automatically registered under the globalPrefix if set.
-     *
-     * @param methods Array of HTTP methods (get, post, put, delete, etc.)
-     * @param path Route path with Express path patterns support
-     * @param handlers One or more Express request handlers (middleware + final handler)
-     * @returns This instance for method chaining
-     */
-    registerRoute(methods: Array<keyof Pick<Express, 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head'>>, path: string, ...handlers: Array<express.RequestHandler>): this;
-    /**
-     * Register custom middleware with optional path restriction.
-     *
-     * Use this for:
-     * - Adding authentication to specific routes
-     * - Custom logging or validation
-     * - Request transformation
-     * - Third-party middleware integration
-     *
-     * @param path Optional path prefix or middleware function if no path
-     * @param middleware Middleware handler (required if path is provided)
-     * @returns This instance for method chaining
-     */
-    registerMiddleware(path: string | express.RequestHandler, middleware?: express.RequestHandler): this;
-    /**
-     * Register one or more middleware functions to be applied globally.
-     * This is a simpler alternative to registerMiddleware when you just want
-     * to add middleware without path restrictions.
-     *
-     * @param middlewares One or more Express middleware functions
-     * @returns This instance for method chaining
-     */
-    useMiddleware(...middlewares: express.RequestHandler[]): this;
-    /**
-     * Get Prometheus registry (to add custom counters/histograms)
-     *
-     * @return {*}  {client.Registry}
-     */
-    getMetricsRegistry(): typeof import("prom-client").Registry;
-    /**
-     * Get server configuration
-     *
-     * @return {*}  {ServerConfig}
-     */
-    getConfig(): ServerConfig;
-    /**
-     * Wait until server initialization (middleware + routes) has completed.
-     * Useful for integration tests that inspect app before starting.
-     */
-    waitUntilReady(): Promise<void>;
-    private normalizePath;
-    private normalizeRouteForMetrics;
-    /**
-     * Destroy all active connections (gracefully if possible).
-     * If a connection does not close cleanly, it will be force-destroyed.
-     */
-    private destroyConnections;
-    private validateHttpsFiles;
-    private static isBuiltServerConfig;
-    private static optionalRequire;
-}