@catbee/utils 2.0.0 → 2.0.2

package/server/index.mjs

@@ -31,9 +31,9 @@ import { Env } from '@catbee/utils/env';
 import { getLogger } from '@catbee/utils/logger';
 import { ServiceUnavailableException, InternalServerErrorException, NotFoundException } from '@catbee/utils/exception';
 import { getCatbeeServerGlobalConfig } from '@catbee/utils/config';
-import { deepObjMerge, deepClone } from '@catbee/utils/object';
+import { deepObjMerge, isPlainObject, deepClone } from '@catbee/utils/object';
 import { fileExists, readFile, readFileSync } from '@catbee/utils/fs';
-import { isPort } from '@catbee/utils/validation';
+import { isPort, isHostname } from '@catbee/utils/validation';
 import { optionalRequire } from '@catbee/utils/async';
 import { uuid } from '@catbee/utils/id';
 
@@ -50,17 +50,29 @@ var ServerConfigBuilder = class {
   *
   * @private
   * @param port - The port number to validate
-  * @throws {Error} If port is not an integer or is outside the valid range (1-65535)
+  * @throws {Error} If port is not an integer or is outside the valid range (0-65535)
   */
   validatePort(port) {
-    if (!isPort(port)) {
-      throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);
+    if (!isPort(port, true)) {
+      throw new Error(`Port must be a valid number between 0 and 65535, got: ${port}`);
+    }
+  }
+  /**
+  * Validates that a hostname is valid.
+  *
+  * @private
+  * @param host - The hostname to validate
+  * @throws {Error} If hostname is invalid
+  */
+  validateHost(host) {
+    if (!isHostname(host)) {
+      throw new Error(`Host must be a valid hostname or IP address, got: ${host}`);
     }
   }
   /**
   * Sets the port the server will listen on.
   *
-  * @param port - The port number (1-65535)
+  * @param port - The port number (0-65535). Use 0 for dynamic port assignment.
   * @returns The builder instance for chaining
   * @throws {Error} If port is invalid
   * @default 3000 (can be overridden via PORT env variable)
@@ -80,14 +92,17 @@ var ServerConfigBuilder = class {
   *
   * @param host - The hostname (e.g., 'localhost', '0.0.0.0', '127.0.0.1')
   * @returns The builder instance for chaining
+  * @throws {Error} If hostname is invalid
   * @default '0.0.0.0' (can be overridden via HOST env variable)
   *
   * @example
   * ```typescript
   * builder.withHost('0.0.0.0') // Listen on all interfaces
+  * builder.withHost('localhost') // Listen on localhost only
   * ```
   */
   withHost(host) {
+    this.validateHost(host);
     this.config.host = host;
     return this;
   }
@@ -498,12 +513,23 @@ var ServerConfigBuilder = class {
   * ```
   */
   withBodyParser(opts) {
+    if (opts === true) {
+      this.config.bodyParser = getCatbeeServerGlobalConfig().bodyParser;
+      return this;
+    } else if (opts === false) {
+      this.config.bodyParser = false;
+      return this;
+    }
     this.config.bodyParser = {
       ...this.config.bodyParser,
       ...opts
     };
     return this;
   }
+  disableBodyParser() {
+    this.config.bodyParser = false;
+    return this;
+  }
   /**
   * Configures cookie parsing middleware.
   *
@@ -654,7 +680,7 @@ var ServerConfigBuilder = class {
     });
   }
   mergeConfig(key, value) {
-    const current = this.config[key] && typeof this.config[key] === "object" ? deepClone(this.config[key]) : {};
+    const current = isPlainObject(this.config[key]) ? deepClone(this.config[key]) : {};
     this.config[key] = deepObjMerge({}, current, value);
   }
   setEnabled(key, enable, overrides = {}) {
@@ -735,12 +761,15 @@ var ExpressServer = class {
   */
   constructor(config, hooks = {}) {
     if (this.hasBuildMarker(config)) {
-      this.config = config;
+      this.config = deepObjMerge({}, config);
     } else {
       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}`;
+    if (this.config.host) {
+      this.config.host = this.normalizeHost(this.config.host);
+    }
+    if (!isPort(this.config.port, true)) {
+      const msg = `Port must be a valid number between 0 and 65535, got: ${this.config.port}`;
       getLogger().error(msg);
       throw new Error(msg);
     }
@@ -853,6 +882,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);
   }
@@ -1018,7 +1048,6 @@ var ExpressServer = class {
         }
         const logger = getLogger();
         const incomingRequestMetaData = {
-          requestId: req.id,
           method: req.method,
           url: req.originalUrl || req.url,
           ip: req.ip
@@ -1068,13 +1097,23 @@ var ExpressServer = class {
   * Set up body parsing middleware.
   */
   setupBodyParsingMiddleware() {
-    if (this.config.bodyParser) {
+    if (isPlainObject(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));
       }
+    } else if (this.config.bodyParser === true) {
+      const globalBodyParserConfig = getCatbeeServerGlobalConfig().bodyParser;
+      if (isPlainObject(globalBodyParserConfig)) {
+        if (globalBodyParserConfig.json) {
+          this.app.use(express.json(globalBodyParserConfig.json));
+        }
+        if (globalBodyParserConfig.urlencoded) {
+          this.app.use(express.urlencoded(globalBodyParserConfig.urlencoded));
+        }
+      }
     }
   }
   /**
@@ -1201,6 +1240,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.NOT_FOUND;
       const response = createFinalErrorResponse(req, status, `Route ${req.method.toUpperCase()} ${req.path} not found`);
@@ -1354,6 +1394,7 @@ var ExpressServer = class {
           resolve(this.server);
         }, "onListening");
         this.server = this.createServerInstance(onListening);
+        this.runHook("onServerCreated", this.server);
         this.setupConnectionTracking();
         this.setupServerErrorHandling(reject);
       } catch (error) {
@@ -1411,7 +1452,9 @@ var ExpressServer = class {
   */
   logServerStartInfo() {
     const protocol = this.config.https ? "https" : "http";
-    const url = `${protocol}://${this.config.host}:${this.config.port}`;
+    const port = this.getPort();
+    const host = this.formatHostForUrl(this.config.host || "localhost");
+    const url = `${protocol}://${host}:${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)}`);
@@ -1636,12 +1679,136 @@ var ExpressServer = class {
     return this.config;
   }
   /**
+  * Get the port the server is listening on.
+  * Returns the actual port if server is running (useful when config.port was 0),
+  * otherwise returns the configured port.
+  *
+  * @returns The port number
+  */
+  getPort() {
+    const address = this.server?.address();
+    if (address && typeof address === "object" && "port" in address) {
+      return address.port;
+    }
+    return this.config.port;
+  }
+  /**
+  * Get the full URL the server is running on.
+  * Returns the actual URL if server is running (useful when config.port was 0),
+  * otherwise returns the configured URL.
+  *
+  * @returns The full server URL (e.g., "http://localhost:3000")
+  */
+  getUrl() {
+    const protocol = this.config.https ? "https" : "http";
+    const port = this.getPort();
+    const host = this.formatHostForUrl(this.config.host || "localhost");
+    return `${protocol}://${host}:${port}`;
+  }
+  /**
+  * Check if the server is configured for dynamic port assignment.
+  * Returns true if the original port configuration was 0.
+  *
+  * @returns True if using dynamic port assignment, false otherwise
+  */
+  isPortDynamic() {
+    return this.config.port === 0;
+  }
+  /**
+  * Check if the server is currently running and listening for requests.
+  *
+  * @returns True if server is running, false otherwise
+  */
+  isRunning() {
+    return this.server !== null && this.server.listening;
+  }
+  /**
+  * Get the host address the server is bound to.
+  *
+  * @returns The host address
+  */
+  getHost() {
+    return this.config.host || "localhost";
+  }
+  /**
+  * Get the protocol the server is using ('http' or 'https').
+  *
+  * @returns The protocol string
+  */
+  getProtocol() {
+    return this.config.https ? "https" : "http";
+  }
+  /**
+  * Check if the server is configured to use HTTPS.
+  *
+  * @returns True if using HTTPS, false otherwise
+  */
+  isHttps() {
+    return this.config.https !== void 0;
+  }
+  /**
+  * Set a new port for the server.
+  * Can only be called before the server starts listening.
+  * Useful for testing scenarios where you need to change the port dynamically.
+  *
+  * @param port - The new port number (0-65535)
+  * @throws Error if server is already running or port is invalid
+  */
+  setPort(port) {
+    if (this.server) {
+      throw new Error("Cannot change port after server has started");
+    }
+    if (!isPort(port, true)) {
+      throw new Error(`Port must be a valid number between 0 and 65535, got: ${port}`);
+    }
+    this.config.port = port;
+  }
+  /**
+  * Set a new host for the server.
+  * Can only be called before the server starts listening.
+  * Useful for testing scenarios where you need to change the host dynamically.
+  *
+  * @param host - The new host (e.g., "localhost", "0.0.0.0", "127.0.0.1", "::1", or "[::1]")
+  * @throws {Error} If server is already running or host is invalid
+  */
+  setHost(host) {
+    if (this.server) {
+      throw new Error("Cannot change host after server has started");
+    }
+    const normalizedHost = this.normalizeHost(host);
+    if (!isHostname(normalizedHost)) {
+      throw new Error(`Host must be a valid hostname or IP address, got: ${host}`);
+    }
+    this.config.host = normalizedHost;
+  }
+  /**
   * Wait until server initialization (middleware + routes) has completed.
   * Useful for integration tests that inspect app before starting.
   */
   async waitUntilReady() {
     await this.initPromise;
   }
+  /**
+  * Normalize host by stripping surrounding brackets from IPv6 addresses.
+  * This ensures the host value is compatible with server.listen().
+  * Brackets are URL syntax only and must be removed for Node.js binding.
+  */
+  normalizeHost(host) {
+    if (host.startsWith("[") && host.endsWith("]")) {
+      return host.slice(1, -1);
+    }
+    return host;
+  }
+  /**
+  * Format host for use in URLs.
+  * Wraps IPv6 addresses in brackets per RFC 3986.
+  */
+  formatHostForUrl(host) {
+    if (host.includes(":")) {
+      return `[${host}]`;
+    }
+    return host;
+  }
   normalizePath(path, withGlobalPrefix = false) {
     const sanitize = /* @__PURE__ */ __name((p) => {
       return "/" + p.trim().replace(/^\/+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "");

package/types/index.d.ts

@@ -24,6 +24,7 @@
 
 import { json, urlencoded, Request, Response, Express, NextFunction } from 'express';
 import http from 'node:http';
+import https from 'node:https';
 import { ExpressServer } from '@catbee/utils/server';
 import { HelmetOptions } from 'helmet';
 import { CompressionOptions } from 'compression';
@@ -165,6 +166,7 @@ interface CatbeeServerConfig {
     /** Server port
      *  - **default**: `3000`
      *  - **env**: `SERVER_PORT` || `PORT`
+     *  - Use `0` for dynamic port assignment (OS assigns available port)
      */
     port: number;
     /** Host address to bind the server
@@ -225,7 +227,7 @@ interface CatbeeServerConfig {
      *    - `SERVER_BODY_PARSER_JSON_LIMIT`
      *    - `SERVER_BODY_PARSER_URLENCODED_LIMIT`
      */
-    bodyParser?: {
+    bodyParser?: ToggleConfig<{
         /** JSON body parser options
          *  - **default**: `{ limit: '1mb' }`
          */
@@ -234,7 +236,7 @@ interface CatbeeServerConfig {
          *  - **default**: `{ extended: true, limit: '1mb' }`
          */
         urlencoded?: Parameters<typeof urlencoded>[0];
-    };
+    }>;
     /** Cookie parser toggle or options
      *  - **default**: `false`
      *  - **env**: `SERVER_COOKIE_PARSER_ENABLE`
@@ -554,8 +556,14 @@ interface CatbeeServerConfig {
 interface CatbeeServerHooks {
     /** Called before middleware & routes initialize */
     beforeInit?: (server: ExpressServer) => Promise<void> | void;
+    /** Called before any routes are registered */
+    beforeRoutes?: (app: Express) => Promise<void> | void;
+    /** Called after all routes are registered, before error handling middleware */
+    afterRoutes?: (app: Express) => Promise<void> | void;
     /** Called after middleware & routes initialize */
     afterInit?: (server: ExpressServer) => Promise<void> | void;
+    /** Called when the underlying HTTP/HTTPS server instance is created */
+    onServerCreated?: (server: http.Server | https.Server) => Promise<void> | void;
     /** Called before server starts listening */
     beforeStart?: (app: Express) => Promise<void> | void;
     /** Called after server is ready */

package/validation/index.cjs

@@ -42,13 +42,15 @@ var BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}
 var DOT_ATOM_REGEX = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
 var QUOTED_LOCAL_REGEX = /^"([\s\x21\x23-\x5B\x5D-\x7E]|\\[\x20-\x7E])*"$/;
 var TLD_REGEX = /^[A-Za-z]{2,63}$/;
-function isPort(value) {
-  if (typeof value === "number") return Number.isInteger(value) && value > 0 && value <= 65535;
+function isPort(value, allowZero = false) {
+  const minPort = allowZero ? 0 : 1;
+  const maxPort = 65535;
+  if (typeof value === "number") return Number.isInteger(value) && value >= minPort && value <= maxPort;
   if (!value || typeof value !== "string") return false;
   const str = value.trim();
   if (!PORT_REGEX.test(str)) return false;
   const port = Number(str);
-  return Number.isInteger(port) && port > 0 && port <= 65535;
+  return Number.isInteger(port) && port >= minPort && port <= maxPort;
 }
 __name(isPort, "isPort");
 function isEmail(str) {
@@ -154,7 +156,7 @@ function isIPv4(str) {
   const parts = str.split(".");
   if (parts.length !== 4) return false;
   return parts.every((p) => {
-    if (p.length > 3 || p.startsWith("0") && p.length > 1) return false;
+    if (!p || p.length > 3 || p.startsWith("0") && p.length > 1) return false;
     const n = Number(p);
     return Number.isInteger(n) && n >= 0 && n <= 255;
   });
@@ -169,6 +171,29 @@ function isIPv6(str) {
   }
 }
 __name(isIPv6, "isIPv6");
+function isHostname(str) {
+  if (!str || typeof str !== "string") return false;
+  let input = str.trim();
+  if (!input || input.length > 255) return false;
+  if (input.endsWith(".")) {
+    input = input.slice(0, -1);
+  }
+  if (isIPv4(input)) return true;
+  if (isIPv6(input)) return true;
+  if (input === "localhost") return true;
+  if (/^\d+(\.\d+){3,}$/.test(input)) {
+    return false;
+  }
+  if (input.includes("..")) return false;
+  const labels = input.split(".");
+  if (labels.length === 0) return false;
+  const labelRegex = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i;
+  return labels.every((label) => {
+    if (!label || label.length > 63) return false;
+    return labelRegex.test(label);
+  });
+}
+__name(isHostname, "isHostname");
 function isCreditCard(str) {
   if (!str || typeof str !== "string") return false;
   const s = str.replace(/\D/g, "");
@@ -243,6 +268,7 @@ exports.isCreditCard = isCreditCard;
 exports.isDateInRange = isDateInRange;
 exports.isEmail = isEmail;
 exports.isHexColor = isHexColor;
+exports.isHostname = isHostname;
 exports.isIPv4 = isIPv4;
 exports.isIPv6 = isIPv6;
 exports.isISODate = isISODate;

package/validation/index.d.ts

@@ -28,10 +28,11 @@
 /**
  * Checks if a string is a valid port number.
  *
- * @param str - The input string or number.
+ * @param value - The input string or number.
+ * @param allowZero - Whether to allow zero as a valid port number.
  * @returns True if valid port number, else false.
  */
-declare function isPort(value: string | number): boolean;
+declare function isPort(value: string | number, allowZero?: boolean): boolean;
 /**
  * Checks if a string is a valid email address.
  *
@@ -142,6 +143,31 @@ declare function isIPv4(str: string): boolean;
  * @returns {boolean} True if valid IPv6 address.
  */
 declare function isIPv6(str: string): boolean;
+/**
+ * Checks if a string is a valid hostname or IP address.
+ *
+ * Validates:
+ * - IPv4 addresses (e.g., '192.168.1.1')
+ * - IPv6 addresses (e.g., '::1', '2001:db8::1')
+ * - Domain names (e.g., 'example.com', 'sub.example.com')
+ * - Localhost variants ('localhost', '0.0.0.0', '127.0.0.1')
+ *
+ * @param {string} str - The hostname or IP address to validate.
+ * @returns {boolean} True if valid hostname or IP address.
+ *
+ * @example
+ * ```typescript
+ * isHostname('localhost');        // true
+ * isHostname('0.0.0.0');          // true
+ * isHostname('192.168.1.1');      // true
+ * isHostname('example.com');      // true
+ * isHostname('sub.example.com');  // true
+ * isHostname('::1');              // true
+ * isHostname('invalid..com');     // false
+ * isHostname('');                 // false
+ * ```
+ */
+declare function isHostname(str: string): boolean;
 /**
  * Validates a credit card number using the Luhn algorithm.
  *
@@ -206,4 +232,4 @@ declare function matchesPattern(str: string, pattern: RegExp): boolean;
  */
 declare function validateAll(value: unknown, validators: Array<(value: unknown) => boolean>): boolean;
 
-export { hasRequiredProps, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isEmail, isHexColor, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isPhone, isPort, isStrongPassword, isURL, isUUID, isValidJSON, matchesPattern, validateAll };
+export { hasRequiredProps, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isEmail, isHexColor, isHostname, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isPhone, isPort, isStrongPassword, isURL, isUUID, isValidJSON, matchesPattern, validateAll };

package/validation/index.mjs

@@ -36,13 +36,15 @@ var BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}
 var DOT_ATOM_REGEX = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
 var QUOTED_LOCAL_REGEX = /^"([\s\x21\x23-\x5B\x5D-\x7E]|\\[\x20-\x7E])*"$/;
 var TLD_REGEX = /^[A-Za-z]{2,63}$/;
-function isPort(value) {
-  if (typeof value === "number") return Number.isInteger(value) && value > 0 && value <= 65535;
+function isPort(value, allowZero = false) {
+  const minPort = allowZero ? 0 : 1;
+  const maxPort = 65535;
+  if (typeof value === "number") return Number.isInteger(value) && value >= minPort && value <= maxPort;
   if (!value || typeof value !== "string") return false;
   const str = value.trim();
   if (!PORT_REGEX.test(str)) return false;
   const port = Number(str);
-  return Number.isInteger(port) && port > 0 && port <= 65535;
+  return Number.isInteger(port) && port >= minPort && port <= maxPort;
 }
 __name(isPort, "isPort");
 function isEmail(str) {
@@ -148,7 +150,7 @@ function isIPv4(str) {
   const parts = str.split(".");
   if (parts.length !== 4) return false;
   return parts.every((p) => {
-    if (p.length > 3 || p.startsWith("0") && p.length > 1) return false;
+    if (!p || p.length > 3 || p.startsWith("0") && p.length > 1) return false;
     const n = Number(p);
     return Number.isInteger(n) && n >= 0 && n <= 255;
   });
@@ -163,6 +165,29 @@ function isIPv6(str) {
   }
 }
 __name(isIPv6, "isIPv6");
+function isHostname(str) {
+  if (!str || typeof str !== "string") return false;
+  let input = str.trim();
+  if (!input || input.length > 255) return false;
+  if (input.endsWith(".")) {
+    input = input.slice(0, -1);
+  }
+  if (isIPv4(input)) return true;
+  if (isIPv6(input)) return true;
+  if (input === "localhost") return true;
+  if (/^\d+(\.\d+){3,}$/.test(input)) {
+    return false;
+  }
+  if (input.includes("..")) return false;
+  const labels = input.split(".");
+  if (labels.length === 0) return false;
+  const labelRegex = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i;
+  return labels.every((label) => {
+    if (!label || label.length > 63) return false;
+    return labelRegex.test(label);
+  });
+}
+__name(isHostname, "isHostname");
 function isCreditCard(str) {
   if (!str || typeof str !== "string") return false;
   const s = str.replace(/\D/g, "");
@@ -228,4 +253,4 @@ function validateAll(value, validators) {
 }
 __name(validateAll, "validateAll");
 
-export { hasRequiredProps, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isEmail, isHexColor, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isPhone, isPort, isStrongPassword, isURL, isUUID, isValidJSON, matchesPattern, validateAll };
+export { hasRequiredProps, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isEmail, isHexColor, isHostname, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isPhone, isPort, isStrongPassword, isURL, isUUID, isValidJSON, matchesPattern, validateAll };