@bloomneo/appkit 1.2.9

package/dist/cache/strategies/memory.js

@@ -0,0 +1,348 @@
+/**
+ * Memory cache strategy with LRU eviction and TTL expiration
+ * @module @bloomneo/appkit/cache
+ * @file src/cache/strategies/memory.ts
+ *
+ * @llm-rule WHEN: No REDIS_URL environment variable - perfect for development and testing
+ * @llm-rule AVOID: Production use without Redis - memory cache doesn't persist across restarts
+ * @llm-rule NOTE: LRU eviction, TTL cleanup, memory limits, thread-safe operations
+ */
+/**
+ * Memory cache strategy with intelligent eviction and cleanup
+ */
+export class MemoryStrategy {
+    config;
+    cache = new Map();
+    totalSize = 0;
+    cleanupInterval = null;
+    connected = false;
+    /**
+     * Creates memory strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Cache initialization without Redis URL - automatic fallback
+     * @llm-rule AVOID: Manual memory configuration - environment detection handles this
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Connects memory cache (starts cleanup intervals)
+     * @llm-rule WHEN: Cache initialization - sets up automatic TTL cleanup
+     * @llm-rule AVOID: Manual memory management - this handles TTL and size limits automatically
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        // Start cleanup interval for TTL expiration
+        this.startCleanupInterval();
+        this.connected = true;
+        if (this.config.environment.isDevelopment) {
+            console.log(`✅ [AppKit] Memory cache initialized (max: ${this.formatBytes(this.config.memory.maxSizeBytes)}, items: ${this.config.memory.maxItems})`);
+        }
+    }
+    /**
+     * Disconnects memory cache (stops cleanup intervals)
+     * @llm-rule WHEN: App shutdown or cache cleanup
+     * @llm-rule AVOID: Memory leaks - always stop intervals on shutdown
+     */
+    async disconnect() {
+        if (!this.connected)
+            return;
+        this.stopCleanupInterval();
+        this.cache.clear();
+        this.totalSize = 0;
+        this.connected = false;
+        if (this.config.environment.isDevelopment) {
+            console.log(`👋 [AppKit] Memory cache disconnected`);
+        }
+    }
+    /**
+     * Gets value from memory cache with TTL checking
+     * @llm-rule WHEN: Retrieving cached data from in-memory storage
+     * @llm-rule AVOID: Manual TTL checking - this handles expiration automatically
+     */
+    async get(key) {
+        const item = this.cache.get(key);
+        if (!item) {
+            return null; // Key not found
+        }
+        // Check TTL expiration
+        if (this.isExpired(item)) {
+            this.deleteItem(key);
+            return null;
+        }
+        // Update access time for LRU
+        item.accessTime = Date.now();
+        return this.deepClone(item.value);
+    }
+    /**
+     * Sets value in memory cache with TTL and automatic eviction
+     * @llm-rule WHEN: Storing data in memory cache with size and TTL management
+     * @llm-rule AVOID: Manual memory management - this handles LRU eviction automatically
+     */
+    async set(key, value, ttl) {
+        try {
+            // Clone value to prevent external mutations
+            const clonedValue = this.deepClone(value);
+            const size = this.calculateSize(clonedValue);
+            const now = Date.now();
+            const item = {
+                value: clonedValue,
+                ttl: now + (ttl * 1000), // Convert seconds to milliseconds
+                size,
+                accessTime: now,
+                createTime: now,
+            };
+            // Remove existing item if present
+            if (this.cache.has(key)) {
+                this.deleteItem(key);
+            }
+            // Check if single item exceeds max size
+            if (size > this.config.memory.maxSizeBytes) {
+                console.warn(`[AppKit] Cache item too large (${this.formatBytes(size)} > ${this.formatBytes(this.config.memory.maxSizeBytes)})`);
+                return false;
+            }
+            // Evict items to make space
+            this.evictIfNeeded(size);
+            // Add new item
+            this.cache.set(key, item);
+            this.totalSize += size;
+            return true;
+        }
+        catch (error) {
+            console.error(`[AppKit] Memory set error for key "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Deletes key from memory cache
+     * @llm-rule WHEN: Cache invalidation or removing specific cached data
+     * @llm-rule AVOID: Manual memory cleanup - this handles size tracking automatically
+     */
+    async delete(key) {
+        return this.deleteItem(key);
+    }
+    /**
+     * Clears entire memory cache
+     * @llm-rule WHEN: Full cache invalidation or testing cleanup
+     * @llm-rule AVOID: Using in production without consideration - clears all cached data
+     */
+    async clear() {
+        this.cache.clear();
+        this.totalSize = 0;
+        return true;
+    }
+    /**
+     * Checks if key exists in memory cache
+     * @llm-rule WHEN: Checking cache key existence without retrieving value
+     * @llm-rule AVOID: Using get() then checking null - this is more efficient
+     */
+    async has(key) {
+        const item = this.cache.get(key);
+        if (!item) {
+            return false;
+        }
+        // Check TTL expiration
+        if (this.isExpired(item)) {
+            this.deleteItem(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Gets all keys matching pattern (supports wildcards)
+     * @llm-rule WHEN: Finding all keys in namespace for bulk operations
+     * @llm-rule AVOID: Complex pattern matching - simple wildcards only
+     */
+    async keys(pattern = '*') {
+        const keys = [];
+        const regex = this.patternToRegex(pattern);
+        for (const [key, item] of this.cache.entries()) {
+            // Skip expired items
+            if (this.isExpired(item)) {
+                this.deleteItem(key);
+                continue;
+            }
+            if (regex.test(key)) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    }
+    /**
+     * Deletes multiple keys efficiently
+     * @llm-rule WHEN: Bulk deletion operations like namespace clearing
+     * @llm-rule AVOID: Individual delete calls in loops - this batches operations
+     */
+    async deleteMany(keys) {
+        let deletedCount = 0;
+        for (const key of keys) {
+            if (this.deleteItem(key)) {
+                deletedCount++;
+            }
+        }
+        return deletedCount;
+    }
+    // Private helper methods
+    /**
+     * Deletes single item and updates size tracking
+     */
+    deleteItem(key) {
+        const item = this.cache.get(key);
+        if (!item)
+            return false;
+        this.cache.delete(key);
+        this.totalSize -= item.size;
+        return true;
+    }
+    /**
+     * Checks if cache item has expired
+     */
+    isExpired(item) {
+        return Date.now() > item.ttl;
+    }
+    /**
+     * Evicts items when memory limits are exceeded
+     */
+    evictIfNeeded(newItemSize) {
+        const memoryConfig = this.config.memory;
+        // Check item count limit
+        while (this.cache.size >= memoryConfig.maxItems) {
+            this.evictLRU();
+        }
+        // Check memory size limit
+        while (this.totalSize + newItemSize > memoryConfig.maxSizeBytes) {
+            if (!this.evictLRU()) {
+                break; // No more items to evict
+            }
+        }
+    }
+    /**
+     * Evicts least recently used item
+     */
+    evictLRU() {
+        if (this.cache.size === 0)
+            return false;
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        // Find LRU item
+        for (const [key, item] of this.cache.entries()) {
+            if (item.accessTime < oldestTime) {
+                oldestTime = item.accessTime;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.deleteItem(oldestKey);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Calculates memory size of value (approximate)
+     */
+    calculateSize(value) {
+        try {
+            // Simple size calculation using JSON serialization
+            const serialized = JSON.stringify(value);
+            return Buffer.byteLength(serialized, 'utf8');
+        }
+        catch {
+            // Fallback for non-serializable values
+            return 1024; // 1KB default
+        }
+    }
+    /**
+     * Deep clones value to prevent external mutations
+     */
+    deepClone(value) {
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            // Fallback for non-serializable values
+            return value;
+        }
+    }
+    /**
+     * Converts glob pattern to regex for key matching
+     */
+    patternToRegex(pattern) {
+        if (pattern === '*') {
+            return /.*/; // Match everything
+        }
+        // Escape special regex characters except * and ?
+        const escaped = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '.*') // * becomes .*
+            .replace(/\?/g, '.'); // ? becomes .
+        return new RegExp(`^${escaped}$`);
+    }
+    /**
+     * Starts automatic cleanup interval for TTL expiration
+     */
+    startCleanupInterval() {
+        const interval = this.config.memory.checkInterval;
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupExpired();
+        }, interval);
+        // Don't let interval keep process alive
+        if (this.cleanupInterval.unref) {
+            this.cleanupInterval.unref();
+        }
+    }
+    /**
+     * Stops cleanup interval
+     */
+    stopCleanupInterval() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+    /**
+     * Removes expired items from cache
+     */
+    cleanupExpired() {
+        const keysToDelete = [];
+        for (const [key, item] of this.cache.entries()) {
+            if (this.isExpired(item)) {
+                keysToDelete.push(key);
+            }
+        }
+        // Delete expired items
+        for (const key of keysToDelete) {
+            this.deleteItem(key);
+        }
+        // Log cleanup results in development
+        if (keysToDelete.length > 0 && this.config.environment.isDevelopment) {
+            console.log(`🧹 [AppKit] Memory cache cleanup: removed ${keysToDelete.length} expired items`);
+        }
+    }
+    /**
+     * Formats bytes for human-readable display
+     */
+    formatBytes(bytes) {
+        if (bytes === 0)
+            return '0 B';
+        const k = 1024;
+        const sizes = ['B', 'KB', 'MB', 'GB'];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+        return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+    }
+    /**
+     * Gets memory cache statistics for debugging
+     */
+    getStats() {
+        const memoryConfig = this.config.memory;
+        return {
+            itemCount: this.cache.size,
+            totalSize: this.totalSize,
+            totalSizeFormatted: this.formatBytes(this.totalSize),
+            maxItems: memoryConfig.maxItems,
+            maxSize: memoryConfig.maxSizeBytes,
+            maxSizeFormatted: this.formatBytes(memoryConfig.maxSizeBytes),
+            memoryUsage: this.totalSize / memoryConfig.maxSizeBytes,
+        };
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/cache/strategies/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/cache/strategies/memory.ts"],"names":[],"mappings":"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"}

package/dist/cache/strategies/redis.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Redis cache strategy with automatic connection management and retry logic
+ * @module @bloomneo/appkit/cache
+ * @file src/cache/strategies/redis.ts
+ *
+ * @llm-rule WHEN: App has REDIS_URL environment variable for distributed caching
+ * @llm-rule AVOID: Manual Redis setup - this handles connection, retry, and serialization automatically
+ * @llm-rule NOTE: Auto-reconnects on failure, handles JSON serialization, production-ready
+ */
+import type { CacheStrategy } from '../cache.js';
+import type { CacheConfig } from '../defaults.js';
+/**
+ * Redis cache strategy with enterprise-grade reliability
+ */
+export declare class RedisStrategy implements CacheStrategy {
+    private config;
+    private client;
+    private connected;
+    private connectionPromise;
+    /**
+     * Creates Redis strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Cache initialization with Redis URL detected
+     * @llm-rule AVOID: Manual Redis configuration - environment detection handles this
+     */
+    constructor(config: CacheConfig);
+    /**
+     * Connects to Redis with automatic retry and connection pooling
+     * @llm-rule WHEN: Cache initialization or reconnection after failure
+     * @llm-rule AVOID: Manual connection management - this handles all Redis complexity
+     */
+    connect(): Promise<void>;
+    /**
+     * Establishes Redis connection with retry logic
+     */
+    private establishConnection;
+    /**
+     * Sets up Redis event handlers for connection management
+     */
+    private setupEventHandlers;
+    /**
+     * Disconnects from Redis gracefully
+     * @llm-rule WHEN: App shutdown or cache cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents data loss
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Gets value from Redis with automatic JSON deserialization
+     * @llm-rule WHEN: Retrieving cached data from distributed Redis cache
+     * @llm-rule AVOID: Manual Redis commands - this handles serialization automatically
+     */
+    get(key: string): Promise<any>;
+    /**
+     * Sets value in Redis with TTL and automatic JSON serialization
+     * @llm-rule WHEN: Storing data in distributed Redis cache with expiration
+     * @llm-rule AVOID: Manual Redis commands - this handles serialization and TTL automatically
+     */
+    set(key: string, value: any, ttl: number): Promise<boolean>;
+    /**
+     * Deletes key from Redis
+     * @llm-rule WHEN: Cache invalidation or removing specific cached data
+     * @llm-rule AVOID: Manual key management - this handles Redis delete operations
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clears all keys matching pattern (usually namespace-based)
+     * @llm-rule WHEN: Namespace-based cache invalidation
+     * @llm-rule AVOID: Using FLUSHDB - this only clears specific namespace keys
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Checks if key exists in Redis
+     * @llm-rule WHEN: Checking cache key existence without retrieving value
+     * @llm-rule AVOID: Using get() then checking null - this is more efficient
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Gets all keys matching pattern (for namespace operations)
+     * @llm-rule WHEN: Finding all keys in namespace for bulk operations
+     * @llm-rule AVOID: Using KEYS in production with large datasets - use SCAN instead
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Deletes multiple keys efficiently
+     * @llm-rule WHEN: Bulk deletion operations like namespace clearing
+     * @llm-rule AVOID: Individual delete calls - batch operations are much faster
+     */
+    deleteMany(keys: string[]): Promise<number>;
+    /**
+     * Ensures Redis connection is established
+     */
+    private ensureConnected;
+    /**
+     * Serializes value to JSON string for Redis storage
+     */
+    private serialize;
+    /**
+     * Deserializes JSON string from Redis
+     */
+    private deserialize;
+    /**
+     * Masks sensitive parts of Redis URL for logging
+     */
+    private maskUrl;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/cache/strategies/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/cache/strategies/redis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;GAEG;AACH,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,iBAAiB,CAA8B;IAEvD;;;;OAIG;gBACS,MAAM,EAAE,WAAW;IAI/B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B;;OAEG;YACW,mBAAmB;IAiDjC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoC1B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBjC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBpC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBjE;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY3C;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAM/B;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYxC;;;;OAIG;IACG,IAAI,CAAC,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBpD;;;;OAIG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBjD;;OAEG;YACW,eAAe;IAM7B;;OAEG;IACH,OAAO,CAAC,SAAS;IAQjB;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,OAAO;CAWhB"}