alepha 0.13.0 → 0.13.2

package/src/core/Alepha.ts

@@ -2,13 +2,11 @@ import type { Static, TObject } from "typebox";
 import { KIND } from "./constants/KIND.ts";
 import { MODULE } from "./constants/MODULE.ts";
 import { OPTIONS } from "./constants/OPTIONS.ts";
-import type { InjectOptions } from "./descriptors/$inject.ts";
-import { Module, type WithModule } from "./descriptors/$module.ts";
 import { AlephaError } from "./errors/AlephaError.ts";
 import { CircularDependencyError } from "./errors/CircularDependencyError.ts";
 import { ContainerLockedError } from "./errors/ContainerLockedError.ts";
 import { TooLateSubstitutionError } from "./errors/TooLateSubstitutionError.ts";
-import { Descriptor } from "./helpers/descriptor.ts";
+import { Primitive } from "./helpers/primitive.ts";
 import { __alephaRef } from "./helpers/ref.ts";
 import type { Async } from "./interfaces/Async.ts";
 import type { LoggerInterface } from "./interfaces/LoggerInterface.ts";
@@ -19,6 +17,8 @@ import {
   type Service,
   type ServiceEntry,
 } from "./interfaces/Service.ts";
+import type { InjectOptions } from "./primitives/$inject.ts";
+import { Module, type WithModule } from "./primitives/$module.ts";
 import { AlsProvider } from "./providers/AlsProvider.ts";
 import { CodecManager } from "./providers/CodecManager.ts";
 import { EventManager } from "./providers/EventManager.ts";
@@ -82,7 +82,7 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * // 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({
@@ -95,7 +95,7 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * ### 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";
@@ -113,7 +113,7 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * ### 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";
@@ -187,7 +187,7 @@ export class Alepha {
         // ignore
       }
 
-      alepha.state
+      alepha.store
         .set("alepha.test.beforeAll", beforeAll)
         .set("alepha.test.afterAll", afterAll)
         .set("alepha.test.afterEach", afterEach)
@@ -257,12 +257,9 @@ export class Alepha {
   protected substitutions = new Map<Service, { use: Service }>();
 
   /**
-   * Registry of descriptors.
+   * Registry of primitives.
    */
-  protected descriptorRegistry = new Map<
-    Service<Descriptor>,
-    Array<Descriptor>
-  >();
+  protected primitiveRegistry = new Map<Service<Primitive>, Array<Primitive>>();
 
   /**
    *  List of all services + how they are provided.
@@ -294,7 +291,7 @@ export class Alepha {
   /**
    * State manager to store arbitrary values.
    */
-  public get state(): StateManager<State> {
+  public get store(): StateManager<State> {
     this.events; // ensure events is initialized first (TODO: move this to constructor?)
     return this.inject(StateManager, {
       args: [this.init],
@@ -314,14 +311,14 @@ export class Alepha {
    * Get logger instance.
    */
   public get log(): LoggerInterface | undefined {
-    return this.state.get("alepha.logger");
+    return this.store.get("alepha.logger");
   }
 
   /**
    * The environment variables for the App.
    */
   public get env(): Readonly<Env> {
-    return this.state.get("env") ?? {};
+    return this.store.get("env") ?? {};
   }
 
   constructor(init: Partial<State> = {}) {
@@ -442,7 +439,7 @@ export 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.
    *
@@ -472,10 +469,10 @@ export class Alepha {
       this.inject(key);
     }
 
-    const target = this.state.get("alepha.target");
+    const target = this.store.get("alepha.target");
     if (target) {
       this.registry = new Map();
-      this.descriptorRegistry = new Map();
+      this.primitiveRegistry = new Map();
       this.with(target);
     }
 
@@ -878,28 +875,28 @@ export class Alepha {
   }
 
   /**
-   * Get all descriptors of the specified type.
+   * Get all primitives of the specified type.
    */
-  public descriptors<TDescriptor extends Descriptor>(
+  public primitives<TPrimitive extends Primitive>(
     factory:
       | {
-          [KIND]: InstantiableClass<TDescriptor>;
+          [KIND]: InstantiableClass<TPrimitive>;
         }
       | string,
-  ): Array<TDescriptor> {
+  ): Array<TPrimitive> {
     if (typeof factory === "string") {
       const key1 = factory.toLowerCase().replace("$", "");
-      const key2 = `${key1}descriptor`;
-      for (const [key, value] of this.descriptorRegistry.entries()) {
+      const key2 = `${key1}primitive`;
+      for (const [key, value] of this.primitiveRegistry.entries()) {
         const name = key.name.toLowerCase();
         if (name === key1 || name === key2) {
-          return value as Array<TDescriptor>;
+          return value as Array<TPrimitive>;
         }
       }
       return [];
     }
-    return (this.descriptorRegistry.get(factory[KIND]) ??
-      []) as Array<TDescriptor>;
+    return (this.primitiveRegistry.get(factory[KIND]) ??
+      []) as Array<TPrimitive>;
   }
 
   // -------------------------------------------------------------------------------------------------------------------
@@ -922,8 +919,8 @@ export class Alepha {
 
     const obj = instance as unknown as Record<string, any>;
     for (const [key, value] of Object.entries(obj)) {
-      if (value instanceof Descriptor) {
-        this.processDescriptor(value, key);
+      if (value instanceof Primitive) {
+        this.processPrimitive(value, key);
       }
       if (
         typeof value === "object" &&
@@ -933,7 +930,7 @@ export class Alepha {
       ) {
         const getter = value[OPTIONS].getter as keyof State;
         Object.defineProperty(obj, key, {
-          get: () => this.state.get(getter),
+          get: () => this.store.get(getter),
         });
       }
     }
@@ -951,13 +948,13 @@ export class Alepha {
     return instance;
   }
 
-  protected processDescriptor(value: Descriptor, propertyKey = "") {
+  protected processPrimitive(value: Primitive, propertyKey = "") {
     value.config.propertyKey = propertyKey;
     (value as any).onInit();
 
     const kind = value.constructor as Service;
-    const list = this.descriptorRegistry.get(kind) ?? [];
-    this.descriptorRegistry.set(kind, [...list, value]);
+    const list = this.primitiveRegistry.get(kind) ?? [];
+    this.primitiveRegistry.set(kind, [...list, value]);
   }
 }
 

package/src/core/constants/KIND.ts

@@ -1,5 +1,5 @@
 /**
- * Used for identifying descriptors.
+ * Used for identifying primitives.
  *
  * @internal
  */

package/src/core/constants/OPTIONS.ts

@@ -1,5 +1,5 @@
 /**
- * Used for descriptors options.
+ * Used for primitives options.
  *
  * @internal
  */

package/src/core/helpers/{descriptor.ts → primitive.ts}

@@ -1,31 +1,31 @@
 import { Alepha } from "../Alepha.ts";
 import { KIND } from "../constants/KIND.ts";
 import { MODULE } from "../constants/MODULE.ts";
-import { $context } from "../descriptors/$context.ts";
 import type { InstantiableClass, Service } from "../interfaces/Service.ts";
+import { $context } from "../primitives/$context.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface DescriptorArgs<T extends object = {}> {
+export interface PrimitiveArgs<T extends object = {}> {
   options: T;
   alepha: Alepha;
   service: InstantiableClass<Service>;
   module?: Service;
 }
 
-export interface DescriptorConfig {
+export interface PrimitiveConfig {
   propertyKey: string;
   service: InstantiableClass<Service>;
   module?: Service;
 }
 
-export abstract class Descriptor<T extends object = {}> {
+export abstract class Primitive<T extends object = {}> {
   protected readonly alepha: Alepha;
 
   public readonly options: T;
-  public readonly config: DescriptorConfig;
+  public readonly config: PrimitiveConfig;
 
-  constructor(args: DescriptorArgs<T>) {
+  constructor(args: PrimitiveArgs<T>) {
     this.alepha = args.alepha;
     this.options = args.options;
     this.config = {
@@ -36,7 +36,7 @@ export abstract class Descriptor<T extends object = {}> {
   }
 
   /**
-   * Called automatically by Alepha after the descriptor is created.
+   * Called automatically by Alepha after the primitive is created.
    */
   protected onInit(): void {
     // this method can be overridden by subclasses to perform initialization logic.
@@ -47,27 +47,27 @@ export abstract class Descriptor<T extends object = {}> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type DescriptorFactory<TDescriptor extends Descriptor = Descriptor> = {
-  (options: TDescriptor["options"]): TDescriptor;
-  [KIND]: InstantiableClass<TDescriptor>;
+export type PrimitiveFactory<TPrimitive extends Primitive = Primitive> = {
+  (options: TPrimitive["options"]): TPrimitive;
+  [KIND]: InstantiableClass<TPrimitive>;
 };
 
-export type DescriptorFactoryLike<T extends object = any> = {
+export type PrimitiveFactoryLike<T extends object = any> = {
   (options: T): any;
   [KIND]: any;
 };
 
-export const createDescriptor = <TDescriptor extends Descriptor>(
-  descriptor: InstantiableClass<TDescriptor> & { [MODULE]?: Service },
-  options: TDescriptor["options"],
-): TDescriptor => {
+export const createPrimitive = <TPrimitive extends Primitive>(
+  primitive: InstantiableClass<TPrimitive> & { [MODULE]?: Service },
+  options: TPrimitive["options"],
+): TPrimitive => {
   const { alepha, service } = $context();
 
-  if (MODULE in descriptor && descriptor[MODULE]) {
-    alepha.with(descriptor[MODULE]);
+  if (MODULE in primitive && primitive[MODULE]) {
+    alepha.with(primitive[MODULE]);
   }
 
-  return alepha.inject(descriptor, {
+  return alepha.inject(primitive, {
     lifetime: "transient",
     args: [
       {

package/src/core/helpers/ref.ts

@@ -18,7 +18,7 @@ export const __alephaRef: {
 /**
  * Note:
  *
- * This file is used to share context between $descriptors and the Alepha core during the injection phase.
+ * This file is used to share context between $primitives and the Alepha core during the injection phase.
  *
  * There is no side effect as long as Alepha is not used concurrently in multiple contexts (which is not the case).
  *

package/src/core/index.shared.ts

@@ -3,13 +3,6 @@
 export * from "./Alepha.ts";
 export * from "./constants/KIND.ts";
 export * from "./constants/OPTIONS.ts";
-export * from "./descriptors/$atom.ts";
-export * from "./descriptors/$context.ts";
-export * from "./descriptors/$env.ts";
-export * from "./descriptors/$hook.ts";
-export * from "./descriptors/$inject.ts";
-export * from "./descriptors/$module.ts";
-export * from "./descriptors/$use.ts";
 export * from "./errors/AlephaError.ts";
 export * from "./errors/AppNotStartedError.ts";
 export * from "./errors/CircularDependencyError.ts";
@@ -17,12 +10,19 @@ export * from "./errors/ContainerLockedError.ts";
 export * from "./errors/TooLateSubstitutionError.ts";
 export * from "./errors/TypeBoxError.ts";
 export * from "./helpers/createPagination.ts";
-export * from "./helpers/descriptor.ts";
 export * from "./helpers/FileLike.ts";
+export * from "./helpers/primitive.ts";
 export * from "./interfaces/Async.ts";
 export * from "./interfaces/LoggerInterface.ts";
 export * from "./interfaces/Pagination.ts";
 export * from "./interfaces/Service.ts";
+export * from "./primitives/$atom.ts";
+export * from "./primitives/$context.ts";
+export * from "./primitives/$env.ts";
+export * from "./primitives/$hook.ts";
+export * from "./primitives/$inject.ts";
+export * from "./primitives/$module.ts";
+export * from "./primitives/$use.ts";
 export * from "./providers/AlsProvider.ts";
 export * from "./providers/CodecManager.ts";
 export * from "./providers/EventManager.ts";

package/src/core/{descriptors → primitives}/$context.ts

@@ -7,7 +7,7 @@ import type { Service } from "../interfaces/Service.ts";
 /**
  * Get Alepha instance and current service from the current context.
  *
- * It can only be used inside $descriptor functions.
+ * It can only be used inside $primitive functions.
  *
  * ```ts
  * import { $context } from "alepha";
@@ -16,7 +16,7 @@ import type { Service } from "../interfaces/Service.ts";
  *   const { alepha, service, module } = $context();
  *
  *   // alepha - alepha instance
- *   // service - class which is creating this descriptor, this is NOT the instance but the service definition
+ *   // service - class which is creating this primitive, this is NOT the instance but the service definition
  *   // module - module definition, if any
  *
  *   return {};
@@ -31,7 +31,7 @@ import type { Service } from "../interfaces/Service.ts";
  *
  * @internal
  */
-export const $context = (): ContextDescriptor => {
+export const $context = (): ContextPrimitive => {
   if (!__alephaRef.alepha) {
     throw new MissingContextError();
   }
@@ -45,13 +45,13 @@ export const $context = (): ContextDescriptor => {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface ContextDescriptor {
+export interface ContextPrimitive {
   /**
    * Alepha instance.
    */
   alepha: Alepha;
   /**
-   * Service definition which is creating this descriptor.
+   * Service definition which is creating this primitive.
    * This is NOT the instance but the service definition.
    */
   service?: Service;

package/src/core/{descriptors → primitives}/$hook.ts

@@ -1,6 +1,6 @@
 import type { Hooks } from "../Alepha.ts";
 import { KIND } from "../constants/KIND.ts";
-import { createDescriptor, Descriptor } from "../helpers/descriptor.ts";
+import { createPrimitive, Primitive } from "../helpers/primitive.ts";
 import type { Async } from "../interfaces/Async.ts";
 
 /**
@@ -43,7 +43,7 @@ import type { Async } from "../interfaces/Async.ts";
  *
  */
 export const $hook = <T extends keyof Hooks>(options: HookOptions<T>) =>
-  createDescriptor(HookDescriptor<T>, options);
+  createPrimitive(HookPrimitive<T>, options);
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -76,7 +76,7 @@ export interface HookOptions<T extends keyof Hooks> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class HookDescriptor<T extends keyof Hooks> extends Descriptor<
+export class HookPrimitive<T extends keyof Hooks> extends Primitive<
   HookOptions<T>
 > {
   public called = 0;
@@ -93,4 +93,4 @@ export class HookDescriptor<T extends keyof Hooks> extends Descriptor<
   }
 }
 
-$hook[KIND] = HookDescriptor;
+$hook[KIND] = HookPrimitive;

package/src/core/{descriptors → primitives}/$inject.ts

@@ -1,4 +1,4 @@
-import { Descriptor } from "../helpers/descriptor.ts";
+import { Primitive } from "../helpers/primitive.ts";
 import type { InstantiableClass, Service } from "../interfaces/Service.ts";
 import { $context } from "./$context.ts";
 
@@ -30,7 +30,7 @@ export const $inject = <T extends object>(
   });
 };
 
-export class InjectDescriptor extends Descriptor {}
+export class InjectPrimitive extends Primitive {}
 
 export interface InjectOptions<T extends object = any> {
   /**

package/src/core/{descriptors → primitives}/$module.ts

@@ -2,11 +2,11 @@ import type { Alepha } from "../Alepha.ts";
 import { KIND } from "../constants/KIND.ts";
 import { MODULE } from "../constants/MODULE.ts";
 import { AlephaError } from "../errors/AlephaError.ts";
-import type { DescriptorFactoryLike } from "../helpers/descriptor.ts";
+import type { PrimitiveFactoryLike } from "../helpers/primitive.ts";
 import type { Service } from "../interfaces/Service.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.
@@ -54,9 +54,9 @@ import type { Service } from "../interfaces/Service.ts";
  * Meaning that if you have 100 actions, you should have at least 3 modules.
  */
 export const $module = <T extends object = {}>(
-  options: ModuleDescriptorOptions,
+  options: ModulePrimitiveOptions,
 ): Service<Module> => {
-  const { services = [], descriptors = [], name } = options;
+  const { services = [], primitives = [], name } = options;
 
   // ensure name is valid
   if (!name || !Module.NAME_REGEX.test(name)) {
@@ -94,7 +94,7 @@ export const $module = <T extends object = {}>(
     }
   }
 
-  for (const factory of descriptors) {
+  for (const factory of primitives) {
     if (typeof factory[KIND] === "function") {
       factory[KIND][MODULE] = $;
     }
@@ -105,7 +105,7 @@ export const $module = <T extends object = {}>(
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface ModuleDescriptorOptions {
+export interface ModulePrimitiveOptions {
   /**
    * Name of the module.
    *
@@ -122,9 +122,9 @@ export 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.
@@ -140,7 +140,7 @@ export interface ModuleDescriptorOptions {
  * Base class for all modules.
  */
 export abstract class Module {
-  public abstract readonly options: ModuleDescriptorOptions;
+  public abstract readonly options: ModulePrimitiveOptions;
 
   public abstract register(alepha: Alepha): void;
 

package/src/core/{descriptors → primitives}/$use.ts

@@ -32,9 +32,9 @@ export const $use = <T extends TObject, N extends string>(
   const { alepha } = $context();
 
   // register atom in state if not already registered
-  alepha.state.register(atom);
+  alepha.store.register(atom);
 
-  const init = alepha.state.get(atom.key as keyof State) as object;
+  const init = alepha.store.get(atom.key as keyof State) as object;
 
   return {
     [OPTIONS]: { getter: atom.key }, // alepha will replace this with by a real 'get prop()'

package/src/core/providers/CodecManager.ts

@@ -1,6 +1,6 @@
 import type { StaticEncode, TSchema } from "typebox";
-import { $inject } from "../descriptors/$inject.ts";
 import { AlephaError } from "../errors/AlephaError.ts";
+import { $inject } from "../primitives/$inject.ts";
 import { JsonSchemaCodec } from "./JsonSchemaCodec.ts";
 import type { SchemaCodec } from "./SchemaCodec.ts";
 import { SchemaValidator, type ValidateOptions } from "./SchemaValidator.ts";

package/src/core/providers/JsonSchemaCodec.ts

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import { $inject } from "../descriptors/$inject.ts";
+import { $inject } from "../primitives/$inject.ts";
 import { Json } from "./Json.ts";
 import { SchemaCodec } from "./SchemaCodec.ts";
 import type { Static } from "./TypeProvider.ts";

package/src/core/providers/StateManager.ts

@@ -4,8 +4,8 @@ import {
   Atom,
   type AtomStatic,
   type TAtomObject,
-} from "../descriptors/$atom.ts";
-import { $inject } from "../descriptors/$inject.ts";
+} from "../primitives/$atom.ts";
+import { $inject } from "../primitives/$inject.ts";
 import { AlsProvider } from "./AlsProvider.ts";
 import { EventManager } from "./EventManager.ts";
 import { JsonSchemaCodec } from "./JsonSchemaCodec.ts";

package/src/datetime/index.ts

@@ -1,14 +1,14 @@
 import { $module } from "alepha";
-import { $interval } from "./descriptors/$interval.ts";
+import { $interval } from "./primitives/$interval.ts";
 import { DateTimeProvider } from "./providers/DateTimeProvider.ts";
 
-export * from "./descriptors/$interval.ts";
+export * from "./primitives/$interval.ts";
 export * from "./providers/DateTimeProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export const AlephaDateTime = $module({
   name: "alepha.datetime",
-  descriptors: [$interval],
+  primitives: [$interval],
   services: [DateTimeProvider],
 });

package/src/datetime/{descriptors → primitives}/$interval.ts

@@ -1,4 +1,4 @@
-import { $inject, createDescriptor, Descriptor, KIND } from "alepha";
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import {
   DateTimeProvider,
   type DurationLike,
@@ -9,12 +9,12 @@ import {
  * It uses the `setInterval` internally.
  * It starts by default when the context starts and stops when the context stops.
  */
-export const $interval = (options: IntervalDescriptorOptions) =>
-  createDescriptor(IntervalDescriptor, options);
+export const $interval = (options: IntervalPrimitiveOptions) =>
+  createPrimitive(IntervalPrimitive, options);
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface IntervalDescriptorOptions {
+export interface IntervalPrimitiveOptions {
   /**
    * The interval handler.
    */
@@ -28,7 +28,7 @@ export interface IntervalDescriptorOptions {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class IntervalDescriptor extends Descriptor<IntervalDescriptorOptions> {
+export class IntervalPrimitive extends Primitive<IntervalPrimitiveOptions> {
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
 
   public called = 0;
@@ -41,4 +41,4 @@ export class IntervalDescriptor extends Descriptor<IntervalDescriptorOptions> {
   }
 }
 
-$interval[KIND] = IntervalDescriptor;
+$interval[KIND] = IntervalPrimitive;

package/src/email/index.ts

@@ -1,5 +1,5 @@
 import { $module } from "alepha";
-import { $email } from "./descriptors/$email.ts";
+import { $email } from "./primitives/$email.ts";
 import { EmailProvider } from "./providers/EmailProvider.ts";
 import { LocalEmailProvider } from "./providers/LocalEmailProvider.ts";
 import { MemoryEmailProvider } from "./providers/MemoryEmailProvider.ts";
@@ -7,8 +7,8 @@ import { NodemailerEmailProvider } from "./providers/NodemailerEmailProvider.ts"
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$email.ts";
 export * from "./errors/EmailError.ts";
+export * from "./primitives/$email.ts";
 export * from "./providers/EmailProvider.ts";
 export * from "./providers/LocalEmailProvider.ts";
 export * from "./providers/MemoryEmailProvider.ts";
@@ -38,7 +38,7 @@ declare module "alepha" {
 /**
  * Provides email sending capabilities for Alepha applications with multiple provider backends.
  *
- * The email module enables declarative email sending through the `$email` descriptor, allowing you to send
+ * The email module enables declarative email sending through the `$email` primitive, allowing you to send
  * emails through different providers: memory (for testing), local file system, or SMTP via Nodemailer.
  * It supports HTML email content and automatic provider selection based on environment configuration.
  *
@@ -47,7 +47,7 @@ declare module "alepha" {
  */
 export const AlephaEmail = $module({
   name: "alepha.email",
-  descriptors: [$email],
+  primitives: [$email],
   services: [
     EmailProvider,
     MemoryEmailProvider,