feat: support quality/compressionLevel options in image converters

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

test/converters/image.test.js

@@ -2,21 +2,55 @@ import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { registerImageConverters } from '../../src/converters/image.js';
+import sharp from 'sharp';
+import { registerImageConverters, buildFormatOptions } from '../../src/converters/image.js';
 import { resolve, listTargetFormats } from '../../src/converters/registry.js';
 import { detectInputMime } from '../../src/mime.js';
 
 let tmpDir;
+let noisyPngPath;
 
 beforeAll(async () => {
   registerImageConverters();
   tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'converter-image-'));
+  noisyPngPath = path.join(tmpDir, 'noisy.png');
+  await sharp({
+    create: {
+      width: 256,
+      height: 256,
+      channels: 3,
+      noise: { type: 'gaussian', mean: 128, sigma: 40 },
+    },
+  })
+    .png()
+    .toFile(noisyPngPath);
 });
 
 afterAll(async () => {
   await fs.rm(tmpDir, { recursive: true, force: true });
 });
 
+describe('buildFormatOptions', () => {
+  it('returns an empty object when quality is not set', () => {
+    expect(buildFormatOptions('jpeg', null)).toEqual({});
+  });
+
+  it('maps quality to the quality option for jpeg/webp/avif/tiff', () => {
+    expect(buildFormatOptions('jpeg', 40)).toEqual({ quality: 40 });
+    expect(buildFormatOptions('webp', 40)).toEqual({ quality: 40 });
+    expect(buildFormatOptions('avif', 40)).toEqual({ quality: 40 });
+    expect(buildFormatOptions('tiff', 40)).toEqual({ quality: 40 });
+  });
+
+  it('maps quality to compressionLevel for png', () => {
+    expect(buildFormatOptions('png', 3)).toEqual({ compressionLevel: 3 });
+  });
+
+  it('ignores quality for gif', () => {
+    expect(buildFormatOptions('gif', 5)).toEqual({});
+  });
+});
+
 describe('image converters', () => {
   it('registers every pair among the supported formats', () => {
     const targets = listTargetFormats('png').sort();
@@ -44,4 +78,31 @@ describe('image converters', () => {
     const detected = await detectInputMime(outputPath);
     expect(detected.mime).toBe('image/jpeg');
   });
+
+  it('produces a smaller JPG at lower quality than at higher quality', async () => {
+    const lowPath = path.join(tmpDir, 'low.jpg');
+    const highPath = path.join(tmpDir, 'high.jpg');
+    const entry = resolve('png', 'jpg');
+
+    await entry.convert(noisyPngPath, lowPath, { quality: 10 });
+    await entry.convert(noisyPngPath, highPath, { quality: 95 });
+
+    const [lowStat, highStat] = await Promise.all([fs.stat(lowPath), fs.stat(highPath)]);
+    expect(lowStat.size).toBeLessThan(highStat.size);
+  });
+
+  it('produces a smaller-or-equal PNG at a higher compressionLevel', async () => {
+    const jpgPath = path.join(tmpDir, 'noisy.jpg');
+    await sharp(noisyPngPath).jpeg({ quality: 90 }).toFile(jpgPath);
+
+    const fastPath = path.join(tmpDir, 'fast.png');
+    const slowPath = path.join(tmpDir, 'slow.png');
+    const entry = resolve('jpg', 'png');
+
+    await entry.convert(jpgPath, fastPath, { quality: 0 });
+    await entry.convert(jpgPath, slowPath, { quality: 9 });
+
+    const [fastStat, slowStat] = await Promise.all([fs.stat(fastPath), fs.stat(slowPath)]);
+    expect(slowStat.size).toBeLessThanOrEqual(fastStat.size);
+  });
 });