@naman_deep_singh/utils 2.4.0 → 2.6.0

package/dist/cjs/utils/compression.js

@@ -0,0 +1,455 @@
+"use strict";
+/**
+ * Compression utilities for data compression/decompression
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Compression = exports.CompressionAlgorithm = void 0;
+exports.compress = compress;
+exports.decompress = decompress;
+exports.compressWithMetrics = compressWithMetrics;
+const CompressionError_js_1 = require("../errors/CompressionError.js");
+/**
+ * Supported compression algorithms
+ */
+var CompressionAlgorithm;
+(function (CompressionAlgorithm) {
+    /** GZIP compression */
+    CompressionAlgorithm["GZIP"] = "gzip";
+    /** Deflate compression */
+    CompressionAlgorithm["DEFLATE"] = "deflate";
+    /** Brotli compression (Node.js 10.16.0+) */
+    CompressionAlgorithm["BROTLI"] = "brotli";
+})(CompressionAlgorithm || (exports.CompressionAlgorithm = CompressionAlgorithm = {}));
+/**
+ * Main compression utility class
+ */
+class Compression {
+    /**
+     * Check if compression algorithm is supported
+     */
+    static isAlgorithmSupported(algorithm) {
+        switch (algorithm) {
+            case CompressionAlgorithm.GZIP:
+            case CompressionAlgorithm.DEFLATE:
+                return true;
+            case CompressionAlgorithm.BROTLI:
+                // Brotli requires Node.js 10.16.0+
+                if (typeof process !== 'undefined' && process.versions?.node) {
+                    const [major, minor, _patch] = process.versions.node
+                        .split('.')
+                        .map(Number);
+                    // Brotli support from Node.js 10.16.0
+                    return major > 10 || (major === 10 && minor >= 16);
+                }
+                return false;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Get supported algorithms for current environment
+     */
+    static getSupportedAlgorithms() {
+        const algorithms = [
+            CompressionAlgorithm.GZIP,
+            CompressionAlgorithm.DEFLATE,
+        ];
+        if (this.isAlgorithmSupported(CompressionAlgorithm.BROTLI)) {
+            algorithms.push(CompressionAlgorithm.BROTLI);
+        }
+        return algorithms;
+    }
+    /**
+     * Compress data
+     * @param input Data to compress (string or Buffer)
+     * @param options Compression options
+     * @returns Compressed data as Buffer
+     */
+    static async compress(input, options = {}) {
+        const opts = { ...this.DEFAULT_OPTIONS, ...options };
+        try {
+            this.validateInput(input);
+            this.validateOptions(opts);
+            const buffer = typeof input === 'string' ? Buffer.from(input, opts.encoding) : input;
+            const compressed = await this.compressBuffer(buffer, opts);
+            return compressed;
+        }
+        catch (error) {
+            throw this.wrapError(error, 'compress', opts.algorithm, input);
+        }
+    }
+    /**
+     * Decompress data
+     * @param input Compressed data (Buffer or base64 string)
+     * @param options Compression options
+     * @returns Decompressed data as Buffer
+     */
+    static async decompress(input, options = {}) {
+        const opts = { ...this.DEFAULT_OPTIONS, ...options };
+        try {
+            this.validateInput(input);
+            const buffer = typeof input === 'string' ? Buffer.from(input, 'base64') : input;
+            const decompressed = await this.decompressBuffer(buffer, opts);
+            return decompressed;
+        }
+        catch (error) {
+            throw this.wrapError(error, 'decompress', opts.algorithm, input);
+        }
+    }
+    /**
+     * Compress data with detailed metrics
+     * @param input Data to compress
+     * @param options Compression options
+     * @returns Compression result with metrics
+     */
+    static async compressWithMetrics(input, options = {}) {
+        const startTime = performance.now();
+        const opts = { ...this.DEFAULT_OPTIONS, ...options };
+        try {
+            this.validateInput(input);
+            this.validateOptions(opts);
+            const buffer = typeof input === 'string' ? Buffer.from(input, opts.encoding) : input;
+            const originalSize = buffer.length;
+            const compressed = await this.compressBuffer(buffer, opts);
+            const endTime = performance.now();
+            const compressedSize = compressed.length;
+            const compressionRatio = compressedSize / originalSize;
+            return {
+                data: opts.encoding === 'base64'
+                    ? compressed.toString('base64')
+                    : compressed,
+                originalSize,
+                compressedSize,
+                compressionRatio,
+                timeTakenMs: endTime - startTime,
+                algorithm: opts.algorithm,
+            };
+        }
+        catch (error) {
+            throw this.wrapError(error, 'compressWithMetrics', opts.algorithm, input);
+        }
+    }
+    /**
+     * Compress buffer data using specified algorithm
+     */
+    static async compressBuffer(buffer, options) {
+        switch (options.algorithm) {
+            case CompressionAlgorithm.GZIP:
+                return this.compressGzip(buffer, options.level);
+            case CompressionAlgorithm.DEFLATE:
+                return this.compressDeflate(buffer, options.level);
+            case CompressionAlgorithm.BROTLI:
+                return this.compressBrotli(buffer, options.level);
+            default:
+                throw new CompressionError_js_1.CompressionError(`Unsupported algorithm: ${options.algorithm}`, options.algorithm);
+        }
+    }
+    /**
+     * Decompress buffer data using specified algorithm
+     */
+    static async decompressBuffer(buffer, options) {
+        switch (options.algorithm) {
+            case CompressionAlgorithm.GZIP:
+                return this.decompressGzip(buffer);
+            case CompressionAlgorithm.DEFLATE:
+                return this.decompressDeflate(buffer);
+            case CompressionAlgorithm.BROTLI:
+                return this.decompressBrotli(buffer);
+            default:
+                throw new CompressionError_js_1.CompressionError(`Unsupported algorithm: ${options.algorithm}`, options.algorithm);
+        }
+    }
+    /**
+     * GZIP compression
+     */
+    static async compressGzip(buffer, level) {
+        const { gzip } = await Promise.resolve().then(() => __importStar(require('zlib')));
+        return new Promise((resolve, reject) => {
+            gzip(buffer, { level }, (error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    /**
+     * GZIP decompression
+     */
+    static async decompressGzip(buffer) {
+        const { gunzip } = await Promise.resolve().then(() => __importStar(require('zlib')));
+        return new Promise((resolve, reject) => {
+            gunzip(buffer, (error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    /**
+     * Deflate compression
+     */
+    static async compressDeflate(buffer, level) {
+        const { deflate } = await Promise.resolve().then(() => __importStar(require('zlib')));
+        return new Promise((resolve, reject) => {
+            deflate(buffer, { level }, (error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    /**
+     * Deflate decompression
+     */
+    static async decompressDeflate(buffer) {
+        const { inflate } = await Promise.resolve().then(() => __importStar(require('zlib')));
+        return new Promise((resolve, reject) => {
+            inflate(buffer, (error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    /**
+     * Brotli compression (Node.js 10.16.0+)
+     */
+    static async compressBrotli(buffer, level) {
+        const zlib = await Promise.resolve().then(() => __importStar(require('zlib')));
+        if (!zlib.brotliCompress) {
+            throw new CompressionError_js_1.CompressionError('Brotli compression requires Node.js 10.16.0+', CompressionAlgorithm.BROTLI, {
+                nodeVersion: process?.version || 'unknown',
+                requiredVersion: '>=10.16.0',
+            });
+        }
+        return new Promise((resolve, reject) => {
+            zlib.brotliCompress(buffer, {
+                params: {
+                    [zlib.constants.BROTLI_PARAM_QUALITY]: level,
+                    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+                },
+            }, (error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    /**
+     * Brotli decompression (Node.js 10.16.0+)
+     */
+    static async decompressBrotli(buffer) {
+        const zlib = await Promise.resolve().then(() => __importStar(require('zlib')));
+        if (!zlib.brotliDecompress) {
+            throw new CompressionError_js_1.CompressionError('Brotli decompression requires Node.js 10.16.0+', CompressionAlgorithm.BROTLI, {
+                nodeVersion: process?.version || 'unknown',
+                requiredVersion: '>=10.16.0',
+            });
+        }
+        return new Promise((resolve, reject) => {
+            zlib.brotliDecompress(buffer, (error, result) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    /**
+     * Create compression stream
+     * @param algorithm Compression algorithm
+     * @param options Compression options
+     * @returns Compression stream
+     */
+    static createCompressionStream(algorithm = CompressionAlgorithm.GZIP, options = {}) {
+        const opts = { ...this.DEFAULT_OPTIONS, ...options, algorithm };
+        this.validateOptions(opts);
+        switch (algorithm) {
+            case CompressionAlgorithm.GZIP:
+                return require('zlib').createGzip({ level: opts.level });
+            case CompressionAlgorithm.DEFLATE:
+                return require('zlib').createDeflate({ level: opts.level });
+            case CompressionAlgorithm.BROTLI:
+                const zlib = require('zlib');
+                if (!zlib.createBrotliCompress) {
+                    throw new CompressionError_js_1.CompressionError('Brotli stream compression requires Node.js 10.16.0+', CompressionAlgorithm.BROTLI);
+                }
+                return zlib.createBrotliCompress({
+                    params: {
+                        [zlib.constants.BROTLI_PARAM_QUALITY]: opts.level,
+                    },
+                });
+            default:
+                throw new CompressionError_js_1.CompressionError(`Unsupported algorithm for streaming: ${algorithm}`, algorithm);
+        }
+    }
+    /**
+     * Create decompression stream
+     * @param algorithm Compression algorithm
+     * @returns Decompression stream
+     */
+    static createDecompressionStream(algorithm = CompressionAlgorithm.GZIP) {
+        switch (algorithm) {
+            case CompressionAlgorithm.GZIP:
+                return require('zlib').createGunzip();
+            case CompressionAlgorithm.DEFLATE:
+                return require('zlib').createInflate();
+            case CompressionAlgorithm.BROTLI:
+                const zlib = require('zlib');
+                if (!zlib.createBrotliDecompress) {
+                    throw new CompressionError_js_1.CompressionError('Brotli stream decompression requires Node.js 10.16.0+', CompressionAlgorithm.BROTLI);
+                }
+                return zlib.createBrotliDecompress();
+            default:
+                throw new CompressionError_js_1.CompressionError(`Unsupported algorithm for streaming: ${algorithm}`, algorithm);
+        }
+    }
+    /**
+     * Stream compression
+     * @param readable Readable stream
+     * @param writable Writable stream
+     * @param options Compression options
+     */
+    static async compressStream(readable, writable, options = {}) {
+        return new Promise((resolve, reject) => {
+            const compressor = this.createCompressionStream(options.algorithm, options);
+            readable
+                .pipe(compressor)
+                .pipe(writable)
+                .on('finish', resolve)
+                .on('error', reject);
+        });
+    }
+    /**
+     * Stream decompression
+     * @param readable Readable stream
+     * @param writable Writable stream
+     * @param options Compression options
+     */
+    static async decompressStream(readable, writable, options = {}) {
+        return new Promise((resolve, reject) => {
+            const decompressor = this.createDecompressionStream(options.algorithm);
+            readable
+                .pipe(decompressor)
+                .pipe(writable)
+                .on('finish', resolve)
+                .on('error', reject);
+        });
+    }
+    /**
+     * Validate input data
+     */
+    static validateInput(input) {
+        if (input === null || input === undefined) {
+            throw new CompressionError_js_1.CompressionError('Input cannot be null or undefined');
+        }
+        if (typeof input !== 'string' && !Buffer.isBuffer(input)) {
+            throw new CompressionError_js_1.CompressionError(`Input must be string or Buffer, got ${typeof input}`);
+        }
+        if (typeof input === 'string' && input.length === 0) {
+            throw new CompressionError_js_1.CompressionError('Input string cannot be empty');
+        }
+        if (Buffer.isBuffer(input) && input.length === 0) {
+            throw new CompressionError_js_1.CompressionError('Input buffer cannot be empty');
+        }
+    }
+    /**
+     * Validate compression options
+     */
+    static validateOptions(options) {
+        if (!Object.values(CompressionAlgorithm).includes(options.algorithm)) {
+            throw new CompressionError_js_1.CompressionError(`Invalid algorithm: ${options.algorithm}`, options.algorithm);
+        }
+        if (options.level < 1 || options.level > 9) {
+            throw new CompressionError_js_1.CompressionError(`Compression level must be between 1-9, got ${options.level}`, options.algorithm, { level: options.level });
+        }
+        if (!this.isAlgorithmSupported(options.algorithm)) {
+            throw new CompressionError_js_1.CompressionError(`Algorithm not supported: ${options.algorithm}`, options.algorithm, {
+                supportedAlgorithms: this.getSupportedAlgorithms(),
+                nodeVersion: process?.version || 'unknown',
+            });
+        }
+    }
+    /**
+     * Wrap errors with CompressionError
+     */
+    static wrapError(error, operation, algorithm, input) {
+        if (error instanceof CompressionError_js_1.CompressionError) {
+            return error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const inputInfo = Buffer.isBuffer(input)
+            ? { size: input.length, type: 'buffer' }
+            : { size: input.length, type: 'string' };
+        return new CompressionError_js_1.CompressionError(`Failed to ${operation} with ${algorithm}: ${errorMessage}`, algorithm, {
+            operation,
+            input: inputInfo,
+        }, error instanceof Error ? error : undefined);
+    }
+}
+exports.Compression = Compression;
+/**
+ * Default compression options
+ */
+Compression.DEFAULT_OPTIONS = {
+    algorithm: CompressionAlgorithm.GZIP,
+    level: 6,
+    encoding: 'utf8',
+};
+/**
+ * Convenience function for compression
+ */
+async function compress(input, options = {}) {
+    return Compression.compress(input, options);
+}
+/**
+ * Convenience function for decompression
+ */
+async function decompress(input, options = {}) {
+    return Compression.decompress(input, options);
+}
+/**
+ * Convenience function for compression with metrics
+ */
+async function compressWithMetrics(input, options = {}) {
+    return Compression.compressWithMetrics(input, options);
+}

package/dist/cjs/utils/index.js

@@ -1,16 +1,37 @@
 "use strict";
+/**
+ * Utils package exports
+ * @packageDocumentation
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineExtension = exports.hasOwnProperty = exports.getPathSegments = exports.safeClone = exports.ensurePositiveInteger = exports.isValidArrayIndex = exports.mergeConfigs = exports.validatePerformanceSettings = exports.validateConfig = void 0;
-// Re-export all utilities
+exports.CompressionAlgorithm = exports.compressWithMetrics = exports.decompress = exports.compress = exports.Compression = exports.PoolManager = exports.GenericPool = exports.withTimeout = exports.TimeoutManager = exports.defineExtension = exports.hasOwnProperty = exports.getPathSegments = exports.safeClone = exports.ensurePositiveInteger = exports.isValidArrayIndex = exports.mergeConfigs = exports.validatePerformanceSettings = exports.validateConfig = void 0;
+// Export configuration utilities
 var config_js_1 = require("./config.js");
 Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return config_js_1.validateConfig; } });
 Object.defineProperty(exports, "validatePerformanceSettings", { enumerable: true, get: function () { return config_js_1.validatePerformanceSettings; } });
 Object.defineProperty(exports, "mergeConfigs", { enumerable: true, get: function () { return config_js_1.mergeConfigs; } });
+// Export helper utilities
 var helpers_js_1 = require("./helpers.js");
 Object.defineProperty(exports, "isValidArrayIndex", { enumerable: true, get: function () { return helpers_js_1.isValidArrayIndex; } });
 Object.defineProperty(exports, "ensurePositiveInteger", { enumerable: true, get: function () { return helpers_js_1.ensurePositiveInteger; } });
 Object.defineProperty(exports, "safeClone", { enumerable: true, get: function () { return helpers_js_1.safeClone; } });
 Object.defineProperty(exports, "getPathSegments", { enumerable: true, get: function () { return helpers_js_1.getPathSegments; } });
 Object.defineProperty(exports, "hasOwnProperty", { enumerable: true, get: function () { return helpers_js_1.hasOwnProperty; } });
+// Export extension utilities
 var defineExtension_js_1 = require("./defineExtension.js");
 Object.defineProperty(exports, "defineExtension", { enumerable: true, get: function () { return defineExtension_js_1.defineExtension; } });
+// Export timeout utilities
+var timeout_js_1 = require("./timeout.js");
+Object.defineProperty(exports, "TimeoutManager", { enumerable: true, get: function () { return timeout_js_1.TimeoutManager; } });
+Object.defineProperty(exports, "withTimeout", { enumerable: true, get: function () { return timeout_js_1.withTimeout; } });
+// Export pool utilities
+var pool_js_1 = require("./pool.js");
+Object.defineProperty(exports, "GenericPool", { enumerable: true, get: function () { return pool_js_1.GenericPool; } });
+Object.defineProperty(exports, "PoolManager", { enumerable: true, get: function () { return pool_js_1.PoolManager; } });
+// Export compression utilities
+var compression_js_1 = require("./compression.js");
+Object.defineProperty(exports, "Compression", { enumerable: true, get: function () { return compression_js_1.Compression; } });
+Object.defineProperty(exports, "compress", { enumerable: true, get: function () { return compression_js_1.compress; } });
+Object.defineProperty(exports, "decompress", { enumerable: true, get: function () { return compression_js_1.decompress; } });
+Object.defineProperty(exports, "compressWithMetrics", { enumerable: true, get: function () { return compression_js_1.compressWithMetrics; } });
+Object.defineProperty(exports, "CompressionAlgorithm", { enumerable: true, get: function () { return compression_js_1.CompressionAlgorithm; } });