@visulima/storage 1.0.0-alpha.15 → 1.0.0-alpha.16

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

@@ -1,37 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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/types.d.ts

@@ -1,31 +0,0 @@
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions } from "../types.d.ts";
-export interface VercelBlobStorageOptions extends BaseStorageOptions {
-    /**
-     * 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

@@ -1,16 +0,0 @@
-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

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

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

@@ -1,76 +0,0 @@
-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 {
-    static readonly name: string;
-    checksumTypes: string[];
-    protected meta: MetaStorage;
-    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/base-transformer.d.ts

@@ -1,63 +0,0 @@
-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 "./transformer-config.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;

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;

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

@@ -1,16 +0,0 @@
-import type { Cache } from "../utils/cache.d.ts";
-/**
- * Base transformer configuration with common properties
- */
-export interface BaseTransformerConfig {
-    /** Cache instance to use for caching */
-    cache?: Cache;
-    /** Cache TTL in seconds */
-    cacheTtl?: number;
-    /** Logger instance */
-    logger?: Console;
-    /** Maximum number of cached items */
-    maxCacheSize?: number;
-    /** Supported input formats */
-    supportedFormats?: string[] | undefined;
-}