@naman_deep_singh/utils 2.4.0 → 2.6.0

package/dist/esm/utils/compression.js

@@ -0,0 +1,415 @@
+/**
+ * Compression utilities for data compression/decompression
+ * @packageDocumentation
+ */
+import { CompressionError } from '../errors/CompressionError.js';
+/**
+ * Supported compression algorithms
+ */
+export 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 || (CompressionAlgorithm = {}));
+/**
+ * Main compression utility class
+ */
+export 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(`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(`Unsupported algorithm: ${options.algorithm}`, options.algorithm);
+        }
+    }
+    /**
+     * GZIP compression
+     */
+    static async compressGzip(buffer, level) {
+        const { gzip } = await import('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 import('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 import('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 import('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 import('zlib');
+        if (!zlib.brotliCompress) {
+            throw new 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 import('zlib');
+        if (!zlib.brotliDecompress) {
+            throw new 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('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(`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('Brotli stream decompression requires Node.js 10.16.0+', CompressionAlgorithm.BROTLI);
+                }
+                return zlib.createBrotliDecompress();
+            default:
+                throw new 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('Input cannot be null or undefined');
+        }
+        if (typeof input !== 'string' && !Buffer.isBuffer(input)) {
+            throw new CompressionError(`Input must be string or Buffer, got ${typeof input}`);
+        }
+        if (typeof input === 'string' && input.length === 0) {
+            throw new CompressionError('Input string cannot be empty');
+        }
+        if (Buffer.isBuffer(input) && input.length === 0) {
+            throw new CompressionError('Input buffer cannot be empty');
+        }
+    }
+    /**
+     * Validate compression options
+     */
+    static validateOptions(options) {
+        if (!Object.values(CompressionAlgorithm).includes(options.algorithm)) {
+            throw new CompressionError(`Invalid algorithm: ${options.algorithm}`, options.algorithm);
+        }
+        if (options.level < 1 || options.level > 9) {
+            throw new CompressionError(`Compression level must be between 1-9, got ${options.level}`, options.algorithm, { level: options.level });
+        }
+        if (!this.isAlgorithmSupported(options.algorithm)) {
+            throw new 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) {
+            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(`Failed to ${operation} with ${algorithm}: ${errorMessage}`, algorithm, {
+            operation,
+            input: inputInfo,
+        }, error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Default compression options
+ */
+Compression.DEFAULT_OPTIONS = {
+    algorithm: CompressionAlgorithm.GZIP,
+    level: 6,
+    encoding: 'utf8',
+};
+/**
+ * Convenience function for compression
+ */
+export async function compress(input, options = {}) {
+    return Compression.compress(input, options);
+}
+/**
+ * Convenience function for decompression
+ */
+export async function decompress(input, options = {}) {
+    return Compression.decompress(input, options);
+}
+/**
+ * Convenience function for compression with metrics
+ */
+export async function compressWithMetrics(input, options = {}) {
+    return Compression.compressWithMetrics(input, options);
+}

package/dist/esm/utils/index.js

@@ -1,4 +1,16 @@
-// Re-export all utilities
+/**
+ * Utils package exports
+ * @packageDocumentation
+ */
+// Export configuration utilities
 export { validateConfig, validatePerformanceSettings, mergeConfigs, } from './config.js';
+// Export helper utilities
 export { isValidArrayIndex, ensurePositiveInteger, safeClone, getPathSegments, hasOwnProperty, } from './helpers.js';
+// Export extension utilities
 export { defineExtension } from './defineExtension.js';
+// Export timeout utilities
+export { TimeoutManager, withTimeout, } from './timeout.js';
+// Export pool utilities
+export { GenericPool, PoolManager, } from './pool.js';
+// Export compression utilities
+export { Compression, compress, decompress, compressWithMetrics, CompressionAlgorithm, } from './compression.js';