@catbee/utils 0.0.8-rc.0 → 0.0.8-rc.2

package/build/esm/servers/server.js

@@ -21,78 +21,6 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
-    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (g && (g = 0, op[0] && (_ = 0)), _) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
-    }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
-    }
-    return ar;
-};
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 import express from 'express';
 import https from 'https';
 import { HttpStatusCodes } from '../utils/http-status-codes';
@@ -122,7 +50,39 @@ import { isPort } from '../utils/validate.utils';
  * Designed for microservices and production workloads.
  * Includes K8s readiness probes and zero-downtime support.
  */
-var ExpressServer = /** @class */ (function () {
+export class ExpressServer {
+    /** Prometheus client registry for metrics collection */
+    register = null;
+    /** HTTP server instance (null when not running) */
+    server = null;
+    /** Merged configuration with defaults applied */
+    config;
+    /** User-defined lifecycle hooks */
+    hooks;
+    /** Global API prefix (from config) */
+    globalPrefix;
+    /** Internal fallback router */
+    rootRouter;
+    /** User-supplied router */
+    externalRouter;
+    /** Internal Express app instance */
+    app;
+    /** Set of active WebSocket connections */
+    connections = new Set();
+    /** Flag indicating if the server is shutting down */
+    isShuttingDown = false;
+    /**
+     * Collection of registered health check functions.
+     * These are executed when the health check endpoint is accessed.
+     */
+    healthChecks = [];
+    /** Prometheus metrics for monitoring */
+    requestCounter;
+    routeTimings;
+    requestSizes;
+    clientIPs;
+    /** Promise that resolves when initialization (middleware + routes) is complete */
+    initPromise;
     /**
      * Initializes server with intelligent defaults and security best practices.
      * All settings can be customized via config and hooks.
@@ -140,23 +100,7 @@ var ExpressServer = /** @class */ (function () {
      * - Health checks
      * - Request tracing
      */
-    function ExpressServer(config, hooks) {
-        var _a;
-        if (hooks === void 0) { hooks = {}; }
-        var _b, _c, _d;
-        /** Prometheus client registry for metrics collection */
-        this.register = null;
-        /** HTTP server instance (null when not running) */
-        this.server = null;
-        /** Set of active WebSocket connections */
-        this.connections = new Set();
-        /** Flag indicating if the server is shutting down */
-        this.isShuttingDown = false;
-        /**
-         * Collection of registered health check functions.
-         * These are executed when the health check endpoint is accessed.
-         */
-        this.healthChecks = [];
+    constructor(config, hooks = {}) {
         if (ExpressServer.isBuiltServerConfig(config)) {
             this.config = config;
         }
@@ -165,13 +109,13 @@ var ExpressServer = /** @class */ (function () {
             this.config = deepObjMerge({}, defaultServerConfig, config);
         }
         if (!isPort(this.config.port)) {
-            getLogger().error("Port must be a valid number between 1 and 65535, got: ".concat(this.config.port));
+            getLogger().error(`Port must be a valid number between 1 and 65535, got: ${this.config.port}`);
             process.exit(1);
         }
         // Sanitize app name for metrics (replace invalid characters with underscore)
-        var safeAppName = (this.config.appName || 'express_app').toLowerCase().replace(/[^a-z0-9_]/g, '_');
-        if ((_b = this.config.metrics) === null || _b === void 0 ? void 0 : _b.enable) {
-            var client = ExpressServer.optionalRequire('prom-client');
+        const safeAppName = (this.config.appName || 'express_app').toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        if (this.config.metrics?.enable) {
+            const client = ExpressServer.optionalRequire('prom-client');
             if (!client) {
                 getLogger().error({ command: 'npm install prom-client' }, 'prom-client is required for metrics but not installed. Please add it to your dependencies');
                 process.exit(1);
@@ -179,27 +123,27 @@ var ExpressServer = /** @class */ (function () {
             this.register = new client.Registry();
             // Initialize Prometheus metrics with sanitized names
             this.requestCounter = new client.Counter({
-                name: "".concat(safeAppName, "_http_requests_total"),
+                name: `${safeAppName}_http_requests_total`,
                 help: 'Total HTTP requests',
                 labelNames: ['method', 'route', 'status'],
                 registers: [this.register]
             });
             this.routeTimings = new client.Histogram({
-                name: "".concat(safeAppName, "_http_request_duration_seconds"),
+                name: `${safeAppName}_http_request_duration_seconds`,
                 help: 'Duration of HTTP requests by route',
                 labelNames: ['method', 'route', 'status'],
                 buckets: [0.1, 0.3, 0.5, 0.7, 1, 3, 5, 7, 10],
                 registers: [this.register]
             });
             this.requestSizes = new client.Histogram({
-                name: "".concat(safeAppName, "_http_request_size_bytes"),
+                name: `${safeAppName}_http_request_size_bytes`,
                 help: 'Size of HTTP request bodies',
                 labelNames: ['method', 'route'],
                 buckets: [100, 1000, 10000, 100000, 1000000],
                 registers: [this.register]
             });
             this.clientIPs = new client.Counter({
-                name: "".concat(safeAppName, "_http_client_ip_total"),
+                name: `${safeAppName}_http_client_ip_total`,
                 help: 'Client IP request counter',
                 labelNames: ['ip', 'method'],
                 registers: [this.register]
@@ -207,15 +151,15 @@ var ExpressServer = /** @class */ (function () {
             // Default system metrics (CPU, memory, event loop lag, etc.)
             client.collectDefaultMetrics({
                 register: this.register,
-                prefix: "".concat(safeAppName, "_")
+                prefix: `${safeAppName}_`
             });
         }
         // Health checks
-        if ((_c = config.healthCheck) === null || _c === void 0 ? void 0 : _c.checks) {
-            (_a = this.healthChecks).push.apply(_a, __spreadArray([], __read(config.healthCheck.checks), false));
+        if (config.healthCheck?.checks) {
+            this.healthChecks.push(...config.healthCheck.checks);
         }
         // Set global prefix (normalize to empty string or "/prefix" without trailing slash)
-        this.globalPrefix = this.normalizePath((_d = this.config.globalPrefix) !== null && _d !== void 0 ? _d : '', false);
+        this.globalPrefix = this.normalizePath(this.config.globalPrefix ?? '', false);
         this.hooks = hooks;
         this.app = express();
         this.rootRouter = express.Router();
@@ -229,61 +173,27 @@ var ExpressServer = /** @class */ (function () {
      * @param hook Name of the lifecycle hook to execute
      * @param args Arguments to pass to the hook function
      */
-    ExpressServer.prototype.runHook = function (hook) {
-        var args = [];
-        for (var _i = 1; _i < arguments.length; _i++) {
-            args[_i - 1] = arguments[_i];
+    async runHook(hook, ...args) {
+        try {
+            const fn = this.hooks[hook];
+            if (fn)
+                await fn.apply(null, args);
         }
-        return __awaiter(this, void 0, void 0, function () {
-            var fn, err_1;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        _a.trys.push([0, 3, , 4]);
-                        fn = this.hooks[hook];
-                        if (!fn) return [3 /*break*/, 2];
-                        return [4 /*yield*/, fn.apply(null, args)];
-                    case 1:
-                        _a.sent();
-                        _a.label = 2;
-                    case 2: return [3 /*break*/, 4];
-                    case 3:
-                        err_1 = _a.sent();
-                        getLogger().error({ err: err_1, hook: hook }, "Error executing ".concat(hook, " hook:"));
-                        return [3 /*break*/, 4];
-                    case 4: return [2 /*return*/];
-                }
-            });
-        });
-    };
+        catch (err) {
+            getLogger().error({ err, hook }, `Error executing ${hook} hook:`);
+        }
+    }
     /**
      * Initialize the Express server with middleware and routes.
      */
-    ExpressServer.prototype.initialize = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.runHook('beforeInit', this)];
-                    case 1:
-                        _a.sent();
-                        // Set up middleware stack (order is critical)
-                        return [4 /*yield*/, this.setupMiddleware()];
-                    case 2:
-                        // Set up middleware stack (order is critical)
-                        _a.sent();
-                        // Set up default routes and error handling
-                        return [4 /*yield*/, this.setupRoutes()];
-                    case 3:
-                        // Set up default routes and error handling
-                        _a.sent();
-                        return [4 /*yield*/, this.runHook('afterInit', this)];
-                    case 4:
-                        _a.sent();
-                        return [2 /*return*/];
-                }
-            });
-        });
-    };
+    async initialize() {
+        await this.runHook('beforeInit', this);
+        // Set up middleware stack (order is critical)
+        await this.setupMiddleware();
+        // Set up default routes and error handling
+        await this.setupRoutes();
+        await this.runHook('afterInit', this);
+    }
     /**
      * Configure and register all middlewares in the optimal order.
      *
@@ -303,290 +213,260 @@ var ExpressServer = /** @class */ (function () {
      * 13. Global headers
      * 14. Custom response hooks
      */
-    ExpressServer.prototype.setupMiddleware = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var helmet, cors, rateLimit, compression, cookieParser, openApiMountPath, openApiFilePath, isOpenApiFilePathExists, apiReference, _a, _b, _c, _d, err_2;
-            var _e, _f;
-            var _this = this;
-            var _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x;
-            return __generator(this, function (_y) {
-                switch (_y.label) {
-                    case 0:
-                        if (!this.config.https) return [3 /*break*/, 2];
-                        return [4 /*yield*/, this.validateHttpsFiles()];
-                    case 1:
-                        _y.sent();
-                        _y.label = 2;
-                    case 2:
-                        // Basic middleware should be first
-                        this.app.disable('x-powered-by');
-                        if (this.config.trustProxy) {
-                            this.app.set('trust proxy', true);
-                        }
-                        // Request ID generation - must be first for proper tracing
-                        this.app.use(requestId({
-                            headerName: (_g = this.config.requestId) === null || _g === void 0 ? void 0 : _g.headerName,
-                            exposeHeader: (_h = this.config.requestId) === null || _h === void 0 ? void 0 : _h.exposeHeader,
-                            generator: (_j = this.config.requestId) === null || _j === void 0 ? void 0 : _j.generator
-                        }));
-                        // Request context setup for logging correlation
-                        this.app.use(setupRequestContext({
-                            headerName: (_k = this.config.requestId) === null || _k === void 0 ? void 0 : _k.headerName,
-                            autoLog: false
-                        }));
-                        // Early shutdown-awareness middleware (lets load balancers drain connections gracefully)
-                        this.app.use(function (_req, res, next) {
-                            if (_this.isShuttingDown) {
-                                res.setHeader('Connection', 'close');
-                                return res
-                                    .status(HttpStatusCodes.SERVICE_UNAVAILABLE)
-                                    .json(new ServiceUnavailableException('Server is shutting down'));
-                            }
-                            next();
-                            return;
-                        });
-                        // Security middleware should come early
-                        if (this.config.helmet) {
-                            helmet = ExpressServer.optionalRequire('helmet');
-                            if (!helmet) {
-                                getLogger().error({ command: 'npm install helmet' }, 'helmet is required but not installed. Please add it to your dependencies');
-                                process.exit(1);
-                            }
-                            if (typeof this.config.helmet === 'object') {
-                                this.app.use(helmet(this.config.helmet));
-                            }
-                            else {
-                                this.app.use(helmet());
-                            }
-                        }
-                        // CORS middleware should be early
-                        if (this.config.cors) {
-                            cors = ExpressServer.optionalRequire('cors');
-                            if (!cors) {
-                                getLogger().error({ command: 'npm install cors' }, 'cors is required but not installed. Please add it to your dependencies');
-                                process.exit(1);
-                            }
-                            this.app.use(cors(this.config.cors === true ? {} : this.config.cors));
-                        }
-                        // Global headers
-                        this.app.use(function (_req, res, next) {
-                            var _a, _b, _c, _d;
-                            if (_this.config.globalHeaders) {
-                                for (var key in _this.config.globalHeaders) {
-                                    var value = _this.config.globalHeaders[key];
-                                    res.setHeader(key, typeof value === 'function' ? value() : value);
-                                }
-                            }
-                            if (_this.config.isMicroservice) {
-                                res.setHeader('X-Microservice', _this.config.appName || 'express_app');
-                            }
-                            if ((_a = _this.config.serviceVersion) === null || _a === void 0 ? void 0 : _a.enable) {
-                                var version = typeof ((_b = _this.config.serviceVersion) === null || _b === void 0 ? void 0 : _b.version) === 'function'
-                                    ? _this.config.serviceVersion.version()
-                                    : (_c = _this.config.serviceVersion) === null || _c === void 0 ? void 0 : _c.version;
-                                res.setHeader(((_d = _this.config.serviceVersion) === null || _d === void 0 ? void 0 : _d.headerName) || 'x-service-version', version || '0.0.0');
-                            }
-                            next();
-                        });
-                        // Global request timeout protection
-                        if (this.config.requestTimeout) {
-                            this.app.use(timeout(this.config.requestTimeout));
-                        }
-                        // Response time tracking for performance monitoring
-                        if ((_l = this.config.responseTime) === null || _l === void 0 ? void 0 : _l.enable) {
-                            this.app.use(responseTime({
-                                addHeader: this.config.responseTime.addHeader,
-                                logOnComplete: this.config.responseTime.logOnComplete
-                            }));
-                        }
-                        // Rate limiting should be early to prevent unnecessary processing
-                        if ((_m = this.config.rateLimit) === null || _m === void 0 ? void 0 : _m.enable) {
-                            rateLimit = ExpressServer.optionalRequire('express-rate-limit');
-                            if (!rateLimit) {
-                                getLogger().error({ command: 'npm install express-rate-limit' }, 'express-rate-limit is required but not installed. Please add it to your dependencies');
-                                process.exit(1);
-                            }
-                            this.app.use(rateLimit({
-                                windowMs: (_o = this.config.rateLimit.windowMs) !== null && _o !== void 0 ? _o : 15 * 60 * 1000,
-                                max: (_p = this.config.rateLimit.max) !== null && _p !== void 0 ? _p : 100,
-                                handler: function (req, res) {
-                                    var _a;
-                                    var status = HttpStatusCodes.TOO_MANY_REQUESTS;
-                                    var response = createFinalErrorResponse(req, status, ((_a = _this.config.rateLimit) === null || _a === void 0 ? void 0 : _a.message) || 'Too many requests');
-                                    res.status(status).json(response);
-                                },
-                                standardHeaders: (_q = this.config.rateLimit.standardHeaders) !== null && _q !== void 0 ? _q : true,
-                                legacyHeaders: (_r = this.config.rateLimit.legacyHeaders) !== null && _r !== void 0 ? _r : false
-                            }));
-                        }
-                        // Request logging with filtering
-                        if ((_s = this.config.requestLogging) === null || _s === void 0 ? void 0 : _s.enable) {
-                            this.app.use(function (req, res, next) {
-                                var _a, _b, _c, _d, _e, _f;
-                                if (typeof ((_a = _this.config.requestLogging) === null || _a === void 0 ? void 0 : _a.ignorePaths) === 'function') {
-                                    var skip = (_c = (_b = _this.config.requestLogging) === null || _b === void 0 ? void 0 : _b.ignorePaths) === null || _c === void 0 ? void 0 : _c.call(_b, req, res);
-                                    if (skip)
-                                        return next();
-                                }
-                                else if (Array.isArray((_d = _this.config.requestLogging) === null || _d === void 0 ? void 0 : _d.ignorePaths)) {
-                                    var skip = (_f = (_e = _this.config.requestLogging) === null || _e === void 0 ? void 0 : _e.ignorePaths) === null || _f === void 0 ? void 0 : _f.includes(req.path);
-                                    if (skip)
-                                        return next();
-                                }
-                                var logger = getLogger();
-                                var incomingRequestMetaData = {
-                                    requestId: req.id,
-                                    method: req.method,
-                                    url: req.originalUrl || req.url,
-                                    ip: req.ip
-                                };
-                                logger.info(incomingRequestMetaData, 'Incoming Request');
-                                next();
-                            });
-                        }
-                        // Custom request preprocessing hook
-                        if (this.hooks.onRequest) {
-                            this.app.use(this.hooks.onRequest);
-                        }
-                        // Response compression for better performance
-                        if (this.config.compression) {
-                            compression = ExpressServer.optionalRequire('compression');
-                            if (!compression) {
-                                getLogger().error({ command: 'npm install compression' }, 'compression is required but not installed. Please add it to your dependencies');
-                                process.exit(1);
-                            }
-                            if (typeof this.config.compression === 'object') {
-                                this.app.use(compression(this.config.compression));
-                            }
-                            else {
-                                this.app.use(compression());
-                            }
-                        }
-                        // Static file serving (do NOT normalize filesystem path; only normalize route)
-                        if (this.config.staticFolders) {
-                            this.config.staticFolders.forEach(function (folder) {
-                                var _a;
-                                _this.app.use(_this.normalizePath((_a = folder.path) !== null && _a !== void 0 ? _a : '/'), express.static(folder.directory, {
-                                    maxAge: folder.maxAge || 0,
-                                    etag: folder.etag !== false,
-                                    immutable: folder.immutable === true,
-                                    lastModified: folder.lastModified !== false,
-                                    cacheControl: folder.cacheControl !== false
-                                }));
-                                getLogger().info("Serving static folder: ".concat(folder.directory, " at path ").concat(folder.path || '/'));
-                            });
-                        }
-                        // Request body parsing with size limits
-                        if (this.config.bodyParser) {
-                            if (this.config.bodyParser.json) {
-                                this.app.use(express.json(this.config.bodyParser.json));
-                            }
-                            if (this.config.bodyParser.urlencoded) {
-                                this.app.use(express.urlencoded(this.config.bodyParser.urlencoded));
-                            }
-                        }
-                        // Cookie parser middleware
-                        if (this.config.cookieParser) {
-                            cookieParser = ExpressServer.optionalRequire('cookie-parser');
-                            if (!cookieParser) {
-                                getLogger().error({ command: 'npm install cookie-parser' }, 'cookie-parser is required but not installed. Please add it to your dependencies');
-                                process.exit(1);
-                            }
-                            if (typeof this.config.cookieParser === 'object') {
-                                this.app.use(cookieParser(undefined, this.config.cookieParser));
-                            }
-                            else {
-                                this.app.use(cookieParser());
-                            }
-                        }
-                        if (!((_t = this.config.openApi) === null || _t === void 0 ? void 0 : _t.enable)) return [3 /*break*/, 7];
-                        _y.label = 3;
-                    case 3:
-                        _y.trys.push([3, 6, , 7]);
-                        openApiMountPath = this.normalizePath((_u = this.config.openApi.mountPath) !== null && _u !== void 0 ? _u : '/docs', this.config.openApi.withGlobalPrefix);
-                        openApiFilePath = this.config.openApi.filePath;
-                        if (!openApiFilePath) {
-                            getLogger().error('OpenAPI file path is required');
-                            process.exit(1);
-                        }
-                        return [4 /*yield*/, fileExists(openApiFilePath)];
-                    case 4:
-                        isOpenApiFilePathExists = _y.sent();
-                        if (!isOpenApiFilePathExists) {
-                            getLogger().error("OpenAPI spec file not found at ".concat(openApiFilePath));
-                            process.exit(1);
-                        }
-                        if ((_v = this.config.openApi) === null || _v === void 0 ? void 0 : _v.verbose) {
-                            getLogger().info("Mounting OpenAPI docs at ".concat(openApiMountPath));
-                            getLogger().info("Using OpenAPI spec file at ".concat(openApiFilePath));
-                        }
-                        apiReference = ExpressServer.optionalRequire('@scalar/express-api-reference').apiReference;
-                        if (!apiReference) {
-                            getLogger().error({ command: 'npm install @scalar/express-api-reference' }, '@scalar/express-api-reference is required for OpenAPI docs but not installed. Please add it to your dependencies');
-                            process.exit(1);
-                        }
-                        _b = (_a = this.app).use;
-                        _c = [openApiMountPath];
-                        _d = apiReference;
-                        _e = {};
-                        _f = {};
-                        return [4 /*yield*/, fs.promises.readFile(openApiFilePath, 'utf8')];
-                    case 5:
-                        _b.apply(_a, _c.concat([_d.apply(void 0, [(_e.spec = (_f.content = _y.sent(),
-                                    _f),
-                                    _e)])]));
-                        if ((_w = this.config.openApi) === null || _w === void 0 ? void 0 : _w.verbose) {
-                            getLogger().info("Mounted OpenAPI docs at ".concat(openApiMountPath));
-                        }
-                        return [3 /*break*/, 7];
-                    case 6:
-                        err_2 = _y.sent();
-                        getLogger().error({ err: err_2 }, 'Failed to mount OpenAPI docs');
-                        return [3 /*break*/, 7];
-                    case 7:
-                        // Custom response preprocessing hook (apply global prefix if set)
-                        if (this.hooks.onResponse) {
-                            this.app.use(this.globalPrefix, this.hooks.onResponse);
-                        }
-                        if ((_x = this.config.metrics) === null || _x === void 0 ? void 0 : _x.enable) {
-                            // Add metrics tracking middleware
-                            this.app.use(function (req, res, next) {
-                                var _a, _b;
-                                var start = process.hrtime();
-                                // Track client IPs
-                                (_a = _this.clientIPs) === null || _a === void 0 ? void 0 : _a.inc({ ip: req.ip, method: req.method });
-                                // Track request sizes (parse safely)
-                                var cl = req.headers['content-length'];
-                                if (cl) {
-                                    var size = Number(cl);
-                                    if (!Number.isNaN(size) && size >= 0) {
-                                        var route = _this.normalizeRouteForMetrics(req, res);
-                                        (_b = _this.requestSizes) === null || _b === void 0 ? void 0 : _b.observe({ method: req.method, route: route }, size);
-                                    }
-                                }
-                                res.once('finish', function () {
-                                    var _a, _b;
-                                    var _c = __read(process.hrtime(start), 2), seconds = _c[0], nanoseconds = _c[1];
-                                    var finalRoute = _this.normalizeRouteForMetrics(req, res);
-                                    (_a = _this.requestCounter) === null || _a === void 0 ? void 0 : _a.inc({
-                                        method: req.method,
-                                        route: finalRoute,
-                                        status: res.statusCode.toString()
-                                    });
-                                    (_b = _this.routeTimings) === null || _b === void 0 ? void 0 : _b.observe({
-                                        method: req.method,
-                                        route: finalRoute,
-                                        status: res.statusCode.toString()
-                                    }, seconds + nanoseconds / 1e9);
-                                });
-                                next();
-                            });
-                        }
-                        return [2 /*return*/];
+    async setupMiddleware() {
+        if (this.config.https) {
+            await this.validateHttpsFiles();
+        }
+        // Basic middleware should be first
+        this.app.disable('x-powered-by');
+        if (this.config.trustProxy) {
+            this.app.set('trust proxy', true);
+        }
+        // Request ID generation - must be first for proper tracing
+        this.app.use(requestId({
+            headerName: this.config.requestId?.headerName,
+            exposeHeader: this.config.requestId?.exposeHeader,
+            generator: this.config.requestId?.generator
+        }));
+        // Request context setup for logging correlation
+        this.app.use(setupRequestContext({
+            headerName: this.config.requestId?.headerName,
+            autoLog: false
+        }));
+        // Early shutdown-awareness middleware (lets load balancers drain connections gracefully)
+        this.app.use((_req, res, next) => {
+            if (this.isShuttingDown) {
+                res.setHeader('Connection', 'close');
+                return res
+                    .status(HttpStatusCodes.SERVICE_UNAVAILABLE)
+                    .json(new ServiceUnavailableException('Server is shutting down'));
+            }
+            next();
+            return;
+        });
+        // Security middleware should come early
+        if (this.config.helmet) {
+            const helmet = ExpressServer.optionalRequire('helmet');
+            if (!helmet) {
+                getLogger().error({ command: 'npm install helmet' }, 'helmet is required but not installed. Please add it to your dependencies');
+                process.exit(1);
+            }
+            if (typeof this.config.helmet === 'object') {
+                this.app.use(helmet(this.config.helmet));
+            }
+            else {
+                this.app.use(helmet());
+            }
+        }
+        // CORS middleware should be early
+        if (this.config.cors) {
+            const cors = ExpressServer.optionalRequire('cors');
+            if (!cors) {
+                getLogger().error({ command: 'npm install cors' }, 'cors is required but not installed. Please add it to your dependencies');
+                process.exit(1);
+            }
+            this.app.use(cors(this.config.cors === true ? {} : this.config.cors));
+        }
+        // Global headers
+        this.app.use((_req, res, next) => {
+            if (this.config.globalHeaders) {
+                for (const key in this.config.globalHeaders) {
+                    const value = this.config.globalHeaders[key];
+                    res.setHeader(key, typeof value === 'function' ? value() : value);
                 }
-            });
+            }
+            if (this.config.isMicroservice) {
+                res.setHeader('X-Microservice', this.config.appName || 'express_app');
+            }
+            if (this.config.serviceVersion?.enable) {
+                const version = typeof this.config.serviceVersion?.version === 'function'
+                    ? this.config.serviceVersion.version()
+                    : this.config.serviceVersion?.version;
+                res.setHeader(this.config.serviceVersion?.headerName || 'x-service-version', version || '0.0.0');
+            }
+            next();
         });
-    };
+        // Global request timeout protection
+        if (this.config.requestTimeout) {
+            this.app.use(timeout(this.config.requestTimeout));
+        }
+        // Response time tracking for performance monitoring
+        if (this.config.responseTime?.enable) {
+            this.app.use(responseTime({
+                addHeader: this.config.responseTime.addHeader,
+                logOnComplete: this.config.responseTime.logOnComplete
+            }));
+        }
+        // Rate limiting should be early to prevent unnecessary processing
+        if (this.config.rateLimit?.enable) {
+            const rateLimit = ExpressServer.optionalRequire('express-rate-limit');
+            if (!rateLimit) {
+                getLogger().error({ command: 'npm install express-rate-limit' }, 'express-rate-limit is required but not installed. Please add it to your dependencies');
+                process.exit(1);
+            }
+            this.app.use(rateLimit({
+                windowMs: this.config.rateLimit.windowMs ?? 15 * 60 * 1000,
+                max: this.config.rateLimit.max ?? 100,
+                handler: (req, res) => {
+                    const status = HttpStatusCodes.TOO_MANY_REQUESTS;
+                    const response = createFinalErrorResponse(req, status, this.config.rateLimit?.message || 'Too many requests');
+                    res.status(status).json(response);
+                },
+                standardHeaders: this.config.rateLimit.standardHeaders ?? true,
+                legacyHeaders: this.config.rateLimit.legacyHeaders ?? false
+            }));
+        }
+        // Request logging with filtering
+        if (this.config.requestLogging?.enable) {
+            this.app.use((req, res, next) => {
+                if (typeof this.config.requestLogging?.ignorePaths === 'function') {
+                    const skip = this.config.requestLogging?.ignorePaths?.(req, res);
+                    if (skip)
+                        return next();
+                }
+                else if (Array.isArray(this.config.requestLogging?.ignorePaths)) {
+                    const skip = this.config.requestLogging?.ignorePaths?.includes(req.path);
+                    if (skip)
+                        return next();
+                }
+                const logger = getLogger();
+                const incomingRequestMetaData = {
+                    requestId: req.id,
+                    method: req.method,
+                    url: req.originalUrl || req.url,
+                    ip: req.ip
+                };
+                logger.info(incomingRequestMetaData, 'Incoming Request');
+                next();
+            });
+        }
+        // Custom request preprocessing hook
+        if (this.hooks.onRequest) {
+            this.app.use(this.hooks.onRequest);
+        }
+        // Response compression for better performance
+        if (this.config.compression) {
+            const compression = ExpressServer.optionalRequire('compression');
+            if (!compression) {
+                getLogger().error({ command: 'npm install compression' }, 'compression is required but not installed. Please add it to your dependencies');
+                process.exit(1);
+            }
+            if (typeof this.config.compression === 'object') {
+                this.app.use(compression(this.config.compression));
+            }
+            else {
+                this.app.use(compression());
+            }
+        }
+        // Static file serving (do NOT normalize filesystem path; only normalize route)
+        if (this.config.staticFolders) {
+            this.config.staticFolders.forEach(folder => {
+                this.app.use(this.normalizePath(folder.path ?? '/'), express.static(folder.directory, {
+                    maxAge: folder.maxAge || 0,
+                    etag: folder.etag !== false,
+                    immutable: folder.immutable === true,
+                    lastModified: folder.lastModified !== false,
+                    cacheControl: folder.cacheControl !== false
+                }));
+                getLogger().info(`Serving static folder: ${folder.directory} at path ${folder.path || '/'}`);
+            });
+        }
+        // Request body parsing with size limits
+        if (this.config.bodyParser) {
+            if (this.config.bodyParser.json) {
+                this.app.use(express.json(this.config.bodyParser.json));
+            }
+            if (this.config.bodyParser.urlencoded) {
+                this.app.use(express.urlencoded(this.config.bodyParser.urlencoded));
+            }
+        }
+        // Cookie parser middleware
+        if (this.config.cookieParser) {
+            const cookieParser = ExpressServer.optionalRequire('cookie-parser');
+            if (!cookieParser) {
+                getLogger().error({ command: 'npm install cookie-parser' }, 'cookie-parser is required but not installed. Please add it to your dependencies');
+                process.exit(1);
+            }
+            if (typeof this.config.cookieParser === 'object') {
+                this.app.use(cookieParser(undefined, this.config.cookieParser));
+            }
+            else {
+                this.app.use(cookieParser());
+            }
+        }
+        // OpenAPI docs via @scalar/express-api-reference
+        if (this.config.openApi?.enable) {
+            try {
+                const openApiMountPath = this.normalizePath(this.config.openApi.mountPath ?? '/docs', this.config.openApi.withGlobalPrefix);
+                const openApiFilePath = this.config.openApi.filePath;
+                if (!openApiFilePath) {
+                    getLogger().error('OpenAPI file path is required');
+                    process.exit(1);
+                }
+                const isOpenApiFilePathExists = await fileExists(openApiFilePath);
+                if (!isOpenApiFilePathExists) {
+                    getLogger().error(`OpenAPI spec file not found at ${openApiFilePath}`);
+                    process.exit(1);
+                }
+                if (this.config.openApi?.verbose) {
+                    getLogger().info(`Mounting OpenAPI docs at ${openApiMountPath}`);
+                    getLogger().info(`Using OpenAPI spec file at ${openApiFilePath}`);
+                }
+                const apiReference = ExpressServer.optionalRequire('@scalar/express-api-reference').apiReference;
+                if (!apiReference) {
+                    getLogger().error({ command: 'npm install @scalar/express-api-reference' }, '@scalar/express-api-reference is required for OpenAPI docs but not installed. Please add it to your dependencies');
+                    process.exit(1);
+                }
+                this.app.use(openApiMountPath, apiReference({
+                    spec: {
+                        content: await fs.promises.readFile(openApiFilePath, 'utf8')
+                    }
+                }));
+                if (this.config.openApi?.verbose) {
+                    getLogger().info(`Mounted OpenAPI docs at ${openApiMountPath}`);
+                }
+            }
+            catch (err) {
+                getLogger().error({ err }, 'Failed to mount OpenAPI docs');
+            }
+        }
+        // Custom response preprocessing hook (apply global prefix if set)
+        if (this.hooks.onResponse) {
+            this.app.use(this.globalPrefix, this.hooks.onResponse);
+        }
+        if (this.config.metrics?.enable) {
+            // Add metrics tracking middleware
+            this.app.use((req, res, next) => {
+                const start = process.hrtime();
+                // Track client IPs
+                this.clientIPs?.inc({ ip: req.ip, method: req.method });
+                // Track request sizes (parse safely)
+                const cl = req.headers['content-length'];
+                if (cl) {
+                    const size = Number(cl);
+                    if (!Number.isNaN(size) && size >= 0) {
+                        const route = this.normalizeRouteForMetrics(req, res);
+                        this.requestSizes?.observe({ method: req.method, route }, size);
+                    }
+                }
+                res.once('finish', () => {
+                    const [seconds, nanoseconds] = process.hrtime(start);
+                    const finalRoute = this.normalizeRouteForMetrics(req, res);
+                    this.requestCounter?.inc({
+                        method: req.method,
+                        route: finalRoute,
+                        status: res.statusCode.toString()
+                    });
+                    this.routeTimings?.observe({
+                        method: req.method,
+                        route: finalRoute,
+                        status: res.statusCode.toString()
+                    }, seconds + nanoseconds / 1e9);
+                });
+                next();
+            });
+        }
+    }
     /**
      * Configure server routes and error handling.
      * Sets up in following order:
@@ -596,118 +476,82 @@ var ExpressServer = /** @class */ (function () {
      * 3. 404 handler
      * 4. Error handler
      */
-    ExpressServer.prototype.setupRoutes = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var healthCheckPath, metricsPath, routerToUse;
-            var _this = this;
-            var _a, _b, _c, _d, _e;
-            return __generator(this, function (_f) {
-                healthCheckPath = this.normalizePath(((_a = this.config.healthCheck) === null || _a === void 0 ? void 0 : _a.path) || '/healthz', (_b = this.config.healthCheck) === null || _b === void 0 ? void 0 : _b.withGlobalPrefix);
-                this.app.get(healthCheckPath, function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
-                    var checkResults, results, allOk, status_1, response, _a;
-                    var _this = this;
-                    var _b;
-                    return __generator(this, function (_c) {
-                        switch (_c.label) {
-                            case 0:
-                                _c.trys.push([0, 2, , 3]);
-                                if (!this.healthChecks.length) {
-                                    return [2 /*return*/, res.status(HttpStatusCodes.OK).json(new SuccessResponse('OK'))];
-                                }
-                                return [4 /*yield*/, Promise.allSettled(this.healthChecks.map(function (_a) { return __awaiter(_this, [_a], void 0, function (_b) {
-                                        var status_2, error_1;
-                                        var name = _b.name, check = _b.check;
-                                        return __generator(this, function (_c) {
-                                            switch (_c.label) {
-                                                case 0:
-                                                    _c.trys.push([0, 2, , 3]);
-                                                    return [4 /*yield*/, Promise.resolve(check())];
-                                                case 1:
-                                                    status_2 = _c.sent();
-                                                    return [2 /*return*/, { name: name, status: status_2, error: null }];
-                                                case 2:
-                                                    error_1 = _c.sent();
-                                                    return [2 /*return*/, { name: name, status: false, error: error_1.message }];
-                                                case 3: return [2 /*return*/];
-                                            }
-                                        });
-                                    }); }))];
-                            case 1:
-                                checkResults = _c.sent();
-                                results = checkResults.map(function (result) {
-                                    if (result.status === 'fulfilled')
-                                        return result.value;
-                                    return { name: 'unknown', status: false, error: result.reason };
-                                });
-                                allOk = results.every(function (r) { return r.status; });
-                                status_1 = allOk ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;
-                                response = new SuccessResponse(allOk ? 'OK' : 'Service unavailable');
-                                if (!allOk)
-                                    response.error = true;
-                                if ((_b = this.config.healthCheck) === null || _b === void 0 ? void 0 : _b.detailed)
-                                    response.data = { checks: results };
-                                return [2 /*return*/, res.status(status_1).json(response)];
-                            case 2:
-                                _a = _c.sent();
-                                return [2 /*return*/, res
-                                        .status(HttpStatusCodes.INTERNAL_SERVER_ERROR)
-                                        .json(new InternalServerErrorException('Health check failed'))];
-                            case 3: return [2 /*return*/];
-                        }
-                    });
-                }); });
-                // Metrics endpoint
-                if ((_c = this.config.metrics) === null || _c === void 0 ? void 0 : _c.enable) {
-                    metricsPath = this.normalizePath((_d = this.config.metrics.path) !== null && _d !== void 0 ? _d : '/metrics', (_e = this.config.metrics) === null || _e === void 0 ? void 0 : _e.withGlobalPrefix);
-                    this.app.get(metricsPath, function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
-                        var _a, _b;
-                        return __generator(this, function (_c) {
-                            switch (_c.label) {
-                                case 0:
-                                    res.set('Content-Type', this.register.contentType);
-                                    _b = (_a = res).end;
-                                    return [4 /*yield*/, this.register.metrics()];
-                                case 1:
-                                    _b.apply(_a, [_c.sent()]);
-                                    return [2 /*return*/];
-                            }
-                        });
-                    }); });
+    async setupRoutes() {
+        // Health check endpoint
+        const healthCheckPath = this.normalizePath(this.config.healthCheck?.path || '/healthz', this.config.healthCheck?.withGlobalPrefix);
+        this.app.get(healthCheckPath, async (_req, res) => {
+            try {
+                if (!this.healthChecks.length) {
+                    return res.status(HttpStatusCodes.OK).json(new SuccessResponse('OK'));
                 }
-                routerToUse = this.externalRouter || this.rootRouter;
-                this.app.use(this.globalPrefix, routerToUse);
-                // 404 handler (must be after all other routes)
-                this.app.use(function (req, res) {
-                    var status = HttpStatusCodes.NOT_FOUND;
-                    var response = createFinalErrorResponse(req, status, "Route ".concat(req.method.toUpperCase(), " ").concat(req.path, " not found"));
-                    res.status(status).json(response);
-                });
-                // Global error handler (must be the last middleware)
-                this.app.use(function (err, req, res, next) {
-                    var _a;
-                    // Check if this is a 404 error that should be handled with special logging rules
-                    var isNotFoundError = err instanceof NotFoundException;
-                    var shouldSkipLogging = !_this.hooks.onError &&
-                        isNotFoundError &&
-                        ((_a = _this.config.requestLogging) === null || _a === void 0 ? void 0 : _a.enable) &&
-                        _this.config.requestLogging.skipNotFoundRoutes === true;
-                    if (_this.hooks.onError) {
-                        // Use custom error handler if provided
-                        _this.hooks.onError(err, req, res, next);
+                const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
+                    try {
+                        const status = await Promise.resolve(check());
+                        return { name, status, error: null };
                     }
-                    else {
-                        // Default error handler with logging
-                        var errorHandlerMiddleware = errorHandler({
-                            logErrors: !shouldSkipLogging,
-                            includeDetails: Env.isDev() // Only show stack traces in development
-                        });
-                        errorHandlerMiddleware(err, req, res, next);
+                    catch (error) {
+                        return { name, status: false, error: error.message };
                     }
+                }));
+                const results = checkResults.map(result => {
+                    if (result.status === 'fulfilled')
+                        return result.value;
+                    return { name: 'unknown', status: false, error: result.reason };
                 });
-                return [2 /*return*/];
+                const allOk = results.every(r => r.status);
+                const status = allOk ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;
+                const response = new SuccessResponse(allOk ? 'OK' : 'Service unavailable');
+                if (!allOk)
+                    response.error = true;
+                if (this.config.healthCheck?.detailed)
+                    response.data = { checks: results };
+                return res.status(status).json(response);
+            }
+            catch {
+                return res
+                    .status(HttpStatusCodes.INTERNAL_SERVER_ERROR)
+                    .json(new InternalServerErrorException('Health check failed'));
+            }
+        });
+        // Metrics endpoint
+        if (this.config.metrics?.enable) {
+            const metricsPath = this.normalizePath(this.config.metrics.path ?? '/metrics', this.config.metrics?.withGlobalPrefix);
+            this.app.get(metricsPath, async (_req, res) => {
+                res.set('Content-Type', this.register.contentType);
+                res.end(await this.register.metrics());
             });
+        }
+        // Application routes
+        const routerToUse = this.externalRouter || this.rootRouter;
+        this.app.use(this.globalPrefix, routerToUse);
+        // 404 handler (must be after all other routes)
+        this.app.use((req, res) => {
+            const status = HttpStatusCodes.NOT_FOUND;
+            const response = createFinalErrorResponse(req, status, `Route ${req.method.toUpperCase()} ${req.path} not found`);
+            res.status(status).json(response);
+        });
+        // Global error handler (must be the last middleware)
+        this.app.use((err, req, res, next) => {
+            // Check if this is a 404 error that should be handled with special logging rules
+            const isNotFoundError = err instanceof NotFoundException;
+            const shouldSkipLogging = !this.hooks.onError &&
+                isNotFoundError &&
+                this.config.requestLogging?.enable &&
+                this.config.requestLogging.skipNotFoundRoutes === true;
+            if (this.hooks.onError) {
+                // Use custom error handler if provided
+                this.hooks.onError(err, req, res, next);
+            }
+            else {
+                // Default error handler with logging
+                const errorHandlerMiddleware = errorHandler({
+                    logErrors: !shouldSkipLogging,
+                    includeDetails: Env.isDev() // Only show stack traces in development
+                });
+                errorHandlerMiddleware(err, req, res, next);
+            }
         });
-    };
+    }
     /**
      * Register a new health check function for monitoring service dependencies.
      *
@@ -724,28 +568,28 @@ var ExpressServer = /** @class */ (function () {
      * @param check Function returning boolean or Promise<boolean> indicating health
      * @returns This instance for method chaining
      */
-    ExpressServer.prototype.registerHealthCheck = function (name, check) {
-        this.healthChecks.push({ name: name, check: check });
+    registerHealthCheck(name, check) {
+        this.healthChecks.push({ name, check });
         return this;
-    };
+    }
     /**
      * Get the underlying Express application instance.
      * Use this for advanced Express features not exposed by this wrapper.
      *
      * @returns The raw Express app instance
      */
-    ExpressServer.prototype.getApp = function () {
+    getApp() {
         return this.app;
-    };
+    }
     /**
      * Get the active HTTP/HTTPS server instance.
      * Returns null if the server is not currently running.
      *
      * @returns The HTTP/HTTPS server instance or null
      */
-    ExpressServer.prototype.getServer = function () {
+    getServer() {
         return this.server;
-    };
+    }
     /**
      * Start the HTTP server and begin listening for requests.
      *
@@ -759,90 +603,68 @@ var ExpressServer = /** @class */ (function () {
      * @returns Promise resolving to the running HTTP server instance
      * @throws Error if server fails to start or port is already in use
      */
-    ExpressServer.prototype.start = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var _this = this;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: 
-                    // Ensure initialization (middleware + routes) completed before starting
-                    return [4 /*yield*/, this.initPromise];
-                    case 1:
-                        // Ensure initialization (middleware + routes) completed before starting
-                        _a.sent();
-                        return [4 /*yield*/, this.runHook('beforeStart', this.app)];
-                    case 2:
-                        _a.sent();
-                        return [2 /*return*/, new Promise(function (resolve, reject) {
-                                var _a, _b;
-                                try {
-                                    // Prepare listen arguments with optional host parameter
-                                    var listenArgs = [
-                                        _this.config.port,
-                                        _this.config.host,
-                                        function () { return __awaiter(_this, void 0, void 0, function () {
-                                            var protocol, url;
-                                            var _a, _b, _c;
-                                            return __generator(this, function (_d) {
-                                                switch (_d.label) {
-                                                    case 0:
-                                                        protocol = this.config.https ? 'https' : 'http';
-                                                        url = "".concat(protocol, "://").concat(this.config.host, ":").concat(this.config.port);
-                                                        getLogger().info("Server running on ".concat(url));
-                                                        if ((_a = this.config.healthCheck) === null || _a === void 0 ? void 0 : _a.path) {
-                                                            getLogger().info("Health check available at ".concat(url).concat(this.normalizePath(this.config.healthCheck.path, this.config.healthCheck.withGlobalPrefix)));
-                                                        }
-                                                        if (((_b = this.config.metrics) === null || _b === void 0 ? void 0 : _b.enable) && this.config.metrics.path) {
-                                                            getLogger().info("Metrics available at ".concat(url).concat(this.normalizePath(this.config.metrics.path, this.config.metrics.withGlobalPrefix)));
-                                                        }
-                                                        if ((_c = this.config.openApi) === null || _c === void 0 ? void 0 : _c.enable) {
-                                                            getLogger().info("API docs available at ".concat(url).concat(this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)));
-                                                        }
-                                                        if (!this.server) return [3 /*break*/, 2];
-                                                        return [4 /*yield*/, this.runHook('afterStart', this.server)];
-                                                    case 1:
-                                                        _d.sent();
-                                                        _d.label = 2;
-                                                    case 2:
-                                                        resolve(this.server);
-                                                        return [2 /*return*/];
-                                                }
-                                            });
-                                        }); }
-                                    ];
-                                    if (_this.config.https) {
-                                        var httpsOptions = __assign(__assign({}, _this.config.https), { key: fs.readFileSync(_this.config.https.key), cert: fs.readFileSync(_this.config.https.cert) });
-                                        if (_this.config.https.ca) {
-                                            httpsOptions.ca = fs.readFileSync(_this.config.https.ca);
-                                        }
-                                        if (_this.config.https.passphrase) {
-                                            httpsOptions.passphrase = _this.config.https.passphrase;
-                                        }
-                                        _this.server = (_a = https.createServer(httpsOptions, _this.app)).listen.apply(_a, __spreadArray([], __read(listenArgs), false));
-                                    }
-                                    else {
-                                        // Start the HTTP server
-                                        _this.server = (_b = _this.app).listen.apply(_b, __spreadArray([], __read(listenArgs), false));
-                                    }
-                                    // Track connections
-                                    _this.server.on('connection', function (conn) {
-                                        _this.connections.add(conn);
-                                        conn.on('close', function () { return _this.connections.delete(conn); });
-                                    });
-                                    // Handle server startup errors (port in use, permission denied, etc.)
-                                    _this.server.on('error', function (err) {
-                                        getLogger().error({ err: err }, 'Server failed to start');
-                                        reject(err);
-                                    });
-                                }
-                                catch (error) {
-                                    reject(error);
-                                }
-                            })];
+    async start() {
+        // Ensure initialization (middleware + routes) completed before starting
+        await this.initPromise;
+        await this.runHook('beforeStart', this.app);
+        return new Promise((resolve, reject) => {
+            try {
+                // Prepare listen arguments with optional host parameter
+                const listenArgs = [
+                    this.config.port,
+                    this.config.host,
+                    async () => {
+                        const protocol = this.config.https ? 'https' : 'http';
+                        const url = `${protocol}://${this.config.host}:${this.config.port}`;
+                        getLogger().info(`Server running on ${url}`);
+                        if (this.config.healthCheck?.path) {
+                            getLogger().info(`Health check available at ${url}${this.normalizePath(this.config.healthCheck.path, this.config.healthCheck.withGlobalPrefix)}`);
+                        }
+                        if (this.config.metrics?.enable && this.config.metrics.path) {
+                            getLogger().info(`Metrics available at ${url}${this.normalizePath(this.config.metrics.path, this.config.metrics.withGlobalPrefix)}`);
+                        }
+                        if (this.config.openApi?.enable) {
+                            getLogger().info(`API docs available at ${url}${this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)}`);
+                        }
+                        if (this.server)
+                            await this.runHook('afterStart', this.server);
+                        resolve(this.server);
+                    }
+                ];
+                if (this.config.https) {
+                    const httpsOptions = {
+                        ...this.config.https,
+                        key: fs.readFileSync(this.config.https.key),
+                        cert: fs.readFileSync(this.config.https.cert)
+                    };
+                    if (this.config.https.ca) {
+                        httpsOptions.ca = fs.readFileSync(this.config.https.ca);
+                    }
+                    if (this.config.https.passphrase) {
+                        httpsOptions.passphrase = this.config.https.passphrase;
+                    }
+                    this.server = https.createServer(httpsOptions, this.app).listen(...listenArgs);
                 }
-            });
+                else {
+                    // Start the HTTP server
+                    this.server = this.app.listen(...listenArgs);
+                }
+                // Track connections
+                this.server.on('connection', (conn) => {
+                    this.connections.add(conn);
+                    conn.on('close', () => this.connections.delete(conn));
+                });
+                // Handle server startup errors (port in use, permission denied, etc.)
+                this.server.on('error', err => {
+                    getLogger().error({ err }, 'Server failed to start');
+                    reject(err);
+                });
+            }
+            catch (error) {
+                reject(error);
+            }
         });
-    };
+    }
     /**
      * Stop the HTTP server gracefully.
      *
@@ -859,78 +681,47 @@ var ExpressServer = /** @class */ (function () {
      * - Resources are properly cleaned up
      * - Monitoring systems are notified
      */
-    ExpressServer.prototype.stop = function () {
-        return __awaiter(this, arguments, void 0, function (force) {
-            var shutdownTimeout, serverClosePromise, timeoutPromise, err_3;
-            var _this = this;
-            if (force === void 0) { force = false; }
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        if (!this.server) {
-                            getLogger().warn('Stop called but server is not running');
-                            return [2 /*return*/];
-                        }
-                        if (this.isShuttingDown) {
-                            getLogger().warn('Stop called while shutdown is already in progress');
-                            return [2 /*return*/];
-                        }
-                        this.isShuttingDown = true;
-                        return [4 /*yield*/, this.runHook('beforeStop', this.server)];
-                    case 1:
-                        _a.sent();
-                        shutdownTimeout = 10000;
-                        serverClosePromise = new Promise(function (resolve, reject) {
-                            _this.server.close(function (err) { return __awaiter(_this, void 0, void 0, function () {
-                                return __generator(this, function (_a) {
-                                    switch (_a.label) {
-                                        case 0:
-                                            if (err) {
-                                                getLogger().error({ err: err }, 'Error while closing server');
-                                                reject(err);
-                                                return [2 /*return*/];
-                                            }
-                                            this.server = null;
-                                            this.isShuttingDown = false;
-                                            getLogger().info('Server stopped gracefully');
-                                            return [4 /*yield*/, this.runHook('afterStop')];
-                                        case 1:
-                                            _a.sent();
-                                            resolve();
-                                            return [2 /*return*/];
-                                    }
-                                });
-                            }); });
-                        });
-                        timeoutPromise = new Promise(function (_, reject) {
-                            return setTimeout(function () { return reject(new Error('Shutdown timeout')); }, shutdownTimeout);
-                        });
-                        _a.label = 2;
-                    case 2:
-                        _a.trys.push([2, 4, 5, 7]);
-                        return [4 /*yield*/, Promise.race([serverClosePromise, timeoutPromise])];
-                    case 3:
-                        _a.sent();
-                        return [3 /*break*/, 7];
-                    case 4:
-                        err_3 = _a.sent();
-                        getLogger().error({ err: err_3 }, 'Graceful shutdown timed out');
-                        if (force) {
-                            getLogger().warn('Forcing connection destroy due to shutdown timeout');
-                        }
-                        return [3 /*break*/, 7];
-                    case 5: 
-                    // Always clean up connections
-                    return [4 /*yield*/, this.destroyConnections()];
-                    case 6:
-                        // Always clean up connections
-                        _a.sent();
-                        return [7 /*endfinally*/];
-                    case 7: return [2 /*return*/];
+    async stop(force = false) {
+        if (!this.server) {
+            getLogger().warn('Stop called but server is not running');
+            return;
+        }
+        if (this.isShuttingDown) {
+            getLogger().warn('Stop called while shutdown is already in progress');
+            return;
+        }
+        this.isShuttingDown = true;
+        await this.runHook('beforeStop', this.server);
+        const shutdownTimeout = 10_000; // 10s max wait
+        const serverClosePromise = new Promise((resolve, reject) => {
+            this.server.close(async (err) => {
+                if (err) {
+                    getLogger().error({ err }, 'Error while closing server');
+                    reject(err);
+                    return;
                 }
+                this.server = null;
+                this.isShuttingDown = false;
+                getLogger().info('Server stopped gracefully');
+                await this.runHook('afterStop');
+                resolve();
             });
         });
-    };
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Shutdown timeout')), shutdownTimeout));
+        try {
+            await Promise.race([serverClosePromise, timeoutPromise]);
+        }
+        catch (err) {
+            getLogger().error({ err }, 'Graceful shutdown timed out');
+            if (force) {
+                getLogger().warn('Forcing connection destroy due to shutdown timeout');
+            }
+        }
+        finally {
+            // Always clean up connections
+            await this.destroyConnections();
+        }
+    }
     /**
      * Enable graceful shutdown on OS signals for production deployment.
      *
@@ -942,66 +733,46 @@ var ExpressServer = /** @class */ (function () {
      *
      * @param signals Array of process signals to listen for (default: SIGINT, SIGTERM)
      */
-    ExpressServer.prototype.enableGracefulShutdown = function (signals) {
-        var _this = this;
-        if (signals === void 0) { signals = ['SIGINT', 'SIGTERM']; }
-        signals.forEach(function (signal) {
-            process.on(signal, function () { return __awaiter(_this, void 0, void 0, function () {
-                var err_4, forceError_1;
-                return __generator(this, function (_a) {
-                    switch (_a.label) {
-                        case 0:
-                            getLogger().info("Received ".concat(signal, ", initiating graceful shutdown..."));
-                            _a.label = 1;
-                        case 1:
-                            _a.trys.push([1, 3, , 8]);
-                            return [4 /*yield*/, this.stop()];
-                        case 2:
-                            _a.sent();
-                            process.exit(0);
-                            return [3 /*break*/, 8];
-                        case 3:
-                            err_4 = _a.sent();
-                            getLogger().error({ err: err_4 }, 'Error during graceful shutdown, forcing stop...');
-                            _a.label = 4;
-                        case 4:
-                            _a.trys.push([4, 6, , 7]);
-                            return [4 /*yield*/, this.stop(true)];
-                        case 5:
-                            _a.sent(); // fallback to forced shutdown
-                            process.exit(1);
-                            return [3 /*break*/, 7];
-                        case 6:
-                            forceError_1 = _a.sent();
-                            getLogger().fatal({ forceError: forceError_1 }, 'Forced shutdown failed, exiting hard');
-                            process.exit(1);
-                            return [3 /*break*/, 7];
-                        case 7: return [3 /*break*/, 8];
-                        case 8: return [2 /*return*/];
+    enableGracefulShutdown(signals = ['SIGINT', 'SIGTERM']) {
+        signals.forEach(signal => {
+            process.on(signal, async () => {
+                getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
+                try {
+                    await this.stop();
+                    process.exit(0);
+                }
+                catch (err) {
+                    getLogger().error({ err }, 'Error during graceful shutdown, forcing stop...');
+                    try {
+                        await this.stop(true); // fallback to forced shutdown
+                        process.exit(1);
                     }
-                });
-            }); });
+                    catch (forceError) {
+                        getLogger().fatal({ forceError }, 'Forced shutdown failed, exiting hard');
+                        process.exit(1);
+                    }
+                }
+            });
         });
         return this;
-    };
+    }
     /**
      * Set an externally created base router.
      * This will override the internal rootRouter.
      */
-    ExpressServer.prototype.setBaseRouter = function (router) {
+    setBaseRouter(router) {
         this.externalRouter = router;
         return this;
-    };
+    }
     /**
      * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).
      */
-    ExpressServer.prototype.createRouter = function (prefix) {
-        if (prefix === void 0) { prefix = ''; }
-        var router = express.Router();
-        var path = this.normalizePath(prefix, true);
+    createRouter(prefix = '') {
+        const router = express.Router();
+        const path = this.normalizePath(prefix, true);
         this.rootRouter.use(path, router);
         return router;
-    };
+    }
     /**
      * Register a new route handler with support for multiple HTTP methods.
      * The route is automatically registered under the globalPrefix if set.
@@ -1011,13 +782,9 @@ var ExpressServer = /** @class */ (function () {
      * @param handlers One or more Express request handlers (middleware + final handler)
      * @returns This instance for method chaining
      */
-    ExpressServer.prototype.registerRoute = function (methods, path) {
-        var handlers = [];
-        for (var _i = 2; _i < arguments.length; _i++) {
-            handlers[_i - 2] = arguments[_i];
-        }
-        var fullPath = this.normalizePath(path, true);
-        var methodMap = {
+    registerRoute(methods, path, ...handlers) {
+        const fullPath = this.normalizePath(path, true);
+        const methodMap = {
             get: this.app.get.bind(this.app),
             post: this.app.post.bind(this.app),
             put: this.app.put.bind(this.app),
@@ -1026,17 +793,17 @@ var ExpressServer = /** @class */ (function () {
             options: this.app.options.bind(this.app),
             head: this.app.head.bind(this.app)
         };
-        methods.forEach(function (m) {
-            var fn = methodMap[m];
+        methods.forEach(m => {
+            const fn = methodMap[m];
             if (fn) {
-                fn.apply(void 0, __spreadArray([fullPath], __read(handlers), false));
+                fn(fullPath, ...handlers);
             }
             else {
-                throw new Error("Unsupported HTTP method: ".concat(m));
+                throw new Error(`Unsupported HTTP method: ${m}`);
             }
         });
         return this;
-    };
+    }
     /**
      * Register custom middleware with optional path restriction.
      *
@@ -1050,9 +817,9 @@ var ExpressServer = /** @class */ (function () {
      * @param middleware Middleware handler (required if path is provided)
      * @returns This instance for method chaining
      */
-    ExpressServer.prototype.registerMiddleware = function (path, middleware) {
+    registerMiddleware(path, middleware) {
         if (typeof path === 'string') {
-            var normalizedPath = this.normalizePath(path);
+            const normalizedPath = this.normalizePath(path);
             if (normalizedPath) {
                 this.app.use(normalizedPath, middleware);
             }
@@ -1064,7 +831,7 @@ var ExpressServer = /** @class */ (function () {
             this.app.use(path);
         }
         return this;
-    };
+    }
     /**
      * Register one or more middleware functions to be applied globally.
      * This is a simpler alternative to registerMiddleware when you just want
@@ -1073,56 +840,40 @@ var ExpressServer = /** @class */ (function () {
      * @param middlewares One or more Express middleware functions
      * @returns This instance for method chaining
      */
-    ExpressServer.prototype.useMiddleware = function () {
-        var _this = this;
-        var middlewares = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            middlewares[_i] = arguments[_i];
-        }
-        middlewares.forEach(function (middleware) {
-            _this.app.use(middleware);
+    useMiddleware(...middlewares) {
+        middlewares.forEach(middleware => {
+            this.app.use(middleware);
         });
         return this;
-    };
+    }
     /**
      * Get Prometheus registry (to add custom counters/histograms)
      *
      * @return {*}  {client.Registry}
      */
-    ExpressServer.prototype.getMetricsRegistry = function () {
-        var _a;
-        if (!((_a = this.config.metrics) === null || _a === void 0 ? void 0 : _a.enable)) {
+    getMetricsRegistry() {
+        if (!this.config.metrics?.enable) {
             throw new Error('Metrics are not enabled in the server configuration');
         }
         return this.register;
-    };
+    }
     /**
      * Get server configuration
      *
      * @return {*}  {ServerConfig}
      */
-    ExpressServer.prototype.getConfig = function () {
+    getConfig() {
         return this.config;
-    };
+    }
     /**
      * Wait until server initialization (middleware + routes) has completed.
      * Useful for integration tests that inspect app before starting.
      */
-    ExpressServer.prototype.waitUntilReady = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.initPromise];
-                    case 1:
-                        _a.sent();
-                        return [2 /*return*/];
-                }
-            });
-        });
-    };
-    ExpressServer.prototype.normalizePath = function (path, withGlobalPrefix) {
-        if (withGlobalPrefix === void 0) { withGlobalPrefix = false; }
-        var sanitize = function (p) {
+    async waitUntilReady() {
+        await this.initPromise;
+    }
+    normalizePath(path, withGlobalPrefix = false) {
+        const sanitize = (p) => {
             return ('/' +
                 p
                     .trim()
@@ -1131,118 +882,82 @@ var ExpressServer = /** @class */ (function () {
                     .replace(/\/+$/, '')); // remove trailing slash
         };
         // Resolve global prefix if enabled
-        var prefix = withGlobalPrefix && this.globalPrefix ? sanitize(this.globalPrefix) : '';
+        const prefix = withGlobalPrefix && this.globalPrefix ? sanitize(this.globalPrefix) : '';
         // If path is invalid, default to prefix or root
         if (typeof path !== 'string' || !path.trim()) {
             return prefix || '/';
         }
         return sanitize(prefix + '/' + path);
-    };
-    ExpressServer.prototype.normalizeRouteForMetrics = function (req, res) {
-        var _a;
+    }
+    normalizeRouteForMetrics(req, res) {
         // Prevent high cardinality metrics by normalizing routes
-        if ((_a = req === null || req === void 0 ? void 0 : req.route) === null || _a === void 0 ? void 0 : _a.path) {
+        if (req?.route?.path) {
             // Use Express route pattern instead of actual URL
             return req.route.path;
         }
         // Group common patterns
         if (res.statusCode === 404)
             return '/404';
-        var path = (req.path || 'unknown').split('?')[0];
+        const path = (req.path || 'unknown').split('?')[0];
         // Replace IDs and UUIDs with placeholders
         return path
             .replace(/\/[0-9]+/g, '/:id')
             .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '/:uuid');
-    };
+    }
     /**
      * Destroy all active connections (gracefully if possible).
      * If a connection does not close cleanly, it will be force-destroyed.
      */
-    ExpressServer.prototype.destroyConnections = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var total, timeoutMs;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        total = this.connections.size;
-                        if (total === 0) {
-                            getLogger().debug('No active connections to close');
-                            return [2 /*return*/];
-                        }
-                        timeoutMs = 5000;
-                        return [4 /*yield*/, Promise.race([
-                                Promise.all(Array.from(this.connections).map(function (conn) {
-                                    return new Promise(function (resolve) {
-                                        conn.end(function () {
-                                            if (!conn.destroyed)
-                                                conn.destroy();
-                                            resolve();
-                                        });
-                                        conn.on('error', function () {
-                                            conn.destroy();
-                                            resolve();
-                                        });
-                                    });
-                                })),
-                                new Promise(function (resolve) { return setTimeout(resolve, timeoutMs); })
-                            ])];
-                    case 1:
-                        _a.sent();
-                        this.connections.clear();
-                        getLogger().info("Closed ".concat(total, " active connections"));
-                        return [2 /*return*/];
-                }
-            });
-        });
-    };
-    ExpressServer.prototype.validateHttpsFiles = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0: return [4 /*yield*/, fileExists(this.config.https.key)];
-                    case 1:
-                        if (!(_b.sent())) {
-                            getLogger().error("HTTPS key file not found: ".concat(this.config.https.key));
-                            process.exit(1);
-                        }
-                        return [4 /*yield*/, fileExists(this.config.https.cert)];
-                    case 2:
-                        if (!(_b.sent())) {
-                            getLogger().error("HTTPS cert file not found: ".concat(this.config.https.cert));
-                            process.exit(1);
-                        }
-                        _a = this.config.https.ca;
-                        if (!_a) return [3 /*break*/, 4];
-                        return [4 /*yield*/, fileExists(this.config.https.ca)];
-                    case 3:
-                        _a = !(_b.sent());
-                        _b.label = 4;
-                    case 4:
-                        if (_a) {
-                            getLogger().error("HTTPS CA file not found: ".concat(this.config.https.ca));
-                            process.exit(1);
-                        }
-                        return [2 /*return*/];
-                }
-            });
-        });
-    };
-    ExpressServer.isBuiltServerConfig = function (config) {
+    async destroyConnections() {
+        const total = this.connections.size;
+        if (total === 0) {
+            getLogger().debug('No active connections to close');
+            return;
+        }
+        const timeoutMs = 5000;
+        await Promise.race([
+            Promise.all(Array.from(this.connections).map(conn => new Promise(resolve => {
+                conn.end(() => {
+                    if (!conn.destroyed)
+                        conn.destroy();
+                    resolve();
+                });
+                conn.on('error', () => {
+                    conn.destroy();
+                    resolve();
+                });
+            }))),
+            new Promise(resolve => setTimeout(resolve, timeoutMs))
+        ]);
+        this.connections.clear();
+        getLogger().info(`Closed ${total} active connections`);
+    }
+    async validateHttpsFiles() {
+        if (!(await fileExists(this.config.https.key))) {
+            getLogger().error(`HTTPS key file not found: ${this.config.https.key}`);
+            process.exit(1);
+        }
+        if (!(await fileExists(this.config.https.cert))) {
+            getLogger().error(`HTTPS cert file not found: ${this.config.https.cert}`);
+            process.exit(1);
+        }
+        if (this.config.https.ca && !(await fileExists(this.config.https.ca))) {
+            getLogger().error(`HTTPS CA file not found: ${this.config.https.ca}`);
+            process.exit(1);
+        }
+    }
+    static isBuiltServerConfig(config) {
         if (config[BUILD_MARKER]) {
             return true;
         }
         return false;
-    };
-    ExpressServer.optionalRequire = function (name) {
+    }
+    static optionalRequire(name) {
         try {
             return require(name);
         }
-        catch (_a) {
+        catch {
             return null;
         }
-    };
-    return ExpressServer;
-}());
-export { ExpressServer };
-//# sourceMappingURL=server.js.map
+    }
+}