express-storage 1.0.0 → 1.1.2

package/dist/storage-manager.d.ts

@@ -1,75 +1,228 @@
-import { FileUploadResult, PresignedUrlResult, FileInput, StorageConfig } from './types/storage.types.js';
-/**
- * Main storage manager class
- */
+import { FileUploadResult, DeleteResult, PresignedUrlResult, FileInput, StorageConfig, StorageOptions, FileValidationOptions, StorageDriver, BlobValidationOptions, BlobValidationResult, ListFilesResult, UploadOptions, FileMetadata } from './types/storage.types.js';
 export declare class StorageManager {
     private driver;
     private config;
-    private isInitialized;
-    constructor();
-    /**
-     * Initialize storage manager with custom configuration
-     */
-    static initialize(config?: Partial<StorageConfig>): StorageManager;
-    /**
-     * Upload a single file
-     */
-    uploadFile(file: Express.Multer.File): Promise<FileUploadResult>;
-    /**
-     * Upload multiple files
-     */
-    uploadFiles(files: Express.Multer.File[]): Promise<FileUploadResult[]>;
-    /**
-     * Upload files with input type detection
-     */
-    upload(input: FileInput): Promise<FileUploadResult | FileUploadResult[]>;
-    /**
-     * Generate upload URL for presigned uploads
+    private logger;
+    private rateLimiter;
+    constructor(options?: StorageOptions);
+    /**
+     * Builds the final configuration by merging environment variables with any
+     * options you passed in. Your explicit options always win over env vars.
+     */
+    private buildConfig;
+    /**
+     * Uploads a single file to your configured storage.
+     *
+     * This is the method you'll use most often. It handles everything:
+     * validation, unique naming, and the actual upload.
+     *
+     * @param file - The file from Multer (req.file)
+     * @param validation - Optional rules like max size and allowed types
+     * @param uploadOptions - Optional metadata, cache headers, etc.
+     *
+     * @example
+     * // Simple upload
+     * const result = await storage.uploadFile(req.file);
+     *
+     * // With validation (reject files over 5MB or wrong type)
+     * const result = await storage.uploadFile(req.file, {
+     *   maxSize: 5 * 1024 * 1024,
+     *   allowedMimeTypes: ['image/jpeg', 'image/png']
+     * });
+     *
+     * // With custom metadata
+     * const result = await storage.uploadFile(req.file, undefined, {
+     *   metadata: { uploadedBy: 'user123' },
+     *   cacheControl: 'max-age=31536000'
+     * });
+     */
+    uploadFile(file: Express.Multer.File, validation?: FileValidationOptions, uploadOptions?: UploadOptions): Promise<FileUploadResult>;
+    /**
+     * Uploads multiple files at once.
+     *
+     * Files are processed in parallel (up to 10 at a time) for speed,
+     * but each file gets its own result — so one failure doesn't stop the others.
+     */
+    uploadFiles(files: Express.Multer.File[], validation?: FileValidationOptions, uploadOptions?: UploadOptions): Promise<FileUploadResult[]>;
+    /**
+     * Smart upload that handles both single files and arrays.
+     * Pass in what you have and it figures out the rest.
+     */
+    upload(input: FileInput, validation?: FileValidationOptions, uploadOptions?: UploadOptions): Promise<FileUploadResult | FileUploadResult[]>;
+    /**
+     * Creates a presigned URL that lets clients upload directly to cloud storage.
+     *
+     * This is powerful for large files — the upload goes straight to S3/GCS/Azure
+     * without passing through your server, saving bandwidth and processing time.
+     *
+     * The URL is time-limited and (for S3/GCS) locked to specific file constraints.
+     *
+     * Rate limiting: If you configured `rateLimit` in StorageOptions, this method
+     * will reject requests that exceed the limit with an error.
+     *
+     * @param fileName - What the user wants to call their file
+     * @param contentType - The MIME type (e.g., 'image/jpeg')
+     * @param fileSize - Exact size in bytes (enforced by S3/GCS, advisory for Azure)
+     * @param folder - Where to put the file (overrides your default BUCKET_PATH)
+     *
+     * @example
+     * const result = await storage.generateUploadUrl('photo.jpg', 'image/jpeg', 12345);
+     * // Give result.uploadUrl to your frontend
+     * // Save result.reference — you'll need it to view or delete the file later
+     */
+    generateUploadUrl(fileName: string, contentType?: string, fileSize?: number, folder?: string): Promise<PresignedUrlResult>;
+    /**
+     * Combines folder and filename into a full path.
+     * Handles edge cases like leading/trailing slashes.
+     */
+    private buildFilePath;
+    /**
+     * Checks folder paths for security issues.
+     * Blocks path traversal attempts and other sneaky tricks.
+     */
+    private validateFolderPath;
+    /**
+     * Checks if a string looks like a valid MIME type.
+     */
+    private isValidMimeType;
+    /**
+     * Converts bytes to a human-readable string like "5.2 MB".
+     */
+    private formatBytes;
+    /**
+     * Creates a presigned URL for viewing/downloading an existing file.
+     *
+     * Rate limiting: If configured, this counts toward the presigned URL rate limit.
+     *
+     * @param reference - The full path you got from generateUploadUrl
+     */
+    generateViewUrl(reference: string): Promise<PresignedUrlResult>;
+    /**
+     * Verifies that a presigned upload actually happened and the file is valid.
+     *
+     * For Azure, this is essential — Azure doesn't enforce file constraints at
+     * the URL level, so we check the actual blob properties here.
+     *
+     * For S3/GCS, this confirms the file exists and optionally validates it.
+     *
+     * @param reference - The file path from generateUploadUrl
+     * @param options - Expected content type and size to validate against
+     *
+     * @example
+     * // After the client uploads, verify everything looks right
+     * const result = await storage.validateAndConfirmUpload(reference, {
+     *   expectedContentType: 'image/jpeg',
+     *   expectedFileSize: 12345
+     * });
+     */
+    validateAndConfirmUpload(reference: string, options?: BlobValidationOptions): Promise<BlobValidationResult>;
+    /**
+     * Returns true if you're using Azure presigned mode.
+     *
+     * This is your hint that you MUST call validateAndConfirmUpload()
+     * after presigned uploads — Azure doesn't enforce constraints otherwise.
+     */
+    requiresPostUploadValidation(): boolean;
+    /**
+     * Creates presigned upload URLs for multiple files at once.
+     * Great for batch uploads or when letting users select multiple files.
+     *
+     * @param files - Array of filenames (strings) or file metadata objects
+     * @param folder - Optional folder to put all files in
+     */
+    generateUploadUrls(files: (string | FileMetadata)[], folder?: string): Promise<PresignedUrlResult[]>;
+    /**
+     * Creates presigned view URLs for multiple files at once.
+     * Useful when displaying a gallery or list of downloadable files.
+     */
+    generateViewUrls(references: string[]): Promise<PresignedUrlResult[]>;
+    /**
+     * Deletes a single file from storage.
+     *
+     * @param reference - The full path from uploadFile result or generateUploadUrl
+     * @returns true if deleted, false if not found
+     */
+    deleteFile(reference: string): Promise<boolean>;
+    /**
+     * Deletes multiple files at once.
+     * Returns detailed results so you know exactly what succeeded and what failed.
+     */
+    deleteFiles(references: string[]): Promise<DeleteResult[]>;
+    /**
+     * Lists files in your storage with optional filtering and pagination.
+     *
+     * @param prefix - Only show files starting with this path (e.g., 'uploads/2026/')
+     * @param maxResults - How many files to return per page (default: 1000)
+     * @param continuationToken - Pass the nextToken from a previous response to get the next page
+     *
+     * @example
+     * // Get all files
+     * const result = await storage.listFiles();
+     *
+     * // Get files in a specific folder
+     * const result = await storage.listFiles('users/123/');
+     *
+     * // Paginate through large results
+     * let result = await storage.listFiles(undefined, 100);
+     * while (result.nextToken) {
+     *   result = await storage.listFiles(undefined, 100, result.nextToken);
+     * }
      */
-    generateUploadUrl(fileName: string): Promise<PresignedUrlResult>;
+    listFiles(prefix?: string, maxResults?: number, continuationToken?: string): Promise<ListFilesResult>;
     /**
-     * Generate view URL for presigned uploads
+     * Returns a copy of the current configuration.
+     *
+     * WARNING: This includes sensitive credentials like AWS keys, Azure connection strings, etc.
+     * Use getSafeConfig() instead if you're logging or exposing this to users.
      */
-    generateViewUrl(fileName: string): Promise<PresignedUrlResult>;
-    /**
-     * Generate multiple upload URLs
-     */
-    generateUploadUrls(fileNames: string[]): Promise<PresignedUrlResult[]>;
-    /**
-     * Generate multiple view URLs
-     */
-    generateViewUrls(fileNames: string[]): Promise<PresignedUrlResult[]>;
-    /**
-     * Delete a single file
-     */
-    deleteFile(fileName: string): Promise<boolean>;
+    getConfig(): StorageConfig;
     /**
-     * Delete multiple files
+     * Returns a copy of the configuration with sensitive values masked.
+     * Safe for logging, debugging, or displaying to users.
+     *
+     * Masked fields: awsAccessKey, awsSecretKey, azureConnectionString,
+     * azureAccountKey, gcsCredentials
      */
-    deleteFiles(fileNames: string[]): Promise<boolean[]>;
+    getSafeConfig(): StorageConfig;
     /**
-     * Get current configuration
+     * Returns which storage driver is currently active.
      */
-    getConfig(): StorageConfig;
+    getDriverType(): StorageDriver;
     /**
-     * Get current driver type
+     * Returns true if the driver operates in presigned mode.
+     *
+     * In presigned mode, upload() returns URLs instead of uploading directly.
+     * All cloud drivers can generate presigned URLs via generateUploadUrl()
+     * regardless of this setting.
      */
-    getDriverType(): string;
+    isPresignedUploadMode(): boolean;
     /**
-     * Check if presigned URLs are supported
+     * Returns rate limit status information.
+     * Returns null if rate limiting is not configured.
+     *
+     * @example
+     * const status = storage.getRateLimitStatus();
+     * if (status && status.remainingRequests === 0) {
+     *   console.log(`Rate limited. Resets in ${status.resetTimeMs}ms`);
+     * }
      */
-    isPresignedSupported(): boolean;
+    getRateLimitStatus(): {
+        remainingRequests: number;
+        resetTimeMs: number;
+    } | null;
     /**
-     * Get available drivers
+     * Returns all available storage drivers.
      */
-    static getAvailableDrivers(): string[];
+    static getAvailableDrivers(): StorageDriver[];
     /**
-     * Clear driver cache
+     * Clears the internal driver cache.
+     * Useful in tests or when you've changed credentials.
      */
     static clearCache(): void;
     /**
-     * Ensure storage manager is initialized
+     * Validates a file against the provided rules.
+     * Returns an error message if validation fails, null if it passes.
      */
-    private ensureInitialized;
+    private validateFile;
 }
 //# sourceMappingURL=storage-manager.d.ts.map

package/dist/storage-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-manager.d.ts","sourceRoot":"","sources":["../src/storage-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,gBAAgB,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAI1H;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAkB;;IAevC;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,cAAc;IAsBlE;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKtE;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAK5E;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;IAU9E;;OAEG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKtE;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKpE;;OAEG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAK5E;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAK1E;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpD;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAK1D;;OAEG;IACH,SAAS,IAAI,aAAa;IAI1B;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B;;OAEG;IACH,MAAM,CAAC,mBAAmB,IAAI,MAAM,EAAE;IAItC;;OAEG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI;IAIzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}
+{"version":3,"file":"storage-manager.d.ts","sourceRoot":"","sources":["../src/storage-manager.ts"],"names":[],"mappings":"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"}