@visulima/storage 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/packem_shared/storage.d-Cxs42eEK.d.ts

@@ -0,0 +1,939 @@
+import { Transform, Readable } from 'node:stream';
+import { BinaryToTextEncoding, Hash } from 'node:crypto';
+import { IncomingMessage } from 'node:http';
+import { LRUCache } from 'lru-cache';
+/**
+* Transform that computes a rolling checksum for a stream while passing
+* data through unchanged.
+*/
+interface RangeChecksum extends Transform {
+  /** Return the current digest in the selected encoding. */
+  digest: (encoding: BinaryToTextEncoding) => string;
+  hash: Hash;
+  path: string;
+  reset: () => void;
+}
+/**
+* LRU-backed map of rolling hashers keyed by file path. Used to compute
+* hex/base64 digests and resume hashing from an offset.
+*/
+interface RangeHasher extends LRUCache<string, Hash> {
+  algorithm: "md5" | "sha1";
+  base64: (path: string) => string;
+  digester: (path: string) => RangeChecksum;
+  hex: (path: string) => string;
+  init: (path: string, start: number) => Promise<Hash>;
+  updateFromFs: (path: string, start: number, initial?: Hash) => Promise<Hash>;
+}
+/**
+* Normalized HTTP error payload returned by handlers and storage backends.
+*/
+interface HttpErrorBody {
+  code: string;
+  detail?: Record<string, unknown> | string;
+  message: string;
+  name?: string;
+  retryable?: boolean;
+  UploadErrorCode?: string;
+}
+/**
+* Rich HTTP error including status code and optional headers/body.
+*/
+interface HttpError<T = HttpErrorBody> extends UploadResponse<T> {
+  statusCode: number;
+}
+/**
+* Node.js IncomingMessage with an optional parsed body attached.
+*/
+interface IncomingMessageWithBody<T = unknown> extends IncomingMessage {
+  _body?: boolean;
+  body?: T;
+}
+type Header = string[] | number | string;
+type Headers = Record<string, Header>;
+type ResponseBody = Record<string, unknown> | string | Buffer | Uint8Array;
+type ResponseBodyType = "json" | "text";
+/**
+* Tuple form for quick response definitions: [status, body, headers].
+*/
+type ResponseTuple<T = ResponseBody> = [statusCode: number, body?: T, headers?: Headers];
+/**
+* Structured response used across handlers and storage operations.
+*/
+interface UploadResponse<T = ResponseBody> extends Record<string, unknown> {
+  body?: T;
+  headers?: Headers;
+  statusCode?: number;
+}
+/**
+* Declarative validator configuration for a single rule.
+*/
+interface ValidatorConfig<T> {
+  isValid?: (t: T) => Promise<boolean> | boolean;
+  response?: HttpError | ResponseTuple;
+  value?: unknown;
+}
+/** Map of rule-name -> validator configuration. */
+type Validation<T> = Record<string, ValidatorConfig<T>>;
+/** Narrowed error response shape for validation failures. */
+interface ValidationError extends HttpError {
+  code: string;
+}
+/**
+* Metrics interface for observability.
+* Provides counters, timers, and gauges for tracking storage operations.
+*/
+interface Metrics {
+  /**
+  * Set a gauge metric value.
+  * @param name Metric name (e.g., "storage.files.size")
+  * @param value Gauge value
+  * @param attributes Optional attributes/labels
+  */
+  gauge: (name: string, value: number, attributes?: Record<string, string | number>) => void;
+  /**
+  * Increment a counter metric.
+  * @param name Metric name (e.g., "storage.operations.create.count")
+  * @param value Increment value (default: 1)
+  * @param attributes Optional attributes/labels (e.g., { storage: "s3", operation: "create" })
+  */
+  increment: (name: string, value?: number, attributes?: Record<string, string | number>) => void;
+  /**
+  * Record a duration/timing metric in milliseconds.
+  * @param name Metric name (e.g., "storage.operations.write.duration")
+  * @param duration Duration in milliseconds
+  * @param attributes Optional attributes/labels
+  */
+  timing: (name: string, duration: number, attributes?: Record<string, string | number>) => void;
+}
+/**
+* Canonical error codes used across handlers and storage adapters.
+* These codes map to standardized HTTP status codes and error messages.
+*/
+declare enum ERRORS {
+  BAD_REQUEST = "BadRequest",
+  CHECKSUM_MISMATCH = "ChecksumMismatch",
+  FILE_CONFLICT = "FileConflict",
+  FILE_ERROR = "FileError",
+  FILE_LOCKED = "FileLocked",
+  FILE_NOT_ALLOWED = "FileNotAllowed",
+  FILE_NOT_FOUND = "FileNotFound",
+  FORBIDDEN = "Forbidden",
+  GONE = "Gone",
+  INVALID_FILE_NAME = "InvalidFileName",
+  INVALID_FILE_SIZE = "InvalidFileSize",
+  INVALID_RANGE = "InvalidRange",
+  INVALID_TYPE = "Invalidtype",
+  METHOD_NOT_ALLOWED = "MethodNotAllowed",
+  REQUEST_ABORTED = "RequestAborted",
+  REQUEST_ENTITY_TOO_LARGE = "RequestEntityTooLarge",
+  STORAGE_BUSY = "StorageBusy",
+  STORAGE_ERROR = "StorageError",
+  TOO_MANY_REQUESTS = "TooManyRequests",
+  UNKNOWN_ERROR = "UnknownError",
+  UNPROCESSABLE_ENTITY = "UnprocessableEntity",
+  UNSUPPORTED_CHECKSUM_ALGORITHM = "UnsupportedChecksumAlgorithm",
+  UNSUPPORTED_MEDIA_TYPE = "UnsupportedMediaType",
+}
+/**
+* Type mapping of error codes to standardized HTTP error responses.
+* @template T - The error code type (defaults to string)
+*/
+type ErrorResponses<T extends string = string> = { [K in T]: HttpError };
+/**
+* Mapping of error codes to HttpError response objects.
+* @returns Map of error codes to standardized HTTP error responses
+*/
+declare const ErrorMap: ErrorResponses<ERRORS>;
+/**
+* Error subclass carrying a stable error code and optional detail.
+* Provides structured error information for upload operations.
+*/
+declare class UploadError extends Error {
+  override name: string;
+  /** The standardized error code from the ERRORS enum */
+  UploadErrorCode: ERRORS;
+  /** Optional additional error details */
+  detail?: unknown;
+  /**
+  * Creates a new UploadError instance.
+  * @param code Standardized error code (defaults to UNKNOWN_ERROR)
+  * @param message Human-readable error message (defaults to the code)
+  * @param detail Optional additional error details
+  */
+  constructor(code?: ERRORS, message?: string, detail?: unknown);
+}
+/**
+* Type guard to check if an error is an UploadError instance.
+* @param error Error to check
+* @returns True if the error is an UploadError with a valid error code
+*/
+declare const isUploadError: (error: unknown) => error is UploadError;
+/**
+* Convenience function to throw an UploadError from a string error code.
+* Looks up the appropriate error message from ErrorMap.
+* @param UploadErrorCode String error code to convert to UploadError
+* @param detail Optional additional error details
+* @throws UploadError with the specified code and message
+*/
+declare const throwErrorCode: (UploadErrorCode: ERRORS | string, detail?: string) => never;
+interface MetaStorageOptions {
+  logger?: Console;
+  prefix?: string;
+  suffix?: string;
+}
+interface LocalMetaStorageOptions extends MetaStorageOptions {
+  /**
+  * Where the upload metadata should be stored
+  */
+  directory?: string;
+}
+declare class Metadata {
+  [key: string]: unknown;
+  psize?: number | string;
+  pname?: string;
+  pfiletype?: string;
+  ptype?: string;
+  pmimeType?: string;
+  pcontentType?: string;
+  ptitle?: string;
+  pfilename?: string;
+  poriginalName?: string;
+  plastModified?: number | string;
+}
+interface FileInit {
+  contentType?: string;
+  expiredAt?: Date | number | string;
+  metadata: Metadata;
+  originalName?: string;
+  size?: number | string;
+  storageClass?: string;
+  ttl?: number | string;
+}
+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";
+type UploadEventType = UploadEventTypeValue;
+interface FileQuery {
+  id: string;
+  name?: string;
+  size?: number;
+}
+interface Checksum {
+  checksum?: string;
+  checksumAlgorithm?: string;
+}
+interface FilePart extends Checksum, FileQuery {
+  body: Readable;
+  contentLength?: number;
+  start: number;
+}
+type DateType = Date | number | string;
+declare class File implements FileInit {
+  bytesWritten: number;
+  contentType: string;
+  originalName: string;
+  id: string;
+  metadata: Metadata;
+  name: string;
+  size?: number;
+  status?: UploadEventType;
+  expiredAt?: DateType;
+  createdAt?: DateType;
+  modifiedAt?: DateType;
+  hash?: {
+    algorithm: string;
+    value: string;
+  };
+  content?: Buffer;
+  ETag?: string;
+  constructor({
+    contentType,
+    expiredAt,
+    metadata,
+    originalName,
+    size
+  }: FileInit);
+}
+type UploadFile = Readonly<File>;
+/**
+* Stores upload metadata.
+*/
+declare class MetaStorage<T extends File = File> {
+  prefix: string;
+  suffix: string;
+  protected readonly logger?: Console;
+  constructor(config?: MetaStorageOptions);
+  /**
+  * Saves upload metadata.
+  */
+  save(_id: string, file: T): Promise<T>;
+  /**
+  * Deletes an upload metadata.
+  */
+  delete(_id: string): Promise<void>;
+  /**
+  * Retrieves upload metadata.
+  */
+  get(_id: string): Promise<T>;
+  /**
+  * Marks upload active.
+  */
+  touch(_id: string, _file: T): Promise<T>;
+  getMetaName(id: string): string;
+  getIdFromMetaName(name: string): string;
+}
+/**
+* Simple cache interface that any cache implementation can follow
+*/
+interface Cache<K = string, V = unknown> {
+  /** Clear all cache entries */
+  clear: () => void | Promise<void>;
+  /** Delete a value from cache */
+  delete: (key: K) => boolean | Promise<boolean>;
+  /** Get a value from cache */
+  get: (key: K) => V | undefined | Promise<V | undefined>;
+  /** Check if a key exists in cache */
+  has: (key: K) => boolean | Promise<boolean>;
+  /** Set a value in cache */
+  set: (key: K, value: V, options?: CacheOptions) => boolean | Promise<boolean>;
+}
+/**
+* Options for cache operations
+*/
+interface CacheOptions {
+  /** TTL in milliseconds */
+  ttl?: number;
+}
+/**
+* A simple lock map keyed by strings, backed by LRUCache. Locks
+* automatically expire according to the configured TTL preventing deadlocks.
+*/
+declare class Locker<K extends string = string, V extends string = string> extends LRUCache<K, V, number> {
+  /**
+  * Creates a new Locker instance with configurable TTL and cache options.
+  * @param options LRU cache configuration options
+  */
+  constructor(options?: LRUCache.Options<K, V, number>);
+  /**
+  * Acquires a lock for the specified key.
+  * Throws an error if the key is already locked.
+  * @param key The key to lock
+  * @returns The lock token (same as the key)
+  * @throws Error if the key is already locked
+  */
+  lock(key: K): string;
+  /**
+  * Releases the lock for the specified key.
+  * @param key The key to unlock
+  */
+  unlock(key: K): void;
+}
+/**
+* Configurable validation system for file upload constraints.
+* Supports multiple validation rules with custom error responses.
+* @template T - The type being validated
+*/
+declare class Validator<T> {
+  private prefix;
+  private validators;
+  /**
+  * Creates a new Validator instance.
+  * @param prefix Prefix for generated error codes (default: "ValidationError")
+  */
+  constructor(prefix?: string);
+  /**
+  * Adds validation rules to the validator.
+  * Each rule must include an `isValid` function.
+  * @param config Validation configuration object
+  * @throws TypeError if any validator is missing the isValid function
+  */
+  add(config: Validation<T>): void;
+  /**
+  * Verifies an object against all configured validation rules.
+  * Throws ValidationError on first validation failure.
+  * @param t Object to validate
+  * @throws ValidationError if validation fails
+  */
+  verify(t: T): Promise<never | void>;
+}
+/**
+* Retry configuration options for storage operations
+*/
+interface RetryConfig {
+  /**
+  * Multiplier for exponential backoff (e.g., 2 means delays double each retry)
+  * @default 2
+  */
+  backoffMultiplier?: number;
+  /**
+  * Custom function to calculate delay for a specific retry attempt
+  * @param attempt The current retry attempt (0-indexed)
+  * @param error The error that occurred
+  * @returns Delay in milliseconds, or undefined to use default exponential backoff
+  */
+  calculateDelay?: (attempt: number, error: unknown) => number | undefined;
+  /**
+  * Initial delay in milliseconds before first retry
+  * @default 1000
+  */
+  initialDelay?: number;
+  /**
+  * Maximum delay in milliseconds between retries
+  * @default 30000
+  */
+  maxDelay?: number;
+  /**
+  * Maximum number of retry attempts
+  * @default 3
+  */
+  maxRetries?: number;
+  /**
+  * HTTP status codes that should trigger a retry
+  * @default [408, 429, 500, 502, 503, 504]
+  */
+  retryableStatusCodes?: number[];
+  /**
+  * Custom function to determine if an error should be retried
+  * @param error The error that occurred
+  * @returns true if the error should be retried, false otherwise
+  */
+  shouldRetry?: (error: unknown) => boolean;
+}
+/**
+* Determines if an error is retryable based on common patterns
+* @param error The error to check
+* @param retryableStatusCodes HTTP status codes that should trigger retry
+* @returns true if the error is retryable
+*/
+declare const isRetryableError: (error: unknown, retryableStatusCodes?: number[]) => boolean;
+/**
+* Retry an async operation with exponential backoff
+* @param fn The async function to retry
+* @param config Retry configuration
+* @returns The result of the function
+* @throws The last error if all retries are exhausted
+*/
+declare const retry: <T>(function_: () => Promise<T>, config?: RetryConfig) => Promise<T>;
+/**
+* Create a retry wrapper function with pre-configured settings.
+* @param config Retry configuration
+* @returns A function that wraps async operations with retry logic
+*/
+declare const createRetryWrapper: (config?: RetryConfig) => <T>(function_: () => Promise<T>) => Promise<T>;
+type OnCreate<TFile extends File = File> = (file: TFile) => Promise<void> | void;
+type OnUpdate<TFile extends File = File> = (file: TFile) => Promise<void> | void;
+type OnComplete<TFile extends File = File, TResponse = unknown, TRequest = unknown> = (file: TFile, response: TResponse, request?: TRequest) => Promise<void> | void;
+type OnDelete<TFile extends File = File> = (file: TFile) => Promise<void> | void;
+type OnError<TBody = HttpErrorBody> = (error: HttpError<TBody>) => Promise<void> | void;
+interface PurgeList {
+  items: UploadFile[];
+  maxAgeMs: number;
+}
+interface ExpirationOptions {
+  /**
+  * Age of the upload, after which it is considered expired and can be deleted
+  */
+  maxAge: number | string;
+  /**
+  * Auto purging interval for expired upload
+  */
+  purgeInterval?: number | string;
+  /**
+  * Auto prolong expiring upload
+  */
+  rolling?: boolean;
+}
+interface BaseStorageOptions<T extends File = File> extends GenericStorageConfig {
+  /** Allowed MIME types */
+  allowMIME?: string[];
+  /** The full path of the folder where the uploaded asset will be stored. */
+  assetFolder?: string;
+  /** Cache instance to use for caching */
+  cache?: Cache;
+  /**
+  * Automatic cleaning of abandoned and completed upload
+  * @example
+  * ```ts
+  * app.use(
+  *   '/upload',
+  *   Upload.upload({
+  *     directory: 'upload',
+  *     expiration: { maxAge: '6h', purgeInterval: '30min' },
+  *     onComplete
+  *   })
+  * );
+  * ```
+  */
+  expiration?: ExpirationOptions;
+  /** File naming function */
+  filename?: (file: T) => string;
+  /**
+  * File name validation function.
+  * Returns true if the filename is valid, false otherwise.
+  * @default Cloud storage platforms: permissive (only blocks path traversal and null bytes)
+  * @default DiskStorage: strict (blocks filesystem-incompatible characters)
+  * @example
+  * ```ts
+  * fileNameValidation: (name: string) => {
+  *   // Custom validation logic
+  *   return name.length > 0 && !name.includes('../');
+  * }
+  * ```
+  */
+  fileNameValidation?: (name: string) => boolean;
+  /** Logger injection */
+  logger?: Console;
+  /** Limiting the size of custom metadata */
+  maxMetadataSize?: number | string;
+  /** File size limit */
+  maxUploadSize?: number | string;
+  /** Provide custom meta storage  */
+  metaStorage?: MetaStorage<T>;
+  /** Metrics injection for observability */
+  metrics?: Metrics;
+  /** Callback function that is called when an upload is completed */
+  onComplete?: OnComplete<T>;
+  /** Callback function that is called when a new upload is created */
+  onCreate?: OnCreate<T>;
+  /** Callback function that is called when an upload is cancelled */
+  onDelete?: OnDelete<T>;
+  /** Customize error response */
+  onError?: OnError;
+  /** Callback function that is called when an upload is updated */
+  onUpdate?: OnUpdate<T>;
+  /** Force relative URI in Location header */
+  useRelativeLocation?: boolean;
+  /** Upload validation options */
+  validation?: Validation<T>;
+}
+type DiskStorageOptions<T extends File> = BaseStorageOptions<T> & {
+  /**
+  * Uploads directory.
+  */
+  directory: string;
+  /**
+  * Configuring metafile storage on the local disk
+  * @example
+  * ```ts
+  * const storage = new DiskStorage({
+  *   directory: 'upload',
+  *   metaStorageConfig: { directory: '/tmp/upload-metafiles', prefix: '.' }
+  * });
+  * ```
+  */
+  metaStorageConfig?: LocalMetaStorageOptions;
+};
+type DiskStorageWithChecksumOptions<T extends File> = DiskStorageOptions<T> & {
+  /**
+  * Enable/disable file/range checksum calculation
+  */
+  checksum?: boolean | "md5" | "sha1";
+};
+/**
+* Unified storage configuration
+*/
+interface GenericStorageConfig {
+  /** Allow additional properties for specific storage backends */
+  [key: string]: unknown;
+  /** Base path/prefix for all operations */
+  basePath?: string;
+  /** Cache TTL */
+  cacheTTL?: number;
+  /** Supported checksum algorithms */
+  checksumTypes?: string[];
+  /** Logger instance */
+  logger?: Console;
+  /** Maximum file size */
+  maxFileSize?: number | string;
+  /** Metrics instance for observability */
+  metrics?: Metrics;
+  /** Retry configuration for transient failures */
+  retryConfig?: RetryConfig;
+}
+/**
+* Batch operation result for a single file
+*/
+interface BatchOperationResult<T extends File = File> {
+  /** Error message if operation failed */
+  error?: string;
+  /** File that was successfully operated on */
+  file?: T;
+  /** File ID */
+  id: string;
+  /** Whether the operation was successful */
+  success: boolean;
+}
+/**
+* Response from batch operations (deleteBatch, copyBatch, moveBatch)
+*/
+interface BatchOperationResponse<T extends File = File> {
+  /** Failed operations with error details */
+  failed: {
+    error: string;
+    id: string;
+  }[];
+  /** Total number of failed operations */
+  failedCount: number;
+  /** Successfully processed files */
+  successful: T[];
+  /** Total number of successful operations */
+  successfulCount: number;
+}
+/**
+* Default filename validation for cloud storage platforms.
+* Permissive validation that only blocks dangerous patterns (path traversal, null bytes).
+* Cloud storage platforms (S3, Azure, GCS) accept most special characters and handle URL encoding automatically.
+*/
+declare const defaultCloudStorageFileNameValidation: (name: string) => boolean;
+/**
+* Default filename validation for local filesystems.
+* Stricter validation that blocks filesystem-incompatible characters.
+*/
+declare const defaultFilesystemFileNameValidation: (name: string) => boolean;
+/**
+* Abstract base class for all storage backends.
+* @template TFile The file type used by this storage backend.
+* @template TFileReturn The return type for file retrieval operations.
+* @remarks
+* ## Error Handling
+*
+* All storage operations follow consistent error handling patterns:
+* - Operations throw `UploadError` with specific error codes (see ERRORS enum)
+* - Common error codes: FILE_NOT_FOUND, GONE (expired), FILE_LOCKED, STORAGE_BUSY
+* - Errors are normalized with storage class context via `normalizeError()`
+* - Batch operations capture individual failures without stopping the batch
+*
+* ## Retry Behavior
+*
+* Storage implementations handle retries differently:
+*
+* ### Cloud Storage (S3, GCS, Azure, Netlify Blob)
+* - Use configurable retry wrappers via `retryConfig` option
+* - Default retryable status codes: 408, 429, 500, 502, 503, 504
+* - Retry logic handles transient network errors and rate limiting
+* - Custom `shouldRetry` functions can be provided for advanced retry logic
+*
+* ### Local Storage (DiskStorage)
+* - No automatic retries (filesystem operations are typically immediate)
+* - Errors are thrown directly for immediate feedback
+*
+* ## Operation Instrumentation
+*
+* All public operations are automatically instrumented via `instrumentOperation()`:
+* - Metrics are recorded for operation count, duration, and errors
+* - File sizes are tracked for operations that return file objects
+* - Error metrics include error messages for debugging
+*
+* ## Metadata Caching
+*
+* File metadata is automatically cached to reduce storage API calls:
+* - Cache is updated on save, delete, and get operations
+* - Cache is invalidated when metadata is deleted
+* - Implementations can override caching behavior if needed
+*/
+declare abstract class BaseStorage<TFile extends File = File, TFileReturn extends FileReturn = FileReturn> {
+  /**
+  * Hook called when a new file is created.
+  * @param file The newly created file object.
+  * @remarks This hook is called after file metadata is saved but before returning the file.
+  * Can be used for side effects like logging, notifications, or custom processing.
+  */
+  onCreate: (file: TFile) => Promise<void> | void;
+  /**
+  * Hook called when file metadata is updated.
+  * @param file The updated file object.
+  * @remarks This hook is called after metadata is updated and saved.
+  * Can be used for side effects like logging or custom processing.
+  */
+  onUpdate: (file: TFile) => Promise<void> | void;
+  /**
+  * Hook called when a file upload is completed.
+  * @param file The completed file object.
+  * @param response The response object that can be modified in place (headers, statusCode, body).
+  * @param request Optional request object for additional context.
+  * @remarks This hook is called when file status becomes "completed".
+  * The response object can be modified directly to add headers or change the status code.
+  */
+  onComplete: (file: TFile, response: unknown, request?: unknown) => Promise<void> | void;
+  /**
+  * Hook called when a file is deleted.
+  * @param file The deleted file object.
+  * @remarks This hook is called after the file is deleted but before returning.
+  * Can be used for side effects like cleanup or logging.
+  */
+  onDelete: (file: TFile) => Promise<void> | void;
+  /**
+  * Hook called when an error occurs during storage operations.
+  * @param error The HTTP error object that can be modified in place.
+  * @remarks This hook allows customizing error responses by modifying the error object.
+  * The error object can be modified to change headers, statusCode, or body properties.
+  * Error formatting happens in handlers after this hook is called.
+  */
+  onError: (error: HttpError) => Promise<void> | void;
+  isReady: boolean;
+  errorResponses: ErrorResponses;
+  cache: Cache<string, TFile>;
+  readonly logger?: Console;
+  readonly metrics: Metrics;
+  readonly genericConfig: BaseStorageOptions<TFile>;
+  maxMetadataSize: number;
+  checksumTypes: string[];
+  maxUploadSize: number;
+  protected expiration?: {
+    maxAge?: string | number;
+    purgeInterval?: string | number;
+    rolling?: boolean;
+  };
+  protected locker: Locker;
+  protected namingFunction: (file: TFile) => string;
+  protected validation: Validator<TFile>;
+  protected abstract meta: MetaStorage<TFile>;
+  protected assetFolder: string | undefined;
+  /**
+  * Limits the number of concurrent upload requests
+  */
+  protected concurrency?: number;
+  protected constructor(config: BaseStorageOptions<TFile>);
+  get tusExtension(): string[];
+  /**
+  * Validates a file against configured validation rules.
+  * @param file File object to validate.
+  * @returns Promise resolving to undefined if file is valid, throws ValidationError otherwise.
+  * @throws {ValidationError} If validation fails
+  */
+  validate(file: TFile): Promise<void>;
+  /**
+  * Checks if a file exists by querying its metadata.
+  * @param query File query containing the file ID to check.
+  * @param query.id File ID to check.
+  * @returns Promise resolving to true if file exists, false otherwise.
+  * @remarks This method does not throw errors - it returns false if the file is not found.
+  */
+  exists(query: FileQuery): Promise<boolean>;
+  /**
+  * Normalizes errors with storage-specific context.
+  * @param error The error to normalize.
+  * @returns Normalized HTTP error with storage class context added to the message.
+  * @remarks Errors are enhanced with the storage class name for better debugging.
+  */
+  normalizeError(error: Error): HttpError;
+  /**
+  * Gets the storage configuration.
+  * @returns The current storage configuration options.
+  */
+  get config(): BaseStorageOptions<TFile>;
+  /**
+  * Saves upload metadata to the metadata storage.
+  * @param file File object containing metadata to save.
+  * @returns Promise resolving to the saved file object.
+  * @remarks Updates timestamps and caches the file metadata.
+  */
+  saveMeta(file: TFile): Promise<TFile>;
+  /**
+  * Deletes upload metadata from the metadata storage.
+  * @param id File ID whose metadata should be deleted.
+  * @returns Promise resolving when metadata is deleted.
+  * @remarks Also removes the file from the cache.
+  */
+  deleteMeta(id: string): Promise<void>;
+  /**
+  * Retrieves upload metadata by file ID.
+  * @param id File ID to retrieve metadata for.
+  * @returns Promise resolving to the file metadata object.
+  * @throws {UploadError} If the file metadata cannot be found (ERRORS.FILE_NOT_FOUND).
+  * @remarks Caches the retrieved metadata for faster subsequent access.
+  */
+  getMeta(id: string): Promise<TFile>;
+  /**
+  * Checks if a file has expired and deletes it if so.
+  * @param file File object to check for expiration.
+  * @returns Promise resolving to the file object if not expired.
+  * @throws {UploadError} If the file has expired (ERRORS.GONE).
+  * @remarks If the file is expired, it is automatically deleted and the metadata is removed.
+  */
+  checkIfExpired(file: TFile): Promise<TFile>;
+  /**
+  * Searches for and purges expired uploads.
+  * @param maxAge Maximum age of files to keep (files older than this will be purged).
+  * Can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
+  * If not provided, uses the expiration.maxAge from configuration.
+  * @returns Promise resolving to a list of purged files.
+  * @remarks
+  * Errors during individual file deletions are logged but do not stop the purge process.
+  * Files with corrupted metadata are skipped with a warning.
+  * Uses rolling expiration if configured (based on modifiedAt) or fixed expiration (based on createdAt).
+  */
+  purge(maxAge?: number | string): Promise<PurgeList>;
+  /**
+  * 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.
+  * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
+  * @remarks This method loads the entire file content into memory. For large files, use getStream() instead.
+  */
+  abstract get({
+    id
+  }: FileQuery): Promise<TFileReturn>;
+  /**
+  * 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
+  * Default implementation falls back to get() and creates a stream from the buffer.
+  * Storage implementations should override this for better streaming performance.
+  * Headers include Content-Type, Content-Length, ETag, and Last-Modified.
+  */
+  getStream({
+    id
+  }: FileQuery): Promise<{
+    headers?: Record<string, string>;
+    size?: number;
+    stream: Readable;
+  }>;
+  /**
+  * Retrieves a list of uploaded files.
+  * @param _limit Maximum number of files to return (default: 1000).
+  * @returns Promise resolving to an array of file metadata objects.
+  * @throws {Error} If not implemented by the storage backend.
+  * @remarks Storage implementations must override this method.
+  */
+  list(_limit?: number): Promise<TFile[]>;
+  /**
+  * Updates file metadata with user-provided key-value pairs.
+  * @param query File query containing the file ID to update.
+  * @param query.id File ID to update.
+  * @param metadata Partial file object containing fields to update.
+  * @returns Promise resolving to the updated file object.
+  * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND).
+  * @remarks
+  * Supports TTL (time-to-live) option: if metadata contains a 'ttl' field,
+  * it will be converted to an 'expiredAt' timestamp.
+  * TTL can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
+  */
+  update({
+    id
+  }: FileQuery, metadata: Partial<File>): Promise<TFile>;
+  /**
+  * Creates a new upload and saves its metadata.
+  * @param file File initialization configuration.
+  * @returns Promise resolving to the created file object.
+  */
+  abstract create(file: FileInit): Promise<TFile>;
+  /**
+  * Writes part and/or returns status of an upload.
+  * @param part File part, query, or full file object to write.
+  * @returns Promise resolving to the updated file object.
+  */
+  abstract write(part: FilePart | FileQuery | TFile): Promise<TFile>;
+  /**
+  * 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.
+  */
+  abstract delete(query: FileQuery): Promise<TFile>;
+  /**
+  * Copies an upload file to a new location.
+  * @param name Source file name/ID.
+  * @param destination Destination file name/ID.
+  * @param options Optional copy options including storage class.
+  * @returns Promise resolving to the copied file object.
+  * @throws {UploadError} If the source file cannot be found.
+  */
+  abstract copy(name: string, destination: string, options?: {
+    storageClass?: 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 {UploadError} If the source file cannot be found.
+  */
+  abstract move(name: string, destination: string): Promise<TFile>;
+  /**
+  * Deletes multiple files in a single batch operation.
+  * @param ids Array of file IDs to delete.
+  * @returns Promise resolving to batch operation response with successful and failed deletions.
+  * @remarks
+  * Processes all deletions in parallel using Promise.allSettled.
+  * Individual failures do not stop the batch operation.
+  * Each deletion is wrapped in error handling to capture failures.
+  * Metrics are recorded for the batch operation and individual failures.
+  * Returns both successful and failed operations with detailed error information.
+  */
+  deleteBatch(ids: string[]): Promise<BatchOperationResponse<TFile>>;
+  /**
+  * Copies multiple files in a single batch operation.
+  * @param operations Array of copy operations, each containing:
+  * source: Source file ID.
+  * destination: Destination file ID or path.
+  * options: Optional copy options including storage class.
+  * @returns Promise resolving to batch operation response with successful and failed copies.
+  * @remarks
+  * Processes all copies in parallel using Promise.allSettled.
+  * Individual failures do not stop the batch operation.
+  * Each copy operation is wrapped in error handling to capture failures.
+  * Metrics are recorded for the batch operation and individual failures.
+  * Returns both successful and failed operations with detailed error information.
+  */
+  copyBatch(operations: {
+    destination: string;
+    options?: {
+      storageClass?: string;
+    };
+    source: string;
+  }[]): Promise<BatchOperationResponse<TFile>>;
+  /**
+  * Moves multiple files in a single batch operation.
+  * @param operations Array of move operations, each containing:
+  * source: Source file ID.
+  * destination: Destination file ID or path.
+  * @returns Promise resolving to batch operation response with successful and failed moves.
+  * @remarks
+  * Processes all moves in parallel using Promise.allSettled.
+  * Individual failures do not stop the batch operation.
+  * Each move operation is wrapped in error handling to capture failures.
+  * Metrics are recorded for the batch operation and individual failures.
+  * Returns both successful and failed operations with detailed error information.
+  */
+  moveBatch(operations: {
+    destination: string;
+    source: string;
+  }[]): Promise<BatchOperationResponse<TFile>>;
+  /**
+  * Prevent upload from being accessed by multiple requests
+  */
+  protected lock(key: string): Promise<string>;
+  protected unlock(key: string): Promise<void>;
+  protected isUnsupportedChecksum(algorithm?: string): boolean;
+  protected startAutoPurge(purgeInterval: number): void;
+  protected updateTimestamps(file: TFile): TFile;
+  /**
+  * Instruments a storage operation with metrics and error tracking.
+  * @param operation Operation name (e.g., "create", "delete", "copy").
+  * @param function_ The operation function to execute.
+  * @param attributes Additional attributes to include in metrics.
+  * @returns Promise resolving to the operation result.
+  * @throws Re-throws any errors from the operation function.
+  * @remarks
+  * Records operation count, duration, and error metrics.
+  * Tracks file sizes for operations returning file objects.
+  * Error metrics include error messages for debugging.
+  * All public methods should use this wrapper for consistent instrumentation.
+  */
+  protected instrumentOperation<T>(operation: string, function_: () => Promise<T>, attributes?: Record<string, string | number>): Promise<T>;
+}
+export { RangeChecksum as A, BaseStorage as B, Cache as C, DiskStorageOptions as D, ERRORS as E, File as F, RangeHasher as G, HttpError as H, IncomingMessageWithBody as I, ResponseBody as J, ResponseTuple as K, LocalMetaStorageOptions as L, MetaStorage as M, ValidationError as N, OnComplete as O, PurgeList as P, ValidatorConfig as Q, RetryConfig as R, defaultCloudStorageFileNameValidation as S, defaultFilesystemFileNameValidation as T, UploadFile as U, Validation as V, isRetryableError as W, isUploadError as X, retry as Y, throwErrorCode as Z, FileReturn as a, UploadError as b, UploadEventType as c, createRetryWrapper as d, FileInit as e, FilePart as f, FileQuery as g, DiskStorageWithChecksumOptions as h, ResponseBodyType as i, ErrorResponses as j, BaseStorageOptions as k, UploadResponse as l, MetaStorageOptions as m, Metrics as n, BatchOperationResponse as o, BatchOperationResult as p, ErrorMap as q, ExpirationOptions as r, Header as s, Headers as t, HttpErrorBody as u, Metadata as v, OnCreate as w, OnDelete as x, OnError as y, OnUpdate as z };