@bernierllc/image-processor

Image processing utilities for resizing, cropping, format conversion, and optimization with built-in support for social media aspect ratios.

Installation

``bash
npm install @bernierllc/image-processor
`

Features

- Image Transformations: Resize, crop, and optimize images
- Format Conversion: Convert between JPEG, PNG, WebP, and AVIF
- Social Media Presets: Built-in aspect ratios for Instagram, Twitter, Facebook, LinkedIn, and YouTube
- Thumbnail Generation: Create square thumbnails from any image
- Quality Optimization: Reduce file size while maintaining visual quality
- Metadata Extraction: Retrieve image dimensions, format, and properties
- Logger Integration: Built-in logging with @bernierllc/logger
- Type-Safe: Full TypeScript support with strict typing

Usage

$3

`typescript
import { ImageProcessor } from '@bernierllc/image-processor';
import fs from 'fs';

const processor = new ImageProcessor();

// Read an image
const imageBuffer = fs.readFileSync('photo.jpg');

// Resize image
const resized = await processor.resize(imageBuffer, {
width: 800,
height: 600
});

if (resized.success) {
fs.writeFileSync('photo-resized.jpg', resized.data!);
console.log('Dimensions:', resized.metadata);
}
`

$3

`typescript
// Resize to specific dimensions
const result = await processor.resize(imageBuffer, {
width: 1200,
height: 800
});

// Resize by width only (maintains aspect ratio)
const widthOnly = await processor.resize(imageBuffer, {
width: 1000
});

// Resize by height only (maintains aspect ratio)
const heightOnly = await processor.resize(imageBuffer, {
height: 600
});

// Resize with fit option
const covered = await processor.resize(imageBuffer, {
width: 800,
height: 800,
fit: 'cover' // Options: cover, contain, fill, inside, outside
});
`

$3

`typescript
// Crop to specific dimensions
const cropped = await processor.crop(imageBuffer, {
width: 1080,
height: 1080,
position: 'center' // center, top, bottom, left, right, top-left, etc.
});

// Crop from different positions
const topCrop = await processor.crop(imageBuffer, {
width: 500,
height: 500,
position: 'top'
});
`

$3

`typescript
// Instagram square (1:1 - 1080x1080)
const instagramSquare = await processor.cropForSocialMedia(
imageBuffer,
'instagram-square'
);

// Instagram portrait (4:5 - 1080x1350)
const instagramPortrait = await processor.cropForSocialMedia(
imageBuffer,
'instagram-portrait'
);

// Instagram story (9:16 - 1080x1920)
const instagramStory = await processor.cropForSocialMedia(
imageBuffer,
'instagram-story'
);

// Twitter post (16:9 - 1200x675)
const twitterPost = await processor.cropForSocialMedia(
imageBuffer,
'twitter-post'
);

// Facebook cover (2.7:1 - 820x312)
const facebookCover = await processor.cropForSocialMedia(
imageBuffer,
'facebook-cover'
);

// YouTube thumbnail (16:9 - 1280x720)
const youtubeThumbnail = await processor.cropForSocialMedia(
imageBuffer,
'youtube-thumbnail'
);
`

$3

`typescript
// Convert to WebP
const webp = await processor.toFormat(imageBuffer, {
format: 'webp',
quality: 85
});

// Convert to PNG
const png = await processor.toFormat(imageBuffer, {
format: 'png',
quality: 90
});

// Convert with metadata stripping
const jpeg = await processor.toFormat(imageBuffer, {
format: 'jpeg',
quality: 80,
stripMetadata: true
});

// Convert to AVIF (modern format with excellent compression)
const avif = await processor.toFormat(imageBuffer, {
format: 'avif',
quality: 75
});
`

$3

`typescript
// Optimize with quality reduction
const optimized = await processor.optimize(imageBuffer, {
quality: 75
});

// Optimize with format conversion
const optimizedWebP = await processor.optimize(imageBuffer, {
quality: 80,
format: 'webp'
});

// Optimize and keep metadata
const optimizedWithMetadata = await processor.optimize(imageBuffer, {
quality: 85,
stripMetadata: false
});
`

$3

`typescript
// Generate 200x200 square thumbnail
const thumbnail = await processor.thumbnail(imageBuffer, 200);

// Generate smaller thumbnail
const smallThumb = await processor.thumbnail(imageBuffer, 100);
`

$3

`typescript
const metadata = await processor.getMetadata(imageBuffer);

if (metadata.success) {
console.log('Width:', metadata.metadata?.width);
console.log('Height:', metadata.metadata?.height);
console.log('Format:', metadata.metadata?.format);
console.log('File size:', metadata.metadata?.size, 'bytes');
console.log('Has alpha:', metadata.metadata?.hasAlpha);
}
`

$3

`typescript
import {
getSocialMediaDimensions,
isValidPreset,
SOCIAL_MEDIA_PRESETS
} from '@bernierllc/image-processor';

// Get dimensions for a preset
const dimensions = getSocialMediaDimensions('instagram-square');
console.log(dimensions); // { width: 1080, height: 1080, aspectRatio: '1:1' }

// Check if preset is valid
if (isValidPreset('twitter-post')) {
const dims = getSocialMediaDimensions('twitter-post');
console.log('Valid preset:', dims);
}

// Access all presets
console.log(SOCIAL_MEDIA_PRESETS);
`

$3

All methods return a ProcessResult object with error handling:

`typescript
const result = await processor.resize(imageBuffer, {
width: 800,
height: 600
});

if (result.success) {
console.log('Success!');
console.log('Data:', result.data);
console.log('Metadata:', result.metadata);
} else {
console.error('Error:', result.error);
}
`

API Reference

$3

Main class for image processing operations.

#### Methods

##### resize(input: Buffer, options: ResizeOptions): Promise

Resize an image to specified dimensions.

Options:
- width?: number - Target width in pixels
- height?: number - Target height in pixels
- fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside' - How to fit image (default: 'inside')
- withoutEnlargement?: boolean - Prevent enlarging small images (default: false)

##### crop(input: Buffer, options: CropOptions): Promise

Crop an image to specific dimensions.

Options:
- width: number - Target width in pixels
- height: number - Target height in pixels
- position?: CropPosition - Position to crop from (default: 'center')

##### cropForSocialMedia(input: Buffer, preset: SocialMediaAspectRatio): Promise

Crop an image for a social media platform using preset dimensions.

Presets:
- instagram-square (1:1 - 1080x1080)
- instagram-portrait (4:5 - 1080x1350)
- instagram-landscape (1.91:1 - 1080x566)
- instagram-story (9:16 - 1080x1920)
- twitter-post (16:9 - 1200x675)
- twitter-header (3:1 - 1500x500)
- facebook-post (1.91:1 - 1200x628)
- facebook-cover (2.7:1 - 820x312)
- linkedin-post (1.91:1 - 1200x627)
- youtube-thumbnail (16:9 - 1280x720)

##### toFormat(input: Buffer, options: FormatOptions): Promise

Convert an image to a different format.

Options:
- format: ImageFormat - Output format ('jpeg', 'png', 'webp', 'avif')
- quality?: number - Quality setting (1-100, format dependent)
- stripMetadata?: boolean - Whether to strip metadata (default: false)

##### optimize(input: Buffer, options: OptimizeOptions): Promise

Optimize an image by reducing quality and/or file size.

Options:
- quality: number - Quality setting (1-100)
- stripMetadata?: boolean - Whether to strip metadata (default: true)
- format?: ImageFormat - Target format (default: original format)

##### thumbnail(input: Buffer, size: number): Promise

Generate a square thumbnail from an image.

Parameters:
- size: number - Thumbnail size in pixels (creates size x size image)

##### getMetadata(input: Buffer): Promise

Get metadata information from an image.

Returns metadata including:
- width: number - Image width in pixels
- height: number - Image height in pixels
- format: string - Image format
- size: number - File size in bytes
- space?: string - Color space
- channels?: number - Number of channels
- density?: number - Pixel density
- hasAlpha?: boolean - Whether image has alpha channel

$3

`typescript
type ImageFormat = 'jpeg' | 'png' | 'webp' | 'avif';

type CropPosition =
| 'center'
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'top-left'
| 'top-right'
| 'bottom-left'
| 'bottom-right';

type SocialMediaAspectRatio =
| 'instagram-square'
| 'instagram-portrait'
| 'instagram-landscape'
| 'instagram-story'
| 'twitter-post'
| 'twitter-header'
| 'facebook-post'
| 'facebook-cover'
| 'linkedin-post'
| 'youtube-thumbnail';

interface ProcessResult {
success: boolean;
data?: Buffer;
metadata?: ImageMetadata;
error?: string;
}

interface ImageMetadata {
width: number;
height: number;
format: string;
size: number;
space?: string;
channels?: number;
density?: number;
hasAlpha?: boolean;
}
`

Dependencies

- @bernierllc/logger - Logging integration
- sharp - High-performance image processing library

Integration Status

$3

Justification: This package uses @bernierllc/logger for operation logging. Image processing operations (resize, crop, convert) are logged with metadata including dimensions, formats, and processing times. This helps with debugging, performance monitoring, and tracking image processing workflows.

Pattern: Direct integration - logger is a required dependency for this package.

$3

`bash
npm test # Run tests in watch mode
npm run test:run # Run tests once
npm run test:coverage # Generate coverage report
`

Examples

$3

`typescript
async function processUserAvatar(uploadBuffer: Buffer) {
const processor = new ImageProcessor();

// Generate multiple sizes
const large = await processor.thumbnail(uploadBuffer, 512);
const medium = await processor.thumbnail(uploadBuffer, 256);
const small = await processor.thumbnail(uploadBuffer, 128);

// Optimize for web
const optimized = await processor.optimize(uploadBuffer, {
quality: 85,
format: 'webp'
});

return {
large: large.data,
medium: medium.data,
small: small.data,
optimized: optimized.data
};
}
`

$3

`typescript
async function createSocialMediaAssets(imageBuffer: Buffer) {
const processor = new ImageProcessor();

const assets = {
instagram: await processor.cropForSocialMedia(imageBuffer, 'instagram-square'),
twitter: await processor.cropForSocialMedia(imageBuffer, 'twitter-post'),
facebook: await processor.cropForSocialMedia(imageBuffer, 'facebook-post'),
youtube: await processor.cropForSocialMedia(imageBuffer, 'youtube-thumbnail')
};

// Convert all to WebP for optimal file size
for (const [platform, result] of Object.entries(assets)) {
if (result.success && result.data) {
const webp = await processor.toFormat(result.data, {
format: 'webp',
quality: 85
});
assets[platform] = webp;
}
}

return assets;
}
`

$3

`typescript
async function optimizeImageDirectory(inputDir: string, outputDir: string) {
const processor = new ImageProcessor();
const files = fs.readdirSync(inputDir);

for (const file of files) {
if (!file.match(/\.(jpg|jpeg|png)$/i)) continue;

const inputPath = path.join(inputDir, file);
const outputPath = path.join(outputDir, file.replace(/\.\w+$/, '.webp'));

const buffer = fs.readFileSync(inputPath);
const optimized = await processor.optimize(buffer, {
quality: 80,
format: 'webp'
});

if (optimized.success) {
fs.writeFileSync(outputPath, optimized.data!);
console.log(Optimized: ${file} -> ${path.basename(outputPath)});
}
}
}
`

Performance

The package uses the sharp` library, which provides:
- High-performance image processing
- Low memory usage
- Support for large images
- Hardware acceleration where available

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

See Also

- @bernierllc/logger - Logging utilities
- @bernierllc/media-manager - Media asset management (Wave 3)
- @bernierllc/social-media-instagram - Instagram integration (Wave 3)