@catbee/utils 2.0.0-next.0 → 2.0.0

package/server/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -32,18 +32,17 @@ var middleware = require('@catbee/utils/middleware');
 var env = require('@catbee/utils/env');
 var logger = require('@catbee/utils/logger');
 var exception = require('@catbee/utils/exception');
-var fs$1 = require('fs');
 var config = require('@catbee/utils/config');
-var obj = require('@catbee/utils/obj');
+var object = require('@catbee/utils/object');
 var fs = require('@catbee/utils/fs');
-var validate = require('@catbee/utils/validate');
+var validation = require('@catbee/utils/validation');
 var async = require('@catbee/utils/async');
+var id = require('@catbee/utils/id');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var express__default = /*#__PURE__*/_interopDefault(express);
 var https__default = /*#__PURE__*/_interopDefault(https);
-var fs__default = /*#__PURE__*/_interopDefault(fs$1);
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -61,7 +60,7 @@ var ServerConfigBuilder = class {
   * @throws {Error} If port is not an integer or is outside the valid range (1-65535)
   */
   validatePort(port) {
-    if (!validate.isPort(port)) {
+    if (!validation.isPort(port)) {
       throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);
     }
   }
@@ -506,7 +505,10 @@ var ServerConfigBuilder = class {
   * ```
   */
   withBodyParser(opts) {
-    this.config.bodyParser = obj.deepObjMerge({}, this.config.bodyParser ?? {}, opts);
+    this.config.bodyParser = {
+      ...this.config.bodyParser,
+      ...opts
+    };
     return this;
   }
   /**
@@ -609,7 +611,7 @@ var ServerConfigBuilder = class {
   * ```
   */
   withCustom(overrides) {
-    this.config = obj.deepObjMerge({}, this.config, overrides);
+    this.config = object.deepObjMerge({}, this.config, overrides);
     return this;
   }
   /**
@@ -649,7 +651,7 @@ var ServerConfigBuilder = class {
   * ```
   */
   build() {
-    const config$1 = obj.deepObjMerge({}, config.defaultServerConfig, this.config);
+    const config$1 = object.deepObjMerge({}, config.getCatbeeServerGlobalConfig(), this.config);
     if (config$1.openApi?.enable && !config$1.openApi.filePath) {
       throw new Error("OpenAPI is enabled but no filePath is specified");
     }
@@ -659,8 +661,8 @@ var ServerConfigBuilder = class {
     });
   }
   mergeConfig(key, value) {
-    const current = typeof this.config[key] === "object" && this.config[key] !== null ? this.config[key] : {};
-    this.config[key] = obj.deepObjMerge({}, current, value);
+    const current = this.config[key] && typeof this.config[key] === "object" ? object.deepClone(this.config[key]) : {};
+    this.config[key] = object.deepObjMerge({}, current, value);
   }
   setEnabled(key, enable, overrides = {}) {
     this.mergeConfig(key, {
@@ -670,9 +672,11 @@ var ServerConfigBuilder = class {
     return this;
   }
 };
-
-// src/server/server.ts
-var getDependencyErrorMessage = /* @__PURE__ */ __name((packageName, x) => `Missing required dependency ${x ? `for ${x}` : ""}: ${packageName}. Please install it to proceed.`, "getDependencyErrorMessage");
+var getDependencyErrorMessage = /* @__PURE__ */ __name((packageName, context) => {
+  const ctxPart = context ? `for ${context}` : "";
+  const spacer = ctxPart ? ` ${ctxPart}` : "";
+  return `Missing required dependency${spacer}: ${packageName}. Please install it to proceed.`;
+}, "getDependencyErrorMessage");
 var DependencyErrors = {
   express: getDependencyErrorMessage("express"),
   helmet: getDependencyErrorMessage("helmet"),
@@ -737,12 +741,12 @@ var ExpressServer = class {
   * - Request tracing
   */
   constructor(config$1, hooks = {}) {
-    if (this.isBuiltServerConfig(config$1)) {
+    if (this.hasBuildMarker(config$1)) {
       this.config = config$1;
     } else {
-      this.config = obj.deepObjMerge({}, config.defaultServerConfig, config$1);
+      this.config = object.deepObjMerge({}, config.getCatbeeServerGlobalConfig(), config$1);
     }
-    if (!validate.isPort(this.config.port)) {
+    if (!validation.isPort(this.config.port)) {
       const msg = `Port must be a valid number between 1 and 65535, got: ${this.config.port}`;
       logger.getLogger().error(msg);
       throw new Error(msg);
@@ -842,7 +846,7 @@ var ExpressServer = class {
   async runHook(hook, ...args) {
     try {
       const fn = this.hooks[hook];
-      if (fn) await fn.apply(null, args);
+      if (fn) await fn(...args);
     } catch (err) {
       logger.getLogger().error({
         err,
@@ -882,6 +886,24 @@ var ExpressServer = class {
     if (this.config.https) {
       await this.validateHttpsFiles();
     }
+    this.setupBasicMiddleware();
+    this.setupSecurityMiddleware();
+    this.setupGlobalHeaders();
+    this.setupTimeoutMiddleware();
+    this.setupResponseTimeMiddleware();
+    this.setupRateLimitingMiddleware();
+    this.setupRequestLoggingMiddleware();
+    this.setupCompressionMiddleware();
+    this.setupStaticFilesMiddleware();
+    this.setupBodyParsingMiddleware();
+    this.setupCookieParsingMiddleware();
+    await this.setupOpenApiMiddleware();
+    this.setupMetricsMiddleware();
+  }
+  /**
+  * Set up basic middleware (trust proxy, request ID, context).
+  */
+  setupBasicMiddleware() {
     this.app.disable("x-powered-by");
     if (this.config.trustProxy) {
       this.app.set("trust proxy", true);
@@ -889,7 +911,7 @@ var ExpressServer = class {
     this.app.use(middleware.requestId({
       headerName: this.config.requestId?.headerName,
       exposeHeader: this.config.requestId?.exposeHeader,
-      generator: this.config.requestId?.generator
+      generator: this.config.requestId?.generator || id.uuid
     }));
     this.app.use(middleware.setupRequestContext({
       headerName: this.config.requestId?.headerName,
@@ -898,11 +920,15 @@ var ExpressServer = class {
     this.app.use((_req, res, next) => {
       if (this.isShuttingDown) {
         res.setHeader("Connection", "close");
-        return res.status(httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE).json(new exception.ServiceUnavailableException("Server is shutting down"));
+        res.status(httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE).json(new exception.ServiceUnavailableException("Server is shutting down"));
       }
       next();
-      return;
     });
+  }
+  /**
+  * Set up security middleware (Helmet, CORS).
+  */
+  setupSecurityMiddleware() {
     if (this.config.helmet) {
       const helmet = async.optionalRequire("helmet");
       if (!helmet) {
@@ -921,6 +947,11 @@ var ExpressServer = class {
       }
       this.app.use(cors(this.config.cors === true ? {} : this.config.cors));
     }
+  }
+  /**
+  * Set up global headers middleware.
+  */
+  setupGlobalHeaders() {
     this.app.use((_req, res, next) => {
       if (this.config.globalHeaders) {
         for (const key in this.config.globalHeaders) {
@@ -937,15 +968,30 @@ var ExpressServer = class {
       }
       next();
     });
+  }
+  /**
+  * Set up request timeout middleware.
+  */
+  setupTimeoutMiddleware() {
     if (this.config.requestTimeout) {
       this.app.use(middleware.timeout(this.config.requestTimeout));
     }
+  }
+  /**
+  * Set up response time tracking middleware.
+  */
+  setupResponseTimeMiddleware() {
     if (this.config.responseTime?.enable) {
       this.app.use(middleware.responseTime({
         addHeader: this.config.responseTime.addHeader,
         logOnComplete: this.config.responseTime.logOnComplete
       }));
     }
+  }
+  /**
+  * Set up rate limiting middleware.
+  */
+  setupRateLimitingMiddleware() {
     if (this.config.rateLimit?.enable) {
       const rateLimit = async.optionalRequire("express-rate-limit");
       if (!rateLimit) {
@@ -963,6 +1009,11 @@ var ExpressServer = class {
         legacyHeaders: this.config.rateLimit.legacyHeaders ?? false
       }));
     }
+  }
+  /**
+  * Set up request logging middleware.
+  */
+  setupRequestLoggingMiddleware() {
     if (this.config.requestLogging?.enable) {
       this.app.use((req, res, next) => {
         if (typeof this.config.requestLogging?.ignorePaths === "function") {
@@ -986,6 +1037,11 @@ var ExpressServer = class {
     if (this.hooks.onRequest) {
       this.app.use(this.hooks.onRequest);
     }
+  }
+  /**
+  * Set up response compression middleware.
+  */
+  setupCompressionMiddleware() {
     if (this.config.compression) {
       const compression = async.optionalRequire("compression");
       if (!compression) {
@@ -997,6 +1053,11 @@ var ExpressServer = class {
         this.app.use(compression());
       }
     }
+  }
+  /**
+  * Set up static file serving middleware.
+  */
+  setupStaticFilesMiddleware() {
     if (this.config.staticFolders) {
       this.config.staticFolders.forEach((folder) => {
         this.app.use(this.normalizePath(folder.path ?? "/"), express__default.default.static(folder.directory, {
@@ -1009,6 +1070,11 @@ var ExpressServer = class {
         logger.getLogger().info(`Serving static folder: ${folder.directory} at path ${folder.path || "/"}`);
       });
     }
+  }
+  /**
+  * Set up body parsing middleware.
+  */
+  setupBodyParsingMiddleware() {
     if (this.config.bodyParser) {
       if (this.config.bodyParser.json) {
         this.app.use(express__default.default.json(this.config.bodyParser.json));
@@ -1017,6 +1083,11 @@ var ExpressServer = class {
         this.app.use(express__default.default.urlencoded(this.config.bodyParser.urlencoded));
       }
     }
+  }
+  /**
+  * Set up cookie parsing middleware.
+  */
+  setupCookieParsingMiddleware() {
     if (this.config.cookieParser) {
       const cookieParser = async.optionalRequire("cookie-parser");
       if (!cookieParser) {
@@ -1028,6 +1099,11 @@ var ExpressServer = class {
         this.app.use(cookieParser());
       }
     }
+  }
+  /**
+  * Set up OpenAPI documentation middleware.
+  */
+  async setupOpenApiMiddleware() {
     if (this.config.openApi?.enable) {
       try {
         const openApiMountPath = this.normalizePath(this.config.openApi.mountPath ?? "/docs", this.config.openApi.withGlobalPrefix);
@@ -1053,7 +1129,7 @@ var ExpressServer = class {
         }
         this.app.use(openApiMountPath, apiReference({
           spec: {
-            content: await fs__default.default.promises.readFile(openApiFilePath, "utf8")
+            content: await fs.readFile(openApiFilePath, "utf8")
           }
         }));
         if (this.config.openApi?.verbose) {
@@ -1068,6 +1144,11 @@ var ExpressServer = class {
     if (this.hooks.onResponse) {
       this.app.use(this.globalPrefix, this.hooks.onResponse);
     }
+  }
+  /**
+  * Set up metrics tracking middleware.
+  */
+  setupMetricsMiddleware() {
     if (this.config.metrics?.enable) {
       this.app.use((req, res, next) => {
         const start = process.hrtime();
@@ -1116,45 +1197,7 @@ var ExpressServer = class {
   async setupRoutes() {
     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 || config.defaultCatbeeConfig.server.skipHealthz) {
-          return res.status(httpStatusCodes.HttpStatusCodes.OK).json(new response.SuccessResponse("OK"));
-        }
-        const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
-          try {
-            const status2 = await Promise.resolve(check());
-            return {
-              name,
-              status: status2,
-              error: null
-            };
-          } 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
-          };
-        });
-        const allOk = results.every((r) => r.status);
-        const status = allOk ? httpStatusCodes.HttpStatusCodes.OK : httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE;
-        const response$1 = new response.SuccessResponse(allOk ? "OK" : "Service unavailable");
-        if (!allOk) response$1.error = true;
-        if (this.config.healthCheck?.detailed) response$1.data = {
-          checks: results
-        };
-        return res.status(status).json(response$1);
-      } catch {
-        return res.status(httpStatusCodes.HttpStatusCodes.INTERNAL_SERVER_ERROR).json(new exception.InternalServerErrorException("Health check failed"));
-      }
+      return this.handleHealthCheckRequest(res);
     });
     if (this.config.metrics?.enable) {
       const metricsPath = this.normalizePath(this.config.metrics.path ?? "/metrics", this.config.metrics?.withGlobalPrefix);
@@ -1186,6 +1229,56 @@ var ExpressServer = class {
     });
   }
   /**
+  * Execute health check and return response.
+  */
+  async handleHealthCheckRequest(res) {
+    try {
+      if (!this.healthChecks.length || config.getCatbeeServerGlobalConfig().skipHealthzChecksValidation) {
+        return res.status(httpStatusCodes.HttpStatusCodes.OK).json(new response.SuccessResponse("OK"));
+      }
+      const results = await this.executeHealthChecks();
+      const allOk = results.every((r) => r.status);
+      const status = allOk ? httpStatusCodes.HttpStatusCodes.OK : httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE;
+      const response$1 = new response.SuccessResponse(allOk ? "OK" : "Service unavailable");
+      if (!allOk) response$1.error = true;
+      if (this.config.healthCheck?.detailed) response$1.data = {
+        checks: results
+      };
+      return res.status(status).json(response$1);
+    } catch {
+      return res.status(httpStatusCodes.HttpStatusCodes.INTERNAL_SERVER_ERROR).json(new exception.InternalServerErrorException("Health check failed"));
+    }
+  }
+  /**
+  * Execute all registered health checks and return results.
+  */
+  async executeHealthChecks() {
+    const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
+      try {
+        const status = await Promise.resolve(check());
+        return {
+          name,
+          status,
+          error: null
+        };
+      } catch (error) {
+        return {
+          name,
+          status: false,
+          error: error.message
+        };
+      }
+    }));
+    return checkResults.map((result) => {
+      if (result.status === "fulfilled") return result.value;
+      return {
+        name: "unknown",
+        status: false,
+        error: result.reason
+      };
+    });
+  }
+  /**
   * Register a new health check function for monitoring service dependencies.
   *
   * Health checks are executed when the health endpoint is accessed and
@@ -1216,28 +1309,8 @@ var ExpressServer = class {
   */
   async ready() {
     try {
-      if (!this.healthChecks.length || config.defaultCatbeeConfig.server.skipHealthz) return true;
-      const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
-        try {
-          const status = await Promise.resolve(check());
-          return {
-            name,
-            status,
-            error: null
-          };
-        } catch (error) {
-          return {
-            name,
-            status: false,
-            error: error.message
-          };
-        }
-      }));
-      const results = checkResults.map((result) => result.status === "fulfilled" ? result.value : {
-        name: "unknown",
-        status: false,
-        error: result.reason
-      });
+      if (!this.healthChecks.length || config.getCatbeeServerGlobalConfig().skipHealthzChecksValidation) return true;
+      const results = await this.executeHealthChecks();
       return results.every((r) => r.status === true);
     } catch (err) {
       logger.getLogger().error({
@@ -1282,58 +1355,82 @@ var ExpressServer = class {
     await this.runHook("beforeStart", this.app);
     return new Promise((resolve, reject) => {
       try {
-        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}`;
-            logger.getLogger().info(`Server running on ${url}`);
-            if (this.config.healthCheck?.path) {
-              logger.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) {
-              logger.getLogger().info(`Metrics available at ${url}${this.normalizePath(this.config.metrics.path, this.config.metrics.withGlobalPrefix)}`);
-            }
-            if (this.config.openApi?.enable) {
-              logger.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__default.default.readFileSync(this.config.https.key),
-            cert: fs__default.default.readFileSync(this.config.https.cert)
-          };
-          if (this.config.https.ca) {
-            httpsOptions.ca = fs__default.default.readFileSync(this.config.https.ca);
-          }
-          if (this.config.https.passphrase) {
-            httpsOptions.passphrase = this.config.https.passphrase;
-          }
-          this.server = https__default.default.createServer(httpsOptions, this.app).listen(...listenArgs);
-        } else {
-          this.server = this.app.listen(...listenArgs);
-        }
-        this.server.on("connection", (conn) => {
-          this.connections.add(conn);
-          conn.on("close", () => this.connections.delete(conn));
-        });
-        this.server.on("error", (err) => {
-          logger.getLogger().error({
-            err
-          }, "Server failed to start");
-          reject(err);
-        });
+        const onListening = /* @__PURE__ */ __name(async () => {
+          this.logServerStartInfo();
+          if (this.server) await this.runHook("afterStart", this.server);
+          resolve(this.server);
+        }, "onListening");
+        this.server = this.createServerInstance(onListening);
+        this.setupConnectionTracking();
+        this.setupServerErrorHandling(reject);
       } catch (error) {
         reject(error);
       }
     });
   }
   /**
+  * Create HTTP or HTTPS server instance.
+  */
+  createServerInstance(onListening) {
+    const listenArgs = [
+      this.config.port,
+      this.config.host,
+      onListening
+    ];
+    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;
+      }
+      return https__default.default.createServer(httpsOptions, this.app).listen(...listenArgs);
+    }
+    return this.app.listen(...listenArgs);
+  }
+  /**
+  * Set up connection tracking for graceful shutdown.
+  */
+  setupConnectionTracking() {
+    this.server.on("connection", (conn) => {
+      this.connections.add(conn);
+      conn.on("close", () => this.connections.delete(conn));
+    });
+  }
+  /**
+  * Set up error handling for server startup.
+  */
+  setupServerErrorHandling(reject) {
+    this.server.on("error", (err) => {
+      logger.getLogger().error({
+        err
+      }, "Server failed to start");
+      reject(err);
+    });
+  }
+  /**
+  * Log server startup information.
+  */
+  logServerStartInfo() {
+    const protocol = this.config.https ? "https" : "http";
+    const url = `${protocol}://${this.config.host}:${this.config.port}`;
+    logger.getLogger().info(`Server running on ${url}`);
+    if (this.config.healthCheck?.path) {
+      logger.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) {
+      logger.getLogger().info(`Metrics available at ${url}${this.normalizePath(this.config.metrics.path, this.config.metrics.withGlobalPrefix)}`);
+    }
+    if (this.config.openApi?.enable) {
+      logger.getLogger().info(`API docs available at ${url}${this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)}`);
+    }
+  }
+  /**
   * Stop the HTTP server gracefully.
   *
   * This method:
@@ -1360,6 +1457,23 @@ var ExpressServer = class {
     }
     this.isShuttingDown = true;
     await this.runHook("beforeStop", this.server);
+    try {
+      await this.gracefulShutdown();
+    } catch (err) {
+      logger.getLogger().error({
+        err
+      }, "Graceful shutdown timed out");
+      if (force) {
+        logger.getLogger().warn("Forcing connection destroy due to shutdown timeout");
+      }
+    } finally {
+      await this.destroyConnections();
+    }
+  }
+  /**
+  * Perform graceful server shutdown with timeout.
+  */
+  async gracefulShutdown() {
     const shutdownTimeout = 1e4;
     const serverClosePromise = new Promise((resolve, reject) => {
       this.server.close(async (err) => {
@@ -1378,21 +1492,10 @@ var ExpressServer = class {
       });
     });
     const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Shutdown timeout")), shutdownTimeout));
-    try {
-      await Promise.race([
-        serverClosePromise,
-        timeoutPromise
-      ]);
-    } catch (err) {
-      logger.getLogger().error({
-        err
-      }, "Graceful shutdown timed out");
-      if (force) {
-        logger.getLogger().warn("Forcing connection destroy due to shutdown timeout");
-      }
-    } finally {
-      await this.destroyConnections();
-    }
+    await Promise.race([
+      serverClosePromise,
+      timeoutPromise
+    ]);
   }
   /**
   * Enable graceful shutdown on OS signals for production deployment.
@@ -1534,7 +1637,7 @@ var ExpressServer = class {
   /**
   * Get server configuration
   *
-  * @return {*}  {ServerConfig}
+  * @return {*}  {CatbeeServerConfig}
   */
   getConfig() {
     return this.config;
@@ -1608,7 +1711,7 @@ var ExpressServer = class {
       throw new Error(msg);
     }
   }
-  isBuiltServerConfig(config) {
+  hasBuildMarker(config) {
     if (config?.[BUILD_MARKER]) {
       return true;
     }