express-storage 2.0.2 → 3.0.0

package/dist/index.d.ts

@@ -1,30 +0,0 @@
-/**
- * Express Storage
- *
- * Unified file upload and storage management for Express.js.
- * One API for local disk, AWS S3, Google Cloud Storage, and Azure Blob Storage.
- *
- * @example
- * import { StorageManager } from 'express-storage';
- *
- * // Initialize (reads from environment variables)
- * const storage = new StorageManager();
- *
- * // Upload a file
- * const result = await storage.uploadFile(req.file);
- *
- * // Generate presigned URL for client-side upload
- * const url = await storage.generateUploadUrl('photo.jpg', 'image/jpeg', 12345);
- */
-export { StorageManager } from './storage-manager.js';
-export { StorageDriverFactory } from './factory/driver.factory.js';
-export type { StorageDriver, FileUploadResult, DeleteResult, PresignedUrlResult, StorageConfig, StorageOptions, StorageCredentials, FileValidationOptions, UploadOptions, FileMetadata, FileInput, SingleFileInput, MultipleFilesInput, IStorageDriver, ValidationResult, EnvironmentConfig, BlobValidationOptions, BlobValidationResult, ListFilesResult, FileInfo, Logger, RateLimitOptions } from './types/storage.types.js';
-export { loadAndValidateConfig, validateStorageConfig, initializeDotenv, resetDotenvInitialization } from './utils/config.utils.js';
-export { generateUniqueFileName, sanitizeFileName, validateFileName, createMonthBasedPath, ensureDirectoryExists, formatFileSize, validateFileSize, validateFileType, getFileExtension, isImageFile, isDocumentFile, withRetry, sleep, withConcurrencyLimit } from './utils/file.utils.js';
-export type { RetryOptions, ConcurrencyOptions } from './utils/file.utils.js';
-export { BaseStorageDriver } from './drivers/base.driver.js';
-export { LocalStorageDriver } from './drivers/local.driver.js';
-export { S3StorageDriver, S3PresignedStorageDriver } from './drivers/s3.driver.js';
-export { GCSStorageDriver, GCSPresignedStorageDriver } from './drivers/gcs.driver.js';
-export { AzureStorageDriver, AzurePresignedStorageDriver } from './drivers/azure.driver.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACR,MAAM,EACN,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAGpI,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,SAAS,EACT,KAAK,EACL,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -1,33 +0,0 @@
-/**
- * Express Storage
- *
- * Unified file upload and storage management for Express.js.
- * One API for local disk, AWS S3, Google Cloud Storage, and Azure Blob Storage.
- *
- * @example
- * import { StorageManager } from 'express-storage';
- *
- * // Initialize (reads from environment variables)
- * const storage = new StorageManager();
- *
- * // Upload a file
- * const result = await storage.uploadFile(req.file);
- *
- * // Generate presigned URL for client-side upload
- * const url = await storage.generateUploadUrl('photo.jpg', 'image/jpeg', 12345);
- */
-// Main class
-export { StorageManager } from './storage-manager.js';
-// Factory
-export { StorageDriverFactory } from './factory/driver.factory.js';
-// Configuration utilities
-export { loadAndValidateConfig, validateStorageConfig, initializeDotenv, resetDotenvInitialization } from './utils/config.utils.js';
-// File utilities
-export { generateUniqueFileName, sanitizeFileName, validateFileName, createMonthBasedPath, ensureDirectoryExists, formatFileSize, validateFileSize, validateFileType, getFileExtension, isImageFile, isDocumentFile, withRetry, sleep, withConcurrencyLimit } from './utils/file.utils.js';
-// Driver classes (for custom implementations or direct use)
-export { BaseStorageDriver } from './drivers/base.driver.js';
-export { LocalStorageDriver } from './drivers/local.driver.js';
-export { S3StorageDriver, S3PresignedStorageDriver } from './drivers/s3.driver.js';
-export { GCSStorageDriver, GCSPresignedStorageDriver } from './drivers/gcs.driver.js';
-export { AzureStorageDriver, AzurePresignedStorageDriver } from './drivers/azure.driver.js';
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,UAAU;AACV,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AA4BnE,0BAA0B;AAC1B,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEpI,iBAAiB;AACjB,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,SAAS,EACT,KAAK,EACL,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAG/B,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/storage-manager.d.ts

@@ -1,228 +0,0 @@
-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 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);
-     * }
-     */
-    listFiles(prefix?: string, maxResults?: number, continuationToken?: string): Promise<ListFilesResult>;
-    /**
-     * 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.
-     */
-    getConfig(): StorageConfig;
-    /**
-     * 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
-     */
-    getSafeConfig(): StorageConfig;
-    /**
-     * Returns which storage driver is currently active.
-     */
-    getDriverType(): StorageDriver;
-    /**
-     * 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.
-     */
-    isPresignedUploadMode(): boolean;
-    /**
-     * 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`);
-     * }
-     */
-    getRateLimitStatus(): {
-        remainingRequests: number;
-        resetTimeMs: number;
-    } | null;
-    /**
-     * Returns all available storage drivers.
-     */
-    static getAvailableDrivers(): StorageDriver[];
-    /**
-     * Clears the internal driver cache.
-     * Useful in tests or when you've changed credentials.
-     */
-    static clearCache(): void;
-    /**
-     * Validates a file against the provided rules.
-     * Returns an error message if validation fails, null if it passes.
-     */
-    private validateFile;
-}
-//# sourceMappingURL=storage-manager.d.ts.map

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

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