@alepha/protobuf 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -1,11 +1,1009 @@
-import * as alepha0 from "alepha";
-import { Alepha, SchemaCodec, Static, TObject, TSchema } from "alepha";
+import * as typebox0 from "typebox";
+import { Static, StaticDecode as Static$1, StaticEncode, TArray, TArray as TArray$1, TBoolean, TInteger, TObject, TObject as TObject$1, TOptional, TOptionalAdd, TRecord, TSchema, TSchema as TSchema$1, TString, TUnsafe } from "typebox";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Validator } from "typebox/compile";
 import protobufjs, { Type } from "protobufjs";
 
+//#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
+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/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/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 src/providers/ProtobufProvider.d.ts
 declare class ProtobufProvider {
   protected readonly alepha: Alepha;
-  protected readonly schemas: Map<string | TObject, Type>;
+  protected readonly schemas: Map<string | TObject$1, Type>;
   protected readonly protobuf: typeof protobufjs;
   protected readonly enumDefinitions: Map<string, string[]>;
   /**
@@ -23,27 +1021,27 @@ declare class ProtobufProvider {
   /**
    * Convert a TypeBox schema to a Protobuf schema as a string.
    */
-  createProtobufSchema(schema: TSchema, options?: CreateProtobufSchemaOptions): string;
+  createProtobufSchema(schema: TSchema$1, options?: CreateProtobufSchemaOptions): string;
   /**
    * Parse an object schema with dependencies (sub-messages).
    */
-  protected parseObjectWithDependencies(obj: TSchema, parentName: string): {
+  protected parseObjectWithDependencies(obj: TSchema$1, parentName: string): {
     message: string;
     subMessages: string[];
   };
   /**
    * Convert a primitive TypeBox schema type to a Protobuf spec type.
    */
-  protected convertType(schema: TSchema): string;
+  protected convertType(schema: TSchema$1): string;
   /**
    * Check if a schema is an enum type.
    * TypeBox enums have an "enum" property with an array of values.
    */
-  protected isEnum(schema: TSchema): boolean;
+  protected isEnum(schema: TSchema$1): boolean;
   /**
    * Extract enum values from a TypeBox enum schema.
    */
-  protected getEnumValues(schema: TSchema): string[];
+  protected getEnumValues(schema: TSchema$1): string[];
   /**
    * Register an enum and return its type name.
    * Generates a PascalCase name from the field name.
@@ -73,31 +1071,31 @@ interface CreateProtobufSchemaOptions {
 declare class ProtobufSchemaCodec extends SchemaCodec {
   protected protobufProvider: ProtobufProvider;
   protected decoder: TextDecoder;
-  encodeToString<T extends TSchema>(schema: T, value: Static<T>): string;
-  encodeToBinary<T extends TSchema>(schema: T, value: Static<T>): Uint8Array;
-  decode<T>(schema: TSchema, value: unknown): T;
+  encodeToString<T extends TSchema$1>(schema: T, value: Static$1<T>): string;
+  encodeToBinary<T extends TSchema$1>(schema: T, value: Static$1<T>): Uint8Array;
+  decode<T>(schema: TSchema$1, value: unknown): T;
   /**
    * Apply proto3 default values for fields that were omitted during encoding.
    * Proto3 omits fields with default values, so we need to restore them.
    * Also converts enum integers back to their string values.
    */
-  protected applyProto3Defaults(schema: TSchema, value: any): any;
+  protected applyProto3Defaults(schema: TSchema$1, value: any): any;
   /**
    * Check if a schema is an enum type.
    */
-  protected isEnum(schema: TSchema): boolean;
+  protected isEnum(schema: TSchema$1): boolean;
   /**
    * Convert an enum value from protobuf integer to TypeBox string.
    */
-  protected convertEnumValue(schema: TSchema, value: any): any;
+  protected convertEnumValue(schema: TSchema$1, value: any): any;
   /**
    * Get the proto3 default value for a schema type.
    */
-  protected getProto3Default(schema: TSchema): any;
+  protected getProto3Default(schema: TSchema$1): any;
 }
 //#endregion
 //#region src/index.d.ts
-declare const AlephaProtobuf: alepha0.Service<alepha0.Module>;
+declare const AlephaProtobuf: Service<Module>;
 //#endregion
 export { AlephaProtobuf, CreateProtobufSchemaOptions, ProtobufProvider, ProtobufSchema, ProtobufSchemaCodec };
 //# sourceMappingURL=index.d.cts.map