alepha 0.7.7 → 0.8.1

package/cache.d.ts

@@ -1,43 +1,41 @@
-import * as _alepha_core0 from "@alepha/core";
-import * as _alepha_core5 from "@alepha/core";
-import { Alepha, KIND, Module, OPTIONS, Static } from "@alepha/core";
-import { DateTimeProvider, DurationLike, Timeout } from "@alepha/datetime";
-import * as _sinclair_typebox1 from "@sinclair/typebox";
+import { Alepha, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TBoolean, TNumber, TObject, TOptional, TString } from "alepha";
+import { DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
 
 //#region src/providers/CacheProvider.d.ts
+
 /**
- * Cache provider interface.
- *
- * All methods are asynchronous and return promises.
- * Values are stored as Uint8Array.
- */
+* Cache provider interface.
+*
+* All methods are asynchronous and return promises.
+* Values are stored as Uint8Array.
+*/
 declare abstract class CacheProvider {
   /**
-   * Get the value of a key.
-   *
-   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-   * @param key The key of the value to get.
-   *
-   * @return The value of the key, or undefined if the key does not exist.
-   */
+  * Get the value of a key.
+  *
+  * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+  * @param key The key of the value to get.
+  *
+  * @return The value of the key, or undefined if the key does not exist.
+  */
   abstract get(name: string, key: string): Promise<Uint8Array | undefined>;
   /**
-   * Set the string value of a key.
-   *
-   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-   * @param key The key of the value to set.
-   * @param value The value to set.
-   * @param ttl The time-to-live of the key, in milliseconds.
-   *
-   * @return The value of the key.
-   */
+  * Set the string value of a key.
+  *
+  * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+  * @param key The key of the value to set.
+  * @param value The value to set.
+  * @param ttl The time-to-live of the key, in milliseconds.
+  *
+  * @return The value of the key.
+  */
   abstract set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
   /**
-   * Remove the specified keys.
-   *
-   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-   * @param keys The keys to delete.
-   */
+  * Remove the specified keys.
+  *
+  * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+  * @param keys The keys to delete.
+  */
   abstract del(name: string, ...keys: string[]): Promise<void>;
   abstract has(name: string, key: string): Promise<boolean>;
   abstract keys(name: string): Promise<string[]>;
@@ -46,76 +44,77 @@ declare abstract class CacheProvider {
 //#region src/descriptors/$cache.d.ts
 declare const KEY = "CACHE";
 /**
- * Cache Descriptor
- */
+* Cache Descriptor
+*/
 declare const $cache: {
   <TReturn = string, TParameter extends any[] = any[]>(options?: CacheDescriptorOptions<TReturn, TParameter>): CacheDescriptor<TReturn, TParameter>;
   [KIND]: string;
 };
+// ---------------------------------------------------------------------------------------------------------------------
 interface CacheDescriptorOptions<TReturn, TParameter extends any[] = any[]> {
   /**
-   * The cache name. This is useful for invalidating multiple caches at once.
-   *
-   * Store key as `cache:$name:$key`.
-   *
-   * @default ClassName:methodName
-   */
+  * The cache name. This is useful for invalidating multiple caches at once.
+  *
+  * Store key as `cache:$name:$key`.
+  *
+  * @default ClassName:methodName
+  */
   name?: string;
   /**
-   * Function which returns cached data.
-   * @param args Arguments for handler.
-   */
+  * Function which returns cached data.
+  * @param args Arguments for handler.
+  */
   handler?: (...args: TParameter) => TReturn;
   /**
-   * The key generator for the cache.
-   * If not provided, the arguments will be json.stringify().
-   */
+  * The key generator for the cache.
+  * If not provided, the arguments will be json.stringify().
+  */
   key?: (...args: TParameter) => string;
   /**
-   * The store provider for the cache.
-   * If not provided, the default store provider will be used.
-   */
+  * The store provider for the cache.
+  * If not provided, the default store provider will be used.
+  */
   provider?: CacheProvider | (() => CacheProvider) | "memory";
   /**
-   * The time-to-live for the cache in seconds.
-   * Set 0 to skip expiration.
-   *
-   * @default 300 (5 minutes).
-   */
+  * The time-to-live for the cache in seconds.
+  * Set 0 to skip expiration.
+  *
+  * @default 300 (5 minutes).
+  */
   ttl?: DurationLike;
   /**
-   * If the cache is disabled.
-   */
+  * If the cache is disabled.
+  */
   disabled?: boolean;
 }
 interface CacheDescriptor<TReturn = any, TParameter extends any[] = any[]> {
   [KIND]: typeof KEY;
   [OPTIONS]: CacheDescriptorOptions<TReturn, TParameter>;
   /**
-   * Cache handler.
-   */
+  * Cache handler.
+  */
   (...args: TParameter): Promise<TReturn>;
   /**
-   * Cache key generator.
-   */
+  * Cache key generator.
+  */
   key: (...args: TParameter) => string;
   /**
-   * Invalidate cache by keys.
-   */
+  * Invalidate cache by keys.
+  */
   invalidate: (...keys: string[]) => Promise<void>;
   /**
-   * Set cache with key, value and ttl.
-   *
-   * @param key
-   * @param value
-   * @param ttl
-   */
+  * Set cache with key, value and ttl.
+  *
+  * @param key
+  * @param value
+  * @param ttl
+  */
   set: (key: string, value: TReturn, ttl?: DurationLike) => Promise<void>;
   /**
-   * Get cache by key.
-   *
-   * @param key
-   */
+  * Get cache by key.
+  *
+  * @param key
+  */
   get: (key: string) => Promise<TReturn | undefined>;
 }
 //#endregion
@@ -128,7 +127,7 @@ type CacheValue = {
 };
 declare class MemoryCacheProvider implements CacheProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _alepha_core0.Logger;
+  protected readonly log: Logger;
   protected store: Record<CacheName, Record<CacheKey, CacheValue>>;
   get(name: string, key: string): Promise<Uint8Array | undefined>;
   set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
@@ -138,10 +137,10 @@ declare class MemoryCacheProvider implements CacheProvider {
 }
 //#endregion
 //#region src/providers/CacheDescriptorProvider.d.ts
-declare const envSchema: _alepha_core5.TObject<{
-  CACHE_DEFAULT_TTL: _sinclair_typebox1.TNumber;
-  CACHE_PREFIX: _sinclair_typebox1.TOptional<_sinclair_typebox1.TString>;
-  CACHE_ENABLED: _sinclair_typebox1.TBoolean;
+declare const envSchema: TObject<{
+  CACHE_DEFAULT_TTL: TNumber;
+  CACHE_PREFIX: TOptional<TString>;
+  CACHE_ENABLED: TBoolean;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
@@ -151,57 +150,53 @@ declare class CacheDescriptorProvider {
   protected readonly cacheProvider: CacheProvider;
   protected readonly memoryCacheProvider: MemoryCacheProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly env: {
-    CACHE_PREFIX?: string | undefined;
-    CACHE_DEFAULT_TTL: number;
-    CACHE_ENABLED: boolean;
-  };
+  protected readonly env: Static<typeof envSchema>;
   protected readonly caches: Cache[];
-  protected readonly configure: _alepha_core5.HookDescriptor<"configure">;
-  register(cache: Cache): Cache<any, any[]>;
+  protected encoder: TextEncoder;
+  protected decoder: TextDecoder;
+  protected codes: {
+    BINARY: number;
+    JSON: number;
+    STRING: number;
+  };
+  protected readonly configure: HookDescriptor<"configure">;
+  register(cache: Cache): Cache;
   processDescriptors(): void;
   getCaches(): Cache[];
   /**
-   * Clear all cache entries.
-   */
+  * Clear all cache entries.
+  */
   clear(): Promise<void>;
   /**
-   * Get the store provider for the given cache options.
-   *
-   * @param options
-   */
+  * Get the store provider for the given cache options.
+  *
+  * @param options
+  */
   provider(options: Pick<CacheDescriptorOptions<any[], any>, "provider">): CacheProvider;
   /**
-   * Get the cache key for the given state and arguments.
-   */
+  * Get the cache key for the given state and arguments.
+  */
   key(cache: Cache, ...args: any[]): string;
   /**
-   * Invalidate the cache for the given state and arguments.
-   */
+  * Invalidate the cache for the given state and arguments.
+  */
   invalidate(cache: Cache, ...keys: string[]): Promise<void>;
   /**
-   * Run the cache handler with the given state and arguments.
-   * You must run on a $cache with a handler defined.
-   */
+  * Run the cache handler with the given state and arguments.
+  * You must run on a $cache with a handler defined.
+  */
   run<TReturn, TParameter extends any[]>(cache: Cache<TReturn, TParameter>, ...args: TParameter): Promise<TReturn>;
   get<TReturn>(cache: Cache<TReturn>, key: string): Promise<TReturn | undefined>;
   /**
-   * Manually set a value in the cache.
-   * It's used by .run() method, but you will need it when you don't have cache handler defined.
-   *
-   * @param cache Cache object with all configuration and options (even TTL).
-   * @param key Cache key, build with .key() method or manually.
-   * @param value Value to store in cache.
-   * @param ttl Override cache.ttl option.
-   */
+  * Manually set a value in the cache.
+  * It's used by .run() method, but you will need it when you don't have cache handler defined.
+  *
+  * @param cache Cache object with all configuration and options (even TTL).
+  * @param key Cache key, build with .key() method or manually.
+  * @param value Value to store in cache.
+  * @param ttl Override cache.ttl option.
+  */
   set<TReturn>(cache: Cache<TReturn>, key: string, value: TReturn, ttl?: DurationLike): Promise<void>;
-  protected encoder: TextEncoder;
-  protected decoder: TextDecoder;
-  protected codes: {
-    BINARY: number;
-    JSON: number;
-    STRING: number;
-  };
   protected serialize<TReturn>(value: TReturn): Uint8Array;
   protected deserialize<TReturn>(uint8Array: Uint8Array): Promise<TReturn>;
 }
@@ -211,15 +206,84 @@ interface Cache<TReturn = any, TParameter extends any[] = any[]> {
 }
 //#endregion
 //#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
 /**
- * Alepha Cache Module
- *
- * This module provides a caching mechanism for Alepha applications.
- *
- * @see {@link $cache}
- * @see {@link CacheProvider}
- * @module alepha.cache
- */
+* Provides high-performance caching capabilities for Alepha applications with configurable TTL and multiple storage backends.
+*
+* 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}
+* @module alepha.cache
+*/
 declare class AlephaCache implements Module {
   readonly name = "alepha.cache";
   readonly $services: (alepha: Alepha) => Alepha;

package/command.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/command');
+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]; }
+	});
+});

package/command.d.ts

@@ -0,0 +1,152 @@
+import { Alepha, AlephaError, Async, HookDescriptor, KIND, Logger, Module, OPTIONS, Static, TObject, TProperties, TSchema, TString } from "alepha";
+import * as fs from "node:fs/promises";
+import { glob } from "node:fs/promises";
+
+//#region src/helpers/Runner.d.ts
+type Task = {
+  name: string;
+  handler: () => any;
+};
+interface Timer {
+  name: string;
+  duration: string;
+}
+interface RunnerMethod {
+  (cmd: string | Array<string | Task>, fn?: () => any): Promise<string>;
+  rm: (glob: string | string[]) => Promise<string>;
+}
+declare class Runner {
+  protected readonly log: Logger;
+  protected readonly timers: Timer[];
+  protected readonly startTime: number;
+  readonly run: RunnerMethod;
+  constructor(log: Logger);
+  protected exec(cmd: string): Promise<string>;
+  /**
+  * Executes one or more tasks.
+  *
+  * @param task - A single task or an array of tasks to run in parallel.
+  */
+  protected execute(task: Task | Task[]): Promise<string>;
+  /**
+  * Prints a summary of all executed tasks and their durations.
+  */
+  summary(): void;
+  protected executeTask(task: Task): Promise<string>;
+  protected renderTable(data: string[][]): void;
+}
+//#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.
+  */
+  handler: (args: {
+    flags: Static<T>;
+    run: RunnerMethod;
+    glob: typeof glob;
+    fs: typeof fs;
+  }) => Async<void>;
+  /**
+  * The name of the command. If omitted, the property key is used.
+  *
+  * An empty string "" denotes the root command.
+  */
+  name?: string;
+  /**
+  * A short description of the command, shown in the help message.
+  */
+  description?: string;
+  /**
+  * An array of alternative names for the command.
+  */
+  aliases?: string[];
+  /**
+  * A TypeBox object schema defining the flags for the command.
+  */
+  flags?: T;
+}
+interface CommandDescriptor<T extends TObject> {
+  [KIND]: typeof KEY;
+  [OPTIONS]: CommandDescriptorOptions<T>;
+  /**
+  * Executes the command. This is a placeholder and will be replaced by the provider.
+  */
+  (flags: Static<T>): Promise<void>;
+}
+//#endregion
+//#region src/errors/CommandError.d.ts
+declare class CommandError extends AlephaError {}
+//#endregion
+//#region src/providers/CommandDescriptorProvider.d.ts
+interface Command {
+  key: string;
+  name: string;
+  description?: string;
+  aliases: string[];
+  flags: TObject<TProperties>;
+  handler: (flags: any) => Promise<void>;
+}
+declare const envSchema: TObject<{
+  CLI_NAME: TString;
+  CLI_DESCRIPTION: TString;
+}>;
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
+declare class CommandDescriptorProvider {
+  protected readonly env: Static<typeof envSchema>;
+  protected readonly alepha: Alepha;
+  protected readonly log: Logger;
+  protected commands: Command[];
+  options: {
+    name: string;
+    description: string;
+    argv: string[];
+  };
+  protected readonly globalFlags: Record<string, {
+    aliases: string[];
+    description: string;
+    schema: TSchema;
+  }>;
+  protected readonly onConfigure: HookDescriptor<"configure">;
+  protected readonly onReady: HookDescriptor<"ready">;
+  private findCommand;
+  protected parseCommandFlags(argv: string[], schema: TObject): Record<string, any>;
+  protected parseFlags(argv: string[], flagDefs: {
+    key: string;
+    aliases: string[];
+    schema: TSchema;
+  }[]): Record<string, any>;
+  private printHelp;
+  private getMaxCmdLength;
+  private getMaxFlagLength;
+}
+//#endregion
+//#region src/index.d.ts
+// ---------------------------------------------------------------------------------------------------------------------
+/**
+*This module provides a powerful way to build command-line interfaces
+* directly within your Alepha application, using declarative descriptors.
+*
+* @see {@link $command}
+* @module alepha.command
+*/
+declare class AlephaCommand implements Module {
+  readonly name = "alepha.command";
+  readonly $services: (alepha: Alepha) => Alepha;
+}
+//#endregion
+export { $command, AlephaCommand, CommandDescriptor, CommandDescriptorOptions, CommandDescriptorProvider, CommandError, Runner, RunnerMethod, Task };
+//# sourceMappingURL=index.d.ts.map

package/command.js

@@ -0,0 +1 @@
+export * from '@alepha/command'