alepha 0.21.2 → 0.23.0

package/dist/bucket/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Buffer"],"sources":["../../src/bucket/errors/InvalidFileError.ts","../../src/bucket/providers/FileStorageProvider.ts","../../src/bucket/errors/FileNotFoundError.ts","../../src/bucket/providers/MemoryFileStorageProvider.ts","../../src/bucket/primitives/$bucket.ts","../../src/bucket/providers/LocalFileStorageProvider.ts","../../src/bucket/providers/NodeS3BucketProvider.ts","../../src/bucket/providers/CloudflareR2Provider.ts","../../src/bucket/index.ts"],"sourcesContent":["import { AlephaError } from \"alepha\";\n\nexport class InvalidFileError extends AlephaError {\n  public readonly status = 400;\n}\n","import type { FileLike } from \"alepha\";\n\nexport abstract class FileStorageProvider {\n  /**\n   * Uploads a file to the storage.\n   *\n   * @param bucketName - Container name\n   * @param file - File to upload\n   * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.\n   * @return The identifier of the uploaded file.\n   */\n  abstract upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string>;\n\n  /**\n   * Downloads a file from the storage.\n   *\n   * @param bucketName - Container name\n   * @param fileId - Identifier of the file to download\n   * @return The downloaded file as a FileLike object.\n   */\n  abstract download(bucketName: string, fileId: string): Promise<FileLike>;\n\n  /**\n   * Check if fileId exists in the storage bucket.\n   *\n   * @param bucketName - Container name\n   * @param fileId - Identifier of the file to stream\n   * @return True is the file exists, false otherwise.\n   */\n  abstract exists(bucketName: string, fileId: string): Promise<boolean>;\n\n  /**\n   * Delete permanently a file from the storage.\n   *\n   * @param bucketName - Container name\n   * @param fileId - Identifier of the file to delete\n   */\n  abstract delete(bucketName: string, fileId: string): Promise<void>;\n\n  /**\n   * Delete multiple files in one round-trip where the provider supports\n   * batch (R2/S3, up to 1000 per call). Memory/Local fall back to a loop.\n   *\n   * @param bucketName - Container name\n   * @param fileIds - Identifiers of the files to delete\n   */\n  abstract deleteMany(bucketName: string, fileIds: string[]): Promise<void>;\n}\n","import { AlephaError } from \"alepha\";\n\nexport class FileNotFoundError extends AlephaError {\n  public readonly status = 404;\n}\n","import { $inject, type FileLike } from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { FileDetector, FileSystemProvider } from \"alepha/system\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\ninterface StoredFile {\n  buffer: Buffer;\n  name: string;\n  type: string;\n  size: number;\n}\n\nexport class MemoryFileStorageProvider implements FileStorageProvider {\n  public readonly files: Record<string, StoredFile> = {};\n  protected readonly fileSystem = $inject(FileSystemProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly crypto = $inject(CryptoProvider);\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    fileId ??= this.createId();\n\n    // Consume the stream and store as buffer so downloads are repeatable\n    const chunks: Uint8Array[] = [];\n    for await (const chunk of file.stream() as AsyncIterable<Uint8Array>) {\n      chunks.push(chunk);\n    }\n    const buffer = Buffer.concat(chunks);\n\n    this.files[`${bucketName}/${fileId}`] = {\n      buffer,\n      name: file.name,\n      type: file.type,\n      size: file.size,\n    };\n\n    return fileId;\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    const fileKey = `${bucketName}/${fileId}`;\n    const stored = this.files[fileKey];\n\n    if (!stored) {\n      throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n    }\n\n    // Create a fresh FileLike with a new stream from the stored buffer\n    return this.fileSystem.createFile({\n      stream: new Blob([new Uint8Array(stored.buffer)]).stream(),\n      name: stored.name,\n      type: stored.type,\n      size: stored.size,\n    });\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    return `${bucketName}/${fileId}` in this.files;\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    const fileKey = `${bucketName}/${fileId}`;\n    if (!(fileKey in this.files)) {\n      throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n    }\n\n    delete this.files[fileKey];\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    for (const id of fileIds) {\n      delete this.files[`${bucketName}/${id}`];\n    }\n  }\n\n  protected createId(): string {\n    return this.crypto.randomUUID();\n  }\n}\n","import {\n  $inject,\n  createPrimitive,\n  type FileLike,\n  KIND,\n  Primitive,\n  type Service,\n} from \"alepha\";\nimport { FileSystemProvider } from \"alepha/system\";\nimport { InvalidFileError } from \"../errors/InvalidFileError.ts\";\nimport { FileStorageProvider } from \"../providers/FileStorageProvider.ts\";\nimport { MemoryFileStorageProvider } from \"../providers/MemoryFileStorageProvider.ts\";\n\n/**\n * Creates a bucket primitive for file storage and management with configurable validation.\n *\n * Provides a comprehensive file storage system that handles uploads, downloads, validation,\n * and management across multiple storage backends with MIME type and size limit controls.\n *\n * **Key Features**\n * - Multi-provider support (filesystem, cloud storage, in-memory)\n * - Automatic MIME type and file size validation\n * - Event integration for file operations monitoring\n * - Flexible per-bucket and per-operation configuration\n * - Smart file type and size detection\n *\n * **Common Use Cases**\n * - User profile pictures and document uploads\n * - Product images and media management\n * - Document storage and retrieval systems\n *\n * @example\n * ```ts\n * class MediaService {\n *   images = $bucket({\n *     name: \"user-images\",\n *     mimeTypes: [\"image/jpeg\", \"image/png\", \"image/gif\"],\n *     maxSize: 5 // 5MB limit\n *   });\n *\n *   documents = $bucket({\n *     name: \"documents\",\n *     mimeTypes: [\"application/pdf\", \"text/plain\"],\n *     maxSize: 50 // 50MB limit\n *   });\n *\n *   async uploadProfileImage(file: FileLike, userId: string): Promise<string> {\n *     const fileId = await this.images.upload(file);\n *     await this.userService.updateProfileImage(userId, fileId);\n *     return fileId;\n *   }\n *\n *   async downloadDocument(documentId: string): Promise<FileLike> {\n *     return await this.documents.download(documentId);\n *   }\n *\n *   async deleteDocument(documentId: string): Promise<void> {\n *     await this.documents.delete(documentId);\n *   }\n * }\n * ```\n */\nexport const $bucket = (options: BucketPrimitiveOptions) =>\n  createPrimitive(BucketPrimitive, options);\n\nexport interface BucketPrimitiveOptions extends BucketFileOptions {\n  /**\n   * File storage provider configuration for the bucket.\n   *\n   * Options:\n   * - **\"memory\"**: In-memory storage (default for development, lost on restart)\n   * - **Service<FileStorageProvider>**: Custom provider class (e.g., S3FileStorageProvider, AzureBlobProvider)\n   * - **undefined**: Uses the default file storage provider from dependency injection\n   *\n   * **Provider Selection Guidelines**:\n   * - **Development**: Use \"memory\" for fast, simple testing without external dependencies\n   * - **Production**: Use cloud providers (S3, Azure Blob, Google Cloud Storage) for scalability\n   * - **Local deployment**: Use filesystem providers for on-premise installations\n   * - **Hybrid**: Use different providers for different bucket types (temp files vs permanent storage)\n   *\n   * **Provider Capabilities**:\n   * - File persistence and durability guarantees\n   * - Scalability and performance characteristics\n   * - Geographic distribution and CDN integration\n   * - Cost implications for storage and bandwidth\n   * - Backup and disaster recovery features\n   *\n   * @default Uses injected FileStorageProvider\n   * @example \"memory\"\n   * @example S3FileStorageProvider\n   * @example AzureBlobStorageProvider\n   */\n  provider?: Service<FileStorageProvider> | \"memory\";\n\n  /**\n   * Unique name identifier for the bucket.\n   *\n   * This name is used for:\n   * - Storage backend organization and partitioning\n   * - File path generation and URL construction\n   * - Logging, monitoring, and debugging\n   * - Access control and permissions management\n   * - Backup and replication configuration\n   *\n   * **Naming Conventions**:\n   * - Use lowercase with hyphens for consistency\n   * - Include purpose or content type in the name\n   * - Avoid spaces and special characters\n   * - Consider environment prefixes for deployment isolation\n   *\n   * If not provided, defaults to the property key where the bucket is declared.\n   *\n   * @example \"user-avatars\"\n   * @example \"product-images\"\n   * @example \"legal-documents\"\n   * @example \"temp-processing-files\"\n   */\n  name?: string;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BucketFileOptions {\n  /**\n   * Human-readable description of the bucket's purpose and contents.\n   *\n   * Used for:\n   * - Documentation generation and API references\n   * - Developer onboarding and system understanding\n   * - Monitoring dashboards and admin interfaces\n   * - Compliance and audit documentation\n   *\n   * **Description Best Practices**:\n   * - Explain what types of files this bucket stores\n   * - Mention any special handling or processing requirements\n   * - Include information about retention policies if applicable\n   * - Note any compliance or security considerations\n   *\n   * @example \"User profile pictures and avatar images\"\n   * @example \"Product catalog images with automated thumbnail generation\"\n   * @example \"Legal documents requiring long-term retention\"\n   * @example \"Temporary files for data processing workflows\"\n   */\n  description?: string;\n\n  /**\n   * Array of allowed MIME types for files uploaded to this bucket.\n   *\n   * When specified, only files with these exact MIME types will be accepted.\n   * Files with disallowed MIME types will be rejected with an InvalidFileError.\n   *\n   * **MIME Type Categories**:\n   * - Images: \"image/jpeg\", \"image/png\", \"image/gif\", \"image/webp\", \"image/svg+xml\"\n   * - Documents: \"application/pdf\", \"text/plain\", \"text/csv\"\n   * - Office: \"application/msword\", \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\"\n   * - Archives: \"application/zip\", \"application/x-tar\", \"application/gzip\"\n   * - Media: \"video/mp4\", \"audio/mpeg\", \"audio/wav\"\n   *\n   * **Security Considerations**:\n   * - Always validate MIME types for user uploads\n   * - Be cautious with executable file types\n   * - Consider using allow-lists rather than deny-lists\n   * - Remember that MIME types can be spoofed by malicious users\n   *\n   * If not specified, all MIME types are allowed (not recommended for user uploads).\n   *\n   * @example [\"image/jpeg\", \"image/png\"] // Only JPEG and PNG images\n   * @example [\"application/pdf\", \"text/plain\"] // Documents only\n   * @example [\"video/mp4\", \"video/webm\"] // Video files\n   */\n  mimeTypes?: string[];\n\n  /**\n   * Maximum file size allowed in megabytes (MB).\n   *\n   * Files larger than this limit will be rejected with an InvalidFileError.\n   * This helps prevent:\n   * - Storage quota exhaustion\n   * - Memory issues during file processing\n   * - Long upload times and timeouts\n   * - Abuse of storage resources\n   *\n   * **Size Guidelines by File Type**:\n   * - Profile images: 1-5 MB\n   * - Product photos: 5-10 MB\n   * - Documents: 10-50 MB\n   * - Video files: 50-500 MB\n   * - Data files: 100-1000 MB\n   *\n   * **Considerations**:\n   * - Consider your storage costs and limits\n   * - Factor in network upload speeds for users\n   * - Account for processing requirements (thumbnails, compression)\n   * - Set reasonable limits based on actual use cases\n   *\n   * @default 10 MB\n   *\n   * @example 1    // 1MB for small images\n   * @example 25   // 25MB for documents\n   * @example 100  // 100MB for media files\n   */\n  maxSize?: number;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {\n  public readonly provider = this.$provider();\n  protected readonly fileSystem = $inject(FileSystemProvider);\n\n  public get name() {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  /**\n   * Uploads a file to the bucket.\n   */\n  public async upload(\n    file: FileLike,\n    options?: BucketFileOptions,\n  ): Promise<string> {\n    if (file instanceof File) {\n      // our createFile is smarter than the browser's File constructor\n      // by doing this, we can guess the MIME type and size!\n      file = this.fileSystem.createFile({ file });\n    }\n\n    options = {\n      ...this.options,\n      ...options,\n    };\n\n    const mimeTypes = options.mimeTypes ?? undefined;\n    const maxSize = options.maxSize ?? 10; // Default to 10 MB if not specified\n\n    if (mimeTypes) {\n      const mimeType = file.type || \"application/octet-stream\";\n      if (!mimeTypes.includes(mimeType)) {\n        throw new InvalidFileError(\n          `MIME type ${mimeType} is not allowed in bucket ${this.name}`,\n        );\n      }\n    }\n\n    // check size in bytes, convert MB to bytes\n    if (file.size > maxSize * 1024 * 1024) {\n      throw new InvalidFileError(\n        `File size ${file.size} exceeds the maximum size of ${maxSize} MB in bucket ${this.name}`,\n      );\n    }\n\n    const id = await this.provider.upload(this.name, file);\n\n    await this.alepha.events.emit(\"bucket:file:uploaded\", {\n      id,\n      bucket: this,\n      file,\n      options,\n    });\n\n    return id;\n  }\n\n  /**\n   * Delete permanently a file from the bucket.\n   */\n  public async delete(fileId: string, skipHook = false): Promise<void> {\n    await this.provider.delete(this.name, fileId);\n\n    if (skipHook) {\n      return;\n    }\n\n    await this.alepha.events.emit(\"bucket:file:deleted\", {\n      id: fileId,\n      bucket: this,\n    });\n  }\n\n  /**\n   * Delete many files in one round-trip when the underlying provider supports\n   * batch (R2/S3 up to 1000 keys per call). Emits one `bucket:file:deleted`\n   * event per id unless `skipHook` is set.\n   */\n  public async deleteMany(fileIds: string[], skipHook = false): Promise<void> {\n    if (fileIds.length === 0) return;\n    await this.provider.deleteMany(this.name, fileIds);\n\n    if (skipHook) {\n      return;\n    }\n\n    for (const id of fileIds) {\n      await this.alepha.events.emit(\"bucket:file:deleted\", {\n        id,\n        bucket: this,\n      });\n    }\n  }\n\n  /**\n   * Checks if a file exists in the bucket.\n   */\n  public async exists(fileId: string): Promise<boolean> {\n    return this.provider.exists(this.name, fileId);\n  }\n\n  /**\n   * Downloads a file from the bucket.\n   */\n  public async download(fileId: string): Promise<FileLike> {\n    const file = await this.provider.download(this.name, fileId);\n\n    await this.alepha.events.emit(\"bucket:file:downloaded\", {\n      id: fileId,\n      bucket: this,\n      file,\n    });\n\n    return file;\n  }\n\n  protected $provider() {\n    if (!this.options.provider) {\n      return this.alepha.inject(FileStorageProvider);\n    }\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemoryFileStorageProvider);\n    }\n    return this.alepha.inject(this.options.provider);\n  }\n}\n\n$bucket[KIND] = BucketPrimitive;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BucketFileOptions {\n  /**\n   * Optional description of the bucket.\n   */\n  description?: string;\n\n  /**\n   * Allowed MIME types.\n   */\n  mimeTypes?: string[];\n\n  /**\n   * Maximum size of the files in the bucket.\n   *\n   * @default 10\n   */\n  maxSize?: number;\n}\n","import type * as fs from \"node:fs\";\nimport { createReadStream } from \"node:fs\";\nimport { mkdir, stat, unlink } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport {\n  $atom,\n  $hook,\n  $inject,\n  $state,\n  Alepha,\n  AlephaError,\n  type FileLike,\n  type Static,\n  t,\n} from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { $logger } from \"alepha/logger\";\nimport { FileDetector, FileSystemProvider } from \"alepha/system\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport { $bucket } from \"../primitives/$bucket.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Local file storage configuration atom\n */\nexport const localFileStorageOptions = $atom({\n  name: \"alepha.bucket.local.options\",\n  schema: t.object({\n    storagePath: t.string({\n      description: \"Directory path where files will be stored\",\n    }),\n  }),\n  default: {\n    storagePath: \"node_modules/.alepha/buckets\",\n  },\n});\n\nexport type LocalFileStorageProviderOptions = Static<\n  typeof localFileStorageOptions.schema\n>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [localFileStorageOptions.key]: LocalFileStorageProviderOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class LocalFileStorageProvider implements FileStorageProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly fileSystemProvider = $inject(FileSystemProvider);\n  protected readonly crypto = $inject(CryptoProvider);\n  protected readonly options = $state(localFileStorageOptions);\n\n  protected get storagePath(): string {\n    return this.options.storagePath;\n  }\n\n  protected readonly onConfigure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      if (\n        this.alepha.isTest() &&\n        this.storagePath === localFileStorageOptions.options.default.storagePath\n      ) {\n        this.alepha.store.set(localFileStorageOptions, {\n          storagePath: join(tmpdir(), `alepha-test-${Date.now()}`),\n        });\n      }\n    },\n  });\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      try {\n        await mkdir(this.storagePath, { recursive: true });\n      } catch {}\n\n      for (const bucket of this.alepha.primitives($bucket)) {\n        if (bucket.provider !== this) {\n          continue;\n        }\n\n        await mkdir(join(this.storagePath, bucket.name), {\n          recursive: true,\n        });\n\n        this.log.debug(`Bucket '${bucket.name}' at ${this.storagePath} OK`);\n      }\n    },\n  });\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    fileId ??= this.createId(file.type);\n\n    this.log.trace(`Uploading file to ${bucketName}`);\n\n    await this.fileSystemProvider.writeFile(\n      this.path(bucketName, fileId),\n      file,\n    );\n\n    return fileId;\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    const filePath = this.path(bucketName, fileId);\n\n    try {\n      const stats = await stat(filePath);\n      const mimeType = this.fileDetector.getContentType(fileId);\n\n      return this.fileSystemProvider.createFile({\n        stream: createReadStream(filePath),\n        name: fileId,\n        type: mimeType,\n        size: stats.size,\n      });\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n      }\n      throw new AlephaError(\"Invalid file operation\", { cause: error });\n    }\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    try {\n      await stat(this.path(bucketName, fileId));\n      return true;\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        return false;\n      }\n      throw new AlephaError(\"Error checking file existence\", { cause: error });\n    }\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    try {\n      return await unlink(this.path(bucketName, fileId));\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n      }\n      throw new AlephaError(\"Error deleting file\", { cause: error });\n    }\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    await Promise.all(\n      fileIds.map((id) =>\n        unlink(this.path(bucketName, id)).catch((error) => {\n          if (this.isErrorNoEntry(error)) return;\n          throw new AlephaError(\"Error deleting file\", { cause: error });\n        }),\n      ),\n    );\n  }\n\n  protected stat(bucket: string, fileId: string): Promise<fs.Stats> {\n    return stat(this.path(bucket, fileId));\n  }\n\n  protected createId(mimeType: string): string {\n    const ext = this.fileDetector.getExtensionFromMimeType(mimeType);\n    return `${this.crypto.randomUUID()}.${ext}`;\n  }\n\n  protected path(bucket: string, fileId = \"\"): string {\n    return join(this.storagePath, bucket, fileId);\n  }\n\n  protected isErrorNoEntry(error: unknown): boolean {\n    return error instanceof Error && \"code\" in error && error.code === \"ENOENT\";\n  }\n}\n","import { Buffer } from \"node:buffer\";\nimport {\n  $env,\n  $hook,\n  $inject,\n  Alepha,\n  AlephaError,\n  type FileLike,\n  type Static,\n  t,\n} from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { $logger } from \"alepha/logger\";\nimport { FileDetector, FileSystemProvider } from \"alepha/system\";\nimport { S3mini } from \"s3mini\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport { $bucket } from \"../primitives/$bucket.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\nconst envSchema = t.object({\n  /**\n   * S3 endpoint URL. The bucket name is appended (path-style) per request.\n   *\n   * Examples:\n   * - AWS S3: `https://s3.us-east-1.amazonaws.com`\n   * - Cloudflare R2: `https://<account-id>.r2.cloudflarestorage.com`\n   * - MinIO: `http://localhost:9000`\n   * - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`\n   */\n  S3_ENDPOINT: t.string(),\n\n  /**\n   * AWS region or \"auto\" for R2.\n   *\n   * @default \"auto\"\n   */\n  S3_REGION: t.optional(t.string()),\n\n  /**\n   * Access key ID for S3 authentication.\n   */\n  S3_ACCESS_KEY_ID: t.string(),\n\n  /**\n   * Secret access key for S3 authentication.\n   */\n  S3_SECRET_ACCESS_KEY: t.string(),\n});\n\ndeclare module \"alepha\" {\n  interface Env extends Partial<Static<typeof envSchema>> {}\n}\n\n/**\n * S3-compatible file storage provider for Node.js.\n *\n * Backed by `s3mini` (zero-dep, ~20 KB). Works with AWS S3, Cloudflare R2,\n * MinIO, DigitalOcean Spaces, Backblaze B2, and any other S3-compatible service.\n *\n * Uses path-style addressing (`<endpoint>/<bucket>`).\n */\nexport class NodeS3BucketProvider implements FileStorageProvider {\n  protected readonly log = $logger();\n  protected readonly env = $env(envSchema);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly fileSystem = $inject(FileSystemProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly crypto = $inject(CryptoProvider);\n  protected readonly clients: Map<string, S3mini> = new Map();\n\n  /**\n   * Convert bucket name to S3-compatible format.\n   * S3 bucket names must be lowercase, 3-63 characters, no underscores.\n   */\n  public convertName(name: string): string {\n    return name.replaceAll(\"/\", \"-\").replaceAll(\"_\", \"-\").toLowerCase();\n  }\n\n  protected getClient(bucketName: string): S3mini {\n    const name = this.convertName(bucketName);\n    let client = this.clients.get(name);\n    if (!client) {\n      const endpoint = this.env.S3_ENDPOINT.replace(/\\/+$/, \"\");\n      client = new S3mini({\n        accessKeyId: this.env.S3_ACCESS_KEY_ID,\n        secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,\n        region: this.env.S3_REGION || \"auto\",\n        endpoint: `${endpoint}/${name}`,\n      });\n      this.clients.set(name, client);\n    }\n    return client;\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      for (const bucket of this.alepha.primitives($bucket)) {\n        if (bucket.provider !== this) {\n          continue;\n        }\n\n        const name = this.convertName(bucket.name);\n        const client = this.getClient(bucket.name);\n\n        this.log.debug(`Preparing S3 bucket '${name}'...`);\n\n        const exists = await client.bucketExists();\n        if (!exists) {\n          this.log.debug(`Creating S3 bucket '${name}'...`);\n          const created = await client.createBucket();\n          if (!created) {\n            throw new AlephaError(`Failed to create S3 bucket '${name}'`);\n          }\n        }\n\n        this.log.info(`S3 bucket '${bucket.name}' OK`);\n      }\n    },\n  });\n\n  protected createId(mimeType: string): string {\n    const ext = this.fileDetector.getExtensionFromMimeType(mimeType);\n    return `${this.crypto.randomUUID()}.${ext}`;\n  }\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    fileId ??= this.createId(file.type);\n\n    this.log.trace(\n      `Uploading file '${file.name}' to bucket '${bucketName}' with id '${fileId}'...`,\n    );\n\n    const client = this.getClient(bucketName);\n\n    try {\n      const buffer = new Uint8Array(await file.arrayBuffer());\n      await client.putObject(\n        fileId,\n        buffer,\n        file.type || \"application/octet-stream\",\n        undefined,\n        { \"x-amz-meta-name\": encodeURIComponent(file.name) },\n        file.size,\n      );\n\n      this.log.trace(`File uploaded successfully: ${fileId}`);\n      return fileId;\n    } catch (error) {\n      this.log.error(`Failed to upload file: ${error}`);\n      if (error instanceof Error) {\n        throw new AlephaError(`Upload failed: ${error.message}`, {\n          cause: error,\n        });\n      }\n      throw error;\n    }\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    this.log.trace(\n      `Downloading file '${fileId}' from bucket '${bucketName}'...`,\n    );\n\n    const client = this.getClient(bucketName);\n    const response = await client.getObjectResponse(fileId);\n\n    if (!response) {\n      throw new FileNotFoundError(\n        `File '${fileId}' not found in bucket '${bucketName}'`,\n      );\n    }\n\n    const buffer = Buffer.from(await response.arrayBuffer());\n\n    const mimeType =\n      response.headers.get(\"content-type\") ||\n      this.fileDetector.getContentType(fileId);\n\n    const metaName = response.headers.get(\"x-amz-meta-name\");\n    const name = metaName ? decodeURIComponent(metaName) : fileId;\n\n    return this.fileSystem.createFile({\n      buffer,\n      name,\n      type: mimeType,\n      size: buffer.length,\n    });\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    this.log.trace(\n      `Checking existence of file '${fileId}' in bucket '${bucketName}'...`,\n    );\n\n    const client = this.getClient(bucketName);\n    const result = await client.objectExists(fileId);\n    return result === true;\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    this.log.trace(`Deleting file '${fileId}' from bucket '${bucketName}'...`);\n\n    const client = this.getClient(bucketName);\n\n    try {\n      await client.deleteObject(fileId);\n    } catch (error) {\n      this.log.error(`Failed to delete file: ${error}`);\n      if (error instanceof Error) {\n        throw new FileNotFoundError(\"Error deleting file\", { cause: error });\n      }\n      throw error;\n    }\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    if (fileIds.length === 0) return;\n    this.log.trace(\n      `Deleting ${fileIds.length} files from bucket '${bucketName}'...`,\n    );\n    const client = this.getClient(bucketName);\n    // S3 DeleteObjects caps at 1000 keys per request.\n    for (let i = 0; i < fileIds.length; i += 1000) {\n      const chunk = fileIds.slice(i, i + 1000);\n      try {\n        // bun:s3 client exposes a per-key deleteObject; some SDKs also expose\n        // deleteObjects(keys: string[]). Prefer batch when available.\n        const batch = (\n          client as unknown as {\n            deleteObjects?: (keys: string[]) => Promise<unknown>;\n          }\n        ).deleteObjects;\n        if (typeof batch === \"function\") {\n          await batch.call(client, chunk);\n        } else {\n          await Promise.all(chunk.map((id) => client.deleteObject(id)));\n        }\n      } catch (error) {\n        this.log.error(`Failed to delete files: ${error}`);\n        if (error instanceof Error) {\n          throw new FileNotFoundError(\"Error deleting files\", { cause: error });\n        }\n        throw error;\n      }\n    }\n  }\n}\n","import type { R2Bucket } from \"@cloudflare/workers-types\";\nimport {\n  $env,\n  $hook,\n  $inject,\n  Alepha,\n  AlephaError,\n  type FileLike,\n  t,\n} from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { $logger } from \"alepha/logger\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport { $bucket } from \"../primitives/$bucket.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Cloudflare R2 storage provider.\n *\n * Uses a single R2 bucket binding for all $bucket primitives.\n * Files are organized as: {APP_NAME}/{bucketName}/{fileId}\n *\n * **Required environment variables:**\n * - `R2_BUCKET_NAME` - The actual R2 bucket name in Cloudflare\n *\n * **Optional (uses core Alepha env):**\n * - `APP_NAME` - Prefix for all files (for multi-app setups sharing one R2 bucket)\n *\n * @example\n * ```bash\n * # .env\n * APP_NAME=myapp        # optional, used as prefix\n * R2_BUCKET_NAME=storage\n * ```\n *\n * @example\n * ```toml\n * # wrangler.toml - automatically generated by alepha build\n * [[r2_buckets]]\n * binding = \"R2\"\n * bucket_name = \"storage\"\n * ```\n *\n * @example\n * ```ts\n * // Define buckets with validation rules\n * const avatars = $bucket({\n *   name: \"avatars\",\n *   maxFileSize: 5 * 1024 * 1024,\n *   allowedMimeTypes: [\"image/*\"],\n * });\n *\n * const documents = $bucket({\n *   name: \"documents\",\n *   maxFileSize: 50 * 1024 * 1024,\n *   allowedMimeTypes: [\"application/pdf\"],\n * });\n *\n * // Files stored at: myapp/avatars/uuid.png, myapp/documents/uuid.pdf\n * ```\n */\nexport class CloudflareR2Provider implements FileStorageProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly crypto = $inject(CryptoProvider);\n  protected readonly env = $env(\n    t.object({\n      /**\n       * The actual R2 bucket name in Cloudflare.\n       */\n      R2_BUCKET_NAME: t.string({\n        description: \"R2 bucket name in Cloudflare\",\n      }),\n    }),\n  );\n\n  protected r2?: R2Bucket;\n\n  /**\n   * Get the R2 bucket name from environment.\n   */\n  public get bucketName(): string {\n    return this.env.R2_BUCKET_NAME;\n  }\n\n  /**\n   * Get the optional prefix from APP_NAME environment variable.\n   * Used for multi-app setups sharing the same R2 bucket.\n   */\n  public get prefix(): string | undefined {\n    return this.alepha.env.APP_NAME;\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      const cloudflareEnv = this.alepha.get(\"cloudflare.env\") as\n        | Record<string, unknown>\n        | undefined;\n      if (!cloudflareEnv) {\n        throw new AlephaError(\n          \"Cloudflare Workers environment not found in Alepha store under 'cloudflare.env'.\",\n        );\n      }\n\n      const binding = cloudflareEnv[this.bucketName] as R2Bucket | undefined;\n      if (!binding) {\n        throw new AlephaError(\n          `R2 binding '${this.bucketName}' not found in Cloudflare Workers environment.`,\n        );\n      }\n\n      this.r2 = binding;\n\n      const prefixStr = this.prefix ? `${this.prefix}/` : \"\";\n      this.log.info(\n        `R2 storage ready (bucket: ${this.bucketName}, prefix: ${prefixStr || \"(none)\"})`,\n      );\n\n      for (const bucket of this.alepha.primitives($bucket)) {\n        if (bucket.provider !== this) {\n          continue;\n        }\n        this.log.debug(\n          `Bucket '${bucket.name}' -> ${prefixStr}${bucket.name}/`,\n        );\n      }\n    },\n  });\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    const r2 = this.getR2();\n    fileId ??= this.createId(file.name);\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Uploading '${key}'`);\n\n    const arrayBuffer = await file.arrayBuffer();\n\n    await r2.put(key, arrayBuffer, {\n      httpMetadata: {\n        contentType: file.type,\n      },\n      customMetadata: {\n        originalName: file.name,\n        bucket: bucketName,\n      },\n    });\n\n    return fileId;\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    const r2 = this.getR2();\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Downloading '${key}'`);\n\n    const object = await r2.get(key);\n    if (!object) {\n      throw new FileNotFoundError(\n        `File '${fileId}' not found in bucket '${bucketName}'.`,\n      );\n    }\n\n    const originalName = object.customMetadata?.originalName ?? fileId;\n    const contentType =\n      object.httpMetadata?.contentType ?? \"application/octet-stream\";\n\n    return {\n      name: originalName,\n      type: contentType,\n      size: object.size,\n      lastModified: object.uploaded.getTime(),\n      stream: () => object.body as unknown as ReadableStream,\n      arrayBuffer: () => object.arrayBuffer(),\n      text: () => object.text(),\n    };\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    const r2 = this.getR2();\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Checking '${key}'`);\n\n    const object = await r2.head(key);\n    return object !== null;\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    const r2 = this.getR2();\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Deleting '${key}'`);\n\n    // R2's delete doesn't throw if the file doesn't exist,\n    // so we check existence first for consistency with other providers\n    const exists = await this.exists(bucketName, fileId);\n    if (!exists) {\n      throw new FileNotFoundError(\n        `File '${fileId}' not found in bucket '${bucketName}'.`,\n      );\n    }\n\n    await r2.delete(key);\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    if (fileIds.length === 0) return;\n    const r2 = this.getR2();\n    const keys = fileIds.map((id) => this.key(bucketName, id));\n    this.log.trace(`Deleting ${keys.length} keys from '${bucketName}'`);\n    // R2 binding accepts a string[] and silently ignores missing keys.\n    // Chunk at 1000 to stay within the documented batch limit.\n    for (let i = 0; i < keys.length; i += 1000) {\n      await r2.delete(keys.slice(i, i + 1000));\n    }\n  }\n\n  /**\n   * Build the full R2 key: {prefix}/{bucketName}/{fileId}\n   */\n  protected key(bucketName: string, fileId: string): string {\n    const parts = [bucketName, fileId];\n    if (this.prefix) {\n      parts.unshift(this.prefix);\n    }\n    return parts.join(\"/\");\n  }\n\n  protected getR2(): R2Bucket {\n    if (!this.r2) {\n      throw new AlephaError(\"R2 storage not initialized. Call start() first.\");\n    }\n    return this.r2;\n  }\n\n  protected createId(filename: string): string {\n    const ext = filename.includes(\".\") ? filename.split(\".\").pop() : \"\";\n    const id = this.crypto.randomUUID();\n    return ext ? `${id}.${ext}` : id;\n  }\n}\n","import { $module, type FileLike } from \"alepha\";\nimport {\n  $bucket,\n  type BucketFileOptions,\n  type BucketPrimitive,\n} from \"./primitives/$bucket.ts\";\nimport { FileStorageProvider } from \"./providers/FileStorageProvider.ts\";\nimport { LocalFileStorageProvider } from \"./providers/LocalFileStorageProvider.ts\";\nimport { MemoryFileStorageProvider } from \"./providers/MemoryFileStorageProvider.ts\";\nimport { NodeS3BucketProvider } from \"./providers/NodeS3BucketProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./errors/FileNotFoundError.ts\";\nexport * from \"./primitives/$bucket.ts\";\nexport * from \"./providers/CloudflareR2Provider.ts\";\nexport * from \"./providers/FileStorageProvider.ts\";\nexport * from \"./providers/LocalFileStorageProvider.ts\";\nexport * from \"./providers/MemoryFileStorageProvider.ts\";\nexport * from \"./providers/NodeS3BucketProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface Hooks {\n    /**\n     * Triggered when a file is uploaded to a bucket.\n     * Can be used to perform actions after a file is uploaded, like creating a database record!\n     */\n    \"bucket:file:uploaded\": {\n      id: string;\n      file: FileLike;\n      bucket: BucketPrimitive;\n      options: BucketFileOptions;\n    };\n    /**\n     * Triggered when a file is deleted from a bucket.\n     */\n    \"bucket:file:deleted\": {\n      id: string;\n      bucket: BucketPrimitive;\n    };\n    /**\n     * Triggered when a file is downloaded from a bucket.\n     */\n    \"bucket:file:downloaded\": {\n      id: string;\n      file: FileLike;\n      bucket: BucketPrimitive;\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Unified file storage abstraction across multiple backends.\n *\n * **Features:**\n * - File storage buckets with constraints\n * - Unified API across all storage backends\n * - MIME type validation\n * - File size limits\n * - Upload/download/delete operations\n * - TTL-based file expiration\n * - Providers: Memory (testing), Local filesystem, AWS S3 / Cloudflare R2 / MinIO, Azure Blob Storage, Vercel Blob\n *\n * @module alepha.bucket\n */\nexport const AlephaBucket = $module({\n  name: \"alepha.bucket\",\n  primitives: [$bucket],\n  services: [FileStorageProvider],\n  variants: [\n    MemoryFileStorageProvider,\n    LocalFileStorageProvider,\n    NodeS3BucketProvider,\n  ],\n  register: (alepha) => {\n    const useS3 = !!alepha.env.S3_ENDPOINT;\n    alepha.with({\n      optional: true,\n      provide: FileStorageProvider,\n      use:\n        alepha.isTest() || alepha.isServerless()\n          ? MemoryFileStorageProvider\n          : useS3\n            ? NodeS3BucketProvider\n            : LocalFileStorageProvider,\n    });\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["Buffer"],"sources":["../../src/bucket/errors/InvalidFileError.ts","../../src/bucket/providers/FileStorageProvider.ts","../../src/bucket/errors/FileNotFoundError.ts","../../src/bucket/providers/MemoryFileStorageProvider.ts","../../src/bucket/primitives/$bucket.ts","../../src/bucket/providers/LocalFileStorageProvider.ts","../../src/bucket/providers/S3FileStorageProvider.ts","../../src/bucket/providers/R2FileStorageProvider.ts","../../src/bucket/index.ts"],"sourcesContent":["import { AlephaError } from \"alepha\";\n\nexport class InvalidFileError extends AlephaError {\n  public readonly status = 400;\n}\n","import type { FileLike } from \"alepha\";\n\nexport abstract class FileStorageProvider {\n  /**\n   * Uploads a file to the storage.\n   *\n   * @param bucketName - Container name\n   * @param file - File to upload\n   * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.\n   * @return The identifier of the uploaded file.\n   */\n  abstract upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string>;\n\n  /**\n   * Downloads a file from the storage.\n   *\n   * @param bucketName - Container name\n   * @param fileId - Identifier of the file to download\n   * @return The downloaded file as a FileLike object.\n   */\n  abstract download(bucketName: string, fileId: string): Promise<FileLike>;\n\n  /**\n   * Check if fileId exists in the storage bucket.\n   *\n   * @param bucketName - Container name\n   * @param fileId - Identifier of the file to stream\n   * @return True is the file exists, false otherwise.\n   */\n  abstract exists(bucketName: string, fileId: string): Promise<boolean>;\n\n  /**\n   * Delete permanently a file from the storage.\n   *\n   * @param bucketName - Container name\n   * @param fileId - Identifier of the file to delete\n   */\n  abstract delete(bucketName: string, fileId: string): Promise<void>;\n\n  /**\n   * Delete multiple files in one round-trip where the provider supports\n   * batch (R2/S3, up to 1000 per call). Memory/Local fall back to a loop.\n   *\n   * @param bucketName - Container name\n   * @param fileIds - Identifiers of the files to delete\n   */\n  abstract deleteMany(bucketName: string, fileIds: string[]): Promise<void>;\n\n  /**\n   * Lists the file identifiers stored in a bucket, like `ls` on a directory.\n   *\n   * This is a flat, unpaginated listing intended for small buckets. Providers\n   * cap the result at their natural page size (~1000 for S3/R2); anything beyond\n   * that is silently dropped. It is NOT a search API — use `alepha/api/files`\n   * when you need querying or pagination.\n   *\n   * @param bucketName - Container name\n   * @return The identifiers of the files in the bucket (empty if none).\n   */\n  abstract list(bucketName: string): Promise<string[]>;\n}\n","import { AlephaError } from \"alepha\";\n\nexport class FileNotFoundError extends AlephaError {\n  public readonly status = 404;\n}\n","import { $inject, type FileLike } from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { FileDetector, FileSystemProvider } from \"alepha/system\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\ninterface StoredFile {\n  buffer: Buffer;\n  name: string;\n  type: string;\n  size: number;\n}\n\nexport class MemoryFileStorageProvider implements FileStorageProvider {\n  public readonly files: Record<string, StoredFile> = {};\n  protected readonly fileSystem = $inject(FileSystemProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly crypto = $inject(CryptoProvider);\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    fileId ??= this.createId();\n\n    // Consume the stream and store as buffer so downloads are repeatable\n    const chunks: Uint8Array[] = [];\n    for await (const chunk of file.stream() as AsyncIterable<Uint8Array>) {\n      chunks.push(chunk);\n    }\n    const buffer = Buffer.concat(chunks);\n\n    this.files[`${bucketName}/${fileId}`] = {\n      buffer,\n      name: file.name,\n      type: file.type,\n      size: file.size,\n    };\n\n    return fileId;\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    const fileKey = `${bucketName}/${fileId}`;\n    const stored = this.files[fileKey];\n\n    if (!stored) {\n      throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n    }\n\n    // Create a fresh FileLike with a new stream from the stored buffer\n    return this.fileSystem.createFile({\n      stream: new Blob([new Uint8Array(stored.buffer)]).stream(),\n      name: stored.name,\n      type: stored.type,\n      size: stored.size,\n    });\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    return `${bucketName}/${fileId}` in this.files;\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    const fileKey = `${bucketName}/${fileId}`;\n    if (!(fileKey in this.files)) {\n      throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n    }\n\n    delete this.files[fileKey];\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    for (const id of fileIds) {\n      delete this.files[`${bucketName}/${id}`];\n    }\n  }\n\n  public async list(bucketName: string): Promise<string[]> {\n    const prefix = `${bucketName}/`;\n    return Object.keys(this.files)\n      .filter((key) => key.startsWith(prefix))\n      .map((key) => key.slice(prefix.length));\n  }\n\n  protected createId(): string {\n    return this.crypto.randomUUID();\n  }\n}\n","import {\n  $inject,\n  createPrimitive,\n  type FileLike,\n  KIND,\n  Primitive,\n  type Service,\n} from \"alepha\";\nimport { FileSystemProvider } from \"alepha/system\";\nimport { InvalidFileError } from \"../errors/InvalidFileError.ts\";\nimport { FileStorageProvider } from \"../providers/FileStorageProvider.ts\";\nimport { MemoryFileStorageProvider } from \"../providers/MemoryFileStorageProvider.ts\";\n\n/**\n * Creates a bucket primitive for file storage and management with configurable validation.\n *\n * Provides a comprehensive file storage system that handles uploads, downloads, validation,\n * and management across multiple storage backends with MIME type and size limit controls.\n *\n * **Key Features**\n * - Multi-provider support (filesystem, cloud storage, in-memory)\n * - Automatic MIME type and file size validation\n * - Event integration for file operations monitoring\n * - Flexible per-bucket and per-operation configuration\n * - Smart file type and size detection\n *\n * **Common Use Cases**\n * - User profile pictures and document uploads\n * - Product images and media management\n * - Document storage and retrieval systems\n *\n * @example\n * ```ts\n * class MediaService {\n *   images = $bucket({\n *     name: \"user-images\",\n *     mimeTypes: [\"image/jpeg\", \"image/png\", \"image/gif\"],\n *     maxSize: 5 // 5MB limit\n *   });\n *\n *   documents = $bucket({\n *     name: \"documents\",\n *     mimeTypes: [\"application/pdf\", \"text/plain\"],\n *     maxSize: 50 // 50MB limit\n *   });\n *\n *   async uploadProfileImage(file: FileLike, userId: string): Promise<string> {\n *     const fileId = await this.images.upload(file);\n *     await this.userService.updateProfileImage(userId, fileId);\n *     return fileId;\n *   }\n *\n *   async downloadDocument(documentId: string): Promise<FileLike> {\n *     return await this.documents.download(documentId);\n *   }\n *\n *   async deleteDocument(documentId: string): Promise<void> {\n *     await this.documents.delete(documentId);\n *   }\n * }\n * ```\n */\nexport const $bucket = (options: BucketPrimitiveOptions) =>\n  createPrimitive(BucketPrimitive, options);\n\nexport interface BucketPrimitiveOptions extends BucketFileOptions {\n  /**\n   * File storage provider configuration for the bucket.\n   *\n   * Options:\n   * - **\"memory\"**: In-memory storage (default for development, lost on restart)\n   * - **Service<FileStorageProvider>**: Custom provider class (e.g., S3FileStorageProvider, AzureBlobProvider)\n   * - **undefined**: Uses the default file storage provider from dependency injection\n   *\n   * **Provider Selection Guidelines**:\n   * - **Development**: Use \"memory\" for fast, simple testing without external dependencies\n   * - **Production**: Use cloud providers (S3, Azure Blob, Google Cloud Storage) for scalability\n   * - **Local deployment**: Use filesystem providers for on-premise installations\n   * - **Hybrid**: Use different providers for different bucket types (temp files vs permanent storage)\n   *\n   * **Provider Capabilities**:\n   * - File persistence and durability guarantees\n   * - Scalability and performance characteristics\n   * - Geographic distribution and CDN integration\n   * - Cost implications for storage and bandwidth\n   * - Backup and disaster recovery features\n   *\n   * @default Uses injected FileStorageProvider\n   * @example \"memory\"\n   * @example S3FileStorageProvider\n   * @example AzureBlobStorageProvider\n   */\n  provider?: Service<FileStorageProvider> | \"memory\";\n\n  /**\n   * Unique name identifier for the bucket.\n   *\n   * This name is used for:\n   * - Storage backend organization and partitioning\n   * - File path generation and URL construction\n   * - Logging, monitoring, and debugging\n   * - Access control and permissions management\n   * - Backup and replication configuration\n   *\n   * **Naming Conventions**:\n   * - Use lowercase with hyphens for consistency\n   * - Include purpose or content type in the name\n   * - Avoid spaces and special characters\n   * - Consider environment prefixes for deployment isolation\n   *\n   * If not provided, defaults to the property key where the bucket is declared.\n   *\n   * @example \"user-avatars\"\n   * @example \"product-images\"\n   * @example \"legal-documents\"\n   * @example \"temp-processing-files\"\n   */\n  name?: string;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BucketFileOptions {\n  /**\n   * Human-readable description of the bucket's purpose and contents.\n   *\n   * Used for:\n   * - Documentation generation and API references\n   * - Developer onboarding and system understanding\n   * - Monitoring dashboards and admin interfaces\n   * - Compliance and audit documentation\n   *\n   * **Description Best Practices**:\n   * - Explain what types of files this bucket stores\n   * - Mention any special handling or processing requirements\n   * - Include information about retention policies if applicable\n   * - Note any compliance or security considerations\n   *\n   * @example \"User profile pictures and avatar images\"\n   * @example \"Product catalog images with automated thumbnail generation\"\n   * @example \"Legal documents requiring long-term retention\"\n   * @example \"Temporary files for data processing workflows\"\n   */\n  description?: string;\n\n  /**\n   * Array of allowed MIME types for files uploaded to this bucket.\n   *\n   * When specified, only files with these exact MIME types will be accepted.\n   * Files with disallowed MIME types will be rejected with an InvalidFileError.\n   *\n   * **MIME Type Categories**:\n   * - Images: \"image/jpeg\", \"image/png\", \"image/gif\", \"image/webp\", \"image/svg+xml\"\n   * - Documents: \"application/pdf\", \"text/plain\", \"text/csv\"\n   * - Office: \"application/msword\", \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\"\n   * - Archives: \"application/zip\", \"application/x-tar\", \"application/gzip\"\n   * - Media: \"video/mp4\", \"audio/mpeg\", \"audio/wav\"\n   *\n   * **Security Considerations**:\n   * - Always validate MIME types for user uploads\n   * - Be cautious with executable file types\n   * - Consider using allow-lists rather than deny-lists\n   * - Remember that MIME types can be spoofed by malicious users\n   *\n   * If not specified, all MIME types are allowed (not recommended for user uploads).\n   *\n   * @example [\"image/jpeg\", \"image/png\"] // Only JPEG and PNG images\n   * @example [\"application/pdf\", \"text/plain\"] // Documents only\n   * @example [\"video/mp4\", \"video/webm\"] // Video files\n   */\n  mimeTypes?: string[];\n\n  /**\n   * Maximum file size allowed in megabytes (MB).\n   *\n   * Files larger than this limit will be rejected with an InvalidFileError.\n   * This helps prevent:\n   * - Storage quota exhaustion\n   * - Memory issues during file processing\n   * - Long upload times and timeouts\n   * - Abuse of storage resources\n   *\n   * **Size Guidelines by File Type**:\n   * - Profile images: 1-5 MB\n   * - Product photos: 5-10 MB\n   * - Documents: 10-50 MB\n   * - Video files: 50-500 MB\n   * - Data files: 100-1000 MB\n   *\n   * **Considerations**:\n   * - Consider your storage costs and limits\n   * - Factor in network upload speeds for users\n   * - Account for processing requirements (thumbnails, compression)\n   * - Set reasonable limits based on actual use cases\n   *\n   * @default 10 MB\n   *\n   * @example 1    // 1MB for small images\n   * @example 25   // 25MB for documents\n   * @example 100  // 100MB for media files\n   */\n  maxSize?: number;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {\n  public readonly provider = this.$provider();\n  protected readonly fileSystem = $inject(FileSystemProvider);\n\n  public get name() {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  /**\n   * Uploads a file to the bucket.\n   */\n  public async upload(\n    file: FileLike,\n    options?: BucketFileOptions,\n  ): Promise<string> {\n    if (file instanceof File) {\n      // our createFile is smarter than the browser's File constructor\n      // by doing this, we can guess the MIME type and size!\n      file = this.fileSystem.createFile({ file });\n    }\n\n    options = {\n      ...this.options,\n      ...options,\n    };\n\n    const mimeTypes = options.mimeTypes ?? undefined;\n    const maxSize = options.maxSize ?? 10; // Default to 10 MB if not specified\n\n    if (mimeTypes) {\n      const mimeType = file.type || \"application/octet-stream\";\n      if (!mimeTypes.includes(mimeType)) {\n        throw new InvalidFileError(\n          `MIME type ${mimeType} is not allowed in bucket ${this.name}`,\n        );\n      }\n    }\n\n    // A reported size of 0 means the body is a one-shot stream — real streams\n    // report 0 until fully read (see FileLike.size). Materialize it once so\n    // that (a) the maxSize check below is accurate instead of being silently\n    // bypassed, and (b) the provider AND any `bucket:file:uploaded` hook can\n    // read the same bytes without draining the stream out from under each\n    // other. Files with a known size are already random-access (Blob/Buffer\n    // backed) and need no copy. Uploads are size-capped, so this is bounded.\n    if (file.size === 0) {\n      file = this.fileSystem.createFile({\n        arrayBuffer: await file.arrayBuffer(),\n        name: file.name,\n        type: file.type,\n      });\n    }\n\n    // check size in bytes, convert MB to bytes\n    if (file.size > maxSize * 1024 * 1024) {\n      throw new InvalidFileError(\n        `File size ${file.size} exceeds the maximum size of ${maxSize} MB in bucket ${this.name}`,\n      );\n    }\n\n    const id = await this.provider.upload(this.name, file);\n\n    await this.alepha.events.emit(\"bucket:file:uploaded\", {\n      id,\n      bucket: this,\n      file,\n      options,\n    });\n\n    return id;\n  }\n\n  /**\n   * Delete permanently a file from the bucket.\n   */\n  public async delete(fileId: string, skipHook = false): Promise<void> {\n    await this.provider.delete(this.name, fileId);\n\n    if (skipHook) {\n      return;\n    }\n\n    await this.alepha.events.emit(\"bucket:file:deleted\", {\n      id: fileId,\n      bucket: this,\n    });\n  }\n\n  /**\n   * Delete many files in one round-trip when the underlying provider supports\n   * batch (R2/S3 up to 1000 keys per call). Emits one `bucket:file:deleted`\n   * event per id unless `skipHook` is set.\n   */\n  public async deleteMany(fileIds: string[], skipHook = false): Promise<void> {\n    if (fileIds.length === 0) return;\n    await this.provider.deleteMany(this.name, fileIds);\n\n    if (skipHook) {\n      return;\n    }\n\n    for (const id of fileIds) {\n      await this.alepha.events.emit(\"bucket:file:deleted\", {\n        id,\n        bucket: this,\n      });\n    }\n  }\n\n  /**\n   * Checks if a file exists in the bucket.\n   */\n  public async exists(fileId: string): Promise<boolean> {\n    return this.provider.exists(this.name, fileId);\n  }\n\n  /**\n   * Lists the file identifiers stored in the bucket, like `ls` on a directory.\n   *\n   * This is a flat, unpaginated listing meant for small buckets — the result is\n   * capped at the provider's natural page size (~1000 for S3/R2) and anything\n   * beyond that is silently dropped. It is NOT a search API; reach for\n   * `alepha/api/files` when you need querying or pagination.\n   */\n  public async list(): Promise<string[]> {\n    return this.provider.list(this.name);\n  }\n\n  /**\n   * Downloads a file from the bucket.\n   */\n  public async download(fileId: string): Promise<FileLike> {\n    const file = await this.provider.download(this.name, fileId);\n\n    await this.alepha.events.emit(\"bucket:file:downloaded\", {\n      id: fileId,\n      bucket: this,\n      file,\n    });\n\n    return file;\n  }\n\n  protected $provider() {\n    if (!this.options.provider) {\n      return this.alepha.inject(FileStorageProvider);\n    }\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemoryFileStorageProvider);\n    }\n    return this.alepha.inject(this.options.provider);\n  }\n}\n\n$bucket[KIND] = BucketPrimitive;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BucketFileOptions {\n  /**\n   * Optional description of the bucket.\n   */\n  description?: string;\n\n  /**\n   * Allowed MIME types.\n   */\n  mimeTypes?: string[];\n\n  /**\n   * Maximum size of the files in the bucket.\n   *\n   * @default 10\n   */\n  maxSize?: number;\n}\n","import type * as fs from \"node:fs\";\nimport { createReadStream } from \"node:fs\";\nimport { mkdir, readdir, stat, unlink } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport {\n  $atom,\n  $hook,\n  $inject,\n  $state,\n  Alepha,\n  AlephaError,\n  type FileLike,\n  type Static,\n  t,\n} from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { $logger } from \"alepha/logger\";\nimport { FileDetector, FileSystemProvider } from \"alepha/system\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport { $bucket } from \"../primitives/$bucket.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Local file storage configuration atom\n */\nexport const localFileStorageOptions = $atom({\n  name: \"alepha.bucket.local.options\",\n  schema: t.object({\n    storagePath: t.string({\n      description: \"Directory path where files will be stored\",\n    }),\n  }),\n  default: {\n    storagePath: \"node_modules/.alepha/buckets\",\n  },\n});\n\nexport type LocalFileStorageProviderOptions = Static<\n  typeof localFileStorageOptions.schema\n>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [localFileStorageOptions.key]: LocalFileStorageProviderOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class LocalFileStorageProvider implements FileStorageProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly fileSystemProvider = $inject(FileSystemProvider);\n  protected readonly crypto = $inject(CryptoProvider);\n  protected readonly options = $state(localFileStorageOptions);\n\n  protected get storagePath(): string {\n    return this.options.storagePath;\n  }\n\n  protected readonly onConfigure = $hook({\n    on: \"configure\",\n    handler: async () => {\n      if (\n        this.alepha.isTest() &&\n        this.storagePath === localFileStorageOptions.options.default.storagePath\n      ) {\n        this.alepha.store.set(localFileStorageOptions, {\n          storagePath: join(tmpdir(), `alepha-test-${Date.now()}`),\n        });\n      }\n    },\n  });\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      try {\n        await mkdir(this.storagePath, { recursive: true });\n      } catch {}\n\n      for (const bucket of this.alepha.primitives($bucket)) {\n        if (bucket.provider !== this) {\n          continue;\n        }\n\n        await mkdir(join(this.storagePath, bucket.name), {\n          recursive: true,\n        });\n\n        this.log.debug(`Bucket '${bucket.name}' at ${this.storagePath} OK`);\n      }\n    },\n  });\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    fileId ??= this.createId(file.type);\n\n    this.log.trace(`Uploading file to ${bucketName}`);\n\n    await this.fileSystemProvider.writeFile(\n      this.path(bucketName, fileId),\n      file,\n    );\n\n    return fileId;\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    const filePath = this.path(bucketName, fileId);\n\n    try {\n      const stats = await stat(filePath);\n      const mimeType = this.fileDetector.getContentType(fileId);\n\n      return this.fileSystemProvider.createFile({\n        stream: createReadStream(filePath),\n        name: fileId,\n        type: mimeType,\n        size: stats.size,\n      });\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n      }\n      throw new AlephaError(\"Invalid file operation\", { cause: error });\n    }\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    try {\n      await stat(this.path(bucketName, fileId));\n      return true;\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        return false;\n      }\n      throw new AlephaError(\"Error checking file existence\", { cause: error });\n    }\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    try {\n      return await unlink(this.path(bucketName, fileId));\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        throw new FileNotFoundError(`File with ID ${fileId} not found.`);\n      }\n      throw new AlephaError(\"Error deleting file\", { cause: error });\n    }\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    await Promise.all(\n      fileIds.map((id) =>\n        unlink(this.path(bucketName, id)).catch((error) => {\n          if (this.isErrorNoEntry(error)) return;\n          throw new AlephaError(\"Error deleting file\", { cause: error });\n        }),\n      ),\n    );\n  }\n\n  public async list(bucketName: string): Promise<string[]> {\n    try {\n      const entries = await readdir(this.path(bucketName), {\n        withFileTypes: true,\n      });\n      return entries\n        .filter((entry) => entry.isFile())\n        .map((entry) => entry.name);\n    } catch (error) {\n      if (this.isErrorNoEntry(error)) {\n        return [];\n      }\n      throw new AlephaError(\"Error listing files\", { cause: error });\n    }\n  }\n\n  protected stat(bucket: string, fileId: string): Promise<fs.Stats> {\n    return stat(this.path(bucket, fileId));\n  }\n\n  protected createId(mimeType: string): string {\n    const ext = this.fileDetector.getExtensionFromMimeType(mimeType);\n    return `${this.crypto.randomUUID()}.${ext}`;\n  }\n\n  protected path(bucket: string, fileId = \"\"): string {\n    return join(this.storagePath, bucket, fileId);\n  }\n\n  protected isErrorNoEntry(error: unknown): boolean {\n    return error instanceof Error && \"code\" in error && error.code === \"ENOENT\";\n  }\n}\n","import { Buffer } from \"node:buffer\";\nimport { Readable } from \"node:stream\";\nimport type { ReadableStream as NodeWebStream } from \"node:stream/web\";\nimport {\n  $env,\n  $hook,\n  $inject,\n  Alepha,\n  AlephaError,\n  type FileLike,\n  type Static,\n  t,\n} from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { $logger } from \"alepha/logger\";\nimport { FileDetector, FileSystemProvider } from \"alepha/system\";\nimport { S3mini } from \"s3mini\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport { $bucket } from \"../primitives/$bucket.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\nconst envSchema = t.object({\n  /**\n   * S3 endpoint URL. The bucket name is appended (path-style) per request.\n   *\n   * Examples:\n   * - AWS S3: `https://s3.us-east-1.amazonaws.com`\n   * - Cloudflare R2: `https://<account-id>.r2.cloudflarestorage.com`\n   * - MinIO: `http://localhost:9000`\n   * - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`\n   */\n  S3_ENDPOINT: t.string(),\n\n  /**\n   * AWS region or \"auto\" for R2.\n   *\n   * @default \"auto\"\n   */\n  S3_REGION: t.optional(t.string()),\n\n  /**\n   * Access key ID for S3 authentication.\n   */\n  S3_ACCESS_KEY_ID: t.string(),\n\n  /**\n   * Secret access key for S3 authentication.\n   */\n  S3_SECRET_ACCESS_KEY: t.string(),\n});\n\ndeclare module \"alepha\" {\n  interface Env extends Partial<Static<typeof envSchema>> {}\n}\n\n/**\n * S3-compatible file storage provider for Node.js.\n *\n * Backed by `s3mini` (zero-dep, ~20 KB). Works with AWS S3, Cloudflare R2,\n * MinIO, DigitalOcean Spaces, Backblaze B2, and any other S3-compatible service.\n *\n * Uses path-style addressing (`<endpoint>/<bucket>`).\n */\nexport class S3FileStorageProvider implements FileStorageProvider {\n  protected readonly log = $logger();\n  protected readonly env = $env(envSchema);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly fileSystem = $inject(FileSystemProvider);\n  protected readonly fileDetector = $inject(FileDetector);\n  protected readonly crypto = $inject(CryptoProvider);\n  protected readonly clients: Map<string, S3mini> = new Map();\n\n  /**\n   * Convert bucket name to S3-compatible format.\n   * S3 bucket names must be lowercase, 3-63 characters, no underscores.\n   */\n  public convertName(name: string): string {\n    return name.replaceAll(\"/\", \"-\").replaceAll(\"_\", \"-\").toLowerCase();\n  }\n\n  protected getClient(bucketName: string): S3mini {\n    const name = this.convertName(bucketName);\n    let client = this.clients.get(name);\n    if (!client) {\n      const endpoint = this.env.S3_ENDPOINT.replace(/\\/+$/, \"\");\n      client = new S3mini({\n        accessKeyId: this.env.S3_ACCESS_KEY_ID,\n        secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,\n        region: this.env.S3_REGION || \"auto\",\n        endpoint: `${endpoint}/${name}`,\n      });\n      this.clients.set(name, client);\n    }\n    return client;\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      for (const bucket of this.alepha.primitives($bucket)) {\n        if (bucket.provider !== this) {\n          continue;\n        }\n\n        const name = this.convertName(bucket.name);\n        const client = this.getClient(bucket.name);\n\n        this.log.debug(`Preparing S3 bucket '${name}'...`);\n\n        const exists = await client.bucketExists();\n        if (!exists) {\n          this.log.debug(`Creating S3 bucket '${name}'...`);\n          const created = await client.createBucket();\n          if (!created) {\n            throw new AlephaError(`Failed to create S3 bucket '${name}'`);\n          }\n        }\n\n        this.log.info(`S3 bucket '${bucket.name}' OK`);\n      }\n    },\n  });\n\n  protected createId(mimeType: string): string {\n    const ext = this.fileDetector.getExtensionFromMimeType(mimeType);\n    return `${this.crypto.randomUUID()}.${ext}`;\n  }\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    fileId ??= this.createId(file.type);\n\n    this.log.trace(\n      `Uploading file '${file.name}' to bucket '${bucketName}' with id '${fileId}'...`,\n    );\n\n    const client = this.getClient(bucketName);\n\n    try {\n      const buffer = new Uint8Array(await file.arrayBuffer());\n      await client.putObject(\n        fileId,\n        buffer,\n        file.type || \"application/octet-stream\",\n        undefined,\n        { \"x-amz-meta-name\": encodeURIComponent(file.name) },\n        file.size,\n      );\n\n      this.log.trace(`File uploaded successfully: ${fileId}`);\n      return fileId;\n    } catch (error) {\n      this.log.error(`Failed to upload file: ${error}`);\n      if (error instanceof Error) {\n        throw new AlephaError(`Upload failed: ${error.message}`, {\n          cause: error,\n        });\n      }\n      throw error;\n    }\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    this.log.trace(\n      `Downloading file '${fileId}' from bucket '${bucketName}'...`,\n    );\n\n    const client = this.getClient(bucketName);\n    const response = await client.getObjectResponse(fileId);\n\n    if (!response) {\n      throw new FileNotFoundError(\n        `File '${fileId}' not found in bucket '${bucketName}'`,\n      );\n    }\n\n    const mimeType =\n      response.headers.get(\"content-type\") ||\n      this.fileDetector.getContentType(fileId);\n\n    const metaName = response.headers.get(\"x-amz-meta-name\");\n    const name = metaName ? decodeURIComponent(metaName) : fileId;\n\n    const contentLength = response.headers.get(\"content-length\");\n    const size = contentLength ? Number.parseInt(contentLength, 10) : 0;\n\n    // Stream the body straight through instead of buffering the whole object\n    // into memory. `response.body` is null only for a zero-byte object.\n    if (!response.body) {\n      return this.fileSystem.createFile({\n        buffer: Buffer.alloc(0),\n        name,\n        type: mimeType,\n      });\n    }\n\n    return this.fileSystem.createFile({\n      stream: Readable.fromWeb(response.body as unknown as NodeWebStream),\n      name,\n      type: mimeType,\n      size,\n    });\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    this.log.trace(\n      `Checking existence of file '${fileId}' in bucket '${bucketName}'...`,\n    );\n\n    const client = this.getClient(bucketName);\n    const result = await client.objectExists(fileId);\n    return result === true;\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    this.log.trace(`Deleting file '${fileId}' from bucket '${bucketName}'...`);\n\n    const client = this.getClient(bucketName);\n\n    try {\n      await client.deleteObject(fileId);\n    } catch (error) {\n      this.log.error(`Failed to delete file: ${error}`);\n      if (error instanceof Error) {\n        throw new FileNotFoundError(\"Error deleting file\", { cause: error });\n      }\n      throw error;\n    }\n  }\n\n  public async list(bucketName: string): Promise<string[]> {\n    this.log.trace(`Listing files in bucket '${bucketName}'...`);\n    const client = this.getClient(bucketName);\n    // Flat, single-page listing (~1000 keys). Not a search API.\n    const objects = await client.listObjects();\n    if (!objects) return [];\n    return objects.map((object) => object.Key);\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    if (fileIds.length === 0) return;\n    this.log.trace(\n      `Deleting ${fileIds.length} files from bucket '${bucketName}'...`,\n    );\n    const client = this.getClient(bucketName);\n    // S3 DeleteObjects caps at 1000 keys per request.\n    for (let i = 0; i < fileIds.length; i += 1000) {\n      const chunk = fileIds.slice(i, i + 1000);\n      try {\n        // bun:s3 client exposes a per-key deleteObject; some SDKs also expose\n        // deleteObjects(keys: string[]). Prefer batch when available.\n        const batch = (\n          client as unknown as {\n            deleteObjects?: (keys: string[]) => Promise<unknown>;\n          }\n        ).deleteObjects;\n        if (typeof batch === \"function\") {\n          await batch.call(client, chunk);\n        } else {\n          await Promise.all(chunk.map((id) => client.deleteObject(id)));\n        }\n      } catch (error) {\n        this.log.error(`Failed to delete files: ${error}`);\n        if (error instanceof Error) {\n          throw new FileNotFoundError(\"Error deleting files\", { cause: error });\n        }\n        throw error;\n      }\n    }\n  }\n}\n","import type { R2Bucket } from \"@cloudflare/workers-types\";\nimport {\n  $env,\n  $hook,\n  $inject,\n  Alepha,\n  AlephaError,\n  type FileLike,\n  t,\n} from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { $logger } from \"alepha/logger\";\nimport { FileNotFoundError } from \"../errors/FileNotFoundError.ts\";\nimport { $bucket } from \"../primitives/$bucket.ts\";\nimport type { FileStorageProvider } from \"./FileStorageProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Cloudflare R2 storage provider.\n *\n * Uses a single R2 bucket binding for all $bucket primitives.\n * Files are organized as: {APP_NAME}/{bucketName}/{fileId}\n *\n * **Required environment variables:**\n * - `R2_BUCKET_NAME` - The actual R2 bucket name in Cloudflare\n *\n * **Optional (uses core Alepha env):**\n * - `APP_NAME` - Prefix for all files (for multi-app setups sharing one R2 bucket)\n *\n * @example\n * ```bash\n * # .env\n * APP_NAME=myapp        # optional, used as prefix\n * R2_BUCKET_NAME=storage\n * ```\n *\n * @example\n * ```toml\n * # wrangler.toml - automatically generated by alepha build\n * [[r2_buckets]]\n * binding = \"R2\"\n * bucket_name = \"storage\"\n * ```\n *\n * @example\n * ```ts\n * // Define buckets with validation rules\n * const avatars = $bucket({\n *   name: \"avatars\",\n *   maxFileSize: 5 * 1024 * 1024,\n *   allowedMimeTypes: [\"image/*\"],\n * });\n *\n * const documents = $bucket({\n *   name: \"documents\",\n *   maxFileSize: 50 * 1024 * 1024,\n *   allowedMimeTypes: [\"application/pdf\"],\n * });\n *\n * // Files stored at: myapp/avatars/uuid.png, myapp/documents/uuid.pdf\n * ```\n */\nexport class R2FileStorageProvider implements FileStorageProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n  protected readonly crypto = $inject(CryptoProvider);\n  protected readonly env = $env(\n    t.object({\n      /**\n       * The actual R2 bucket name in Cloudflare.\n       */\n      R2_BUCKET_NAME: t.string({\n        description: \"R2 bucket name in Cloudflare\",\n      }),\n    }),\n  );\n\n  protected r2?: R2Bucket;\n\n  /**\n   * Get the R2 bucket name from environment.\n   */\n  public get bucketName(): string {\n    return this.env.R2_BUCKET_NAME;\n  }\n\n  /**\n   * Get the optional prefix from APP_NAME environment variable.\n   * Used for multi-app setups sharing the same R2 bucket.\n   */\n  public get prefix(): string | undefined {\n    return this.alepha.env.APP_NAME;\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      const cloudflareEnv = this.alepha.get(\"cloudflare.env\") as\n        | Record<string, unknown>\n        | undefined;\n      if (!cloudflareEnv) {\n        throw new AlephaError(\n          \"Cloudflare Workers environment not found in Alepha store under 'cloudflare.env'.\",\n        );\n      }\n\n      const binding = cloudflareEnv[this.bucketName] as R2Bucket | undefined;\n      if (!binding) {\n        throw new AlephaError(\n          `R2 binding '${this.bucketName}' not found in Cloudflare Workers environment.`,\n        );\n      }\n\n      this.r2 = binding;\n\n      const prefixStr = this.prefix ? `${this.prefix}/` : \"\";\n      this.log.info(\n        `R2 storage ready (bucket: ${this.bucketName}, prefix: ${prefixStr || \"(none)\"})`,\n      );\n\n      for (const bucket of this.alepha.primitives($bucket)) {\n        if (bucket.provider !== this) {\n          continue;\n        }\n        this.log.debug(\n          `Bucket '${bucket.name}' -> ${prefixStr}${bucket.name}/`,\n        );\n      }\n    },\n  });\n\n  public async upload(\n    bucketName: string,\n    file: FileLike,\n    fileId?: string,\n  ): Promise<string> {\n    const r2 = this.getR2();\n    fileId ??= this.createId(file.name);\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Uploading '${key}'`);\n\n    const arrayBuffer = await file.arrayBuffer();\n\n    await r2.put(key, arrayBuffer, {\n      httpMetadata: {\n        contentType: file.type,\n      },\n      customMetadata: {\n        originalName: file.name,\n        bucket: bucketName,\n      },\n    });\n\n    return fileId;\n  }\n\n  public async download(bucketName: string, fileId: string): Promise<FileLike> {\n    const r2 = this.getR2();\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Downloading '${key}'`);\n\n    const object = await r2.get(key);\n    if (!object) {\n      throw new FileNotFoundError(\n        `File '${fileId}' not found in bucket '${bucketName}'.`,\n      );\n    }\n\n    const originalName = object.customMetadata?.originalName ?? fileId;\n    const contentType =\n      object.httpMetadata?.contentType ?? \"application/octet-stream\";\n\n    return {\n      name: originalName,\n      type: contentType,\n      size: object.size,\n      lastModified: object.uploaded.getTime(),\n      stream: () => object.body as unknown as ReadableStream,\n      arrayBuffer: () => object.arrayBuffer(),\n      text: () => object.text(),\n    };\n  }\n\n  public async exists(bucketName: string, fileId: string): Promise<boolean> {\n    const r2 = this.getR2();\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Checking '${key}'`);\n\n    const object = await r2.head(key);\n    return object !== null;\n  }\n\n  public async delete(bucketName: string, fileId: string): Promise<void> {\n    const r2 = this.getR2();\n    const key = this.key(bucketName, fileId);\n\n    this.log.trace(`Deleting '${key}'`);\n\n    // R2's delete doesn't throw if the file doesn't exist,\n    // so we check existence first for consistency with other providers\n    const exists = await this.exists(bucketName, fileId);\n    if (!exists) {\n      throw new FileNotFoundError(\n        `File '${fileId}' not found in bucket '${bucketName}'.`,\n      );\n    }\n\n    await r2.delete(key);\n  }\n\n  public async deleteMany(\n    bucketName: string,\n    fileIds: string[],\n  ): Promise<void> {\n    if (fileIds.length === 0) return;\n    const r2 = this.getR2();\n    const keys = fileIds.map((id) => this.key(bucketName, id));\n    this.log.trace(`Deleting ${keys.length} keys from '${bucketName}'`);\n    // R2 binding accepts a string[] and silently ignores missing keys.\n    // Chunk at 1000 to stay within the documented batch limit.\n    for (let i = 0; i < keys.length; i += 1000) {\n      await r2.delete(keys.slice(i, i + 1000));\n    }\n  }\n\n  public async list(bucketName: string): Promise<string[]> {\n    const r2 = this.getR2();\n    const keyPrefix = this.key(bucketName, \"\");\n    this.log.trace(`Listing files in '${keyPrefix}'`);\n    // Flat, single-page listing (~1000 keys). Not a search API.\n    const listed = await r2.list({ prefix: keyPrefix });\n    return listed.objects.map((object) => object.key.slice(keyPrefix.length));\n  }\n\n  /**\n   * Build the full R2 key: {prefix}/{bucketName}/{fileId}\n   */\n  protected key(bucketName: string, fileId: string): string {\n    const parts = [bucketName, fileId];\n    if (this.prefix) {\n      parts.unshift(this.prefix);\n    }\n    return parts.join(\"/\");\n  }\n\n  protected getR2(): R2Bucket {\n    if (!this.r2) {\n      throw new AlephaError(\"R2 storage not initialized. Call start() first.\");\n    }\n    return this.r2;\n  }\n\n  protected createId(filename: string): string {\n    const ext = filename.includes(\".\") ? filename.split(\".\").pop() : \"\";\n    const id = this.crypto.randomUUID();\n    return ext ? `${id}.${ext}` : id;\n  }\n}\n","import { $module, type FileLike } from \"alepha\";\nimport {\n  $bucket,\n  type BucketFileOptions,\n  type BucketPrimitive,\n} from \"./primitives/$bucket.ts\";\nimport { FileStorageProvider } from \"./providers/FileStorageProvider.ts\";\nimport { LocalFileStorageProvider } from \"./providers/LocalFileStorageProvider.ts\";\nimport { MemoryFileStorageProvider } from \"./providers/MemoryFileStorageProvider.ts\";\nimport { S3FileStorageProvider } from \"./providers/S3FileStorageProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./errors/FileNotFoundError.ts\";\nexport * from \"./primitives/$bucket.ts\";\nexport * from \"./providers/FileStorageProvider.ts\";\nexport * from \"./providers/LocalFileStorageProvider.ts\";\nexport * from \"./providers/MemoryFileStorageProvider.ts\";\nexport * from \"./providers/R2FileStorageProvider.ts\";\nexport * from \"./providers/S3FileStorageProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha\" {\n  interface Hooks {\n    /**\n     * Triggered when a file is uploaded to a bucket.\n     * Can be used to perform actions after a file is uploaded, like creating a database record!\n     */\n    \"bucket:file:uploaded\": {\n      id: string;\n      file: FileLike;\n      bucket: BucketPrimitive;\n      options: BucketFileOptions;\n    };\n    /**\n     * Triggered when a file is deleted from a bucket.\n     */\n    \"bucket:file:deleted\": {\n      id: string;\n      bucket: BucketPrimitive;\n    };\n    /**\n     * Triggered when a file is downloaded from a bucket.\n     */\n    \"bucket:file:downloaded\": {\n      id: string;\n      file: FileLike;\n      bucket: BucketPrimitive;\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Unified file storage abstraction across multiple backends.\n *\n * **Features:**\n * - File storage buckets with constraints\n * - Unified API across all storage backends\n * - MIME type validation\n * - File size limits\n * - Upload/download/delete operations\n * - TTL-based file expiration\n * - Providers: Memory (testing), Local filesystem, AWS S3 / Cloudflare R2 / MinIO, Azure Blob Storage, Vercel Blob\n *\n * @module alepha.bucket\n */\nexport const AlephaBucket = $module({\n  name: \"alepha.bucket\",\n  primitives: [$bucket],\n  services: [FileStorageProvider],\n  variants: [\n    MemoryFileStorageProvider,\n    LocalFileStorageProvider,\n    S3FileStorageProvider,\n  ],\n  register: (alepha) => {\n    const useS3 = !!alepha.env.S3_ENDPOINT;\n    alepha.with({\n      optional: true,\n      provide: FileStorageProvider,\n      use:\n        alepha.isTest() || alepha.isServerless()\n          ? MemoryFileStorageProvider\n          : useS3\n            ? S3FileStorageProvider\n            : LocalFileStorageProvider,\n    });\n  },\n});\n"],"mappings":"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"}

package/dist/bucket/index.workerd.js

@@ -2,6 +2,9 @@ import { $env, $hook, $inject, $module, Alepha, AlephaError, KIND, Primitive, cr
 import { FileDetector, FileSystemProvider } from "alepha/system";
 import { CryptoProvider } from "alepha/crypto";
 import { $logger } from "alepha/logger";
+import { Buffer as Buffer$1 } from "node:buffer";
+import { Readable } from "node:stream";
+import { S3mini } from "s3mini";
 //#region ../../src/bucket/errors/InvalidFileError.ts
 var InvalidFileError = class extends AlephaError {
 	status = 400;
@@ -56,6 +59,10 @@ var MemoryFileStorageProvider = class {
 	async deleteMany(bucketName, fileIds) {
 		for (const id of fileIds) delete this.files[`${bucketName}/${id}`];
 	}
+	async list(bucketName) {
+		const prefix = `${bucketName}/`;
+		return Object.keys(this.files).filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+	}
 	createId() {
 		return this.crypto.randomUUID();
 	}
@@ -133,6 +140,11 @@ var BucketPrimitive = class extends Primitive {
 			const mimeType = file.type || "application/octet-stream";
 			if (!mimeTypes.includes(mimeType)) throw new InvalidFileError(`MIME type ${mimeType} is not allowed in bucket ${this.name}`);
 		}
+		if (file.size === 0) file = this.fileSystem.createFile({
+			arrayBuffer: await file.arrayBuffer(),
+			name: file.name,
+			type: file.type
+		});
 		if (file.size > maxSize * 1024 * 1024) throw new InvalidFileError(`File size ${file.size} exceeds the maximum size of ${maxSize} MB in bucket ${this.name}`);
 		const id = await this.provider.upload(this.name, file);
 		await this.alepha.events.emit("bucket:file:uploaded", {
@@ -175,6 +187,17 @@ var BucketPrimitive = class extends Primitive {
 		return this.provider.exists(this.name, fileId);
 	}
 	/**
+	* Lists the file identifiers stored in the bucket, like `ls` on a directory.
+	*
+	* This is a flat, unpaginated listing meant for small buckets — the result is
+	* capped at the provider's natural page size (~1000 for S3/R2) and anything
+	* beyond that is silently dropped. It is NOT a search API; reach for
+	* `alepha/api/files` when you need querying or pagination.
+	*/
+	async list() {
+		return this.provider.list(this.name);
+	}
+	/**
 	* Downloads a file from the bucket.
 	*/
 	async download(fileId) {
@@ -194,7 +217,7 @@ var BucketPrimitive = class extends Primitive {
 };
 $bucket[KIND] = BucketPrimitive;
 //#endregion
-//#region ../../src/bucket/providers/CloudflareR2Provider.ts
+//#region ../../src/bucket/providers/R2FileStorageProvider.ts
 /**
 * Cloudflare R2 storage provider.
 *
@@ -240,7 +263,7 @@ $bucket[KIND] = BucketPrimitive;
 * // Files stored at: myapp/avatars/uuid.png, myapp/documents/uuid.pdf
 * ```
 */
-var CloudflareR2Provider = class {
+var R2FileStorageProvider = class {
 	alepha = $inject(Alepha);
 	log = $logger();
 	crypto = $inject(CryptoProvider);
@@ -330,6 +353,12 @@ R2_BUCKET_NAME: t.string({ description: "R2 bucket name in Cloudflare" }) }));
 		this.log.trace(`Deleting ${keys.length} keys from '${bucketName}'`);
 		for (let i = 0; i < keys.length; i += 1e3) await r2.delete(keys.slice(i, i + 1e3));
 	}
+	async list(bucketName) {
+		const r2 = this.getR2();
+		const keyPrefix = this.key(bucketName, "");
+		this.log.trace(`Listing files in '${keyPrefix}'`);
+		return (await r2.list({ prefix: keyPrefix })).objects.map((object) => object.key.slice(keyPrefix.length));
+	}
 	/**
 	* Build the full R2 key: {prefix}/{bucketName}/{fileId}
 	*/
@@ -349,6 +378,167 @@ R2_BUCKET_NAME: t.string({ description: "R2 bucket name in Cloudflare" }) }));
 	}
 };
 //#endregion
+//#region ../../src/bucket/providers/S3FileStorageProvider.ts
+const envSchema = t.object({
+	/**
+	* S3 endpoint URL. The bucket name is appended (path-style) per request.
+	*
+	* Examples:
+	* - AWS S3: `https://s3.us-east-1.amazonaws.com`
+	* - Cloudflare R2: `https://<account-id>.r2.cloudflarestorage.com`
+	* - MinIO: `http://localhost:9000`
+	* - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`
+	*/
+	S3_ENDPOINT: t.string(),
+	/**
+	* AWS region or "auto" for R2.
+	*
+	* @default "auto"
+	*/
+	S3_REGION: t.optional(t.string()),
+	/**
+	* Access key ID for S3 authentication.
+	*/
+	S3_ACCESS_KEY_ID: t.string(),
+	/**
+	* Secret access key for S3 authentication.
+	*/
+	S3_SECRET_ACCESS_KEY: t.string()
+});
+/**
+* S3-compatible file storage provider for Node.js.
+*
+* Backed by `s3mini` (zero-dep, ~20 KB). Works with AWS S3, Cloudflare R2,
+* MinIO, DigitalOcean Spaces, Backblaze B2, and any other S3-compatible service.
+*
+* Uses path-style addressing (`<endpoint>/<bucket>`).
+*/
+var S3FileStorageProvider = class {
+	log = $logger();
+	env = $env(envSchema);
+	alepha = $inject(Alepha);
+	fileSystem = $inject(FileSystemProvider);
+	fileDetector = $inject(FileDetector);
+	crypto = $inject(CryptoProvider);
+	clients = /* @__PURE__ */ new Map();
+	/**
+	* Convert bucket name to S3-compatible format.
+	* S3 bucket names must be lowercase, 3-63 characters, no underscores.
+	*/
+	convertName(name) {
+		return name.replaceAll("/", "-").replaceAll("_", "-").toLowerCase();
+	}
+	getClient(bucketName) {
+		const name = this.convertName(bucketName);
+		let client = this.clients.get(name);
+		if (!client) {
+			const endpoint = this.env.S3_ENDPOINT.replace(/\/+$/, "");
+			client = new S3mini({
+				accessKeyId: this.env.S3_ACCESS_KEY_ID,
+				secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,
+				region: this.env.S3_REGION || "auto",
+				endpoint: `${endpoint}/${name}`
+			});
+			this.clients.set(name, client);
+		}
+		return client;
+	}
+	onStart = $hook({
+		on: "start",
+		handler: async () => {
+			for (const bucket of this.alepha.primitives($bucket)) {
+				if (bucket.provider !== this) continue;
+				const name = this.convertName(bucket.name);
+				const client = this.getClient(bucket.name);
+				this.log.debug(`Preparing S3 bucket '${name}'...`);
+				if (!await client.bucketExists()) {
+					this.log.debug(`Creating S3 bucket '${name}'...`);
+					if (!await client.createBucket()) throw new AlephaError(`Failed to create S3 bucket '${name}'`);
+				}
+				this.log.info(`S3 bucket '${bucket.name}' OK`);
+			}
+		}
+	});
+	createId(mimeType) {
+		const ext = this.fileDetector.getExtensionFromMimeType(mimeType);
+		return `${this.crypto.randomUUID()}.${ext}`;
+	}
+	async upload(bucketName, file, fileId) {
+		fileId ??= this.createId(file.type);
+		this.log.trace(`Uploading file '${file.name}' to bucket '${bucketName}' with id '${fileId}'...`);
+		const client = this.getClient(bucketName);
+		try {
+			const buffer = new Uint8Array(await file.arrayBuffer());
+			await client.putObject(fileId, buffer, file.type || "application/octet-stream", void 0, { "x-amz-meta-name": encodeURIComponent(file.name) }, file.size);
+			this.log.trace(`File uploaded successfully: ${fileId}`);
+			return fileId;
+		} catch (error) {
+			this.log.error(`Failed to upload file: ${error}`);
+			if (error instanceof Error) throw new AlephaError(`Upload failed: ${error.message}`, { cause: error });
+			throw error;
+		}
+	}
+	async download(bucketName, fileId) {
+		this.log.trace(`Downloading file '${fileId}' from bucket '${bucketName}'...`);
+		const response = await this.getClient(bucketName).getObjectResponse(fileId);
+		if (!response) throw new FileNotFoundError(`File '${fileId}' not found in bucket '${bucketName}'`);
+		const mimeType = response.headers.get("content-type") || this.fileDetector.getContentType(fileId);
+		const metaName = response.headers.get("x-amz-meta-name");
+		const name = metaName ? decodeURIComponent(metaName) : fileId;
+		const contentLength = response.headers.get("content-length");
+		const size = contentLength ? Number.parseInt(contentLength, 10) : 0;
+		if (!response.body) return this.fileSystem.createFile({
+			buffer: Buffer$1.alloc(0),
+			name,
+			type: mimeType
+		});
+		return this.fileSystem.createFile({
+			stream: Readable.fromWeb(response.body),
+			name,
+			type: mimeType,
+			size
+		});
+	}
+	async exists(bucketName, fileId) {
+		this.log.trace(`Checking existence of file '${fileId}' in bucket '${bucketName}'...`);
+		return await this.getClient(bucketName).objectExists(fileId) === true;
+	}
+	async delete(bucketName, fileId) {
+		this.log.trace(`Deleting file '${fileId}' from bucket '${bucketName}'...`);
+		const client = this.getClient(bucketName);
+		try {
+			await client.deleteObject(fileId);
+		} catch (error) {
+			this.log.error(`Failed to delete file: ${error}`);
+			if (error instanceof Error) throw new FileNotFoundError("Error deleting file", { cause: error });
+			throw error;
+		}
+	}
+	async list(bucketName) {
+		this.log.trace(`Listing files in bucket '${bucketName}'...`);
+		const objects = await this.getClient(bucketName).listObjects();
+		if (!objects) return [];
+		return objects.map((object) => object.Key);
+	}
+	async deleteMany(bucketName, fileIds) {
+		if (fileIds.length === 0) return;
+		this.log.trace(`Deleting ${fileIds.length} files from bucket '${bucketName}'...`);
+		const client = this.getClient(bucketName);
+		for (let i = 0; i < fileIds.length; i += 1e3) {
+			const chunk = fileIds.slice(i, i + 1e3);
+			try {
+				const batch = client.deleteObjects;
+				if (typeof batch === "function") await batch.call(client, chunk);
+				else await Promise.all(chunk.map((id) => client.deleteObject(id)));
+			} catch (error) {
+				this.log.error(`Failed to delete files: ${error}`);
+				if (error instanceof Error) throw new FileNotFoundError("Error deleting files", { cause: error });
+				throw error;
+			}
+		}
+	}
+};
+//#endregion
 //#region ../../src/bucket/index.workerd.ts
 const AlephaBucket = $module({
 	name: "alepha.bucket",
@@ -356,17 +546,22 @@ const AlephaBucket = $module({
 	services: [
 		FileStorageProvider,
 		MemoryFileStorageProvider,
-		CloudflareR2Provider
+		R2FileStorageProvider
+	],
+	variants: [
+		MemoryFileStorageProvider,
+		R2FileStorageProvider,
+		S3FileStorageProvider
 	],
 	register: (alepha) => {
 		alepha.with({
 			optional: true,
 			provide: FileStorageProvider,
-			use: alepha.isTest() ? MemoryFileStorageProvider : CloudflareR2Provider
+			use: alepha.isTest() ? MemoryFileStorageProvider : R2FileStorageProvider
 		});
 	}
 });
 //#endregion
-export { $bucket, AlephaBucket, BucketPrimitive, CloudflareR2Provider, FileNotFoundError, FileStorageProvider, MemoryFileStorageProvider };
+export { $bucket, AlephaBucket, BucketPrimitive, FileNotFoundError, FileStorageProvider, MemoryFileStorageProvider, R2FileStorageProvider, S3FileStorageProvider };
 
 //# sourceMappingURL=index.workerd.js.map