@ecopages/image-processor 0.3.0 → 0.3.2

package/README.md

@@ -6,7 +6,7 @@ It provides automatic image processing (e.g. converting and compressing to WebP)
 
 ## Features
 
-Build contributions use one `plugins(app)` method with server and browser environment declarations. Image processing, type generation and the cache restore run in `setup()`; `ecopages types` runs it. The virtual image module resolves through the implementation for the requested environment.
+Build contributions use one `plugins(app)` method with server and browser environment declarations. Image processing, type generation and the cache restore run in `setup()`; `ecopages types` runs it. The virtual image module resolves through the implementation for the requested environment. In a process where `setup()` has not run, such as the Lit static render worker, the first load of `ecopages:images` restores the image map from the outputs already on disk.
 
 - **Automatic Image Optimization**: Converts and compresses images to modern formats at build time. Each variant is named from a hash of its encoded bytes, so a quality or format change gets a new URL.
 - **Responsive Image Generation**: Creates multiple variants for different screen sizes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/image-processor",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Image processor, transform and optimize images for web",
   "keywords": [
     "image",
@@ -18,7 +18,7 @@
     "directory": "packages/processors/image-processor"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.3.0",
+    "@ecopages/core": "0.3.2",
     "@ecopages/jsx": "^0.4.0"
   },
   "peerDependenciesMeta": {
@@ -27,10 +27,9 @@
     }
   },
   "dependencies": {
-    "@ecopages/file-system": "0.3.0",
+    "@ecopages/file-system": "0.3.2",
     "@ecopages/logger": "^0.2.3",
     "react": "^19.2.6",
-    "react-dom": "^19.2.6",
     "sharp": "^0.35.3"
   },
   "exports": {

package/src/image-plugins.d.ts

@@ -4,11 +4,14 @@
  */
 import type { EcoBuildPlugin } from '@ecopages/core/processor';
 import type { ImageMap } from './plugin.js';
+/** Fills the image map before the module is loaded. */
+type EnsureImagesReady = () => Promise<void>;
 /**
  * Declares `ecopages:images` as a virtual module for server builds.
  */
-export declare function createImagePlugin(exports: ImageMap): EcoBuildPlugin;
+export declare function createImagePlugin(exports: ImageMap, ensureReady: EnsureImagesReady): EcoBuildPlugin;
 /**
  * Resolves `ecopages:images` with `onResolve` and `onLoad` for browser builds.
  */
-export declare function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin;
+export declare function createImagePluginBundler(exports: ImageMap, ensureReady: EnsureImagesReady): EcoBuildPlugin;
+export {};

package/src/image-plugins.js

@@ -17,18 +17,21 @@ function createPluginResult(exports) {
 /**
  * Declares `ecopages:images` as a virtual module for server builds.
  */
-export function createImagePlugin(exports) {
+export function createImagePlugin(exports, ensureReady) {
     return {
         name: 'ecopages:images',
         setup(build) {
-            build.module('ecopages:images', () => createPluginResult(exports));
+            build.module('ecopages:images', async () => {
+                await ensureReady();
+                return createPluginResult(exports);
+            });
         },
     };
 }
 /**
  * Resolves `ecopages:images` with `onResolve` and `onLoad` for browser builds.
  */
-export function createImagePluginBundler(exports) {
+export function createImagePluginBundler(exports, ensureReady) {
     return {
         name: 'ecopages:images',
         setup(build) {
@@ -38,7 +41,10 @@ export function createImagePluginBundler(exports) {
                     path: 'ecopages:images',
                 };
             });
-            build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
+            build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, async () => {
+                await ensureReady();
+                return createPluginResult(exports);
+            });
         },
     };
 }

package/src/image-runtime-state.d.ts

@@ -10,6 +10,10 @@ export type ImageProcessorDiskConfig = {
  */
 export declare function parseVirtualModuleExports(content: string): Record<string, ImageSpecifications> | null;
 export declare function getSourceImagePaths(resolvedConfig: ImageProcessorDiskConfig): Promise<string[]>;
+/**
+ * Lists the public paths of every file a specification points at.
+ */
+export declare function getOutputSources(spec: ImageSpecifications): string[];
 /**
  * Restores processed image state from generated dist artifacts when every source
  * image has a matching virtual-module export and output files on disk.

package/src/image-runtime-state.js

@@ -22,6 +22,12 @@ export async function getSourceImagePaths(resolvedConfig) {
     const acceptedFormats = resolvedConfig.acceptedFormats ?? ['jpg', 'jpeg', 'png', 'webp'];
     return fileSystem.glob([`${resolvedConfig.sourceDir}/**/*.{${acceptedFormats.join(',')}}`]);
 }
+/**
+ * Lists the public paths of every file a specification points at.
+ */
+export function getOutputSources(spec) {
+    return [spec.attributes.src, ...spec.variants.map((variant) => variant.src)];
+}
 function getGeneratedOutputPath(outputDir, src) {
     return path.join(outputDir, path.basename(src));
 }
@@ -49,7 +55,7 @@ export async function loadProcessedImagesFromDisk(options) {
         if (!spec) {
             return null;
         }
-        const outputPaths = [spec.attributes.src, ...spec.variants.map((variant) => variant.src)];
+        const outputPaths = getOutputSources(spec);
         if (!outputPaths.every((src) => fileSystem.exists(getGeneratedOutputPath(options.resolvedConfig.outputDir, src)))) {
             return null;
         }

package/src/plugin.d.ts

@@ -3,7 +3,6 @@
  * @module @ecopages/image-processor
  */
 import { Processor, type EcoBuildPlugin, type ProcessorConfig } from '@ecopages/core/processor';
-import { ImageProcessor } from './image-processor.js';
 import type { ImageSize, ImageSpecifications } from './types.js';
 /**
  * Configuration for the image processor
@@ -41,6 +40,7 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
     private processor;
     private resolvedConfig?;
     processedImages: Record<string, ImageSpecifications>;
+    private preparation?;
     constructor(config: Omit<ProcessorConfig<ImageProcessorConfig>, 'name'>);
     private handleImageChanges;
     plugins(): EcoBuildPlugin[];
@@ -57,7 +57,6 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
      */
     private initializeProcessor;
     private getRuntimeVirtualModulePath;
-    private getGeneratedOutputPath;
     /**
      * Restores in-memory image state from previously generated dist artifacts.
      *
@@ -70,16 +69,36 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
      * Ensures optimized image outputs and virtual-module state exist on disk.
      */
     setup(): Promise<void>;
+    private prepare;
+    /**
+     * 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.
+     */
+    private ensurePrepared;
     /**
      * Process images.
      * @param images
      */
     process(images: string[]): Promise<void>;
     /**
-     * Delete processed images using the original image path.
-     * @param imagePath
+     * 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.
      */
     deleteProcessedImagesbyPath(imagePath: string): Promise<void>;
+    /**
+     * 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.
+     */
+    private removeSupersededOutputs;
     /**
      * Generate types for the virtual module.
      */
@@ -88,10 +107,5 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
      * Writes the ambient declaration package for `ecopages:images`.
      */
     private writeVirtualModuleTypes;
-    /**
-     * Get the image processor instance.
-     * @returns The image processor instance.
-     */
-    getProcessor(): ImageProcessor | undefined;
 }
 export declare const imageProcessorPlugin: (config: Omit<ProcessorConfig<ImageProcessorConfig>, "name">) => ImageProcessorPlugin;

package/src/plugin.js

@@ -9,7 +9,7 @@ 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 { getSourceImagePaths, loadProcessedImagesFromDisk } from './image-runtime-state.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'),
@@ -66,6 +66,7 @@ type ImageSize = {
 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(/^\./, '')}`);
@@ -98,8 +99,11 @@ export class ImageProcessorPlugin extends Processor {
     }
     plugins() {
         return [
-            { ...createImagePlugin(this.processedImages), environments: ['server'] },
-            { ...createImagePluginBundler(this.processedImages), environments: ['browser'] },
+            { ...createImagePlugin(this.processedImages, () => this.ensurePrepared()), environments: ['server'] },
+            {
+                ...createImagePluginBundler(this.processedImages, () => this.ensurePrepared()),
+                environments: ['browser'],
+            },
         ];
     }
     /**
@@ -157,12 +161,6 @@ export class ImageProcessorPlugin extends Processor {
             subPath: 'virtual-module.ts',
         });
     }
-    getGeneratedOutputPath(src) {
-        if (!this.resolvedConfig) {
-            throw new Error('ImageProcessor not initialized');
-        }
-        return path.join(this.resolvedConfig.outputDir, path.basename(src));
-    }
     /**
      * Restores in-memory image state from previously generated dist artifacts.
      *
@@ -210,9 +208,24 @@ export class ImageProcessorPlugin extends Processor {
      * Ensures optimized image outputs and virtual-module state exist on disk.
      */
     async setup() {
+        this.preparation = this.prepare();
+        await this.preparation;
+    }
+    async prepare() {
         this.initializeProcessor();
         await this.ensureGeneratedOutputs();
     }
+    /**
+     * 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;
+    }
     /**
      * Process images.
      * @param images
@@ -226,7 +239,12 @@ export class ImageProcessorPlugin extends Processor {
             try {
                 const result = await this.processor.processImage(image);
                 if (result) {
-                    this.processedImages[path.basename(image)] = result;
+                    const key = path.basename(image);
+                    const previous = this.processedImages[key];
+                    this.processedImages[key] = result;
+                    if (previous) {
+                        await this.removeSupersededOutputs(previous, result);
+                    }
                 }
             }
             catch (error) {
@@ -236,44 +254,65 @@ export class ImageProcessorPlugin extends Processor {
         this.generateTypes();
     }
     /**
-     * Delete processed images using the original image path.
-     * @param imagePath
+     * 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 });
-        try {
-            const baseNameWithoutExt = path.basename(imagePath, path.extname(imagePath));
-            if (!this.options) {
-                throw new Error('Options not set');
+        const key = path.basename(imagePath);
+        const previous = this.processedImages[key];
+        if (!previous) {
+            return;
+        }
+        delete this.processedImages[key];
+        await this.removeSupersededOutputs(previous);
+        this.generateTypes();
+    }
+    /**
+     * 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 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 });
-                }
-            }));
+        }
+        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 {
-                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 });
+                logger.error('Failed to delete cache file for image', { cachePath, error });
             }
-            delete this.processedImages[path.basename(imagePath)];
-            this.generateTypes();
-        }
-        catch (error) {
-            logger.error('Failed to delete processed images', { path: imagePath, error });
         }
     }
     /**
@@ -335,13 +374,6 @@ declare module "ecopages:images" {
             writeFile: (filePath, content) => this.writeGeneratedFile(filePath, content),
         });
     }
-    /**
-     * Get the image processor instance.
-     * @returns The image processor instance.
-     */
-    getProcessor() {
-        return this.processor;
-    }
 }
 export const imageProcessorPlugin = (config) => {
     return new ImageProcessorPlugin(config);