@naman_deep_singh/utils 2.3.0 → 2.6.0

package/dist/types/utils/compression.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Compression utilities for data compression/decompression
+ * @packageDocumentation
+ */
+/**
+ * Supported compression algorithms
+ */
+export declare enum CompressionAlgorithm {
+    /** GZIP compression */
+    GZIP = "gzip",
+    /** Deflate compression */
+    DEFLATE = "deflate",
+    /** Brotli compression (Node.js 10.16.0+) */
+    BROTLI = "brotli"
+}
+/**
+ * Compression options
+ */
+export interface CompressionOptions {
+    /** Compression algorithm to use */
+    algorithm?: CompressionAlgorithm;
+    /** Compression level (1-9, higher = better compression but slower) */
+    level?: number;
+    /** Encoding for string data */
+    encoding?: BufferEncoding;
+}
+/**
+ * Compression result with metrics
+ */
+export interface CompressionResult {
+    /** Compressed data */
+    data: Buffer | string;
+    /** Original size in bytes */
+    originalSize: number;
+    /** Compressed size in bytes */
+    compressedSize: number;
+    /** Compression ratio (0-1) */
+    compressionRatio: number;
+    /** Time taken in milliseconds */
+    timeTakenMs: number;
+    /** Algorithm used */
+    algorithm: CompressionAlgorithm;
+}
+/**
+ * Main compression utility class
+ */
+export declare class Compression {
+    /**
+     * Default compression options
+     */
+    private static readonly DEFAULT_OPTIONS;
+    /**
+     * Check if compression algorithm is supported
+     */
+    static isAlgorithmSupported(algorithm: CompressionAlgorithm): boolean;
+    /**
+     * Get supported algorithms for current environment
+     */
+    static getSupportedAlgorithms(): CompressionAlgorithm[];
+    /**
+     * Compress data
+     * @param input Data to compress (string or Buffer)
+     * @param options Compression options
+     * @returns Compressed data as Buffer
+     */
+    static compress(input: string | Buffer, options?: CompressionOptions): Promise<Buffer>;
+    /**
+     * Decompress data
+     * @param input Compressed data (Buffer or base64 string)
+     * @param options Compression options
+     * @returns Decompressed data as Buffer
+     */
+    static decompress(input: string | Buffer, options?: CompressionOptions): Promise<Buffer>;
+    /**
+     * Compress data with detailed metrics
+     * @param input Data to compress
+     * @param options Compression options
+     * @returns Compression result with metrics
+     */
+    static compressWithMetrics(input: string | Buffer, options?: CompressionOptions): Promise<CompressionResult>;
+    /**
+     * Compress buffer data using specified algorithm
+     */
+    private static compressBuffer;
+    /**
+     * Decompress buffer data using specified algorithm
+     */
+    private static decompressBuffer;
+    /**
+     * GZIP compression
+     */
+    private static compressGzip;
+    /**
+     * GZIP decompression
+     */
+    private static decompressGzip;
+    /**
+     * Deflate compression
+     */
+    private static compressDeflate;
+    /**
+     * Deflate decompression
+     */
+    private static decompressDeflate;
+    /**
+     * Brotli compression (Node.js 10.16.0+)
+     */
+    private static compressBrotli;
+    /**
+     * Brotli decompression (Node.js 10.16.0+)
+     */
+    private static decompressBrotli;
+    /**
+     * Create compression stream
+     * @param algorithm Compression algorithm
+     * @param options Compression options
+     * @returns Compression stream
+     */
+    static createCompressionStream(algorithm?: CompressionAlgorithm, options?: Omit<CompressionOptions, 'algorithm'>): NodeJS.ReadWriteStream;
+    /**
+     * Create decompression stream
+     * @param algorithm Compression algorithm
+     * @returns Decompression stream
+     */
+    static createDecompressionStream(algorithm?: CompressionAlgorithm): NodeJS.ReadWriteStream;
+    /**
+     * Stream compression
+     * @param readable Readable stream
+     * @param writable Writable stream
+     * @param options Compression options
+     */
+    static compressStream(readable: NodeJS.ReadableStream, writable: NodeJS.WritableStream, options?: CompressionOptions): Promise<void>;
+    /**
+     * Stream decompression
+     * @param readable Readable stream
+     * @param writable Writable stream
+     * @param options Compression options
+     */
+    static decompressStream(readable: NodeJS.ReadableStream, writable: NodeJS.WritableStream, options?: CompressionOptions): Promise<void>;
+    /**
+     * Validate input data
+     */
+    private static validateInput;
+    /**
+     * Validate compression options
+     */
+    private static validateOptions;
+    /**
+     * Wrap errors with CompressionError
+     */
+    private static wrapError;
+}
+/**
+ * Convenience function for compression
+ */
+export declare function compress(input: string | Buffer, options?: CompressionOptions): Promise<Buffer>;
+/**
+ * Convenience function for decompression
+ */
+export declare function decompress(input: string | Buffer, options?: CompressionOptions): Promise<Buffer>;
+/**
+ * Convenience function for compression with metrics
+ */
+export declare function compressWithMetrics(input: string | Buffer, options?: CompressionOptions): Promise<CompressionResult>;

package/dist/types/utils/config.d.ts

@@ -1,4 +1,4 @@
-import { type PerformanceConfig } from '../core/index.js';
+import type { PerformanceConfig } from '../core/performance.js';
 export declare function validateConfig(config: Partial<PerformanceConfig>, defaultConfig: PerformanceConfig): PerformanceConfig;
 export declare function validatePerformanceSettings(settings: Partial<PerformanceConfig>): PerformanceConfig;
 export declare function mergeConfigs<T extends Record<string, any>>(base: T, override: Partial<T>): T;

package/dist/types/utils/index.d.ts

@@ -1,3 +1,11 @@
-export * from './config.js';
-export * from './helpers.js';
-export * from './defineExtension.js';
+/**
+ * Utils package exports
+ * @packageDocumentation
+ */
+export { validateConfig, validatePerformanceSettings, mergeConfigs, } from './config.js';
+export { isValidArrayIndex, ensurePositiveInteger, safeClone, getPathSegments, hasOwnProperty, } from './helpers.js';
+export { defineExtension } from './defineExtension.js';
+export { TimeoutManager, withTimeout, } from './timeout.js';
+export { GenericPool, PoolManager, } from './pool.js';
+export type { PoolConfig, Connection, } from './pool.js';
+export { Compression, compress, decompress, compressWithMetrics, CompressionAlgorithm, type CompressionResult, type CompressionOptions, } from './compression.js';

package/dist/types/utils/pool.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Generic connection pooling utilities
+ * @packageDocumentation
+ */
+/**
+ * Connection resource interface
+ */
+export interface Connection {
+    /** Unique connection ID */
+    id: string;
+    /** Connection metadata */
+    metadata?: Record<string, unknown>;
+    /** Check if connection is healthy */
+    isHealthy(): boolean;
+    /** Close/cleanup the connection */
+    close(): Promise<void>;
+}
+/**
+ * Pool configuration options
+ */
+export interface PoolConfig<T extends Connection> {
+    /** Pool name for identification */
+    name?: string;
+    /** Minimum number of connections in pool */
+    minConnections?: number;
+    /** Maximum number of connections in pool */
+    maxConnections?: number;
+    /** Timeout for acquiring connection (ms) */
+    acquireTimeoutMs?: number;
+    /** Timeout for releasing connection (ms) */
+    releaseTimeoutMs?: number;
+    /** Maximum connection idle time before cleanup (ms) */
+    idleTimeoutMs?: number;
+    /** Maximum connection lifetime (ms) */
+    maxLifetimeMs?: number;
+    /** Health check interval (ms) */
+    healthCheckIntervalMs?: number;
+    /** Function to create new connection */
+    createConnection: () => Promise<T>;
+    /** Function to validate connection health */
+    validateConnection?: (connection: T) => boolean;
+    /** Function to destroy connection */
+    destroyConnection?: (connection: T) => Promise<void>;
+}
+/**
+ * Generic connection pool manager
+ */
+export declare class GenericPool<T extends Connection> {
+    private readonly config;
+    private readonly connections;
+    private readonly pendingAcquires;
+    private isShuttingDown;
+    private healthCheckInterval?;
+    private stats;
+    constructor(config: PoolConfig<T>);
+    /**
+     * Validate pool configuration
+     */
+    private validateConfig;
+    /**
+     * Start periodic health checks
+     */
+    private startHealthChecks;
+    /**
+     * Stop health checks
+     */
+    private stopHealthChecks;
+    /**
+     * Acquire a connection from the pool
+     * @returns Promise resolving to connection
+     */
+    acquire(): Promise<T>;
+    /**
+     * Release a connection back to the pool
+     * @param connection Connection to release
+     */
+    release(connection: T): Promise<void>;
+    /**
+     * Try to fulfill pending acquire requests
+     */
+    private tryFulfillPendingAcquires;
+    /**
+     * Create and register a new connection
+     */
+    private createAndRegisterConnection;
+    /**
+     * Destroy a connection
+     */
+    private destroyConnection;
+    /**
+     * Clean up idle connections
+     */
+    private cleanupIdleConnections;
+    /**
+     * Clean up expired connections
+     */
+    private cleanupExpiredConnections;
+    /**
+     * Maintain minimum connections
+     */
+    private maintainMinConnections;
+    /**
+     * Get pool statistics
+     */
+    getStats(): {
+        totalConnections: number;
+        acquiredConnections: number;
+        availableConnections: number;
+        pendingAcquires: number;
+        isShuttingDown: boolean;
+        config: {
+            name: string;
+            minConnections: number;
+            maxConnections: number;
+        };
+        totalConnectionsCreated: number;
+        totalConnectionsDestroyed: number;
+        totalAcquireRequests: number;
+        totalAcquireTimeouts: number;
+        totalAcquireErrors: number;
+        totalReleaseRequests: number;
+    };
+    /**
+     * Get number of available connections
+     */
+    getAvailableCount(): number;
+    /**
+     * Drain the pool (graceful shutdown)
+     */
+    drain(): Promise<void>;
+    /**
+     * Execute a function with a connection from the pool
+     */
+    withConnection<R>(fn: (connection: T) => Promise<R>): Promise<R>;
+}
+/**
+ * Pool manager for multiple pools
+ */
+export declare class PoolManager {
+    private pools;
+    /**
+     * Create or get a pool
+     */
+    createPool<T extends Connection>(config: PoolConfig<T>): GenericPool<T>;
+    /**
+     * Get a pool by name
+     */
+    getPool<T extends Connection>(name: string): GenericPool<T> | undefined;
+    /**
+     * Drain all pools
+     */
+    drainAll(): Promise<void>;
+    /**
+     * Get statistics for all pools
+     */
+    getAllStats(): Record<string, ReturnType<GenericPool<any>['getStats']>>;
+}

package/dist/types/utils/timeout.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Timeout utilities for async operations
+ * @packageDocumentation
+ */
+/**
+ * Timeout manager for async operations
+ */
+export declare class TimeoutManager {
+    /**
+     * Execute a promise with a timeout
+     * @param promise Promise to execute
+     * @param timeoutMs Timeout duration in milliseconds
+     * @param errorMessage Optional custom error message
+     * @returns Promise result or throws TimeoutError
+     * @throws {TimeoutError} If operation times out
+     * @throws Any error thrown by the original promise
+     */
+    static withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage?: string): Promise<T>;
+    /**
+     * Create an AbortSignal that aborts after specified timeout
+     * @param timeoutMs Timeout duration in milliseconds
+     * @returns AbortSignal that aborts after timeout
+     */
+    static createTimeoutSignal(timeoutMs: number): AbortSignal;
+    /**
+     * Create a promise that resolves after specified delay
+     * @param delayMs Delay in milliseconds
+     * @returns Promise that resolves after delay
+     */
+    static delay(delayMs: number): Promise<void>;
+    /**
+     * Create a promise that rejects after specified timeout
+     * @param timeoutMs Timeout in milliseconds
+     * @param errorMessage Optional error message
+     * @returns Promise that rejects with TimeoutError after timeout
+     */
+    static timeoutPromise<T = never>(timeoutMs: number, errorMessage?: string): Promise<T>;
+    /**
+     * Race multiple promises with individual timeouts
+     * @param promises Array of promises to race
+     * @param timeoutMs Timeout for each promise
+     * @returns First promise to resolve, or rejects if all timeout
+     */
+    static raceWithTimeout<T>(promises: Promise<T>[], timeoutMs: number): Promise<T>;
+    /**
+     * Execute function with retry and timeout for each attempt
+     * @param fn Function to execute
+     * @param options Retry and timeout options
+     * @returns Function result
+     */
+    static retryWithTimeout<T>(fn: () => Promise<T>, options?: {
+        maxAttempts?: number;
+        timeoutPerAttempt?: number;
+        delayBetweenAttempts?: number;
+        backoffMultiplier?: number;
+    }): Promise<T>;
+}
+/**
+ * Create a timeout wrapper for async functions
+ * @param timeoutMs Timeout in milliseconds
+ * @param errorMessage Optional error message
+ * @returns Function wrapper that adds timeout
+ */
+export declare function withTimeout<TArgs extends any[], TReturn>(timeoutMs: number, errorMessage?: string): (target: (...args: TArgs) => Promise<TReturn>, _context?: ClassMethodDecoratorContext) => (this: any, ...args: TArgs) => Promise<TReturn>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naman_deep_singh/utils",
-  "version": "2.3.0",
+  "version": "2.6.0",
   "description": "Universal JavaScript prototype extensions for common development utilities",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -81,6 +81,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@naman_deep_singh/errors": "^2.3.0",
     "@types/node": "^25.0.1"
   },
   "publishConfig": {