alepha 0.13.1 → 0.13.2

package/dist/core/index.d.ts

@@ -10,7 +10,7 @@ import { ReadableStream as ReadableStream$1 } from "node:stream/web";
 
 //#region src/core/constants/KIND.d.ts
 /**
- * Used for identifying descriptors.
+ * Used for identifying primitives.
  *
  * @internal
  */
@@ -72,41 +72,65 @@ interface ServiceSubstitution<T extends object = any> {
 type ServiceEntry<T extends object = any> = Service<T> | ServiceSubstitution<T>;
 declare function isClass(func: any): func is InstantiableClass;
 //#endregion
-//#region src/core/helpers/descriptor.d.ts
-interface DescriptorArgs<T extends object = {}> {
+//#region src/core/helpers/primitive.d.ts
+interface PrimitiveArgs<T extends object = {}> {
   options: T;
   alepha: Alepha;
   service: InstantiableClass<Service>;
   module?: Service;
 }
-interface DescriptorConfig {
+interface PrimitiveConfig {
   propertyKey: string;
   service: InstantiableClass<Service>;
   module?: Service;
 }
-declare abstract class Descriptor<T extends object = {}> {
+declare abstract class Primitive<T extends object = {}> {
   protected readonly alepha: Alepha;
   readonly options: T;
-  readonly config: DescriptorConfig;
-  constructor(args: DescriptorArgs<T>);
+  readonly config: PrimitiveConfig;
+  constructor(args: PrimitiveArgs<T>);
   /**
-   * Called automatically by Alepha after the descriptor is created.
+   * Called automatically by Alepha after the primitive is created.
    */
   protected onInit(): void;
 }
-type DescriptorFactory<TDescriptor extends Descriptor = Descriptor> = {
-  (options: TDescriptor["options"]): TDescriptor;
-  [KIND]: InstantiableClass<TDescriptor>;
+type PrimitiveFactory<TPrimitive extends Primitive = Primitive> = {
+  (options: TPrimitive["options"]): TPrimitive;
+  [KIND]: InstantiableClass<TPrimitive>;
 };
-type DescriptorFactoryLike<T extends object = any> = {
+type PrimitiveFactoryLike<T extends object = any> = {
   (options: T): any;
   [KIND]: any;
 };
-declare const createDescriptor: <TDescriptor extends Descriptor>(descriptor: InstantiableClass<TDescriptor> & {
+declare const createPrimitive: <TPrimitive extends Primitive>(primitive: InstantiableClass<TPrimitive> & {
   [MODULE]?: Service;
-}, options: TDescriptor["options"]) => TDescriptor;
+}, options: TPrimitive["options"]) => TPrimitive;
 //#endregion
-//#region src/core/descriptors/$inject.d.ts
+//#region 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>;
+/**
+ * Represents a function that returns an async value.
+ */
+type AsyncFn = (...args: any[]) => Async<any>;
+/**
+ * Transforms a type T into a promise if it is not already a promise.
+ */
+type MaybePromise<T> = T extends Promise<any> ? T : Promise<T>;
+//#endregion
+//#region src/core/interfaces/LoggerInterface.d.ts
+type LogLevel = "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE" | "SILENT";
+interface LoggerInterface {
+  trace(message: string, data?: unknown): void;
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+//#endregion
+//#region src/core/primitives/$inject.d.ts
 /**
  * Get the instance of the specified type from the context.
  *
@@ -118,7 +142,7 @@ declare const createDescriptor: <TDescriptor extends Descriptor>(descriptor: Ins
  * ```
  */
 declare const $inject: <T extends object>(type: Service<T>, opts?: InjectOptions<T>) => T;
-declare class InjectDescriptor extends Descriptor {}
+declare class InjectPrimitive extends Primitive {}
 interface InjectOptions<T extends object = any> {
   /**
    * - 'transient' → Always a new instance on every inject. Zero caching.
@@ -143,9 +167,9 @@ interface InjectOptions<T extends object = any> {
   parent?: Service | null;
 }
 //#endregion
-//#region src/core/descriptors/$module.d.ts
+//#region src/core/primitives/$module.d.ts
 /**
- * Wrap Services and Descriptors into a Module.
+ * Wrap Services and Primitives into a Module.
  *
  * - A module is just a Service with some extra {@link Module}.
  * - You must attach a `name` to it.
@@ -192,8 +216,8 @@ interface InjectOptions<T extends object = any> {
  * 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) => Service<Module>;
-interface ModuleDescriptorOptions {
+declare const $module: <T extends object = {}>(options: ModulePrimitiveOptions) => Service<Module>;
+interface ModulePrimitiveOptions {
   /**
    * Name of the module.
    *
@@ -208,9 +232,9 @@ interface ModuleDescriptorOptions {
    */
   services?: Array<Service>;
   /**
-   * List of $descriptors to register in the module.
+   * List of $primitives to register in the module.
    */
-  descriptors?: Array<DescriptorFactoryLike>;
+  primitives?: Array<PrimitiveFactoryLike>;
   /**
    * By default, module will register ALL services.
    * You can override this behavior by providing a register function.
@@ -224,7 +248,7 @@ interface ModuleDescriptorOptions {
  * Base class for all modules.
  */
 declare abstract class Module {
-  abstract readonly options: ModuleDescriptorOptions;
+  abstract readonly options: ModulePrimitiveOptions;
   abstract register(alepha: Alepha): void;
   static NAME_REGEX: RegExp;
   /**
@@ -245,30 +269,6 @@ type WithModule<T extends object = any> = T & {
   [MODULE]?: Service;
 };
 //#endregion
-//#region 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>;
-/**
- * Represents a function that returns an async value.
- */
-type AsyncFn = (...args: any[]) => Async<any>;
-/**
- * Transforms a type T into a promise if it is not already a promise.
- */
-type MaybePromise<T> = T extends Promise<any> ? T : Promise<T>;
-//#endregion
-//#region src/core/interfaces/LoggerInterface.d.ts
-type LogLevel = "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE" | "SILENT";
-interface LoggerInterface {
-  trace(message: string, data?: unknown): void;
-  debug(message: string, data?: unknown): void;
-  info(message: string, data?: unknown): void;
-  warn(message: string, data?: unknown): void;
-  error(message: string, data?: unknown): void;
-}
-//#endregion
 //#region src/core/providers/AlsProvider.d.ts
 type AsyncLocalStorageData = any;
 declare class AlsProvider {
@@ -844,7 +844,7 @@ declare class EventManager {
   }): Promise<void>;
 }
 //#endregion
-//#region src/core/descriptors/$atom.d.ts
+//#region src/core/primitives/$atom.d.ts
 /**
  * Define an atom for state management.
  *
@@ -1010,7 +1010,7 @@ type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends A
  * // 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.
+ * // But you should use $env() primitive to get typed values from the environment.
  * class App {
  *   env = $env(
  *     t.object({
@@ -1023,7 +1023,7 @@ type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends A
  * ### Modules
  *
  * Modules are a way to group services together.
- * You can register a module using the `$module` descriptor.
+ * You can register a module using the `$module` primitive.
  *
  * ```ts
  * import { $module } from "alepha";
@@ -1041,7 +1041,7 @@ type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends A
  * ### Hooks
  *
  * Hooks are a way to run async functions from all registered providers/services.
- * You can register a hook using the `$hook` descriptor.
+ * You can register a hook using the `$hook` primitive.
  *
  * ```ts
  * import { $hook } from "alepha";
@@ -1138,9 +1138,9 @@ declare class Alepha {
     use: Service;
   }>;
   /**
-   * Registry of descriptors.
+   * Registry of primitives.
    */
-  protected descriptorRegistry: Map<Service<Descriptor<{}>>, Descriptor<{}>[]>;
+  protected primitiveRegistry: Map<Service<Primitive<{}>>, Primitive<{}>[]>;
   /**
    *  List of all services + how they are provided.
    */
@@ -1160,7 +1160,7 @@ declare class Alepha {
   /**
    * State manager to store arbitrary values.
    */
-  get state(): StateManager<State>;
+  get store(): StateManager<State>;
   /**
    * Codec manager for encoding and decoding data with different formats.
    *
@@ -1233,7 +1233,7 @@ declare class Alepha {
    * Starts the App.
    *
    * - Lock any further changes to the container.
-   * - Run "configure" hook for all services. Descriptors will be processed.
+   * - Run "configure" hook for all services. Primitives 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.
    *
@@ -1338,13 +1338,13 @@ declare class Alepha {
   }>;
   services<T extends object>(base: Service<T>): Array<T>;
   /**
-   * Get all descriptors of the specified type.
+   * Get all primitives of the specified type.
    */
-  descriptors<TDescriptor extends Descriptor>(factory: {
-    [KIND]: InstantiableClass<TDescriptor>;
-  } | string): Array<TDescriptor>;
+  primitives<TPrimitive extends Primitive>(factory: {
+    [KIND]: InstantiableClass<TPrimitive>;
+  } | string): Array<TPrimitive>;
   protected new<T extends object>(service: Service<T>, args?: any[]): T;
-  protected processDescriptor(value: Descriptor, propertyKey?: string): void;
+  protected processPrimitive(value: Primitive, propertyKey?: string): void;
 }
 interface Hook<T extends keyof Hooks = any> {
   caller?: Service;
@@ -1500,182 +1500,12 @@ interface RunOptions {
 //#endregion
 //#region src/core/constants/OPTIONS.d.ts
 /**
- * Used for descriptors options.
+ * Used for primitives options.
  *
  * @internal
  */
 declare const OPTIONS: unique symbol;
 //#endregion
-//#region src/core/descriptors/$context.d.ts
-/**
- * Get Alepha instance and current service from the current context.
- *
- * It can only be used inside $descriptor functions.
- *
- * ```ts
- * import { $context } from "alepha";
- *
- * const $hello = () => {
- *   const { alepha, service, module } = $context();
- *
- *   // 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 {};
- * }
- *
- * class MyService {
- *   hello = $hello();
- * }
- *
- * const alepha = new Alepha().with(MyService);
- * ```
- *
- * @internal
- */
-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
-//#region src/core/descriptors/$env.d.ts
-/**
- * Get typed values from environment variables.
- *
- * @example
- * ```ts
- * const alepha = Alepha.create({
- *   env: {
- *     // Alepha.create() will also use process.env when running on Node.js
- *     HELLO: "world",
- *   }
- * });
- *
- * class App {
- *   log = $logger();
- *
- *   // program expect a var env "HELLO" as string to works
- *   env = $env(t.object({
- *     HELLO: t.text()
- *   }));
- *
- *   sayHello = () => this.log.info("Hello ${this.env.HELLO}")
- * }
- *
- * run(alepha.with(App));
- * ```
- */
-declare const $env: <T extends TObject$1>(type: T) => Static$1<T>;
-//#endregion
-//#region src/core/descriptors/$hook.d.ts
-/**
- * Registers a new hook.
- *
- * ```ts
- * import { $hook } from "alepha";
- *
- * class MyProvider {
- *   onStart = $hook({
- *     name: "start", // or "configure", "ready", "stop", ...
- *     handler: async (app) => {
- *       // await db.connect(); ...
- *     }
- *   });
- * }
- * ```
- *
- * Hooks are used to run async functions from all registered providers/services.
- *
- * You can't register a hook after the App has started.
- *
- * It's used under the hood by the `configure`, `start`, and `stop` methods.
- * Some modules also use hooks to run their own logic. (e.g. `alepha/server`).
- *
- * You can create your own hooks by using module augmentation:
- *
- * ```ts
- * declare module "alepha" {
- *
- *   interface Hooks {
- *     "my:custom:hook": {
- *       arg1: string;
- *     }
- *   }
- * }
- *
- * await alepha.events.emit("my:custom:hook", { arg1: "value" });
- * ```
- *
- */
-declare const $hook: {
-  <T extends keyof Hooks>(options: HookOptions<T>): HookDescriptor<T>;
-  [KIND]: typeof HookDescriptor;
-};
-interface HookOptions<T extends keyof Hooks> {
-  /**
-   * The name of the hook. "configure", "start", "ready", "stop", ...
-   */
-  on: T;
-  /**
-   * The handler to run when the hook is triggered.
-   */
-  handler: (args: Hooks[T]) => Async<any>;
-  /**
-   * Force the hook to run first or last on the list of hooks.
-   */
-  priority?: "first" | "last";
-  /**
-   * Empty placeholder, not implemented yet. :-)
-   */
-  before?: object | Array<object>;
-  /**
-   * Empty placeholder, not implemented yet. :-)
-   */
-  after?: object | Array<object>;
-}
-declare class HookDescriptor<T extends keyof Hooks> extends Descriptor<HookOptions<T>> {
-  called: number;
-  protected onInit(): void;
-}
-//#endregion
-//#region src/core/descriptors/$use.d.ts
-/**
- * Subscribes to an atom's state and returns its current value for use in components.
- *
- * Creates a reactive connection between an atom and a component, automatically registering
- * the atom in the application state if not already registered. The returned value is reactive
- * and will update when the atom's state changes.
- *
- * **Use Cases**: Accessing global state, sharing data between components, reactive UI updates
- *
- * @example
- * ```ts
- * const userState = $atom({ schema: t.object({ name: t.text(), role: t.text() }) });
- *
- * class UserComponent {
- *   user = $use(userState); // Reactive reference to atom state
- *
- *   render() {
- *     return <div>Hello {this.user.name}!</div>;
- *   }
- * }
- * ```
- */
-declare const $use: <T extends TObject, N extends string>(atom: Atom<T, N>) => Readonly<Static<T>>;
-//#endregion
 //#region src/core/errors/AppNotStartedError.d.ts
 declare class AppNotStartedError extends AlephaError {
   readonly name = "AppNotStartedError";
@@ -1898,6 +1728,176 @@ interface SortField {
   direction: SortDirection;
 }
 //#endregion
+//#region src/core/primitives/$context.d.ts
+/**
+ * Get Alepha instance and current service from the current context.
+ *
+ * It can only be used inside $primitive functions.
+ *
+ * ```ts
+ * import { $context } from "alepha";
+ *
+ * const $hello = () => {
+ *   const { alepha, service, module } = $context();
+ *
+ *   // alepha - alepha instance
+ *   // service - class which is creating this primitive, this is NOT the instance but the service definition
+ *   // module - module definition, if any
+ *
+ *   return {};
+ * }
+ *
+ * class MyService {
+ *   hello = $hello();
+ * }
+ *
+ * const alepha = new Alepha().with(MyService);
+ * ```
+ *
+ * @internal
+ */
+declare const $context: () => ContextPrimitive;
+interface ContextPrimitive {
+  /**
+   * Alepha instance.
+   */
+  alepha: Alepha;
+  /**
+   * Service definition which is creating this primitive.
+   * This is NOT the instance but the service definition.
+   */
+  service?: Service;
+  /**
+   * Module definition, if any.
+   */
+  module?: Service;
+}
+//#endregion
+//#region src/core/primitives/$env.d.ts
+/**
+ * Get typed values from environment variables.
+ *
+ * @example
+ * ```ts
+ * const alepha = Alepha.create({
+ *   env: {
+ *     // Alepha.create() will also use process.env when running on Node.js
+ *     HELLO: "world",
+ *   }
+ * });
+ *
+ * class App {
+ *   log = $logger();
+ *
+ *   // program expect a var env "HELLO" as string to works
+ *   env = $env(t.object({
+ *     HELLO: t.text()
+ *   }));
+ *
+ *   sayHello = () => this.log.info("Hello ${this.env.HELLO}")
+ * }
+ *
+ * run(alepha.with(App));
+ * ```
+ */
+declare const $env: <T extends TObject$1>(type: T) => Static$1<T>;
+//#endregion
+//#region src/core/primitives/$hook.d.ts
+/**
+ * Registers a new hook.
+ *
+ * ```ts
+ * import { $hook } from "alepha";
+ *
+ * class MyProvider {
+ *   onStart = $hook({
+ *     name: "start", // or "configure", "ready", "stop", ...
+ *     handler: async (app) => {
+ *       // await db.connect(); ...
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * Hooks are used to run async functions from all registered providers/services.
+ *
+ * You can't register a hook after the App has started.
+ *
+ * It's used under the hood by the `configure`, `start`, and `stop` methods.
+ * Some modules also use hooks to run their own logic. (e.g. `alepha/server`).
+ *
+ * You can create your own hooks by using module augmentation:
+ *
+ * ```ts
+ * declare module "alepha" {
+ *
+ *   interface Hooks {
+ *     "my:custom:hook": {
+ *       arg1: string;
+ *     }
+ *   }
+ * }
+ *
+ * await alepha.events.emit("my:custom:hook", { arg1: "value" });
+ * ```
+ *
+ */
+declare const $hook: {
+  <T extends keyof Hooks>(options: HookOptions<T>): HookPrimitive<T>;
+  [KIND]: typeof HookPrimitive;
+};
+interface HookOptions<T extends keyof Hooks> {
+  /**
+   * The name of the hook. "configure", "start", "ready", "stop", ...
+   */
+  on: T;
+  /**
+   * The handler to run when the hook is triggered.
+   */
+  handler: (args: Hooks[T]) => Async<any>;
+  /**
+   * Force the hook to run first or last on the list of hooks.
+   */
+  priority?: "first" | "last";
+  /**
+   * Empty placeholder, not implemented yet. :-)
+   */
+  before?: object | Array<object>;
+  /**
+   * Empty placeholder, not implemented yet. :-)
+   */
+  after?: object | Array<object>;
+}
+declare class HookPrimitive<T extends keyof Hooks> extends Primitive<HookOptions<T>> {
+  called: number;
+  protected onInit(): void;
+}
+//#endregion
+//#region src/core/primitives/$use.d.ts
+/**
+ * Subscribes to an atom's state and returns its current value for use in components.
+ *
+ * Creates a reactive connection between an atom and a component, automatically registering
+ * the atom in the application state if not already registered. The returned value is reactive
+ * and will update when the atom's state changes.
+ *
+ * **Use Cases**: Accessing global state, sharing data between components, reactive UI updates
+ *
+ * @example
+ * ```ts
+ * const userState = $atom({ schema: t.object({ name: t.text(), role: t.text() }) });
+ *
+ * class UserComponent {
+ *   user = $use(userState); // Reactive reference to atom state
+ *
+ *   render() {
+ *     return <div>Hello {this.user.name}!</div>;
+ *   }
+ * }
+ * ```
+ */
+declare const $use: <T extends TObject, N extends string>(atom: Atom<T, N>) => Readonly<Static<T>>;
+//#endregion
 //#region src/core/schemas/pageQuerySchema.d.ts
 declare const pageQuerySchema: TObject<{
   page: TOptional<TInteger>;
@@ -1923,5 +1923,5 @@ type PageQuery = Static<typeof pageQuerySchema>;
  */
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
 //#endregion
-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, EventManager, 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, createDescriptor, createPagination, isClass, isDate, isDateTime, isDuration, isEmail, isFileLike, isTime, isTypeFile, isURL, isUUID, pageMetadataSchema, pageQuerySchema, 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, ContextPrimitive, DecodeOptions, EncodeOptions, EncodeResult, Encoding, Env, EventManager, FileLike, Hook, HookOptions, HookPrimitive, Hooks, InjectOptions, InjectPrimitive, InstantiableClass, JsonSchemaCodec, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModulePrimitiveOptions, OPTIONS, Page, PageMetadata, PageQuery, PageRequest, Primitive, PrimitiveArgs, PrimitiveConfig, PrimitiveFactory, PrimitiveFactoryLike, 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, createPagination, createPrimitive, isClass, isDate, isDateTime, isDuration, isEmail, isFileLike, isTime, isTypeFile, isURL, isUUID, pageMetadataSchema, pageQuerySchema, pageSchema, run, t };
 //# sourceMappingURL=index.d.ts.map