Responsive Image Query Helper for Gatsby

Build a Node.js module that provides helper functions to query and retrieve responsive image data from Gatsby's GraphQL layer. This module will be used by Gatsby page components to fetch optimized images for blog posts.

Requirements

Core Functionality

The module must provide functions that:

1. Query Gatsby's GraphQL layer to retrieve image nodes by file path
2. Request responsive image transformations with specified dimensions and formats
3. Return image data that includes multiple format variants (WebP, AVIF) and responsive srcSet
4. Handle queries for both constrained (max-width) and full-width responsive layouts

Image Query Specifications

• Accept an image file path (relative to the source directory) and transformation options
• Transformation options should include: layout type (constrained or fullWidth), maximum width, and desired formats
• Return an object containing src, srcSet, sizes, and format-specific sources
• Support querying images that will be processed during the Gatsby build

Integration Requirements

• Use Gatsby's GraphQL client to execute queries against the image data layer
• Work within Gatsby's Node.js API environment
• Return data in a format compatible with modern image display components

Test Cases

• Query an image with constrained layout at 800px width and return data with WebP and AVIF sources @test
• Query an image with fullWidth layout and return data with appropriate breakpoint sizes @test
• Query a non-existent image path and return null without throwing an error @test

API

/**
 * Helper module for querying responsive image data from Gatsby
 */

// Image transformation options
interface ImageQueryOptions {
  // Layout type for the image
  layout: 'constrained' | 'fullWidth';
  // Maximum width in pixels (for constrained layout)
  width?: number;
  // Image formats to generate
  formats?: Array<'AUTO' | 'WEBP' | 'AVIF'>;
}

// Returned image data structure
interface ImageData {
  src: string;
  srcSet: string;
  sizes: string;
  sources: Array<{
    srcSet: string;
    sizes: string;
    type: string;
  }>;
  width: number;
  height: number;
}

/**
 * Query image data from Gatsby's GraphQL layer
 * @param graphql - Gatsby's GraphQL query function
 * @param relativePath - Path to image file relative to source directory
 * @param options - Transformation options
 * @returns Image data object or null if not found
 */
export async function queryImageData(
  graphql: Function,
  relativePath: string,
  options: ImageQueryOptions
): Promise<ImageData | null>;

Implementation

@generates

Dependencies { .dependencies }

gatsby-plugin-sharp { .dependency }

Provides image processing and transformation capabilities for Gatsby. Should be used for all image optimization operations including format conversion, resizing, and responsive image generation.

@satisfied-by