@warlock.js/core 4.0.48 → 4.0.59

package/esm/storage/drivers/cloud-driver.d.ts

@@ -0,0 +1,196 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { Readable } from "stream";
+import type { CloudStorageDriverContract, CloudStorageDriverOptions, CloudStorageFileData, DeleteManyResult, FileVisibility, ListOptions, PresignedOptions, PresignedUploadOptions, PutOptions, StorageDriverType, StorageFileInfo } from "../types";
+/**
+ * Base abstract class for all S3-compatible cloud storage drivers
+ *
+ * This class contains all shared logic for S3-compatible storage services
+ * including AWS S3, Cloudflare R2, DigitalOcean Spaces, and others.
+ *
+ * **Important:** S3 SDK packages are lazy-loaded on first use.
+ * Users must install them separately:
+ * ```
+ * npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+ * ```
+ *
+ * Subclasses must implement:
+ * - `name`: Driver identifier (e.g., "s3", "r2", "spaces")
+ * - `url()`: Returns the public URL for a file (provider-specific format)
+ */
+export declare abstract class CloudDriver<TOptions extends Partial<CloudStorageDriverOptions> = CloudStorageDriverOptions> implements CloudStorageDriverContract {
+    options: TOptions;
+    /**
+     * S3-compatible client (lazy-loaded)
+     */
+    protected client: InstanceType<typeof import("@aws-sdk/client-s3").S3Client>;
+    /**
+     * Retry configuration
+     */
+    protected retryConfig: {
+        maxRetries: number;
+        initialDelayMs: number;
+        maxDelayMs: number;
+        backoffMultiplier: number;
+    };
+    constructor(options: TOptions);
+    /**
+     * Driver name identifier
+     */
+    abstract readonly name: StorageDriverType;
+    /**
+     * Get public URL for file
+     * Must be implemented by subclasses with provider-specific format
+     */
+    abstract url(location: string): string;
+    /**
+     * Get endpoint URL
+     * Can be overridden by subclasses for provider-specific endpoints
+     */
+    protected getEndpoint(): string | undefined;
+    /**
+     * Apply prefix to location path
+     *
+     * Priority: context prefix > driver options prefix > no prefix
+     * This allows multi-tenant scenarios where context overrides driver config.
+     *
+     * @param location - Original location path
+     * @returns Location with prefix applied if one exists
+     */
+    applyPrefix(location: string): string;
+    /**
+     * Normalize storage path (remove double slashes, sanitize)
+     * @internal
+     */
+    protected normalizePath(path: string): string;
+    /**
+     * Execute an operation with retry logic
+     *
+     * Retries on transient errors with exponential backoff.
+     *
+     * @param operation - Async operation to execute
+     * @param operationName - Name for logging
+     * @returns Result of the operation
+     * @internal
+     */
+    protected withRetry<T>(operation: () => Promise<T>, operationName?: string): Promise<T>;
+    /**
+     * Check if an error is retryable
+     *
+     * Retries on:
+     * - Network errors
+     * - 5xx server errors
+     * - Rate limiting (429)
+     * - Timeout errors
+     *
+     * Does NOT retry on:
+     * - 4xx client errors (except 429)
+     * - Authentication errors
+     * - Not found errors
+     *
+     * @param error - Error to check
+     * @returns true if error is retryable
+     * @internal
+     */
+    protected isRetryableError(error: any): boolean;
+    /**
+     * Put file to cloud storage
+     */
+    put(file: Buffer, location: string, options?: PutOptions): Promise<CloudStorageFileData>;
+    /**
+     * Put file from a readable stream (for large files)
+     * Uses S3 multipart upload for efficient streaming
+     */
+    putStream(stream: Readable, location: string, options?: PutOptions): Promise<CloudStorageFileData>;
+    /**
+     * Get file contents as Buffer
+     */
+    get(location: string): Promise<Buffer>;
+    /**
+     * Get file as a readable stream (for large files)
+     */
+    getStream(location: string): Promise<Readable>;
+    /**
+     * Delete a file
+     */
+    delete(location: string): Promise<boolean>;
+    /**
+     * Delete multiple files at once (uses batch delete for efficiency)
+     */
+    deleteMany(locations: string[]): Promise<DeleteManyResult[]>;
+    /**
+     * Delete directory (recursively deletes all objects with matching prefix)
+     *
+     * S3/R2 doesn't have true directories - only key prefixes.
+     * This method lists all objects with the prefix and deletes them in batches.
+     *
+     * @param directoryPath - Directory prefix to delete
+     * @returns true when all objects are deleted
+     */
+    deleteDirectory(directoryPath: string): Promise<boolean>;
+    /**
+     * Check if file exists
+     */
+    exists(location: string): Promise<boolean>;
+    /**
+     * Get a temporary presigned URL (alias for getPresignedUrl)
+     */
+    temporaryUrl(location: string, expiresIn?: number): Promise<string>;
+    /**
+     * Get presigned URL for downloading
+     */
+    getPresignedUrl(location: string, options?: PresignedOptions): Promise<string>;
+    /**
+     * Get presigned URL for uploading
+     */
+    getPresignedUploadUrl(location: string, options?: PresignedUploadOptions): Promise<string>;
+    /**
+     * Get file info/metadata without downloading
+     */
+    getInfo(location: string): Promise<StorageFileInfo>;
+    /**
+     * Get file size in bytes (shortcut for getInfo().size)
+     */
+    size(location: string): Promise<number>;
+    /**
+     * Copy file to a new location
+     */
+    copy(from: string, to: string): Promise<CloudStorageFileData>;
+    /**
+     * Move file to a new location
+     */
+    move(from: string, to: string): Promise<CloudStorageFileData>;
+    /**
+     * List files in a directory
+     */
+    list(directory: string, options?: ListOptions): Promise<StorageFileInfo[]>;
+    /**
+     * Get bucket name
+     */
+    getBucket(): string;
+    /**
+     * Get region
+     */
+    getRegion(): string;
+    /**
+     * Set storage class (e.g., STANDARD, GLACIER, etc.)
+     */
+    setStorageClass(location: string, storageClass: string): Promise<void>;
+    /**
+     * Set file visibility (public or private)
+     */
+    setVisibility(location: string, visibility: FileVisibility): Promise<void>;
+    /**
+     * Get file visibility
+     */
+    getVisibility(location: string): Promise<FileVisibility>;
+    /**
+     * Calculate SHA-256 hash
+     */
+    protected calculateHash(buffer: Buffer): string;
+    /**
+     * Guess MIME type from file extension
+     */
+    protected guessMimeType(location: string): string;
+}
+//# sourceMappingURL=cloud-driver.d.ts.map

package/esm/storage/drivers/cloud-driver.d.ts.map

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