bun-image-turbo 0.0.2-beta

package/README.md

@@ -0,0 +1,328 @@
+# bun-image-turbo
+
+High-performance image processing for Bun and Node.js, built with Rust and napi-rs.
+
+[![npm version](https://badge.fury.io/js/bun-image-turbo.svg)](https://www.npmjs.com/package/bun-image-turbo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Fast** - Built with Rust for maximum performance
+- **Modern Formats** - JPEG, PNG, WebP, GIF, BMP support
+- **Resize** - High-quality resizing with multiple algorithms (Lanczos3, Mitchell, etc.)
+- **Transform** - Rotate, flip, blur, sharpen, grayscale, brightness, contrast
+- **Blurhash** - Generate compact image placeholders
+- **Async & Sync** - Both async and sync APIs available
+- **TypeScript** - Full TypeScript support with strict types
+- **Cross-platform** - macOS, Linux, Windows support
+
+## Benchmarks
+
+Tested on Apple M1 Pro with Bun 1.3.3 (compared to sharp v0.34.5):
+
+### Metadata Extraction
+| Operation | bun-image-turbo | sharp | Speedup |
+|-----------|-----------------|-------|---------|
+| 1MB JPEG Metadata | 0.003ms | 0.1ms | **38x faster** |
+| 10MB JPEG Metadata | 0.003ms | 0.1ms | **37x faster** |
+| 10MB WebP Metadata | 0.003ms | 3.0ms | **950x faster** |
+
+### JPEG Resize (Real-world thumbnail generation)
+| Operation | bun-image-turbo | sharp | Speedup |
+|-----------|-----------------|-------|---------|
+| 1MB JPEG → 800px | 12.4ms | 20.0ms | **1.61x faster** |
+| 1MB JPEG → 400px | 9.9ms | 12.3ms | **1.24x faster** |
+| 1MB JPEG → 200px | 8.7ms | 10.5ms | **1.20x faster** |
+| 10MB JPEG → 800px | 96.9ms | 102.5ms | **1.06x faster** |
+
+### Format Conversion
+| Operation | bun-image-turbo | sharp | Speedup |
+|-----------|-----------------|-------|---------|
+| 1MB JPEG → WebP | 37.1ms | 45.8ms | **1.23x faster** |
+| 10MB JPEG → WebP | 114.9ms | 119.3ms | **1.04x faster** |
+
+### Complex Transform Pipeline
+| Operation | bun-image-turbo | sharp | Speedup |
+|-----------|-----------------|-------|---------|
+| Resize + Grayscale | 11.9ms | 18.1ms | **1.53x faster** |
+| Resize + Rotate + Grayscale | 12.3ms | 19.3ms | **1.57x faster** |
+
+### Concurrent Operations (High Load)
+| Concurrency | bun-image-turbo | sharp | Speedup |
+|-------------|-----------------|-------|---------|
+| 10 parallel | 16ms | 30ms | **1.85x faster** |
+| 25 parallel | 42ms | 82ms | **1.96x faster** |
+| 50 parallel | 67ms | 156ms | **2.33x faster** |
+| 100 parallel | 129ms | 303ms | **2.34x faster** |
+
+**Key Strengths:**
+- **950x faster** metadata extraction (header-only parsing)
+- **2.3x faster** under concurrent load
+- **1.6x faster** for thumbnail generation
+- **1.5x faster** for transform pipelines
+- Built-in **blurhash** generation
+- Uses **TurboJPEG** (libjpeg-turbo) with SIMD acceleration
+
+> Run benchmarks yourself: `bun run benchmarks/final_comparison.ts`
+
+## Installation
+
+```bash
+# Using Bun (recommended)
+bun add bun-image-turbo
+
+# Using npm
+npm install bun-image-turbo
+
+# Using yarn
+yarn add bun-image-turbo
+
+# Using pnpm
+pnpm add bun-image-turbo
+```
+
+## Quick Start
+
+```typescript
+import { resize, toWebp, metadata, transform } from 'bun-image-turbo';
+
+// Read image
+const input = await Bun.file('input.jpg').arrayBuffer();
+const buffer = Buffer.from(input);
+
+// Get metadata
+const info = await metadata(buffer);
+console.log(`${info.width}x${info.height} ${info.format}`);
+
+// Resize image
+const resized = await resize(buffer, { width: 800 });
+
+// Convert to WebP
+const webp = await toWebp(buffer, { quality: 85 });
+
+// Apply multiple transformations
+const result = await transform(buffer, {
+  resize: { width: 400, height: 300 },
+  rotate: 90,
+  grayscale: true,
+  output: { format: 'webp', webp: { quality: 80 } }
+});
+
+// Save result
+await Bun.write('output.webp', result);
+```
+
+## API Reference
+
+### `metadata(input)` / `metadataSync(input)`
+
+Get image metadata.
+
+```typescript
+const info = await metadata(imageBuffer);
+// { width: 1920, height: 1080, format: 'jpeg', hasAlpha: false, ... }
+```
+
+### `resize(input, options)` / `resizeSync(input, options)`
+
+Resize an image.
+
+```typescript
+// Resize by width (maintains aspect ratio)
+const resized = await resize(imageBuffer, { width: 800 });
+
+// Resize by height
+const resized = await resize(imageBuffer, { height: 600 });
+
+// Resize with specific dimensions
+const resized = await resize(imageBuffer, {
+  width: 800,
+  height: 600,
+  fit: 'cover',      // 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
+  filter: 'lanczos3' // 'nearest' | 'bilinear' | 'catmullRom' | 'mitchell' | 'lanczos3'
+});
+```
+
+### `toJpeg(input, options?)` / `toJpegSync(input, options?)`
+
+Convert to JPEG.
+
+```typescript
+const jpeg = await toJpeg(imageBuffer, { quality: 85 });
+```
+
+### `toPng(input, options?)` / `toPngSync(input, options?)`
+
+Convert to PNG.
+
+```typescript
+const png = await toPng(imageBuffer, { compression: 6 });
+```
+
+### `toWebp(input, options?)` / `toWebpSync(input, options?)`
+
+Convert to WebP.
+
+```typescript
+// Lossy WebP
+const webp = await toWebp(imageBuffer, { quality: 80 });
+
+// Lossless WebP
+const lossless = await toWebp(imageBuffer, { lossless: true });
+```
+
+### `transform(input, options)` / `transformSync(input, options)`
+
+Apply multiple transformations in a single operation (most efficient).
+
+```typescript
+const result = await transform(imageBuffer, {
+  // Resize
+  resize: { width: 800, height: 600, fit: 'cover' },
+
+  // Transformations
+  rotate: 90,        // 90, 180, or 270 degrees
+  flipH: true,       // Flip horizontally
+  flipV: false,      // Flip vertically
+  grayscale: true,   // Convert to grayscale
+  blur: 5,           // Blur radius (0-100)
+  sharpen: 10,       // Sharpen amount (0-100)
+  brightness: 10,    // Brightness (-100 to 100)
+  contrast: 5,       // Contrast (-100 to 100)
+
+  // Output format
+  output: {
+    format: 'webp',
+    webp: { quality: 85 }
+  }
+});
+```
+
+### `blurhash(input, componentsX?, componentsY?)` / `blurhashSync(...)`
+
+Generate a blurhash placeholder string.
+
+```typescript
+const { hash, width, height } = await blurhash(imageBuffer, 4, 3);
+console.log(hash); // "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
+```
+
+### `version()`
+
+Get library version.
+
+```typescript
+console.log(version()); // "1.0.0"
+```
+
+## Options
+
+### Resize Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `width` | `number` | - | Target width (optional if height provided) |
+| `height` | `number` | - | Target height (optional if width provided) |
+| `filter` | `string` | `'lanczos3'` | Resize algorithm |
+| `fit` | `string` | `'cover'` | How to fit the image |
+
+### Filter Types
+
+- `nearest` - Fastest, lowest quality
+- `bilinear` - Fast, good quality
+- `catmullRom` - Balanced speed and quality
+- `mitchell` - Good for downscaling
+- `lanczos3` - Highest quality, slower (default)
+
+### Fit Modes
+
+- `cover` - Resize to cover target dimensions (may crop)
+- `contain` - Resize to fit within target (may have padding)
+- `fill` - Resize to exact dimensions (may distort)
+- `inside` - Resize only if larger than target
+- `outside` - Resize only if smaller than target
+
+### JPEG Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `quality` | `number` | `80` | Quality 1-100 |
+
+### PNG Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `compression` | `number` | `6` | Compression level 0-9 |
+
+### WebP Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `quality` | `number` | `80` | Quality 1-100 (lossy) |
+| `lossless` | `boolean` | `false` | Use lossless compression |
+
+## Supported Formats
+
+| Format | Read | Write |
+|--------|------|-------|
+| JPEG | Yes | Yes |
+| PNG | Yes | Yes |
+| WebP | Yes | Yes |
+| GIF | Yes | Yes |
+| BMP | Yes | Yes |
+| ICO | Yes | No |
+| TIFF | Yes | No |
+
+## Supported Platforms
+
+| Platform | Architecture | Support |
+|----------|--------------|---------|
+| macOS | ARM64 (M1/M2/M3) | Yes |
+| macOS | x64 (Intel) | Yes |
+| Linux | x64 (glibc) | Yes |
+| Linux | x64 (musl/Alpine) | Yes |
+| Linux | ARM64 (glibc) | Yes |
+| Linux | ARM64 (musl) | Yes |
+| Windows | x64 | Yes |
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/nexus-aissam/bun-image-turbo.git
+cd bun-image-turbo
+
+# Install dependencies
+bun install
+
+# Build native module (requires Rust)
+bun run build
+
+# Build TypeScript
+bun run build:ts
+
+# Run tests
+bun test
+```
+
+### Requirements
+
+- Bun 1.0+ or Node.js 18+
+- Rust 1.70+ (for building from source)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Author
+
+Aissam Irhir ([@nexus-aissam](https://github.com/nexus-aissam))
+
+## Acknowledgments
+
+- [turbojpeg](https://crates.io/crates/turbojpeg) - libjpeg-turbo bindings with SIMD
+- [image](https://crates.io/crates/image) - Rust image processing library
+- [fast_image_resize](https://crates.io/crates/fast_image_resize) - Fast image resizing
+- [webp](https://crates.io/crates/webp) - WebP encoding/decoding
+- [blurhash](https://crates.io/crates/blurhash) - Blurhash generation
+- [napi-rs](https://napi.rs/) - Rust bindings for Node.js

package/dist/index.d.mts

@@ -0,0 +1,327 @@
+/**
+ * bun-image-turbo Types
+ */
+/** Supported image formats */
+type ImageFormat = 'jpeg' | 'png' | 'webp' | 'gif' | 'bmp' | 'ico' | 'tiff' | 'avif';
+/** Resize filter/algorithm */
+type ResizeFilter = 'nearest' | 'bilinear' | 'catmullRom' | 'mitchell' | 'lanczos3';
+/** Image fit mode for resize */
+type FitMode = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+/** Resize options */
+interface ResizeOptions {
+    /** Target width (optional if height is provided) */
+    width?: number;
+    /** Target height (optional if width is provided) */
+    height?: number;
+    /** Resize filter/algorithm (default: lanczos3) */
+    filter?: ResizeFilter;
+    /** Fit mode (default: cover) */
+    fit?: FitMode;
+    /** Background color for padding [r, g, b, a] (default: transparent) */
+    background?: number[];
+}
+/** JPEG encode options */
+interface JpegOptions {
+    /** Quality 1-100 (default: 80) */
+    quality?: number;
+}
+/** PNG encode options */
+interface PngOptions {
+    /** Compression level 0-9 (default: 6) */
+    compression?: number;
+}
+/** WebP encode options */
+interface WebPOptions {
+    /** Quality 1-100 for lossy, ignored for lossless (default: 80) */
+    quality?: number;
+    /** Use lossless compression (default: false) */
+    lossless?: boolean;
+}
+/** AVIF encode options */
+interface AvifOptions {
+    /** Quality 1-100 (default: 80) */
+    quality?: number;
+    /** Speed 1-10, higher is faster but lower quality (default: 6) */
+    speed?: number;
+}
+/** Output format options */
+interface OutputOptions {
+    /** Output format */
+    format: ImageFormat;
+    /** JPEG options (if format is jpeg) */
+    jpeg?: JpegOptions;
+    /** PNG options (if format is png) */
+    png?: PngOptions;
+    /** WebP options (if format is webp) */
+    webp?: WebPOptions;
+    /** AVIF options (if format is avif) */
+    avif?: AvifOptions;
+}
+/** Image metadata (sharp-compatible) */
+interface ImageMetadata {
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Detected format (jpeg, png, webp, gif, bmp, ico, tiff) */
+    format: string;
+    /** File size in bytes */
+    size?: number;
+    /** Color space (srgb, rgb, grayscale) */
+    space: string;
+    /** Number of channels (1, 2, 3, or 4) */
+    channels: number;
+    /** Bit depth per sample (uchar = 8-bit, ushort = 16-bit) */
+    depth: string;
+    /** Whether the image has an alpha channel */
+    hasAlpha: boolean;
+    /** Bits per sample */
+    bitsPerSample: number;
+    /** Whether the image is progressive (JPEG) or interlaced (PNG) */
+    isProgressive: boolean;
+    /** Whether the image uses palette/indexed colors (PNG/GIF) */
+    isPalette: boolean;
+    /** Whether the image has an embedded ICC profile */
+    hasProfile: boolean;
+    /** EXIF orientation value (1-8, if present) */
+    orientation?: number;
+    /** Page/frame count for multi-page images (GIF, TIFF) */
+    pages?: number;
+    /** Loop count for animated images */
+    loopCount?: number;
+    /** Delay between frames in ms (for animated images) */
+    delay?: number[];
+    /** Background color (for GIF) */
+    background?: number[];
+    /** Compression type used */
+    compression?: string;
+    /** Density/DPI info */
+    density?: number;
+}
+/** Blurhash result */
+interface BlurHashResult {
+    /** The blurhash string */
+    hash: string;
+    /** Original width */
+    width: number;
+    /** Original height */
+    height: number;
+}
+/** Transform options (all-in-one processing) */
+interface TransformOptions {
+    /** Resize options */
+    resize?: ResizeOptions;
+    /** Output options */
+    output?: OutputOptions;
+    /** Rotate degrees (90, 180, 270) */
+    rotate?: number;
+    /** Flip horizontally */
+    flipH?: boolean;
+    /** Flip vertically */
+    flipV?: boolean;
+    /** Grayscale conversion */
+    grayscale?: boolean;
+    /** Blur radius (0-100) */
+    blur?: number;
+    /** Sharpen amount (0-100) */
+    sharpen?: number;
+    /** Brightness adjustment (-100 to 100) */
+    brightness?: number;
+    /** Contrast adjustment (-100 to 100) */
+    contrast?: number;
+}
+
+/**
+ * bun-image-turbo - High-performance image processing for Bun and Node.js
+ *
+ * @module bun-image-turbo
+ * @author Aissam Irhir <aissamirhir@gmail.com>
+ *
+ * @example
+ * ```typescript
+ * import { resize, toWebp, metadata } from 'bun-image-turbo';
+ *
+ * // Read image
+ * const input = await Bun.file('input.jpg').arrayBuffer();
+ *
+ * // Resize image
+ * const resized = await resize(Buffer.from(input), { width: 800, height: 600 });
+ *
+ * // Convert to WebP
+ * const webp = await toWebp(Buffer.from(input), { quality: 85 });
+ *
+ * // Get metadata
+ * const info = await metadata(Buffer.from(input));
+ * console.log(info.width, info.height, info.format);
+ * ```
+ */
+
+/**
+ * Get image metadata asynchronously
+ *
+ * @param input - Image buffer
+ * @returns Promise resolving to image metadata
+ *
+ * @example
+ * ```typescript
+ * const info = await metadata(imageBuffer);
+ * console.log(`${info.width}x${info.height} ${info.format}`);
+ * ```
+ */
+declare function metadata(input: Buffer): Promise<ImageMetadata>;
+/**
+ * Resize image asynchronously
+ *
+ * @param input - Image buffer
+ * @param options - Resize options
+ * @returns Promise resolving to resized image buffer (PNG)
+ *
+ * @example
+ * ```typescript
+ * // Resize to specific dimensions
+ * const resized = await resize(imageBuffer, { width: 800, height: 600 });
+ *
+ * // Resize maintaining aspect ratio
+ * const thumb = await resize(imageBuffer, { width: 200 });
+ *
+ * // High-quality resize
+ * const hq = await resize(imageBuffer, {
+ *   width: 1920,
+ *   filter: 'lanczos3',
+ *   fit: 'contain'
+ * });
+ * ```
+ */
+declare function resize(input: Buffer, options: ResizeOptions): Promise<Buffer>;
+/**
+ * Convert image to JPEG asynchronously
+ *
+ * @param input - Image buffer
+ * @param options - JPEG encoding options
+ * @returns Promise resolving to JPEG buffer
+ *
+ * @example
+ * ```typescript
+ * const jpeg = await toJpeg(imageBuffer, { quality: 85 });
+ * ```
+ */
+declare function toJpeg(input: Buffer, options?: JpegOptions): Promise<Buffer>;
+/**
+ * Convert image to PNG asynchronously
+ *
+ * @param input - Image buffer
+ * @param options - PNG encoding options
+ * @returns Promise resolving to PNG buffer
+ *
+ * @example
+ * ```typescript
+ * const png = await toPng(imageBuffer, { compression: 9 });
+ * ```
+ */
+declare function toPng(input: Buffer, options?: PngOptions): Promise<Buffer>;
+/**
+ * Convert image to WebP asynchronously
+ *
+ * @param input - Image buffer
+ * @param options - WebP encoding options
+ * @returns Promise resolving to WebP buffer
+ *
+ * @example
+ * ```typescript
+ * // Lossy WebP
+ * const webp = await toWebp(imageBuffer, { quality: 80 });
+ *
+ * // Lossless WebP
+ * const lossless = await toWebp(imageBuffer, { lossless: true });
+ * ```
+ */
+declare function toWebp(input: Buffer, options?: WebPOptions): Promise<Buffer>;
+/**
+ * Transform image with multiple operations asynchronously
+ *
+ * This is the most efficient way to apply multiple transformations
+ * as it processes the image only once.
+ *
+ * @param input - Image buffer
+ * @param options - Transform options
+ * @returns Promise resolving to transformed image buffer
+ *
+ * @example
+ * ```typescript
+ * const result = await transform(imageBuffer, {
+ *   resize: { width: 800, height: 600 },
+ *   rotate: 90,
+ *   grayscale: true,
+ *   output: { format: 'webp', webp: { quality: 85 } }
+ * });
+ * ```
+ */
+declare function transform(input: Buffer, options: TransformOptions): Promise<Buffer>;
+/**
+ * Generate blurhash from image asynchronously
+ *
+ * Blurhash is a compact representation of a placeholder for an image.
+ *
+ * @param input - Image buffer
+ * @param componentsX - Number of X components (default: 4)
+ * @param componentsY - Number of Y components (default: 3)
+ * @returns Promise resolving to blurhash result
+ *
+ * @example
+ * ```typescript
+ * const { hash, width, height } = await blurhash(imageBuffer);
+ * console.log(hash); // "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
+ * ```
+ */
+declare function blurhash(input: Buffer, componentsX?: number, componentsY?: number): Promise<BlurHashResult>;
+/**
+ * Get image metadata synchronously
+ */
+declare function metadataSync(input: Buffer): ImageMetadata;
+/**
+ * Resize image synchronously
+ */
+declare function resizeSync(input: Buffer, options: ResizeOptions): Buffer;
+/**
+ * Convert image to JPEG synchronously
+ */
+declare function toJpegSync(input: Buffer, options?: JpegOptions): Buffer;
+/**
+ * Convert image to PNG synchronously
+ */
+declare function toPngSync(input: Buffer, options?: PngOptions): Buffer;
+/**
+ * Convert image to WebP synchronously
+ */
+declare function toWebpSync(input: Buffer, options?: WebPOptions): Buffer;
+/**
+ * Transform image with multiple operations synchronously
+ */
+declare function transformSync(input: Buffer, options: TransformOptions): Buffer;
+/**
+ * Generate blurhash from image synchronously
+ */
+declare function blurhashSync(input: Buffer, componentsX?: number, componentsY?: number): BlurHashResult;
+/**
+ * Get library version
+ */
+declare function version(): string;
+declare const _default: {
+    metadata: typeof metadata;
+    metadataSync: typeof metadataSync;
+    resize: typeof resize;
+    resizeSync: typeof resizeSync;
+    toJpeg: typeof toJpeg;
+    toJpegSync: typeof toJpegSync;
+    toPng: typeof toPng;
+    toPngSync: typeof toPngSync;
+    toWebp: typeof toWebp;
+    toWebpSync: typeof toWebpSync;
+    transform: typeof transform;
+    transformSync: typeof transformSync;
+    blurhash: typeof blurhash;
+    blurhashSync: typeof blurhashSync;
+    version: typeof version;
+};
+
+export { type AvifOptions, type BlurHashResult, type FitMode, type ImageFormat, type ImageMetadata, type JpegOptions, type OutputOptions, type PngOptions, type ResizeFilter, type ResizeOptions, type TransformOptions, type WebPOptions, blurhash, blurhashSync, _default as default, metadata, metadataSync, resize, resizeSync, toJpeg, toJpegSync, toPng, toPngSync, toWebp, toWebpSync, transform, transformSync, version };