@ductape/sdk 0.0.4-v99 → 0.0.5

package/dist/cache/cache.manager.d.ts

@@ -10,8 +10,46 @@
  * QuotaService, FallbackService, AgentsService, SessionsService, BrokersService,
  * NotificationsService, etc.
  */
-import { RedisClientType } from 'redis';
+import type { Redis as IORedisClient } from 'ioredis';
 import { EnvType } from '../types';
+/**
+ * Cache log levels
+ */
+type CacheLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Cache logger configuration
+ */
+interface ICacheLoggerConfig {
+    /** Enable logging */
+    enabled: boolean;
+    /** Minimum log level to display */
+    level: CacheLogLevel;
+    /** Include timestamps */
+    timestamps: boolean;
+    /** Include stack traces for errors */
+    stackTraces: boolean;
+}
+/**
+ * Cache logger for detailed operation tracking
+ */
+export declare class CacheLogger {
+    private config;
+    private readonly levelPriority;
+    constructor(config?: Partial<ICacheLoggerConfig>);
+    setConfig(config: Partial<ICacheLoggerConfig>): void;
+    enable(): void;
+    disable(): void;
+    private shouldLog;
+    private formatMessage;
+    debug(component: string, message: string, data?: Record<string, unknown>): void;
+    info(component: string, message: string, data?: Record<string, unknown>): void;
+    warn(component: string, message: string, data?: Record<string, unknown>): void;
+    error(component: string, message: string, error?: Error, data?: Record<string, unknown>): void;
+    /** Log cache operation with timing */
+    operation(op: string, key: string, startTime: number, result: 'hit' | 'miss' | 'stored' | 'deleted' | 'error', tier: string, data?: Record<string, unknown>): void;
+}
+/** Global cache logger instance */
+export declare const cacheLogger: CacheLogger;
 /**
  * Cache value wrapper with type information for auto-detection
  */
@@ -30,7 +68,7 @@ export interface ICacheManagerConfig {
     user_id: string;
     token: string;
     env_type: EnvType | string;
-    redis_client?: RedisClientType;
+    redis_client?: IORedisClient;
 }
 /**
  * Component types for cache operations
@@ -102,8 +140,8 @@ export interface ICacheFetchResult<T> {
  * // Execute operation...
  * const result = await doOperation();
  *
- * // Store in cache
- * await cacheManager.store({
+ * // Store in cache (fire-and-forget - no await needed)
+ * cacheManager.store({
  *   cache_tag: 'my-cache',
  *   product_tag: 'my-product',
  *   component_tag: 'my-storage',
@@ -123,6 +161,18 @@ export declare class CacheManager {
     /** Maximum number of entries in internal cache before LRU eviction */
     private maxInternalCacheSize;
     constructor(config: ICacheManagerConfig);
+    /**
+     * Enable cache logging
+     */
+    enableLogging(config?: {
+        level?: CacheLogLevel;
+        timestamps?: boolean;
+        stackTraces?: boolean;
+    }): void;
+    /**
+     * Disable cache logging
+     */
+    disableLogging(): void;
     /**
      * Set maximum size for internal cache
      */
@@ -182,7 +232,16 @@ export declare class CacheManager {
     /**
      * Store data in cache (all three tiers: internal, Redis, and remote)
      */
-    store<T>(options: ICacheOperationOptions, data: T): Promise<void>;
+    /**
+     * Store data in cache - fire-and-forget pattern.
+     * Internal cache is written synchronously for immediate availability.
+     * Redis and remote cache writes happen asynchronously without blocking.
+     */
+    store<T>(options: ICacheOperationOptions, data: T): void;
+    /**
+     * Internal method to store to Redis and remote cache asynchronously
+     */
+    private storeToExternalTiers;
     /**
      * Invalidate/delete data from cache (all three tiers)
      */
@@ -224,6 +283,26 @@ export declare class CacheManager {
     getInternalCacheStats(): {
         size: number;
         maxSize: number;
+        utilizationPercent: number;
+        redisAvailable: boolean;
+    };
+    /**
+     * Get detailed cache statistics including entry ages
+     */
+    getDetailedStats(): {
+        internal: {
+            size: number;
+            maxSize: number;
+            utilizationPercent: number;
+            oldestEntryAge: number | null;
+            newestEntryAge: number | null;
+        };
+        redis: {
+            available: boolean;
+        };
+        remote: {
+            available: boolean;
+        };
     };
 }
 export default CacheManager;