@onlineapps/conn-base-cache 1.0.1 → 1.0.3

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@onlineapps/conn-base-cache",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Redis cache connector with TTL, invalidation, and namespace support for OA Drive microservices",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
-    "test:unit": "jest test/unit",
-    "test:integration": "jest test/integration",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration",
     "test:watch": "jest --watch",
     "docs": "jsdoc2md --files src/**/*.js > API.md"
   },
@@ -20,6 +20,7 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
+    "@onlineapps/runtime-config": "1.0.1",
     "ioredis": "^5.3.2"
   },
   "devDependencies": {

package/src/config.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Runtime configuration schema for @onlineapps/conn-base-cache.
+ *
+ * Uses @onlineapps/runtime-config for unified priority:
+ * 1. Explicit config (passed to constructor)
+ * 2. Environment variable
+ * 3. Owner defaults (from ./defaults.js)
+ *
+ * @module @onlineapps/conn-base-cache/config
+ */
+
+const { createRuntimeConfig } = require('@onlineapps/runtime-config');
+const DEFAULTS = require('./defaults');
+
+/**
+ * Runtime config schema for CacheConnector
+ *
+ * Schema defines:
+ * - env: Environment variable name
+ * - defaultKey: Key in DEFAULTS object
+ * - type: Value type for coercion
+ * - required: Fail-fast if missing (for infra topology)
+ */
+const runtimeCfg = createRuntimeConfig({
+  defaults: DEFAULTS,
+  schema: {
+    // Connection settings (dev-friendly defaults, ENV override)
+    host: { env: 'REDIS_HOST', defaultKey: 'defaultHost' },
+    port: { env: 'REDIS_PORT', defaultKey: 'defaultPort', type: 'number' },
+    password: { env: 'REDIS_PASSWORD' },
+    db: { env: 'REDIS_DB', defaultKey: 'defaultDb', type: 'number' },
+
+    // Cache behavior (module-owned defaults)
+    keyPrefix: { defaultKey: 'keyPrefix' },
+    defaultTTL: { env: 'CACHE_TTL', defaultKey: 'defaultTTLSeconds', type: 'number' },
+    maxRetries: { defaultKey: 'maxRetries', type: 'number' },
+    retryDelay: { defaultKey: 'retryDelayMs', type: 'number' },
+
+    // Connection behavior (module-owned defaults)
+    connectWaitTimeoutMs: { defaultKey: 'connectWaitTimeoutMs', type: 'number' },
+    connectWaitPollIntervalMs: { defaultKey: 'connectWaitPollIntervalMs', type: 'number' },
+  }
+});
+
+module.exports = runtimeCfg;
+

package/src/defaults.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Module-owned defaults for @onlineapps/conn-base-cache.
+ *
+ * Ownership rule:
+ * - Defaults that belong to this cache connector live here (host/port for dev/test, TTL, retry policy, key prefix, db).
+ * - Callers can override via explicit config or environment variables.
+ */
+
+module.exports = {
+  defaultHost: 'localhost',
+  defaultPort: 6379,
+  keyPrefix: 'cache:',
+  defaultDb: 0,
+  defaultTTLSeconds: 3600,
+  maxRetries: 3,
+  retryDelayMs: 100,
+  connectWaitTimeoutMs: 5000,
+  connectWaitPollIntervalMs: 100,
+};
+
+

package/src/index.js

@@ -15,6 +15,7 @@
 
 const Redis = require('ioredis');
 const crypto = require('crypto');
+const runtimeCfg = require('./config');
 
 /**
  * Redis cache connector providing caching operations with automatic key management
@@ -68,16 +69,25 @@ class CacheConnector {
    * });
    */
   constructor(config = {}) {
-    // Configuration
+    if (config === null || config === undefined) {
+      config = {};
+    }
+
+    // Resolve runtime configuration using unified priority: explicit config → ENV → owner defaults
+    const resolved = runtimeCfg.resolve(config);
+
+    // Configuration (resolved values + non-schema options from config)
     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,
+      host: resolved.host,
+      port: resolved.port,
+      password: resolved.password,
+      db: resolved.db,
+      keyPrefix: resolved.keyPrefix,
+      defaultTTL: resolved.defaultTTL,
+      maxRetries: resolved.maxRetries,
+      retryDelay: resolved.retryDelay,
+      connectWaitTimeoutMs: resolved.connectWaitTimeoutMs,
+      connectWaitPollIntervalMs: resolved.connectWaitPollIntervalMs,
       enableOfflineQueue: config.enableOfflineQueue !== false,
       lazyConnect: config.lazyConnect || false
     };
@@ -151,13 +161,13 @@ class CacheConnector {
             clearInterval(checkInterval);
             reject(new Error('Connection attempt failed'));
           }
-        }, 100);
+        }, this.config.connectWaitPollIntervalMs);
 
-        // Timeout after 5 seconds
+        // Timeout after fixed max wait
         setTimeout(() => {
           clearInterval(checkInterval);
           reject(new Error('Connection timeout'));
-        }, 5000);
+        }, this.config.connectWaitTimeoutMs);
       });
     }
 
@@ -311,20 +321,19 @@ class CacheConnector {
    * @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);
+   * @example <caption>Set with Default TTL (ttl omitted / invalid)</caption>
+   * await cache.set('session:abc', sessionData, 0); // uses defaultTTL
    */
   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;
+      const expiry =
+        typeof ttl === 'number' && Number.isFinite(ttl) && ttl > 0
+          ? ttl
+          : this.config.defaultTTL;
 
-      if (expiry > 0) {
-        await this.client.setex(fullKey, expiry, serialized);
-      } else {
-        await this.client.set(fullKey, serialized);
-      }
+      await this.client.setex(fullKey, expiry, serialized);
 
       this.stats.sets++;
       return true;
@@ -363,6 +372,33 @@ class CacheConnector {
     }
   }
 
+  /**
+   * Redis DEL alias.
+   *
+   * NOTE:
+   * - Returns the raw count of deleted keys (Redis semantics).
+   * - This is a convenience for batch deletes; prefer `delete()` when you need boolean.
+   *
+   * @param {string|string[]} keys
+   * @returns {Promise<number>}
+   */
+  async del(keys) {
+    const list = Array.isArray(keys) ? keys : [keys];
+    if (list.length === 0) return 0;
+    const fullKeys = list.map((k) => this.buildKey(k));
+    const result = await this.client.del(...fullKeys);
+    this.stats.deletes++;
+    return result;
+  }
+
+  /**
+   * Connection helper for convenience/testing.
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this.connected === true;
+  }
+
   /**
    * Deletes keys matching a pattern
    *
@@ -403,6 +439,15 @@ class CacheConnector {
     }
   }
 
+  /**
+   * Clear all keys in the current namespace (or all keys when namespace is empty).
+   *
+   * @returns {Promise<number>} Number of deleted keys
+   */
+  async clear() {
+    return await this.deleteByPattern('*');
+  }
+
   /**
    * Check if key exists in cache
    *

package/{test → tests}/component/cache.component.test.js

@@ -109,7 +109,7 @@ class RedisSimulator {
   }
 }
 
-describe('CacheConnector - Component Tests', () => {
+describe('CacheConnector - Component Tests @component', () => {
   let cacheConnector;
   let redisSimulator;
 

package/{test → tests}/integration/cache.integration.test.js

@@ -11,7 +11,7 @@ const SKIP_INTEGRATION = process.env.SKIP_INTEGRATION === 'true';
 const REDIS_HOST = process.env.REDIS_HOST || 'localhost';
 const REDIS_PORT = process.env.REDIS_PORT || 6379;
 
-describe('CacheConnector - Integration Tests', () => {
+describe('CacheConnector - Integration Tests @integration', () => {
   if (SKIP_INTEGRATION) {
     it.skip('Skipping integration tests (SKIP_INTEGRATION=true)', () => {});
     return;
@@ -59,7 +59,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('Redis Connection', () => {
     it('should connect to Redis successfully', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -71,7 +70,6 @@ describe('CacheConnector - Integration Tests', () => {
 
     it('should handle reconnection', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -86,7 +84,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('Real-world Caching Scenarios', () => {
     it('should cache API response data', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -108,7 +105,6 @@ describe('CacheConnector - Integration Tests', () => {
 
     it('should handle high-volume operations', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -140,7 +136,6 @@ describe('CacheConnector - Integration Tests', () => {
 
     it('should handle concurrent access correctly', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -168,7 +163,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('TTL and Expiration', () => {
     it('should respect TTL on real Redis', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -192,7 +186,6 @@ describe('CacheConnector - Integration Tests', () => {
 
     it('should update TTL on existing keys', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -210,7 +203,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('Namespace Isolation', () => {
     it('should isolate data between different namespaces', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -247,7 +239,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('Error Recovery', () => {
     it('should handle temporary network issues', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -280,7 +271,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('Large Data Handling', () => {
     it('should handle large JSON objects', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -306,7 +296,6 @@ describe('CacheConnector - Integration Tests', () => {
 
     it('should handle binary data (base64 encoded)', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -326,7 +315,6 @@ describe('CacheConnector - Integration Tests', () => {
   describe('Performance Monitoring', () => {
     it('should accurately track statistics', async () => {
       if (!cacheConnector) {
-        pending('Redis not available');
         return;
       }
 
@@ -349,8 +337,9 @@ describe('CacheConnector - Integration Tests', () => {
       expect(stats.hits).toBe(2);
       expect(stats.misses).toBe(2);
       expect(stats.deletes).toBe(2); // del operations, not key count
-      expect(stats.hitRate).toBe(0.5);
-      expect(stats.totalOperations).toBe(9);
+      expect(stats.hitRate).toBe('50.00%');
+      // Total operations can be derived from counters
+      expect(stats.hits + stats.misses + stats.sets + stats.deletes + stats.errors).toBe(9);
     });
   });
 });

package/{test → tests}/unit/CacheConnector.edge.test.js

@@ -9,7 +9,7 @@ jest.mock('ioredis');
 const Redis = require('ioredis');
 const CacheConnector = require('../../src/index');
 
-describe('CacheConnector - Edge Cases & Full Coverage', () => {
+describe('CacheConnector - Edge Cases & Full Coverage @unit', () => {
   let cacheConnector;
   let mockRedisClient;
 
@@ -62,9 +62,9 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
       const cache = new CacheConnector();
 
       expect(cache.config.host).toBe('env-host');
-      expect(cache.config.port).toBe('6380');
+      expect(cache.config.port).toBe(6380);
       expect(cache.config.password).toBe('secret');
-      expect(cache.config.db).toBe('2');
+      expect(cache.config.db).toBe(2);
 
       // Cleanup
       delete process.env.REDIS_HOST;
@@ -87,7 +87,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
   describe('Connection Edge Cases', () => {
     beforeEach(() => {
-      cacheConnector = new CacheConnector();
+      cacheConnector = new CacheConnector({ host: 'localhost', port: 6379 });
     });
 
     it('should handle connection timeout', async () => {
@@ -138,7 +138,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
   describe('Data Type Edge Cases', () => {
     beforeEach(async () => {
-      cacheConnector = new CacheConnector();
+      cacheConnector = new CacheConnector({ host: 'localhost', port: 6379 });
       await cacheConnector.connect();
     });
 
@@ -314,7 +314,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
     it('should handle empty array in mget', async () => {
       const result = await cacheConnector.mget([]);
-      expect(result).toEqual([]);
+      expect(result).toEqual({});
     });
 
     it('should handle null responses in mget', async () => {
@@ -326,7 +326,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
       const result = await cacheConnector.mget(['key1', 'key2', 'key3']);
 
-      expect(result).toEqual(['value1', null, 'value3']);
+      expect(result).toEqual({ key1: 'value1', key3: 'value3' });
     });
   });
 
@@ -375,8 +375,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
         sets: 0,
         deletes: 0,
         errors: 0,
-        hitRate: 0,
-        totalOperations: 0
+        hitRate: '0%'
       });
     });
 
@@ -385,7 +384,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
       const stats = cacheConnector.getStats();
 
-      expect(stats.hitRate).toBe(0);
+      expect(stats.hitRate).toBe('0.00%');
     });
 
     it('should handle hitRate with only hits', () => {
@@ -393,7 +392,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
       const stats = cacheConnector.getStats();
 
-      expect(stats.hitRate).toBe(1);
+      expect(stats.hitRate).toBe('100.00%');
     });
 
     it('should handle integer overflow in stats', () => {
@@ -407,8 +406,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
 
       const stats = cacheConnector.getStats();
 
-      expect(stats.totalOperations).toBeDefined();
-      expect(stats.hitRate).toBe(0.5);
+      expect(stats.hitRate).toBe('50.00%');
     });
   });
 
@@ -458,7 +456,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
         expect.stringContaining('key'),
         300
       );
-      expect(result).toBe(1);
+      expect(result).toBe(true);
     });
 
     it('should have working resetStats method', () => {
@@ -505,7 +503,7 @@ describe('CacheConnector - Edge Cases & Full Coverage', () => {
       const results = await Promise.all(operations);
 
       expect(results).toHaveLength(100);
-      expect(results.every(r => r === 'OK')).toBe(true);
+      expect(results.every(r => r === true)).toBe(true);
       expect(cacheConnector.stats.sets).toBe(100);
     });
 

package/{test → tests}/unit/CacheConnector.test.js

@@ -9,7 +9,7 @@ jest.mock('ioredis');
 const Redis = require('ioredis');
 const CacheConnector = require('../../src/index');
 
-describe('CacheConnector - Unit Tests', () => {
+describe('CacheConnector - Unit Tests @unit', () => {
   let cacheConnector;
   let mockRedisClient;
 
@@ -77,7 +77,7 @@ describe('CacheConnector - Unit Tests', () => {
       const cache = new CacheConnector();
 
       expect(cache.config.host).toBe('env-redis');
-      expect(cache.config.port).toBe('6381');
+      expect(cache.config.port).toBe(6381);
 
       delete process.env.REDIS_HOST;
       delete process.env.REDIS_PORT;
@@ -98,6 +98,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('connect', () => {
     beforeEach(() => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
     });
@@ -144,6 +146,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('disconnect', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -170,6 +174,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('get', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -225,6 +231,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('set', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service',
         defaultTTL: 3600
       });
@@ -292,6 +300,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('delete', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -327,6 +337,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('deleteByPattern', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -370,6 +382,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('exists', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -403,6 +417,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('ttl', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -444,6 +460,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('expire', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -477,6 +495,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('incr/decr', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -616,6 +636,8 @@ describe('CacheConnector - Unit Tests', () => {
   describe('flush', () => {
     beforeEach(async () => {
       cacheConnector = new CacheConnector({
+        host: 'localhost',
+        port: 6379,
         namespace: 'test-service'
       });
       await cacheConnector.connect();
@@ -719,7 +741,7 @@ describe('CacheConnector - Unit Tests', () => {
 
   describe('healthCheck', () => {
     beforeEach(async () => {
-      cacheConnector = new CacheConnector();
+      cacheConnector = new CacheConnector({ host: 'localhost', port: 6379 });
       await cacheConnector.connect();
     });
 
@@ -761,7 +783,7 @@ describe('CacheConnector - Unit Tests', () => {
 
   describe('withNamespace', () => {
     it('should create new instance with combined namespace', async () => {
-      const cache1 = new CacheConnector({ namespace: 'service1' });
+      const cache1 = new CacheConnector({ host: 'localhost', port: 6379, namespace: 'service1' });
       const cache2 = cache1.withNamespace('subsection');
 
       expect(cache2).toBeInstanceOf(CacheConnector);
@@ -773,7 +795,7 @@ describe('CacheConnector - Unit Tests', () => {
 
   describe('wrap function', () => {
     beforeEach(async () => {
-      cacheConnector = new CacheConnector({ namespace: 'test' });
+      cacheConnector = new CacheConnector({ host: 'localhost', port: 6379, namespace: 'test' });
       await cacheConnector.connect();
     });