alepha 0.9.4 → 0.10.0

package/core.d.ts

@@ -1,11 +1,12 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { TypeCheck } from "@sinclair/typebox/compiler";
-import * as TypeBoxValue from "@sinclair/typebox/value";
-import * as TypeBox from "@sinclair/typebox";
-import { ArrayOptions, FormatRegistry, IntegerOptions, NumberOptions, ObjectOptions, SchemaOptions, Static, Static as Static$1, StaticDecode, StaticEncode, StringOptions, TAny, TAny as TAny$1, TArray, TArray as TArray$1, TBoolean, TBoolean as TBoolean$1, TComposite, TInteger, TIntersect, TNull, TNumber, TNumber as TNumber$1, TObject, TObject as TObject$1, TOmit, TOptional, TOptionalWithFlag, TPartial, TPick, TProperties, TProperties as TProperties$1, TRecord, TRecord as TRecord$1, TSchema, TSchema as TSchema$1, TString, TString as TString$1, TUnion, TUnsafe, TypeGuard, UnsafeOptions } from "@sinclair/typebox";
-import { ValueError } from "@sinclair/typebox/errors";
+import { Validator } from "typebox/compile";
+import * as TypeBox from "typebox";
+import { Static, Static as Static$1, StaticDecode, StaticEncode, TAny, TAny as TAny$1, TArray, TArray as TArray$1, TArrayOptions, TBigInt, TBoolean, TBoolean as TBoolean$1, TInteger, TInteger as TInteger$1, TKeysToIndexer, TNull, TNull as TNull$1, TNumber, TNumber as TNumber$1, TNumberOptions, TNumberOptions as TNumberOptions$1, TObject, TObject as TObject$1, TObjectOptions, TObjectOptions as TObjectOptions$1, TOptional, TOptionalAdd, TOptionalAdd as TOptionalAdd$1, TPick, TProperties, TProperties as TProperties$1, TRecord, TRecord as TRecord$1, TSchema, TSchema as TSchema$1, TSchemaOptions, TString, TString as TString$1, TStringOptions, TStringOptions as TStringOptions$1, TTuple, TUnion, TUnion as TUnion$1, TUnsafe, TVoid } from "typebox";
+import Format from "typebox/format";
+import * as TypeBoxValue from "typebox/value";
 import { Readable } from "node:stream";
 import { ReadableStream as ReadableStream$1 } from "node:stream/web";
+import { TLocalizedValidationError } from "typebox/error";
 
 //#region src/constants/KIND.d.ts
 /**
@@ -118,47 +119,42 @@ declare const $inject: <T extends object>(type: Service<T>, opts?: InjectOptions
 declare class InjectDescriptor extends Descriptor {}
 interface InjectOptions<T extends object = any> {
   /**
-   * Ignore current existing instance.
-   */
-  skipCache?: boolean;
-  /**
-   * Don't store the instance in the registry.
+   * - '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"
    */
-  skipRegistration?: boolean;
+  lifetime?: "transient" | "singleton" | "scoped";
   /**
    * Constructor arguments to pass when creating a new instance.
    */
   args?: ConstructorParameters<InstantiableClass<T>>;
   /**
-   * Parent service that requested the instance.
+   * Parent that requested the instance.
+   *
    * @internal
    */
   parent?: Service | null;
 }
 //#endregion
-//#region src/constants/OPTIONS.d.ts
-/**
- * Used for descriptors options.
- *
- * @internal
- */
-declare const OPTIONS: unique symbol;
-//#endregion
 //#region src/descriptors/$module.d.ts
 /**
- * Wrap services and descriptors into a module.
+ * Wrap Services and Descriptors into a Module.
  *
- * Module is just a class.
- * You must attach a `name` to it.
- *
- * It's recommended to use `project.module.submodule` format.
+ * - A module is just a Service extended {@link Module}.
+ * - You must attach a `name` to it.
+ * - Name must follow the pattern: `project.module.submodule`.
  *
  * @example
  * ```ts
  * import { $module } from "alepha";
  * import { MyService } from "./MyService.ts";
  *
- * // export MyService so it can be used everywhere
+ * // export MyService, so it can be used everywhere
  * export * from "./MyService.ts";
  *
  * export default $module({
@@ -168,9 +164,30 @@ declare const OPTIONS: unique symbol;
  * });
  * ```
  *
- * - Module is used for logging and other purposes.
- * - It's useful for large applications or libraries to group services and descriptors together.
- * - It's probably overkill for small applications.
+ * ## Why Modules?
+ *
+ * ### Logging
+ *
+ * By default, AlephaLogger will log the module name in the logs.
+ * This helps to identify where the logs are coming from.
+ *
+ * You can also set different log levels for different modules.
+ * It means you can set 'some.very.specific.module' to 'debug' and keep the rest of the application to 'info'.
+ *
+ * ### Modulith
+ *
+ * Force to structure your application in modules, even if it's a single deployable unit.
+ * It helps to keep a clean architecture and avoid monolithic applications.
+ *
+ * You can also use `MODULE_INCLUDE` and `MODULE_EXCLUDE` environment variables to load only specific modules.
+ *
+ * A strict mode is planned to enforce module boundaries. Throwing errors when a service from another module is injected.
+ *
+ * ### When not to use Modules?
+ *
+ * Small applications does not need modules. It's better to keep it simple.
+ * Modules are more useful when the application grows and needs to be structured.
+ * If we speak with `$actions`, a module should be used when you have more than 30 actions in a single module.
  */
 declare const $module: (options: ModuleDescriptorOptions) => Service<Module>;
 interface ModuleDescriptorOptions {
@@ -195,16 +212,25 @@ interface ModuleDescriptorOptions {
    */
   register?: (alepha: Alepha) => void;
 }
-interface Module {
-  [KIND]: "MODULE";
-  [OPTIONS]: ModuleDescriptorOptions;
-  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.
+   */
+  static of(ctor: Service): Service<Module> | undefined;
 }
-type ServiceWithModule<T extends object = any> = T & {
+type WithModule<T extends object = any> = T & {
   [MODULE]?: Service;
 };
-declare const isModule: (value: unknown) => value is Module;
-declare const toModuleName: (name: string) => string;
 //#endregion
 //#region src/interfaces/Async.d.ts
 /**
@@ -230,6 +256,45 @@ interface LoggerInterface {
   error(message: string, data?: unknown): void;
 }
 //#endregion
+//#region src/helpers/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: 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>;
+}
+//#endregion
 //#region src/providers/AlsProvider.d.ts
 type AsyncLocalStorageData = any;
 declare class AlsProvider {
@@ -243,6 +308,313 @@ declare class AlsProvider {
   set<T>(key: string, value: T): void;
 }
 //#endregion
+//#region src/helpers/StateManager.d.ts
+declare class StateManager<S extends Record<string, any> = State> {
+  protected store: Partial<S>;
+  protected readonly events?: EventManager;
+  protected readonly als?: AlsProvider;
+  constructor(events?: EventManager, als?: AlsProvider);
+  /**
+   * Get a value from the state with proper typing
+   */
+  get<Key extends keyof S>(key: Key): S[Key] | undefined;
+  /**
+   * Set a value in the state
+   */
+  set<Key extends keyof S>(key: Key, value: S[Key] | undefined): this;
+  /**
+   * Check if a key exists in the state
+   */
+  has<Key extends keyof S>(key: Key): boolean;
+  /**
+   * Delete a key from the state (set to undefined)
+   */
+  del<Key extends keyof S>(key: Key): this;
+  /**
+   * Clear all state
+   */
+  clear(): this;
+  /**
+   * Get all keys that exist in the state
+   */
+  keys(): (keyof S)[];
+}
+//#endregion
+//#region src/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;
+}
+/**
+ * TypeBox view of FileLike.
+ */
+type TFile = TUnsafe<FileLike>;
+declare const isTypeFile: (value: TSchema$1) => value is TFile;
+declare const isFileLike: (value: any) => value is FileLike;
+type StreamLike = ReadableStream | ReadableStream$1 | Readable | NodeJS.ReadableStream;
+type TStream = TUnsafe<StreamLike>;
+//#endregion
+//#region src/providers/TypeProvider.d.ts
+declare class TypeGuard {
+  isSchema: typeof TypeBox.IsSchema;
+  isObject: typeof TypeBox.IsObject;
+  isNumber: typeof TypeBox.IsNumber;
+  isString: typeof TypeBox.IsString;
+  isBoolean: typeof TypeBox.IsBoolean;
+  isAny: typeof TypeBox.IsAny;
+  isArray: typeof TypeBox.IsArray;
+  isOptional: typeof TypeBox.IsOptional;
+  isUnion: typeof TypeBox.IsUnion;
+  isInteger: typeof TypeBox.IsInteger;
+  isNull: typeof TypeBox.IsNull;
+  isUndefined: typeof TypeBox.IsUndefined;
+  isUnsafe: typeof TypeBox.IsUnsafe;
+  isRecord: typeof TypeBox.IsRecord;
+  isTuple: typeof TypeBox.IsTuple;
+  isVoid: typeof TypeBox.IsVoid;
+  isFile: (value: TSchema$1) => value is TFile;
+  isBigInt: (value: TSchema$1) => value is TString$1;
+  isDate: (value: TSchema$1) => value is TString$1;
+  isDatetime: (value: TSchema$1) => value is TString$1;
+  isUuid: (value: TSchema$1) => value is TString$1;
+}
+declare module "typebox" {
+  interface TString {
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+  }
+  interface TNumber {
+    format?: "int64";
+  }
+}
+declare class TypeProvider {
+  static format: typeof Format;
+  static isValidBigInt(value: string | number): boolean;
+  /**
+   * Default maximum length for strings.
+   *
+   * It can be set to a larger value:
+   * ```ts
+   * TypeProvider.DEFAULT_STRING_MAX_LENGTH = 1000000;
+   * TypeProvider.DEFAULT_STRING_MAX_LENGTH = undefined; // no limit (not recommended)
+   * ```
+   */
+  static DEFAULT_STRING_MAX_LENGTH: number | undefined;
+  /**
+   * Maximum length for short strings, such as names or titles.
+   */
+  static DEFAULT_SHORT_STRING_MAX_LENGTH: number | undefined;
+  /**
+   * Maximum length for long strings, such as descriptions or comments.
+   * It can be overridden in the string options.
+   *
+   * It can be set to a larger value:
+   * ```ts
+   * TypeProvider.DEFAULT_LONG_STRING_MAX_LENGTH = 2048;
+   * ```
+   */
+  static DEFAULT_LONG_STRING_MAX_LENGTH: number | undefined;
+  /**
+   * Maximum length for rich strings, such as HTML or Markdown.
+   * This is a large value to accommodate rich text content.
+   * > It's also the maximum length of PG's TEXT type.
+   *
+   * It can be overridden in the string options.
+   *
+   * It can be set to a larger value:
+   * ```ts
+   * TypeProvider.DEFAULT_RICH_STRING_MAX_LENGTH = 1000000;
+   * ```
+   */
+  static DEFAULT_RICH_STRING_MAX_LENGTH: number | undefined;
+  /**
+   * Maximum number of items in an array.
+   * This is a default value to prevent excessive memory usage.
+   * It can be overridden in the array options.
+   */
+  static DEFAULT_ARRAY_MAX_ITEMS: number;
+  raw: typeof TypeBox.Type;
+  any: typeof TypeBox.Any;
+  void: typeof TypeBox.Void;
+  undefined: typeof TypeBox.Undefined;
+  record: typeof TypeBox.Record;
+  omit: typeof TypeBox.Omit;
+  partial: typeof TypeBox.Partial;
+  union: typeof TypeBox.Union;
+  pick: typeof TypeBox.Pick;
+  tuple: typeof TypeBox.Tuple;
+  interface: typeof TypeBox.Interface;
+  readonly schema: TypeGuard;
+  /**
+   * Create a schema for an object.
+   */
+  object<T extends TProperties$1>(properties: T, options?: TObjectOptions$1): TObject$1<T>;
+  /**
+   * Create a schema for an array.
+   *
+   * @param schema
+   * @param options
+   */
+  array<T extends TSchema$1>(schema: T, options?: TArrayOptions): TArray$1<T>;
+  /**
+   * Create a schema for a string.
+   */
+  string(options?: AlephaStringOptions): TString$1;
+  /**
+   * Create a schema for a JSON object.
+   * This is a record with string keys and any values.
+   */
+  json(options?: TSchemaOptions): TRecord$1<string, TAny$1>;
+  /**
+   * Create a schema for a boolean.
+   */
+  boolean(options?: TSchemaOptions): TBoolean$1;
+  /**
+   * Create a schema for a number.
+   */
+  number(options?: TNumberOptions$1): TNumber$1;
+  /**
+   * Create a schema for a signed 32-bit integer.
+   */
+  int(options?: TNumberOptions$1): TInteger$1;
+  /**
+   * Mimic a signed 64-bit integer.
+   *
+   * This is NOT a true int64, as JavaScript cannot represent all int64 values.
+   * It is a number that is an integer and between -9007199254740991 and 9007199254740991.
+   * Use `t.bigint()` for true int64 values represented as strings.
+   */
+  int64(options?: TNumberOptions$1): TNumber$1;
+  /**
+   * Make a schema optional.
+   */
+  optional<T extends TSchema$1>(schema: T): TOptionalAdd$1<T>;
+  /**
+   * Make a schema nullable.
+   */
+  nullable<T extends TSchema$1>(schema: T, options?: TObjectOptions$1): TUnion$1<[TNull$1, T]>;
+  /**
+   * Create a schema that maps all properties of an object schema to nullable.
+   */
+  nullify: <T extends TSchema$1>(schema: T, options?: TObjectOptions$1) => TypeBox.TMappedInstantiate<{}, {
+    callstack: [];
+  }, TypeBox.TIdentifier<"K">, TypeBox.TKeyOfInstantiate<{}, {
+    callstack: [];
+  }, T>, TypeBox.TRef<"K">, TUnion$1<[TypeBox.TIndexInstantiate<{}, {
+    callstack: [];
+  }, T, TypeBox.TRef<"K">>, TNull$1]>>;
+  /**
+   * Create a schema for a string enum.
+   */
+  enum<T extends string[]>(values: [...T], options?: TStringOptions$1): TUnsafe<T[number]>;
+  /**
+   * Create a schema for a bigint.
+   * This is NOT a BigInt object, but a string that represents a bigint.
+   */
+  bigint(options?: TStringOptions$1): TString$1;
+  /**
+   * Create a schema for a datetime.
+   * This is NOT a Date object, but a string in ISO 8601 format.
+   */
+  datetime(options?: TStringOptions$1): TString$1;
+  /**
+   * Create a schema for a date.
+   * This is NOT a Date object, but a string in ISO 8601 date format (YYYY-MM-DD).
+   */
+  date(options?: TStringOptions$1): TString$1;
+  /**
+   * Create a schema for a url.
+   */
+  url(options?: TStringOptions$1): TString$1;
+  /**
+   * Create a schema for uuid.
+   */
+  uuid(options?: TStringOptions$1): TString$1;
+  /**
+   * Create a schema for a file-like object.
+   *
+   * File like mimics the File API in browsers, but is adapted to work in Node.js as well.
+   *
+   * Implementation of file-like objects is handled by "alepha/file" package.
+   */
+  file(options?: {
+    maxSize?: number;
+  }): TFile;
+  /**
+   * @experimental
+   */
+  stream(): TStream;
+  /**
+   * Create a schema for a string enum e.g. LIKE_THIS.
+   *
+   * @param options
+   */
+  snakeCase: (options?: TStringOptions$1) => TString$1;
+  /**
+   * Create a schema for an object with a value and label.
+   */
+  valueLabel: (options?: TObjectOptions$1) => TObject$1<{
+    value: TString$1;
+    label: TString$1;
+    description: TypeBox.TOptional<TString$1>;
+  }>;
+}
+type TextLength = "short" | "long" | "rich";
+interface AlephaStringOptions extends TStringOptions$1 {
+  size?: TextLength;
+}
+declare const t: TypeProvider;
+//#endregion
 //#region src/Alepha.d.ts
 /**
  * Core container of the Alepha framework.
@@ -350,7 +722,7 @@ declare class AlsProvider {
  * Alepha.create()
  * 	 .with(App)
  * 	 .start()
- * 	 .then(alepha => alepha.emit("my:custom:hook"));
+ * 	 .then(alepha => alepha.events.emit("my:custom:hook"));
  * ```
  *
  * 	Hooks are fully typed. You can create your own hooks by using module augmentation:
@@ -364,6 +736,8 @@ declare class AlsProvider {
  * 		}
  * 	}
  * 	```
+ *
+ * 	@module alepha
  */
 declare class Alepha {
   /**
@@ -437,16 +811,12 @@ declare class Alepha {
    * Cache for environment variables.
    * > It allows us to avoid parsing the same schema multiple times.
    */
-  protected cacheEnv: Map<TSchema$1, any>;
+  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$1, TypeCheck<TSchema$1>>;
-  /**
-   * List of events that can be triggered. Powered by $hook().
-   */
-  protected events: Record<string, Array<Hook>>;
+  protected cacheTypeCheck: Map<TSchema, Validator>;
   /**
    * List of modules that are registered in the container.
    *
@@ -465,7 +835,15 @@ declare class Alepha {
    *
    * Mocked for browser environments.
    */
-  readonly context: AlsProvider;
+  readonly context: AlsProvider;
+  /**
+   * Event manager to handle lifecycle events and custom events.
+   */
+  readonly events: EventManager;
+  /**
+   * State manager to store arbitrary values.
+   */
+  readonly state: StateManager<State>;
   /**
    * Get logger instance.
    */
@@ -475,10 +853,6 @@ declare class Alepha {
    */
   get env(): Readonly<Env>;
   constructor(state?: Partial<State>);
-  /**
-   * State accessor and mutator.
-   */
-  state<Key extends keyof State>(key: Key, value?: State[Key]): State[Key];
   /**
    * True when start() is called.
    *
@@ -556,15 +930,27 @@ declare class Alepha {
     /**
      * Check if the entry is registered in the pending instantiation stack.
      *
-     * Default: true
+     * @default true
      */
     inStack?: boolean;
     /**
      * Check if the entry is registered in the container registry.
      *
-     * Default: true
+     * @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.
@@ -596,14 +982,9 @@ declare class Alepha {
     default: ServiceEntry<T>;
   }): this;
   /**
-   * Get the instance of the specified service and apply some changes, depending on the options.
-   * - If the service is already registered, it will return the existing instance. (except if `skipCache` is true)
-   * - If the service is not registered, it will create a new instance and register it. (except if `skipRegistration` is true)
-   * - New instance can be created with custom constructor arguments. (`args` option)
+   * Get an instance of the specified service from the container.
    *
-   * > This method is used by $inject() under the hood.
-   *
-   * @return The instance of the specified class or type.
+   * @see {@link InjectOptions} for the available options.
    */
   inject<T extends object>(service: Service<T>, opts?: InjectOptions<T>): T;
   /**
@@ -626,40 +1007,12 @@ declare class Alepha {
   configure<T extends {
     options: object;
   }>(service: Service<T>, state: Partial<T["options"]>): this;
-  /**
-   * 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.
    */
-  parse<T extends TSchema$1>(schema: T, value?: any, opts?: {
+  parse<T extends TSchema>(schema: T, value?: unknown, opts?: {
     /**
      * Clone the value before parsing.
      * @default true
@@ -680,6 +1033,11 @@ declare class Alepha {
      * @default true
      */
     convert?: boolean;
+    /**
+     * Convert `null` to `undefined`
+     * @default true
+     */
+    convertNullToUndefined?: boolean;
     /**
      * Prepare value after being deserialized.
      * @default true
@@ -729,10 +1087,6 @@ interface ServiceDefinition<T extends object = any> {
    * List of classes which use this class.
    */
   parents: Array<Service | null>;
-  /**
-   * If the service is provided by a module, the module definition.
-   */
-  module?: Service;
 }
 interface Env {
   [key: string]: string | boolean | number | undefined;
@@ -828,15 +1182,13 @@ interface RunOptions {
   cluster?: boolean;
 }
 //#endregion
-//#region src/constants/PRIMITIVE.d.ts
+//#region src/constants/OPTIONS.d.ts
 /**
- * Symbol to mark a value as a primitive.
- *
- * Used to enhance TypeBox types with metadata. See @alepha/protobuf.
+ * Used for descriptors options.
  *
  * @internal
  */
-declare const PRIMITIVE: unique symbol;
+declare const OPTIONS: unique symbol;
 //#endregion
 //#region src/descriptors/$cursor.d.ts
 /**
@@ -949,7 +1301,7 @@ declare const $env: <T extends TObject$1>(type: T) => Static$1<T>;
  *   }
  * }
  *
- * await alepha.emit("my:custom:hook", { arg1: "value" });
+ * await alepha.events.emit("my:custom:hook", { arg1: "value" });
  * ```
  *
  */
@@ -993,295 +1345,36 @@ declare class AlephaError extends Error {
 }
 //#endregion
 //#region src/errors/AppNotStartedError.d.ts
-declare class AppNotStartedError extends Error {
+declare class AppNotStartedError extends AlephaError {
   readonly name = "AppNotStartedError";
   constructor();
 }
 //#endregion
 //#region src/errors/CircularDependencyError.d.ts
-declare class CircularDependencyError extends Error {
+declare class CircularDependencyError extends AlephaError {
   readonly name = "CircularDependencyError";
   constructor(provider: string, parents?: string[]);
 }
 //#endregion
 //#region src/errors/ContainerLockedError.d.ts
-declare class ContainerLockedError extends Error {
+declare class ContainerLockedError extends AlephaError {
   readonly name = "ContainerLockedError";
   constructor(message?: string);
 }
 //#endregion
-//#region src/errors/TypeBoxError.d.ts
-declare class TypeBoxError extends Error {
-  readonly name = "TypeBoxError";
-  readonly value: ValueError;
-  constructor(value: ValueError);
+//#region src/errors/TooLateSubstitutionError.d.ts
+declare class TooLateSubstitutionError extends AlephaError {
+  readonly name = "TooLateSubstitutionError";
+  constructor(original: string, substitution: string);
 }
 //#endregion
-//#region src/providers/TypeProvider.d.ts
-declare class TypeProvider {
-  /**
-   * Default maximum length for strings.
-   *
-   * It can be set to a larger value:
-   * ```ts
-   * TypeProvider.DEFAULT_STRING_MAX_LENGTH = 1000000;
-   * TypeProvider.DEFAULT_STRING_MAX_LENGTH = undefined; // no limit (not recommended)
-   * ```
-   */
-  static DEFAULT_STRING_MAX_LENGTH: number | undefined;
-  static DEFAULT_SHORT_STRING_MAX_LENGTH: number | undefined;
-  /**
-   * Maximum length for long strings, such as descriptions or comments.
-   * It can be overridden in the string options.
-   *
-   * It can be set to a larger value:
-   * ```ts
-   * TypeProvider.DEFAULT_LONG_STRING_MAX_LENGTH = 2048;
-   * ```
-   */
-  static DEFAULT_LONG_STRING_MAX_LENGTH: number | undefined;
-  /**
-   * Maximum length for rich strings, such as HTML or Markdown.
-   * This is a large value to accommodate rich text content.
-   * > It's also the maximum length of PG's TEXT type.
-   *
-   * It can be overridden in the string options.
-   *
-   * It can be set to a larger value:
-   * ```ts
-   * TypeProvider.DEFAULT_RICH_STRING_MAX_LENGTH = 1000000;
-   * ```
-   */
-  static DEFAULT_RICH_STRING_MAX_LENGTH: number | undefined;
-  /**
-   * Maximum number of items in an array.
-   * This is a default value to prevent excessive memory usage.
-   * It can be overridden in the array options.
-   */
-  static DEFAULT_ARRAY_MAX_ITEMS: number;
-  static FormatRegistry: typeof FormatRegistry;
-  raw: TypeBox.JavaScriptTypeBuilder;
-  any: (options?: SchemaOptions) => TAny$1;
-  void: (options?: SchemaOptions) => TypeBox.TVoid;
-  undefined: (options?: SchemaOptions) => TypeBox.TUndefined;
-  record: <Key extends TSchema$1, Value extends TSchema$1>(key: Key, value: Value, options?: ObjectOptions) => TypeBox.TRecordOrObject<Key, Value>;
-  omit: {
-    <Type extends TSchema$1, Key extends PropertyKey[]>(type: Type, key: readonly [...Key], options?: SchemaOptions): TOmit<Type, Key>;
-    <Type extends TSchema$1, Key extends TSchema$1>(type: Type, key: Key, options?: SchemaOptions): TOmit<Type, Key>;
-  };
-  partial: {
-    <MappedResult extends TypeBox.TMappedResult>(type: MappedResult, options?: SchemaOptions): TypeBox.TPartialFromMappedResult<MappedResult>;
-    <Type extends TSchema$1>(type: Type, options?: SchemaOptions): TPartial<Type>;
-  };
-  union: <Types extends TSchema$1[]>(types: [...Types], options?: SchemaOptions) => TypeBox.Union<Types>;
-  composite: <T extends TSchema$1[]>(schemas: [...T], options?: ObjectOptions) => TComposite<T>;
-  pick: {
-    <Type extends TSchema$1, Key extends PropertyKey[]>(type: Type, key: readonly [...Key], options?: SchemaOptions): TPick<Type, Key>;
-    <Type extends TSchema$1, Key extends TSchema$1>(type: Type, key: Key, options?: SchemaOptions): TPick<Type, Key>;
-  };
-  /**
-   * Create a schema for an object.
-   *
-   * @param properties The properties of the object.
-   * @param options The options for the object.
-   */
-  object<T extends TProperties$1>(properties: T, options?: ObjectOptions): TObject$1<T>;
-  /**
-   * Create a schema for an array.
-   *
-   * @param schema
-   * @param options
-   */
-  array<T extends TSchema$1>(schema: T, options?: ArrayOptions): TArray$1<T>;
-  /**
-   * Create a schema for a string.
-   *
-   * @param options
-   */
-  string(options?: AlephaStringOptions): TString$1;
-  /**
-   * Create a schema for a JSON object.
-   *
-   * @param options
-   */
-  json(options?: SchemaOptions): TRecord$1<TString$1, TAny$1>;
-  /**
-   * Create a schema for a boolean.
-   *
-   * @param options
-   */
-  boolean(options?: SchemaOptions): TBoolean$1;
-  /**
-   * Create a schema for a number.
-   *
-   * @param options
-   */
-  number(options?: NumberOptions): TNumber$1;
-  /**
-   * Create a schema for an unsigned 8-bit integer.
-   *
-   * @param options
-   */
-  uchar(options?: IntegerOptions): TInteger;
-  /**
-   * Create a schema for an unsigned 32-bit integer.
-   */
-  uint(options?: IntegerOptions): TNumber$1;
-  /**
-   * Create a schema for a signed 32-bit integer.
-   */
-  int(options?: IntegerOptions): TInteger;
-  /**
-   * Create a schema for a signed 32-bit integer.
-   */
-  integer(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?: NumberOptions): TNumber$1;
-  /**
-   * Make a schema optional.
-   *
-   * @param schema The schema to make optional.
-   */
-  optional<T extends TSchema$1>(schema: T): TOptionalWithFlag<T, true>;
-  /**
-   * Make a schema nullable.
-   *
-   * @param schema The schema to make nullable.
-   * @param options The options for the schema.
-   */
-  nullable<T extends TSchema$1>(schema: T, options?: ObjectOptions): TUnion<[TNull, T]>;
-  nullify: <T extends TSchema$1>(schema: T, options?: ObjectOptions) => TObject$1<TypeBox.Evaluate<TypeBox.TMappedFunctionReturnType<TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>>, TUnion<[TNull, TypeBox.TMappedResult<TypeBox.Evaluate<TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>> extends infer T_1 ? T_1 extends TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>> ? T_1 extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? /*elided*/any : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : {} : never : never>>]>, {}>>>;
-  /**
-   * Map a schema to another schema.
-   *
-   * @param schema The schema to map.
-   * @param operations The operations to perform on the schema.
-   * @param options The options for the schema.
-   * @returns The mapped schema.
-   */
-  map<T extends TObject$1 | TIntersect, Omit extends (keyof T["properties"])[], Optional extends (keyof T["properties"])[]>(schema: T, operations: {
-    omit: readonly [...Omit];
-    optional: [...Optional];
-  }, options?: ObjectOptions): TComposite<[TOmit<T, [...Omit, ...Optional]>, TPartial<TPick<T, Optional>>]>;
-  /**
-   * Create a schema for a string enum.
-   *
-   * @param values
-   * @param options
-   */
-  enum<T extends string[]>(values: [...T], options?: StringOptions): TUnsafe<T[number]>;
-  /**
-   * Create a schema for a datetime.
-   *
-   * @param options The options for the date.
-   */
-  datetime(options?: StringOptions): TString$1;
-  /**
-   * Create a schema for a date.
-   *
-   * @param options
-   */
-  date(options?: StringOptions): TString$1;
-  /**
-   * Create a schema for uuid.
-   *
-   * @param options The options for the duration.
-   */
-  uuid(options?: StringOptions): TString$1;
-  unsafe<T>(kind: string, options?: UnsafeOptions): TUnsafe<T>;
-  file(options?: {
-    max?: number;
-  }): TFile;
-  stream(): TStream;
-  /**
-   * Create a schema for a string enum e.g. LIKE_THIS.
-   *
-   * @param options
-   */
-  snakeCase: (options?: StringOptions) => TString$1;
-  /**
-   * Create a schema for an object with a value and label.
-   */
-  valueLabel: (options?: ObjectOptions) => TObject$1<{
-    value: TString$1;
-    label: TString$1;
-    description: TypeBox.TOptional<TString$1>;
-  }>;
-}
-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>;
-declare const isTypeFile: (value: TSchema$1) => 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$1) => value is TStream;
-type TextLength = "short" | "long" | "rich";
-interface AlephaStringOptions extends StringOptions {
-  size?: TextLength;
+//#region src/errors/TypeBoxError.d.ts
+declare class TypeBoxError extends AlephaError {
+  readonly name = "TypeBoxError";
+  readonly cause: TLocalizedValidationError;
+  readonly value: any;
+  constructor(error: TLocalizedValidationError, value: any);
 }
-declare const t: TypeProvider;
-declare function isISODate(str: string): boolean;
-declare function isISODateTime(value: string): boolean;
-declare function isUUID(value: string): boolean;
-declare function isEmail(value: string): boolean;
 //#endregion
 //#region src/index.d.ts
 declare global {
@@ -1297,5 +1390,5 @@ declare global {
  */
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => void;
 //#endregion
-export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlephaStringOptions, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, ContainerLockedError, CursorDescriptor, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, PRIMITIVE, Service, ServiceEntry, ServiceSubstitution, ServiceWithModule, State, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, type TBoolean, TFile, type TNumber, type TObject, type TOptional, type TProperties, type TRecord, type TSchema, TStream, type TString, TextLength, TypeBox, TypeBoxError, TypeBoxValue, TypeGuard, TypeProvider, __alephaRef, createDescriptor, isEmail, isFileLike, isISODate, isISODateTime, isModule, isTypeFile, isTypeStream, isUUID, run, t, toModuleName };
+export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlephaStringOptions, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, ContainerLockedError, CursorDescriptor, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, Service, ServiceEntry, ServiceSubstitution, State, StateManager, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, type TBigInt, type TBoolean, TFile, type TInteger, type TKeysToIndexer, type TNull, type TNumber, type TNumberOptions, type TObject, type TObjectOptions, type TOptional, type TOptionalAdd, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, type TTuple, type TUnion, type TVoid, TextLength, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxValue, TypeGuard, TypeProvider, WithModule, __alephaRef, createDescriptor, isFileLike, isTypeFile, run, t };
 //# sourceMappingURL=index.d.ts.map