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

package/context-store/context-store.utils.d.ts

@@ -1,212 +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 { AsyncLocalStorage } from 'async_hooks';
-/**
- * Type representing the store object used in AsyncLocalStorage.
- * Keys must be unique symbols to ensure isolation and prevent collisions.
- */
-export interface Store {
-    [key: symbol]: unknown;
-}
-/**
- * Predefined symbols used as keys in AsyncLocalStorage.
- * Add new symbols here to avoid duplication.
- */
-export declare const StoreKeys: {
-    LOGGER: symbol;
-    REQUEST_ID: symbol;
-    USER: symbol;
-    SESSION: symbol;
-    TRANSACTION_ID: symbol;
-    USER_ID: symbol;
-    TENANT_ID: symbol;
-    TRACE_ID: symbol;
-    CORRELATION_ID: symbol;
-};
-/**
- * Retrieves the current request ID from the async context, if available.
- *
- * @returns {string | undefined} The request ID string or undefined if not present in the current context.
- */
-export declare function getRequestId(): string | undefined;
-/**
- * Type-safe getter for common context values.
- *
- * @param key The store key symbol
- * @returns The typed value from the store
- */
-export declare function getFromContext<T>(key: symbol): T | undefined;
-/**
- * ContextStore manages per-request scoped context using AsyncLocalStorage.
- * It allows storing and retrieving data across async calls (e.g., request ID, logger).
- *
- * Example (Express middleware):
- * ```
- * // Middleware to initialize context and logger
- * app.use((req, res, next) => {
- *   const requestId = req.headers["x-request-id"]?.toString() || crypto.randomUUID();
- *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
- *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ requestId }));
- *     next();
- *   });
- * });
- * ```
- */
-export declare class ContextStore {
-    /**
-     * The underlying AsyncLocalStorage instance for context.
-     * @private
-     */
-    private static readonly storage;
-    /**
-     * Returns the raw AsyncLocalStorage instance for advanced access.
-     *
-     * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.
-     */
-    static getInstance(): AsyncLocalStorage<Store>;
-    /**
-     * Retrieves a value from the async context store by symbol key.
-     *
-     * @typeParam T - The expected return type of the value.
-     * @param {symbol} key - Unique symbol used as the store key.
-     * @returns {T | undefined} The value found (typed) or undefined if not present.
-     */
-    static get<T>(key: symbol): T | undefined;
-    /**
-     * Sets a value in the current context store by symbol key.
-     *
-     * @typeParam T - The value type to set.
-     * @param {symbol} key - Unique symbol key.
-     * @param {T} value - Value to set in context.
-     * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).
-     */
-    static set<T>(key: symbol, value: T): void;
-    /**
-     * Retrieves the entire context store object for the current async context.
-     *
-     * @returns {Store | undefined} The current store object or undefined if called outside a context.
-     */
-    static getAll(): Store | undefined;
-    /**
-     * Initializes a new async context and executes a callback within it.
-     * This must be called at the beginning of a request or logical async flow.
-     *
-     * @typeParam T - The callback's return type.
-     * @param {Store} store - The initial key-value store object.
-     * @param {() => T} callback - The function to run within the new context.
-     * @returns {T} The result of the callback function.
-     */
-    static run<T>(store: Store, callback: () => T): T;
-    /**
-     * Checks if a key exists in the current context store.
-     *
-     * @param {symbol} key - The symbol key to check.
-     * @returns {boolean} True if the key exists, false otherwise.
-     */
-    static has(key: symbol): boolean;
-    /**
-     * Removes a value from the current context store by symbol key.
-     *
-     * @param {symbol} key - The symbol key to delete.
-     * @returns {boolean} True if the key was deleted, false if the key wasn't found or no active context.
-     * @throws {Error} If called outside an active context.
-     */
-    static delete(key: symbol): boolean;
-    /**
-     * Updates multiple values in the current context store at once.
-     *
-     * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.
-     * @throws {Error} If called outside an active context.
-     */
-    static patch(values: Partial<Record<symbol, unknown>>): void;
-    /**
-     * Executes a callback with a temporary store value that only exists during execution.
-     * Original store is restored after callback completes.
-     *
-     * @typeParam T - The callback's return type.
-     * @param {symbol} key - The symbol key to temporarily set.
-     * @param {unknown} value - The temporary value.
-     * @param {() => T} callback - The function to execute with the temporary value.
-     * @returns {T} The result of the callback function.
-     * @throws {Error} If called outside an active context.
-     */
-    static withValue<T>(key: symbol, value: unknown, callback: () => T): T;
-    /**
-     * Creates a new context that inherits values from the current context.
-     *
-     * @typeParam T - The callback's return type.
-     * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.
-     * @param {() => T} callback - The function to execute in the new context.
-     * @returns {T} The result of the callback function.
-     */
-    static extend<T>(newValues: Partial<Record<symbol, unknown>>, callback: () => T): T;
-    /**
-     * Creates Express middleware that initializes a context for each request.
-     *
-     * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.
-     * @returns Express middleware function.
-     */
-    static createExpressMiddleware(initialValuesFactory?: (req: any) => Partial<Record<symbol, unknown>>): (req: any, _res: any, next: any) => void;
-}
-/**
- * Type-safe wrapper for accessing and modifying context values with specific types.
- *
- * @typeParam T - The value type.
- */
-export declare class TypedContextKey<T> {
-    private symbol;
-    private defaultValue?;
-    /**
-     * Creates a new typed context key.
-     *
-     * @param symbol - The unique symbol for this key
-     * @param defaultValue - Optional default value if key is not found
-     */
-    constructor(symbol: symbol, defaultValue?: T | undefined);
-    /**
-     * Gets the current value for this key.
-     *
-     * @returns The value or defaultValue if not found
-     */
-    get(): T | undefined;
-    /**
-     * Sets the value for this key.
-     *
-     * @param value The value to set
-     */
-    set(value: T): void;
-    /**
-     * Checks if this key exists in the context.
-     *
-     * @returns True if the key exists
-     */
-    exists(): boolean;
-    /**
-     * Deletes this key from the context.
-     *
-     * @returns True if the key was deleted
-     */
-    delete(): boolean;
-}

package/crypto/crypto.utils.d.ts

@@ -1,183 +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 { BinaryToTextEncoding, CipherGCMTypes } from 'crypto';
-export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'utf-16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
-/**
- * Generates an HMAC digest using the specified algorithm and secret key.
- *
- * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'sha1').
- * @param {string} input - The string to hash.
- * @param {string} secret - The secret key for HMAC.
- * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
- * @returns {string} HMAC digest as a string.
- */
-export declare function hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string;
-/**
- * Generates a hash digest using the specified algorithm.
- *
- * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'md5').
- * @param {string} input - The string to hash.
- * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
- * @returns {string} Hash digest as a string.
- */
-export declare function hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string;
-/**
- * Generates an HMAC-SHA256 digest.
- *
- * @param {string} input - The string to hash.
- * @param {string} secret - The secret key.
- * @returns {string} SHA-256 HMAC digest as a string.
- */
-export declare function sha256Hmac(input: string, secret: string): string;
-/**
- * Generates a SHA1 hash digest.
- *
- * @param {string} input - The string to hash.
- * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
- * @returns {string} SHA-1 hash as a string.
- */
-export declare function sha1(input: string, encoding?: BinaryToTextEncoding): string;
-/**
- * Generates a SHA256 hash digest.
- *
- * @param {string} input - The string to hash.
- * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
- * @returns {string} SHA-256 hash as a string.
- */
-export declare function sha256(input: string, encoding?: BinaryToTextEncoding): string;
-/**
- * Generates an MD5 hash digest.
- *
- * @param {string} input - The string to hash.
- * @returns {string} MD5 hash as a string.
- */
-export declare function md5(input: string): string;
-/**
- * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
- *
- * @returns {string} Random string hashed with SHA-256 (hex encoding).
- */
-export declare function randomString(): string;
-/**
- * Generates a secure random buffer of specified byte length.
- *
- * @param {number} [byteLength=32] - Number of random bytes to generate.
- * @returns {Buffer} Buffer containing random bytes.
- */
-export declare function generateRandomBytes(byteLength?: number): Buffer;
-/**
- * Generates a secure random string of specified byte length with specified encoding.
- *
- * @param {number} [byteLength=32] - Number of random bytes to generate.
- * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
- * @returns {string} Random string in specified encoding.
- */
-export declare function generateRandomBytesAsString(byteLength?: number, encoding?: BinaryToTextEncoding): string;
-/**
- * Generates a secure API key with a specified format.
- *
- * @param {string} [prefix=''] - Optional prefix for the key.
- * @param {number} [byteLength=24] - Number of random bytes to generate.
- * @returns {string} Formatted API key.
- */
-export declare function generateApiKey(prefix?: string, byteLength?: number): string;
-/**
- * Compares two strings, arrays, or buffers in constant time to prevent timing attacks.
- *
- * @param {string | Buffer | Uint8Array} a - First value to compare
- * @param {string | Buffer | Uint8Array} b - Second value to compare
- * @returns {boolean} True if values are equal
- */
-export declare function safeCompare(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
-/**
- * Interface for encryption options
- */
-export interface EncryptionOptions {
-    /** Algorithm to use (default: aes-256-gcm) */
-    algorithm?: CipherGCMTypes;
-    /** Input encoding for plaintext if string (default: utf8) */
-    inputEncoding?: BufferEncoding;
-    /** Output encoding for ciphertext (default: hex) */
-    outputEncoding?: BinaryToTextEncoding;
-}
-/**
- * Interface for decryption options
- */
-export interface DecryptionOptions {
-    /** Algorithm to use (default: aes-256-gcm) */
-    algorithm?: CipherGCMTypes;
-    /** Input encoding for ciphertext if string (default: hex) */
-    inputEncoding?: BinaryToTextEncoding;
-    /** Output encoding for plaintext (default: utf8) */
-    outputEncoding?: BufferEncoding;
-}
-/**
- * Result of encryption operation including all data needed for decryption
- */
-export interface EncryptionResult {
-    /** Encrypted data (string or Buffer based on options) */
-    ciphertext: string | Buffer;
-    /** Initialization vector */
-    iv: Buffer;
-    /** Authentication tag (for GCM mode) */
-    authTag?: Buffer;
-    /** Algorithm used */
-    algorithm: string;
-}
-/**
- * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
- *
- * @param {string | Buffer} data - Data to encrypt
- * @param {string | Buffer} key - Encryption key or passphrase
- * @param {EncryptionOptions} [options] - Encryption options
- * @returns {Promise<EncryptionResult>} Encrypted data with metadata
- */
-export declare function encrypt(data: string | Buffer, key: string | Buffer, options?: EncryptionOptions): Promise<EncryptionResult>;
-/**
- * Decrypts data that was encrypted with the encrypt function.
- *
- * @param {EncryptionResult} encryptedData - The encrypted data and metadata
- * @param {string | Buffer} key - Decryption key or passphrase
- * @param {DecryptionOptions} [options] - Decryption options
- * @returns {Promise<string | Buffer>} Decrypted data
- */
-export declare function decrypt(encryptedData: EncryptionResult, key: string | Buffer, options?: DecryptionOptions): Promise<string | Buffer>;
-/**
- * Creates a signed token with an expiration time and payload.
- *
- * @param {object} payload - Data to include in the token
- * @param {string} secret - Secret key for signing
- * @param {number} [expiresInSeconds=3600] - Token expiration in seconds
- * @returns {string} Signed token string
- */
-export declare function createSignedToken(payload: Record<string, any>, secret: string, expiresInSeconds?: number): string;
-/**
- * Verifies and decodes a signed token.
- *
- * @param {string} token - The token to verify
- * @param {string} secret - Secret key for verification
- * @returns {object | null} Decoded payload if valid, null if invalid
- */
-export declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;

package/date/date.utils.d.ts

@@ -1,190 +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.
- */
-
-/**
- * Format options for the formatDate function
- */
-export interface DateFormatOptions {
-    /** Date format pattern (default: 'yyyy-MM-dd') */
-    format?: string;
-    /** Locale to use for formatting (default: system locale) */
-    locale?: string | string[];
-    /** Time zone to use (default: system time zone) */
-    timeZone?: string;
-}
-/**
- * Format a date according to the specified format pattern.
- *
- * @param date - Date to format
- * @param options - Formatting options
- * @returns Formatted date string
- *
- * @example
- * ```typescript
- * // Format as ISO date
- * formatDate(new Date(), { format: 'yyyy-MM-dd' }); // '2023-05-15'
- *
- * // Format with time
- * formatDate(new Date(), { format: 'yyyy-MM-dd HH:mm:ss' }); // '2023-05-15 14:30:22'
- *
- * // Format with locale
- * formatDate(new Date(), { format: 'PPPP', locale: 'fr-FR' }); // 'lundi 15 mai 2023'
- * ```
- */
-export declare function formatDate(date: Date | number, options?: DateFormatOptions): string;
-/**
- * Format a date as relative time (e.g., "5 minutes ago", "in 3 days").
- *
- * @param date - Date to format
- * @param now - Reference date (default: current time)
- * @param locale - Locale to use for formatting
- * @returns Formatted relative time string
- */
-export declare function formatRelativeTime(date: Date | number, now?: Date | number, locale?: string | string[]): string;
-/**
- * Parse a date string or timestamp into a Date object.
- *
- * @param input - Date string or timestamp to parse
- * @param fallback - Fallback date if parsing fails
- * @returns Parsed Date object or fallback
- *
- * @example
- * ```typescript
- * parseDate('2023-05-15'); // Date object for May 15, 2023
- * parseDate('invalid', new Date()); // Returns current date as fallback
- * ```
- */
-export declare function parseDate(input: string | number, fallback?: Date): Date | null;
-/**
- * Calculate the difference between two dates in the specified unit.
- *
- * @param date1 - First date
- * @param date2 - Second date (default: current time)
- * @param unit - Unit of time for the difference
- * @returns Difference in the specified unit
- *
- * @example
- * ```typescript
- * // Get difference in days
- * dateDiff(new Date('2023-05-15'), new Date('2023-05-10'), 'days'); // 5
- *
- * // Get difference in hours
- * dateDiff(new Date('2023-05-15T10:00:00'), new Date('2023-05-15T06:00:00'), 'hours'); // 4
- * ```
- */
-export declare function dateDiff(date1: Date | number, date2?: Date | number, unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
-/**
- * Add a specified amount of time to a date.
- *
- * @param date - Base date
- * @param amount - Amount to add (can be negative)
- * @param unit - Unit of time to add
- * @returns New date with the addition
- *
- * @example
- * ```typescript
- * // Add 5 days
- * addToDate(new Date('2023-05-15'), 5, 'days'); // Date for May 20, 2023
- *
- * // Subtract 2 hours
- * addToDate(new Date('2023-05-15T10:00:00'), -2, 'hours'); // Date for May 15, 2023 08:00:00
- * ```
- */
-export declare function addToDate(date: Date | number, amount: number, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): Date;
-/**
- * Get the start of a time period containing the specified date.
- *
- * @param date - Date to get the start from
- * @param unit - Time unit
- * @returns Date object representing the start of the time unit
- *
- * @example
- * ```typescript
- * // Get start of day (midnight)
- * startOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 00:00:00
- *
- * // Get start of month
- * startOf(new Date('2023-05-15'), 'month'); // Date for May 1, 2023
- * ```
- */
-export declare function startOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
-/**
- * Get the end of a time period containing the specified date.
- *
- * @param date - Date to get the end from
- * @param unit - Time unit
- * @returns Date object representing the end of the time unit
- *
- * @example
- * ```typescript
- * // Get end of day (23:59:59.999)
- * endOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 23:59:59.999
- *
- * // Get end of month
- * endOf(new Date('2023-05-15'), 'month'); // Date for May 31, 2023 23:59:59.999
- * ```
- */
-export declare function endOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
-/**
- * Check if a date is between two other dates.
- *
- * @param date - Date to check
- * @param start - Start date of the range
- * @param end - End date of the range
- * @param inclusive - Whether the comparison should be inclusive of start/end
- * @returns True if the date is within the range
- *
- * @example
- * ```typescript
- * const date = new Date('2023-05-15');
- * const start = new Date('2023-05-10');
- * const end = new Date('2023-05-20');
- *
- * isBetween(date, start, end); // true
- * ```
- */
-export declare function isBetween(date: Date | number, start: Date | number, end: Date | number, inclusive?: boolean): boolean;
-/**
- * Check if a year is a leap year.
- *
- * @param year - Year to check (or date object)
- * @returns True if the year is a leap year
- */
-export declare function isLeapYear(year: number | Date): boolean;
-/**
- * Get the number of days in a month.
- *
- * @param year - Year
- * @param month - Month (0-11)
- * @returns Number of days in the month
- */
-export declare function daysInMonth(year: number | Date, month?: number): number;
-/**
- * Format a duration given in milliseconds to a human readable string.
- * Examples: 3661000 -> "1h 1m 1s", 90061 -> "1m 30s 61ms"
- *
- * @param {number} ms - Duration in milliseconds
- * @returns {string} Human readable duration
- */
-export declare function formatDuration(ms: number): string;