tessl/npm-mz

Promise-based wrappers for Node.js core APIs that modernize callback-based methods to work with async/await patterns

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Compression Operations

Name: tessl/npm-mz
Author: tessl

Compress and decompress data using various algorithms with promise support. Provides modern async/await compatibility for Node.js zlib operations.

Capabilities

Gzip Compression

Compress and decompress data using the gzip algorithm.

/**
 * Compress data using gzip algorithm
 * @param buffer - Data to compress (Buffer or string)
 * @param options - Compression options
 * @returns Promise resolving to compressed Buffer
 */
function gzip(buffer, options): Promise<Buffer>;

/**
 * Decompress gzip-compressed data
 * @param buffer - Compressed data Buffer
 * @param options - Decompression options
 * @returns Promise resolving to decompressed Buffer
 */
function gunzip(buffer, options): Promise<Buffer>;

Deflate Compression

Compress and decompress data using the deflate algorithm.

/**
 * Compress data using deflate algorithm
 * @param buffer - Data to compress (Buffer or string)
 * @param options - Compression options
 * @returns Promise resolving to compressed Buffer
 */
function deflate(buffer, options): Promise<Buffer>;

/**
 * Decompress deflate-compressed data
 * @param buffer - Compressed data Buffer
 * @param options - Decompression options
 * @returns Promise resolving to decompressed Buffer
 */
function inflate(buffer, options): Promise<Buffer>;

Raw Deflate Compression

Compress and decompress data using raw deflate (without headers).

/**
 * Compress data using raw deflate algorithm (no headers)
 * @param buffer - Data to compress (Buffer or string)
 * @param options - Compression options
 * @returns Promise resolving to compressed Buffer
 */
function deflateRaw(buffer, options): Promise<Buffer>;

/**
 * Decompress raw deflate-compressed data
 * @param buffer - Compressed data Buffer
 * @param options - Decompression options
 * @returns Promise resolving to decompressed Buffer
 */
function inflateRaw(buffer, options): Promise<Buffer>;

Universal Decompression

Automatically detect and decompress various compression formats.

/**
 * Decompress data, automatically detecting the compression format
 * @param buffer - Compressed data Buffer
 * @param options - Decompression options
 * @returns Promise resolving to decompressed Buffer
 */
function unzip(buffer, options): Promise<Buffer>;

Usage Examples:

const zlib = require('mz/zlib');

// Basic gzip compression and decompression
async function gzipExample() {
  try {
    const originalData = 'Hello, World! This is some text to compress.';
    console.log('Original:', originalData);
    console.log('Original size:', originalData.length, 'bytes');
    
    // Compress with gzip
    const compressed = await zlib.gzip(originalData);
    console.log('Compressed size:', compressed.length, 'bytes');
    console.log('Compression ratio:', (compressed.length / originalData.length * 100).toFixed(1) + '%');
    
    // Decompress
    const decompressed = await zlib.gunzip(compressed);
    console.log('Decompressed:', decompressed.toString());
    
  } catch (error) {
    console.error('Compression failed:', error);
  }
}

// Deflate compression
async function deflateExample() {
  try {
    const data = Buffer.from('This is test data for deflate compression');
    
    // Compress with deflate
    const compressed = await zlib.deflate(data);
    console.log('Deflate compressed:', compressed.length, 'bytes');
    
    // Decompress
    const decompressed = await zlib.inflate(compressed);
    console.log('Decompressed:', decompressed.toString());
    
  } catch (error) {
    console.error('Deflate operation failed:', error);
  }
}

// Raw deflate (no headers)
async function rawDeflateExample() {
  try {
    const data = 'Raw deflate compression example';
    
    const compressed = await zlib.deflateRaw(data);
    const decompressed = await zlib.inflateRaw(compressed);
    
    console.log('Raw deflate works:', decompressed.toString() === data);
    
  } catch (error) {
    console.error('Raw deflate failed:', error);
  }
}

// Universal decompression
async function unzipExample() {
  try {
    // Compress with gzip first
    const data = 'Data compressed with gzip';
    const gzipped = await zlib.gzip(data);
    
    // Decompress with unzip (auto-detects format)
    const unzipped = await zlib.unzip(gzipped);
    console.log('Unzipped:', unzipped.toString());
    
  } catch (error) {
    console.error('Unzip failed:', error);
  }
}

// Compress large data with options
async function compressWithOptions() {
  try {
    const largeData = 'Large data string...'.repeat(1000);
    
    // Compress with custom options
    const compressed = await zlib.gzip(largeData, {
      level: 9,        // Maximum compression
      chunkSize: 1024, // Chunk size for processing
      windowBits: 15,  // Window size
      memLevel: 8,     // Memory usage level
      strategy: zlib.constants.Z_DEFAULT_STRATEGY
    });
    
    console.log('Highly compressed size:', compressed.length);
    
    const decompressed = await zlib.gunzip(compressed);
    console.log('Decompression successful:', decompressed.length === largeData.length);
    
  } catch (error) {
    console.error('Compression with options failed:', error);
  }
}

// Callback support is still available
zlib.gzip('callback example', (err, compressed) => {
  if (err) {
    console.error('Error:', err);
  } else {
    console.log('Compressed with callback:', compressed.length, 'bytes');
  }
});

// File compression example
const fs = require('mz/fs');

async function compressFile(inputPath, outputPath) {
  try {
    // Read file
    const fileData = await fs.readFile(inputPath);
    console.log('Original file size:', fileData.length, 'bytes');
    
    // Compress
    const compressed = await zlib.gzip(fileData);
    console.log('Compressed size:', compressed.length, 'bytes');
    
    // Write compressed file
    await fs.writeFile(outputPath, compressed);
    console.log('Compressed file saved to:', outputPath);
    
  } catch (error) {
    console.error('File compression failed:', error);
  }
}

// Compare compression algorithms
async function compareAlgorithms() {
  const testData = 'This is test data for comparing compression algorithms. '.repeat(100);
  
  try {
    const gzipResult = await zlib.gzip(testData);
    const deflateResult = await zlib.deflate(testData);
    const deflateRawResult = await zlib.deflateRaw(testData);
    
    console.log('Original size:', testData.length);
    console.log('Gzip size:', gzipResult.length);
    console.log('Deflate size:', deflateResult.length);
    console.log('Deflate raw size:', deflateRawResult.length);
    
  } catch (error) {
    console.error('Comparison failed:', error);
  }
}

Compression Options

All compression functions accept an options object:

interface CompressionOptions {
  /** Compression level (0-9, where 9 is best compression) */
  level?: number;
  /** Chunk size for processing data */
  chunkSize?: number;
  /** Window size (affects compression ratio and memory usage) */
  windowBits?: number;
  /** Memory usage level (1-9, where 9 uses most memory) */
  memLevel?: number;
  /** Compression strategy */
  strategy?: number;
  /** Dictionary for compression (advanced usage) */
  dictionary?: Buffer;
  /** Information about the original data */
  info?: boolean;
}

Compression Levels

0: No compression (fastest)
1: Best speed
2-8: Balanced speed/compression
9: Best compression (slowest)
-1: Default compression level

Error Handling

Compression functions will reject with errors for:

Invalid input data
Corrupted compressed data
Invalid options
Memory allocation failures

const zlib = require('mz/zlib');

async function handleCompressionErrors() {
  try {
    // This will fail - trying to decompress non-compressed data
    await zlib.gunzip('not compressed data');
  } catch (error) {
    console.error('Decompression error:', error.message);
    // Error codes: Z_DATA_ERROR, Z_BUF_ERROR, etc.
  }
  
  try {
    // This will fail - invalid compression level
    await zlib.gzip('data', { level: 15 }); // Max level is 9
  } catch (error) {
    console.error('Invalid options:', error.message);
  }
}

Performance Considerations

Gzip: Good compression ratio, widely supported, includes headers
Deflate: Similar to gzip but with different headers
DeflateRaw: No headers, slightly smaller, faster for small data
Level 1: Fast compression, larger output
Level 9: Slow compression, smaller output
Chunk size: Larger chunks use more memory but may be more efficient

Practical Use Cases

// Web server response compression
async function compressHttpResponse(data) {
  try {
    return await zlib.gzip(data);
  } catch (error) {
    // Return uncompressed data if compression fails
    return Buffer.from(data);
  }
}

// Database storage compression
async function compressForStorage(jsonData) {
  try {
    const stringified = JSON.stringify(jsonData);
    const compressed = await zlib.deflate(stringified);
    return compressed;
  } catch (error) {
    throw new Error('Failed to compress data for storage: ' + error.message);
  }
}

// Log file compression
async function compressLogs(logEntries) {
  try {
    const logText = logEntries.join('\n');
    return await zlib.gzip(logText, { level: 9 }); // Maximum compression for logs
  } catch (error) {
    throw new Error('Log compression failed: ' + error.message);
  }
}

Implementation Notes

Uses thenify-all to wrap native zlib methods
Maintains complete compatibility with native zlib behavior
Supports both promise and callback interfaces
All functions work with Buffers and strings (strings are converted to Buffers)
Error behavior matches native zlib module exactly
Constants from native zlib module are available (e.g., zlib.constants.Z_BEST_COMPRESSION)