express-storage 1.0.0 → 1.1.2

package/dist/utils/config.utils.js

@@ -1,115 +1,176 @@
 import dotenv from 'dotenv';
-// Load environment variables
-dotenv.config();
-// Environment variable keys
+let dotenvInitialized = false;
+/**
+ * Loads your .env file if it hasn't been loaded already.
+ * Safe to call multiple times — it only runs once.
+ */
+export function initializeDotenv() {
+    if (!dotenvInitialized) {
+        dotenv.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',
-    // AWS S3
+    MAX_FILE_SIZE: 'MAX_FILE_SIZE',
     AWS_REGION: 'AWS_REGION',
     AWS_ACCESS_KEY: 'AWS_ACCESS_KEY',
     AWS_SECRET_KEY: 'AWS_SECRET_KEY',
-    // Google Cloud Storage
     GCS_PROJECT_ID: 'GCS_PROJECT_ID',
     GCS_CREDENTIALS: 'GCS_CREDENTIALS',
-    // Oracle Cloud Infrastructure
-    OCI_REGION: 'OCI_REGION',
-    OCI_CREDENTIALS: 'OCI_CREDENTIALS',
+    AZURE_CONNECTION_STRING: 'AZURE_CONNECTION_STRING',
+    AZURE_ACCOUNT_NAME: 'AZURE_ACCOUNT_NAME',
+    AZURE_ACCOUNT_KEY: 'AZURE_ACCOUNT_KEY',
 };
-// Default configuration
 const DEFAULT_CONFIG = {
-    presignedUrlExpiry: 600, // 10 minutes
+    presignedUrlExpiry: 600,
     localPath: 'public/express-storage',
 };
 /**
- * Load environment configuration
+ * Reads storage configuration from environment variables.
+ * Automatically loads .env on first call.
  */
 export 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,
-        // AWS S3
+        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,
-        // Google Cloud Storage
         GCS_PROJECT_ID: process.env[ENV_KEYS.GCS_PROJECT_ID] || undefined,
         GCS_CREDENTIALS: process.env[ENV_KEYS.GCS_CREDENTIALS] || undefined,
-        // Oracle Cloud Infrastructure
-        OCI_REGION: process.env[ENV_KEYS.OCI_REGION] || undefined,
-        OCI_CREDENTIALS: process.env[ENV_KEYS.OCI_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,
     };
 }
 /**
- * Convert environment config to storage config
+ * 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.
  */
 export 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: envConfig.PRESIGNED_URL_EXPIRY
-            ? parseInt(envConfig.PRESIGNED_URL_EXPIRY, 10)
-            : DEFAULT_CONFIG.presignedUrlExpiry,
-        // AWS S3
+        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,
-        // Google Cloud Storage
         gcsProjectId: envConfig.GCS_PROJECT_ID,
         gcsCredentials: envConfig.GCS_CREDENTIALS,
-        // Oracle Cloud Infrastructure
-        ociRegion: envConfig.OCI_REGION,
-        ociCredentials: envConfig.OCI_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;
 }
 /**
- * Validate storage configuration
+ * 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.
  */
 export function validateStorageConfig(config) {
     const errors = [];
-    // Validate driver
+    // Check driver
     if (!config.driver) {
         errors.push('FILE_DRIVER is required');
     }
-    else if (!['s3', 's3-presigned', 'gcs', 'gcs-presigned', 'oci', 'oci-presigned', 'local'].includes(config.driver)) {
-        errors.push(`Invalid FILE_DRIVER: ${config.driver}. Must be one of: s3, s3-presigned, gcs, gcs-presigned, oci, oci-presigned, local`);
+    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`);
     }
-    // Validate cloud storage requirements
+    // 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');
-        if (!config.awsAccessKey)
-            errors.push('AWS_ACCESS_KEY is required for S3');
-        if (!config.awsSecretKey)
-            errors.push('AWS_SECRET_KEY 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');
-        if (!config.gcsCredentials)
-            errors.push('GCS_CREDENTIALS is required for GCS');
+        // Credentials are optional — ADC works when running on GCP
     }
-    if (config.driver?.includes('oci')) {
-        if (!config.bucketName)
-            errors.push('BUCKET_NAME is required for OCI');
-        if (!config.ociRegion)
-            errors.push('OCI_REGION is required for OCI');
-        if (!config.ociCredentials)
-            errors.push('OCI_CREDENTIALS is required for OCI');
+    // 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 presigned URL expiry
-    if (config.presignedUrlExpiry && config.presignedUrlExpiry <= 0) {
-        errors.push('PRESIGNED_URL_EXPIRY must be greater than 0');
+    // 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,
@@ -117,7 +178,8 @@ export function validateStorageConfig(config) {
     };
 }
 /**
- * Load and validate configuration from environment
+ * Convenience function that loads and validates config in one call.
+ * Returns both the config and validation result.
  */
 export function loadAndValidateConfig() {
     const envConfig = loadEnvironmentConfig();
@@ -125,4 +187,16 @@ export function loadAndValidateConfig() {
     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.
+ */
+export function resetDotenvInitialization() {
+    dotenvInitialized = false;
+}
 //# sourceMappingURL=config.utils.js.map

package/dist/utils/config.utils.js.map

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

package/dist/utils/file.utils.d.ts

@@ -1,45 +1,142 @@
 /**
- * Generate unique filename with unix timestamp
+ * Creates a unique filename that won't collide with existing files.
+ *
+ * Format: {timestamp}_{random}_{sanitized_name}.{extension}
+ * Example: 1769104576000_a1b2c3d4e5_my_image.jpeg
+ *
+ * The random part uses crypto.randomBytes() for extra collision resistance
+ * in high-throughput scenarios.
  */
 export declare function generateUniqueFileName(originalName: string): string;
 /**
- * Sanitize filename to prevent security issues
+ * Makes a filename safe for storage by removing problematic characters.
+ *
+ * Replaces anything that isn't alphanumeric, a dot, or a hyphen with underscores.
+ * This ensures compatibility with all filesystems and cloud storage providers.
+ *
+ * Note: Unicode characters like Chinese or emojis become underscores.
+ * If you need to preserve these, consider using your own sanitization function.
  */
 export declare function sanitizeFileName(fileName: string): string;
 /**
- * Create month-based directory path
+ * Checks if a filename is safe to use.
+ *
+ * Rejects:
+ * - Empty filenames
+ * - Filenames over 255 characters
+ * - Path traversal attempts (../, /, \)
+ * - Null bytes
+ *
+ * Returns an error message if invalid, null if OK.
+ */
+export declare function validateFileName(fileName: string): string | null;
+/**
+ * Creates a date-based folder path: YYYY/MM
+ *
+ * Uses UTC to keep things consistent across timezones.
+ * Example: For January 2026 -> 'uploads/2026/01'
  */
 export declare function createMonthBasedPath(basePath: string): string;
 /**
- * Ensure directory exists, create if it doesn't
+ * Creates a directory if it doesn't exist.
+ * Also creates any parent directories needed (recursive).
  */
 export declare function ensureDirectoryExists(dirPath: string): void;
 /**
- * Get file size in human readable format
+ * Converts bytes to a human-readable string.
+ *
+ * Examples:
+ * - 1024 -> "1 KB"
+ * - 1048576 -> "1 MB"
+ * - 0 -> "0 Bytes"
  */
 export declare function formatFileSize(bytes: number): string;
 /**
- * Validate file size
+ * Checks if a file size is within the allowed limit.
  */
 export declare function validateFileSize(fileSize: number, maxSize: number): boolean;
 /**
- * Validate file type
+ * Checks if a MIME type is in the allowed list.
  */
 export declare function validateFileType(mimeType: string, allowedTypes: string[]): boolean;
 /**
- * Create relative URL for local files
- */
-export declare function createLocalFileUrl(filePath: string, baseUrl?: string): string;
-/**
- * Get file extension from filename
+ * Extracts the file extension (lowercase, includes the dot).
+ *
+ * Examples:
+ * - 'photo.jpg' -> '.jpg'
+ * - '.gitignore' -> '' (dotfiles have no extension)
+ * - 'archive.tar.gz' -> '.gz' (only the last extension)
  */
 export declare function getFileExtension(fileName: string): string;
 /**
- * Check if file is an image
+ * Checks if a MIME type indicates an image.
  */
 export declare function isImageFile(mimeType: string): boolean;
 /**
- * Check if file is a document
+ * Checks if a MIME type indicates a document (PDF, Word, Excel, etc.).
  */
 export declare function isDocumentFile(mimeType: string): boolean;
+/**
+ * Configuration for retry behavior.
+ */
+export interface RetryOptions {
+    /** Total attempts including the first one. Default: 3 */
+    maxAttempts?: number;
+    /** Starting delay between retries in ms. Default: 1000 */
+    baseDelay?: number;
+    /** Maximum delay between retries in ms. Default: 10000 */
+    maxDelay?: number;
+    /** Use exponential backoff. Default: true */
+    exponentialBackoff?: boolean;
+}
+/**
+ * Retries an async operation with exponential backoff.
+ *
+ * Great for cloud operations that might fail due to network blips
+ * or rate limiting.
+ *
+ * @example
+ * // Retry up to 3 times with increasing delays
+ * const result = await withRetry(() => storage.uploadFile(file));
+ *
+ * // More aggressive retry strategy
+ * const result = await withRetry(() => fetchData(), {
+ *   maxAttempts: 5,
+ *   baseDelay: 500
+ * });
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Pauses execution for the specified number of milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Configuration for concurrent execution.
+ */
+export interface ConcurrencyOptions {
+    /** Maximum parallel operations. Default: 10 */
+    maxConcurrent?: number;
+}
+/**
+ * Processes an array with a concurrency limit.
+ *
+ * Prevents overwhelming APIs or running out of resources by limiting
+ * how many operations run at once.
+ *
+ * Implementation uses pre-assigned chunk-based processing to avoid any
+ * potential race conditions with shared index counters. Each worker gets
+ * its own set of indices to process.
+ *
+ * Note: The input array is snapshotted at the start to prevent issues
+ * if the caller modifies it during processing.
+ *
+ * @example
+ * // Upload 100 files, but only 10 at a time
+ * const results = await withConcurrencyLimit(
+ *   files,
+ *   (file) => uploadFile(file),
+ *   { maxConcurrent: 10 }
+ * );
+ */
+export declare function withConcurrencyLimit<T, R>(items: T[], operation: (item: T, index: number) => Promise<R>, options?: ConcurrencyOptions): Promise<R[]>;
 //# sourceMappingURL=file.utils.d.ts.map

package/dist/utils/file.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file.utils.d.ts","sourceRoot":"","sources":["../../src/utils/file.utils.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAOnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAElF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW,GAAG,MAAM,CAGjF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWxD"}
+{"version":3,"file":"file.utils.d.ts","sourceRoot":"","sources":["../../src/utils/file.utils.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAsBnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBhE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM7D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAwBpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASzD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWxD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAC7C,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACjD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,CAAC,EAAE,CAAC,CAyCd"}