@catbee/utils 2.0.0-next.1 → 2.0.1

package/response/index.mjs

@@ -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

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
@@ -33,7 +33,7 @@ var env = require('@catbee/utils/env');
 var logger = require('@catbee/utils/logger');
 var exception = require('@catbee/utils/exception');
 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 validation = require('@catbee/utils/validation');
 var async = require('@catbee/utils/async');
@@ -611,7 +611,7 @@ var ServerConfigBuilder = class {
   * ```
   */
   withCustom(overrides) {
-    this.config = obj.deepObjMerge({}, this.config, overrides);
+    this.config = object.deepObjMerge({}, this.config, overrides);
     return this;
   }
   /**
@@ -651,7 +651,7 @@ var ServerConfigBuilder = class {
   * ```
   */
   build() {
-    const config$1 = obj.deepObjMerge({}, config.getCatbeeServerGlobalConfig(), 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");
     }
@@ -661,8 +661,8 @@ var ServerConfigBuilder = class {
     });
   }
   mergeConfig(key, value) {
-    const current = this.config[key] && typeof this.config[key] === "object" ? obj.deepClone(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, {
@@ -744,7 +744,7 @@ var ExpressServer = class {
     if (this.hasBuildMarker(config$1)) {
       this.config = config$1;
     } else {
-      this.config = obj.deepObjMerge({}, config.getCatbeeServerGlobalConfig(), config$1);
+      this.config = object.deepObjMerge({}, config.getCatbeeServerGlobalConfig(), config$1);
     }
     if (!validation.isPort(this.config.port)) {
       const msg = `Port must be a valid number between 1 and 65535, got: ${this.config.port}`;
@@ -860,6 +860,7 @@ var ExpressServer = class {
   async initialize() {
     await this.runHook("beforeInit", this);
     await this.setupMiddleware();
+    await this.runHook("beforeRoutes", this.app);
     await this.setupRoutes();
     await this.runHook("afterInit", this);
   }
@@ -886,6 +887,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);
@@ -902,11 +921,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) {
@@ -925,6 +948,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) {
@@ -941,15 +969,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) {
@@ -967,6 +1010,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") {
@@ -990,6 +1038,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) {
@@ -1001,6 +1054,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, {
@@ -1013,6 +1071,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));
@@ -1021,6 +1084,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) {
@@ -1032,6 +1100,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);
@@ -1072,6 +1145,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();
@@ -1120,45 +1198,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.getCatbeeServerGlobalConfig().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);
@@ -1169,6 +1209,7 @@ var ExpressServer = class {
     }
     const routerToUse = this.externalRouter || this.rootRouter;
     this.app.use(this.globalPrefix, routerToUse);
+    await this.runHook("afterRoutes", this.app);
     this.app.use((req, res) => {
       const status = httpStatusCodes.HttpStatusCodes.NOT_FOUND;
       const response$1 = response.createFinalErrorResponse(req, status, `Route ${req.method.toUpperCase()} ${req.path} not found`);
@@ -1190,6 +1231,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
@@ -1220,28 +1311,8 @@ var ExpressServer = class {
   */
   async ready() {
     try {
-      if (!this.healthChecks.length || config.getCatbeeServerGlobalConfig().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({
@@ -1286,58 +1357,83 @@ 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.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__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.runHook("onServerCreated", this.server);
+        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:
@@ -1364,6 +1460,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) => {
@@ -1382,21 +1495,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.

package/server/index.d.ts

@@ -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
@@ -138,6 +138,58 @@ declare class ExpressServer {
      * 14. Custom response hooks
      */
     protected setupMiddleware(): Promise<void>;
+    /**
+     * Set up basic middleware (trust proxy, request ID, context).
+     */
+    private setupBasicMiddleware;
+    /**
+     * Set up security middleware (Helmet, CORS).
+     */
+    private setupSecurityMiddleware;
+    /**
+     * Set up global headers middleware.
+     */
+    private setupGlobalHeaders;
+    /**
+     * Set up request timeout middleware.
+     */
+    private setupTimeoutMiddleware;
+    /**
+     * Set up response time tracking middleware.
+     */
+    private setupResponseTimeMiddleware;
+    /**
+     * Set up rate limiting middleware.
+     */
+    private setupRateLimitingMiddleware;
+    /**
+     * Set up request logging middleware.
+     */
+    private setupRequestLoggingMiddleware;
+    /**
+     * Set up response compression middleware.
+     */
+    private setupCompressionMiddleware;
+    /**
+     * Set up static file serving middleware.
+     */
+    private setupStaticFilesMiddleware;
+    /**
+     * Set up body parsing middleware.
+     */
+    private setupBodyParsingMiddleware;
+    /**
+     * Set up cookie parsing middleware.
+     */
+    private setupCookieParsingMiddleware;
+    /**
+     * Set up OpenAPI documentation middleware.
+     */
+    private setupOpenApiMiddleware;
+    /**
+     * Set up metrics tracking middleware.
+     */
+    private setupMetricsMiddleware;
     /**
      * Configure server routes and error handling.
      * Sets up in following order:
@@ -148,6 +200,14 @@ declare class ExpressServer {
      * 4. Error handler
      */
     protected setupRoutes(): Promise<void>;
+    /**
+     * Execute health check and return response.
+     */
+    private handleHealthCheckRequest;
+    /**
+     * Execute all registered health checks and return results.
+     */
+    private executeHealthChecks;
     /**
      * Register a new health check function for monitoring service dependencies.
      *
@@ -200,6 +260,22 @@ declare class ExpressServer {
      * @throws Error if server fails to start or port is already in use
      */
     start(): Promise<http.Server | https.Server>;
+    /**
+     * Create HTTP or HTTPS server instance.
+     */
+    private createServerInstance;
+    /**
+     * Set up connection tracking for graceful shutdown.
+     */
+    private setupConnectionTracking;
+    /**
+     * Set up error handling for server startup.
+     */
+    private setupServerErrorHandling;
+    /**
+     * Log server startup information.
+     */
+    private logServerStartInfo;
     /**
      * Stop the HTTP server gracefully.
      *
@@ -217,6 +293,10 @@ declare class ExpressServer {
      * - Monitoring systems are notified
      */
     stop(force?: boolean): Promise<void>;
+    /**
+     * Perform graceful server shutdown with timeout.
+     */
+    private gracefulShutdown;
     /**
      * Enable graceful shutdown on OS signals for production deployment.
      *