alepha/bucket.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core1 from "alepha";
import * as _alepha_core0 from "alepha";
import { Alepha, Descriptor, FileLike, KIND, Service } from "alepha";
import * as fs from "node:fs";
import * as _sinclair_typebox0 from "@sinclair/typebox";

//#region src/providers/FileStorageProvider.d.ts
declare abstract class FileStorageProvider {
  /**
   * Uploads a file to the storage.
   *
   * @param bucketName - Container name
   * @param file - File to upload
   * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.
   * @return The identifier of the uploaded file.
   */
  abstract upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
  /**
   * Downloads a file from the storage.
   *
   * @param bucketName - Container name
   * @param fileId - Identifier of the file to download
   * @return The downloaded file as a FileLike object.
   */
  abstract download(bucketName: string, fileId: string): Promise<FileLike>;
  /**
   * Check if fileId exists in the storage bucket.
   *
   * @param bucketName - Container name
   * @param fileId - Identifier of the file to stream
   * @return True is the file exists, false otherwise.
   */
  abstract exists(bucketName: string, fileId: string): Promise<boolean>;
  /**
   * Delete permanently a file from the storage.
   *
   * @param bucketName - Container name
   * @param fileId - Identifier of the file to delete
   */
  abstract delete(bucketName: string, fileId: string): Promise<void>;
}
//# sourceMappingURL=FileStorageProvider.d.ts.map
//#endregion
//#region src/providers/MemoryFileStorageProvider.d.ts
declare class MemoryFileStorageProvider implements FileStorageProvider {
  readonly files: Record<string, FileLike>;
  upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
  download(bucketName: string, fileId: string): Promise<FileLike>;
  exists(bucketName: string, fileId: string): Promise<boolean>;
  delete(bucketName: string, fileId: string): Promise<void>;
  protected createId(): string;
}
//# sourceMappingURL=MemoryFileStorageProvider.d.ts.map

//#endregion
//#region src/descriptors/$bucket.d.ts
/**
 * Create a container for storing files.
 *
 * @example
 * ```ts
 * import { $bucket } from "alepha/bucket";
 *
 * class App {
 *   images = $bucket();
 *
 *   uploadImage(file: FileLike): Promise<string> {
 *     return this.images.upload(file);
 *   }
 * }
 * ```
 */
declare const $bucket: {
  (options: BucketDescriptorOptions): BucketDescriptor;
  [KIND]: typeof BucketDescriptor;
};
interface BucketDescriptorOptions extends BucketFileOptions {
  /**
   * File storage provider. If not provided, the default provider will be used.
   */
  provider?: Service<FileStorageProvider> | "memory";
  /**
   * Optional name of the bucket. If not provided, the key of the descriptor will be used.
   */
  name?: string;
}
declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
  readonly provider: MemoryFileStorageProvider | FileStorageProvider;
  get name(): string;
  /**
   * Uploads a file to the bucket.
   */
  upload(file: FileLike, options?: BucketFileOptions): Promise<string>;
  /**
   * Delete permanently a file from the bucket.
   */
  delete(fileId: string): Promise<void>;
  /**
   * Checks if a file exists in the bucket.
   */
  exists(fileId: string): Promise<boolean>;
  /**
   * Downloads a file from the bucket.
   */
  download(fileId: string): Promise<FileLike>;
  protected $provider(): MemoryFileStorageProvider | FileStorageProvider;
}
interface BucketFileOptions {
  /**
   * Optional description of the bucket.
   */
  description?: string;
  /**
   * Allowed MIME types.
   */
  mimeTypes?: string[];
  /**
   * Maximum size of the files in the bucket.
   *
   * @default 10
   */
  maxSize?: number;
}
//# sourceMappingURL=$bucket.d.ts.map
//#endregion
//#region src/errors/FileNotFoundError.d.ts
declare class FileNotFoundError extends Error {
  readonly status = 404;
}
//# sourceMappingURL=FileNotFoundError.d.ts.map
//#endregion
//#region src/providers/LocalFileStorageProvider.d.ts
declare class LocalFileStorageProvider implements FileStorageProvider {
  static METADATA_HEADER_LENGTH: number;
  protected readonly alepha: Alepha;
  options: {
    storagePath: string;
  };
  protected readonly configure: _alepha_core1.HookDescriptor<"start">;
  upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
  download(bucketName: string, fileId: string): Promise<FileLike>;
  exists(bucketName: string, fileId: string): Promise<boolean>;
  delete(bucketName: string, fileId: string): Promise<void>;
  protected stat(container: string, fileId: string): Promise<fs.Stats>;
  protected createId(): string;
  protected path(container: string, fileId?: string): string;
  protected isErrorNoEntry(error: unknown): boolean;
}
declare const fileMetadataSchema: _sinclair_typebox0.TObject<{
  name: _sinclair_typebox0.TString;
  type: _sinclair_typebox0.TString;
  size: _sinclair_typebox0.TNumber;
}>;
//# sourceMappingURL=LocalFileStorageProvider.d.ts.map
//#endregion
//#region src/index.d.ts
declare module "alepha" {
  interface Hooks {
    /**
     * Triggered when a file is uploaded to a bucket.
     * Can be used to perform actions after a file is uploaded, like creating a database record!
     */
    "bucket:file:uploaded": {
      id: string;
      file: FileLike;
      bucket: BucketDescriptor;
      options: BucketFileOptions;
    };
    /**
     * Triggered when a file is deleted from a bucket.
     */
    "bucket:file:deleted": {
      id: string;
      bucket: BucketDescriptor;
    };
  }
}
/**
 * Provides file storage capabilities through declarative bucket descriptors with support for multiple storage backends.
 *
 * The bucket module enables unified file operations across different storage systems using the `$bucket` descriptor
 * on class properties. It abstracts storage provider differences, offering consistent APIs for local filesystem,
 * cloud storage, or in-memory storage for testing environments.
 *
 * @see {@link $bucket}
 * @see {@link FileStorageProvider}
 * @module alepha.bucket
 */
declare const AlephaBucket: _alepha_core0.Service<_alepha_core0.Module>;
//# sourceMappingURL=index.d.ts.map

//#endregion
export { $bucket, AlephaBucket, BucketDescriptor, BucketDescriptorOptions, BucketFileOptions, FileNotFoundError, FileStorageProvider, LocalFileStorageProvider, MemoryFileStorageProvider, fileMetadataSchema };
//# sourceMappingURL=index.d.ts.map