alepha 0.8.0 → 0.8.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Feunard
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Feunard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,44 +1,17 @@
-<div align="center">
+# Alepha Alepha
 
-<h1 >
-<img
-	src="https://raw.githubusercontent.com/feunard/alepha/main/assets/logo.png"
-	width="128"
-	height="128"
-	alt="Logo"
-  valign="middle"
-/>
-Alepha
-</h1>
-<p style="max-width: 512px">
-🚧
-</p>
-<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/v/alepha.svg" alt="npm"/></a>
-<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/l/alepha.svg" alt="npm"/></a>
-<a href="https://codecov.io/gh/feunard/alepha"><img src="https://codecov.io/gh/feunard/alepha/graph/badge.svg?token=ZDLWI514CP" alt="npm"/></a>
-<a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/dt/alepha.svg" alt="npm"/></a>
-<a href="https://github.com/feunard/alepha"><img src="https://img.shields.io/github/stars/feunard/alepha.svg?style=social" alt="GitHub stars"/></a>
-</div>
+TypeScript framework for building full-stack apps with strict conventions, and React-based SPA or SSR without filesystem-based routing.
 
 ## Installation
 
+This package is part of the Alepha framework and can be installed via the all-in-one package:
+
 ```bash
 npm install alepha
 ```
 
-## Usage
-
-Minimalist http server with a single endpoint.
-
-```ts
-import { run } from "alepha";
-import { $action } from "alepha/server";
+Alternatively, you can install it individually:
 
-class App {
-  hello = $action({
-    handler: () => "Hello world!",
-  })
-}
-
-run(App);
+```bash
+npm install @alepha/core alepha
 ```

package/batch.d.ts

@@ -4,6 +4,15 @@ import { RetryDescriptorOptions } from "alepha/retry";
 
 //#region src/descriptors/$batch.d.ts
 declare const KEY = "BATCH";
+/**
+* Creates a batch processor. This is useful for grouping multiple operations
+* (like API calls or database writes) into a single one to improve performance.
+*/
+declare const $batch: {
+  <TItem extends TSchema, TResponse>(options: BatchDescriptorOptions<TItem, TResponse>): BatchDescriptor<TItem, TResponse>;
+  [KIND]: string;
+};
+// ---------------------------------------------------------------------------------------------------------------------
 interface BatchDescriptorOptions<TItem extends TSchema, TResponse = any> {
   /**
   * A TypeBox schema to validate each item pushed to the batch.
@@ -55,14 +64,6 @@ interface BatchDescriptor<TItem extends TSchema, TResponse = any> {
   */
   flush: (partitionKey?: string) => Promise<TResponse>;
 }
-/**
-* Creates a batch processor. This is useful for grouping multiple operations
-* (like API calls or database writes) into a single one to improve performance.
-*/
-declare const $batch: {
-  <TItem extends TSchema, TResponse>(options: BatchDescriptorOptions<TItem, TResponse>): BatchDescriptor<TItem, TResponse>;
-  [KIND]: string;
-};
 //#endregion
 //#region src/providers/BatchDescriptorProvider.d.ts
 interface PartitionState<TItem extends TSchema> {
@@ -81,6 +82,9 @@ interface BatchInstance<TItem extends TSchema> {
   activeHandlers: PromiseWithResolvers<void>[];
   handler: (items: Static<TItem>[]) => Promise<void>;
 }
+/**
+* Process every $batch.
+*/
 declare class BatchDescriptorProvider {
   protected readonly alepha: Alepha;
   protected readonly log: Logger;
@@ -97,10 +101,39 @@ declare class BatchDescriptorProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Batch Module
+* This module allows you to group multiple asynchronous operations into a single "batch," which is then processed together.
+* This is an essential pattern for improving performance, reducing I/O, and interacting efficiently with rate-limited APIs or databases.
+*
+* ### Basic Example: A Simple Event Logger
+*
+* Let's create a batch processor that collects log messages and prints them to the console every 5 seconds or whenever 10 messages have been collected.
+*
+* ```ts
+* import { Alepha, $hook, run, t } from "alepha";
+* import { $batch } from "alepha/batch";
+*
+* class LoggingService {
+*   // define the batch processor
+*   logBatch = $batch({
+*     schema: t.string(),
+*     maxSize: 10,
+*     maxDuration: [5, "seconds"],
+*     handler: async (items) => {
+*       console.log(`[BATCH LOG] Processing ${items.length} events:`, items);
+*     },
+*   });
 *
-* This module provides a powerful batch processing utility that can group
-* multiple operations into a single one based on size, time, or partitions.
+*   // example of how to use it
+*   onReady = $hook({
+*     on: "ready",
+*     handler: async () => {
+*       this.logBatch.push("Application started.");
+*       this.logBatch.push("User authenticated.");
+*       // ... more events pushed from elsewhere in the app
+*     },
+*   });
+* }
+* ```
 *
 * @see {@link $batch}
 * @module alepha.batch

package/cache/redis.d.ts

@@ -25,8 +25,6 @@ declare class RedisCacheProvider implements CacheProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Cache Redis Module
-*
 * Plugin for Alepha Cache that provides Redis caching capabilities.
 *
 * @see {@link RedisCacheProvider}

package/cache.d.ts

@@ -208,9 +208,77 @@ interface Cache<TReturn = any, TParameter extends any[] = any[]> {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Cache Module
+* Provides high-performance caching capabilities for Alepha applications with configurable TTL and multiple storage backends.
 *
-* This module provides a caching mechanism for Alepha applications.
+* The cache module enables declarative caching through the `$cache` descriptor, allowing you to cache method results,
+* API responses, or computed values with automatic invalidation and type safety. It supports both in-memory and
+* persistent storage backends for different performance and durability requirements.
+*
+* **Key Features:**
+* - Declarative caching with `$cache` descriptor on class properties
+* - Configurable TTL (time-to-live) with duration literals
+* - Custom key generation and automatic serialization
+* - Multiple storage backends (memory, Redis, etc.)
+* - Cache invalidation and manual cache operations
+* - Type-safe operations with full TypeScript support
+*
+* **Basic Usage:**
+* ```ts
+* import { Alepha, run } from "alepha";
+* import { AlephaCache, $cache } from "alepha/cache";
+*
+* class UserService {
+*   getUserData = $cache({
+*     key: (userId: string) => `user:${userId}`,
+*     ttl: [1, "hour"],
+*     handler: async (userId: string) => {
+*       // This will be cached for 1 hour
+*       return await fetchUserFromDatabase(userId);
+*     },
+*   });
+*
+*   getUserProfile = $cache({
+*     provider: "memory",
+*     ttl: [5, "minutes"],
+*     handler: async (userId: string) => {
+*       return await buildUserProfile(userId);
+*     },
+*   });
+* }
+*
+* const alepha = Alepha.create()
+*   .with(AlephaCache)
+*   .with(UserService);
+*
+* run(alepha);
+* ```
+*
+* **Cache Operations:**
+* ```ts
+* class ProductService {
+*   productCache = $cache({
+*     handler: async (productId: string) => {
+*       return await getProduct(productId);
+*     },
+*   });
+*
+*   async getProduct(id: string) {
+*     // Get from cache or compute
+*     return await this.productCache(id);
+*   }
+*
+*   async updateProduct(id: string, data: any) {
+*     await updateProductInDb(id, data);
+*     // Invalidate cache
+*     await this.productCache.invalidate(this.productCache.key(id));
+*   }
+*
+*   async warmUpCache(id: string, data: any) {
+*     // Manually set cache
+*     await this.productCache.set(this.productCache.key(id), data, [30, "minutes"]);
+*   }
+* }
+* ```
 *
 * @see {@link $cache}
 * @see {@link CacheProvider}

package/command.d.ts

@@ -38,6 +38,16 @@ declare class Runner {
 //#endregion
 //#region src/descriptors/$command.d.ts
 declare const KEY = "COMMAND";
+/**
+* Declares a CLI command.
+*
+* This descriptor allows you to define a command, its flags, and its handler
+* within your Alepha application structure.
+*/
+declare const $command: {
+  <T extends TObject>(options: CommandDescriptorOptions<T>): CommandDescriptor<T>;
+  [KIND]: string;
+};
 interface CommandDescriptorOptions<T extends TObject> {
   /**
   * The handler function to execute when the command is matched.
@@ -75,16 +85,6 @@ interface CommandDescriptor<T extends TObject> {
   */
   (flags: Static<T>): Promise<void>;
 }
-/**
-* Declares a CLI command.
-*
-* This descriptor allows you to define a command, its flags, and its handler
-* within your Alepha application structure.
-*/
-declare const $command: {
-  <T extends TObject>(options: CommandDescriptorOptions<T>): CommandDescriptor<T>;
-  [KIND]: string;
-};
 //#endregion
 //#region src/errors/CommandError.d.ts
 declare class CommandError extends AlephaError {}
@@ -137,9 +137,7 @@ declare class CommandDescriptorProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Command Module
-*
-* This module provides a powerful way to build command-line interfaces
+*This module provides a powerful way to build command-line interfaces
 * directly within your Alepha application, using declarative descriptors.
 *
 * @see {@link $command}

package/core.d.ts

@@ -85,38 +85,6 @@ type ServiceEntry<T extends object = any> = Service<T> | ServiceSubstitution<T>;
 //#endregion
 //#region src/descriptors/$hook.d.ts
 declare const KEY = "HOOK";
-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: (app: Hooks[T]) => Async<any>;
-  /**
-  * Force the hook to run first or last on the list of hooks.
-  */
-  priority?: "first" | "last";
-  /**
-  * Empty placeholder, not working yet. :-)
-  */
-  before?: object | Array<object>;
-  /**
-  * Empty placeholder, not working yet. :-)
-  */
-  after?: object | Array<object>;
-}
-interface Hook<T extends keyof Hooks = any> {
-  caller?: Service;
-  priority?: "first" | "last";
-  callback: (payload: Hooks[T]) => Async<void>;
-}
-interface HookDescriptor<T extends keyof Hooks> {
-  [KIND]: typeof KEY;
-  [OPTIONS]: HookOptions<T>;
-  (app: Hooks[T]): Async<any>;
-}
 /**
 * Registers a new hook.
 *
@@ -160,6 +128,38 @@ declare const $hook: {
   <T extends keyof Hooks>(options: HookOptions<T>): HookDescriptor<T>;
   [KIND]: string;
 };
+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: (app: Hooks[T]) => Async<any>;
+  /**
+  * Force the hook to run first or last on the list of hooks.
+  */
+  priority?: "first" | "last";
+  /**
+  * Empty placeholder, not working yet. :-)
+  */
+  before?: object | Array<object>;
+  /**
+  * Empty placeholder, not working yet. :-)
+  */
+  after?: object | Array<object>;
+}
+interface Hook<T extends keyof Hooks = any> {
+  caller?: Service;
+  priority?: "first" | "last";
+  callback: (payload: Hooks[T]) => Async<void>;
+}
+interface HookDescriptor<T extends keyof Hooks> {
+  [KIND]: typeof KEY;
+  [OPTIONS]: HookOptions<T>;
+  (app: Hooks[T]): Async<any>;
+}
 //#endregion
 //#region src/helpers/Module.d.ts
 interface Module {
@@ -174,6 +174,28 @@ declare const isModule: (value: unknown) => value is Module;
 declare const toModuleName: (name: string) => string;
 //#endregion
 //#region src/descriptors/$cursor.d.ts
+/**
+* Get Alepha instance and Class definition from the current context.
+* This should be used inside a descriptor only.
+*
+* ```ts
+* import { $cursor } from "alepha";
+*
+* const $ = () => {
+*
+*   const { context, definition } = $cursor();
+*
+*   // context - alepha instance
+*   // definition - class which is creating this descriptor
+*
+*   return {};
+* }
+*
+* ```
+*
+* @internal
+*/
+declare const $cursor: () => CursorDescriptor;
 // ---------------------------------------------------------------------------------------------------------------------
 /**
 * /!\ Global variable /!\
@@ -200,28 +222,6 @@ interface CursorDescriptor {
   definition?: Service;
   module?: ModuleDefinition;
 }
-/**
-* Get Alepha instance and Class definition from the current context.
-* This should be used inside a descriptor only.
-*
-* ```ts
-* import { $cursor } from "alepha";
-*
-* const $ = () => {
-*
-*   const { context, definition } = $cursor();
-*
-*   // context - alepha instance
-*   // definition - class which is creating this descriptor
-*
-*   return {};
-* }
-*
-* ```
-*
-* @internal
-*/
-declare const $cursor: () => CursorDescriptor;
 //#endregion
 //#region src/helpers/EventEmitterLike.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
@@ -461,81 +461,6 @@ interface MockLoggerStore {
 }
 //#endregion
 //#region src/Alepha.d.ts
-// ---------------------------------------------------------------------------------------------------------------------
-interface Env extends LoggerEnv {
-  [key: string]: string | boolean | number | undefined;
-  /**
-  * Optional environment variable that indicates the current environment.
-  */
-  NODE_ENV?: "dev" | "test" | "production";
-  /**
-  * Optional name of the application.
-  */
-  APP_NAME?: string;
-  /**
-  * Optional root module name.
-  */
-  MODULE_NAME?: string;
-  /**
-  * If true, the container will not automatically register the default providers based on the descriptors.
-  *
-  * It means that you have to alepha.with(ServiceModule) manually. No magic.
-  *
-  * @default false
-  */
-  EXPLICIT_PROVIDERS?: boolean;
-}
-// ---------------------------------------------------------------------------------------------------------------------
-interface State {
-  log: Logger;
-  env?: Readonly<Env>;
-  // test hooks
-  beforeAll?: (run: any) => any;
-  afterAll?: (run: any) => any;
-  afterEach?: (run: any) => any;
-  onTestFinished?: (run: any) => any;
-}
-// ---------------------------------------------------------------------------------------------------------------------
-interface Hooks {
-  echo: any;
-  /**
-  * Triggered during the configuration phase. Before the start phase.
-  */
-  configure: Alepha;
-  /**
-  * Triggered during the start phase. When `Alepha#start()` is called.
-  */
-  start: Alepha;
-  /**
-  * Triggered during the ready phase. After the start phase.
-  */
-  ready: Alepha;
-  /**
-  * Triggered during the stop phase.
-  *
-  * - Stop should be called after a SIGINT or SIGTERM signal in order to gracefully shutdown the application. (@see `run()` method)
-  *
-  */
-  stop: Alepha;
-  /**
-  * Triggered when a state value is mutated.
-  */
-  "state:mutate": {
-    /**
-    * The key of the state that was mutated.
-    */
-    key: keyof State;
-    /**
-    * The new value of the state.
-    */
-    value: any;
-    /**
-    * The previous value of the state.
-    */
-    prevValue: any;
-  };
-}
-// ---------------------------------------------------------------------------------------------------------------------
 /**
 * Core container of the Alepha framework.
 *
@@ -561,9 +486,9 @@ interface Hooks {
 * ```
 *
 * > Some alepha methods are not intended to be used directly, use descriptors instead.
-*
-* - $hook -> alepha.on()
-* - $inject -> alepha.get(), alepha.parseEnv()
+* >
+* > - $hook -> alepha.on()
+* > - $inject -> alepha.get(), alepha.parseEnv()
 */
 declare class Alepha {
   /**
@@ -846,6 +771,9 @@ declare class Alepha {
     options: object;
   }>(service: Service<T>, state: Partial<T["options"]>): this;
   // -------------------------------------------------------------------------------------------------------------------
+  protected useCounter: number;
+  use<T extends Descriptor>(descriptor: T, options: Parameters<T>[0]): ReturnType<T>;
+  // -------------------------------------------------------------------------------------------------------------------
   /**
   * Registers a hook for the specified event.
   */
@@ -969,6 +897,80 @@ interface ServiceDefinition<T extends object = any> {
   */
   module?: ModuleDefinition;
 }
+// ---------------------------------------------------------------------------------------------------------------------
+interface Env extends LoggerEnv {
+  [key: string]: string | boolean | number | undefined;
+  /**
+  * Optional environment variable that indicates the current environment.
+  */
+  NODE_ENV?: "dev" | "test" | "production";
+  /**
+  * Optional name of the application.
+  */
+  APP_NAME?: string;
+  /**
+  * Optional root module name.
+  */
+  MODULE_NAME?: string;
+  /**
+  * If true, the container will not automatically register the default providers based on the descriptors.
+  *
+  * It means that you have to alepha.with(ServiceModule) manually. No magic.
+  *
+  * @default false
+  */
+  EXPLICIT_PROVIDERS?: boolean;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+interface State {
+  log: Logger;
+  env?: Readonly<Env>;
+  // test hooks
+  beforeAll?: (run: any) => any;
+  afterAll?: (run: any) => any;
+  afterEach?: (run: any) => any;
+  onTestFinished?: (run: any) => any;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+interface Hooks {
+  echo: any;
+  /**
+  * Triggered during the configuration phase. Before the start phase.
+  */
+  configure: Alepha;
+  /**
+  * Triggered during the start phase. When `Alepha#start()` is called.
+  */
+  start: Alepha;
+  /**
+  * Triggered during the ready phase. After the start phase.
+  */
+  ready: Alepha;
+  /**
+  * Triggered during the stop phase.
+  *
+  * - Stop should be called after a SIGINT or SIGTERM signal in order to gracefully shutdown the application. (@see `run()` method)
+  *
+  */
+  stop: Alepha;
+  /**
+  * Triggered when a state value is mutated.
+  */
+  "state:mutate": {
+    /**
+    * The key of the state that was mutated.
+    */
+    key: keyof State;
+    /**
+    * The new value of the state.
+    */
+    value: any;
+    /**
+    * The previous value of the state.
+    */
+    prevValue: any;
+  };
+}
 //#endregion
 //#region src/interfaces/Run.d.ts
 interface RunOptions {
@@ -1019,7 +1021,6 @@ declare class InjectResolverRegistry {
 declare const $injectResolverRegistry: InjectResolverRegistry;
 //#endregion
 //#region src/descriptors/$logger.d.ts
-// ---------------------------------------------------------------------------------------------------------------------
 /**
 * Create a logger.
 *
@@ -1285,6 +1286,9 @@ declare const t: TypeProvider;
 declare const isUUID: (value: string) => boolean;
 //#endregion
 //#region src/index.d.ts
+/**
+*
+*/
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
 //#endregion
 export { $cursor, $hook, $inject, $injectResolverRegistry, $logger, AbstractService, Alepha, AlephaError, AlephaStringOptions, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, COLORS, CircularDependencyError, ContainerLockedError, CursorDescriptor, Descriptor, DescriptorIdentifier, DescriptorItem, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InstantiableService, KIND, LEVEL_COLORS, LogLevel, Logger, LoggerEnv, LoggerOptions, MaybePromise, MockLogger, MockLoggerStore, Module, ModuleDefinition, NotImplementedError, OPTIONS, PromiseFn, Service, ServiceEntry, ServiceSubstitution, State, Static, StaticDecode, StaticEncode, StreamLike, TAny, TArray, TBoolean, TFile, TNumber, TObject, TOptional, TProperties, TRecord, TSchema, TStream, TString, TextLength, TypeBox, TypeBoxError, TypeBoxValue, TypeGuard, TypeProvider, __alephaRef, __bind, __descriptor, descriptorEvents, isDescriptorValue, isFileLike, isModule, isTypeFile, isTypeStream, isUUID, run, t, toModuleName };

package/datetime.d.ts

@@ -134,6 +134,10 @@ declare class DateTimeProvider {
 }
 //#endregion
 //#region src/descriptors/$interval.d.ts
+/**
+* Registers a new interval.
+*/
+declare const $interval: (options: IntervalDescriptorOptions) => Interval;
 interface IntervalDescriptorOptions {
   /**
   * Whether to start the interval immediately.
@@ -158,10 +162,6 @@ interface IntervalDescriptorOptions {
   */
   duration: DurationLike;
 }
-/**
-* Registers a new interval.
-*/
-declare const $interval: (options: IntervalDescriptorOptions) => Interval;
 //#endregion
 export { $interval, DateTime, DateTimeProvider, Duration, DurationLike, Interval, IntervalDescriptorOptions, Timeout };
 //# sourceMappingURL=index.d.ts.map

package/file.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/file');
+Object.keys(m).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return m[k]; }
+	});
+});