@naman_deep_singh/utils 2.3.0 → 2.6.0

package/dist/esm/utils/pool.js

@@ -0,0 +1,370 @@
+/**
+ * Generic connection pooling utilities
+ * @packageDocumentation
+ */
+import { ConnectionError } from '../errors/ConnectionError.js';
+import { PoolError } from '../errors/PoolError.js';
+/**
+ * Pool connection wrapper with metadata
+ */
+class PooledConnection {
+    constructor(connection, poolName) {
+        this.connection = connection;
+        this.poolName = poolName;
+        this.id = `${poolName}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.createdAt = new Date();
+        this.lastUsedAt = new Date();
+        this.isAcquired = false;
+        this.useCount = 0;
+        this.isMarkedForDestruction = false;
+    }
+    /** Mark connection as used */
+    markUsed() {
+        this.lastUsedAt = new Date();
+        this.useCount++;
+    }
+    /** Check if connection is idle beyond timeout */
+    isIdle(idleTimeoutMs) {
+        const idleTime = Date.now() - this.lastUsedAt.getTime();
+        return idleTime > idleTimeoutMs;
+    }
+    /** Check if connection has exceeded max lifetime */
+    hasExceededLifetime(maxLifetimeMs) {
+        const lifetime = Date.now() - this.createdAt.getTime();
+        return lifetime > maxLifetimeMs;
+    }
+}
+/**
+ * Generic connection pool manager
+ */
+export class GenericPool {
+    constructor(config) {
+        this.connections = new Map();
+        this.pendingAcquires = [];
+        this.isShuttingDown = false;
+        this.stats = {
+            totalConnectionsCreated: 0,
+            totalConnectionsDestroyed: 0,
+            totalAcquireRequests: 0,
+            totalAcquireTimeouts: 0,
+            totalAcquireErrors: 0,
+            totalReleaseRequests: 0,
+        };
+        this.config = {
+            name: config.name || 'default',
+            minConnections: config.minConnections ?? 1,
+            maxConnections: config.maxConnections ?? 10,
+            acquireTimeoutMs: config.acquireTimeoutMs ?? 30000,
+            releaseTimeoutMs: config.releaseTimeoutMs ?? 5000,
+            idleTimeoutMs: config.idleTimeoutMs ?? 60000,
+            maxLifetimeMs: config.maxLifetimeMs ?? 3600000,
+            healthCheckIntervalMs: config.healthCheckIntervalMs ?? 30000,
+            createConnection: config.createConnection,
+            validateConnection: config.validateConnection ?? ((conn) => conn.isHealthy()),
+            destroyConnection: config.destroyConnection ?? ((conn) => conn.close()),
+        };
+        this.validateConfig();
+        this.startHealthChecks();
+    }
+    /**
+     * Validate pool configuration
+     */
+    validateConfig() {
+        if (this.config.minConnections < 0) {
+            throw new RangeError('minConnections must be non-negative');
+        }
+        if (this.config.maxConnections <= 0) {
+            throw new RangeError('maxConnections must be positive');
+        }
+        if (this.config.minConnections > this.config.maxConnections) {
+            throw new RangeError('minConnections cannot exceed maxConnections');
+        }
+        if (this.config.acquireTimeoutMs <= 0) {
+            throw new RangeError('acquireTimeoutMs must be positive');
+        }
+        if (this.config.idleTimeoutMs < 0) {
+            throw new RangeError('idleTimeoutMs must be non-negative');
+        }
+        if (this.config.maxLifetimeMs < 0) {
+            throw new RangeError('maxLifetimeMs must be non-negative');
+        }
+    }
+    /**
+     * Start periodic health checks
+     */
+    startHealthChecks() {
+        if (this.config.healthCheckIntervalMs > 0) {
+            this.healthCheckInterval = setInterval(() => {
+                this.cleanupIdleConnections();
+                this.cleanupExpiredConnections();
+                this.maintainMinConnections();
+            }, this.config.healthCheckIntervalMs);
+        }
+    }
+    /**
+     * Stop health checks
+     */
+    stopHealthChecks() {
+        if (this.healthCheckInterval) {
+            clearInterval(this.healthCheckInterval);
+        }
+    }
+    /**
+     * Acquire a connection from the pool
+     * @returns Promise resolving to connection
+     */
+    async acquire() {
+        if (this.isShuttingDown) {
+            throw new PoolError('Cannot acquire connection: pool is shutting down', this.config.name);
+        }
+        this.stats.totalAcquireRequests++;
+        // Try to get available connection
+        for (const pooledConn of this.connections.values()) {
+            if (!pooledConn.isAcquired &&
+                this.config.validateConnection(pooledConn.connection)) {
+                pooledConn.isAcquired = true;
+                pooledConn.markUsed();
+                return pooledConn.connection;
+            }
+        }
+        // Create new connection if under max
+        if (this.connections.size < this.config.maxConnections) {
+            try {
+                const connection = await this.createAndRegisterConnection();
+                connection.isAcquired = true;
+                connection.markUsed();
+                return connection.connection;
+            }
+            catch (error) {
+                this.stats.totalAcquireErrors++;
+                throw new ConnectionError('Failed to create connection', undefined, { poolName: this.config.name }, error instanceof Error ? error : undefined);
+            }
+        }
+        // Wait for connection to be released
+        return new Promise((resolve, reject) => {
+            const request = {
+                resolve,
+                reject,
+                timestamp: Date.now(),
+            };
+            this.pendingAcquires.push(request);
+            // Set timeout for acquire request
+            setTimeout(() => {
+                const index = this.pendingAcquires.indexOf(request);
+                if (index !== -1) {
+                    this.pendingAcquires.splice(index, 1);
+                    this.stats.totalAcquireTimeouts++;
+                    reject(new PoolError(`Acquire timeout after ${this.config.acquireTimeoutMs}ms`, this.config.name, { pendingRequests: this.pendingAcquires.length }));
+                }
+            }, this.config.acquireTimeoutMs);
+        });
+    }
+    /**
+     * Release a connection back to the pool
+     * @param connection Connection to release
+     */
+    async release(connection) {
+        this.stats.totalReleaseRequests++;
+        const pooledConn = Array.from(this.connections.values()).find((pc) => pc.connection === connection);
+        if (!pooledConn) {
+            throw new PoolError('Connection not found in pool', this.config.name, {
+                connectionId: connection.id,
+            });
+        }
+        if (!pooledConn.isAcquired) {
+            throw new PoolError('Connection is not acquired', this.config.name, {
+                connectionId: connection.id,
+            });
+        }
+        // Validate connection before returning to pool
+        if (!this.config.validateConnection(connection)) {
+            await this.destroyConnection(pooledConn);
+            this.tryFulfillPendingAcquires();
+            return;
+        }
+        pooledConn.isAcquired = false;
+        pooledConn.markUsed();
+        // Fulfill pending acquire requests
+        this.tryFulfillPendingAcquires();
+    }
+    /**
+     * Try to fulfill pending acquire requests
+     */
+    tryFulfillPendingAcquires() {
+        while (this.pendingAcquires.length > 0) {
+            const availableConn = Array.from(this.connections.values()).find((pc) => !pc.isAcquired && this.config.validateConnection(pc.connection));
+            if (!availableConn) {
+                break;
+            }
+            const request = this.pendingAcquires.shift();
+            if (request) {
+                availableConn.isAcquired = true;
+                availableConn.markUsed();
+                request.resolve(availableConn.connection);
+            }
+        }
+    }
+    /**
+     * Create and register a new connection
+     */
+    async createAndRegisterConnection() {
+        const connection = await this.config.createConnection();
+        const pooledConn = new PooledConnection(connection, this.config.name);
+        this.connections.set(pooledConn.id, pooledConn);
+        this.stats.totalConnectionsCreated++;
+        return pooledConn;
+    }
+    /**
+     * Destroy a connection
+     */
+    async destroyConnection(pooledConn) {
+        try {
+            await this.config.destroyConnection(pooledConn.connection);
+            this.connections.delete(pooledConn.id);
+            this.stats.totalConnectionsDestroyed++;
+        }
+        catch (error) {
+            console.error(`Failed to destroy connection ${pooledConn.id}:`, error);
+        }
+    }
+    /**
+     * Clean up idle connections
+     */
+    cleanupIdleConnections() {
+        if (this.config.idleTimeoutMs <= 0)
+            return;
+        for (const pooledConn of this.connections.values()) {
+            if (!pooledConn.isAcquired &&
+                !pooledConn.isMarkedForDestruction &&
+                pooledConn.isIdle(this.config.idleTimeoutMs) &&
+                this.connections.size > this.config.minConnections) {
+                pooledConn.isMarkedForDestruction = true;
+                this.destroyConnection(pooledConn);
+            }
+        }
+    }
+    /**
+     * Clean up expired connections
+     */
+    cleanupExpiredConnections() {
+        if (this.config.maxLifetimeMs <= 0)
+            return;
+        for (const pooledConn of this.connections.values()) {
+            if (!pooledConn.isMarkedForDestruction &&
+                pooledConn.hasExceededLifetime(this.config.maxLifetimeMs)) {
+                pooledConn.isMarkedForDestruction = true;
+                this.destroyConnection(pooledConn);
+            }
+        }
+    }
+    /**
+     * Maintain minimum connections
+     */
+    async maintainMinConnections() {
+        const needed = this.config.minConnections - this.getAvailableCount();
+        for (let i = 0; i < needed && this.connections.size < this.config.maxConnections; i++) {
+            try {
+                await this.createAndRegisterConnection();
+            }
+            catch (error) {
+                console.error('Failed to maintain min connections:', error);
+                break;
+            }
+        }
+    }
+    /**
+     * Get pool statistics
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            totalConnections: this.connections.size,
+            acquiredConnections: Array.from(this.connections.values()).filter((c) => c.isAcquired).length,
+            availableConnections: this.getAvailableCount(),
+            pendingAcquires: this.pendingAcquires.length,
+            isShuttingDown: this.isShuttingDown,
+            config: {
+                name: this.config.name,
+                minConnections: this.config.minConnections,
+                maxConnections: this.config.maxConnections,
+            },
+        };
+    }
+    /**
+     * Get number of available connections
+     */
+    getAvailableCount() {
+        return Array.from(this.connections.values()).filter((pc) => !pc.isAcquired && this.config.validateConnection(pc.connection)).length;
+    }
+    /**
+     * Drain the pool (graceful shutdown)
+     */
+    async drain() {
+        this.isShuttingDown = true;
+        this.stopHealthChecks();
+        // Reject all pending acquire requests
+        for (const request of this.pendingAcquires) {
+            request.reject(new PoolError('Pool is draining', this.config.name));
+        }
+        this.pendingAcquires.length = 0;
+        // Close all connections
+        const destroyPromises = Array.from(this.connections.values()).map((pooledConn) => this.destroyConnection(pooledConn));
+        await Promise.allSettled(destroyPromises);
+    }
+    /**
+     * Execute a function with a connection from the pool
+     */
+    async withConnection(fn) {
+        const connection = await this.acquire();
+        try {
+            return await fn(connection);
+        }
+        finally {
+            await this.release(connection);
+        }
+    }
+}
+/**
+ * Pool manager for multiple pools
+ */
+export class PoolManager {
+    constructor() {
+        this.pools = new Map();
+    }
+    /**
+     * Create or get a pool
+     */
+    createPool(config) {
+        const name = config.name || 'default';
+        if (this.pools.has(name)) {
+            throw new PoolError(`Pool with name '${name}' already exists`, name);
+        }
+        const pool = new GenericPool(config);
+        this.pools.set(name, pool);
+        return pool;
+    }
+    /**
+     * Get a pool by name
+     */
+    getPool(name) {
+        return this.pools.get(name);
+    }
+    /**
+     * Drain all pools
+     */
+    async drainAll() {
+        const drainPromises = Array.from(this.pools.values()).map((pool) => pool.drain());
+        await Promise.all(drainPromises);
+        this.pools.clear();
+    }
+    /**
+     * Get statistics for all pools
+     */
+    getAllStats() {
+        const stats = {};
+        for (const [name, pool] of this.pools.entries()) {
+            stats[name] = pool.getStats();
+        }
+        return stats;
+    }
+}

package/dist/esm/utils/timeout.js

@@ -0,0 +1,128 @@
+/**
+ * Timeout utilities for async operations
+ * @packageDocumentation
+ */
+import { TimeoutError } from '../errors/TimeoutError.js';
+/**
+ * Timeout manager for async operations
+ */
+export 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 async withTimeout(promise, timeoutMs, errorMessage) {
+        if (timeoutMs <= 0) {
+            throw new RangeError(`Timeout must be positive, got ${timeoutMs}`);
+        }
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new TimeoutError(errorMessage || 'Operation timed out', timeoutMs));
+            }, timeoutMs);
+            promise
+                .then((result) => {
+                clearTimeout(timeoutId);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Create an AbortSignal that aborts after specified timeout
+     * @param timeoutMs Timeout duration in milliseconds
+     * @returns AbortSignal that aborts after timeout
+     */
+    static createTimeoutSignal(timeoutMs) {
+        if (timeoutMs <= 0) {
+            throw new RangeError(`Timeout must be positive, got ${timeoutMs}`);
+        }
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeoutMs);
+        return controller.signal;
+    }
+    /**
+     * Create a promise that resolves after specified delay
+     * @param delayMs Delay in milliseconds
+     * @returns Promise that resolves after delay
+     */
+    static delay(delayMs) {
+        if (delayMs < 0) {
+            throw new RangeError(`Delay must be non-negative, got ${delayMs}`);
+        }
+        return new Promise((resolve) => {
+            setTimeout(resolve, delayMs);
+        });
+    }
+    /**
+     * 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(timeoutMs, errorMessage) {
+        return new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new TimeoutError(errorMessage || 'Timeout reached', timeoutMs));
+            }, timeoutMs);
+        });
+    }
+    /**
+     * 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 async raceWithTimeout(promises, timeoutMs) {
+        const timeoutPromises = promises.map((promise) => this.withTimeout(promise, timeoutMs, 'Race participant timed out'));
+        return Promise.race(timeoutPromises);
+    }
+    /**
+     * Execute function with retry and timeout for each attempt
+     * @param fn Function to execute
+     * @param options Retry and timeout options
+     * @returns Function result
+     */
+    static async retryWithTimeout(fn, options = {}) {
+        const { maxAttempts = 3, timeoutPerAttempt = 5000, delayBetweenAttempts = 1000, backoffMultiplier = 2, } = options;
+        if (maxAttempts < 1) {
+            throw new RangeError(`maxAttempts must be at least 1, got ${maxAttempts}`);
+        }
+        let lastError;
+        let currentDelay = delayBetweenAttempts;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await this.withTimeout(fn(), timeoutPerAttempt, `Attempt ${attempt} timed out`);
+            }
+            catch (error) {
+                lastError = error;
+                // Don't delay after last attempt
+                if (attempt < maxAttempts) {
+                    await this.delay(currentDelay);
+                    currentDelay *= backoffMultiplier;
+                }
+            }
+        }
+        throw lastError || new Error('All retry attempts failed');
+    }
+}
+/**
+ * Create a timeout wrapper for async functions
+ * @param timeoutMs Timeout in milliseconds
+ * @param errorMessage Optional error message
+ * @returns Function wrapper that adds timeout
+ */
+export function withTimeout(timeoutMs, errorMessage) {
+    return (target, _context) => {
+        return function (...args) {
+            return TimeoutManager.withTimeout(target.apply(this, args), timeoutMs, errorMessage);
+        };
+    };
+}

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

@@ -1,2 +1,3 @@
-export * from './validation.js';
-export * from './performance.js';
+export { validateExtensionInput, validateArrayInput, validateNumberRange, validatePositiveInteger, } from './validation.js';
+export { type PerformanceConfig, setPerformanceConfig, getPerformanceConfig, LRUCache, makeInternalCacheKey, withCache, } from './performance.js';
+export { getPackageVersion } from './version.js';

package/dist/types/errors/CompressionError.d.ts

@@ -0,0 +1,8 @@
+import { AppError } from '@naman_deep_singh/errors';
+/**
+ * Compression error - when compression/decompression fails
+ */
+export declare class CompressionError extends AppError {
+    readonly algorithm?: string | undefined;
+    constructor(message: string, algorithm?: string | undefined, details?: unknown, cause?: Error);
+}

package/dist/types/errors/ConnectionError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Connection error - when connection fails
+ * @packageDocumentation
+ */
+import { AppError } from '@naman_deep_singh/errors';
+export declare class ConnectionError extends AppError {
+    readonly endpoint?: string | undefined;
+    constructor(message: string, endpoint?: string | undefined, details?: unknown, cause?: Error);
+}

package/dist/types/errors/PoolError.d.ts

@@ -0,0 +1,8 @@
+import { AppError } from '@naman_deep_singh/errors';
+/**
+ * Pool error - when pool operations fail
+ */
+export declare class PoolError extends AppError {
+    readonly poolName?: string | undefined;
+    constructor(message: string, poolName?: string | undefined, details?: unknown, cause?: Error);
+}

package/dist/types/errors/TimeoutError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility-specific error classes
+ * @packageDocumentation
+ */
+import { AppError } from '@naman_deep_singh/errors';
+/**
+ * Timeout error - when operation times out
+ */
+export declare class TimeoutError extends AppError {
+    readonly timeoutMs: number;
+    constructor(message: string | undefined, timeoutMs: number, details?: unknown, cause?: Error);
+}

package/dist/types/errors/ValidationError.d.ts

@@ -0,0 +1,9 @@
+import { AppError } from '@naman_deep_singh/errors';
+/**
+ * Validation error - when utility input validation fails
+ */
+export declare class ValidationError extends AppError {
+    readonly field?: string | undefined;
+    readonly value?: unknown | undefined;
+    constructor(message: string, field?: string | undefined, value?: unknown | undefined, details?: unknown, cause?: Error);
+}

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

@@ -0,0 +1,5 @@
+export { CompressionError } from './CompressionError.js';
+export { ConnectionError } from './ConnectionError.js';
+export { PoolError } from './PoolError.js';
+export { TimeoutError } from './TimeoutError.js';
+export { ValidationError } from './ValidationError.js';

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

@@ -1,4 +1,4 @@
-export * from '../string/index.js';
-export * from '../array/index.js';
-export * from '../object/index.js';
-export * from '../number/index.js';
+export { extendString } from '../string/index.js';
+export { extendArray } from '../array/index.js';
+export { extendObject } from '../object/index.js';
+export { extendNumber } from '../number/index.js';

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

@@ -1,2 +1,2 @@
-export * from './initializer.js';
-export * from './options.js';
+export { initExtensions, extendAll } from './initializer.js';
+export { validateExtensionOptions, createExtensionOptions } from './options.js';

package/dist/types/init/initializer.d.ts

@@ -1,3 +1,3 @@
-import type { ExtensionOptions } from '../types/index.js';
+import type { ExtensionOptions } from '../types/extensionTypes.js';
 export declare function initExtensions(options?: ExtensionOptions): void;
 export declare function extendAll(): void;

package/dist/types/init/options.d.ts

@@ -1,3 +1,3 @@
-import type { ExtensionOptions } from '../types/index.js';
+import type { ExtensionOptions } from '../types/extensionTypes.js';
 export declare function validateExtensionOptions(options: Partial<ExtensionOptions>): ExtensionOptions;
 export declare function createExtensionOptions(enableString?: boolean, enableArray?: boolean, enableObject?: boolean, enableNumber?: boolean, performanceConfig?: any): ExtensionOptions;

package/dist/types/types/extensionTypes.d.ts

@@ -1,4 +1,4 @@
-import { type PerformanceConfig } from '../core/index.js';
+import type { PerformanceConfig } from '../core/performance.js';
 export interface ExtensionOptions {
     string?: boolean;
     array?: boolean;

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

@@ -1,2 +1 @@
-export * from './extensionTypes.js';
-export * from './globalAugmentations.js';
+export { type ExtensionOptions, type PerformanceConfig, } from './extensionTypes.js';