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

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

@@ -1,273 +0,0 @@
-/*
- * 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.
- */
-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 = {}) {
-    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 = 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`);
- * ```
- */
-export 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 = 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
- *   }
- * }
- * ```
- */
-export 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 }
- * );
- * ```
- */
-export function memoize(fn, options = {}) {
-    const { ttl, maxSize, autoCleanupMs, cacheKey = (...args) => JSON.stringify(args) } = options;
-    // Create a properly configured TTLCache instance
-    const cache = new 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
- */
-export 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) {
-        getLogger().info({
-            label,
-            memoryBefore: beforeMemory,
-            memoryAfter: afterMemory,
-            memoryDiff: diff
-        }, `Memory usage for ${label}`);
-    }
-    return {
-        result,
-        memoryUsage: {
-            before: beforeMemory,
-            after: afterMemory,
-            diff
-        }
-    };
-}

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

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

package/build/esm/utils/request.utils.js

@@ -1,190 +0,0 @@
-/*
- * 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.
- */
-import { BadRequestException } from './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
- */
-export 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
-    };
-};
-/**
- * Safely parses a string parameter to a number.
- *
- * @param value - String value to parse
- * @param options - Validation options
- * @returns Validation result containing the parsed number or error
- */
-export function parseNumberParam(value, options = {}) {
-    const { throwOnError = false, errorMessage = 'Invalid number parameter', defaultValue, required = false } = options;
-    // Handle undefined case
-    if (value === undefined) {
-        if (required) {
-            const error = `Required number parameter is missing`;
-            if (throwOnError)
-                throw new 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 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
- */
-export function parseBooleanParam(value, options = {}) {
-    const { throwOnError = false, errorMessage = 'Invalid boolean parameter', defaultValue, required = false } = options;
-    // Handle undefined case
-    if (value === undefined) {
-        if (required) {
-            const error = `Required boolean parameter is missing`;
-            if (throwOnError)
-                throw new 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 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
- */
-export function extractPaginationParams(query, defaultPage = 1, defaultLimit = 20, maxLimitSize = 100) {
-    // Parse page parameter
-    const pageParam = typeof query.page === 'string' ? query.page : undefined;
-    const pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });
-    // Parse limit parameter
-    const limitParam = typeof query.limit === 'string' ? query.limit : undefined;
-    const limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });
-    // Ensure valid values (handle 0 → fallback to default)
-    const page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;
-    const limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;
-    return { page, limit };
-}
-/**
- * Extracts sorting parameters from request query parameters.
- *
- * @param query - Query parameters object
- * @param allowedFields - Array of field names that are allowed to be sorted
- * @param defaultSort - Default sort configuration if not specified
- * @returns Object containing sort field and direction
- */
-export function extractSortParams(query, allowedFields, defaultSort = { sortBy: 'createdAt', sortOrder: 'desc' }) {
-    let sortBy = defaultSort.sortBy;
-    let sortOrder = defaultSort.sortOrder;
-    // Extract from `sortBy` or `sort`
-    if (typeof query.sortBy === 'string') {
-        sortBy = query.sortBy;
-    }
-    else if (Array.isArray(query.sortBy)) {
-        sortBy = query.sortBy[0];
-    }
-    else if (typeof query.sort === 'string') {
-        sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;
-        sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';
-    }
-    else if (Array.isArray(query.sort)) {
-        sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];
-        sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';
-    }
-    // Explicit sortOrder (overrides inferred one if valid)
-    if (typeof query.sortOrder === 'string') {
-        const order = query.sortOrder.toLowerCase();
-        if (order === 'asc' || order === 'desc') {
-            sortOrder = order;
-        }
-    }
-    // Validate field
-    if (allowedFields.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
- */
-export function extractFilterParams(query, allowedFilters) {
-    const filters = {};
-    // Find filter parameters in the query
-    for (const field of allowedFilters) {
-        if (field in query) {
-            filters[field] = query[field];
-        }
-    }
-    return filters;
-}