alepha 0.11.3 → 0.11.4

package/cache.d.ts

@@ -1,288 +1 @@
-import * as _alepha_core0 from "alepha";
-import { Descriptor, InstantiableClass, KIND } from "alepha";
-import { DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
-import * as _alepha_logger0 from "alepha/logger";
-
-//#region src/providers/CacheProvider.d.ts
-/**
- * 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.
-   */
-  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.
-   */
-  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.
-   */
-  abstract del(name: string, ...keys: string[]): Promise<void>;
-  abstract has(name: string, key: string): Promise<boolean>;
-  abstract keys(name: string, filter?: string): Promise<string[]>;
-  /**
-   * Remove all keys from all cache names.
-   */
-  abstract clear(): Promise<void>;
-}
-//#endregion
-//#region src/descriptors/$cache.d.ts
-/**
- * Creates a cache descriptor for high-performance data caching with automatic cache management.
- *
- * This descriptor provides a powerful caching layer that can significantly improve application performance
- * by storing frequently accessed data in memory or external cache stores like Redis. It supports both
- * function result caching and manual cache operations with intelligent serialization and TTL management.
- *
- * **Key Features**
- *
- * - **Function Result Caching**: Automatically cache function results based on input parameters
- * - **Multiple Storage Backends**: Support for in-memory, Redis, and custom cache providers
- * - **Intelligent Serialization**: Automatic handling of JSON, strings, and binary data
- * - **TTL Management**: Configurable time-to-live with automatic expiration
- * - **Cache Invalidation**: Pattern-based cache invalidation with wildcard support
- * - **Environment Controls**: Enable/disable caching via environment variables
- * - **Type Safety**: Full TypeScript support with generic type parameters
- *
- * ## Cache Strategies
- *
- * ### 1. Function Result Caching (Memoization)
- * Automatically cache the results of expensive operations based on input parameters.
- *
- * ### 2. Manual Cache Operations
- * Direct cache operations for custom caching logic and data storage.
- *
- * ## Storage Backends
- *
- * - **Memory**: Fast in-memory cache (default for development)
- * - **Redis**: Distributed cache for production environments
- * - **Custom Providers**: Implement your own cache storage backend
- *
- * @example
- * **Basic function result caching:**
- * ```ts
- * import { $cache } from "alepha/cache";
- *
- * class DataService {
- *   // Cache expensive database queries
- *   getUserData = $cache({
- *     name: "user-data",
- *     ttl: [10, "minutes"],
- *     handler: async (userId: string) => {
- *       // Expensive database operation
- *       return await database.users.findById(userId);
- *     }
- *   });
- *
- *   async getUser(id: string) {
- *     // This will hit cache on subsequent calls with same ID
- *     return await this.getUserData(id);
- *   }
- * }
- * ```
- *
- * @example
- * **API response caching with custom key generation:**
- * ```ts
- * class ApiService {
- *   fetchUserPosts = $cache({
- *     name: "user-posts",
- *     ttl: [5, "minutes"],
- *     key: (userId: string, page: number) => `${userId}:page:${page}`,
- *     handler: async (userId: string, page: number = 1) => {
- *       const response = await fetch(`/api/users/${userId}/posts?page=${page}`);
- *       return await response.json();
- *     }
- *   });
- * }
- * ```
- *
- * @example
- * **Manual cache operations for custom logic:**
- * ```ts
- * class SessionService {
- *   sessionCache = $cache<UserSession>({
- *     name: "user-sessions",
- *     ttl: [1, "hour"],
- *     provider: "memory"  // Use memory cache for sessions
- *   });
- *
- *   async storeSession(sessionId: string, session: UserSession) {
- *     await this.sessionCache.set(sessionId, session);
- *   }
- *
- *   async getSession(sessionId: string): Promise<UserSession | undefined> {
- *     return await this.sessionCache.get(sessionId);
- *   }
- *
- *   async invalidateUserSessions(userId: string) {
- *     // Invalidate all sessions for a user using wildcards
- *     await this.sessionCache.invalidate(`user:${userId}:*`);
- *   }
- * }
- * ```
- *
- * @example
- * **Redis-backed caching for production:**
- * ```ts
- * class ProductService {
- *   productCache = $cache({
- *     name: "products",
- *     ttl: [1, "hour"],
- *     provider: RedisCacheProvider,  // Use Redis for distributed caching
- *     handler: async (productId: string) => {
- *       return await this.database.products.findById(productId);
- *     }
- *   });
- *
- *   async invalidateProduct(productId: string) {
- *     await this.productCache.invalidate(productId);
- *   }
- *
- *   async invalidateAllProducts() {
- *     await this.productCache.invalidate("*");
- *   }
- * }
- * ```
- *
- * @example
- * **Conditional caching with environment controls:**
- * ```ts
- * class ExpensiveService {
- *   computation = $cache({
- *     name: "heavy-computation",
- *     ttl: [1, "day"],
- *     disabled: process.env.NODE_ENV === "development", // Disable in dev
- *     handler: async (input: ComplexInput) => {
- *       // Very expensive computation that should be cached in production
- *       return await performHeavyComputation(input);
- *     }
- *   });
- * }
- * ```
- */
-declare const $cache: {
-  <TReturn = string, TParameter extends any[] = any[]>(options?: CacheDescriptorOptions<TReturn, TParameter>): CacheDescriptorFn<TReturn, TParameter>;
-  [KIND]: typeof CacheDescriptor;
-};
-interface CacheDescriptorOptions<TReturn = any, TParameter extends any[] = any[]> {
-  /**
-   * The cache name. This is useful for invalidating multiple caches at once.
-   *
-   * Store key as `cache:$name:$key`.
-   *
-   * @default Name of the key of the class.
-   */
-  name?: string;
-  /**
-   * Function which returns cached data.
-   */
-  handler?: (...args: TParameter) => TReturn;
-  /**
-   * 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.
-   */
-  provider?: InstantiableClass<CacheProvider> | "memory";
-  /**
-   * 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.
-   */
-  disabled?: boolean;
-}
-declare class CacheDescriptor<TReturn = any, TParameter extends any[] = any[]> extends Descriptor<CacheDescriptorOptions<TReturn, TParameter>> {
-  protected readonly env: {
-    CACHE_ENABLED: boolean;
-    CACHE_DEFAULT_TTL: number;
-  };
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly provider: CacheProvider;
-  protected encoder: TextEncoder;
-  protected decoder: TextDecoder;
-  protected codes: {
-    BINARY: number;
-    JSON: number;
-    STRING: number;
-  };
-  get container(): string;
-  run(...args: TParameter): Promise<TReturn>;
-  key(...args: TParameter): string;
-  invalidate(...keys: string[]): Promise<void>;
-  set(key: string, value: TReturn, ttl?: DurationLike): Promise<void>;
-  get(key: string): Promise<TReturn | undefined>;
-  protected serialize<TReturn>(value: TReturn): Uint8Array;
-  protected deserialize<TReturn>(uint8Array: Uint8Array): Promise<TReturn>;
-  protected $provider(): CacheProvider;
-}
-interface CacheDescriptorFn<TReturn = any, TParameter extends any[] = any[]> extends CacheDescriptor<TReturn, TParameter> {
-  /**
-   * Run the cache descriptor with the provided arguments.
-   */
-  (...args: TParameter): Promise<TReturn>;
-}
-//#endregion
-//#region src/providers/MemoryCacheProvider.d.ts
-type CacheName = string;
-type CacheKey = string;
-type CacheValue = {
-  data?: Uint8Array;
-  timeout?: Timeout;
-};
-declare class MemoryCacheProvider implements CacheProvider {
-  protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _alepha_logger0.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>;
-  del(name: string, ...keys: string[]): Promise<void>;
-  has(name: string, key: string): Promise<boolean>;
-  keys(name: string, filter?: string): Promise<string[]>;
-  clear(): Promise<void>;
-}
-//#endregion
-//#region src/index.d.ts
-/**
- * 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.
- *
- * @see {@link $cache}
- * @see {@link CacheProvider}
- * @module alepha.cache
- */
-declare const AlephaCache: _alepha_core0.Service<_alepha_core0.Module<{}>>;
-//#endregion
-export { $cache, AlephaCache, CacheDescriptor, CacheDescriptorFn, CacheDescriptorOptions, CacheProvider, MemoryCacheProvider };
-//# sourceMappingURL=index.d.ts.map
+export * from '@alepha/cache';

package/command.d.ts

@@ -1,238 +1 @@
-import * as _alepha_core1 from "alepha";
-import { Alepha, AlephaError, Async, Descriptor, KIND, Static, TObject, TSchema, TString } from "alepha";
-import * as _alepha_logger0 from "alepha/logger";
-import * as fs from "node:fs/promises";
-import { glob } from "node:fs/promises";
-import * as readline_promises0 from "readline/promises";
-import * as typebox0 from "typebox";
-
-//#region src/helpers/Asker.d.ts
-interface AskOptions<T extends TSchema = TString> {
-  /**
-   * Response schema expected.
-   *
-   * Recommended schemas:
-   * - t.text() - for free text input
-   * - t.number() - for numeric input
-   * - t.boolean() - for yes/no input (accepts "true", "false", "1", "0")
-   * - t.enum(["option1", "option2"]) - for predefined options
-   *
-   * You can use schema.default to provide a default value.
-   *
-   * @example
-   * ```ts
-   * ask("What is your name?", { schema: t.text({ default: "John Doe" }) })
-   * ```
-   *
-   * @default TString
-   */
-  schema?: T;
-  /**
-   * Custom validation function.
-   * Throws an AlephaError in case of validation failure.
-   */
-  validate?: (value: Static<T>) => void;
-}
-interface AskMethod {
-  <T extends TSchema = TString>(question: string, options?: AskOptions<T>): Promise<Static<T>>;
-}
-declare class Asker {
-  protected readonly log: _alepha_logger0.Logger;
-  readonly ask: AskMethod;
-  protected readonly alepha: Alepha;
-  constructor();
-  protected createAskMethod(): AskMethod;
-  protected prompt<T extends TSchema = TString>(question: string, options: AskOptions<T>): Promise<Static<T>>;
-  protected createPromptInterface(): readline_promises0.Interface;
-}
-//#endregion
-//#region src/helpers/Runner.d.ts
-type Task = {
-  name: string;
-  handler: () => any;
-};
-interface Timer {
-  name: string;
-  duration: string;
-}
-interface RunOptions {
-  /**
-   * Rename the command for logging purposes.
-   */
-  alias?: string;
-}
-interface RunnerMethod {
-  (cmd: string | Task | Array<string | Task>, options?: RunOptions | (() => any)): Promise<string>;
-  rm: (glob: string | string[], options?: RunOptions) => Promise<string>;
-  cp: (source: string, dest: string, options?: RunOptions) => Promise<string>;
-}
-declare class Runner {
-  protected readonly log: _alepha_logger0.Logger;
-  protected readonly timers: Timer[];
-  protected readonly startTime: number;
-  readonly run: RunnerMethod;
-  constructor();
-  protected createRunMethod(): RunnerMethod;
-  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
-/**
- * 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, A extends TSchema>(options: CommandDescriptorOptions<T, A>): CommandDescriptor<T, A>;
-  [KIND]: typeof CommandDescriptor;
-};
-interface CommandDescriptorOptions<T extends TObject, A extends TSchema> {
-  /**
-   * The handler function to execute when the command is matched.
-   */
-  handler: (args: CommandHandlerArgs<T, A>) => 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;
-  /**
-   * An optional TypeBox schema defining the arguments for the command.
-   *
-   * @example
-   * args: t.text()
-   * my-cli command <arg1: string>
-   *
-   * args: t.optional(t.text())
-   * my-cli command [arg1: string]
-   *
-   * args: t.tuple([t.text(), t.number()])
-   * my-cli command <arg1: string> <arg2: number>
-   *
-   * args: t.tuple([t.text(), t.optional(t.number())])
-   * my-cli command <arg1: string> [arg2: number]
-   */
-  args?: A;
-  /**
-   * If false, skip summary message at the end of the command execution.
-   */
-  summary?: boolean;
-}
-declare class CommandDescriptor<T extends TObject = TObject, A extends TSchema = TSchema> extends Descriptor<CommandDescriptorOptions<T, A>> {
-  readonly flags: TObject<{}>;
-  readonly aliases: string[];
-  get name(): string;
-}
-interface CommandHandlerArgs<T extends TObject, A extends TSchema = TSchema> {
-  flags: Static<T>;
-  args: A extends TSchema ? Static<A> : Array<string>;
-  run: RunnerMethod;
-  ask: AskMethod;
-  glob: typeof glob;
-  fs: typeof fs;
-}
-//#endregion
-//#region src/errors/CommandError.d.ts
-declare class CommandError extends AlephaError {
-  readonly name = "CommandError";
-}
-//#endregion
-//#region src/providers/CliProvider.d.ts
-declare const envSchema: TObject<{
-  CLI_NAME: _alepha_core1.TString;
-  CLI_DESCRIPTION: _alepha_core1.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
-declare class CliProvider {
-  protected readonly env: {
-    CLI_NAME: string;
-    CLI_DESCRIPTION: string;
-  };
-  protected readonly alepha: Alepha;
-  protected readonly log: _alepha_logger0.Logger;
-  protected readonly runner: Runner;
-  protected readonly asker: Asker;
-  options: {
-    name: string;
-    description: string;
-    argv: string[];
-  };
-  protected readonly globalFlags: {
-    help: {
-      aliases: string[];
-      description: string;
-      schema: typebox0.TBoolean;
-    };
-  };
-  protected readonly onReady: _alepha_core1.HookDescriptor<"ready">;
-  get commands(): CommandDescriptor<any>[];
-  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>;
-  protected parseCommandArgs(argv: string[], schema?: TSchema): any;
-  protected parseArgumentValue(value: string, schema: TSchema): any;
-  protected generateArgsUsage(schema?: TSchema): string;
-  protected getTypeName(schema: TSchema): string;
-  printHelp(command?: CommandDescriptor<any>): void;
-  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.
- *
- * It allows you to define commands using the `$command` descriptor.
- *
- * @see {@link $command}
- * @module alepha.command
- */
-declare const AlephaCommand: _alepha_core1.Service<_alepha_core1.Module<{}>>;
-declare module "typebox" {
-  interface StringOptions {
-    /**
-     * Additional aliases for the flags.
-     *
-     * @module alepha.command
-     */
-    aliases?: string[];
-  }
-}
-//# sourceMappingURL=index.d.ts.map
-
-//#endregion
-export { $command, AlephaCommand, AskMethod, AskOptions, Asker, CliProvider, CommandDescriptor, CommandDescriptorOptions, CommandError, CommandHandlerArgs, RunOptions, Runner, RunnerMethod, Task };
-//# sourceMappingURL=index.d.ts.map
+export * from '@alepha/command';