file-adapters

Original：🇺🇸 English
Translated

Image file processing utilities (圖像檔案處理工具). Use when working with image resizing (圖片縮放), format conversion (格式轉換), watermarks (浮水印), or processing pipelines (處理管道). Covers Sharp integration, Buffer/Stream handling (緩衝/串流處理), batch processing (批次處理), and NestJS integration (NestJS 整合).

8installs
Sourcerytass/utils
Added on

NPX Install

npx skill4agent add rytass/utils file-adapters

Tags

Translated version includes tags in frontmatter
image-processingfile-convertersharp-librarybatch-processingnestjs-integration

SKILL.md Content

View Translation Comparison →

File Converter Adapters

This skill provides comprehensive guidance for using 
@rytass/file-converter
packages to process images with resizing, format conversion, watermarking, and pipeline processing.

Overview

All adapters implement the 
FileConverter
interface from 
@rytass/file-converter
, providing a unified API for image processing:
PackageFunctionBased On
@rytass/file-converter
Core interfaces and pipeline manager (核心介面與管道管理器)TypeScript interfaces
@rytass/file-converter-adapter-image-resizer
Image resizing (圖像縮放)Sharp ^0.34.5
@rytass/file-converter-adapter-image-transcoder
Format conversion (格式轉換)Sharp ^0.34.5, file-type ^21.1.1
@rytass/file-converter-adapter-image-watermark
Watermark overlay (浮水印疊加)Sharp ^0.34.5

Base Interface (@rytass/file-converter)

All adapters share these core concepts:
FileConverter<O> - Main interface for file conversion
typescript
interface FileConverter<O = Record<string, unknown>> {
  convert<Buffer>(file: ConvertableFile): Promise<Buffer>;
  convert<Readable>(file: ConvertableFile): Promise<Readable>;
}
ConvertableFile - Supported input types
typescript
type ConvertableFile = Readable | Buffer;
ConverterManager - Pipeline processor for chaining conversions
typescript
class ConverterManager {
  constructor(converters: FileConverter[]);
  convert<Output>(file: ConvertableFile): Promise<Output>;
}

Installation

bash
# Install base package
npm install @rytass/file-converter

# Choose the adapters you need
npm install @rytass/file-converter-adapter-image-resizer
npm install @rytass/file-converter-adapter-image-transcoder
npm install @rytass/file-converter-adapter-image-watermark

Quick Start

ImageResizer (圖像縮放)

Resize images while maintaining or controlling aspect ratio:
typescript
import { ImageResizer } from '@rytass/file-converter-adapter-image-resizer';
import { readFileSync, writeFileSync } from 'fs';

// Resize to max 800x600, maintaining aspect ratio
const resizer = new ImageResizer({
  maxWidth: 800,
  maxHeight: 600,
  keepAspectRatio: true,
  concurrency: 4, // Optional: parallel processing
});

const originalImage = readFileSync('photo.jpg');
const resizedImage = await resizer.convert<Buffer>(originalImage);
writeFileSync('photo-resized.jpg', resizedImage);

ImageTranscoder (格式轉換)

Convert images between formats (JPEG, PNG, WebP, AVIF, etc.):
typescript
import { ImageTranscoder } from '@rytass/file-converter-adapter-image-transcoder';

// Convert to WebP format
const transcoder = new ImageTranscoder({
  targetFormat: 'webp',
  quality: 85,
  effort: 4,
});

const jpegBuffer = readFileSync('photo.jpg');
const webpBuffer = await transcoder.convert<Buffer>(jpegBuffer);
writeFileSync('photo.webp', webpBuffer);

ImageWatermark (浮水印)

Add watermarks to images:
typescript
import { ImageWatermark } from '@rytass/file-converter-adapter-image-watermark';
import { gravity } from 'sharp';

// Add watermark at bottom-right corner
const watermarker = new ImageWatermark({
  watermarks: [
    {
      image: readFileSync('logo.png'), // Can be Buffer or file path
      gravity: gravity.southeast, // Position: bottom-right
    },
  ],
});

const originalImage = readFileSync('photo.jpg');
const watermarkedImage = await watermarker.convert<Buffer>(originalImage);
writeFileSync('photo-watermarked.jpg', watermarkedImage);

ConverterManager (管道處理)

Chain multiple converters in a pipeline:
typescript
import { ConverterManager } from '@rytass/file-converter';
import { ImageResizer } from '@rytass/file-converter-adapter-image-resizer';
import { ImageWatermark } from '@rytass/file-converter-adapter-image-watermark';
import { ImageTranscoder } from '@rytass/file-converter-adapter-image-transcoder';
import { gravity } from 'sharp';

// Create processing pipeline: Resize → Watermark → Convert to WebP
const pipeline = new ConverterManager([
  new ImageResizer({
    maxWidth: 1200,
    maxHeight: 800,
    keepAspectRatio: true,
  }),
  new ImageWatermark({
    watermarks: [
      {
        image: './logo.png',
        gravity: gravity.southeast,
      },
    ],
  }),
  new ImageTranscoder({
    targetFormat: 'webp',
    quality: 85,
    effort: 4,
  }),
]);

const originalImage = readFileSync('photo.jpg');
const processedImage = await pipeline.convert<Buffer>(originalImage);
writeFileSync('processed.webp', processedImage);

Common Patterns

Buffer vs Stream Processing

Buffer - Use for small files (小檔案), faster, uses more memory:
typescript
const buffer = readFileSync('image.jpg');
const result = await converter.convert<Buffer>(buffer);
writeFileSync('output.jpg', result);
Stream (Readable) - Use for large files (大檔案), memory efficient:
typescript
import { createReadStream, createWriteStream } from 'fs';
import { Readable } from 'stream';

const stream = createReadStream('large-image.jpg');
const resultStream = await converter.convert<Readable>(stream);

// Pipe to output
resultStream.pipe(createWriteStream('output.jpg'));

Single Conversion

Process one image with one converter:
typescript
// Resize only
const resizer = new ImageResizer({ maxWidth: 800 });
const resized = await resizer.convert<Buffer>(imageBuffer);

// Convert format only
const transcoder = new ImageTranscoder({ targetFormat: 'webp', quality: 90 });
const webp = await transcoder.convert<Buffer>(jpegBuffer);

Pipeline Conversion

Chain multiple operations:
typescript
// Three-step processing
const pipeline = new ConverterManager([
  new ImageResizer({ maxWidth: 1000, maxHeight: 750 }),
  new ImageWatermark({ watermarks: [{ image: 'logo.png' }] }),
  new ImageTranscoder({ targetFormat: 'webp', quality: 85 }),
]);

const result = await pipeline.convert<Buffer>(originalImage);

Batch Processing

Process multiple images:
typescript
import { glob } from 'glob';
import { basename } from 'path';

const pipeline = new ConverterManager([
  new ImageResizer({ maxWidth: 800 }),
  new ImageTranscoder({ targetFormat: 'webp', quality: 85 }),
]);

// Find all JPEG files
const images = await glob('photos/*.jpg');

// Process all images
await Promise.all(
  images.map(async (imagePath) => {
    const buffer = readFileSync(imagePath);
    const result = await pipeline.convert<Buffer>(buffer);
    const outputName = basename(imagePath, '.jpg') + '.webp';
    writeFileSync(`output/${outputName}`, result);
  })
);

Feature Comparison

FeatureImageResizerImageTranscoderImageWatermarkConverterManager
Resize Images (縮放圖片)YesNoNoVia pipeline
Convert Formats (轉換格式)NoYesNoVia pipeline
Add Watermarks (添加浮水印)NoNoYesVia pipeline
Maintain Aspect Ratio (保持縱橫比)YesN/AN/AN/A
Crop to Fit (裁剪適配)YesNoNoN/A
Buffer Support (緩衝支援)YesYesYesYes
Stream Support (串流支援)YesYesYesYes
Concurrency Control (並發控制)YesYesYesN/A
Multiple Watermarks (多浮水印)NoNoYesN/A
Pipeline Chaining (管道串聯)NoNoNoYes

Supported Formats (ImageTranscoder)

Input FormatsOutput Formats
jpg, png, webp, gif, avif, tif, svgjpg/jpeg, png, webp, avif, heif, gif, tif/tiff
Note: Input formats are detected by 
file-type
library. JPEG uses 'jpg' internally.
內部常數（未導出）：
  • SupportSources
    - 支援的輸入格式陣列：
    ['jpg', 'png', 'webp', 'gif', 'avif', 'tif', 'svg']
  • UnsupportedSource
    - 當輸入格式不支援時拋出的錯誤類別

ImageTranscoderOptions Types

每種輸出格式都有對應的 Sharp options：
typescript
import type { AvifOptions, GifOptions, HeifOptions, JpegOptions, PngOptions, TiffOptions, WebpOptions } from 'sharp';

type ImageTranscoderOptions =
  | { targetFormat: 'avif' } & AvifOptions
  | { targetFormat: 'heif' } & HeifOptions
  | { targetFormat: 'gif' } & GifOptions
  | { targetFormat: 'tif' | 'tiff' } & TiffOptions
  | { targetFormat: 'png' } & PngOptions
  | { targetFormat: 'webp' } & WebpOptions
  | { targetFormat: 'jpg' | 'jpeg' } & JpegOptions;

// Constructor 額外支援 concurrency 選項
new ImageTranscoder(options: ImageTranscoderOptions & { concurrency?: number });

ImageResizerOptions

typescript
interface ImageResizerOptions {
  maxWidth?: number;      // 最大寬度（至少需設定 maxWidth 或 maxHeight 其一）
  maxHeight?: number;     // 最大高度
  keepAspectRatio?: boolean;  // 保持縱橫比（預設 true，使用 'inside' fit）
  concurrency?: number;   // 並發數（預設 1）
}
Note: 使用 
withoutEnlargement: true
確保不會放大小於目標尺寸的圖片。當 
keepAspectRatio=false
時使用 
fit: 'cover'
裁剪適配。

ImageWatermarkOptions

typescript
interface Watermark {
  image: string | Buffer;  // 浮水印圖片（檔案路徑或 Buffer）
  gravity?: Gravity;       // 位置（預設 southeast）
}

interface ImageWatermarkOptions {
  watermarks: Watermark[];  // 浮水印陣列（支援多個浮水印）
  concurrency?: number;     // 並發數（預設 1）
}

Watermark Positions (ImageWatermark)

PositionGravity ConstantDescription
Top-Left (左上)
gravity.northwest
Northwest corner
Top-Center (上中)
gravity.north
Top center
Top-Right (右上)
gravity.northeast
Northeast corner
Middle-Left (中左)
gravity.west
Middle left
Center (中央)
gravity.center
Center
Middle-Right (中右)
gravity.east
Middle right
Bottom-Left (左下)
gravity.southwest
Southwest corner
Bottom-Center (下中)
gravity.south
Bottom center
Bottom-Right (右下)
gravity.southeast
Southeast corner (default)

Detailed Documentation

For complete API reference and advanced usage:
  • ImageResizer Complete Reference - All options, methods, and use cases
  • ImageTranscoder Complete Reference - Format-specific options, error handling
  • ImageWatermark Complete Reference - Watermark configuration, positioning

Complete Examples

E-commerce Product Images

Process product photos: resize for web, add branding watermark, convert to modern format:
typescript
import { ConverterManager } from '@rytass/file-converter';
import { ImageResizer } from '@rytass/file-converter-adapter-image-resizer';
import { ImageWatermark } from '@rytass/file-converter-adapter-image-watermark';
import { ImageTranscoder } from '@rytass/file-converter-adapter-image-transcoder';
import { readFileSync, writeFileSync } from 'fs';
import { gravity } from 'sharp';

// Create product image processor
const productImageProcessor = new ConverterManager([
  // Step 1: Resize to 1200x1200 max
  new ImageResizer({
    maxWidth: 1200,
    maxHeight: 1200,
    keepAspectRatio: true,
    concurrency: 4,
  }),

  // Step 2: Add brand watermark at bottom-right
  new ImageWatermark({
    watermarks: [
      {
        image: readFileSync('brand-logo.png'),
        gravity: gravity.southeast,
      },
    ],
  }),

  // Step 3: Convert to WebP for smaller file size
  new ImageTranscoder({
    targetFormat: 'webp',
    quality: 85,
    effort: 4, // Higher effort = better compression
  }),
]);

// Process a product image
const originalPhoto = readFileSync('product-001-raw.jpg');
const processedPhoto = await productImageProcessor.convert<Buffer>(originalPhoto);
writeFileSync('product-001.webp', processedPhoto);

Large File Stream Processing

Handle large files efficiently with streams to avoid memory issues:
typescript
import { createReadStream, createWriteStream } from 'fs';
import { ImageResizer } from '@rytass/file-converter-adapter-image-resizer';
import { Readable } from 'stream';

// Create resizer
const resizer = new ImageResizer({
  maxWidth: 1920,
  maxHeight: 1080,
  keepAspectRatio: true,
});

// Process large file using streams
const inputStream = createReadStream('large-photo.jpg');
const outputStream = await resizer.convert<Readable>(inputStream);

// Pipe to output file
outputStream.pipe(createWriteStream('large-photo-resized.jpg'));

// Wait for completion
await new Promise((resolve, reject) => {
  outputStream.on('finish', resolve);
  outputStream.on('error', reject);
});

Batch Processing with Progress Tracking

Process multiple images with progress updates:
typescript
import { glob } from 'glob';
import { basename } from 'path';
import { ConverterManager } from '@rytass/file-converter';
import { ImageResizer } from '@rytass/file-converter-adapter-image-resizer';
import { ImageTranscoder } from '@rytass/file-converter-adapter-image-transcoder';

// Create pipeline
const pipeline = new ConverterManager([
  new ImageResizer({ maxWidth: 800, maxHeight: 600, keepAspectRatio: true }),
  new ImageTranscoder({ targetFormat: 'webp', quality: 80 }),
]);

// Find all images
const images = await glob('input-photos/*.{jpg,png,jpeg}');
const total = images.length;
let processed = 0;

console.log(`Found ${total} images to process`);

// Process with progress tracking
for (const imagePath of images) {
  const buffer = readFileSync(imagePath);
  const result = await pipeline.convert<Buffer>(buffer);

  const outputName = basename(imagePath).replace(/\.(jpg|png|jpeg)$/, '.webp');
  writeFileSync(`output/${outputName}`, result);

  processed++;
  console.log(`Progress: ${processed}/${total} (${Math.round((processed / total) * 100)}%)`);
}

console.log('All images processed successfully!');

Conditional Processing

Apply different processing based on image properties:
typescript
import sharp from 'sharp';
import { ImageResizer } from '@rytass/file-converter-adapter-image-resizer';
import { ImageTranscoder } from '@rytass/file-converter-adapter-image-transcoder';
import { ConverterManager } from '@rytass/file-converter';

async function processImage(inputBuffer: Buffer): Promise<Buffer> {
  // Get image metadata
  const metadata = await sharp(inputBuffer).metadata();

  if (!metadata.width || !metadata.height) {
    throw new Error('Unable to read image dimensions');
  }

  // For large images: resize first
  if (metadata.width > 2000 || metadata.height > 2000) {
    console.log('Large image detected, resizing...');
    const pipeline = new ConverterManager([
      new ImageResizer({ maxWidth: 1600, maxHeight: 1600, keepAspectRatio: true }),
      new ImageTranscoder({ targetFormat: 'webp', quality: 85 }),
    ]);
    return pipeline.convert<Buffer>(inputBuffer);
  }

  // For small images: just convert format
  console.log('Small image detected, converting format only...');
  const transcoder = new ImageTranscoder({ targetFormat: 'webp', quality: 90 });
  return transcoder.convert<Buffer>(inputBuffer);
}

// Usage
const imageBuffer = readFileSync('photo.jpg');
const result = await processImage(imageBuffer);
writeFileSync('output.webp', result);

Troubleshooting

Common Issues

Memory Errors with Large Images
  • Solution: Use Stream processing instead of Buffer
typescript
// Instead of Buffer
const buffer = readFileSync('huge-image.jpg');
const result = await converter.convert<Buffer>(buffer);

// Use Stream
const stream = createReadStream('huge-image.jpg');
const resultStream = await converter.convert<Readable>(stream);
Sharp Cache Issues
  • Sharp automatically disables cache in all adapters with 
    sharp.cache(false)
  • No action needed
Concurrency Performance
  • Adjust 
    concurrency
    option based on your CPU cores
  • Default is 1 (single-threaded)
  • Try 4-8 for multi-core systems
typescript
const resizer = new ImageResizer({
  maxWidth: 800,
  concurrency: 8, // Adjust based on CPU cores
});
Unsupported Format Errors (ImageTranscoder)
  • Check input format is supported: JPEG, PNG, WebP, GIF, AVIF, TIFF, SVG
  • Error will throw 
    UnsupportedSource
    exception (internal class, catch using 
    instanceof Error
    and check 
    message === 'UnsupportedSource'
    )
Output Quality Issues
  • Increase 
    quality
    parameter (0-100)
  • For WebP/AVIF, increase 
    effort
    (0-9) for better compression
typescript
const transcoder = new ImageTranscoder({
  targetFormat: 'webp',
  quality: 95, // Higher quality
  effort: 6,   // More compression effort
});