@catbee/utils 0.0.5 → 0.0.6

package/LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+The MIT License
+
+Copyright (c) 2025 Catbee Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -56,6 +56,7 @@ console.log(isEmail("user@example.com")); // true
 - [**URL Utilities**](#-url-utilities)
 - [**Validate Utilities**](#-validate-utilities)
 - [**Decorators Utilities**](#-decorators-utilities)
+- [**Express Server**](#-express-server)
 
 ---
 
@@ -536,11 +537,11 @@ logger.error({ context: "some context" }, "Error occurred");
 
 ## 🧩 Middleware Utilities
 
-- `requestId(options?): Middleware` – Generate and attach a unique request ID to each request.
-- `responseTime(options?): Middleware` – Measure and log the response time for each request.
+- `requestId(options: { headerName?: string; exposeHeader?: boolean; generator?: () => string }): Middleware` – Generate and attach a unique request ID to each request.
+- `responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }): Middleware` – Measure and log the response time for each request.
 - `timeout(timeoutMs?: number): Middleware` – Abort requests that exceed a specified timeout.
 - `setupRequestContext(): Middleware` – Set up the request context for each incoming request.
-- `errorHandler(options?): Middleware` – Centralized error handling middleware.
+- `errorHandler(options: { logErrors?: boolean; includeDetails?: boolean }): Middleware` – Centralized error handling middleware.
 
 **Example:**
 ```ts
@@ -557,7 +558,8 @@ A set of helpers for working with JavaScript objects, including deep merging, fl
 - `isObjEmpty(obj: Record<any, any>): boolean` – Check if an object has no own properties.
 - `pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>` – Create a new object with only the specified keys.
 - `omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>` – Create a new object without the specified keys.
-- `deepObjMerge<T>(target: T, source: Partial<T>): T` – Deeply merge two objects.
+- `deepObjMerge<T extends object>(target: T, ...sources: any[]): T` – Deeply merge multiple objects into the target.
+- `isPlainObject(value: any): value is Record<string, any>` – Check if a value is a plain object.
 - `flattenObject<T>(obj: T, prefix?: string): Record<string, any>` – Flatten a nested object into dot notation.
 - `getValueByPath<T>(obj: T, path: string): any` – Get a value from an object by dot path.
 - `setValueByPath<T>(obj: T, path: string, value: any): T` – Set a value in an object by dot path.
@@ -828,6 +830,7 @@ const url = appendQueryParams('https://example.com', { page: 1, limit: 10 });
 
 A comprehensive suite of validators for checking strings, numbers, objects, arrays, and common formats such as email, UUID, IP, and more. Useful for input validation and API parameter checks.
 
+- `isPort(str: string | number): boolean` – Check if a string or number is a valid port number.
 - `isEmail(str: string): boolean` – Check if a string is a valid email address.
 - `isUUID(str: string): boolean` – Check if a string is a valid UUID.
 - `isURL(str: string): boolean` – Check if a string is a valid URL.
@@ -926,6 +929,221 @@ registerControllers(router, [ExampleController]);
 - All parameter decorators (`@Query`, `@Param`, etc.) are optional and can be used in any order.
 - `registerControllers(router, controllers)` will register all routes and apply middlewares, hooks, status codes, and headers as defined.
 
+## 🚀 Express Server
+
+A production-ready Express server with enterprise-grade features for building robust web services and APIs.
+
+### Features
+
+- **Security**: CORS, Helmet, rate limiting, timeouts, body size limits
+- **Monitoring**: Request logging, Prometheus metrics, health checks
+- **Performance**: Response compression, static file serving, conditional settings
+- **Reliability**: Graceful shutdown, connection tracking, error handling
+- **Developer UX**: OpenAPI docs, debugging tools
+- **Extensibility**: Lifecycle hooks, middleware registration, custom routes
+
+### Getting Started
+
+Create a server with the fluent builder pattern:
+
+```ts
+import { ServerConfigBuilder, ExpressServer } from "@catbee/utils";
+
+// Configure the server
+const config = new ServerConfigBuilder()
+  .withPort(3000)
+  .withHost('localhost')
+  .enableCors()
+  .enableHelmet()
+  .enableCompression()
+  .withGlobalPrefix('/api')
+  .withRequestLogging({ 
+    enable: true,
+    ignorePaths: ['/healthz', '/metrics']
+  })
+  .enableMetrics()
+  .build();
+
+// Create and start the server
+const server = new ExpressServer(config, {
+  beforeStart: (app) => console.log('Server about to start...'),
+  afterStart: (server) => console.log('Server started successfully!')
+});
+
+// Register health checks
+server.registerHealthCheck('database', async () => {
+  return await checkDatabaseConnection();
+});
+
+// Register routes
+const router = server.createRouter('/users');
+router.get('/', (req, res) => {
+  res.json({ users: [] });
+});
+
+// Start the server
+await server.start();
+
+// Enable graceful shutdown handling
+server.enableGracefulShutdown();
+```
+
+### Server Configuration Builder
+
+Use the fluent builder API to configure all aspects of your server:
+
+```ts
+import { ServerConfigBuilder } from "@catbee/utils";
+
+const config = new ServerConfigBuilder()
+  // Basic configuration
+  .withPort(3000)                     // Set listen port
+  .withHost('0.0.0.0')                // Set listen address
+  .withGlobalPrefix('/api/v1')        // Set global route prefix
+
+  // Security
+  .enableCors()                       // Enable CORS (simple)
+  .withCors({                         // Configure CORS (advanced)
+    origin: ['https://example.com'],
+    methods: ['GET', 'POST']
+  })
+  .enableHelmet()                     // Enable secure headers
+  .enableRateLimit({                  // Configure rate limiting
+    max: 100,                        
+    windowMs: 15 * 60 * 1000
+  })
+
+  // Performance
+  .enableCompression()                // Enable response compression
+  .withStaticFolder({                 // Serve static files
+    path: '/assets',
+    directory: './public/assets',
+    maxAge: '1d'
+  })
+
+  // Monitoring
+  .enableMetrics({                    // Enable Prometheus metrics
+    path: '/metrics'
+  })
+  .withHealthCheck({                  // Configure health checks
+    path: '/health',
+    detailed: true
+  })
+  .enableResponseTime()               // Track response times
+  .enableRequestLogging()             // Log requests
+
+  // Documentation
+  .enableOpenApi('./openapi.yaml', {  // Enable OpenAPI docs
+    mountPath: '/docs'
+  })
+
+  // Microservice configuration
+  .withMicroService({                 // Configure as microservice
+    appName: 'user-service',
+    serviceVersion: {
+      enable: true,
+      version: '1.0.0'
+    }
+  })
+  
+  // Build final configuration
+  .build();
+```
+
+### Server Lifecycle Hooks
+
+Register hooks for key server lifecycle events:
+
+```ts
+const server = new ExpressServer(config, {
+  // Before server initialization (middleware setup)
+  beforeInit: (server) => {
+    console.log('Initializing server...');
+  },
+
+  // After server initialization (routes registered)
+  afterInit: (server) => {
+    console.log('Server initialized');
+  },
+
+  // Before server starts listening
+  beforeStart: (app) => {
+    console.log('Starting server...');
+  },
+
+  // After server has started listening
+  afterStart: (httpServer) => {
+    console.log('Server started');
+  },
+
+  // Before server begins shutdown
+  beforeStop: (httpServer) => {
+    console.log('Shutting down server...');
+  },
+
+  // After server has fully stopped
+  afterStop: () => {
+    console.log('Server stopped');
+  },
+
+  // Global request handler
+  onRequest: (req, res, next) => {
+    console.log('Processing request...');
+    next();
+  },
+
+  // Global response handler
+  onResponse: (req, res, next) => {
+    res.setHeader('X-Server-Time', new Date().toISOString());
+    next();
+  },
+
+  // Global error handler
+  onError: (err, req, res, next) => {
+    console.error('Error processing request:', err);
+    res.status(500).json({ error: 'Something went wrong' });
+  }
+});
+```
+
+### Health Checks
+
+Register health checks for monitoring service dependencies:
+
+```ts
+// Simple health check
+server.registerHealthCheck('storage', () => {
+  return fs.existsSync('./data');
+});
+
+// Async health check
+server.registerHealthCheck('database', async () => {
+  try {
+    await db.ping();
+    return true;
+  } catch (err) {
+    return false;
+  }
+});
+```
+
+### Graceful Shutdown
+
+Enable zero-downtime deployments with graceful shutdown:
+
+```ts
+// Enable graceful shutdown handling
+server.enableGracefulShutdown();
+
+// Manually trigger a graceful shutdown
+async function shutdown() {
+  console.log('Starting graceful shutdown...');
+  await server.stop();
+  console.log('Server stopped gracefully');
+  process.exit(0);
+}
+```
+
 ## 🏁 Usage
 
 Import only what you need:

package/build/esm/config.d.ts

@@ -1,4 +1,16 @@
-type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+import { LoggerLevels } from './utils/logger.utils';
+/**
+ * Extends Express Request interface to add request ID tracking.
+ * Added by requestId middleware during request processing.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            /** Unique request identifier (set by middleware) */
+            id?: string;
+        }
+    }
+}
 /**
  * Application runtime configuration loaded from environment variables.
  */
@@ -7,7 +19,7 @@ export declare let config: {
         /**
          * Logging level (e.g., 'info', 'debug', 'warn', 'error').
          */
-        level: LogLevel;
+        level: LoggerLevels;
         /**
          * Name of the logger instance (defaults to npm package name).
          */
@@ -17,6 +29,10 @@ export declare let config: {
          * Has no effect in production.
          */
         pretty: boolean;
+        /**
+         * Single line output for pretty-print (default: false)
+         */
+        singleLine: boolean;
     };
     http: {
         /**
@@ -31,6 +47,76 @@ export declare let config: {
         defaultTtl: number;
     };
 };
+export declare const defaultServerConfig: {
+    port: number;
+    host: string;
+    cors: false;
+    helmet: false;
+    compression: false;
+    bodyParser: {
+        json: {
+            limit: string;
+        };
+        urlencoded: {
+            extended: true;
+            limit: string;
+        };
+    };
+    cookieParser: false;
+    isMicroservice: false;
+    appName: string;
+    globalHeaders: {};
+    rateLimit: {
+        enable: false;
+        windowMs: number;
+        max: number;
+        message: string;
+        standardHeaders: true;
+        legacyHeaders: false;
+    };
+    requestLogging: {
+        enable: boolean;
+        ignorePaths: (req: import("express").Request<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>, _res: import("express").Response<any, Record<string, any>>) => boolean;
+        skipNotFoundRoutes: false;
+    };
+    openApi: {
+        enable: false;
+        mountPath: string;
+        verbose: false;
+        withGlobalPrefix: false;
+    };
+    healthCheck: {
+        path: string;
+        detailed: true;
+    };
+    requestTimeout: number;
+    responseTime: {
+        enable: false;
+        addHeader: true;
+        logOnComplete: false;
+    };
+    requestId: {
+        headerName: string;
+        exposeHeader: true;
+        generator: () => string;
+    };
+    logger: {
+        name: string;
+        level: LoggerLevels;
+        prettyPrint: false;
+        singleLine: false;
+    };
+    metrics: {
+        enable: false;
+        path: string;
+        withGlobalPrefix: false;
+    };
+    serviceVersion: {
+        enable: false;
+        headerName: string;
+        version: string;
+    };
+};
 /**
  * Update the @catbee/utils configuration.
  * @param value Partial configuration object.
@@ -41,5 +127,4 @@ export declare function setConfig(value: Partial<typeof config>): void;
  * @returns The current configuration object.
  */
 export declare function getConfig(): typeof config;
-export {};
 //# sourceMappingURL=config.d.ts.map