@catbee/utils 0.0.7 → 0.0.8-next.0

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

@@ -1,136 +0,0 @@
-/**
- * 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

@@ -1,278 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"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,86 +0,0 @@
-import { Request } from 'express';
-import { WithPagination } from '../types/api-response';
-/**
- * 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;
-}
-/**
- * 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.
- *
- * @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