alepha 0.6.10 → 0.7.1

package/core.d.ts

@@ -1,13 +1,13 @@
 import * as TypeBox from '@sinclair/typebox';
-import { TSchema, Static, TObject, FormatRegistry, SchemaOptions, ObjectOptions, Union, TProperties, ArrayOptions, TArray, StringOptions, TString, TBoolean, NumberOptions, TNumber, IntegerOptions, TInteger, TOptionalWithFlag, TNull, TIntersect, TUnsafe, UnsafeOptions } from '@sinclair/typebox';
+import { TSchema, Static, TObject, SchemaOptions, ObjectOptions, Union, TProperties, ArrayOptions, TArray, StringOptions, TString, TBoolean, NumberOptions, TNumber, IntegerOptions, TInteger, TOptionalWithFlag, TNull, TIntersect, TUnsafe, UnsafeOptions } from '@sinclair/typebox';
 export { TypeBox };
 export { Static, StaticDecode, StaticEncode, TObject, TSchema, TypeGuard } from '@sinclair/typebox';
 import { TypeCheck } from '@sinclair/typebox/compiler';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ValueError } from '@sinclair/typebox/errors';
-import { ReadableStream as ReadableStream$1 } from 'node:stream/web';
 import * as TypeBoxValue from '@sinclair/typebox/value';
 export { TypeBoxValue };
+import { ReadableStream as ReadableStream$1 } from 'node:stream/web';
 import { Readable } from 'node:stream';
 
 /**
@@ -18,7 +18,7 @@ import { Readable } from 'node:stream';
 declare const KIND: unique symbol;
 
 /**
- * Used for identifying descriptors.
+ * Used for descriptors options.
  *
  * @internal
  */
@@ -36,60 +36,44 @@ type PromiseFn = (...args: any[]) => Promise<any>;
  * Represents a function that returns an async value.
  */
 type AsyncFn = (...args: any[]) => Async<any>;
+type MaybePromise<T> = T extends Promise<any> ? T : Promise<T>;
 
 /**
- * Represents a generic definition type in TypeScript.
+ * In Alepha, a service is a class that can be instantiated. Nothing more, nothing less.
  */
-interface Class<T extends object = any> {
-    new (...args: any[]): T;
-}
+type Service<T extends object = any> = InstantiableService<T> | AbstractService<T>;
+type InstantiableService<T extends object = any> = new (...args: any[]) => T;
+type AbstractService<T extends object = any> = abstract new (...args: any[]) => T;
 /**
- *
+ * Service substitution allows you to register a class as a different class.
  */
-interface ClassSwap<T extends object = any> {
+interface ServiceSubstitution<T extends object = any> {
     /**
-     * Class to register.
+     * Every time someone asks for this service, it will be provided with the 'use' service.
      */
-    provide: Class<T>;
+    provide: Service<T>;
     /**
-     * Class to use AS the provided class.
+     * Service to use instead of the 'provide' service.
+     *
+     * Note: Syntax is based on Angular's DI system.
      */
-    use: Class<T>;
+    use: Service<T>;
     /**
-     * If true, "use" only if class is not already registered.
+     * If true, will not throw an error if the service already exists.
+     * Mostly used for plugins to enforce a substitution without throwing an error.
      */
     default?: boolean;
-    /**
-     * If true, class will be removed if nobody is using it.
-     */
-    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 ClassEntry<T extends object = any> = Class<T> | ClassSwap<T>;
-/**
- * Represents a definition for a class.
- */
-interface ClassProvider<T extends object = any> {
-    /**
-     * The class or type definition to provide.
-     */
-    provide: Class<T>;
-    /**
-     * The class or type definition to use. This will override the 'provide' property.
-     */
-    use?: Class<T>;
-    /**
-     * 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<Class | null>;
-}
+type ServiceEntry<T extends object = any> = Service<T> | ServiceSubstitution<T>;
 
 declare const KEY = "HOOK";
 interface HookOptions<T extends keyof Hooks> {
@@ -101,12 +85,21 @@ interface HookOptions<T extends keyof Hooks> {
      * The handler to run when the hook is triggered.
      */
     handler: (app: Hooks[T]) => Async<any>;
+    /**
+     * Force the hook to run first or last on the list of hooks.
+     */
+    priority?: "first" | "last";
+    /**
+     * Empty placeholder, not working yet. :-)
+     */
     before?: object | Array<object>;
+    /**
+     * Empty placeholder, not working yet. :-)
+     */
     after?: object | Array<object>;
-    priority?: "first" | "last";
 }
 interface Hook<T extends keyof Hooks = any> {
-    caller?: Class;
+    caller?: Service;
     priority?: "first" | "last";
     callback: (payload: Hooks[T]) => Async<void>;
 }
@@ -133,44 +126,114 @@ interface HookDescriptor<T extends keyof Hooks> {
  *
  * Hooks are used to run async functions from all registered providers/services.
  *
- * - You can't unregister a hook once it has been registered.
- * - You can't register a hook after the App has started.
+ * You can't register a hook after the App has started.
  *
  * It's used under the hood by the `configure`, `start`, and `stop` methods.
- * Some modules also use hooks to run their own logic.
+ * Some modules also use hooks to run their own logic. (e.g. `@alepha/server`).
+ *
+ * You can create your own hooks by using module augmentation:
+ *
+ * ```ts
+ * declare module "alepha" {
+ *
+ *   interface Hooks {
+ *     "my:custom:hook": {
+ *       arg1: string;
+ *     }
+ *   }
+ * }
+ *
+ * await alepha.emit("my:custom:hook", { arg1: "value" });
+ * ```
+ *
  */
 declare const $hook: {
     <T extends keyof Hooks>(options: HookOptions<T>): HookDescriptor<T>;
     [KIND]: string;
 };
 
+interface ModuleDescriptorOptions<T extends TSchema> {
+    name: string;
+    version?: string;
+    description?: string;
+    services?: ServiceEntry[] | ((args: Alepha & {
+        env: Static<T>;
+    }) => ServiceEntry[]);
+    env?: T;
+}
+type ModuleDescriptor<T extends TSchema = TSchema> = {
+    [KIND]: "MODULE";
+    [OPTIONS]: ModuleDescriptorOptions<T>;
+};
+/**
+ * This descriptor can be used to define the application metadata and services.
+ */
+declare const $module: <T extends TSchema>(opts: ModuleDescriptorOptions<T>) => ModuleDescriptor<T>;
+interface Module {
+    /**
+     * The name of the module.
+     */
+    name: string;
+    /**
+     * The version of the module.
+     */
+    version?: string;
+    /**
+     * The description of the module.
+     */
+    description?: string;
+    /**
+     * The services provided by the module.
+     */
+    services?: Service[];
+}
+
 /**
- * Used to store the current context and definition during injections.
+ * /!\ Global variable /!\
+ *
+ * Store the current context and definition during injection phase.
  *
  * @internal
  */
 declare const __alephaRef: {
     context?: Alepha;
-    definition?: Class;
+    definition?: Service;
+    module?: Module;
 };
 /**
  * Cursor descriptor.
  */
 interface CursorDescriptor {
     context: Alepha;
-    definition?: Class;
+    definition?: Service;
+    module?: Module;
 }
 /**
  * Get Alepha instance and Class definition from the current context.
- *
  * This should be used inside a descriptor only.
  *
+ * ```ts
+ * import { $cursor } from "@alepha/core";
+ *
+ * const $ = () => {
+ *
+ *   const { context, definition } = $cursor();
+ *
+ *   // context - alepha instance
+ *   // definition - class which is creating this descriptor
+ *
+ *   return {};
+ * }
+ *
+ * ```
+ *
  * @internal
  */
 declare const $cursor: () => CursorDescriptor;
 
 /**
- * Light-weight event emitter like.
+ * Low-cost event emitter like for internal use.
+ * Used only for descriptor implicit registration.
  */
 declare class EventEmitterLike<TEvents extends {
     [key: string]: any;
@@ -179,6 +242,7 @@ declare class EventEmitterLike<TEvents extends {
     on<T extends keyof TEvents>(event: T, callback: (data: TEvents[T]) => void): void;
     emit<T extends keyof TEvents>(event: T, data: TEvents[T]): void;
 }
+
 /**
  * Descriptor events.
  *
@@ -208,7 +272,7 @@ declare const __descriptor: (kind: string) => void;
  */
 declare const __bind: (descriptor: {
     [KIND]: string;
-}, ...to: Class[]) => void;
+}, ...to: Service[]) => void;
 /**
  * Check if the value is a descriptor value.
  *
@@ -242,7 +306,7 @@ interface DescriptorItem<T extends Descriptor> {
 type AsyncLocalStorageData = any;
 declare class AsyncLocalStorageProvider {
     protected als?: AsyncLocalStorage<AsyncLocalStorageData>;
-    configure(): Promise<void>;
+    init(): Promise<void>;
     run<R>(data: AsyncLocalStorageData, callback: () => R): R;
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T): void;
@@ -356,6 +420,7 @@ declare class Logger {
      * @protected
      */
     protected formatJson(level: LogLevel, message: unknown, data?: object | Error | string): string;
+    protected formatJsonError(error: Error): object;
     /**
      * Format a log message to a string.
      *
@@ -365,6 +430,7 @@ declare class Logger {
      * @protected
      */
     protected formatLog(level: LogLevel, message: string, data?: object | Error): string;
+    protected colorize(color: string, text: string, reset?: string): string;
     /**
      * Format an error to a string.
      *
@@ -393,16 +459,19 @@ interface MockLoggerStore {
 interface Env extends LoggerEnv {
     [key: string]: string | boolean | number | undefined;
     /**
-     *
+     * Optional environment variable that indicates the current environment.
      */
     NODE_ENV?: "dev" | "test" | "production";
     /**
-     * Optional name of the application.
+     * Optional name of the application. Same as `state.name`.
      */
     APP_NAME?: string;
     /**
-     * If true, the container will not automatically register the default providers.
-     * Default is false.
+     * If true, the container will not automatically register the default providers based on the descriptors.
+     *
+     * It means that you have to alepha.with(ServiceModule) manually. No magic.
+     *
+     * @default false
      */
     EXPLICIT_PROVIDERS?: boolean;
 }
@@ -418,38 +487,69 @@ interface Hooks {
     echo: any;
     /**
      * Triggered during the configuration phase. Before the start phase.
-     *
-     * - Configuration should technically be called many times without any side effects.
-     * - Spamming Alepha#configure() should not cause any issues.
      */
     configure: Alepha;
     /**
      * Triggered during the start phase. When `Alepha#start()` is called.
-     *
-     * - Start is called only once. It should not be called multiple times.
      */
     start: Alepha;
     /**
      * Triggered during the ready phase. After the start phase.
-     *
-     * - Ready is called only once. It should not be called multiple times.
      */
     ready: Alepha;
     /**
      * Triggered during the stop phase.
      *
-     * - Stop is called only once. It should not be called multiple times.
-     * - Stop should be called after a SIGINT or SIGTERM signal in order to gracefully shutdown the application.
+     * - 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;
+    };
 }
 /**
+ * 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
- * const app = Alepha.create();
+ * import { Alepha, run } from "@alepha/core";
+ *
+ * class MyService {
+ *   // business logic here
+ * }
+ *
+ * const alepha = Alepha.create({
+ *   // state, env, and other properties
+ * })
+ *
+ * alepha.register(MyService);
+ *
+ * run(alepha); // trigger .start (and .stop) automatically
  * ```
+ *
+ * > Some alepha methods are not intended to be used directly, use descriptors instead.
+ *
+ * - $hook -> alepha.on()
+ * - $inject -> alepha.get(), alepha.parseEnv()
  */
 declare class Alepha {
     /**
@@ -460,7 +560,7 @@ declare class Alepha {
     /**
      *  List of all services + how they are provided.
      */
-    protected registry: Map<Class, ClassProvider>;
+    protected registry: Map<Service, Definition>;
     /**
      * Flag indicating whether the App won't accept any further changes.
      * Pass to true when #start() is called.
@@ -479,31 +579,92 @@ declare class Alepha {
      */
     protected ready: boolean;
     /**
-     * The state of the App.
-     */
-    protected _starting?: PromiseWithResolvers<this>;
-    protected _state: State;
-    protected _dependencyStack: Class[];
-    protected _lazyRegistrations: Array<Promise<{
-        default: Class<object>;
-    }>>;
-    protected _cacheEnv: Map<TSchema, any>;
-    protected _cacheTypeCheck: Map<TSchema, TypeCheck<TSchema>>;
-    protected _events: Record<string, Array<Hook>>;
-    readonly als: AsyncLocalStorageProvider;
+     * A promise that resolves when the App has started.
+     */
+    protected starting?: PromiseWithResolvers<this>;
+    /**
+     * The current state of the App.
+     *
+     * It contains the environment variables, logger, and other state-related properties.
+     *
+     * You can declare your own state properties by extending the `State` interface.
+     *
+     * ```ts
+     * declare module "alepha/core" {
+     *   interface State {
+     *     myCustomValue: string;
+     *   }
+     * }
+     * ```
+     *
+     * Same story for the `Env` interface.
+     * ```ts
+     * declare module "@alepha/core" {
+     *   interface Env {
+     *     readonly myCustomValue: string;
+     *   }
+     * }
+     * ```
+     *
+     * State values can be function or primitive values.
+     * However, all .env variables must serializable to JSON.
+     */
+    protected store: 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, any>;
+    /**
+     * Cache for TypeBox type checks.
+     * > It allows us to avoid compiling the same schema multiple times.
+     */
+    protected cacheTypeCheck: Map<TSchema, TypeCheck<TSchema>>;
+    /**
+     * List of events that can be triggered. Powered by $hook().
+     */
+    protected events: Record<string, Array<Hook>>;
+    /**
+     * 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>;
+    /**
+     * 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.
+     */
+    readonly context: AsyncLocalStorageProvider;
+    /**
+     * Get logger instance.
+     */
     get log(): Logger;
-    handle?: (req: any, res: any) => Promise<any>;
     /**
      * The environment variables for the App.
      */
     get env(): Readonly<Env>;
     constructor(state?: Partial<State>);
     /**
-     * State accessor.
+     * Generic handle function used as generic interface for serverless functions.
+     * You should not use this property directly.
+     */
+    handle?: (req: any, res: any) => Promise<any>;
+    /**
+     * State accessor and mutator.
      */
     state<Key extends keyof State>(key: Key, value?: State[Key]): State[Key];
     /**
+     * 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[];
@@ -524,35 +685,50 @@ declare class Alepha {
      */
     isReady(): boolean;
     /**
-     * True when start() is called. No more services can be added.
+     * 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 is running in a serverless environment.
+     *
+     * > Vite developer mode is also considered serverless.
      */
     isServerless(): boolean | "vite" | "vercel";
     /**
      * 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;
     /**
-     * > configure() is automatically called by start().
-     * Use this method only if you need to configure the App without starting it.
+     * Trigger configuration of the App manually.
      *
-     * @internal
+     * > configure() is called automatically when start() is called, you should not need to call it manually.
      */
     configure(): Promise<this | undefined>;
     /**
      * Starts the App.
      *
      * - Lock any further changes to the container.
-     * - Run "configure" hook for all services.
-     * - Run "start" hook for all services.
+     * - 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.
      */
@@ -562,27 +738,38 @@ declare class Alepha {
      *
      * - 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>;
     /**
-     * Returns whether the specified class or type is registered in the container.
-     *
-     * @param injectable - The class or type definition to check.
-     * @param opts - Additional options for the check.
-     * @return True if the class or type is registered in the container, false otherwise.
+     * Check if entry is registered in the container.
      */
-    has(injectable: ClassEntry, opts?: {
-        overridden?: boolean;
-        pending?: boolean;
+    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;
     }): boolean;
     /**
-     * Registers the specified class or type in the container.
+     * Registers the specified service in the container.
      *
-     * - If the class or type is already registered, the method does nothing.
-     * - If the class or type is not registered, a new instance is created and registered.
+     * - If the service is already registered, the method does nothing.
+     * - If the service is not registered, a new instance is created and registered.
      *
-     * ClassEntry allows to provide a class swapping feature.
+     * > ServiceEntry allows to provide a service substitution feature.
      *
      * @example
      * ```ts
@@ -593,51 +780,76 @@ declare class Alepha {
      * Alepha.create().register({ provide: A, use: B }).get(M).a.value; // "b"
      * ```
      *
-     * > Swapping is an advanced feature that allows you to replace a class with another class.
-     * > It's useful for testing or for providing different implementations of a class.
+     * > 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.
      *
-     * @param it - The class or type definitions to register in the container.
-     * @return The current instance of the container.
+     * @param entry - The service to register in the container.
+     * @return Current instance of Alepha.
      */
-    register<T extends object>(it: ClassEntry<T> | Promise<{
-        default: Class<object>;
-    }>): this;
+    register(...entries: Array<ServiceEntry | ModuleDescriptor>): this;
     /**
      * Alias for the 'register' method.
      *
      * @alias {Alepha#register}
      */
-    with: <T extends object>(it: ClassEntry<T> | Promise<{
-        default: Class<object>;
-    }>) => this;
+    with: (...entries: Array<ServiceEntry | ModuleDescriptor>) => this;
     /**
-     * Works like 'Alepha#register' but it must return the instance.
+     * Works like 'Alepha#register' but it will return the instance.
+     *
+     * > This method is used by $inject() under the hood.
      *
-     * @param entry - The class or type definition to retrieve or create.
-     * @param opts
-     * @param opts.parent - The parent class that requested the instance.
      * @return The instance of the specified class or type.
      */
-    get<T extends object>(entry: ClassEntry<T>, opts?: {
-        parent?: Class | null;
+    get<T extends object>(serviceEntry: ServiceEntry<T>, opts?: {
+        /**
+         * Parent service that requested the instance.
+         */
+        parent?: Service | null;
+        /**
+         * Ignore current existing instance.
+         */
         skipCache?: boolean;
+        /**
+         * Don't store the instance in the registry.
+         */
         skipRegistration?: boolean;
+        /**
+         * Constructor arguments to pass when creating a new instance.
+         */
         args?: any[];
     }): T;
+    /**
+     * 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: keyof Hooks, 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>;
     /**
      * Casts the given value to the specified schema.
      *
      * It uses the TypeBox library to validate the value against the schema.
-     *
-     * @param schema - The schema to cast the value to.
-     * @param value - The value to cast.
-     * @param opts - default: true, clean: true, convert: true, decode: true, encode: false
      */
     parse<T extends TSchema>(schema: T, value?: any, opts?: {
         /**
@@ -675,12 +887,6 @@ declare class Alepha {
      * @return The schema object with environment variables applied.
      */
     parseEnv<T extends TObject>(schema: T): Static<T>;
-    /**
-     * Returns all registered services that match the specified descriptor.
-     *
-     * @param descriptor
-     */
-    getDescriptorValues<T extends Descriptor>(descriptor: T): Array<DescriptorItem<T>>;
     /**
      * Create a new instance of a logger.
      *
@@ -688,27 +894,40 @@ declare class Alepha {
      */
     protected createLogger(env: Env): Logger;
     /**
-     * Creates a new instance of a given class with dependency injection.
-     *
-     * @param definition - The class for which to create a new instance.
-     * @param args - The arguments to pass to the class constructor
-     * @returns The newly created instance of the given class.
+     * @internal
      */
-    protected new<T extends object>(definition: Class<T>, args?: any[]): T;
+    getDescriptorValues<T extends Descriptor>(descriptor: T): Array<DescriptorItem<T>>;
     /**
-     * Removes all useless dependencies.
-     *
-     * @protected
+     * @internal
      */
-    protected removeUselessDependencies(): void;
+    protected new<T extends object>(definition: Service<T>, args?: any[]): T;
+    /**
+     * @interface
+     */
+    moduleOf(service: Service): Module | undefined;
 }
-
 /**
- * Symbol to mark a value create from a provider.
- *
- * @internal
+ * This is how we store services in the Alepha container.
  */
-declare const PROVIDER: unique symbol;
+interface Definition<T extends object = any> {
+    /**
+     * The class or type definition to provide.
+     */
+    provide: Service<T>;
+    /**
+     * The class or type definition to use. This will override the 'provide' property.
+     */
+    use?: Service<T>;
+    /**
+     * 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>;
+}
 
 /**
  * Get the instance of the specified type from the context.
@@ -727,42 +946,32 @@ declare const PROVIDER: unique symbol;
  * @returns Instance of the specified type
  */
 declare function $inject<T extends TObject>(type: T): Static<T>;
-declare function $inject<T extends object>(type: Class<T>): T;
-
-declare const $logger: (name?: string) => Logger;
-
+declare function $inject<T extends object>(type: Service<T>): T;
 /**
- * Retry Descriptor options.
+ * @alias $inject
  */
-interface RetryDescriptorOptions<T extends (...args: any[]) => any> {
-    /**
-     * Maximum number of attempts.
-     *
-     * @default 3
-     */
-    max?: number;
-    /**
-     * Delay in milliseconds.
-     *
-     * @default 0
-     */
-    delay?: number;
-    /**
-     *
-     */
-    when?: (error: Error) => boolean;
-    /**
-     *
-     */
-    handler: T;
-}
+declare const $env: typeof $inject;
+
 /**
- * Retry descriptor.
+ * Create a logger.
  *
- * @param opts - Retry descriptor options.
- * @returns A function that will retry the handler.
+ * `name` is optional, by default it will use the name of the service.
+ *
+ * @example
+ * ```ts
+ * import { $logger } from "@alepha/core";
+ *
+ * class MyService {
+ * 	log = $logger();
+ *
+ * 	constructor() {
+ * 	    // print something like 'date - [MyService] Service initialized'
+ * 		this.log.info("Service initialized");
+ * 	}
+ * }
+ * ```
  */
-declare const $retry: <T extends (...args: any[]) => any>(opts: RetryDescriptorOptions<T>) => ((...parameters: Parameters<T>) => Promise<ReturnType<T>>);
+declare const $logger: (name?: string) => Logger;
 
 declare class AppNotStartedError extends Error {
     constructor();
@@ -790,7 +999,7 @@ declare class TypeProvider {
     static DEFAULT_LONG_STRING_MAX_LENGTH: number;
     static DEFAULT_RICH_STRING_MAX_LENGTH: number;
     static DEFAULT_ARRAY_MAX_ITEMS: number;
-    static FormatRegistry: typeof FormatRegistry;
+    static FormatRegistry: typeof TypeBox.FormatRegistry;
     Type: TypeBox.JavaScriptTypeBuilder;
     any: (options?: SchemaOptions) => TypeBox.TAny;
     void: (options?: SchemaOptions) => TypeBox.TVoid;
@@ -857,16 +1066,17 @@ declare class TypeProvider {
     uchar: (options?: IntegerOptions) => TInteger;
     /**
      * Create a schema for an unsigned 32-bit integer.
-     *
-     * @param options
      */
     uint: (options?: IntegerOptions) => TNumber;
     /**
      * Create a schema for a signed 32-bit integer.
-     *
-     * @param options
      */
     int: (options?: IntegerOptions) => TInteger;
+    /**
+     * Create a schema for a bigint. Bigint is a 64-bit integer.
+     * This is a workaround for TypeBox, which does not support bigint natively.
+     */
+    bigint: (options?: IntegerOptions) => TNumber;
     /**
      * Make a schema optional.
      *
@@ -953,32 +1163,104 @@ declare class TypeProvider {
     stream: () => TStream;
 }
 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;
 }
+/**
+ * TypeBox view of FileLike.
+ */
 type TFile = TUnsafe<FileLike>;
-type StreamLike = ReadableStream | ReadableStream$1 | Readable;
-type TStream = TUnsafe<StreamLike>;
-declare const t: TypeProvider;
 declare const isTypeFile: (value: TSchema) => value is TFile;
 declare const isFileLike: (value: any) => value is FileLike;
+type StreamLike = ReadableStream | ReadableStream$1 | Readable | NodeJS.ReadableStream;
+type TStream = TUnsafe<StreamLike>;
 declare const isTypeStream: (value: TSchema) => value is TStream;
 type TextLength = "short" | "long" | "rich";
 interface AlephaStringOptions extends StringOptions {
     size?: TextLength;
 }
+declare const t: TypeProvider;
 declare const isUUID: (value: string) => boolean;
 
-declare const run: (arg: Alepha | Class | ((env?: Env) => Alepha), opts?: {
+declare const substitute: <T extends object>(rule: {
+    provide: T;
+    use: T;
+    default?: boolean;
+}) => {
+    use: T;
+    provide: T;
+    default?: boolean;
+};
+interface RunOptions {
+    /**
+     * Environment variables to be used by the application.
+     * If not provided, it will use the current process environment.
+     */
     env?: Env;
+    /**
+     * A callback that will be executed before the application starts.
+     */
     configure?: (alepha: Alepha) => Async<void>;
+    /**
+     * A callback that will be executed once the application is ready.
+     * This is useful for initializing resources or starting background tasks.
+     */
     ready?: (alepha: Alepha) => Async<void>;
-}) => Alepha;
+    /**
+     * If true, the application will stop after the ready callback is executed.
+     */
+    once?: boolean;
+}
+
+declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
 
-export { $cursor, $hook, $inject, $logger, $retry, Alepha, type AlephaStringOptions, AppNotStartedError, type Async, type AsyncFn, type AsyncLocalStorageData, AsyncLocalStorageProvider, COLORS, CircularDependencyError, type Class, type ClassEntry, type ClassProvider, type ClassSwap, ContainerLockedError, type CursorDescriptor, type Descriptor, type DescriptorIdentifier, type DescriptorItem, type Env, EventEmitterLike, type FileLike, type Hook, type HookDescriptor, type HookOptions, type Hooks, KIND, LEVEL_COLORS, type LogLevel, Logger, type LoggerEnv, type LoggerOptions, MockLogger, type MockLoggerStore, NotImplementedError, OPTIONS, PROVIDER, type PromiseFn, type RetryDescriptorOptions, type State, type StreamLike, type TFile, type TStream, type TextLength, TypeBoxError, TypeProvider, __alephaRef, __bind, __descriptor, descriptorEvents, isDescriptorValue, isFileLike, isTypeFile, isTypeStream, isUUID, run, t };
+export { $cursor, $env, $hook, $inject, $logger, $module, type AbstractService, Alepha, type AlephaStringOptions, AppNotStartedError, type Async, type AsyncFn, type AsyncLocalStorageData, AsyncLocalStorageProvider, COLORS, CircularDependencyError, ContainerLockedError, type CursorDescriptor, type Descriptor, type DescriptorIdentifier, type DescriptorItem, type Env, type FileLike, type Hook, type HookDescriptor, type HookOptions, type Hooks, type InstantiableService, KIND, LEVEL_COLORS, type LogLevel, Logger, type LoggerEnv, type LoggerOptions, type MaybePromise, MockLogger, type MockLoggerStore, type Module, type ModuleDescriptor, type ModuleDescriptorOptions, NotImplementedError, OPTIONS, type PromiseFn, type RunOptions, type Service, type ServiceEntry, type ServiceSubstitution, type State, type StreamLike, type TFile, type TStream, type TextLength, TypeBoxError, TypeProvider, __alephaRef, __bind, __descriptor, descriptorEvents, isDescriptorValue, isFileLike, isTypeFile, isTypeStream, isUUID, run, substitute, t };