alepha 0.7.3 → 0.7.5

package/core.d.ts

@@ -5,9 +5,9 @@ export { Static, StaticDecode, StaticEncode, TObject, TSchema, TypeGuard } from
 import { TypeCheck } from '@sinclair/typebox/compiler';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ValueError } from '@sinclair/typebox/errors';
+import { ReadableStream as ReadableStream$1 } from 'node:stream/web';
 import * as TypeBoxValue from '@sinclair/typebox/value';
 export { TypeBoxValue };
-import { ReadableStream as ReadableStream$1 } from 'node:stream/web';
 import { Readable } from 'node:stream';
 
 /**
@@ -59,10 +59,10 @@ interface ServiceSubstitution<T extends object = any> {
      */
     use: Service<T>;
     /**
-     * If true, will not throw an error if the service already exists.
+     * If true and 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.
      */
-    default?: boolean;
+    optional?: boolean;
 }
 /**
  * Every time you register a service, you can use this type to define it.
@@ -152,41 +152,15 @@ declare const $hook: {
     [KIND]: string;
 };
 
-interface ModuleDescriptorOptions<T extends TSchema> {
-    name: string;
-    version?: string;
-    description?: string;
-    services?: ServiceEntry[] | ((args: Alepha & {
-        env: Static<T>;
-    }) => ServiceEntry[]);
-    env?: T;
-}
-type ModuleDescriptor<T extends TSchema = TSchema> = {
-    [KIND]: "MODULE";
-    [OPTIONS]: ModuleDescriptorOptions<T>;
-};
-/**
- * This descriptor can be used to define the application metadata and services.
- */
-declare const $module: <T extends TSchema>(opts: ModuleDescriptorOptions<T>) => ModuleDescriptor<T>;
 interface Module {
-    /**
-     * The name of the module.
-     */
-    name: string;
-    /**
-     * The version of the module.
-     */
-    version?: string;
-    /**
-     * The description of the module.
-     */
-    description?: string;
-    /**
-     * The services provided by the module.
-     */
-    services?: Service[];
+    name?: string;
+    $services: (alepha: Alepha) => void | Alepha;
+}
+interface ModuleDefinition extends Module {
+    services: Array<Service>;
 }
+declare const isModule: (value: unknown) => value is Module;
+declare const toModuleName: (name: string) => string;
 
 /**
  * /!\ Global variable /!\
@@ -198,7 +172,11 @@ interface Module {
 declare const __alephaRef: {
     context?: Alepha;
     definition?: Service;
-    module?: Module;
+    module?: ModuleDefinition;
+    $services?: {
+        module: ModuleDefinition;
+        parent: Service;
+    };
 };
 /**
  * Cursor descriptor.
@@ -206,7 +184,7 @@ declare const __alephaRef: {
 interface CursorDescriptor {
     context: Alepha;
     definition?: Service;
-    module?: Module;
+    module?: ModuleDefinition;
 }
 /**
  * Get Alepha instance and Class definition from the current context.
@@ -451,9 +429,8 @@ interface MockLoggerStore {
     stack: Array<{
         date: string;
         level: string;
-        msg: string;
-        data?: object;
-    }>;
+        message: string;
+    } & Record<string, any>>;
 }
 
 interface Env extends LoggerEnv {
@@ -463,7 +440,7 @@ interface Env extends LoggerEnv {
      */
     NODE_ENV?: "dev" | "test" | "production";
     /**
-     * Optional name of the application. Same as `state.name`.
+     * Optional name of the application.
      */
     APP_NAME?: string;
     /**
@@ -541,7 +518,7 @@ interface Hooks {
  *   // state, env, and other properties
  * })
  *
- * alepha.register(MyService);
+ * alepha.with(MyService);
  *
  * run(alepha); // trigger .start (and .stop) automatically
  * ```
@@ -553,14 +530,18 @@ interface Hooks {
  */
 declare class Alepha {
     /**
-     * Syntactic sugar for creating a new instance of the container.
-     * Equivalent to `Alepha.create()`.
+     * 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;
     /**
      *  List of all services + how they are provided.
      */
-    protected registry: Map<Service, Definition>;
+    protected registry: Map<Service, ServiceDefinition>;
     /**
      * Flag indicating whether the App won't accept any further changes.
      * Pass to true when #start() is called.
@@ -634,7 +615,7 @@ declare class Alepha {
      *
      * Modules are used to group services and provide a way to register them in the container.
      */
-    protected modules: Array<Module>;
+    protected modules: Array<ModuleDefinition>;
     /**
      * Node.js feature that allows to store context across asynchronous calls.
      *
@@ -662,18 +643,19 @@ declare class Alepha {
      */
     state<Key extends keyof State>(key: Key, value?: State[Key]): State[Key];
     /**
-     * Dump the current dependency graph of the App.
+     * True when start() is called.
      *
-     * This method returns a record where the keys are the names of the services.
+     * -> No more services can be added, it's over, bye!
      */
-    graph(): Record<string, {
-        from: string[];
-        as?: string;
-    }>;
+    isLocked(): boolean;
     /**
-     * True if the App is running in a browser environment.
+     * 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.
      */
-    isBrowser(): boolean;
+    isConfigured(): boolean;
     /**
      * Returns whether the App has started.
      *
@@ -685,19 +667,9 @@ declare class Alepha {
      */
     isReady(): boolean;
     /**
-     * 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.
+     * True if the App is running in a browser environment.
      */
-    isConfigured(): boolean;
+    isBrowser(): boolean;
     /**
      * Returns whether the App is running in a serverless environment.
      *
@@ -716,12 +688,6 @@ declare class Alepha {
      * > This is automatically set by Vite or Vercel. However, you have to set it manually when running Docker apps.
      */
     isProduction(): boolean;
-    /**
-     * Trigger configuration of the App manually.
-     *
-     * > configure() is called automatically when start() is called, you should not need to call it manually.
-     */
-    configure(): Promise<this | undefined>;
     /**
      * Starts the App.
      *
@@ -766,10 +732,12 @@ declare class Alepha {
     /**
      * 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.
+     * - 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.
+     * > ServiceEntry allows to provide a service **substitution** feature.
      *
      * @example
      * ```ts
@@ -777,34 +745,28 @@ declare class Alepha {
      * class B { value = "b"; }
      * class M { a = $inject(A); }
      *
-     * Alepha.create().register({ provide: A, use: B }).get(M).a.value; // "b"
+     * 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.
+     * > **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 entry - The service to register in the container.
      * @return Current instance of Alepha.
      */
-    register(...entries: Array<ServiceEntry | ModuleDescriptor>): this;
+    with<T extends object>(entry: ServiceEntry<T>): this;
     /**
-     * Alias for the 'register' method.
-     *
-     * @alias {Alepha#register}
-     */
-    with: (...entries: Array<ServiceEntry | ModuleDescriptor>) => this;
-    /**
-     * Works like 'Alepha#register' but it will return the instance.
+     * Get the instance of the specified service and apply some changes, depending on the options.
+     * - If the service is already registered, it will return the existing instance. (except if `skipCache` is true)
+     * - If the service is not registered, it will create a new instance and register it. (except if `skipRegistration` is true)
+     * - New instance can be created with custom constructor arguments. (`args` option)
      *
      * > This method is used by $inject() under the hood.
      *
      * @return The instance of the specified class or type.
      */
     get<T extends object>(serviceEntry: ServiceEntry<T>, opts?: {
-        /**
-         * Parent service that requested the instance.
-         */
-        parent?: Service | null;
         /**
          * Ignore current existing instance.
          */
@@ -816,8 +778,36 @@ declare class Alepha {
         /**
          * Constructor arguments to pass when creating a new instance.
          */
-        args?: any[];
+        args?: ConstructorParameters<InstantiableService<T>>;
+        /**
+         * Parent service that requested the instance.
+         * @internal
+         */
+        parent?: Service | null;
+        /**
+         * If the service is provided by a module, the module definition.
+         * @internal
+         */
+        module?: ModuleDefinition;
     }): 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 object>(service: Service<T>, state: Partial<T>): void;
     /**
      * Registers a hook for the specified event.
      */
@@ -888,11 +878,15 @@ declare class Alepha {
      */
     parseEnv<T extends TObject>(schema: T): Static<T>;
     /**
-     * Create a new instance of a logger.
+     * Dump the current dependency graph of the App.
      *
-     * @returns The newly created logger instance.
+     * This method returns a record where the keys are the names of the services.
      */
-    protected createLogger(env: Env): Logger;
+    graph(): Record<string, {
+        from: string[];
+        as?: string;
+        module?: string;
+    }>;
     /**
      * @internal
      */
@@ -900,16 +894,20 @@ declare class Alepha {
     /**
      * @internal
      */
-    protected new<T extends object>(definition: Service<T>, args?: any[]): T;
+    protected new<T extends object>(definition: Service<T>, args?: any[], module?: ModuleDefinition): T;
     /**
-     * @interface
+     * @internal
      */
-    moduleOf(service: Service): Module | undefined;
+    protected createLogger(env: Env): Logger;
+    /**
+     * @internal
+     */
+    getModuleOf(service: Service): Module | undefined;
 }
 /**
  * This is how we store services in the Alepha container.
  */
-interface Definition<T extends object = any> {
+interface ServiceDefinition<T extends object = any> {
     /**
      * The class or type definition to provide.
      */
@@ -927,6 +925,31 @@ interface Definition<T extends object = any> {
      * List of classes which use this class.
      */
     parents: Array<Service | null>;
+    /**
+     * If the service is provided by a module, the module definition.
+     */
+    module?: ModuleDefinition;
+}
+
+interface RunOptions {
+    /**
+     * Environment variables to be used by the application.
+     * If not provided, it will use the current process environment.
+     */
+    env?: Env;
+    /**
+     * A callback that will be executed before the application starts.
+     */
+    configure?: (alepha: Alepha) => Async<void>;
+    /**
+     * A callback that will be executed once the application is ready.
+     * This is useful for initializing resources or starting background tasks.
+     */
+    ready?: (alepha: Alepha) => Async<void>;
+    /**
+     * If true, the application will stop after the ready callback is executed.
+     */
+    once?: boolean;
 }
 
 /**
@@ -973,6 +996,12 @@ declare const $env: typeof $inject;
  */
 declare const $logger: (name?: string) => Logger;
 
+/**
+ * Default error class for Alepha.
+ */
+declare class AlephaError extends Error {
+}
+
 declare class AppNotStartedError extends Error {
     constructor();
 }
@@ -1231,36 +1260,6 @@ interface AlephaStringOptions extends StringOptions {
 declare const t: TypeProvider;
 declare const isUUID: (value: string) => boolean;
 
-declare const substitute: <T extends object>(rule: {
-    provide: T;
-    use: T;
-    default?: boolean;
-}) => {
-    use: T;
-    provide: T;
-    default?: boolean;
-};
-interface RunOptions {
-    /**
-     * Environment variables to be used by the application.
-     * If not provided, it will use the current process environment.
-     */
-    env?: Env;
-    /**
-     * A callback that will be executed before the application starts.
-     */
-    configure?: (alepha: Alepha) => Async<void>;
-    /**
-     * A callback that will be executed once the application is ready.
-     * This is useful for initializing resources or starting background tasks.
-     */
-    ready?: (alepha: Alepha) => Async<void>;
-    /**
-     * If true, the application will stop after the ready callback is executed.
-     */
-    once?: boolean;
-}
-
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
 
-export { $cursor, $env, $hook, $inject, $logger, $module, type AbstractService, Alepha, type AlephaStringOptions, AppNotStartedError, type Async, type AsyncFn, type AsyncLocalStorageData, AsyncLocalStorageProvider, COLORS, CircularDependencyError, ContainerLockedError, type CursorDescriptor, type Descriptor, type DescriptorIdentifier, type DescriptorItem, type Env, type FileLike, type Hook, type HookDescriptor, type HookOptions, type Hooks, type InstantiableService, KIND, LEVEL_COLORS, type LogLevel, Logger, type LoggerEnv, type LoggerOptions, type MaybePromise, MockLogger, type MockLoggerStore, type Module, type ModuleDescriptor, type ModuleDescriptorOptions, NotImplementedError, OPTIONS, type PromiseFn, type RunOptions, type Service, type ServiceEntry, type ServiceSubstitution, type State, type StreamLike, type TFile, type TStream, type TextLength, TypeBoxError, TypeProvider, __alephaRef, __bind, __descriptor, descriptorEvents, isDescriptorValue, isFileLike, isTypeFile, isTypeStream, isUUID, run, substitute, t };
+export { $cursor, $env, $hook, $inject, $logger, type AbstractService, Alepha, AlephaError, type AlephaStringOptions, AppNotStartedError, type Async, type AsyncFn, type AsyncLocalStorageData, AsyncLocalStorageProvider, COLORS, CircularDependencyError, ContainerLockedError, type CursorDescriptor, type Descriptor, type DescriptorIdentifier, type DescriptorItem, type Env, type FileLike, type Hook, type HookDescriptor, type HookOptions, type Hooks, type InstantiableService, KIND, LEVEL_COLORS, type LogLevel, Logger, type LoggerEnv, type LoggerOptions, type MaybePromise, MockLogger, type MockLoggerStore, type Module, type ModuleDefinition, NotImplementedError, OPTIONS, type PromiseFn, type Service, type ServiceEntry, type ServiceSubstitution, type State, type StreamLike, type TFile, type TStream, type TextLength, TypeBoxError, TypeProvider, __alephaRef, __bind, __descriptor, descriptorEvents, isDescriptorValue, isFileLike, isModule, isTypeFile, isTypeStream, isUUID, run, t, toModuleName };

package/datetime.d.ts

@@ -1,7 +1,7 @@
 import * as _alepha_core from '@alepha/core';
 import { Async } from '@alepha/core';
 import dayjs, { ManipulateType, Dayjs } from 'dayjs';
-import dayjsDuration from 'dayjs/plugin/duration';
+import dayjsDuration from 'dayjs/plugin/duration.js';
 
 declare class Interval {
     private timer;
@@ -94,12 +94,18 @@ declare class DateTimeProvider {
     tick(): Promise<void>;
     /**
      * Wait for a certain duration.
+     *
+     * You can clear the timeout by using the `AbortSignal` API.
+     * Aborted signal will resolve the promise immediately, it does not reject it.
      */
-    wait(duration: DurationLike, signal?: AbortSignal): Promise<void>;
+    wait(duration: DurationLike, options?: {
+        signal?: AbortSignal;
+        now?: number;
+    }): Promise<void>;
     /**
      * Run a callback after a certain duration.
      */
-    timeout(callback: () => void, duration: DurationLike): Timeout;
+    timeout(callback: () => void, duration: DurationLike, now?: number): Timeout;
     /**
      * Create an interval.
      *
@@ -113,7 +119,7 @@ declare class DateTimeProvider {
     /**
      * Add time to the current date.
      */
-    travel(duration: DurationLike): Promise<void>;
+    travel(duration: DurationLike, unit?: ManipulateType): Promise<void>;
     /**
      * Stop the time.
      */

package/lock/redis.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+var lock = require('@alepha/lock');
+var topicRedis = require('@alepha/topic-redis');
+var core = require('@alepha/core');
+var redis = require('@alepha/redis');
+
+class RedisLockProvider {
+  log = core.$logger();
+  redisProvider = core.$inject(redis.RedisProvider);
+  async set(key, value, nx, px) {
+    const options = {
+      GET: true
+      // all the secrets of $lock is based on this
+    };
+    if (px) {
+      options.expiration = {
+        type: "PX",
+        value: px
+      };
+    }
+    if (nx) {
+      options.condition = "NX";
+    }
+    const resp = await this.redisProvider.set(key, value, options);
+    if (resp === null) {
+      this.log.debug(`Lock already exists`, { key, value });
+      return value;
+    }
+    return resp.toString("utf-8");
+  }
+  async del(...keys) {
+    await this.redisProvider.del(keys);
+  }
+}
+class AlephaLockRedis {
+  name = "alepha.lock.redis";
+  $services = (alepha) => alepha.with({
+    provide: lock.LockTopicProvider,
+    use: topicRedis.RedisTopicProvider,
+    optional: true
+  }).with({
+    provide: lock.LockProvider,
+    use: RedisLockProvider,
+    optional: true
+  }).with(lock.AlephaLock);
+}
+
+exports.AlephaLockRedis = AlephaLockRedis;
+exports.RedisLockProvider = RedisLockProvider;

package/lock/redis.d.ts

@@ -0,0 +1,26 @@
+import * as _alepha_core from '@alepha/core';
+import { Alepha } from '@alepha/core';
+import { LockProvider } from '@alepha/lock';
+import { RedisProvider } from '@alepha/redis';
+
+declare class RedisLockProvider implements LockProvider {
+    protected readonly log: _alepha_core.Logger;
+    protected readonly redisProvider: RedisProvider;
+    set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
+    del(...keys: string[]): Promise<void>;
+}
+
+/**
+ * Alepha Lock Redis Module
+ *
+ * Plugin for Alepha that provides a locking mechanism.
+ *
+ * @see {@link RedisLockProvider}
+ * @module alepha.lock.redis
+ */
+declare class AlephaLockRedis {
+    readonly name = "alepha.lock.redis";
+    readonly $services: (alepha: Alepha) => Alepha;
+}
+
+export { AlephaLockRedis, RedisLockProvider };

package/lock/redis.js

@@ -0,0 +1,47 @@
+import { LockTopicProvider, LockProvider, AlephaLock } from '@alepha/lock';
+import { RedisTopicProvider } from '@alepha/topic-redis';
+import { $logger, $inject } from '@alepha/core';
+import { RedisProvider } from '@alepha/redis';
+
+class RedisLockProvider {
+  log = $logger();
+  redisProvider = $inject(RedisProvider);
+  async set(key, value, nx, px) {
+    const options = {
+      GET: true
+      // all the secrets of $lock is based on this
+    };
+    if (px) {
+      options.expiration = {
+        type: "PX",
+        value: px
+      };
+    }
+    if (nx) {
+      options.condition = "NX";
+    }
+    const resp = await this.redisProvider.set(key, value, options);
+    if (resp === null) {
+      this.log.debug(`Lock already exists`, { key, value });
+      return value;
+    }
+    return resp.toString("utf-8");
+  }
+  async del(...keys) {
+    await this.redisProvider.del(keys);
+  }
+}
+class AlephaLockRedis {
+  name = "alepha.lock.redis";
+  $services = (alepha) => alepha.with({
+    provide: LockTopicProvider,
+    use: RedisTopicProvider,
+    optional: true
+  }).with({
+    provide: LockProvider,
+    use: RedisLockProvider,
+    optional: true
+  }).with(AlephaLock);
+}
+
+export { AlephaLockRedis, RedisLockProvider };