@visulima/storage 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/transformer/image-transformer.js

@@ -0,0 +1,1100 @@
+import { Readable } from 'node:stream';
+import sharp from 'sharp';
+import BaseTransformer from '../packem_shared/BaseTransformer-C2gLib6v.js';
+import { isValidMediaType, getFormatFromContentType } from '../packem_shared/isValidMediaType-BeDgiObq.js';
+
+class ImageTransformer extends BaseTransformer {
+  /**
+   * Creates a new ImageTransformer instance.
+   * @param storage The storage backend for retrieving and storing image files.
+   * @param config Configuration options for image transformation including cache settings and size limits.
+   */
+  constructor(storage, config = {}) {
+    const logger = config.logger || storage.logger;
+    const transformerConfig = {
+      cacheTtl: 3600,
+      // 1 hour
+      maxCacheSize: 100,
+      // Max 100 transformed images in cache
+      maxImageSize: 50 * 1024 * 1024,
+      // 50MB
+      supportedFormats: ["jpeg", "png", "webp", "avif", "tiff", "gif", "svg"],
+      ...config
+    };
+    super(storage, transformerConfig, logger);
+  }
+  /**
+   * Resizes an image to specified dimensions with optional fit mode.
+   * @param fileId Unique identifier of the image file to resize.
+   * @param options Resize options including width, height, and fit mode.
+   * @returns Promise resolving to transformed image result.
+   */
+  async resize(fileId, options) {
+    return this.transform(fileId, [{ options, type: "resize" }]);
+  }
+  /**
+   * Crops an image to the specified region.
+   * @param fileId Unique identifier of the image file to crop.
+   * @param options Crop options including region coordinates.
+   * @returns Promise resolving to transformed image result.
+   */
+  async crop(fileId, options) {
+    return this.transform(fileId, [{ options, type: "crop" }]);
+  }
+  /**
+   * Rotates an image by the specified angle.
+   * @param fileId Unique identifier of the image file to rotate.
+   * @param options Rotate options including angle.
+   * @returns Promise resolving to transformed image result.
+   */
+  async rotate(fileId, options) {
+    return this.transform(fileId, [{ options, type: "rotate" }]);
+  }
+  /**
+   * Converts an image to the specified format.
+   * @param fileId Unique identifier of the image file to convert.
+   * @param format Target image format (e.g., "jpeg", "png", "webp").
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async convertFormat(fileId, format, options = {}) {
+    return this.transform(fileId, [{ options: { ...options, format }, type: "format" }]);
+  }
+  /**
+   * Applies sharpening filter to an image.
+   * @param fileId Unique identifier of the image file to sharpen.
+   * @param options Sharpen options including sigma and flat/jagged threshold.
+   * @returns Promise resolving to transformed image result.
+   */
+  async sharpen(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "sharpen" }]);
+  }
+  /**
+   * Applies blurring filter to an image.
+   * @param fileId Unique identifier of the image file to blur.
+   * @param options Blur options including sigma.
+   * @returns Promise resolving to transformed image result.
+   */
+  async blur(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "blur" }]);
+  }
+  /**
+   * Applies median filter to an image for noise reduction.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Median filter options including radius.
+   * @returns Promise resolving to transformed image result.
+   */
+  async median(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "median" }]);
+  }
+  /**
+   * Applies CLAHE (Contrast Limited Adaptive Histogram Equalization) to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options CLAHE options including width, height, and maxSlope.
+   * @returns Promise resolving to transformed image result.
+   */
+  async clahe(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "clahe" }]);
+  }
+  /**
+   * Applies convolution kernel to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Convolve options including kernel matrix.
+   * @returns Promise resolving to transformed image result.
+   */
+  async convolve(fileId, options) {
+    return this.transform(fileId, [{ options, type: "convolve" }]);
+  }
+  /**
+   * Applies thresholding to an image to create a binary image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Threshold options including threshold value.
+   * @returns Promise resolving to transformed image result.
+   */
+  async threshold(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "threshold" }]);
+  }
+  /**
+   * Applies boolean operation to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Boolean operation options including operator and operand.
+   * @returns Promise resolving to transformed image result.
+   */
+  async boolean(fileId, options) {
+    return this.transform(fileId, [{ options, type: "boolean" }]);
+  }
+  /**
+   * Applies linear transformation to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Linear transformation options including a and b coefficients.
+   * @returns Promise resolving to transformed image result.
+   */
+  async linear(fileId, options) {
+    return this.transform(fileId, [{ options, type: "linear" }]);
+  }
+  /**
+   * Applies recombine transformation to an image using a matrix.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Recombine options including matrix coefficients.
+   * @returns Promise resolving to transformed image result.
+   */
+  async recombine(fileId, options) {
+    return this.transform(fileId, [{ options, type: "recombine" }]);
+  }
+  /**
+   * Applies modulation (brightness, saturation, hue) to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Modulate options including brightness, saturation, and hue.
+   * @returns Promise resolving to transformed image result.
+   */
+  async modulate(fileId, options) {
+    return this.transform(fileId, [{ options, type: "modulate" }]);
+  }
+  /**
+   * Applies tinting to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Tint options including RGB color values.
+   * @returns Promise resolving to transformed image result.
+   */
+  async tint(fileId, options) {
+    return this.transform(fileId, [{ options, type: "tint" }]);
+  }
+  /**
+   * Converts an image to greyscale.
+   * @param fileId Unique identifier of the image file to convert.
+   * @param options Greyscale conversion options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async greyscale(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "greyscale" }]);
+  }
+  /**
+   * Converts an image to a different colourspace.
+   * @param fileId Unique identifier of the image file to convert.
+   * @param options Colourspace conversion options including target colourspace.
+   * @returns Promise resolving to transformed image result.
+   */
+  async colourspace(fileId, options) {
+    return this.transform(fileId, [{ options, type: "colourspace" }]);
+  }
+  /**
+   * Extracts a specific channel from an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Extract channel options including channel index.
+   * @returns Promise resolving to transformed image result.
+   */
+  async extractChannel(fileId, options) {
+    return this.transform(fileId, [{ options, type: "extractChannel" }]);
+  }
+  /**
+   * Joins channels to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Join channel options including channel sources.
+   * @returns Promise resolving to transformed image result.
+   */
+  async joinChannel(fileId, options) {
+    return this.transform(fileId, [{ options, type: "joinChannel" }]);
+  }
+  /**
+   * Applies band boolean operation to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Band boolean options including operator.
+   * @returns Promise resolving to transformed image result.
+   */
+  async bandbool(fileId, options) {
+    return this.transform(fileId, [{ options, type: "bandbool" }]);
+  }
+  /**
+   * Auto-orients an image based on EXIF orientation data.
+   * @param fileId Unique identifier of the image file to orient.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async autoOrient(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "autoOrient" }]);
+  }
+  /**
+   * Flips an image vertically.
+   * @param fileId Unique identifier of the image file to flip.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async flip(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "flip" }]);
+  }
+  /**
+   * Flops an image horizontally.
+   * @param fileId Unique identifier of the image file to flop.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async flop(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "flop" }]);
+  }
+  /**
+   * Flattens an image alpha channel onto a background color.
+   * @param fileId Unique identifier of the image file to flatten.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async flatten(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "flatten" }]);
+  }
+  /**
+   * Unflattens an image alpha channel.
+   * @param fileId Unique identifier of the image file to unflatten.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async unflatten(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "unflatten" }]);
+  }
+  /**
+   * Applies gamma correction to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async gamma(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "gamma" }]);
+  }
+  /**
+   * Negates (inverts) an image.
+   * @param fileId Unique identifier of the image file to negate.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async negate(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "negate" }]);
+  }
+  /**
+   * Normalises an image by enhancing contrast.
+   * @param fileId Unique identifier of the image file to normalise.
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async normalise(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "normalise" }]);
+  }
+  /**
+   * Applies affine transformation to an image.
+   * @param fileId Unique identifier of the image file to transform.
+   * @param options Affine transformation options including matrix.
+   * @returns Promise resolving to transformed image result.
+   */
+  async affine(fileId, options) {
+    return this.transform(fileId, [{ options, type: "affine" }]);
+  }
+  /**
+   * Applies dilation (morphological operation) to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Dilate options including iterations.
+   * @returns Promise resolving to transformed image result.
+   */
+  async dilate(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "dilate" }]);
+  }
+  /**
+   * Applies erosion (morphological operation) to an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Erode options including iterations.
+   * @returns Promise resolving to transformed image result.
+   */
+  async erode(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "erode" }]);
+  }
+  /**
+   * Sets pipeline colourspace for an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options Pipeline colourspace options including colourspace.
+   * @returns Promise resolving to transformed image result.
+   */
+  async pipelineColourspace(fileId, options) {
+    return this.transform(fileId, [{ options, type: "pipelineColourspace" }]);
+  }
+  /**
+   * Converts colourspace of an image.
+   * @param fileId Unique identifier of the image file to convert.
+   * @param options ToColourspace options including target colourspace.
+   * @returns Promise resolving to transformed image result.
+   */
+  async toColourspace(fileId, options) {
+    return this.transform(fileId, [{ options, type: "toColourspace" }]);
+  }
+  /**
+   * Removes alpha channel from an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options RemoveAlpha transformation options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async removeAlpha(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "removeAlpha" }]);
+  }
+  /**
+   * Ensures alpha channel exists in an image.
+   * @param fileId Unique identifier of the image file to process.
+   * @param options EnsureAlpha transformation options.
+   * @returns Promise resolving to transformed image result.
+   */
+  async ensureAlpha(fileId, options = {}) {
+    return this.transform(fileId, [{ options, type: "ensureAlpha" }]);
+  }
+  /**
+   * Applies a custom transformation pipeline to an image.
+   * @param fileId Unique identifier of the image file to transform.
+   * @param steps Array of transformation steps to apply in sequence.
+   * @returns Promise resolving to transformed image result.
+   */
+  async transform(fileId, steps) {
+    const fileQuery = { id: fileId };
+    const cacheKey = this.generateCacheKey(fileId, steps);
+    const cached = this.cache ? await Promise.resolve(this.cache.get(cacheKey)) : void 0;
+    if (cached) {
+      this.logger?.debug("Returning cached transformed image for %s", fileId);
+      return cached;
+    }
+    const originalFile = await this.storage.get(fileQuery);
+    await this.validateImage(originalFile);
+    const transformedBuffer = await this.applyTransformations(originalFile.content, steps);
+    const result = await this.createTransformResult(transformedBuffer, originalFile);
+    if (this.cache) {
+      this.cache.set(cacheKey, result);
+    }
+    return result;
+  }
+  /**
+   * Streams transform of a file (for large files, falls back to regular transform).
+   * @param fileId Unique identifier of the image file to transform.
+   * @param steps Array of transformation steps to apply in sequence.
+   * @returns Promise resolving to stream with headers and size information.
+   */
+  async transformStream(fileId, steps) {
+    const result = await this.transform(fileId, steps);
+    return {
+      headers: {
+        "Content-Length": result.buffer.length.toString(),
+        "Content-Type": this.getContentTypeFromResult(result),
+        "X-Image-Height": result.height?.toString(),
+        "X-Image-Width": result.width?.toString()
+      },
+      size: result.buffer.length,
+      stream: Readable.from(result.buffer)
+    };
+  }
+  /**
+   * Applies multiple transformations in sequence using Sharp.
+   * @param buffer The original image buffer.
+   * @param steps Array of transformation steps to apply.
+   * @returns Promise resolving to transformed image buffer.
+   * @private
+   */
+  async applyTransformations(buffer, steps) {
+    let sharpInstance = sharp(buffer);
+    for (const step of steps) {
+      switch (step.type) {
+        case "affine": {
+          sharpInstance = this.applyAffine(sharpInstance, step.options);
+          break;
+        }
+        case "autoOrient": {
+          sharpInstance = sharpInstance.rotate();
+          break;
+        }
+        case "bandbool": {
+          sharpInstance = this.applyBandbool(sharpInstance, step.options);
+          break;
+        }
+        case "blur": {
+          sharpInstance = this.applyBlur(sharpInstance, step.options);
+          break;
+        }
+        case "boolean": {
+          sharpInstance = this.applyBoolean(sharpInstance, step.options);
+          break;
+        }
+        case "clahe": {
+          sharpInstance = this.applyCLAHE(sharpInstance, step.options);
+          break;
+        }
+        case "colourspace": {
+          sharpInstance = this.applyColourspace(sharpInstance, step.options);
+          break;
+        }
+        case "convolve": {
+          sharpInstance = this.applyConvolve(sharpInstance, step.options);
+          break;
+        }
+        case "crop": {
+          sharpInstance = this.applyCrop(sharpInstance, step.options);
+          break;
+        }
+        case "dilate": {
+          sharpInstance = this.applyDilate(sharpInstance, step.options);
+          break;
+        }
+        case "ensureAlpha": {
+          sharpInstance = this.applyEnsureAlpha(sharpInstance, step.options);
+          break;
+        }
+        case "erode": {
+          sharpInstance = this.applyErode(sharpInstance, step.options);
+          break;
+        }
+        case "extractChannel": {
+          sharpInstance = this.applyExtractChannel(sharpInstance, step.options);
+          break;
+        }
+        case "flatten": {
+          sharpInstance = sharpInstance.flatten();
+          break;
+        }
+        case "flip": {
+          sharpInstance = sharpInstance.flip();
+          break;
+        }
+        case "flop": {
+          sharpInstance = sharpInstance.flop();
+          break;
+        }
+        case "format":
+        case "quality": {
+          sharpInstance = this.applyFormatAndQuality(sharpInstance, step.options);
+          break;
+        }
+        case "gamma": {
+          sharpInstance = sharpInstance.gamma();
+          break;
+        }
+        case "greyscale": {
+          sharpInstance = this.applyGreyscale(sharpInstance, step.options);
+          break;
+        }
+        case "joinChannel": {
+          sharpInstance = this.applyJoinChannel(sharpInstance, step.options);
+          break;
+        }
+        case "linear": {
+          sharpInstance = this.applyLinear(sharpInstance, step.options);
+          break;
+        }
+        case "median": {
+          sharpInstance = this.applyMedian(sharpInstance, step.options);
+          break;
+        }
+        case "modulate": {
+          sharpInstance = this.applyModulate(sharpInstance, step.options);
+          break;
+        }
+        case "negate": {
+          sharpInstance = sharpInstance.negate();
+          break;
+        }
+        case "normalise":
+        case "normalize": {
+          sharpInstance = sharpInstance.normalise();
+          break;
+        }
+        case "pipelineColourspace": {
+          sharpInstance = this.applyPipelineColourspace(sharpInstance, step.options);
+          break;
+        }
+        case "recombine": {
+          sharpInstance = this.applyRecombine(sharpInstance, step.options);
+          break;
+        }
+        case "removeAlpha": {
+          sharpInstance = this.applyRemoveAlpha(sharpInstance, step.options);
+          break;
+        }
+        case "resize": {
+          sharpInstance = this.applyResize(sharpInstance, step.options);
+          break;
+        }
+        case "rotate": {
+          sharpInstance = this.applyRotate(sharpInstance, step.options);
+          break;
+        }
+        case "sharpen": {
+          sharpInstance = this.applySharpen(sharpInstance, step.options);
+          break;
+        }
+        case "threshold": {
+          sharpInstance = this.applyThreshold(sharpInstance, step.options);
+          break;
+        }
+        case "tint": {
+          sharpInstance = this.applyTint(sharpInstance, step.options);
+          break;
+        }
+        case "toColourspace": {
+          sharpInstance = this.applyToColourspace(sharpInstance, step.options);
+          break;
+        }
+        case "unflatten": {
+          sharpInstance = sharpInstance.unflatten();
+          break;
+        }
+        default: {
+          throw new Error(`Unknown transformation type: ${step.type}`);
+        }
+      }
+    }
+    return sharpInstance.toBuffer();
+  }
+  /**
+   * Applies resize transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Resize transformation options.
+   * @returns Modified Sharp instance with resize applied.
+   * @private
+   */
+  applyResize(sharpInstance, options) {
+    const {
+      background,
+      fastShrinkOnLoad,
+      fit = "cover",
+      height,
+      kernel,
+      position,
+      width,
+      withoutEnlargement,
+      withoutReduction,
+      ...formatOptions
+    } = options;
+    let resizeOptions = {
+      background: background || "transparent",
+      fastShrinkOnLoad,
+      fit,
+      height,
+      kernel,
+      position,
+      width,
+      withoutEnlargement,
+      withoutReduction
+    };
+    if (Object.keys(formatOptions).length > 0) {
+      resizeOptions = { ...resizeOptions, ...this.getFormatOptions(formatOptions) };
+    }
+    return sharpInstance.resize(resizeOptions);
+  }
+  /**
+   * Applies crop transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Crop transformation options.
+   * @returns Modified Sharp instance with crop applied.
+   * @private
+   */
+  applyCrop(sharpInstance, options) {
+    const { height, left, top, width, ...formatOptions } = options;
+    let cropInstance = sharpInstance.extract({
+      height,
+      left,
+      top,
+      width
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      cropInstance = this.applyFormatAndQuality(cropInstance, formatOptions);
+    }
+    return cropInstance;
+  }
+  /**
+   * Applies rotate transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Rotate transformation options.
+   * @returns Modified Sharp instance with rotation applied.
+   * @private
+   */
+  applyRotate(sharpInstance, options) {
+    const { angle, background, ...formatOptions } = options;
+    let rotateInstance = sharpInstance.rotate(angle, {
+      background: background || "transparent"
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      rotateInstance = this.applyFormatAndQuality(rotateInstance, formatOptions);
+    }
+    return rotateInstance;
+  }
+  /**
+   * Applies sharpen transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Sharpen transformation options.
+   * @returns Modified Sharp instance with sharpening applied.
+   * @private
+   */
+  applySharpen(sharpInstance, options) {
+    const { sigma, ...formatOptions } = options;
+    const sharpenOptions = {};
+    if (sigma !== void 0) {
+      sharpenOptions.sigma = sigma;
+    }
+    let sharpenInstance = sharpInstance.sharpen(sharpenOptions);
+    if (Object.keys(formatOptions).length > 0) {
+      sharpenInstance = this.applyFormatAndQuality(sharpenInstance, formatOptions);
+    }
+    return sharpenInstance;
+  }
+  /**
+   * Applies blur transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Blur transformation options.
+   * @returns Modified Sharp instance with blurring applied.
+   * @private
+   */
+  applyBlur(sharpInstance, options) {
+    const { sigma, ...formatOptions } = options;
+    let blurInstance = sharpInstance.blur(sigma === void 0 ? true : sigma);
+    if (Object.keys(formatOptions).length > 0) {
+      blurInstance = this.applyFormatAndQuality(blurInstance, formatOptions);
+    }
+    return blurInstance;
+  }
+  /**
+   * Applies median filter using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Median transformation options.
+   * @returns Modified Sharp instance with median filter applied.
+   * @private
+   */
+  applyMedian(sharpInstance, options) {
+    const { size, ...formatOptions } = options;
+    let medianInstance = sharpInstance.median(size);
+    if (Object.keys(formatOptions).length > 0) {
+      medianInstance = this.applyFormatAndQuality(medianInstance, formatOptions);
+    }
+    return medianInstance;
+  }
+  /**
+   * Applies CLAHE (Contrast Limited Adaptive Histogram Equalization) using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options CLAHE transformation options.
+   * @returns Modified Sharp instance with CLAHE applied.
+   * @private
+   */
+  applyCLAHE(sharpInstance, options) {
+    const { height, maxSlope, width, ...formatOptions } = options;
+    let claheInstance = sharpInstance.clahe({
+      height,
+      maxSlope,
+      width
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      claheInstance = this.applyFormatAndQuality(claheInstance, formatOptions);
+    }
+    return claheInstance;
+  }
+  /**
+   * Applies convolution using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Convolution transformation options.
+   * @returns Modified Sharp instance with convolution applied.
+   * @private
+   */
+  applyConvolve(sharpInstance, options) {
+    const { height, kernel, offset, scale, width, ...formatOptions } = options;
+    let convolveInstance = sharpInstance.convolve({
+      height,
+      kernel,
+      offset,
+      scale,
+      width
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      convolveInstance = this.applyFormatAndQuality(convolveInstance, formatOptions);
+    }
+    return convolveInstance;
+  }
+  /**
+   * Applies threshold using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Threshold transformation options.
+   * @returns Modified Sharp instance with thresholding applied.
+   * @private
+   */
+  applyThreshold(sharpInstance, options) {
+    const { grayscale, greyscale, threshold = 128, ...formatOptions } = options;
+    let thresholdInstance = sharpInstance.threshold(threshold, {
+      greyscale: greyscale || grayscale
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      thresholdInstance = this.applyFormatAndQuality(thresholdInstance, formatOptions);
+    }
+    return thresholdInstance;
+  }
+  /**
+   * Applies boolean operation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Boolean operation options.
+   * @returns Modified Sharp instance with boolean operation applied.
+   * @private
+   */
+  applyBoolean(sharpInstance, options) {
+    const { operand, operator, raw, ...formatOptions } = options;
+    let booleanInstance = sharpInstance.boolean(operand, operator, raw);
+    if (Object.keys(formatOptions).length > 0) {
+      booleanInstance = this.applyFormatAndQuality(booleanInstance, formatOptions);
+    }
+    return booleanInstance;
+  }
+  /**
+   * Applies linear transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Linear transformation options.
+   * @returns Modified Sharp instance with linear transformation applied.
+   * @private
+   */
+  applyLinear(sharpInstance, options) {
+    const { a, b, ...formatOptions } = options;
+    let linearInstance = sharpInstance.linear(a, b);
+    if (Object.keys(formatOptions).length > 0) {
+      linearInstance = this.applyFormatAndQuality(linearInstance, formatOptions);
+    }
+    return linearInstance;
+  }
+  /**
+   * Applies recombine transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Recombine transformation options.
+   * @returns Modified Sharp instance with recombine applied.
+   * @private
+   */
+  applyRecombine(sharpInstance, options) {
+    const { matrix, ...formatOptions } = options;
+    let recombineInstance = sharpInstance.recomb(matrix.flat());
+    if (Object.keys(formatOptions).length > 0) {
+      recombineInstance = this.applyFormatAndQuality(recombineInstance, formatOptions);
+    }
+    return recombineInstance;
+  }
+  /**
+   * Applies modulate transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Modulate transformation options.
+   * @returns Modified Sharp instance with modulation applied.
+   * @private
+   */
+  applyModulate(sharpInstance, options) {
+    const { brightness, hue, lightness, saturation, ...formatOptions } = options;
+    let modulateInstance = sharpInstance.modulate({
+      brightness,
+      hue,
+      lightness,
+      saturation
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      modulateInstance = this.applyFormatAndQuality(modulateInstance, formatOptions);
+    }
+    return modulateInstance;
+  }
+  /**
+   * Applies tint using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Tint transformation options.
+   * @returns Modified Sharp instance with tinting applied.
+   * @private
+   */
+  applyTint(sharpInstance, options) {
+    const { rgb, ...formatOptions } = options;
+    let tintInstance = sharpInstance.tint(Array.isArray(rgb) ? rgb : rgb);
+    if (Object.keys(formatOptions).length > 0) {
+      tintInstance = this.applyFormatAndQuality(tintInstance, formatOptions);
+    }
+    return tintInstance;
+  }
+  /**
+   * Applies greyscale conversion using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Greyscale transformation options.
+   * @returns Modified Sharp instance converted to greyscale.
+   * @private
+   */
+  applyGreyscale(sharpInstance, options) {
+    const { grayscale, greyscale, ...formatOptions } = options;
+    let greyscaleInstance = sharpInstance.greyscale(greyscale || grayscale);
+    if (Object.keys(formatOptions).length > 0) {
+      greyscaleInstance = this.applyFormatAndQuality(greyscaleInstance, formatOptions);
+    }
+    return greyscaleInstance;
+  }
+  /**
+   * Applies colourspace conversion using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Colourspace transformation options.
+   * @returns Modified Sharp instance with colourspace conversion.
+   * @private
+   */
+  applyColourspace(sharpInstance, options) {
+    const { colourspace, ...formatOptions } = options;
+    let colourspaceInstance = sharpInstance.toColourspace(colourspace);
+    if (Object.keys(formatOptions).length > 0) {
+      colourspaceInstance = this.applyFormatAndQuality(colourspaceInstance, formatOptions);
+    }
+    return colourspaceInstance;
+  }
+  /**
+   * Extracts channel using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Channel extraction options including channel index.
+   * @returns Modified Sharp instance with channel extracted.
+   * @private
+   */
+  applyExtractChannel(sharpInstance, options) {
+    const { channel, ...formatOptions } = options;
+    let extractInstance = sharpInstance.extractChannel(channel);
+    if (Object.keys(formatOptions).length > 0) {
+      extractInstance = this.applyFormatAndQuality(extractInstance, formatOptions);
+    }
+    return extractInstance;
+  }
+  /**
+   * Joins channels using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Channel joining options including image sources.
+   * @returns Modified Sharp instance with channels joined.
+   * @private
+   */
+  applyJoinChannel(sharpInstance, options) {
+    const { images, ...formatOptions } = options;
+    let joinInstance = sharpInstance.joinChannel(images);
+    if (Object.keys(formatOptions).length > 0) {
+      joinInstance = this.applyFormatAndQuality(joinInstance, formatOptions);
+    }
+    return joinInstance;
+  }
+  /**
+   * Applies band boolean operation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Band boolean options including operator.
+   * @returns Modified Sharp instance with band boolean operation applied.
+   * @private
+   */
+  applyBandbool(sharpInstance, options) {
+    const { operator, ...formatOptions } = options;
+    let bandboolInstance = sharpInstance.bandbool(operator);
+    if (Object.keys(formatOptions).length > 0) {
+      bandboolInstance = this.applyFormatAndQuality(bandboolInstance, formatOptions);
+    }
+    return bandboolInstance;
+  }
+  /**
+   * Applies affine transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Affine transformation options including matrix.
+   * @returns Modified Sharp instance with affine transformation applied.
+   * @private
+   */
+  applyAffine(sharpInstance, options) {
+    const { background, interpolation, matrix, ...formatOptions } = options;
+    let affineInstance = sharpInstance.affine(matrix, {
+      background: background || "transparent",
+      interpolator: interpolation || "bicubic"
+    });
+    if (Object.keys(formatOptions).length > 0) {
+      affineInstance = this.applyFormatAndQuality(affineInstance, formatOptions);
+    }
+    return affineInstance;
+  }
+  /**
+   * Applies dilation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Dilate options including kernel size.
+   * @returns Modified Sharp instance with dilation applied.
+   * @private
+   */
+  applyDilate(sharpInstance, options) {
+    const { kernelSize, ...formatOptions } = options;
+    let dilateInstance = kernelSize ? sharpInstance.dilate(kernelSize) : sharpInstance.dilate();
+    if (Object.keys(formatOptions).length > 0) {
+      dilateInstance = this.applyFormatAndQuality(dilateInstance, formatOptions);
+    }
+    return dilateInstance;
+  }
+  /**
+   * Applies erosion using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Erode options including kernel size.
+   * @returns Modified Sharp instance with erosion applied.
+   * @private
+   */
+  applyErode(sharpInstance, options) {
+    const { kernelSize, ...formatOptions } = options;
+    let erodeInstance = kernelSize ? sharpInstance.erode(kernelSize) : sharpInstance.erode();
+    if (Object.keys(formatOptions).length > 0) {
+      erodeInstance = this.applyFormatAndQuality(erodeInstance, formatOptions);
+    }
+    return erodeInstance;
+  }
+  /**
+   * Applies pipeline colourspace using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Pipeline colourspace options including target colourspace.
+   * @returns Modified Sharp instance with pipeline colourspace applied.
+   * @private
+   */
+  applyPipelineColourspace(sharpInstance, options) {
+    const { colourspace, ...formatOptions } = options;
+    let colourspaceInstance = sharpInstance.pipelineColourspace(colourspace);
+    if (Object.keys(formatOptions).length > 0) {
+      colourspaceInstance = this.applyFormatAndQuality(colourspaceInstance, formatOptions);
+    }
+    return colourspaceInstance;
+  }
+  /**
+   * Applies to colourspace conversion using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options To colourspace options including target colourspace.
+   * @returns Modified Sharp instance with colourspace conversion applied.
+   * @private
+   */
+  applyToColourspace(sharpInstance, options) {
+    const { colourspace, ...formatOptions } = options;
+    let colourspaceInstance = sharpInstance.toColourspace(colourspace);
+    if (Object.keys(formatOptions).length > 0) {
+      colourspaceInstance = this.applyFormatAndQuality(colourspaceInstance, formatOptions);
+    }
+    return colourspaceInstance;
+  }
+  /**
+   * Applies remove alpha using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Remove alpha transformation options.
+   * @returns Modified Sharp instance with alpha channel removed.
+   * @private
+   */
+  applyRemoveAlpha(sharpInstance, options) {
+    const { background, ...formatOptions } = options;
+    let alphaInstance = sharpInstance.removeAlpha();
+    if (Object.keys(formatOptions).length > 0) {
+      alphaInstance = this.applyFormatAndQuality(alphaInstance, formatOptions);
+    }
+    return alphaInstance;
+  }
+  /**
+   * Applies ensure alpha using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Ensure alpha transformation options.
+   * @returns Modified Sharp instance with alpha channel ensured.
+   * @private
+   */
+  applyEnsureAlpha(sharpInstance, options) {
+    const { alpha, ...formatOptions } = options;
+    let alphaInstance = sharpInstance.ensureAlpha();
+    if (Object.keys(formatOptions).length > 0) {
+      alphaInstance = this.applyFormatAndQuality(alphaInstance, formatOptions);
+    }
+    return alphaInstance;
+  }
+  /**
+   * Applies format and quality transformation using Sharp.
+   * @param sharpInstance The Sharp instance to modify.
+   * @param options Format and quality transformation options.
+   * @returns Modified Sharp instance with format and quality settings applied.
+   * @private
+   */
+  applyFormatAndQuality(sharpInstance, options) {
+    const formatOptions = this.getFormatOptions(options);
+    if (options.format) {
+      return sharpInstance.toFormat(options.format, formatOptions);
+    }
+    if (Object.keys(formatOptions).length > 0) {
+      return sharpInstance.jpeg(formatOptions).png(formatOptions).webp(formatOptions);
+    }
+    return sharpInstance;
+  }
+  /**
+   * Gets format-specific options for Sharp.
+   * @param options Transform options containing format-specific settings.
+   * @returns Record of format options for Sharp processing.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  getFormatOptions(options) {
+    const { alphaQuality, compressionLevel, delay, effort, loop, lossless, progressive, quality } = options;
+    const formatOptions = {};
+    if (quality !== void 0) {
+      formatOptions.quality = quality;
+    }
+    if (progressive !== void 0) {
+      formatOptions.progressive = progressive;
+    }
+    if (lossless !== void 0) {
+      formatOptions.lossless = lossless;
+    }
+    if (compressionLevel !== void 0) {
+      formatOptions.compressionLevel = compressionLevel;
+    }
+    if (effort !== void 0) {
+      formatOptions.effort = effort;
+    }
+    if (alphaQuality !== void 0) {
+      formatOptions.alphaQuality = alphaQuality;
+    }
+    if (loop !== void 0) {
+      formatOptions.loop = loop;
+    }
+    if (delay !== void 0) {
+      formatOptions.delay = delay;
+    }
+    return formatOptions;
+  }
+  /**
+   * Validates that the file is a supported image.
+   * @param file The file to validate.
+   * @returns Promise that resolves if validation passes.
+   * @throws Error if file size exceeds limits, wrong content type, unsupported format, or invalid image.
+   * @private
+   */
+  async validateImage(file) {
+    const fileSize = typeof file.size === "string" ? Number.parseInt(file.size, 10) : file.size;
+    if (this.config?.maxImageSize && fileSize > this.config.maxImageSize) {
+      throw new Error(`Image size ${fileSize} exceeds maximum allowed size ${this.config.maxImageSize}`);
+    }
+    if (!isValidMediaType(file.contentType, "image")) {
+      throw new Error(`File is not an image: ${file.contentType}`);
+    }
+    const format = getFormatFromContentType(file.contentType);
+    if (this.config?.supportedFormats && format && !this.config.supportedFormats.includes(format)) {
+      throw new Error(`Unsupported image format: ${format}`);
+    }
+    try {
+      const metadata = await sharp(file.content).metadata();
+      if (!metadata.width || !metadata.height) {
+        throw new Error("Invalid image: missing dimensions");
+      }
+    } catch (error) {
+      throw new Error(`Invalid image file: ${error}`);
+    }
+  }
+  /**
+   * Creates transformation result with metadata.
+   * @param buffer The transformed image buffer.
+   * @param originalFile The original file information.
+   * @returns Image transformation result with metadata.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  async createTransformResult(buffer, originalFile) {
+    const metadata = await sharp(buffer).metadata();
+    return {
+      buffer,
+      format: metadata.format || "unknown",
+      height: metadata.height || 0,
+      originalFile,
+      size: buffer.length,
+      width: metadata.width || 0
+    };
+  }
+  /**
+   * Generates cache key for transformation.
+   * @param fileId The file identifier.
+   * @param steps Array of transformation steps.
+   * @returns Unique cache key string.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  generateCacheKey(fileId, steps) {
+    const stepsKey = steps.map((step) => `${step.type}:${JSON.stringify(step.options)}`).join("|");
+    return `${fileId}:${stepsKey}`;
+  }
+}
+
+export { ImageTransformer as default };