@warlock.js/core 4.0.174 → 4.1.3

package/esm/storage/storage-file.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-file.mjs","names":[],"sources":["../../../../../../@warlock.js/core/src/storage/storage-file.ts"],"sourcesContent":["import { basename, dirname, extname } from \"path\";\nimport type { Readable } from \"stream\";\nimport type {\n  CloudStorageDriverContract,\n  CloudStorageFileData,\n  FileVisibility,\n  StorageDriverContract,\n  StorageFileData,\n  StorageFileInfo,\n} from \"./types\";\n\n/**\n * StorageFile class - OOP wrapper for storage file operations\n *\n * Provides a fluent interface for working with files in storage,\n * wrapping the underlying driver operations.\n *\n * @example\n * ```typescript\n * const file = await storage.put(buffer, \"uploads/image.jpg\");\n *\n * // Properties (sync, from cached data)\n * file.name        // \"image.jpg\"\n * file.extension   // \"jpg\"\n * file.path        // \"uploads/image.jpg\"\n * file.hash        // \"sha256:abc123...\"\n *\n * // Operations\n * await file.copy(\"uploads/backup.jpg\")\n * await file.move(\"archive/image.jpg\")\n * await file.delete()\n *\n * // Content\n * const buffer = await file.contents();\n * const stream = await file.stream();\n * ```\n */\nexport class StorageFile {\n  /**\n   * Relative file path\n   */\n  protected _path: string;\n\n  /**\n   * The driver instance\n   */\n  protected _driver: StorageDriverContract;\n\n  /**\n   * Cached file data (from put operations or lazy loaded)\n   */\n  protected _data?: StorageFileData;\n\n  /**\n   * Whether the file has been deleted\n   */\n  protected _deleted = false;\n\n  /**\n   * Create a new StorageFile instance\n   *\n   * @param path - Relative file path\n   * @param driver - Driver instance\n   * @param data - Optional initial data from put/copy operations\n   */\n  public constructor(path: string, driver: StorageDriverContract, data?: StorageFileData) {\n    this._path = path;\n    this._driver = driver;\n    this._data = data;\n  }\n\n  // ============================================================\n  // Properties\n  // ============================================================\n\n  /**\n   * Get the relative file path\n   */\n  public get path(): string {\n    return this._path;\n  }\n\n  /**\n   * Get the file name (with extension)\n   */\n  public get name(): string {\n    return basename(this._path);\n  }\n\n  /**\n   * Get the file extension (without dot)\n   */\n  public get extension(): string {\n    return extname(this._path).slice(1).toLowerCase();\n  }\n\n  /**\n   * Get the directory path\n   */\n  public get directory(): string {\n    return dirname(this._path);\n  }\n\n  /**\n   * Get the driver name\n   */\n  public get driver(): string {\n    return this._driver.name;\n  }\n\n  /**\n   * Check if file has been deleted\n   */\n  public get isDeleted(): boolean {\n    return this._deleted;\n  }\n\n  /**\n   * Get public URL (sync if data cached, otherwise computed)\n   */\n  public get url(): string {\n    this.ensureNotDeleted();\n    return this._data?.url || this._driver.url(this._path);\n  }\n\n  /**\n   * Get the absolute filesystem path (local driver only)\n   */\n  public get absolutePath(): string | undefined {\n    this.ensureNotDeleted();\n    if (\"path\" in this._driver && typeof this._driver.path === \"function\") {\n      return this._driver.path(this._path);\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Get file hash (SHA-256, available from put operations)\n   */\n  public get hash(): string | undefined {\n    return this._data?.hash;\n  }\n\n  // ============================================================\n  // Data Methods (Lazy Loaded)\n  // ============================================================\n\n  /**\n   * Get cached file data, or fetch it if not available\n   */\n  public async data(): Promise<StorageFileData> {\n    this.ensureNotDeleted();\n    if (!this._data) {\n      // Fetch info and construct data\n      const info = await this.metadata();\n      this._data = {\n        path: info.path,\n        url: this._driver.url(this._path),\n        size: info.size,\n        hash: \"\", // Not available from metadata\n        mimeType: info.mimeType || \"application/octet-stream\",\n        driver: this._driver.name,\n      };\n    }\n    return this._data;\n  }\n\n  /**\n   * Get file size in bytes\n   */\n  public async size(): Promise<number> {\n    const data = await this.data();\n    return data.size;\n  }\n\n  /**\n   * Get MIME type\n   */\n  public async mimeType(): Promise<string> {\n    const data = await this.data();\n    return data.mimeType;\n  }\n\n  /**\n   * Get last modified date (fetches from driver)\n   */\n  public async lastModified(): Promise<Date | undefined> {\n    this.ensureNotDeleted();\n    const info = await this.metadata();\n    return info.lastModified;\n  }\n\n  /**\n   * Get ETag (cloud drivers, fetches from driver)\n   */\n  public async etag(): Promise<string | undefined> {\n    this.ensureNotDeleted();\n    const info = await this.metadata();\n    return info.etag;\n  }\n\n  // ============================================================\n  // Content Methods\n  // ============================================================\n\n  /**\n   * Get file contents as Buffer\n   */\n  public async contents(): Promise<Buffer> {\n    this.ensureNotDeleted();\n    return this._driver.get(this._path);\n  }\n\n  /**\n   * Get file contents as readable stream\n   */\n  public async stream(): Promise<Readable> {\n    this.ensureNotDeleted();\n    return this._driver.getStream(this._path);\n  }\n\n  /**\n   * Get file contents as UTF-8 text\n   */\n  public async text(): Promise<string> {\n    const buffer = await this.contents();\n    return buffer.toString(\"utf-8\");\n  }\n\n  /**\n   * Get file contents as base64 string\n   */\n  public async base64(): Promise<string> {\n    const buffer = await this.contents();\n    return buffer.toString(\"base64\");\n  }\n\n  /**\n   * Get file contents as data URL\n   */\n  public async dataUrl(): Promise<string> {\n    const [buffer, data] = await Promise.all([this.contents(), this.data()]);\n    return `data:${data.mimeType};base64,${buffer.toString(\"base64\")}`;\n  }\n\n  // ============================================================\n  // URL Methods\n  // ============================================================\n\n  /**\n   * Get a temporary signed URL\n   *\n   * @param expiresIn - Seconds until expiration (default: 3600)\n   */\n  public async temporaryUrl(expiresIn = 3600): Promise<string> {\n    this.ensureNotDeleted();\n    return this._driver.temporaryUrl(this._path, expiresIn);\n  }\n\n  // ============================================================\n  // File Operations\n  // ============================================================\n\n  /**\n   * Check if the file exists\n   */\n  public async exists(): Promise<boolean> {\n    if (this._deleted) return false;\n    return this._driver.exists(this._path);\n  }\n\n  /**\n   * Copy the file to a new location\n   *\n   * @param destination - Destination path\n   * @returns New StorageFile instance at destination\n   */\n  public async copy(destination: string): Promise<StorageFile> {\n    this.ensureNotDeleted();\n    const result = await this._driver.copy(this._path, destination);\n    return new StorageFile(destination, this._driver, result);\n  }\n\n  /**\n   * Move the file to a new location\n   *\n   * @param destination - Destination path\n   * @returns This StorageFile instance with updated path\n   */\n  public async move(destination: string): Promise<this> {\n    this.ensureNotDeleted();\n    const result = await this._driver.move(this._path, destination);\n    this._path = destination;\n    this._data = result; // Update cached data\n    return this;\n  }\n\n  /**\n   * Rename the file (move within same directory)\n   *\n   * @param newName - New file name\n   * @returns This StorageFile instance with updated path\n   */\n  public async rename(newName: string): Promise<this> {\n    const newPath = this.directory === \".\" ? newName : `${this.directory}/${newName}`;\n    return this.move(newPath);\n  }\n\n  /**\n   * Delete the file\n   *\n   * @returns true if deleted, false if not found\n   */\n  public async delete(): Promise<boolean> {\n    this.ensureNotDeleted();\n    const result = await this._driver.delete(this._path);\n    this._deleted = true;\n    return result;\n  }\n\n  // ============================================================\n  // Cloud-Specific Methods\n  // ============================================================\n\n  /**\n   * Set file visibility (cloud drivers only)\n   *\n   * @param visibility - \"public\" or \"private\"\n   * @throws Error if driver doesn't support visibility\n   */\n  public async setVisibility(visibility: FileVisibility): Promise<this> {\n    this.ensureNotDeleted();\n\n    if (!(\"setVisibility\" in this._driver)) {\n      throw new Error(\"setVisibility is only available for cloud storage drivers\");\n    }\n\n    await (this._driver as CloudStorageDriverContract).setVisibility(this._path, visibility);\n    return this;\n  }\n\n  /**\n   * Get file visibility (cloud drivers only)\n   *\n   * @throws Error if driver doesn't support visibility\n   */\n  public async getVisibility(): Promise<FileVisibility> {\n    this.ensureNotDeleted();\n\n    if (!(\"getVisibility\" in this._driver)) {\n      throw new Error(\"getVisibility is only available for cloud storage drivers\");\n    }\n\n    return (this._driver as CloudStorageDriverContract).getVisibility(this._path);\n  }\n\n  /**\n   * Set storage class (cloud drivers only)\n   *\n   * @param storageClass - Storage class (e.g., \"STANDARD\", \"GLACIER\")\n   * @throws Error if driver doesn't support storage class\n   */\n  public async setStorageClass(storageClass: string): Promise<this> {\n    this.ensureNotDeleted();\n\n    if (!(\"setStorageClass\" in this._driver)) {\n      throw new Error(\"setStorageClass is only available for cloud storage drivers\");\n    }\n\n    await (this._driver as CloudStorageDriverContract).setStorageClass(this._path, storageClass);\n    return this;\n  }\n\n  // ============================================================\n  // Utilities\n  // ============================================================\n\n  /**\n   * Ensure the file has not been deleted\n   */\n  protected ensureNotDeleted(): void {\n    if (this._deleted) {\n      throw new Error(`File \"${this._path}\" has been deleted`);\n    }\n  }\n\n  /**\n   * Create a StorageFile instance from StorageFileData\n   *\n   * @param data - Storage file data from put/copy/move operations\n   * @param driver - Driver instance\n   */\n  public static fromData(\n    data: StorageFileData | CloudStorageFileData,\n    driver: StorageDriverContract,\n  ): StorageFile {\n    return new StorageFile(data.path, driver, data);\n  }\n\n  /**\n   * Get file metadata\n   */\n  public async metadata(): Promise<StorageFileInfo> {\n    this.ensureNotDeleted();\n    return this._driver.metadata(this._path);\n  }\n\n  /**\n   * Determine if this file is an image type\n   */\n  public async isImage() {\n    const metadata = await this.metadata();\n    return metadata.mimeType!.startsWith(\"image/\");\n  }\n\n  /**\n   * Determine if this file is a document type\n   */\n  public async isDocument() {\n    const metadata = await this.metadata();\n    return metadata.mimeType!.startsWith(\"application/\");\n  }\n\n  /**\n   * Determine if this file is a pdf type\n   */\n  public async isPdf() {\n    const metadata = await this.metadata();\n    return metadata.mimeType!.startsWith(\"application/pdf\");\n  }\n\n  /**\n   * Determine if this file is an excel file (any support excel file)\n   */\n  public async isExcel() {\n    const metadata = await this.metadata();\n    return (\n      metadata.mimeType!.startsWith(\n        \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n      ) || metadata.mimeType!.startsWith(\"application/vnd.ms-excel\")\n    );\n  }\n\n  /**\n   * Determine if this file is a doc file\n   */\n  public async isDoc() {\n    const metadata = await this.metadata();\n    return (\n      metadata.mimeType!.startsWith(\"application/msword\") ||\n      metadata.mimeType!.startsWith(\n        \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      )\n    );\n  }\n\n  /**\n   * Determine if this file is an audio type\n   */\n  public async isAudio() {\n    const metadata = await this.metadata();\n    return metadata.mimeType!.startsWith(\"audio/\");\n  }\n\n  /**\n   * Determine if this file is a video type\n   */\n  public async isVideo() {\n    const metadata = await this.metadata();\n    return metadata.mimeType!.startsWith(\"video/\");\n  }\n\n  /**\n   * Convert to plain object (returns cached data or constructs it)\n   */\n  public toJSON(): {\n    path: string;\n    name: string;\n    extension: string;\n    driver: string;\n    url: string;\n    hash?: string;\n    size?: number;\n    mimeType?: string;\n  } {\n    return {\n      path: this._path,\n      name: this.name,\n      extension: this.extension,\n      driver: this._driver.name,\n      url: this._deleted ? \"\" : this.url,\n      hash: this._data?.hash,\n      size: this._data?.size,\n      mimeType: this._data?.mimeType,\n    };\n  }\n\n  /**\n   * String representation\n   */\n  public toString(): string {\n    return this._path;\n  }\n}\n"],"mappings":"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"}

package/esm/storage/storage.d.mts

@@ -0,0 +1,578 @@
+import { StorageFile } from "./storage-file.mjs";
+import { CloudStorageDriverContract, CloudStorageDriverOptions, DeleteManyResult, FileVisibility, ListOptions, LocalStorageDriverOptions, PresignedOptions, PresignedUploadOptions, PutOptions, R2StorageDriverOptions, ScopedStorageContract, StorageDriverConfig, StorageDriverContract, StorageDriverName, StorageEventHandler, StorageEventPayload, StorageEventType, StorageFileInfo, StorageManagerContract, TemporaryTokenValidation } from "./types.mjs";
+import { ScopedStorage } from "./scoped-storage.mjs";
+import { UploadedFile } from "../http/uploaded-file.mjs";
+import { EventSubscription } from "@mongez/events";
+import { Readable } from "stream";
+
+//#region ../../@warlock.js/core/src/storage/storage.d.ts
+/**
+ * Storage Manager
+ *
+ * Provides a unified interface for file storage operations across multiple
+ * drivers (local, S3, R2, DigitalOcean Spaces). Extends `ScopedStorage` to
+ * inherit all base operations while adding driver management and events.
+ *
+ * All operations return `StorageFile` instances for a consistent, rich DX.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (uses default driver)
+ * const file = await storage.put(buffer, "uploads/image.jpg");
+ *
+ * // With options
+ * const file = await storage.put(buffer, "uploads/image.jpg", {
+ *   mimeType: "image/jpeg",
+ *   cacheControl: "max-age=31536000"
+ * });
+ *
+ * // Using specific driver (also returns StorageFile)
+ * const file = await storage.use("s3").put(buffer, "path/to/file");
+ *
+ * // Get raw driver for advanced use
+ * const driver = storage.driver("s3");
+ * const data = await driver.put(buffer, "path/to/file"); // Returns StorageFileData
+ *
+ * // Stream operations for large files
+ * const stream = await storage.getStream("large-file.zip");
+ * await storage.putStream(readableStream, "output/file.zip");
+ *
+ * // Batch operations
+ * const results = await storage.deleteMany(["file1.txt", "file2.txt"]);
+ *
+ * // Event hooks
+ * storage.on("afterPut", ({ location, file }) => {
+ *   console.log(`Uploaded ${location}`);
+ * });
+ * ```
+ */
+declare class Storage extends ScopedStorage implements StorageManagerContract {
+  /**
+   * Registered drivers (cached instances)
+   * @internal
+   */
+  protected drivers: Map<string, StorageDriverContract>;
+  /**
+   * Driver configurations
+   * @internal
+   */
+  protected configs: Map<string, StorageDriverConfig>;
+  /**
+   * Default driver name
+   * @internal
+   */
+  protected defaultDriverName: StorageDriverName;
+  /**
+   * Whether the storage has been initialized
+   * @internal
+   */
+  private initialized;
+  /**
+   * Create a new Storage manager instance
+   *
+   * Uses lazy initialization - driver is resolved on first access.
+   */
+  constructor();
+  /**
+   * Ensure storage is initialized (lazy initialization)
+   *
+   * Called automatically on first driver access.
+   */
+  init(): Promise<void>;
+  /**
+   * Reset storage defaults
+   */
+  reset(): void;
+  /**
+   * Get the currently active driver (context-aware in future)
+   *
+   * Currently returns the default driver.
+   * Will be enhanced to check AsyncLocalStorage context for multi-tenant support.
+   *
+   * @returns The active storage driver
+   */
+  get activeDriver(): StorageDriverContract;
+  /**
+   * Load drivers from configuration
+   * @internal
+   */
+  protected loadDriversFromConfig(): void;
+  /**
+   * Get a scoped storage for a specific driver
+   *
+   * Returns a `ScopedStorage` instance that wraps the specified driver.
+   * Operations on the returned instance also return `StorageFile` objects.
+   *
+   * @param name - Driver name as defined in configuration
+   * @returns ScopedStorage instance for the specified driver
+   *
+   * @example
+   * ```typescript
+   * // Upload to S3
+   * const s3File = await storage.use("s3").put(buffer, "images/photo.jpg");
+   *
+   * // Upload to local
+   * const localFile = await storage.use("local").put(buffer, "temp/file.txt");
+   *
+   * // Both return StorageFile with identical API
+   * console.log(s3File.url);
+   * console.log(localFile.url);
+   * ```
+   */
+  use(name: StorageDriverName): ScopedStorageContract;
+  /**
+   * Get a raw driver instance
+   *
+   * Returns the underlying driver directly for advanced use cases.
+   * Unlike `use()`, calling methods on the raw driver returns
+   * `StorageFileData` instead of `StorageFile`.
+   *
+   * @param name - Driver name as defined in configuration
+   * @returns Raw driver instance implementing StorageDriverContract
+   *
+   * @example
+   * ```typescript
+   * const driver = storage.getDriver("s3");
+   * const data = await driver.put(buffer, "path/to/file");
+   * // data is StorageFileData, not StorageFile
+   * ```
+   */
+  getDriver(name: StorageDriverName): StorageDriverContract;
+  /**
+   * Get root directory of current driver
+   */
+  root(apepndedPath?: string): string;
+  /**
+   * Use a cloud storage driver with extended cloud capabilities
+   *
+   * @param name - Cloud driver name (s3, r2, spaces)
+   * @returns Driver instance implementing CloudStorageDriverContract
+   * @throws Error if driver doesn't support cloud operations
+   *
+   * @example
+   * ```typescript
+   * const cloudDriver = storage.useCloud("s3");
+   * const presignedUrl = await cloudDriver.getPresignedUrl("private/doc.pdf");
+   * ```
+   */
+  useCloud(name: StorageDriverName): CloudStorageDriverContract;
+  /**
+   * Register a new driver configuration at runtime
+   *
+   * Allows dynamic driver registration for multi-tenancy or
+   * runtime configuration scenarios.
+   *
+   * @param name - Unique driver name
+   * @param config - Driver configuration
+   * @returns This instance for chaining
+   *
+   * @example
+   * ```typescript
+   * storage.register("tenant-s3", {
+   *   driver: "s3",
+   *   bucket: "tenant-bucket",
+   *   region: "us-east-1",
+   *   accessKeyId: process.env.TENANT_AWS_KEY,
+   *   secretAccessKey: process.env.TENANT_AWS_SECRET
+   * });
+   *
+   * await storage.use("tenant-s3").put(buffer, "file.txt");
+   * ```
+   */
+  register(name: StorageDriverName, config: StorageDriverConfig): this;
+  /**
+   * Set the default driver name
+   *
+   * @param name - Driver name to use as default
+   * @returns This instance for chaining
+   *
+   * @example
+   * ```typescript
+   * storage.setDefault("s3");
+   * await storage.put(buffer, "file.txt"); // Now uses S3
+   * ```
+   */
+  setDefault(name: StorageDriverName): this;
+  /**
+   * Check if current driver is a cloud driver
+   *
+   * @returns Promise resolving to true if the current driver supports cloud operations
+   */
+  isCloud(): Promise<boolean>;
+  /**
+   * Check if a driver instance supports cloud operations
+   * @internal
+   */
+  protected isCloudDriver(driver: StorageDriverContract): driver is CloudStorageDriverContract;
+  /**
+   * Register an event handler
+   *
+   * Subscribe to storage events for logging, analytics, or side effects.
+   *
+   * @param event - Event type to listen for
+   * @param handler - Handler function
+   * @returns Event subscription for unsubscribing
+   *
+   * @example
+   * ```typescript
+   * // Log all uploads
+   * storage.on("afterPut", ({ location, file }) => {
+   *   console.log(`Uploaded ${file?.size} bytes to ${location}`);
+   * });
+   *
+   * // Track deletions
+   * storage.on("afterDelete", ({ location }) => {
+   *   analytics.track("file_deleted", { path: location });
+   * });
+   * ```
+   */
+  on<T extends StorageEventPayload = StorageEventPayload>(event: StorageEventType, handler: StorageEventHandler<T>): EventSubscription;
+  /**
+   * Remove all handlers for an event type
+   *
+   * @param event - Event type to remove handlers for
+   * @returns This instance for chaining
+   *
+   * @example
+   * ```typescript
+   * storage.off("afterPut"); // Remove all afterPut handlers
+   * ```
+   */
+  off(event: StorageEventType): this;
+  /**
+   * Emit an event to all registered handlers
+   * @internal
+   */
+  protected emit<T extends StorageEventPayload>(event: StorageEventType, payload: T): Promise<void>;
+  /**
+   * Store a file in storage
+   *
+   * Extends base `put()` with event emission for beforePut/afterPut hooks.
+   *
+   * @param file - File content as Buffer, string, UploadedFile, or Readable stream
+   * @param location - Destination path
+   * @param options - Storage options (mimeType, cacheControl, etc.)
+   * @returns StorageFile instance with cached metadata
+   */
+  put(file: UploadedFile | Buffer | string | Readable, location: string, options?: PutOptions): Promise<StorageFile>;
+  /**
+   * Store a file from a readable stream (for large files)
+   *
+   * Extends base `putStream()` with event emission.
+   *
+   * @param stream - Readable stream
+   * @param location - Destination path
+   * @param options - Storage options
+   * @returns StorageFile instance with cached metadata
+   */
+  putStream(stream: Readable | string, location: string, options?: PutOptions): Promise<StorageFile>;
+  /**
+   * Store a file from a URL
+   *
+   * Downloads content from the URL and stores it at the specified location.
+   *
+   * @param url - Source URL to download from
+   * @param location - Destination path
+   * @param options - Storage options
+   * @returns StorageFile instance with cached metadata
+   *
+   * @example
+   * ```typescript
+   * const file = await storage.putFromUrl(
+   *   "https://example.com/image.jpg",
+   *   "downloads/image.jpg"
+   * );
+   * ```
+   */
+  putFromUrl(url: string, location: string, options?: PutOptions): Promise<StorageFile>;
+  /**
+   * Store a file from base64 encoded string
+   *
+   * Decodes base64 content (with optional data URL prefix) and stores it.
+   *
+   * @param base64 - Base64 encoded file content (or data URL)
+   * @param location - Destination path
+   * @param options - Storage options
+   * @returns StorageFile instance with cached metadata
+   *
+   * @example
+   * ```typescript
+   * // From plain base64
+   * const file = await storage.putFromBase64(base64String, "images/photo.jpg");
+   *
+   * // From data URL (auto-extracts MIME type)
+   * const file = await storage.putFromBase64(
+   *   "data:image/png;base64,iVBORw0KGgo...",
+   *   "images/photo.png"
+   * );
+   * ```
+   */
+  putFromBase64(base64: string, location: string, options?: PutOptions): Promise<StorageFile>;
+  /**
+   * Retrieve file contents as Buffer
+   *
+   * Uses the current driver (with async resolution).
+   *
+   * @param location - File path
+   * @returns Buffer containing file contents
+   */
+  get(location: string): Promise<Buffer>;
+  /**
+   * Get JSON content from a file
+   *
+   * Downloads and parses JSON file content.
+   *
+   * @param location - File path
+   * @returns Parsed JSON content
+   *
+   * @example
+   * ```typescript
+   * const config = await storage.getJson("config/settings.json");
+   * console.log(config.apiKey);
+   * ```
+   */
+  getJson(location: string): Promise<any>;
+  /**
+   * Retrieve a file as a readable stream (for large files)
+   *
+   * @param location - File path
+   * @returns Readable stream of file contents
+   */
+  getStream(location: string): Promise<Readable>;
+  /**
+   * Delete a file
+   *
+   * Extends base `delete()` with event emission.
+   *
+   * @param location - File path or StorageFile
+   * @returns true if deleted, false if not found
+   */
+  delete(location: string | StorageFile): Promise<boolean>;
+  /**
+   * Delete multiple files at once
+   *
+   * @param locations - Array of file paths
+   * @returns Array of delete results with status for each file
+   */
+  deleteMany(locations: string[]): Promise<DeleteManyResult[]>;
+  /**
+   * Check if a file exists
+   *
+   * @param location - File path
+   * @returns true if file exists
+   */
+  exists(location: string): Promise<boolean>;
+  /**
+   * Copy a file to a new location
+   *
+   * Extends base `copy()` with event emission.
+   *
+   * @param from - Source path or StorageFile
+   * @param to - Destination path
+   * @returns StorageFile instance at destination
+   */
+  copy(from: string | StorageFile, to: string): Promise<StorageFile>;
+  /**
+   * Move a file to a new location
+   *
+   * Extends base `move()` with event emission.
+   *
+   * @param from - Source path or StorageFile
+   * @param to - Destination path
+   * @returns StorageFile instance at destination
+   */
+  move(from: string | StorageFile, to: string): Promise<StorageFile>;
+  /**
+   * List files in a directory
+   *
+   * @param directory - Directory path (defaults to root)
+   * @param options - List options (recursive, limit, etc.)
+   * @returns Array of file information objects
+   */
+  list(directory?: string, options?: ListOptions): Promise<StorageFileInfo[]>;
+  /**
+   * Get file metadata without downloading
+   *
+   * @param location - File path
+   * @returns File information object
+   */
+  metadata(location: string): Promise<StorageFileInfo>;
+  /**
+   * Get file size in bytes
+   *
+   * @param location - File path
+   * @returns File size in bytes
+   */
+  size(location: string): Promise<number>;
+  /**
+   * Get the absolute filesystem path for a location
+   *
+   * Only available for local driver.
+   *
+   * @param location - File path
+   * @throws Error if current driver is not a local driver
+   * @returns Absolute filesystem path
+   */
+  path(location: string): Promise<string>;
+  /**
+   * Get a presigned URL for downloading a file
+   *
+   * Only available for cloud drivers.
+   *
+   * @param location - File path
+   * @param options - Presigned URL options (expiresIn)
+   * @throws Error if current driver is not a cloud driver
+   * @returns Presigned download URL
+   *
+   * @example
+   * ```typescript
+   * const url = await storage.getPresignedUrl("private/document.pdf", {
+   *   expiresIn: 3600 // 1 hour
+   * });
+   * ```
+   */
+  getPresignedUrl(location: string, options?: PresignedOptions): Promise<string>;
+  /**
+   * Get a presigned URL for uploading a file directly to cloud storage
+   *
+   * Only available for cloud drivers.
+   *
+   * @param location - Destination path
+   * @param options - Upload options (expiresIn, contentType, maxSize)
+   * @throws Error if current driver is not a cloud driver
+   * @returns Presigned upload URL
+   *
+   * @example
+   * ```typescript
+   * const uploadUrl = await storage.getPresignedUploadUrl("uploads/file.pdf", {
+   *   expiresIn: 3600,
+   *   contentType: "application/pdf"
+   * });
+   *
+   * // Client can PUT directly to this URL
+   * ```
+   */
+  getPresignedUploadUrl(location: string, options?: PresignedUploadOptions): Promise<string>;
+  /**
+   * Get the bucket name for cloud storage
+   *
+   * Only available for cloud drivers.
+   *
+   * @throws Error if current driver is not a cloud driver
+   * @returns Bucket name
+   */
+  getBucket(): Promise<string>;
+  /**
+   * Get the region for cloud storage
+   *
+   * Only available for cloud drivers.
+   *
+   * @throws Error if current driver is not a cloud driver
+   * @returns Region name
+   */
+  getRegion(): Promise<string>;
+  /**
+   * Set storage class for a file (e.g., STANDARD, GLACIER, etc.)
+   *
+   * Only available for cloud drivers.
+   *
+   * @param location - File path
+   * @param storageClass - Target storage class
+   * @throws Error if current driver is not a cloud driver
+   */
+  setStorageClass(location: string, storageClass: string): Promise<void>;
+  /**
+   * Set file visibility (public or private)
+   *
+   * Only available for cloud drivers.
+   *
+   * @param location - File path
+   * @param visibility - "public" or "private"
+   * @throws Error if current driver is not a cloud driver
+   */
+  setVisibility(location: string, visibility: FileVisibility): Promise<void>;
+  /**
+   * Get file visibility
+   *
+   * Only available for cloud drivers.
+   *
+   * @param location - File path
+   * @throws Error if current driver is not a cloud driver
+   * @returns Current visibility setting
+   */
+  getVisibility(location: string): Promise<FileVisibility>;
+  /**
+   * Get a temporary signed URL
+   *
+   * Creates a URL that provides temporary access to the file.
+   *
+   * @param location - File path
+   * @param expiresIn - Seconds until expiration (default: 3600)
+   * @returns Signed URL string
+   */
+  temporaryUrl(location: string, expiresIn?: number): Promise<string>;
+  /**
+   * Validate a temporary URL token
+   *
+   * For local driver: validates HMAC-signed tokens
+   * For cloud drivers: returns invalid (cloud validates via presigned URL)
+   *
+   * @param token - The token from the temporary URL
+   * @returns Validation result with file info and convenience methods
+   *
+   * @example
+   * ```typescript
+   * const result = await storage.validateTemporaryToken(token);
+   *
+   * if (!result.valid) {
+   *   return response.status(403).send(result.error);
+   * }
+   *
+   * // For local driver - use sendFile for efficiency
+   * if (result.absolutePath) {
+   *   return response.sendFile(result.absolutePath);
+   * }
+   *
+   * // For cloud driver - stream the file
+   * const stream = await result.getStream!();
+   * stream.pipe(response.raw);
+   * ```
+   */
+  validateTemporaryToken(token: string): Promise<TemporaryTokenValidation>;
+  /**
+   * Parse config into driver-specific options
+   * @internal
+   */
+  protected parseOptions(config: StorageDriverConfig): LocalStorageDriverOptions | CloudStorageDriverOptions | R2StorageDriverOptions;
+  /**
+   * Validate cloud driver configuration has required fields
+   * @internal
+   */
+  protected validateCloudConfig(config: StorageDriverConfig, driverName: string): void;
+  /**
+   * Get or create driver instance from cache
+   * @internal
+   */
+  protected resolveDriver(name: string): StorageDriverContract;
+  /**
+   * Resolve the default driver name (supports async resolver for multi-tenancy)
+   * @internal
+   */
+  protected resolveDefaultDriver(): Promise<StorageDriverName>;
+}
+/**
+ * Singleton storage instance
+ *
+ * Pre-configured storage manager ready for use throughout the application.
+ *
+ * @example
+ * ```typescript
+ * import { storage } from "@warlock.js/core";
+ *
+ * const file = await storage.put(buffer, "uploads/file.txt");
+ * ```
+ */
+declare const storage: Storage;
+//#endregion
+export { Storage, storage };
+//# sourceMappingURL=storage.d.mts.map

package/esm/storage/storage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.mts","names":[],"sources":["../../../../../../@warlock.js/core/src/storage/storage.ts"],"mappings":"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"}