@ecopages/image-processor 0.2.0-beta.9 → 0.2.0-rc.1

package/src/plugin.js

@@ -1,21 +1,18 @@
-import path from "node:path";
-import { GENERATED_BASE_PATHS } from "@ecopages/core/constants";
-import { fileSystem } from "@ecopages/file-system";
-import {
-  mergeProcessorOptions,
-  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/plugins/processor';
+import { isLitStaticRenderWorkerThread } from '@ecopages/core/build/lit-static-render-worker-context';
+import { Logger } from '@ecopages/logger';
+import { createImagePlugin, createImagePluginBundler } from './image-plugins.js';
+import { ImageProcessor } from './image-processor.js';
+import { getSourceImagePaths, loadProcessedImagesFromDisk } from './image-runtime-state.js';
+import { anyCaseToCamelCase } from './utils.js';
+const logger = new Logger('[@ecopages/image-processor]', {
+    debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true',
 });
 const IMAGE_VIRTUAL_MODULE_TYPES = `/**
  * ImageAttributes
@@ -62,230 +59,284 @@ 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
-        }
-      ],
-      watch: config.watch ? mergeProcessorOptions(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;
-    }
-    if (process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === "true") {
-      this.buildContributionsPrepared = true;
-      return;
+/**
+ * ImageProcessorPlugin
+ * A Processor for optimizing images.
+ */
+export 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,
+                },
+            ],
+            watch: config.watch ? mergeProcessorOptions(defaultWatchConfig, config.watch) : defaultWatchConfig,
+        });
     }
-    if (!this.context) {
-      throw new Error("ImageProcessor requires context to be set");
+    get buildPlugins() {
+        return [createImagePluginBundler(this.processedImages)];
     }
-    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)
-    });
-    this.replaceProcessedImages(await this.processor.processDirectory());
-    if (this.watchConfig) {
-      this.watchConfig.paths = [config.sourceDir];
+    get plugins() {
+        return [createImagePlugin(this.processedImages)];
     }
-    this.dependencies = this.generateDependencies();
-    this.generateTypes();
-    this.buildContributionsPrepared = true;
-  }
-  getRuntimeVirtualModulePath() {
-    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);
     }
-    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");
+    /**
+     * 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];
+        }
     }
-    return path.join(this.resolvedConfig.outputDir, path.basename(src));
-  }
-  hasGeneratedOutputs() {
-    if (!this.resolvedConfig) {
-      return false;
+    /**
+     * Prepares build-facing processor state before config build seals the app manifest.
+     *
+     * @remarks
+     * Image processing stays in {@link setup}; this hook only initializes config and
+     * restores any previously generated virtual-module state from disk.
+     */
+    async prepareBuildContributions() {
+        if (this.buildContributionsPrepared) {
+            return;
+        }
+        // Lit SSR workers import eco.config in an isolated thread; image outputs are
+        // already prepared on the main dev server thread.
+        if (isLitStaticRenderWorkerThread()) {
+            this.buildContributionsPrepared = true;
+            return;
+        }
+        this.initializeProcessor();
+        await this.generateSourceTypes();
+        await this.syncProcessedImagesFromDisk();
+        this.buildContributionsPrepared = true;
     }
-    if (!fileSystem.exists(this.resolvedConfig.outputDir) || !fileSystem.exists(this.getRuntimeVirtualModulePath())) {
-      return false;
+    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 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)));
-    });
-  }
-  writeGeneratedFile(filePath, content) {
-    fileSystem.ensureDir(path.dirname(filePath));
-    if (fileSystem.exists(filePath) && fileSystem.readFileSync(filePath) === content) {
-      return;
+    getGeneratedOutputPath(src) {
+        if (!this.resolvedConfig) {
+            throw new Error('ImageProcessor not initialized');
+        }
+        return path.join(this.resolvedConfig.outputDir, path.basename(src));
     }
-    fileSystem.write(filePath, content);
-  }
-  async rehydrateGeneratedOutputs() {
-    if (!this.processor) {
-      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;
     }
-    if (this.hasGeneratedOutputs()) {
-      return;
+    async ensureGeneratedOutputs() {
+        if (!this.processor) {
+            throw new Error('ImageProcessor not initialized');
+        }
+        if (await this.syncProcessedImagesFromDisk()) {
+            return;
+        }
+        this.replaceProcessedImages(await this.processor.processDirectory());
+        this.generateTypes();
     }
-    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") {
+    writeGeneratedFile(filePath, content) {
+        fileSystem.ensureDir(path.dirname(filePath));
+        if (fileSystem.exists(filePath) && fileSystem.readFileSync(filePath) === content) {
+            return;
+        }
+        fileSystem.write(filePath, content);
     }
-    return deps;
-  }
-  /**
-   * Prepares build contributions if not already done and rehydrates previously generated image outputs.
-   */
-  async setup() {
-    if (process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === "true") {
-      return;
+    /**
+     * Generates virtual-module declarations from source filenames before image
+     * processing runs.
+     *
+     * @remarks
+     * Editors need the ambient `ecopages:images` module during config build, but
+     * actual image optimization is deferred until {@link setup}. Declaring exports
+     * from the source directory preserves typed named imports on a clean checkout.
+     */
+    async generateSourceTypes() {
+        if (!this.resolvedConfig) {
+            return;
+        }
+        const sourceImages = await getSourceImagePaths(this.resolvedConfig);
+        this.writeVirtualModuleTypes(sourceImages.map((imagePath) => path.basename(imagePath)));
     }
-    await this.prepareBuildContributions();
-    await this.rehydrateGeneratedOutputs();
-  }
-  /**
-   * Process images.
-   * @param images
-   */
-  async process(images) {
-    if (!this.processor) {
-      throw new Error("ImageProcessor not initialized");
+    /**
+     * Ensures optimized image outputs and virtual-module state exist on disk.
+     */
+    async setup() {
+        if (isLitStaticRenderWorkerThread()) {
+            return;
+        }
+        this.initializeProcessor();
+        await this.ensureGeneratedOutputs();
     }
-    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;
+    /**
+     * 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 });
+            }
         }
-      } catch (error) {
-        logger.error("Failed to process image", { image, error });
-      }
+        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");
+    /**
+     * 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 });
+        }
     }
-    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 });
-    }
-  }
-  /**
-   * Generate types for the virtual module.
-   */
-  generateTypes() {
-    if (!this.options?.outputDir) {
-      throw new Error("Output directory not set");
+            .join('\n\n');
+        this.writeGeneratedFile(runtimeVirtualModulePath, runtimeModuleContent);
+        logger.debug('Generated runtime virtual module for images', { runtimeVirtualModulePath });
     }
-    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".
@@ -294,53 +345,46 @@ 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"
-    });
-    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";';
-    this.writeGeneratedFile(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");
-    this.writeGeneratedFile(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),
+        });
+    }
+    /**
+     * 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
+export const imageProcessorPlugin = (config) => {
+    return new ImageProcessorPlugin(config);
 };

package/src/types.js

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