@ecopages/image-processor 0.2.1 → 0.3.1

package/src/image-utils.js

@@ -1,103 +1,114 @@
-import { DEFAULT_LAYOUT } from "./constants.js";
-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]);
+import { DEFAULT_LAYOUT } from './constants.js';
+/**
+ * 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 {
+    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(', ');
     }
-    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}`]);
+    /**
+     * 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]);
         }
-        break;
-      case "full-width":
-        styles.push(["width", "100%"]);
-        if (config.height) {
-          styles.push(["height", `${config.height}px`], ["min-height", `${config.height}px`]);
+        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;
         }
-        break;
+        return styles;
     }
-    return styles;
-  }
 }
-export {
-  ImageUtils
-};

package/src/index.js

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

package/src/plugin.d.ts

@@ -2,9 +2,7 @@
  * 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.js';
+import { Processor, type EcoBuildPlugin, type ProcessorConfig } from '@ecopages/core/processor';
 import type { ImageSize, ImageSpecifications } from './types.js';
 /**
  * Configuration for the image processor
@@ -33,19 +31,19 @@ export interface ImageProcessorConfig {
  * ImageMap
  * This is the representation of the image map in the virtual module
  */
-export type ImageMap = Record<string, ImageSpecifications>;
+export type { ImageMap } from './image-runtime-state.js';
 /**
  * ImageProcessorPlugin
  * A Processor for optimizing images.
  */
 export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
     private processor;
-    private buildContributionsPrepared;
     private resolvedConfig?;
     processedImages: Record<string, ImageSpecifications>;
-    constructor(config: Omit<ProcessorConfig<ImageProcessorConfig>, 'name' | 'description'>);
-    get buildPlugins(): EcoBuildPlugin[];
-    get plugins(): EcoBuildPlugin[];
+    private preparation?;
+    constructor(config: Omit<ProcessorConfig<ImageProcessorConfig>, 'name'>);
+    private handleImageChanges;
+    plugins(): EcoBuildPlugin[];
     /**
      * Replaces image-map contents without swapping the backing object.
      *
@@ -55,46 +53,59 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
      */
     private replaceProcessedImages;
     /**
-     * Prepares the image virtual-module state before config build seals the app
-     * manifest.
+     * Resolves processor config and creates the sharp-backed worker instance.
      */
-    prepareBuildContributions(): Promise<void>;
+    private initializeProcessor;
     private getRuntimeVirtualModulePath;
-    private getGeneratedOutputPath;
-    private hasGeneratedOutputs;
-    private rehydrateGeneratedOutputs;
     /**
-     * Generate dependencies for processor.
-     * It is ossible to define which one should be included in the final bundle based on the environment.
-     * @returns
+     * Restores in-memory image state from previously generated dist artifacts.
+     *
+     * @returns `true` when state was restored without invoking sharp.
      */
-    private generateDependencies;
+    private syncProcessedImagesFromDisk;
+    private ensureGeneratedOutputs;
+    private writeGeneratedFile;
     /**
-     * Prepares build contributions if not already done and rehydrates previously generated image outputs.
+     * 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>;
     /**
-     * Generate types for the virtual module.
+     * 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 generateTypes;
+    private removeSupersededOutputs;
     /**
-     * Teardown the image processor.
+     * Generate types for the virtual module.
      */
-    teardown(): Promise<void>;
+    private generateTypes;
     /**
-     * Get the image processor instance.
-     * @returns The image processor instance.
+     * Writes the ambient declaration package for `ecopages:images`.
      */
-    getProcessor(): ImageProcessor | undefined;
+    private writeVirtualModuleTypes;
 }
-export declare const imageProcessorPlugin: (config: Omit<ProcessorConfig<ImageProcessorConfig>, "name" | "description">) => ImageProcessorPlugin;
+export declare const imageProcessorPlugin: (config: Omit<ProcessorConfig<ImageProcessorConfig>, "name">) => ImageProcessorPlugin;