alepha 0.15.0 → 0.15.2

package/dist/bucket/index.d.ts

@@ -1,45 +1,462 @@
 import * as alepha1 from "alepha";
-import { Alepha, AlephaError, FileLike, KIND, Primitive, Service, Static } from "alepha";
-import { FileDetector, FileSystemProvider } from "alepha/file";
+import { Alepha, AlephaError, FileLike, Json, KIND, Primitive, Service, Static, StreamLike } from "alepha";
 import * as fs from "node:fs";
+import { Readable } from "node:stream";
 import * as alepha_logger0 from "alepha/logger";
 
 //#region ../../src/bucket/providers/FileStorageProvider.d.ts
 declare abstract class FileStorageProvider {
   /**
-       * Uploads a file to the storage.
-       *
-       * @param bucketName - Container name
-       * @param file - File to upload
-       * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.
-       * @return The identifier of the uploaded file.
-       */
+   * Uploads a file to the storage.
+   *
+   * @param bucketName - Container name
+   * @param file - File to upload
+   * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.
+   * @return The identifier of the uploaded file.
+   */
   abstract upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
   /**
-       * Downloads a file from the storage.
-       *
-       * @param bucketName - Container name
-       * @param fileId - Identifier of the file to download
-       * @return The downloaded file as a FileLike object.
-       */
+   * Downloads a file from the storage.
+   *
+   * @param bucketName - Container name
+   * @param fileId - Identifier of the file to download
+   * @return The downloaded file as a FileLike object.
+   */
   abstract download(bucketName: string, fileId: string): Promise<FileLike>;
   /**
-       * Check if fileId exists in the storage bucket.
-       *
-       * @param bucketName - Container name
-       * @param fileId - Identifier of the file to stream
-       * @return True is the file exists, false otherwise.
-       */
+   * Check if fileId exists in the storage bucket.
+   *
+   * @param bucketName - Container name
+   * @param fileId - Identifier of the file to stream
+   * @return True is the file exists, false otherwise.
+   */
   abstract exists(bucketName: string, fileId: string): Promise<boolean>;
   /**
-       * Delete permanently a file from the storage.
-       *
-       * @param bucketName - Container name
-       * @param fileId - Identifier of the file to delete
-       */
+   * Delete permanently a file from the storage.
+   *
+   * @param bucketName - Container name
+   * @param fileId - Identifier of the file to delete
+   */
   abstract delete(bucketName: string, fileId: string): Promise<void>;
 }
 //#endregion
+//#region ../../src/system/providers/FileSystemProvider.d.ts
+/**
+ * Options for creating a file from a URL
+ */
+interface CreateFileFromUrlOptions {
+  /**
+   * The URL to load the file from (file://, http://, or https://)
+   */
+  url: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a path (URL with file:// scheme)
+ */
+interface CreateFileFromPathOptions {
+  /**
+   * The path to the file on the local filesystem
+   */
+  path: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a Buffer
+ */
+interface CreateFileFromBufferOptions {
+  /**
+   * The Buffer containing the file data
+   */
+  buffer: Buffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a stream
+ */
+interface CreateFileFromStreamOptions {
+  /**
+   * The readable stream containing the file data
+   */
+  stream: StreamLike;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+  /**
+   * The size of the file in bytes (optional)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from text content
+ */
+interface CreateFileFromTextOptions {
+  /**
+   * The text content to create the file from
+   */
+  text: string;
+  /**
+   * The MIME type of the file (default: text/plain)
+   */
+  type?: string;
+  /**
+   * The name of the file (default: "file.txt")
+   */
+  name?: string;
+}
+interface CreateFileFromResponseOptions {
+  /**
+   * The Response object containing the file data
+   */
+  response: Response;
+  /**
+   * Override the name (optional, uses filename from Content-Disposition header if not provided)
+   */
+  name?: string;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+}
+/**
+ * Options for creating a file from a Web File object
+ */
+interface CreateFileFromWebFileOptions {
+  /**
+   * The Web File object
+   */
+  file: File;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+  /**
+   * Override the name (optional, uses file.name if not provided)
+   */
+  name?: string;
+  /**
+   * Override the size (optional, uses file.size if not provided)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from an ArrayBuffer
+ */
+interface CreateFileFromArrayBufferOptions {
+  /**
+   * The ArrayBuffer containing the file data
+   */
+  arrayBuffer: ArrayBuffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Union type for all createFile options
+ */
+type CreateFileOptions = CreateFileFromUrlOptions | CreateFileFromPathOptions | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | CreateFileFromResponseOptions | CreateFileFromArrayBufferOptions;
+/**
+ * Options for rm (remove) operation
+ */
+interface RmOptions {
+  /**
+   * If true, removes directories and their contents recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, no error will be thrown if the path does not exist
+   */
+  force?: boolean;
+}
+/**
+ * Options for cp (copy) operation
+ */
+interface CpOptions {
+  /**
+   * If true, copy directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, overwrite existing destination
+   */
+  force?: boolean;
+}
+/**
+ * Options for mkdir operation
+ */
+interface MkdirOptions {
+  /**
+   * If true, creates parent directories as needed
+   */
+  recursive?: boolean;
+  /**
+   * File mode (permission and sticky bits)
+   */
+  mode?: number;
+}
+/**
+ * Options for ls (list) operation
+ */
+interface LsOptions {
+  /**
+   * If true, list contents of directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, include hidden files (starting with .)
+   */
+  hidden?: boolean;
+}
+/**
+ * FileSystem interface providing utilities for working with files.
+ */
+declare abstract class FileSystemProvider {
+  /**
+   * Joins multiple path segments into a single path.
+   *
+   * @param paths - The path segments to join
+   * @returns The joined path
+   */
+  abstract join(...paths: string[]): string;
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   */
+  abstract createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   */
+  abstract rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copies a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Copy options
+   */
+  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Moves/renames a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   */
+  abstract mv(src: string, dest: string): Promise<void>;
+  /**
+   * Creates a directory.
+   *
+   * @param path - The directory path to create
+   * @param options - Mkdir options
+   */
+  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Lists files in a directory.
+   *
+   * @param path - The directory path to list
+   * @param options - List options
+   * @returns Array of filenames
+   */
+  abstract ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Checks if a file or directory exists.
+   *
+   * @param path - The path to check
+   * @returns True if the path exists, false otherwise
+   */
+  abstract exists(path: string): Promise<boolean>;
+  /**
+   * Reads the content of a file.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a Buffer
+   */
+  abstract readFile(path: string): Promise<Buffer>;
+  /**
+   * Writes data to a file.
+   *
+   * @param path - The file path to write to
+   * @param data - The data to write (Buffer or string)
+   */
+  abstract writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+  /**
+   * Reads the content of a file as a string.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a string
+   */
+  abstract readTextFile(path: string): Promise<string>;
+  /**
+   * Reads the content of a file as JSON.
+   *
+   * @param path - The file path to read
+   * @returns The parsed JSON content
+   */
+  abstract readJsonFile<T = unknown>(path: string): Promise<T>;
+}
+//#endregion
+//#region ../../src/system/services/FileDetector.d.ts
+interface FileTypeResult {
+  /**
+   * The detected MIME type
+   */
+  mimeType: string;
+  /**
+   * The detected file extension
+   */
+  extension: string;
+  /**
+   * Whether the file type was verified by magic bytes
+   */
+  verified: boolean;
+  /**
+   * The stream (potentially wrapped to allow re-reading)
+   */
+  stream: Readable;
+}
+/**
+ * Service for detecting file types and getting content types.
+ *
+ * @example
+ * ```typescript
+ * const detector = alepha.inject(FileDetector);
+ *
+ * // Get content type from filename
+ * const mimeType = detector.getContentType("image.png"); // "image/png"
+ *
+ * // Detect file type by magic bytes
+ * const stream = createReadStream('image.png');
+ * const result = await detector.detectFileType(stream, 'image.png');
+ * console.log(result.mimeType); // 'image/png'
+ * console.log(result.verified); // true if magic bytes match
+ * ```
+ */
+declare class FileDetector {
+  /**
+   * Magic byte signatures for common file formats.
+   * Each signature is represented as an array of bytes or null (wildcard).
+   */
+  protected static readonly MAGIC_BYTES: Record<string, {
+    signature: (number | null)[];
+    mimeType: string;
+  }[]>;
+  /**
+   * All possible format signatures for checking against actual file content
+   */
+  protected static readonly ALL_SIGNATURES: {
+    signature: (number | null)[];
+    mimeType: string;
+    ext: string;
+  }[];
+  /**
+   * MIME type map for file extensions.
+   *
+   * Can be used to get the content type of file based on its extension.
+   * Feel free to add more mime types in your project!
+   */
+  static readonly mimeMap: Record<string, string>;
+  /**
+   * Reverse MIME type map for looking up extensions from MIME types.
+   * Prefers shorter, more common extensions when multiple exist.
+   */
+  protected static readonly reverseMimeMap: Record<string, string>;
+  /**
+   * Returns the file extension for a given MIME type.
+   *
+   * @param mimeType - The MIME type to look up
+   * @returns The file extension (without dot), or "bin" if not found
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const ext = detector.getExtensionFromMimeType("image/png"); // "png"
+   * const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
+   * ```
+   */
+  getExtensionFromMimeType(mimeType: string): string;
+  /**
+   * Returns the content type of file based on its filename.
+   *
+   * @param filename - The filename to check
+   * @returns The MIME type
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const mimeType = detector.getContentType("image.png"); // "image/png"
+   * ```
+   */
+  getContentType(filename: string): string;
+  /**
+   * Detects the file type by checking magic bytes against the stream content.
+   *
+   * @param stream - The readable stream to check
+   * @param filename - The filename (used to get the extension)
+   * @returns File type information including MIME type, extension, and verification status
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const stream = createReadStream('image.png');
+   * const result = await detector.detectFileType(stream, 'image.png');
+   * console.log(result.mimeType); // 'image/png'
+   * console.log(result.verified); // true if magic bytes match
+   * ```
+   */
+  detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
+  /**
+   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
+   * This approach reads the entire stream upfront to avoid complex async handling issues.
+   *
+   * @protected
+   */
+  protected peekBytes(stream: Readable, numBytes: number): Promise<{
+    buffer: Buffer;
+    stream: Readable;
+  }>;
+  /**
+   * Checks if a buffer matches a magic byte signature.
+   *
+   * @protected
+   */
+  protected matchesSignature(buffer: Buffer, signature: (number | null)[]): boolean;
+}
+//#endregion
 //#region ../../src/bucket/providers/MemoryFileStorageProvider.d.ts
 declare class MemoryFileStorageProvider implements FileStorageProvider {
   readonly files: Record<string, FileLike>;
@@ -108,134 +525,134 @@ declare const $bucket: {
 };
 interface BucketPrimitiveOptions extends BucketFileOptions {
   /**
-       * 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
-       */
+   * 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";
   /**
-       * 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"
-       */
+   * 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"
-       */
+   * 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
-       */
+   * 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
-       */
+   * 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 BucketPrimitive extends Primitive<BucketPrimitiveOptions> {
@@ -243,37 +660,37 @@ declare class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {
   private readonly fileSystem;
   get name(): string;
   /**
-       * Uploads a file to the bucket.
-       */
+   * Uploads a file to the bucket.
+   */
   upload(file: FileLike, options?: BucketFileOptions): Promise<string>;
   /**
-       * Delete permanently a file from the bucket.
-       */
+   * Delete permanently a file from the bucket.
+   */
   delete(fileId: string, skipHook?: boolean): Promise<void>;
   /**
-       * Checks if a file exists in the bucket.
-       */
+   * Checks if a file exists in the bucket.
+   */
   exists(fileId: string): Promise<boolean>;
   /**
-       * Downloads a file from the bucket.
-       */
+   * Downloads a file from the bucket.
+   */
   download(fileId: string): Promise<FileLike>;
   protected $provider(): FileStorageProvider | MemoryFileStorageProvider;
 }
 interface BucketFileOptions {
   /**
-       * Optional description of the bucket.
-       */
+   * Optional description of the bucket.
+   */
   description?: string;
   /**
-       * Allowed MIME types.
-       */
+   * Allowed MIME types.
+   */
   mimeTypes?: string[];
   /**
-       * Maximum size of the files in the bucket.
-       *
-       * @default 10
-       */
+   * Maximum size of the files in the bucket.
+   *
+   * @default 10
+   */
   maxSize?: number;
 }
 //#endregion
@@ -320,9 +737,9 @@ declare class LocalFileStorageProvider implements FileStorageProvider {
 declare module "alepha" {
   interface Hooks {
     /**
-             * Triggered when a file is uploaded to a bucket.
-             * Can be used to perform actions after a file is uploaded, like creating a database record!
-             */
+     * Triggered when a file is uploaded to a bucket.
+     * Can be used to perform actions after a file is uploaded, like creating a database record!
+     */
     "bucket:file:uploaded": {
       id: string;
       file: FileLike;
@@ -330,8 +747,8 @@ declare module "alepha" {
       options: BucketFileOptions;
     };
     /**
-             * Triggered when a file is deleted from a bucket.
-             */
+     * Triggered when a file is deleted from a bucket.
+     */
     "bucket:file:deleted": {
       id: string;
       bucket: BucketPrimitive;
@@ -339,14 +756,21 @@ declare module "alepha" {
   }
 }
 /**
- * Provides file storage capabilities through declarative bucket primitives with support for multiple storage backends.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
+ *
+ * Unified file storage abstraction across multiple backends.
  *
- * The bucket module enables unified file operations across different storage systems using the `$bucket` primitive
- * on class properties. It abstracts storage provider differences, offering consistent APIs for local filesystem,
- * cloud storage, or in-memory storage for testing environments.
+ * **Features:**
+ * - File storage buckets with constraints
+ * - Unified API across all storage backends
+ * - MIME type validation
+ * - File size limits
+ * - Upload/download/delete operations
+ * - TTL-based file expiration
+ * - Providers: Memory (testing), Local filesystem, AWS S3 / Cloudflare R2 / MinIO, Azure Blob Storage, Vercel Blob
  *
- * @see {@link $bucket}
- * @see {@link FileStorageProvider}
  * @module alepha.bucket
  */
 declare const AlephaBucket: alepha1.Service<alepha1.Module>;