@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

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

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

package/build/esm/utils/performance.utils.js

@@ -0,0 +1,376 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+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

@@ -0,0 +1 @@
+{"version":3,"file":"performance.utils.js","sourceRoot":"","sources":["../../../src/utils/performance.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA8B3C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,QAAQ,CAAI,EAAW,EAAE,OAA2B;IAA3B,wBAAA,EAAA,YAA2B;IAC1D,IAAA,KAA6E,OAAO,MAA7C,EAAvC,KAAK,mBAAG,EAAE,CAAC,IAAI,IAAI,oBAAoB,KAAA,EAAE,KAAoC,OAAO,IAAhC,EAAX,GAAG,mBAAG,KAAK,KAAA,EAAE,KAAuB,OAAO,SAAZ,EAAlB,QAAQ,mBAAG,OAAO,KAAA,CAAa;IAE7F,IAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACpC,IAAM,MAAM,GAAG,EAAE,EAAE,CAAC;IACpB,IAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAElC,IAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;IACvC,IAAM,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;IAEtC,IAAM,MAAM,GAAiB;QAC3B,UAAU,YAAA;QACV,WAAW,aAAA;QACX,SAAS,WAAA;QACT,OAAO,SAAA;QACP,KAAK,OAAA;KACN,CAAC;IAEF,IAAI,GAAG,EAAE,CAAC;QACR,IAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,IAAM,OAAO,GAAG,UAAG,KAAK,2BAAiB,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,OAAI,CAAC;QAEnE,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,OAAO;gBACV,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gBAClC,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gBAClC,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gBAClC,MAAM;YACR;gBACE,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gBAClC,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,QAAA,EAAE,MAAM,QAAA,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAgB,SAAS;wDAC7B,EAAoB,EACpB,OAA2B;;QAA3B,wBAAA,EAAA,YAA2B;;;;oBAEnB,KAAmF,OAAO,MAA7C,EAA7C,KAAK,mBAAG,EAAE,CAAC,IAAI,IAAI,0BAA0B,KAAA,EAAE,KAAoC,OAAO,IAAhC,EAAX,GAAG,mBAAG,KAAK,KAAA,EAAE,KAAuB,OAAO,SAAZ,EAAlB,QAAQ,mBAAG,OAAO,KAAA,CAAa;oBAE7F,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;oBACrB,qBAAM,EAAE,EAAE,EAAA;;oBAAnB,MAAM,GAAG,SAAU;oBACnB,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;oBAE5B,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;oBACjC,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;oBAEhC,MAAM,GAAiB;wBAC3B,UAAU,YAAA;wBACV,WAAW,aAAA;wBACX,SAAS,WAAA;wBACT,OAAO,SAAA;wBACP,KAAK,OAAA;qBACN,CAAC;oBAEF,IAAI,GAAG,EAAE,CAAC;wBACF,MAAM,GAAG,SAAS,EAAE,CAAC;wBACrB,OAAO,GAAG,UAAG,KAAK,2BAAiB,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,OAAI,CAAC;wBAEnE,QAAQ,QAAQ,EAAE,CAAC;4BACjB,KAAK,OAAO;gCACV,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gCAClC,MAAM;4BACR,KAAK,OAAO;gCACV,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gCAClC,MAAM;4BACR,KAAK,MAAM;gCACT,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gCACjC,MAAM;4BACR,KAAK,MAAM;gCACT,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gCACjC,MAAM;4BACR,KAAK,OAAO;gCACV,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gCAClC,MAAM;4BACR;gCACE,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,QAAA,EAAE,EAAE,OAAO,CAAC,CAAC;gCAClC,MAAM;wBACV,CAAC;oBACH,CAAC;oBAED,sBAAO,EAAE,MAAM,QAAA,EAAE,MAAM,QAAA,EAAE,EAAC;;;;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,KAAK,CAAC,OAA2B;IAA3B,wBAAA,EAAA,YAA2B;IAC/C,OAAO,UAAU,MAAW,EAAE,oBAA2C,EAAE,UAA+B;QACxG,IAAI,WAA4B,CAAC;QACjC,IAAI,gBAAoC,CAAC;QAEzC,sDAAsD;QACtD,IAAI,OAAO,oBAAoB,KAAK,QAAQ,IAAI,oBAAoB,KAAK,IAAI,IAAI,MAAM,IAAI,oBAAoB,EAAE,CAAC;YAChH,WAAW,GAAG,oBAAoB,CAAC,IAAI,CAAC;YACxC,gBAAgB,GAAG,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAE,CAAC;QACzF,CAAC;aAAM,CAAC;YACN,oDAAoD;YACpD,WAAW,GAAG,oBAAoB,CAAC;YACnC,gBAAgB,GAAG,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAE,CAAC;QACzF,CAAC;QAED,IAAM,cAAc,GAAG,gBAAgB,CAAC,KAAK,CAAC;QAE9C,gBAAgB,CAAC,KAAK,GAAG;YAAA,iBAWxB;YAXkC,cAAc;iBAAd,UAAc,EAAd,qBAAc,EAAd,IAAc;gBAAd,yBAAc;;YAC/C,IAAM,aAAa,yBACd,OAAO,KACV,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,UAAG,MAAM,CAAC,WAAW,CAAC,IAAI,cAAI,MAAM,CAAC,WAAW,CAAC,CAAE,GAC5E,CAAC;YAEF,IAAI,cAAc,CAAC,WAAW,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;gBACxD,OAAO,SAAS,CAAC,cAAM,OAAA,cAAc,CAAC,KAAK,CAAC,KAAI,EAAE,IAAI,CAAC,EAAhC,CAAgC,EAAE,aAAa,CAAC,CAAC,IAAI,CAAC,UAAC,EAAU;wBAAR,MAAM,YAAA;oBAAO,OAAA,MAAM;gBAAN,CAAM,CAAC,CAAC;YACvG,CAAC;iBAAM,CAAC;gBACN,OAAO,QAAQ,CAAC,cAAM,OAAA,cAAc,CAAC,KAAK,CAAC,KAAI,EAAE,IAAI,CAAC,EAAhC,CAAgC,EAAE,aAAa,CAAC,CAAC,MAAM,CAAC;YAChF,CAAC;QACH,CAAC,CAAC;QAEF,mDAAmD;QACnD,IAAI,UAAU,EAAE,CAAC;YACf,UAAU,CAAC,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC;QAC5C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC;QAC/D,CAAC;QACD,yCAAyC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,OAAO,CACrB,EAAwB,EACxB,OASM;IATN,wBAAA,EAAA,YASM;IAEE,IAAA,GAAG,GAA2E,OAAO,IAAlF,EAAE,OAAO,GAAkE,OAAO,QAAzE,EAAE,aAAa,GAAmD,OAAO,cAA1D,EAAE,KAAiD,OAAO,SAAZ,EAA5C,QAAQ,mBAAG;QAAC,cAAO;aAAP,UAAO,EAAP,qBAAO,EAAP,IAAO;YAAP,yBAAO;;QAAK,OAAA,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAApB,CAAoB,KAAA,CAAa;IAE9F,iDAAiD;IACjD,IAAM,KAAK,GAAG,IAAI,QAAQ,CAAY;QACpC,KAAK,EAAE,GAAG;QACV,OAAO,EAAE,OAAO;QAChB,aAAa,EAAE,aAAa;KAC7B,CAAC,CAAC;IAEH,OAAO;QAAU,cAAa;aAAb,UAAa,EAAb,qBAAa,EAAb,IAAa;YAAb,yBAAa;;QAC5B,IAAM,GAAG,GAAG,QAAQ,wCAAI,IAAI,UAAC,CAAC;QAE9B,uEAAuE;QACvE,IAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,6DAA6D;QAC7D,IAAM,KAAK,GAAG,EAAE,wCAAI,IAAI,UAAC,CAAC;QAC1B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,EAAW,EACX,OAKM;IALN,wBAAA,EAAA,YAKM;IAEE,IAAA,KAAyD,OAAO,IAArD,EAAX,GAAG,mBAAG,KAAK,KAAA,EAAE,KAA4C,OAAO,MAAZ,EAAvC,KAAK,mBAAG,EAAE,CAAC,IAAI,IAAI,oBAAoB,KAAA,CAAa;IAEzE,8CAA8C;IAC9C,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,CAAC,EAAE,EAAE,CAAC;IACd,CAAC;IAED,IAAM,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAM,MAAM,GAAG,EAAE,EAAE,CAAC;IACpB,IAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAE1C,wBAAwB;IACxB,IAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,IAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC;YAC3D,IAAI,CAAC,GAAG,CAAC,GAAI,WAAmB,CAAC,GAAG,CAAC,GAAI,YAAoB,CAAC,GAAG,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,IAAI,GAAG,EAAE,CAAC;QACR,SAAS,EAAE,CAAC,IAAI,CACd;YACE,KAAK,OAAA;YACL,YAAY,EAAE,YAAY;YAC1B,WAAW,EAAE,WAAW;YACxB,UAAU,EAAE,IAAI;SACjB,EACD,2BAAoB,KAAK,CAAE,CAC5B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,QAAA;QACN,WAAW,EAAE;YACX,MAAM,EAAE,YAAY;YACpB,KAAK,EAAE,WAAW;YAClB,IAAI,MAAA;SACL;KACF,CAAC;AACJ,CAAC","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\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

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