express-storage 2.0.2 → 3.0.0

package/dist/cjs/factory/driver.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.factory.js","sourceRoot":"","sources":["../../../src/factory/driver.factory.ts"],"names":[],"mappings":";;;;;;AAcA,oCAgBC;AAKD,kDAUC;AA7CD,oDAA4B;AAE5B,gEAAgE;AAChE,0DAA0D;AAC1D,4DAA4D;AAC5D,gEAAgE;AAEhE;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,MAAqB;IAChD,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,OAAO;YACV,OAAO,IAAI,oCAAkB,CAAC,MAAM,CAAC,CAAC;QACxC,KAAK,IAAI,CAAC;QACV,KAAK,cAAc;YACjB,OAAO,IAAI,8BAAe,CAAC,MAAM,CAAC,CAAC;QACrC,KAAK,KAAK,CAAC;QACX,KAAK,eAAe;YAClB,OAAO,IAAI,gCAAgB,CAAC,MAAM,CAAC,CAAC;QACtC,KAAK,OAAO,CAAC;QACb,KAAK,iBAAiB;YACpB,OAAO,IAAI,oCAAkB,CAAC,MAAM,CAAC,CAAC;QACxC;YACE,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB;IACjC,OAAO;QACL,OAAO;QACP,IAAI;QACJ,cAAc;QACd,KAAK;QACL,eAAe;QACf,OAAO;QACP,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAa,oBAAoB;IACd,OAAO,GAAgC,IAAI,GAAG,EAAE,CAAC;IAE1D,UAAU,CAAC,MAAqB;QACtC,OAAO,gBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,CAAC;IAED,WAAW,CAAC,MAAqB;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAEpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC9B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,mBAAmB;QACxB,OAAO,mBAAmB,EAAE,CAAC;IAC/B,CAAC;CACF;AArCD,oDAqCC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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';
+ *
+ * const storage = new StorageManager({ driver: 'local' });
+ * const result = await storage.uploadFile(req.file);
+ *
+ * if (result.success) {
+ *   console.log(result.reference); // stored file path
+ * }
+ *
+ * // Advanced imports:
+ * // import { withRetry, formatFileSize } from 'express-storage/utils';
+ * // import { BaseStorageDriver } from 'express-storage/drivers';
+ * // import { validateStorageConfig } from 'express-storage/config';
+ */
+export { StorageManager } from './storage-manager.js';
+export { InMemoryRateLimiter } from './utils/rate-limiter.js';
+export type { StorageDriver, StorageErrorCode, FileUploadResult, FileUploadSuccess, FileUploadError, DeleteResult, DeleteSuccess, DeleteError, PresignedUrlResult, PresignedUrlSuccess, PresignedUrlError, PresignedUploadUrlResult, PresignedUploadUrlSuccess, PresignedViewUrlResult, PresignedViewUrlSuccess, BlobValidationResult, BlobValidationSuccess, BlobValidationError, ListFilesResult, ListFilesSuccess, ListFilesError, StorageConfig, PublicStorageConfig, StorageOptions, StorageCredentials, FileValidationOptions, UploadOptions, FileMetadata, IStorageDriver, ValidationResult, EnvironmentConfig, BlobValidationOptions, FileInfo, Logger, RateLimitOptions, RateLimiterAdapter, StorageHooks, HookErrorContext, BatchOptions, } from './types/storage.types.js';
+export type { RetryOptions, ConcurrencyOptions } from './utils/file.utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,QAAQ,EACR,MAAM,EACN,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * 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';
+ *
+ * const storage = new StorageManager({ driver: 'local' });
+ * const result = await storage.uploadFile(req.file);
+ *
+ * if (result.success) {
+ *   console.log(result.reference); // stored file path
+ * }
+ *
+ * // Advanced imports:
+ * // import { withRetry, formatFileSize } from 'express-storage/utils';
+ * // import { BaseStorageDriver } from 'express-storage/drivers';
+ * // import { validateStorageConfig } from 'express-storage/config';
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryRateLimiter = exports.StorageManager = void 0;
+// Core class
+var storage_manager_js_1 = require("./storage-manager.js");
+Object.defineProperty(exports, "StorageManager", { enumerable: true, get: function () { return storage_manager_js_1.StorageManager; } });
+// Rate limiter (needed for StorageOptions.rateLimiter)
+var rate_limiter_js_1 = require("./utils/rate-limiter.js");
+Object.defineProperty(exports, "InMemoryRateLimiter", { enumerable: true, get: function () { return rate_limiter_js_1.InMemoryRateLimiter; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,aAAa;AACb,2DAAsD;AAA7C,oHAAA,cAAc,OAAA;AAEvB,uDAAuD;AACvD,2DAA8D;AAArD,sHAAA,mBAAmB,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

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

@@ -0,0 +1,210 @@
+import { FileUploadResult, DeleteResult, PresignedUploadUrlResult, PresignedViewUrlResult, PublicStorageConfig, StorageOptions, FileValidationOptions, StorageDriver, BlobValidationOptions, BlobValidationResult, ListFilesResult, UploadOptions, FileMetadata, FileInfo, BatchOptions } from './types/storage.types.js';
+/**
+ * StorageManager - Your single point of contact for all file operations.
+ *
+ * Think of it as a universal remote that works with any storage provider.
+ * You don't need to know the specifics of S3, GCS, Azure, or local storage —
+ * just tell StorageManager what you want to do and it handles the rest.
+ *
+ * @example
+ * // The simplest setup - just reads from your .env file
+ * const storage = new StorageManager();
+ *
+ * // Full-featured setup
+ * const storage = new StorageManager({
+ *   driver: 's3',
+ *   credentials: { bucketName: 'my-bucket', awsRegion: 'us-east-1' },
+ *   hooks: {
+ *     beforeUpload: async (file) => { await virusScan(file.buffer); },
+ *     afterUpload: (result) => { auditLog('file_uploaded', result); },
+ *   },
+ *   rateLimiter: { maxRequests: 100, windowMs: 60000 },
+ *   concurrency: 5,
+ * });
+ */
+export declare class StorageManager {
+    private driver;
+    private readonly config;
+    private readonly logger;
+    private rateLimiter;
+    private hooks;
+    private readonly concurrency;
+    private destroyed;
+    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;
+    private assertNotDestroyed;
+    /**
+     * Uploads a single file to your configured storage.
+     *
+     * @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
+     * const result = await storage.uploadFile(req.file, {
+     *   maxSize: 5 * 1024 * 1024,
+     *   allowedMimeTypes: ['image/jpeg', 'image/png'],
+     * });
+     * if (result.success) {
+     *   console.log(result.reference, result.fileUrl);
+     * }
+     */
+    uploadFile(file: Express.Multer.File, validation?: FileValidationOptions, uploadOptions?: UploadOptions): Promise<FileUploadResult>;
+    /**
+     * Uploads multiple files at once.
+     * Files are processed in parallel (up to concurrency limit) for speed,
+     * but each file gets its own result — one failure doesn't stop the others.
+     *
+     * @example
+     * const results = await storage.uploadFiles(req.files, {
+     *   maxSize: 10 * 1024 * 1024,
+     * });
+     * const uploaded = results.filter(r => r.success);
+     * const failed = results.filter(r => !r.success);
+     */
+    uploadFiles(files: Express.Multer.File[], validation?: FileValidationOptions, uploadOptions?: UploadOptions, options?: BatchOptions): Promise<FileUploadResult[]>;
+    /**
+     * Creates a presigned URL that lets clients upload directly to cloud storage.
+     *
+     * The URL is time-limited and (for S3/GCS) locked to specific file constraints.
+     *
+     * @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', 204800);
+     * if (result.success) {
+     *   // result.uploadUrl  — PUT request goes here
+     *   // result.reference  — save this to confirm/view/delete later
+     *   // result.expiresIn  — seconds until URL expires
+     * }
+     */
+    generateUploadUrl(fileName: string, contentType?: string, fileSize?: number, folder?: string): Promise<PresignedUploadUrlResult>;
+    /**
+     * Creates a presigned URL for viewing/downloading an existing file.
+     *
+     * @param reference - The full path you got from generateUploadUrl
+     */
+    generateViewUrl(reference: string): Promise<PresignedViewUrlResult>;
+    /**
+     * 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.
+     */
+    validateAndConfirmUpload(reference: string, options?: BlobValidationOptions): Promise<BlobValidationResult>;
+    /**
+     * Returns true if you're using Azure presigned mode.
+     * Your hint that you MUST call validateAndConfirmUpload() after presigned uploads.
+     */
+    requiresPostUploadValidation(): boolean;
+    /**
+     * Creates presigned upload URLs for multiple files at once.
+     */
+    generateUploadUrls(files: (string | FileMetadata)[], folder?: string, options?: BatchOptions): Promise<PresignedUploadUrlResult[]>;
+    /**
+     * Creates presigned view URLs for multiple files at once.
+     */
+    generateViewUrls(references: string[], options?: BatchOptions): Promise<PresignedViewUrlResult[]>;
+    /**
+     * Deletes a single file from storage.
+     *
+     * @param reference - The full path from uploadFile result or generateUploadUrl
+     * @returns DeleteResult with success status and error details on failure
+     *
+     * @example
+     * const result = await storage.deleteFile(uploadResult.reference);
+     * if (!result.success) {
+     *   console.log(result.error, result.code); // e.g., 'FILE_NOT_FOUND'
+     * }
+     */
+    deleteFile(reference: string): Promise<DeleteResult>;
+    /**
+     * Deletes multiple files at once.
+     */
+    deleteFiles(references: string[], options?: BatchOptions): Promise<DeleteResult[]>;
+    /**
+     * Lists files in your storage with optional filtering and pagination.
+     *
+     * @param prefix - Only show files starting with this path
+     * @param maxResults - How many files to return per page (default: 1000)
+     * @param continuationToken - Pass nextToken from previous response for next page
+     */
+    listFiles(prefix?: string, maxResults?: number, continuationToken?: string): Promise<ListFilesResult>;
+    /**
+     * Returns metadata about a file without downloading it.
+     *
+     * @param reference - The full path from uploadFile result or generateUploadUrl
+     * @returns FileInfo with name, size, contentType, lastModified — or null if not found
+     *
+     * @example
+     * const info = await storage.getMetadata(uploadResult.reference);
+     * if (info) {
+     *   console.log(`${info.name}: ${info.size} bytes, ${info.contentType}`);
+     * }
+     */
+    getMetadata(reference: string): Promise<FileInfo | null>;
+    /**
+     * Returns true if a file exists at the given reference.
+     *
+     * @param reference - The full path from uploadFile result or generateUploadUrl
+     */
+    exists(reference: string): Promise<boolean>;
+    /**
+     * Returns a copy of the current configuration without credentials.
+     * Safe to log, expose in admin panels, or include in error reports.
+     */
+    getConfig(): PublicStorageConfig;
+    getDriverType(): StorageDriver;
+    /**
+     * Returns true if the driver operates in presigned mode.
+     * In presigned mode, upload() returns URLs instead of uploading directly.
+     */
+    isPresignedUploadMode(): boolean;
+    /**
+     * Returns rate limit status information.
+     * Returns null if rate limiting is not configured.
+     */
+    getRateLimitStatus(): Promise<{
+        remainingRequests: number;
+        resetTimeMs: number;
+    } | null>;
+    static getAvailableDrivers(): StorageDriver[];
+    /**
+     * Releases resources held by this StorageManager instance.
+     * Clears the rate limiter and hooks. The instance should not be reused
+     * after calling this method.
+     *
+     * @example
+     * const storage = new StorageManager({ driver: 's3' });
+     * // ... use storage ...
+     * storage.destroy(); // free resources
+     */
+    destroy(): void;
+    isDestroyed(): boolean;
+    /**
+     * Shared upload orchestration: validation → beforeUpload hook → driver.upload → afterUpload hook.
+     * Used by both uploadFile() and uploadFiles() to eliminate duplication.
+     */
+    private executeSingleUpload;
+    /**
+     * Shared delete orchestration: path check → beforeDelete hook → driver.delete → afterDelete hook.
+     * Used by both deleteFile() and deleteFiles() to eliminate duplication.
+     */
+    private executeSingleDelete;
+    private checkRateLimit;
+    private buildFilePath;
+    /**
+     * Safely invokes the onError hook. Swallows hook exceptions to prevent
+     * error-in-error-handler cascades.
+     */
+    private invokeOnError;
+}
+//# sourceMappingURL=storage-manager.d.ts.map

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

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