From 57d7dac2b50612ab29de69a15ac2744abb123442 Mon Sep 17 00:00:00 2001
From: Anthony GAEREMYNCK <1@anthony.sh>
Date: Thu, 30 Jul 2026 23:03:39 +0200
Subject: [PATCH] feat: support quality/compressionLevel options in image
 converters

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/converters/image.js       | 13 ++++++--
 test/converters/image.test.js | 63 ++++++++++++++++++++++++++++++++++-
 2 files changed, 73 insertions(+), 3 deletions(-)

diff --git a/src/converters/image.js b/src/converters/image.js
index 6c4086e..7895de6 100644
--- a/src/converters/image.js
+++ b/src/converters/image.js
@@ -7,6 +7,13 @@ function sharpFormatName(format) {
   return format === 'jpg' ? 'jpeg' : format;
 }
 
+export function buildFormatOptions(targetFormat, quality) {
+  if (quality == null) return {};
+  if (targetFormat === 'png') return { compressionLevel: quality };
+  if (targetFormat === 'gif') return {};
+  return { quality };
+}
+
 export function registerImageConverters() {
   for (const sourceFormat of IMAGE_FORMATS) {
     for (const targetFormat of IMAGE_FORMATS) {
@@ -16,8 +23,10 @@ export function registerImageConverters() {
         family: 'image',
         sourceFormat,
         targetFormat,
-        convert: async (inputPath, outputPath) => {
-          await sharp(inputPath).toFormat(sharpFormatName(targetFormat)).toFile(outputPath);
+        convert: async (inputPath, outputPath, { quality } = {}) => {
+          await sharp(inputPath)
+            .toFormat(sharpFormatName(targetFormat), buildFormatOptions(targetFormat, quality))
+            .toFile(outputPath);
         },
       });
     }
diff --git a/test/converters/image.test.js b/test/converters/image.test.js
index 684e311..2f371c4 100644
--- a/test/converters/image.test.js
+++ b/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);
+  });
 });