@visulima/storage 1.0.0-alpha.9 → 1.0.0

package/dist/transformer/media-transformer.d.ts

@@ -1,332 +0,0 @@
-import type { BaseStorage } from "../storage/storage.d.ts";
-import type { File, FileReturn } from "../storage/utils/index.d.ts";
-import type { MediaTransformerConfig, MediaTransformResult } from "./types.d.ts";
-/**
- * Unified media transformer that automatically detects media type and routes to appropriate transformer.
- * @template TFile The file type used by this transformer.
- * @template TFileReturn The return type for file retrieval operations.
- *
- * Supports transformations via query parameters for on-demand media processing across all supported formats.
- * @example
- * // eslint-disable-next-line jsdoc/match-description
- * ```ts
- * const transformer = new MediaTransformer(storage, {
- *   maxImageSize: 10 * 1024 * 1024, // 10MB
- *   maxVideoSize: 100 * 1024 * 1024, // 100MB
- *   maxAudioSize: 50 * 1024 * 1024, // 50MB
- *   cache: new MapCache(), // In-memory caching
- *   saveTransformedFiles: true // Persist transformed files to storage
- * });
- *
- * // Handle transformation via query parameters
- * const result = await transformer.handle('file-id', {
- *   width: 800,
- *   height: 600,
- *   fit: 'cover',
- *   format: 'webp',
- *   quality: 80
- * });
- *
- * // Fetch with URL query string
- * const result = await transformer.fetch('file-id', 'width=1280&height=720&codec=avc&bitrate=2000000');
- *
- * // Clear all cached transformed files
- * transformer.clearSavedTransformedFiles();
- * ```
- *
- * ## Configuration Options
- *
- * - `saveTransformedFiles`: Persist transformed files to storage for reuse (default: false)
- * - `cache`: Cache instance for in-memory caching (optional)
- * - `maxImageSize/maxVideoSize/maxAudioSize`: Size limits for processing
- * - `cacheTtl`: Cache time-to-live in seconds
- *
- * ## Supported Query Parameters
- *
- * ### Common Parameters
- * - `format`: Output format (jpeg/png/webp/avif/mp4/webm/mkv/mp3/wav/ogg/aac/flac)
- * - `quality`: Quality for images (0-100), bitrate for video/audio
- *
- * ### Image Parameters
- * - `width`: Width in pixels
- * - `height`: Height in pixels
- * - `fit`: Resize fit mode - cover/contain/fill/inside/outside
- * - `position`: Position for cover/contain fits
- * - `withoutEnlargement`: Avoid enlarging smaller images (boolean)
- * - `withoutReduction`: Avoid reducing larger images (boolean)
- * - `kernel`: Resize kernel - nearest/cubic/mitchell/lanczos2/lanczos3
- * - `fastShrinkOnLoad`: Fast shrink on load (boolean)
- * - `left/top/cropWidth/cropHeight`: Crop parameters
- * - `angle`: Rotation angle in degrees (any number, but angles other than 90°/180°/270° use interpolation and may affect quality)
- * - `background`: Background color for rotation
- * - `blur`: Apply blur effect (boolean)
- * - `sharpen`: Apply sharpening (boolean)
- * - `median`: Apply median filter with size (number)
- * // eslint-disable-next-line jsdoc/match-description
- * - `clahe`: Apply CLAHE (Contrast Limited Adaptive Histogram Equalization) (boolean)
- * - `threshold`: Apply thresholding with value (0-255)
- * - `gamma`: Apply gamma correction (boolean)
- * - `negate`: Negate (invert) the image (boolean)
- * - `normalise/normalize`: Normalise the image (boolean)
- * - `flatten`: Flatten alpha channel (boolean)
- * - `unflatten`: Unflatten alpha channel (boolean)
- * - `flip`: Flip image vertically (boolean)
- * - `flop`: Flop image horizontally (boolean)
- * - `greyscale/grayscale`: Convert to greyscale (boolean)
- * - `modulate`: Apply modulation effects (boolean)
- * - `brightness`: Brightness multiplier for modulation (number)
- * - `saturation`: Saturation multiplier for modulation (number)
- * - `hue`: Hue rotation in degrees for modulation (number)
- * // eslint-disable-next-line jsdoc/match-description
- * - `lightness`: Lightness adjustment for modulation (number)
- * - `tint`: Apply tinting (boolean)
- * - `colourspace`: Convert colourspace - srgb/rgb/cmyk/lab/b-w
- *
- * ### Video Parameters
- * - `width/height/fit`: Same as images
- * - `codec`: Video codec - avc/hevc/vp8/vp9/av1
- * - `bitrate`: Video bitrate in bits per second
- * - `frameRate`: Frame rate in Hz
- * - `keyFrameInterval`: Key frame interval in seconds
- * - `angle`: Rotation angle in degrees (any number, but angles other than 90°/180°/270° use interpolation and may affect quality)
- * - `background`: Background color for rotation
- *
- * ### Audio Parameters
- * - `sampleRate`: Sample rate in Hz
- * - `numberOfChannels`: Number of channels
- * - `codec`: Audio codec - aac/opus/mp3/vorbis/flac
- * - `bitrate`: Audio bitrate in bits per second
- *
- * ## File Persistence
- *
- * When `saveTransformedFiles` is enabled, transformed files are automatically saved to storage
- * with deterministic IDs based on the original file and transformation parameters. Subsequent
- * requests for the same transformation will serve the cached file directly, improving performance
- * and reducing processing costs.
- */
-declare class MediaTransformer<TFile extends File = File, TFileReturn extends FileReturn = FileReturn> {
-    private readonly storage;
-    private readonly imageTransformer?;
-    private readonly videoTransformer?;
-    private readonly audioTransformer?;
-    private readonly config;
-    private readonly logger;
-    /**
-     * 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: BaseStorage<TFile, TFileReturn>, config?: MediaTransformerConfig<TFile, TFileReturn>);
-    supportedFormats(): string[];
-    /**
-     * Handles media transformation based on query parameters.
-     * @param fileId File identifier.
-     * @param query Query parameters for transformation.
-     * @returns Unified transformation result.
-     */
-    handle(fileId: string, query: Record<string, string | undefined> | URLSearchParams | string): Promise<MediaTransformResult>;
-    /**
-     * Fetches media transformation with URL query string support.
-     * @param fileId File identifier.
-     * @param queryString URL query string (e.g., "width=800&amp;height=600&amp;format=webp").
-     * @returns Unified transformation result.
-     */
-    fetch(fileId: string, queryString: string): Promise<MediaTransformResult>;
-    /**
-     * 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?: string): void;
-    /**
-     * Clears all saved transformed files from storage.
-     * @remarks This is a maintenance operation and may take time for large numbers of files.
-     */
-    clearSavedTransformedFiles(): Promise<void>;
-    /**
-     * Clears saved transformed files for a specific original file.
-     * @param originalFileId Original file identifier to clear transformed files for.
-     */
-    clearSavedTransformedFilesForFile(originalFileId: string): Promise<void>;
-    /**
-     * Gets cache statistics (combined from all transformers).
-     * @returns Cache statistics for audio, image, and video transformers.
-     */
-    getCacheStats(): {
-        audio?: {
-            maxSize: number;
-            size: number;
-        };
-        image?: {
-            maxSize: number;
-            size: number;
-        };
-        video?: {
-            maxSize: number;
-            size: number;
-        };
-    };
-    /**
-     * 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.
-     */
-    private validateQueryParameters;
-    /**
-     * 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.
-     */
-    private validateImageQueryParameters;
-    /**
-     * 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.
-     */
-    private validateVideoQueryParameters;
-    /**
-     * 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
-     */
-    private generateTransformedFileId;
-    /**
-     * Checks if the query contains any transformations.
-     * @param query The transformation query parameters.
-     * @returns True if any transformations are requested.
-     * @private
-     */
-    private hasTransformations;
-    /**
-     * 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
-     */
-    private createMediaTransformResult;
-    /**
-     * Extracts format from content type.
-     * @param contentType MIME content type string.
-     * @returns Format string extracted from content type.
-     * @private
-     */
-    private getFormatFromContentType;
-    /**
-     * 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
-     */
-    private saveTransformedFile;
-    /**
-     * 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.
-     */
-    private validateAudioQueryParameters;
-    /**
-     * Handles image transformation.
-     * @param fileId The file identifier.
-     * @param query The transformation query parameters.
-     * @returns Promise resolving to media transformation result.
-     * @private
-     */
-    private handleImageTransformation;
-    /**
-     * Handles video transformation.
-     * @param fileId The file identifier.
-     * @param query The transformation query parameters.
-     * @returns Promise resolving to media transformation result.
-     * @private
-     */
-    private handleVideoTransformation;
-    /**
-     * Handles audio transformation.
-     * @param fileId The file identifier.
-     * @param query The transformation query parameters.
-     * @returns Promise resolving to media transformation result.
-     * @private
-     */
-    private handleAudioTransformation;
-    /**
-     * Parses query parameters from various input formats.
-     * @param query Query parameters in various formats.
-     * @returns Normalized MediaTransformQuery object.
-     * @private
-     */
-    private parseQuery;
-    /**
-     * Parses boolean parameter from string.
-     * @param value String value to parse.
-     * @returns Boolean value or undefined.
-     * @private
-     */
-    private parseBooleanParameter;
-    /**
-     * Parses URLSearchParams into MediaTransformQuery.
-     * @param parameters URL search parameters object.
-     * @returns MediaTransformQuery object with parsed parameters.
-     * @private
-     */
-    private parseURLSearchParams;
-    /**
-     * 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
-     */
-    private detectMediaType;
-    /**
-     * Checks if query has image transformations.
-     * @param query The transformation query parameters.
-     * @returns True if image transformations are requested.
-     * @private
-     */
-    private hasImageTransformations;
-    /**
-     * Checks if query has video transformations.
-     * @param query The transformation query parameters.
-     * @returns True if video transformations are requested.
-     * @private
-     */
-    private hasVideoTransformations;
-    /**
-     * Checks if query has audio transformations.
-     * @param query The transformation query parameters.
-     * @returns True if audio transformations are requested.
-     * @private
-     */
-    private hasAudioTransformations;
-    /**
-     * Converts ImageTransformer result to unified format.
-     * @param result The image transformation result.
-     * @returns Unified media transformation result.
-     * @private
-     */
-    private convertImageResult;
-    /**
-     * Converts VideoTransformer result to unified format.
-     * @param result The video transformation result.
-     * @returns Unified media transformation result.
-     * @private
-     */
-    private convertVideoResult;
-    /**
-     * Converts AudioTransformer result to unified format.
-     * @param result The audio transformation result.
-     * @returns Unified media transformation result.
-     * @private
-     */
-    private convertAudioResult;
-}
-export default MediaTransformer;