@warlock.js/core 4.0.6 → 4.0.10

package/esm/storage/scoped-storage.d.ts

@@ -0,0 +1,402 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { Readable } from "stream";
+import type { UploadedFile } from "../http";
+import { StorageFile } from "./storage-file";
+import type { DeleteManyResult, ListOptions, PutOptions, StorageDriverContract, StorageDriverType, StorageFileInfo } from "./types";
+/**
+ * ScopedStorage - Base class for storage operations
+ *
+ * Wraps a storage driver and provides a consistent, developer-friendly API
+ * that returns `StorageFile` instances instead of raw data objects.
+ *
+ * This class serves as the base for both direct driver usage and the
+ * full `Storage` manager class.
+ *
+ * @example
+ * ```typescript
+ * // Using via storage.use()
+ * const s3Storage = storage.use("s3");
+ * const file = await s3Storage.put(buffer, "images/photo.jpg");
+ *
+ * // file is a StorageFile instance with rich API
+ * console.log(file.name);       // "photo.jpg"
+ * console.log(file.url);        // "https://..."
+ * await file.copy("backup/photo.jpg");
+ * ```
+ */
+export declare class ScopedStorage {
+    /**
+     * The underlying storage driver instance
+     * @internal
+     */
+    protected _driver: StorageDriverContract;
+    /**
+     * Create a new ScopedStorage instance
+     *
+     * @param driver - The storage driver to wrap
+     */
+    constructor(driver: StorageDriverContract);
+    /**
+     * Get the driver name
+     *
+     * @returns The name identifier of the underlying driver (e.g., "local", "s3", "r2")
+     */
+    get name(): StorageDriverType;
+    /**
+     * Get the underlying driver instance
+     *
+     * Use this for advanced operations that require direct driver access.
+     *
+     * @returns The raw storage driver
+     */
+    get driver(): StorageDriverContract;
+    /**
+     * Store a file in storage
+     *
+     * Accepts multiple input types and stores the file at the specified location.
+     * Returns a `StorageFile` instance for further operations.
+     *
+     * @param file - File content as Buffer, string path, UploadedFile, or Readable stream
+     * @param location - Destination path in storage (e.g., "uploads/images/photo.jpg")
+     * @param options - Optional storage options
+     * @returns StorageFile instance with cached metadata
+     *
+     * @example
+     * ```typescript
+     * // From buffer
+     * const file = await storage.put(buffer, "documents/report.pdf");
+     *
+     * // From uploaded file
+     * const file = await storage.put(uploadedFile, "avatars/user-123.jpg");
+     *
+     * // With options
+     * const file = await storage.put(buffer, "images/photo.jpg", {
+     *   mimeType: "image/jpeg",
+     *   cacheControl: "max-age=31536000"
+     * });
+     * ```
+     */
+    put(file: UploadedFile | Buffer | string | Readable, location: string, options?: PutOptions): Promise<StorageFile>;
+    /**
+     * Store a file from a readable stream
+     *
+     * Optimized for large files - streams data directly without full buffering.
+     * Ideal for file uploads, remote file fetching, or processing pipelines.
+     *
+     * @param stream - Readable stream of file content
+     * @param location - Destination path in storage
+     * @param options - Optional storage options
+     * @returns StorageFile instance with cached metadata
+     *
+     * @example
+     * ```typescript
+     * import { createReadStream } from "fs";
+     *
+     * const stream = createReadStream("./large-video.mp4");
+     * const file = await storage.putStream(stream, "videos/upload.mp4");
+     * ```
+     */
+    putStream(stream: Readable, location: string, options?: PutOptions): Promise<StorageFile>;
+    /**
+     * Retrieve file contents as a Buffer
+     *
+     * Downloads the entire file into memory. For large files,
+     * consider using `getStream()` instead.
+     *
+     * @param location - Path to the file in storage
+     * @returns Buffer containing file contents
+     * @throws Error if file not found
+     *
+     * @example
+     * ```typescript
+     * const buffer = await storage.get("documents/report.pdf");
+     * const content = buffer.toString("utf-8");
+     * ```
+     */
+    get(location: string): Promise<Buffer>;
+    /**
+     * Retrieve file contents as a readable stream
+     *
+     * Streams file data without loading entire file into memory.
+     * Ideal for large files or when piping to a response.
+     *
+     * @param location - Path to the file in storage
+     * @returns Readable stream of file contents
+     * @throws Error if file not found
+     *
+     * @example
+     * ```typescript
+     * const stream = await storage.getStream("videos/large.mp4");
+     * stream.pipe(response.raw);
+     * ```
+     */
+    getStream(location: string): Promise<Readable>;
+    /**
+     * Delete a file from storage
+     *
+     * @param location - Path to the file, or a StorageFile instance
+     * @returns `true` if deleted, `false` if file not found
+     *
+     * @example
+     * ```typescript
+     * // By path
+     * await storage.delete("temp/old-file.txt");
+     *
+     * // From StorageFile instance
+     * const file = await storage.put(buffer, "temp/file.txt");
+     * await storage.delete(file);
+     * ```
+     */
+    delete(location: string | StorageFile): Promise<boolean>;
+    /**
+     * Delete multiple files at once
+     *
+     * Performs batch deletion for efficiency. Returns results for each file
+     * including success/failure status.
+     *
+     * @param locations - Array of file paths to delete
+     * @returns Array of delete results with status for each file
+     *
+     * @example
+     * ```typescript
+     * const results = await storage.deleteMany([
+     *   "temp/file1.txt",
+     *   "temp/file2.txt",
+     *   "temp/file3.txt"
+     * ]);
+     *
+     * for (const result of results) {
+     *   console.log(`${result.location}: ${result.deleted ? "deleted" : result.error}`);
+     * }
+     * ```
+     */
+    deleteMany(locations: string[]): Promise<DeleteManyResult[]>;
+    /**
+     * Check if a file exists in storage
+     *
+     * @param location - Path to check
+     * @returns `true` if file exists, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * if (await storage.exists("config/settings.json")) {
+     *   const config = await storage.get("config/settings.json");
+     * }
+     * ```
+     */
+    exists(location: string): Promise<boolean>;
+    /**
+     * Copy a file to a new location
+     *
+     * Creates a copy of the file at the destination path.
+     * The original file remains unchanged.
+     *
+     * @param from - Source path or StorageFile instance
+     * @param to - Destination path
+     * @returns StorageFile instance at the new location
+     *
+     * @example
+     * ```typescript
+     * // Copy by path
+     * const backup = await storage.copy("documents/report.pdf", "backups/report.pdf");
+     *
+     * // Copy from StorageFile
+     * const original = await storage.file("documents/report.pdf");
+     * const backup = await storage.copy(original, "backups/report.pdf");
+     * ```
+     */
+    copy(from: string | StorageFile, to: string): Promise<StorageFile>;
+    /**
+     * Move a file to a new location
+     *
+     * Moves the file to the destination path. The original file
+     * is deleted after successful copy.
+     *
+     * @param from - Source path or StorageFile instance
+     * @param to - Destination path
+     * @returns StorageFile instance at the new location
+     *
+     * @example
+     * ```typescript
+     * // Move by path
+     * const file = await storage.move("uploads/temp.jpg", "images/photo.jpg");
+     *
+     * // Move from StorageFile
+     * const temp = await storage.file("uploads/temp.jpg");
+     * const final = await storage.move(temp, "images/photo.jpg");
+     * ```
+     */
+    move(from: string | StorageFile, to: string): Promise<StorageFile>;
+    /**
+     * List files in a directory
+     *
+     * Returns file information for all files in the specified directory.
+     * Supports recursive listing and pagination.
+     *
+     * @param directory - Directory path (defaults to root)
+     * @param options - List options (recursive, limit, cursor)
+     * @returns Array of file information objects
+     *
+     * @example
+     * ```typescript
+     * // List all files in uploads
+     * const files = await storage.list("uploads");
+     *
+     * // Recursive listing with limit
+     * const files = await storage.list("uploads", {
+     *   recursive: true,
+     *   limit: 100
+     * });
+     * ```
+     */
+    list(directory?: string, options?: ListOptions): Promise<StorageFileInfo[]>;
+    /**
+     * Get the public URL for a file
+     *
+     * Returns the URL where the file can be accessed. For local storage,
+     * this is typically a path prefix. For cloud storage, this is the
+     * bucket URL or CDN URL.
+     *
+     * @param location - File path
+     * @returns Public URL string
+     *
+     * @example
+     * ```typescript
+     * const url = storage.url("images/photo.jpg");
+     * // Local: "/uploads/images/photo.jpg"
+     * // S3: "https://bucket.s3.amazonaws.com/images/photo.jpg"
+     * ```
+     */
+    url(location: string): string;
+    /**
+     * Get a temporary signed URL with expiration
+     *
+     * Creates a URL that provides temporary access to the file.
+     * For cloud storage, this uses presigned URLs.
+     * For local storage, this uses HMAC-signed tokens.
+     *
+     * @param location - File path
+     * @param expiresIn - Seconds until URL expires (default: 3600)
+     * @returns Signed URL string
+     *
+     * @example
+     * ```typescript
+     * // URL valid for 1 hour
+     * const url = await storage.temporaryUrl("private/document.pdf");
+     *
+     * // URL valid for 24 hours
+     * const url = await storage.temporaryUrl("private/document.pdf", 86400);
+     * ```
+     */
+    temporaryUrl(location: string, expiresIn?: number): Promise<string>;
+    /**
+     * Get file metadata without downloading the file
+     *
+     * Retrieves information about a file including size, last modified date,
+     * and MIME type without downloading the file contents.
+     *
+     * @param location - File path
+     * @returns File information object
+     * @throws Error if file not found
+     *
+     * @example
+     * ```typescript
+     * const info = await storage.getInfo("documents/report.pdf");
+     * console.log(`Size: ${info.size} bytes`);
+     * console.log(`Type: ${info.mimeType}`);
+     * console.log(`Modified: ${info.lastModified}`);
+     * ```
+     */
+    getInfo(location: string): Promise<StorageFileInfo>;
+    /**
+     * Get file size in bytes
+     *
+     * Shortcut for `getInfo(location).size`.
+     *
+     * @param location - File path
+     * @returns File size in bytes
+     * @throws Error if file not found
+     */
+    size(location: string): Promise<number>;
+    /**
+     * Get a StorageFile instance for OOP-style operations
+     *
+     * Creates a `StorageFile` wrapper for the specified path,
+     * allowing fluent method chaining for file operations.
+     *
+     * @param location - File path
+     * @returns StorageFile instance
+     *
+     * @example
+     * ```typescript
+     * const file = await storage.file("uploads/image.jpg");
+     *
+     * // Properties
+     * console.log(file.name);       // "image.jpg"
+     * console.log(file.extension);  // "jpg"
+     *
+     * // Operations
+     * await file.copy("backup/image.jpg");
+     * await file.delete();
+     * ```
+     */
+    file(location: string): Promise<StorageFile>;
+    /**
+     * Convert various input types to Buffer
+     *
+     * @param file - Input file in various formats
+     * @returns Buffer containing file contents
+     * @internal
+     */
+    protected toBuffer(file: UploadedFile | Buffer | string | Readable): Promise<Buffer>;
+    /**
+     * Check if value is a Readable stream
+     *
+     * @param value - Value to check
+     * @returns True if value is a Readable stream
+     * @internal
+     */
+    protected isReadable(value: unknown): value is Readable;
+    /**
+     * Convert a Readable stream to Buffer
+     *
+     * @param stream - Readable stream
+     * @returns Buffer containing stream contents
+     * @internal
+     */
+    protected streamToBuffer(stream: Readable): Promise<Buffer>;
+    /**
+     * Prepend a prefix to a location path
+     *
+     * Useful for organizing files into directories.
+     *
+     * @param prefix - Prefix to add (e.g., "uploads")
+     * @param location - Original location path
+     * @returns Combined path with prefix
+     *
+     * @example
+     * ```typescript
+     * storage.prepend("uploads", "image.jpg"); // "uploads/image.jpg"
+     * storage.prepend("uploads/", "/image.jpg"); // "uploads/image.jpg"
+     * ```
+     */
+    prepend(prefix: string, location: string): string;
+    /**
+     * Append a suffix to a location path (before extension)
+     *
+     * Useful for creating variants of files (thumbnails, etc.).
+     *
+     * @param location - Original location path
+     * @param suffix - Suffix to add before extension
+     * @returns Path with suffix added before extension
+     *
+     * @example
+     * ```typescript
+     * storage.append("image.jpg", "_thumb"); // "image_thumb.jpg"
+     * storage.append("document.pdf", "_v2"); // "document_v2.pdf"
+     * ```
+     */
+    append(location: string, suffix: string): string;
+}
+//# sourceMappingURL=scoped-storage.d.ts.map

package/esm/storage/scoped-storage.d.ts.map

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