@warlock.js/core 4.0.10 → 4.0.15

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

@@ -1,402 +0,0 @@
-/// <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/cjs/storage/scoped-storage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scoped-storage.d.ts","sourceRoot":"","sources":["../../src/storage/scoped-storage.ts"],"names":[],"mappings":";;AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,qBAAqB,CAAC;IAEzC;;;;OAIG;gBACgB,MAAM,EAAE,qBAAqB;IAQhD;;;;OAIG;IACH,IAAW,IAAI,IAAI,iBAAiB,CAEnC;IAED;;;;;;OAMG;IACH,IAAW,MAAM,IAAI,qBAAqB,CAEzC;IAMD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,GAAG,CACd,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,WAAW,CAAC;IAMvB;;;;;;;;;;;;;;;;;;OAkBG;IACU,SAAS,CACpB,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,WAAW,CAAC;IAKvB;;;;;;;;;;;;;;;OAeG;IACU,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD;;;;;;;;;;;;;;;OAeG;IACU,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3D;;;;;;;;;;;;;;;OAeG;IACU,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIzE;;;;;;;;;;;;OAYG;IACU,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvD;;;;;;;;;;;;;;;;;;;OAmBG;IACU,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAM/E;;;;;;;;;;;;;;;;;;;OAmBG;IACU,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAM/E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAQxF;;;;;;;;;;;;;;;;OAgBG;IACI,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIpC;;;;;;;;;;;;;;;;;;;OAmBG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQhF;;;;;;;;;;;;;;;;;OAiBG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIhE;;;;;;;;OAQG;IACU,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAQzD;;;;;;OAMG;cACa,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB1F;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IASvD;;;;;;OAMG;cACa,cAAc,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAQjE;;;;;;;;;;;;;;OAcG;IACI,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIxD;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;CAOxD"}