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

package/dist/packem_shared/storage.d-RteRC-cG.d.ts

@@ -0,0 +1,1106 @@
+import { Transform, Readable } from 'node:stream';
+import { BinaryToTextEncoding, Hash } from 'node:crypto';
+import { IncomingMessage } from 'node:http';
+import { LRUCache } from 'lru-cache';
+/**
+* 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>;
+  /**
+  * Optional. Iterate over the cache's current keys. Required for prefix-based
+  * eviction (`clearCache(fileId)` in transformers) — when absent, per-file
+  * clear falls back to a full `clear()`. `LRUCache` from `lru-cache`
+  * satisfies this out of the box.
+  */
+  keys?: () => Iterable<K>;
+  /** 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;
+}
+/**
+* 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;
+/**
+* Best-effort extraction of an HTTP status from a native SDK error.
+*
+* Covers the shapes used by the consumer-provider SDKs:
+* - Dropbox `DropboxResponseError` → `error.status`
+* - Box `BoxAPIError` / Microsoft Graph errors → `error.statusCode`
+* - googleapis errors → `error.code` (numeric) or `error.response.status`
+* - Supabase / fetch-style errors → `error.status` or `error.response.status`
+*/
+declare const extractHttpStatus: (error: unknown) => number | undefined;
+/**
+* Map an HTTP status code to the closest canonical ERRORS value.
+*
+* Returns STORAGE_ERROR for unknown/5xx and BAD_REQUEST for unmapped 4xx.
+* 401 (unauthenticated) collapses to FORBIDDEN because the ERRORS enum has
+* no dedicated UNAUTHORIZED value; callers needing to distinguish the two
+* should inspect the native error on `UploadError.detail`.
+*/
+declare const mapStatusToErrorCode: (status?: number) => ERRORS;
+/**
+* Normalize a native storage-SDK error into an `UploadError`.
+*
+* The native error is preserved on `.detail` so advanced callers can drop down
+* to provider-specific shapes when needed. Already-wrapped `UploadError`
+* instances pass through unchanged.
+* @example
+* ```ts
+* try {
+*     await client.filesCopyV2({ from_path, to_path });
+* } catch (error) {
+*     throw wrapStorageError(error, { adapter: "Dropbox", operation: "copy" });
+* }
+* ```
+*/
+declare const wrapStorageError: (error: unknown, options: {
+  adapter: string;
+  code?: ERRORS;
+  message?: string;
+  operation: string;
+  status?: number;
+}) => 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;
+/**
+* A simple lock map keyed by strings, backed by LRUCache. Locks
+* automatically expire according to the configured TTL preventing deadlocks.
+*
+* Each successful `lock()` returns a unique token; the corresponding `unlock(key, token)`
+* call only releases the lock when the token matches the current holder. This prevents a
+* stale lock owner (e.g. one whose entry TTL'd out and was re-acquired by another caller)
+* from releasing another caller's lock by accident.
+*/
+declare class Locker<K extends string = string> extends LRUCache<K, string, number> {
+  constructor(options?: LRUCache.Options<K, string, number>);
+  /**
+  * Acquires a lock for the specified key.
+  * @returns A unique token identifying the lock holder.
+  * @throws Error if the key is already locked.
+  */
+  lock(key: K): string;
+  /**
+  * Releases the lock for the specified key, but only if the token matches the current holder.
+  * Silently no-ops when the lock has expired or is owned by someone else — releasing somebody
+  * else's lock is worse than leaving a stale entry to TTL out on its own.
+  * @returns true if the lock was released, false if it was already gone or owned by another caller.
+  */
+  unlock(key: K, token: string): boolean;
+}
+/**
+* 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>;
+/**
+* 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>;
+}
+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;
+  /**
+  * Explicit identifier. When provided, the File constructor uses it directly
+  * instead of deriving an id from originalName/size/mtime. Lets callers map a
+  * user-chosen storage key (e.g. `"avatars/abc.png"`) onto the metadata id.
+  */
+  id?: string;
+  metadata: Metadata;
+  originalName?: string;
+  size?: number | string;
+  storageClass?: string;
+  ttl?: number | string;
+}
+interface FileReturn extends Omit<Required<FileInit>, "id" | "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,
+    id,
+    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;
+}
+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[];
+  /**
+  * Default abort signal merged into every operation. A per-call
+  * `OperationOptions.signal` is combined with this, not replaced — either
+  * one aborts the call. Note this signal lives for the storage instance's
+  * lifetime: once it aborts, every subsequent operation fails fast.
+  */
+  defaultSignal?: AbortSignal;
+  /**
+  * Default per-operation timeout in milliseconds, applied per retry
+  * attempt when a call omits `OperationOptions.timeout`. A per-call
+  * `timeout` (including `0` to explicitly disable) takes precedence.
+  */
+  defaultTimeout?: number;
+  /** Logger instance */
+  logger?: Console;
+  /** Maximum file size */
+  maxFileSize?: number | string;
+  /** Metrics instance for observability */
+  metrics?: Metrics;
+  /** Retry configuration for transient failures */
+  retryConfig?: RetryConfig;
+}
+/**
+* Per-operation overrides for cancellation, deadlines and retries.
+*
+* Threaded through the public storage operations down to the backend SDK call.
+* Backends that wrap an SDK with native cancellation honour `signal`/`timeout`
+* directly; backends without a cancellation primitive still fail fast at the
+* storage layer, but the provider request may continue in the background.
+*/
+interface OperationOptions {
+  /**
+  * Retry override for this call. A number is treated as `maxRetries`; an
+  * object is shallow-merged over the backend's configured `RetryConfig`.
+  * Aborted and timed-out operations are never retried regardless of this.
+  */
+  retries?: number | RetryConfig;
+  /**
+  * Abort the operation when this signal fires. Merged with any
+  * per-call `timeout` via `AbortSignal.any`.
+  */
+  signal?: AbortSignal;
+  /**
+  * Per-operation timeout in milliseconds. `0` or a negative value
+  * disables the timeout. Applied per retry attempt.
+  */
+  timeout?: number;
+}
+/**
+* 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>);
+  /**
+  * Escape hatch returning the underlying native client (S3Client, BlobServiceClient, etc.)
+  * for provider-specific operations not covered by the unified API.
+  * Returns `undefined` when no native client is available (e.g. DiskStorage).
+  */
+  get raw(): unknown;
+  /**
+  * Returns a presigned URL for downloading the object at `key`.
+  * Throws `ERRORS.METHOD_NOT_ALLOWED` when the adapter has no native presign support.
+  * @param _key Storage key.
+  * @param _options Optional expiry and response overrides.
+  */
+  getReadUrl(_key: string, _options?: {
+    expiresIn?: number;
+    responseContentDisposition?: string;
+    responseContentType?: string;
+  }): Promise<string>;
+  /**
+  * Returns a presigned URL for uploading a single object to `key`.
+  * Throws `ERRORS.METHOD_NOT_ALLOWED` when the adapter has no native presign support.
+  * @param _key Storage key.
+  * @param _options Optional content type, expiry, and content length hints.
+  */
+  getUploadUrl(_key: string, _options?: {
+    contentLength?: number;
+    contentType?: string;
+    expiresIn?: number;
+  }): Promise<string>;
+  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.
+  * @throws {UploadError} If `file.id` contains path-traversal sequences, null bytes, or is an absolute path — patterns that could let a local MetaStorage implementation write outside its directory.
+  */
+  saveMeta(file: TFile): Promise<TFile>;
+  /**
+  * Rejects ids containing `..` segments, null bytes, or absolute paths — defense-in-depth
+  * so any MetaStorage / facade / handler that uses `id` as part of a filesystem path or
+  * cross-bucket lookup can't be escaped. Public so the `Files` facade and Fetch handlers
+  * can validate user-supplied keys before any adapter call.
+  */
+  static assertSafeId(id: string): void;
+  /**
+  * 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.
+  * Returns a unique token that must be passed back to `unlock()` so a caller whose lock TTL'd
+  * out cannot accidentally release a newly-acquired lock held by another request.
+  */
+  protected lock(key: string): Promise<string>;
+  protected unlock(key: string, token?: string): Promise<void>;
+  /**
+  * Run a function while holding the lock for `key`. The lock is released even if `fn` throws,
+  * and only released when the caller still owns the lock (token-verified). Public so that
+  * handlers can serialize cross-call read-modify-write sequences on the same upload (e.g.
+  * appending to `_chunks` during chunked PATCH).
+  */
+  withLock<R>(key: string, function_: () => Promise<R>): Promise<R>;
+  protected isUnsupportedChecksum(algorithm?: string): boolean;
+  protected startAutoPurge(purgeInterval: number): void;
+  protected updateTimestamps(file: TFile): TFile;
+  /**
+  * Backend-resolved retry configuration that {@link runOperation} layers
+  * per-call overrides on top of. Subclasses that build a `RetryConfig`
+  * (S3, Azure, Netlify, …) override this; the default (`undefined`) makes
+  * `runOperation` fall back to the retry engine's own defaults.
+  */
+  protected getRetryConfig(): RetryConfig | undefined;
+  /**
+  * Runs a backend SDK call with per-operation cancellation, timeout and
+  * retry handling.
+  *
+  * The provided `signal` is the merge of the caller's `options.signal` and
+  * a fresh per-attempt `options.timeout` deadline (via `AbortSignal.any` /
+  * `AbortSignal.timeout`). Pass it to the underlying SDK so the provider
+  * request is actually cancelled rather than merely abandoned.
+  *
+  * Aborted or timed-out calls are never retried. Pass
+  * `{ replayable: false }` for operations whose body is a one-shot stream —
+  * a consumed `Readable`/`ReadableStream` cannot be safely re-sent, so the
+  * retry count is forced to zero.
+  * @param options Per-call overrides (`signal`, `timeout`, `retries`).
+  * @param function_ Receives the merged abort signal for the attempt.
+  * @param operationConfig `replayable: false` disables retries for non-replayable bodies.
+  */
+  protected runOperation<T>(options: OperationOptions | undefined, function_: (signal: AbortSignal | undefined) => Promise<T>, operationConfig?: {
+    replayable?: boolean;
+  }): Promise<T>;
+  /**
+  * 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 { throwErrorCode as $, RangeChecksum as A, BaseStorage as B, RangeHasher as C, DiskStorageOptions as D, ERRORS as E, File as F, ResponseBody as G, HttpError as H, IncomingMessageWithBody as I, ResponseTuple as J, UploadResponse as K, LocalMetaStorageOptions as L, MetaStorage as M, ValidationError as N, OperationOptions as O, PurgeList as P, ValidatorConfig as Q, RetryConfig as R, defaultCloudStorageFileNameValidation as S, defaultFilesystemFileNameValidation as T, UploadFile as U, Validation as V, extractHttpStatus as W, isRetryableError as X, isUploadError as Y, mapStatusToErrorCode as Z, retry as _, FileReturn as a, wrapStorageError as a0, Cache as a1, UploadError as b, UploadEventType as c, createRetryWrapper as d, FileInit as e, FilePart as f, FileQuery as g, DiskStorageWithChecksumOptions as h, BaseStorageOptions as i, ResponseBodyType as j, ErrorResponses as k, Metrics as l, BatchOperationResponse as m, BatchOperationResult as n, ErrorMap as o, ExpirationOptions as p, Header as q, Headers as r, HttpErrorBody as s, MetaStorageOptions as t, Metadata as u, OnComplete as v, OnCreate as w, OnDelete as x, OnError as y, OnUpdate as z };