pulp-image 0.1.0

package/src/buildOutputPath.js

@@ -0,0 +1,67 @@
+import { dirname, basename, extname, join, resolve } from 'path';
+import { mkdirSync } from 'fs';
+
+/**
+ * Builds the output path for an image file
+ */
+export function buildOutputPath(inputPath, config, fileIndex = null) {
+  const { out, format, width, height, suffix, autoSuffix, renamePattern } = config;
+  
+  // Resolve output directory (but don't create it yet - will be created when writing)
+  const outputDir = resolve(out);
+  
+  // Get base filename and extension
+  const baseName = basename(inputPath);
+  const inputExt = extname(baseName);
+  const nameWithoutExt = baseName.slice(0, -inputExt.length);
+  
+  // Determine output extension
+  const outputExt = format ? `.${format}` : inputExt;
+  const outputExtNoDot = outputExt.slice(1); // Remove leading dot
+  
+  // If rename pattern is provided, use it
+  if (renamePattern) {
+    let outputFilename = renamePattern
+      .replace(/{name}/g, nameWithoutExt)
+      .replace(/{ext}/g, outputExtNoDot)
+      .replace(/{index}/g, fileIndex !== null ? String(fileIndex + 1) : '1');
+    
+    // Ensure we have an extension
+    if (!outputFilename.includes('.')) {
+      outputFilename += outputExt;
+    }
+    
+    const outputPath = join(outputDir, outputFilename);
+    return outputPath;
+  }
+  
+  // Original logic (suffix-based naming)
+  // Build suffix parts
+  const suffixParts = [];
+  
+  // Auto suffix first (if enabled)
+  if (autoSuffix) {
+    if (width && height) {
+      suffixParts.push(`${width}x${height}`);
+    } else if (width) {
+      suffixParts.push(`${width}w`);
+    } else if (height) {
+      suffixParts.push(`${height}h`);
+    }
+  }
+  
+  // Custom suffix second (if provided)
+  if (suffix) {
+    suffixParts.push(suffix);
+  }
+  
+  // Combine suffix
+  const finalSuffix = suffixParts.length > 0 ? `-${suffixParts.join('-')}` : '';
+  
+  // Build final filename
+  const outputFilename = `${nameWithoutExt}${finalSuffix}${outputExt}`;
+  const outputPath = join(outputDir, outputFilename);
+  
+  return outputPath;
+}
+

package/src/formats.js

@@ -0,0 +1,54 @@
+export const SUPPORTED_INPUT_FORMATS = ['png', 'jpg', 'jpeg', 'webp', 'avif'];
+export const SUPPORTED_OUTPUT_FORMATS = ['png', 'jpg', 'webp', 'avif'];
+
+export const FORMATS_WITH_TRANSPARENCY = ['png', 'webp', 'avif'];
+
+export const DEFAULT_QUALITY = {
+  jpg: 80,
+  webp: 80,
+  avif: 50,
+  png: null // PNG is lossless by default
+};
+
+export const FORMATS_SUPPORTING_LOSSLESS = ['png', 'webp', 'avif'];
+
+/**
+ * Validates if a format is supported for output
+ */
+export function isValidOutputFormat(format) {
+  return format && SUPPORTED_OUTPUT_FORMATS.includes(format.toLowerCase());
+}
+
+/**
+ * Gets the default quality for a format
+ */
+export function getDefaultQuality(format) {
+  if (!format) return null;
+  return DEFAULT_QUALITY[format.toLowerCase()] || null;
+}
+
+/**
+ * Checks if a format supports transparency
+ */
+export function supportsTransparency(format) {
+  if (!format) return false;
+  return FORMATS_WITH_TRANSPARENCY.includes(format.toLowerCase());
+}
+
+/**
+ * Checks if a format supports lossless compression
+ */
+export function supportsLossless(format) {
+  if (!format) return false;
+  return FORMATS_SUPPORTING_LOSSLESS.includes(format.toLowerCase());
+}
+
+/**
+ * Normalizes format name (jpg -> jpeg for Sharp compatibility)
+ */
+export function normalizeFormat(format) {
+  if (!format) return null;
+  const normalized = format.toLowerCase();
+  return normalized === 'jpg' ? 'jpeg' : normalized;
+}
+

package/src/planTasks.js

@@ -0,0 +1,42 @@
+import { readdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { SUPPORTED_INPUT_FORMATS } from './formats.js';
+
+/**
+ * Plans tasks for processing images in a directory
+ * Returns array of file paths to process
+ */
+export function planTasks(directoryPath) {
+  const resolvedPath = resolve(directoryPath);
+  const tasks = [];
+  
+  try {
+    const entries = readdirSync(resolvedPath);
+    
+    for (const entry of entries) {
+      const entryPath = join(resolvedPath, entry);
+      
+      try {
+        const stats = statSync(entryPath);
+        
+        // Only process files (not directories)
+        if (stats.isFile()) {
+          // Check if file has supported extension
+          const ext = entry.split('.').pop()?.toLowerCase();
+          
+          if (ext && SUPPORTED_INPUT_FORMATS.includes(ext)) {
+            tasks.push(entryPath);
+          }
+        }
+      } catch (err) {
+        // Skip entries we can't stat (permissions, etc.)
+        continue;
+      }
+    }
+  } catch (error) {
+    throw new Error(`Failed to read directory: ${error.message}`);
+  }
+  
+  return tasks;
+}
+

package/src/processImage.js

@@ -0,0 +1,216 @@
+import sharp from 'sharp';
+import { readFileSync, statSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { buildOutputPath } from './buildOutputPath.js';
+import { 
+  normalizeFormat, 
+  supportsTransparency, 
+  supportsLossless,
+  getDefaultQuality,
+  isValidOutputFormat
+} from './formats.js';
+import { calculateStats, formatBytes } from './stats.js';
+
+/**
+ * Processes a single image file
+ * @param {string} inputPath - Input file path
+ * @param {object} config - Processing configuration
+ * @param {number} fileIndex - Optional 0-based index for batch processing (used in rename patterns)
+ */
+export async function processImage(inputPath, config, fileIndex = null) {
+  const resolvedInputPath = resolve(inputPath);
+  
+  // Check if input file exists
+  if (!existsSync(resolvedInputPath)) {
+    throw new Error(`Input file not found: ${resolvedInputPath}`);
+  }
+  
+  // Get original file size
+  const originalStats = statSync(resolvedInputPath);
+  const originalSize = originalStats.size;
+  
+  // Read image metadata
+  const image = sharp(resolvedInputPath);
+  const metadata = await image.metadata();
+  
+  // Determine output format
+  const outputFormat = config.format 
+    ? normalizeFormat(config.format)
+    : normalizeFormat(metadata.format);
+  
+  // Validate output format
+  if (config.format && !isValidOutputFormat(config.format)) {
+    throw new Error(`Unsupported output format: ${config.format}`);
+  }
+  
+  // Build output path
+  const outputPath = buildOutputPath(resolvedInputPath, config, fileIndex);
+  
+  // Safety check: If input and output paths are the same, require --overwrite
+  // This prevents accidental in-place overwrites
+  if (resolvedInputPath === outputPath && !config.overwrite) {
+    throw new Error(`Input and output paths are the same: ${outputPath}. Use --overwrite to process in-place.`);
+  }
+  
+  // Check if output exists and overwrite is not enabled
+  if (!config.overwrite && existsSync(outputPath)) {
+    throw new Error(`Output file already exists: ${outputPath} (use --overwrite to overwrite)`);
+  }
+  
+  // Prepare Sharp pipeline
+  let pipeline = image.clone();
+  
+  // Handle resize
+  if (config.width || config.height) {
+    const resizeOptions = {};
+    
+    if (config.width && config.height) {
+      // Both dimensions provided - exact resize
+      resizeOptions.width = config.width;
+      resizeOptions.height = config.height;
+    } else if (config.width) {
+      // Only width - preserve aspect ratio
+      resizeOptions.width = config.width;
+      resizeOptions.height = null;
+    } else if (config.height) {
+      // Only height - preserve aspect ratio
+      resizeOptions.width = null;
+      resizeOptions.height = config.height;
+    }
+    
+    pipeline = pipeline.resize(resizeOptions);
+  }
+  
+  // Handle format conversion and quality
+  const formatOptions = {};
+  
+  // Check if output format supports transparency
+  const outputSupportsTransparency = supportsTransparency(config.format || metadata.format);
+  const inputHasAlpha = metadata.hasAlpha;
+  
+  // Handle transparency for formats that don't support it (JPG)
+  if (inputHasAlpha && !outputSupportsTransparency) {
+    if (config.alphaMode === 'error') {
+      throw new Error(`Input has transparency but output format ${outputFormat} does not support it. Use --alpha-mode flatten or choose a format that supports transparency.`);
+    }
+    
+    // Flatten onto background color
+    const background = parseColor(config.background);
+    pipeline = pipeline.flatten({ background });
+  }
+  
+  // Set quality/lossless
+  if (config.lossless) {
+    if (supportsLossless(outputFormat)) {
+      formatOptions.lossless = true;
+    } else {
+      console.warn(`Warning: Lossless compression not supported for ${outputFormat}, using quality settings instead.`);
+    }
+  }
+  
+  // Set quality if not lossless or if lossless not supported
+  if (!formatOptions.lossless) {
+    const quality = config.quality || getDefaultQuality(outputFormat);
+    if (quality !== null) {
+      formatOptions.quality = quality;
+    }
+  }
+  
+  // Convert to output format
+  switch (outputFormat) {
+    case 'png':
+      pipeline = pipeline.png(formatOptions);
+      break;
+    case 'jpeg':
+      pipeline = pipeline.jpeg(formatOptions);
+      break;
+    case 'webp':
+      pipeline = pipeline.webp(formatOptions);
+      break;
+    case 'avif':
+      pipeline = pipeline.avif(formatOptions);
+      break;
+    default:
+      // Keep original format
+      break;
+  }
+  
+  // Ensure output directory exists (only create when about to write)
+  const { mkdirSync } = await import('fs');
+  const { dirname } = await import('path');
+  const outputDir = dirname(outputPath);
+  mkdirSync(outputDir, { recursive: true });
+  
+  // Write output
+  await pipeline.toFile(outputPath);
+  
+  // Get final file size
+  const finalStats = statSync(outputPath);
+  const finalSize = finalStats.size;
+  
+  // Calculate statistics
+  const stats = calculateStats(originalSize, finalSize);
+  
+  // Handle delete original if requested
+  // Safety: Only delete after successful write, and only if paths differ
+  // This prevents accidental deletion of the output file or same-path scenarios
+  let deleteError = null;
+  if (config.deleteOriginal && resolvedInputPath !== outputPath) {
+    try {
+      const { unlinkSync } = await import('fs');
+      // Verify file still exists before attempting deletion
+      if (existsSync(resolvedInputPath)) {
+        unlinkSync(resolvedInputPath);
+      } else {
+        console.warn(`Original file already deleted or not found: ${resolvedInputPath}`);
+      }
+    } catch (err) {
+      // Don't fail the entire operation if deletion fails
+      // Log warning but continue processing
+      console.warn(`Failed to delete original file ${resolvedInputPath}:`, err.message);
+      deleteError = err;
+    }
+  }
+  
+  return {
+    inputPath: resolvedInputPath,
+    outputPath,
+    originalSize,
+    finalSize,
+    ...stats,
+    metadata: {
+      width: metadata.width,
+      height: metadata.height,
+      format: metadata.format,
+      hasAlpha: metadata.hasAlpha
+    },
+    deleteError: deleteError ? deleteError.message : null
+  };
+}
+
+/**
+ * Parses a color string (hex, rgb, etc.) to RGBA object
+ * Simple implementation for hex colors
+ */
+function parseColor(color) {
+  // Handle hex colors (#ffffff, #fff)
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    if (hex.length === 3) {
+      // Short hex (#fff -> #ffffff)
+      const r = parseInt(hex[0] + hex[0], 16);
+      const g = parseInt(hex[1] + hex[1], 16);
+      const b = parseInt(hex[2] + hex[2], 16);
+      return { r, g, b, alpha: 1 };
+    } else if (hex.length === 6) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      return { r, g, b, alpha: 1 };
+    }
+  }
+  
+  // Default to white if parsing fails
+  return { r: 255, g: 255, b: 255, alpha: 1 };
+}
+

package/src/reporter.js

@@ -0,0 +1,115 @@
+import chalk from 'chalk';
+import { formatBytes } from './stats.js';
+
+/**
+ * Reporter class to track processing results
+ */
+export class Reporter {
+  constructor() {
+    this.processed = [];
+    this.skipped = [];
+    this.failed = [];
+  }
+  
+  /**
+   * Record a successfully processed file
+   */
+  recordProcessed(result) {
+    this.processed.push(result);
+  }
+  
+  /**
+   * Record a skipped file
+   */
+  recordSkipped(filePath, reason) {
+    this.skipped.push({ filePath, reason });
+  }
+  
+  /**
+   * Record a failed file
+   */
+  recordFailed(filePath, error) {
+    this.failed.push({ filePath, error: error.message || String(error) });
+  }
+  
+  /**
+   * Calculate totals
+   */
+  getTotals() {
+    const totalOriginal = this.processed.reduce((sum, r) => sum + r.originalSize, 0);
+    const totalFinal = this.processed.reduce((sum, r) => sum + r.finalSize, 0);
+    const totalSaved = totalOriginal - totalFinal;
+    const percentSaved = totalOriginal > 0 
+      ? ((totalSaved / totalOriginal) * 100).toFixed(2)
+      : '0.00';
+    
+    return {
+      totalOriginal,
+      totalFinal,
+      totalSaved,
+      percentSaved: parseFloat(percentSaved),
+      processedCount: this.processed.length,
+      skippedCount: this.skipped.length,
+      failedCount: this.failed.length
+    };
+  }
+  
+  /**
+   * Print summary report
+   */
+  printSummary(verbose = false) {
+    const totals = this.getTotals();
+    
+    console.log(chalk.cyan('\n' + '='.repeat(60)));
+    console.log(chalk.bold.cyan('Processing Summary'));
+    console.log(chalk.cyan('='.repeat(60)));
+    
+    // Overall statistics
+    if (totals.processedCount > 0) {
+      console.log(chalk.green(`\n✓ Processed: ${totals.processedCount} file(s)`));
+      console.log(chalk.gray(`  Total original size: ${formatBytes(totals.totalOriginal)}`));
+      console.log(chalk.gray(`  Total final size:    ${formatBytes(totals.totalFinal)}`));
+      console.log(chalk.gray(`  Total saved:         ${formatBytes(totals.totalSaved)} (${totals.percentSaved}%)`));
+    }
+    
+    // Skipped files
+    if (totals.skippedCount > 0) {
+      console.log(chalk.yellow(`\n⚠ Skipped: ${totals.skippedCount} file(s)`));
+      if (verbose) {
+        this.skipped.forEach(({ filePath, reason }) => {
+          console.log(chalk.gray(`  - ${filePath}: ${reason}`));
+        });
+      }
+    }
+    
+    // Failed files
+    if (totals.failedCount > 0) {
+      console.log(chalk.red(`\n✗ Failed: ${totals.failedCount} file(s)`));
+      if (verbose) {
+        this.failed.forEach(({ filePath, error }) => {
+          console.log(chalk.gray(`  - ${filePath}: ${error}`));
+        });
+      }
+    }
+    
+    console.log(chalk.cyan('\n' + '='.repeat(60)));
+  }
+  
+  /**
+   * Print per-file results (for verbose mode)
+   */
+  printFileResult(result, verbose = false) {
+    if (verbose) {
+      console.log(chalk.green(`\n✓ ${result.outputPath}`));
+      console.log(chalk.gray(`  Original: ${formatBytes(result.originalSize)} (${result.metadata.width}x${result.metadata.height})`));
+      console.log(chalk.gray(`  Final:    ${formatBytes(result.finalSize)}`));
+      console.log(chalk.gray(`  Saved:    ${formatBytes(result.bytesSaved)} (${result.percentSaved}%)`));
+      
+      // Warn if deletion failed
+      if (result.deleteError) {
+        console.log(chalk.yellow(`  Warning: Failed to delete original: ${result.deleteError}`));
+      }
+    }
+  }
+}
+

package/src/runJob.js

@@ -0,0 +1,97 @@
+import { statSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { processImage } from './processImage.js';
+import { planTasks } from './planTasks.js';
+import { Reporter } from './reporter.js';
+
+/**
+ * Orchestrates image processing job
+ * Returns pure JS object with results (no terminal output)
+ * 
+ * @param {string} inputPath - Input file or directory path
+ * @param {object} config - Processing configuration
+ * @returns {Promise<object>} Results object with processed, skipped, failed arrays and totals
+ */
+export async function runJob(inputPath, config) {
+  const resolvedInputPath = resolve(inputPath);
+  
+  // Validate input exists
+  if (!existsSync(resolvedInputPath)) {
+    throw new Error(`Input not found: ${resolvedInputPath}`);
+  }
+  
+  const inputStats = statSync(resolvedInputPath);
+  const isDirectory = inputStats.isDirectory();
+  const isFile = inputStats.isFile();
+  
+  if (!isFile && !isDirectory) {
+    throw new Error(`Input must be a file or directory: ${resolvedInputPath}`);
+  }
+  
+  // Initialize reporter for data aggregation (not printing)
+  const reporter = new Reporter();
+  
+  if (isFile) {
+    // Single file processing
+    try {
+      const result = await processImage(resolvedInputPath, config, 0);
+      reporter.recordProcessed(result);
+    } catch (error) {
+      // Check if it's a skip (file exists or same path) or a real error
+      if (error.message.includes('already exists') || error.message.includes('Input and output paths are the same')) {
+        reporter.recordSkipped(resolvedInputPath, error.message);
+      } else {
+        reporter.recordFailed(resolvedInputPath, error);
+      }
+    }
+  } else {
+    // Directory processing
+    const tasks = planTasks(resolvedInputPath);
+    
+    if (tasks.length === 0) {
+      // Return empty results for empty directory
+      return {
+        processed: [],
+        skipped: [],
+        failed: [],
+        totals: {
+          totalOriginal: 0,
+          totalFinal: 0,
+          totalSaved: 0,
+          percentSaved: 0,
+          processedCount: 0,
+          skippedCount: 0,
+          failedCount: 0
+        }
+      };
+    }
+    
+    // Process each file
+    for (let i = 0; i < tasks.length; i++) {
+      const filePath = tasks[i];
+      try {
+        const result = await processImage(filePath, config, i);
+        reporter.recordProcessed(result);
+      } catch (error) {
+        // Check if it's a skip (file exists or same path) or a real error
+        if (error.message.includes('already exists') || error.message.includes('Input and output paths are the same')) {
+          reporter.recordSkipped(filePath, error.message);
+        } else {
+          reporter.recordFailed(filePath, error);
+        }
+      }
+    }
+  }
+  
+  // Get totals from reporter
+  const totals = reporter.getTotals();
+  
+  // Return pure JS object (no terminal output)
+  return {
+    processed: reporter.processed,
+    skipped: reporter.skipped,
+    failed: reporter.failed,
+    totals
+  };
+}
+

package/src/stats.js

@@ -0,0 +1,30 @@
+/**
+ * Calculates file size statistics
+ */
+export function calculateStats(originalSize, finalSize) {
+  const bytesSaved = originalSize - finalSize;
+  const percentSaved = originalSize > 0 
+    ? ((bytesSaved / originalSize) * 100).toFixed(2)
+    : '0.00';
+  
+  return {
+    originalSize,
+    finalSize,
+    bytesSaved,
+    percentSaved: parseFloat(percentSaved)
+  };
+}
+
+/**
+ * Formats bytes to human-readable string
+ */
+export function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+