@catbee/utils 1.0.5 → 2.0.0-next.0

package/server/server.d.ts

@@ -0,0 +1,303 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * 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.
+ */
+
+import express, { Express, Router } from 'express';
+import http from 'http';
+import https from 'https';
+import { ServerConfig, ServerHooks } from '@catbee/utils/types';
+/**
+ * Generate standardized error message for missing dependencies.
+ */
+export declare const getDependencyErrorMessage: (packageName: string, x?: string) => string;
+/**
+ * Map of critical dependencies to their error messages.
+ */
+export declare const DependencyErrors: {
+    express: string;
+    helmet: string;
+    cors: string;
+    compression: string;
+    'express-rate-limit': string;
+    'cookie-parser': string;
+    '@scalar/express-api-reference': string;
+    'prom-client': string;
+};
+/**
+ * Production-ready Express server with enterprise features.
+ *
+ * Core Features:
+ * - Security: Helmet, CORS, rate limiting, timeouts
+ * - Monitoring: Request logs, metrics, health checks
+ * - Performance: Compression, caching, static files
+ * - Reliability: Graceful shutdown, error handling
+ * - Developer UX: OpenAPI docs, debugging tools
+ * - Extensibility: Hooks, middleware, custom routes
+ *
+ * Designed for microservices and production workloads.
+ * Includes K8s readiness probes and zero-downtime support.
+ */
+export declare class ExpressServer {
+    /** Prometheus client registry for metrics collection */
+    private register;
+    /** HTTP server instance (null when not running) */
+    protected server: http.Server | https.Server | null;
+    /** Merged configuration with defaults applied */
+    protected config: ServerConfig;
+    /** User-defined lifecycle hooks */
+    protected hooks: ServerHooks;
+    /** Global API prefix (from config) */
+    protected globalPrefix: string;
+    /** Internal fallback router */
+    private rootRouter;
+    /** User-supplied router */
+    private externalRouter?;
+    /** Internal Express app instance */
+    private app;
+    /** Set of active WebSocket connections */
+    private connections;
+    /** Flag indicating if the server is shutting down */
+    private isShuttingDown;
+    /**
+     * Collection of registered health check functions.
+     * These are executed when the health check endpoint is accessed.
+     */
+    private healthChecks;
+    /** Prometheus metrics for monitoring */
+    private requestCounter?;
+    private routeTimings?;
+    private requestSizes?;
+    private clientIPs?;
+    /** Promise that resolves when initialization (middleware + routes) is complete */
+    private initPromise;
+    /**
+     * Initializes server with intelligent defaults and security best practices.
+     * All settings can be customized via config and hooks.
+     *
+     * Default Security:
+     * - Secure headers (Helmet)
+     * - Rate limiting
+     * - Request timeouts
+     * - Body size limits
+     * - CORS protection
+     *
+     * Default Monitoring:
+     * - Request/Response logging
+     * - Prometheus metrics
+     * - Health checks
+     * - Request tracing
+     */
+    constructor(config: Partial<ServerConfig>, hooks?: ServerHooks);
+    /**
+     * Execute a lifecycle hook safely with comprehensive error handling.
+     * Prevents hook failures from crashing the server while logging issues.
+     *
+     * @param hook Name of the lifecycle hook to execute
+     * @param args Arguments to pass to the hook function
+     */
+    private runHook;
+    /**
+     * Initialize the Express server with middleware and routes.
+     */
+    private initialize;
+    /**
+     * Configure and register all middlewares in the optimal order.
+     *
+     * Middleware Order (CRITICAL - don't change without understanding implications):
+     * 1.  Basic server configuration (trust proxy, x-powered-by)
+     * 2.  Request ID generation (for tracing)
+     * 3.  Request context setup (for logging correlation)
+     * 4.  Timeout protection (prevents hanging requests)
+     * 5.  Response time tracking (for performance monitoring)
+     * 6.  Request logging (after ID/context setup)
+     * 7.  Custom request hooks
+     * 8.  Security middleware (rate limiting, CORS, Helmet)
+     * 9.  Response compression
+     * 10. Static file serving
+     * 11. Request parsing (body parsing, cookies)
+     * 12. API documentation (OpenAPI)
+     * 13. Global headers
+     * 14. Custom response hooks
+     */
+    protected setupMiddleware(): Promise<void>;
+    /**
+     * Configure server routes and error handling.
+     * Sets up in following order:
+     *
+     * 1. Built-in routes (health, metrics)
+     * 2. Application routes
+     * 3. 404 handler
+     * 4. Error handler
+     */
+    protected setupRoutes(): Promise<void>;
+    /**
+     * Register a new health check function for monitoring service dependencies.
+     *
+     * Health checks are executed when the health endpoint is accessed and
+     * help determine if the service is ready to handle requests.
+     *
+     * Examples:
+     * - Database connectivity
+     * - External service availability
+     * - File system access
+     * - Memory/CPU usage checks
+     *
+     * @param name Unique identifier for the check (used in detailed responses)
+     * @param check Function returning boolean or Promise<boolean> indicating health
+     * @returns This instance for method chaining
+     */
+    registerHealthCheck(name: string, check: () => Promise<boolean> | boolean): this;
+    /**
+     * Run registered health checks and return whether the service is ready.
+     * Useful for readiness probes in deployment tooling.
+     *
+     * @returns Promise resolving to `true` when all checks pass, otherwise `false`.
+     */
+    ready(): Promise<boolean>;
+    /**
+     * Get the underlying Express application instance.
+     * Use this for advanced Express features not exposed by this wrapper.
+     *
+     * @returns The raw Express app instance
+     */
+    getApp(): Express;
+    /**
+     * Get the active HTTP/HTTPS server instance.
+     * Returns null if the server is not currently running.
+     *
+     * @returns The HTTP/HTTPS server instance or null
+     */
+    getServer(): http.Server | https.Server | null;
+    /**
+     * Start the HTTP server and begin listening for requests.
+     *
+     * This method:
+     * - Executes beforeStart hooks
+     * - Binds to the configured host/port
+     * - Sets up error handling for startup failures
+     * - Executes afterStart hooks on success
+     * - Logs startup information
+     *
+     * @returns Promise resolving to the running HTTP server instance
+     * @throws Error if server fails to start or port is already in use
+     */
+    start(): Promise<http.Server | https.Server>;
+    /**
+     * Stop the HTTP server gracefully.
+     *
+     * This method:
+     * - Executes beforeStop hooks
+     * - Stops accepting new connections
+     * - Waits for existing connections to finish
+     * - Closes the server
+     * - Executes afterStop hooks
+     * - Logs shutdown information
+     *
+     * Graceful shutdown ensures:
+     * - No requests are dropped
+     * - Resources are properly cleaned up
+     * - Monitoring systems are notified
+     */
+    stop(force?: boolean): Promise<void>;
+    /**
+     * Enable graceful shutdown on OS signals for production deployment.
+     *
+     * This is essential for:
+     * - Container orchestration (Docker, Kubernetes)
+     * - Process managers (PM2, systemd)
+     * - Load balancer health checks
+     * - Zero-downtime deployments
+     *
+     * @param signals Array of process signals to listen for (default: SIGINT, SIGTERM)
+     */
+    enableGracefulShutdown(signals?: NodeJS.Signals[]): this;
+    /**
+     * Set an externally created base router.
+     * This will override the internal rootRouter.
+     */
+    setBaseRouter(router: Router): this;
+    /**
+     * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).
+     */
+    createRouter(prefix?: string): Router;
+    /**
+     * Register a new route handler with support for multiple HTTP methods.
+     * The route is automatically registered under the globalPrefix if set.
+     *
+     * @param methods Array of HTTP methods (get, post, put, delete, etc.)
+     * @param path Route path with Express path patterns support
+     * @param handlers One or more Express request handlers (middleware + final handler)
+     * @returns This instance for method chaining
+     */
+    registerRoute(methods: Array<keyof Pick<Express, 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head'>>, path: string, ...handlers: Array<express.RequestHandler>): this;
+    /**
+     * Register custom middleware with optional path restriction.
+     *
+     * Use this for:
+     * - Adding authentication to specific routes
+     * - Custom logging or validation
+     * - Request transformation
+     * - Third-party middleware integration
+     *
+     * @param path Optional path prefix or middleware function if no path
+     * @param middleware Middleware handler (required if path is provided)
+     * @returns This instance for method chaining
+     */
+    registerMiddleware(path: string | express.RequestHandler, middleware?: express.RequestHandler): this;
+    /**
+     * Register one or more middleware functions to be applied globally.
+     * This is a simpler alternative to registerMiddleware when you just want
+     * to add middleware without path restrictions.
+     *
+     * @param middlewares One or more Express middleware functions
+     * @returns This instance for method chaining
+     */
+    useMiddleware(...middlewares: express.RequestHandler[]): this;
+    /**
+     * Get Prometheus registry (to add custom counters/histograms)
+     *
+     * @return {*}  {client.Registry}
+     */
+    getMetricsRegistry(): typeof import("prom-client").Registry;
+    /**
+     * Get server configuration
+     *
+     * @return {*}  {ServerConfig}
+     */
+    getConfig(): ServerConfig;
+    /**
+     * Wait until server initialization (middleware + routes) has completed.
+     * Useful for integration tests that inspect app before starting.
+     */
+    waitUntilReady(): Promise<void>;
+    private normalizePath;
+    private normalizeRouteForMetrics;
+    /**
+     * Destroy all active connections (gracefully if possible).
+     * If a connection does not close cleanly, it will be force-destroyed.
+     */
+    private destroyConnections;
+    private validateHttpsFiles;
+    private isBuiltServerConfig;
+    private throwDependancyError;
+}

package/stream/index.cjs

@@ -0,0 +1,151 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * 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.
+ */
+
+'use strict';
+
+var stream = require('stream');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function bufferToStream(data) {
+  const readable = new stream.Readable();
+  readable.push(data);
+  readable.push(null);
+  return readable;
+}
+__name(bufferToStream, "bufferToStream");
+async function streamToBuffer(stream) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+__name(streamToBuffer, "streamToBuffer");
+async function streamToString(stream, encoding = "utf8") {
+  const buffer = await streamToBuffer(stream);
+  return buffer.toString(encoding);
+}
+__name(streamToString, "streamToString");
+function createThrottleStream(bytesPerSecond) {
+  let bytesSent = 0;
+  let startTime = Date.now();
+  return new stream.Transform({
+    transform(chunk, _encoding, callback) {
+      const elapsedSeconds = (Date.now() - startTime) / 1e3;
+      const targetBytes = bytesPerSecond * elapsedSeconds;
+      const chunkSize = chunk.length;
+      if (bytesSent + chunkSize <= targetBytes) {
+        bytesSent += chunkSize;
+        callback(null, chunk);
+        return;
+      }
+      const delay = ((bytesSent + chunkSize) / bytesPerSecond - elapsedSeconds) * 1e3;
+      setTimeout(() => {
+        bytesSent += chunkSize;
+        callback(null, chunk);
+      }, delay);
+    }
+  });
+}
+__name(createThrottleStream, "createThrottleStream");
+function createBatchStream(size, options = {}) {
+  const objectMode = options.objectMode !== false;
+  let batch = [];
+  let buffers = [];
+  let bufferSize = 0;
+  return new stream.Transform({
+    objectMode,
+    transform(chunk, _encoding, callback) {
+      if (objectMode) {
+        batch.push(chunk);
+        if (batch.length >= size) {
+          this.push(batch);
+          batch = [];
+        }
+      } else {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        buffers.push(buffer);
+        bufferSize += buffer.length;
+        let combined = Buffer.concat(buffers, bufferSize);
+        while (combined.length >= size) {
+          this.push(combined.slice(0, size));
+          combined = combined.slice(size);
+        }
+        buffers = combined.length > 0 ? [
+          combined
+        ] : [];
+        bufferSize = combined.length;
+      }
+      callback();
+    },
+    flush(callback) {
+      if (objectMode && batch.length > 0) {
+        this.push(batch);
+      } else if (!objectMode && buffers.length > 0 && bufferSize > 0) {
+        let combined = Buffer.concat(buffers, bufferSize);
+        while (combined.length >= size) {
+          this.push(combined.slice(0, size));
+          combined = combined.slice(size);
+        }
+        if (combined.length > 0) {
+          this.push(combined);
+        }
+      }
+      callback();
+    }
+  });
+}
+__name(createBatchStream, "createBatchStream");
+function createLineStream(options = {}) {
+  const { encoding = "utf8", includeNewlines = false } = options;
+  let buffer = "";
+  return new stream.Transform({
+    objectMode: true,
+    transform(chunk, _encoding, callback) {
+      const str = buffer + (Buffer.isBuffer(chunk) ? chunk.toString(encoding) : chunk);
+      const lines = str.split(/\r?\n/);
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        this.push(includeNewlines ? line + "\n" : line);
+      }
+      callback();
+    },
+    flush(callback) {
+      if (buffer) {
+        this.push(buffer);
+      }
+      callback();
+    }
+  });
+}
+__name(createLineStream, "createLineStream");
+
+exports.bufferToStream = bufferToStream;
+exports.createBatchStream = createBatchStream;
+exports.createLineStream = createLineStream;
+exports.createThrottleStream = createThrottleStream;
+exports.streamToBuffer = streamToBuffer;
+exports.streamToString = streamToString;

package/stream/index.d.ts

@@ -0,0 +1,25 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * 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.
+ */
+
+export * from './stream.utils';

package/stream/index.mjs

@@ -0,0 +1,144 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * 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.
+ */
+
+import { Readable, Transform } from 'stream';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function bufferToStream(data) {
+  const readable = new Readable();
+  readable.push(data);
+  readable.push(null);
+  return readable;
+}
+__name(bufferToStream, "bufferToStream");
+async function streamToBuffer(stream) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+__name(streamToBuffer, "streamToBuffer");
+async function streamToString(stream, encoding = "utf8") {
+  const buffer = await streamToBuffer(stream);
+  return buffer.toString(encoding);
+}
+__name(streamToString, "streamToString");
+function createThrottleStream(bytesPerSecond) {
+  let bytesSent = 0;
+  let startTime = Date.now();
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      const elapsedSeconds = (Date.now() - startTime) / 1e3;
+      const targetBytes = bytesPerSecond * elapsedSeconds;
+      const chunkSize = chunk.length;
+      if (bytesSent + chunkSize <= targetBytes) {
+        bytesSent += chunkSize;
+        callback(null, chunk);
+        return;
+      }
+      const delay = ((bytesSent + chunkSize) / bytesPerSecond - elapsedSeconds) * 1e3;
+      setTimeout(() => {
+        bytesSent += chunkSize;
+        callback(null, chunk);
+      }, delay);
+    }
+  });
+}
+__name(createThrottleStream, "createThrottleStream");
+function createBatchStream(size, options = {}) {
+  const objectMode = options.objectMode !== false;
+  let batch = [];
+  let buffers = [];
+  let bufferSize = 0;
+  return new Transform({
+    objectMode,
+    transform(chunk, _encoding, callback) {
+      if (objectMode) {
+        batch.push(chunk);
+        if (batch.length >= size) {
+          this.push(batch);
+          batch = [];
+        }
+      } else {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        buffers.push(buffer);
+        bufferSize += buffer.length;
+        let combined = Buffer.concat(buffers, bufferSize);
+        while (combined.length >= size) {
+          this.push(combined.slice(0, size));
+          combined = combined.slice(size);
+        }
+        buffers = combined.length > 0 ? [
+          combined
+        ] : [];
+        bufferSize = combined.length;
+      }
+      callback();
+    },
+    flush(callback) {
+      if (objectMode && batch.length > 0) {
+        this.push(batch);
+      } else if (!objectMode && buffers.length > 0 && bufferSize > 0) {
+        let combined = Buffer.concat(buffers, bufferSize);
+        while (combined.length >= size) {
+          this.push(combined.slice(0, size));
+          combined = combined.slice(size);
+        }
+        if (combined.length > 0) {
+          this.push(combined);
+        }
+      }
+      callback();
+    }
+  });
+}
+__name(createBatchStream, "createBatchStream");
+function createLineStream(options = {}) {
+  const { encoding = "utf8", includeNewlines = false } = options;
+  let buffer = "";
+  return new Transform({
+    objectMode: true,
+    transform(chunk, _encoding, callback) {
+      const str = buffer + (Buffer.isBuffer(chunk) ? chunk.toString(encoding) : chunk);
+      const lines = str.split(/\r?\n/);
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        this.push(includeNewlines ? line + "\n" : line);
+      }
+      callback();
+    },
+    flush(callback) {
+      if (buffer) {
+        this.push(buffer);
+      }
+      callback();
+    }
+  });
+}
+__name(createLineStream, "createLineStream");
+
+export { bufferToStream, createBatchStream, createLineStream, createThrottleStream, streamToBuffer, streamToString };