Image Processing

/**
 * Queues a single image transformation job
 * @param options - Configuration object
 * @param options.file - Gatsby file node to process
 * @param options.args - Transform arguments specifying output parameters
 * @param options.reporter - Gatsby reporter instance for logging
 * @returns Promise resolving to processed image result
 */
function queueImageResizing(options: {
  file: FileNode;
  args: ITransformArgs;
  reporter: Reporter;
}): Promise<ImageResult>;

interface ImageResult {
  src: string;           // URL path to processed image
  absolutePath: string;  // Absolute file system path
  width: number;         // Output image width in pixels
  height: number;        // Output image height in pixels
  aspectRatio: number;   // Width/height ratio
  originalName: string;  // Original filename
  finishedPromise: Promise<void>; // Promise that resolves when processing completes
}

const sharp = require("gatsby-plugin-sharp");

// Basic image resize
const result = await sharp.queueImageResizing({
  file: fileNode,
  args: {
    width: 800,
    height: 600,
    quality: 80
  },
  reporter
});

// WebP conversion with crop
const webpResult = await sharp.queueImageResizing({
  file: fileNode,
  args: {
    width: 1200,
    toFormat: "webp",
    quality: 85,
    fit: "cover",
    cropFocus: "attention"
  },
  reporter
});

// Grayscale transformation
const bwResult = await sharp.queueImageResizing({
  file: fileNode,
  args: {
    width: 500,
    grayscale: true,
    quality: 75
  },
  reporter
});

/**
 * Queues multiple image transformations for a single image in batch
 * @param options - Configuration object
 * @param options.file - Gatsby file node to process
 * @param options.transforms - Array of transform argument objects
 * @param options.reporter - Gatsby reporter instance for logging
 * @returns Promise resolving to array of processed image results
 */
function batchQueueImageResizing(options: {
  file: FileNode;
  transforms: ITransformArgs[];
  reporter: Reporter;
}): Promise<ImageResult[]>;

const sharp = require("gatsby-plugin-sharp");

// Generate multiple sizes of the same image
const sizes = await sharp.batchQueueImageResizing({
  file: fileNode,
  transforms: [
    { width: 400, quality: 80 },
    { width: 800, quality: 80 },
    { width: 1200, quality: 80 },
    { width: 1600, quality: 80 }
  ],
  reporter
});

// Generate multiple formats
const formats = await sharp.batchQueueImageResizing({
  file: fileNode,
  transforms: [
    { width: 800, toFormat: "jpg", quality: 85 },
    { width: 800, toFormat: "webp", quality: 80 },
    { width: 800, toFormat: "avif", quality: 75 }
  ],
  reporter
});

/**
 * Alias for queueImageResizing function
 */
const resize = queueImageResizing;

interface ITransformArgs {
  /** Output width in pixels */
  width?: number;
  /** Output height in pixels */
  height?: number;
  /** Image quality (1-100) */
  quality?: number;
  /** Output format: "jpg", "png", "webp", "avif", "tiff" */
  toFormat?: string;
  /** Crop focus for resizing: "center", "top", "bottom", "left", "right", "attention", etc. */
  cropFocus?: number | string;
  /** Background color for transparent areas */
  background?: string;
  /** How to resize: "cover", "contain", "fill", "inside", "outside" */
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  /** Convert to grayscale */
  grayscale?: boolean;
  /** Rotation angle in degrees */
  rotate?: number;
  /** Trim whitespace pixels */
  trim?: number;
  /** Duotone effect configuration */
  duotone?: {
    highlight: string;  // Hex color for highlights
    shadow: string;     // Hex color for shadows
    opacity?: number;   // Effect opacity (0-1)
  };
  /** PNG compression level (0-9) */
  pngCompressionLevel?: number;
  /** JPEG quality (overrides general quality) */
  jpegQuality?: number;
  /** PNG quality (overrides general quality) */
  pngQuality?: number;
  /** WebP quality (overrides general quality) */
  webpQuality?: number;
  /** Use progressive JPEG encoding */
  jpegProgressive?: boolean;
  /** Maximum width for fluid images */
  maxWidth?: number;
  /** Maximum height for fluid images */
  maxHeight?: number;
  /** Base64 thumbnail width */
  base64Width?: number;
  /** Path prefix for URLs */
  pathPrefix?: string;
}