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:

Package	Function	Based 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

Feature	ImageResizer	ImageTranscoder	ImageWatermark	ConverterManager
Resize Images (縮放圖片)	Yes	No	No	Via pipeline
Convert Formats (轉換格式)	No	Yes	No	Via pipeline
Add Watermarks (添加浮水印)	No	No	Yes	Via pipeline
Maintain Aspect Ratio (保持縱橫比)	Yes	N/A	N/A	N/A
Crop to Fit (裁剪適配)	Yes	No	No	N/A
Buffer Support (緩衝支援)	Yes	Yes	Yes	Yes
Stream Support (串流支援)	Yes	Yes	Yes	Yes
Concurrency Control (並發控制)	Yes	Yes	Yes	N/A
Multiple Watermarks (多浮水印)	No	No	Yes	N/A
Pipeline Chaining (管道串聯)	No	No	No	Yes

Supported Formats (ImageTranscoder)

Input Formats	Output Formats
jpg, png, webp, gif, avif, tif, svg	jpg/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)

Position	Gravity Constant	Description
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
});

file-adapters

NPX Install

Tags

SKILL.md Content

File Converter Adapters

Overview

Base Interface (@rytass/file-converter)

Installation

Quick Start

ImageResizer (圖像縮放)

ImageTranscoder (格式轉換)

ImageWatermark (浮水印)

ConverterManager (管道處理)

Common Patterns

Buffer vs Stream Processing

Single Conversion

Pipeline Conversion

Batch Processing

Feature Comparison

Supported Formats (ImageTranscoder)

ImageTranscoderOptions Types

ImageResizerOptions

ImageWatermarkOptions

Watermark Positions (ImageWatermark)

Detailed Documentation

Complete Examples

E-commerce Product Images

Large File Stream Processing

Batch Processing with Progress Tracking

Conditional Processing

Troubleshooting

Common Issues