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

package/dist/packem_shared/disk-storage-with-checksum.d-hEoe2ugb.d.ts

@@ -0,0 +1,148 @@
+import { F as File, M as MetaStorage, D as DiskStorageOptions, H as HttpError, b as FileInit, d as FilePart, e as FileQuery, a as FileReturn, E as ERRORS, B as BaseStorage, h as DiskStorageWithChecksumOptions } from "./storage.d-BOMUJD96.js";
+import { Readable } from 'node:stream';
+/**
+* Local disk-based storage implementation.
+* @template TFile The file type used by this storage backend.
+* @remarks
+* ## Error Handling
+* - Filesystem operations throw errors directly (no retry logic)
+* - File not found errors are thrown immediately
+* - Permission errors are propagated as-is
+*
+* ## Retry Behavior
+* - No automatic retries (filesystem operations are typically immediate)
+* - Errors are thrown directly for immediate feedback
+*
+* ## File Paths
+* - Files are stored in the configured directory
+* - Metadata files use the `.META` suffix by default
+* - File paths are resolved relative to the storage directory
+*/
+declare class DiskStorage<TFile extends File = File> extends BaseStorage<TFile> {
+  static override readonly name: string;
+  override checksumTypes: string[];
+  directory: string;
+  meta: MetaStorage<TFile>;
+  constructor(config: DiskStorageOptions<TFile>);
+  /**
+  * Normalizes errors with disk storage context.
+  * @param error The error to normalize.
+  * @returns Normalized HTTP error.
+  */
+  override normalizeError(error: Error): HttpError;
+  /**
+  * Creates a new file upload and saves its metadata.
+  * @param fileInit File initialization configuration.
+  * @returns Promise resolving to the created file object.
+  * @throws {Error} If validation fails or file already exists and is completed.
+  * @remarks
+  * Supports TTL (time-to-live) option in fileInit.
+  * Creates the file on disk if it doesn't exist.
+  * Returns existing file if it's already completed.
+  */
+  create(fileInit: FileInit): Promise<TFile>;
+  /**
+  * Writes data to a file upload.
+  * @param part File part containing data to write, file query, or full file object.
+  * @returns Promise resolving to the updated file object.
+  * @throws {Error} If file is expired (ERRORS.GONE), locked (ERRORS.FILE_LOCKED), or conflicts occur (ERRORS.FILE_CONFLICT).
+  * @remarks
+  * Supports chunked uploads with start position.
+  * Automatically detects file type from stream on first chunk if contentType is not set.
+  * Validates checksum algorithms if provided.
+  * Uses file locking to prevent concurrent writes.
+  * Updates file status to "completed" when all bytes are written.
+  */
+  write(part: FilePart | FileQuery | TFile): Promise<TFile>;
+  /**
+  * Gets an uploaded file by ID.
+  * @param query File query containing the file ID to retrieve.
+  * @param query.id File ID to retrieve.
+  * @returns Promise resolving to the file data including content buffer.
+  * @throws {Error} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
+  * @remarks
+  * Loads the entire file content into memory as a Buffer.
+  * For large files, consider using getStream() instead.
+  * Includes ETag (MD5 hash) for content verification.
+  */
+  get({
+    id
+  }: FileQuery): Promise<FileReturn>;
+  /**
+  * Checks if a file exists by verifying both metadata and the actual filesystem file.
+  * Returns true only if both the metadata and the file exist.
+  * @param query File query containing the file ID to check.
+  * @returns Promise resolving to true if both metadata and file exist, false otherwise.
+  */
+  override exists({
+    id
+  }: FileQuery): Promise<boolean>;
+  /**
+  * Gets an uploaded file as a readable stream for efficient large file handling.
+  * @param query File query containing the file ID to stream.
+  * @param query.id File ID to stream.
+  * @returns Promise resolving to an object containing the stream, headers, and size.
+  * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
+  * @remarks Creates a readable stream directly from the file system for efficient memory usage.
+  */
+  override getStream({
+    id
+  }: FileQuery): Promise<{
+    headers?: Record<string, string>;
+    size?: number;
+    stream: Readable;
+  }>;
+  /**
+  * 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<TFile>;
+  /**
+  * 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<TFile>;
+  /**
+  * 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 {Error} If the source file cannot be found.
+  */
+  move(name: string, destination: string): Promise<TFile>;
+  /**
+  * Retrieves a list of uploaded files.
+  * @returns Promise resolving to an array of file metadata objects.
+  * @remarks Walks the storage directory and returns all files, excluding metadata files.
+  */
+  override list(): Promise<TFile[]>;
+  /**
+  * Returns path for the uploaded file
+  * If filename is already an absolute path, returns it as-is.
+  * Otherwise, joins it with the storage directory.
+  */
+  protected getFilePath(filename: string): string;
+  protected lazyWrite(part: File & FilePart): Promise<[number, ERRORS?]>;
+  private accessCheck;
+}
+/**
+* Additionally calculates checksum of the file/range.
+*/
+declare class DiskStorageWithChecksum<TFile extends File = File> extends DiskStorage<TFile> {
+  private hashes;
+  constructor(config: DiskStorageWithChecksumOptions<TFile>);
+  override delete({
+    id
+  }: FileQuery): Promise<TFile>;
+  override write(part: FilePart | FileQuery): Promise<TFile>;
+  protected override lazyWrite(part: File & FilePart): Promise<[number, ERRORS?]>;
+}
+export { DiskStorage as D, DiskStorageWithChecksum as a };

package/dist/packem_shared/{gcs-meta-storage-C8rMsqR_.js → gcs-meta-storage-B5AVt1aS.js}

@@ -7,7 +7,7 @@ import GCSConfig from './GCSConfig-vPP22kN6.js';
 import { h as hasContent } from './has-content-CY66ehMK.js';
 
 var name = "@visulima/storage";
-var version = "1.0.0-alpha.13";
+var version = "1.0.0-alpha.15";
 const package_ = {
 	name: name,
 	version: version};

package/dist/packem_shared/local-meta-storage.d-Dop9RP9k.d.ts

@@ -0,0 +1,20 @@
+import { F as File, L as LocalMetaStorageOptions, M as MetaStorage } from "./storage.d-BOMUJD96.js";
+import 'node:stream';
+/**
+* Stores upload metafiles on local disk
+*/
+declare class LocalMetaStorage<T extends File = File> extends MetaStorage<T> {
+  readonly directory: string;
+  constructor(config?: LocalMetaStorageOptions);
+  /**
+  * Returns metafile path.
+  * @param id upload id
+  */
+  getMetaPath: (id: string) => string;
+  override save(id: string, file: T): Promise<T>;
+  override touch(id: string, file: T): Promise<T>;
+  override get(id: string): Promise<T>;
+  override delete(id: string): Promise<void>;
+  private accessCheck;
+}
+export { LocalMetaStorage as L };

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

@@ -0,0 +1,331 @@
+import { F as File, a as FileReturn, B as BaseStorage } from "./storage.d-BOMUJD96.js";
+import { O as MediaTransformerConfig, Q as MediaTransformResult } from "./types.d-BPd_JkW1.js";
+/**
+* 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 { MediaTransformer as M };