@ecopages/image-processor 0.2.0-alpha.1

package/src/image-utils.js

@@ -0,0 +1,103 @@
+import { DEFAULT_LAYOUT } from "./constants";
+class ImageUtils {
+  static BREAKPOINTS = {
+    desktop: 1024,
+    tablet: 768
+  };
+  static VIEWPORT_SIZES = {
+    desktop: "70vw",
+    tablet: "80vw",
+    mobile: "100vw"
+  };
+  static DEFAULT_LAYOUT = DEFAULT_LAYOUT;
+  /**
+   * Generates a srcset string from processed image variants using relative paths
+   * @param {ImageVariant[]} variants - Array of processed image variants
+   * @returns {string} srcset attribute string
+   * @private
+   */
+  static generateSrcset(variants) {
+    return variants.sort((a, b) => b.width - a.width).map(({ src, width }) => `${src} ${width}w`).join(", ");
+  }
+  /**
+   * Generates sizes attribute based on image variants.
+   * Sizes are generated based on the variant widths and breakpoints.
+   * Here we use a smart approach to generate sizes based on the variant widths.
+   * We start with the largest variant and set a min-width condition for its width.
+   * Then we add conditions for each variant based on the viewport width.
+   * Finally, we add a catch-all for the smallest screens.
+   * This approach ensures that the browser will select the correct image variant based on the viewport width.
+   * @see https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_different_sizes
+   * @param {ImageVariant[]} variants - Array of processed image variants
+   * @returns {string} sizes attribute string
+   * @private
+   */
+  static generateSizes(variants) {
+    if (!variants?.length) return "";
+    const sortedVariants = [...variants].sort((a, b) => b.width - a.width);
+    const [largest, ...rest] = sortedVariants;
+    const conditions = [
+      `(min-width: ${largest.width}px) ${largest.width}px`,
+      ...rest.map((variant) => {
+        if (variant.width >= ImageUtils.BREAKPOINTS.desktop) {
+          return `(min-width: ${variant.width}px) ${ImageUtils.VIEWPORT_SIZES.desktop}`;
+        }
+        if (variant.width >= ImageUtils.BREAKPOINTS.tablet) {
+          return `(min-width: ${variant.width}px) ${ImageUtils.VIEWPORT_SIZES.tablet}`;
+        }
+        return null;
+      }).filter(Boolean),
+      ImageUtils.VIEWPORT_SIZES.mobile
+    ];
+    return conditions.join(", ");
+  }
+  /**
+   * Generates a styles string based on image layout and config
+   * @param {ImageLayout} layout - Image layout type
+   * @param {LayoutAttributes} config - Image layout configuration
+   * @returns {string} styles string
+   * @private
+   */
+  static generateLayoutStyles(config) {
+    const layout = config.layout || ImageUtils.DEFAULT_LAYOUT;
+    const styles = [["object-fit", "cover"]];
+    if (config.aspectRatio) {
+      styles.push(["aspect-ratio", config.aspectRatio]);
+    }
+    switch (layout) {
+      case "fixed":
+        if (config.width) {
+          styles.push(["width", `${config.width}px`], ["min-width", `${config.width}px`]);
+        }
+        if (config.height) {
+          styles.push(["height", `${config.height}px`], ["min-height", `${config.height}px`]);
+        }
+        break;
+      case "constrained":
+        styles.push(["width", "100%"]);
+        if (config.width && config.height) {
+          styles.push(["max-width", `${config.width}px`], ["max-height", `${config.height}px`]);
+          if (!config.aspectRatio) {
+            styles.push(["aspect-ratio", `${config.width}/${config.height}`]);
+          }
+        } else if (config.height) {
+          styles.push(["height", `${config.height}px`], ["min-height", `${config.height}px`]);
+        } else if (config.width) {
+          styles.push(["max-width", `${config.width}px`]);
+        } else if (!config.aspectRatio) {
+          styles.push(["aspect-ratio", `${config.attributes.width}/${config.attributes.height}`]);
+        }
+        break;
+      case "full-width":
+        styles.push(["width", "100%"]);
+        if (config.height) {
+          styles.push(["height", `${config.height}px`], ["min-height", `${config.height}px`]);
+        }
+        break;
+    }
+    return styles;
+  }
+}
+export {
+  ImageUtils
+};

package/src/image-utils.ts

@@ -0,0 +1,128 @@
+import { DEFAULT_LAYOUT } from './constants';
+import type { EcoImageProps } from './image-renderer';
+
+/**
+ * ImageUtils
+ * This class contains utility methods for working with images
+ * It contains methods for generating srcset, sizes and styles attributes for the image element
+ */
+export class ImageUtils {
+	private static readonly BREAKPOINTS = {
+		desktop: 1024,
+		tablet: 768,
+	} as const;
+
+	private static readonly VIEWPORT_SIZES = {
+		desktop: '70vw',
+		tablet: '80vw',
+		mobile: '100vw',
+	} as const;
+
+	static readonly DEFAULT_LAYOUT = DEFAULT_LAYOUT;
+
+	/**
+	 * Generates a srcset string from processed image variants using relative paths
+	 * @param {ImageVariant[]} variants - Array of processed image variants
+	 * @returns {string} srcset attribute string
+	 * @private
+	 */
+	static generateSrcset(variants: Array<{ width: number; src: string }>): string {
+		return variants
+			.sort((a, b) => b.width - a.width)
+			.map(({ src, width }) => `${src} ${width}w`)
+			.join(', ');
+	}
+
+	/**
+	 * Generates sizes attribute based on image variants.
+	 * Sizes are generated based on the variant widths and breakpoints.
+	 * Here we use a smart approach to generate sizes based on the variant widths.
+	 * We start with the largest variant and set a min-width condition for its width.
+	 * Then we add conditions for each variant based on the viewport width.
+	 * Finally, we add a catch-all for the smallest screens.
+	 * This approach ensures that the browser will select the correct image variant based on the viewport width.
+	 * @see https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_different_sizes
+	 * @param {ImageVariant[]} variants - Array of processed image variants
+	 * @returns {string} sizes attribute string
+	 * @private
+	 */
+	static generateSizes(variants: Array<{ width: number }>): string {
+		if (!variants?.length) return '';
+
+		const sortedVariants = [...variants].sort((a, b) => b.width - a.width);
+		const [largest, ...rest] = sortedVariants;
+
+		const conditions = [
+			`(min-width: ${largest.width}px) ${largest.width}px`,
+			...rest
+				.map((variant) => {
+					if (variant.width >= ImageUtils.BREAKPOINTS.desktop) {
+						return `(min-width: ${variant.width}px) ${ImageUtils.VIEWPORT_SIZES.desktop}`;
+					}
+					if (variant.width >= ImageUtils.BREAKPOINTS.tablet) {
+						return `(min-width: ${variant.width}px) ${ImageUtils.VIEWPORT_SIZES.tablet}`;
+					}
+					return null;
+				})
+				.filter(Boolean),
+			ImageUtils.VIEWPORT_SIZES.mobile,
+		];
+
+		return conditions.join(', ');
+	}
+
+	/**
+	 * Generates a styles string based on image layout and config
+	 * @param {ImageLayout} layout - Image layout type
+	 * @param {LayoutAttributes} config - Image layout configuration
+	 * @returns {string} styles string
+	 * @private
+	 */
+	static generateLayoutStyles(
+		config: Pick<EcoImageProps, 'layout' | 'width' | 'height' | 'aspectRatio' | 'attributes'>,
+	): [string, string][] {
+		const layout = config.layout || ImageUtils.DEFAULT_LAYOUT;
+		const styles: [string, string][] = [['object-fit', 'cover']];
+
+		if (config.aspectRatio) {
+			styles.push(['aspect-ratio', config.aspectRatio]);
+		}
+
+		switch (layout) {
+			case 'fixed':
+				if (config.width) {
+					styles.push(['width', `${config.width}px`], ['min-width', `${config.width}px`]);
+				}
+				if (config.height) {
+					styles.push(['height', `${config.height}px`], ['min-height', `${config.height}px`]);
+				}
+				break;
+
+			case 'constrained':
+				styles.push(['width', '100%']);
+
+				if (config.width && config.height) {
+					styles.push(['max-width', `${config.width}px`], ['max-height', `${config.height}px`]);
+					if (!config.aspectRatio) {
+						styles.push(['aspect-ratio', `${config.width}/${config.height}`]);
+					}
+				} else if (config.height) {
+					styles.push(['height', `${config.height}px`], ['min-height', `${config.height}px`]);
+				} else if (config.width) {
+					styles.push(['max-width', `${config.width}px`]);
+				} else if (!config.aspectRatio) {
+					styles.push(['aspect-ratio', `${config.attributes.width}/${config.attributes.height}`]);
+				}
+				break;
+
+			case 'full-width':
+				styles.push(['width', '100%']);
+				if (config.height) {
+					styles.push(['height', `${config.height}px`], ['min-height', `${config.height}px`]);
+				}
+				break;
+		}
+
+		return styles;
+	}
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './image-processor';
+export * from './plugin';
+export * from './types';

package/src/index.js

@@ -0,0 +1,3 @@
+export * from "./image-processor";
+export * from "./plugin";
+export * from "./types";

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './image-processor';
+export * from './plugin';
+export * from './types';

package/src/plugin.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ImageProcessorPlugin
+ * @module @ecopages/image-processor
+ */
+import { Processor, type ProcessorConfig } from '@ecopages/core/plugins/processor';
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { ImageProcessor } from './image-processor';
+import type { ImageSize, ImageSpecifications } from './types';
+/**
+ * Configuration for the image processor
+ */
+export interface ImageProcessorConfig {
+    sourceDir: string;
+    outputDir: string;
+    publicPath: string;
+    /**
+     * @default []
+     */
+    sizes: ImageSize[];
+    quality: number;
+    format: 'webp' | 'jpeg' | 'png' | 'avif';
+    /**
+     * Optional list of accepted image formats
+     * @default ["jpg", "jpeg", "png", "webp"]
+     */
+    acceptedFormats?: string[];
+    /**
+     * @default true
+     */
+    cacheEnabled?: boolean;
+}
+/**
+ * ImageMap
+ * This is the representation of the image map in the virtual module
+ */
+export type ImageMap = Record<string, ImageSpecifications>;
+/**
+ * ImageProcessorPlugin
+ * A Processor for optimizing images.
+ */
+export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
+    private processor;
+    processedImages: Record<string, ImageSpecifications>;
+    constructor(config: Omit<ProcessorConfig<ImageProcessorConfig>, 'name' | 'description'>);
+    get buildPlugins(): EcoBuildPlugin[];
+    get plugins(): EcoBuildPlugin[];
+    /**
+     * Generate dependencies for processor.
+     * It is ossible to define which one should be included in the final bundle based on the environment.
+     * @returns
+     */
+    private generateDependencies;
+    /**
+     * Setup the image processor and create the virtual module.
+     */
+    setup(): Promise<void>;
+    /**
+     * Process images.
+     * @param images
+     */
+    process(images: string[]): Promise<void>;
+    /**
+     * Delete processed images using the original image path.
+     * @param imagePath
+     */
+    deleteProcessedImagesbyPath(imagePath: string): Promise<void>;
+    /**
+     * Generate types for the virtual module.
+     */
+    private generateTypes;
+    /**
+     * Teardown the image processor.
+     */
+    teardown(): Promise<void>;
+    /**
+     * Get the image processor instance.
+     * @returns The image processor instance.
+     */
+    getProcessor(): ImageProcessor | undefined;
+}
+export declare const imageProcessorPlugin: (config: Omit<ProcessorConfig<ImageProcessorConfig>, "name" | "description">) => ImageProcessorPlugin;

package/src/plugin.js

@@ -0,0 +1,223 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { deepMerge } from "@ecopages/core/utils/deep-merge";
+import { GENERATED_BASE_PATHS } from "@ecopages/core/constants";
+import { fileSystem } from "@ecopages/file-system";
+import { Processor } from "@ecopages/core/plugins/processor";
+import { Logger } from "@ecopages/logger";
+import { createImagePlugin, createImagePluginBundler } from "./image-plugins";
+import { ImageProcessor } from "./image-processor";
+import { anyCaseToCamelCase } from "./utils";
+function resolveGeneratedPath(type, options) {
+  const { root, module, subPath } = options;
+  const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
+  return path.join(...parts);
+}
+const logger = new Logger("[@ecopages/image-processor]", {
+  debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
+});
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+class ImageProcessorPlugin extends Processor {
+  processedImages = {};
+  constructor(config) {
+    const acceptedFormats = config.options?.acceptedFormats ?? ["jpg", "jpeg", "png", "webp"];
+    const extensionPatterns = acceptedFormats.map((format) => `*.${format.replace(/^\./, "")}`);
+    const defaultWatchConfig = {
+      paths: [],
+      extensions: acceptedFormats,
+      onCreate: async (ctx) => this.process([ctx.path]),
+      onChange: async (ctx) => this.process([ctx.path]),
+      onDelete: async (ctx) => this.deleteProcessedImagesbyPath(ctx.path),
+      onError: (error) => logger.error("Watcher error", { error })
+    };
+    super({
+      ...config,
+      name: "ecopages-image-processor",
+      description: "A Processor for optimizing images.",
+      capabilities: [
+        {
+          kind: "image",
+          extensions: extensionPatterns
+        }
+      ],
+      watch: config.watch ? deepMerge(defaultWatchConfig, config.watch) : defaultWatchConfig
+    });
+  }
+  get buildPlugins() {
+    return [createImagePluginBundler(this.processedImages)];
+  }
+  get plugins() {
+    return [createImagePlugin(this.processedImages)];
+  }
+  /**
+   * Generate dependencies for processor.
+   * It is ossible to define which one should be included in the final bundle based on the environment.
+   * @returns
+   */
+  generateDependencies() {
+    const deps = [];
+    if (process.env.NODE_ENV === "development") {
+    }
+    return deps;
+  }
+  /**
+   * Setup the image processor and create the virtual module.
+   */
+  async setup() {
+    if (!this.context) {
+      throw new Error("ImageProcessor requires context to be set");
+    }
+    logger.debug("Setting up image processor", {
+      srcDir: this.context.srcDir,
+      distDir: this.context.distDir
+    });
+    const defaultConfig = {
+      sourceDir: `${this.context.srcDir}/public/assets/images`,
+      outputDir: `${this.context.distDir}/assets/optimized`,
+      publicPath: "/assets/optimized",
+      sizes: [],
+      quality: 80,
+      format: "webp"
+    };
+    const config = this.options ? deepMerge(defaultConfig, this.options) : defaultConfig;
+    this.processor = new ImageProcessor(config, {
+      readCache: (key) => this.readCache(key),
+      writeCache: (key, data) => this.writeCache(key, data)
+    });
+    this.processedImages = await this.processor.processDirectory();
+    if (this.watchConfig) {
+      this.watchConfig.paths = [config.sourceDir];
+    }
+    this.dependencies = this.generateDependencies();
+    this.generateTypes();
+  }
+  /**
+   * Process images.
+   * @param images
+   */
+  async process(images) {
+    if (!this.processor) {
+      throw new Error("ImageProcessor not initialized");
+    }
+    logger.debug("Processing images", { count: images.length });
+    for (const image of images) {
+      try {
+        const result = await this.processor.processImage(image);
+        if (result) {
+          this.processedImages[path.basename(image)] = result;
+        }
+      } catch (error) {
+        logger.error("Failed to process image", { image, error });
+      }
+    }
+    this.generateTypes();
+  }
+  /**
+   * Delete processed images using the original image path.
+   * @param imagePath
+   */
+  async deleteProcessedImagesbyPath(imagePath) {
+    if (!this.processor) {
+      throw new Error("ImageProcessor not initialized");
+    }
+    logger.debug("Deleting processed images", { path: imagePath });
+    try {
+      const baseNameWithoutExt = path.basename(imagePath, path.extname(imagePath));
+      if (!this.options) {
+        throw new Error("Options not set");
+      }
+      const outputDir = this.options.outputDir;
+      const files = await fileSystem.glob([`${outputDir}/${baseNameWithoutExt}-*`]);
+      await Promise.all(
+        files.map(async (file) => {
+          try {
+            await fileSystem.removeAsync(file);
+            logger.debug("Deleted processed image", { file });
+          } catch (error) {
+            logger.error("Failed to delete processed image", { file, error });
+          }
+        })
+      );
+      try {
+        const cacheKey = this.processedImages[path.basename(imagePath)].cacheKey;
+        const cachePath = this.getCachePath(cacheKey);
+        await fileSystem.removeAsync(cachePath);
+        logger.debug("Deleted cache file for image", { cachePath });
+      } catch (error) {
+        logger.error("Failed to delete cache file for image", { imagePath, error });
+      }
+      delete this.processedImages[path.basename(imagePath)];
+      this.generateTypes();
+    } catch (error) {
+      logger.error("Failed to delete processed images", { path: imagePath, error });
+    }
+  }
+  /**
+   * Generate types for the virtual module.
+   */
+  generateTypes() {
+    if (!this.options?.outputDir) {
+      throw new Error("Output directory not set");
+    }
+    const requiredTypes = fileSystem.readFileSync(path.join(currentDir, "types.ts")).toString().replaceAll("export ", "");
+    const content = `
+/**
+ * Do not edit manually. This file is auto-generated.
+ * This file contains the type definitions for the virtual module "ecopages:images".
+ */
+
+${requiredTypes}
+
+declare module "ecopages:images" {
+	${Object.keys(this.processedImages).map((key) => `export const ${anyCaseToCamelCase(key)}: ImageSpecifications;`).join("\n    ")}
+}`;
+    if (!this.context) throw new Error("Processor is not configured correctly");
+    const typesDir = resolveGeneratedPath("types", {
+      root: this.context.rootDir,
+      module: this.name,
+      subPath: "virtual-module.d.ts"
+    });
+    fileSystem.ensureDir(path.dirname(typesDir));
+    fileSystem.write(typesDir, content);
+    logger.debug("Generated types for virtual module", { typesDir });
+    const indexTypesDir = resolveGeneratedPath("types", {
+      root: this.context.rootDir,
+      module: this.name,
+      subPath: "index.d.ts"
+    });
+    const indexContent = 'import "./virtual-module.d.js";';
+    fileSystem.write(indexTypesDir, indexContent);
+    logger.debug("Generated index types for virtual module", { indexTypesDir });
+    const runtimeVirtualModulePath = resolveGeneratedPath("cache", {
+      root: this.context.distDir,
+      module: this.name,
+      subPath: "virtual-module.ts"
+    });
+    const runtimeModuleContent = Object.entries(this.processedImages).map(([key, value]) => {
+      return `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value, null, 2)} as const;`;
+    }).join("\n\n");
+    fileSystem.ensureDir(path.dirname(runtimeVirtualModulePath));
+    fileSystem.write(runtimeVirtualModulePath, runtimeModuleContent);
+    logger.debug("Generated runtime virtual module for images", { runtimeVirtualModulePath });
+  }
+  /**
+   * Teardown the image processor.
+   */
+  async teardown() {
+    logger.debug("Tearing down image processor");
+  }
+  /**
+   * Get the image processor instance.
+   * @returns The image processor instance.
+   */
+  getProcessor() {
+    return this.processor;
+  }
+}
+const imageProcessorPlugin = (config) => {
+  return new ImageProcessorPlugin(config);
+};
+export {
+  ImageProcessorPlugin,
+  imageProcessorPlugin
+};