lumisjs 1.0.0

package/src/cache/CacheManager.js

@@ -0,0 +1,393 @@
+'use strict';
+
+const { EventEmitter } = require('node:events');
+const MemoryAdapter = require('./MemoryAdapter');
+const Logger = require('../utils/Logger');
+const { LumisError } = require('../errors/LumisError');
+const { ErrorCodes } = require('../errors/ErrorCodes');
+
+class CacheManager extends EventEmitter {
+  /**
+   * Unified cache interface that delegates to a pluggable adapter.
+   * Enhanced with metrics, monitoring, and advanced features.
+   *
+   * @param {object} [options]
+   * @param {'memory'|'redis'|'sqlite'|object} [options.adapter='memory']
+   * @param {object} [options.maxSize] Passed to MemoryAdapter
+   * @param {number} [options.ttl] Default TTL in seconds
+   * @param {boolean} [options.enableMetrics=true] Enable cache metrics
+   * @param {boolean} [options.enableEvents=true] Enable cache events
+   */
+  constructor(options = {}) {
+    super();
+    this.options = options;
+    this.logger = new Logger({ prefix: 'Cache', level: 'info' });
+
+    const adapterName = options.adapter || 'memory';
+    this.adapter = this._createAdapter(adapterName, options);
+    this.logger.info(`Cache adapter: ${typeof adapterName === 'string' ? adapterName : 'custom'}`);
+
+    // Metrics tracking
+    this.enableMetrics = options.enableMetrics !== false;
+    this.metrics = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      deletes: 0,
+      gets: 0,
+      evictions: 0,
+      startTime: Date.now(),
+    };
+
+    // Event emission
+    this.enableEvents = options.enableEvents !== false;
+  }
+
+  _createAdapter(name, options) {
+    if (typeof name === 'object' && name !== null) {
+      // Custom adapter passed directly — validate the interface
+      const required = ['get', 'set', 'delete', 'has', 'clear', 'keys'];
+      const missing = required.filter((m) => typeof name[m] !== 'function');
+      if (missing.length) {
+        throw new LumisError(
+          ErrorCodes.CACHE_ADAPTER_ERROR,
+          `Custom adapter is missing methods: ${missing.join(', ')}`
+        );
+      }
+      return name;
+    }
+
+    switch (name) {
+      case 'memory':
+        return new MemoryAdapter(options);
+
+      case 'redis': {
+        const RedisAdapter = require('./RedisAdapter');
+        return new RedisAdapter(options);
+      }
+
+      case 'sqlite': {
+        const SQLiteAdapter = require('./SQLiteAdapter');
+        return new SQLiteAdapter(options);
+      }
+
+      default:
+        throw new LumisError(ErrorCodes.CACHE_ADAPTER_NOT_FOUND, name);
+    }
+  }
+
+  // ── Core API ──────────────────────────────────────────────────────────────
+
+  async get(key) {
+    this._trackMetric('gets');
+    const value = await this.adapter.get(key);
+    
+    if (this.enableMetrics) {
+      if (value !== undefined) {
+        this.metrics.hits++;
+      } else {
+        this.metrics.misses++;
+      }
+    }
+    
+    if (this.enableEvents) {
+      this.emit('get', { key, hit: value !== undefined });
+    }
+    
+    return value;
+  }
+
+  async set(key, value, ttl) {
+    this._trackMetric('sets');
+    await this.adapter.set(key, value, ttl);
+    
+    if (this.enableEvents) {
+      this.emit('set', { key, ttl });
+    }
+  }
+
+  async delete(key) {
+    this._trackMetric('deletes');
+    const result = await this.adapter.delete(key);
+    
+    if (this.enableEvents) {
+      this.emit('delete', { key, existed: result });
+    }
+    
+    return result;
+  }
+
+  async has(key) {
+    return this.adapter.has(key);
+  }
+
+  async clear() {
+    await this.adapter.clear();
+    
+    if (this.enableEvents) {
+      this.emit('clear');
+    }
+  }
+
+  async size() {
+    return this.adapter.size();
+  }
+
+  async values() {
+    return this.adapter.values();
+  }
+
+  async keys() {
+    return this.adapter.keys();
+  }
+
+  async filter(fn) {
+    return this.adapter.filter(fn);
+  }
+
+  // ── Utilities ─────────────────────────────────────────────────────────────
+
+  /**
+   * Return existing value for key, or compute, store, and return defaultValue.
+   * @template T
+   * @param {string} key
+   * @param {T|(() => T|Promise<T>)} defaultValue
+   * @param {number} [ttl]
+   * @returns {Promise<T>}
+   */
+  async ensure(key, defaultValue, ttl) {
+    const existing = await this.get(key);
+    if (existing !== undefined) return existing;
+
+    const value =
+      typeof defaultValue === 'function' ? await defaultValue() : defaultValue;
+    await this.set(key, value, ttl);
+    
+    if (this.enableEvents) {
+      this.emit('ensure', { key, computed: true });
+    }
+    
+    return value;
+  }
+
+  /**
+   * Get the value and delete the key atomically (pop).
+   * @param {string} key
+   * @returns {Promise<any>}
+   */
+  async take(key) {
+    const value = await this.get(key);
+    if (value !== undefined) {
+      await this.delete(key);
+      if (this.enableEvents) {
+        this.emit('take', { key });
+      }
+    }
+    return value;
+  }
+
+  /**
+   * Get multiple keys at once.
+   * @param {string[]} keys
+   * @returns {Promise<Map<string, any>>}
+   */
+  async getMany(keys) {
+    const result = new Map();
+    await Promise.all(
+      keys.map(async (key) => {
+        const val = await this.get(key);
+        if (val !== undefined) result.set(key, val);
+      })
+    );
+    
+    if (this.enableEvents) {
+      this.emit('getMany', { keys, count: result.size });
+    }
+    
+    return result;
+  }
+
+  /**
+   * Set multiple key/value pairs at once.
+   * @param {Array<[string, any, number?]>} entries - [key, value, ttl?]
+   * @returns {Promise<void>}
+   */
+  async setMany(entries) {
+    await Promise.all(entries.map(([key, value, ttl]) => this.set(key, value, ttl)));
+    
+    if (this.enableEvents) {
+      this.emit('setMany', { count: entries.length });
+    }
+  }
+
+  async destroy() {
+    if (typeof this.adapter.destroy === 'function') {
+      await this.adapter.destroy();
+    }
+    
+    if (this.enableEvents) {
+      this.emit('destroy');
+    }
+    
+    this.removeAllListeners();
+  }
+
+  // ── Metrics & Monitoring ────────────────────────────────────────────────────
+
+  /**
+   * Get cache metrics.
+   * @returns {object}
+   */
+  getMetrics() {
+    if (!this.enableMetrics) return null;
+
+    const uptime = Date.now() - this.metrics.startTime;
+    const totalRequests = this.metrics.hits + this.metrics.misses;
+    const hitRate = totalRequests > 0 ? (this.metrics.hits / totalRequests) * 100 : 0;
+
+    return {
+      ...this.metrics,
+      uptime,
+      totalRequests,
+      hitRate: hitRate.toFixed(2) + '%',
+      missRate: (100 - hitRate).toFixed(2) + '%',
+    };
+  }
+
+  /**
+   * Reset cache metrics.
+   */
+  resetMetrics() {
+    this.metrics = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      deletes: 0,
+      gets: 0,
+      evictions: 0,
+      startTime: Date.now(),
+    };
+  }
+
+  /**
+   * Get cache statistics summary.
+   * @returns {Promise<object>}
+   */
+  async getStats() {
+    const size = await this.size();
+    const metrics = this.getMetrics();
+
+    return {
+      size,
+      adapter: this.adapter.constructor.name,
+      metrics,
+    };
+  }
+
+  // ── Advanced Features ───────────────────────────────────────────────────────
+
+  /**
+   * Execute multiple operations atomically (transaction-like).
+   * @param {Function} fn - Function that receives cache instance
+   * @returns {Promise<any>}
+   */
+  async transaction(fn) {
+    // For memory adapter, this is synchronous
+    // For distributed adapters, this would need proper transaction support
+    return fn(this);
+  }
+
+  /**
+   * Invalidate keys matching a pattern.
+   * @param {string} pattern - Glob pattern (e.g., 'user:*')
+   * @returns {Promise<number>} Number of deleted keys
+   */
+  async invalidatePattern(pattern) {
+    const allKeys = await this.keys();
+    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+    const keysToDelete = allKeys.filter(key => regex.test(key));
+    
+    await Promise.all(keysToDelete.map(key => this.delete(key)));
+    
+    if (this.enableEvents) {
+      this.emit('invalidatePattern', { pattern, count: keysToDelete.length });
+    }
+    
+    return keysToDelete.length;
+  }
+
+  /**
+   * Warm up cache with preloaded data.
+   * @param {Map<string, any>} data - Data to preload
+   * @param {number} [ttl] - Default TTL for all entries
+   * @returns {Promise<void>}
+   */
+  async warmup(data, ttl) {
+    const entries = Array.from(data.entries()).map(([key, value]) => [key, value, ttl]);
+    await this.setMany(entries);
+    
+    if (this.enableEvents) {
+      this.emit('warmup', { count: entries.length });
+    }
+  }
+
+  /**
+   * Get or set with sliding expiration.
+   * Extends TTL on each access.
+   * @param {string} key
+   * @param {Function} factory - Function to generate value if missing
+   * @param {number} ttl - TTL in seconds
+   * @returns {Promise<any>}
+   */
+  async getOrSet(key, factory, ttl) {
+    const value = await this.get(key);
+    if (value !== undefined) {
+      // Extend TTL on hit
+      await this.set(key, value, ttl);
+      return value;
+    }
+    
+    const newValue = await factory();
+    await this.set(key, newValue, ttl);
+    return newValue;
+  }
+
+  /**
+   * Backup cache data to object.
+   * @returns {Promise<object>}
+   */
+  async backup() {
+    const keys = await this.keys();
+    const backup = {};
+    
+    for (const key of keys) {
+      backup[key] = await this.get(key);
+    }
+    
+    return backup;
+  }
+
+  /**
+   * Restore cache data from backup object.
+   * @param {object} backup - Backup data
+   * @param {number} [ttl] - TTL for restored entries
+   * @returns {Promise<void>}
+   */
+  async restore(backup, ttl) {
+    const entries = Object.entries(backup).map(([key, value]) => [key, value, ttl]);
+    await this.setMany(entries);
+    
+    if (this.enableEvents) {
+      this.emit('restore', { count: entries.length });
+    }
+  }
+
+  /** @private */
+  _trackMetric(metric) {
+    if (this.enableMetrics) {
+      this.metrics[metric]++;
+    }
+  }
+}
+
+module.exports = CacheManager;

package/src/cache/MemoryAdapter.js

@@ -0,0 +1,259 @@
+'use strict';
+
+class MemoryAdapter {
+  /**
+   * LRU-capable in-memory cache adapter with TTL support.
+   * @param {object} [options]
+   * @param {number} [options.maxSize=0] Max entries; 0 = unlimited
+   * @param {number} [options.ttl=0] Default TTL in seconds; 0 = no expiry
+   */
+  constructor(options = {}) {
+    this._store = new Map();
+    this.maxSize = options.maxSize ?? 0;
+    this.defaultTTL = options.ttl ?? 0;
+    // LRU order: leftmost = oldest, rightmost = newest
+    this._accessOrder = [];
+    // Periodic cleanup interval (every 5 min by default)
+    this._cleanupInterval = null;
+    const cleanupMs = (options.cleanupIntervalSec ?? 300) * 1000;
+    if (cleanupMs > 0) {
+      this._cleanupInterval = setInterval(() => this._cleanup(), cleanupMs);
+      if (this._cleanupInterval.unref) this._cleanupInterval.unref();
+    }
+  }
+
+  async get(key) {
+    const entry = this._store.get(key);
+    if (!entry) {
+      this._missCount++;
+      return undefined;
+    }
+
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this._store.delete(key);
+      this._removeFromAccessOrder(key);
+      this._missCount++;
+      return undefined;
+    }
+
+    this._hitCount++;
+    this._touchAccessOrder(key);
+    return entry.value;
+  }
+
+  async set(key, value, ttl) {
+    if (this.maxSize > 0 && !this._store.has(key) && this._store.size >= this.maxSize) {
+      this._evict();
+    }
+
+    const effectiveTTL = ttl ?? this.defaultTTL;
+    const expiresAt = effectiveTTL > 0 ? Date.now() + effectiveTTL * 1000 : null;
+
+    this._store.set(key, { value, expiresAt, createdAt: Date.now() });
+    this._touchAccessOrder(key);
+  }
+
+  async delete(key) {
+    this._removeFromAccessOrder(key);
+    return this._store.delete(key);
+  }
+
+  async has(key) {
+    const value = await this.get(key);
+    return value !== undefined;
+  }
+
+  async clear() {
+    this._store.clear();
+    this._accessOrder = [];
+  }
+
+  async size() {
+    await this._cleanup();
+    return this._store.size;
+  }
+
+  async values() {
+    await this._cleanup();
+    return [...this._store.values()].map((e) => e.value);
+  }
+
+  async keys() {
+    await this._cleanup();
+    return [...this._store.keys()];
+  }
+
+  async filter(fn) {
+    await this._cleanup();
+    const results = [];
+    for (const [key, entry] of this._store) {
+      if (fn(entry.value, key)) results.push(entry.value);
+    }
+    return results;
+  }
+
+  async forEach(fn) {
+    await this._cleanup();
+    for (const [key, entry] of this._store) {
+      fn(entry.value, key);
+    }
+  }
+
+  // ── Advanced Memory Features ────────────────────────────────────────────────────
+
+  /**
+   * Get multiple keys at once.
+   * @param {string[]} keys
+   * @returns {Promise<Map<string, any>>}
+   */
+  async getMany(keys) {
+    const result = new Map();
+    for (const key of keys) {
+      const value = await this.get(key);
+      if (value !== undefined) result.set(key, value);
+    }
+    return result;
+  }
+
+  /**
+   * Set multiple keys at once.
+   * @param {Array<[string, any, number?]>} entries
+   * @returns {Promise<void>}
+   */
+  async setMany(entries) {
+    for (const [key, value, ttl] of entries) {
+      await this.set(key, value, ttl);
+    }
+  }
+
+  /**
+   * Get cache statistics.
+   * @returns {object}
+   */
+  getStats() {
+    const now = Date.now();
+    let expiredCount = 0;
+    let totalSize = 0;
+
+    for (const [key, entry] of this._store) {
+      if (entry.expiresAt !== null && now > entry.expiresAt) {
+        expiredCount++;
+      }
+      totalSize += JSON.stringify(entry.value).length;
+    }
+
+    return {
+      size: this._store.size,
+      maxSize: this.maxSize,
+      expiredCount,
+      memoryUsage: totalSize,
+      hitRate: this._calculateHitRate(),
+    };
+  }
+
+  /**
+   * Get keys sorted by access time (LRU order).
+   * @param {number} [limit]
+   * @returns {string[]}
+   */
+  getLRUKeys(limit) {
+    const keys = limit ? this._accessOrder.slice(-limit) : [...this._accessOrder];
+    return keys.reverse();
+  }
+
+  /**
+   * Peek at a value without updating access time.
+   * @param {string} key
+   * @returns {any}
+   */
+  async peek(key) {
+    const entry = this._store.get(key);
+    if (!entry) return undefined;
+
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this._store.delete(key);
+      this._removeFromAccessOrder(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Get time until expiration for a key.
+   * @param {string} key
+   * @returns {number|null} TTL in milliseconds, or null if no expiry
+   */
+  async getTTL(key) {
+    const entry = this._store.get(key);
+    if (!entry || entry.expiresAt === null) return null;
+    
+    const remaining = entry.expiresAt - Date.now();
+    return remaining > 0 ? remaining : 0;
+  }
+
+  /**
+   * Set TTL on existing key.
+   * @param {string} key
+   * @param {number} ttl TTL in seconds
+   * @returns {boolean}
+   */
+  async setTTL(key, ttl) {
+    const entry = this._store.get(key);
+    if (!entry) return false;
+    
+    entry.expiresAt = ttl > 0 ? Date.now() + ttl * 1000 : null;
+    return true;
+  }
+
+  /** @private */
+  _hitCount = 0;
+  /** @private */
+  _missCount = 0;
+
+  _calculateHitRate() {
+    const total = this._hitCount + this._missCount;
+    return total > 0 ? (this._hitCount / total) * 100 : 0;
+  }
+
+  /** Evict the least-recently-used entry. */
+  _evict() {
+    if (this._accessOrder.length === 0) return;
+    const oldestKey = this._accessOrder.shift();
+    this._store.delete(oldestKey);
+  }
+
+  _touchAccessOrder(key) {
+    const idx = this._accessOrder.indexOf(key);
+    if (idx !== -1) this._accessOrder.splice(idx, 1);
+    this._accessOrder.push(key);
+  }
+
+  _removeFromAccessOrder(key) {
+    const idx = this._accessOrder.indexOf(key);
+    if (idx !== -1) this._accessOrder.splice(idx, 1);
+  }
+
+  async _cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this._store) {
+      if (entry.expiresAt !== null && now > entry.expiresAt) {
+        this._store.delete(key);
+        this._removeFromAccessOrder(key);
+      }
+    }
+  }
+
+  async destroy() {
+    if (this._cleanupInterval) {
+      clearInterval(this._cleanupInterval);
+      this._cleanupInterval = null;
+    }
+    this._store.clear();
+    this._accessOrder = [];
+    this._hitCount = 0;
+    this._missCount = 0;
+  }
+}
+
+module.exports = MemoryAdapter;