@onlineapps/conn-base-cache 1.0.0

package/src/index.js

@@ -0,0 +1,923 @@
+/**
+ * @module @onlineapps/conn-base-cache
+ * @description Redis cache connector with TTL, invalidation, and namespace support for OA Drive microservices.
+ * This connector provides a high-level abstraction over Redis operations with automatic key prefixing,
+ * statistics tracking, and namespace isolation.
+ *
+ * IMPORTANT: This connector uses "cache:" prefix for all keys.
+ * Never accesses "obs:" namespace (reserved for monitoring).
+ *
+ * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-base-cache|GitHub Repository}
+ * @author OA Drive Team
+ * @license MIT
+ * @since 1.0.0
+ */
+
+const Redis = require('ioredis');
+const crypto = require('crypto');
+
+/**
+ * Redis cache connector providing caching operations with automatic key management
+ *
+ * @class CacheConnector
+ *
+ * @example <caption>Basic Usage</caption>
+ * const cache = new CacheConnector({
+ *   host: 'localhost',
+ *   port: 6379,
+ *   defaultTTL: 3600
+ * });
+ * await cache.connect();
+ * await cache.set('user:123', { name: 'John' }, 600);
+ * const user = await cache.get('user:123');
+ *
+ * @example <caption>With Namespace</caption>
+ * const cache = new CacheConnector({
+ *   namespace: 'invoice-service'
+ * });
+ * await cache.set('inv:123', data); // Actual key: cache:invoice-service:inv:123
+ */
+class CacheConnector {
+  /**
+   * Creates a new CacheConnector instance
+   *
+   * @constructor
+   * @param {Object} [config={}] - Configuration options
+   * @param {string} [config.host='localhost'] - Redis server host
+   * @param {number} [config.port=6379] - Redis server port
+   * @param {string} [config.password] - Redis password for authentication
+   * @param {number} [config.db=0] - Redis database number to use
+   * @param {number} [config.defaultTTL=3600] - Default TTL in seconds for cached items
+   * @param {string} [config.namespace=''] - Namespace prefix for all keys
+   * @param {number} [config.maxRetries=3] - Maximum connection retry attempts
+   * @param {number} [config.retryDelay=100] - Initial retry delay in milliseconds
+   * @param {boolean} [config.enableOfflineQueue=true] - Queue commands when disconnected
+   * @param {boolean} [config.lazyConnect=false] - Delay connection until first operation
+   *
+   * @throws {TypeError} If configuration is invalid
+   *
+   * @example <caption>Full Configuration</caption>
+   * const cache = new CacheConnector({
+   *   host: 'redis.example.com',
+   *   port: 6380,
+   *   password: 'secret',
+   *   namespace: 'my-service',
+   *   defaultTTL: 1800,
+   *   maxRetries: 5,
+   *   enableOfflineQueue: false
+   * });
+   */
+  constructor(config = {}) {
+    // Configuration
+    this.config = {
+      host: config.host || process.env.REDIS_HOST || 'localhost',
+      port: config.port || process.env.REDIS_PORT || 6379,
+      password: config.password || process.env.REDIS_PASSWORD,
+      db: config.db || process.env.REDIS_DB || 0,
+      keyPrefix: 'cache:', // ALWAYS use cache: prefix
+      defaultTTL: config.defaultTTL || 3600, // 1 hour default
+      maxRetries: config.maxRetries || 3,
+      retryDelay: config.retryDelay || 100,
+      enableOfflineQueue: config.enableOfflineQueue !== false,
+      lazyConnect: config.lazyConnect || false
+    };
+
+    // Namespace configuration
+    this.namespace = config.namespace || '';
+
+    // Redis client
+    this.client = null;
+
+    // Connection state
+    this.connected = false;
+    this.connecting = false;
+
+    // Statistics
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      deletes: 0,
+      errors: 0
+    };
+  }
+
+  /**
+   * Establishes connection to Redis server
+   *
+   * @async
+   * @method connect
+   * @returns {Promise<boolean>} Returns true when connection is established
+   *
+   * @throws {Error} Throws error if connection fails after all retries
+   *
+   * @fires CacheConnector#connect
+   * @fires CacheConnector#error
+   * @fires CacheConnector#close
+   *
+   * @example <caption>Simple Connection</caption>
+   * try {
+   *   await cache.connect();
+   *   console.log('Connected to Redis');
+   * } catch (error) {
+   *   console.error('Failed to connect:', error);
+   * }
+   *
+   * @example <caption>With Event Handlers</caption>
+   * cache.client.on('connect', () => {
+   *   console.log('Redis connected');
+   * });
+   *
+   * cache.client.on('error', (err) => {
+   *   console.error('Redis error:', err);
+   * });
+   *
+   * await cache.connect();
+   */
+  async connect() {
+    if (this.connected || this.connecting) {
+      return true;
+    }
+
+    this.connecting = true;
+
+    try {
+      this.client = new Redis({
+        host: this.config.host,
+        port: this.config.port,
+        password: this.config.password,
+        db: this.config.db,
+        keyPrefix: this.config.keyPrefix,
+        retryStrategy: (times) => {
+          if (times > this.config.maxRetries) {
+            return null; // Stop retrying
+          }
+          return Math.min(times * this.config.retryDelay, 2000);
+        },
+        enableOfflineQueue: this.config.enableOfflineQueue,
+        lazyConnect: this.config.lazyConnect
+      });
+
+      // Handle events
+      this.client.on('connect', () => {
+        this.connected = true;
+        this.connecting = false;
+        console.log('Redis cache connected');
+      });
+
+      this.client.on('error', (err) => {
+        this.stats.errors++;
+        console.error('Redis cache error:', err);
+      });
+
+      this.client.on('close', () => {
+        this.connected = false;
+        console.log('Redis cache connection closed');
+      });
+
+      // Wait for connection if not lazy
+      if (!this.config.lazyConnect) {
+        await this.client.connect();
+      }
+
+      this.connected = true;
+      this.connecting = false;
+
+      return true;
+    } catch (error) {
+      this.connecting = false;
+      throw new Error(`Failed to connect to Redis: ${error.message}`);
+    }
+  }
+
+  /**
+   * Disconnect from Redis server gracefully
+   *
+   * @async
+   * @method disconnect
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await cache.disconnect();
+   * console.log('Disconnected from Redis');
+   */
+  async disconnect() {
+    if (this.client) {
+      await this.client.quit();
+      this.client = null;
+      this.connected = false;
+    }
+  }
+
+  /**
+   * Build cache key with namespace
+   * @private
+   */
+  buildKey(key) {
+    if (this.namespace) {
+      return `${this.namespace}:${key}`;
+    }
+    return key;
+  }
+
+  /**
+   * Retrieves a value from cache by key
+   *
+   * @async
+   * @method get
+   * @param {string} key - Cache key to retrieve
+   * @returns {Promise<*|null>} The cached value (parsed from JSON if applicable) or null if not found
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @fires CacheConnector#hit - When cache hit occurs
+   * @fires CacheConnector#miss - When cache miss occurs
+   *
+   * @example <caption>Get Simple Value</caption>
+   * const value = await cache.get('user:123');
+   * if (value) {
+   *   console.log('User found:', value);
+   * }
+   *
+   * @example <caption>Get with Fallback</caption>
+   * let user = await cache.get('user:123');
+   * if (!user) {
+   *   user = await fetchFromDatabase(123);
+   *   await cache.set('user:123', user, 600);
+   * }
+   */
+  async get(key) {
+    try {
+      const fullKey = this.buildKey(key);
+      const value = await this.client.get(fullKey);
+
+      if (value === null) {
+        this.stats.misses++;
+        return null;
+      }
+
+      this.stats.hits++;
+
+      // Try to parse JSON
+      try {
+        return JSON.parse(value);
+      } catch {
+        // Return as string if not JSON
+        return value;
+      }
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Cache get failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Stores a value in cache with optional TTL
+   *
+   * @async
+   * @method set
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache (will be JSON stringified if not a string)
+   * @param {number} [ttl] - Time to live in seconds (uses defaultTTL if not specified)
+   * @returns {Promise<boolean>} Returns true on successful storage
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example <caption>Set with Default TTL</caption>
+   * await cache.set('config', { theme: 'dark' });
+   *
+   * @example <caption>Set with Custom TTL</caption>
+   * await cache.set('session:abc', sessionData, 1800); // 30 minutes
+   *
+   * @example <caption>Set Permanent (no expiry)</caption>
+   * await cache.set('permanent:data', data, 0);
+   */
+  async set(key, value, ttl) {
+    try {
+      const fullKey = this.buildKey(key);
+      const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+      const expiry = ttl || this.config.defaultTTL;
+
+      if (expiry > 0) {
+        await this.client.setex(fullKey, expiry, serialized);
+      } else {
+        await this.client.set(fullKey, serialized);
+      }
+
+      this.stats.sets++;
+      return true;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Cache set failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete a single key from cache
+   *
+   * @async
+   * @method delete
+   * @param {string} key - Cache key to delete
+   * @returns {Promise<boolean>} Returns true if key was deleted
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * const deleted = await cache.delete('user:123');
+   * if (deleted) {
+   *   console.log('Key deleted');
+   * }
+   */
+  async delete(key) {
+    try {
+      const fullKey = this.buildKey(key);
+      const result = await this.client.del(fullKey);
+
+      this.stats.deletes++;
+      return result > 0;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Cache delete failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Deletes keys matching a pattern
+   *
+   * @async
+   * @method deleteByPattern
+   * @param {string} pattern - Redis key pattern (e.g., "user:*", "session:*")
+   * @returns {Promise<number>} Number of deleted keys
+   *
+   * @throws {Error} Throws error if pattern deletion fails
+   *
+   * @warning This operation can be expensive on large datasets
+   *
+   * @example <caption>Delete All User Cache Entries</caption>
+   * const deleted = await cache.deleteByPattern('user:*');
+   * console.log(`Deleted ${deleted} user entries`);
+   *
+   * @example <caption>Delete Specific Session Pattern</caption>
+   * await cache.deleteByPattern('session:user:123:*');
+   */
+  async deleteByPattern(pattern) {
+    try {
+      const fullPattern = this.buildKey(pattern);
+      const keys = await this.client.keys(`${this.config.keyPrefix}${fullPattern}`);
+
+      if (keys.length === 0) {
+        return 0;
+      }
+
+      // Remove key prefix for del command
+      const cleanKeys = keys.map(k => k.replace(this.config.keyPrefix, ''));
+      const result = await this.client.del(...cleanKeys);
+
+      this.stats.deletes += result;
+      return result;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Pattern delete failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check if key exists in cache
+   *
+   * @async
+   * @method exists
+   * @param {string} key - Cache key to check
+   * @returns {Promise<boolean>} Returns true if key exists
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * if (await cache.exists('user:123')) {
+   *   console.log('User is cached');
+   * }
+   */
+  async exists(key) {
+    try {
+      const fullKey = this.buildKey(key);
+      const result = await this.client.exists(fullKey);
+      return result === 1;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Cache exists check failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get remaining TTL for key
+   *
+   * @async
+   * @method ttl
+   * @param {string} key - Cache key
+   * @returns {Promise<number>} TTL in seconds, -1 if no TTL, -2 if not exists
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * const ttl = await cache.ttl('session:abc');
+   * if (ttl > 0) {
+   *   console.log(`Session expires in ${ttl} seconds`);
+   * } else if (ttl === -1) {
+   *   console.log('Session has no expiry');
+   * } else {
+   *   console.log('Session does not exist');
+   * }
+   */
+  async ttl(key) {
+    try {
+      const fullKey = this.buildKey(key);
+      return await this.client.ttl(fullKey);
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`TTL check failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Update TTL for existing key
+   *
+   * @async
+   * @method expire
+   * @param {string} key - Cache key
+   * @param {number} ttl - New TTL in seconds
+   * @returns {Promise<boolean>} Returns true if TTL was set
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * // Extend session by 30 minutes
+   * await cache.expire('session:abc', 1800);
+   */
+  async expire(key, ttl) {
+    try {
+      const fullKey = this.buildKey(key);
+      const result = await this.client.expire(fullKey, ttl);
+      return result === 1;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Expire failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Increment numeric value atomically
+   *
+   * @async
+   * @method incr
+   * @param {string} key - Cache key
+   * @param {number} [increment=1] - Increment value
+   * @returns {Promise<number>} New value after increment
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example <caption>Simple Counter</caption>
+   * const count = await cache.incr('page:views');
+   * console.log(`Page views: ${count}`);
+   *
+   * @example <caption>Increment by Value</caption>
+   * const score = await cache.incr('user:score', 10);
+   */
+  async incr(key, increment = 1) {
+    try {
+      const fullKey = this.buildKey(key);
+
+      if (increment === 1) {
+        return await this.client.incr(fullKey);
+      } else {
+        return await this.client.incrby(fullKey, increment);
+      }
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Increment failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Decrement numeric value atomically
+   *
+   * @async
+   * @method decr
+   * @param {string} key - Cache key
+   * @param {number} [decrement=1] - Decrement value
+   * @returns {Promise<number>} New value after decrement
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * const remaining = await cache.decr('inventory:count', 1);
+   * if (remaining < 0) {
+   *   console.log('Out of stock');
+   * }
+   */
+  async decr(key, decrement = 1) {
+    try {
+      const fullKey = this.buildKey(key);
+
+      if (decrement === 1) {
+        return await this.client.decr(fullKey);
+      } else {
+        return await this.client.decrby(fullKey, decrement);
+      }
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Decrement failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get multiple values at once
+   *
+   * @async
+   * @method mget
+   * @param {string[]} keys - Array of cache keys
+   * @returns {Promise<Object>} Key-value object with found values
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * const result = await cache.mget(['user:1', 'user:2', 'user:3']);
+   * // Returns: { 'user:1': {...}, 'user:2': {...} }
+   * // Missing keys are not included in result
+   */
+  async mget(keys) {
+    try {
+      const fullKeys = keys.map(k => this.buildKey(k));
+      const values = await this.client.mget(...fullKeys);
+
+      const result = {};
+      keys.forEach((key, index) => {
+        if (values[index] !== null) {
+          try {
+            result[key] = JSON.parse(values[index]);
+            this.stats.hits++;
+          } catch {
+            result[key] = values[index];
+            this.stats.hits++;
+          }
+        } else {
+          this.stats.misses++;
+        }
+      });
+
+      return result;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Multi-get failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Set multiple values at once
+   *
+   * @async
+   * @method mset
+   * @param {Object} keyValues - Key-value pairs to set
+   * @param {number} [ttl] - TTL in seconds for all keys
+   * @returns {Promise<boolean>} Returns true on success
+   *
+   * @throws {Error} Throws error if Redis operation fails
+   *
+   * @example
+   * await cache.mset({
+   *   'user:1': { name: 'Alice' },
+   *   'user:2': { name: 'Bob' },
+   *   'user:3': { name: 'Charlie' }
+   * }, 3600);
+   */
+  async mset(keyValues, ttl) {
+    try {
+      const pipeline = this.client.pipeline();
+
+      for (const [key, value] of Object.entries(keyValues)) {
+        const fullKey = this.buildKey(key);
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+        const expiry = ttl || this.config.defaultTTL;
+
+        if (expiry > 0) {
+          pipeline.setex(fullKey, expiry, serialized);
+        } else {
+          pipeline.set(fullKey, serialized);
+        }
+
+        this.stats.sets++;
+      }
+
+      await pipeline.exec();
+      return true;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Multi-set failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Flush all cache keys (dangerous!)
+   *
+   * @async
+   * @method flush
+   * @param {boolean} [confirm=false] - Must be true to execute
+   * @returns {Promise<boolean>} Returns true on success
+   *
+   * @throws {Error} If confirmation not provided or flush fails
+   *
+   * @warning This will delete ALL cache keys with the configured prefix
+   *
+   * @example
+   * // Safety check required
+   * await cache.flush(true);
+   * console.log('All cache cleared');
+   */
+  async flush(confirm = false) {
+    if (!confirm) {
+      throw new Error('Flush requires confirmation parameter to be true');
+    }
+
+    try {
+      // Only flush keys with our prefix
+      const keys = await this.client.keys(`${this.config.keyPrefix}*`);
+
+      if (keys.length > 0) {
+        const cleanKeys = keys.map(k => k.replace(this.config.keyPrefix, ''));
+        await this.client.del(...cleanKeys);
+      }
+
+      return true;
+    } catch (error) {
+      this.stats.errors++;
+      throw new Error(`Flush failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get cache statistics
+   *
+   * @method getStats
+   * @returns {CacheStats} Current statistics
+   * @returns {number} stats.hits - Number of cache hits
+   * @returns {number} stats.misses - Number of cache misses
+   * @returns {number} stats.sets - Number of set operations
+   * @returns {number} stats.deletes - Number of delete operations
+   * @returns {number} stats.errors - Number of errors
+   * @returns {string} stats.hitRate - Hit rate percentage
+   *
+   * @example
+   * const stats = cache.getStats();
+   * console.log(`Hit rate: ${stats.hitRate}`);
+   * console.log(`Total operations: ${stats.hits + stats.misses}`);
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      hitRate: this.stats.hits + this.stats.misses > 0
+        ? (this.stats.hits / (this.stats.hits + this.stats.misses) * 100).toFixed(2) + '%'
+        : '0%'
+    };
+  }
+
+  /**
+   * Reset statistics counters
+   *
+   * @method resetStats
+   * @returns {void}
+   *
+   * @example
+   * cache.resetStats();
+   * // All counters set to 0
+   */
+  resetStats() {
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      deletes: 0,
+      errors: 0
+    };
+  }
+
+  /**
+   * Creates a new CacheConnector instance with additional namespace
+   *
+   * @method withNamespace
+   * @param {string} namespace - Additional namespace to append
+   * @returns {CacheConnector} New instance with combined namespace
+   *
+   * @example
+   * const baseCache = new CacheConnector({ namespace: 'app' });
+   * const userCache = baseCache.withNamespace('users');
+   * const sessionCache = baseCache.withNamespace('sessions');
+   *
+   * // userCache keys: cache:app:users:*
+   * // sessionCache keys: cache:app:sessions:*
+   */
+  withNamespace(namespace) {
+    return new CacheConnector({
+      ...this.config,
+      namespace: this.namespace ? `${this.namespace}:${namespace}` : namespace
+    });
+  }
+
+  /**
+   * Wraps a function with caching (memoization)
+   *
+   * @method wrap
+   * @param {Function} fn - Async function to wrap
+   * @param {Object} [options={}] - Wrapping options
+   * @param {number} [options.ttl] - Cache TTL in seconds
+   * @param {string} [options.keyPrefix] - Prefix for cache keys
+   * @param {Function} [options.keyGenerator] - Custom key generation function
+   * @returns {Function} Wrapped function with caching
+   *
+   * @example <caption>Basic Function Wrapping</caption>
+   * const expensiveOperation = async (userId) => {
+   *   // Complex database query
+   *   return await db.query('SELECT * FROM users WHERE id = ?', [userId]);
+   * };
+   *
+   * const cachedOperation = cache.wrap(expensiveOperation, {
+   *   ttl: 600,
+   *   keyPrefix: 'expensive-op'
+   * });
+   *
+   * // First call hits database
+   * const result1 = await cachedOperation(123);
+   *
+   * // Second call returns from cache
+   * const result2 = await cachedOperation(123);
+   *
+   * @example <caption>Custom Key Generation</caption>
+   * const searchUsers = cache.wrap(async (filters) => {
+   *   return await db.searchUsers(filters);
+   * }, {
+   *   ttl: 300,
+   *   keyGenerator: (filters) => `search:${JSON.stringify(filters)}`
+   * });
+   */
+  wrap(fn, options = {}) {
+    const ttl = options.ttl || this.config.defaultTTL;
+    const keyPrefix = options.keyPrefix || fn.name || 'wrapped';
+    const keyGenerator = options.keyGenerator || ((...args) => {
+      const hash = crypto.createHash('sha256');
+      hash.update(JSON.stringify(args));
+      return `${keyPrefix}:${hash.digest('hex')}`;
+    });
+
+    return async (...args) => {
+      const key = keyGenerator(...args);
+
+      // Try to get from cache
+      const cached = await this.get(key);
+      if (cached !== null) {
+        return cached;
+      }
+
+      // Execute function
+      const result = await fn(...args);
+
+      // Cache result
+      await this.set(key, result, ttl);
+
+      return result;
+    };
+  }
+
+  /**
+   * Perform health check on Redis connection
+   *
+   * @async
+   * @method healthCheck
+   * @returns {Promise<boolean>} Returns true if healthy
+   *
+   * @example
+   * if (await cache.healthCheck()) {
+   *   console.log('Redis is healthy');
+   * } else {
+   *   console.error('Redis is down');
+   * }
+   */
+  async healthCheck() {
+    try {
+      await this.client.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * @typedef {Object} CacheConfig
+ * @property {string} [host='localhost'] - Redis host
+ * @property {number} [port=6379] - Redis port
+ * @property {string} [password] - Redis password
+ * @property {number} [db=0] - Redis database
+ * @property {number} [defaultTTL=3600] - Default TTL in seconds
+ * @property {string} [namespace=''] - Key namespace
+ * @property {number} [maxRetries=3] - Max connection retries
+ * @property {number} [retryDelay=100] - Retry delay in ms
+ * @property {boolean} [enableOfflineQueue=true] - Queue commands when disconnected
+ * @property {boolean} [lazyConnect=false] - Delay connection
+ */
+
+/**
+ * @typedef {Object} CacheStats
+ * @property {number} hits - Number of cache hits
+ * @property {number} misses - Number of cache misses
+ * @property {number} sets - Number of set operations
+ * @property {number} deletes - Number of delete operations
+ * @property {number} errors - Number of errors
+ * @property {string} hitRate - Hit rate percentage
+ */
+
+/**
+ * Connection established event
+ *
+ * @event CacheConnector#connect
+ * @type {void}
+ */
+
+/**
+ * Error event
+ *
+ * @event CacheConnector#error
+ * @type {Error}
+ */
+
+/**
+ * Connection closed event
+ *
+ * @event CacheConnector#close
+ * @type {void}
+ */
+
+// Export main class
+module.exports = CacheConnector;
+
+/**
+ * Factory function to create cache instance
+ *
+ * @function create
+ * @param {CacheConfig} config - Configuration object
+ * @returns {CacheConnector} New cache connector instance
+ *
+ * @example
+ * const cache = CacheConnector.create({
+ *   host: 'localhost',
+ *   namespace: 'my-service'
+ * });
+ */
+module.exports.create = (config) => new CacheConnector(config);
+
+/**
+ * Current version
+ * @constant {string}
+ */
+module.exports.VERSION = '1.0.0';
+
+// Export mock for testing
+module.exports.MockCacheConnector = class MockCacheConnector {
+  constructor() {
+    this.cache = new Map();
+    this.stats = { hits: 0, misses: 0, sets: 0, deletes: 0, errors: 0 };
+  }
+
+  async connect() { return true; }
+  async disconnect() { return true; }
+
+  async get(key) {
+    if (this.cache.has(key)) {
+      this.stats.hits++;
+      return this.cache.get(key);
+    }
+    this.stats.misses++;
+    return null;
+  }
+
+  async set(key, value, ttl) {
+    this.cache.set(key, value);
+    this.stats.sets++;
+    // Simulate TTL
+    if (ttl > 0) {
+      setTimeout(() => this.cache.delete(key), ttl * 1000);
+    }
+    return true;
+  }
+
+  async delete(key) {
+    this.stats.deletes++;
+    return this.cache.delete(key);
+  }
+
+  async flush() {
+    this.cache.clear();
+    return true;
+  }
+
+  getStats() { return this.stats; }
+  resetStats() {
+    this.stats = { hits: 0, misses: 0, sets: 0, deletes: 0, errors: 0 };
+  }
+};