@catbee/utils 0.0.8-rc.2 → 0.0.8-rc.3

package/build/cjs/utils/performance.utils.js

@@ -0,0 +1,280 @@
+"use strict";
+/*
+ * 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.
+ */
+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 ?? Object.getOwnPropertyDescriptor(target, propertyKey);
+        }
+        else {
+            // Legacy decorator: second argument is property key
+            propertyKey = propertyKeyOrContext;
+            actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey);
+        }
+        const originalMethod = actualDescriptor.value;
+        actualDescriptor.value = function (...args) {
+            const methodOptions = {
+                ...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
+        }
+    };
+}

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

@@ -0,0 +1,85 @@
+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[]>;

package/build/cjs/utils/request.utils.js

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