express-storage 2.0.2 → 3.0.0

package/dist/cjs/types/storage.types.d.ts

@@ -0,0 +1,438 @@
+/**
+ * The storage drivers you can use.
+ *
+ * Direct drivers upload through your server.
+ * Presigned drivers give you URLs for client-side uploads.
+ */
+export type StorageDriver = "s3" | "s3-presigned" | "gcs" | "gcs-presigned" | "azure" | "azure-presigned" | "local";
+/**
+ * Programmatic error codes for every failure case.
+ *
+ * Use these to branch on specific error conditions without parsing strings:
+ * ```typescript
+ * if (!result.success) {
+ *   switch (result.code) {
+ *     case 'FILE_TOO_LARGE': showSizeError(); break;
+ *     case 'INVALID_MIME_TYPE': showTypeError(); break;
+ *     case 'RATE_LIMITED': retryLater(); break;
+ *   }
+ * }
+ * ```
+ */
+export type StorageErrorCode = "NO_FILE" | "FILE_EMPTY" | "FILE_TOO_LARGE" | "INVALID_MIME_TYPE" | "INVALID_EXTENSION" | "INVALID_FILENAME" | "INVALID_INPUT" | "PATH_TRAVERSAL" | "FILE_NOT_FOUND" | "VALIDATION_FAILED" | "RATE_LIMITED" | "HOOK_ABORTED" | "PRESIGNED_NOT_SUPPORTED" | "PROVIDER_ERROR";
+/**
+ * What you get back after uploading a file.
+ *
+ * Use `result.success` to narrow the type:
+ * ```typescript
+ * const result = await storage.uploadFile(file);
+ * if (result.success) {
+ *   console.log(result.reference); // TypeScript knows this exists
+ * } else {
+ *   console.log(result.error);    // TypeScript knows this exists
+ *   console.log(result.code);     // e.g., 'FILE_TOO_LARGE'
+ * }
+ * ```
+ */
+export type FileUploadResult = FileUploadSuccess | FileUploadError;
+export interface FileUploadSuccess {
+    success: true;
+    /** The stored file path — pass this to deleteFile(), getMetadata(), generateViewUrl(), etc. */
+    reference: string;
+    /** URL to access the file */
+    fileUrl: string;
+}
+export interface FileUploadError {
+    success: false;
+    /** What went wrong */
+    error: string;
+    /** Programmatic error code */
+    code: StorageErrorCode;
+}
+/**
+ * What you get back after deleting a file.
+ */
+export type DeleteResult = DeleteSuccess | DeleteError;
+export interface DeleteSuccess {
+    success: true;
+    /** The file reference that was deleted */
+    reference: string;
+}
+export interface DeleteError {
+    success: false;
+    /** The file reference that failed to delete */
+    reference: string;
+    /** What went wrong */
+    error: string;
+    /** Programmatic error code */
+    code: StorageErrorCode;
+}
+/**
+ * What you get back when generating presigned URLs.
+ */
+/**
+ * Driver-level presigned URL result. Drivers only set uploadUrl or viewUrl.
+ * StorageManager enriches this into PresignedUploadUrlResult / PresignedViewUrlResult
+ * with guaranteed fields like fileName, reference, and expiresIn.
+ */
+export type PresignedUrlResult = PresignedUrlSuccess | PresignedUrlError;
+export interface PresignedUrlSuccess {
+    success: true;
+    /** URL for uploading (set by generateUploadUrl) */
+    uploadUrl?: string;
+    /** URL for viewing/downloading (set by generateViewUrl) */
+    viewUrl?: string;
+}
+export interface PresignedUrlError {
+    success: false;
+    /** What went wrong */
+    error: string;
+    /** Programmatic error code */
+    code: StorageErrorCode;
+}
+/**
+ * Stricter result from StorageManager.generateUploadUrl().
+ * On success, fileName, reference, uploadUrl, and expiresIn are guaranteed.
+ */
+export type PresignedUploadUrlResult = PresignedUploadUrlSuccess | PresignedUrlError;
+export interface PresignedUploadUrlSuccess extends PresignedUrlSuccess {
+    fileName: string;
+    reference: string;
+    uploadUrl: string;
+    expiresIn: number;
+    /** Folder path if any (e.g., "users/123/uploads") */
+    filePath?: string;
+    /** The content type this URL is restricted to */
+    contentType?: string;
+    /** The file size this URL is restricted to (S3/GCS enforce this) */
+    fileSize?: number;
+    /** True for Azure — you must call validateAndConfirmUpload after */
+    requiresValidation?: boolean;
+}
+/**
+ * Stricter result from StorageManager.generateViewUrl().
+ * On success, reference, viewUrl, and expiresIn are guaranteed.
+ */
+export type PresignedViewUrlResult = PresignedViewUrlSuccess | PresignedUrlError;
+export interface PresignedViewUrlSuccess extends PresignedUrlSuccess {
+    reference: string;
+    viewUrl: string;
+    expiresIn: number;
+}
+/**
+ * What you get back after validating an upload.
+ */
+export type BlobValidationResult = BlobValidationSuccess | BlobValidationError;
+export interface BlobValidationSuccess {
+    success: true;
+    /** The file reference that was validated */
+    reference: string;
+    /** URL to view the file */
+    viewUrl?: string;
+    /** What the file's content type actually is */
+    actualContentType?: string;
+    /** What the file's size actually is */
+    actualFileSize?: number;
+    /** How long the view URL is valid */
+    expiresIn?: number;
+}
+export interface BlobValidationError {
+    success: false;
+    /** What went wrong */
+    error: string;
+    /** Programmatic error code */
+    code: StorageErrorCode;
+    /** Actual content type (for diagnostic purposes) */
+    actualContentType?: string;
+    /** Actual file size (for diagnostic purposes) */
+    actualFileSize?: number;
+}
+/**
+ * What you get back when listing files.
+ */
+export type ListFilesResult = ListFilesSuccess | ListFilesError;
+export interface ListFilesSuccess {
+    success: true;
+    /** The files found */
+    files: FileInfo[];
+    /** Token for getting the next page of results */
+    nextToken?: string;
+}
+export interface ListFilesError {
+    success: false;
+    /** What went wrong */
+    error: string;
+    /** Programmatic error code */
+    code: StorageErrorCode;
+}
+/**
+ * Options for validating uploads (especially important for Azure).
+ */
+export interface BlobValidationOptions {
+    /** The content type you're expecting */
+    expectedContentType?: string;
+    /** The file size you're expecting (in bytes) */
+    expectedFileSize?: number;
+    /** Delete the file if validation fails (default: true) */
+    deleteOnFailure?: boolean;
+}
+/**
+ * Options for validating files before upload.
+ */
+export interface FileValidationOptions {
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Allowed MIME types (e.g., ['image/jpeg', 'image/png']) */
+    allowedMimeTypes?: string[];
+    /** Allowed extensions (e.g., ['.jpg', '.png'] or ['jpg', 'png']) */
+    allowedExtensions?: string[];
+}
+/**
+ * Options for customizing how files are uploaded.
+ */
+export interface UploadOptions {
+    /** Override the detected content type */
+    contentType?: string;
+    /** Custom metadata (key-value pairs stored with the file) */
+    metadata?: Record<string, string>;
+    /** Cache-Control header (e.g., 'max-age=31536000') */
+    cacheControl?: string;
+    /** Content-Disposition header (e.g., 'attachment; filename="file.pdf"') */
+    contentDisposition?: string;
+    /** AbortSignal to cancel an in-flight upload */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * File metadata for generating multiple presigned URLs at once.
+ */
+export interface FileMetadata {
+    /** The filename */
+    fileName: string;
+    /** MIME type (e.g., 'image/jpeg') */
+    contentType?: string;
+    /** File size in bytes */
+    fileSize?: number;
+}
+/**
+ * Context passed to the onError hook.
+ */
+export interface HookErrorContext {
+    operation: "upload" | "uploadMultiple" | "delete" | "deleteMultiple" | "generateUploadUrl" | "generateViewUrl" | "validateUpload" | "listFiles";
+    file?: Express.Multer.File;
+    reference?: string;
+}
+/**
+ * Hooks let you tap into the upload/delete lifecycle without modifying drivers.
+ *
+ * All hooks are optional and async-safe. If a "before" hook throws, the
+ * operation is aborted and an error result is returned.
+ *
+ * @example
+ * const storage = new StorageManager({
+ *   driver: 's3',
+ *   hooks: {
+ *     beforeUpload: async (file) => {
+ *       await virusScan(file.buffer);
+ *     },
+ *     afterUpload: (result) => {
+ *       auditLog('file_uploaded', result);
+ *     },
+ *     onError: (error, ctx) => {
+ *       metrics.increment('storage.error', { operation: ctx.operation });
+ *     },
+ *   },
+ * });
+ */
+export interface StorageHooks {
+    /** Called before each file upload. Throw to abort. */
+    beforeUpload?: (file: Express.Multer.File, options?: UploadOptions) => void | Promise<void>;
+    /** Called after each file upload (success or failure). */
+    afterUpload?: (result: FileUploadResult, file: Express.Multer.File) => void | Promise<void>;
+    /** Called before each file deletion. Throw to abort. */
+    beforeDelete?: (reference: string) => void | Promise<void>;
+    /** Called after each file deletion. */
+    afterDelete?: (reference: string, success: boolean) => void | Promise<void>;
+    /** Called when any operation encounters an error. */
+    onError?: (error: Error, context: HookErrorContext) => void | Promise<void>;
+}
+/**
+ * Adapter interface for rate limiting presigned URL generation.
+ *
+ * The built-in InMemoryRateLimiter works for single-process apps.
+ * For multi-process/clustered deployments, implement this interface
+ * backed by Redis, Memcached, or another shared store.
+ *
+ * @example
+ * // Custom Redis-backed rate limiter
+ * class RedisRateLimiter implements RateLimiterAdapter {
+ *   async tryAcquire() { ... }
+ *   async getRemainingRequests() { ... }
+ *   async getResetTime() { ... }
+ * }
+ * const storage = new StorageManager({
+ *   driver: 's3',
+ *   rateLimiter: new RedisRateLimiter(redis),
+ * });
+ */
+export interface RateLimiterAdapter {
+    /** Check if a request is allowed and record it if so. */
+    tryAcquire(): boolean | Promise<boolean>;
+    /** Get the number of remaining requests in the current window. */
+    getRemainingRequests(): number | Promise<number>;
+    /** Get the time until the rate limit resets (in ms). */
+    getResetTime(): number | Promise<number>;
+}
+/**
+ * Shorthand options for creating the built-in InMemoryRateLimiter.
+ */
+export interface RateLimitOptions {
+    /** Maximum number of presigned URLs that can be generated per window */
+    maxRequests: number;
+    /** Time window in milliseconds (default: 60000 = 1 minute) */
+    windowMs?: number;
+}
+/**
+ * Logging interface — pass your own logger if you want debug output.
+ */
+export interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Credentials and settings for storage configuration.
+ *
+ * These can be passed programmatically to override environment variables.
+ */
+export interface StorageCredentials {
+    /** Bucket or container name (S3/GCS bucket, Azure container) */
+    bucketName?: string;
+    /** Default folder path (e.g., 'uploads/files') */
+    bucketPath?: string;
+    /** Local storage directory */
+    localPath?: string;
+    /** How long presigned URLs stay valid (seconds, default: 600) */
+    presignedUrlExpiry?: number;
+    /** Maximum file size (bytes, default: 5GB) */
+    maxFileSize?: number;
+    awsRegion?: string;
+    awsAccessKey?: string;
+    awsSecretKey?: string;
+    gcsProjectId?: string;
+    gcsCredentials?: string;
+    azureConnectionString?: string;
+    azureAccountName?: string;
+    azureAccountKey?: string;
+    /** Azure container name (overrides bucketName for Azure driver) */
+    azureContainerName?: string;
+}
+/**
+ * Options for initializing StorageManager.
+ */
+export interface StorageOptions {
+    /** Which storage driver to use */
+    driver: StorageDriver;
+    /** Credentials and settings (optional — can come from env vars) */
+    credentials?: StorageCredentials;
+    /** Your logger (optional — silent by default) */
+    logger?: Logger;
+    /**
+     * Rate limiting for presigned URL generation.
+     * Pass RateLimitOptions for the built-in in-memory limiter,
+     * or a RateLimiterAdapter for a custom implementation (e.g., Redis).
+     */
+    rateLimiter?: RateLimitOptions | RateLimiterAdapter;
+    /** Lifecycle hooks (optional) */
+    hooks?: StorageHooks;
+    /** Maximum parallel operations for batch methods (default: 10) */
+    concurrency?: number;
+}
+/**
+ * Options for batch operations (uploadFiles, deleteFiles, etc.).
+ */
+export interface BatchOptions {
+    /** AbortSignal to cancel the batch operation mid-flight. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Public configuration — safe to expose via getConfig().
+ * Contains non-sensitive settings only.
+ */
+export interface PublicStorageConfig {
+    driver: StorageDriver;
+    bucketName?: string | undefined;
+    bucketPath?: string | undefined;
+    localPath?: string | undefined;
+    presignedUrlExpiry?: number | undefined;
+    maxFileSize?: number | undefined;
+    awsRegion?: string | undefined;
+    gcsProjectId?: string | undefined;
+    azureAccountName?: string | undefined;
+    azureContainerName?: string | undefined;
+}
+/**
+ * Internal configuration format (used by drivers). Extends the public config
+ * with sensitive credential fields that should never be exposed to consumers.
+ */
+export interface StorageConfig extends PublicStorageConfig {
+    awsAccessKey?: string | undefined;
+    awsSecretKey?: string | undefined;
+    gcsCredentials?: string | undefined;
+    azureConnectionString?: string | undefined;
+    azureAccountKey?: string | undefined;
+}
+/**
+ * Information about a single file.
+ */
+export interface FileInfo {
+    /** File path/name */
+    name: string;
+    /** File size in bytes */
+    size?: number;
+    /** MIME type */
+    contentType?: string;
+    /** When the file was last modified */
+    lastModified?: Date;
+}
+/**
+ * The interface all storage drivers implement.
+ */
+export interface IStorageDriver {
+    upload(file: Express.Multer.File, options?: UploadOptions): Promise<FileUploadResult>;
+    generateUploadUrl(fileName: string, contentType?: string, fileSize?: number): Promise<PresignedUrlResult>;
+    generateViewUrl(fileName: string): Promise<PresignedUrlResult>;
+    delete(fileName: string): Promise<DeleteResult>;
+    validateAndConfirmUpload(reference: string, options?: BlobValidationOptions): Promise<BlobValidationResult>;
+    listFiles(prefix?: string, maxResults?: number, continuationToken?: string): Promise<ListFilesResult>;
+    getMetadata(reference: string): Promise<FileInfo | null>;
+    /** Releases SDK client connections and internal resources. */
+    destroy(): void;
+}
+/**
+ * Result of configuration validation.
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+}
+/**
+ * Environment variables we look for.
+ */
+export interface EnvironmentConfig {
+    FILE_DRIVER: string;
+    BUCKET_NAME?: string | undefined;
+    BUCKET_PATH?: string | undefined;
+    LOCAL_PATH?: string | undefined;
+    PRESIGNED_URL_EXPIRY?: string | undefined;
+    MAX_FILE_SIZE?: string | undefined;
+    AWS_REGION?: string | undefined;
+    AWS_ACCESS_KEY?: string | undefined;
+    AWS_SECRET_KEY?: string | undefined;
+    GCS_PROJECT_ID?: string | undefined;
+    GCS_CREDENTIALS?: string | undefined;
+    AZURE_CONNECTION_STRING?: string | undefined;
+    AZURE_ACCOUNT_NAME?: string | undefined;
+    AZURE_ACCOUNT_KEY?: string | undefined;
+}
+//# sourceMappingURL=storage.types.d.ts.map

package/dist/cjs/types/storage.types.d.ts.map

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

package/dist/cjs/types/storage.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=storage.types.js.map

package/dist/cjs/types/storage.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.types.js","sourceRoot":"","sources":["../../../src/types/storage.types.ts"],"names":[],"mappings":""}

package/dist/cjs/utils/config.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.utils.d.ts","sourceRoot":"","sources":["../../../src/utils/config.utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAI/F;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AA2BD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,iBAAiB,CAsBzD;AAuBD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,iBAAiB,GAAG,aAAa,CAuBtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB,CA2E7E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAM/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/cjs/utils/config.utils.js

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeDotenv = initializeDotenv;
+exports.loadEnvironmentConfig = loadEnvironmentConfig;
+exports.environmentToStorageConfig = environmentToStorageConfig;
+exports.validateStorageConfig = validateStorageConfig;
+exports.loadAndValidateConfig = loadAndValidateConfig;
+exports.resetDotenvInitialization = resetDotenvInitialization;
+const dotenv_1 = __importDefault(require("dotenv"));
+let dotenvInitialized = false;
+/**
+ * Loads your .env file if it hasn't been loaded already.
+ * Safe to call multiple times — it only runs once.
+ */
+function initializeDotenv() {
+    if (!dotenvInitialized) {
+        dotenv_1.default.config();
+        dotenvInitialized = true;
+    }
+}
+const ENV_KEYS = {
+    FILE_DRIVER: 'FILE_DRIVER',
+    BUCKET_NAME: 'BUCKET_NAME',
+    BUCKET_PATH: 'BUCKET_PATH',
+    LOCAL_PATH: 'LOCAL_PATH',
+    PRESIGNED_URL_EXPIRY: 'PRESIGNED_URL_EXPIRY',
+    MAX_FILE_SIZE: 'MAX_FILE_SIZE',
+    AWS_REGION: 'AWS_REGION',
+    AWS_ACCESS_KEY: 'AWS_ACCESS_KEY',
+    AWS_SECRET_KEY: 'AWS_SECRET_KEY',
+    GCS_PROJECT_ID: 'GCS_PROJECT_ID',
+    GCS_CREDENTIALS: 'GCS_CREDENTIALS',
+    AZURE_CONNECTION_STRING: 'AZURE_CONNECTION_STRING',
+    AZURE_ACCOUNT_NAME: 'AZURE_ACCOUNT_NAME',
+    AZURE_ACCOUNT_KEY: 'AZURE_ACCOUNT_KEY',
+};
+const DEFAULT_CONFIG = {
+    presignedUrlExpiry: 600,
+    localPath: 'public/express-storage',
+};
+/**
+ * Reads storage configuration from environment variables.
+ * Automatically loads .env on first call.
+ */
+function loadEnvironmentConfig() {
+    initializeDotenv();
+    return {
+        FILE_DRIVER: process.env[ENV_KEYS.FILE_DRIVER] || '',
+        BUCKET_NAME: process.env[ENV_KEYS.BUCKET_NAME] || undefined,
+        BUCKET_PATH: process.env[ENV_KEYS.BUCKET_PATH] || undefined,
+        LOCAL_PATH: process.env[ENV_KEYS.LOCAL_PATH] || undefined,
+        PRESIGNED_URL_EXPIRY: process.env[ENV_KEYS.PRESIGNED_URL_EXPIRY] || undefined,
+        MAX_FILE_SIZE: process.env[ENV_KEYS.MAX_FILE_SIZE] || undefined,
+        AWS_REGION: process.env[ENV_KEYS.AWS_REGION] || undefined,
+        AWS_ACCESS_KEY: process.env[ENV_KEYS.AWS_ACCESS_KEY] || undefined,
+        AWS_SECRET_KEY: process.env[ENV_KEYS.AWS_SECRET_KEY] || undefined,
+        GCS_PROJECT_ID: process.env[ENV_KEYS.GCS_PROJECT_ID] || undefined,
+        GCS_CREDENTIALS: process.env[ENV_KEYS.GCS_CREDENTIALS] || undefined,
+        AZURE_CONNECTION_STRING: process.env[ENV_KEYS.AZURE_CONNECTION_STRING] || undefined,
+        AZURE_ACCOUNT_NAME: process.env[ENV_KEYS.AZURE_ACCOUNT_NAME] || undefined,
+        AZURE_ACCOUNT_KEY: process.env[ENV_KEYS.AZURE_ACCOUNT_KEY] || undefined,
+    };
+}
+/**
+ * Safely parses a string to an integer, returning a default for invalid values.
+ *
+ * Unlike parseInt(), this function rejects strings with trailing non-numeric characters.
+ * For example, "100abc" returns the default value, not 100.
+ */
+function parseIntSafe(value, defaultValue) {
+    if (!value)
+        return defaultValue;
+    // Trim whitespace and check if the entire string is a valid integer
+    const trimmed = value.trim();
+    // Check if the string matches a valid integer pattern (optional sign followed by digits)
+    if (!/^-?\d+$/.test(trimmed)) {
+        return defaultValue;
+    }
+    const parsed = parseInt(trimmed, 10);
+    return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+/**
+ * Converts environment variables into a StorageConfig object.
+ */
+function environmentToStorageConfig(envConfig) {
+    const config = {
+        driver: envConfig.FILE_DRIVER,
+        bucketName: envConfig.BUCKET_NAME,
+        bucketPath: envConfig.BUCKET_PATH || '',
+        localPath: envConfig.LOCAL_PATH || DEFAULT_CONFIG.localPath,
+        presignedUrlExpiry: parseIntSafe(envConfig.PRESIGNED_URL_EXPIRY, DEFAULT_CONFIG.presignedUrlExpiry),
+        maxFileSize: parseIntSafe(envConfig.MAX_FILE_SIZE, undefined),
+        awsRegion: envConfig.AWS_REGION,
+        awsAccessKey: envConfig.AWS_ACCESS_KEY,
+        awsSecretKey: envConfig.AWS_SECRET_KEY,
+        gcsProjectId: envConfig.GCS_PROJECT_ID,
+        gcsCredentials: envConfig.GCS_CREDENTIALS,
+        azureConnectionString: envConfig.AZURE_CONNECTION_STRING,
+        azureAccountName: envConfig.AZURE_ACCOUNT_NAME,
+        azureAccountKey: envConfig.AZURE_ACCOUNT_KEY,
+        azureContainerName: envConfig.BUCKET_NAME, // Use BUCKET_NAME for Azure container
+    };
+    return config;
+}
+/**
+ * Validates a storage configuration.
+ *
+ * Checks that:
+ * - A valid driver is specified
+ * - Required credentials are present for the chosen driver
+ * - Numeric values are within acceptable ranges
+ *
+ * Returns an object with isValid and an array of error messages.
+ */
+function validateStorageConfig(config) {
+    const errors = [];
+    // Check driver
+    if (!config.driver) {
+        errors.push('FILE_DRIVER is required');
+    }
+    else if (!['s3', 's3-presigned', 'gcs', 'gcs-presigned', 'azure', 'azure-presigned', 'local'].includes(config.driver)) {
+        errors.push(`Invalid FILE_DRIVER: ${config.driver}. Must be one of: s3, s3-presigned, gcs, gcs-presigned, azure, azure-presigned, local`);
+    }
+    // S3 requirements
+    if (config.driver?.includes('s3')) {
+        if (!config.bucketName)
+            errors.push('BUCKET_NAME is required for S3');
+        if (!config.awsRegion)
+            errors.push('AWS_REGION is required for S3');
+        // Access keys are optional — IAM roles work when running on AWS
+    }
+    // GCS requirements
+    if (config.driver?.includes('gcs')) {
+        if (!config.bucketName)
+            errors.push('BUCKET_NAME is required for GCS');
+        if (!config.gcsProjectId)
+            errors.push('GCS_PROJECT_ID is required for GCS');
+        // Credentials are optional — ADC works when running on GCP
+    }
+    // Azure requirements
+    if (config.driver?.includes('azure')) {
+        const hasConnectionString = !!config.azureConnectionString;
+        const hasAccountKey = config.azureAccountName && config.azureAccountKey;
+        const hasManagedIdentity = config.azureAccountName && !config.azureAccountKey;
+        if (config.driver === 'azure-presigned') {
+            // Presigned mode needs account key for SAS URL generation
+            if (!hasConnectionString && !hasAccountKey) {
+                errors.push('Azure presigned driver requires either AZURE_CONNECTION_STRING or both AZURE_ACCOUNT_NAME and AZURE_ACCOUNT_KEY (Managed Identity cannot generate SAS URLs)');
+            }
+        }
+        else {
+            // Direct mode supports any authentication method
+            if (!hasConnectionString && !hasAccountKey && !hasManagedIdentity) {
+                errors.push('Azure requires AZURE_CONNECTION_STRING, AZURE_ACCOUNT_NAME + AZURE_ACCOUNT_KEY, or AZURE_ACCOUNT_NAME only (for Managed Identity)');
+            }
+        }
+        if (!config.azureContainerName) {
+            errors.push('BUCKET_NAME is required for Azure');
+        }
+    }
+    // Validate URL expiry time
+    if (config.presignedUrlExpiry !== undefined) {
+        if (Number.isNaN(config.presignedUrlExpiry) || config.presignedUrlExpiry <= 0) {
+            errors.push('PRESIGNED_URL_EXPIRY must be a positive number greater than 0');
+        }
+        // Max 7 days — that's the cloud provider limit
+        const MAX_EXPIRY = 604800;
+        if (!Number.isNaN(config.presignedUrlExpiry) && config.presignedUrlExpiry > MAX_EXPIRY) {
+            errors.push(`PRESIGNED_URL_EXPIRY cannot exceed ${MAX_EXPIRY} seconds (7 days). Cloud providers enforce this limit.`);
+        }
+    }
+    // Validate max file size
+    if (config.maxFileSize !== undefined) {
+        if (Number.isNaN(config.maxFileSize) || config.maxFileSize <= 0) {
+            errors.push('MAX_FILE_SIZE must be a positive number greater than 0');
+        }
+        // Max 5TB — reasonable limit for single uploads
+        const MAX_FILE_SIZE_LIMIT = 5 * 1024 * 1024 * 1024 * 1024;
+        if (!Number.isNaN(config.maxFileSize) && config.maxFileSize > MAX_FILE_SIZE_LIMIT) {
+            errors.push(`MAX_FILE_SIZE cannot exceed ${MAX_FILE_SIZE_LIMIT} bytes (5TB). Consider using multipart uploads for larger files.`);
+        }
+    }
+    return {
+        isValid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Convenience function that loads and validates config in one call.
+ * Returns both the config and validation result.
+ */
+function loadAndValidateConfig() {
+    const envConfig = loadEnvironmentConfig();
+    const config = environmentToStorageConfig(envConfig);
+    const validation = validateStorageConfig(config);
+    return { config, validation };
+}
+/**
+ * Resets the dotenv initialization flag.
+ *
+ * This is primarily useful for testing scenarios where you need to
+ * reinitialize dotenv with different environment variables.
+ *
+ * WARNING: This does not clear previously loaded environment variables.
+ * It only allows initializeDotenv() to run again.
+ */
+function resetDotenvInitialization() {
+    dotenvInitialized = false;
+}
+//# sourceMappingURL=config.utils.js.map