@warlock.js/core 4.0.174 → 4.1.3

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

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-storage.mjs","names":["fs"],"sources":["../../../../../../@warlock.js/core/src/storage/scoped-storage.ts"],"sourcesContent":["import { fileExistsAsync } from \"@warlock.js/fs\";\r\nimport { createReadStream } from \"fs\";\r\nimport fs from \"fs/promises\";\r\nimport path from \"path\";\r\nimport type { Readable } from \"stream\";\r\nimport type { UploadedFile } from \"../http\";\r\nimport { StorageFile } from \"./storage-file\";\r\nimport type {\r\n  DeleteManyResult,\r\n  ListOptions,\r\n  PutDirectoryOptions,\r\n  PutDirectoryResult,\r\n  PutOptions,\r\n  ScopedStorageContract,\r\n  StorageDriverContract,\r\n  StorageDriverType,\r\n  StorageFileInfo,\r\n} from \"./types\";\r\n\r\n/**\r\n * ScopedStorage - Base class for storage operations\r\n *\r\n * Wraps a storage driver and provides a consistent, developer-friendly API\r\n * that returns `StorageFile` instances instead of raw data objects.\r\n *\r\n * This class serves as the base for both direct driver usage and the\r\n * full `Storage` manager class.\r\n *\r\n * @example\r\n * ```typescript\r\n * // Using via storage.use()\r\n * const s3Storage = storage.use(\"s3\");\r\n * const file = await s3Storage.put(buffer, \"images/photo.jpg\");\r\n *\r\n * // file is a StorageFile instance with rich API\r\n * console.log(file.name);       // \"photo.jpg\"\r\n * console.log(file.url);        // \"https://...\"\r\n * await file.copy(\"backup/photo.jpg\");\r\n * ```\r\n */\r\nexport class ScopedStorage implements ScopedStorageContract {\r\n  /**\r\n   * The underlying storage driver instance\r\n   * @internal\r\n   */\r\n  protected _driver: StorageDriverContract;\r\n\r\n  /**\r\n   * Create a new ScopedStorage instance\r\n   *\r\n   * @param driver - The storage driver to wrap\r\n   */\r\n  public constructor(driver: StorageDriverContract) {\r\n    this._driver = driver;\r\n  }\r\n\r\n  // ============================================================\r\n  // Properties\r\n  // ============================================================\r\n\r\n  /**\r\n   * Get the driver name\r\n   *\r\n   * @returns The name identifier of the underlying driver (e.g., \"local\", \"s3\", \"r2\")\r\n   */\r\n  public get name(): StorageDriverType {\r\n    return this.activeDriver.name;\r\n  }\r\n\r\n  /**\r\n   * Get the default driver instance\r\n   *\r\n   * Use this for advanced operations that require direct driver access.\r\n   *\r\n   * @returns The raw storage driver\r\n   */\r\n  public get defaultDriver(): StorageDriverContract {\r\n    return this._driver;\r\n  }\r\n\r\n  /**\r\n   * Get the currently active driver\r\n   *\r\n   * Returns the driver being used for storage operations.\r\n   * Can be overridden in subclasses for dynamic driver resolution (e.g., multi-tenant contexts).\r\n   *\r\n   * @returns The active storage driver\r\n   */\r\n  public get activeDriver(): StorageDriverContract {\r\n    return this._driver;\r\n  }\r\n\r\n  // ============================================================\r\n  // File Operations\r\n  // ============================================================\r\n\r\n  /**\r\n   * Store a file in storage\r\n   *\r\n   * Accepts multiple input types and stores the file at the specified location.\r\n   * Returns a `StorageFile` instance for further operations.\r\n   *\r\n   * @param file - File content as Buffer, string path, UploadedFile, or Readable stream\r\n   * @param location - Destination path in storage (e.g., \"uploads/images/photo.jpg\")\r\n   * @param options - Optional storage options\r\n   * @returns StorageFile instance with cached metadata\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // From buffer\r\n   * const file = await storage.put(buffer, \"documents/report.pdf\");\r\n   *\r\n   * // From uploaded file\r\n   * const file = await storage.put(uploadedFile, \"avatars/user-123.jpg\");\r\n   *\r\n   * // With options\r\n   * const file = await storage.put(buffer, \"images/photo.jpg\", {\r\n   *   mimeType: \"image/jpeg\",\r\n   *   cacheControl: \"max-age=31536000\"\r\n   * });\r\n   * ```\r\n   */\r\n  public async put(\r\n    file: UploadedFile | Buffer | string | Readable,\r\n    location: string,\r\n    options?: PutOptions,\r\n  ): Promise<StorageFile> {\r\n    const buffer = await this.toBuffer(file);\r\n    const data = await this.activeDriver.put(buffer, location, options);\r\n    return StorageFile.fromData(data, this.activeDriver);\r\n  }\r\n\r\n  /**\r\n   * Store a file from a readable stream\r\n   *\r\n   * Optimized for large files - streams data directly without full buffering.\r\n   * Ideal for file uploads, remote file fetching, or processing pipelines.\r\n   *\r\n   * @param stream - Readable stream of file content\r\n   * @param location - Destination path in storage\r\n   * @param options - Optional storage options\r\n   * @returns StorageFile instance with cached metadata\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * import { createReadStream } from \"fs\";\r\n   *\r\n   * const stream = createReadStream(\"./large-video.mp4\");\r\n   * const file = await storage.putStream(stream, \"videos/upload.mp4\");\r\n   * ```\r\n   */\r\n  public async putStream(\r\n    stream: Readable,\r\n    location: string,\r\n    options?: PutOptions,\r\n  ): Promise<StorageFile> {\r\n    const data = await this.activeDriver.putStream(stream, location, options);\r\n    return StorageFile.fromData(data, this.activeDriver);\r\n  }\r\n\r\n  /**\r\n   * Store a file from a URL\r\n   *\r\n   * Downloads the file from the URL and stores it.\r\n   *\r\n   * @param url - URL to download from\r\n   * @param location - Destination path in storage\r\n   * @param options - Optional storage options\r\n   * @returns StorageFile instance\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const file = await storage.putFromUrl(\r\n   *   \"https://example.com/image.jpg\",\r\n   *   \"images/downloaded.jpg\"\r\n   * );\r\n   * ```\r\n   */\r\n  public async putFromUrl(\r\n    url: string,\r\n    location: string,\r\n    options?: PutOptions,\r\n  ): Promise<StorageFile> {\r\n    const response = await fetch(url);\r\n\r\n    if (!response.ok) {\r\n      throw new Error(`Failed to fetch file from ${url}: ${response.statusText}`);\r\n    }\r\n\r\n    const buffer = Buffer.from(await response.arrayBuffer());\r\n    return this.put(buffer, location, options);\r\n  }\r\n\r\n  /**\r\n   * Store a file from base64 data URL\r\n   *\r\n   * @param dataUrl - Data URL (data:image/png;base64,iVBORw0KG...)\r\n   * @param location - Destination path in storage\r\n   * @param options - Optional storage options\r\n   * @returns StorageFile instance\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const file = await storage.putFromBase64(\r\n   *   \"data:image/png;base64,iVBORw0KGgoAAAANS...\",\r\n   *   \"images/upload.png\"\r\n   * );\r\n   * ```\r\n   */\r\n  public async putFromBase64(\r\n    dataUrl: string,\r\n    location: string,\r\n    options?: PutOptions,\r\n  ): Promise<StorageFile> {\r\n    // Parse data URL: data:image/png;base64,iVBORw0KG...\r\n    const matches = dataUrl.match(/^data:([^;]+);base64,(.+)$/);\r\n\r\n    if (!matches) {\r\n      throw new Error(\"Invalid base64 data URL format. Expected: data:mime/type;base64,<data>\");\r\n    }\r\n\r\n    const [, mimeType, base64Data] = matches;\r\n    const buffer = Buffer.from(base64Data, \"base64\");\r\n\r\n    return this.put(buffer, location, {\r\n      ...options,\r\n      mimeType: options?.mimeType || mimeType,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Retrieve file contents as a Buffer\r\n   *\r\n   * Downloads the entire file into memory. For large files,\r\n   * consider using `getStream()` instead.\r\n   *\r\n   * @param location - Path to the file in storage\r\n   * @returns Buffer containing file contents\r\n   * @throws Error if file not found\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const buffer = await storage.get(\"documents/report.pdf\");\r\n   * const content = buffer.toString(\"utf-8\");\r\n   * ```\r\n   */\r\n  public async get(location: string): Promise<Buffer> {\r\n    return this.activeDriver.get(location);\r\n  }\r\n\r\n  /**\r\n   * Retrieve file contents as a readable stream\r\n   *\r\n   * Streams file data without loading entire file into memory.\r\n   * Ideal for large files or when piping to a response.\r\n   *\r\n   * @param location - Path to the file in storage\r\n   * @returns Readable stream of file contents\r\n   * @throws Error if file not found\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const stream = await storage.getStream(\"videos/large.mp4\");\r\n   * stream.pipe(response.raw);\r\n   * ```\r\n   */\r\n  public async getStream(location: string): Promise<Readable> {\r\n    return this.activeDriver.getStream(location);\r\n  }\r\n\r\n  /**\r\n   * Delete a file from storage\r\n   *\r\n   * @param location - Path to the file, or a StorageFile instance\r\n   * @returns `true` if deleted, `false` if file not found\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // By path\r\n   * await storage.delete(\"temp/old-file.txt\");\r\n   *\r\n   * // From StorageFile instance\r\n   * const file = await storage.put(buffer, \"temp/file.txt\");\r\n   * await storage.delete(file);\r\n   * ```\r\n   */\r\n  public async delete(location: string | StorageFile): Promise<boolean> {\r\n    const path = typeof location === \"string\" ? location : location.path;\r\n    return this.activeDriver.delete(path);\r\n  }\r\n\r\n  /**\r\n   * Delete multiple files at once\r\n   *\r\n   * Performs batch deletion for efficiency. Returns results for each file\r\n   * including success/failure status.\r\n   *\r\n   * @param locations - Array of file paths to delete\r\n   * @returns Array of delete results with status for each file\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const results = await storage.deleteMany([\r\n   *   \"temp/file1.txt\",\r\n   *   \"temp/file2.txt\",\r\n   *   \"temp/file3.txt\"\r\n   * ]);\r\n   *\r\n   * for (const result of results) {\r\n   *   console.log(`${result.location}: ${result.deleted ? \"deleted\" : result.error}`);\r\n   * }\r\n   * ```\r\n   */\r\n  public async deleteMany(locations: string[]): Promise<DeleteManyResult[]> {\r\n    return this.activeDriver.deleteMany(locations);\r\n  }\r\n\r\n  /**\r\n   * Delete a directory\r\n   *\r\n   * @param directoryPath - Path to the directory\r\n   */\r\n  public async deleteDirectory(directoryPath: string): Promise<boolean> {\r\n    return await this.activeDriver.deleteDirectory(directoryPath);\r\n  }\r\n\r\n  /**\r\n   * Check if a file exists in storage\r\n   *\r\n   * @param location - Path to check\r\n   * @returns `true` if file exists, `false` otherwise\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * if (await storage.exists(\"config/settings.json\")) {\r\n   *   const config = await storage.get(\"config/settings.json\");\r\n   * }\r\n   * ```\r\n   */\r\n  public async exists(location: string): Promise<boolean> {\r\n    return this.activeDriver.exists(location);\r\n  }\r\n\r\n  /**\r\n   * Copy a file to a new location\r\n   *\r\n   * Creates a copy of the file at the destination path.\r\n   * The original file remains unchanged.\r\n   *\r\n   * @param from - Source path or StorageFile instance\r\n   * @param to - Destination path\r\n   * @returns StorageFile instance at the new location\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // Copy by path\r\n   * const backup = await storage.copy(\"documents/report.pdf\", \"backups/report.pdf\");\r\n   *\r\n   * // Copy from StorageFile\r\n   * const original = await storage.file(\"documents/report.pdf\");\r\n   * const backup = await storage.copy(original, \"backups/report.pdf\");\r\n   * ```\r\n   */\r\n  public async copy(from: string | StorageFile, to: string): Promise<StorageFile> {\r\n    const fromPath = typeof from === \"string\" ? from : from.path;\r\n    const data = await this.activeDriver.copy(fromPath, to);\r\n    return StorageFile.fromData(data, this.activeDriver);\r\n  }\r\n\r\n  /**\r\n   * Move a file to a new location\r\n   *\r\n   * Moves the file to the destination path. The original file\r\n   * is deleted after successful copy.\r\n   *\r\n   * @param from - Source path or StorageFile instance\r\n   * @param to - Destination path\r\n   * @returns StorageFile instance at the new location\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // Move by path\r\n   * const file = await storage.move(\"uploads/temp.jpg\", \"images/photo.jpg\");\r\n   *\r\n   * // Move from StorageFile\r\n   * const temp = await storage.file(\"uploads/temp.jpg\");\r\n   * const final = await storage.move(temp, \"images/photo.jpg\");\r\n   * ```\r\n   */\r\n  public async move(from: string | StorageFile, to: string): Promise<StorageFile> {\r\n    const fromPath = typeof from === \"string\" ? from : from.path;\r\n    const data = await this.activeDriver.move(fromPath, to);\r\n    return StorageFile.fromData(data, this.activeDriver);\r\n  }\r\n\r\n  /**\r\n   * Copy an entire directory recursively\r\n   *\r\n   * Copies all files from the source directory to the destination directory,\r\n   * preserving the directory structure.\r\n   *\r\n   * @param from - Source directory path\r\n   * @param to - Destination directory path\r\n   * @param options - Optional concurrency control\r\n   * @returns Number of files copied\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // Copy entire directory\r\n   * const count = await storage.copyDirectory(\"uploads/temp\", \"uploads/final\");\r\n   * console.log(`Copied ${count} files`);\r\n   *\r\n   * // With concurrency limit\r\n   * const count = await storage.copyDirectory(\"large-dir\", \"backup\", {\r\n   *   concurrency: 10\r\n   * });\r\n   * ```\r\n   */\r\n  public async copyDirectory(\r\n    from: string,\r\n    to: string,\r\n    options?: { concurrency?: number },\r\n  ): Promise<number> {\r\n    const concurrency = options?.concurrency || 5;\r\n\r\n    // List all files recursively\r\n    const files = await this.list(from, { recursive: true });\r\n    const filesToCopy = files.filter((f) => !f.isDirectory);\r\n\r\n    // Copy files in batches for efficiency\r\n    let copied = 0;\r\n    for (let i = 0; i < filesToCopy.length; i += concurrency) {\r\n      const batch = filesToCopy.slice(i, i + concurrency);\r\n      await Promise.all(\r\n        batch.map(async (file) => {\r\n          // Calculate relative path and new destination\r\n          const relativePath = file.path.substring(from.length).replace(/^\\//, \"\");\r\n          const newPath = `${to}/${relativePath}`;\r\n          await this.copy(file.path, newPath);\r\n          copied++;\r\n        }),\r\n      );\r\n    }\r\n\r\n    return copied;\r\n  }\r\n\r\n  /**\r\n   * Move an entire directory recursively\r\n   *\r\n   * Moves all files from the source directory to the destination directory,\r\n   * then deletes the source directory.\r\n   *\r\n   * @param from - Source directory path\r\n   * @param to - Destination directory path\r\n   * @param options - Optional concurrency control\r\n   * @returns Number of files moved\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const count = await storage.moveDirectory(\"uploads/temp\", \"uploads/final\");\r\n   * console.log(`Moved ${count} files`);\r\n   * ```\r\n   */\r\n  public async moveDirectory(\r\n    from: string,\r\n    to: string,\r\n    options?: { concurrency?: number },\r\n  ): Promise<number> {\r\n    // Copy all files first\r\n    const count = await this.copyDirectory(from, to, options);\r\n\r\n    // Delete source directory\r\n    await this.deleteDirectory(from);\r\n\r\n    return count;\r\n  }\r\n\r\n  /**\r\n   * Upload a local filesystem directory into storage\r\n   *\r\n   * Recursively walks the local directory, applies an optional filter, then\r\n   * streams each file into storage. Uploads run in concurrent batches for\r\n   * efficiency. Failures are collected — a single failed file never aborts\r\n   * the entire operation (mirrors the contract of `deleteMany`).\r\n   *\r\n   * @param localDirPath  - Absolute path of the local directory to upload\r\n   * @param destination   - Target prefix in storage (e.g. \"uploads/assets\")\r\n   * @param options       - Concurrency, filter, progress callback, put options\r\n   * @returns             - { uploaded, failed, total }\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const result = await storage.putDirectory(\"./public/assets\", \"cdn/assets\", {\r\n   *   concurrency: 10,\r\n   *   filter: (_, rel) => !rel.startsWith(\".\"),\r\n   *   onProgress: (done, total) => console.log(`${done}/${total}`),\r\n   * });\r\n   *\r\n   * console.log(`Uploaded: ${result.uploaded.length}, Failed: ${result.failed.length}`);\r\n   * ```\r\n   */\r\n  public async putDirectory(\r\n    localDirPath: string,\r\n    destination: string,\r\n    options?: PutDirectoryOptions,\r\n  ): Promise<PutDirectoryResult> {\r\n    const concurrency = options?.concurrency ?? 5;\r\n\r\n    // Collect all local file paths recursively\r\n    const localFiles = await this.walkLocalDirectory(localDirPath);\r\n\r\n    // Apply the user-supplied filter if any\r\n    const filteredFiles = options?.filter\r\n      ? localFiles.filter(({ absolute, relative }) => options.filter!(absolute, relative))\r\n      : localFiles;\r\n\r\n    const total = filteredFiles.length;\r\n    const uploaded: StorageFile[] = [];\r\n    const failed: Array<{ localPath: string; error: Error }> = [];\r\n    let doneCount = 0;\r\n\r\n    // Upload in concurrent batches\r\n    for (let i = 0; i < filteredFiles.length; i += concurrency) {\r\n      const batch = filteredFiles.slice(i, i + concurrency);\r\n\r\n      await Promise.all(\r\n        batch.map(async ({ absolute, relative }) => {\r\n          const storagePath = `${destination.replace(/\\/$/, \"\")}/${relative}`;\r\n\r\n          try {\r\n            const stream = createReadStream(absolute);\r\n            const file = await this.putStream(stream, storagePath, options?.putOptions);\r\n            uploaded.push(file);\r\n            doneCount++;\r\n            options?.onProgress?.(doneCount, total, file);\r\n          } catch (err) {\r\n            failed.push({\r\n              localPath: absolute,\r\n              error: err instanceof Error ? err : new Error(String(err)),\r\n            });\r\n          }\r\n        }),\r\n      );\r\n    }\r\n\r\n    return { uploaded, failed, total };\r\n  }\r\n\r\n  /**\r\n   * Walk a local directory recursively and return all file paths\r\n   *\r\n   * @param dirPath - Absolute local directory path\r\n   * @returns Array of { absolute, relative } file path pairs\r\n   * @internal\r\n   */\r\n  private async walkLocalDirectory(\r\n    dirPath: string,\r\n    baseDir?: string,\r\n  ): Promise<Array<{ absolute: string; relative: string }>> {\r\n    const root = baseDir ?? dirPath;\r\n    const entries = await fs.readdir(dirPath, { withFileTypes: true });\r\n    const results: Array<{ absolute: string; relative: string }> = [];\r\n\r\n    for (const entry of entries) {\r\n      const absolute = path.join(dirPath, entry.name);\r\n      const relative = path.relative(root, absolute).replace(/\\\\/g, \"/\");\r\n\r\n      if (entry.isDirectory()) {\r\n        const nested = await this.walkLocalDirectory(absolute, root);\r\n        results.push(...nested);\r\n      } else if (entry.isFile()) {\r\n        results.push({ absolute, relative });\r\n      }\r\n      // Symlinks are intentionally skipped\r\n    }\r\n\r\n    return results;\r\n  }\r\n\r\n  /**\r\n   * Empty a directory without deleting the directory itself\r\n   *\r\n   * Deletes all files within the directory but preserves the directory structure.\r\n   *\r\n   * @param path - Directory path to empty\r\n   * @returns Number of files deleted\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const count = await storage.emptyDirectory(\"uploads/temp\");\r\n   * console.log(`Deleted ${count} files`);\r\n   * ```\r\n   */\r\n  public async emptyDirectory(path: string): Promise<number> {\r\n    // List all files in directory\r\n    const files = await this.list(path, { recursive: true });\r\n    const filePaths = files.filter((f) => !f.isDirectory).map((f) => f.path);\r\n\r\n    if (filePaths.length === 0) {\r\n      return 0;\r\n    }\r\n\r\n    // Delete all files\r\n    await this.deleteMany(filePaths);\r\n\r\n    return filePaths.length;\r\n  }\r\n\r\n  /**\r\n   * List files in a directory\r\n   *\r\n   * Returns file information for all files in the specified directory.\r\n   * Supports recursive listing and pagination.\r\n   *\r\n   * @param directory - Directory path (defaults to root)\r\n   * @param options - List options (recursive, limit, cursor)\r\n   * @returns Array of file information objects\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // List all files in uploads\r\n   * const files = await storage.list(\"uploads\");\r\n   *\r\n   * // Recursive listing with limit\r\n   * const files = await storage.list(\"uploads\", {\r\n   *   recursive: true,\r\n   *   limit: 100\r\n   * });\r\n   * ```\r\n   */\r\n  public async list(directory?: string, options?: ListOptions): Promise<StorageFileInfo[]> {\r\n    return this.activeDriver.list(directory || \"\", options);\r\n  }\r\n\r\n  // ============================================================\r\n  // URL Operations\r\n  // ============================================================\r\n\r\n  /**\r\n   * Get the public URL for a file\r\n   *\r\n   * Returns the URL where the file can be accessed. For local storage,\r\n   * this is typically a path prefix. For cloud storage, this is the\r\n   * bucket URL or CDN URL.\r\n   *\r\n   * @param location - File path\r\n   * @returns Public URL string\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const url = storage.url(\"images/photo.jpg\");\r\n   * // Local: \"/uploads/images/photo.jpg\"\r\n   * // S3: \"https://bucket.s3.amazonaws.com/images/photo.jpg\"\r\n   * ```\r\n   */\r\n  public url(location: string): string {\r\n    return this.activeDriver.url(location);\r\n  }\r\n\r\n  /**\r\n   * Get a temporary signed URL with expiration\r\n   *\r\n   * Creates a URL that provides temporary access to the file.\r\n   * For cloud storage, this uses presigned URLs.\r\n   * For local storage, this uses HMAC-signed tokens.\r\n   *\r\n   * @param location - File path\r\n   * @param expiresIn - Seconds until URL expires (default: 3600)\r\n   * @returns Signed URL string\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * // URL valid for 1 hour\r\n   * const url = await storage.temporaryUrl(\"private/document.pdf\");\r\n   *\r\n   * // URL valid for 24 hours\r\n   * const url = await storage.temporaryUrl(\"private/document.pdf\", 86400);\r\n   * ```\r\n   */\r\n  public async temporaryUrl(location: string, expiresIn?: number): Promise<string> {\r\n    return this.activeDriver.temporaryUrl(location, expiresIn);\r\n  }\r\n\r\n  // ============================================================\r\n  // Metadata Operations\r\n  // ============================================================\r\n\r\n  /**\r\n   * Get file metadata without downloading the file\r\n   *\r\n   * Retrieves information about a file including size, last modified date,\r\n   * and MIME type without downloading the file contents.\r\n   *\r\n   * @param location - File path\r\n   * @returns File information object\r\n   * @throws Error if file not found\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const info = await storage.metadata(\"documents/report.pdf\");\r\n   * console.log(`Size: ${info.size} bytes`);\r\n   * console.log(`Type: ${info.mimeType}`);\r\n   * console.log(`Modified: ${info.lastModified}`);\r\n   * ```\r\n   */\r\n  public async metadata(location: string): Promise<StorageFileInfo> {\r\n    return this.activeDriver.metadata(location);\r\n  }\r\n\r\n  /**\r\n   * Get file size in bytes\r\n   *\r\n   * Shortcut for `metadata(location).size`.\r\n   *\r\n   * @param location - File path\r\n   * @returns File size in bytes\r\n   * @throws Error if file not found\r\n   */\r\n  public async size(location: string): Promise<number> {\r\n    return this.activeDriver.size(location);\r\n  }\r\n\r\n  /**\r\n   * Get a StorageFile instance for OOP-style operations\r\n   *\r\n   * Creates a `StorageFile` wrapper for the specified path,\r\n   * allowing fluent method chaining for file operations.\r\n   *\r\n   * @param location - File path\r\n   * @returns StorageFile instance\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const file = await storage.file(\"uploads/image.jpg\");\r\n   *\r\n   * // Properties\r\n   * console.log(file.name);       // \"image.jpg\"\r\n   * console.log(file.extension);  // \"jpg\"\r\n   *\r\n   * // Operations\r\n   * await file.copy(\"backup/image.jpg\");\r\n   * await file.delete();\r\n   * ```\r\n   */\r\n  public file(location: string): StorageFile {\r\n    return new StorageFile(location, this.activeDriver);\r\n  }\r\n\r\n  // ============================================================\r\n  // Utilities\r\n  // ============================================================\r\n\r\n  /**\r\n   * Convert various input types to Buffer\r\n   *\r\n   * @param file - Input file in various formats\r\n   * @returns Buffer containing file contents\r\n   * @internal\r\n   */\r\n  protected async toBuffer(file: UploadedFile | Buffer | string | Readable): Promise<Buffer> {\r\n    // Already a buffer\r\n    if (Buffer.isBuffer(file)) {\r\n      return file;\r\n    }\r\n\r\n    // Readable stream - collect into buffer\r\n    if (this.isReadable(file)) {\r\n      return this.streamToBuffer(file as Readable);\r\n    }\r\n\r\n    // String content\r\n    if (typeof file === \"string\") {\r\n      if (await fileExistsAsync(file)) {\r\n        return fs.readFile(file);\r\n      }\r\n\r\n      return Buffer.from(file);\r\n    }\r\n\r\n    // UploadedFile\r\n    return (file as UploadedFile).buffer();\r\n  }\r\n\r\n  /**\r\n   * Check if value is a Readable stream\r\n   *\r\n   * @param value - Value to check\r\n   * @returns True if value is a Readable stream\r\n   * @internal\r\n   */\r\n  protected isReadable(value: unknown): value is Readable {\r\n    return (\r\n      typeof value === \"object\" &&\r\n      value !== null &&\r\n      \"pipe\" in value &&\r\n      typeof (value as Readable).pipe === \"function\"\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Convert a Readable stream to Buffer\r\n   *\r\n   * @param stream - Readable stream\r\n   * @returns Buffer containing stream contents\r\n   * @internal\r\n   */\r\n  protected async streamToBuffer(stream: Readable): Promise<Buffer> {\r\n    const chunks: Buffer[] = [];\r\n    for await (const chunk of stream) {\r\n      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\r\n    }\r\n    return Buffer.concat(chunks as unknown as Uint8Array[]);\r\n  }\r\n\r\n  /**\r\n   * Prepend a prefix to a location path\r\n   *\r\n   * Useful for organizing files into directories.\r\n   *\r\n   * @param prefix - Prefix to add (e.g., \"uploads\")\r\n   * @param location - Original location path\r\n   * @returns Combined path with prefix\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * storage.prepend(\"uploads\", \"image.jpg\"); // \"uploads/image.jpg\"\r\n   * storage.prepend(\"uploads/\", \"/image.jpg\"); // \"uploads/image.jpg\"\r\n   * ```\r\n   */\r\n  public prepend(prefix: string, location: string): string {\r\n    return `${prefix.replace(/\\/$/, \"\")}/${location.replace(/^\\//, \"\")}`;\r\n  }\r\n\r\n  /**\r\n   * Append a suffix to a location path (before extension)\r\n   *\r\n   * Useful for creating variants of files (thumbnails, etc.).\r\n   *\r\n   * @param location - Original location path\r\n   * @param suffix - Suffix to add before extension\r\n   * @returns Path with suffix added before extension\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * storage.append(\"image.jpg\", \"_thumb\"); // \"image_thumb.jpg\"\r\n   * storage.append(\"document.pdf\", \"_v2\"); // \"document_v2.pdf\"\r\n   * ```\r\n   */\r\n  public append(location: string, suffix: string): string {\r\n    const lastDot = location.lastIndexOf(\".\");\r\n    if (lastDot === -1) {\r\n      return `${location}${suffix}`;\r\n    }\r\n    return `${location.substring(0, lastDot)}${suffix}${location.substring(lastDot)}`;\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/storage/storage-file.d.mts

@@ -0,0 +1,252 @@
+import { CloudStorageFileData, FileVisibility, StorageDriverContract, StorageFileData, StorageFileInfo } from "./types.mjs";
+import { Readable } from "stream";
+
+//#region ../../@warlock.js/core/src/storage/storage-file.d.ts
+/**
+ * StorageFile class - OOP wrapper for storage file operations
+ *
+ * Provides a fluent interface for working with files in storage,
+ * wrapping the underlying driver operations.
+ *
+ * @example
+ * ```typescript
+ * const file = await storage.put(buffer, "uploads/image.jpg");
+ *
+ * // Properties (sync, from cached data)
+ * file.name        // "image.jpg"
+ * file.extension   // "jpg"
+ * file.path        // "uploads/image.jpg"
+ * file.hash        // "sha256:abc123..."
+ *
+ * // Operations
+ * await file.copy("uploads/backup.jpg")
+ * await file.move("archive/image.jpg")
+ * await file.delete()
+ *
+ * // Content
+ * const buffer = await file.contents();
+ * const stream = await file.stream();
+ * ```
+ */
+declare class StorageFile {
+  /**
+   * Relative file path
+   */
+  protected _path: string;
+  /**
+   * The driver instance
+   */
+  protected _driver: StorageDriverContract;
+  /**
+   * Cached file data (from put operations or lazy loaded)
+   */
+  protected _data?: StorageFileData;
+  /**
+   * Whether the file has been deleted
+   */
+  protected _deleted: boolean;
+  /**
+   * Create a new StorageFile instance
+   *
+   * @param path - Relative file path
+   * @param driver - Driver instance
+   * @param data - Optional initial data from put/copy operations
+   */
+  constructor(path: string, driver: StorageDriverContract, data?: StorageFileData);
+  /**
+   * Get the relative file path
+   */
+  get path(): string;
+  /**
+   * Get the file name (with extension)
+   */
+  get name(): string;
+  /**
+   * Get the file extension (without dot)
+   */
+  get extension(): string;
+  /**
+   * Get the directory path
+   */
+  get directory(): string;
+  /**
+   * Get the driver name
+   */
+  get driver(): string;
+  /**
+   * Check if file has been deleted
+   */
+  get isDeleted(): boolean;
+  /**
+   * Get public URL (sync if data cached, otherwise computed)
+   */
+  get url(): string;
+  /**
+   * Get the absolute filesystem path (local driver only)
+   */
+  get absolutePath(): string | undefined;
+  /**
+   * Get file hash (SHA-256, available from put operations)
+   */
+  get hash(): string | undefined;
+  /**
+   * Get cached file data, or fetch it if not available
+   */
+  data(): Promise<StorageFileData>;
+  /**
+   * Get file size in bytes
+   */
+  size(): Promise<number>;
+  /**
+   * Get MIME type
+   */
+  mimeType(): Promise<string>;
+  /**
+   * Get last modified date (fetches from driver)
+   */
+  lastModified(): Promise<Date | undefined>;
+  /**
+   * Get ETag (cloud drivers, fetches from driver)
+   */
+  etag(): Promise<string | undefined>;
+  /**
+   * Get file contents as Buffer
+   */
+  contents(): Promise<Buffer>;
+  /**
+   * Get file contents as readable stream
+   */
+  stream(): Promise<Readable>;
+  /**
+   * Get file contents as UTF-8 text
+   */
+  text(): Promise<string>;
+  /**
+   * Get file contents as base64 string
+   */
+  base64(): Promise<string>;
+  /**
+   * Get file contents as data URL
+   */
+  dataUrl(): Promise<string>;
+  /**
+   * Get a temporary signed URL
+   *
+   * @param expiresIn - Seconds until expiration (default: 3600)
+   */
+  temporaryUrl(expiresIn?: number): Promise<string>;
+  /**
+   * Check if the file exists
+   */
+  exists(): Promise<boolean>;
+  /**
+   * Copy the file to a new location
+   *
+   * @param destination - Destination path
+   * @returns New StorageFile instance at destination
+   */
+  copy(destination: string): Promise<StorageFile>;
+  /**
+   * Move the file to a new location
+   *
+   * @param destination - Destination path
+   * @returns This StorageFile instance with updated path
+   */
+  move(destination: string): Promise<this>;
+  /**
+   * Rename the file (move within same directory)
+   *
+   * @param newName - New file name
+   * @returns This StorageFile instance with updated path
+   */
+  rename(newName: string): Promise<this>;
+  /**
+   * Delete the file
+   *
+   * @returns true if deleted, false if not found
+   */
+  delete(): Promise<boolean>;
+  /**
+   * Set file visibility (cloud drivers only)
+   *
+   * @param visibility - "public" or "private"
+   * @throws Error if driver doesn't support visibility
+   */
+  setVisibility(visibility: FileVisibility): Promise<this>;
+  /**
+   * Get file visibility (cloud drivers only)
+   *
+   * @throws Error if driver doesn't support visibility
+   */
+  getVisibility(): Promise<FileVisibility>;
+  /**
+   * Set storage class (cloud drivers only)
+   *
+   * @param storageClass - Storage class (e.g., "STANDARD", "GLACIER")
+   * @throws Error if driver doesn't support storage class
+   */
+  setStorageClass(storageClass: string): Promise<this>;
+  /**
+   * Ensure the file has not been deleted
+   */
+  protected ensureNotDeleted(): void;
+  /**
+   * Create a StorageFile instance from StorageFileData
+   *
+   * @param data - Storage file data from put/copy/move operations
+   * @param driver - Driver instance
+   */
+  static fromData(data: StorageFileData | CloudStorageFileData, driver: StorageDriverContract): StorageFile;
+  /**
+   * Get file metadata
+   */
+  metadata(): Promise<StorageFileInfo>;
+  /**
+   * Determine if this file is an image type
+   */
+  isImage(): Promise<boolean>;
+  /**
+   * Determine if this file is a document type
+   */
+  isDocument(): Promise<boolean>;
+  /**
+   * Determine if this file is a pdf type
+   */
+  isPdf(): Promise<boolean>;
+  /**
+   * Determine if this file is an excel file (any support excel file)
+   */
+  isExcel(): Promise<boolean>;
+  /**
+   * Determine if this file is a doc file
+   */
+  isDoc(): Promise<boolean>;
+  /**
+   * Determine if this file is an audio type
+   */
+  isAudio(): Promise<boolean>;
+  /**
+   * Determine if this file is a video type
+   */
+  isVideo(): Promise<boolean>;
+  /**
+   * Convert to plain object (returns cached data or constructs it)
+   */
+  toJSON(): {
+    path: string;
+    name: string;
+    extension: string;
+    driver: string;
+    url: string;
+    hash?: string;
+    size?: number;
+    mimeType?: string;
+  };
+  /**
+   * String representation
+   */
+  toString(): string;
+}
+//#endregion
+export { StorageFile };
+//# sourceMappingURL=storage-file.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage-file.d.mts","names":[],"sources":["../../../../../../@warlock.js/core/src/storage/storage-file.ts"],"mappings":";;;;;;AAqCA;;;;;;;;;;;;;;;;;;;;;;;;cAAa,WAAA;EA6P6B;;;EAAA,UAzP9B,KAAA;EAkS8C;;;EAAA,UA7R9C,OAAA,EAAS,qBAAA;EA4VX;;;EAAA,UAvVE,KAAA,GAAQ,eAAA;EAgWe;;;EAAA,UA3VvB,QAAA;EAmXQ;;;;;;;cA1WC,IAAA,UAAc,MAAA,EAAQ,qBAAA,EAAuB,IAAA,GAAO,eAAA;EAnB7D;;;EAAA,IAgCC,IAAA,CAAA;EAtBD;;;EAAA,IA6BC,IAAA,CAAA;EApBsB;;;EAAA,IA2BtB,SAAA,CAAA;EAPA;;;EAAA,IAcA,SAAA,CAAA;EAcA;;;EAAA,IAPA,MAAA,CAAA;EA6CE;;;EAAA,IAtCF,SAAA,CAAA;EA0DU;;;EAAA,IAnDV,GAAA,CAAA;EAmEkB;;;EAAA,IA3DlB,YAAA,CAAA;EAiFE;;;EAAA,IArEF,IAAA,CAAA;EA6EY;;;EAlEV,IAAA,CAAA,GAAQ,OAAA,CAAQ,eAAA;EAkFhB;;;EA9DA,IAAA,CAAA,GAAQ,OAAA;EAoFR;;;EA5EA,QAAA,CAAA,GAAY,OAAA;EAwFF;;;EAhFV,YAAA,CAAA,GAAgB,OAAA,CAAQ,IAAA;EA2FW;;;EAlFnC,IAAA,CAAA,GAAQ,OAAA;EA4GR;;;EA/FA,QAAA,CAAA,GAAY,OAAA,CAAQ,MAAA;EAyGV;;;EAjGV,MAAA,CAAA,GAAU,OAAA,CAAQ,QAAA;EAkHyB;;;EA1G3C,IAAA,CAAA,GAAQ,OAAA;EA0IR;;;EAlIA,MAAA,CAAA,GAAU,OAAA;EAgKT;;;EAxJD,OAAA,CAAA,GAAW,OAAA;EA0Jd;;;;;EA5IG,YAAA,CAAa,SAAA,YAAmB,OAAA;EA4JhC;;;EAhJA,MAAA,CAAA,GAAU,OAAA;EAgKV;;;;;;EArJA,IAAA,CAAK,WAAA,WAAsB,OAAA,CAAQ,WAAA;EAsL5B;;;;;;EA1KP,IAAA,CAAK,WAAA,WAAsB,OAAA;EA8LtC;;;;;;EAhLW,MAAA,CAAO,OAAA,WAAkB,OAAA;EAqMvB;;;;;EA3LF,MAAA,CAAA,GAAU,OAAA;;;;;;;EAiBV,aAAA,CAAc,UAAA,EAAY,cAAA,GAAiB,OAAA;;;;;;EAgB3C,aAAA,CAAA,GAAiB,OAAA,CAAQ,cAAA;;;;;;;EAgBzB,eAAA,CAAgB,YAAA,WAAuB,OAAA;;;;YAkB1C,gBAAA,CAAA;;;;;;;SAYI,QAAA,CACZ,IAAA,EAAM,eAAA,GAAkB,oBAAA,EACxB,MAAA,EAAQ,qBAAA,GACP,WAAA;;;;EAOU,QAAA,CAAA,GAAY,OAAA,CAAQ,eAAA;;;;EAQpB,OAAA,CAAA,GAAO,OAAA;;;;EAQP,UAAA,CAAA,GAAU,OAAA;;;;EAQV,KAAA,CAAA,GAAK,OAAA;;;;EAQL,OAAA,CAAA,GAAO,OAAA;;;;EAYP,KAAA,CAAA,GAAK,OAAA;;;;EAaL,OAAA,CAAA,GAAO,OAAA;;;;EAQP,OAAA,CAAA,GAAO,OAAA;;;;EAQb,MAAA,CAAA;IACL,IAAA;IACA,IAAA;IACA,SAAA;IACA,MAAA;IACA,GAAA;IACA,IAAA;IACA,IAAA;IACA,QAAA;EAAA;;;;EAiBK,QAAA,CAAA;AAAA"}

package/esm/storage/storage-file.mjs

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