alepha 0.9.4 → 0.10.0

package/bucket.d.ts

@@ -2,7 +2,7 @@ import * as _alepha_core1 from "alepha";
 import { Alepha, AlephaError, Descriptor, FileLike, KIND, Service } from "alepha";
 import * as fs from "node:fs";
 import * as _alepha_logger0 from "alepha/logger";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 
 //#region src/providers/FileStorageProvider.d.ts
 declare abstract class FileStorageProvider {
@@ -52,17 +52,332 @@ declare class MemoryFileStorageProvider implements FileStorageProvider {
 //#endregion
 //#region src/descriptors/$bucket.d.ts
 /**
- * Create a container for storing files.
+ * Creates a bucket descriptor for file storage and management with configurable validation.
+ *
+ * This descriptor provides a comprehensive file storage system that handles file uploads,
+ * downloads, validation, and management across multiple storage backends. It supports
+ * MIME type validation, size limits, and integrates seamlessly with various storage
+ * providers for scalable file management in applications.
+ *
+ * **Key Features**
+ *
+ * - **Multi-Provider Support**: Works with filesystem, cloud storage (S3, Azure), and in-memory providers
+ * - **File Validation**: Automatic MIME type checking and file size validation
+ * - **Type Safety**: Full TypeScript support with FileLike interface compatibility
+ * - **Event Integration**: Emits events for file operations (upload, delete) for monitoring
+ * - **Flexible Configuration**: Per-bucket and per-operation configuration options
+ * - **Automatic Detection**: Smart file type and size detection with fallback mechanisms
+ * - **Error Handling**: Comprehensive error handling with descriptive error messages
+ *
+ * **Use Cases**
+ *
+ * Perfect for handling file storage requirements across applications:
+ * - User profile picture and document uploads
+ * - Product image and media management
+ * - Document storage and retrieval systems
+ * - Temporary file handling and processing
+ * - Content delivery and asset management
+ * - Backup and archival storage
+ * - File-based data import/export workflows
  *
  * @example
+ * **Basic file upload bucket:**
  * ```ts
  * import { $bucket } from "alepha/bucket";
  *
- * class App {
- *   images = $bucket();
+ * class MediaService {
+ *   images = $bucket({
+ *     name: "user-images",
+ *     description: "User uploaded profile images and photos",
+ *     mimeTypes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+ *     maxSize: 5 // 5MB limit
+ *   });
+ *
+ *   async uploadProfileImage(file: FileLike, userId: string): Promise<string> {
+ *     // File is automatically validated against MIME types and size
+ *     const fileId = await this.images.upload(file);
+ *
+ *     // Update user profile with new image
+ *     await this.userService.updateProfileImage(userId, fileId);
+ *
+ *     return fileId;
+ *   }
+ *
+ *   async getUserProfileImage(userId: string): Promise<FileLike> {
+ *     const user = await this.userService.getUser(userId);
+ *     if (!user.profileImageId) {
+ *       throw new Error('User has no profile image');
+ *     }
+ *
+ *     return await this.images.download(user.profileImageId);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Document storage with multiple file types:**
+ * ```ts
+ * class DocumentManager {
+ *   documents = $bucket({
+ *     name: "company-documents",
+ *     description: "Legal documents, contracts, and reports",
+ *     mimeTypes: [
+ *       "application/pdf",
+ *       "application/msword",
+ *       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ *       "text/plain",
+ *       "text/csv"
+ *     ],
+ *     maxSize: 50 // 50MB for large documents
+ *   });
+ *
+ *   async uploadDocument(file: FileLike, metadata: { title: string; category: string; userId: string }): Promise<string> {
+ *     try {
+ *       const fileId = await this.documents.upload(file);
+ *
+ *       // Store document metadata in database
+ *       await this.database.documents.create({
+ *         id: fileId,
+ *         title: metadata.title,
+ *         category: metadata.category,
+ *         uploadedBy: metadata.userId,
+ *         fileName: file.name,
+ *         fileSize: file.size,
+ *         mimeType: file.type,
+ *         uploadedAt: new Date()
+ *       });
+ *
+ *       console.log(`Document uploaded successfully: ${metadata.title} (${fileId})`);
+ *       return fileId;
+ *
+ *     } catch (error) {
+ *       console.error(`Failed to upload document: ${metadata.title}`, error);
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   async downloadDocument(documentId: string, userId: string): Promise<FileLike> {
+ *     // Check permissions
+ *     const document = await this.database.documents.findById(documentId);
+ *     if (!document) {
+ *       throw new Error('Document not found');
+ *     }
+ *
+ *     const hasAccess = await this.permissionService.canAccessDocument(userId, documentId);
+ *     if (!hasAccess) {
+ *       throw new Error('Insufficient permissions to access document');
+ *     }
+ *
+ *     // Download and return file
+ *     return await this.documents.download(documentId);
+ *   }
+ *
+ *   async deleteDocument(documentId: string, userId: string): Promise<void> {
+ *     // Verify ownership or admin privileges
+ *     const document = await this.database.documents.findById(documentId);
+ *     if (document.uploadedBy !== userId && !await this.userService.isAdmin(userId)) {
+ *       throw new Error('Cannot delete document: insufficient permissions');
+ *     }
+ *
+ *     // Delete from storage and database
+ *     await this.documents.delete(documentId);
+ *     await this.database.documents.delete(documentId);
  *
- *   uploadImage(file: FileLike): Promise<string> {
- *     return this.images.upload(file);
+ *     console.log(`Document deleted: ${document.title} (${documentId})`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Cloud storage integration with custom provider:**
+ * ```ts
+ * class ProductImageService {
+ *   productImages = $bucket({
+ *     name: "product-images",
+ *     provider: S3FileStorageProvider, // Use AWS S3 for production storage
+ *     description: "Product catalog images and thumbnails",
+ *     mimeTypes: ["image/jpeg", "image/png", "image/webp"],
+ *     maxSize: 10 // 10MB for high-quality product images
+ *   });
+ *
+ *   thumbnails = $bucket({
+ *     name: "product-thumbnails",
+ *     provider: S3FileStorageProvider,
+ *     description: "Generated product thumbnail images",
+ *     mimeTypes: ["image/jpeg", "image/webp"],
+ *     maxSize: 1 // 1MB for thumbnails
+ *   });
+ *
+ *   async uploadProductImage(productId: string, file: FileLike): Promise<{ imageId: string; thumbnailId: string }> {
+ *     try {
+ *       // Upload original image
+ *       const imageId = await this.productImages.upload(file);
+ *
+ *       // Generate and upload thumbnail
+ *       const thumbnailFile = await this.imageProcessor.generateThumbnail(file, {
+ *         width: 300,
+ *         height: 300,
+ *         format: 'webp',
+ *         quality: 80
+ *       });
+ *
+ *       const thumbnailId = await this.thumbnails.upload(thumbnailFile);
+ *
+ *       // Update product in database
+ *       await this.database.products.update(productId, {
+ *         imageId,
+ *         thumbnailId,
+ *         imageUpdatedAt: new Date()
+ *       });
+ *
+ *       console.log(`Product images uploaded for ${productId}: image=${imageId}, thumbnail=${thumbnailId}`);
+ *
+ *       return { imageId, thumbnailId };
+ *
+ *     } catch (error) {
+ *       console.error(`Failed to upload product image for ${productId}`, error);
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   async getProductImage(productId: string, thumbnail: boolean = false): Promise<FileLike> {
+ *     const product = await this.database.products.findById(productId);
+ *     if (!product) {
+ *       throw new Error(`Product ${productId} not found`);
+ *     }
+ *
+ *     const imageId = thumbnail ? product.thumbnailId : product.imageId;
+ *     if (!imageId) {
+ *       throw new Error(`Product ${productId} has no ${thumbnail ? 'thumbnail' : 'image'}`);
+ *     }
+ *
+ *     const bucket = thumbnail ? this.thumbnails : this.productImages;
+ *     return await bucket.download(imageId);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Temporary file processing with memory storage:**
+ * ```ts
+ * class FileProcessingService {
+ *   tempFiles = $bucket({
+ *     name: "temp-processing",
+ *     provider: "memory", // Use in-memory storage for temporary files
+ *     description: "Temporary files during processing workflows",
+ *     maxSize: 100 // Large limit for processing workflows
+ *   });
+ *
+ *   async processDataFile(inputFile: FileLike, transformations: string[]): Promise<FileLike> {
+ *     let currentFile = inputFile;
+ *     const intermediateFiles: string[] = [];
+ *
+ *     try {
+ *       // Upload initial file to temp storage
+ *       let currentFileId = await this.tempFiles.upload(currentFile);
+ *       intermediateFiles.push(currentFileId);
+ *
+ *       // Apply each transformation
+ *       for (const transformation of transformations) {
+ *         console.log(`Applying transformation: ${transformation}`);
+ *
+ *         // Download current file
+ *         currentFile = await this.tempFiles.download(currentFileId);
+ *
+ *         // Apply transformation
+ *         const transformedFile = await this.applyTransformation(currentFile, transformation);
+ *
+ *         // Upload transformed file
+ *         currentFileId = await this.tempFiles.upload(transformedFile);
+ *         intermediateFiles.push(currentFileId);
+ *       }
+ *
+ *       // Download final result
+ *       const finalFile = await this.tempFiles.download(currentFileId);
+ *
+ *       console.log(`File processing completed with ${transformations.length} transformations`);
+ *       return finalFile;
+ *
+ *     } finally {
+ *       // Clean up all intermediate files
+ *       for (const fileId of intermediateFiles) {
+ *         try {
+ *           await this.tempFiles.delete(fileId);
+ *         } catch (error) {
+ *           console.warn(`Failed to clean up temp file ${fileId}:`, error.message);
+ *         }
+ *       }
+ *       console.log(`Cleaned up ${intermediateFiles.length} temporary files`);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **File validation with dynamic configuration:**
+ * ```ts
+ * class UserContentService {
+ *   userContent = $bucket({
+ *     name: "user-content",
+ *     description: "User-generated content with flexible validation"
+ *     // Base configuration - can be overridden per operation
+ *   });
+ *
+ *   async uploadUserFile(file: FileLike, userId: string, contentType: 'avatar' | 'document' | 'media'): Promise<string> {
+ *     // Dynamic validation based on content type
+ *     const validationConfig = this.getValidationConfig(contentType, userId);
+ *
+ *     try {
+ *       // Upload with specific validation rules
+ *       const fileId = await this.userContent.upload(file, validationConfig);
+ *
+ *       // Log upload for audit trail
+ *       await this.auditLogger.log({
+ *         action: 'file_upload',
+ *         userId,
+ *         fileId,
+ *         contentType,
+ *         fileName: file.name,
+ *         fileSize: file.size,
+ *         mimeType: file.type
+ *       });
+ *
+ *       return fileId;
+ *
+ *     } catch (error) {
+ *       console.error(`File upload failed for user ${userId}`, {
+ *         contentType,
+ *         fileName: file.name,
+ *         error: error.message
+ *       });
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   private getValidationConfig(contentType: string, userId: string) {
+ *     const baseConfig = {
+ *       avatar: {
+ *         mimeTypes: ['image/jpeg', 'image/png'],
+ *         maxSize: 2 // 2MB for avatars
+ *       },
+ *       document: {
+ *         mimeTypes: ['application/pdf', 'text/plain'],
+ *         maxSize: 10 // 10MB for documents
+ *       },
+ *       media: {
+ *         mimeTypes: ['image/jpeg', 'image/png', 'video/mp4'],
+ *         maxSize: 50 // 50MB for media files
+ *       }
+ *     };
+ *
+ *     const config = baseConfig[contentType];
+ *
+ *     // Premium users get higher limits
+ *     if (this.userService.isPremium(userId)) {
+ *       config.maxSize *= 2;
+ *     }
+ *
+ *     return config;
  *   }
  * }
  * ```
@@ -73,14 +388,136 @@ declare const $bucket: {
 };
 interface BucketDescriptorOptions extends BucketFileOptions {
   /**
-   * File storage provider. If not provided, the default provider will be used.
+   * File storage provider configuration for the bucket.
+   *
+   * Options:
+   * - **"memory"**: In-memory storage (default for development, lost on restart)
+   * - **Service<FileStorageProvider>**: Custom provider class (e.g., S3FileStorageProvider, AzureBlobProvider)
+   * - **undefined**: Uses the default file storage provider from dependency injection
+   *
+   * **Provider Selection Guidelines**:
+   * - **Development**: Use "memory" for fast, simple testing without external dependencies
+   * - **Production**: Use cloud providers (S3, Azure Blob, Google Cloud Storage) for scalability
+   * - **Local deployment**: Use filesystem providers for on-premise installations
+   * - **Hybrid**: Use different providers for different bucket types (temp files vs permanent storage)
+   *
+   * **Provider Capabilities**:
+   * - File persistence and durability guarantees
+   * - Scalability and performance characteristics
+   * - Geographic distribution and CDN integration
+   * - Cost implications for storage and bandwidth
+   * - Backup and disaster recovery features
+   *
+   * @default Uses injected FileStorageProvider
+   * @example "memory"
+   * @example S3FileStorageProvider
+   * @example AzureBlobStorageProvider
    */
   provider?: Service<FileStorageProvider> | "memory";
   /**
-   * Optional name of the bucket. If not provided, the key of the descriptor will be used.
+   * Unique name identifier for the bucket.
+   *
+   * This name is used for:
+   * - Storage backend organization and partitioning
+   * - File path generation and URL construction
+   * - Logging, monitoring, and debugging
+   * - Access control and permissions management
+   * - Backup and replication configuration
+   *
+   * **Naming Conventions**:
+   * - Use lowercase with hyphens for consistency
+   * - Include purpose or content type in the name
+   * - Avoid spaces and special characters
+   * - Consider environment prefixes for deployment isolation
+   *
+   * If not provided, defaults to the property key where the bucket is declared.
+   *
+   * @example "user-avatars"
+   * @example "product-images"
+   * @example "legal-documents"
+   * @example "temp-processing-files"
    */
   name?: string;
 }
+interface BucketFileOptions {
+  /**
+   * Human-readable description of the bucket's purpose and contents.
+   *
+   * Used for:
+   * - Documentation generation and API references
+   * - Developer onboarding and system understanding
+   * - Monitoring dashboards and admin interfaces
+   * - Compliance and audit documentation
+   *
+   * **Description Best Practices**:
+   * - Explain what types of files this bucket stores
+   * - Mention any special handling or processing requirements
+   * - Include information about retention policies if applicable
+   * - Note any compliance or security considerations
+   *
+   * @example "User profile pictures and avatar images"
+   * @example "Product catalog images with automated thumbnail generation"
+   * @example "Legal documents requiring long-term retention"
+   * @example "Temporary files for data processing workflows"
+   */
+  description?: string;
+  /**
+   * Array of allowed MIME types for files uploaded to this bucket.
+   *
+   * When specified, only files with these exact MIME types will be accepted.
+   * Files with disallowed MIME types will be rejected with an InvalidFileError.
+   *
+   * **MIME Type Categories**:
+   * - Images: "image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml"
+   * - Documents: "application/pdf", "text/plain", "text/csv"
+   * - Office: "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+   * - Archives: "application/zip", "application/x-tar", "application/gzip"
+   * - Media: "video/mp4", "audio/mpeg", "audio/wav"
+   *
+   * **Security Considerations**:
+   * - Always validate MIME types for user uploads
+   * - Be cautious with executable file types
+   * - Consider using allow-lists rather than deny-lists
+   * - Remember that MIME types can be spoofed by malicious users
+   *
+   * If not specified, all MIME types are allowed (not recommended for user uploads).
+   *
+   * @example ["image/jpeg", "image/png"] // Only JPEG and PNG images
+   * @example ["application/pdf", "text/plain"] // Documents only
+   * @example ["video/mp4", "video/webm"] // Video files
+   */
+  mimeTypes?: string[];
+  /**
+   * Maximum file size allowed in megabytes (MB).
+   *
+   * Files larger than this limit will be rejected with an InvalidFileError.
+   * This helps prevent:
+   * - Storage quota exhaustion
+   * - Memory issues during file processing
+   * - Long upload times and timeouts
+   * - Abuse of storage resources
+   *
+   * **Size Guidelines by File Type**:
+   * - Profile images: 1-5 MB
+   * - Product photos: 5-10 MB
+   * - Documents: 10-50 MB
+   * - Video files: 50-500 MB
+   * - Data files: 100-1000 MB
+   *
+   * **Considerations**:
+   * - Consider your storage costs and limits
+   * - Factor in network upload speeds for users
+   * - Account for processing requirements (thumbnails, compression)
+   * - Set reasonable limits based on actual use cases
+   *
+   * @default 10 MB
+   *
+   * @example 1    // 1MB for small images
+   * @example 25   // 25MB for documents
+   * @example 100  // 100MB for media files
+   */
+  maxSize?: number;
+}
 declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
   readonly provider: FileStorageProvider | MemoryFileStorageProvider;
   get name(): string;
@@ -142,10 +579,10 @@ declare class LocalFileStorageProvider implements FileStorageProvider {
   protected path(container: string, fileId?: string): string;
   protected isErrorNoEntry(error: unknown): boolean;
 }
-declare const fileMetadataSchema: _sinclair_typebox0.TObject<{
-  name: _sinclair_typebox0.TString;
-  type: _sinclair_typebox0.TString;
-  size: _sinclair_typebox0.TNumber;
+declare const fileMetadataSchema: typebox0.TObject<{
+  name: typebox0.TString;
+  type: typebox0.TString;
+  size: typebox0.TNumber;
 }>;
 //#endregion
 //#region src/index.d.ts

package/cache.d.ts

@@ -44,7 +44,138 @@ declare abstract class CacheProvider {
 //#endregion
 //#region src/descriptors/$cache.d.ts
 /**
- * Creates a cache storage or a cache function.
+ * Creates a cache descriptor for high-performance data caching with automatic cache management.
+ *
+ * This descriptor provides a powerful caching layer that can significantly improve application performance
+ * by storing frequently accessed data in memory or external cache stores like Redis. It supports both
+ * function result caching and manual cache operations with intelligent serialization and TTL management.
+ *
+ * **Key Features**
+ *
+ * - **Function Result Caching**: Automatically cache function results based on input parameters
+ * - **Multiple Storage Backends**: Support for in-memory, Redis, and custom cache providers
+ * - **Intelligent Serialization**: Automatic handling of JSON, strings, and binary data
+ * - **TTL Management**: Configurable time-to-live with automatic expiration
+ * - **Cache Invalidation**: Pattern-based cache invalidation with wildcard support
+ * - **Environment Controls**: Enable/disable caching via environment variables
+ * - **Type Safety**: Full TypeScript support with generic type parameters
+ *
+ * ## Cache Strategies
+ *
+ * ### 1. Function Result Caching (Memoization)
+ * Automatically cache the results of expensive operations based on input parameters.
+ *
+ * ### 2. Manual Cache Operations
+ * Direct cache operations for custom caching logic and data storage.
+ *
+ * ## Storage Backends
+ *
+ * - **Memory**: Fast in-memory cache (default for development)
+ * - **Redis**: Distributed cache for production environments
+ * - **Custom Providers**: Implement your own cache storage backend
+ *
+ * @example
+ * **Basic function result caching:**
+ * ```ts
+ * import { $cache } from "alepha/cache";
+ *
+ * class DataService {
+ *   // Cache expensive database queries
+ *   getUserData = $cache({
+ *     name: "user-data",
+ *     ttl: [10, "minutes"],
+ *     handler: async (userId: string) => {
+ *       // Expensive database operation
+ *       return await database.users.findById(userId);
+ *     }
+ *   });
+ *
+ *   async getUser(id: string) {
+ *     // This will hit cache on subsequent calls with same ID
+ *     return await this.getUserData(id);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **API response caching with custom key generation:**
+ * ```ts
+ * class ApiService {
+ *   fetchUserPosts = $cache({
+ *     name: "user-posts",
+ *     ttl: [5, "minutes"],
+ *     key: (userId: string, page: number) => `${userId}:page:${page}`,
+ *     handler: async (userId: string, page: number = 1) => {
+ *       const response = await fetch(`/api/users/${userId}/posts?page=${page}`);
+ *       return await response.json();
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Manual cache operations for custom logic:**
+ * ```ts
+ * class SessionService {
+ *   sessionCache = $cache<UserSession>({
+ *     name: "user-sessions",
+ *     ttl: [1, "hour"],
+ *     provider: "memory"  // Use memory cache for sessions
+ *   });
+ *
+ *   async storeSession(sessionId: string, session: UserSession) {
+ *     await this.sessionCache.set(sessionId, session);
+ *   }
+ *
+ *   async getSession(sessionId: string): Promise<UserSession | undefined> {
+ *     return await this.sessionCache.get(sessionId);
+ *   }
+ *
+ *   async invalidateUserSessions(userId: string) {
+ *     // Invalidate all sessions for a user using wildcards
+ *     await this.sessionCache.invalidate(`user:${userId}:*`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Redis-backed caching for production:**
+ * ```ts
+ * class ProductService {
+ *   productCache = $cache({
+ *     name: "products",
+ *     ttl: [1, "hour"],
+ *     provider: RedisCacheProvider,  // Use Redis for distributed caching
+ *     handler: async (productId: string) => {
+ *       return await this.database.products.findById(productId);
+ *     }
+ *   });
+ *
+ *   async invalidateProduct(productId: string) {
+ *     await this.productCache.invalidate(productId);
+ *   }
+ *
+ *   async invalidateAllProducts() {
+ *     await this.productCache.invalidate("*");
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Conditional caching with environment controls:**
+ * ```ts
+ * class ExpensiveService {
+ *   computation = $cache({
+ *     name: "heavy-computation",
+ *     ttl: [1, "day"],
+ *     disabled: process.env.NODE_ENV === "development", // Disable in dev
+ *     handler: async (input: ComplexInput) => {
+ *       // Very expensive computation that should be cached in production
+ *       return await performHeavyComputation(input);
+ *     }
+ *   });
+ * }
+ * ```
  */
 declare const $cache: {
   <TReturn = string, TParameter extends any[] = any[]>(options?: CacheDescriptorOptions<TReturn, TParameter>): CacheDescriptorFn<TReturn, TParameter>;