@alepha/bucket-vercel 0.12.0 → 0.12.1

package/dist/index.d.cts

@@ -1,11 +1,1957 @@
-import * as alepha1 from "alepha";
-import { Alepha, FileLike, Static } from "alepha";
-import * as alepha_logger0 from "alepha/logger";
-import { FileMetadataService, FileStorageProvider } from "alepha/bucket";
-import { DateTimeProvider } from "alepha/datetime";
-import { FileSystemProvider } from "alepha/file";
+import * as typebox0 from "typebox";
+import { Static, StaticDecode as Static$1, StaticEncode, TAny, TArray, TArray as TArray$1, TBoolean, TInteger, TNumber, TObject, TObject as TObject$1, TOptional, TOptionalAdd, TRecord, TSchema, TSchema as TSchema$1, TString, TUnsafe } from "typebox";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Readable } from "node:stream";
+import { ReadableStream as ReadableStream$1 } from "node:stream/web";
+import { Validator } from "typebox/compile";
+import dayjsDuration from "dayjs/plugin/duration.js";
+import DayjsApi, { Dayjs, ManipulateType, PluginFunc } from "dayjs";
 import { del, head, put } from "@vercel/blob";
 
+//#region ../alepha/src/core/constants/KIND.d.ts
+/**
+ * Used for identifying descriptors.
+ *
+ * @internal
+ */
+declare const KIND: unique symbol;
+//#endregion
+//#region ../alepha/src/core/interfaces/Service.d.ts
+/**
+ * In Alepha, a service is a class that can be instantiated or an abstract class. Nothing more, nothing less...
+ */
+type Service<T extends object = any> = InstantiableClass<T> | AbstractClass<T> | RunFunction<T>;
+type RunFunction<T extends object = any> = (...args: any[]) => T | void;
+type InstantiableClass<T extends object = any> = new (...args: any[]) => T;
+/**
+ * Abstract class is a class that cannot be instantiated directly!
+ * It widely used for defining interfaces.
+ */
+type AbstractClass<T extends object = any> = abstract new (...args: any[]) => T;
+/**
+ * Service substitution allows you to register a class as a different class.
+ * Providing class A, but using class B instead.
+ * This is useful for testing, mocking, or providing a different implementation of a service.
+ *
+ * class A is mostly an AbstractClass, while class B is an InstantiableClass.
+ */
+interface ServiceSubstitution<T extends object = any> {
+  /**
+   * Every time someone asks for this class, it will be provided with the 'use' class.
+   */
+  provide: Service<T>;
+  /**
+   * Service to use instead of the 'provide' service.
+   *
+   * Syntax is inspired by Angular's DI system.
+   */
+  use: Service<T>;
+  /**
+   * If true, if the service already exists -> just ignore the substitution and do not throw an error.
+   * Mostly used for plugins to enforce a substitution without throwing an error.
+   */
+  optional?: boolean;
+}
+/**
+ * Every time you register a service, you can use this type to define it.
+ *
+ * alepha.with( ServiceEntry )
+ * or
+ * alepha.with( provide: ServiceEntry, use: MyOwnServiceEntry )
+ *
+ * And yes, you declare the *type* of the service, not the *instance*.
+ */
+type ServiceEntry<T extends object = any> = Service<T> | ServiceSubstitution<T>;
+//#endregion
+//#region ../alepha/src/core/helpers/descriptor.d.ts
+interface DescriptorArgs<T extends object = {}> {
+  options: T;
+  alepha: Alepha;
+  service: InstantiableClass<Service>;
+  module?: Service;
+}
+interface DescriptorConfig {
+  propertyKey: string;
+  service: InstantiableClass<Service>;
+  module?: Service;
+}
+declare abstract class Descriptor<T extends object = {}> {
+  protected readonly alepha: Alepha;
+  readonly options: T;
+  readonly config: DescriptorConfig;
+  constructor(args: DescriptorArgs<T>);
+  /**
+   * Called automatically by Alepha after the descriptor is created.
+   */
+  protected onInit(): void;
+}
+type DescriptorFactoryLike<T extends object = any> = {
+  (options: T): any;
+  [KIND]: any;
+};
+//#endregion
+//#region ../alepha/src/core/descriptors/$inject.d.ts
+interface InjectOptions<T extends object = any> {
+  /**
+   * - 'transient' → Always a new instance on every inject. Zero caching.
+   * - 'singleton' → One instance per Alepha runtime (per-thread). Never disposed until Alepha shuts down. (default)
+   * - 'scoped' → One instance per AsyncLocalStorage context.
+   *   - A new scope is created when Alepha handles a request, a scheduled job, a queue worker task...
+   *   - You can also start a manual scope via alepha.context.run(() => { ... }).
+   *   - When the scope ends, the scoped registry is discarded.
+   *
+   * @default "singleton"
+   */
+  lifetime?: "transient" | "singleton" | "scoped";
+  /**
+   * Constructor arguments to pass when creating a new instance.
+   */
+  args?: ConstructorParameters<InstantiableClass<T>>;
+  /**
+   * Parent that requested the instance.
+   *
+   * @internal
+   */
+  parent?: Service | null;
+}
+//#endregion
+//#region ../alepha/src/core/descriptors/$module.d.ts
+interface ModuleDescriptorOptions {
+  /**
+   * Name of the module.
+   *
+   * It should be in the format of `project.module.submodule`.
+   */
+  name: string;
+  /**
+   * List all services related to this module.
+   *
+   * If you don't declare 'register' function, all services will be registered automatically.
+   * If you declare 'register' function, you must handle the registration of ALL services manually.
+   */
+  services?: Array<Service>;
+  /**
+   * List of $descriptors to register in the module.
+   */
+  descriptors?: Array<DescriptorFactoryLike>;
+  /**
+   * By default, module will register ALL services.
+   * You can override this behavior by providing a register function.
+   * It's useful when you want to register services conditionally or in a specific order.
+   *
+   * Again, if you declare 'register', you must handle the registration of ALL services manually.
+   */
+  register?: (alepha: Alepha) => void;
+}
+/**
+ * Base class for all modules.
+ */
+declare abstract class Module {
+  abstract readonly options: ModuleDescriptorOptions;
+  abstract register(alepha: Alepha): void;
+  static NAME_REGEX: RegExp;
+  /**
+   * Check if a Service is a Module.
+   */
+  static is(ctor: Service): boolean;
+  /**
+   * Get the Module of a Service.
+   *
+   * Returns undefined if the Service is not part of a Module.
+   */
+  static of(ctor: Service): Service<Module> | undefined;
+}
+//#endregion
+//#region ../alepha/src/core/interfaces/Async.d.ts
+/**
+ * Represents a value that can be either a value or a promise of value.
+ */
+type Async<T> = T | Promise<T>;
+//#endregion
+//#region ../alepha/src/core/interfaces/LoggerInterface.d.ts
+type LogLevel = "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE" | "SILENT";
+interface LoggerInterface {
+  trace(message: string, data?: unknown): void;
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+//#endregion
+//#region ../alepha/src/core/providers/AlsProvider.d.ts
+type AsyncLocalStorageData = any;
+declare class AlsProvider {
+  static create: () => AsyncLocalStorage<AsyncLocalStorageData> | undefined;
+  als?: AsyncLocalStorage<AsyncLocalStorageData>;
+  constructor();
+  createContextId(): string;
+  run<R>(callback: () => R, data?: Record<string, any>): R;
+  exists(): boolean;
+  get<T>(key: string): T | undefined;
+  set<T>(key: string, value: T): void;
+}
+//#endregion
+//#region ../alepha/src/core/providers/Json.d.ts
+/**
+ * Mimics the JSON global object with stringify and parse methods.
+ *
+ * Used across the codebase via dependency injection.
+ */
+declare class Json {
+  stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
+  parse(text: string, reviver?: (this: any, key: string, value: any) => any): any;
+}
+//#endregion
+//#region ../alepha/src/core/helpers/FileLike.d.ts
+interface FileLike {
+  /**
+   * Filename.
+   * @default "file"
+   */
+  name: string;
+  /**
+   * Mandatory MIME type of the file.
+   * @default "application/octet-stream"
+   */
+  type: string;
+  /**
+   * Size of the file in bytes.
+   *
+   * Always 0 for streams, as the size is not known until the stream is fully read.
+   *
+   * @default 0
+   */
+  size: number;
+  /**
+   * Last modified timestamp in milliseconds since epoch.
+   *
+   * Always the current timestamp for streams, as the last modified time is not known.
+   * We use this field to ensure compatibility with File API.
+   *
+   * @default Date.now()
+   */
+  lastModified: number;
+  /**
+   * Returns a ReadableStream or Node.js Readable stream of the file content.
+   *
+   * For streams, this is the original stream.
+   */
+  stream(): StreamLike;
+  /**
+   * Returns the file content as an ArrayBuffer.
+   *
+   * For streams, this reads the entire stream into memory.
+   */
+  arrayBuffer(): Promise<ArrayBuffer>;
+  /**
+   * Returns the file content as a string.
+   *
+   * For streams, this reads the entire stream into memory and converts it to a string.
+   */
+  text(): Promise<string>;
+  /**
+   * Optional file path, if the file is stored on disk.
+   *
+   * This is not from the File API, but rather a custom field to indicate where the file is stored.
+   */
+  filepath?: string;
+}
+type StreamLike = ReadableStream | ReadableStream$1 | Readable | NodeJS.ReadableStream;
+//#endregion
+//#region ../alepha/src/core/providers/TypeProvider.d.ts
+declare module "typebox" {
+  interface TString {
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+  }
+  interface TNumber {
+    format?: "int64";
+  }
+}
+//#endregion
+//#region ../alepha/src/core/providers/SchemaCodec.d.ts
+declare abstract class SchemaCodec {
+  /**
+   * Encode the value to a string format.
+   */
+  abstract encodeToString<T extends TSchema$1>(schema: T, value: Static$1<T>): string;
+  /**
+   * Encode the value to a binary format.
+   */
+  abstract encodeToBinary<T extends TSchema$1>(schema: T, value: Static$1<T>): Uint8Array;
+  /**
+   * Decode string, binary, or other formats to the schema type.
+   */
+  abstract decode<T>(schema: TSchema$1, value: unknown): T;
+}
+//#endregion
+//#region ../alepha/src/core/providers/JsonSchemaCodec.d.ts
+declare class JsonSchemaCodec extends SchemaCodec {
+  protected readonly json: Json;
+  protected readonly encoder: TextEncoder;
+  protected readonly decoder: TextDecoder;
+  encodeToString<T extends TSchema>(schema: T, value: Static$1<T>): string;
+  encodeToBinary<T extends TSchema>(schema: T, value: Static$1<T>): Uint8Array;
+  decode<T>(schema: TSchema, value: unknown): T;
+}
+//#endregion
+//#region ../alepha/src/core/providers/SchemaValidator.d.ts
+declare class SchemaValidator {
+  protected cache: Map<TSchema, Validator<typebox0.TProperties, TSchema, unknown, unknown>>;
+  /**
+   * Validate the value against the provided schema.
+   *
+   * Validation create a new value by applying some preprocessing. (e.g., trimming text)
+   */
+  validate<T extends TSchema>(schema: T, value: unknown, options?: ValidateOptions): Static$1<T>;
+  protected getValidator<T extends TSchema>(schema: T): Validator<{}, T>;
+  /**
+   * Preprocess the value based on the schema before validation.
+   *
+   * - If the value is `null` and the schema does not allow `null`, it converts it to `undefined`.
+   * - If the value is a string and the schema has a `~options.trim` flag, it trims whitespace from the string.
+   */
+  beforeParse(schema: any, value: any, options: ValidateOptions): any;
+  /**
+   * Used by `beforeParse` to determine if a schema allows null values.
+   */
+  protected isSchemaNullable: (schema: any) => boolean;
+}
+interface ValidateOptions {
+  trim?: boolean;
+  nullToUndefined?: boolean;
+  deleteUndefined?: boolean;
+}
+//#endregion
+//#region ../alepha/src/core/providers/CodecManager.d.ts
+type Encoding = "object" | "string" | "binary";
+interface EncodeOptions<T extends Encoding = Encoding> {
+  /**
+   * The output encoding format:
+   * - 'string': Returns JSON string
+   * - 'binary': Returns Uint8Array (for protobuf, msgpack, etc.)
+   *
+   * @default "string"
+   */
+  as?: T;
+  /**
+   * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
+   *
+   * @default "json"
+   */
+  encoder?: string;
+  /**
+   * Validation options to apply before encoding.
+   */
+  validation?: ValidateOptions | false;
+}
+type EncodeResult<T extends TSchema, E extends Encoding> = E extends "string" ? string : E extends "binary" ? Uint8Array : StaticEncode<T>;
+interface DecodeOptions {
+  /**
+   * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
+   *
+   * @default "json"
+   */
+  encoder?: string;
+  /**
+   * Validation options to apply before encoding.
+   */
+  validation?: ValidateOptions | false;
+}
+/**
+ * CodecManager manages multiple codec formats and provides a unified interface
+ * for encoding and decoding data with different formats.
+ */
+declare class CodecManager {
+  protected readonly codecs: Map<string, SchemaCodec>;
+  protected readonly jsonCodec: JsonSchemaCodec;
+  protected readonly schemaValidator: SchemaValidator;
+  default: string;
+  constructor();
+  /**
+   * Register a new codec format.
+   *
+   * @param name - The name of the codec (e.g., 'json', 'protobuf')
+   * @param codec - The codec implementation
+   */
+  register(name: string, codec: SchemaCodec): void;
+  /**
+   * Get a specific codec by name.
+   *
+   * @param name - The name of the codec
+   * @returns The codec instance
+   * @throws {AlephaError} If the codec is not found
+   */
+  getCodec(name: string): SchemaCodec;
+  /**
+   * Encode data using the specified codec and output format.
+   */
+  encode<T extends TSchema, E extends Encoding = "object">(schema: T, value: unknown, options?: EncodeOptions<E>): EncodeResult<T, E>;
+  /**
+   * Decode data using the specified codec.
+   */
+  decode<T extends TSchema>(schema: T, data: any, options?: DecodeOptions): Static$1<T>;
+  /**
+   * Validate decoded data against the schema.
+   *
+   * This is automatically called before encoding or after decoding.
+   */
+  validate<T extends TSchema>(schema: T, value: unknown, options?: ValidateOptions): Static$1<T>;
+}
+//#endregion
+//#region ../alepha/src/core/providers/EventManager.d.ts
+declare class EventManager {
+  protected logFn?: () => LoggerInterface | undefined;
+  /**
+   * List of events that can be triggered. Powered by $hook().
+   */
+  protected events: Record<string, Array<Hook>>;
+  constructor(logFn?: () => LoggerInterface | undefined);
+  protected get log(): LoggerInterface | undefined;
+  /**
+   * Registers a hook for the specified event.
+   */
+  on<T extends keyof Hooks>(event: T, hookOrFunc: Hook<T> | ((payload: Hooks[T]) => Async<void>)): () => void;
+  /**
+   * Emits the specified event with the given payload.
+   */
+  emit<T extends keyof Hooks>(func: T, payload: Hooks[T], options?: {
+    /**
+     * If true, the hooks will be executed in reverse order.
+     * This is useful for "stop" hooks that should be executed in reverse order.
+     *
+     * @default false
+     */
+    reverse?: boolean;
+    /**
+     * If true, the hooks will be logged with their execution time.
+     *
+     * @default false
+     */
+    log?: boolean;
+    /**
+     * If true, errors will be caught and logged instead of throwing.
+     *
+     * @default false
+     */
+    catch?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+//#region ../alepha/src/core/descriptors/$atom.d.ts
+type AtomOptions<T extends TAtomObject, N extends string> = {
+  name: N;
+  schema: T;
+  description?: string;
+} & (T extends TOptionalAdd<T> ? {
+  default?: Static$1<T>;
+} : {
+  default: Static$1<T>;
+});
+declare class Atom<T extends TAtomObject = TObject$1, N extends string = string> {
+  readonly options: AtomOptions<T, N>;
+  get schema(): T;
+  get key(): N;
+  constructor(options: AtomOptions<T, N>);
+}
+type TAtomObject = TObject$1<any> | TArray;
+type AtomStatic<T extends TAtomObject> = T extends TOptionalAdd<T> ? Static$1<T> | undefined : Static$1<T>;
+//#endregion
+//#region ../alepha/src/core/providers/StateManager.d.ts
+interface AtomWithValue {
+  atom: Atom;
+  value: unknown;
+}
+declare class StateManager<State$1 extends object = State> {
+  protected readonly als: AlsProvider;
+  protected readonly events: EventManager;
+  protected readonly codec: JsonSchemaCodec;
+  protected readonly atoms: Map<keyof State$1, Atom<TObject<typebox0.TProperties>, string>>;
+  protected store: Partial<State$1>;
+  constructor(store?: Partial<State$1>);
+  getAtoms(context?: boolean): Array<AtomWithValue>;
+  register(atom: Atom<any>): this;
+  /**
+   * Get a value from the state with proper typing
+   */
+  get<T extends TAtomObject>(target: Atom<T>): Static$1<T>;
+  get<Key extends keyof State$1>(target: Key): State$1[Key] | undefined;
+  /**
+   * Set a value in the state
+   */
+  set<T extends TAtomObject>(target: Atom<T>, value: AtomStatic<T>): this;
+  set<Key extends keyof State$1>(target: Key, value: State$1[Key] | undefined): this;
+  /**
+   * Mutate a value in the state.
+   */
+  mut<T extends TObject>(target: Atom<T>, mutator: (current: Static$1<T>) => Static$1<T>): this;
+  mut<Key extends keyof State$1>(target: Key, mutator: (current: State$1[Key] | undefined) => State$1[Key] | undefined): this;
+  /**
+   * Check if a key exists in the state
+   */
+  has<Key extends keyof State$1>(key: Key): boolean;
+  /**
+   * Delete a key from the state (set to undefined)
+   */
+  del<Key extends keyof State$1>(key: Key): this;
+  /**
+   * Push a value to an array in the state
+   */
+  push<Key extends keyof OnlyArray<State$1>>(key: Key, value: NonNullable<State$1[Key]> extends Array<infer U> ? U : never): this;
+  /**
+   * Clear all state
+   */
+  clear(): this;
+  /**
+   * Get all keys that exist in the state
+   */
+  keys(): (keyof State$1)[];
+}
+type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends Array<any> ? K : never };
+//#endregion
+//#region ../alepha/src/core/Alepha.d.ts
+/**
+ * Core container of the Alepha framework.
+ *
+ * It is responsible for managing the lifecycle of services,
+ * handling dependency injection,
+ * and providing a unified interface for the application.
+ *
+ * @example
+ * ```ts
+ * import { Alepha, run } from "alepha";
+ *
+ * class MyService {
+ *   // business logic here
+ * }
+ *
+ * const alepha = Alepha.create({
+ *   // state, env, and other properties
+ * })
+ *
+ * alepha.with(MyService);
+ *
+ * run(alepha); // trigger .start (and .stop) automatically
+ * ```
+ *
+ * ### Alepha Factory
+ *
+ * Alepha.create() is an enhanced version of new Alepha().
+ * - It merges `process.env` with the provided state.env when available.
+ * - It populates the test hooks for Vitest or Jest environments when available.
+ *
+ * new Alepha() is fine if you don't need these helpers.
+ *
+ * ### Platforms & Environments
+ *
+ * Alepha is designed to work in various environments:
+ * - **Browser**: Runs in the browser, using the global `window` object.
+ * - **Serverless**: Runs in serverless environments like Vercel or Vite.
+ * - **Test**: Runs in test environments like Jest or Vitest.
+ * - **Production**: Runs in production environments, typically with NODE_ENV set to "production".
+ * * You can check the current environment using the following methods:
+ *
+ * - `isBrowser()`: Returns true if the App is running in a browser environment.
+ * - `isServerless()`: Returns true if the App is running in a serverless environment.
+ * - `isTest()`: Returns true if the App is running in a test environment.
+ * - `isProduction()`: Returns true if the App is running in a production environment.
+ *
+ * ### State & Environment
+ *
+ * The state of the Alepha container is stored in the `store` property.
+ * Most important property is `store.env`, which contains the environment variables.
+ *
+ * ```ts
+ * const alepha = Alepha.create({ env: { MY_VAR: "value" } });
+ *
+ * // You can access the environment variables using alepha.env
+ * console.log(alepha.env.MY_VAR); // "value"
+ *
+ * // But you should use $env() descriptor to get typed values from the environment.
+ * class App {
+ *   env = $env(
+ *     t.object({
+ *  	   MY_VAR: t.text(),
+ *     })
+ *   );
+ * }
+ * ```
+ *
+ * ### Modules
+ *
+ * Modules are a way to group services together.
+ * You can register a module using the `$module` descriptor.
+ *
+ * ```ts
+ * import { $module } from "alepha";
+ *
+ * class MyLib {}
+ *
+ * const myModule = $module({
+ *   name: "my.project.module",
+ *   services: [MyLib],
+ * });
+ * ```
+ *
+ * Do not use modules for small applications.
+ *
+ * ### Hooks
+ *
+ * Hooks are a way to run async functions from all registered providers/services.
+ * You can register a hook using the `$hook` descriptor.
+ *
+ * ```ts
+ * import { $hook } from "alepha";
+ *
+ * class App {
+ * 	 log = $logger();
+ * 	 onCustomerHook = $hook({
+ * 			on: "my:custom:hook",
+ * 			handler: () => {
+ * 		 	  this.log?.info("App is being configured");
+ * 	 		},
+ * 	  });
+ * 	}
+ *
+ * Alepha.create()
+ * 	 .with(App)
+ * 	 .start()
+ * 	 .then(alepha => alepha.events.emit("my:custom:hook"));
+ * ```
+ *
+ * 	Hooks are fully typed. You can create your own hooks by using module augmentation:
+ *
+ * 	```ts
+ * 	declare module "alepha" {
+ * 		interface Hooks {
+ * 		  "my:custom:hook": {
+ * 				arg1: string;
+ * 		  }
+ * 		}
+ * 	}
+ * 	```
+ *
+ * 	@module alepha
+ */
+declare class Alepha {
+  /**
+   * Creates a new instance of the Alepha container with some helpers:
+   *
+   * - merges `process.env` with the provided state.env when available.
+   * - populates the test hooks for Vitest or Jest environments when available.
+   *
+   * If you are not interested about these helpers, you can use the constructor directly.
+   */
+  static create(state?: Partial<State>): Alepha;
+  /**
+   * Flag indicating whether the App won't accept any further changes.
+   * Pass to true when #start() is called.
+   */
+  protected locked: boolean;
+  /**
+   * True if the App has been configured.
+   */
+  protected configured: boolean;
+  /**
+   * True if the App has started.
+   */
+  protected started: boolean;
+  /**
+   * True if the App is ready.
+   */
+  protected ready: boolean;
+  /**
+   * A promise that resolves when the App has started.
+   */
+  protected starting?: PromiseWithResolvers<this>;
+  /**
+   * Initial state of the container.
+   *
+   * > Used to initialize the StateManager.
+   */
+  protected init: Partial<State>;
+  /**
+   * During the instantiation process, we keep a list of pending instantiations.
+   * > It allows us to detect circular dependencies.
+   */
+  protected pendingInstantiations: Service[];
+  /**
+   * Cache for environment variables.
+   * > It allows us to avoid parsing the same schema multiple times.
+   */
+  protected cacheEnv: Map<TSchema$1, any>;
+  /**
+   * List of modules that are registered in the container.
+   *
+   * Modules are used to group services and provide a way to register them in the container.
+   */
+  protected modules: Array<Module>;
+  /**
+   * List of service substitutions.
+   *
+   * Services registered here will be replaced by the specified service when injected.
+   */
+  protected substitutions: Map<Service, {
+    use: Service;
+  }>;
+  /**
+   * Registry of descriptors.
+   */
+  protected descriptorRegistry: Map<Service<Descriptor<{}>>, Descriptor<{}>[]>;
+  /**
+   *  List of all services + how they are provided.
+   */
+  protected registry: Map<Service, ServiceDefinition>;
+  /**
+   * Node.js feature that allows to store context across asynchronous calls.
+   *
+   * This is used for logging, tracing, and other context-related features.
+   *
+   * Mocked for browser environments.
+   */
+  get context(): AlsProvider;
+  /**
+   * Event manager to handle lifecycle events and custom events.
+   */
+  get events(): EventManager;
+  /**
+   * State manager to store arbitrary values.
+   */
+  get state(): StateManager<State>;
+  /**
+   * Codec manager for encoding and decoding data with different formats.
+   *
+   * Supports multiple codec formats (JSON, Protobuf, etc.) with a unified interface.
+   */
+  get codec(): CodecManager;
+  /**
+   * Get logger instance.
+   */
+  get log(): LoggerInterface | undefined;
+  /**
+   * The environment variables for the App.
+   */
+  get env(): Readonly<Env>;
+  constructor(init?: Partial<State>);
+  /**
+   * True when start() is called.
+   *
+   * -> No more services can be added, it's over, bye!
+   */
+  isLocked(): boolean;
+  /**
+   * Returns whether the App is configured.
+   *
+   * It means that Alepha#configure() has been called.
+   *
+   * > By default, configure() is called automatically when start() is called, but you can also call it manually.
+   */
+  isConfigured(): boolean;
+  /**
+   * Returns whether the App has started.
+   *
+   * It means that #start() has been called but maybe not all services are ready.
+   */
+  isStarted(): boolean;
+  /**
+   * True if the App is ready. It means that Alepha is started AND ready() hook has beed called.
+   */
+  isReady(): boolean;
+  /**
+   * True if the App is running in a Continuous Integration environment.
+   */
+  isCI(): boolean;
+  /**
+   * True if the App is running in a browser environment.
+   */
+  isBrowser(): boolean;
+  /**
+   * Returns whether the App is running in Vite dev mode.
+   */
+  isViteDev(): boolean;
+  isBun(): boolean;
+  /**
+   * Returns whether the App is running in a serverless environment.
+   */
+  isServerless(): boolean;
+  /**
+   * Returns whether the App is in test mode. (Running in a test environment)
+   *
+   * > This is automatically set when running tests with Jest or Vitest.
+   */
+  isTest(): boolean;
+  /**
+   * Returns whether the App is in production mode. (Running in a production environment)
+   *
+   * > This is automatically set by Vite or Vercel. However, you have to set it manually when running Docker apps.
+   */
+  isProduction(): boolean;
+  /**
+   * Starts the App.
+   *
+   * - Lock any further changes to the container.
+   * - Run "configure" hook for all services. Descriptors will be processed.
+   * - Run "start" hook for all services. Providers will connect/listen/...
+   * - Run "ready" hook for all services. This is the point where the App is ready to serve requests.
+   *
+   * @return A promise that resolves when the App has started.
+   */
+  start(): Promise<this>;
+  /**
+   * Stops the App.
+   *
+   * - Run "stop" hook for all services.
+   *
+   * Stop will NOT reset the container.
+   * Stop will NOT unlock the container.
+   *
+   * > Stop is used to gracefully shut down the application, nothing more. There is no "restart".
+   *
+   * @return A promise that resolves when the App has stopped.
+   */
+  stop(): Promise<void>;
+  /**
+   * Check if entry is registered in the container.
+   */
+  has(entry: ServiceEntry, opts?: {
+    /**
+     * Check if the entry is registered in the pending instantiation stack.
+     *
+     * @default true
+     */
+    inStack?: boolean;
+    /**
+     * Check if the entry is registered in the container registry.
+     *
+     * @default true
+     */
+    inRegistry?: boolean;
+    /**
+     * Check if the entry is registered in the substitutions.
+     *
+     * @default true
+     */
+    inSubstitutions?: boolean;
+    /**
+     * Where to look for registered services.
+     *
+     * @default this.registry
+     */
+    registry?: Map<Service, ServiceDefinition>;
+  }): boolean;
+  /**
+   * Registers the specified service in the container.
+   *
+   * - If the service is ALREADY registered, the method does nothing.
+   * - If the service is NOT registered, a new instance is created and registered.
+   *
+   * Method is chainable, so you can register multiple services in a single call.
+   *
+   * > ServiceEntry allows to provide a service **substitution** feature.
+   *
+   * @example
+   * ```ts
+   * class A { value = "a"; }
+   * class B { value = "b"; }
+   * class M { a = $inject(A); }
+   *
+   * Alepha.create().with({ provide: A, use: B }).get(M).a.value; // "b"
+   * ```
+   *
+   * > **Substitution** is an advanced feature that allows you to replace a service with another service.
+   * > It's useful for testing or for providing different implementations of a service.
+   * > If you are interested in configuring a service, use Alepha#configure() instead.
+   *
+   * @param serviceEntry - The service to register in the container.
+   * @return Current instance of Alepha.
+   */
+  with<T extends object>(serviceEntry: ServiceEntry<T> | {
+    default: ServiceEntry<T>;
+  }): this;
+  /**
+   * Get an instance of the specified service from the container.
+   *
+   * @see {@link InjectOptions} for the available options.
+   */
+  inject<T extends object>(service: Service<T> | string, opts?: InjectOptions<T>): T;
+  /**
+   * Applies environment variables to the provided schema and state object.
+   *
+   * It replaces also all templated $ENV inside string values.
+   *
+   * @param schema - The schema object to apply environment variables to.
+   * @return The schema object with environment variables applied.
+   */
+  parseEnv<T extends TObject>(schema: T): Static<T>;
+  /**
+   * Dump the current dependency graph of the App.
+   *
+   * This method returns a record where the keys are the names of the services.
+   */
+  graph(): Record<string, {
+    from: string[];
+    as?: string[];
+    module?: string;
+  }>;
+  services<T extends object>(base: Service<T>): Array<T>;
+  /**
+   * Get all descriptors of the specified type.
+   */
+  descriptors<TDescriptor extends Descriptor>(factory: {
+    [KIND]: InstantiableClass<TDescriptor>;
+  } | string): Array<TDescriptor>;
+  protected new<T extends object>(service: Service<T>, args?: any[]): T;
+  protected processDescriptor(value: Descriptor, propertyKey?: string): void;
+}
+interface Hook<T extends keyof Hooks = any> {
+  caller?: Service;
+  priority?: "first" | "last";
+  callback: (payload: Hooks[T]) => Async<void>;
+}
+/**
+ * This is how we store services in the Alepha container.
+ */
+interface ServiceDefinition<T extends object = any> {
+  /**
+   * The instance of the class or type definition.
+   * Mostly used for caching / singleton but can be used for other purposes like forcing the instance.
+   */
+  instance: T;
+  /**
+   * List of classes which use this class.
+   */
+  parents: Array<Service | null>;
+}
+interface Env {
+  [key: string]: string | boolean | number | undefined;
+  /**
+   * Optional environment variable that indicates the current environment.
+   */
+  NODE_ENV?: "dev" | "test" | "production";
+  /**
+   * Optional name of the application.
+   */
+  APP_NAME?: string;
+  /**
+   * Optional root module name.
+   */
+  MODULE_NAME?: string;
+}
+interface State {
+  /**
+   * Environment variables for the application.
+   */
+  env?: Readonly<Env>;
+  /**
+   * Logger instance to be used by the Alepha container.
+   *
+   * @internal
+   */
+  "alepha.logger"?: LoggerInterface;
+  /**
+   * If defined, the Alepha container will only register this service and its dependencies.
+   */
+  "alepha.target"?: Service;
+  /**
+   * Bind to Vitest 'beforeAll' hook.
+   * Used for testing purposes.
+   * This is automatically attached if Alepha#create() detects a test environment and global 'beforeAll' is available.
+   */
+  "alepha.test.beforeAll"?: (run: any) => any;
+  /**
+   * Bind to Vitest 'afterAll' hook.
+   * Used for testing purposes.
+   * This is automatically attached if Alepha#create() detects a test environment and global 'afterAll' is available.
+   */
+  "alepha.test.afterAll"?: (run: any) => any;
+  /**
+   * Bind to Vitest 'afterEach' hook.
+   * Used for testing purposes.
+   * This is automatically attached if Alepha#create() detects a test environment and global 'afterEach' is available.
+   */
+  "alepha.test.afterEach"?: (run: any) => any;
+  /**
+   * Bind to Vitest 'onTestFinished' hook.
+   * Used for testing purposes.
+   * This is automatically attached if Alepha#create() detects a test environment and global 'onTestFinished' is available.
+   */
+  "alepha.test.onTestFinished"?: (run: any) => any;
+  /**
+   * List of static assets to be copied to the output directory during the build process.
+   *
+   * Used for Alepha-based applications that require static assets.
+   *
+   * See alepha/vite for more details.
+   */
+  "alepha.build.assets"?: Array<string>;
+}
+interface Hooks {
+  /**
+   * Used for testing purposes.
+   */
+  echo: unknown;
+  /**
+   * Triggered during the configuration phase. Before the start phase.
+   */
+  configure: Alepha;
+  /**
+   * Triggered during the start phase. When `Alepha#start()` is called.
+   */
+  start: Alepha;
+  /**
+   * Triggered during the ready phase. After the start phase.
+   */
+  ready: Alepha;
+  /**
+   * Triggered during the stop phase.
+   *
+   * - Stop should be called after a SIGINT or SIGTERM signal in order to gracefully shutdown the application. (@see `run()` method)
+   *
+   */
+  stop: Alepha;
+  /**
+   * Triggered when a state value is mutated.
+   */
+  "state:mutate": {
+    /**
+     * The key of the state that was mutated.
+     */
+    key: keyof State;
+    /**
+     * The new value of the state.
+     */
+    value: any;
+    /**
+     * The previous value of the state.
+     */
+    prevValue: any;
+  };
+}
+//#endregion
+//#region ../alepha/src/core/descriptors/$hook.d.ts
+interface HookOptions<T extends keyof Hooks> {
+  /**
+   * The name of the hook. "configure", "start", "ready", "stop", ...
+   */
+  on: T;
+  /**
+   * The handler to run when the hook is triggered.
+   */
+  handler: (args: Hooks[T]) => Async<any>;
+  /**
+   * Force the hook to run first or last on the list of hooks.
+   */
+  priority?: "first" | "last";
+  /**
+   * Empty placeholder, not implemented yet. :-)
+   */
+  before?: object | Array<object>;
+  /**
+   * Empty placeholder, not implemented yet. :-)
+   */
+  after?: object | Array<object>;
+}
+declare class HookDescriptor<T extends keyof Hooks> extends Descriptor<HookOptions<T>> {
+  called: number;
+  protected onInit(): void;
+}
+//#endregion
+//#region ../alepha/src/core/schemas/pageSchema.d.ts
+declare const pageMetadataSchema: TObject$1<{
+  number: TInteger;
+  size: TInteger;
+  offset: TInteger;
+  numberOfElements: TInteger;
+  totalElements: TOptional<TInteger>;
+  totalPages: TOptional<TInteger>;
+  isEmpty: TBoolean;
+  isFirst: TBoolean;
+  isLast: TBoolean;
+  sort: TOptional<TObject$1<{
+    sorted: TBoolean;
+    fields: TArray$1<TObject$1<{
+      field: TString;
+      direction: TUnsafe<"asc" | "desc">;
+    }>>;
+  }>>;
+}>;
+type TPage<T extends TObject$1 | TRecord> = TObject$1<{
+  content: TArray$1<T>;
+  page: typeof pageMetadataSchema;
+}>;
+declare module "alepha" {
+  interface TypeProvider {
+    /**
+     * Create a schema for a paginated response.
+     */
+    page<T extends TObject$1 | TRecord>(itemSchema: T): TPage<T>;
+  }
+}
+//#endregion
+//#region ../alepha/src/logger/schemas/logEntrySchema.d.ts
+declare const logEntrySchema: TObject$1<{
+  level: TUnsafe<"SILENT" | "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR">;
+  message: TString;
+  service: TString;
+  module: TString;
+  context: TOptional<TString>;
+  app: TOptional<TString>;
+  data: TOptional<TAny>;
+  timestamp: TNumber;
+}>;
+type LogEntry = Static$1<typeof logEntrySchema>;
+//#endregion
+//#region ../alepha/src/datetime/providers/DateTimeProvider.d.ts
+type DateTime = DayjsApi.Dayjs;
+type Duration = dayjsDuration.Duration;
+type DurationLike = number | dayjsDuration.Duration | [number, ManipulateType];
+declare class DateTimeProvider {
+  static PLUGINS: Array<PluginFunc<any>>;
+  protected alepha: Alepha;
+  protected ref: DateTime | null;
+  protected readonly timeouts: Timeout[];
+  protected readonly intervals: Interval[];
+  constructor();
+  protected readonly onStart: HookDescriptor<"start">;
+  protected readonly onStop: HookDescriptor<"stop">;
+  setLocale(locale: string): void;
+  isDateTime(value: unknown): value is DateTime;
+  /**
+   * Create a new UTC DateTime instance.
+   */
+  utc(date: string | number | Date | Dayjs | null | undefined): DateTime;
+  /**
+   * Create a new DateTime instance.
+   */
+  of(date: string | number | Date | Dayjs | null | undefined): DateTime;
+  /**
+   * Get the current date as a string.
+   */
+  toISOString(date?: Date | string | DateTime): string;
+  /**
+   * Get the current date.
+   */
+  now(): DateTime;
+  /**
+   * Get the current date as a string.
+   *
+   * This is much faster than `DateTimeProvider.now().toISOString()` as it avoids creating a DateTime instance.
+   */
+  nowISOString(): string;
+  /**
+   * Get the current date as milliseconds since epoch.
+   *
+   * This is much faster than `DateTimeProvider.now().valueOf()` as it avoids creating a DateTime instance.
+   */
+  nowMillis(): number;
+  /**
+   * Get the current date as a string.
+   *
+   * @protected
+   */
+  protected getCurrentDate(): DateTime;
+  /**
+   * Create a new Duration instance.
+   */
+  duration: (duration: DurationLike, unit?: ManipulateType) => Duration;
+  isDurationLike(value: unknown): value is DurationLike;
+  /**
+   * Return a promise that resolves after the next tick.
+   * It uses `setTimeout` with 0 ms delay.
+   */
+  tick(): Promise<void>;
+  /**
+   * Wait for a certain duration.
+   *
+   * You can clear the timeout by using the `AbortSignal` API.
+   * Aborted signal will resolve the promise immediately, it does not reject it.
+   */
+  wait(duration: DurationLike, options?: {
+    signal?: AbortSignal;
+    now?: number;
+  }): Promise<void>;
+  createInterval(run: () => unknown, duration: DurationLike, start?: boolean): Interval;
+  /**
+   * Run a callback after a certain duration.
+   */
+  createTimeout(callback: () => void, duration: DurationLike, now?: number): Timeout;
+  clearTimeout(timeout: Timeout): void;
+  clearInterval(interval: Interval): void;
+  /**
+   * Run a function with a deadline.
+   */
+  deadline<T>(fn: (signal: AbortSignal) => Promise<T>, duration: DurationLike): Promise<T>;
+  /**
+   * Add time to the current date.
+   */
+  travel(duration: DurationLike, unit?: ManipulateType): Promise<void>;
+  /**
+   * Stop the time.
+   */
+  pause(): DateTime;
+  /**
+   * Reset the reference date.
+   */
+  reset(): void;
+}
+interface Interval {
+  timer?: any;
+  duration: number;
+  run: () => unknown;
+}
+interface Timeout {
+  now: number;
+  timer?: any;
+  duration: number;
+  callback: () => void;
+  clear: () => void;
+}
+//#endregion
+//#region ../alepha/src/logger/providers/LogDestinationProvider.d.ts
+declare abstract class LogDestinationProvider {
+  abstract write(message: string, entry: LogEntry): void;
+}
+//#endregion
+//#region ../alepha/src/logger/providers/LogFormatterProvider.d.ts
+declare abstract class LogFormatterProvider {
+  abstract format(entry: LogEntry): string;
+}
+//#endregion
+//#region ../alepha/src/logger/services/Logger.d.ts
+declare class Logger implements LoggerInterface {
+  protected readonly alepha: Alepha;
+  protected readonly formatter: LogFormatterProvider;
+  protected readonly destination: LogDestinationProvider;
+  protected readonly dateTimeProvider: DateTimeProvider;
+  protected readonly levels: Record<string, number>;
+  protected readonly service: string;
+  protected readonly module: string;
+  protected readonly app?: string;
+  protected appLogLevel: string;
+  protected logLevel: LogLevel;
+  constructor(service: string, module: string);
+  get context(): string | undefined;
+  get level(): string;
+  parseLevel(level: string, app: string): LogLevel;
+  private matchesPattern;
+  asLogLevel(something: string): LogLevel;
+  error(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  debug(message: string, data?: unknown): void;
+  trace(message: string, data?: unknown): void;
+  protected log(level: LogLevel, message: string, data?: unknown): void;
+  protected emit(entry: LogEntry, message?: string): void;
+}
+//#endregion
+//#region ../alepha/src/logger/index.d.ts
+declare const envSchema$1: TObject$1<{
+  /**
+   * Default log level for the application.
+   *
+   * Default by environment:
+   * - dev = info
+   * - prod = info
+   * - test = error
+   *
+   * Levels are: "trace" | "debug" | "info" | "warn" | "error" | "silent"
+   *
+   * Level can be set for a specific module:
+   *
+   * @example
+   * LOG_LEVEL=my.module.name:debug,info # Set debug level for my.module.name and info for all other modules
+   * LOG_LEVEL=alepha:trace, info # Set trace level for all alepha modules and info for all other modules
+   */
+  LOG_LEVEL: TOptional<TString>;
+  /**
+   * Built-in log formats.
+   * - "json" - JSON format, useful for structured logging and log aggregation. {@link JsonFormatterProvider}
+   * - "pretty" - Simple text format, human-readable, with colors. {@link SimpleFormatterProvider}
+   * - "raw" - Raw format, no formatting, just the message.  {@link RawFormatterProvider}
+   */
+  LOG_FORMAT: TOptional<TUnsafe<"json" | "pretty" | "raw">>;
+}>;
+declare module "alepha" {
+  interface Env extends Partial<Static$1<typeof envSchema$1>> {}
+  interface State {
+    /**
+     * Current log level for the application or specific modules.
+     */
+    "alepha.logger.level"?: string;
+  }
+  interface Hooks {
+    log: {
+      message?: string;
+      entry: LogEntry;
+    };
+  }
+}
+//#endregion
+//#region ../alepha/src/bucket/providers/FileStorageProvider.d.ts
+declare abstract class FileStorageProvider {
+  /**
+   * Uploads a file to the storage.
+   *
+   * @param bucketName - Container name
+   * @param file - File to upload
+   * @param fileId - Optional file identifier. If not provided, a unique ID will be generated.
+   * @return The identifier of the uploaded file.
+   */
+  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>;
+}
+//#endregion
+//#region ../alepha/src/file/providers/FileSystemProvider.d.ts
+/**
+ * Options for creating a file from a URL
+ */
+interface CreateFileFromUrlOptions {
+  /**
+   * The URL to load the file from (file://, http://, or https://)
+   */
+  url: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a path (URL with file:// scheme)
+ */
+interface CreateFileFromPathOptions {
+  /**
+   * The path to the file on the local filesystem
+   */
+  path: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a Buffer
+ */
+interface CreateFileFromBufferOptions {
+  /**
+   * The Buffer containing the file data
+   */
+  buffer: Buffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a stream
+ */
+interface CreateFileFromStreamOptions {
+  /**
+   * The readable stream containing the file data
+   */
+  stream: StreamLike;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+  /**
+   * The size of the file in bytes (optional)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from text content
+ */
+interface CreateFileFromTextOptions {
+  /**
+   * The text content to create the file from
+   */
+  text: string;
+  /**
+   * The MIME type of the file (default: text/plain)
+   */
+  type?: string;
+  /**
+   * The name of the file (default: "file.txt")
+   */
+  name?: string;
+}
+interface CreateFileFromResponseOptions {
+  /**
+   * The Response object containing the file data
+   */
+  response: Response;
+  /**
+   * Override the name (optional, uses filename from Content-Disposition header if not provided)
+   */
+  name?: string;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+}
+/**
+ * Options for creating a file from a Web File object
+ */
+interface CreateFileFromWebFileOptions {
+  /**
+   * The Web File object
+   */
+  file: File;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+  /**
+   * Override the name (optional, uses file.name if not provided)
+   */
+  name?: string;
+  /**
+   * Override the size (optional, uses file.size if not provided)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from an ArrayBuffer
+ */
+interface CreateFileFromArrayBufferOptions {
+  /**
+   * The ArrayBuffer containing the file data
+   */
+  arrayBuffer: ArrayBuffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Union type for all createFile options
+ */
+type CreateFileOptions = CreateFileFromUrlOptions | CreateFileFromPathOptions | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | CreateFileFromResponseOptions | CreateFileFromArrayBufferOptions;
+/**
+ * Options for rm (remove) operation
+ */
+interface RmOptions {
+  /**
+   * If true, removes directories and their contents recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, no error will be thrown if the path does not exist
+   */
+  force?: boolean;
+}
+/**
+ * Options for cp (copy) operation
+ */
+interface CpOptions {
+  /**
+   * If true, copy directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, overwrite existing destination
+   */
+  force?: boolean;
+}
+/**
+ * Options for mkdir operation
+ */
+interface MkdirOptions {
+  /**
+   * If true, creates parent directories as needed
+   */
+  recursive?: boolean;
+  /**
+   * File mode (permission and sticky bits)
+   */
+  mode?: number;
+}
+/**
+ * Options for ls (list) operation
+ */
+interface LsOptions {
+  /**
+   * If true, list contents of directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, include hidden files (starting with .)
+   */
+  hidden?: boolean;
+}
+/**
+ * FileSystem interface providing utilities for working with files.
+ */
+declare abstract class FileSystemProvider {
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   */
+  abstract createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   */
+  abstract rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copies a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Copy options
+   */
+  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Moves/renames a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   */
+  abstract mv(src: string, dest: string): Promise<void>;
+  /**
+   * Creates a directory.
+   *
+   * @param path - The directory path to create
+   * @param options - Mkdir options
+   */
+  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Lists files in a directory.
+   *
+   * @param path - The directory path to list
+   * @param options - List options
+   * @returns Array of filenames
+   */
+  abstract ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Checks if a file or directory exists.
+   *
+   * @param path - The path to check
+   * @returns True if the path exists, false otherwise
+   */
+  abstract exists(path: string): Promise<boolean>;
+  /**
+   * Reads the content of a file.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a Buffer
+   */
+  abstract readFile(path: string): Promise<Buffer>;
+  /**
+   * Writes data to a file.
+   *
+   * @param path - The file path to write to
+   * @param data - The data to write (Buffer or string)
+   */
+  abstract writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+}
+//#endregion
+//#region ../alepha/src/file/services/FileDetector.d.ts
+interface FileTypeResult {
+  /**
+   * The detected MIME type
+   */
+  mimeType: string;
+  /**
+   * The detected file extension
+   */
+  extension: string;
+  /**
+   * Whether the file type was verified by magic bytes
+   */
+  verified: boolean;
+  /**
+   * The stream (potentially wrapped to allow re-reading)
+   */
+  stream: Readable;
+}
+/**
+ * Service for detecting file types and getting content types.
+ *
+ * @example
+ * ```typescript
+ * const detector = alepha.inject(FileDetector);
+ *
+ * // Get content type from filename
+ * const mimeType = detector.getContentType("image.png"); // "image/png"
+ *
+ * // Detect file type by magic bytes
+ * const stream = createReadStream('image.png');
+ * const result = await detector.detectFileType(stream, 'image.png');
+ * console.log(result.mimeType); // 'image/png'
+ * console.log(result.verified); // true if magic bytes match
+ * ```
+ */
+declare class FileDetector {
+  /**
+   * Magic byte signatures for common file formats.
+   * Each signature is represented as an array of bytes or null (wildcard).
+   */
+  protected static readonly MAGIC_BYTES: Record<string, {
+    signature: (number | null)[];
+    mimeType: string;
+  }[]>;
+  /**
+   * All possible format signatures for checking against actual file content
+   */
+  protected static readonly ALL_SIGNATURES: {
+    signature: (number | null)[];
+    mimeType: string;
+    ext: string;
+  }[];
+  /**
+   * MIME type map for file extensions.
+   *
+   * Can be used to get the content type of file based on its extension.
+   * Feel free to add more mime types in your project!
+   */
+  static readonly mimeMap: Record<string, string>;
+  /**
+   * Reverse MIME type map for looking up extensions from MIME types.
+   * Prefers shorter, more common extensions when multiple exist.
+   */
+  protected static readonly reverseMimeMap: Record<string, string>;
+  /**
+   * Returns the file extension for a given MIME type.
+   *
+   * @param mimeType - The MIME type to look up
+   * @returns The file extension (without dot), or "bin" if not found
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const ext = detector.getExtensionFromMimeType("image/png"); // "png"
+   * const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
+   * ```
+   */
+  getExtensionFromMimeType(mimeType: string): string;
+  /**
+   * Returns the content type of file based on its filename.
+   *
+   * @param filename - The filename to check
+   * @returns The MIME type
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const mimeType = detector.getContentType("image.png"); // "image/png"
+   * ```
+   */
+  getContentType(filename: string): string;
+  /**
+   * Detects the file type by checking magic bytes against the stream content.
+   *
+   * @param stream - The readable stream to check
+   * @param filename - The filename (used to get the extension)
+   * @returns File type information including MIME type, extension, and verification status
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const stream = createReadStream('image.png');
+   * const result = await detector.detectFileType(stream, 'image.png');
+   * console.log(result.mimeType); // 'image/png'
+   * console.log(result.verified); // true if magic bytes match
+   * ```
+   */
+  detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
+  /**
+   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
+   * This approach reads the entire stream upfront to avoid complex async handling issues.
+   *
+   * @protected
+   */
+  protected peekBytes(stream: Readable, numBytes: number): Promise<{
+    buffer: Buffer;
+    stream: Readable;
+  }>;
+  /**
+   * Checks if a buffer matches a magic byte signature.
+   *
+   * @protected
+   */
+  protected matchesSignature(buffer: Buffer, signature: (number | null)[]): boolean;
+}
+//#endregion
+//#region ../alepha/src/bucket/providers/MemoryFileStorageProvider.d.ts
+declare class MemoryFileStorageProvider implements FileStorageProvider {
+  readonly files: Record<string, FileLike>;
+  protected readonly fileSystem: FileSystemProvider;
+  protected readonly fileDetector: FileDetector;
+  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;
+}
+//#endregion
+//#region ../alepha/src/bucket/descriptors/$bucket.d.ts
+interface BucketDescriptorOptions extends BucketFileOptions {
+  /**
+   * File storage provider configuration for the bucket.
+   *
+   * Options:
+   * - **"memory"**: In-memory storage (default for development, lost on restart)
+   * - **Service<FileStorageProvider>**: Custom provider class (e.g., S3FileStorageProvider, AzureBlobProvider)
+   * - **undefined**: Uses the default file storage provider from dependency injection
+   *
+   * **Provider Selection Guidelines**:
+   * - **Development**: Use "memory" for fast, simple testing without external dependencies
+   * - **Production**: Use cloud providers (S3, Azure Blob, Google Cloud Storage) for scalability
+   * - **Local deployment**: Use filesystem providers for on-premise installations
+   * - **Hybrid**: Use different providers for different bucket types (temp files vs permanent storage)
+   *
+   * **Provider Capabilities**:
+   * - File persistence and durability guarantees
+   * - Scalability and performance characteristics
+   * - Geographic distribution and CDN integration
+   * - Cost implications for storage and bandwidth
+   * - Backup and disaster recovery features
+   *
+   * @default Uses injected FileStorageProvider
+   * @example "memory"
+   * @example S3FileStorageProvider
+   * @example AzureBlobStorageProvider
+   */
+  provider?: Service<FileStorageProvider> | "memory";
+  /**
+   * Unique name identifier for the bucket.
+   *
+   * This name is used for:
+   * - Storage backend organization and partitioning
+   * - File path generation and URL construction
+   * - Logging, monitoring, and debugging
+   * - Access control and permissions management
+   * - Backup and replication configuration
+   *
+   * **Naming Conventions**:
+   * - Use lowercase with hyphens for consistency
+   * - Include purpose or content type in the name
+   * - Avoid spaces and special characters
+   * - Consider environment prefixes for deployment isolation
+   *
+   * If not provided, defaults to the property key where the bucket is declared.
+   *
+   * @example "user-avatars"
+   * @example "product-images"
+   * @example "legal-documents"
+   * @example "temp-processing-files"
+   */
+  name?: string;
+}
+interface BucketFileOptions {
+  /**
+   * Human-readable description of the bucket's purpose and contents.
+   *
+   * Used for:
+   * - Documentation generation and API references
+   * - Developer onboarding and system understanding
+   * - Monitoring dashboards and admin interfaces
+   * - Compliance and audit documentation
+   *
+   * **Description Best Practices**:
+   * - Explain what types of files this bucket stores
+   * - Mention any special handling or processing requirements
+   * - Include information about retention policies if applicable
+   * - Note any compliance or security considerations
+   *
+   * @example "User profile pictures and avatar images"
+   * @example "Product catalog images with automated thumbnail generation"
+   * @example "Legal documents requiring long-term retention"
+   * @example "Temporary files for data processing workflows"
+   */
+  description?: string;
+  /**
+   * Array of allowed MIME types for files uploaded to this bucket.
+   *
+   * When specified, only files with these exact MIME types will be accepted.
+   * Files with disallowed MIME types will be rejected with an InvalidFileError.
+   *
+   * **MIME Type Categories**:
+   * - Images: "image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml"
+   * - Documents: "application/pdf", "text/plain", "text/csv"
+   * - Office: "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+   * - Archives: "application/zip", "application/x-tar", "application/gzip"
+   * - Media: "video/mp4", "audio/mpeg", "audio/wav"
+   *
+   * **Security Considerations**:
+   * - Always validate MIME types for user uploads
+   * - Be cautious with executable file types
+   * - Consider using allow-lists rather than deny-lists
+   * - Remember that MIME types can be spoofed by malicious users
+   *
+   * If not specified, all MIME types are allowed (not recommended for user uploads).
+   *
+   * @example ["image/jpeg", "image/png"] // Only JPEG and PNG images
+   * @example ["application/pdf", "text/plain"] // Documents only
+   * @example ["video/mp4", "video/webm"] // Video files
+   */
+  mimeTypes?: string[];
+  /**
+   * Maximum file size allowed in megabytes (MB).
+   *
+   * Files larger than this limit will be rejected with an InvalidFileError.
+   * This helps prevent:
+   * - Storage quota exhaustion
+   * - Memory issues during file processing
+   * - Long upload times and timeouts
+   * - Abuse of storage resources
+   *
+   * **Size Guidelines by File Type**:
+   * - Profile images: 1-5 MB
+   * - Product photos: 5-10 MB
+   * - Documents: 10-50 MB
+   * - Video files: 50-500 MB
+   * - Data files: 100-1000 MB
+   *
+   * **Considerations**:
+   * - Consider your storage costs and limits
+   * - Factor in network upload speeds for users
+   * - Account for processing requirements (thumbnails, compression)
+   * - Set reasonable limits based on actual use cases
+   *
+   * @default 10 MB
+   *
+   * @example 1    // 1MB for small images
+   * @example 25   // 25MB for documents
+   * @example 100  // 100MB for media files
+   */
+  maxSize?: number;
+}
+declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
+  readonly provider: FileStorageProvider | MemoryFileStorageProvider;
+  private readonly fileSystem;
+  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, skipHook?: boolean): 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(): FileStorageProvider | MemoryFileStorageProvider;
+}
+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;
+}
+//#endregion
+//#region ../alepha/src/bucket/providers/LocalFileStorageProvider.d.ts
+/**
+ * Local file storage configuration atom
+ */
+declare const localFileStorageOptions: Atom<TObject$1<{
+  storagePath: TString;
+}>, "alepha.bucket.local.options">;
+type LocalFileStorageProviderOptions = Static$1<typeof localFileStorageOptions.schema>;
+declare module "alepha" {
+  interface State {
+    [localFileStorageOptions.key]: LocalFileStorageProviderOptions;
+  }
+}
+//#endregion
+//#region ../alepha/src/bucket/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
+ */
+//#endregion
 //#region src/providers/VercelBlobProvider.d.ts
 declare class VercelBlobApi {
   put: typeof put;
@@ -14,29 +1960,29 @@ declare class VercelBlobApi {
 }
 //#endregion
 //#region src/providers/VercelFileStorageProvider.d.ts
-declare const envSchema: alepha1.TObject<{
-  BLOB_READ_WRITE_TOKEN: alepha1.TString;
+declare const envSchema: TObject$1<{
+  BLOB_READ_WRITE_TOKEN: TString;
 }>;
 declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
+  interface Env extends Partial<Static$1<typeof envSchema>> {}
 }
 /**
  * Vercel Blob Storage implementation of File Storage Provider.
  */
 declare class VercelFileStorageProvider implements FileStorageProvider {
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: Logger;
   protected readonly env: {
     BLOB_READ_WRITE_TOKEN: string;
   };
   protected readonly alepha: Alepha;
   protected readonly time: DateTimeProvider;
   protected readonly fileSystem: FileSystemProvider;
+  protected readonly fileDetector: FileDetector;
   protected readonly stores: Set<string>;
   protected readonly vercelBlobApi: VercelBlobApi;
-  protected readonly metadataService: FileMetadataService;
-  protected readonly onStart: alepha1.HookDescriptor<"start">;
+  protected readonly onStart: HookDescriptor<"start">;
   convertName(name: string): string;
-  protected createId(): string;
+  protected createId(mimeType: string): string;
   upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
   download(bucketName: string, fileId: string): Promise<FileLike>;
   exists(bucketName: string, fileId: string): Promise<boolean>;
@@ -50,7 +1996,7 @@ declare class VercelFileStorageProvider implements FileStorageProvider {
  * @see {@link VercelFileStorageProvider}
  * @module alepha.bucket.vercel
  */
-declare const AlephaBucketVercel: alepha1.Service<alepha1.Module>;
+declare const AlephaBucketVercel: Service<Module>;
 //#endregion
 export { AlephaBucketVercel, VercelFileStorageProvider };
 //# sourceMappingURL=index.d.cts.map