@catbee/utils 0.0.6 → 0.0.7

package/build/esm/utils/type.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.utils.js","sourceRoot":"","sources":["../../../src/utils/type.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Check if a value is of a specific primitive type.\n *\n * @param value - Value to check\n * @param type - Type to check against\n * @returns Whether the value is of the specified type\n *\n * @example\n * ```typescript\n * isPrimitiveType('hello', 'string'); // true\n * isPrimitiveType(42, 'number'); // true\n * isPrimitiveType(true, 'boolean'); // true\n * isPrimitiveType(null, 'null'); // true\n * isPrimitiveType(undefined, 'undefined'); // true\n * isPrimitiveType({}, 'object'); // true\n * isPrimitiveType([], 'array'); // true\n * ```\n */\nexport function isPrimitiveType(\n  value: unknown,\n  type: 'string' | 'number' | 'boolean' | 'symbol' | 'bigint' | 'function' | 'object' | 'array' | 'null' | 'undefined'\n): boolean {\n  if (type === 'array') {\n    return Array.isArray(value);\n  }\n\n  if (type === 'null') {\n    return value === null;\n  }\n\n  if (type === 'undefined') {\n    return value === undefined;\n  }\n\n  if (type === 'object') {\n    // Only plain objects, not arrays or null\n    return typeof value === 'object' && value !== null && !Array.isArray(value);\n  }\n\n  return typeof value === type;\n}\n\n/**\n * Get the primitive type of a value as a string.\n *\n * @param value - Value to get the type of\n * @returns String representing the type\n *\n * @example\n * ```typescript\n * getTypeOf('hello'); // 'string'\n * getTypeOf(42); // 'number'\n * getTypeOf([]); // 'array'\n * getTypeOf(null); // 'null'\n * ```\n */\nexport function getTypeOf(value: unknown): string {\n  if (value === null) return 'null';\n  if (value === undefined) return 'undefined';\n  if (Array.isArray(value)) return 'array';\n  return typeof value;\n}\n\n/**\n * Type guard for checking if a value is an array of a specific type.\n *\n * @param value - Value to check\n * @param itemTypeGuard - Function that checks if items are of the expected type\n * @returns True if the value is an array with items of the expected type\n *\n * @example\n * ```typescript\n * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true\n * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true\n * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false\n * ```\n */\nexport function isArrayOf<T>(value: unknown, itemTypeGuard: (item: unknown) => item is T): value is T[] {\n  if (!Array.isArray(value)) return false;\n  return value.every(item => itemTypeGuard(item));\n}\n\n/**\n * Convert a value to a string.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns String representation of the value\n */\nexport function toStr(value: unknown, defaultValue: string = ''): string {\n  if (value === null || value === undefined) return defaultValue;\n\n  try {\n    if (typeof value === 'object') {\n      return JSON.stringify(value);\n    }\n    return String(value);\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Convert a value to a number.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns Numeric representation of the value\n */\nexport function toNum(value: unknown, defaultValue: number = 0): number {\n  if (value === null || value === undefined) return defaultValue;\n\n  if (typeof value === 'number') return value;\n\n  try {\n    const num = Number(value);\n    return isNaN(num) ? defaultValue : num;\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Convert a value to a boolean.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns Boolean representation of the value\n */\nexport function toBool(value: unknown, defaultValue: boolean = false): boolean {\n  if (value === null || value === undefined) return defaultValue;\n\n  if (typeof value === 'boolean') return value;\n\n  if (typeof value === 'string') {\n    const lowercased = value.toLowerCase();\n    if (lowercased === 'true' || lowercased === 'yes' || lowercased === 'y' || lowercased === '1') {\n      return true;\n    }\n    if (lowercased === 'false' || lowercased === 'no' || lowercased === 'n' || lowercased === '0') {\n      return false;\n    }\n  }\n\n  if (typeof value === 'number') {\n    return value !== 0;\n  }\n\n  return defaultValue;\n}\n\n/**\n * Ensure a value matches the expected type, or provide a default.\n *\n * @param value - Value to check\n * @param expectedType - Expected primitive type\n * @param defaultValue - Default value to use if type doesn't match\n * @returns The value if it matches the type, otherwise the default\n *\n * @example\n * ```typescript\n * ensureType(42, 'number', 0); // 42\n * ensureType('42', 'number', 0); // 0\n * ensureType(undefined, 'string', 'default'); // 'default'\n * ```\n */\nexport function ensureType<T>(value: unknown, expectedType: string, defaultValue: T): T {\n  if (getTypeOf(value) === expectedType) {\n    return value as unknown as T;\n  }\n  return defaultValue;\n}\n"]}

package/build/esnext/config.d.ts

@@ -1,4 +1,4 @@
-import { LoggerLevels } from './utils/logger.utils';
+import { Logger, LoggerLevels } from './utils/logger.utils';
 /**
  * Extends Express Request interface to add request ID tracking.
  * Added by requestId middleware during request processing.
@@ -8,6 +8,10 @@ declare global {
         interface Request {
             /** Unique request identifier (set by middleware) */
             id?: string;
+            /** Logger instance for the request (set by middleware) */
+            logger?: Logger;
+            /** User information (set by authentication middleware) */
+            user?: any;
         }
     }
 }
@@ -34,12 +38,6 @@ export declare let config: {
          */
         singleLine: boolean;
     };
-    http: {
-        /**
-         * Timeout for HTTP requests in milliseconds
-         */
-        timeout: number;
-    };
     cache: {
         /**
          * Default TTL (time to live) for cache entries in seconds
@@ -100,12 +98,6 @@ export declare const defaultServerConfig: {
         exposeHeader: true;
         generator: () => string;
     };
-    logger: {
-        name: string;
-        level: LoggerLevels;
-        prettyPrint: false;
-        singleLine: false;
-    };
     metrics: {
         enable: false;
         path: string;

package/build/esnext/config.js

@@ -47,12 +47,6 @@ export let config = {
          */
         singleLine: Env.getBoolean('LOGGER_PRETTY_SINGLE_LINE', false)
     },
-    http: {
-        /**
-         * Timeout for HTTP requests in milliseconds
-         */
-        timeout: Env.getNumber('HTTP_TIMEOUT', 30000)
-    },
     cache: {
         /**
          * Default TTL (time to live) for cache entries in seconds
@@ -111,12 +105,6 @@ export const defaultServerConfig = {
         exposeHeader: true,
         generator: () => uuid()
     },
-    logger: {
-        name: 'express_app',
-        level: 'info',
-        prettyPrint: false,
-        singleLine: false
-    },
     metrics: {
         enable: false,
         path: '/metrics',

package/build/esnext/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { ServerConfig } from './types/server';\nimport { Env } from './utils/env.utils';\nimport { uuid } from './utils/id.utils';\nimport { LoggerLevels } from './utils/logger.utils';\nimport { deepObjMerge } from './utils/obj.utils';\n\n/**\n * Extends Express Request interface to add request ID tracking.\n * Added by requestId middleware during request processing.\n */\ndeclare global {\n  namespace Express {\n    interface Request {\n      /** Unique request identifier (set by middleware) */\n      id?: string;\n    }\n  }\n}\n\n/**\n * Application runtime configuration loaded from environment variables.\n */\nexport let config = {\n  logger: {\n    /**\n     * Logging level (e.g., 'info', 'debug', 'warn', 'error').\n     */\n    level: Env.get('LOGGER_LEVEL', 'info') as LoggerLevels,\n\n    /**\n     * Name of the logger instance (defaults to npm package name).\n     */\n    name: Env.get('LOGGER_NAME', Env.get('npm_package_name', '@catbee/utils')),\n\n    /**\n     * Enables pretty-print logging in development.\n     * Has no effect in production.\n     */\n    pretty: Env.getBoolean('LOGGER_PRETTY', true),\n    /**\n     * Single line output for pretty-print (default: false)\n     */\n    singleLine: Env.getBoolean('LOGGER_PRETTY_SINGLE_LINE', false)\n  },\n\n  http: {\n    /**\n     * Timeout for HTTP requests in milliseconds\n     */\n    timeout: Env.getNumber('HTTP_TIMEOUT', 30000)\n  },\n\n  cache: {\n    /**\n     * Default TTL (time to live) for cache entries in seconds\n     */\n    defaultTtl: Env.getNumber('CACHE_DEFAULT_TTL_SECONDS', 3600) * 1000\n  }\n};\n\nexport const defaultServerConfig = {\n  port: 3000,\n  host: '0.0.0.0',\n  cors: false,\n  helmet: false,\n  compression: false,\n  bodyParser: {\n    json: { limit: '1mb' },\n    urlencoded: { extended: true, limit: '1mb' }\n  },\n  cookieParser: false,\n  isMicroservice: false,\n  appName: 'express_app',\n  globalHeaders: {},\n  rateLimit: {\n    enable: false,\n    windowMs: 15 * 60 * 1000,\n    max: 100,\n    message: 'Too many requests',\n    standardHeaders: true,\n    legacyHeaders: false\n  },\n  requestLogging: {\n    enable: Env.isDev(),\n    ignorePaths: (req, _res) => {\n      const skipPaths = ['/healthz', '/favicon.ico', '/metrics', '/docs', '/.well-known'];\n      return skipPaths.some(path => req.path.startsWith(path));\n    },\n    skipNotFoundRoutes: false\n  },\n  openApi: {\n    enable: false,\n    mountPath: '/docs',\n    verbose: false,\n    withGlobalPrefix: false\n  },\n  healthCheck: {\n    path: '/healthz',\n    detailed: true\n  },\n  requestTimeout: 30000,\n  responseTime: {\n    enable: false,\n    addHeader: true,\n    logOnComplete: false\n  },\n  requestId: {\n    headerName: 'x-request-id',\n    exposeHeader: true,\n    generator: () => uuid()\n  },\n  logger: {\n    name: 'express_app',\n    level: 'info' as LoggerLevels,\n    prettyPrint: false,\n    singleLine: false\n  },\n  metrics: {\n    enable: false,\n    path: '/metrics',\n    withGlobalPrefix: false\n  },\n  serviceVersion: {\n    enable: false,\n    headerName: 'x-service-version',\n    version: '0.0.0'\n  }\n} satisfies ServerConfig;\n\n/**\n * Update the @catbee/utils configuration.\n * @param value Partial configuration object.\n */\nexport function setConfig(value: Partial<typeof config>): void {\n  deepObjMerge(config, value);\n}\n\n/**\n * Get the current @catbee/utils configuration.\n * @returns The current configuration object.\n */\nexport function getConfig(): typeof config {\n  return config;\n}\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { ServerConfig } from './types/server';\nimport { Env } from './utils/env.utils';\nimport { uuid } from './utils/id.utils';\nimport { Logger, LoggerLevels } from './utils/logger.utils';\nimport { deepObjMerge } from './utils/obj.utils';\n\n/**\n * Extends Express Request interface to add request ID tracking.\n * Added by requestId middleware during request processing.\n */\ndeclare global {\n  namespace Express {\n    interface Request {\n      /** Unique request identifier (set by middleware) */\n      id?: string;\n      /** Logger instance for the request (set by middleware) */\n      logger?: Logger;\n      /** User information (set by authentication middleware) */\n      user?: any;\n    }\n  }\n}\n\n/**\n * Application runtime configuration loaded from environment variables.\n */\nexport let config = {\n  logger: {\n    /**\n     * Logging level (e.g., 'info', 'debug', 'warn', 'error').\n     */\n    level: Env.get('LOGGER_LEVEL', 'info') as LoggerLevels,\n\n    /**\n     * Name of the logger instance (defaults to npm package name).\n     */\n    name: Env.get('LOGGER_NAME', Env.get('npm_package_name', '@catbee/utils')),\n\n    /**\n     * Enables pretty-print logging in development.\n     * Has no effect in production.\n     */\n    pretty: Env.getBoolean('LOGGER_PRETTY', true),\n    /**\n     * Single line output for pretty-print (default: false)\n     */\n    singleLine: Env.getBoolean('LOGGER_PRETTY_SINGLE_LINE', false)\n  },\n\n  cache: {\n    /**\n     * Default TTL (time to live) for cache entries in seconds\n     */\n    defaultTtl: Env.getNumber('CACHE_DEFAULT_TTL_SECONDS', 3600) * 1000\n  }\n};\n\nexport const defaultServerConfig = {\n  port: 3000,\n  host: '0.0.0.0',\n  cors: false,\n  helmet: false,\n  compression: false,\n  bodyParser: {\n    json: { limit: '1mb' },\n    urlencoded: { extended: true, limit: '1mb' }\n  },\n  cookieParser: false,\n  isMicroservice: false,\n  appName: 'express_app',\n  globalHeaders: {},\n  rateLimit: {\n    enable: false,\n    windowMs: 15 * 60 * 1000,\n    max: 100,\n    message: 'Too many requests',\n    standardHeaders: true,\n    legacyHeaders: false\n  },\n  requestLogging: {\n    enable: Env.isDev(),\n    ignorePaths: (req, _res) => {\n      const skipPaths = ['/healthz', '/favicon.ico', '/metrics', '/docs', '/.well-known'];\n      return skipPaths.some(path => req.path.startsWith(path));\n    },\n    skipNotFoundRoutes: false\n  },\n  openApi: {\n    enable: false,\n    mountPath: '/docs',\n    verbose: false,\n    withGlobalPrefix: false\n  },\n  healthCheck: {\n    path: '/healthz',\n    detailed: true\n  },\n  requestTimeout: 30000,\n  responseTime: {\n    enable: false,\n    addHeader: true,\n    logOnComplete: false\n  },\n  requestId: {\n    headerName: 'x-request-id',\n    exposeHeader: true,\n    generator: () => uuid()\n  },\n  metrics: {\n    enable: false,\n    path: '/metrics',\n    withGlobalPrefix: false\n  },\n  serviceVersion: {\n    enable: false,\n    headerName: 'x-service-version',\n    version: '0.0.0'\n  }\n} satisfies ServerConfig;\n\n/**\n * Update the @catbee/utils configuration.\n * @param value Partial configuration object.\n */\nexport function setConfig(value: Partial<typeof config>): void {\n  deepObjMerge(config, value);\n}\n\n/**\n * Get the current @catbee/utils configuration.\n * @returns The current configuration object.\n */\nexport function getConfig(): typeof config {\n  return config;\n}\n"]}

package/build/esnext/servers/server.builder.d.ts

@@ -408,23 +408,6 @@ export declare class ServerConfigBuilder {
      * ```
      */
     withCookies(opts: ServerConfig['cookieParser']): this;
-    /**
-     * Configures the logger used by the server.
-     *
-     * @param opts - Logger configuration options
-     * @returns The builder instance for chaining
-     * @default { name: 'express_app', level: 'info', prettyPrint: true in dev, singleLine: false }
-     *
-     * @example
-     * ```typescript
-     * builder.withLogger({
-     *   level: 'info',
-     *   prettyPrint: true,
-     *   singleLine: false
-     * })
-     * ```
-     */
-    withLogger(opts: Partial<NonNullable<ServerConfig['logger']>>): this;
     /**
      * Adds a static folder to serve files from.
      *
@@ -518,107 +501,7 @@ export declare class ServerConfigBuilder {
      *   .build();
      * ```
      */
-    build(): Readonly<{
-        [BUILD_MARKER]: boolean;
-        port: number;
-        host?: string;
-        cors?: import("..").ToggleConfig<import("cors").CorsOptions>;
-        helmet?: import("..").ToggleConfig<import("helmet").HelmetOptions>;
-        compression?: import("..").ToggleConfig<import("compression").CompressionOptions>;
-        bodyParser?: {
-            json? /**
-             * Sets the hostname the server will bind to.
-             *
-             * @param host - The hostname (e.g., 'localhost', '0.0.0.0', '127.0.0.1')
-             * @returns The builder instance for chaining
-             * @default '0.0.0.0' (can be overridden via HOST env variable)
-             *
-             * @example
-             * ```typescript
-             * builder.withHost('0.0.0.0') // Listen on all interfaces
-             * ```
-             */: Parameters<typeof import("express").json>[0];
-            urlencoded?: Parameters<typeof import("express").urlencoded>[0];
-        };
-        cookieParser?: import("..").ToggleConfig<import("cookie-parser").CookieParseOptions>;
-        trustProxy?: boolean;
-        staticFolders?: Array<{
-            path?: string;
-            directory: string;
-            maxAge?: string;
-            etag?: boolean;
-            immutable?: boolean;
-            lastModified?: boolean;
-            cacheControl?: boolean;
-        }>;
-        isMicroservice?: boolean;
-        appName?: string;
-        globalHeaders?: Record<string, string | (() => string)>;
-        rateLimit?: {
-            enable: boolean;
-            windowMs?: number;
-            max?: number;
-            message?: string;
-            standardHeaders?: boolean;
-            legacyHeaders?: boolean;
-        };
-        requestLogging?: {
-            enable: boolean;
-            ignorePaths?: string[] | ((req: import("express").Request, res: import("express").Response) => boolean);
-            skipNotFoundRoutes?: boolean;
-        };
-        healthCheck?: {
-            path?: string;
-            checks?: Array<{
-                name: string;
-                check: () => Promise<boolean> | boolean;
-            }>;
-            detailed?: boolean;
-            withGlobalPrefix?: boolean;
-        };
-        requestTimeout?: number;
-        responseTime?: {
-            enable: boolean;
-            addHeader?: boolean;
-            logOnComplete?: boolean;
-        };
-        requestId?: {
-            headerName?: string;
-            exposeHeader?: boolean;
-            generator?: () => string;
-        };
-        globalPrefix?: string;
-        openApi?: {
-            enable: boolean;
-            mountPath?: string;
-            filePath?: string;
-            verbose?: boolean;
-            withGlobalPrefix?: boolean;
-        };
-        logger?: {
-            name?: string;
-            level?: import("..").LoggerLevels;
-            prettyPrint?: boolean;
-            singleLine?: boolean;
-        };
-        metrics?: {
-            enable: boolean;
-            path?: string;
-            withGlobalPrefix?: boolean;
-        };
-        serviceVersion?: {
-            enable: boolean;
-            headerName?: string;
-            version?: string | (() => string);
-        };
-        https?: {
-            key: string;
-            cert: string;
-            ca?: string;
-            passphrase?: string;
-            [key: string]: any;
-        };
-    }>;
+    build(): Readonly<ServerConfig>;
     private mergeConfig;
     private setEnabled;
 }

package/build/esnext/servers/server.builder.js

@@ -522,26 +522,6 @@ export class ServerConfigBuilder {
         this.config.cookieParser = opts;
         return this;
     }
-    /**
-     * Configures the logger used by the server.
-     *
-     * @param opts - Logger configuration options
-     * @returns The builder instance for chaining
-     * @default { name: 'express_app', level: 'info', prettyPrint: true in dev, singleLine: false }
-     *
-     * @example
-     * ```typescript
-     * builder.withLogger({
-     *   level: 'info',
-     *   prettyPrint: true,
-     *   singleLine: false
-     * })
-     * ```
-     */
-    withLogger(opts) {
-        this.mergeConfig('logger', opts);
-        return this;
-    }
     /**
      * Adds a static folder to serve files from.
      *

package/build/esnext/servers/server.builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.builder.js","sourceRoot":"","sources":["../../../src/servers/server.builder.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { deepObjMerge } from '../utils/obj.utils';\nimport { ServerConfig } from '../types/server';\nimport { defaultServerConfig } from '../config';\nimport { isPort } from '../utils/validate.utils';\n\n/**\n * Builder class for creating and configuring an Express server configuration.\n *\n * This class provides a fluent interface to configure all aspects of the Express server\n * including security settings, middleware, routing, and more.\n *\n * @example\n * ```typescript\n * const serverConfig = new ServerConfigBuilder()\n *   .withPort(3000)\n *   .withHost('localhost')\n *   .enableCors()\n *   .enableHelmet()\n *   .build();\n * ```\n */\n\nexport const BUILD_MARKER = Symbol.for('catbee.express.server.build');\n\nexport class ServerConfigBuilder {\n  private config: Partial<ServerConfig> = {};\n\n  /**\n   * Validates that a port number is valid and usable.\n   *\n   * @private\n   * @param port - The port number to validate\n   * @throws {Error} If port is not an integer or is outside the valid range (1-65535)\n   */\n  private validatePort(port: number): void {\n    if (!isPort(port)) {\n      throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);\n    }\n  }\n\n  /**\n   * Sets the port the server will listen on.\n   *\n   * @param port - The port number (1-65535)\n   * @returns The builder instance for chaining\n   * @throws {Error} If port is invalid\n   * @default 3000 (can be overridden via PORT env variable)\n   *\n   * @example\n   * ```typescript\n   * builder.withPort(3000)\n   * ```\n   */\n  withPort(port: number): this {\n    this.validatePort(port);\n    this.config.port = port;\n    return this;\n  }\n\n  /**\n   * Sets the hostname the server will bind to.\n   *\n   * @param host - The hostname (e.g., 'localhost', '0.0.0.0', '127.0.0.1')\n   * @returns The builder instance for chaining\n   * @default '0.0.0.0' (can be overridden via HOST env variable)\n   *\n   * @example\n   * ```typescript\n   * builder.withHost('0.0.0.0') // Listen on all interfaces\n   * ```\n   */\n  withHost(host: string): this {\n    this.config.host = host;\n    return this;\n  }\n\n  /**\n   * Configures Cross-Origin Resource Sharing (CORS) for the server.\n   *\n   * @param opts - CORS options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (CORS is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable CORS with default options\n   * builder.withCors(true)\n   *\n   * // Configure CORS with specific options\n   * builder.withCors({\n   *   origin: ['https://example.com'],\n   *   methods: ['GET', 'POST']\n   * })\n   * ```\n   */\n  withCors(opts: ServerConfig['cors']): this {\n    this.config.cors = opts;\n    return this;\n  }\n\n  /**\n   * Enables CORS with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableCors(): this {\n    return this.withCors(true);\n  }\n\n  /**\n   * Disables CORS\n   *\n   * @returns The builder instance for chaining\n   */\n  disableCors(): this {\n    return this.withCors(false);\n  }\n\n  /**\n   * Configures the Helmet middleware for setting HTTP security headers.\n   *\n   * @param opts - Helmet options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (Helmet is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable Helmet with default settings\n   * builder.withHelmet(true)\n   *\n   * // Configure Helmet with specific options\n   * builder.withHelmet({\n   *   contentSecurityPolicy: false,\n   *   xssFilter: true\n   * })\n   * ```\n   */\n  withHelmet(opts: ServerConfig['helmet']): this {\n    this.config.helmet = opts;\n    return this;\n  }\n\n  /**\n   * Enables Helmet with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableHelmet(): this {\n    return this.withHelmet(true);\n  }\n\n  /**\n   * Disables Helmet\n   *\n   * @returns The builder instance for chaining\n   */\n  disableHelmet(): this {\n    return this.withHelmet(false);\n  }\n\n  /**\n   * Configures response compression middleware.\n   *\n   * @param opts - Compression options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (Compression is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable compression with default settings\n   * builder.withCompression(true)\n   *\n   * // Configure compression with specific options\n   * builder.withCompression({\n   *   level: 6,\n   *   threshold: 1024\n   * })\n   * ```\n   */\n  withCompression(opts: ServerConfig['compression']): this {\n    this.config.compression = opts;\n    return this;\n  }\n\n  /**\n   * Enables compression with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableCompression(): this {\n    return this.withCompression(true);\n  }\n\n  /**\n   * Disables compression\n   *\n   * @returns The builder instance for chaining\n   */\n  disableCompression(): this {\n    return this.withCompression(false);\n  }\n\n  /**\n   * Configures rate limiting to protect against brute-force attacks.\n   *\n   * @param opts - Rate limit configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, windowMs: 15 * 60 * 1000, max: 100, message: 'Too many requests', standardHeaders: true, legacyHeaders: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withRateLimit({\n   *   enable: true,\n   *   windowMs: 15 * 60 * 1000, // 15 minutes\n   *   max: 100 // limit each IP to 100 requests per windowMs\n   * })\n   * ```\n   */\n  withRateLimit(opts: Partial<ServerConfig['rateLimit']>): this {\n    this.mergeConfig('rateLimit', opts as NonNullable<ServerConfig['rateLimit']>);\n    return this;\n  }\n\n  /**\n   * Enables rate limiting with default or custom settings\n   *\n   * @param opts - Optional rate limit configuration (max requests, window, etc.)\n   * @returns The builder instance for chaining\n   */\n  enableRateLimit(opts: Omit<Partial<NonNullable<ServerConfig['rateLimit']>>, 'enable'> = {}): this {\n    return this.setEnabled('rateLimit', true, opts);\n  }\n\n  /**\n   * Disables rate limiting\n   *\n   * @returns The builder instance for chaining\n   */\n  disableRateLimit(): this {\n    return this.setEnabled('rateLimit', false);\n  }\n\n  /**\n   * Configures HTTP request logging middleware.\n   *\n   * @param opts - Request logging configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: true in dev/false in prod, ignorePaths: ['/healthz', '/favicon.ico', '/metrics', '/docs', '/.well-known'], skipNotFoundRoutes: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withRequestLogging({\n   *   enable: true,\n   *   ignorePaths: ['/health', '/metrics'],\n   *   skipNotFoundRoutes: true\n   * })\n   * ```\n   */\n  withRequestLogging(opts: Partial<NonNullable<ServerConfig['requestLogging']>>): this {\n    this.mergeConfig('requestLogging', opts as NonNullable<ServerConfig['requestLogging']>);\n    return this;\n  }\n\n  /**\n   * Enables request logging with default or custom settings\n   *\n   * @param opts - Optional request logging configuration\n   * @returns The builder instance for chaining\n   */\n  enableRequestLogging(opts: Omit<Partial<NonNullable<ServerConfig['requestLogging']>>, 'enable'> = {}): this {\n    return this.setEnabled('requestLogging', true, opts);\n  }\n\n  /**\n   * Disables request logging\n   *\n   * @returns The builder instance for chaining\n   */\n  disableRequestLogging(): this {\n    return this.setEnabled('requestLogging', false);\n  }\n\n  /**\n   * Configures server metrics collection and endpoints.\n   *\n   * @param opts - Metrics configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, path: '/metrics', withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withMetrics({\n   *   enable: true,\n   *   path: '/metrics'\n   * })\n   * ```\n   */\n  withMetrics(opts: Partial<NonNullable<ServerConfig['metrics']>>): this {\n    this.mergeConfig('metrics', opts as NonNullable<ServerConfig['metrics']>);\n    return this;\n  }\n\n  /**\n   * Enables Prometheus metrics collection and endpoint\n   *\n   * @param opts - Optional metrics configuration\n   * @returns The builder instance for chaining\n   */\n  enableMetrics(opts: Omit<Partial<NonNullable<ServerConfig['metrics']>>, 'enable'> = {}): this {\n    return this.setEnabled('metrics', true, opts);\n  }\n\n  /**\n   * Disables Prometheus metrics\n   *\n   * @returns The builder instance for chaining\n   */\n  disableMetrics(): this {\n    return this.setEnabled('metrics', false);\n  }\n\n  /**\n   * Configures server health check endpoint.\n   *\n   * @param opts - Health check configuration options\n   * @returns The builder instance for chaining\n   * @default { path: '/healthz', detailed: true, withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withHealthCheck({\n   *   path: '/health',\n   *   detailed: true\n   * })\n   * ```\n   */\n  withHealthCheck(opts: Partial<NonNullable<ServerConfig['healthCheck']>>): this {\n    this.mergeConfig('healthCheck', opts as NonNullable<ServerConfig['healthCheck']>);\n    return this;\n  }\n\n  /**\n   * Configures OpenAPI/Swagger documentation for the API.\n   *\n   * @param opts - OpenAPI configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, mountPath: '/docs', verbose: false, withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withOpenApi({\n   *   enable: true,\n   *   path: '/api-docs',\n   *   filePath: './openapi.yaml'\n   * })\n   * ```\n   */\n  withOpenApi(opts: Partial<NonNullable<ServerConfig['openApi']>>): this {\n    this.mergeConfig('openApi', opts as NonNullable<ServerConfig['openApi']>);\n    return this;\n  }\n\n  /**\n   * Enables OpenAPI documentation with required file path\n   *\n   * @param filePath - Path to OpenAPI specification file (required)\n   * @param opts - Optional OpenAPI configuration\n   * @returns The builder instance for chaining\n   */\n  enableOpenApi(\n    filePath: string,\n    opts: Omit<Partial<NonNullable<ServerConfig['openApi']>>, 'enable' | 'filePath'> = {}\n  ): this {\n    this.setEnabled('openApi', true, { filePath, ...opts });\n    return this;\n  }\n\n  /**\n   * Disables OpenAPI documentation\n   *\n   * @returns The builder instance for chaining\n   */\n  disableOpenApi(): this {\n    return this.setEnabled('openApi', false);\n  }\n\n  /**\n   * Configures the server as a microservice with versioning.\n   *\n   * @param opts - Microservice configuration options including app name and service version\n   * @returns The builder instance for chaining\n   * @default { isMicroservice: false, appName: 'express_app' }\n   *\n   * @example\n   * ```typescript\n   * builder.withMicroService({\n   *   appName: 'user-service',\n   *   serviceVersion: {\n   *     enable: true,\n   *     version: '1.2.3'\n   *   }\n   * })\n   * ```\n   */\n  withMicroService(opts: {\n    appName: NonNullable<ServerConfig['appName']>;\n    serviceVersion: Partial<NonNullable<ServerConfig['serviceVersion']>>;\n  }): this {\n    this.config.isMicroservice = true;\n    this.config.appName = opts.appName;\n\n    this.mergeConfig('serviceVersion', opts.serviceVersion as NonNullable<ServerConfig['serviceVersion']>);\n    return this;\n  }\n\n  /**\n   * Configures the trust proxy settings to determine if X-Forwarded-* headers should be trusted.\n   *\n   * @param opts - Trust proxy configuration options\n   * @returns The builder instance for chaining\n   * @default false\n   *\n   * @example\n   * ```typescript\n   * // Trust proxy headers (useful when behind a load balancer)\n   * builder.withTrustProxy(true)\n   * ```\n   */\n  withTrustProxy(opts: NonNullable<ServerConfig['trustProxy']>): this {\n    this.config.trustProxy = opts;\n    return this;\n  }\n\n  /**\n   * Configures the request ID middleware for tracing requests across services.\n   *\n   * @param opts - Request ID configuration options\n   * @returns The builder instance for chaining\n   * @default { headerName: 'x-request-id', exposeHeader: true }\n   *\n   * @example\n   * ```typescript\n   * builder.withRequestId({\n   *   headerName: 'X-Request-Id',\n   *   generator: () => crypto.randomUUID()\n   * })\n   * ```\n   */\n  withRequestId(opts: Partial<NonNullable<ServerConfig['requestId']>>): this {\n    this.mergeConfig('requestId', opts as NonNullable<ServerConfig['requestId']>);\n    return this;\n  }\n\n  /**\n   * Configures the response time middleware for measuring request processing times.\n   *\n   * @param opts - Response time configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, addHeader: true, logOnComplete: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withResponseTime({\n   *   enable: true,\n   *   addHeader: true,\n   *   logOnComplete: true\n   * })\n   * ```\n   */\n  withResponseTime(opts: Partial<NonNullable<ServerConfig['responseTime']>>): this {\n    this.mergeConfig('responseTime', opts as NonNullable<ServerConfig['responseTime']>);\n    return this;\n  }\n\n  /**\n   * Enables response time tracking with default or custom settings\n   *\n   * @param opts - Optional response time configuration\n   * @returns The builder instance for chaining\n   */\n  enableResponseTime(opts: Omit<Partial<NonNullable<ServerConfig['responseTime']>>, 'enable'> = {}): this {\n    this.setEnabled('responseTime', true, opts);\n    return this;\n  }\n\n  /**\n   * Disables response time tracking\n   *\n   * @returns The builder instance for chaining\n   */\n  disableResponseTime(): this {\n    return this.setEnabled('responseTime', false);\n  }\n\n  /**\n   * Configures the body parser middleware options for parsing request bodies.\n   *\n   * @param opts - Body parser configuration options\n   * @returns The builder instance for chaining\n   * @default { json: { limit: '1mb' }, urlencoded: { extended: true, limit: '1mb' } }\n   *\n   * @example\n   * ```typescript\n   * builder.withBodyParser({\n   *   json: {\n   *     limit: '1mb'\n   *   },\n   *   urlencoded: {\n   *     extended: true,\n   *     limit: '1mb'\n   *   }\n   * })\n   * ```\n   */\n  withBodyParser(opts: NonNullable<ServerConfig['bodyParser']>): this {\n    this.config.bodyParser = deepObjMerge({}, this.config.bodyParser ?? {}, opts);\n    return this;\n  }\n\n  /**\n   * Configures cookie parsing middleware.\n   *\n   * @param opts - Cookie parser options or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false\n   *\n   * @example\n   * ```typescript\n   * // Enable cookie parsing with default options\n   * builder.withCookies(true)\n   *\n   * // Enable cookie parsing with specific options\n   * builder.withCookies({\n   *   secret: 'your-secret-key',\n   *   secure: true\n   * })\n   * ```\n   */\n  withCookies(opts: ServerConfig['cookieParser']): this {\n    this.config.cookieParser = opts;\n    return this;\n  }\n\n  /**\n   * Configures the logger used by the server.\n   *\n   * @param opts - Logger configuration options\n   * @returns The builder instance for chaining\n   * @default { name: 'express_app', level: 'info', prettyPrint: true in dev, singleLine: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withLogger({\n   *   level: 'info',\n   *   prettyPrint: true,\n   *   singleLine: false\n   * })\n   * ```\n   */\n  withLogger(opts: Partial<NonNullable<ServerConfig['logger']>>): this {\n    this.mergeConfig('logger', opts as NonNullable<ServerConfig['logger']>);\n    return this;\n  }\n\n  /**\n   * Adds a static folder to serve files from.\n   *\n   * @param folder - Static folder configuration\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withStaticFolder({\n   *   path: '/assets',\n   *   directory: './public',\n   *   options: { maxAge: '1d' }\n   * })\n   * ```\n   */\n  withStaticFolder(folder: NonNullable<ServerConfig['staticFolders']>[number]): this {\n    if (!folder.path) throw new Error('Static folder requires a path');\n    const folders = [...(this.config.staticFolders ?? []), folder];\n    this.config.staticFolders = Array.from(new Map(folders.map(f => [f.path, f])).values());\n    return this;\n  }\n\n  /**\n   * Sets global headers to be included in all responses.\n   *\n   * @param headers - Object containing header name/value pairs or functions that return values\n   * @returns The builder instance for chaining\n   * @default {}\n   *\n   * @example\n   * ```typescript\n   * builder.withGlobalHeaders({\n   *   'X-Powered-By': 'Catbee',\n   *   'Server-Time': () => new Date().toISOString()\n   * })\n   * ```\n   */\n  withGlobalHeaders(headers: NonNullable<ServerConfig['globalHeaders']>): this {\n    this.mergeConfig('globalHeaders', headers);\n    return this;\n  }\n\n  /**\n   * Sets a global prefix for all routes.\n   *\n   * @param prefix - The prefix to prepend to all routes (e.g., '/api/v1')\n   * @returns The builder instance for chaining\n   * @default '/'\n   *\n   * @example\n   * ```typescript\n   * builder.withGlobalPrefix('/api/v1')\n   * ```\n   */\n  withGlobalPrefix(prefix: string): this {\n    this.config.globalPrefix = prefix;\n    return this;\n  }\n\n  /**\n   * Applies custom configuration overrides directly.\n   *\n   * @param overrides - Custom configuration options to merge\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withCustom({\n   *   port: 8080,\n   *   customMiddleware: myMiddlewareFunction\n   * })\n   * ```\n   */\n  withCustom(overrides: Partial<ServerConfig>): this {\n    this.config = deepObjMerge({}, this.config, overrides);\n    return this;\n  }\n\n  /**\n   * Configures HTTPS server options.\n   *\n   * @param opts - HTTPS configuration (key, cert, ca, passphrase, etc.)\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withHttps({\n   *   key: './localhost-key.pem',\n   *   cert: './localhost-cert.pem'\n   * })\n   * ```\n   */\n  withHttps(opts: NonNullable<ServerConfig['https']>): this {\n    this.config.https = opts;\n    return this;\n  }\n\n  /**\n   * Builds and returns the final server configuration.\n   *\n   * This method merges the user-specified configuration with default values,\n   * ensures all sections with 'enable' flags are properly structured, and\n   * produces the final configuration to be used by the server.\n   *\n   * @returns The complete ServerConfig object\n   *\n   * @example\n   * ```typescript\n   * const config = new ServerConfigBuilder()\n   *   .withPort(3000)\n   *   .withHost('localhost')\n   *   .withCors(true)\n   *   .build();\n   * ```\n   */\n  build() {\n    const config = deepObjMerge({}, defaultServerConfig, this.config) as ServerConfig;\n\n    // Common validation\n    if (config.openApi?.enable && !config.openApi.filePath) {\n      throw new Error('OpenAPI is enabled but no filePath is specified');\n    }\n\n    return Object.freeze({\n      ...config,\n      [BUILD_MARKER]: true\n    });\n  }\n\n  private mergeConfig<K extends keyof ServerConfig>(key: K, value: Partial<NonNullable<ServerConfig[K]>>): void {\n    const current =\n      typeof this.config[key] === 'object' && this.config[key] !== null\n        ? (this.config[key] as NonNullable<ServerConfig[K]>)\n        : {};\n    this.config[key] = deepObjMerge({}, current, value) as NonNullable<ServerConfig[K]>;\n  }\n\n  private setEnabled<K extends keyof ServerConfig>(\n    key: K,\n    enable: boolean,\n    overrides: Partial<NonNullable<ServerConfig[K]>> = {}\n  ): this {\n    this.mergeConfig(key, { ...overrides, enable });\n    return this;\n  }\n}\n"]}
+{"version":3,"file":"server.builder.js","sourceRoot":"","sources":["../../../src/servers/server.builder.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { deepObjMerge } from '../utils/obj.utils';\nimport { ServerConfig } from '../types/server';\nimport { defaultServerConfig } from '../config';\nimport { isPort } from '../utils/validate.utils';\n\n/**\n * Builder class for creating and configuring an Express server configuration.\n *\n * This class provides a fluent interface to configure all aspects of the Express server\n * including security settings, middleware, routing, and more.\n *\n * @example\n * ```typescript\n * const serverConfig = new ServerConfigBuilder()\n *   .withPort(3000)\n *   .withHost('localhost')\n *   .enableCors()\n *   .enableHelmet()\n *   .build();\n * ```\n */\n\nexport const BUILD_MARKER = Symbol.for('catbee.express.server.build');\n\nexport class ServerConfigBuilder {\n  private config: Partial<ServerConfig> = {};\n\n  /**\n   * Validates that a port number is valid and usable.\n   *\n   * @private\n   * @param port - The port number to validate\n   * @throws {Error} If port is not an integer or is outside the valid range (1-65535)\n   */\n  private validatePort(port: number): void {\n    if (!isPort(port)) {\n      throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);\n    }\n  }\n\n  /**\n   * Sets the port the server will listen on.\n   *\n   * @param port - The port number (1-65535)\n   * @returns The builder instance for chaining\n   * @throws {Error} If port is invalid\n   * @default 3000 (can be overridden via PORT env variable)\n   *\n   * @example\n   * ```typescript\n   * builder.withPort(3000)\n   * ```\n   */\n  withPort(port: number): this {\n    this.validatePort(port);\n    this.config.port = port;\n    return this;\n  }\n\n  /**\n   * Sets the hostname the server will bind to.\n   *\n   * @param host - The hostname (e.g., 'localhost', '0.0.0.0', '127.0.0.1')\n   * @returns The builder instance for chaining\n   * @default '0.0.0.0' (can be overridden via HOST env variable)\n   *\n   * @example\n   * ```typescript\n   * builder.withHost('0.0.0.0') // Listen on all interfaces\n   * ```\n   */\n  withHost(host: string): this {\n    this.config.host = host;\n    return this;\n  }\n\n  /**\n   * Configures Cross-Origin Resource Sharing (CORS) for the server.\n   *\n   * @param opts - CORS options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (CORS is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable CORS with default options\n   * builder.withCors(true)\n   *\n   * // Configure CORS with specific options\n   * builder.withCors({\n   *   origin: ['https://example.com'],\n   *   methods: ['GET', 'POST']\n   * })\n   * ```\n   */\n  withCors(opts: ServerConfig['cors']): this {\n    this.config.cors = opts;\n    return this;\n  }\n\n  /**\n   * Enables CORS with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableCors(): this {\n    return this.withCors(true);\n  }\n\n  /**\n   * Disables CORS\n   *\n   * @returns The builder instance for chaining\n   */\n  disableCors(): this {\n    return this.withCors(false);\n  }\n\n  /**\n   * Configures the Helmet middleware for setting HTTP security headers.\n   *\n   * @param opts - Helmet options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (Helmet is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable Helmet with default settings\n   * builder.withHelmet(true)\n   *\n   * // Configure Helmet with specific options\n   * builder.withHelmet({\n   *   contentSecurityPolicy: false,\n   *   xssFilter: true\n   * })\n   * ```\n   */\n  withHelmet(opts: ServerConfig['helmet']): this {\n    this.config.helmet = opts;\n    return this;\n  }\n\n  /**\n   * Enables Helmet with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableHelmet(): this {\n    return this.withHelmet(true);\n  }\n\n  /**\n   * Disables Helmet\n   *\n   * @returns The builder instance for chaining\n   */\n  disableHelmet(): this {\n    return this.withHelmet(false);\n  }\n\n  /**\n   * Configures response compression middleware.\n   *\n   * @param opts - Compression options object or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false (Compression is disabled by default)\n   *\n   * @example\n   * ```typescript\n   * // Enable compression with default settings\n   * builder.withCompression(true)\n   *\n   * // Configure compression with specific options\n   * builder.withCompression({\n   *   level: 6,\n   *   threshold: 1024\n   * })\n   * ```\n   */\n  withCompression(opts: ServerConfig['compression']): this {\n    this.config.compression = opts;\n    return this;\n  }\n\n  /**\n   * Enables compression with default settings\n   *\n   * @returns The builder instance for chaining\n   */\n  enableCompression(): this {\n    return this.withCompression(true);\n  }\n\n  /**\n   * Disables compression\n   *\n   * @returns The builder instance for chaining\n   */\n  disableCompression(): this {\n    return this.withCompression(false);\n  }\n\n  /**\n   * Configures rate limiting to protect against brute-force attacks.\n   *\n   * @param opts - Rate limit configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, windowMs: 15 * 60 * 1000, max: 100, message: 'Too many requests', standardHeaders: true, legacyHeaders: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withRateLimit({\n   *   enable: true,\n   *   windowMs: 15 * 60 * 1000, // 15 minutes\n   *   max: 100 // limit each IP to 100 requests per windowMs\n   * })\n   * ```\n   */\n  withRateLimit(opts: Partial<ServerConfig['rateLimit']>): this {\n    this.mergeConfig('rateLimit', opts as NonNullable<ServerConfig['rateLimit']>);\n    return this;\n  }\n\n  /**\n   * Enables rate limiting with default or custom settings\n   *\n   * @param opts - Optional rate limit configuration (max requests, window, etc.)\n   * @returns The builder instance for chaining\n   */\n  enableRateLimit(opts: Omit<Partial<NonNullable<ServerConfig['rateLimit']>>, 'enable'> = {}): this {\n    return this.setEnabled('rateLimit', true, opts);\n  }\n\n  /**\n   * Disables rate limiting\n   *\n   * @returns The builder instance for chaining\n   */\n  disableRateLimit(): this {\n    return this.setEnabled('rateLimit', false);\n  }\n\n  /**\n   * Configures HTTP request logging middleware.\n   *\n   * @param opts - Request logging configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: true in dev/false in prod, ignorePaths: ['/healthz', '/favicon.ico', '/metrics', '/docs', '/.well-known'], skipNotFoundRoutes: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withRequestLogging({\n   *   enable: true,\n   *   ignorePaths: ['/health', '/metrics'],\n   *   skipNotFoundRoutes: true\n   * })\n   * ```\n   */\n  withRequestLogging(opts: Partial<NonNullable<ServerConfig['requestLogging']>>): this {\n    this.mergeConfig('requestLogging', opts as NonNullable<ServerConfig['requestLogging']>);\n    return this;\n  }\n\n  /**\n   * Enables request logging with default or custom settings\n   *\n   * @param opts - Optional request logging configuration\n   * @returns The builder instance for chaining\n   */\n  enableRequestLogging(opts: Omit<Partial<NonNullable<ServerConfig['requestLogging']>>, 'enable'> = {}): this {\n    return this.setEnabled('requestLogging', true, opts);\n  }\n\n  /**\n   * Disables request logging\n   *\n   * @returns The builder instance for chaining\n   */\n  disableRequestLogging(): this {\n    return this.setEnabled('requestLogging', false);\n  }\n\n  /**\n   * Configures server metrics collection and endpoints.\n   *\n   * @param opts - Metrics configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, path: '/metrics', withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withMetrics({\n   *   enable: true,\n   *   path: '/metrics'\n   * })\n   * ```\n   */\n  withMetrics(opts: Partial<NonNullable<ServerConfig['metrics']>>): this {\n    this.mergeConfig('metrics', opts as NonNullable<ServerConfig['metrics']>);\n    return this;\n  }\n\n  /**\n   * Enables Prometheus metrics collection and endpoint\n   *\n   * @param opts - Optional metrics configuration\n   * @returns The builder instance for chaining\n   */\n  enableMetrics(opts: Omit<Partial<NonNullable<ServerConfig['metrics']>>, 'enable'> = {}): this {\n    return this.setEnabled('metrics', true, opts);\n  }\n\n  /**\n   * Disables Prometheus metrics\n   *\n   * @returns The builder instance for chaining\n   */\n  disableMetrics(): this {\n    return this.setEnabled('metrics', false);\n  }\n\n  /**\n   * Configures server health check endpoint.\n   *\n   * @param opts - Health check configuration options\n   * @returns The builder instance for chaining\n   * @default { path: '/healthz', detailed: true, withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withHealthCheck({\n   *   path: '/health',\n   *   detailed: true\n   * })\n   * ```\n   */\n  withHealthCheck(opts: Partial<NonNullable<ServerConfig['healthCheck']>>): this {\n    this.mergeConfig('healthCheck', opts as NonNullable<ServerConfig['healthCheck']>);\n    return this;\n  }\n\n  /**\n   * Configures OpenAPI/Swagger documentation for the API.\n   *\n   * @param opts - OpenAPI configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, mountPath: '/docs', verbose: false, withGlobalPrefix: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withOpenApi({\n   *   enable: true,\n   *   path: '/api-docs',\n   *   filePath: './openapi.yaml'\n   * })\n   * ```\n   */\n  withOpenApi(opts: Partial<NonNullable<ServerConfig['openApi']>>): this {\n    this.mergeConfig('openApi', opts as NonNullable<ServerConfig['openApi']>);\n    return this;\n  }\n\n  /**\n   * Enables OpenAPI documentation with required file path\n   *\n   * @param filePath - Path to OpenAPI specification file (required)\n   * @param opts - Optional OpenAPI configuration\n   * @returns The builder instance for chaining\n   */\n  enableOpenApi(\n    filePath: string,\n    opts: Omit<Partial<NonNullable<ServerConfig['openApi']>>, 'enable' | 'filePath'> = {}\n  ): this {\n    this.setEnabled('openApi', true, { filePath, ...opts });\n    return this;\n  }\n\n  /**\n   * Disables OpenAPI documentation\n   *\n   * @returns The builder instance for chaining\n   */\n  disableOpenApi(): this {\n    return this.setEnabled('openApi', false);\n  }\n\n  /**\n   * Configures the server as a microservice with versioning.\n   *\n   * @param opts - Microservice configuration options including app name and service version\n   * @returns The builder instance for chaining\n   * @default { isMicroservice: false, appName: 'express_app' }\n   *\n   * @example\n   * ```typescript\n   * builder.withMicroService({\n   *   appName: 'user-service',\n   *   serviceVersion: {\n   *     enable: true,\n   *     version: '1.2.3'\n   *   }\n   * })\n   * ```\n   */\n  withMicroService(opts: {\n    appName: NonNullable<ServerConfig['appName']>;\n    serviceVersion: Partial<NonNullable<ServerConfig['serviceVersion']>>;\n  }): this {\n    this.config.isMicroservice = true;\n    this.config.appName = opts.appName;\n\n    this.mergeConfig('serviceVersion', opts.serviceVersion as NonNullable<ServerConfig['serviceVersion']>);\n    return this;\n  }\n\n  /**\n   * Configures the trust proxy settings to determine if X-Forwarded-* headers should be trusted.\n   *\n   * @param opts - Trust proxy configuration options\n   * @returns The builder instance for chaining\n   * @default false\n   *\n   * @example\n   * ```typescript\n   * // Trust proxy headers (useful when behind a load balancer)\n   * builder.withTrustProxy(true)\n   * ```\n   */\n  withTrustProxy(opts: NonNullable<ServerConfig['trustProxy']>): this {\n    this.config.trustProxy = opts;\n    return this;\n  }\n\n  /**\n   * Configures the request ID middleware for tracing requests across services.\n   *\n   * @param opts - Request ID configuration options\n   * @returns The builder instance for chaining\n   * @default { headerName: 'x-request-id', exposeHeader: true }\n   *\n   * @example\n   * ```typescript\n   * builder.withRequestId({\n   *   headerName: 'X-Request-Id',\n   *   generator: () => crypto.randomUUID()\n   * })\n   * ```\n   */\n  withRequestId(opts: Partial<NonNullable<ServerConfig['requestId']>>): this {\n    this.mergeConfig('requestId', opts as NonNullable<ServerConfig['requestId']>);\n    return this;\n  }\n\n  /**\n   * Configures the response time middleware for measuring request processing times.\n   *\n   * @param opts - Response time configuration options\n   * @returns The builder instance for chaining\n   * @default { enable: false, addHeader: true, logOnComplete: false }\n   *\n   * @example\n   * ```typescript\n   * builder.withResponseTime({\n   *   enable: true,\n   *   addHeader: true,\n   *   logOnComplete: true\n   * })\n   * ```\n   */\n  withResponseTime(opts: Partial<NonNullable<ServerConfig['responseTime']>>): this {\n    this.mergeConfig('responseTime', opts as NonNullable<ServerConfig['responseTime']>);\n    return this;\n  }\n\n  /**\n   * Enables response time tracking with default or custom settings\n   *\n   * @param opts - Optional response time configuration\n   * @returns The builder instance for chaining\n   */\n  enableResponseTime(opts: Omit<Partial<NonNullable<ServerConfig['responseTime']>>, 'enable'> = {}): this {\n    this.setEnabled('responseTime', true, opts);\n    return this;\n  }\n\n  /**\n   * Disables response time tracking\n   *\n   * @returns The builder instance for chaining\n   */\n  disableResponseTime(): this {\n    return this.setEnabled('responseTime', false);\n  }\n\n  /**\n   * Configures the body parser middleware options for parsing request bodies.\n   *\n   * @param opts - Body parser configuration options\n   * @returns The builder instance for chaining\n   * @default { json: { limit: '1mb' }, urlencoded: { extended: true, limit: '1mb' } }\n   *\n   * @example\n   * ```typescript\n   * builder.withBodyParser({\n   *   json: {\n   *     limit: '1mb'\n   *   },\n   *   urlencoded: {\n   *     extended: true,\n   *     limit: '1mb'\n   *   }\n   * })\n   * ```\n   */\n  withBodyParser(opts: NonNullable<ServerConfig['bodyParser']>): this {\n    this.config.bodyParser = deepObjMerge({}, this.config.bodyParser ?? {}, opts);\n    return this;\n  }\n\n  /**\n   * Configures cookie parsing middleware.\n   *\n   * @param opts - Cookie parser options or boolean (true to enable with defaults, false to disable)\n   * @returns The builder instance for chaining\n   * @default false\n   *\n   * @example\n   * ```typescript\n   * // Enable cookie parsing with default options\n   * builder.withCookies(true)\n   *\n   * // Enable cookie parsing with specific options\n   * builder.withCookies({\n   *   secret: 'your-secret-key',\n   *   secure: true\n   * })\n   * ```\n   */\n  withCookies(opts: ServerConfig['cookieParser']): this {\n    this.config.cookieParser = opts;\n    return this;\n  }\n\n  /**\n   * Adds a static folder to serve files from.\n   *\n   * @param folder - Static folder configuration\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withStaticFolder({\n   *   path: '/assets',\n   *   directory: './public',\n   *   options: { maxAge: '1d' }\n   * })\n   * ```\n   */\n  withStaticFolder(folder: NonNullable<ServerConfig['staticFolders']>[number]): this {\n    if (!folder.path) throw new Error('Static folder requires a path');\n    const folders = [...(this.config.staticFolders ?? []), folder];\n    this.config.staticFolders = Array.from(new Map(folders.map(f => [f.path, f])).values());\n    return this;\n  }\n\n  /**\n   * Sets global headers to be included in all responses.\n   *\n   * @param headers - Object containing header name/value pairs or functions that return values\n   * @returns The builder instance for chaining\n   * @default {}\n   *\n   * @example\n   * ```typescript\n   * builder.withGlobalHeaders({\n   *   'X-Powered-By': 'Catbee',\n   *   'Server-Time': () => new Date().toISOString()\n   * })\n   * ```\n   */\n  withGlobalHeaders(headers: NonNullable<ServerConfig['globalHeaders']>): this {\n    this.mergeConfig('globalHeaders', headers);\n    return this;\n  }\n\n  /**\n   * Sets a global prefix for all routes.\n   *\n   * @param prefix - The prefix to prepend to all routes (e.g., '/api/v1')\n   * @returns The builder instance for chaining\n   * @default '/'\n   *\n   * @example\n   * ```typescript\n   * builder.withGlobalPrefix('/api/v1')\n   * ```\n   */\n  withGlobalPrefix(prefix: string): this {\n    this.config.globalPrefix = prefix;\n    return this;\n  }\n\n  /**\n   * Applies custom configuration overrides directly.\n   *\n   * @param overrides - Custom configuration options to merge\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withCustom({\n   *   port: 8080,\n   *   customMiddleware: myMiddlewareFunction\n   * })\n   * ```\n   */\n  withCustom(overrides: Partial<ServerConfig>): this {\n    this.config = deepObjMerge({}, this.config, overrides);\n    return this;\n  }\n\n  /**\n   * Configures HTTPS server options.\n   *\n   * @param opts - HTTPS configuration (key, cert, ca, passphrase, etc.)\n   * @returns The builder instance for chaining\n   *\n   * @example\n   * ```typescript\n   * builder.withHttps({\n   *   key: './localhost-key.pem',\n   *   cert: './localhost-cert.pem'\n   * })\n   * ```\n   */\n  withHttps(opts: NonNullable<ServerConfig['https']>): this {\n    this.config.https = opts;\n    return this;\n  }\n\n  /**\n   * Builds and returns the final server configuration.\n   *\n   * This method merges the user-specified configuration with default values,\n   * ensures all sections with 'enable' flags are properly structured, and\n   * produces the final configuration to be used by the server.\n   *\n   * @returns The complete ServerConfig object\n   *\n   * @example\n   * ```typescript\n   * const config = new ServerConfigBuilder()\n   *   .withPort(3000)\n   *   .withHost('localhost')\n   *   .withCors(true)\n   *   .build();\n   * ```\n   */\n  build(): Readonly<ServerConfig> {\n    const config = deepObjMerge({}, defaultServerConfig, this.config) as ServerConfig;\n\n    // Common validation\n    if (config.openApi?.enable && !config.openApi.filePath) {\n      throw new Error('OpenAPI is enabled but no filePath is specified');\n    }\n\n    return Object.freeze({\n      ...config,\n      [BUILD_MARKER]: true\n    });\n  }\n\n  private mergeConfig<K extends keyof ServerConfig>(key: K, value: Partial<NonNullable<ServerConfig[K]>>): void {\n    const current =\n      typeof this.config[key] === 'object' && this.config[key] !== null\n        ? (this.config[key] as NonNullable<ServerConfig[K]>)\n        : {};\n    this.config[key] = deepObjMerge({}, current, value) as NonNullable<ServerConfig[K]>;\n  }\n\n  private setEnabled<K extends keyof ServerConfig>(\n    key: K,\n    enable: boolean,\n    overrides: Partial<NonNullable<ServerConfig[K]>> = {}\n  ): this {\n    this.mergeConfig(key, { ...overrides, enable });\n    return this;\n  }\n}\n"]}

package/build/esnext/servers/server.d.ts

@@ -183,12 +183,12 @@ export declare class ExpressServer {
      *
      * @param signals Array of process signals to listen for (default: SIGINT, SIGTERM)
      */
-    enableGracefulShutdown(signals?: NodeJS.Signals[]): void;
+    enableGracefulShutdown(signals?: NodeJS.Signals[]): this;
     /**
      * Set an externally created base router.
      * This will override the internal rootRouter.
      */
-    setBaseRouter(router: Router): void;
+    setBaseRouter(router: Router): this;
     /**
      * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).
      */

package/build/esnext/servers/server.js

@@ -38,7 +38,7 @@ import client, { Counter, Histogram } from 'prom-client';
 import { NotFoundException } from '../utils/exception.utils';
 import fs from 'fs';
 import { apiReference } from '@scalar/express-api-reference';
-import { defaultServerConfig, setConfig } from '../config';
+import { defaultServerConfig } from '../config';
 import { deepObjMerge } from '../utils/obj.utils';
 import { fileExists } from '../utils/fs.utils';
 import { BUILD_MARKER } from './server.builder';
@@ -140,18 +140,6 @@ export class ExpressServer {
         if ((_b = config.healthCheck) === null || _b === void 0 ? void 0 : _b.checks) {
             this.healthChecks.push(...config.healthCheck.checks);
         }
-        // Logger
-        if (this.config.logger) {
-            const { name, level, prettyPrint: pretty, singleLine } = this.config.logger;
-            setConfig({
-                logger: {
-                    name: name !== null && name !== void 0 ? name : 'express_app',
-                    level: level !== null && level !== void 0 ? level : 'info',
-                    pretty: pretty !== null && pretty !== void 0 ? pretty : Env.isDev(),
-                    singleLine: singleLine !== null && singleLine !== void 0 ? singleLine : false
-                }
-            });
-        }
         // Set global prefix (normalize to empty string or "/prefix" without trailing slash)
         this.globalPrefix = this.normalizePath((_c = this.config.globalPrefix) !== null && _c !== void 0 ? _c : '', false);
         this.hooks = hooks;
@@ -723,6 +711,7 @@ export class ExpressServer {
                 }
             });
         });
+        return this;
     }
     /**
      * Set an externally created base router.
@@ -730,6 +719,7 @@ export class ExpressServer {
      */
     setBaseRouter(router) {
         this.externalRouter = router;
+        return this;
     }
     /**
      * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).