@catbee/utils 2.0.0 → 2.0.2

package/server/index.cjs

@@ -57,17 +57,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 (!validation.isPort(port)) {
-      throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);
+    if (!validation.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 (!validation.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)
@@ -87,14 +99,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;
   }
@@ -505,12 +520,23 @@ var ServerConfigBuilder = class {
   * ```
   */
   withBodyParser(opts) {
+    if (opts === true) {
+      this.config.bodyParser = config.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.
   *
@@ -661,7 +687,7 @@ var ServerConfigBuilder = class {
     });
   }
   mergeConfig(key, value) {
-    const current = this.config[key] && typeof this.config[key] === "object" ? object.deepClone(this.config[key]) : {};
+    const current = object.isPlainObject(this.config[key]) ? object.deepClone(this.config[key]) : {};
     this.config[key] = object.deepObjMerge({}, current, value);
   }
   setEnabled(key, enable, overrides = {}) {
@@ -742,12 +768,15 @@ var ExpressServer = class {
   */
   constructor(config$1, hooks = {}) {
     if (this.hasBuildMarker(config$1)) {
-      this.config = config$1;
+      this.config = object.deepObjMerge({}, config$1);
     } else {
       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}`;
+    if (this.config.host) {
+      this.config.host = this.normalizeHost(this.config.host);
+    }
+    if (!validation.isPort(this.config.port, true)) {
+      const msg = `Port must be a valid number between 0 and 65535, got: ${this.config.port}`;
       logger.getLogger().error(msg);
       throw new Error(msg);
     }
@@ -860,6 +889,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);
   }
@@ -1025,7 +1055,6 @@ var ExpressServer = class {
         }
         const logger$1 = logger.getLogger();
         const incomingRequestMetaData = {
-          requestId: req.id,
           method: req.method,
           url: req.originalUrl || req.url,
           ip: req.ip
@@ -1075,13 +1104,23 @@ var ExpressServer = class {
   * Set up body parsing middleware.
   */
   setupBodyParsingMiddleware() {
-    if (this.config.bodyParser) {
+    if (object.isPlainObject(this.config.bodyParser)) {
       if (this.config.bodyParser.json) {
         this.app.use(express__default.default.json(this.config.bodyParser.json));
       }
       if (this.config.bodyParser.urlencoded) {
         this.app.use(express__default.default.urlencoded(this.config.bodyParser.urlencoded));
       }
+    } else if (this.config.bodyParser === true) {
+      const globalBodyParserConfig = config.getCatbeeServerGlobalConfig().bodyParser;
+      if (object.isPlainObject(globalBodyParserConfig)) {
+        if (globalBodyParserConfig.json) {
+          this.app.use(express__default.default.json(globalBodyParserConfig.json));
+        }
+        if (globalBodyParserConfig.urlencoded) {
+          this.app.use(express__default.default.urlencoded(globalBodyParserConfig.urlencoded));
+        }
+      }
     }
   }
   /**
@@ -1208,6 +1247,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`);
@@ -1361,6 +1401,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) {
@@ -1418,7 +1459,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}`;
     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)}`);
@@ -1643,12 +1686,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 (!validation.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 (!validation.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/server/index.d.ts

@@ -363,11 +363,87 @@ declare class ExpressServer {
      * @return {*}  {CatbeeServerConfig}
      */
     getConfig(): CatbeeServerConfig;
+    /**
+     * 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(): number;
+    /**
+     * 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(): string;
+    /**
+     * 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(): boolean;
+    /**
+     * Check if the server is currently running and listening for requests.
+     *
+     * @returns True if server is running, false otherwise
+     */
+    isRunning(): boolean;
+    /**
+     * Get the host address the server is bound to.
+     *
+     * @returns The host address
+     */
+    getHost(): string;
+    /**
+     * Get the protocol the server is using ('http' or 'https').
+     *
+     * @returns The protocol string
+     */
+    getProtocol(): string;
+    /**
+     * Check if the server is configured to use HTTPS.
+     *
+     * @returns True if using HTTPS, false otherwise
+     */
+    isHttps(): boolean;
+    /**
+     * 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: number): void;
+    /**
+     * 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: string): void;
     /**
      * Wait until server initialization (middleware + routes) has completed.
      * Useful for integration tests that inspect app before starting.
      */
     waitUntilReady(): Promise<void>;
+    /**
+     * 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.
+     */
+    private normalizeHost;
+    /**
+     * Format host for use in URLs.
+     * Wraps IPv6 addresses in brackets per RFC 3986.
+     */
+    private formatHostForUrl;
     private normalizePath;
     private normalizeRouteForMetrics;
     /**
@@ -403,13 +479,21 @@ declare class ServerConfigBuilder {
      *
      * @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)
      */
     private validatePort;
+    /**
+     * Validates that a hostname is valid.
+     *
+     * @private
+     * @param host - The hostname to validate
+     * @throws {Error} If hostname is invalid
+     */
+    private validateHost;
     /**
      * 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)
@@ -425,11 +509,13 @@ declare class ServerConfigBuilder {
      *
      * @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: string): this;
@@ -768,6 +854,7 @@ declare class ServerConfigBuilder {
      * ```
      */
     withBodyParser(opts: NonNullable<CatbeeServerConfig['bodyParser']>): this;
+    disableBodyParser(): this;
     /**
      * Configures cookie parsing middleware.
      *