@catbee/utils 0.0.6 → 0.0.7

package/build/src/utils/middleware.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.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\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { createFinalErrorResponse, ErrorResponse } from './response.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { RequestTimeoutException } from './exception.utils';\nimport { ApiErrorResponse } from '../types/api-response';\n\nexport type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @param {() => string} [options.generator] - Custom ID generator function\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n  generator?: () => string;\n}): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n  const generateId = options?.generator || uuid;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || generateId();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }) {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    const start = process.hrtime();\n\n    // Function to calculate duration\n    const getDuration = () => {\n      const diff = process.hrtime(start);\n      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);\n    };\n\n    if (addHeader) {\n      // Ensure header is set before response is sent\n      const originalWriteHead = res.writeHead;\n      res.writeHead = function (...args: any[]) {\n        res.setHeader('X-Response-Time', `${getDuration()}ms`);\n        return originalWriteHead.apply(this, args as any);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);\n      });\n    }\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = 30000): Middleware {\n  return (_req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      const response = new RequestTimeoutException('Request timed out');\n      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates an Express middleware that initializes a per-request context.\n *\n * @param {object} [options] - Optional configuration\n * @param {string} [options.headerName='x-request-id'] - Header to look for request ID\n * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized\n * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function\n */\nexport function setupRequestContext(options: { headerName?: string; autoLog?: boolean } = {}): Middleware {\n  const { headerName = 'x-request-id', autoLog = true } = options;\n  return (req, _res, next) => {\n    // Generate or use existing request ID\n    const requestId = (req.headers[headerName] as string) || req?.['id'] || uuid();\n\n    ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n      // Create a child logger for this request\n      const childLogger = getLogger().child({\n        requestId,\n        method: req.method,\n        url: req.originalUrl || req.url\n      });\n\n      // Store logger in context\n      ContextStore.set(StoreKeys.LOGGER, childLogger);\n\n      if (autoLog) {\n        childLogger.info('Request context initialized');\n      }\n\n      next();\n    });\n  };\n}\n\nexport interface ErrorHandlerOptions {\n  /** Whether to log errors (default: true) */\n  logErrors?: boolean;\n  /** Whether to include error details in non-production (default: false) */\n  includeDetails?: boolean;\n}\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {ErrorHandlerOptions} options - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns Error middleware\n *\n * @example\n * import express from 'express';\n * import { errorHandler } from '@catbee/utils';\n *\n * const app = express();\n *\n * // Your routes\n * app.get('/ping', (req, res) => {\n *   throw new Error('Something went wrong');\n * });\n *\n * // Error handler (must be last middleware)\n * app.use(errorHandler({ includeDetails: true }));\n *\n * app.listen(3000, () => {\n *   console.log('Server running on port 3000');\n * });\n */\nexport function errorHandler(options?: ErrorHandlerOptions) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      getLogger().error({ err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      const result: ApiErrorResponse = {\n        error: true,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err?.requestId || req?.id || uuid(),\n        status,\n        path: req.originalUrl || req.url\n      };\n\n      if (includeDetails && err?.stack) {\n        result.stack = err.stack.split('\\n').map((line: string) => line.trim());\n      }\n      return res.status(status).json(result);\n    }\n\n    // Handle any other errors\n    return res\n      .status(status)\n      .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));\n  };\n}\n"]}
+{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.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\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { createFinalErrorResponse, ErrorResponse } from './response.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { RequestTimeoutException } from './exception.utils';\nimport { ApiErrorResponse } from '../types/api-response';\n\nexport type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @param {() => string} [options.generator] - Custom ID generator function\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n  generator?: () => string;\n}): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n  const generateId = options?.generator || uuid;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || generateId();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }) {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    const start = process.hrtime();\n\n    // Function to calculate duration\n    const getDuration = () => {\n      const diff = process.hrtime(start);\n      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);\n    };\n\n    if (addHeader) {\n      // Ensure header is set before response is sent\n      const originalWriteHead = res.writeHead;\n      res.writeHead = function (...args: any[]) {\n        res.setHeader('X-Response-Time', `${getDuration()}ms`);\n        return originalWriteHead.apply(this, args as any);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);\n      });\n    }\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = 30000): Middleware {\n  return (_req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      const response = new RequestTimeoutException('Request timed out');\n      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates an Express middleware that initializes a per-request context.\n *\n * @param {object} [options] - Optional configuration\n * @param {string} [options.headerName='x-request-id'] - Header to look for request ID\n * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized\n * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function\n */\nexport function setupRequestContext(options: { headerName?: string; autoLog?: boolean } = {}): Middleware {\n  const { headerName = 'x-request-id', autoLog = true } = options;\n  return (req, _res, next) => {\n    // Generate or use existing request ID\n    const requestId = (req.headers[headerName] as string) || req?.['id'] || uuid();\n\n    ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n      // Create a child logger for this request\n      const childLogger = getLogger().child({\n        requestId,\n        method: req.method,\n        url: req.originalUrl || req.url\n      });\n\n      req.logger = childLogger;\n\n      // Store logger in context\n      ContextStore.set(StoreKeys.LOGGER, childLogger);\n\n      if (autoLog) {\n        req.logger.info('Request context initialized');\n      }\n\n      next();\n    });\n  };\n}\n\nexport interface ErrorHandlerOptions {\n  /** Whether to log errors (default: true) */\n  logErrors?: boolean;\n  /** Whether to include error details in non-production (default: false) */\n  includeDetails?: boolean;\n}\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {ErrorHandlerOptions} options - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns Error middleware\n *\n * @example\n * import express from 'express';\n * import { errorHandler } from '@catbee/utils';\n *\n * const app = express();\n *\n * // Your routes\n * app.get('/ping', (req, res) => {\n *   throw new Error('Something went wrong');\n * });\n *\n * // Error handler (must be last middleware)\n * app.use(errorHandler({ includeDetails: true }));\n *\n * app.listen(3000, () => {\n *   console.log('Server running on port 3000');\n * });\n */\nexport function errorHandler(options?: ErrorHandlerOptions) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      getLogger().error({ err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      const result: ApiErrorResponse = {\n        error: true,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err?.requestId || req?.id || uuid(),\n        status,\n        path: req.originalUrl || req.url\n      };\n\n      if (includeDetails && err?.stack) {\n        result.stack = err.stack.split('\\n').map((line: string) => line.trim());\n      }\n      return res.status(status).json(result);\n    }\n\n    // Handle any other errors\n    return res\n      .status(status)\n      .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));\n  };\n}\n"]}

package/build/src/utils/performance.utils.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Options for timing function execution.
+ */
+export interface TimingOptions {
+    /** Optional label for the timing (defaults to function name) */
+    label?: string;
+    /** Whether to log the timing (default: false) */
+    log?: boolean;
+    /** Log level to use if logging is enabled (default: 'debug') */
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Result of a timing operation.
+ */
+export interface TimingResult {
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Duration in seconds */
+    durationSec: number;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime: number;
+    /** Label used for the timing */
+    label: string;
+}
+/**
+ * Measure the execution time of a synchronous function.
+ *
+ * @param fn - Function to measure
+ * @param options - Timing options
+ * @returns Result containing the return value and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = timeSync(() => {
+ *   // Some expensive operation
+ *   return computeResult();
+ * }, { label: 'Computation', log: true });
+ *
+ * console.log(`Result: ${result}, took ${timing.durationMs}ms`);
+ * ```
+ */
+export declare function timeSync<T>(fn: () => T, options?: TimingOptions): {
+    result: T;
+    timing: TimingResult;
+};
+/**
+ * Measure the execution time of an asynchronous function.
+ *
+ * @param fn - Async function to measure
+ * @param options - Timing options
+ * @returns Promise resolving to result and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = await timeAsync(async () => {
+ *   // Some expensive async operation
+ *   const data = await fetchData();
+ *   return processData(data);
+ * }, { label: 'API Request', log: true });
+ *
+ * console.log(`Fetched ${result.length} items in ${timing.durationSec.toFixed(2)}s`);
+ * ```
+ */
+export declare function timeAsync<T>(fn: () => Promise<T>, options?: TimingOptions): Promise<{
+    result: T;
+    timing: TimingResult;
+}>;
+/**
+ * Create a timing decorator for class methods.
+ *
+ * @param options - Timing options
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * class DataService {
+ *   @timed({ log: true, logLevel: 'info' })
+ *   async fetchData() {
+ *     // ...implementation
+ *   }
+ * }
+ * ```
+ */
+export declare function timed(options?: TimingOptions): (target: any, propertyKeyOrContext: string | symbol | any, descriptor?: PropertyDescriptor) => void;
+/**
+ * Memoize function results with optional TTL and max cache size.
+ *
+ * @param fn - Function to memoize
+ * @param options - Memoization options
+ * @returns Memoized function
+ *
+ * @example
+ * ```typescript
+ * // Cache results for 30 seconds, with a maximum of 100 entries
+ * const cachedFetch = memoize(
+ *   async (url) => {
+ *     const response = await fetch(url);
+ *     return response.json();
+ *   },
+ *   { ttl: 30000, maxSize: 100, cacheKey: (url) => url }
+ * );
+ * ```
+ */
+export declare function memoize<T, Args extends any[]>(fn: (...args: Args) => T, options?: {
+    /** Time-to-live in milliseconds (default: indefinite) */
+    ttl?: number;
+    /** Maximum cache size (default: unlimited) */
+    maxSize?: number;
+    /** Function to generate a cache key from arguments */
+    cacheKey?: (...args: Args) => string;
+    /** Auto-cleanup interval in milliseconds (default: disabled) */
+    autoCleanupMs?: number;
+}): (...args: Args) => T;
+/**
+ * Track memory usage for a function execution.
+ *
+ * @param fn - Function to track
+ * @param options - Memory tracking options
+ * @returns Result and memory usage information
+ */
+export declare function trackMemoryUsage<T>(fn: () => T, options?: {
+    /** Whether to log the memory usage (default: false) */
+    log?: boolean;
+    /** Label for the memory tracking (default: function name) */
+    label?: string;
+}): {
+    result: T;
+    memoryUsage: {
+        before: NodeJS.MemoryUsage;
+        after: NodeJS.MemoryUsage;
+        diff: Record<string, number>;
+    };
+};
+//# sourceMappingURL=performance.utils.d.ts.map

package/build/src/utils/performance.utils.js

@@ -0,0 +1,278 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeSync = timeSync;
+exports.timeAsync = timeAsync;
+exports.timed = timed;
+exports.memoize = memoize;
+exports.trackMemoryUsage = trackMemoryUsage;
+const cache_utils_1 = require("./cache.utils");
+const logger_utils_1 = require("./logger.utils");
+/**
+ * Measure the execution time of a synchronous function.
+ *
+ * @param fn - Function to measure
+ * @param options - Timing options
+ * @returns Result containing the return value and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = timeSync(() => {
+ *   // Some expensive operation
+ *   return computeResult();
+ * }, { label: 'Computation', log: true });
+ *
+ * console.log(`Result: ${result}, took ${timing.durationMs}ms`);
+ * ```
+ */
+function timeSync(fn, options = {}) {
+    const { label = fn.name || 'anonymous function', log = false, logLevel = 'debug' } = options;
+    const startTime = performance.now();
+    const result = fn();
+    const endTime = performance.now();
+    const durationMs = endTime - startTime;
+    const durationSec = durationMs / 1000;
+    const timing = {
+        durationMs,
+        durationSec,
+        startTime,
+        endTime,
+        label
+    };
+    if (log) {
+        const logger = (0, logger_utils_1.getLogger)();
+        const message = `${label} completed in ${durationMs.toFixed(2)}ms`;
+        switch (logLevel) {
+            case 'trace':
+                logger.trace({ timing }, message);
+                break;
+            case 'debug':
+                logger.debug({ timing }, message);
+                break;
+            case 'info':
+                logger.info({ timing }, message);
+                break;
+            case 'warn':
+                logger.warn({ timing }, message);
+                break;
+            case 'error':
+                logger.error({ timing }, message);
+                break;
+            default:
+                logger.debug({ timing }, message);
+                break;
+        }
+    }
+    return { result, timing };
+}
+/**
+ * Measure the execution time of an asynchronous function.
+ *
+ * @param fn - Async function to measure
+ * @param options - Timing options
+ * @returns Promise resolving to result and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = await timeAsync(async () => {
+ *   // Some expensive async operation
+ *   const data = await fetchData();
+ *   return processData(data);
+ * }, { label: 'API Request', log: true });
+ *
+ * console.log(`Fetched ${result.length} items in ${timing.durationSec.toFixed(2)}s`);
+ * ```
+ */
+async function timeAsync(fn, options = {}) {
+    const { label = fn.name || 'anonymous async function', log = false, logLevel = 'debug' } = options;
+    const startTime = performance.now();
+    const result = await fn();
+    const endTime = performance.now();
+    const durationMs = endTime - startTime;
+    const durationSec = durationMs / 1000;
+    const timing = {
+        durationMs,
+        durationSec,
+        startTime,
+        endTime,
+        label
+    };
+    if (log) {
+        const logger = (0, logger_utils_1.getLogger)();
+        const message = `${label} completed in ${durationMs.toFixed(2)}ms`;
+        switch (logLevel) {
+            case 'trace':
+                logger.trace({ timing }, message);
+                break;
+            case 'debug':
+                logger.debug({ timing }, message);
+                break;
+            case 'info':
+                logger.info({ timing }, message);
+                break;
+            case 'warn':
+                logger.warn({ timing }, message);
+                break;
+            case 'error':
+                logger.error({ timing }, message);
+                break;
+            default:
+                logger.debug({ timing }, message);
+                break;
+        }
+    }
+    return { result, timing };
+}
+/**
+ * Create a timing decorator for class methods.
+ *
+ * @param options - Timing options
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * class DataService {
+ *   @timed({ log: true, logLevel: 'info' })
+ *   async fetchData() {
+ *     // ...implementation
+ *   }
+ * }
+ * ```
+ */
+function timed(options = {}) {
+    return function (target, propertyKeyOrContext, descriptor) {
+        let propertyKey;
+        let actualDescriptor;
+        // ESNext decorator: second argument is context object
+        if (typeof propertyKeyOrContext === 'object' && propertyKeyOrContext !== null && 'name' in propertyKeyOrContext) {
+            propertyKey = propertyKeyOrContext.name;
+            actualDescriptor = descriptor !== null && descriptor !== void 0 ? descriptor : Object.getOwnPropertyDescriptor(target, propertyKey);
+        }
+        else {
+            // Legacy decorator: second argument is property key
+            propertyKey = propertyKeyOrContext;
+            actualDescriptor = descriptor !== null && descriptor !== void 0 ? descriptor : Object.getOwnPropertyDescriptor(target, propertyKey);
+        }
+        const originalMethod = actualDescriptor.value;
+        actualDescriptor.value = function (...args) {
+            const methodOptions = Object.assign(Object.assign({}, options), { label: options.label || `${target.constructor.name}.${String(propertyKey)}` });
+            if (originalMethod.constructor.name === 'AsyncFunction') {
+                return timeAsync(() => originalMethod.apply(this, args), methodOptions).then(({ result }) => result);
+            }
+            else {
+                return timeSync(() => originalMethod.apply(this, args), methodOptions).result;
+            }
+        };
+        // For legacy decorators, assign the new descriptor
+        if (descriptor) {
+            descriptor.value = actualDescriptor.value;
+        }
+        else {
+            Object.defineProperty(target, propertyKey, actualDescriptor);
+        }
+        // No return needed for method decorators
+    };
+}
+/**
+ * Memoize function results with optional TTL and max cache size.
+ *
+ * @param fn - Function to memoize
+ * @param options - Memoization options
+ * @returns Memoized function
+ *
+ * @example
+ * ```typescript
+ * // Cache results for 30 seconds, with a maximum of 100 entries
+ * const cachedFetch = memoize(
+ *   async (url) => {
+ *     const response = await fetch(url);
+ *     return response.json();
+ *   },
+ *   { ttl: 30000, maxSize: 100, cacheKey: (url) => url }
+ * );
+ * ```
+ */
+function memoize(fn, options = {}) {
+    const { ttl, maxSize, autoCleanupMs, cacheKey = (...args) => JSON.stringify(args) } = options;
+    // Create a properly configured TTLCache instance
+    const cache = new cache_utils_1.TTLCache({
+        ttlMs: ttl,
+        maxSize: maxSize,
+        autoCleanupMs: autoCleanupMs
+    });
+    return function (...args) {
+        const key = cacheKey(...args);
+        // Try to get from cache first - TTLCache handles expiration internally
+        const cachedValue = cache.get(key);
+        if (cachedValue !== undefined) {
+            return cachedValue;
+        }
+        // Calculate the value and store in cache with configured TTL
+        const value = fn(...args);
+        cache.set(key, value);
+        return value;
+    };
+}
+/**
+ * Track memory usage for a function execution.
+ *
+ * @param fn - Function to track
+ * @param options - Memory tracking options
+ * @returns Result and memory usage information
+ */
+function trackMemoryUsage(fn, options = {}) {
+    const { log = false, label = fn.name || 'anonymous function' } = options;
+    // Collect garbage before measuring (optional)
+    if (global.gc) {
+        global.gc();
+    }
+    const beforeMemory = process.memoryUsage();
+    const result = fn();
+    const afterMemory = process.memoryUsage();
+    // Calculate differences
+    const diff = {};
+    for (const key in afterMemory) {
+        if (Object.prototype.hasOwnProperty.call(afterMemory, key)) {
+            diff[key] = afterMemory[key] - beforeMemory[key];
+        }
+    }
+    if (log) {
+        (0, logger_utils_1.getLogger)().info({
+            label,
+            memoryBefore: beforeMemory,
+            memoryAfter: afterMemory,
+            memoryDiff: diff
+        }, `Memory usage for ${label}`);
+    }
+    return {
+        result,
+        memoryUsage: {
+            before: beforeMemory,
+            after: afterMemory,
+            diff
+        }
+    };
+}
+//# sourceMappingURL=performance.utils.js.map

package/build/src/utils/performance.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.utils.js","sourceRoot":"","sources":["../../../src/utils/performance.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\nimport { TTLCache } from './cache.utils';\nimport { getLogger } from './logger.utils';\n\n/**\n * Options for timing function execution.\n */\nexport interface TimingOptions {\n  /** Optional label for the timing (defaults to function name) */\n  label?: string;\n  /** Whether to log the timing (default: false) */\n  log?: boolean;\n  /** Log level to use if logging is enabled (default: 'debug') */\n  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';\n}\n\n/**\n * Result of a timing operation.\n */\nexport interface TimingResult {\n  /** Duration in milliseconds */\n  durationMs: number;\n  /** Duration in seconds */\n  durationSec: number;\n  /** Start timestamp */\n  startTime: number;\n  /** End timestamp */\n  endTime: number;\n  /** Label used for the timing */\n  label: string;\n}\n\n/**\n * Measure the execution time of a synchronous function.\n *\n * @param fn - Function to measure\n * @param options - Timing options\n * @returns Result containing the return value and timing information\n *\n * @example\n * ```typescript\n * const { result, timing } = timeSync(() => {\n *   // Some expensive operation\n *   return computeResult();\n * }, { label: 'Computation', log: true });\n *\n * console.log(`Result: ${result}, took ${timing.durationMs}ms`);\n * ```\n */\nexport function timeSync<T>(fn: () => T, options: TimingOptions = {}): { result: T; timing: TimingResult } {\n  const { label = fn.name || 'anonymous function', log = false, logLevel = 'debug' } = options;\n\n  const startTime = performance.now();\n  const result = fn();\n  const endTime = performance.now();\n\n  const durationMs = endTime - startTime;\n  const durationSec = durationMs / 1000;\n\n  const timing: TimingResult = {\n    durationMs,\n    durationSec,\n    startTime,\n    endTime,\n    label\n  };\n\n  if (log) {\n    const logger = getLogger();\n    const message = `${label} completed in ${durationMs.toFixed(2)}ms`;\n\n    switch (logLevel) {\n      case 'trace':\n        logger.trace({ timing }, message);\n        break;\n      case 'debug':\n        logger.debug({ timing }, message);\n        break;\n      case 'info':\n        logger.info({ timing }, message);\n        break;\n      case 'warn':\n        logger.warn({ timing }, message);\n        break;\n      case 'error':\n        logger.error({ timing }, message);\n        break;\n      default:\n        logger.debug({ timing }, message);\n        break;\n    }\n  }\n\n  return { result, timing };\n}\n\n/**\n * Measure the execution time of an asynchronous function.\n *\n * @param fn - Async function to measure\n * @param options - Timing options\n * @returns Promise resolving to result and timing information\n *\n * @example\n * ```typescript\n * const { result, timing } = await timeAsync(async () => {\n *   // Some expensive async operation\n *   const data = await fetchData();\n *   return processData(data);\n * }, { label: 'API Request', log: true });\n *\n * console.log(`Fetched ${result.length} items in ${timing.durationSec.toFixed(2)}s`);\n * ```\n */\nexport async function timeAsync<T>(\n  fn: () => Promise<T>,\n  options: TimingOptions = {}\n): Promise<{ result: T; timing: TimingResult }> {\n  const { label = fn.name || 'anonymous async function', log = false, logLevel = 'debug' } = options;\n\n  const startTime = performance.now();\n  const result = await fn();\n  const endTime = performance.now();\n\n  const durationMs = endTime - startTime;\n  const durationSec = durationMs / 1000;\n\n  const timing: TimingResult = {\n    durationMs,\n    durationSec,\n    startTime,\n    endTime,\n    label\n  };\n\n  if (log) {\n    const logger = getLogger();\n    const message = `${label} completed in ${durationMs.toFixed(2)}ms`;\n\n    switch (logLevel) {\n      case 'trace':\n        logger.trace({ timing }, message);\n        break;\n      case 'debug':\n        logger.debug({ timing }, message);\n        break;\n      case 'info':\n        logger.info({ timing }, message);\n        break;\n      case 'warn':\n        logger.warn({ timing }, message);\n        break;\n      case 'error':\n        logger.error({ timing }, message);\n        break;\n      default:\n        logger.debug({ timing }, message);\n        break;\n    }\n  }\n\n  return { result, timing };\n}\n\n/**\n * Create a timing decorator for class methods.\n *\n * @param options - Timing options\n * @returns Method decorator\n *\n * @example\n * ```typescript\n * class DataService {\n *   @timed({ log: true, logLevel: 'info' })\n *   async fetchData() {\n *     // ...implementation\n *   }\n * }\n * ```\n */\nexport function timed(options: TimingOptions = {}) {\n  return function (target: any, propertyKeyOrContext: string | symbol | any, descriptor?: PropertyDescriptor): void {\n    let propertyKey: string | symbol;\n    let actualDescriptor: PropertyDescriptor;\n\n    // ESNext decorator: second argument is context object\n    if (typeof propertyKeyOrContext === 'object' && propertyKeyOrContext !== null && 'name' in propertyKeyOrContext) {\n      propertyKey = propertyKeyOrContext.name;\n      actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey)!;\n    } else {\n      // Legacy decorator: second argument is property key\n      propertyKey = propertyKeyOrContext;\n      actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey)!;\n    }\n\n    const originalMethod = actualDescriptor.value;\n\n    actualDescriptor.value = function (...args: any[]) {\n      const methodOptions = {\n        ...options,\n        label: options.label || `${target.constructor.name}.${String(propertyKey)}`\n      };\n\n      if (originalMethod.constructor.name === 'AsyncFunction') {\n        return timeAsync(() => originalMethod.apply(this, args), methodOptions).then(({ result }) => result);\n      } else {\n        return timeSync(() => originalMethod.apply(this, args), methodOptions).result;\n      }\n    };\n\n    // For legacy decorators, assign the new descriptor\n    if (descriptor) {\n      descriptor.value = actualDescriptor.value;\n    } else {\n      Object.defineProperty(target, propertyKey, actualDescriptor);\n    }\n    // No return needed for method decorators\n  };\n}\n\n/**\n * Memoize function results with optional TTL and max cache size.\n *\n * @param fn - Function to memoize\n * @param options - Memoization options\n * @returns Memoized function\n *\n * @example\n * ```typescript\n * // Cache results for 30 seconds, with a maximum of 100 entries\n * const cachedFetch = memoize(\n *   async (url) => {\n *     const response = await fetch(url);\n *     return response.json();\n *   },\n *   { ttl: 30000, maxSize: 100, cacheKey: (url) => url }\n * );\n * ```\n */\nexport function memoize<T, Args extends any[]>(\n  fn: (...args: Args) => T,\n  options: {\n    /** Time-to-live in milliseconds (default: indefinite) */\n    ttl?: number;\n    /** Maximum cache size (default: unlimited) */\n    maxSize?: number;\n    /** Function to generate a cache key from arguments */\n    cacheKey?: (...args: Args) => string;\n    /** Auto-cleanup interval in milliseconds (default: disabled) */\n    autoCleanupMs?: number;\n  } = {}\n) {\n  const { ttl, maxSize, autoCleanupMs, cacheKey = (...args) => JSON.stringify(args) } = options;\n\n  // Create a properly configured TTLCache instance\n  const cache = new TTLCache<string, T>({\n    ttlMs: ttl,\n    maxSize: maxSize,\n    autoCleanupMs: autoCleanupMs\n  });\n\n  return function (...args: Args): T {\n    const key = cacheKey(...args);\n\n    // Try to get from cache first - TTLCache handles expiration internally\n    const cachedValue = cache.get(key);\n    if (cachedValue !== undefined) {\n      return cachedValue;\n    }\n\n    // Calculate the value and store in cache with configured TTL\n    const value = fn(...args);\n    cache.set(key, value);\n    return value;\n  };\n}\n\n/**\n * Track memory usage for a function execution.\n *\n * @param fn - Function to track\n * @param options - Memory tracking options\n * @returns Result and memory usage information\n */\nexport function trackMemoryUsage<T>(\n  fn: () => T,\n  options: {\n    /** Whether to log the memory usage (default: false) */\n    log?: boolean;\n    /** Label for the memory tracking (default: function name) */\n    label?: string;\n  } = {}\n): { result: T; memoryUsage: { before: NodeJS.MemoryUsage; after: NodeJS.MemoryUsage; diff: Record<string, number> } } {\n  const { log = false, label = fn.name || 'anonymous function' } = options;\n\n  // Collect garbage before measuring (optional)\n  if (global.gc) {\n    global.gc();\n  }\n\n  const beforeMemory = process.memoryUsage();\n  const result = fn();\n  const afterMemory = process.memoryUsage();\n\n  // Calculate differences\n  const diff: Record<string, number> = {};\n  for (const key in afterMemory) {\n    if (Object.prototype.hasOwnProperty.call(afterMemory, key)) {\n      diff[key] = (afterMemory as any)[key] - (beforeMemory as any)[key];\n    }\n  }\n\n  if (log) {\n    getLogger().info(\n      {\n        label,\n        memoryBefore: beforeMemory,\n        memoryAfter: afterMemory,\n        memoryDiff: diff\n      },\n      `Memory usage for ${label}`\n    );\n  }\n\n  return {\n    result,\n    memoryUsage: {\n      before: beforeMemory,\n      after: afterMemory,\n      diff\n    }\n  };\n}\n"]}

package/build/src/utils/request.utils.d.ts

@@ -1,3 +1,5 @@
+import { Request } from 'express';
+import { WithPagination } from '../types/api-response';
 /**
  * Options for parsing and validating request parameters.
  */
@@ -22,6 +24,13 @@ export interface ValidationResult<T> {
     /** Error message if validation failed */
     error?: string;
 }
+/**
+ * Extracts pagination, sorting, and optional search params from a request.
+ *
+ * @param req - Express request
+ * @returns Object containing validated pagination, sorting, and additional query params
+ */
+export declare const getPaginationParams: <T = {}>(req: Request) => WithPagination<T>;
 /**
  * Safely parses a string parameter to a number.
  *

package/build/src/utils/request.utils.js

@@ -23,11 +23,31 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPaginationParams = void 0;
 exports.parseNumberParam = parseNumberParam;
 exports.parseBooleanParam = parseBooleanParam;
 exports.extractPaginationParams = extractPaginationParams;
 exports.extractSortParams = extractSortParams;
 exports.extractFilterParams = extractFilterParams;
+const exception_utils_1 = require("./exception.utils");
+/**
+ * Extracts pagination, sorting, and optional search params from a request.
+ *
+ * @param req - Express request
+ * @returns Object containing validated pagination, sorting, and additional query params
+ */
+const getPaginationParams = (req) => {
+    const query = req.query;
+    // Extract page & limit
+    const { page, limit } = extractPaginationParams(query, 1, 20, 100);
+    const { sortBy, sortOrder } = extractSortParams(query, []);
+    // Optional search param
+    const search = typeof query.search === 'string' ? query.search : undefined;
+    return Object.assign(Object.assign({}, query), { page,
+        limit,
+        sortBy, sortOrder: sortOrder, search });
+};
+exports.getPaginationParams = getPaginationParams;
 /**
  * Safely parses a string parameter to a number.
  *
@@ -42,7 +62,7 @@ function parseNumberParam(value, options = {}) {
         if (required) {
             const error = `Required number parameter is missing`;
             if (throwOnError)
-                throw new Error(error);
+                throw new exception_utils_1.BadRequestException(error);
             return { isValid: false, value: null, error };
         }
         return {
@@ -55,7 +75,7 @@ function parseNumberParam(value, options = {}) {
     const num = Number(value);
     if (isNaN(num)) {
         if (throwOnError)
-            throw new Error(errorMessage);
+            throw new exception_utils_1.BadRequestException(errorMessage);
         return { isValid: false, value: null, error: errorMessage };
     }
     return { isValid: true, value: num };
@@ -74,7 +94,7 @@ function parseBooleanParam(value, options = {}) {
         if (required) {
             const error = `Required boolean parameter is missing`;
             if (throwOnError)
-                throw new Error(error);
+                throw new exception_utils_1.BadRequestException(error);
             return { isValid: false, value: null, error };
         }
         return {
@@ -92,7 +112,7 @@ function parseBooleanParam(value, options = {}) {
         return { isValid: true, value: false };
     }
     if (throwOnError)
-        throw new Error(errorMessage);
+        throw new exception_utils_1.BadRequestException(errorMessage);
     return { isValid: false, value: null, error: errorMessage };
 }
 /**
@@ -150,7 +170,7 @@ function extractSortParams(query, allowedFields, defaultSort = { sortBy: 'create
         }
     }
     // Validate field
-    if (!allowedFields.includes(sortBy)) {
+    if (allowedFields.length && !allowedFields.includes(sortBy)) {
         sortBy = defaultSort.sortBy;
     }
     return { sortBy, sortOrder };