@ecopages/image-processor 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/plugin.js

@@ -1,13 +1,14 @@
 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 {
+  mergeProcessorOptions,
+  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";
+import { createImagePlugin, createImagePluginBundler } from "./image-plugins.js";
+import { ImageProcessor } from "./image-processor.js";
+import { anyCaseToCamelCase } from "./utils.js";
 function resolveGeneratedPath(type, options) {
   const { root, module, subPath } = options;
   const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
@@ -16,8 +17,54 @@ function resolveGeneratedPath(type, options) {
 const logger = new Logger("[@ecopages/image-processor]", {
   debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
 });
-const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const IMAGE_VIRTUAL_MODULE_TYPES = `/**
+ * ImageAttributes
+ * These are the core attributes for the image element generated by the image processor
+ */
+interface ImageAttributes {
+	src: string;
+	width: number;
+	height: number;
+	sizes: string;
+	srcset?: string;
+}
+
+/**
+ * This represents a single image variant created using the size configuration
+ */
+interface ImageVariant {
+	width: number;
+	height: number;
+	src: string;
+	label: string;
+}
+
+/**
+ * These are the core attributes for the image element and the image variants
+ * This is the representation of the image element in the virtual module
+ */
+interface ImageSpecifications {
+	attributes: ImageAttributes;
+	variants: ImageVariant[];
+	/**
+	 * A unique key used to cache the image specifications.
+	 * This key should uniquely identify the combination of attributes and variants
+	 * to ensure proper caching behavior.
+	 */
+	cacheKey: string;
+}
+
+/**
+ * This is the representation of an image breakpoint
+ * This is used to generate the srcset attribute
+ */
+type ImageSize = {
+	width: number;
+	label: string;
+};`;
 class ImageProcessorPlugin extends Processor {
+  buildContributionsPrepared = false;
+  resolvedConfig;
   processedImages = {};
   constructor(config) {
     const acceptedFormats = config.options?.acceptedFormats ?? ["jpg", "jpeg", "png", "webp"];
@@ -40,7 +87,7 @@ class ImageProcessorPlugin extends Processor {
           extensions: extensionPatterns
         }
       ],
-      watch: config.watch ? deepMerge(defaultWatchConfig, config.watch) : defaultWatchConfig
+      watch: config.watch ? mergeProcessorOptions(defaultWatchConfig, config.watch) : defaultWatchConfig
     });
   }
   get buildPlugins() {
@@ -50,20 +97,26 @@ class ImageProcessorPlugin extends Processor {
     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
+   * Replaces image-map contents without swapping the backing object.
+   *
+   * @remarks
+   * The build/runtime virtual-module plugins close over `processedImages`, so
+   * mutating the existing object keeps those plugins live after preparation.
    */
-  generateDependencies() {
-    const deps = [];
-    if (process.env.NODE_ENV === "development") {
+  replaceProcessedImages(images) {
+    for (const key of Object.keys(this.processedImages)) {
+      delete this.processedImages[key];
     }
-    return deps;
+    Object.assign(this.processedImages, images);
   }
   /**
-   * Setup the image processor and create the virtual module.
+   * Prepares the image virtual-module state before config build seals the app
+   * manifest.
    */
-  async setup() {
+  async prepareBuildContributions() {
+    if (this.buildContributionsPrepared) {
+      return;
+    }
     if (!this.context) {
       throw new Error("ImageProcessor requires context to be set");
     }
@@ -79,17 +132,76 @@ class ImageProcessorPlugin extends Processor {
       quality: 80,
       format: "webp"
     };
-    const config = this.options ? deepMerge(defaultConfig, this.options) : defaultConfig;
+    const config = this.options ? mergeProcessorOptions(defaultConfig, this.options) : defaultConfig;
+    this.resolvedConfig = config;
     this.processor = new ImageProcessor(config, {
       readCache: (key) => this.readCache(key),
       writeCache: (key, data) => this.writeCache(key, data)
     });
-    this.processedImages = await this.processor.processDirectory();
+    this.replaceProcessedImages(await this.processor.processDirectory());
     if (this.watchConfig) {
       this.watchConfig.paths = [config.sourceDir];
     }
     this.dependencies = this.generateDependencies();
     this.generateTypes();
+    this.buildContributionsPrepared = true;
+  }
+  getRuntimeVirtualModulePath() {
+    if (!this.context) {
+      throw new Error("ImageProcessor requires context to be set");
+    }
+    return resolveGeneratedPath("cache", {
+      root: this.context.distDir,
+      module: this.name,
+      subPath: "virtual-module.ts"
+    });
+  }
+  getGeneratedOutputPath(src) {
+    if (!this.resolvedConfig) {
+      throw new Error("ImageProcessor not initialized");
+    }
+    return path.join(this.resolvedConfig.outputDir, path.basename(src));
+  }
+  hasGeneratedOutputs() {
+    if (!this.resolvedConfig) {
+      return false;
+    }
+    if (!fileSystem.exists(this.resolvedConfig.outputDir) || !fileSystem.exists(this.getRuntimeVirtualModulePath())) {
+      return false;
+    }
+    return Object.values(this.processedImages).every((image) => {
+      const outputPaths = [image.attributes.src, ...image.variants.map((variant) => variant.src)];
+      return outputPaths.every((src) => fileSystem.exists(this.getGeneratedOutputPath(src)));
+    });
+  }
+  async rehydrateGeneratedOutputs() {
+    if (!this.processor) {
+      throw new Error("ImageProcessor not initialized");
+    }
+    if (this.hasGeneratedOutputs()) {
+      return;
+    }
+    this.replaceProcessedImages(await this.processor.processDirectory());
+    this.dependencies = this.generateDependencies();
+    this.generateTypes();
+  }
+  /**
+   * 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;
+  }
+  /**
+   * Prepares build contributions if not already done and rehydrates previously generated image outputs.
+   */
+  async setup() {
+    await this.prepareBuildContributions();
+    await this.rehydrateGeneratedOutputs();
   }
   /**
    * Process images.
@@ -159,14 +271,13 @@ class ImageProcessorPlugin extends Processor {
     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}
+${IMAGE_VIRTUAL_MODULE_TYPES}
 
 declare module "ecopages:images" {
 	${Object.keys(this.processedImages).map((key) => `export const ${anyCaseToCamelCase(key)}: ImageSpecifications;`).join("\n    ")}

package/CHANGELOG.md

@@ -1,23 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/image-processor` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-- **`image-plugins.ts`** — New file extracting image processing plugin logic for reuse across build adapters (`image-plugins.ts`).
-- Bun-specific plugin helpers moved to `bun-plugins.ts`, separating runtime concerns from the image processing core.
-
-### Refactoring
-
-- `plugin.ts` updated to use the new `image-plugins.ts` abstraction.
-- `image-processor.ts` minor updates.
-- README updated with usage clarification.
-
-### Tests
-
-- `image-renderer.test.ts` expanded (68 lines added).
-- `image-processor.test.ts` and `image-utils.test.ts` updated.

package/src/bun-plugins.ts

@@ -1,59 +0,0 @@
-/**
- * This file contains the plugins for bundling the image specifications.
- * @module @ecopages/image-processor/bun-plugins
- */
-
-import type { EcoBuildOnLoadResult, EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { ImageMap } from './plugin';
-import { anyCaseToCamelCase } from './utils';
-
-/**
- * This function creates the plugin result for the image specifications.
- */
-function createPluginResult(exports: ImageMap): EcoBuildOnLoadResult {
-	return {
-		contents: `${Object.entries(exports)
-			.map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`)
-			.join('\n')}`,
-		loader: 'ts',
-	};
-}
-
-/**
- * This function creates a plugin for bundling the image specifications.
- * https://bun.sh/docs/runtime/plugins#virtual-modules
- * @param exports
- * @returns
- */
-export function createImagePlugin(exports: ImageMap): EcoBuildPlugin {
-	return {
-		name: 'ecopages:images',
-		setup(build) {
-			build.module('ecopages:images', () => createPluginResult(exports));
-		},
-	};
-}
-
-/**
- * This function creates a plugin for bundling the image specifications.
- * Due to some limitations in the bundler, we need to use a different approach.
- * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
- * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
- * @param exports
- * @returns
- */
-export function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin {
-	return {
-		name: 'ecopages:images',
-		setup(build) {
-			build.onResolve({ filter: /^ecopages:images$/ }, () => {
-				return {
-					namespace: 'ecopages-images',
-					path: 'ecopages:images',
-				};
-			});
-
-			build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
-		},
-	};
-}

package/src/component/html.ts

@@ -1,15 +0,0 @@
-/**
- * Image component that renders the image as a string.
- * @module @ecopages/image-processor/component/html
- */
-
-import { type EcoImageProps, renderer } from '../image-renderer';
-
-/**
- * EcoImage
- * This component generates the image element based on the provided props as a string
- * @param props {@link EcoImageProps}
- */
-export const EcoImage = (props: EcoImageProps): string => {
-	return renderer.renderToString(props);
-};

package/src/component/react.ts

@@ -1,20 +0,0 @@
-/**
- * Image component that renders the image as a string.
- * @module @ecopages/image-processor/component/react
- */
-
-import { createElement, type JSX } from 'react';
-import { type EcoImageProps, renderer } from '../image-renderer';
-
-/**
- * EcoImage
- * This component generates the image element based on the provided props as JSX
- * @param props {@link EcoImageProps}
- * @returns
- */
-export const EcoImage = (props: EcoImageProps): JSX.Element => {
-	return createElement('img', {
-		...renderer.generateAttributesJsx(props),
-		suppressHydrationWarning: true,
-	});
-};

package/src/constants.ts

@@ -1,7 +0,0 @@
-import type { ImageLayout } from './image-renderer';
-
-/**
- * Default image layout
- * @constant "constrained"
- */
-export const DEFAULT_LAYOUT: ImageLayout = 'constrained';

package/src/image-plugins.ts

@@ -1,59 +0,0 @@
-/**
- * This file contains the plugins for bundling the image specifications.
- * @module @ecopages/image-processor/image-plugins
- */
-
-import type { EcoBuildOnLoadResult, EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { ImageMap } from './plugin';
-import { anyCaseToCamelCase } from './utils';
-
-/**
- * This function creates the plugin result for the image specifications.
- */
-function createPluginResult(exports: ImageMap): EcoBuildOnLoadResult {
-	return {
-		contents: `${Object.entries(exports)
-			.map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`)
-			.join('\n')}`,
-		loader: 'ts',
-	};
-}
-
-/**
- * This function creates a plugin for bundling the image specifications.
- * https://bun.sh/docs/runtime/plugins#virtual-modules
- * @param exports
- * @returns
- */
-export function createImagePlugin(exports: ImageMap): EcoBuildPlugin {
-	return {
-		name: 'ecopages:images',
-		setup(build) {
-			build.module('ecopages:images', () => createPluginResult(exports));
-		},
-	};
-}
-
-/**
- * This function creates a plugin for bundling the image specifications.
- * Due to some limitations in the bundler, we need to use a different approach.
- * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
- * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
- * @param exports
- * @returns
- */
-export function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin {
-	return {
-		name: 'ecopages:images',
-		setup(build) {
-			build.onResolve({ filter: /^ecopages:images$/ }, () => {
-				return {
-					namespace: 'ecopages-images',
-					path: 'ecopages:images',
-				};
-			});
-
-			build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
-		},
-	};
-}

package/src/image-processor.ts

@@ -1,201 +0,0 @@
-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);
-	}
-}