alepha 0.11.5 → 0.11.7

package/core.d.ts

@@ -1,9 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Validator } from "typebox/compile";
-import * as TypeBoxValue from "typebox/value";
 import * as TypeBox from "typebox";
-import { Static as Static$1, StaticDecode, StaticDecode as Static, StaticDecode as StaticDecode$1, StaticEncode, StaticEncode as StaticEncode$1, TAny, TAny as TAny$1, TArray, TArray as TArray$1, TArrayOptions, TBigInt, TBoolean, TBoolean as TBoolean$1, TInteger, TInteger as TInteger$1, TKeysToIndexer, TKeysToIndexer as TKeysToIndexer$1, 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, TOmit, TOptional, TOptionalAdd, TOptionalAdd as TOptionalAdd$1, TPick, TPick as TPick$1, 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, TUnsafe as TUnsafe$1, TVoid } from "typebox";
+import { Static as Static$1, StaticDecode, StaticDecode as Static, StaticEncode, StaticEncode as StaticEncode$1, TAny, TAny as TAny$1, TArray, TArray as TArray$1, TArrayOptions, TBigInt, TBoolean, TBoolean as TBoolean$1, TInteger, TInteger as TInteger$1, TInterface, TKeysToIndexer, TKeysToIndexer as TKeysToIndexer$1, 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, TOmit, TOptional, TOptionalAdd, TOptionalAdd as TOptionalAdd$1, TPartial, TPick, TPick as TPick$1, 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, TUnsafe as TUnsafe$1, TVoid } from "typebox";
 import TypeBoxFormat from "typebox/format";
+import * as TypeBoxValue from "typebox/value";
 import { TLocalizedValidationError } from "typebox/error";
 import { Readable } from "node:stream";
 import { ReadableStream as ReadableStream$1 } from "node:stream/web";
@@ -147,16 +147,16 @@ interface InjectOptions<T extends object = any> {
 /**
  * Wrap Services and Descriptors into a Module.
  *
- * - A module is just a Service extended {@link Module}.
+ * - A module is just a Service with some extra {@link Module}.
  * - You must attach a `name` to it.
- * - Name must follow the pattern: `project.module.submodule`.
+ * - Name must follow the pattern: `project.module.submodule`. (e.g. `myapp.users.auth`).
  *
  * @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 (optional)
  * export * from "./MyService.ts";
  *
  * export default $module({
@@ -166,9 +166,9 @@ interface InjectOptions<T extends object = any> {
  * });
  * ```
  *
- * ## Why Modules?
+ * ### Why Modules?
  *
- * ### Logging
+ * #### Logging
  *
  * By default, AlephaLogger will log the module name in the logs.
  * This helps to identify where the logs are coming from.
@@ -176,23 +176,24 @@ interface InjectOptions<T extends object = any> {
  * 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
+ * #### 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.
+ * A strict mode flag will probably come to enforce module boundaries.
+ * -> Throwing errors when a service from another module is injected.
+ * But it's not implemented yet.
  *
  * ### 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.
+ * If we speak with number of `$actions`, a module should be used when you have more than 30 actions in a single module.
+ * Meaning that if you have 100 actions, you should have at least 3 modules.
  */
-declare const $module: <T extends object = {}>(options: ModuleDescriptorOptions<T>) => Service<Module<T>>;
-interface ModuleDescriptorOptions<T extends object> {
+declare const $module: <T extends object = {}>(options: ModuleDescriptorOptions) => Service<Module>;
+interface ModuleDescriptorOptions {
   /**
    * Name of the module.
    *
@@ -200,7 +201,10 @@ interface ModuleDescriptorOptions<T extends object> {
    */
   name: string;
   /**
-   * List of services to register in the module.
+   * 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>;
   /**
@@ -208,29 +212,35 @@ interface ModuleDescriptorOptions<T extends object> {
    */
   descriptors?: Array<DescriptorFactoryLike>;
   /**
-   * By default, module will register all services.
+   * 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, options: T) => void;
+  register?: (alepha: Alepha) => void;
 }
 /**
  * Base class for all modules.
  */
-declare abstract class Module<T extends object = {}> {
-  abstract readonly config: ModuleDescriptorOptions<T>;
+declare abstract class Module {
+  abstract readonly options: ModuleDescriptorOptions;
   abstract register(alepha: Alepha): void;
   static NAME_REGEX: RegExp;
-  options: T;
   /**
    * 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;
 }
+/**
+ * Helper type to add Module metadata to a Service.
+ */
 type WithModule<T extends object = any> = T & {
   [MODULE]?: Service;
 };
@@ -372,8 +382,11 @@ type TStream = TUnsafe$1<StreamLike>;
 declare const isUUID: typeof TypeBoxFormat.IsUuid;
 declare const isEmail: typeof TypeBoxFormat.IsEmail;
 declare const isURL: typeof TypeBoxFormat.IsUrl;
+declare const isDateTime: typeof TypeBoxFormat.IsDateTime;
+declare const isDate: typeof TypeBoxFormat.IsDate;
+declare const isTime: typeof TypeBoxFormat.IsTime;
+declare const isDuration: typeof TypeBoxFormat.IsDuration;
 declare class TypeGuard {
-  isFile: (value: TSchema$1) => value is TFile;
   isBigInt: (value: TSchema$1) => value is TString$1;
   isUUID: (value: TSchema$1) => value is TString$1;
   isObject: typeof TypeBox.IsObject;
@@ -393,6 +406,11 @@ declare class TypeGuard {
   isVoid: typeof TypeBox.IsVoid;
   isLiteral: typeof TypeBox.IsLiteral;
   isSchema: typeof TypeBox.IsSchema;
+  isFile: (value: TSchema$1) => value is TFile;
+  isDateTime: (schema: unknown) => boolean;
+  isDate: (schema: unknown) => boolean;
+  isTime: (schema: unknown) => boolean;
+  isDuration: (schema: unknown) => boolean;
 }
 declare module "typebox" {
   interface TString {
@@ -457,13 +475,11 @@ declare class TypeProvider {
   void: typeof TypeBox.Void;
   undefined: typeof TypeBox.Undefined;
   record: typeof TypeBox.Record;
-  partial: typeof TypeBox.Partial;
   union: typeof TypeBox.Union;
   tuple: typeof TypeBox.Tuple;
-  interface: typeof TypeBox.Interface;
   null: typeof TypeBox.Null;
   const: typeof TypeBox.Literal;
-  codec: typeof TypeBox.Codec;
+  options: typeof TypeBox.Options;
   /**
    * Type guards to check the type of schema.
    * This is not a runtime type check, but a compile-time type guard.
@@ -476,8 +492,11 @@ declare class TypeProvider {
    * ```
    */
   readonly schema: TypeGuard;
+  extend<T extends TSchema$1[], U$1 extends TProperties$1>(schema: [...T], properties: U$1, options?: TSchemaOptions): TInterface<T, U$1>;
+  extend<T extends TObject$1, U$1 extends TProperties$1>(schema: T, properties: U$1, options?: TSchemaOptions): TInterface<[T], U$1>;
   pick<T extends TObject$1, Indexer extends PropertyKey[]>(schema: T, keys: [...Indexer], options?: TObjectOptions$1): TPick$1<T, TKeysToIndexer$1<Indexer>>;
   omit<T extends TObject$1, Indexer extends PropertyKey[]>(schema: T, keys: [...Indexer], options?: TObjectOptions$1): TOmit<T, TKeysToIndexer$1<Indexer>>;
+  partial<T extends TSchema$1>(schema: T, options?: TSchemaOptions): TPartial<T>;
   /**
    * Create a schema for an object.
    * By default, additional properties are not allowed.
@@ -564,18 +583,18 @@ declare class TypeProvider {
    */
   enum<T extends string[]>(values: [...T], options?: TStringOptions$1): TUnsafe$1<T[number]>;
   /**
-   * Create a schema for a bigint.
-   * This is NOT a BigInt object, but a string that represents a bigint.
+   * Create a schema for a bigint represented as a string.
+   * This is a string that validates bigint format (e.g. "123456789").
    */
-  bigint(options?: TStringOptions$1): TypeBox.TCodec<TString$1, bigint>;
+  bigint(options?: TStringOptions$1): TString$1;
   /**
-   * Create a schema for a url.
+   * Create a schema for a URL represented as a string.
    */
-  url(options?: TStringOptions$1): TypeBox.TCodec<TString$1, URL>;
+  url(options?: TStringOptions$1): TString$1;
   /**
-   * Create a schema for binary data represented as a string.
+   * Create a schema for binary data represented as a base64 string.
    */
-  binary(options: TStringOptions$1): TypeBox.TCodec<TString$1, Uint8Array<ArrayBuffer>>;
+  binary(options: TStringOptions$1): TString$1;
   /**
    * Create a schema for uuid.
    */
@@ -624,6 +643,10 @@ declare class TypeProvider {
     label: TString$1;
     description: TypeBox.TOptional<TString$1>;
   }>;
+  datetime: (options?: TStringOptions$1) => TString$1;
+  date: (options?: TStringOptions$1) => TString$1;
+  time: (options?: TStringOptions$1) => TString$1;
+  duration: (options?: TStringOptions$1) => TString$1;
 }
 type TextLength = "short" | "regular" | "long" | "rich";
 interface TTextOptions extends TStringOptions$1 {
@@ -651,61 +674,56 @@ declare const t: TypeProvider;
 //#endregion
 //#region src/providers/SchemaCodec.d.ts
 declare abstract class SchemaCodec {
-  protected cache: Map<TSchema$1, Validator>;
-  protected guard: TypeGuard;
   /**
    * Encode the value to a string format.
    */
-  abstract encodeToString(schema: TSchema$1, value: any): string;
+  abstract encodeToString<T extends TSchema>(schema: T, value: Static<T>): string;
   /**
    * Encode the value to a binary format.
    */
-  abstract encodeToBinary(schema: TSchema$1, value: any): Uint8Array;
-  /**
-   * Transform a specific type for this codec.
-   * Return undefined to use the default schema, or return a new schema to replace it.
-   *
-   * Override this method to customize how specific types are handled in this codec.
-   * For example, a ProtobufCodec might keep BigInt as-is instead of converting to string.
-   */
-  protected abstract transformType(schema: TSchema$1): TSchema$1 | false | void;
-  encode<T extends TSchema$1>(schema: T, value: any): StaticEncode$1<T>;
-  decode<T extends TSchema$1>(schema: T, value: any): StaticDecode$1<T>;
-  protected validator<T extends TSchema$1>(schema: T): Validator<{}, T>;
+  abstract encodeToBinary<T extends TSchema>(schema: T, value: Static<T>): Uint8Array;
   /**
-   * Transform the schema for this codec.
-   * Override this method to provide custom schema transformations.
-   * This method should recursively transform all nested schemas.
+   * Decode string, binary, or other formats to the schema type.
    */
-  protected transformSchema<T extends TSchema$1>(schema: T): TSchema$1;
+  abstract decode<T>(schema: TSchema, value: unknown): T;
+}
+//#endregion
+//#region src/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$1>(schema: T, value: Static<T>): string;
+  encodeToBinary<T extends TSchema$1>(schema: T, value: Static<T>): Uint8Array;
+  decode<T>(schema: TSchema$1, value: unknown): T;
+}
+//#endregion
+//#region src/providers/SchemaValidator.d.ts
+declare class SchemaValidator {
+  protected cache: Map<TSchema$1, Validator<TypeBox.TProperties, TSchema$1>>;
   /**
-   * Preprocess the value based on the schema before encoding.
+   * Validate the value against the provided schema.
    *
-   * - Remove `undefined` values from objects. { a: 1, b: undefined } => { a: 1 }
+   * Validation create a new value by applying some preprocessing. (e.g., trimming text)
    */
-  beforeEncode: (schema: any, value: any) => any;
+  validate<T extends TSchema$1>(schema: T, value: unknown, options?: ValidateOptions): Static<T>;
+  protected getValidator<T extends TSchema$1>(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.
    */
-  beforeDecode: (schema: any, value: any) => any;
+  beforeParse(schema: any, value: any, options: ValidateOptions): any;
   /**
-   * Used by `preprocess` to determine if a schema allows null values.
+   * Used by `beforeParse` to determine if a schema allows null values.
    */
   protected isSchemaNullable: (schema: any) => boolean;
 }
-//#endregion
-//#region src/providers/JsonSchemaCodec.d.ts
-declare class JsonSchemaCodec extends SchemaCodec {
-  protected readonly json: Json;
-  protected readonly encoder: TextEncoder;
-  protected readonly decoder: TextDecoder;
-  protected transformType(schema: TSchema$1): TSchema$1 | false | void;
-  encodeToString(schema: TSchema$1, value: any): string;
-  encodeToBinary(schema: TSchema$1, value: any): Uint8Array;
-  decode<T extends TSchema$1>(schema: T, value: any): StaticDecode$1<T>;
+interface ValidateOptions {
+  trim?: boolean;
+  nullToUndefined?: boolean;
+  deleteUndefined?: boolean;
 }
 //#endregion
 //#region src/providers/CodecManager.d.ts
@@ -713,24 +731,35 @@ type Encoding = "object" | "string" | "binary";
 interface EncodeOptions<T extends Encoding = Encoding> {
   /**
    * The output encoding format:
-   * - 'object': Returns native types (objects, BigInt, Date, etc.)
    * - 'string': Returns JSON string
    * - 'binary': Returns Uint8Array (for protobuf, msgpack, etc.)
+   *
+   * @default "string"
    */
   as?: T;
   /**
    * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
-   * Defaults to 'json'
+   *
+   * @default "json"
    */
   encoder?: string;
+  /**
+   * Validation options to apply before encoding.
+   */
+  validation?: ValidateOptions | false;
 }
 type EncodeResult<T extends TSchema$1, E extends Encoding> = E extends "string" ? string : E extends "binary" ? Uint8Array : StaticEncode$1<T>;
 interface DecodeOptions {
   /**
    * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
-   * Defaults to 'json'
+   *
+   * @default "json"
    */
   encoder?: string;
+  /**
+   * Validation options to apply before encoding.
+   */
+  validation?: ValidateOptions | false;
 }
 /**
  * CodecManager manages multiple codec formats and provides a unified interface
@@ -739,29 +768,38 @@ interface DecodeOptions {
 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
    */
-  get(name: string): SchemaCodec;
+  getCodec(name: string): SchemaCodec;
   /**
    * Encode data using the specified codec and output format.
    */
-  encode<T extends TSchema$1, E extends Encoding = "object">(schema: T, value: any, options?: EncodeOptions<E>): EncodeResult<T, E>;
+  encode<T extends TSchema$1, E extends Encoding = "object">(schema: T, value: unknown, options?: EncodeOptions<E>): EncodeResult<T, E>;
   /**
    * Decode data using the specified codec.
    */
-  decode<T extends TSchema$1>(schema: T, value: any, options?: DecodeOptions): StaticDecode$1<T>;
+  decode<T extends TSchema$1>(schema: T, data: any, options?: DecodeOptions): Static<T>;
+  /**
+   * Validate decoded data against the schema.
+   *
+   * This is automatically called before encoding or after decoding.
+   */
+  validate<T extends TSchema$1>(schema: T, value: unknown, options?: ValidateOptions): Static<T>;
 }
 //#endregion
 //#region src/providers/EventManager.d.ts
@@ -803,20 +841,91 @@ declare class EventManager {
   }): Promise<void>;
 }
 //#endregion
+//#region src/descriptors/$atom.d.ts
+/**
+ * Define an atom for state management.
+ *
+ * Atom lets you define a piece of state with a name, schema, and default value.
+ *
+ * By default, Alepha state is just a simple key-value store.
+ * Using atoms allows you to have type safety, validation, and default values for your state.
+ *
+ * You control how state is structured and validated.
+ *
+ * Features:
+ * - Set a schema for validation
+ * - Set a default value for initial state
+ * - Rules, like read-only, custom validation, etc.
+ * - Automatic getter access in services with {@link $use}
+ * - SSR support (server state automatically serialized and hydrated on client)
+ * - React integration (useAtom hook for automatic component re-renders)
+ * - Middleware
+ * - Persistence adapters (localStorage, Redis, database, file system, cookie, etc.)
+ * - State migrations (version upgrades when schema changes)
+ * - Documentation generation & devtools integration
+ *
+ * Common use cases:
+ * - user preferences
+ * - feature flags
+ * - configuration options
+ * - session data
+ *
+ * Atom must contain only serializable data.
+ * Avoid storing complex objects like class instances, functions, or DOM elements.
+ * If you need to store complex data, consider using identifiers or references instead.
+ */
+declare const $atom: {
+  <T extends TObject<TProperties$2> | TArray$1, N extends string>(options: AtomOptions<T, N>): Atom<T, N>;
+  [KIND]: string;
+};
+type AtomOptions<T extends TAtomObject, N extends string> = {
+  name: N;
+  schema: T;
+  description?: string;
+} & (T extends TOptionalAdd<T> ? {
+  default?: Static<T>;
+} : {
+  default: Static<T>;
+});
+declare class Atom<T extends TAtomObject = TObject, N extends string = string> {
+  readonly options: AtomOptions<T, N>;
+  get schema(): T;
+  get key(): N;
+  constructor(options: AtomOptions<T, N>);
+}
+type TProperties$2 = any;
+type TAtomObject = TObject<any> | TArray$1;
+type AtomStatic<T extends TAtomObject> = T extends TOptionalAdd<T> ? Static<T> | undefined : Static<T>;
+//#endregion
 //#region src/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$1<TypeBox.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<Key extends keyof State$1>(key: Key): State$1[Key] | undefined;
+  get<T extends TAtomObject>(target: Atom<T>): Static<T>;
+  get<Key extends keyof State$1>(target: Key): State$1[Key] | undefined;
   /**
    * Set a value in the state
    */
-  set<Key extends keyof State$1>(key: Key, value: State$1[Key] | undefined): this;
+  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$1>(target: Atom<T>, mutator: (current: Static<T>) => Static<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
    */
@@ -1000,7 +1109,7 @@ declare class Alepha {
    *
    * > Used to initialize the StateManager.
    */
-  protected init: State;
+  protected init: Partial<State>;
   /**
    * During the instantiation process, we keep a list of pending instantiations.
    * > It allows us to detect circular dependencies.
@@ -1025,12 +1134,6 @@ declare class Alepha {
   protected substitutions: Map<Service, {
     use: Service;
   }>;
-  /**
-   * Configuration states for services.
-   *
-   * Used to configure services when they are instantiated.
-   */
-  protected configurations: Map<Service, object>;
   /**
    * Registry of descriptors.
    */
@@ -1195,40 +1298,17 @@ declare class Alepha {
    * > If you are interested in configuring a service, use Alepha#configure() instead.
    *
    * @param serviceEntry - The service to register in the container.
-   * @param configure - Optional configuration object to merge with the service's options.
    * @return Current instance of Alepha.
    */
-  with<T extends {
-    options?: object;
-  } & object>(serviceEntry: ServiceEntry<T> | {
+  with<T extends object>(serviceEntry: ServiceEntry<T> | {
     default: ServiceEntry<T>;
-  }, configure?: Partial<T["options"]>): this;
+  }): 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>, opts?: InjectOptions<T>): T;
-  /**
-   * Configures the specified service with the provided state.
-   * If service is not registered, it will do nothing.
-   *
-   * It's recommended to use this method on the `configure` hook.
-   * @example
-   * ```ts
-   * class AppConfig {
-   *   configure = $hook({
-   *     name: "configure",
-   *     handler: (a) => {
-   *       a.configure(MyProvider, { some: "data" });
-   *     }
-   *   })
-   * }
-   * ```
-   */
-  configure<T extends {
-    options?: object;
-  }>(service: Service<T>, state: Partial<T["options"]>): this;
   /**
    * Applies environment variables to the provided schema and state object.
    *
@@ -1248,6 +1328,10 @@ declare class Alepha {
     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>;
@@ -1289,20 +1373,52 @@ interface Env {
   MODULE_NAME?: string;
 }
 interface State {
-  log?: LoggerInterface;
+  /**
+   * 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.
    */
-  target?: Service;
-  beforeAll?: (run: any) => any;
-  afterAll?: (run: any) => any;
-  afterEach?: (run: any) => any;
-  onTestFinished?: (run: any) => any;
+  "alepha.target"?: Service;
   /**
-   * List of static assets to be copied to the output directory.
+   * 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.
    */
-  assets?: Array<string>;
+  "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 {
   /**
@@ -1346,9 +1462,6 @@ interface Hooks {
     prevValue: any;
   };
 }
-interface Configurable<T extends object = any> {
-  options: T;
-}
 //#endregion
 //#region src/interfaces/Run.d.ts
 interface RunOptions {
@@ -1391,49 +1504,48 @@ declare const boot: {
  */
 declare const OPTIONS: unique symbol;
 //#endregion
-//#region src/descriptors/$cursor.d.ts
+//#region src/descriptors/$context.d.ts
 /**
- * Get Alepha instance and Class definition from the current context.
- * This should be used inside a descriptor only.
+ * Get Alepha instance and current service from the current context.
  *
- * ```ts
- * import { $cursor } from "alepha";
+ * It can only be used inside $descriptor functions.
  *
- * const $ = () => {
+ * ```ts
+ * import { $context } from "alepha";
  *
- *   const { context, definition } = $cursor();
+ * const $hello = () => {
+ *   const { alepha, service, module } = $context();
  *
- *   // context - alepha instance
- *   // definition - class which is creating this descriptor
+ *   // alepha - alepha instance
+ *   // service - class which is creating this descriptor, this is NOT the instance but the service definition
+ *   // module - module definition, if any
  *
  *   return {};
  * }
  *
- * ```
- *
- * @internal
- */
-declare const $cursor: () => CursorDescriptor;
-/**
- * /!\ Global variable /!\
+ * class MyService {
+ *   hello = $hello();
+ * }
  *
- * Store the current context and definition during injection phase.
+ * const alepha = new Alepha().with(MyService);
+ * ```
  *
  * @internal
  */
-declare const __alephaRef: {
-  context?: Alepha;
-  definition?: Service & {
-    [MODULE]?: Service;
-  };
-  parent?: Service;
-};
-/**
- * Cursor descriptor.
- */
-interface CursorDescriptor {
-  context: Alepha;
-  definition?: Service;
+declare const $context: () => ContextDescriptor;
+interface ContextDescriptor {
+  /**
+   * Alepha instance.
+   */
+  alepha: Alepha;
+  /**
+   * Service definition which is creating this descriptor.
+   * This is NOT the instance but the service definition.
+   */
+  service?: Service;
+  /**
+   * Module definition, if any.
+   */
   module?: Service;
 }
 //#endregion
@@ -1537,6 +1649,9 @@ declare class HookDescriptor<T extends keyof Hooks> extends Descriptor<HookOptio
   protected onInit(): void;
 }
 //#endregion
+//#region src/descriptors/$use.d.ts
+declare const $use: <T extends TObject, N extends string>(atom: Atom<T, N>) => Readonly<Static<T>>;
+//#endregion
 //#region src/errors/AppNotStartedError.d.ts
 declare class AppNotStartedError extends AlephaError {
   readonly name = "AppNotStartedError";
@@ -1562,6 +1677,24 @@ declare class TooLateSubstitutionError extends AlephaError {
 }
 //#endregion
 //#region src/schemas/pageSchema.d.ts
+declare const pageMetadataSchema: TObject<{
+  number: TypeBox.TInteger;
+  size: TypeBox.TInteger;
+  offset: TypeBox.TInteger;
+  numberOfElements: TypeBox.TInteger;
+  totalElements: TypeBox.TOptional<TypeBox.TInteger>;
+  totalPages: TypeBox.TOptional<TypeBox.TInteger>;
+  isEmpty: TypeBox.TBoolean;
+  isFirst: TypeBox.TBoolean;
+  isLast: TypeBox.TBoolean;
+  sort: TypeBox.TOptional<TObject<{
+    sorted: TypeBox.TBoolean;
+    fields: TArray<TObject<{
+      field: TypeBox.TString;
+      direction: TypeBox.TUnsafe<"asc" | "desc">;
+    }>>;
+  }>>;
+}>;
 /**
  * Create a pagination schema for the given object schema.
  *
@@ -1587,24 +1720,7 @@ declare class TooLateSubstitutionError extends AlephaError {
 declare const pageSchema: <T extends TObject | TRecord>(objectSchema: T, options?: TObjectOptions) => TPage<T>;
 type TPage<T extends TObject | TRecord> = TObject<{
   content: TArray<T>;
-  page: TObject<{
-    number: TInteger;
-    size: TInteger;
-    offset: TInteger;
-    numberOfElements: TInteger;
-    totalElements: TOptionalAdd<TInteger>;
-    totalPages: TOptionalAdd<TInteger>;
-    isEmpty: TBoolean;
-    isFirst: TBoolean;
-    isLast: TBoolean;
-    sort: TOptionalAdd<TObject<{
-      sorted: TBoolean;
-      fields: TArray<TObject<{
-        field: TString;
-        direction: TSchema;
-      }>>;
-    }>>;
-  }>;
+  page: typeof pageMetadataSchema;
 }>;
 /**
  * Opinionated type definition for a paginated response.
@@ -1641,65 +1757,18 @@ type Page<T> = {
    * Array of items on the current page.
    */
   content: T[];
-  page: {
-    /**
-     * Page number, starting from 0.
-     */
-    number: number;
-    /**
-     * Number of items per page (requested page size).
-     */
-    size: number;
-    /**
-     * Offset in the dataset (page × size).
-     */
-    offset: number;
-    /**
-     * Number of elements in THIS page (content.length).
-     * Different from totalElements which is the total across all pages.
-     */
-    numberOfElements: number;
-    /**
-     * Total number of elements across all pages.
-     * Only available when counting is enabled.
-     */
-    totalElements?: number;
-    /**
-     * Total number of pages.
-     * Only available when `totalElements` is present.
-     */
-    totalPages?: number;
-    /**
-     * Indicates if the current page has no items (numberOfElements === 0).
-     */
-    isEmpty: boolean;
-    /**
-     * Indicates if this is the first page (number === 0).
-     */
-    isFirst: boolean;
-    /**
-     * Indicates if this is the last page (no more pages after this).
-     */
-    isLast: boolean;
+  page: Static<typeof pageMetadataSchema>;
+};
+type PageMetadata = Static<typeof pageMetadataSchema>;
+declare module "alepha" {
+  interface TypeProvider {
     /**
-     * Sort metadata indicating what sorting was applied.
-     * Only present when sorting is applied.
+     * Create a schema for a paginated response.
      */
-    sort?: {
-      /**
-       * Whether the results are sorted.
-       */
-      sorted: boolean;
-      /**
-       * The fields and directions used for sorting.
-       */
-      fields: Array<{
-        field: string;
-        direction: "asc" | "desc";
-      }>;
-    };
-  };
-};
+    page<T extends TObject | TRecord>(itemSchema: T): TPage<T>;
+  }
+}
+//# sourceMappingURL=pageSchema.d.ts.map
 //#endregion
 //#region src/helpers/createPagination.d.ts
 /**
@@ -1806,6 +1875,14 @@ interface SortField {
   direction: SortDirection;
 }
 //#endregion
+//#region src/schemas/pageQuerySchema.d.ts
+declare const pageQuerySchema: TypeBox.TObject<{
+  page: TypeBox.TOptional<TypeBox.TInteger>;
+  size: TypeBox.TOptional<TypeBox.TInteger>;
+  sort: TypeBox.TOptional<TypeBox.TString>;
+}>;
+type PageQuery = Static<typeof pageQuerySchema>;
+//#endregion
 //#region src/index.d.ts
 /**
  * Run Alepha application, trigger start lifecycle.
@@ -1823,5 +1900,5 @@ interface SortField {
  */
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
 //#endregion
-export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, CodecManager, Configurable, ContainerLockedError, CursorDescriptor, DecodeOptions, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, EncodeOptions, EncodeResult, Encoding, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, JsonSchemaCodec, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, Page, PageRequest, RunFunction, SchemaCodec, Service, ServiceEntry, ServiceSubstitution, SortDirection, SortField, 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, TPage, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, TTextOptions, type TTuple, type TUnion, type TUnsafe, type TVoid, TextLength, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxErrorParams, TypeBoxFormat, TypeBoxValue, TypeGuard, TypeProvider, WithModule, __alephaRef, boot, createDescriptor, createPagination, isClass, isEmail, isFileLike, isTypeFile, isURL, isUUID, pageSchema, run, t };
+export { $atom, $context, $env, $hook, $inject, $module, $use, AbstractClass, Alepha, AlephaError, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, Atom, AtomOptions, AtomStatic, AtomWithValue, CircularDependencyError, CodecManager, ContainerLockedError, ContextDescriptor, DecodeOptions, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, EncodeOptions, EncodeResult, Encoding, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, JsonSchemaCodec, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, Page, PageMetadata, PageQuery, PageRequest, RunFunction, SchemaCodec, Service, ServiceEntry, ServiceSubstitution, SortDirection, SortField, State, StateManager, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, TAtomObject, type TBigInt, type TBoolean, TFile, type TInteger, type TKeysToIndexer, type TNull, type TNumber, type TNumberOptions, type TObject, type TObjectOptions, type TOptional, type TOptionalAdd, TPage, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, TTextOptions, type TTuple, type TUnion, type TUnsafe, type TVoid, TextLength, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxErrorParams, TypeBoxFormat, TypeBoxValue, TypeGuard, TypeProvider, WithModule, boot, createDescriptor, createPagination, isClass, isDate, isDateTime, isDuration, isEmail, isFileLike, isTime, isTypeFile, isURL, isUUID, pageMetadataSchema, pageQuerySchema, pageSchema, run, t };
 //# sourceMappingURL=index.d.ts.map