@catbee/utils 0.0.4 → 0.0.6

package/build/esnext/servers/server.builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.builder.js","sourceRoot":"","sources":["../../../src/servers/server.builder.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { deepObjMerge } from '../utils/obj.utils';\nimport { ServerConfig } from '../types/server';\nimport { defaultServerConfig } from '../config';\nimport { isPort } from '../utils/validate.utils';\n\n/**\n * Builder class for creating and configuring an Express server configuration.\n *\n * This class provides a fluent interface to configure all aspects of the Express server\n * including security settings, middleware, routing, and more.\n *\n * @example\n * ```typescript\n * const serverConfig = new ServerConfigBuilder()\n *   .withPort(3000)\n *   .withHost('localhost')\n *   .enableCors()\n *   .enableHelmet()\n *   .build();\n * ```\n */\n\nexport const BUILD_MARKER = Symbol.for('catbee.express.server.build');\n\nexport class ServerConfigBuilder {\n  private config: Partial<ServerConfig> = {};\n\n  /**\n   * Validates that a port number is valid and usable.\n   *\n   * @private\n   * @param port - The port number to validate\n   * @throws {Error} If port is not an integer or is outside the valid range (1-65535)\n   */\n  private validatePort(port: number): void {\n    if (!isPort(port)) {\n      throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);\n    }\n  }\n\n  /**\n   * Sets the port the server will listen on.\n   *\n   * @param port - The port number (1-65535)\n   * @returns The builder instance for chaining\n   * @throws {Error} If port is invalid\n   * @default 3000 (can be overridden via PORT env variable)\n   *\n   * @example\n   * ```typescript\n   * builder.withPort(3000)\n   * ```\n   */\n  withPort(port: number): this {\n    this.validatePort(port);\n    this.config.port = port;\n    return this;\n  }\n\n  /**\n   * Sets the hostname the server will bind to.\n   *\n   * @param host - The hostname (e.g., 'localhost', '0.0.0.0', '127.0.0.1')\n   * @returns The builder instance for chaining\n   * @default '0.0.0.0' (can be overridden via HOST env variable)\n   *\n   * @example\n   * ```typescript\n   * builder.withHost('0.0.0.0') // Listen on all interfaces\n   * ```\n   */\n  withHost(host: string): this {\n    this.config.host = host;\n    return this;\n  }\n\n  /**\n   * Configures Cross-Origin Resource Sharing (CORS) for the server.\n   *\n   * @param opts - CORS options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (CORS is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable CORS with default options\n   * builder.withCors(true)\n   *\n   * // Configure CORS with specific options\n   * builder.withCors({\n   *   origin: ['https://example.com'],\n   *   methods: ['GET', 'POST']\n   * })\n   * ```\n   */\n  withCors(opts: ServerConfig['cors']): this {\n    this.config.cors = opts;\n    return this;\n  }\n\n  /**\n   * Enables CORS with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableCors(): this {\n    return this.withCors(true);\n  }\n\n  /**\n   * Disables CORS\n   *\n   * @returns The builder instance for chaining\n   */\n  disableCors(): this {\n    return this.withCors(false);\n  }\n\n  /**\n   * Configures the Helmet middleware for setting HTTP security headers.\n   *\n   * @param opts - Helmet options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (Helmet is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable Helmet with default settings\n   * builder.withHelmet(true)\n   *\n   * // Configure Helmet with specific options\n   * builder.withHelmet({\n   *   contentSecurityPolicy: false,\n   *   xssFilter: true\n   * })\n   * ```\n   */\n  withHelmet(opts: ServerConfig['helmet']): this {\n    this.config.helmet = opts;\n    return this;\n  }\n\n  /**\n   * Enables Helmet with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableHelmet(): this {\n    return this.withHelmet(true);\n  }\n\n  /**\n   * Disables Helmet\n   *\n   * @returns The builder instance for chaining\n   */\n  disableHelmet(): this {\n    return this.withHelmet(false);\n  }\n\n  /**\n   * Configures response compression middleware.\n   *\n   * @param opts - Compression options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (Compression is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable compression with default settings\n   * builder.withCompression(true)\n   *\n   * // Configure compression with specific options\n   * builder.withCompression({\n   *   level: 6,\n   *   threshold: 1024\n   * })\n   * ```\n   */\n  withCompression(opts: ServerConfig['compression']): this {\n    this.config.compression = opts;\n    return this;\n  }\n\n  /**\n   * Enables compression with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableCompression(): this {\n    return this.withCompression(true);\n  }\n\n  /**\n   * Disables compression\n   *\n   * @returns The builder instance for chaining\n   */\n  disableCompression(): this {\n    return this.withCompression(false);\n  }\n\n  /**\n   * Configures rate limiting to protect against brute-force attacks.\n   *\n   * @param opts - Rate limit configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, windowMs: 15 * 60 * 1000, max: 100, message: 'Too many requests', standardHeaders: true, legacyHeaders: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withRateLimit({\n   *   enable: true,\n   *   windowMs: 15 * 60 * 1000, // 15 minutes\n   *   max: 100 // limit each IP to 100 requests per windowMs\n   * })\n   * ```\n   */\n  withRateLimit(opts: Partial<ServerConfig['rateLimit']>): this {\n    this.mergeConfig('rateLimit', opts as NonNullable<ServerConfig['rateLimit']>);\n    return this;\n  }\n\n  /**\n   * Enables rate limiting with default or custom settings\n   *\n   * @param opts - Optional rate limit configuration (max requests, window, etc.)\n   * @returns The builder instance for chaining\n   */\n  enableRateLimit(opts: Omit<Partial<NonNullable<ServerConfig['rateLimit']>>, 'enable'> = {}): this {\n    return this.setEnabled('rateLimit', true, opts);\n  }\n\n  /**\n   * Disables rate limiting\n   *\n   * @returns The builder instance for chaining\n   */\n  disableRateLimit(): this {\n    return this.setEnabled('rateLimit', false);\n  }\n\n  /**\n   * Configures HTTP request logging middleware.\n   *\n   * @param opts - Request logging configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: true in dev/false in prod, ignorePaths: ['/healthz', '/favicon.ico', '/metrics', '/docs', '/.well-known'], skipNotFoundRoutes: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withRequestLogging({\n   *   enable: true,\n   *   ignorePaths: ['/health', '/metrics'],\n   *   skipNotFoundRoutes: true\n   * })\n   * ```\n   */\n  withRequestLogging(opts: Partial<NonNullable<ServerConfig['requestLogging']>>): this {\n    this.mergeConfig('requestLogging', opts as NonNullable<ServerConfig['requestLogging']>);\n    return this;\n  }\n\n  /**\n   * Enables request logging with default or custom settings\n   *\n   * @param opts - Optional request logging configuration\n   * @returns The builder instance for chaining\n   */\n  enableRequestLogging(opts: Omit<Partial<NonNullable<ServerConfig['requestLogging']>>, 'enable'> = {}): this {\n    return this.setEnabled('requestLogging', true, opts);\n  }\n\n  /**\n   * Disables request logging\n   *\n   * @returns The builder instance for chaining\n   */\n  disableRequestLogging(): this {\n    return this.setEnabled('requestLogging', false);\n  }\n\n  /**\n   * Configures server metrics collection and endpoints.\n   *\n   * @param opts - Metrics configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, path: '/metrics', withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withMetrics({\n   *   enable: true,\n   *   path: '/metrics'\n   * })\n   * ```\n   */\n  withMetrics(opts: Partial<NonNullable<ServerConfig['metrics']>>): this {\n    this.mergeConfig('metrics', opts as NonNullable<ServerConfig['metrics']>);\n    return this;\n  }\n\n  /**\n   * Enables Prometheus metrics collection and endpoint\n   *\n   * @param opts - Optional metrics configuration\n   * @returns The builder instance for chaining\n   */\n  enableMetrics(opts: Omit<Partial<NonNullable<ServerConfig['metrics']>>, 'enable'> = {}): this {\n    return this.setEnabled('metrics', true, opts);\n  }\n\n  /**\n   * Disables Prometheus metrics\n   *\n   * @returns The builder instance for chaining\n   */\n  disableMetrics(): this {\n    return this.setEnabled('metrics', false);\n  }\n\n  /**\n   * Configures server health check endpoint.\n   *\n   * @param opts - Health check configuration options\n   * @returns The builder instance for chaining\n   * @default { path: '/healthz', detailed: true, withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withHealthCheck({\n   *   path: '/health',\n   *   detailed: true\n   * })\n   * ```\n   */\n  withHealthCheck(opts: Partial<NonNullable<ServerConfig['healthCheck']>>): this {\n    this.mergeConfig('healthCheck', opts as NonNullable<ServerConfig['healthCheck']>);\n    return this;\n  }\n\n  /**\n   * Configures OpenAPI/Swagger documentation for the API.\n   *\n   * @param opts - OpenAPI configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, mountPath: '/docs', verbose: false, withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withOpenApi({\n   *   enable: true,\n   *   path: '/api-docs',\n   *   filePath: './openapi.yaml'\n   * })\n   * ```\n   */\n  withOpenApi(opts: Partial<NonNullable<ServerConfig['openApi']>>): this {\n    this.mergeConfig('openApi', opts as NonNullable<ServerConfig['openApi']>);\n    return this;\n  }\n\n  /**\n   * Enables OpenAPI documentation with required file path\n   *\n   * @param filePath - Path to OpenAPI specification file (required)\n   * @param opts - Optional OpenAPI configuration\n   * @returns The builder instance for chaining\n   */\n  enableOpenApi(\n    filePath: string,\n    opts: Omit<Partial<NonNullable<ServerConfig['openApi']>>, 'enable' | 'filePath'> = {}\n  ): this {\n    this.setEnabled('openApi', true, { filePath, ...opts });\n    return this;\n  }\n\n  /**\n   * Disables OpenAPI documentation\n   *\n   * @returns The builder instance for chaining\n   */\n  disableOpenApi(): this {\n    return this.setEnabled('openApi', false);\n  }\n\n  /**\n   * Configures the server as a microservice with versioning.\n   *\n   * @param opts - Microservice configuration options including app name and service version\n   * @returns The builder instance for chaining\n   * @default { isMicroservice: false, appName: 'express_app' }\n   *\n   * @example\n   * ```typescript\n   * builder.withMicroService({\n   *   appName: 'user-service',\n   *   serviceVersion: {\n   *     enable: true,\n   *     version: '1.2.3'\n   *   }\n   * })\n   * ```\n   */\n  withMicroService(opts: {\n    appName: NonNullable<ServerConfig['appName']>;\n    serviceVersion: Partial<NonNullable<ServerConfig['serviceVersion']>>;\n  }): this {\n    this.config.isMicroservice = true;\n    this.config.appName = opts.appName;\n\n    this.mergeConfig('serviceVersion', opts.serviceVersion as NonNullable<ServerConfig['serviceVersion']>);\n    return this;\n  }\n\n  /**\n   * Configures the trust proxy settings to determine if X-Forwarded-* headers should be trusted.\n   *\n   * @param opts - Trust proxy configuration options\n   * @returns The builder instance for chaining\n   * @default false\n   *\n   * @example\n   * ```typescript\n   * // Trust proxy headers (useful when behind a load balancer)\n   * builder.withTrustProxy(true)\n   * ```\n   */\n  withTrustProxy(opts: NonNullable<ServerConfig['trustProxy']>): this {\n    this.config.trustProxy = opts;\n    return this;\n  }\n\n  /**\n   * Configures the request ID middleware for tracing requests across services.\n   *\n   * @param opts - Request ID configuration options\n   * @returns The builder instance for chaining\n   * @default { headerName: 'x-request-id', exposeHeader: true }\n   *\n   * @example\n   * ```typescript\n   * builder.withRequestId({\n   *   headerName: 'X-Request-Id',\n   *   generator: () => crypto.randomUUID()\n   * })\n   * ```\n   */\n  withRequestId(opts: Partial<NonNullable<ServerConfig['requestId']>>): this {\n    this.mergeConfig('requestId', opts as NonNullable<ServerConfig['requestId']>);\n    return this;\n  }\n\n  /**\n   * Configures the response time middleware for measuring request processing times.\n   *\n   * @param opts - Response time configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, addHeader: true, logOnComplete: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withResponseTime({\n   *   enable: true,\n   *   addHeader: true,\n   *   logOnComplete: true\n   * })\n   * ```\n   */\n  withResponseTime(opts: Partial<NonNullable<ServerConfig['responseTime']>>): this {\n    this.mergeConfig('responseTime', opts as NonNullable<ServerConfig['responseTime']>);\n    return this;\n  }\n\n  /**\n   * Enables response time tracking with default or custom settings\n   *\n   * @param opts - Optional response time configuration\n   * @returns The builder instance for chaining\n   */\n  enableResponseTime(opts: Omit<Partial<NonNullable<ServerConfig['responseTime']>>, 'enable'> = {}): this {\n    this.setEnabled('responseTime', true, opts);\n    return this;\n  }\n\n  /**\n   * Disables response time tracking\n   *\n   * @returns The builder instance for chaining\n   */\n  disableResponseTime(): this {\n    return this.setEnabled('responseTime', false);\n  }\n\n  /**\n   * Configures the body parser middleware options for parsing request bodies.\n   *\n   * @param opts - Body parser configuration options\n   * @returns The builder instance for chaining\n   * @default { json: { limit: '1mb' }, urlencoded: { extended: true, limit: '1mb' } }\n   *\n   * @example\n   * ```typescript\n   * builder.withBodyParser({\n   *   json: {\n   *     limit: '1mb'\n   *   },\n   *   urlencoded: {\n   *     extended: true,\n   *     limit: '1mb'\n   *   }\n   * })\n   * ```\n   */\n  withBodyParser(opts: NonNullable<ServerConfig['bodyParser']>): this {\n    this.config.bodyParser = deepObjMerge({}, this.config.bodyParser ?? {}, opts);\n    return this;\n  }\n\n  /**\n   * Configures cookie parsing middleware.\n   *\n   * @param opts - Cookie parser options or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false\n   *\n   * @example\n   * ```typescript\n   * // Enable cookie parsing with default options\n   * builder.withCookies(true)\n   *\n   * // Enable cookie parsing with specific options\n   * builder.withCookies({\n   *   secret: 'your-secret-key',\n   *   secure: true\n   * })\n   * ```\n   */\n  withCookies(opts: ServerConfig['cookieParser']): this {\n    this.config.cookieParser = opts;\n    return this;\n  }\n\n  /**\n   * Configures the logger used by the server.\n   *\n   * @param opts - Logger configuration options\n   * @returns The builder instance for chaining\n   * @default { name: 'express_app', level: 'info', prettyPrint: true in dev, singleLine: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withLogger({\n   *   level: 'info',\n   *   prettyPrint: true,\n   *   singleLine: false\n   * })\n   * ```\n   */\n  withLogger(opts: Partial<NonNullable<ServerConfig['logger']>>): this {\n    this.mergeConfig('logger', opts as NonNullable<ServerConfig['logger']>);\n    return this;\n  }\n\n  /**\n   * Adds a static folder to serve files from.\n   *\n   * @param folder - Static folder configuration\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withStaticFolder({\n   *   path: '/assets',\n   *   directory: './public',\n   *   options: { maxAge: '1d' }\n   * })\n   * ```\n   */\n  withStaticFolder(folder: NonNullable<ServerConfig['staticFolders']>[number]): this {\n    if (!folder.path) throw new Error('Static folder requires a path');\n    const folders = [...(this.config.staticFolders ?? []), folder];\n    this.config.staticFolders = Array.from(new Map(folders.map(f => [f.path, f])).values());\n    return this;\n  }\n\n  /**\n   * Sets global headers to be included in all responses.\n   *\n   * @param headers - Object containing header name/value pairs or functions that return values\n   * @returns The builder instance for chaining\n   * @default {}\n   *\n   * @example\n   * ```typescript\n   * builder.withGlobalHeaders({\n   *   'X-Powered-By': 'Catbee',\n   *   'Server-Time': () => new Date().toISOString()\n   * })\n   * ```\n   */\n  withGlobalHeaders(headers: NonNullable<ServerConfig['globalHeaders']>): this {\n    this.mergeConfig('globalHeaders', headers);\n    return this;\n  }\n\n  /**\n   * Sets a global prefix for all routes.\n   *\n   * @param prefix - The prefix to prepend to all routes (e.g., '/api/v1')\n   * @returns The builder instance for chaining\n   * @default '/'\n   *\n   * @example\n   * ```typescript\n   * builder.withGlobalPrefix('/api/v1')\n   * ```\n   */\n  withGlobalPrefix(prefix: string): this {\n    this.config.globalPrefix = prefix;\n    return this;\n  }\n\n  /**\n   * Applies custom configuration overrides directly.\n   *\n   * @param overrides - Custom configuration options to merge\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withCustom({\n   *   port: 8080,\n   *   customMiddleware: myMiddlewareFunction\n   * })\n   * ```\n   */\n  withCustom(overrides: Partial<ServerConfig>): this {\n    this.config = deepObjMerge({}, this.config, overrides);\n    return this;\n  }\n\n  /**\n   * Configures HTTPS server options.\n   *\n   * @param opts - HTTPS configuration (key, cert, ca, passphrase, etc.)\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withHttps({\n   *   key: './localhost-key.pem',\n   *   cert: './localhost-cert.pem'\n   * })\n   * ```\n   */\n  withHttps(opts: NonNullable<ServerConfig['https']>): this {\n    this.config.https = opts;\n    return this;\n  }\n\n  /**\n   * Builds and returns the final server configuration.\n   *\n   * This method merges the user-specified configuration with default values,\n   * ensures all sections with 'enable' flags are properly structured, and\n   * produces the final configuration to be used by the server.\n   *\n   * @returns The complete ServerConfig object\n   *\n   * @example\n   * ```typescript\n   * const config = new ServerConfigBuilder()\n   *   .withPort(3000)\n   *   .withHost('localhost')\n   *   .withCors(true)\n   *   .build();\n   * ```\n   */\n  build() {\n    const config = deepObjMerge({}, defaultServerConfig, this.config) as ServerConfig;\n\n    // Common validation\n    if (config.openApi?.enable && !config.openApi.filePath) {\n      throw new Error('OpenAPI is enabled but no filePath is specified');\n    }\n\n    return Object.freeze({\n      ...config,\n      [BUILD_MARKER]: true\n    });\n  }\n\n  private mergeConfig<K extends keyof ServerConfig>(key: K, value: Partial<NonNullable<ServerConfig[K]>>): void {\n    const current =\n      typeof this.config[key] === 'object' && this.config[key] !== null\n        ? (this.config[key] as NonNullable<ServerConfig[K]>)\n        : {};\n    this.config[key] = deepObjMerge({}, current, value) as NonNullable<ServerConfig[K]>;\n  }\n\n  private setEnabled<K extends keyof ServerConfig>(\n    key: K,\n    enable: boolean,\n    overrides: Partial<NonNullable<ServerConfig[K]>> = {}\n  ): this {\n    this.mergeConfig(key, { ...overrides, enable });\n    return this;\n  }\n}\n"]}

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

@@ -0,0 +1,256 @@
+import express, { Express, Router } from 'express';
+import http from 'http';
+import https from 'https';
+import client from 'prom-client';
+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[]): void;
+    /**
+     * Set an externally created base router.
+     * This will override the internal rootRouter.
+     */
+    setBaseRouter(router: Router): void;
+    /**
+     * 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(): 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;
+}
+//# sourceMappingURL=server.d.ts.map