🚀 Quick Start

Installation

# npm
npm install @xbibzlibrary/kompreser

# yarn
yarn add @xbibzlibrary/kompreser

# pnpm
pnpm add @xbibzlibrary/kompreser

Basic Usage

import Kompreser from '@xbibzlibrary/kompreser';

// Initialize the compressor
const kompreser = new Kompreser({
  quality: 0.8,
  format: 'auto',
  progressive: true
});

// Compress an image
const compressed = await kompreser.compress(fileInput.files[0]);
console.log(`Compressed from ${compressed.metadata.originalSize} to ${compressed.size} bytes`);
console.log(`Compression ratio: ${Math.round(compressed.metadata.compressionRatio * 100)}%`);

📖 Comprehensive Documentation

Supported Formats

Advanced Configuration

const kompreser = new Kompreser({
  // Compression settings
  quality: 0.85,                    // 0.0 - 1.0
  format: 'auto',                   // auto, jpeg, png, webp, avif
  progressive: true,                // Enable progressive encoding
  
  // Performance settings
  useWorkers: true,                 // Use Web Workers
  maxWorkers: 8,                    // Maximum worker threads
  batchSize: 10,                    // Batch processing size
  memoryLimit: 512 * 1024 * 1024,   // 512MB memory limit
  
  // Advanced features
  enableAI: false,                  // AI-powered optimization
  enableWebAssembly: true,          // Use WASM for performance
  enableStreaming: true,            // Streaming compression
  enableCaching: true,              // Enable result caching
  
  // Error handling
  enableRecovery: true,             // Automatic error recovery
  maxRetries: 3,                    // Maximum retry attempts
  
  // Security settings
  maxFileSize: 50 * 1024 * 1024,    // 50MB file size limit
  sanitizeMetadata: false,          // Remove sensitive metadata
  
  // Logging
  logLevel: 'INFO',                 // DEBUG, INFO, WARN, ERROR
  enablePerformanceTracking: true    // Performance monitoring
});

🎯 Advanced Features

1. Batch Processing

// Compress multiple images at once
const results = await kompreser.compressBatch(files, {
  quality: 0.8,
  format: 'webp'
});

results.forEach((result, index) => {
  if (result.success) {
    console.log(`Image ${index}: ${result.compressionRatio}% reduction`);
  } else {
    console.error(`Image ${index} failed:`, result.error);
  }
});

2. Format Conversion

// Convert between formats
const webpImage = await kompreser.convert(pngFile, 'webp', {
  quality: 0.9
});

const avifImage = await kompreser.convert(jpegFile, 'avif', {
  quality: 0.85
});

3. Progressive JPEG

// Create progressive JPEG for better web performance
const progressiveJPEG = await kompreser.createProgressive(imageFile, {
  quality: 0.9,
  scans: 3 // Number of progressive scans
});

4. Web Optimization

// Optimize specifically for web delivery
const webOptimized = await kompreser.optimizeForWeb(imageFile, {
  targetFormat: 'webp',  // Use WebP with fallbacks
  maxWidth: 1920,        // Responsive sizing
  maxHeight: 1080,
  metadata: 'none'       // Strip metadata for smaller size
});

5. Custom Compression Strategies

// Define custom compression strategies
const strategies = {
  thumbnail: {
    quality: 0.7,
    format: 'webp',
    maxWidth: 300,
    maxHeight: 300
  },
  hero: {
    quality: 0.95,
    format: 'avif',
    progressive: true
  },
  gallery: {
    quality: 0.85,
    format: 'auto',
    enableWebAssembly: true
  }
};

const thumbnail = await kompreser.compress(imageFile, strategies.thumbnail);

🛠️ Error Handling & Recovery

try {
  const result = await kompreser.compress(largeImageFile);
  console.log('Compression successful:', result);
} catch (error) {
  if (error.code === 'MEMORY_ERROR') {
    console.warn('Not enough memory, trying with lower quality...');
    const fallback = await kompreser.compress(largeImageFile, {
      quality: 0.6,
      batchSize: 5
    });
  } else if (error.code === 'FORMAT_ERROR') {
    console.error('Unsupported format:', error.format);
  } else {
    console.error('Compression failed:', error.message);
  }
}

📊 Performance Monitoring

// Get performance statistics
const stats = await kompreser.getPerformanceStats();
console.log('Performance Report:', {
  totalProcessed: stats.logger.operations.totalOperations,
  averageTime: stats.logger.operations.avgDuration,
  memoryUsage: stats.logger.memoryUsage,
  cacheHitRate: stats.cache?.hitRate || 0
});

// Export detailed logs
const logs = kompreser.logger.exportLogs({
  level: 'WARN',
  since: new Date(Date.now() - 24 * 60 * 60 * 1000) // Last 24 hours
});

🔧 Module System Support

ES Modules

import Kompreser from '@xbibzlibrary/kompreser';
const kompreser = new Kompreser();

CommonJS

const Kompreser = require('@xbibzlibrary/kompreser');
const kompreser = new Kompreser();

UMD (Browser)

<script src="https://unpkg.com/@xbibzlibrary/kompreser/dist/kompreser.umd.js"></script>
<script>
  const kompreser = new Kompreser();
</script>

TypeScript

import Kompreser, { KompreserOptions, CompressionResult } from '@xbibzlibrary/kompreser';

const options: KompreserOptions = {
  quality: 0.8,
  format: 'webp'
};

const kompreser = new Kompreser(options);

🧪 Advanced Examples

Real-time Image Processing

class ImageProcessor {
  constructor() {
    this.kompreser = new Kompreser({
      useWorkers: true,
      maxWorkers: 4
    });
  }

  async processUserUpload(file) {
    // Validate file
    const validation = await this.kompreser.validator.validateInput(file);
    if (!validation.valid) {
      throw new Error(`Invalid file: ${validation.errors.join(', ')}`);
    }

    // Create multiple variants
    const variants = await Promise.all([
      // Thumbnail
      this.kompreser.compress(file, {
        maxWidth: 300,
        maxHeight: 300,
        quality: 0.7,
        format: 'webp'
      }),
      
      // Medium size
      this.kompreser.compress(file, {
        maxWidth: 1200,
        maxHeight: 800,
        quality: 0.85,
        format: 'webp'
      }),
      
      // Original quality
      this.kompreser.compress(file, {
        quality: 0.95,
        format: 'avif'
      })
    ]);

    return {
      thumbnail: variants[0],
      medium: variants[1],
      original: variants[2]
    };
  }
}

Progressive Web App Integration

// Service Worker for offline image processing
self.addEventListener('install', event => {
  self.skipWaiting();
});

self.addEventListener('activate', event => {
  event.waitUntil(self.clients.claim());
});

self.addEventListener('message', async event => {
  if (event.data.type === 'COMPRESS_IMAGE') {
    try {
      const kompreser = new Kompreser();
      const result = await kompreser.compress(event.data.file);
      
      event.ports[0].postMessage({
        type: 'COMPRESSION_COMPLETE',
        result
      });
    } catch (error) {
      event.ports[0].postMessage({
        type: 'COMPRESSION_ERROR',
        error: error.message
      });
    }
  }
});

🎨 Browser Compatibility

🏗️ Development

Building from Source

# Clone the repository
git clone https://github.com/XbibzOfficial777/kompreser.git
cd kompreser

# Install dependencies
npm install

# Build all versions
npm run build

# Run tests
npm test

# Run performance benchmarks
npm run test:performance

# Start development server
npm run dev

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run performance benchmarks
npm run test:performance

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

🙏 Acknowledgments

• Author: Xbibz Official
• Special Thanks: All contributors and the open-source community
• Inspiration: Modern web performance optimization techniques