alepha 0.9.3 → 0.9.5

package/cache.d.ts

@@ -1,7 +1,7 @@
-import * as _alepha_core1 from "alepha";
 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
 /**
@@ -41,11 +41,141 @@ declare abstract class CacheProvider {
   abstract has(name: string, key: string): Promise<boolean>;
   abstract keys(name: string, filter?: string): Promise<string[]>;
 }
-//# sourceMappingURL=CacheProvider.d.ts.map
 //#endregion
 //#region src/descriptors/$cache.d.ts
 /**
- * Creates a cache storage or a cache function.
+ * 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>;
@@ -116,7 +246,6 @@ interface CacheDescriptorFn<TReturn = any, TParameter extends any[] = any[]> ext
    */
   (...args: TParameter): Promise<TReturn>;
 }
-//# sourceMappingURL=$cache.d.ts.map
 //#endregion
 //#region src/providers/MemoryCacheProvider.d.ts
 type CacheName = string;
@@ -127,7 +256,7 @@ type CacheValue = {
 };
 declare class MemoryCacheProvider implements CacheProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: _alepha_core1.Logger;
+  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>;
@@ -149,8 +278,6 @@ declare class MemoryCacheProvider implements CacheProvider {
  * @module alepha.cache
  */
 declare const AlephaCache: _alepha_core0.Service<_alepha_core0.Module>;
-//# sourceMappingURL=index.d.ts.map
-
 //#endregion
 export { $cache, AlephaCache, CacheDescriptor, CacheDescriptorFn, CacheDescriptorOptions, CacheProvider, MemoryCacheProvider };
 //# sourceMappingURL=index.d.ts.map

package/command.d.ts

@@ -1,8 +1,8 @@
 import * as _alepha_core1 from "alepha";
-import * as _alepha_core0 from "alepha";
-import { Alepha, AlephaError, Async, Descriptor, KIND, Logger, Static, TObject, TSchema } from "alepha";
+import { Alepha, AlephaError, Async, Descriptor, KIND, Static, TObject, TSchema } from "alepha";
 import * as fs from "node:fs/promises";
 import { glob } from "node:fs/promises";
+import * as _alepha_logger0 from "alepha/logger";
 import * as _sinclair_typebox0 from "@sinclair/typebox";
 
 //#region src/helpers/Runner.d.ts
@@ -30,11 +30,11 @@ interface RunnerMethod {
   cp: (source: string, dest: string, options?: RunOptions) => Promise<string>;
 }
 declare class Runner {
-  protected readonly log: Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly timers: Timer[];
   protected readonly startTime: number;
   readonly run: RunnerMethod;
-  constructor(log: Logger);
+  constructor();
   protected createRunMethod(): RunnerMethod;
   protected exec(cmd: string): Promise<string>;
   /**
@@ -101,13 +101,11 @@ interface CommandHandlerArgs<T extends TObject> {
   glob: typeof glob;
   fs: typeof fs;
 }
-//# sourceMappingURL=$command.d.ts.map
 //#endregion
 //#region src/errors/CommandError.d.ts
 declare class CommandError extends AlephaError {
   readonly name = "CommandError";
 }
-//# sourceMappingURL=CommandError.d.ts.map
 //#endregion
 //#region src/providers/CliProvider.d.ts
 declare const envSchema: TObject<{
@@ -118,9 +116,13 @@ declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
 declare class CliProvider {
-  protected readonly env: Static<typeof envSchema>;
+  protected readonly env: {
+    CLI_NAME: string;
+    CLI_DESCRIPTION: string;
+  };
   protected readonly alepha: Alepha;
-  protected readonly log: Logger;
+  protected readonly log: _alepha_logger0.Logger;
+  protected readonly runner: Runner;
   options: {
     name: string;
     description: string;
@@ -157,7 +159,7 @@ declare class CliProvider {
  * @see {@link $command}
  * @module alepha.command
  */
-declare const AlephaCommand: _alepha_core0.Service<_alepha_core0.Module>;
+declare const AlephaCommand: _alepha_core1.Service<_alepha_core1.Module>;
 declare module "@sinclair/typebox" {
   interface StringOptions {
     /**