@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/obj/obj.utils.d.ts

@@ -1,156 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
- */
-
-/**
- * Checks whether the object has no own enumerable properties.
- *
- * @param {Record<any, any>} obj - The object to check.
- * @returns {boolean} True if the object is empty, false otherwise.
- */
-export declare function isObjEmpty(obj: Record<any, any>): boolean;
-/**
- * Returns a new object with only the specified keys picked.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to pick from the object.
- * @returns {Pick<T, K>} New object with picked keys.
- */
-export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
-/**
- * Returns a new object with the specified keys omitted.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to omit from the object.
- * @returns {Omit<T, K>} New object without omitted keys.
- */
-export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
-/**
- * Deeply merges multiple objects into the target object (mutates and returns the target object, not pure).
- *
- * @template T
- * @param {T} target - The object to merge into (will be mutated).
- * @param {...any[]} sources - The objects to merge from.
- * @returns {T} The merged object (same as target).
- */
-export declare function deepObjMerge<T extends object>(target: T, ...sources: any[]): T;
-/**
- * Checks if a value is a plain object (i.e., not an array, null, or a built-in object).
- *
- * @param value - The value to check.
- * @returns True if the value is a plain object, false otherwise.
- */
-export declare function isPlainObject(value: any): value is Record<string, any>;
-/**
- * Flattens a nested object using dot notation for keys (e.g., `{a: {b: 1}}` → `{ "a.b": 1 }`).
- *
- * @template T
- * @param {T} obj - The object to flatten.
- * @param {string} [prefix=""] - Optional prefix for nested keys (used internally).
- * @returns {Record<string, any>} A new object with flattened keys.
- */
-export declare function flattenObject<T extends Record<string, any>>(obj: T, prefix?: string): Record<string, any>;
-/**
- * Safely gets the value of a deeply nested key in an object using dot/bracket notation path.
- *
- * @template T
- * @param {T} obj - The object to extract from.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @returns {any} The value at the given path, or undefined if not found.
- */
-export declare function getValueByPath<T extends object>(obj: T, path: string): any;
-/**
- * Sets a value at a deeply nested key in an object using dot/bracket notation path.
- * Secured against prototype pollution.
- *
- * @template T
- * @param {T} obj - The object to modify.
- * @param {string} path - Dot/bracket notation path (e.g., "user.friends[0].name").
- * @param {any} value - Value to assign.
- * @returns {T} The modified object.
- */
-export declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
-/**
- * Performs a deep equality check between two objects.
- *
- * @param {any} a - First value to compare.
- * @param {any} b - Second value to compare.
- * @returns {boolean} True if values are deeply equal.
- */
-export declare function isEqual(a: any, b: any): boolean;
-/**
- * Filters object properties based on a predicate function.
- *
- * @template T
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => boolean} predicate - Filter function.
- * @returns {Partial<T>} New object with filtered properties.
- */
-export declare function filterObject<T extends object>(obj: T, predicate: (value: any, key: string, obj: T) => boolean): Partial<T>;
-/**
- * Maps object values to new values using a mapping function.
- *
- * @template T
- * @template U
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => U} mapFn - Mapping function.
- * @returns {Record<keyof T, U>} New object with mapped values.
- */
-export declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
-/**
- * Create a deep clone of a value. Uses structuredClone when available, falls back to JSON
- * serialization as a best-effort fallback (may lose functions and special objects).
- *
- * @template T
- * @param {T} value
- * @returns {T}
- */
-export declare function deepClone<T>(value: T): T;
-/**
- * Recursively freezes an object and all its properties.
- * Makes an object immutable.
- *
- * @template T
- * @param {T} obj - The object to freeze.
- * @returns {Readonly<T>} The frozen object.
- */
-export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
-/**
- * Safely checks if a value is an object (not null, not array).
- *
- * @param {unknown} value - Value to check.
- * @returns {boolean} True if value is a non-null, non-array object.
- */
-export declare function isObject(value: unknown): value is Record<string, any>;
-/**
- * Gets all paths in an object using dot notation.
- *
- * @param {Record<string, any>} obj - Object to analyze.
- * @param {string} [parentPath=""] - Internal param for recursion.
- * @returns {string[]} Array of all paths in dot notation.
- */
-export declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];

package/performance/performance.utils.d.ts

@@ -1,159 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
- */
-
-/**
- * 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>;
-    };
-};

package/request/request.utils.d.ts

@@ -1,109 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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 { Request } from 'express';
-import type { WithPagination } from '@catbee/utils/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/response/response.utils.d.ts

@@ -1,186 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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 type { Request } from 'express';
-import { ApiErrorResponse, ApiResponse } from '@catbee/utils/response';
-/**
- * Standard HTTP response wrapper for successful responses.
- * Implements the `ApiResponse<T>` interface and sets default values.
- *
- * @typeParam T - The shape of the data returned in the response.
- */
-export declare class SuccessResponse<T> implements ApiResponse<T> {
-    /** Message describing the result of the operation. */
-    message: string;
-    /** Whether the response is an error. Always false in success responses. */
-    error: boolean;
-    /** The payload returned from the API. */
-    data: T | null;
-    /** Timestamp when the response was generated, in ISO format. */
-    timestamp: string;
-    /** Unique identifier for this response, useful for request tracing. */
-    requestId: string;
-    /**
-     * Constructs a new success response.
-     *
-     * @param {string} message - Optional message to override the default.
-     * @param {T} [data] - Optional data payload.
-     */
-    constructor(message: string, data?: T);
-}
-/**
- * Wrapper for error responses that extends the native `Error` object.
- * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).
- */
-export declare class ErrorResponse extends Error implements Omit<ApiResponse<never>, 'data'> {
-    /** HTTP status code associated with the error (e.g., 404, 500). */
-    status: number;
-    /** Indicates that this is an error. Always true. */
-    error: boolean;
-    /** Timestamp when the error occurred, in ISO format. */
-    timestamp: string;
-    /** Unique identifier for this error instance. */
-    requestId: string;
-    /**
-     * Constructs a new error response.
-     *
-     * @param {string} message - The error message to display or log.
-     * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
-     */
-    constructor(message: string, status?: number);
-}
-/**
- * Response with paginated data extending the standard success response.
- * Useful for APIs that return large collections of data.
- *
- * @typeParam T - The shape of each item in the paginated collection.
- */
-export declare class PaginatedResponse<T> extends SuccessResponse<T[]> {
-    /** Total number of items across all pages */
-    total: number;
-    /** Current page number (1-based) */
-    page: number;
-    /** Number of items per page */
-    pageSize: number;
-    /** Total number of pages */
-    totalPages: number;
-    /** Whether there's a next page available */
-    hasNext: boolean;
-    /** Whether there's a previous page available */
-    hasPrevious: boolean;
-    /**
-     * Constructs a new paginated response.
-     *
-     * @param {T[]} items - The current page of items.
-     * @param {Object} pagination - Pagination information.
-     * @param {number} pagination.total - Total number of items across all pages.
-     * @param {number} pagination.page - Current page number (1-based).
-     * @param {number} pagination.pageSize - Number of items per page.
-     * @param {string} [message="Success"] - Optional custom message.
-     */
-    constructor(items: T[], pagination: {
-        total: number;
-        page: number;
-        pageSize: number;
-    }, message?: string);
-}
-/**
- * Specialized response for operations that don't return data (HTTP 204).
- */
-export declare class NoContentResponse extends SuccessResponse<null> {
-    /**
-     * Constructs a new no-content response.
-     *
-     * @param {string} [message="Operation completed successfully"] - Optional custom message.
-     */
-    constructor(message?: string);
-}
-/**
- * Specialized response for redirects.
- */
-export declare class RedirectResponse {
-    /** The URL to redirect to */
-    redirectUrl: string;
-    /** HTTP status code for the redirect (301, 302, 303, 307, 308) */
-    statusCode: number;
-    /** Whether the response is a redirect */
-    isRedirect: boolean;
-    /** Unique identifier for this response */
-    requestId: string;
-    /**
-     * Constructs a new redirect response.
-     *
-     * @param {string} url - The URL to redirect to.
-     * @param {number} [statusCode=302] - HTTP status code for the redirect.
-     */
-    constructor(url: string, statusCode?: number);
-}
-/**
- * Creates a standard success response.
- *
- * @typeParam T - The shape of the data returned in the response.
- * @param {T} data - The data to include in the response.
- * @param {string} [message="Success"] - Optional custom message.
- * @returns {SuccessResponse<T>} A properly formatted success response.
- */
-export declare function createSuccessResponse<T>(data: T, message?: string): SuccessResponse<T>;
-/**
- * Creates a standard error response.
- *
- * @param {string} message - The error message.
- * @param {number} [statusCode=500] - HTTP status code for the error.
- * @returns {ErrorResponse} A properly formatted error response.
- */
-export declare function createErrorResponse(message: string, statusCode?: number): ErrorResponse;
-/**
- * Creates a final error response with request information.
- *
- * @param req - The original request object.
- * @param status - The HTTP status code.
- * @param message - The error message.
- * @param error - The original error object (optional).
- * @param options - Additional options for the response (optional).
- * @returns A properly formatted final error response.
- */
-export declare function createFinalErrorResponse(req: Request, status: number, message: string, error?: any, options?: {
-    includeDetails?: boolean;
-}): ApiErrorResponse;
-/**
- * Creates a paginated response from array data.
- *
- * @typeParam T - The shape of each item in the collection.
- * @param {T[]} allItems - The complete array of items to paginate.
- * @param {number} page - The requested page (1-based).
- * @param {number} pageSize - The number of items per page.
- * @param {string} [message="Success"] - Optional custom message.
- * @returns {PaginatedResponse<T>} A properly formatted paginated response.
- */
-export declare function createPaginatedResponse<T>(allItems: T[], page: number, pageSize: number, message?: string): PaginatedResponse<T>;
-/**
- * Adapter to convert API responses to Express.js response format.
- *
- * @param {any} res - Express response object.
- * @param {SuccessResponse<any> | ErrorResponse | RedirectResponse} apiResponse - API response instance.
- */
-export declare function sendResponse(res: any, apiResponse: SuccessResponse<any> | ErrorResponse | RedirectResponse): void;