@bloomneo/appkit 1.2.9

package/dist/cache/defaults.js

@@ -0,0 +1,193 @@
+/**
+ * Smart defaults and environment validation for caching
+ * @module @bloomneo/appkit/cache
+ * @file src/cache/defaults.ts
+ *
+ * @llm-rule WHEN: App startup - need to configure cache behavior and connection strategy
+ * @llm-rule AVOID: Calling multiple times - expensive environment parsing, use lazy loading in get()
+ * @llm-rule NOTE: Called once at startup, cached globally for performance
+ */
+/**
+ * Gets smart defaults using environment variables with auto-strategy detection
+ * @llm-rule WHEN: App startup to get production-ready cache configuration
+ * @llm-rule AVOID: Calling repeatedly - expensive validation, cache the result
+ * @llm-rule NOTE: Auto-detects Redis vs Memory based on REDIS_URL environment variable
+ */
+export function getSmartDefaults() {
+    validateEnvironment();
+    const nodeEnv = process.env.NODE_ENV || 'development';
+    const isDevelopment = nodeEnv === 'development';
+    const isProduction = nodeEnv === 'production';
+    const isTest = nodeEnv === 'test';
+    // Auto-detect strategy from environment
+    const strategy = detectCacheStrategy();
+    return {
+        // Strategy selection with smart detection
+        strategy,
+        // Key management with service identification
+        keyPrefix: process.env.VOILA_CACHE_PREFIX || process.env.VOILA_SERVICE_NAME || 'app',
+        namespace: process.env.VOILA_CACHE_NAMESPACE || 'default',
+        // TTL configuration with environment awareness
+        defaultTTL: parseInt(process.env.VOILA_CACHE_TTL || (isProduction ? '3600' : '300')), // 1hr prod, 5min dev
+        // Redis configuration (only used when strategy is 'redis')
+        redis: {
+            url: process.env.REDIS_URL || 'redis://localhost:6379',
+            password: process.env.REDIS_PASSWORD,
+            maxRetries: parseInt(process.env.VOILA_CACHE_REDIS_RETRIES || '3'),
+            retryDelay: parseInt(process.env.VOILA_CACHE_REDIS_RETRY_DELAY || '1000'),
+            connectTimeout: parseInt(process.env.VOILA_CACHE_REDIS_CONNECT_TIMEOUT || '10000'),
+            commandTimeout: parseInt(process.env.VOILA_CACHE_REDIS_COMMAND_TIMEOUT || '5000'),
+        },
+        // Memory configuration (only used when strategy is 'memory')
+        memory: {
+            maxItems: parseInt(process.env.VOILA_CACHE_MEMORY_MAX_ITEMS || '10000'),
+            maxSizeBytes: parseInt(process.env.VOILA_CACHE_MEMORY_MAX_SIZE || '100000000'), // 100MB
+            checkInterval: parseInt(process.env.VOILA_CACHE_MEMORY_CHECK_INTERVAL || '60000'), // 1 minute
+        },
+        // Environment information
+        environment: {
+            isDevelopment,
+            isProduction,
+            isTest,
+            nodeEnv,
+        },
+    };
+}
+/**
+ * Auto-detect cache strategy from environment variables
+ * @llm-rule WHEN: Determining which cache strategy to use automatically
+ * @llm-rule AVOID: Manual strategy selection - environment detection handles most cases
+ * @llm-rule NOTE: REDIS_URL = Redis, no REDIS_URL = Memory (perfect for dev/test)
+ */
+function detectCacheStrategy() {
+    // Explicit override wins (for testing/debugging)
+    const explicit = process.env.VOILA_CACHE_STRATEGY?.toLowerCase();
+    if (explicit === 'redis' || explicit === 'memory') {
+        return explicit;
+    }
+    // Auto-detection logic
+    if (process.env.REDIS_URL) {
+        return 'redis'; // Redis URL available
+    }
+    if (process.env.NODE_ENV === 'production') {
+        console.warn('[VoilaJSX AppKit] No REDIS_URL found in production. ' +
+            'Using memory cache which will not persist across server restarts. ' +
+            'Set REDIS_URL for production caching.');
+    }
+    return 'memory'; // Default to memory for development/testing
+}
+/**
+ * Validates environment variables for cache configuration
+ * @llm-rule WHEN: App startup to ensure proper cache environment configuration
+ * @llm-rule AVOID: Skipping validation - improper config causes silent cache failures
+ * @llm-rule NOTE: Validates Redis URLs, numeric values, and production requirements
+ */
+function validateEnvironment() {
+    // Validate Redis URL if provided
+    const redisUrl = process.env.REDIS_URL;
+    if (redisUrl && !isValidRedisUrl(redisUrl)) {
+        throw new Error(`Invalid REDIS_URL: "${redisUrl}". Must start with redis:// or rediss://`);
+    }
+    // Validate cache strategy if explicitly set
+    const strategy = process.env.VOILA_CACHE_STRATEGY;
+    if (strategy && !['redis', 'memory'].includes(strategy.toLowerCase())) {
+        throw new Error(`Invalid VOILA_CACHE_STRATEGY: "${strategy}". Must be "redis" or "memory"`);
+    }
+    // Validate numeric values
+    validateNumericEnv('VOILA_CACHE_TTL', 1, 86400 * 7); // 1 second to 1 week
+    validateNumericEnv('VOILA_CACHE_REDIS_RETRIES', 0, 10);
+    validateNumericEnv('VOILA_CACHE_REDIS_RETRY_DELAY', 100, 10000);
+    validateNumericEnv('VOILA_CACHE_REDIS_CONNECT_TIMEOUT', 1000, 60000);
+    validateNumericEnv('VOILA_CACHE_REDIS_COMMAND_TIMEOUT', 1000, 30000);
+    validateNumericEnv('VOILA_CACHE_MEMORY_MAX_ITEMS', 100, 1000000);
+    validateNumericEnv('VOILA_CACHE_MEMORY_MAX_SIZE', 1000000, 1000000000); // 1MB to 1GB
+    validateNumericEnv('VOILA_CACHE_MEMORY_CHECK_INTERVAL', 10000, 300000); // 10s to 5min
+    // Validate key prefix
+    const keyPrefix = process.env.VOILA_CACHE_PREFIX;
+    if (keyPrefix && !/^[a-zA-Z0-9_-]+$/.test(keyPrefix)) {
+        throw new Error(`Invalid VOILA_CACHE_PREFIX: "${keyPrefix}". Must contain only letters, numbers, underscores, and hyphens`);
+    }
+    // Validate namespace
+    const namespace = process.env.VOILA_CACHE_NAMESPACE;
+    if (namespace && !/^[a-zA-Z0-9_-]+$/.test(namespace)) {
+        throw new Error(`Invalid VOILA_CACHE_NAMESPACE: "${namespace}". Must contain only letters, numbers, underscores, and hyphens`);
+    }
+    // Production-specific validations
+    const nodeEnv = process.env.NODE_ENV;
+    if (nodeEnv === 'production') {
+        if (!redisUrl) {
+            console.warn('[VoilaJSX AppKit] Production environment detected without REDIS_URL. ' +
+                'Memory cache will not persist across server restarts. ' +
+                'Consider setting REDIS_URL for production deployments.');
+        }
+    }
+    // Validate NODE_ENV
+    if (nodeEnv && !['development', 'production', 'test', 'staging'].includes(nodeEnv)) {
+        console.warn(`[VoilaJSX AppKit] Unusual NODE_ENV: "${nodeEnv}". ` +
+            `Expected: development, production, test, or staging`);
+    }
+}
+/**
+ * Validates Redis URL format
+ * @llm-rule WHEN: Checking Redis connection string validity
+ * @llm-rule AVOID: Using invalid Redis URLs - causes connection failures
+ */
+function isValidRedisUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return ['redis:', 'rediss:'].includes(parsed.protocol);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates numeric environment variable within acceptable range
+ * @llm-rule WHEN: Validating cache configuration numeric values
+ * @llm-rule AVOID: Using values outside safe ranges - causes performance or memory issues
+ */
+function validateNumericEnv(name, min, max) {
+    const value = process.env[name];
+    if (!value)
+        return;
+    const num = parseInt(value);
+    if (isNaN(num) || num < min || num > max) {
+        throw new Error(`Invalid ${name}: "${value}". Must be a number between ${min} and ${max}`);
+    }
+}
+/**
+ * Gets cache configuration summary for debugging and health checks
+ * @llm-rule WHEN: Debugging cache configuration or building health check endpoints
+ * @llm-rule AVOID: Exposing sensitive connection details - this only shows safe info
+ */
+export function getConfigSummary() {
+    const config = getSmartDefaults();
+    return {
+        strategy: config.strategy,
+        keyPrefix: config.keyPrefix,
+        namespace: config.namespace,
+        defaultTTL: config.defaultTTL,
+        redisConnected: config.strategy === 'redis' && !!config.redis?.url,
+        environment: config.environment.nodeEnv,
+    };
+}
+/**
+ * Validates that required cache configuration is present for production
+ * @llm-rule WHEN: App startup validation for production deployments
+ * @llm-rule AVOID: Skipping validation - missing cache config causes runtime issues
+ */
+export function validateProductionRequirements() {
+    const config = getSmartDefaults();
+    if (config.environment.isProduction) {
+        if (config.strategy === 'memory') {
+            console.warn('[VoilaJSX AppKit] Using memory cache in production. ' +
+                'Data will not persist across server restarts. ' +
+                'Set REDIS_URL for persistent caching.');
+        }
+        if (config.strategy === 'redis' && !config.redis?.url) {
+            throw new Error('Redis strategy selected but REDIS_URL not configured. ' +
+                'Set REDIS_URL environment variable for Redis caching.');
+        }
+    }
+}
+//# sourceMappingURL=defaults.js.map

package/dist/cache/defaults.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Ultra-simple caching that just works with automatic Redis/Memory strategy selection
+ * @module @bloomneo/appkit/cache
+ * @file src/cache/index.ts
+ *
+ * @llm-rule WHEN: Building apps that need caching with zero configuration
+ * @llm-rule AVOID: Complex cache setups - this auto-detects Redis vs Memory from environment
+ * @llm-rule NOTE: Uses cacheClass.get(namespace) pattern like auth - get() → cache.set() → done
+ * @llm-rule NOTE: Common pattern - cacheClass.get('users') → cache.set('user:123', data) → cache.get('user:123')
+ */
+import { type CacheConfig } from './defaults.js';
+export interface Cache {
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<boolean>;
+    getOrSet(key: string, factory: () => Promise<any>, ttl?: number): Promise<any>;
+    getStrategy(): string;
+    getConfig(): any;
+}
+/**
+ * Get cache instance for specific namespace - the only function you need to learn
+ * Strategy auto-detected from environment (REDIS_URL = Redis, no REDIS_URL = Memory)
+ * @llm-rule WHEN: Need caching in any part of your app - this is your main entry point
+ * @llm-rule AVOID: Creating CacheClass directly - always use this function
+ * @llm-rule NOTE: Typical flow - get(namespace) → cache.set() → cache.get() → cached data
+ */
+declare function get(namespace?: string): Cache;
+/**
+ * Clear all cache instances and disconnect - essential for testing
+ * @llm-rule WHEN: Testing cache logic with different configurations or app shutdown
+ * @llm-rule AVOID: Using in production except for graceful shutdown
+ */
+declare function clear(): Promise<void>;
+/**
+ * Reset cache configuration (useful for testing)
+ * @llm-rule WHEN: Testing cache logic with different environment configurations
+ * @llm-rule AVOID: Using in production - only for tests and development
+ */
+declare function reset(newConfig?: Partial<CacheConfig>): Promise<void>;
+/**
+ * Get active cache strategy for debugging
+ * @llm-rule WHEN: Debugging or health checks to see which strategy is active (Redis vs Memory)
+ * @llm-rule AVOID: Using for application logic - cache should be transparent
+ */
+declare function getStrategy(): string;
+/**
+ * Get all active cache namespaces
+ * @llm-rule WHEN: Debugging or monitoring which cache namespaces are active
+ * @llm-rule AVOID: Using for business logic - this is for observability only
+ */
+declare function getActiveNamespaces(): string[];
+/**
+ * Get cache configuration summary for debugging
+ * @llm-rule WHEN: Health checks or debugging cache configuration
+ * @llm-rule AVOID: Exposing sensitive connection details - this only shows safe info
+ */
+declare function getConfig(): {
+    strategy: string;
+    keyPrefix: string;
+    defaultTTL: number;
+    activeNamespaces: string[];
+    environment: string;
+};
+/**
+ * Check if Redis is available and configured
+ * @llm-rule WHEN: Conditional logic based on cache capabilities
+ * @llm-rule AVOID: Complex cache detection - just use cache normally, it handles strategy
+ */
+declare function hasRedis(): boolean;
+/**
+ * Flush all caches across all namespaces (dangerous)
+ * @llm-rule WHEN: Testing or emergency cache clearing across all namespaces
+ * @llm-rule AVOID: Using in production - this clears ALL cached data in ALL namespaces
+ * @llm-rule NOTE: Only use for testing or emergency situations
+ */
+declare function flushAll(): Promise<boolean>;
+/**
+ * Graceful shutdown for all cache instances
+ * @llm-rule WHEN: App shutdown or process termination
+ * @llm-rule AVOID: Abrupt process exit - graceful shutdown prevents data loss
+ */
+declare function shutdown(): Promise<void>;
+/**
+ * Single caching export with minimal API (like auth module)
+ */
+export declare const cacheClass: {
+    readonly get: typeof get;
+    readonly clear: typeof clear;
+    readonly reset: typeof reset;
+    readonly getStrategy: typeof getStrategy;
+    readonly getActiveNamespaces: typeof getActiveNamespaces;
+    readonly getConfig: typeof getConfig;
+    readonly hasRedis: typeof hasRedis;
+    readonly flushAll: typeof flushAll;
+    readonly shutdown: typeof shutdown;
+};
+export type { CacheConfig } from './defaults.js';
+export { CacheClass } from './cache.js';
+export default cacheClass;
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAMnE,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/E,WAAW,IAAI,MAAM,CAAC;IACtB,SAAS,IAAI,GAAG,CAAC;CAClB;AAED;;;;;;GAMG;AACH,iBAAS,GAAG,CAAC,SAAS,GAAE,MAAc,GAAG,KAAK,CA8B7C;AAED;;;;GAIG;AACH,iBAAe,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAcpC;AAED;;;;GAIG;AACH,iBAAe,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpE;AAED;;;;GAIG;AACH,iBAAS,WAAW,IAAI,MAAM,CAK7B;AAED;;;;GAIG;AACH,iBAAS,mBAAmB,IAAI,MAAM,EAAE,CAEvC;AAED;;;;GAIG;AACH,iBAAS,SAAS,IAAI;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB,CAYA;AAED;;;;GAIG;AACH,iBAAS,QAAQ,IAAI,OAAO,CAE3B;AAED;;;;;GAKG;AACH,iBAAe,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAc1C;AAED;;;;GAIG;AACH,iBAAe,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CASvC;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;CAab,CAAC;AAGX,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,eAAe,UAAU,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,203 @@
+/**
+ * Ultra-simple caching that just works with automatic Redis/Memory strategy selection
+ * @module @bloomneo/appkit/cache
+ * @file src/cache/index.ts
+ *
+ * @llm-rule WHEN: Building apps that need caching with zero configuration
+ * @llm-rule AVOID: Complex cache setups - this auto-detects Redis vs Memory from environment
+ * @llm-rule NOTE: Uses cacheClass.get(namespace) pattern like auth - get() → cache.set() → done
+ * @llm-rule NOTE: Common pattern - cacheClass.get('users') → cache.set('user:123', data) → cache.get('user:123')
+ */
+import { CacheClass } from './cache.js';
+import { getSmartDefaults } from './defaults.js';
+// Global cache instances for performance (like auth module)
+let globalConfig = null;
+const namedCaches = new Map();
+/**
+ * Get cache instance for specific namespace - the only function you need to learn
+ * Strategy auto-detected from environment (REDIS_URL = Redis, no REDIS_URL = Memory)
+ * @llm-rule WHEN: Need caching in any part of your app - this is your main entry point
+ * @llm-rule AVOID: Creating CacheClass directly - always use this function
+ * @llm-rule NOTE: Typical flow - get(namespace) → cache.set() → cache.get() → cached data
+ */
+function get(namespace = 'app') {
+    // Validate namespace
+    if (!namespace || typeof namespace !== 'string') {
+        throw new Error('Cache namespace must be a non-empty string');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(namespace)) {
+        throw new Error('Cache namespace must contain only letters, numbers, underscores, and hyphens');
+    }
+    // Lazy initialization - parse environment once (like auth)
+    if (!globalConfig) {
+        globalConfig = getSmartDefaults();
+    }
+    // Return cached instance if exists
+    if (namedCaches.has(namespace)) {
+        return namedCaches.get(namespace);
+    }
+    // Create new cache instance for namespace
+    const cacheInstance = new CacheClass(globalConfig, namespace);
+    // Auto-connect on first use
+    cacheInstance.connect().catch((error) => {
+        console.error(`[AppKit] Cache auto-connect failed for namespace "${namespace}":`, error.message);
+    });
+    namedCaches.set(namespace, cacheInstance);
+    return cacheInstance;
+}
+/**
+ * Clear all cache instances and disconnect - essential for testing
+ * @llm-rule WHEN: Testing cache logic with different configurations or app shutdown
+ * @llm-rule AVOID: Using in production except for graceful shutdown
+ */
+async function clear() {
+    const disconnectPromises = [];
+    for (const [namespace, cache] of namedCaches) {
+        disconnectPromises.push(cache.disconnect().catch((error) => {
+            console.error(`[AppKit] Cache disconnect failed for namespace "${namespace}":`, error.message);
+        }));
+    }
+    await Promise.all(disconnectPromises);
+    namedCaches.clear();
+    globalConfig = null;
+}
+/**
+ * Reset cache configuration (useful for testing)
+ * @llm-rule WHEN: Testing cache logic with different environment configurations
+ * @llm-rule AVOID: Using in production - only for tests and development
+ */
+async function reset(newConfig) {
+    // Clear existing instances
+    await clear();
+    // Reset configuration
+    if (newConfig) {
+        const defaults = getSmartDefaults();
+        globalConfig = { ...defaults, ...newConfig };
+    }
+    else {
+        globalConfig = null; // Will reload from environment on next get()
+    }
+}
+/**
+ * Get active cache strategy for debugging
+ * @llm-rule WHEN: Debugging or health checks to see which strategy is active (Redis vs Memory)
+ * @llm-rule AVOID: Using for application logic - cache should be transparent
+ */
+function getStrategy() {
+    if (!globalConfig) {
+        globalConfig = getSmartDefaults();
+    }
+    return globalConfig.strategy;
+}
+/**
+ * Get all active cache namespaces
+ * @llm-rule WHEN: Debugging or monitoring which cache namespaces are active
+ * @llm-rule AVOID: Using for business logic - this is for observability only
+ */
+function getActiveNamespaces() {
+    return Array.from(namedCaches.keys());
+}
+/**
+ * Get cache configuration summary for debugging
+ * @llm-rule WHEN: Health checks or debugging cache configuration
+ * @llm-rule AVOID: Exposing sensitive connection details - this only shows safe info
+ */
+function getConfig() {
+    if (!globalConfig) {
+        globalConfig = getSmartDefaults();
+    }
+    return {
+        strategy: globalConfig.strategy,
+        keyPrefix: globalConfig.keyPrefix,
+        defaultTTL: globalConfig.defaultTTL,
+        activeNamespaces: getActiveNamespaces(),
+        environment: globalConfig.environment.nodeEnv,
+    };
+}
+/**
+ * Check if Redis is available and configured
+ * @llm-rule WHEN: Conditional logic based on cache capabilities
+ * @llm-rule AVOID: Complex cache detection - just use cache normally, it handles strategy
+ */
+function hasRedis() {
+    return !!process.env.REDIS_URL;
+}
+/**
+ * Flush all caches across all namespaces (dangerous)
+ * @llm-rule WHEN: Testing or emergency cache clearing across all namespaces
+ * @llm-rule AVOID: Using in production - this clears ALL cached data in ALL namespaces
+ * @llm-rule NOTE: Only use for testing or emergency situations
+ */
+async function flushAll() {
+    try {
+        const clearPromises = [];
+        for (const cache of namedCaches.values()) {
+            clearPromises.push(cache.clear());
+        }
+        const results = await Promise.all(clearPromises);
+        return results.every(result => result === true);
+    }
+    catch (error) {
+        console.error('[AppKit] Cache flushAll error:', error.message);
+        return false;
+    }
+}
+/**
+ * Graceful shutdown for all cache instances
+ * @llm-rule WHEN: App shutdown or process termination
+ * @llm-rule AVOID: Abrupt process exit - graceful shutdown prevents data loss
+ */
+async function shutdown() {
+    console.log('🔄 [AppKit] Cache graceful shutdown...');
+    try {
+        await clear();
+        console.log('✅ [AppKit] Cache shutdown complete');
+    }
+    catch (error) {
+        console.error('❌ [AppKit] Cache shutdown error:', error.message);
+    }
+}
+/**
+ * Single caching export with minimal API (like auth module)
+ */
+export const cacheClass = {
+    // Core method (like auth.get())
+    get,
+    // Utility methods
+    clear,
+    reset,
+    getStrategy,
+    getActiveNamespaces,
+    getConfig,
+    hasRedis,
+    flushAll,
+    shutdown,
+};
+export { CacheClass } from './cache.js';
+// Default export
+export default cacheClass;
+// Auto-setup graceful shutdown handlers
+if (typeof process !== 'undefined') {
+    // Handle graceful shutdown
+    const shutdownHandler = () => {
+        shutdown().finally(() => {
+            process.exit(0);
+        });
+    };
+    process.on('SIGTERM', shutdownHandler);
+    process.on('SIGINT', shutdownHandler);
+    // Handle uncaught errors
+    process.on('uncaughtException', (error) => {
+        console.error('[AppKit] Uncaught exception during cache operation:', error);
+        shutdown().finally(() => {
+            process.exit(1);
+        });
+    });
+    process.on('unhandledRejection', (reason) => {
+        console.error('[AppKit] Unhandled rejection during cache operation:', reason);
+        shutdown().finally(() => {
+            process.exit(1);
+        });
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

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

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

@@ -0,0 +1,138 @@
+/**
+ * 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
+ */
+import type { CacheStrategy } from '../cache.js';
+import type { CacheConfig } from '../defaults.js';
+/**
+ * Memory cache strategy with intelligent eviction and cleanup
+ */
+export declare class MemoryStrategy implements CacheStrategy {
+    private config;
+    private cache;
+    private totalSize;
+    private cleanupInterval;
+    private connected;
+    /**
+     * 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: CacheConfig);
+    /**
+     * 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
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects memory cache (stops cleanup intervals)
+     * @llm-rule WHEN: App shutdown or cache cleanup
+     * @llm-rule AVOID: Memory leaks - always stop intervals on shutdown
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 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
+     */
+    get(key: string): Promise<any>;
+    /**
+     * 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
+     */
+    set(key: string, value: any, ttl: number): Promise<boolean>;
+    /**
+     * 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
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    clear(): Promise<boolean>;
+    /**
+     * 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
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Deletes multiple keys efficiently
+     * @llm-rule WHEN: Bulk deletion operations like namespace clearing
+     * @llm-rule AVOID: Individual delete calls in loops - this batches operations
+     */
+    deleteMany(keys: string[]): Promise<number>;
+    /**
+     * Deletes single item and updates size tracking
+     */
+    private deleteItem;
+    /**
+     * Checks if cache item has expired
+     */
+    private isExpired;
+    /**
+     * Evicts items when memory limits are exceeded
+     */
+    private evictIfNeeded;
+    /**
+     * Evicts least recently used item
+     */
+    private evictLRU;
+    /**
+     * Calculates memory size of value (approximate)
+     */
+    private calculateSize;
+    /**
+     * Deep clones value to prevent external mutations
+     */
+    private deepClone;
+    /**
+     * Converts glob pattern to regex for key matching
+     */
+    private patternToRegex;
+    /**
+     * Starts automatic cleanup interval for TTL expiration
+     */
+    private startCleanupInterval;
+    /**
+     * Stops cleanup interval
+     */
+    private stopCleanupInterval;
+    /**
+     * Removes expired items from cache
+     */
+    private cleanupExpired;
+    /**
+     * Formats bytes for human-readable display
+     */
+    private formatBytes;
+    /**
+     * Gets memory cache statistics for debugging
+     */
+    getStats(): {
+        itemCount: number;
+        totalSize: number;
+        totalSizeFormatted: string;
+        maxItems: number;
+        maxSize: number;
+        maxSizeFormatted: string;
+        memoryUsage: number;
+    };
+}
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/cache/strategies/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAUlD;;GAEG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;OAIG;gBACS,MAAM,EAAE,WAAW;IAI/B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAmBpC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwCjE;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3C;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAM/B;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBxC;;;;OAIG;IACG,IAAI,CAAC,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBpD;;;;OAIG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAcjD;;OAEG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,aAAa;IAgBrB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAsBhB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,SAAS;IASjB;;OAEG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAoBtB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB;CAaF"}