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

package/dist/packem_shared/MediaTransformer-BErvw2vE.js

@@ -0,0 +1,1196 @@
+import { createHash } from 'node:crypto';
+import mime from 'mime';
+import { N as NoOpCache } from './cache-B88MXQ_2.js';
+import { isKnownContentType } from './isValidMediaType-BeDgiObq.js';
+import ValidationError from './ValidationError-BfF1aE4h.js';
+
+class MediaTransformer {
+  /**
+   * Creates a new MediaTransformer instance.
+   * @param storage The storage backend for retrieving and storing media files.
+   * @param config Configuration options for the media transformer including transformer classes and settings.
+   * @throws Error if no transformer classes are provided in the configuration.
+   */
+  constructor(storage, config = {}) {
+    this.storage = storage;
+    this.logger = config.logger || this.storage.logger;
+    this.config = {
+      audioBitrate: 128e3,
+      // 128 kbps
+      audioCodec: "aac",
+      cache: config.cache ?? new NoOpCache(),
+      cacheTtl: 3600,
+      // 1 hour
+      maxAudioSize: 100 * 1024 * 1024,
+      // 100MB
+      maxImageSize: 10 * 1024 * 1024,
+      // 10MB
+      maxVideoSize: 500 * 1024 * 1024,
+      // 500MB
+      saveTransformedFiles: false,
+      // Save transformed files to storage
+      supportedAudioFormats: [],
+      supportedImageFormats: [],
+      supportedVideoFormats: [],
+      videoBitrate: 2e6,
+      // 2 Mbps
+      videoCodec: "avc",
+      ...config
+    };
+    if (config.ImageTransformer) {
+      if (!Array.isArray(this.config.supportedImageFormats) || this.config.supportedImageFormats.length === 0) {
+        this.config.supportedImageFormats = ["jpeg", "png", "webp", "avif", "tiff", "gif", "svg"];
+      }
+      this.imageTransformer = new config.ImageTransformer(this.storage, {
+        cache: this.config.cache,
+        cacheTtl: this.config.cacheTtl,
+        logger: this.logger,
+        maxImageSize: this.config.maxImageSize,
+        supportedFormats: this.config.supportedImageFormats
+      });
+    }
+    if (config.VideoTransformer) {
+      if (!Array.isArray(this.config.supportedVideoFormats) || this.config.supportedVideoFormats.length === 0) {
+        this.config.supportedVideoFormats = ["mp4", "webm", "mkv", "avi", "mov", "flv", "wmv"];
+      }
+      this.videoTransformer = new config.VideoTransformer(this.storage, {
+        cache: this.config.cache,
+        cacheTtl: this.config.cacheTtl,
+        defaultBitrate: this.config.videoBitrate,
+        defaultCodec: this.config.videoCodec,
+        logger: this.logger,
+        maxVideoSize: this.config.maxVideoSize,
+        supportedFormats: this.config.supportedVideoFormats
+      });
+    }
+    if (config.AudioTransformer) {
+      if (!Array.isArray(this.config.supportedAudioFormats) || this.config.supportedAudioFormats.length === 0) {
+        this.config.supportedAudioFormats = ["mp3", "wav", "ogg", "aac", "flac", "m4a", "wma", "aiff"];
+      }
+      this.audioTransformer = new config.AudioTransformer(this.storage, {
+        cache: this.config.cache,
+        cacheTtl: this.config.cacheTtl,
+        defaultBitrate: this.config.audioBitrate,
+        defaultCodec: this.config.audioCodec,
+        logger: this.logger,
+        maxAudioSize: this.config.maxAudioSize,
+        supportedFormats: this.config.supportedAudioFormats
+      });
+    }
+    if (config.AudioTransformer === void 0 && config.ImageTransformer === void 0 && config.VideoTransformer === void 0) {
+      throw new Error(
+        "MediaTransformer initialization failed: No transformers are configured. At least one transformer (AudioTransformer, ImageTransformer, or VideoTransformer) must be provided in the configuration to enable media processing functionality."
+      );
+    }
+  }
+  storage;
+  imageTransformer;
+  videoTransformer;
+  audioTransformer;
+  config;
+  logger;
+  supportedFormats() {
+    return [...this.config.supportedAudioFormats, ...this.config.supportedImageFormats, ...this.config.supportedVideoFormats];
+  }
+  /**
+   * Handles media transformation based on query parameters.
+   * @param fileId File identifier.
+   * @param query Query parameters for transformation.
+   * @returns Unified transformation result.
+   */
+  async handle(fileId, query) {
+    const parsedQuery = this.parseQuery(query);
+    const fileQuery = { id: fileId };
+    const file = await this.storage.get(fileQuery);
+    const mediaType = this.detectMediaType(file.contentType);
+    this.validateQueryParameters(parsedQuery, mediaType);
+    if (this.config.saveTransformedFiles && this.hasTransformations(parsedQuery)) {
+      const transformedFileId = this.generateTransformedFileId(fileId, parsedQuery, mediaType);
+      try {
+        const transformedFile = await this.storage.get({ id: transformedFileId });
+        this.logger?.debug?.(`Serving cached transformed file: ${transformedFileId}`);
+        return this.createMediaTransformResult(transformedFile, mediaType, file);
+      } catch {
+        this.logger?.debug?.(`Transformed file not found, processing: ${transformedFileId}`);
+      }
+    }
+    let result;
+    switch (mediaType) {
+      case "audio": {
+        if (!this.audioTransformer) {
+          throw new Error(
+            "Audio transformer not available. Please install audio transformation dependencies or provide an audio transformer instance."
+          );
+        }
+        result = await this.handleAudioTransformation(fileId, parsedQuery);
+        break;
+      }
+      case "image": {
+        if (!this.imageTransformer) {
+          throw new Error(
+            "Image transformer not available. Please install image transformation dependencies or provide an image transformer instance."
+          );
+        }
+        result = await this.handleImageTransformation(fileId, parsedQuery);
+        break;
+      }
+      case "video": {
+        if (!this.videoTransformer) {
+          throw new Error(
+            "Video transformer not available. Please install video transformation dependencies or provide a video transformer instance."
+          );
+        }
+        result = await this.handleVideoTransformation(fileId, parsedQuery);
+        break;
+      }
+      default: {
+        throw new Error(`Unsupported media type: ${file.contentType}`);
+      }
+    }
+    if (this.config.saveTransformedFiles && this.hasTransformations(parsedQuery)) {
+      await this.saveTransformedFile(result, fileId, parsedQuery, mediaType);
+    }
+    return result;
+  }
+  /**
+   * Fetches media transformation with URL query string support.
+   * @param fileId File identifier.
+   * @param queryString URL query string (e.g., "width=800&height=600&format=webp").
+   * @returns Unified transformation result.
+   */
+  async fetch(fileId, queryString) {
+    const query = new URLSearchParams(queryString);
+    return this.handle(fileId, query);
+  }
+  /**
+   * Clears cache for a specific file across all transformers.
+   * @param fileId Optional file identifier to clear cache for. If omitted, clears all cache.
+   */
+  clearCache(fileId) {
+    this.imageTransformer?.clearCache(fileId);
+    this.videoTransformer?.clearCache(fileId);
+    this.audioTransformer?.clearCache(fileId);
+  }
+  /**
+   * Clears all saved transformed files from storage.
+   * @remarks This is a maintenance operation and may take time for large numbers of files.
+   */
+  async clearSavedTransformedFiles() {
+    if (!this.config.saveTransformedFiles) {
+      return;
+    }
+    try {
+      this.logger?.warn?.("clearSavedTransformedFiles requires custom storage implementation to find and delete transformed files");
+    } catch (error) {
+      this.logger?.error?.(`Failed to clear saved transformed files: ${error}`);
+    }
+  }
+  /**
+   * Clears saved transformed files for a specific original file.
+   * @param originalFileId Original file identifier to clear transformed files for.
+   */
+  async clearSavedTransformedFilesForFile(originalFileId) {
+    if (!this.config.saveTransformedFiles) {
+      return;
+    }
+    try {
+      this.logger?.warn?.("clearSavedTransformedFilesForFile requires custom storage implementation");
+    } catch (error) {
+      this.logger?.error?.(`Failed to clear saved transformed files for ${originalFileId}: ${error}`);
+    }
+  }
+  /**
+   * Gets cache statistics (combined from all transformers).
+   * @returns Cache statistics for audio, image, and video transformers.
+   */
+  getCacheStats() {
+    const stats = {
+      audio: this.audioTransformer?.getCacheStats(),
+      image: this.imageTransformer?.getCacheStats(),
+      video: this.videoTransformer?.getCacheStats()
+    };
+    if (stats.image === void 0) delete stats.image;
+    if (stats.video === void 0) delete stats.video;
+    if (stats.audio === void 0) delete stats.audio;
+    return stats;
+  }
+  /**
+   * Validates query parameters for the given media type.
+   * @param query The query parameters to validate.
+   * @param mediaType The media type being validated ('image', 'video', or 'audio').
+   * @throws {ValidationError} When invalid parameters are provided.
+   */
+  validateQueryParameters(query, mediaType) {
+    switch (mediaType) {
+      case "audio": {
+        this.validateAudioQueryParameters(query);
+        break;
+      }
+      case "image": {
+        this.validateImageQueryParameters(query);
+        break;
+      }
+      case "video": {
+        this.validateVideoQueryParameters(query);
+        break;
+      }
+    }
+  }
+  /**
+   * Validates query parameters for image transformations. Checks for invalid video/audio-only parameters, invalid fit values, invalid rotation angles, invalid formats, and incomplete crop parameter sets.
+   * @param query Query parameters to validate.
+   * @throws {ValidationError} When validation fails.
+   */
+  // eslint-disable-next-line class-methods-use-this
+  validateImageQueryParameters(query) {
+    const allowedParameters = /* @__PURE__ */ new Set([
+      "alphaQuality",
+      "angle",
+      "background",
+      "bandbool",
+      "blur",
+      "boolean",
+      "brightness",
+      "channel",
+      "clahe",
+      "colourspace",
+      "compressionLevel",
+      "convolve",
+      "cropHeight",
+      "cropWidth",
+      "delay",
+      "dilate",
+      "effort",
+      "erode",
+      "extractChannel",
+      "fastShrinkOnLoad",
+      "fit",
+      "flatten",
+      "flip",
+      "flop",
+      "format",
+      "frameRate",
+      "gamma",
+      "grayscale",
+      "greyscale",
+      "height",
+      "hue",
+      "joinChannel",
+      "kernel",
+      "left",
+      "lightness",
+      "linear",
+      "loop",
+      "maxSlope",
+      "median",
+      "modulate",
+      "negate",
+      "normalise",
+      "normalize",
+      "position",
+      "quality",
+      "recombine",
+      "saturation",
+      "sharpen",
+      "threshold",
+      "tint",
+      "top",
+      "unflatten",
+      "width",
+      "withoutEnlargement",
+      "withoutReduction"
+    ]);
+    const videoAudioOnlyParameters = /* @__PURE__ */ new Set(["bitrate", "codec", "frameRate", "keyFrameInterval", "numberOfChannels", "sampleRate"]);
+    const invalidParameters = [];
+    for (const parameter of videoAudioOnlyParameters) {
+      if (query[parameter] !== void 0) {
+        invalidParameters.push(parameter);
+      }
+    }
+    if (invalidParameters.length > 0) {
+      const sortedInvalidParameters = [...invalidParameters].toSorted();
+      throw new ValidationError(
+        `Invalid query parameters for image transformation: ${sortedInvalidParameters.join(", ")}. Images support: ${[...allowedParameters].toSorted().join(", ")}. Video/audio parameters (${sortedInvalidParameters.join(", ")}) are not supported for images.`,
+        "INVALID_PARAMS_FOR_IMAGE",
+        "image",
+        sortedInvalidParameters,
+        [...allowedParameters].toSorted()
+      );
+    }
+    if (query.fit && !["contain", "cover", "fill", "inside", "outside"].includes(query.fit)) {
+      throw new ValidationError(
+        `Invalid fit value: "${query.fit}". Supported values: "cover", "contain", "fill", "inside", "outside"`,
+        "INVALID_FIT_VALUE",
+        "image",
+        ["fit"],
+        ["cover", "contain", "fill", "inside", "outside"]
+      );
+    }
+    if (query.format && !["avif", "gif", "jpeg", "png", "tiff", "webp"].includes(query.format)) {
+      throw new ValidationError(
+        `Invalid format for image: "${query.format}". Supported formats: jpeg, png, webp, avif, tiff, gif`,
+        "INVALID_FORMAT",
+        "image",
+        ["format"],
+        ["jpeg", "png", "webp", "avif", "tiff", "gif"]
+      );
+    }
+    const cropParameters = ["left", "top", "cropWidth", "cropHeight"];
+    const providedCropParameters = cropParameters.filter((parameter) => query[parameter] !== void 0);
+    if (providedCropParameters.length > 0 && providedCropParameters.length !== cropParameters.length) {
+      throw new ValidationError(
+        `Incomplete crop parameters: ${providedCropParameters.join(", ")}. All crop parameters must be provided: left, top, cropWidth, cropHeight`,
+        "INCOMPLETE_CROP_PARAMS",
+        "image",
+        providedCropParameters,
+        cropParameters
+      );
+    }
+  }
+  /**
+   * Validates query parameters for video transformations. Checks for invalid audio-only parameters, invalid fit values, invalid rotation angles, invalid codecs, invalid formats, incomplete crop parameter sets, and invalid numeric values.
+   * @param query Query parameters to validate.
+   * @throws {ValidationError} When validation fails.
+   */
+  // eslint-disable-next-line class-methods-use-this
+  validateVideoQueryParameters(query) {
+    const allowedParameters = /* @__PURE__ */ new Set([
+      "angle",
+      "background",
+      "bitrate",
+      "codec",
+      "cropHeight",
+      "cropWidth",
+      "fit",
+      "format",
+      "frameRate",
+      "height",
+      "keyFrameInterval",
+      "left",
+      "position",
+      "quality",
+      "top",
+      "width",
+      "withoutEnlargement",
+      "withoutReduction"
+    ]);
+    const audioOnlyParameters = /* @__PURE__ */ new Set(["numberOfChannels", "sampleRate"]);
+    const invalidParameters = [];
+    for (const parameter of audioOnlyParameters) {
+      if (query[parameter] !== void 0) {
+        invalidParameters.push(parameter);
+      }
+    }
+    if (invalidParameters.length > 0) {
+      const sortedInvalidParameters = [...invalidParameters].toSorted();
+      throw new ValidationError(
+        `Invalid query parameters for video transformation: ${sortedInvalidParameters.join(", ")}. Videos support: ${[...allowedParameters].toSorted().join(", ")}. Audio-only parameters (${sortedInvalidParameters.join(", ")}) are not supported for videos.`,
+        "INVALID_PARAMS_FOR_VIDEO",
+        "video",
+        sortedInvalidParameters,
+        [...allowedParameters].toSorted()
+      );
+    }
+    if (query.fit && !["contain", "cover", "fill", "inside", "outside"].includes(query.fit)) {
+      throw new ValidationError(
+        `Invalid fit value: "${query.fit}". Supported values: "cover", "contain", "fill", "inside", "outside"`,
+        "INVALID_FIT_VALUE",
+        "video",
+        ["fit"],
+        ["cover", "contain", "fill", "inside", "outside"]
+      );
+    }
+    if (query.codec && !["av1", "avc", "hevc", "vp8", "vp9"].includes(query.codec)) {
+      throw new ValidationError(
+        `Invalid codec for video: "${query.codec}". Supported codecs: avc, hevc, vp8, vp9, av1`,
+        "INVALID_VIDEO_CODEC",
+        "video",
+        ["codec"],
+        ["avc", "hevc", "vp8", "vp9", "av1"]
+      );
+    }
+    if (query.format && !["mkv", "mp4", "ogg", "webm"].includes(query.format)) {
+      throw new ValidationError(
+        `Invalid format for video: "${query.format}". Supported formats: mp4, webm, mkv, ogg`,
+        "INVALID_VIDEO_FORMAT",
+        "video",
+        ["format"],
+        ["mp4", "webm", "mkv", "ogg"]
+      );
+    }
+    const cropParameters = ["left", "top", "cropWidth", "cropHeight"];
+    const providedCropParameters = cropParameters.filter((parameter) => query[parameter] !== void 0);
+    if (providedCropParameters.length > 0 && providedCropParameters.length !== cropParameters.length) {
+      throw new ValidationError(
+        `Incomplete crop parameters: ${providedCropParameters.join(", ")}. All crop parameters must be provided: left, top, cropWidth, cropHeight`,
+        "INCOMPLETE_CROP_PARAMS",
+        "video",
+        providedCropParameters,
+        cropParameters
+      );
+    }
+    if (query.width !== void 0 && (typeof query.width !== "number" || query.width <= 0)) {
+      throw new ValidationError(`Invalid width: ${query.width}. Must be a positive number.`, "INVALID_WIDTH", "video", ["width"], []);
+    }
+    if (query.height !== void 0 && (typeof query.height !== "number" || query.height <= 0)) {
+      throw new ValidationError(`Invalid height: ${query.height}. Must be a positive number.`, "INVALID_HEIGHT", "video", ["height"], []);
+    }
+    if (query.bitrate !== void 0 && (typeof query.bitrate !== "number" || query.bitrate <= 0)) {
+      throw new ValidationError(`Invalid bitrate: ${query.bitrate}. Must be a positive number.`, "INVALID_BITRATE", "video", ["bitrate"], []);
+    }
+    if (query.frameRate !== void 0 && (typeof query.frameRate !== "number" || query.frameRate <= 0)) {
+      throw new ValidationError(`Invalid frameRate: ${query.frameRate}. Must be a positive number.`, "INVALID_FRAME_RATE", "video", ["frameRate"], []);
+    }
+    if (query.keyFrameInterval !== void 0 && (typeof query.keyFrameInterval !== "number" || query.keyFrameInterval <= 0)) {
+      throw new ValidationError(
+        `Invalid keyFrameInterval: ${query.keyFrameInterval}. Must be a positive number.`,
+        "INVALID_KEY_FRAME_INTERVAL",
+        "video",
+        ["keyFrameInterval"],
+        []
+      );
+    }
+  }
+  /**
+   * Generates a unique ID for transformed files based on original file and transformations.
+   * @param originalFileId The original file identifier.
+   * @param query The transformation query parameters.
+   * @param mediaType The media type (image, video, audio).
+   * @returns Unique deterministic identifier for the transformed file.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  generateTransformedFileId(originalFileId, query, mediaType) {
+    const transformParameters = Object.keys(query).filter((key) => query[key] !== void 0).toSorted().map((key) => `${key}:${query[key]}`).join("|");
+    const hashInput = `${originalFileId}|${mediaType}|${transformParameters}`;
+    const hash = createHash("sha256").update(hashInput).digest("hex").slice(0, 16);
+    return `${originalFileId}_transformed_${hash}`;
+  }
+  /**
+   * Checks if the query contains any transformations.
+   * @param query The transformation query parameters.
+   * @returns True if any transformations are requested.
+   * @private
+   */
+  hasTransformations(query) {
+    return this.hasImageTransformations(query) || this.hasVideoTransformations(query) || this.hasAudioTransformations(query);
+  }
+  /**
+   * Creates a MediaTransformResult from a stored transformed file.
+   * @param storedFile The stored transformed file.
+   * @param mediaType The media type (image, video, audio).
+   * @param originalFile The original file information.
+   * @returns Media transformation result with metadata.
+   * @private
+   */
+  createMediaTransformResult(storedFile, mediaType, originalFile) {
+    const baseResult = {
+      buffer: storedFile.content,
+      format: this.getFormatFromContentType(storedFile.contentType || ""),
+      mediaType,
+      originalFile,
+      size: storedFile.content.length
+    };
+    switch (mediaType) {
+      case "audio": {
+        return {
+          ...baseResult,
+          bitrate: storedFile.bitrate,
+          duration: storedFile.duration,
+          mediaType: "audio",
+          numberOfChannels: storedFile.numberOfChannels,
+          sampleRate: storedFile.sampleRate
+        };
+      }
+      case "image": {
+        return {
+          ...baseResult,
+          height: storedFile.height,
+          mediaType: "image",
+          width: storedFile.width
+        };
+      }
+      case "video": {
+        return {
+          ...baseResult,
+          bitrate: storedFile.bitrate,
+          duration: storedFile.duration,
+          height: storedFile.height,
+          mediaType: "video",
+          width: storedFile.width
+        };
+      }
+      default: {
+        return baseResult;
+      }
+    }
+  }
+  /**
+   * Extracts format from content type.
+   * @param contentType MIME content type string.
+   * @returns Format string extracted from content type.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  getFormatFromContentType(contentType) {
+    if (!contentType) {
+      return "";
+    }
+    const extension = mime.getExtension(contentType);
+    return extension || "application/octet-stream";
+  }
+  /**
+   * Saves transformed file to storage.
+   * @param result The transformation result to save.
+   * @param originalFileId The original file identifier.
+   * @param query The transformation query parameters.
+   * @param mediaType The media type (image, video, audio).
+   * @returns Promise that resolves when file is saved.
+   * @private
+   */
+  async saveTransformedFile(result, originalFileId, query, mediaType) {
+    try {
+      const transformedFileId = this.generateTransformedFileId(originalFileId, query, mediaType);
+      const metadata = {
+        format: result.format,
+        mediaType,
+        originalFileId,
+        size: result.size,
+        transformation: query,
+        transformedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      if (mediaType === "image" && result.width && result.height) {
+        metadata.width = result.width;
+        metadata.height = result.height;
+      } else if (mediaType === "video" && result.width && result.height) {
+        metadata.width = result.width;
+        metadata.height = result.height;
+        metadata.duration = result.duration;
+        metadata.bitrate = result.bitrate;
+      } else if (mediaType === "audio") {
+        metadata.duration = result.duration;
+        metadata.numberOfChannels = result.numberOfChannels;
+        metadata.sampleRate = result.sampleRate;
+        metadata.bitrate = result.bitrate;
+      }
+      await this.storage.create({
+        contentType: mime.getType(result.format) ?? void 0,
+        metadata,
+        originalName: `${transformedFileId}.${result.format}`,
+        size: result.size
+      });
+      this.logger?.debug?.(`Saved transformed file: ${transformedFileId}`);
+    } catch (error) {
+      this.logger?.error?.(`Failed to save transformed file: ${error}`);
+    }
+  }
+  /**
+   * Validates query parameters for audio transformations. Checks for invalid video-only parameters, invalid codecs, invalid formats, and invalid numeric values.
+   * @param query Query parameters to validate.
+   * @throws {ValidationError} When validation fails.
+   */
+  // eslint-disable-next-line class-methods-use-this
+  validateAudioQueryParameters(query) {
+    const allowedParameters = /* @__PURE__ */ new Set(["bitrate", "codec", "format", "numberOfChannels", "quality", "sampleRate"]);
+    const videoOnlyParameters = /* @__PURE__ */ new Set([
+      "angle",
+      "background",
+      "cropHeight",
+      "cropWidth",
+      "fit",
+      "frameRate",
+      "height",
+      "keyFrameInterval",
+      "left",
+      "position",
+      "top",
+      "width",
+      "withoutEnlargement",
+      "withoutReduction"
+    ]);
+    const invalidParameters = [];
+    for (const parameter of videoOnlyParameters) {
+      if (query[parameter] !== void 0) {
+        invalidParameters.push(parameter);
+      }
+    }
+    if (invalidParameters.length > 0) {
+      const sortedInvalidParameters = [...invalidParameters].toSorted();
+      throw new ValidationError(
+        `Invalid query parameters for audio transformation: ${sortedInvalidParameters.join(", ")}. Audio supports: ${[...allowedParameters].toSorted().join(", ")}. Video-only parameters (${sortedInvalidParameters.join(", ")}) are not supported for audio.`,
+        "INVALID_PARAMS_FOR_AUDIO",
+        "audio",
+        sortedInvalidParameters,
+        [...allowedParameters].toSorted()
+      );
+    }
+    if (query.codec && !["aac", "flac", "mp3", "opus", "vorbis"].includes(query.codec)) {
+      throw new ValidationError(
+        `Invalid codec for audio: "${query.codec}". Supported codecs: aac, opus, mp3, vorbis, flac`,
+        "INVALID_AUDIO_CODEC",
+        "audio",
+        ["codec"],
+        ["aac", "opus", "mp3", "vorbis", "flac"]
+      );
+    }
+    if (query.format && !["aac", "flac", "mp3", "ogg", "wav"].includes(query.format)) {
+      throw new ValidationError(
+        `Invalid format for audio: "${query.format}". Supported formats: mp3, wav, ogg, aac, flac`,
+        "INVALID_AUDIO_FORMAT",
+        "audio",
+        ["format"],
+        ["mp3", "wav", "ogg", "aac", "flac"]
+      );
+    }
+    if (query.bitrate !== void 0 && (typeof query.bitrate !== "number" || query.bitrate <= 0)) {
+      throw new ValidationError(`Invalid bitrate: ${query.bitrate}. Must be a positive number.`, "INVALID_BITRATE", "audio", ["bitrate"], []);
+    }
+    if (query.numberOfChannels !== void 0 && (typeof query.numberOfChannels !== "number" || query.numberOfChannels <= 0 || query.numberOfChannels > 8)) {
+      throw new ValidationError(
+        `Invalid numberOfChannels: ${query.numberOfChannels}. Must be a number between 1 and 8.`,
+        "INVALID_CHANNEL_COUNT",
+        "audio",
+        ["numberOfChannels"],
+        ["1", "2", "3", "4", "5", "6", "7", "8"]
+      );
+    }
+    if (query.sampleRate !== void 0) {
+      const validSampleRates = [8e3, 11025, 16e3, 22050, 32e3, 44100, 48e3, 88200, 96e3, 192e3];
+      if (typeof query.sampleRate !== "number" || !validSampleRates.includes(query.sampleRate)) {
+        throw new ValidationError(
+          `Invalid sampleRate: ${query.sampleRate}. Supported sample rates: ${validSampleRates.join(", ")}`,
+          "INVALID_SAMPLE_RATE",
+          "audio",
+          ["sampleRate"],
+          validSampleRates.map(String)
+        );
+      }
+    }
+  }
+  /**
+   * Handles image transformation.
+   * @param fileId The file identifier.
+   * @param query The transformation query parameters.
+   * @returns Promise resolving to media transformation result.
+   * @private
+   */
+  async handleImageTransformation(fileId, query) {
+    const steps = [];
+    if (this.hasImageTransformations(query)) {
+      if (query.width || query.height || query.fit) {
+        steps.push({
+          options: {
+            fit: query.fit,
+            height: query.height,
+            position: query.position,
+            width: query.width,
+            withoutEnlargement: query.withoutEnlargement,
+            withoutReduction: query.withoutReduction
+          },
+          type: "resize"
+        });
+      }
+      if (query.left !== void 0 && query.top !== void 0 && query.cropWidth && query.cropHeight) {
+        steps.push({
+          options: {
+            height: query.cropHeight,
+            left: query.left,
+            top: query.top,
+            width: query.cropWidth
+          },
+          type: "crop"
+        });
+      }
+      if (query.angle) {
+        steps.push({
+          options: {
+            angle: query.angle,
+            background: query.background
+          },
+          type: "rotate"
+        });
+      }
+      if (query.format) {
+        steps.push({
+          options: {
+            format: query.format,
+            quality: query.quality
+          },
+          type: "format"
+        });
+      } else if (query.quality) {
+        steps.push({
+          options: {
+            quality: query.quality
+          },
+          type: "quality"
+        });
+      }
+    }
+    const result = steps.length > 0 ? await this.imageTransformer.transform(fileId, steps) : await this.imageTransformer.transform(fileId, []);
+    return this.convertImageResult(result);
+  }
+  /**
+   * Handles video transformation.
+   * @param fileId The file identifier.
+   * @param query The transformation query parameters.
+   * @returns Promise resolving to media transformation result.
+   * @private
+   */
+  async handleVideoTransformation(fileId, query) {
+    const steps = [];
+    if (this.hasVideoTransformations(query)) {
+      if (query.width || query.height || query.fit) {
+        steps.push({
+          options: {
+            fit: query.fit,
+            height: query.height,
+            position: query.position,
+            width: query.width,
+            withoutEnlargement: query.withoutEnlargement,
+            withoutReduction: query.withoutReduction
+          },
+          type: "resize"
+        });
+      }
+      if (query.left !== void 0 && query.top !== void 0 && query.cropWidth && query.cropHeight) {
+        steps.push({
+          options: {
+            height: Number(query.cropHeight),
+            left: query.left,
+            top: query.top,
+            width: query.cropWidth
+          },
+          type: "crop"
+        });
+      }
+      if (query.angle) {
+        steps.push({
+          options: {
+            angle: query.angle,
+            background: query.background
+          },
+          type: "rotate"
+        });
+      }
+      if (query.codec || query.bitrate) {
+        steps.push({
+          options: {
+            bitrate: query.bitrate || query.quality,
+            codec: query.codec,
+            frameRate: query.frameRate,
+            keyFrameInterval: query.keyFrameInterval
+          },
+          type: "codec"
+        });
+      }
+      if (query.format) {
+        steps.push({
+          options: {
+            format: query.format
+          },
+          type: "format"
+        });
+      }
+    }
+    const result = steps.length > 0 ? await this.videoTransformer.transform(fileId, steps) : await this.videoTransformer.transform(fileId, []);
+    return this.convertVideoResult(result);
+  }
+  /**
+   * Handles audio transformation.
+   * @param fileId The file identifier.
+   * @param query The transformation query parameters.
+   * @returns Promise resolving to media transformation result.
+   * @private
+   */
+  async handleAudioTransformation(fileId, query) {
+    const steps = [];
+    if (this.hasAudioTransformations(query)) {
+      if (query.sampleRate) {
+        steps.push({
+          options: {
+            sampleRate: query.sampleRate
+          },
+          type: "resample"
+        });
+      }
+      if (query.numberOfChannels) {
+        steps.push({
+          options: {
+            numberOfChannels: query.numberOfChannels
+          },
+          type: "channels"
+        });
+      }
+      if (query.codec || query.bitrate) {
+        steps.push({
+          options: {
+            bitrate: query.bitrate || query.quality,
+            codec: query.codec
+          },
+          type: "codec"
+        });
+      }
+      if (query.format) {
+        steps.push({
+          options: {
+            format: query.format
+          },
+          type: "format"
+        });
+      }
+    }
+    const result = steps.length > 0 ? await this.audioTransformer.transform(fileId, steps) : await this.audioTransformer.transform(fileId, []);
+    return this.convertAudioResult(result);
+  }
+  /**
+   * Parses query parameters from various input formats.
+   * @param query Query parameters in various formats.
+   * @returns Normalized MediaTransformQuery object.
+   * @private
+   */
+  parseQuery(query) {
+    if (typeof query === "string") {
+      return this.parseURLSearchParams(new URLSearchParams(query));
+    }
+    if (query instanceof URLSearchParams) {
+      return this.parseURLSearchParams(query);
+    }
+    const transformQuery = query;
+    if (query.left) {
+      transformQuery.left = Number.parseInt(query.left, 10);
+    }
+    if (query.top) {
+      transformQuery.top = Number.parseInt(query.top, 10);
+    }
+    if (query.cropWidth) {
+      transformQuery.cropWidth = Number.parseInt(query.cropWidth, 10);
+    }
+    if (query.cropHeight) {
+      transformQuery.cropHeight = Number.parseInt(query.cropHeight, 10);
+    }
+    if (query.angle) {
+      transformQuery.angle = Number.parseInt(query.angle, 10);
+    }
+    if (query.quality) {
+      transformQuery.quality = Number.parseInt(query.quality, 10);
+    }
+    if (query.width) {
+      transformQuery.width = Number.parseInt(query.width, 10);
+    }
+    if (query.height) {
+      transformQuery.height = Number.parseInt(query.height, 10);
+    }
+    if (query.bitrate) {
+      transformQuery.bitrate = Number.parseInt(query.bitrate, 10);
+    }
+    if (query.frameRate) {
+      transformQuery.frameRate = Number.parseInt(query.frameRate, 10);
+    }
+    if (query.keyFrameInterval) {
+      transformQuery.keyFrameInterval = Number.parseInt(query.keyFrameInterval, 10);
+    }
+    if (query.numberOfChannels) {
+      transformQuery.numberOfChannels = Number.parseInt(query.numberOfChannels, 10);
+    }
+    if (query.sampleRate) {
+      transformQuery.sampleRate = Number.parseInt(query.sampleRate, 10);
+    }
+    return transformQuery;
+  }
+  /**
+   * Parses boolean parameter from string.
+   * @param value String value to parse.
+   * @returns Boolean value or undefined.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  parseBooleanParameter(value) {
+    if (value === null) {
+      return void 0;
+    }
+    return value === "true" || value === "1";
+  }
+  /**
+   * Parses URLSearchParams into MediaTransformQuery.
+   * @param parameters URL search parameters object.
+   * @returns MediaTransformQuery object with parsed parameters.
+   * @private
+   */
+  parseURLSearchParams(parameters) {
+    const query = {};
+    if (parameters.has("format")) {
+      query.format = parameters.get("format") ?? void 0;
+    }
+    if (parameters.has("quality")) {
+      query.quality = parameters.get("quality") ? Number.parseInt(parameters.get("quality"), 10) : void 0;
+    }
+    if (parameters.has("width")) {
+      query.width = parameters.get("width") ? Number.parseInt(parameters.get("width"), 10) : void 0;
+    }
+    if (parameters.has("height")) {
+      query.height = parameters.get("height") ? Number.parseInt(parameters.get("height"), 10) : void 0;
+    }
+    if (parameters.has("fit")) {
+      const fitValue = parameters.get("fit");
+      if (fitValue && ["contain", "cover", "fill", "inside", "outside"].includes(fitValue)) {
+        query.fit = fitValue;
+      }
+    }
+    if (parameters.has("position")) {
+      query.position = parameters.get("position") ?? void 0;
+    }
+    if (parameters.has("withoutEnlargement")) {
+      const value = parameters.get("withoutEnlargement");
+      query.withoutEnlargement = value === "true" ? true : void 0;
+    }
+    if (parameters.has("withoutReduction")) {
+      const value = parameters.get("withoutReduction");
+      query.withoutReduction = value === "true" ? true : void 0;
+    }
+    if (parameters.has("left")) {
+      query.left = parameters.get("left") ? Number.parseInt(parameters.get("left"), 10) : void 0;
+    }
+    if (parameters.has("top")) {
+      query.top = parameters.get("top") ? Number.parseInt(parameters.get("top"), 10) : void 0;
+    }
+    if (parameters.has("cropWidth")) {
+      query.cropWidth = parameters.get("cropWidth") ? Number.parseInt(parameters.get("cropWidth"), 10) : void 0;
+    }
+    if (parameters.has("cropHeight")) {
+      query.cropHeight = parameters.get("cropHeight") ? Number.parseInt(parameters.get("cropHeight"), 10) : void 0;
+    }
+    if (parameters.has("angle")) {
+      const angleValue = parameters.get("angle") ? Number.parseInt(parameters.get("angle"), 10) : void 0;
+      if (angleValue !== void 0) {
+        query.angle = angleValue;
+      }
+    }
+    if (parameters.has("background")) {
+      query.background = parameters.get("background") ?? void 0;
+    }
+    if (parameters.has("blur")) {
+      query.blur = this.parseBooleanParameter(parameters.get("blur"));
+    }
+    if (parameters.has("sharpen")) {
+      query.sharpen = this.parseBooleanParameter(parameters.get("sharpen"));
+    }
+    if (parameters.has("median")) {
+      query.median = parameters.get("median") ? Number.parseInt(parameters.get("median"), 10) : void 0;
+    }
+    if (parameters.has("clahe")) {
+      query.clahe = this.parseBooleanParameter(parameters.get("clahe"));
+    }
+    if (parameters.has("threshold")) {
+      query.threshold = parameters.get("threshold") ? Number.parseInt(parameters.get("threshold"), 10) : void 0;
+    }
+    if (parameters.has("gamma")) {
+      query.gamma = this.parseBooleanParameter(parameters.get("gamma"));
+    }
+    if (parameters.has("negate")) {
+      query.negate = this.parseBooleanParameter(parameters.get("negate"));
+    }
+    if (parameters.has("normalise") || parameters.has("normalize")) {
+      query.normalise = this.parseBooleanParameter(parameters.get("normalise")) || this.parseBooleanParameter(parameters.get("normalize"));
+    }
+    if (parameters.has("flatten")) {
+      query.flatten = this.parseBooleanParameter(parameters.get("flatten"));
+    }
+    if (parameters.has("unflatten")) {
+      query.unflatten = this.parseBooleanParameter(parameters.get("unflatten"));
+    }
+    if (parameters.has("flip")) {
+      query.flip = this.parseBooleanParameter(parameters.get("flip"));
+    }
+    if (parameters.has("flop")) {
+      query.flop = this.parseBooleanParameter(parameters.get("flop"));
+    }
+    if (parameters.has("affine")) {
+      query.affine = this.parseBooleanParameter(parameters.get("affine"));
+    }
+    if (parameters.has("dilate")) {
+      query.dilate = this.parseBooleanParameter(parameters.get("dilate"));
+    }
+    if (parameters.has("erode")) {
+      query.erode = this.parseBooleanParameter(parameters.get("erode"));
+    }
+    if (parameters.has("pipelineColourspace")) {
+      query.pipelineColourspace = this.parseBooleanParameter(parameters.get("pipelineColourspace"));
+    }
+    if (parameters.has("toColourspace")) {
+      query.toColourspace = this.parseBooleanParameter(parameters.get("toColourspace"));
+    }
+    if (parameters.has("removeAlpha")) {
+      query.removeAlpha = this.parseBooleanParameter(parameters.get("removeAlpha"));
+    }
+    if (parameters.has("ensureAlpha")) {
+      query.ensureAlpha = this.parseBooleanParameter(parameters.get("ensureAlpha"));
+    }
+    if (parameters.has("greyscale") || parameters.has("grayscale")) {
+      query.greyscale = this.parseBooleanParameter(parameters.get("greyscale")) || this.parseBooleanParameter(parameters.get("grayscale"));
+    }
+    if (parameters.has("modulate")) {
+      query.modulate = this.parseBooleanParameter(parameters.get("modulate"));
+    }
+    if (parameters.has("tint")) {
+      query.tint = this.parseBooleanParameter(parameters.get("tint"));
+    }
+    if (parameters.has("brightness")) {
+      query.brightness = parameters.get("brightness") ? Number.parseFloat(parameters.get("brightness")) : void 0;
+    }
+    if (parameters.has("saturation")) {
+      query.saturation = parameters.get("saturation") ? Number.parseFloat(parameters.get("saturation")) : void 0;
+    }
+    if (parameters.has("hue")) {
+      query.hue = parameters.get("hue") ? Number.parseInt(parameters.get("hue"), 10) : void 0;
+    }
+    if (parameters.has("lightness")) {
+      query.lightness = parameters.get("lightness") ? Number.parseInt(parameters.get("lightness"), 10) : void 0;
+    }
+    if (parameters.has("kernel")) {
+      query.kernel = parameters.get("kernel") ?? void 0;
+    }
+    if (parameters.has("fastShrinkOnLoad")) {
+      query.fastShrinkOnLoad = parameters.get("fastShrinkOnLoad") === "true";
+    }
+    if (parameters.has("codec")) {
+      const codecValue = parameters.get("codec");
+      const validCodecs = ["avc", "hevc", "vp8", "vp9", "av1", "aac", "opus", "mp3", "vorbis", "flac"];
+      if (codecValue && validCodecs.includes(codecValue)) {
+        query.codec = codecValue;
+      }
+    }
+    if (parameters.has("bitrate")) {
+      query.bitrate = parameters.get("bitrate") ? Number.parseInt(parameters.get("bitrate"), 10) : void 0;
+    }
+    if (parameters.has("frameRate")) {
+      query.frameRate = parameters.get("frameRate") ? Number.parseInt(parameters.get("frameRate"), 10) : void 0;
+    }
+    if (parameters.has("keyFrameInterval")) {
+      query.keyFrameInterval = parameters.get("keyFrameInterval") ? Number.parseInt(parameters.get("keyFrameInterval"), 10) : void 0;
+    }
+    if (parameters.has("numberOfChannels")) {
+      query.numberOfChannels = parameters.get("numberOfChannels") ? Number.parseInt(parameters.get("numberOfChannels"), 10) : void 0;
+    }
+    if (parameters.has("sampleRate")) {
+      query.sampleRate = parameters.get("sampleRate") ? Number.parseInt(parameters.get("sampleRate"), 10) : void 0;
+    }
+    return query;
+  }
+  /**
+   * Detects media type from MIME type.
+   * @param contentType MIME content type string.
+   * @returns Detected media type.
+   * @throws Error if content type is missing or unsupported.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  detectMediaType(contentType) {
+    if (!contentType) {
+      throw new Error("Cannot detect media type: no content type provided");
+    }
+    if (!isKnownContentType(contentType)) {
+      throw new Error(`Unknown or invalid content type: ${contentType}`);
+    }
+    if (contentType.startsWith("image/")) {
+      return "image";
+    }
+    if (contentType.startsWith("video/")) {
+      return "video";
+    }
+    if (contentType.startsWith("audio/")) {
+      return "audio";
+    }
+    throw new Error(`Unsupported media type for content type: ${contentType}`);
+  }
+  /**
+   * Checks if query has image transformations.
+   * @param query The transformation query parameters.
+   * @returns True if image transformations are requested.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  hasImageTransformations(query) {
+    return !!(query.width || query.height || query.fit || query.position || query.withoutEnlargement || query.withoutReduction || query.left !== void 0 || query.top !== void 0 || query.cropWidth || query.cropHeight || query.angle !== void 0 || query.background || query.blur || query.sharpen || query.median || query.clahe || query.threshold !== void 0 || query.gamma || query.negate || query.normalise || query.flatten || query.unflatten || query.flip || query.flop || query.greyscale || query.modulate || query.tint || query.brightness !== void 0 || query.saturation !== void 0 || query.hue !== void 0 || query.lightness !== void 0 || query.kernel || query.fastShrinkOnLoad || query.affine || query.dilate || query.erode || query.pipelineColourspace || query.toColourspace || query.removeAlpha || query.ensureAlpha || query.format || query.quality);
+  }
+  /**
+   * Checks if query has video transformations.
+   * @param query The transformation query parameters.
+   * @returns True if video transformations are requested.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  hasVideoTransformations(query) {
+    return !!(query.width || query.height || query.fit || query.position || query.withoutEnlargement || query.withoutReduction || query.left !== void 0 || query.top !== void 0 || query.cropWidth || query.cropHeight || query.angle || query.background || query.codec || query.bitrate || query.frameRate || query.keyFrameInterval || query.format || query.quality);
+  }
+  /**
+   * Checks if query has audio transformations.
+   * @param query The transformation query parameters.
+   * @returns True if audio transformations are requested.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  hasAudioTransformations(query) {
+    return !!(query.sampleRate || query.numberOfChannels || query.codec || query.bitrate || query.format || query.quality);
+  }
+  /**
+   * Converts ImageTransformer result to unified format.
+   * @param result The image transformation result.
+   * @returns Unified media transformation result.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  convertImageResult(result) {
+    return {
+      buffer: result.buffer,
+      format: result.format,
+      height: result.height,
+      mediaType: "image",
+      originalFile: result.originalFile,
+      size: result.size,
+      width: result.width
+    };
+  }
+  /**
+   * Converts VideoTransformer result to unified format.
+   * @param result The video transformation result.
+   * @returns Unified media transformation result.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  convertVideoResult(result) {
+    return {
+      bitrate: result.bitrate,
+      buffer: result.buffer,
+      duration: result.duration,
+      format: result.format,
+      height: result.height,
+      mediaType: "video",
+      originalFile: result.originalFile,
+      size: result.size,
+      width: result.width
+    };
+  }
+  /**
+   * Converts AudioTransformer result to unified format.
+   * @param result The audio transformation result.
+   * @returns Unified media transformation result.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  convertAudioResult(result) {
+    return {
+      bitrate: result.bitrate,
+      buffer: result.buffer,
+      duration: result.duration,
+      format: result.format,
+      mediaType: "audio",
+      numberOfChannels: result.numberOfChannels,
+      originalFile: result.originalFile,
+      sampleRate: result.sampleRate,
+      size: result.size
+    };
+  }
+}
+
+export { MediaTransformer as default };