@catbee/utils 0.0.3 → 0.0.5

package/build/esnext/utils/logger.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import pino, { LoggerOptions, stdTimeFunctions } from 'pino';\nimport type { Logger as PinoLogger } from 'pino'; // Type-only import\nimport { Config } from '../config';\nimport { ContextStore, StoreKeys } from './context-store.utils';\n\n/**\n * Symbol used to store the root logger in the Node.js global object.\n */\nconst GLOBAL_LOGGER_KEY = Symbol.for('logger');\n\n/**\n * Logger type for application-wide logging.\n */\nexport type Logger = pino.Logger;\n\n/**\n * Logger levels for application-wide logging.\n */\nexport type LoggerLevels = pino.Level;\n\n/**\n * Use an object compatible with either modern or legacy global scopes.\n */\nexport const _globalThis = typeof globalThis === 'object' ? globalThis : global;\nconst _global = _globalThis as unknown as { [GLOBAL_LOGGER_KEY]: PinoLogger };\n\n/**\n * Initializes the global root logger according to app configuration.\n *\n * - Sets log name, level, timestamp, and redaction for sensitive fields.\n * - Uses singleton in global symbol registry.\n */\nfunction setupLogger(): void {\n  const logParams: LoggerOptions = {\n    name: Config.Logger.name,\n    level: Config.Logger.level,\n    redact: {\n      paths: ['req.authorization', 'url'],\n      censor(value, path) {\n        if (path[0] === 'url') {\n          return value.replace(/access_token=[a-zA-Z0-9_-]*/, 'access_token=***');\n        } else if (path[1] === 'authorization') {\n          return value.replace(/\\s+(\\S+)$/, ' ***');\n        }\n        return '***';\n      }\n    }\n  };\n\n  if (Config.Logger.isoTimestamp) {\n    logParams.timestamp = stdTimeFunctions.isoTime;\n  }\n\n  _global[GLOBAL_LOGGER_KEY] = pino(logParams);\n  _global[GLOBAL_LOGGER_KEY].debug('Logger initialized');\n}\n\n/**\n * Retrieves the current logger instance:\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n *\n * @returns {Logger} The logger instance (request-bound or global root logger)\n */\nexport function getLogger(): PinoLogger {\n  const logger = ContextStore.get<PinoLogger>(StoreKeys.LOGGER);\n  if (logger) return logger;\n\n  if (!_global[GLOBAL_LOGGER_KEY]) {\n    setupLogger();\n  }\n\n  return _global[GLOBAL_LOGGER_KEY];\n}\n\n/**\n * Creates a child logger with additional context.\n *\n * @param {Record<string, any>} bindings - Properties to attach to all log records\n * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)\n * @returns {Logger} Child logger with merged context\n */\nexport function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger {\n  const logger = parentLogger || getLogger();\n  return logger.child(bindings);\n}\n\n/**\n * Creates a request-scoped logger with request ID and stores it in context\n *\n * @param {string} requestId - Unique request identifier\n * @param {object} [additionalContext] - Additional context to include in logs\n * @returns {Logger} Request-scoped logger instance\n */\nexport function createRequestLogger(requestId: string, additionalContext: Record<string, any> = {}): PinoLogger {\n  const logger = createChildLogger({\n    requestId,\n    ...additionalContext\n  });\n\n  try {\n    ContextStore.set(StoreKeys.LOGGER, logger);\n  } catch {\n    // Context not initialized, can't store logger\n    logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');\n  }\n\n  return logger;\n}\n\n/**\n * Utility to safely log errors with proper stack trace extraction\n *\n * @param {Error|unknown} error - Error object to log\n * @param {string} [message] - Optional message to include\n * @param {Record<string, any>} [context] - Additional context properties\n */\nexport function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void {\n  const logger = getLogger();\n\n  const errObj = error instanceof Error ? error : new Error(String(error));\n  const logContext = {\n    ...context,\n    err: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}
+{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import pino, { LoggerOptions, stdTimeFunctions } from 'pino';\nimport type { Logger as PinoLogger } from 'pino'; // Type-only import\nimport { config } from '../config';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { Env } from './env.utils';\n\n/**\n * Symbol used to store the root logger in the Node.js global object.\n */\nconst GLOBAL_LOGGER_KEY = Symbol.for('logger');\n\n/**\n * Logger type for application-wide logging.\n */\nexport type Logger = pino.Logger;\n\n/**\n * Logger levels for application-wide logging.\n */\nexport type LoggerLevels = pino.Level;\n\n// Default sensitive fields\nexport const defaultSensitiveFields = [\n  'password',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'auth',\n  'jwt',\n  'access_token',\n  'client_secret',\n  'session_token',\n  'refresh_token'\n];\n\n/**\n * The global censor function used by the logger.\n */\nlet globalRedactCensor: (value: unknown, path: string[], sensitiveFields?: string[]) => string = (\n  value,\n  path,\n  sensitiveFields = defaultSensitiveFields\n) => {\n  if (typeof value !== 'string') return '***';\n\n  const lowerPath = path.map(p => p.toLowerCase());\n  const lowerSensitiveFields = sensitiveFields.map(f => f.toLowerCase());\n\n  if (lowerPath.some(p => lowerSensitiveFields.includes(p))) return '***';\n\n  // Redact URLs\n  if (lowerPath[0] === 'url') {\n    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join('|')})=)[^&#]*`, 'gi'), '$1***');\n  }\n\n  if (lowerPath.some(p => p.includes('authorization') || p.includes('auth'))) {\n    return value.replace(/^(\\S+)\\s+.+$/, '$1 ***') || '***';\n  }\n\n  // Redact sensitive fields - check each path segment against each sensitive field\n  if (lowerPath.some(pathPart => lowerSensitiveFields.some(field => pathPart.includes(field)))) {\n    return '***';\n  }\n\n  if (path.length > 0 && !['req', 'res', 'headers'].includes(lowerPath[0])) {\n    return value;\n  }\n\n  return value;\n};\n\n/**\n * Sets the global redaction censor function used throughout the application for log redaction.\n *\n * Use this function to customize how sensitive data is redacted in logs. The provided function\n * will replace the default censor implementation.\n *\n * @example\n * ```typescript\n * // Custom censor that redacts only specific values\n * setRedactCensor((value, path, sensitiveFields) => {\n *   if (path.includes('password')) return '***';\n *   return value;\n * });\n * ```\n *\n * @param fn - The redaction censor function to use globally. This function receives:\n *   - value: The data value to potentially redact\n *   - path: Array of strings representing the path to the value in the object\n *   - sensitiveFields: Optional array of field names to consider sensitive\n * @returns void\n */\nexport function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string) {\n  globalRedactCensor = fn;\n}\n\n/**\n * Gets the current global redaction censor function used for log redaction.\n *\n * This function is called internally by the logger when determining how to redact\n * sensitive information. It can also be used to access the current censor implementation\n * for composition or extension.\n *\n * @example\n * ```typescript\n * const currentCensor = getRedactCensor();\n * // Create an enhanced censor that extends the current one\n * setRedactCensor((value, path, fields) => {\n *   // Add custom logic before delegating to current censor\n *   if (someCondition) return customHandling();\n *   return currentCensor(value, path, fields);\n * });\n * ```\n *\n * @returns The current redaction censor function\n */\nexport function getRedactCensor() {\n  return globalRedactCensor;\n}\n\n/**\n * Convenience function to redact sensitive data using the current global redact censor.\n *\n * This is a direct wrapper around the global censor function that simplifies usage\n * in application code without needing to access the censor function directly.\n *\n * @example\n * ```typescript\n * // Redact a potential sensitive value\n * const safeValue = redact(value, ['user', 'apiKey']);\n * ```\n *\n * @param value - The value to potentially redact\n * @param path - Array of strings representing the path to the value in the object\n * @param sensitiveFields - Optional array of field names to consider sensitive\n * @returns The redacted string value or \"***\" for redacted content\n */\nexport function redact(value: unknown, path: string[], sensitiveFields?: string[]) {\n  return globalRedactCensor(value, path, sensitiveFields);\n}\n\n/**\n * Extends the current redaction function with additional fields to redact.\n *\n * This function wraps the existing censor while adding more fields to be considered\n * sensitive without replacing the entire redaction logic.\n *\n * @example\n * ```typescript\n * // Add custom fields to be redacted in all future redaction operations\n * addRedactFields(['customerId', 'accountNumber']);\n * ```\n *\n * @param fields - Array of additional field names to redact\n */\nexport function addRedactFields(fields: string[]) {\n  const prev = globalRedactCensor;\n  globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) =>\n    prev(value, path, [...(sensitiveFields || []), ...fields]);\n}\n\n/**\n * Replaces the default list of sensitive fields with a new list.\n *\n * This is useful when you want complete control over what fields are considered\n * sensitive by default, rather than using the library's built-in list.\n *\n * @example\n * ```typescript\n * // Replace default sensitive fields with a custom list\n * setSensitiveFields(['password', 'ssn', 'creditCard']);\n * ```\n *\n * @param fields - Array of field names to set as the new default sensitive fields\n */\nexport function setSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);\n}\n\n/**\n * Adds additional field names to the default sensitive fields list.\n *\n * This preserves the existing sensitive fields while adding new ones for\n * application-specific sensitive data.\n *\n * @example\n * ```typescript\n * // Add domain-specific sensitive fields to the default list\n * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);\n * ```\n *\n * @param fields - Array of additional field names to add to the sensitive fields list\n */\nexport function addSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.push(...fields);\n}\n\n/**\n * Use an object compatible with either modern or legacy global scopes.\n */\nexport const _globalThis = typeof globalThis === 'object' ? globalThis : global;\nconst _global = _globalThis as unknown as { [GLOBAL_LOGGER_KEY]: PinoLogger };\n\n/**\n * Initializes the global root logger according to app configuration.\n *\n * - Sets log name, level, timestamp, and redaction for sensitive fields.\n * - Uses singleton in global symbol registry.\n */\nfunction setupLogger(): void {\n  const logParams: LoggerOptions = {\n    name: config.logger.name || '@catbee/utils',\n    level: config.logger.level || 'info',\n    redact: {\n      paths: ['req.authorization', 'res.authorization', 'url', 'headers.authorization'],\n      censor: (value, path) => redact(value, path)\n    },\n    timestamp: stdTimeFunctions.isoTime\n  };\n\n  const logger =\n    config.logger.pretty && Env.isDev()\n      ? pino(\n          logParams,\n          pino.transport({\n            target: 'pino-pretty',\n            options: {\n              colorize: true,\n              translateTime: 'SYS:standard',\n              ignore: 'pid,hostname',\n              singleLine: false, // multi-line errors\n              levelFirst: true\n            }\n          })\n        )\n      : pino(logParams);\n\n  _global[GLOBAL_LOGGER_KEY] = logger;\n  _global[GLOBAL_LOGGER_KEY].debug('Logger initialized');\n}\n\n/**\n * Retrieves the current logger instance:\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n *\n * @returns {Logger} The logger instance (request-bound or global root logger)\n */\nexport function getLogger(): PinoLogger {\n  const logger = ContextStore.get<PinoLogger>(StoreKeys.LOGGER);\n  if (logger) return logger;\n\n  if (!_global[GLOBAL_LOGGER_KEY]) {\n    setupLogger();\n  }\n\n  return _global[GLOBAL_LOGGER_KEY];\n}\n\n/**\n * Creates a child logger with additional context.\n *\n * @param {Record<string, any>} bindings - Properties to attach to all log records\n * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)\n * @returns {Logger} Child logger with merged context\n */\nexport function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger {\n  const logger = parentLogger || getLogger();\n  return logger.child(bindings);\n}\n\n/**\n * Creates a request-scoped logger with request ID and stores it in context\n *\n * @param {string} requestId - Unique request identifier\n * @param {object} [additionalContext] - Additional context to include in logs\n * @returns {Logger} Request-scoped logger instance\n */\nexport function createRequestLogger(requestId: string, additionalContext: Record<string, any> = {}): PinoLogger {\n  const logger = createChildLogger({\n    requestId,\n    ...additionalContext\n  });\n\n  try {\n    ContextStore.set(StoreKeys.LOGGER, logger);\n  } catch {\n    // Context not initialized, can't store logger\n    logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');\n  }\n\n  return logger;\n}\n\n/**\n * Utility to safely log errors with proper stack trace extraction\n *\n * @param {Error|unknown} error - Error object to log\n * @param {string} [message] - Optional message to include\n * @param {Record<string, any>} [context] - Additional context properties\n */\nexport function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void {\n  const logger = getLogger();\n\n  const errObj = error instanceof Error ? error : new Error(String(error));\n  const logContext = {\n    ...context,\n    error: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}

package/build/esnext/utils/middleware.utils.d.ts

@@ -1,27 +1,5 @@
-/**
- * Type definitions for Express-compatible middleware
- */
-type Request = {
-    headers: Record<string, string | string[] | undefined>;
-    method: string;
-    url: string;
-    ip?: string;
-    body?: any;
-    query?: Record<string, any>;
-    params?: Record<string, any>;
-    [key: string]: any;
-};
-type Response = {
-    status: (code: number) => Response;
-    json: (data: any) => void;
-    send: (data: any) => void;
-    setHeader: (name: string, value: string | string[]) => void;
-    end: (data?: any) => void;
-    on: (event: string, callback: (...args: any[]) => void) => void;
-    [key: string]: any;
-};
-type NextFunction = (err?: Error | any) => void;
-type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+import type { Request, Response, NextFunction } from 'express';
+export type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
 /**
  * Attaches a unique request ID to each request.
  * Useful for request tracing and correlation between logs.
@@ -46,7 +24,7 @@ export declare function requestId(options?: {
 export declare function responseTime(options?: {
     addHeader?: boolean;
     logOnComplete?: boolean;
-}): Middleware;
+}): (req: Request, res: Response, next: NextFunction) => void;
 /**
  * Request timeout middleware.
  * Aborts requests that take too long to process.
@@ -55,19 +33,49 @@ export declare function responseTime(options?: {
  * @returns {Middleware} Express-compatible middleware
  */
 export declare function timeout(timeoutMs?: number): Middleware;
+/**
+ * Creates an Express middleware that initializes a per-request context.
+ *
+ * @param {object} [options] - Optional configuration
+ * @param {string} [options.headerName='x-request-id'] - Header to look for request ID
+ * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized
+ * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function
+ */
+export declare function setupRequestContext(options?: {
+    headerName?: string;
+    autoLog?: boolean;
+}): Middleware;
+export interface ErrorHandlerOptions {
+    /** Whether to log errors (default: true) */
+    logErrors?: boolean;
+    /** Whether to include error details in non-production (default: false) */
+    includeDetails?: boolean;
+}
 /**
  * Global error handling middleware with enhanced features.
  *
- * @param {object} [options] - Error handler options
+ * @param {ErrorHandlerOptions} options - Error handler options
  * @param {boolean} [options.logErrors=true] - Whether to log errors
  * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
- * @param {Function} [options.logger=getLogger().error] - Custom logging function
- * @returns {(err: any, req: Request, res: Response, next: NextFunction) => void} Error middleware
+ * @returns Error middleware
+ *
+ * @example
+ * import express from 'express';
+ * import { errorHandler } from '@catbee/utils';
+ *
+ * const app = express();
+ *
+ * // Your routes
+ * app.get('/ping', (req, res) => {
+ *   throw new Error('Something went wrong');
+ * });
+ *
+ * // Error handler (must be last middleware)
+ * app.use(errorHandler({ includeDetails: true }));
+ *
+ * app.listen(3000, () => {
+ *   console.log('Server running on port 3000');
+ * });
  */
-export declare function errorHandler(options?: {
-    logErrors?: boolean;
-    includeDetails?: boolean;
-    logger?: (message: string, error: any) => void;
-}): (err: any, req: Request, res: Response, _next: NextFunction) => void;
-export {};
+export declare function errorHandler(options?: ErrorHandlerOptions): (err: any, req: Request, res: Response, _next: NextFunction) => Response<any, Record<string, any>>;
 //# sourceMappingURL=middleware.utils.d.ts.map

package/build/esnext/utils/middleware.utils.js

@@ -1,10 +1,10 @@
-import { randomUUID } from 'crypto';
-import { Config } from '../config';
+import { config } from '../config';
 import { uuid } from './id.utils';
 import { HttpStatusCodes } from './http-status-codes';
 import { ErrorResponse } from './response.utils';
 import { Env } from './env.utils';
 import { getLogger } from './logger.utils';
+import { ContextStore, StoreKeys } from './context-store.utils';
 /**
  * Attaches a unique request ID to each request.
  * Useful for request tracing and correlation between logs.
@@ -20,7 +20,7 @@ export function requestId(options) {
     return (req, res, next) => {
         // Use existing request ID from header or generate a new one
         const existingId = req.headers[headerName.toLowerCase()];
-        const id = existingId || randomUUID();
+        const id = existingId || uuid();
         // Attach ID to request object
         req.id = id;
         // Add ID to response headers
@@ -43,22 +43,23 @@ export function responseTime(options) {
     const logOnComplete = (options === null || options === void 0 ? void 0 : options.logOnComplete) === true;
     return (req, res, next) => {
         const start = process.hrtime();
-        // Function to calculate elapsed time
-        const calculateDuration = () => {
-            const diff = process.hrtime(start);
-            return diff[0] * 1e3 + diff[1] * 1e-6; // Convert to ms
-        };
-        // Handle response completion
-        res.on('finish', () => {
-            const duration = calculateDuration();
-            if (addHeader) {
+        if (addHeader) {
+            // Wrap res.end to set header just before sending response
+            const originalEnd = res.end;
+            res.end = function (chunk, encoding, cb) {
+                const diff = process.hrtime(start);
+                const duration = diff[0] * 1e3 + diff[1] * 1e-6;
                 res.setHeader('X-Response-Time', `${duration.toFixed(2)}ms`);
-            }
-            if (logOnComplete) {
-                const { method, url } = req;
-                getLogger().info(`${method} ${url} - ${duration.toFixed(2)}ms`);
-            }
-        });
+                return originalEnd.call(this, chunk, encoding, cb);
+            };
+        }
+        if (logOnComplete) {
+            res.on('finish', () => {
+                const diff = process.hrtime(start);
+                const duration = diff[0] * 1e3 + diff[1] * 1e-6;
+                getLogger().info(`${req.method} ${req.url} - ${duration.toFixed(2)}ms`);
+            });
+        }
         next();
     };
 }
@@ -69,7 +70,7 @@ export function responseTime(options) {
  * @param {number} [timeoutMs=30000] - Timeout in milliseconds
  * @returns {Middleware} Express-compatible middleware
  */
-export function timeout(timeoutMs = Config.Http.timeout) {
+export function timeout(timeoutMs = config.http.timeout) {
     return (req, res, next) => {
         // Set timeout for the request
         const timer = setTimeout(() => {
@@ -88,55 +89,69 @@ export function timeout(timeoutMs = Config.Http.timeout) {
     };
 }
 /**
- * Creates a standardized error response object for API errors.
+ * Creates an Express middleware that initializes a per-request context.
  *
- * @param {string} message - Error message
- * @param {Request} req - Express request object
- * @param {any} error - Original error object
- * @param {object} [options] - Additional options
- * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
- * @returns {object} Formatted error response
+ * @param {object} [options] - Optional configuration
+ * @param {string} [options.headerName='x-request-id'] - Header to look for request ID
+ * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized
+ * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function
  */
-const createErrorResponse = (message, req, error, options) => {
-    const isDev = Env.isDev();
-    const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) && isDev;
-    const response = {
-        error: true,
-        message,
-        timestamp: new Date().toISOString(),
-        requestId: (error === null || error === void 0 ? void 0 : error.requestId) || req.id || uuid(),
-        path: req.originalUrl || req.url
+export function setupRequestContext(options = {}) {
+    const { headerName = 'x-request-id', autoLog = true } = options;
+    return (req, _res, next) => {
+        // Generate or use existing request ID
+        const requestId = req.headers[headerName] || (req === null || req === void 0 ? void 0 : req['id']) || uuid();
+        ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
+            // Create a child logger for this request
+            const childLogger = getLogger().child({
+                requestId,
+                method: req.method,
+                url: req.originalUrl || req.url
+            });
+            // Store logger in context
+            ContextStore.set(StoreKeys.LOGGER, childLogger);
+            if (autoLog) {
+                childLogger.info('Request context initialized');
+            }
+            next();
+        });
     };
-    // Include error code if present
-    if (error === null || error === void 0 ? void 0 : error.code) {
-        response.code = error.code;
-    }
-    // Include stack trace in development mode if requested
-    if (includeDetails && (error === null || error === void 0 ? void 0 : error.stack)) {
-        response.stack = error.stack.split('\n').map((line) => line.trim());
-    }
-    return response;
-};
+}
 /**
  * Global error handling middleware with enhanced features.
  *
- * @param {object} [options] - Error handler options
+ * @param {ErrorHandlerOptions} options - Error handler options
  * @param {boolean} [options.logErrors=true] - Whether to log errors
  * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
- * @param {Function} [options.logger=getLogger().error] - Custom logging function
- * @returns {(err: any, req: Request, res: Response, next: NextFunction) => void} Error middleware
+ * @returns Error middleware
+ *
+ * @example
+ * import express from 'express';
+ * import { errorHandler } from '@catbee/utils';
+ *
+ * const app = express();
+ *
+ * // Your routes
+ * app.get('/ping', (req, res) => {
+ *   throw new Error('Something went wrong');
+ * });
+ *
+ * // Error handler (must be last middleware)
+ * app.use(errorHandler({ includeDetails: true }));
+ *
+ * app.listen(3000, () => {
+ *   console.log('Server running on port 3000');
+ * });
  */
 export function errorHandler(options) {
     const logErrors = (options === null || options === void 0 ? void 0 : options.logErrors) !== false;
     const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) === true;
-    const logger = (options === null || options === void 0 ? void 0 : options.logger) || getLogger().error;
     return (err, req, res, _next) => {
         // Determine status code
         const status = (err === null || err === void 0 ? void 0 : err.status) || (err === null || err === void 0 ? void 0 : err.statusCode) || HttpStatusCodes.INTERNAL_SERVER_ERROR;
         // Log error if enabled
         if (logErrors) {
-            const logMessage = `[ERROR] ${req.method} ${req.originalUrl || req.url}: ${err.message || 'Unknown error'}`;
-            logger(logMessage, err);
+            getLogger().error({ error: err }, `${err.message || 'Unknown error'}`);
         }
         // Handle ErrorResponse instances (our custom error class)
         if (err instanceof ErrorResponse) {
@@ -148,6 +163,26 @@ export function errorHandler(options) {
                 path: req.originalUrl || req.url
             });
         }
+        const createErrorResponse = (message, req, error, options) => {
+            const isDev = Env.isDev();
+            const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) && isDev;
+            const response = {
+                error: true,
+                message,
+                timestamp: new Date().toISOString(),
+                requestId: (error === null || error === void 0 ? void 0 : error.requestId) || req.id || uuid(),
+                path: req.originalUrl || req.url
+            };
+            // Include error code if present
+            if (error === null || error === void 0 ? void 0 : error.code) {
+                response.code = error.code;
+            }
+            // Include stack trace in development mode if requested
+            if (includeDetails && (error === null || error === void 0 ? void 0 : error.stack)) {
+                response.stack = error.stack.split('\n').map((line) => line.trim());
+            }
+            return response;
+        };
         // Handle any other errors
         return res.status(status).json(createErrorResponse((err === null || err === void 0 ? void 0 : err.message) || 'Internal Server Error', req, err, {
             includeDetails

package/build/esnext/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":["import { randomUUID } from 'crypto';\nimport { Config } from '../config';\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { ErrorResponse } from './response.utils';\nimport { Env } from './env.utils';\nimport { getLogger } from './logger.utils';\n\n/**\n * Type definitions for Express-compatible middleware\n */\ntype Request = {\n  headers: Record<string, string | string[] | undefined>;\n  method: string;\n  url: string;\n  ip?: string;\n  body?: any;\n  query?: Record<string, any>;\n  params?: Record<string, any>;\n  [key: string]: any;\n};\n\ntype Response = {\n  status: (code: number) => Response;\n  json: (data: any) => void;\n  send: (data: any) => void;\n  setHeader: (name: string, value: string | string[]) => void;\n  end: (data?: any) => void;\n  on: (event: string, callback: (...args: any[]) => void) => void;\n  [key: string]: any;\n};\n\ntype NextFunction = (err?: Error | any) => void;\n\ntype 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 * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: { headerName?: string; exposeHeader?: boolean }): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\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) || randomUUID();\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 }): Middleware {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req, res, next) => {\n    const start = process.hrtime();\n\n    // Function to calculate elapsed time\n    const calculateDuration = (): number => {\n      const diff = process.hrtime(start);\n      return diff[0] * 1e3 + diff[1] * 1e-6; // Convert to ms\n    };\n\n    // Handle response completion\n    res.on('finish', () => {\n      const duration = calculateDuration();\n\n      if (addHeader) {\n        res.setHeader('X-Response-Time', `${duration.toFixed(2)}ms`);\n      }\n\n      if (logOnComplete) {\n        const { method, url } = req;\n        getLogger().info(`${method} ${url} - ${duration.toFixed(2)}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 = Config.Http.timeout): Middleware {\n  return (req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      res.status(408).json({\n        error: true,\n        message: 'Request timeout',\n        status: 408,\n        timestamp: new Date().toISOString()\n      });\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 a standardized error response object for API errors.\n *\n * @param {string} message - Error message\n * @param {Request} req - Express request object\n * @param {any} error - Original error object\n * @param {object} [options] - Additional options\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns {object} Formatted error response\n */\nconst createErrorResponse = (message: string, req: Request, error: any, options?: { includeDetails?: boolean }) => {\n  const isDev = Env.isDev();\n  const includeDetails = options?.includeDetails && isDev;\n\n  const response: Record<string, any> = {\n    error: true,\n    message,\n    timestamp: new Date().toISOString(),\n    requestId: error?.requestId || req.id || uuid(),\n    path: req.originalUrl || req.url\n  };\n\n  // Include error code if present\n  if (error?.code) {\n    response.code = error.code;\n  }\n\n  // Include stack trace in development mode if requested\n  if (includeDetails && error?.stack) {\n    response.stack = error.stack.split('\\n').map((line: string) => line.trim());\n  }\n\n  return response;\n};\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {object} [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 * @param {Function} [options.logger=getLogger().error] - Custom logging function\n * @returns {(err: any, req: Request, res: Response, next: NextFunction) => void} Error middleware\n */\nexport function errorHandler(options?: {\n  logErrors?: boolean;\n  includeDetails?: boolean;\n  logger?: (message: string, error: any) => void;\n}) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n  const logger = options?.logger || getLogger().error;\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      const logMessage = `[ERROR] ${req.method} ${req.originalUrl || req.url}: ${err.message || 'Unknown error'}`;\n      logger(logMessage, err);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      return res.status(status).json({\n        error: err.error,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err.requestId || req.id || uuid(),\n        path: req.originalUrl || req.url\n      });\n    }\n\n    // Handle any other errors\n    return res.status(status).json(\n      createErrorResponse(err?.message || 'Internal Server Error', req, err, {\n        includeDetails\n      })\n    );\n  };\n}\n"]}
+{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { config } from '../config';\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { ErrorResponse } from './response.utils';\nimport { Env } from './env.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\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 * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: { headerName?: string; exposeHeader?: boolean }): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\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) || uuid();\n\n    // Attach ID to request object\n    (req as any).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    if (addHeader) {\n      // Wrap res.end to set header just before sending response\n      const originalEnd = res.end;\n      res.end = function (chunk?: any, encoding?: any, cb?: any) {\n        const diff = process.hrtime(start);\n        const duration = diff[0] * 1e3 + diff[1] * 1e-6;\n        res.setHeader('X-Response-Time', `${duration.toFixed(2)}ms`);\n        return originalEnd.call(this, chunk, encoding, cb);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        const diff = process.hrtime(start);\n        const duration = diff[0] * 1e3 + diff[1] * 1e-6;\n        getLogger().info(`${req.method} ${req.url} - ${duration.toFixed(2)}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 = config.http.timeout): Middleware {\n  return (req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      res.status(408).json({\n        error: true,\n        message: 'Request timeout',\n        status: 408,\n        timestamp: new Date().toISOString()\n      });\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({ error: err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      return res.status(status).json({\n        error: err.error,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err.requestId || (req as any).id || uuid(),\n        path: req.originalUrl || req.url\n      });\n    }\n\n    const createErrorResponse = (message: string, req: Request, error: any, options?: { includeDetails?: boolean }) => {\n      const isDev = Env.isDev();\n      const includeDetails = options?.includeDetails && isDev;\n\n      const response: Record<string, any> = {\n        error: true,\n        message,\n        timestamp: new Date().toISOString(),\n        requestId: error?.requestId || (req as any).id || uuid(),\n        path: req.originalUrl || req.url\n      };\n\n      // Include error code if present\n      if (error?.code) {\n        response.code = error.code;\n      }\n\n      // Include stack trace in development mode if requested\n      if (includeDetails && error?.stack) {\n        response.stack = error.stack.split('\\n').map((line: string) => line.trim());\n      }\n\n      return response;\n    };\n\n    // Handle any other errors\n    return res.status(status).json(\n      createErrorResponse(err?.message || 'Internal Server Error', req, err, {\n        includeDetails\n      })\n    );\n  };\n}\n"]}

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

@@ -0,0 +1,77 @@
+/**
+ * Options for parsing and validating request parameters.
+ */
+export interface ValidationOptions {
+    /** Whether to throw an error on validation failure */
+    throwOnError?: boolean;
+    /** Custom error message for validation failures */
+    errorMessage?: string;
+    /** Default value to use if parameter is missing */
+    defaultValue?: any;
+    /** Whether the parameter is required */
+    required?: boolean;
+}
+/**
+ * Result of a parameter validation operation.
+ */
+export interface ValidationResult<T> {
+    /** Whether validation was successful */
+    isValid: boolean;
+    /** The validated and potentially transformed value */
+    value: T | null;
+    /** Error message if validation failed */
+    error?: string;
+}
+/**
+ * Safely parses a string parameter to a number.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed number or error
+ */
+export declare function parseNumberParam(value: string | undefined, options?: ValidationOptions): ValidationResult<number>;
+/**
+ * Safely parses a string parameter to a boolean.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed boolean or error
+ */
+export declare function parseBooleanParam(value: string | undefined, options?: ValidationOptions): ValidationResult<boolean>;
+/**
+ * Extracts pagination parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param defaultPage - Default page number if not specified (defaults to 1)
+ * @param defaultLimit - Default per page size if not specified (defaults to 20)
+ * @param maxLimitSize - Maximum allowed per page size (defaults to 100)
+ * @returns Object containing validated page and limit
+ */
+export declare function extractPaginationParams(query: Record<string, string | string[]>, defaultPage?: number, defaultLimit?: number, maxLimitSize?: number): {
+    page: number;
+    limit: number;
+};
+/**
+ * Extracts sorting parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param allowedFields - Array of field names that are allowed to be sorted
+ * @param defaultSort - Default sort configuration if not specified
+ * @returns Object containing sort field and direction
+ */
+export declare function extractSortParams(query: Record<string, string | string[]>, allowedFields: string[], defaultSort?: {
+    sortBy: string;
+    sortOrder: 'asc' | 'desc';
+}): {
+    sortBy: string;
+    sortOrder: 'asc' | 'desc';
+};
+/**
+ * Extracts filter parameters from query parameters based on allowed filter fields.
+ *
+ * @param query - Query parameters object
+ * @param allowedFilters - Array of field names that are allowed to be used as filters
+ * @returns Object containing the filters as key-value pairs
+ */
+export declare function extractFilterParams(query: Record<string, string | string[]>, allowedFilters: string[]): Record<string, string | string[]>;
+//# sourceMappingURL=request.utils.d.ts.map

package/build/esnext/utils/request.utils.js

@@ -0,0 +1,145 @@
+/**
+ * Safely parses a string parameter to a number.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed number or error
+ */
+export function parseNumberParam(value, options = {}) {
+    const { throwOnError = false, errorMessage = 'Invalid number parameter', defaultValue, required = false } = options;
+    // Handle undefined case
+    if (value === undefined) {
+        if (required) {
+            const error = `Required number parameter is missing`;
+            if (throwOnError)
+                throw new Error(error);
+            return { isValid: false, value: null, error };
+        }
+        return {
+            isValid: defaultValue !== undefined,
+            value: defaultValue !== undefined ? defaultValue : null,
+            error: defaultValue === undefined ? 'Missing parameter with no default' : undefined
+        };
+    }
+    // Parse and validate the number
+    const num = Number(value);
+    if (isNaN(num)) {
+        if (throwOnError)
+            throw new Error(errorMessage);
+        return { isValid: false, value: null, error: errorMessage };
+    }
+    return { isValid: true, value: num };
+}
+/**
+ * Safely parses a string parameter to a boolean.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed boolean or error
+ */
+export function parseBooleanParam(value, options = {}) {
+    const { throwOnError = false, errorMessage = 'Invalid boolean parameter', defaultValue, required = false } = options;
+    // Handle undefined case
+    if (value === undefined) {
+        if (required) {
+            const error = `Required boolean parameter is missing`;
+            if (throwOnError)
+                throw new Error(error);
+            return { isValid: false, value: null, error };
+        }
+        return {
+            isValid: defaultValue !== undefined,
+            value: defaultValue !== undefined ? defaultValue : null,
+            error: defaultValue === undefined ? 'Missing parameter with no default' : undefined
+        };
+    }
+    // Parse the boolean value with various allowed formats
+    const lowercaseValue = value.toLowerCase();
+    if (['true', 't', 'yes', 'y', '1'].includes(lowercaseValue)) {
+        return { isValid: true, value: true };
+    }
+    if (['false', 'f', 'no', 'n', '0'].includes(lowercaseValue)) {
+        return { isValid: true, value: false };
+    }
+    if (throwOnError)
+        throw new Error(errorMessage);
+    return { isValid: false, value: null, error: errorMessage };
+}
+/**
+ * Extracts pagination parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param defaultPage - Default page number if not specified (defaults to 1)
+ * @param defaultLimit - Default per page size if not specified (defaults to 20)
+ * @param maxLimitSize - Maximum allowed per page size (defaults to 100)
+ * @returns Object containing validated page and limit
+ */
+export function extractPaginationParams(query, defaultPage = 1, defaultLimit = 20, maxLimitSize = 100) {
+    // Parse page parameter
+    const pageParam = typeof query.page === 'string' ? query.page : undefined;
+    const pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });
+    // Parse limit parameter
+    const limitParam = typeof query.limit === 'string' ? query.limit : undefined;
+    const limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });
+    // Ensure valid values (handle 0 → fallback to default)
+    const page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;
+    const limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;
+    return { page, limit };
+}
+/**
+ * Extracts sorting parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param allowedFields - Array of field names that are allowed to be sorted
+ * @param defaultSort - Default sort configuration if not specified
+ * @returns Object containing sort field and direction
+ */
+export function extractSortParams(query, allowedFields, defaultSort = { sortBy: 'createdAt', sortOrder: 'desc' }) {
+    let sortBy = defaultSort.sortBy;
+    let sortOrder = defaultSort.sortOrder;
+    // Extract from `sortBy` or `sort`
+    if (typeof query.sortBy === 'string') {
+        sortBy = query.sortBy;
+    }
+    else if (Array.isArray(query.sortBy)) {
+        sortBy = query.sortBy[0];
+    }
+    else if (typeof query.sort === 'string') {
+        sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;
+        sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';
+    }
+    else if (Array.isArray(query.sort)) {
+        sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];
+        sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';
+    }
+    // Explicit sortOrder (overrides inferred one if valid)
+    if (typeof query.sortOrder === 'string') {
+        const order = query.sortOrder.toLowerCase();
+        if (order === 'asc' || order === 'desc') {
+            sortOrder = order;
+        }
+    }
+    // Validate field
+    if (!allowedFields.includes(sortBy)) {
+        sortBy = defaultSort.sortBy;
+    }
+    return { sortBy, sortOrder };
+}
+/**
+ * Extracts filter parameters from query parameters based on allowed filter fields.
+ *
+ * @param query - Query parameters object
+ * @param allowedFilters - Array of field names that are allowed to be used as filters
+ * @returns Object containing the filters as key-value pairs
+ */
+export function extractFilterParams(query, allowedFilters) {
+    const filters = {};
+    // Find filter parameters in the query
+    for (const field of allowedFilters) {
+        if (field in query) {
+            filters[field] = query[field];
+        }
+    }
+    return filters;
+}
+//# sourceMappingURL=request.utils.js.map