@catbee/utils 2.0.0-next.0 → 2.0.0

package/server/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
@@ -25,17 +25,17 @@
 import express from 'express';
 import https from 'https';
 import { HttpStatusCodes } from '@catbee/utils/http-status-codes';
-import { SuccessResponse, createFinalErrorResponse } from '@catbee/utils/response';
+import { createFinalErrorResponse, SuccessResponse } from '@catbee/utils/response';
 import { requestId, setupRequestContext, timeout, responseTime, errorHandler } from '@catbee/utils/middleware';
 import { Env } from '@catbee/utils/env';
 import { getLogger } from '@catbee/utils/logger';
 import { ServiceUnavailableException, InternalServerErrorException, NotFoundException } from '@catbee/utils/exception';
-import fs from 'fs';
-import { defaultServerConfig, defaultCatbeeConfig } from '@catbee/utils/config';
-import { deepObjMerge } from '@catbee/utils/obj';
-import { fileExists } from '@catbee/utils/fs';
-import { isPort } from '@catbee/utils/validate';
+import { getCatbeeServerGlobalConfig } from '@catbee/utils/config';
+import { deepObjMerge, deepClone } from '@catbee/utils/object';
+import { fileExists, readFile, readFileSync } from '@catbee/utils/fs';
+import { isPort } from '@catbee/utils/validation';
 import { optionalRequire } from '@catbee/utils/async';
+import { uuid } from '@catbee/utils/id';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -498,7 +498,10 @@ var ServerConfigBuilder = class {
   * ```
   */
   withBodyParser(opts) {
-    this.config.bodyParser = deepObjMerge({}, this.config.bodyParser ?? {}, opts);
+    this.config.bodyParser = {
+      ...this.config.bodyParser,
+      ...opts
+    };
     return this;
   }
   /**
@@ -641,7 +644,7 @@ var ServerConfigBuilder = class {
   * ```
   */
   build() {
-    const config = deepObjMerge({}, defaultServerConfig, this.config);
+    const config = deepObjMerge({}, getCatbeeServerGlobalConfig(), this.config);
     if (config.openApi?.enable && !config.openApi.filePath) {
       throw new Error("OpenAPI is enabled but no filePath is specified");
     }
@@ -651,7 +654,7 @@ var ServerConfigBuilder = class {
     });
   }
   mergeConfig(key, value) {
-    const current = typeof this.config[key] === "object" && this.config[key] !== null ? this.config[key] : {};
+    const current = this.config[key] && typeof this.config[key] === "object" ? deepClone(this.config[key]) : {};
     this.config[key] = deepObjMerge({}, current, value);
   }
   setEnabled(key, enable, overrides = {}) {
@@ -662,9 +665,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"),
@@ -729,10 +734,10 @@ var ExpressServer = class {
   * - Request tracing
   */
   constructor(config, hooks = {}) {
-    if (this.isBuiltServerConfig(config)) {
+    if (this.hasBuildMarker(config)) {
       this.config = config;
     } else {
-      this.config = deepObjMerge({}, defaultServerConfig, config);
+      this.config = deepObjMerge({}, getCatbeeServerGlobalConfig(), config);
     }
     if (!isPort(this.config.port)) {
       const msg = `Port must be a valid number between 1 and 65535, got: ${this.config.port}`;
@@ -834,7 +839,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) {
       getLogger().error({
         err,
@@ -874,6 +879,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);
@@ -881,7 +904,7 @@ var ExpressServer = class {
     this.app.use(requestId({
       headerName: this.config.requestId?.headerName,
       exposeHeader: this.config.requestId?.exposeHeader,
-      generator: this.config.requestId?.generator
+      generator: this.config.requestId?.generator || uuid
     }));
     this.app.use(setupRequestContext({
       headerName: this.config.requestId?.headerName,
@@ -890,11 +913,15 @@ var ExpressServer = class {
     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"));
+        res.status(HttpStatusCodes.SERVICE_UNAVAILABLE).json(new ServiceUnavailableException("Server is shutting down"));
       }
       next();
-      return;
     });
+  }
+  /**
+  * Set up security middleware (Helmet, CORS).
+  */
+  setupSecurityMiddleware() {
     if (this.config.helmet) {
       const helmet = optionalRequire("helmet");
       if (!helmet) {
@@ -913,6 +940,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) {
@@ -929,15 +961,30 @@ var ExpressServer = class {
       }
       next();
     });
+  }
+  /**
+  * Set up request timeout middleware.
+  */
+  setupTimeoutMiddleware() {
     if (this.config.requestTimeout) {
       this.app.use(timeout(this.config.requestTimeout));
     }
+  }
+  /**
+  * Set up response time tracking middleware.
+  */
+  setupResponseTimeMiddleware() {
     if (this.config.responseTime?.enable) {
       this.app.use(responseTime({
         addHeader: this.config.responseTime.addHeader,
         logOnComplete: this.config.responseTime.logOnComplete
       }));
     }
+  }
+  /**
+  * Set up rate limiting middleware.
+  */
+  setupRateLimitingMiddleware() {
     if (this.config.rateLimit?.enable) {
       const rateLimit = optionalRequire("express-rate-limit");
       if (!rateLimit) {
@@ -955,6 +1002,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") {
@@ -978,6 +1030,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 = optionalRequire("compression");
       if (!compression) {
@@ -989,6 +1046,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.static(folder.directory, {
@@ -1001,6 +1063,11 @@ var ExpressServer = class {
         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.json(this.config.bodyParser.json));
@@ -1009,6 +1076,11 @@ var ExpressServer = class {
         this.app.use(express.urlencoded(this.config.bodyParser.urlencoded));
       }
     }
+  }
+  /**
+  * Set up cookie parsing middleware.
+  */
+  setupCookieParsingMiddleware() {
     if (this.config.cookieParser) {
       const cookieParser = optionalRequire("cookie-parser");
       if (!cookieParser) {
@@ -1020,6 +1092,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);
@@ -1045,7 +1122,7 @@ var ExpressServer = class {
         }
         this.app.use(openApiMountPath, apiReference({
           spec: {
-            content: await fs.promises.readFile(openApiFilePath, "utf8")
+            content: await readFile(openApiFilePath, "utf8")
           }
         }));
         if (this.config.openApi?.verbose) {
@@ -1060,6 +1137,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();
@@ -1108,45 +1190,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 || defaultCatbeeConfig.server.skipHealthz) {
-          return res.status(HttpStatusCodes.OK).json(new 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.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"));
-      }
+      return this.handleHealthCheckRequest(res);
     });
     if (this.config.metrics?.enable) {
       const metricsPath = this.normalizePath(this.config.metrics.path ?? "/metrics", this.config.metrics?.withGlobalPrefix);
@@ -1178,6 +1222,56 @@ var ExpressServer = class {
     });
   }
   /**
+  * Execute health check and return response.
+  */
+  async handleHealthCheckRequest(res) {
+    try {
+      if (!this.healthChecks.length || getCatbeeServerGlobalConfig().skipHealthzChecksValidation) {
+        return res.status(HttpStatusCodes.OK).json(new SuccessResponse("OK"));
+      }
+      const results = await this.executeHealthChecks();
+      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"));
+    }
+  }
+  /**
+  * 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
@@ -1208,28 +1302,8 @@ var ExpressServer = class {
   */
   async ready() {
     try {
-      if (!this.healthChecks.length || 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 || getCatbeeServerGlobalConfig().skipHealthzChecksValidation) return true;
+      const results = await this.executeHealthChecks();
       return results.every((r) => r.status === true);
     } catch (err) {
       getLogger().error({
@@ -1274,58 +1348,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}`;
-            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 {
-          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) => {
-          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: readFileSync(this.config.https.key),
+        cert: readFileSync(this.config.https.cert)
+      };
+      if (this.config.https.ca) {
+        httpsOptions.ca = readFileSync(this.config.https.ca);
+      }
+      if (this.config.https.passphrase) {
+        httpsOptions.passphrase = this.config.https.passphrase;
+      }
+      return https.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) => {
+      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}`;
+    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)}`);
+    }
+  }
+  /**
   * Stop the HTTP server gracefully.
   *
   * This method:
@@ -1352,6 +1450,23 @@ var ExpressServer = class {
     }
     this.isShuttingDown = true;
     await this.runHook("beforeStop", this.server);
+    try {
+      await this.gracefulShutdown();
+    } catch (err) {
+      getLogger().error({
+        err
+      }, "Graceful shutdown timed out");
+      if (force) {
+        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) => {
@@ -1370,21 +1485,10 @@ var ExpressServer = class {
       });
     });
     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 {
-      await this.destroyConnections();
-    }
+    await Promise.race([
+      serverClosePromise,
+      timeoutPromise
+    ]);
   }
   /**
   * Enable graceful shutdown on OS signals for production deployment.
@@ -1526,7 +1630,7 @@ var ExpressServer = class {
   /**
   * Get server configuration
   *
-  * @return {*}  {ServerConfig}
+  * @return {*}  {CatbeeServerConfig}
   */
   getConfig() {
     return this.config;
@@ -1600,7 +1704,7 @@ var ExpressServer = class {
       throw new Error(msg);
     }
   }
-  isBuiltServerConfig(config) {
+  hasBuildMarker(config) {
     if (config?.[BUILD_MARKER]) {
       return true;
     }

package/stream/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