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

package/dist/storage/utils/file/types.d.ts

@@ -0,0 +1,37 @@
+import type { Readable } from "node:stream";
+import type { Metadata } from "./metadata.d.ts";
+export interface FileInit {
+    contentType?: string;
+    expiredAt?: Date | number | string;
+    metadata: Metadata;
+    originalName?: string;
+    size?: number | string;
+    storageClass?: string;
+    ttl?: number | string;
+}
+export interface FileReturn extends Omit<Required<FileInit>, "storageClass" | "ttl" | "expiredAt"> {
+    content: Buffer;
+    ETag?: string;
+    expiredAt?: Date | number | string;
+    id: string;
+    modifiedAt?: Date | number | string;
+    name: string;
+    storageClass?: string;
+}
+type UploadEventTypeValue = "completed" | "created" | "deleted" | "part" | "updated";
+export type UploadEventType = UploadEventTypeValue;
+export interface FileQuery {
+    id: string;
+    name?: string;
+    size?: number;
+}
+export interface Checksum {
+    checksum?: string;
+    checksumAlgorithm?: string;
+}
+export interface FilePart extends Checksum, FileQuery {
+    body: Readable;
+    contentLength?: number;
+    start: number;
+}
+export {};

package/dist/storage/utils/file/update-metadata.d.ts

@@ -0,0 +1,10 @@
+import type File from "./file.d.ts";
+/**
+ * Updates a file object with new metadata using deep merge.
+ * Also updates the originalName based on the merged metadata.
+ * @param file File object to update
+ * @param metadata Partial metadata to merge into the file
+ * @template T - File type extending base File class
+ */
+declare const updateMetadata: <T extends File>(file: T, metadata: Partial<T>) => void;
+export default updateMetadata;

package/dist/storage/utils/file/update-size.d.ts

@@ -0,0 +1,10 @@
+import type File from "./file.d.ts";
+/**
+ * Updates a file's size, but only if the new size is smaller than the current size.
+ * This prevents accidental size increases that could indicate data corruption.
+ * @param file File object to update
+ * @param size New size value
+ * @returns The updated file object
+ */
+declare const updateSize: (file: File, size: number) => File;
+export default updateSize;

package/dist/storage/vercel-blob/index.d.ts

@@ -0,0 +1,4 @@
+export type { VercelBlobStorageOptions } from "./types.d.ts";
+export { default as VercelBlobFile } from "./vercel-blob-file.d.ts";
+export { default as VercelBlobMetaStorage } from "./vercel-blob-meta-storage.d.ts";
+export { default as VercelBlobStorage } from "./vercel-blob-storage.d.ts";

package/dist/storage/vercel-blob/index.js

@@ -0,0 +1,3 @@
+export { default as VercelBlobFile } from '../../packem_shared/VercelBlobFile-BCg4aTEq.js';
+export { default as VercelBlobMetaStorage } from '../../packem_shared/VercelBlobMetaStorage-Bd9F-VFm.js';
+export { default as VercelBlobStorage } from '../../packem_shared/VercelBlobStorage-DD9LMOS6.js';

package/dist/storage/vercel-blob/types.d.ts

@@ -0,0 +1,32 @@
+import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
+import type { BaseStorageOptions } from "../types.d.ts";
+import type VercelBlobFile from "./vercel-blob-file.d.ts";
+export interface VercelBlobStorageOptions extends BaseStorageOptions<VercelBlobFile> {
+    /**
+     * Configure metafiles storage
+     * @example
+     * Using local metafiles
+     * ```ts
+     * const storage = new VercelBlobStorage({
+     *   token: process.env.BLOB_READ_WRITE_TOKEN,
+     *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
+     * })
+     * ```
+     */
+    metaStorageConfig?: LocalMetaStorageOptions;
+    /**
+     * Enable multipart uploads for large files
+     * Can be a boolean to always use multipart, or a number (in bytes) as threshold
+     * @default false
+     * @example
+     * // Always use multipart uploads
+     * multipart: true
+     * // Use multipart for files larger than 100MB
+     * multipart: 100 * 1024 * 1024
+     */
+    multipart?: boolean | number;
+    /**
+     * Vercel Blob read-write token
+     */
+    token?: string;
+}

package/dist/storage/vercel-blob/vercel-blob-file.d.ts

@@ -0,0 +1,16 @@
+import { File } from "../utils/index.d.ts";
+declare class VercelBlobFile extends File {
+    /**
+     * The blob's public URL
+     */
+    url?: string;
+    /**
+     * The blob's download URL (may be different from url for private blobs)
+     */
+    downloadUrl?: string;
+    /**
+     * The blob's pathname within the store
+     */
+    pathname?: string;
+}
+export default VercelBlobFile;

package/dist/storage/vercel-blob/vercel-blob-meta-storage.d.ts

@@ -0,0 +1,7 @@
+import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
+import LocalMetaStorage from "../local/local-meta-storage.d.ts";
+import type VercelBlobFile from "./vercel-blob-file.d.ts";
+declare class VercelBlobMetaStorage extends LocalMetaStorage<VercelBlobFile> {
+    constructor(config?: LocalMetaStorageOptions);
+}
+export default VercelBlobMetaStorage;

package/dist/storage/vercel-blob/vercel-blob-storage.d.ts

@@ -0,0 +1,76 @@
+import type MetaStorage from "../meta-storage.d.ts";
+import { BaseStorage } from "../storage.d.ts";
+import type { FileInit, FilePart, FileQuery, FileReturn } from "../utils/index.d.ts";
+import type { VercelBlobStorageOptions } from "./types.d.ts";
+import VercelBlobFile from "./vercel-blob-file.d.ts";
+/**
+ * Vercel Blob storage based backend.
+ * @example
+ * ```ts
+ * const storage = new VercelBlobStorage({
+ *   token: process.env.BLOB_READ_WRITE_TOKEN,
+ *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
+ * });
+ * ```
+ * @remarks
+ * ## Supported Operations
+ * - ✅ create, write, delete, get, copy, move
+ * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
+ * - ✅ exists: Implemented (checks metadata and Vercel Blob)
+ * - ❌ getStream: Not implemented (use get() for file retrieval)
+ * - ❌ list: Not implemented (Vercel Blob API doesn't support listing)
+ * - ❌ update: Not implemented (Vercel Blob API doesn't support metadata updates)
+ * - ❌ getUrl: Not implemented (Vercel Blob URLs available via Vercel Blob API)
+ * - ❌ getUploadUrl: Not implemented (Vercel Blob upload URLs handled internally)
+ */
+declare class VercelBlobStorage extends BaseStorage<VercelBlobFile, FileReturn> {
+    static readonly name: string;
+    checksumTypes: string[];
+    protected meta: MetaStorage<VercelBlobFile>;
+    private readonly token;
+    private readonly multipart;
+    constructor(config: VercelBlobStorageOptions);
+    create(config: FileInit): Promise<VercelBlobFile>;
+    write(part: FilePart | FileQuery | VercelBlobFile): Promise<VercelBlobFile>;
+    /**
+     * Deletes an upload and its metadata.
+     * @param query File query containing the file ID to delete.
+     * @param query.id File ID to delete.
+     * @returns Promise resolving to the deleted file object with status: "deleted".
+     * @throws {UploadError} If the file metadata cannot be found.
+     */
+    delete({ id }: FileQuery): Promise<VercelBlobFile>;
+    /**
+     * Checks if a file exists by verifying both metadata and the actual Vercel Blob.
+     * Returns true only if both the metadata and the blob exist.
+     * @param query File query containing the file ID to check.
+     * @returns Promise resolving to true if both metadata and blob exist, false otherwise.
+     */
+    exists({ id }: FileQuery): Promise<boolean>;
+    get({ id }: FileQuery): Promise<FileReturn>;
+    /**
+     * Copies an upload file to a new location.
+     * @param name Source file name/ID.
+     * @param destination Destination file name/ID.
+     * @returns Promise resolving to the copied file object.
+     * @throws {UploadError} If the source file cannot be found.
+     */
+    copy(name: string, destination: string): Promise<VercelBlobFile>;
+    /**
+     * Moves an upload file to a new location.
+     * @param name Source file name/ID.
+     * @param destination Destination file name/ID.
+     * @returns Promise resolving to the moved file object.
+     * @throws {UploadError} If the source file cannot be found.
+     */
+    move(name: string, destination: string): Promise<VercelBlobFile>;
+    list(limit?: number): Promise<VercelBlobFile[]>;
+    private internalOnComplete;
+    /**
+     * Determines if multipart upload should be used for the given file.
+     * @param file File object to check.
+     * @returns True if multipart upload should be used, false otherwise.
+     */
+    private shouldUseMultipart;
+}
+export default VercelBlobStorage;

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

@@ -0,0 +1,128 @@
+import type { BaseStorage } from "../storage/storage.d.ts";
+import type { File, FileReturn } from "../storage/utils/index.d.ts";
+import BaseTransformer from "./base-transformer.d.ts";
+import type { AudioChannelMixOptions, AudioResampleOptions, AudioTransformationStep, AudioTransformerConfig, AudioTransformOptions, AudioTransformResult } from "./types.d.ts";
+/**
+ * Audio transformer that uses storage backends and Mediabunny to retrieve and transform audio files
+ *
+ * Supports audio transformations with query parameters for on-demand audio processing.
+ * @example
+ * ```ts
+ * const transformer = new AudioTransformer(storage, {
+ *   maxAudioSize: 50 * 1024 * 1024, // 50MB
+ *   cache: new Map()
+ * });
+ *
+ * // Programmatic usage - resample audio
+ * const result = await transformer.resample('audio-id', {
+ *   sampleRate: 44100
+ * });
+ *
+ * // URL-based transformations
+ * // GET /files/audio-id?sampleRate=48000&codec=aac&bitrate=128000
+ * // GET /files/audio-id?numberOfChannels=1&format=mp3
+ * ```
+ *
+ * ## Supported Query Parameters
+ *
+ * - `sampleRate`: Sample rate in Hz (Number)
+ * - `numberOfChannels`: Number of channels (Number)
+ * - `codec`: Audio codec - aac/opus/mp3/vorbis/flac
+ * - `bitrate`: Audio bitrate in bits per second (Number)
+ * - `format`: Output format - mp3/wav/ogg/aac/flac
+ */
+declare class AudioTransformer<TFile extends File = File, TFileReturn extends FileReturn = FileReturn> extends BaseTransformer<AudioTransformerConfig, AudioTransformResult<TFileReturn>, TFile, TFileReturn> {
+    /**
+     * Creates a new AudioTransformer instance.
+     * @param storage The storage backend for retrieving and storing audio files.
+     * @param config Configuration options for audio transformation including cache settings, codec defaults, and size limits.
+     */
+    constructor(storage: BaseStorage<TFile, TFileReturn>, config?: AudioTransformerConfig);
+    /**
+     * Resamples audio to different sample rate.
+     * @param fileId Unique identifier of the audio file to resample.
+     * @param options Resample options including target sample rate.
+     * @returns Promise resolving to transformed audio result.
+     */
+    resample(fileId: string, options: AudioResampleOptions): Promise<AudioTransformResult<TFileReturn>>;
+    /**
+     * Changes number of channels (up/downmixing).
+     * @param fileId Unique identifier of the audio file to process.
+     * @param options Channel mix options including target number of channels.
+     * @returns Promise resolving to transformed audio result.
+     */
+    mixChannels(fileId: string, options: AudioChannelMixOptions): Promise<AudioTransformResult<TFileReturn>>;
+    /**
+     * Converts audio format or codec.
+     * @param fileId Unique identifier of the audio file to convert.
+     * @param format Target audio format (e.g., "mp3", "wav", "ogg").
+     * @param options Additional transform options.
+     * @returns Promise resolving to transformed audio result.
+     */
+    convertFormat(fileId: string, format: string, options?: AudioTransformOptions): Promise<AudioTransformResult<TFileReturn>>;
+    /**
+     * Transcodes audio to different codec.
+     * @param fileId Unique identifier of the audio file to transcode.
+     * @param codec Target audio codec (e.g., "aac", "opus", "mp3").
+     * @param options Additional transform options.
+     * @returns Promise resolving to transformed audio result.
+     */
+    transcode(fileId: string, codec: AudioTransformOptions["codec"], options?: Omit<AudioTransformOptions, "codec">): Promise<AudioTransformResult<TFileReturn>>;
+    /**
+     * Applies a custom transformation pipeline to an audio file.
+     * @param fileId Unique identifier of the audio file to transform.
+     * @param steps Array of transformation steps to apply in sequence.
+     * @returns Promise resolving to transformed audio result.
+     */
+    transform(fileId: string, steps: AudioTransformationStep[]): Promise<AudioTransformResult<TFileReturn>>;
+    /**
+     * Apply multiple transformations in sequence using Mediabunny
+     */
+    private applyTransformations;
+    /**
+     * Convert transformation steps to Mediabunny audio options
+     * @param steps Array of audio transformation steps to convert
+     * @returns Mediabunny audio options object for conversion
+     * @private
+     */
+    private stepsToAudioOptions;
+    /**
+     * Determine output format based on transformation steps
+     * @param steps Array of audio transformation steps
+     * @returns Mediabunny output format instance (defaults to MP3)
+     * @private
+     */
+    private determineOutputFormat;
+    /**
+     * Convert format string to Mediabunny output format
+     * @param format Audio format string (aac, flac, mp3, ogg, wav)
+     * @returns Mediabunny output format instance
+     * @private
+     */
+    private formatStringToOutputFormat;
+    /**
+     * Validate that the file is a supported audio file
+     * @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 audio
+     * @private
+     */
+    private validateAudio;
+    /**
+     * Create transformation result with metadata
+     * @param buffer The transformed audio buffer
+     * @param originalFile The original file information
+     * @returns Audio transformation result with metadata
+     * @private
+     */
+    private createTransformResult;
+    /**
+     * Generate cache key for transformation
+     * @param fileId The file identifier
+     * @param steps Array of transformation steps
+     * @returns Unique cache key string
+     * @private
+     */
+    private generateCacheKey;
+}
+export default AudioTransformer;

package/dist/transformer/audio-transformer.js

@@ -0,0 +1,278 @@
+import { Input, BufferSource, ALL_FORMATS, Output, BufferTarget, Conversion, Mp3OutputFormat, WavOutputFormat, OggOutputFormat, FlacOutputFormat, AdtsOutputFormat } from 'mediabunny';
+import BaseTransformer from '../packem_shared/BaseTransformer-C2gLib6v.js';
+import { isValidMediaType, getFormatFromContentType } from '../packem_shared/isValidMediaType-BeDgiObq.js';
+
+class AudioTransformer extends BaseTransformer {
+  /**
+   * Creates a new AudioTransformer instance.
+   * @param storage The storage backend for retrieving and storing audio files.
+   * @param config Configuration options for audio transformation including cache settings, codec defaults, and size limits.
+   */
+  constructor(storage, config = {}) {
+    const logger = config.logger || storage.logger;
+    const transformerConfig = {
+      cacheTtl: 3600,
+      // 1 hour
+      defaultBitrate: 128e3,
+      // 128 kbps
+      defaultCodec: "aac",
+      maxAudioSize: 100 * 1024 * 1024,
+      // 100MB
+      maxCacheSize: 100,
+      // Max 100 transformed audio files in cache
+      supportedFormats: ["mp3", "wav", "ogg", "aac", "flac", "m4a", "wma", "aiff"],
+      ...config
+    };
+    super(storage, transformerConfig, logger);
+  }
+  /**
+   * Resamples audio to different sample rate.
+   * @param fileId Unique identifier of the audio file to resample.
+   * @param options Resample options including target sample rate.
+   * @returns Promise resolving to transformed audio result.
+   */
+  async resample(fileId, options) {
+    return this.transform(fileId, [{ options, type: "resample" }]);
+  }
+  /**
+   * Changes number of channels (up/downmixing).
+   * @param fileId Unique identifier of the audio file to process.
+   * @param options Channel mix options including target number of channels.
+   * @returns Promise resolving to transformed audio result.
+   */
+  async mixChannels(fileId, options) {
+    return this.transform(fileId, [{ options, type: "channels" }]);
+  }
+  /**
+   * Converts audio format or codec.
+   * @param fileId Unique identifier of the audio file to convert.
+   * @param format Target audio format (e.g., "mp3", "wav", "ogg").
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed audio result.
+   */
+  async convertFormat(fileId, format, options = {}) {
+    return this.transform(fileId, [{ options: { ...options, format }, type: "format" }]);
+  }
+  /**
+   * Transcodes audio to different codec.
+   * @param fileId Unique identifier of the audio file to transcode.
+   * @param codec Target audio codec (e.g., "aac", "opus", "mp3").
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed audio result.
+   */
+  async transcode(fileId, codec, options = {}) {
+    return this.transform(fileId, [{ options: { ...options, codec }, type: "codec" }]);
+  }
+  /**
+   * Applies a custom transformation pipeline to an audio file.
+   * @param fileId Unique identifier of the audio file to transform.
+   * @param steps Array of transformation steps to apply in sequence.
+   * @returns Promise resolving to transformed audio result.
+   */
+  async transform(fileId, steps) {
+    const fileQuery = { id: fileId };
+    const cacheKey = this.generateCacheKey(fileId, steps);
+    if (this.cache) {
+      const cached = await Promise.resolve(this.cache.get(cacheKey));
+      if (cached) {
+        this.logger?.debug("Returning cached transformed audio for %s", fileId);
+        return cached;
+      }
+    }
+    const originalFile = await this.storage.get(fileQuery);
+    await this.validateAudio(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;
+  }
+  /**
+   * Apply multiple transformations in sequence using Mediabunny
+   */
+  async applyTransformations(buffer, steps) {
+    const input = new Input({
+      formats: ALL_FORMATS,
+      source: new BufferSource(buffer)
+    });
+    const outputFormat = this.determineOutputFormat(steps);
+    const output = new Output({
+      format: outputFormat,
+      target: new BufferTarget()
+    });
+    const audioOptions = this.stepsToAudioOptions(steps);
+    const conversion = await Conversion.init({
+      audio: audioOptions,
+      input,
+      output
+    });
+    if (!conversion.isValid) {
+      const reasons = conversion.discardedTracks.map((track) => track.reason).join(", ");
+      throw new Error(`Audio transformation failed: ${reasons}`);
+    }
+    await conversion.execute();
+    return Buffer.from(output.target.buffer);
+  }
+  /**
+   * Convert transformation steps to Mediabunny audio options
+   * @param steps Array of audio transformation steps to convert
+   * @returns Mediabunny audio options object for conversion
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  stepsToAudioOptions(steps) {
+    const options = {};
+    for (const step of steps) {
+      switch (step.type) {
+        case "bitrate": {
+          const bitrateOptions = step.options;
+          if (bitrateOptions.bitrate) {
+            options.bitrate = bitrateOptions.bitrate;
+          }
+          break;
+        }
+        case "channels": {
+          const channelOptions = step.options;
+          if (channelOptions.numberOfChannels) {
+            options.numberOfChannels = channelOptions.numberOfChannels;
+          }
+          break;
+        }
+        case "codec": {
+          const codecOptions = step.options;
+          if (codecOptions.codec) {
+            options.codec = codecOptions.codec;
+          }
+          if (codecOptions.bitrate) {
+            options.bitrate = codecOptions.bitrate;
+          }
+          break;
+        }
+        case "resample": {
+          const resampleOptions = step.options;
+          if (resampleOptions.sampleRate) {
+            options.sampleRate = resampleOptions.sampleRate;
+          }
+          break;
+        }
+      }
+    }
+    return options;
+  }
+  /**
+   * Determine output format based on transformation steps
+   * @param steps Array of audio transformation steps
+   * @returns Mediabunny output format instance (defaults to MP3)
+   * @private
+   */
+  determineOutputFormat(steps) {
+    for (const step of steps) {
+      if (step.type === "format" && step.options.format) {
+        return this.formatStringToOutputFormat(step.options.format);
+      }
+    }
+    return new Mp3OutputFormat();
+  }
+  /**
+   * Convert format string to Mediabunny output format
+   * @param format Audio format string (aac, flac, mp3, ogg, wav)
+   * @returns Mediabunny output format instance
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  formatStringToOutputFormat(format) {
+    switch (format.toLowerCase()) {
+      case "aac": {
+        return new AdtsOutputFormat();
+      }
+      case "flac": {
+        return new FlacOutputFormat();
+      }
+      case "mp3": {
+        return new Mp3OutputFormat();
+      }
+      case "ogg": {
+        return new OggOutputFormat();
+      }
+      case "wav": {
+        return new WavOutputFormat();
+      }
+      default: {
+        return new Mp3OutputFormat();
+      }
+    }
+  }
+  /**
+   * Validate that the file is a supported audio file
+   * @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 audio
+   * @private
+   */
+  async validateAudio(file) {
+    const fileSize = typeof file.size === "string" ? Number.parseInt(file.size, 10) : file.size;
+    if (this.config?.maxAudioSize && fileSize > this.config.maxAudioSize) {
+      throw new Error(`Audio size ${fileSize} exceeds maximum allowed size ${this.config.maxAudioSize}`);
+    }
+    if (!isValidMediaType(file.contentType, "audio")) {
+      throw new Error(`File is not audio: ${file.contentType}`);
+    }
+    const format = getFormatFromContentType(file.contentType);
+    if (this.config?.supportedFormats && format && !this.config.supportedFormats.includes(format)) {
+      throw new Error(`Unsupported audio format: ${format}`);
+    }
+    try {
+      const input = new Input({
+        formats: ALL_FORMATS,
+        source: new BufferSource(file.content)
+      });
+      const primaryTrack = await input.getPrimaryAudioTrack();
+      if (!primaryTrack) {
+        throw new Error("No audio track found");
+      }
+    } catch (error) {
+      throw new Error(`Invalid audio file: ${error}`);
+    }
+  }
+  /**
+   * Create transformation result with metadata
+   * @param buffer The transformed audio buffer
+   * @param originalFile The original file information
+   * @returns Audio transformation result with metadata
+   * @private
+   */
+  async createTransformResult(buffer, originalFile) {
+    const input = new Input({
+      formats: ALL_FORMATS,
+      source: new BufferSource(buffer)
+    });
+    const audioTrack = await input.getPrimaryAudioTrack();
+    const duration = await input.computeDuration();
+    return {
+      bitrate: this.config.defaultBitrate,
+      buffer,
+      duration,
+      format: "mp3",
+      // Default, would need to detect actual format
+      numberOfChannels: audioTrack?.numberOfChannels || 2,
+      originalFile,
+      sampleRate: audioTrack?.sampleRate || 44100,
+      size: buffer.length
+    };
+  }
+  /**
+   * Generate 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 { AudioTransformer as default };

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

@@ -0,0 +1,63 @@
+import { Readable } from "node:stream";
+import type { BaseStorage } from "../storage/storage.d.ts";
+import type { File, FileReturn } from "../storage/utils/index.d.ts";
+import type { Cache } from "../utils/cache.d.ts";
+import type { BaseTransformerConfig } from "./types.d.ts";
+/**
+ * Abstract base class for all media transformers.
+ *
+ * Provides a common interface and shared functionality for image, video, and audio transformers.
+ * All transformers must implement the abstract methods defined here.
+ */
+declare abstract class BaseTransformer<Config extends BaseTransformerConfig, CacheValue extends object, TFile extends File = File, TFileReturn extends FileReturn = FileReturn> {
+    protected readonly storage: BaseStorage<TFile, TFileReturn>;
+    protected config: Config;
+    protected logger?: Console;
+    protected cache?: Cache<string, CacheValue>;
+    /**
+     * Creates a new BaseTransformer instance with common functionality.
+     * @param storage The storage backend for retrieving and storing files.
+     * @param config Configuration options for the transformer.
+     * @param logger Optional logger instance for logging operations.
+     * @protected
+     */
+    protected constructor(storage: BaseStorage<TFile, TFileReturn>, config: Config, logger?: Console);
+    /**
+     * Transforms a file with the given steps.
+     * @param fileId Unique identifier of the file to transform.
+     * @param steps Array of transformation steps to apply.
+     * @returns Promise resolving to transformation result.
+     */
+    abstract transform(fileId: string, steps: any[]): Promise<any>;
+    /**
+     * Streams transform of a file with the given steps (for large files).
+     * @param fileId Unique identifier of the file to transform.
+     * @param steps Array of transformation steps to apply.
+     * @returns Promise resolving to streaming result with headers, size, and stream.
+     */
+    transformStream?(fileId: string, steps: any[]): Promise<{
+        headers?: Record<string, string>;
+        size?: number;
+        stream: Readable;
+    }>;
+    /**
+     * Clears cache for a specific file or all files.
+     * @param fileId Optional file identifier to clear cache for specific file.
+     */
+    clearCache(fileId?: string): void;
+    /**
+     * Gets cache statistics.
+     * @returns Cache statistics including max size and current size.
+     */
+    getCacheStats(): {
+        maxSize: number;
+        size: number;
+    };
+    /**
+     * Gets content type from transformation result based on format.
+     * @param result Transformation result object containing format information.
+     * @returns Content type string (MIME type).
+     */
+    protected getContentTypeFromResult(result: any): string;
+}
+export default BaseTransformer;