npm package: @iamasek/optim
Description: Fast local image optimization for WebP
Author: iamasek
Latest version: 1.0.0

# @iamasek/optim

Fast local image optimization for WebP with beautiful ASCII progress bars.

## Features

- 🚀 **Fast parallel processing** - Processes multiple images concurrently
- 🎨 **Real-time progress bars** - Overall progress + individual file progress
- 🖼️ **Smart format selection** - Automatically picks WebP or original format based on size
- 🎯 **Quality/Speed balance** - Optimized for both quality (82% default) and speed
- 📊 **Detailed reporting** - Shows savings, file sizes, and compression ratios
- 🔧 **Flexible options** - Quality, width, output directory, recursive mode, and more

## Installation

```bash
npm install -g @iamasek/optim
# or
yarn global add @iamasek/optim
```

## Usage

### Basic Usage

```bash
# Optimize images in current directory
optim

# Optimize specific directory
optim ./images

# Recursive optimization
optim ./images -r
```

### Advanced Options

```bash
# Custom quality and max width
optim ./images -q 85 -w 1920

# Output to different directory
optim ./images -o ./optimized

# Dry run (preview without changes)
optim ./images --dry-run

# Verbose output (show all processed files)
optim ./images -v

# Custom concurrency (number of parallel workers)
optim ./images -c 4
```

### All Options

```
Options:
  -q, --quality <number>      WebP quality (1-100) (default: 82)
  -w, --width <number>        Max width in pixels (default: 1920)
  -o, --output <path>         Output directory (default: in-place)
  -r, --recursive             Process subdirectories
  -c, --concurrency <number>  Concurrent files to process (default: CPU cores - 1)
  --dry-run                   Preview without making changes
  -v, --verbose               Show detailed output
  -h, --help                  Display help
```

## Programmatic Usage

You can also use `@iamasek/optim` as a library in your Node.js projects:

```typescript
import { optimizeImage, processFiles, scanDirectory } from '@iamasek/optim';

const files = await scanDirectory('./images', { recursive: true });

const summary = await processFiles(files, './images', {
  quality: 82,
  maxWidth: 1920,
  outputDir: './optimized',
  recursive: true,
  preserveNames: false,
  overwrite: true,
  dryRun: false,
  verbose: false,
  concurrency: 4,
});

console.log(`Saved ${summary.totalSavedBytes} bytes`);
```

## How It Works

1. **Scans directory** for images (jpg, jpeg, png, gif, tiff, webp, avif)
2. **Processes in parallel** with configurable concurrency
3. **Smart optimization**:
   - Generates WebP version at specified quality
   - For PNG with transparency, also generates optimized PNG
   - Compares file sizes and picks the smaller one
   - Skips conversion if result would be larger than original
4. **Real-time progress** with ASCII progress bars
5. **Detailed summary** showing total savings and statistics

## Output Example

```
  optim v1.0.0

  Scanning /path/to/images...
  Found 124 images (45.2 MB)
  Quality: 82 | Max width: 1920px | Workers: 7


  Overall   ██████████████████████████████  85% (105/124)

  photo1.jpg            ████████████████████  100%
  banner.png            ████████████░░░░░░░░   65%
  logo.svg              ██████░░░░░░░░░░░░░░   30%


  ✓ Complete!

  Files:     118 optimized, 5 skipped, 1 errors
  Size:      45.2 MB → 18.7 MB
  Saved:     26.5 MB (58% reduction)
```

## Algorithm Details

### Quality/Speed Balance

- **WebP Quality**: Default 82% provides excellent quality with significant size reduction
- **Max Width**: Default 1920px covers most modern displays
- **Parallel Processing**: Uses CPU cores - 1 for optimal performance
- **Smart Format Selection**: Preserves PNG for small transparent images (logos, icons)

### Optimization Strategy

```
For each image:
1. Read metadata (width, height, format, transparency)
2. Resize if width > maxWidth (preserving aspect ratio)
3. Generate WebP at specified quality
4. If PNG with alpha channel:
   - Also generate optimized PNG (compression level 9)
5. Compare file sizes:
   - Pick smaller of WebP vs original format
   - Skip if result >= original size (no degradation)
6. Write optimized file
```

## License

MIT

## Author

iamasek