@ecopages/image-processor 0.2.1 → 0.3.1

package/src/plugin.js

@@ -1,19 +1,18 @@
-import path from "node:path";
-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.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);
-  return path.join(...parts);
-}
-const logger = new Logger("[@ecopages/image-processor]", {
-  debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
+/**
+ * ImageProcessorPlugin
+ * @module @ecopages/image-processor
+ */
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { mergeProcessorOptions, Processor, resolveGeneratedPath, writeGeneratedTypesPackage, } from '@ecopages/core/processor';
+import { Logger } from '@ecopages/logger';
+import { isEcopagesEnvEnabled } from '@ecopages/core/processor';
+import { createImagePlugin, createImagePluginBundler } from './image-plugins.js';
+import { ImageProcessor } from './image-processor.js';
+import { getOutputSources, getSourceImagePaths, loadProcessedImagesFromDisk, } from './image-runtime-state.js';
+import { anyCaseToCamelCase } from './utils.js';
+const logger = new Logger('[@ecopages/image-processor]', {
+    debug: isEcopagesEnvEnabled('ECOPAGES_LOGGER_DEBUG'),
 });
 const IMAGE_VIRTUAL_MODULE_TYPES = `/**
  * ImageAttributes
@@ -60,216 +59,287 @@ 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"];
-    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
+/**
+ * ImageProcessorPlugin
+ * A Processor for optimizing images.
+ */
+export class ImageProcessorPlugin extends Processor {
+    resolvedConfig;
+    processedImages = {};
+    preparation;
+    constructor(config) {
+        const acceptedFormats = config.options?.acceptedFormats ?? ['jpg', 'jpeg', 'png', 'webp'];
+        const extensionPatterns = acceptedFormats.map((format) => `*.${format.replace(/^\./, '')}`);
+        const defaultWatchConfig = {
+            paths: [],
+            extensions: acceptedFormats,
+            onChanges: async (changes) => this.handleImageChanges(changes),
+            onError: (error) => logger.error('Watcher error', { error }),
+        };
+        super({
+            ...config,
+            name: 'ecopages-image-processor',
+            capabilities: [
+                {
+                    kind: 'image',
+                    extensions: extensionPatterns,
+                },
+            ],
+            watch: config.watch ? mergeProcessorOptions(defaultWatchConfig, config.watch) : defaultWatchConfig,
+        });
+    }
+    async handleImageChanges({ created, changed, deleted }) {
+        const changedImages = [...created, ...changed];
+        if (changedImages.length > 0) {
+            await this.process(changedImages);
+        }
+        for (const imagePath of deleted) {
+            await this.deleteProcessedImagesbyPath(imagePath);
         }
-      ],
-      watch: config.watch ? deepMerge(defaultWatchConfig, config.watch) : defaultWatchConfig
-    });
-  }
-  get buildPlugins() {
-    return [createImagePluginBundler(this.processedImages)];
-  }
-  get plugins() {
-    return [createImagePlugin(this.processedImages)];
-  }
-  /**
-   * 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.
-   */
-  replaceProcessedImages(images) {
-    for (const key of Object.keys(this.processedImages)) {
-      delete this.processedImages[key];
     }
-    Object.assign(this.processedImages, images);
-  }
-  /**
-   * Prepares the image virtual-module state before config build seals the app
-   * manifest.
-   */
-  async prepareBuildContributions() {
-    if (this.buildContributionsPrepared) {
-      return;
+    plugins() {
+        return [
+            { ...createImagePlugin(this.processedImages, () => this.ensurePrepared()), environments: ['server'] },
+            {
+                ...createImagePluginBundler(this.processedImages, () => this.ensurePrepared()),
+                environments: ['browser'],
+            },
+        ];
     }
-    if (!this.context) {
-      throw new Error("ImageProcessor requires context to be set");
+    /**
+     * 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.
+     */
+    replaceProcessedImages(images) {
+        for (const key of Object.keys(this.processedImages)) {
+            delete this.processedImages[key];
+        }
+        Object.assign(this.processedImages, images);
     }
-    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.resolvedConfig = config;
-    this.processor = new ImageProcessor(config, {
-      readCache: (key) => this.readCache(key),
-      writeCache: (key, data) => this.writeCache(key, data)
-    });
-    this.replaceProcessedImages(await this.processor.processDirectory());
-    if (this.watchConfig) {
-      this.watchConfig.paths = [config.sourceDir];
+    /**
+     * Resolves processor config and creates the sharp-backed worker instance.
+     */
+    initializeProcessor() {
+        if (this.processor && this.resolvedConfig) {
+            return;
+        }
+        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 ? 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),
+        });
+        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");
+    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',
+        });
     }
-    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");
+    /**
+     * Restores in-memory image state from previously generated dist artifacts.
+     *
+     * @returns `true` when state was restored without invoking sharp.
+     */
+    async syncProcessedImagesFromDisk() {
+        if (!this.resolvedConfig) {
+            return false;
+        }
+        const sourceImages = await getSourceImagePaths(this.resolvedConfig);
+        const imageMap = await loadProcessedImagesFromDisk({
+            resolvedConfig: this.resolvedConfig,
+            runtimeVirtualModulePath: this.getRuntimeVirtualModulePath(),
+        });
+        if (imageMap === null) {
+            return false;
+        }
+        if (sourceImages.length > 0 && Object.keys(imageMap).length !== sourceImages.length) {
+            return false;
+        }
+        this.replaceProcessedImages(imageMap);
+        if (Object.keys(imageMap).length > 0) {
+            this.generateTypes();
+        }
+        return true;
     }
-    return path.join(this.resolvedConfig.outputDir, path.basename(src));
-  }
-  hasGeneratedOutputs() {
-    if (!this.resolvedConfig) {
-      return false;
+    async ensureGeneratedOutputs() {
+        if (!this.processor) {
+            throw new Error('ImageProcessor not initialized');
+        }
+        if (await this.syncProcessedImagesFromDisk()) {
+            return;
+        }
+        this.replaceProcessedImages(await this.processor.processDirectory());
+        this.generateTypes();
     }
-    if (!fileSystem.exists(this.resolvedConfig.outputDir) || !fileSystem.exists(this.getRuntimeVirtualModulePath())) {
-      return false;
+    writeGeneratedFile(filePath, content) {
+        fileSystem.ensureDir(path.dirname(filePath));
+        if (fileSystem.exists(filePath) && fileSystem.readFileSync(filePath) === content) {
+            return;
+        }
+        fileSystem.write(filePath, content);
     }
-    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");
+    /**
+     * Ensures optimized image outputs and virtual-module state exist on disk.
+     */
+    async setup() {
+        this.preparation = this.prepare();
+        await this.preparation;
     }
-    if (this.hasGeneratedOutputs()) {
-      return;
+    async prepare() {
+        this.initializeProcessor();
+        await this.ensureGeneratedOutputs();
     }
-    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") {
+    /**
+     * Prepares the image map on first load of `ecopages:images` when `setup()` has not run in this process.
+     *
+     * @remarks
+     * The Lit static render worker skips Processor setup because the main thread already wrote the outputs, so
+     * the worker's map starts empty and is restored from those outputs here.
+     */
+    ensurePrepared() {
+        this.preparation ??= this.prepare();
+        return this.preparation;
     }
-    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.
-   * @param images
-   */
-  async process(images) {
-    if (!this.processor) {
-      throw new Error("ImageProcessor not initialized");
+    /**
+     * 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) {
+                    const key = path.basename(image);
+                    const previous = this.processedImages[key];
+                    this.processedImages[key] = result;
+                    if (previous) {
+                        await this.removeSupersededOutputs(previous, result);
+                    }
+                }
+            }
+            catch (error) {
+                logger.error('Failed to process image', { image, error });
+            }
+        }
+        this.generateTypes();
     }
-    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;
+    /**
+     * Deletes the optimized files and cache entry recorded for a removed source image.
+     *
+     * @remarks
+     * Variant files are named after a hash of their bytes, so the files to delete are
+     * the ones the recorded specification points at, not a pattern on the source name.
+     */
+    async deleteProcessedImagesbyPath(imagePath) {
+        if (!this.processor) {
+            throw new Error('ImageProcessor not initialized');
+        }
+        logger.debug('Deleting processed images', { path: imagePath });
+        const key = path.basename(imagePath);
+        const previous = this.processedImages[key];
+        if (!previous) {
+            return;
         }
-      } catch (error) {
-        logger.error("Failed to process image", { image, error });
-      }
+        delete this.processedImages[key];
+        await this.removeSupersededOutputs(previous);
+        this.generateTypes();
     }
-    this.generateTypes();
-  }
-  /**
-   * Delete processed images using the original image path.
-   * @param imagePath
-   */
-  async deleteProcessedImagesbyPath(imagePath) {
-    if (!this.processor) {
-      throw new Error("ImageProcessor not initialized");
+    /**
+     * Removes the cache entry and the output files of `previous` that `next` no longer uses.
+     *
+     * @remarks
+     * Identical encoded bytes share one hashed file across source images, so a file
+     * is only removed once no remaining specification references it.
+     */
+    async removeSupersededOutputs(previous, next) {
+        if (!this.resolvedConfig) {
+            throw new Error('ImageProcessor not initialized');
+        }
+        const referenced = new Set();
+        for (const spec of [...Object.values(this.processedImages), ...(next ? [next] : [])]) {
+            for (const src of getOutputSources(spec)) {
+                referenced.add(path.basename(src));
+            }
+        }
+        const files = getOutputSources(previous)
+            .map((src) => path.basename(src))
+            .filter((name) => !referenced.has(name));
+        for (const file of new Set(files)) {
+            const filePath = path.join(this.resolvedConfig.outputDir, file);
+            try {
+                await fileSystem.removeAsync(filePath);
+                logger.debug('Deleted processed image', { file: filePath });
+            }
+            catch (error) {
+                logger.error('Failed to delete processed image', { file: filePath, error });
+            }
+        }
+        if (previous.cacheKey !== next?.cacheKey) {
+            const cachePath = this.getCachePath(previous.cacheKey);
+            try {
+                await fileSystem.removeAsync(cachePath);
+                logger.debug('Deleted cache file for image', { cachePath });
+            }
+            catch (error) {
+                logger.error('Failed to delete cache file for image', { cachePath, error });
+            }
+        }
     }
-    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 });
-          }
+    /**
+     * Generate types for the virtual module.
+     */
+    generateTypes() {
+        this.writeVirtualModuleTypes(Object.keys(this.processedImages));
+        if (!this.context)
+            throw new Error('Processor is not configured correctly');
+        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;`;
         })
-      );
-      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 });
+            .join('\n\n');
+        this.writeGeneratedFile(runtimeVirtualModulePath, runtimeModuleContent);
+        logger.debug('Generated runtime virtual module for images', { runtimeVirtualModulePath });
     }
-  }
-  /**
-   * Generate types for the virtual module.
-   */
-  generateTypes() {
-    if (!this.options?.outputDir) {
-      throw new Error("Output directory not set");
-    }
-    const content = `
+    /**
+     * Writes the ambient declaration package for `ecopages:images`.
+     */
+    writeVirtualModuleTypes(imageKeys) {
+        const content = `
 /**
  * Do not edit manually. This file is auto-generated.
  * This file contains the type definitions for the virtual module "ecopages:images".
@@ -278,55 +348,33 @@ class ImageProcessorPlugin extends Processor {
 ${IMAGE_VIRTUAL_MODULE_TYPES}
 
 declare module "ecopages:images" {
-	${Object.keys(this.processedImages).map((key) => `export const ${anyCaseToCamelCase(key)}: ImageSpecifications;`).join("\n    ")}
+	${imageKeys.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;
-  }
+        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',
+        });
+        this.writeGeneratedFile(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";\n';
+        this.writeGeneratedFile(indexTypesDir, indexContent);
+        logger.debug('Generated index types for virtual module', { indexTypesDir });
+        writeGeneratedTypesPackage({
+            root: this.context.rootDir,
+            module: this.name,
+            packageName: '@types/ecopages-image-processor',
+            writeFile: (filePath, content) => this.writeGeneratedFile(filePath, content),
+        });
+    }
 }
-const imageProcessorPlugin = (config) => {
-  return new ImageProcessorPlugin(config);
-};
-export {
-  ImageProcessorPlugin,
-  imageProcessorPlugin
+export const imageProcessorPlugin = (config) => {
+    return new ImageProcessorPlugin(config);
 };

package/src/types.js

@@ -0,0 +1 @@
+export {};

package/src/utils.js

@@ -1,27 +1,26 @@
-function anyCaseToCamelCase(str) {
-  if (!str) return "";
-  let result = "";
-  let capitalize = false;
-  for (let i = 0; i < str.length; i++) {
-    const char = str[i];
-    if (/[0-9]/.test(char)) {
-      result += char;
-      capitalize = true;
-      continue;
+export function anyCaseToCamelCase(str) {
+    if (!str)
+        return '';
+    let result = '';
+    let capitalize = false;
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        if (/[0-9]/.test(char)) {
+            result += char;
+            capitalize = true;
+            continue;
+        }
+        if (/[a-zA-Z]/.test(char)) {
+            if (capitalize) {
+                result += char.toUpperCase();
+                capitalize = false;
+            }
+            else {
+                result += char.toLowerCase();
+            }
+            continue;
+        }
+        capitalize = true;
     }
-    if (/[a-zA-Z]/.test(char)) {
-      if (capitalize) {
-        result += char.toUpperCase();
-        capitalize = false;
-      } else {
-        result += char.toLowerCase();
-      }
-      continue;
-    }
-    capitalize = true;
-  }
-  return result;
+    return result;
 }
-export {
-  anyCaseToCamelCase
-};