respimagen 2.0.0

package/.github/copilot-instructions.md

@@ -0,0 +1,139 @@
+# Respimagen - AI Coding Agent Instructions
+
+## Project Overview
+
+Respimagen is a Node.js CLI tool and library for batch image processing. It resizes images to multiple sizes and converts them to various formats (AVIF, WebP, JPEG, PNG) using Sharp, then generates responsive image srcset strings.
+
+## Architecture
+
+### Core Module (`lib/processor.js`)
+
+- **Exports**: `processPath(input, options)`
+  - `input`: string - file path or directory
+  - `options`: object with `{ sizes, filetypes, outputdir, clear }`
+  - Returns: `Promise<{ output: Array, srcset?: string }>`
+- Contains all image processing logic using Sharp
+- Handles both single files and directories
+- Validates filetypes and throws errors for unknown formats
+- Can be imported and used programmatically
+
+### CLI Runner (`index.js`)
+
+- Thin wrapper around `lib/processor.js`
+- Uses yargs for argument parsing with positional input argument
+- Calls `processPath()` and logs results
+- Executable with Node.js: `node index.js <input> ...`
+
+### Utilities (`utils.js`)
+
+- **Exports**: `srcsetGenerator(files)`
+  - Groups files by extension
+  - Formats srcset strings for responsive images
+  - Filters invalid entries (missing ext/size)
+
+### CLI Wrapper (`bin/respimagen.mjs`)
+
+- Shebang wrapper for npm bin exposure
+- Spawns `node index.js` with forwarded arguments
+- Enables global `respimagen` command via npm
+
+## Key Conventions
+
+### ESM Only
+
+- `package.json` has `"type": "module"`
+- All imports use ESM syntax
+- Use `.mjs` extension for bin scripts
+
+### Image Processing
+
+- Sizes are optional - if not specified, keeps original dimensions
+- Default format: `avif` (modern, efficient format)
+- Supported formats: `avif`, `webp`, `jpeg`, `jpg`, `png`
+- Output directory: `output/` (configurable)
+- File naming with sizes: `{basename}-{size}.{ext}`
+- File naming without sizes: `{basename}.{ext}`
+
+### Testing
+
+- Uses Node's built-in test runner (`node:test`)
+- Run with: `npm test`
+- Integration tests: spawn CLI and verify file output
+- Unit tests: directly import and test `processPath()` and `srcsetGenerator()`
+- Format tests: verify all supported formats (avif, webp, jpeg, jpg, png) work correctly
+- Test fixtures use temporary directories, cleaned up after each test
+
+## Common Tasks
+
+### Running the CLI
+
+```bash
+# Single file with multiple formats
+node index.js image.jpg -s 500,750 -t webp,avif
+
+# Directory with default avif format
+node index.js ./photos -s 300,500,700
+
+# Simplest: just convert to avif, keep original size
+node index.js ./photos
+
+# Via wrapper
+node bin/respimagen.mjs image.jpg
+```
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Using Programmatically
+
+```javascript
+import { processPath } from "./lib/processor.js";
+
+const result = await processPath("photo.jpg", {
+  sizes: [400, 800],
+  filetypes: "webp,avif",
+  outputdir: "dist",
+  clear: true,
+});
+
+console.log(result.output); // Array of processed files
+console.log(result.srcset); // Srcset string
+```
+
+## Known Issues & Gotchas
+
+### Async Array Methods
+
+- **Fixed**: Previously used async predicate in `Array.filter()` which returned promises
+- Now uses `Promise.all()` with map+filter pattern for async directory checks
+
+### CLI Argument Parsing
+
+- yargs may parse numeric sizes as numbers
+- Always coerce `argv.sizes` to string before calling `.split()`
+
+### File Validation
+
+- `srcsetGenerator` filters invalid entries (missing ext/size, non-numeric size)
+- `processPath` validates filetypes and throws clear errors for unknown formats
+
+### Output Directory
+
+- Use `{ force: true }` with `fs.rm()` to handle non-existent directories
+- Always create output dir with `{ recursive: true }`
+
+## Dependencies
+
+- **sharp** (^0.34.4): Image processing
+- **yargs** (^18.0.0): CLI argument parsing
+- **eslint**: Code linting (devDep)
+
+## Next Steps / TODOs
+
+- Add concurrency limiting for large directories (e.g., p-limit)
+- Add GitHub Actions CI to run tests on PRs
+- Consider additional format validation
+- Add benchmarks for performance testing

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/bin/respimagen.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import path from "path";
+
+// Simple wrapper that delegates to index.js
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const indexPath = path.join(__dirname, "..", "index.js");
+
+// Forward all arguments to index.js
+const child = spawn("node", [indexPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+child.on("exit", (code) => {
+  process.exit(code || 0);
+});

package/eslint.config.js

@@ -0,0 +1,10 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+
+export default [
+  { languageOptions: { globals: globals.browser } },
+  pluginJs.configs.recommended,
+  "env": {
+     "node": true,
+  }
+];

package/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { processPath } from "./lib/processor.js";
+
+const argv = yargs(process.argv.slice(2))
+  .usage(
+    "Usage: $0 <input> -s [sizes] -t [filetypes] -o [outputdir] -c [clear]"
+  )
+  .command("$0 <input>", "Process image(s)", (yargs) => {
+    yargs.positional("input", {
+      describe: "file or directory to process",
+      type: "string",
+    });
+  })
+  .alias("s", "sizes")
+  .alias("t", "filetypes")
+  .alias("o", "outputdir")
+  .describe(
+    "s",
+    "different sizes to generate, separated by comma. If omitted, keeps original size"
+  )
+  .describe(
+    "t",
+    "different filetypes to generate, separated by comma. Supported: avif, webp, jpeg, jpg, png"
+  )
+  .describe("c", "clear the output directory before processing, default false")
+  .boolean("c")
+  .default({
+    filetypes: "avif",
+    outputdir: "output",
+    c: false,
+  })
+  .example(
+    "$0 beach.jpg -s 500,750 -t webp,avif",
+    "Resize and convert beach.jpg to 500px and 750px in webp and avif format"
+  )
+  .example(
+    "$0 ./photos",
+    "Convert all images in photos directory to avif (original size)"
+  )
+  .example(
+    "$0 ./photos -s 300,500,700",
+    "Process all images in the photos directory to avif with multiple sizes"
+  ).argv;
+
+const { input, outputdir } = argv;
+const sizes = [];
+
+if (argv.sizes) {
+  // yargs may parse a single numeric size as Number (e.g. -s 100),
+  // so coerce to string before splitting to avoid calling .split on a Number.
+  const sizesRaw =
+    typeof argv.sizes === "string" ? argv.sizes : String(argv.sizes);
+  sizes.push(...sizesRaw.split(",").map((s) => parseInt(s)));
+}
+
+const options = {
+  sizes: sizes.length > 0 ? sizes : null,
+  filetypes: argv.filetypes,
+  outputdir,
+  clear: argv.c,
+};
+
+try {
+  const result = await processPath(input, options);
+
+  // Log results
+  for (const item of result.output) {
+    console.log(`✅ ${item.file} - ${item.size}`);
+  }
+
+  console.log("Everything done");
+
+  if (result.srcset) {
+    console.log(`\n` + result.srcset);
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}

package/lib/processor.js

@@ -0,0 +1,127 @@
+import fs from "fs/promises";
+import path from "path";
+import sharp from "sharp";
+import { srcsetGenerator } from "../utils.js";
+
+const defaultFiletypeSettings = [
+  { id: "avif" },
+  { id: "webp" },
+  { id: "jpeg", options: { mozjpeg: true } },
+  { id: "jpg", options: { mozjpeg: true } },
+  { id: "png" },
+];
+
+const logFile = (outputArr, file, ext, size) => {
+  // collect result
+  outputArr.push({ file: `${file}-${size}.${ext}`, ext, size });
+};
+
+/**
+ * Process a file or directory and generate resized/converted images.
+ * @param {string} input - path to file or directory
+ * @param {object} options - { sizes: number[]|null, filetypes: string|array, outputdir: string, clear: boolean }
+ * @returns {Promise<{ output: Array, srcset?: string }>} resolves when processing finished
+ */
+export async function processPath(input, options = {}) {
+  const output = [];
+  const queue = [];
+
+  const sizes = Array.isArray(options.sizes) ? options.sizes : [];
+  const filetypesRaw = options.filetypes || "avif,jpeg";
+  const outputdir = options.outputdir || "output";
+  const clear = !!options.clear;
+
+  const formats = (
+    typeof filetypesRaw === "string" ? filetypesRaw.split(",") : filetypesRaw
+  ).map((f) =>
+    defaultFiletypeSettings.find(
+      (df) => df.id.toLowerCase() === String(f).toLowerCase()
+    )
+  );
+
+  // validate formats
+  if (formats.some((f) => !f)) {
+    const bad = (
+      typeof filetypesRaw === "string" ? filetypesRaw.split(",") : filetypesRaw
+    ).filter(
+      (f) =>
+        !defaultFiletypeSettings.find(
+          (df) => df.id.toLowerCase() === String(f).toLowerCase()
+        )
+    );
+    throw new Error(`Unknown filetypes: ${bad.join(",")}`);
+  }
+
+  // resolve input
+  const inputPath = path.resolve(input);
+  let files = [];
+  try {
+    const stats = await fs.stat(inputPath);
+    if (stats.isFile()) files.push(inputPath);
+    else if (stats.isDirectory()) {
+      const rawDirFils = await fs.readdir(inputPath);
+      const directoryFiles = rawDirFils.map((file) =>
+        path.join(inputPath, file)
+      );
+      const checks = await Promise.all(
+        directoryFiles.map(async (file) => {
+          try {
+            const check = await fs.lstat(file);
+            return { file, isFile: check.isFile() };
+          } catch (e) {
+            return { file, isFile: false };
+          }
+        })
+      );
+      files = checks.filter((c) => c.isFile).map((c) => c.file);
+    } else {
+      throw new Error(`${inputPath} is neither a file nor a directory`);
+    }
+  } catch (e) {
+    throw e;
+  }
+
+  if (clear) {
+    await fs.rm(outputdir, { recursive: true, force: true });
+  }
+
+  await fs.mkdir(outputdir, { recursive: true });
+
+  for (const file of files) {
+    const filename = path.basename(file, path.extname(file));
+    const image = sharp(file);
+
+    for (const format of formats) {
+      if (sizes.length > 0) {
+        for (const size of sizes) {
+          queue.push(
+            image
+              .clone()
+              .resize({ width: size })
+              .toFormat(format.id, format.options)
+              .toFile(`${outputdir}/${filename}-${size}.${format.id}`)
+              .then(() => logFile(output, filename, format.id, size))
+          );
+        }
+      } else {
+        // no sizes -> keep original width
+        const imgSize = await image.metadata();
+        queue.push(
+          image
+            .clone()
+            .toFormat(format.id, format.options)
+            .toFile(`${outputdir}/${filename}.${format.id}`)
+            .then(() => logFile(output, filename, format.id, imgSize.width))
+        );
+      }
+    }
+  }
+
+  await Promise.all(queue);
+
+  const result = { output };
+  if (sizes.length !== 0) result.srcset = srcsetGenerator(output);
+  return result;
+}
+
+export default { processPath };

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "respimagen",
+	"version": "2.0.0",
+	"description": "",
+	"main": "index.js",
+	"type": "module",
+	"bin": {
+		"respimagen": "bin/respimagen.mjs"
+	},
+	"scripts": {
+		"test": "node --test",
+		"cli": "node index.js",
+		"lint": "npx eslint . || true"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"dependencies": {
+		"sharp": "^0.34.4",
+		"yargs": "^18.0.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.0",
+		"eslint": "^9.39.0",
+		"globals": "^16.5.0"
+	}
+}

package/readme.md

@@ -0,0 +1,78 @@
+# Responsive Images Generator
+
+This is a Node.js script and library that generates responsive images for your website. It uses the [sharp](https://sharp.pixelplumbing.com/) image processing library.
+
+Feel free to use it and modify it to your needs.
+
+## CLI Usage
+
+```bash
+node index.js <input> -s [sizes] -t [filetypes] -o [outputdir] -c [clear]
+
+Positional Arguments:
+  input            file or directory to process                       [required]
+
+Options:
+      --help       Show help                                           [boolean]
+      --version    Show version number                                 [boolean]
+  -s, --sizes      different sizes to generate, separated by comma. If omitted,
+                   keeps original size                               [optional]
+  -t, --filetypes  different filetypes to generate, separated by comma
+                   Supported: avif, webp, jpeg, jpg, png
+                                                             [default: "avif"]
+  -o, --outputdir  output directory                           [default: "output"]
+  -c               clear the output directory before processing, default false
+                                                      [boolean] [default: false]
+
+Examples:
+  node index.js beach.jpg -s 500,750 -t webp,avif
+    Resize and convert beach.jpg to 500px and 750px in webp and avif format
+
+  node index.js ./photos
+    Convert all images to avif, keeping original dimensions
+
+  node index.js ./photos -s 300,500,700
+    Process all images with multiple sizes (avif format)
+
+  node index.js ./photos -s 300,500,700 -t webp,avif -o output -c
+    Process all images with multiple sizes and formats, clearing output first
+```
+
+## Programmatic Usage
+
+You can also import and use the core functionality in your own Node.js projects:
+
+```javascript
+import { processPath } from './lib/processor.js';
+
+// Process a single image
+const result = await processPath('photo.jpg', {
+  sizes: [400, 800, 1200],
+  filetypes: 'webp,avif',
+  outputdir: 'dist',
+  clear: true
+});
+
+console.log(result.output); // Array of processed files
+console.log(result.srcset); // Srcset string for responsive images
+
+// Process a directory
+const dirResult = await processPath('./images', {
+  sizes: [300, 500, 700],
+  filetypes: 'avif,jpeg',
+  outputdir: 'output'
+});
+```
+
+## Testing
+
+Run the test suite with:
+
+```bash
+npm test
+```
+
+## Dependencies
+
+- **sharp** (^0.34.4): Image processing
+- **yargs** (^18.0.0): CLI argument parsing

package/test/dir.test.mjs

@@ -0,0 +1,81 @@
+import fs from "fs/promises";
+import path from "path";
+import { execFile } from "child_process";
+import sharp from "sharp";
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const tmpDir = path.join(process.cwd(), "test", "tmp-dir");
+const fixturesDir = path.join(process.cwd(), "test", "fixtures-dir");
+
+const run = (file, args) =>
+  new Promise((resolve, reject) => {
+    execFile(file, args, { cwd: process.cwd() }, (err, stdout, stderr) => {
+      if (err) return reject({ err, stdout, stderr });
+      resolve({ stdout, stderr });
+    });
+  });
+
+const ensureDir = async (d) => {
+  await fs.rm(d, { recursive: true, force: true }).catch(() => {});
+  await fs.mkdir(d, { recursive: true });
+};
+
+test("integration CLI directory", async (t) => {
+  await ensureDir(tmpDir);
+  await ensureDir(fixturesDir);
+
+  const inputDir = fixturesDir;
+  const outDir = path.join(tmpDir, "output");
+
+  // create two tiny images
+  await sharp({
+    create: {
+      width: 100,
+      height: 100,
+      channels: 3,
+      background: { r: 0, g: 255, b: 0 },
+    },
+  })
+    .png()
+    .toFile(path.join(inputDir, "a.png"));
+
+  await sharp({
+    create: {
+      width: 150,
+      height: 150,
+      channels: 3,
+      background: { r: 0, g: 0, b: 255 },
+    },
+  })
+    .png()
+    .toFile(path.join(inputDir, "b.png"));
+
+  const nodeBin = process.execPath;
+  const cliArgs = [
+    "index.js",
+    inputDir,
+    "-s",
+    "50",
+    "-t",
+    "jpeg",
+    "-o",
+    outDir,
+    "-c",
+  ];
+
+  const { stdout } = await run(nodeBin, cliArgs);
+  assert.match(stdout, /Everything done/);
+
+  const expectedFiles = [
+    path.join(outDir, "a-50.jpeg"),
+    path.join(outDir, "b-50.jpeg"),
+  ];
+  for (const f of expectedFiles) {
+    const stat = await fs.stat(f);
+    assert.ok(stat.isFile());
+  }
+
+  await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  await fs.rm(fixturesDir, { recursive: true, force: true }).catch(() => {});
+});

package/test/file.test.mjs

@@ -0,0 +1,66 @@
+import fs from "fs/promises";
+import path from "path";
+import { execFile } from "child_process";
+import sharp from "sharp";
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const tmpDir = path.join(process.cwd(), "test", "tmp");
+const fixturesDir = path.join(process.cwd(), "test", "fixtures");
+
+const run = (file, args) =>
+  new Promise((resolve, reject) => {
+    execFile(file, args, { cwd: process.cwd() }, (err, stdout, stderr) => {
+      if (err) return reject({ err, stdout, stderr });
+      resolve({ stdout, stderr });
+    });
+  });
+
+const ensureDir = async (d) => {
+  await fs.rm(d, { recursive: true, force: true }).catch(() => {});
+  await fs.mkdir(d, { recursive: true });
+};
+
+test("integration CLI single file", async (t) => {
+  await ensureDir(tmpDir);
+  await ensureDir(fixturesDir);
+
+  const inputImage = path.join(fixturesDir, "test.png");
+  const outDir = path.join(tmpDir, "output");
+
+  // create a tiny 200x200 red PNG
+  await sharp({
+    create: {
+      width: 200,
+      height: 200,
+      channels: 3,
+      background: { r: 255, g: 0, b: 0 },
+    },
+  })
+    .png()
+    .toFile(inputImage);
+
+  const nodeBin = process.execPath;
+  const cliArgs = [
+    "index.js",
+    inputImage,
+    "-s",
+    "100",
+    "-t",
+    "jpeg",
+    "-o",
+    outDir,
+    "-c",
+  ];
+
+  const { stdout } = await run(nodeBin, cliArgs);
+  assert.match(stdout, /Everything done/);
+
+  const expectedFile = path.join(outDir, "test-100.jpeg");
+  const stat = await fs.stat(expectedFile);
+  assert.ok(stat.isFile());
+
+  // cleanup
+  await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  await fs.rm(fixturesDir, { recursive: true, force: true }).catch(() => {});
+});

package/test/formats.test.mjs

@@ -0,0 +1,193 @@
+import test from "node:test";
+import assert from "node:assert";
+import fs from "fs/promises";
+import path from "path";
+import sharp from "sharp";
+import { processPath } from "../lib/processor.js";
+
+// Test each supported format individually
+const supportedFormats = ["avif", "webp", "jpeg", "jpg", "png"];
+
+for (const format of supportedFormats) {
+  test(`processPath supports ${format} format`, async () => {
+    const testDir = path.join(process.cwd(), `test-fixtures-format-${format}`);
+    const inputFile = path.join(testDir, "test-image.jpg");
+    const outputDir = path.join(testDir, "output");
+
+    try {
+      await fs.mkdir(testDir, { recursive: true });
+
+      // Create test image
+      await sharp({
+        create: {
+          width: 80,
+          height: 80,
+          channels: 3,
+          background: { r: 200, g: 100, b: 50 },
+        },
+      })
+        .jpeg()
+        .toFile(inputFile);
+
+      // Process with specific format
+      const result = await processPath(inputFile, {
+        sizes: [40],
+        filetypes: format,
+        outputdir: outputDir,
+        clear: true,
+      });
+
+      // Verify output
+      assert.ok(result.output, "result should have output array");
+      assert.strictEqual(
+        result.output.length,
+        1,
+        `should have 1 output for ${format}`
+      );
+      assert.strictEqual(
+        result.output[0].ext,
+        format,
+        `output extension should be ${format}`
+      );
+
+      // Verify file exists
+      const outputFiles = await fs.readdir(outputDir);
+      assert.strictEqual(
+        outputFiles.length,
+        1,
+        "output directory should contain 1 file"
+      );
+
+      const expectedExtension = format;
+      assert.ok(
+        outputFiles[0].endsWith(`.${expectedExtension}`),
+        `file should have ${expectedExtension} extension`
+      );
+
+      // Verify file is valid by reading metadata
+      const outputFile = path.join(outputDir, outputFiles[0]);
+      const metadata = await sharp(outputFile).metadata();
+      assert.ok(metadata, "should be able to read output file metadata");
+      assert.strictEqual(metadata.width, 40, "width should be 40px");
+    } finally {
+      await fs.rm(testDir, { recursive: true, force: true });
+    }
+  });
+}
+
+test("processPath supports multiple formats at once", async () => {
+  const testDir = path.join(process.cwd(), "test-fixtures-multi-format");
+  const inputFile = path.join(testDir, "test-image.png");
+  const outputDir = path.join(testDir, "output");
+
+  try {
+    await fs.mkdir(testDir, { recursive: true });
+
+    // Create test image
+    await sharp({
+      create: {
+        width: 100,
+        height: 100,
+        channels: 3,
+        background: { r: 50, g: 150, b: 250 },
+      },
+    })
+      .png()
+      .toFile(inputFile);
+
+    // Process with all formats
+    const result = await processPath(inputFile, {
+      sizes: [50],
+      filetypes: "avif,webp,jpeg,png",
+      outputdir: outputDir,
+      clear: true,
+    });
+
+    // Verify output
+    assert.ok(result.output, "result should have output array");
+    assert.strictEqual(
+      result.output.length,
+      4,
+      "should have 4 outputs (4 formats)"
+    );
+
+    // Verify all formats are present
+    const extensions = result.output.map((o) => o.ext);
+    assert.ok(extensions.includes("avif"), "should include avif");
+    assert.ok(extensions.includes("webp"), "should include webp");
+    assert.ok(extensions.includes("jpeg"), "should include jpeg");
+    assert.ok(extensions.includes("png"), "should include png");
+
+    // Verify files exist
+    const outputFiles = await fs.readdir(outputDir);
+    assert.strictEqual(
+      outputFiles.length,
+      4,
+      "output directory should contain 4 files"
+    );
+
+    // Verify each file is valid
+    for (const file of outputFiles) {
+      const filePath = path.join(outputDir, file);
+      const metadata = await sharp(filePath).metadata();
+      assert.ok(metadata, `should be able to read ${file} metadata`);
+      assert.strictEqual(metadata.width, 50, `${file} width should be 50px`);
+    }
+  } finally {
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});
+
+test("processPath handles jpg and jpeg equivalently", async () => {
+  const testDir = path.join(process.cwd(), "test-fixtures-jpg-jpeg");
+  const inputFile = path.join(testDir, "test-image.png");
+  const outputDir = path.join(testDir, "output");
+
+  try {
+    await fs.mkdir(testDir, { recursive: true });
+
+    // Create test image
+    await sharp({
+      create: {
+        width: 60,
+        height: 60,
+        channels: 3,
+        background: { r: 128, g: 128, b: 128 },
+      },
+    })
+      .png()
+      .toFile(inputFile);
+
+    // Process with both jpg and jpeg
+    const result = await processPath(inputFile, {
+      sizes: [30],
+      filetypes: "jpg,jpeg",
+      outputdir: outputDir,
+      clear: true,
+    });
+
+    // Both should produce valid output
+    assert.strictEqual(
+      result.output.length,
+      2,
+      "should have 2 outputs (jpg and jpeg)"
+    );
+
+    // Verify files exist and are valid
+    const outputFiles = await fs.readdir(outputDir);
+    assert.strictEqual(outputFiles.length, 2, "should have 2 output files");
+
+    for (const file of outputFiles) {
+      const filePath = path.join(outputDir, file);
+      const metadata = await sharp(filePath).metadata();
+      assert.ok(metadata, `should be able to read ${file}`);
+      // Both jpg and jpeg files are handled as JPEG by Sharp
+      assert.ok(
+        metadata.format === "jpeg" || metadata.format === "jpg",
+        `${file} should be JPEG format`
+      );
+    }
+  } finally {
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});

package/test/processor.test.mjs

@@ -0,0 +1,213 @@
+import test from "node:test";
+import assert from "node:assert";
+import fs from "fs/promises";
+import path from "path";
+import sharp from "sharp";
+import { processPath } from "../lib/processor.js";
+
+test("processPath can be imported and used programmatically", async () => {
+  const testDir = path.join(process.cwd(), "test-fixtures-processor");
+  const inputFile = path.join(testDir, "test-image.jpg");
+  const outputDir = path.join(testDir, "output");
+
+  try {
+    // Setup: create test fixture
+    await fs.mkdir(testDir, { recursive: true });
+    await sharp({
+      create: {
+        width: 100,
+        height: 100,
+        channels: 3,
+        background: { r: 255, g: 0, b: 0 },
+      },
+    })
+      .jpeg()
+      .toFile(inputFile);
+
+    // Use the exported API
+    const result = await processPath(inputFile, {
+      sizes: [50, 75],
+      filetypes: "webp,avif",
+      outputdir: outputDir,
+      clear: true,
+    });
+
+    // Verify output
+    assert.ok(result.output, "result should have output array");
+    assert.ok(result.srcset, "result should have srcset string");
+    assert.strictEqual(
+      result.output.length,
+      4,
+      "should have 4 outputs (2 sizes × 2 formats)"
+    );
+
+    // Verify files exist
+    const outputFiles = await fs.readdir(outputDir);
+    assert.strictEqual(
+      outputFiles.length,
+      4,
+      "output directory should contain 4 files"
+    );
+    assert.ok(
+      outputFiles.some((f) => f.includes("-50.webp")),
+      "should have 50px webp file"
+    );
+    assert.ok(
+      outputFiles.some((f) => f.includes("-75.avif")),
+      "should have 75px avif file"
+    );
+  } finally {
+    // Cleanup
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});
+
+test("processPath throws error for unknown filetypes", async () => {
+  const testDir = path.join(process.cwd(), "test-fixtures-processor-error");
+  const inputFile = path.join(testDir, "test-image.jpg");
+
+  try {
+    await fs.mkdir(testDir, { recursive: true });
+    await sharp({
+      create: {
+        width: 50,
+        height: 50,
+        channels: 3,
+        background: { r: 0, g: 255, b: 0 },
+      },
+    })
+      .jpeg()
+      .toFile(inputFile);
+
+    // Should throw for unknown filetype
+    await assert.rejects(
+      async () => {
+        await processPath(inputFile, {
+          sizes: [50],
+          filetypes: "unknownformat",
+          outputdir: path.join(testDir, "output"),
+        });
+      },
+      {
+        message: /Unknown filetypes/,
+      }
+    );
+  } finally {
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});
+
+test("processPath handles directory input", async () => {
+  const testDir = path.join(process.cwd(), "test-fixtures-processor-dir");
+  const outputDir = path.join(testDir, "output");
+
+  try {
+    await fs.mkdir(testDir, { recursive: true });
+
+    // Create two test images
+    await sharp({
+      create: {
+        width: 80,
+        height: 80,
+        channels: 3,
+        background: { r: 100, g: 100, b: 255 },
+      },
+    })
+      .png()
+      .toFile(path.join(testDir, "image1.png"));
+
+    await sharp({
+      create: {
+        width: 90,
+        height: 90,
+        channels: 3,
+        background: { r: 255, g: 255, b: 0 },
+      },
+    })
+      .png()
+      .toFile(path.join(testDir, "image2.png"));
+
+    const result = await processPath(testDir, {
+      sizes: [40],
+      filetypes: "webp",
+      outputdir: outputDir,
+      clear: true,
+    });
+
+    // Should process both images
+    assert.strictEqual(result.output.length, 2, "should process 2 images");
+    assert.ok(result.srcset, "should generate srcset");
+
+    const outputFiles = await fs.readdir(outputDir);
+    assert.strictEqual(outputFiles.length, 2, "should have 2 output files");
+  } finally {
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});
+
+test("processPath without sizes keeps original dimensions", async () => {
+  const testDir = path.join(process.cwd(), "test-fixtures-processor-no-resize");
+  const inputFile = path.join(testDir, "test-image.jpg");
+  const outputDir = path.join(testDir, "output");
+
+  try {
+    await fs.mkdir(testDir, { recursive: true });
+
+    // Create 120x120 test image
+    await sharp({
+      create: {
+        width: 120,
+        height: 120,
+        channels: 3,
+        background: { r: 255, g: 100, b: 50 },
+      },
+    })
+      .jpeg()
+      .toFile(inputFile);
+
+    // Process without sizes
+    const result = await processPath(inputFile, {
+      sizes: null,
+      filetypes: "webp,avif",
+      outputdir: outputDir,
+      clear: true,
+    });
+
+    // Verify output
+    assert.ok(result.output, "result should have output array");
+    assert.strictEqual(
+      result.output.length,
+      2,
+      "should have 2 outputs (2 formats, no resize)"
+    );
+
+    // Should not generate srcset when no sizes specified
+    assert.strictEqual(
+      result.srcset,
+      undefined,
+      "should not have srcset when no sizes"
+    );
+
+    // Verify files exist with original dimensions
+    const outputFiles = await fs.readdir(outputDir);
+    assert.strictEqual(outputFiles.length, 2, "should have 2 output files");
+
+    // Check files don't have size suffix
+    assert.ok(
+      outputFiles.some((f) => f === "test-image.webp"),
+      "should have webp without size suffix"
+    );
+    assert.ok(
+      outputFiles.some((f) => f === "test-image.avif"),
+      "should have avif without size suffix"
+    );
+
+    // Verify dimensions are preserved
+    const webpPath = path.join(outputDir, "test-image.webp");
+    const metadata = await sharp(webpPath).metadata();
+    assert.strictEqual(metadata.width, 120, "width should be preserved");
+    assert.strictEqual(metadata.height, 120, "height should be preserved");
+  } finally {
+    await fs.rm(testDir, { recursive: true, force: true });
+  }
+});

package/test/srcset.test.mjs

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { srcsetGenerator } from "../utils.js";
+
+test("srcsetGenerator groups by extension and formats srcset correctly", () => {
+  const files = [
+    { file: "image-300.avif", ext: "avif", size: 300 },
+    { file: "image-600.avif", ext: "avif", size: 600 },
+    { file: "image-300.jpeg", ext: "jpeg", size: 300 },
+  ];
+
+  const out = srcsetGenerator(files);
+
+  // Expect two srcset blocks separated by blank line
+  assert.ok(out.includes('srcset="image-300.avif 300w,\nimage-600.avif 600w"'));
+  assert.ok(out.includes('srcset="image-300.jpeg 300w"'));
+});
+
+test("srcsetGenerator returns empty string for empty input", () => {
+  const out = srcsetGenerator([]);
+  assert.strictEqual(out, "");
+});
+
+test("srcsetGenerator skips entries missing ext or size gracefully", () => {
+  const files = [
+    { file: "ok-300.webp", ext: "webp", size: 300 },
+    { file: "bad-noext", size: 200 },
+    { file: "bad-nosize.webp", ext: "webp" },
+  ];
+
+  const out = srcsetGenerator(files);
+  // Should include only the valid entry
+  assert.ok(out.includes('srcset="ok-300.webp 300w"'));
+  // Ensure entries without ext/size do not crash the function
+  assert.ok(!out.includes("bad-noext"));
+  assert.ok(!out.includes("bad-nosize"));
+});
+
+test("srcsetGenerator preserves input ordering within each extension group", () => {
+  const files = [
+    { file: "first-100.jpg", ext: "jpg", size: 100 },
+    { file: "second-200.jpg", ext: "jpg", size: 200 },
+  ];
+
+  const out = srcsetGenerator(files);
+  const idxFirst = out.indexOf("first-100.jpg");
+  const idxSecond = out.indexOf("second-200.jpg");
+  assert.ok(idxFirst < idxSecond, "ordering should preserve insertion order");
+});

package/utils.js

@@ -0,0 +1,30 @@
+const srcsetGenerator = (files) => {
+  if (!Array.isArray(files) || files.length === 0) return "";
+
+  // keep only valid entries with ext, file and numeric size
+  const valid = files.filter(
+    (f) => f && f.ext && f.file && Number.isFinite(Number(f.size))
+  );
+
+  if (valid.length === 0) return "";
+
+  // group files by extension while preserving input order
+  const groupedFiles = valid.reduce((acc, file) => {
+    const ext = file.ext;
+    if (!acc[ext]) acc[ext] = [];
+    acc[ext].push(file);
+    return acc;
+  }, {});
+
+  // generate srcset for each extension
+  const srcsets = Object.entries(groupedFiles).map(
+    ([ext, files]) =>
+      `srcset="${files
+        .map((file) => `${file.file} ${file.size}w`)
+        .join(",\n")}"`
+  );
+
+  return srcsets.join("\n\n");
+};
+
+export { srcsetGenerator };