@naman_deep_singh/utils 2.4.0 → 2.6.1

package/README.md

@@ -1,19 +1,30 @@
+```bash
 @naman_deep_singh/utils
 
-Version: 2.4.0
+**Version: 2.6.1**
 
-Universal JavaScript prototype extensions for common development utilities. Works in both Node.js and browser environments with 70+ utility methods.
+Universal JavaScript prototype extensions for common development utilities. Works in both Node.js and browser environments with 70+ utility methods, plus timeout management, connection pooling, and compression utilities.
 
-⚠️ This library extends native prototypes (String, Array, Object, Number). Use consciously in shared or library code.
+⚠️ Note: This library extends native prototypes (String, Array, Object, Number). Use consciously in shared or library code.
 
----
+What's New in v2.6.0
+✨ New Utility Modules
+Timeout Management: Async operations with timeout support, retry logic, and delays
 
-## Installation
-```bash
+Connection Pooling: Generic connection pooling with health checks and statistics
+
+Compression Utilities: GZIP, Deflate, and Brotli compression with streaming support
+
+Error Integration: Proper integration with @naman_deep_singh/errors package
+
+Installation
+bash
 npm install @naman_deep_singh/utils
 # or
 pnpm add @naman_deep_singh/utils
 Quick Start
+1. Prototype Extensions
+typescript
 import { initializeExtensions } from '@naman_deep_singh/utils';
 
 // Initialize all extensions
@@ -22,60 +33,142 @@ initializeExtensions();
 // String utilities
 "hello world".toCapitalize();       // "Hello world"
 "hello world".capitalizeWords();    // "Hello World"
-"hello world".reverseWords();       // "world hello"
-"test@email.com".isEmail();         // true
-"hello world".words();              // ["hello", "world"]
 
-// Array utilities
+// Array utilities  
 [1, 2, 2, 3].unique();              // [1, 2, 3]
 [1, 2, 3, 4, 5].chunk(2);           // [[1,2],[3,4],[5]]
-[1, 2, 3].sample();                 // random element
-[1,2,3,4].last();                   // 4
-[{id:1},{id:2},{id:1}].uniqueBy(x => x.id); // [{id:1},{id:2}]
-[3,1,2].sortBy(x => x);             // [1,2,3]
 
 // Number utilities
-(42).toOrdinal();                    // "42nd"
-(0.75).toPercent();                  // "75.00%"
-(3.14159).toFixedNumber(2);          // 3.14
-(5).randomUpTo();                    // 0..5 random number
-(5).times(i => console.log(i));      // 0..4
+(42).toOrdinal();                   // "42nd"
+(0.75).toPercent();                 // "75.00%"
 
 // Object utilities
-({ a: 1, b: 2 }).pick(['a']);        // { a: 1 }
-({ a: 1, b: 2 }).mapValues(v => v * 2); // { a: 2, b: 4 }
-({ a: 1, b: 2 }).mapKeys(k => k + "_"); // { a_: 1, b_: 2 }
-({}).isEmpty();                       // true
-({ user: { name: "John" } }).getPath('user.name'); // "John"
-({ a: 1, b: 2 }).filterKeys(k => k === 'a'); // { a: 1 }
-({ a: 1, b: 2 }).filterValues(v => v === 1); // { a: 1 }
+({ a: 1, b: 2 }).pick(['a']);       // { a: 1 }
+({}).isEmpty();                     // true
+2. Timeout Utilities
+typescript
+import { TimeoutManager } from '@naman_deep_singh/utils';
+
+// Execute promise with timeout
+const result = await TimeoutManager.withTimeout(
+  fetchData(),
+  5000,
+  'Fetch operation timed out'
+);
+
+// Create delay
+await TimeoutManager.delay(1000);
+
+// Retry with timeout
+const data = await TimeoutManager.retryWithTimeout(fetchData, {
+  maxAttempts: 3,
+  timeoutPerAttempt: 3000,
+  backoffMultiplier: 2
+});
+
+// Decorator for class methods
+class ApiService {
+  @withTimeout(5000)
+  async fetchUser(id: string) {
+    // Method automatically times out after 5s
+  }
+}
+3. Connection Pooling
+typescript
+import { GenericPool, PoolManager } from '@naman_deep_singh/utils';
+
+// Create a database connection pool
+const dbPool = new GenericPool({
+  name: 'database',
+  minConnections: 2,
+  maxConnections: 10,
+  createConnection: async () => {
+    return await createDatabaseConnection();
+  },
+  validateConnection: (conn) => conn.isHealthy()
+});
+
+// Acquire and use connection
+const connection = await dbPool.acquire();
+try {
+  await connection.query('SELECT * FROM users');
+} finally {
+  await dbPool.release(connection);
+}
+
+// Or use helper method
+const users = await dbPool.withConnection(async (conn) => {
+  return await conn.query('SELECT * FROM users');
+});
+
+// Pool statistics
+console.log(dbPool.getStats());
+4. Compression Utilities
+typescript
+import { Compression, CompressionAlgorithm } from '@naman_deep_singh/utils';
+
+// Basic compression
+const compressed = await Compression.compress('Hello World', {
+  algorithm: CompressionAlgorithm.GZIP,
+  level: 6
+});
+
+const decompressed = await Compression.decompress(compressed);
+
+// Compression with metrics
+const result = await Compression.compressWithMetrics(largeData, {
+  algorithm: CompressionAlgorithm.BROTLI,
+  level: 9
+});
+console.log(result.compressionRatio); // 0.45 (55% reduction)
+
+// Streaming compression
+await Compression.compressStream(readableStream, writableStream);
+
+// Check supported algorithms
+const supported = Compression.getSupportedAlgorithms();
+// ['gzip', 'deflate', 'brotli'] (if Node.js 10.16.0+)
+5. Error Handling with Custom Errors
+typescript
+import { 
+  TimeoutError, 
+  PoolError, 
+  CompressionError 
+} from '@naman_deep_singh/utils';
+
+try {
+  await TimeoutManager.withTimeout(slowOperation(), 1000);
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.log(`Timeout after ${error.timeoutMs}ms`);
+  }
+}
 Error Handling & Validation
-All methods include strict runtime validation and throw clear native errors.
+Prototype Methods
+All prototype extension methods include strict runtime validation and throw clear native errors.
 
+typescript
 "hello".count(123);
 // TypeError: count: substring must be a string, got number
 
-"hello".count("");
-// TypeError: count: substring cannot be empty
-
 [].sum();
 // TypeError: sum: array must contain at least one number
 
-({ a: 1 }).pick(null as any);
-// TypeError: pick: keys must be an array, got object
-
 (3.14).round(-1);
 // TypeError: round: decimals must be a non-negative integer, got -1
-Error Types Used
-
-TypeError – invalid type or missing argument
-
-RangeError – out-of-range numeric values (e.g. toRoman)
-
-✅ No custom error classes are exposed — only standard JS errors.
-
+Utility Errors
+New utilities throw specific error classes from @naman_deep_singh/errors:
+
+typescript
+import { 
+  TimeoutError,    // Operation timeout (408)
+  PoolError,       // Pool exhaustion (503)
+  ConnectionError, // Connection failure (502)
+  CompressionError // Compression failure (500)
+} from '@naman_deep_singh/utils';
 Configuration
 Selective Extension Loading
+typescript
 import { initializeExtensions, extend } from '@naman_deep_singh/utils';
 
 // Enable only specific prototypes
@@ -90,7 +183,7 @@ initializeExtensions({
 extend.string();
 extend.array();
 Performance Configuration
-Caching System
+typescript
 import { setPerformanceConfig } from '@naman_deep_singh/utils';
 
 setPerformanceConfig({
@@ -101,90 +194,64 @@ Notes:
 
 Validation cannot be disabled
 
-Caching is optional
-
-Uses a simple LRU cache
-
+Caching is optional (LRU cache)
+
+Pool utilities have built-in health checks
+
+API Reference
+Timeout Utilities
+typescript
+TimeoutManager.withTimeout(promise, timeoutMs, errorMessage?);
+TimeoutManager.delay(delayMs);
+TimeoutManager.createTimeoutSignal(timeoutMs);
+TimeoutManager.retryWithTimeout(fn, options);
+TimeoutManager.raceWithTimeout(promises, timeoutMs);
+Connection Pooling
+typescript
+GenericPool<T extends Connection> // Generic connection pool
+PoolManager                       // Multi-pool manager
+interface PoolConfig              // Pool configuration
+interface Connection              // Connection interface
+Compression Utilities
+typescript
+Compression.compress(data, options)
+Compression.decompress(data, options)
+Compression.compressWithMetrics(data, options)
+Compression.createCompressionStream(algorithm, options)
+Compression.createDecompressionStream(algorithm)
+Compression.isAlgorithmSupported(algorithm)
+Compression.getSupportedAlgorithms()
+Prototype Extensions (Summary)
 String Extensions (21 methods)
-Case Conversion
-
-"hello world".toCapitalize();    // "Hello world"
-"hello world".capitalizeWords(); // "Hello World"
-"hello-world".toCamelCase();     // "helloWorld"
-"HelloWorld".toKebabCase();      // "hello-world"
-"Hello World".toSnakeCase();     // "hello_world"
-"hello world".toTitleCase();     // "Hello World"
-Validation & Checks
-
-"test@example.com".isEmail();   // true
-"https://example.com".isUrl();  // true
-"racecar".isPalindrome();       // true
-Text Utilities
-
-"Long text here".truncate(8);        // "Long tex..."
-"hello world".truncateWords(1);      // "hello..."
-"hello world".removeWhitespace();    // "helloworld"
-"<p>Hello</p>".stripHtml();          // "Hello"
-"hello".reverse();                   // "olleh"
-"hello world".reverseWords();        // "world hello"
-"hello hello".count("hello");        // 2
-"Hello World".slugify();             // "hello-world"
-"hello world".words();               // ["hello", "world"]
-"hello\nworld".lines();              // ["hello","world"]
+typescript
+.toCapitalize() .capitalizeWords() .toCamelCase()
+.toKebabCase()  .toSnakeCase()     .toTitleCase()
+.isEmail()      .isUrl()          .isPalindrome()
+.truncate()     .truncateWords()   .removeWhitespace()
+.stripHtml()    .reverse()        .reverseWords()
+.count()        .slugify()        .words()
+.lines()
 Array Extensions (23 methods)
-Core Utilities
-
-[1, 2, 2, 3].unique();                  // [1,2,3]
-[{id:1},{id:2},{id:1}].uniqueBy(x => x.id); // [{id:1},{id:2}]
-[1,2,3,4,5].shuffle();                  // random order
-[1,2,3,4,5].chunk(2);                   // [[1,2],[3,4],[5]]
-[0,1,false,2,"",3].compact();           // [1,2,3] removes null, undefined, false, and empty strings
-[1,2,3,4].last();                        // 4
-[3,1,2].sortBy(x => x);                  // [1,2,3]
-Math
-
-[1,2,3].sum();       // 6
-[1,2,3].average();   // 2
-Advanced
-
-users.groupBy(u => u.age);
-users.pluck('name');
-[1,2,3,4].partition(n => n % 2 === 0);
-// [[2,4],[1,3]]
-Set Operations
-
-[1,2,3].difference([2]);     // [1,3]
-[1,2,3].intersection([2,3]); // [2,3]
-[1,2,3].union([3,4]);        // [1,2,3,4]
-Object Extensions (13 methods)
-({}).isEmpty(); // true
-({ a: 1, b: 2 }).pick(['a']);      // { a: 1 }
-({ a: 1, b: 2 }).omit(['b']);      // { a: 1 }
-({ a: 1, b: 2 }).mapValues(v => v*2); // { a: 2, b: 4 }
-({ a: 1, b: 2 }).mapKeys(k => k+"_");  // { a_:1, b_:2 }
-({ a: 1, b: 2 }).filterKeys(k => k==='a'); // { a:1 }
-({ a: 1, b: 2 }).filterValues(v => v===1); // { a:1 }
-({ a: { b: 2 } }).deepClone();
-({ a: { b: 2 } }).deepFreeze();
-data.hasPath('user.profile.name');
-data.getPath('user.profile.email', 'N/A');
-data.setPath('user.profile.email', 'john@example.com');
+typescript
+.unique()       .uniqueBy()       .shuffle()
+.chunk()        .compact()        .last()
+.sortBy()       .sum()           .average()
+.groupBy()      .pluck()         .partition()
+.difference()   .intersection()   .union()
 Number Extensions (19 methods)
-(0.75).toPercent();                 // "75.00%"
-(3.14159).toFixedNumber(2);         // 3.14
-(1234.56).toCurrency();             // "$1,234.56"
-(1234.56).toCurrency('EUR','de-DE'); // "1.234,56 €"
-(5).clamp(1,10);                     // 5
-(5).inRange(1,10);                   // true
-(7).isPrime();                        // true
-(5).factorial();                      // 120
-(5).randomUpTo();                     // 0..5
-(3).times(i => console.log(i));      // 0,1,2
-(42).toOrdinal();                     // "42nd"
-(123).sign();                         // 1
+typescript
+.toPercent()    .toFixedNumber()  .toCurrency()
+.clamp()        .inRange()        .isPrime()
+.factorial()    .randomUpTo()     .times()
+.toOrdinal()    .sign()
+Object Extensions (13 methods)
+typescript
+.isEmpty()      .pick()          .omit()
+.mapValues()    .mapKeys()       .filterKeys()
+.filterValues() .deepClone()     .deepFreeze()
+.hasPath()      .getPath()       .setPath()
 Caching Details
 Cached Methods (when enabled):
-
 Number.isPrime()
 
 Number.factorial()
@@ -192,27 +259,59 @@ Number.factorial()
 Number.toRoman()
 
 Custom Caching:
-
+typescript
 import { withCache } from '@naman_deep_singh/utils';
 const result = withCache('key', () => expensiveFn());
+Pool Health Checks:
+Automatic idle connection cleanup
+
+Maximum lifetime enforcement
+
+Periodic health validation
+
+Statistics tracking
+
 TypeScript Support
-Full global augmentation
+Full TypeScript support with:
+
+Complete global augmentation
 
 Strict typing for all methods
 
 Zero any leakage in public APIs
 
-const x: number[] = [1,2,2].unique();
+Proper type imports/exports
+
+typescript
+const x: number[] = [1, 2, 2].unique();
 const y: string = "hello".toCapitalize();
+const z: CompressionResult = await compressWithMetrics(data);
 Package Stats
-~70 utility methods
+70+ prototype utility methods
+
+Timeout management utilities
+
+Generic connection pooling
+
+Multi-algorithm compression
 
-Zero dependencies
+Zero production dependencies (except peer deps)
 
-Node.js + Browser
+Node.js + Browser compatibility
 
-TypeScript-first
+TypeScript-first design
 
 Optional LRU caching
 
-Strict runtime validation
+Strict runtime validation
+
+Dependencies
+json
+{
+  "peerDependencies": {
+    "@naman_deep_singh/errors": "^2.3.0"
+  }
+}
+License
+ISC © Naman Deep Singh
+```

package/dist/cjs/errors/CompressionError.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompressionError = void 0;
+const errors_1 = require("@naman_deep_singh/errors");
+/**
+ * Compression error - when compression/decompression fails
+ */
+class CompressionError extends errors_1.AppError {
+    constructor(message, algorithm, details, cause) {
+        super(errors_1.ERROR_CODES.FILE_ERROR, 500, {
+            message,
+            algorithm,
+            ...(details ? { details } : {}),
+        }, cause);
+        this.algorithm = algorithm;
+        this.name = 'CompressionError';
+    }
+}
+exports.CompressionError = CompressionError;

package/dist/cjs/errors/ConnectionError.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Connection error - when connection fails
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionError = void 0;
+const errors_1 = require("@naman_deep_singh/errors");
+class ConnectionError extends errors_1.AppError {
+    constructor(message, endpoint, details, cause) {
+        super(errors_1.ERROR_CODES.DEPENDENCY_FAILURE, 502, // 502 = Bad Gateway
+        {
+            message,
+            endpoint,
+            ...(details ? { details } : {}),
+        }, cause);
+        this.endpoint = endpoint;
+        this.name = 'ConnectionError';
+    }
+}
+exports.ConnectionError = ConnectionError;

package/dist/cjs/errors/PoolError.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolError = void 0;
+const errors_1 = require("@naman_deep_singh/errors");
+/**
+ * Pool error - when pool operations fail
+ */
+class PoolError extends errors_1.AppError {
+    constructor(message, poolName, details, cause) {
+        super(errors_1.ERROR_CODES.RESOURCE_EXHAUSTED, 503, // 503 = Service Unavailable
+        {
+            message,
+            poolName,
+            ...(details ? { details } : {}),
+        }, cause);
+        this.poolName = poolName;
+        this.name = 'PoolError';
+    }
+}
+exports.PoolError = PoolError;

package/dist/cjs/errors/TimeoutError.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Utility-specific error classes
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = void 0;
+const errors_1 = require("@naman_deep_singh/errors");
+/**
+ * Timeout error - when operation times out
+ */
+class TimeoutError extends errors_1.AppError {
+    constructor(message = 'Operation timed out', timeoutMs, details, cause) {
+        super(errors_1.ERROR_CODES.TIMEOUT_ERROR, 408, // 408 = Request Timeout
+        {
+            message,
+            timeoutMs,
+            ...(details ? { details } : {}),
+        }, cause);
+        this.timeoutMs = timeoutMs;
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;

package/dist/cjs/errors/ValidationError.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+const errors_1 = require("@naman_deep_singh/errors");
+/**
+ * Validation error - when utility input validation fails
+ */
+class ValidationError extends errors_1.AppError {
+    constructor(message, field, value, details, cause) {
+        super(errors_1.ERROR_CODES.VALIDATION_FAILED, 400, // 400 = Bad Request
+        {
+            message,
+            field,
+            value,
+            ...(details ? { details } : {}),
+        }, cause);
+        this.field = field;
+        this.value = value;
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;

package/dist/cjs/errors/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.TimeoutError = exports.PoolError = exports.ConnectionError = exports.CompressionError = void 0;
+var CompressionError_js_1 = require("./CompressionError.js");
+Object.defineProperty(exports, "CompressionError", { enumerable: true, get: function () { return CompressionError_js_1.CompressionError; } });
+var ConnectionError_js_1 = require("./ConnectionError.js");
+Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return ConnectionError_js_1.ConnectionError; } });
+var PoolError_js_1 = require("./PoolError.js");
+Object.defineProperty(exports, "PoolError", { enumerable: true, get: function () { return PoolError_js_1.PoolError; } });
+var TimeoutError_js_1 = require("./TimeoutError.js");
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return TimeoutError_js_1.TimeoutError; } });
+var ValidationError_js_1 = require("./ValidationError.js");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return ValidationError_js_1.ValidationError; } });

package/dist/cjs/index.js

@@ -27,5 +27,7 @@ __exportStar(require("./utils/index.js"), exports);
 // Initialization & setup
 __exportStar(require("./init/index.js"), exports);
 __exportStar(require("./extensions/index.js"), exports);
+// Error handling
+__exportStar(require("./errors/index.js"), exports);
 // Types
 __exportStar(require("./types/index.js"), exports);