@ecopages/image-processor 0.2.0-alpha.1

package/src/image-processor.d.ts

@@ -0,0 +1,19 @@
+import type { ImageMap, ImageProcessorConfig } from './plugin';
+import type { ImageSpecifications } from './types';
+/**
+ * ImageProcessor
+ * This is the core class for processing images.
+ * It uses the sharp library to resize and optimize images.
+ */
+export declare class ImageProcessor {
+    private readonly config;
+    private readonly cacheManager;
+    constructor(config: ImageProcessorConfig, cacheManager: {
+        readCache: <T>(key: string) => Promise<T | null>;
+        writeCache: <T>(key: string, data: T) => Promise<void>;
+    });
+    private calculateDimensions;
+    private getOutputPath;
+    processImage(imagePath: string): Promise<ImageSpecifications | null>;
+    processDirectory(): Promise<ImageMap>;
+}

package/src/image-processor.js

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { deepMerge } from "@ecopages/core/utils/deep-merge";
+import { fileSystem } from "@ecopages/file-system";
+import { Logger } from "@ecopages/logger";
+import sharp from "sharp";
+import { ImageUtils } from "./image-utils";
+const appLogger = new Logger("[@ecopages/image-processor]", {
+  debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
+});
+class ImageProcessor {
+  config;
+  cacheManager;
+  constructor(config, cacheManager) {
+    this.config = deepMerge({ cacheEnabled: true }, config);
+    this.cacheManager = cacheManager;
+    fileSystem.ensureDir(this.config.outputDir);
+  }
+  async calculateDimensions(metadata, targetWidth) {
+    const originalWidth = metadata.width || 0;
+    const originalHeight = metadata.height || 0;
+    const aspectRatio = originalHeight / originalWidth;
+    const width = Math.min(targetWidth, originalWidth);
+    const height = Math.round(width * aspectRatio);
+    return { width, height };
+  }
+  getOutputPath(imagePath, width) {
+    const hash = fileSystem.hash(imagePath);
+    const ext = path.extname(imagePath);
+    const base = path.basename(imagePath, ext);
+    const filename = `${base}-${hash}-${width}.${this.config.format}`;
+    return path.join(this.config.outputDir, filename);
+  }
+  async processImage(imagePath) {
+    try {
+      const fileHash = fileSystem.hash(imagePath);
+      const cacheKey = `${path.basename(imagePath)}:${fileHash}`;
+      if (this.config.cacheEnabled) {
+        const cached = await this.cacheManager.readCache(cacheKey);
+        if (cached) {
+          const mainFilePath = path.join(process.cwd(), cached.attributes.src);
+          const mainFileExists = fileSystem.exists(mainFilePath);
+          const variantsExist = cached.variants.every(
+            (v) => fileSystem.exists(path.join(process.cwd(), v.src))
+          );
+          if (mainFileExists && variantsExist) {
+            appLogger.debug(`Cache hit for ${imagePath}`);
+            return cached;
+          }
+          appLogger.debug(`Cache invalid for ${imagePath}, reprocessing`);
+        }
+      }
+      fileSystem.ensureDir(this.config.outputDir);
+      const metadata = await sharp(imagePath).metadata();
+      const originalWidth = metadata.width || 0;
+      const originalHeight = metadata.height || 0;
+      if (this.config.sizes.length === 0) {
+        const outputPath = this.getOutputPath(imagePath, originalWidth);
+        if (fileSystem.exists(outputPath)) {
+          appLogger.debug(`Using existing file for ${imagePath}`);
+        } else {
+          await sharp(imagePath).toFormat(this.config.format, { quality: this.config.quality }).toFile(outputPath);
+        }
+        const src = path.join(this.config.publicPath, path.basename(outputPath));
+        const imageSpecifications2 = {
+          attributes: {
+            src,
+            width: originalWidth,
+            height: originalHeight,
+            sizes: ""
+          },
+          variants: [],
+          cacheKey
+        };
+        if (this.config.cacheEnabled) {
+          await this.cacheManager.writeCache(cacheKey, imageSpecifications2);
+        }
+        return imageSpecifications2;
+      }
+      let applicableSizes = this.config.sizes.filter((size) => size.width <= originalWidth).sort((a, b) => b.width - a.width);
+      if (applicableSizes.length === 0) {
+        applicableSizes = this.config.sizes.sort((a, b) => b.width - a.width).slice(0, 1);
+      }
+      const variants = await Promise.all(
+        applicableSizes.map(async ({ width: targetWidth, label }) => {
+          const { width, height } = await this.calculateDimensions(metadata, targetWidth);
+          const outputPath = this.getOutputPath(imagePath, width);
+          if (fileSystem.exists(outputPath)) {
+            appLogger.debug(`Variant ${width}px already exists for ${imagePath}`);
+          } else {
+            await sharp(imagePath).resize(width, height).toFormat(this.config.format, { quality: this.config.quality }).toFile(outputPath);
+          }
+          const src = path.join(this.config.publicPath, path.basename(outputPath));
+          return {
+            width,
+            height,
+            src,
+            label
+          };
+        })
+      );
+      const mainVariant = variants[0];
+      const attributes = {
+        src: mainVariant.src,
+        width: mainVariant.width,
+        height: mainVariant.height,
+        sizes: ImageUtils.generateSizes(variants),
+        srcset: ImageUtils.generateSrcset(variants)
+      };
+      const imageSpecifications = {
+        attributes,
+        variants,
+        cacheKey
+      };
+      if (this.config.cacheEnabled) {
+        await this.cacheManager.writeCache(cacheKey, imageSpecifications);
+      }
+      return imageSpecifications;
+    } catch (error) {
+      appLogger.error(`Failed to process image ${imagePath}:`, error);
+      return null;
+    }
+  }
+  async processDirectory() {
+    const acceptedFormats = this.config.acceptedFormats || ["jpg", "jpeg", "png", "webp"];
+    const images = await fileSystem.glob([`${this.config.sourceDir}/**/*.{${acceptedFormats.join(",")}}`]);
+    appLogger.debugTime("Processing images");
+    const results = (await Promise.all(
+      images.map(async (file) => {
+        const processed = await this.processImage(file);
+        if (!processed) return null;
+        return [path.basename(file), processed];
+      })
+    )).filter(Boolean);
+    appLogger.debugTimeEnd("Processing images");
+    appLogger.info(`Processed ${results.length} images`);
+    return Object.fromEntries(results);
+  }
+}
+export {
+  ImageProcessor
+};

package/src/image-processor.ts

@@ -0,0 +1,201 @@
+import path from 'node:path';
+import { deepMerge } from '@ecopages/core/utils/deep-merge';
+import { fileSystem } from '@ecopages/file-system';
+import { Logger } from '@ecopages/logger';
+import sharp from 'sharp';
+import { ImageUtils } from './image-utils';
+import type { ImageMap, ImageProcessorConfig } from './plugin';
+import type { ImageAttributes, ImageSpecifications, ImageVariant } from './types';
+
+const appLogger = new Logger('[@ecopages/image-processor]', {
+	debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true',
+});
+
+/**
+ * ImageProcessor
+ * This is the core class for processing images.
+ * It uses the sharp library to resize and optimize images.
+ */
+export class ImageProcessor {
+	private readonly config: ImageProcessorConfig;
+	private readonly cacheManager: {
+		readCache: <T>(key: string) => Promise<T | null>;
+		writeCache: <T>(key: string, data: T) => Promise<void>;
+	};
+
+	constructor(
+		config: ImageProcessorConfig,
+		cacheManager: {
+			readCache: <T>(key: string) => Promise<T | null>;
+			writeCache: <T>(key: string, data: T) => Promise<void>;
+		},
+	) {
+		this.config = deepMerge({ cacheEnabled: true }, config);
+		this.cacheManager = cacheManager;
+		fileSystem.ensureDir(this.config.outputDir);
+	}
+
+	private async calculateDimensions(metadata: sharp.Metadata, targetWidth: number) {
+		const originalWidth = metadata.width || 0;
+		const originalHeight = metadata.height || 0;
+		const aspectRatio = originalHeight / originalWidth;
+		const width = Math.min(targetWidth, originalWidth);
+		const height = Math.round(width * aspectRatio);
+		return { width, height };
+	}
+
+	private getOutputPath(imagePath: string, width: number) {
+		const hash = fileSystem.hash(imagePath);
+		const ext = path.extname(imagePath);
+		const base = path.basename(imagePath, ext);
+		const filename = `${base}-${hash}-${width}.${this.config.format}`;
+		return path.join(this.config.outputDir, filename);
+	}
+
+	async processImage(imagePath: string): Promise<ImageSpecifications | null> {
+		try {
+			const fileHash = fileSystem.hash(imagePath);
+			const cacheKey = `${path.basename(imagePath)}:${fileHash}`;
+
+			if (this.config.cacheEnabled) {
+				const cached = await this.cacheManager.readCache<ImageSpecifications>(cacheKey);
+				if (cached) {
+					/**
+					 * Verify that the files actually exist
+					 * We construct the absolute path relative to the process current working directory
+					 * since the src in attributes is relative from the root
+					 */
+					const mainFilePath = path.join(process.cwd(), cached.attributes.src);
+					const mainFileExists = fileSystem.exists(mainFilePath);
+					const variantsExist = cached.variants.every((v) =>
+						fileSystem.exists(path.join(process.cwd(), v.src)),
+					);
+
+					if (mainFileExists && variantsExist) {
+						appLogger.debug(`Cache hit for ${imagePath}`);
+						return cached;
+					}
+
+					appLogger.debug(`Cache invalid for ${imagePath}, reprocessing`);
+				}
+			}
+
+			fileSystem.ensureDir(this.config.outputDir);
+
+			const metadata = await sharp(imagePath).metadata();
+			const originalWidth = metadata.width || 0;
+			const originalHeight = metadata.height || 0;
+
+			if (this.config.sizes.length === 0) {
+				const outputPath = this.getOutputPath(imagePath, originalWidth);
+
+				if (fileSystem.exists(outputPath)) {
+					appLogger.debug(`Using existing file for ${imagePath}`);
+				} else {
+					await sharp(imagePath)
+						.toFormat(this.config.format, { quality: this.config.quality })
+						.toFile(outputPath);
+				}
+
+				const src = path.join(this.config.publicPath, path.basename(outputPath));
+
+				const imageSpecifications: ImageSpecifications = {
+					attributes: {
+						src,
+						width: originalWidth,
+						height: originalHeight,
+						sizes: '',
+					},
+					variants: [],
+					cacheKey,
+				};
+
+				if (this.config.cacheEnabled) {
+					await this.cacheManager.writeCache(cacheKey, imageSpecifications);
+				}
+
+				return imageSpecifications;
+			}
+
+			let applicableSizes = this.config.sizes
+				.filter((size) => size.width <= originalWidth)
+				.sort((a, b) => b.width - a.width);
+
+			if (applicableSizes.length === 0) {
+				applicableSizes = this.config.sizes.sort((a, b) => b.width - a.width).slice(0, 1);
+			}
+
+			const variants: ImageVariant[] = await Promise.all(
+				applicableSizes.map(async ({ width: targetWidth, label }) => {
+					const { width, height } = await this.calculateDimensions(metadata, targetWidth);
+					const outputPath = this.getOutputPath(imagePath, width);
+
+					if (fileSystem.exists(outputPath)) {
+						appLogger.debug(`Variant ${width}px already exists for ${imagePath}`);
+					} else {
+						await sharp(imagePath)
+							.resize(width, height)
+							.toFormat(this.config.format, { quality: this.config.quality })
+							.toFile(outputPath);
+					}
+
+					const src = path.join(this.config.publicPath, path.basename(outputPath));
+
+					return {
+						width,
+						height,
+						src,
+						label,
+					};
+				}),
+			);
+
+			const mainVariant = variants[0];
+			const attributes: ImageAttributes = {
+				src: mainVariant.src,
+				width: mainVariant.width,
+				height: mainVariant.height,
+				sizes: ImageUtils.generateSizes(variants),
+				srcset: ImageUtils.generateSrcset(variants),
+			};
+
+			const imageSpecifications: ImageSpecifications = {
+				attributes,
+				variants,
+				cacheKey,
+			};
+
+			if (this.config.cacheEnabled) {
+				await this.cacheManager.writeCache(cacheKey, imageSpecifications);
+			}
+
+			return imageSpecifications;
+		} catch (error) {
+			appLogger.error(`Failed to process image ${imagePath}:`, error as Error);
+			return null;
+		}
+	}
+
+	async processDirectory(): Promise<ImageMap> {
+		const acceptedFormats = this.config.acceptedFormats || ['jpg', 'jpeg', 'png', 'webp'];
+
+		const images = await fileSystem.glob([`${this.config.sourceDir}/**/*.{${acceptedFormats.join(',')}}`]);
+
+		appLogger.debugTime('Processing images');
+
+		const results = (
+			await Promise.all(
+				images.map(async (file) => {
+					const processed = await this.processImage(file);
+					if (!processed) return null;
+					return [path.basename(file), processed] as [string, ImageSpecifications];
+				}),
+			)
+		).filter(Boolean) as [string, ImageSpecifications][];
+
+		appLogger.debugTimeEnd('Processing images');
+		appLogger.info(`Processed ${results.length} images`);
+
+		return Object.fromEntries(results);
+	}
+}

package/src/image-renderer.d.ts

@@ -0,0 +1,152 @@
+/**
+ * ImageRenderer
+ * @module
+ */
+import type { ImageSpecifications } from './types';
+/**
+ * Image layout options
+ */
+export type ImageLayout = 'fixed' | 'constrained' | 'full-width';
+/**
+ * ImageProps
+ * This interface represents the properties that can be passed to the image element
+ */
+export type EcoImageProps = ImageSpecifications & {
+    /**
+     * width of the image as defined in the component
+     */
+    width?: number;
+    /**
+     * height of the image as defined in the component
+     */
+    height?: number;
+    /**
+     * The alt text for the image
+     */
+    aspectRatio?: string;
+    /**
+     * If true, the image will be loaded eagerly
+     */
+    priority?: boolean;
+    /**
+     * The layout of the image
+     * @default "constrained"
+     */
+    layout?: ImageLayout;
+    /**
+     * If true, the image will not have any styles applied to it
+     */
+    unstyled?: boolean;
+    /**
+     * Specifies a fixed image variant from the configuration.
+     * This should match one of the variant labels defined in your image optimization config.
+     * When set, the image will use this specific variant instead of responsive sizes.
+     */
+    staticVariant?: string;
+    /**
+     * Optional additional attributes to be added to the image element
+     */
+    [additionalAttributes: string]: any;
+};
+/**
+ * CollectedAttributes
+ * This interface represents the attributes that are collected by the image renderer
+ * These attributes are used to generate the attributes for the image element
+ */
+export interface CollectedAttributes {
+    width?: number;
+    height?: number;
+    loading: HTMLImageElement['loading'];
+    fetchpriority: HTMLImageElement['fetchPriority'];
+    decoding: HTMLImageElement['decoding'];
+    src: string;
+    srcset?: string;
+    sizes?: string;
+    styles: [string, string][];
+}
+/**
+ * GenerateAttributesResult
+ * This interface represents the result of the generateAttributes method
+ */
+export interface GenerateAttributesResult {
+    fetchpriority: HTMLImageElement['fetchPriority'];
+    loading: HTMLImageElement['loading'];
+    decoding: HTMLImageElement['decoding'];
+    src: string;
+    srcset?: string;
+    sizes?: string;
+    width?: number;
+    height?: number;
+    style?: string;
+}
+/**
+ * GenerateAttributesResultJsx
+ * This interface represents the result of the generateAttributes method as JSX
+ */
+export interface GenerateAttributesResultJsx {
+    fetchPriority: HTMLImageElement['fetchPriority'];
+    loading: HTMLImageElement['loading'];
+    decoding: HTMLImageElement['decoding'];
+    src: string;
+    srcSet?: string;
+    sizes?: string;
+    width?: number;
+    height?: number;
+    style?: React.CSSProperties;
+}
+/**
+ * IImageRenderer
+ * This interface represents the image renderer in charge of generating the attributes for the image element
+ */
+export interface IImageRenderer {
+    /**
+     * This method generates the attributes for the image element based on the provided props
+     * This is the main method that should be used to generate the attributes for the image element
+     * @param props
+     */
+    generateAttributes(props: EcoImageProps): GenerateAttributesResult | null;
+    /**
+     * This method generates the attributes for the image element based on the provided props as JSX
+     * @param props
+     */
+    generateAttributesJsx(props: EcoImageProps): GenerateAttributesResultJsx | null;
+    /**
+     * This method generates the image element based on the provided props as a string
+     * @param props
+     */
+    renderToString(props: EcoImageProps): string;
+}
+export declare class LayoutAttributesManager {
+    static shouldIncludeWidthHeight(layout: ImageLayout): boolean;
+    static filterDimensionAttributes(props: Pick<EcoImageProps, 'width' | 'height' | 'layout'>): Pick<EcoImageProps, 'width' | 'height'>;
+    static getEffectiveDimensions(props: EcoImageProps, variants?: Array<{
+        width: number;
+        height: number;
+    }>): {
+        width?: number;
+        height?: number;
+    };
+}
+/**
+ * ImageRenderer
+ * This class is responsible for generating the attributes for the image element
+ */
+export declare class ImageRenderer implements IImageRenderer {
+    private originalProps?;
+    private readonly internalProps;
+    generateAttributes(props: EcoImageProps): GenerateAttributesResult | null;
+    private getHtmlAttributes;
+    generateAttributesJsx(props: EcoImageProps): GenerateAttributesResultJsx | null;
+    renderToString({ attributes, variants, ...rest }: EcoImageProps): string;
+    private collectAttributes;
+    private getPriorityAttributes;
+    private getMainVariant;
+    private calculateEffectiveDimensions;
+    private calculateStyles;
+    private buildImageAttributes;
+    private handleNoVariants;
+    private stringifyAttributes;
+    private generateStyleString;
+    private createCamelCaseKeysOnStyle;
+}
+export declare const renderer: ImageRenderer;