@catbee/utils 0.0.7 → 0.0.8-next.0

package/build/esm/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/esm/utils/performance.utils.js

@@ -1,376 +0,0 @@
-/*
- * 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.
- */
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
-    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (g && (g = 0, op[0] && (_ = 0)), _) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
-    }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
-    }
-    return ar;
-};
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
-import { TTLCache } from './cache.utils';
-import { getLogger } from './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`);
- * ```
- */
-export function timeSync(fn, options) {
-    if (options === void 0) { options = {}; }
-    var _a = options.label, label = _a === void 0 ? fn.name || 'anonymous function' : _a, _b = options.log, log = _b === void 0 ? false : _b, _c = options.logLevel, logLevel = _c === void 0 ? 'debug' : _c;
-    var startTime = performance.now();
-    var result = fn();
-    var endTime = performance.now();
-    var durationMs = endTime - startTime;
-    var durationSec = durationMs / 1000;
-    var timing = {
-        durationMs: durationMs,
-        durationSec: durationSec,
-        startTime: startTime,
-        endTime: endTime,
-        label: label
-    };
-    if (log) {
-        var logger = getLogger();
-        var message = "".concat(label, " completed in ").concat(durationMs.toFixed(2), "ms");
-        switch (logLevel) {
-            case 'trace':
-                logger.trace({ timing: timing }, message);
-                break;
-            case 'debug':
-                logger.debug({ timing: timing }, message);
-                break;
-            case 'info':
-                logger.info({ timing: timing }, message);
-                break;
-            case 'warn':
-                logger.warn({ timing: timing }, message);
-                break;
-            case 'error':
-                logger.error({ timing: timing }, message);
-                break;
-            default:
-                logger.debug({ timing: timing }, message);
-                break;
-        }
-    }
-    return { result: result, timing: 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`);
- * ```
- */
-export function timeAsync(fn_1) {
-    return __awaiter(this, arguments, void 0, function (fn, options) {
-        var _a, label, _b, log, _c, logLevel, startTime, result, endTime, durationMs, durationSec, timing, logger, message;
-        if (options === void 0) { options = {}; }
-        return __generator(this, function (_d) {
-            switch (_d.label) {
-                case 0:
-                    _a = options.label, label = _a === void 0 ? fn.name || 'anonymous async function' : _a, _b = options.log, log = _b === void 0 ? false : _b, _c = options.logLevel, logLevel = _c === void 0 ? 'debug' : _c;
-                    startTime = performance.now();
-                    return [4 /*yield*/, fn()];
-                case 1:
-                    result = _d.sent();
-                    endTime = performance.now();
-                    durationMs = endTime - startTime;
-                    durationSec = durationMs / 1000;
-                    timing = {
-                        durationMs: durationMs,
-                        durationSec: durationSec,
-                        startTime: startTime,
-                        endTime: endTime,
-                        label: label
-                    };
-                    if (log) {
-                        logger = getLogger();
-                        message = "".concat(label, " completed in ").concat(durationMs.toFixed(2), "ms");
-                        switch (logLevel) {
-                            case 'trace':
-                                logger.trace({ timing: timing }, message);
-                                break;
-                            case 'debug':
-                                logger.debug({ timing: timing }, message);
-                                break;
-                            case 'info':
-                                logger.info({ timing: timing }, message);
-                                break;
-                            case 'warn':
-                                logger.warn({ timing: timing }, message);
-                                break;
-                            case 'error':
-                                logger.error({ timing: timing }, message);
-                                break;
-                            default:
-                                logger.debug({ timing: timing }, message);
-                                break;
-                        }
-                    }
-                    return [2 /*return*/, { result: result, timing: 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
- *   }
- * }
- * ```
- */
-export function timed(options) {
-    if (options === void 0) { options = {}; }
-    return function (target, propertyKeyOrContext, descriptor) {
-        var propertyKey;
-        var 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);
-        }
-        var originalMethod = actualDescriptor.value;
-        actualDescriptor.value = function () {
-            var _this = this;
-            var args = [];
-            for (var _i = 0; _i < arguments.length; _i++) {
-                args[_i] = arguments[_i];
-            }
-            var methodOptions = __assign(__assign({}, options), { label: options.label || "".concat(target.constructor.name, ".").concat(String(propertyKey)) });
-            if (originalMethod.constructor.name === 'AsyncFunction') {
-                return timeAsync(function () { return originalMethod.apply(_this, args); }, methodOptions).then(function (_a) {
-                    var result = _a.result;
-                    return result;
-                });
-            }
-            else {
-                return timeSync(function () { return 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 }
- * );
- * ```
- */
-export function memoize(fn, options) {
-    if (options === void 0) { options = {}; }
-    var ttl = options.ttl, maxSize = options.maxSize, autoCleanupMs = options.autoCleanupMs, _a = options.cacheKey, cacheKey = _a === void 0 ? function () {
-        var args = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            args[_i] = arguments[_i];
-        }
-        return JSON.stringify(args);
-    } : _a;
-    // Create a properly configured TTLCache instance
-    var cache = new TTLCache({
-        ttlMs: ttl,
-        maxSize: maxSize,
-        autoCleanupMs: autoCleanupMs
-    });
-    return function () {
-        var args = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            args[_i] = arguments[_i];
-        }
-        var key = cacheKey.apply(void 0, __spreadArray([], __read(args), false));
-        // Try to get from cache first - TTLCache handles expiration internally
-        var cachedValue = cache.get(key);
-        if (cachedValue !== undefined) {
-            return cachedValue;
-        }
-        // Calculate the value and store in cache with configured TTL
-        var value = fn.apply(void 0, __spreadArray([], __read(args), false));
-        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
- */
-export function trackMemoryUsage(fn, options) {
-    if (options === void 0) { options = {}; }
-    var _a = options.log, log = _a === void 0 ? false : _a, _b = options.label, label = _b === void 0 ? fn.name || 'anonymous function' : _b;
-    // Collect garbage before measuring (optional)
-    if (global.gc) {
-        global.gc();
-    }
-    var beforeMemory = process.memoryUsage();
-    var result = fn();
-    var afterMemory = process.memoryUsage();
-    // Calculate differences
-    var diff = {};
-    for (var key in afterMemory) {
-        if (Object.prototype.hasOwnProperty.call(afterMemory, key)) {
-            diff[key] = afterMemory[key] - beforeMemory[key];
-        }
-    }
-    if (log) {
-        getLogger().info({
-            label: label,
-            memoryBefore: beforeMemory,
-            memoryAfter: afterMemory,
-            memoryDiff: diff
-        }, "Memory usage for ".concat(label));
-    }
-    return {
-        result: result,
-        memoryUsage: {
-            before: beforeMemory,
-            after: afterMemory,
-            diff: diff
-        }
-    };
-}
-//# sourceMappingURL=performance.utils.js.map

package/build/esm/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/esm/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