@onlineapps/conn-base-cache 1.0.0

package/README.md

@@ -0,0 +1,383 @@
+# @onlineapps/conn-base-cache
+
+Redis cache connector with TTL, invalidation, and namespace support for OA Drive microservices.
+
+## Features
+
+- 🔑 **Automatic key prefixing** - All keys use `cache:` prefix
+- ⏱️ **TTL support** - Automatic expiration for cached data
+- 🗂️ **Namespace isolation** - Separate cache spaces per service
+- 📊 **Built-in statistics** - Hit rate, miss tracking
+- 🔄 **Atomic operations** - Increment, decrement support
+- 🎯 **Pattern invalidation** - Delete by wildcard patterns
+- 🔐 **Safe namespacing** - Never touches `obs:` monitoring keys
+- 🧪 **Mock implementation** - For testing
+
+## Installation
+
+```bash
+npm install @onlineapps/conn-base-cache
+```
+
+## Quick Start
+
+```javascript
+const CacheConnector = require('@onlineapps/conn-base-cache');
+
+const cache = new CacheConnector({
+  host: 'localhost',
+  port: 6379,
+  defaultTTL: 3600, // 1 hour
+  namespace: 'invoice-service'
+});
+
+await cache.connect();
+
+// Set value with TTL
+await cache.set('user:123', { name: 'John', role: 'admin' }, 600); // 10 min
+
+// Get value
+const user = await cache.get('user:123');
+
+// Delete by pattern
+await cache.deleteByPattern('user:*');
+
+// Get statistics
+console.log(cache.getStats());
+// { hits: 1, misses: 0, sets: 1, deletes: 5, errors: 0, hitRate: '100%' }
+```
+
+## Configuration
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `host` | `REDIS_HOST` | `localhost` | Redis server host |
+| `port` | `REDIS_PORT` | `6379` | Redis server port |
+| `password` | `REDIS_PASSWORD` | - | Redis password |
+| `db` | `REDIS_DB` | `0` | Redis database number |
+| `defaultTTL` | - | `3600` | Default TTL in seconds |
+| `namespace` | - | - | Key namespace |
+| `maxRetries` | - | `3` | Max connection retries |
+| `retryDelay` | - | `100` | Retry delay in ms |
+
+## API Reference
+
+### Connection Management
+
+#### `connect()`
+Establish Redis connection.
+
+```javascript
+await cache.connect();
+```
+
+#### `disconnect()`
+Close Redis connection.
+
+```javascript
+await cache.disconnect();
+```
+
+### Basic Operations
+
+#### `get(key)`
+Get value from cache.
+
+```javascript
+const value = await cache.get('key');
+// Returns parsed object or string
+```
+
+#### `set(key, value, ttl?)`
+Set value in cache with optional TTL.
+
+```javascript
+await cache.set('key', { data: 'value' }, 3600);
+// Returns true on success
+```
+
+#### `delete(key)`
+Delete single key.
+
+```javascript
+await cache.delete('key');
+// Returns true if key existed
+```
+
+#### `exists(key)`
+Check if key exists.
+
+```javascript
+const exists = await cache.exists('key');
+// Returns boolean
+```
+
+### Pattern Operations
+
+#### `deleteByPattern(pattern)`
+Delete all keys matching pattern.
+
+```javascript
+const deleted = await cache.deleteByPattern('session:*');
+// Returns number of deleted keys
+```
+
+### TTL Management
+
+#### `ttl(key)`
+Get remaining TTL for key.
+
+```javascript
+const seconds = await cache.ttl('key');
+// Returns: seconds (-1 if no TTL, -2 if not exists)
+```
+
+#### `expire(key, ttl)`
+Update TTL for existing key.
+
+```javascript
+await cache.expire('key', 7200); // 2 hours
+// Returns true on success
+```
+
+### Atomic Operations
+
+#### `incr(key, increment?)`
+Increment numeric value.
+
+```javascript
+const newValue = await cache.incr('counter', 5);
+// Returns new value
+```
+
+#### `decr(key, decrement?)`
+Decrement numeric value.
+
+```javascript
+const newValue = await cache.decr('counter', 1);
+// Returns new value
+```
+
+### Batch Operations
+
+#### `mget(keys)`
+Get multiple values at once.
+
+```javascript
+const values = await cache.mget(['key1', 'key2', 'key3']);
+// Returns: { key1: value1, key2: value2, key3: value3 }
+```
+
+#### `mset(keyValues, ttl?)`
+Set multiple values at once.
+
+```javascript
+await cache.mset({
+  'key1': 'value1',
+  'key2': { data: 'value2' }
+}, 3600);
+// Returns true on success
+```
+
+### Utility Methods
+
+#### `withNamespace(namespace)`
+Create namespaced instance.
+
+```javascript
+const userCache = cache.withNamespace('users');
+await userCache.set('123', userData);
+// Actual key: cache:invoice-service:users:123
+```
+
+#### `wrap(fn, options)`
+Create cached function (memoization).
+
+```javascript
+const cachedFetch = cache.wrap(async (userId) => {
+  return await fetchUserFromDB(userId);
+}, {
+  ttl: 600,
+  keyPrefix: 'user'
+});
+
+const user = await cachedFetch(123);
+// First call fetches from DB and caches
+// Subsequent calls return from cache
+```
+
+#### `flush(confirm)`
+Clear all cache keys (dangerous!).
+
+```javascript
+await cache.flush(true); // Must confirm with true
+```
+
+#### `getStats()`
+Get cache statistics.
+
+```javascript
+const stats = cache.getStats();
+// { hits: 50, misses: 10, sets: 30, deletes: 5, errors: 0, hitRate: '83.33%' }
+```
+
+#### `healthCheck()`
+Check Redis connection health.
+
+```javascript
+const healthy = await cache.healthCheck();
+// Returns boolean
+```
+
+## Usage Patterns
+
+### Service-Level Caching
+
+```javascript
+class InvoiceService {
+  constructor() {
+    this.cache = new CacheConnector({
+      namespace: 'invoice-service'
+    });
+  }
+
+  async getInvoice(id) {
+    // Check cache first
+    const cached = await this.cache.get(`invoice:${id}`);
+    if (cached) return cached;
+
+    // Fetch from database
+    const invoice = await db.getInvoice(id);
+
+    // Cache for 1 hour
+    await this.cache.set(`invoice:${id}`, invoice, 3600);
+
+    return invoice;
+  }
+
+  async invalidateInvoice(id) {
+    await this.cache.delete(`invoice:${id}`);
+  }
+}
+```
+
+### API Response Caching
+
+```javascript
+// In service wrapper
+async function callApiWithCache(operation, params) {
+  const cacheKey = `api:${operation}:${JSON.stringify(params)}`;
+
+  // Try cache
+  const cached = await cache.get(cacheKey);
+  if (cached) {
+    logger.debug('Cache hit for API call');
+    return cached;
+  }
+
+  // Make API call
+  const result = await apiCaller.call(operation, params);
+
+  // Cache result
+  await cache.set(cacheKey, result, 300); // 5 minutes
+
+  return result;
+}
+```
+
+### Session Management
+
+```javascript
+const sessionCache = cache.withNamespace('sessions');
+
+// Store session
+await sessionCache.set(sessionId, {
+  userId: 123,
+  roles: ['admin'],
+  createdAt: Date.now()
+}, 1800); // 30 minutes
+
+// Refresh session TTL
+await sessionCache.expire(sessionId, 1800);
+
+// Clear all sessions for user
+await sessionCache.deleteByPattern(`*:user:123`);
+```
+
+## Testing
+
+Use the built-in mock for testing:
+
+```javascript
+const { MockCacheConnector } = require('@onlineapps/conn-base-cache');
+
+describe('MyService', () => {
+  let cache;
+
+  beforeEach(() => {
+    cache = new MockCacheConnector();
+  });
+
+  it('should cache results', async () => {
+    await cache.set('test', 'value');
+    const value = await cache.get('test');
+    expect(value).toBe('value');
+    expect(cache.getStats().hits).toBe(1);
+  });
+});
+```
+
+## Important Notes
+
+1. **Key Prefixing**: All keys automatically get `cache:` prefix
+2. **Namespace Isolation**: Use namespaces to avoid key collisions
+3. **TTL Best Practices**: Always set appropriate TTL to prevent memory issues
+4. **Pattern Deletion**: Use carefully as it can be expensive on large datasets
+5. **Never Access**: This connector never touches `obs:` namespace (monitoring)
+
+## Integration with Service Wrapper
+
+```javascript
+class ServiceWrapper {
+  constructor(config) {
+    this.cache = new CacheConnector({
+      namespace: config.serviceName
+    });
+  }
+
+  async processWorkflow(message) {
+    // Cache workflow state
+    await this.cache.set(
+      `workflow:${message.workflowId}`,
+      message,
+      600 // 10 minutes
+    );
+  }
+}
+```
+
+## Error Handling
+
+All methods throw errors with descriptive messages:
+
+```javascript
+try {
+  await cache.get('key');
+} catch (error) {
+  if (error.message.includes('Cache get failed')) {
+    // Handle cache failure
+  }
+}
+```
+
+## Performance Tips
+
+1. **Use mget/mset** for batch operations
+2. **Enable pipelining** for multiple operations
+3. **Set appropriate TTL** to balance freshness and performance
+4. **Use namespaces** to organize keys
+5. **Monitor hit rate** with getStats()
+
+## License
+
+MIT

package/coverage/clover.xml

@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<coverage generated="1758821391698" clover="3.2.0">
+  <project timestamp="1758821391699" name="All files">
+    <metrics statements="196" coveredstatements="164" conditionals="81" coveredconditionals="69" methods="42" coveredmethods="28" elements="319" coveredelements="261" complexity="0" loc="196" ncloc="196" packages="1" files="1" classes="1"/>
+    <file name="index.js" path="/var/www/html/oa_drive/shared/connector/conn-base-cache/src/index.js">
+      <metrics statements="196" coveredstatements="164" conditionals="81" coveredconditionals="69" methods="42" coveredmethods="28"/>
+      <line num="16" count="2" type="stmt"/>
+      <line num="17" count="2" type="stmt"/>
+      <line num="72" count="79" type="stmt"/>
+      <line num="86" count="79" type="cond" truecount="2" falsecount="0"/>
+      <line num="89" count="79" type="stmt"/>
+      <line num="92" count="79" type="stmt"/>
+      <line num="93" count="79" type="stmt"/>
+      <line num="96" count="79" type="stmt"/>
+      <line num="138" count="54" type="cond" truecount="4" falsecount="0"/>
+      <line num="139" count="1" type="stmt"/>
+      <line num="142" count="53" type="stmt"/>
+      <line num="144" count="53" type="stmt"/>
+      <line num="145" count="53" type="stmt"/>
+      <line num="152" count="0" type="cond" truecount="0" falsecount="2"/>
+      <line num="153" count="0" type="stmt"/>
+      <line num="155" count="0" type="stmt"/>
+      <line num="162" count="53" type="stmt"/>
+      <line num="163" count="0" type="stmt"/>
+      <line num="164" count="0" type="stmt"/>
+      <line num="165" count="0" type="stmt"/>
+      <line num="168" count="53" type="stmt"/>
+      <line num="169" count="0" type="stmt"/>
+      <line num="170" count="0" type="stmt"/>
+      <line num="173" count="53" type="stmt"/>
+      <line num="174" count="0" type="stmt"/>
+      <line num="175" count="0" type="stmt"/>
+      <line num="179" count="53" type="cond" truecount="1" falsecount="1"/>
+      <line num="180" count="53" type="stmt"/>
+      <line num="183" count="52" type="stmt"/>
+      <line num="184" count="52" type="stmt"/>
+      <line num="186" count="52" type="stmt"/>
+      <line num="188" count="1" type="stmt"/>
+      <line num="189" count="1" type="stmt"/>
+      <line num="205" count="15" type="cond" truecount="2" falsecount="0"/>
+      <line num="206" count="14" type="stmt"/>
+      <line num="207" count="14" type="stmt"/>
+      <line num="208" count="14" type="stmt"/>
+      <line num="217" count="98" type="cond" truecount="2" falsecount="0"/>
+      <line num="218" count="97" type="stmt"/>
+      <line num="220" count="1" type="stmt"/>
+      <line num="250" count="31" type="stmt"/>
+      <line num="251" count="31" type="stmt"/>
+      <line num="252" count="31" type="stmt"/>
+      <line num="254" count="29" type="cond" truecount="2" falsecount="0"/>
+      <line num="255" count="9" type="stmt"/>
+      <line num="256" count="9" type="stmt"/>
+      <line num="259" count="20" type="stmt"/>
+      <line num="262" count="20" type="stmt"/>
+      <line num="263" count="20" type="stmt"/>
+      <line num="266" count="11" type="stmt"/>
+      <line num="269" count="2" type="stmt"/>
+      <line num="270" count="2" type="stmt"/>
+      <line num="296" count="29" type="stmt"/>
+      <line num="297" count="29" type="stmt"/>
+      <line num="298" count="29" type="cond" truecount="2" falsecount="0"/>
+      <line num="299" count="28" type="cond" truecount="2" falsecount="0"/>
+      <line num="301" count="28" type="cond" truecount="1" falsecount="1"/>
+      <line num="302" count="28" type="stmt"/>
+      <line num="304" count="0" type="stmt"/>
+      <line num="307" count="26" type="stmt"/>
+      <line num="308" count="26" type="stmt"/>
+      <line num="310" count="3" type="stmt"/>
+      <line num="311" count="3" type="stmt"/>
+      <line num="332" count="8" type="stmt"/>
+      <line num="333" count="8" type="stmt"/>
+      <line num="334" count="8" type="stmt"/>
+      <line num="336" count="7" type="stmt"/>
+      <line num="337" count="7" type="stmt"/>
+      <line num="339" count="1" type="stmt"/>
+      <line num="340" count="1" type="stmt"/>
+      <line num="364" count="3" type="stmt"/>
+      <line num="365" count="3" type="stmt"/>
+      <line num="366" count="3" type="stmt"/>
+      <line num="368" count="2" type="cond" truecount="2" falsecount="0"/>
+      <line num="369" count="1" type="stmt"/>
+      <line num="373" count="2" type="stmt"/>
+      <line num="374" count="1" type="stmt"/>
+      <line num="376" count="1" type="stmt"/>
+      <line num="377" count="1" type="stmt"/>
+      <line num="379" count="1" type="stmt"/>
+      <line num="380" count="1" type="stmt"/>
+      <line num="400" count="3" type="stmt"/>
+      <line num="401" count="3" type="stmt"/>
+      <line num="402" count="3" type="stmt"/>
+      <line num="403" count="2" type="stmt"/>
+      <line num="405" count="1" type="stmt"/>
+      <line num="406" count="1" type="stmt"/>
+      <line num="431" count="4" type="stmt"/>
+      <line num="432" count="4" type="stmt"/>
+      <line num="433" count="4" type="stmt"/>
+      <line num="435" count="1" type="stmt"/>
+      <line num="436" count="1" type="stmt"/>
+      <line num="456" count="3" type="stmt"/>
+      <line num="457" count="3" type="stmt"/>
+      <line num="458" count="3" type="stmt"/>
+      <line num="459" count="2" type="stmt"/>
+      <line num="461" count="1" type="stmt"/>
+      <line num="462" count="1" type="stmt"/>
+      <line num="485" count="4" type="stmt"/>
+      <line num="486" count="4" type="stmt"/>
+      <line num="488" count="4" type="cond" truecount="2" falsecount="0"/>
+      <line num="489" count="3" type="stmt"/>
+      <line num="491" count="1" type="stmt"/>
+      <line num="494" count="1" type="stmt"/>
+      <line num="495" count="1" type="stmt"/>
+      <line num="517" count="3" type="stmt"/>
+      <line num="518" count="3" type="stmt"/>
+      <line num="520" count="3" type="cond" truecount="2" falsecount="0"/>
+      <line num="521" count="2" type="stmt"/>
+      <line num="523" count="1" type="stmt"/>
+      <line num="526" count="1" type="stmt"/>
+      <line num="527" count="1" type="stmt"/>
+      <line num="547" count="3" type="stmt"/>
+      <line num="548" count="7" type="stmt"/>
+      <line num="549" count="3" type="stmt"/>
+      <line num="551" count="2" type="stmt"/>
+      <line num="552" count="2" type="stmt"/>
+      <line num="553" count="6" type="cond" truecount="2" falsecount="0"/>
+      <line num="554" count="4" type="stmt"/>
+      <line num="555" count="4" type="stmt"/>
+      <line num="556" count="2" type="stmt"/>
+      <line num="558" count="2" type="stmt"/>
+      <line num="559" count="2" type="stmt"/>
+      <line num="562" count="2" type="stmt"/>
+      <line num="566" count="2" type="stmt"/>
+      <line num="568" count="1" type="stmt"/>
+      <line num="569" count="1" type="stmt"/>
+      <line num="592" count="2" type="stmt"/>
+      <line num="593" count="2" type="stmt"/>
+      <line num="595" count="2" type="stmt"/>
+      <line num="596" count="3" type="stmt"/>
+      <line num="597" count="3" type="cond" truecount="2" falsecount="0"/>
+      <line num="598" count="3" type="cond" truecount="2" falsecount="0"/>
+      <line num="600" count="3" type="cond" truecount="1" falsecount="1"/>
+      <line num="601" count="3" type="stmt"/>
+      <line num="603" count="0" type="stmt"/>
+      <line num="606" count="3" type="stmt"/>
+      <line num="609" count="2" type="stmt"/>
+      <line num="610" count="1" type="stmt"/>
+      <line num="612" count="1" type="stmt"/>
+      <line num="613" count="1" type="stmt"/>
+      <line num="635" count="4" type="cond" truecount="2" falsecount="0"/>
+      <line num="636" count="2" type="stmt"/>
+      <line num="639" count="2" type="stmt"/>
+      <line num="641" count="2" type="stmt"/>
+      <line num="643" count="1" type="cond" truecount="1" falsecount="1"/>
+      <line num="644" count="2" type="stmt"/>
+      <line num="645" count="1" type="stmt"/>
+      <line num="648" count="1" type="stmt"/>
+      <line num="650" count="1" type="stmt"/>
+      <line num="651" count="1" type="stmt"/>
+      <line num="673" count="5" type="stmt"/>
+      <line num="692" count="2" type="stmt"/>
+      <line num="717" count="1" type="stmt"/>
+      <line num="760" count="2" type="cond" truecount="2" falsecount="0"/>
+      <line num="761" count="2" type="cond" truecount="2" falsecount="1"/>
+      <line num="762" count="2" type="cond" truecount="2" falsecount="0"/>
+      <line num="763" count="3" type="stmt"/>
+      <line num="764" count="3" type="stmt"/>
+      <line num="765" count="3" type="stmt"/>
+      <line num="768" count="2" type="stmt"/>
+      <line num="769" count="3" type="stmt"/>
+      <line num="772" count="3" type="stmt"/>
+      <line num="773" count="3" type="cond" truecount="2" falsecount="0"/>
+      <line num="774" count="1" type="stmt"/>
+      <line num="778" count="2" type="stmt"/>
+      <line num="781" count="1" type="stmt"/>
+      <line num="783" count="1" type="stmt"/>
+      <line num="802" count="3" type="stmt"/>
+      <line num="803" count="3" type="stmt"/>
+      <line num="804" count="1" type="stmt"/>
+      <line num="806" count="2" type="stmt"/>
+      <line num="857" count="2" type="stmt"/>
+      <line num="872" count="2" type="stmt"/>
+      <line num="878" count="2" type="stmt"/>
+      <line num="881" count="2" type="stmt"/>
+      <line num="883" count="0" type="stmt"/>
+      <line num="884" count="0" type="stmt"/>
+      <line num="887" count="0" type="stmt"/>
+      <line num="888" count="0" type="stmt"/>
+      <line num="891" count="0" type="cond" truecount="0" falsecount="2"/>
+      <line num="892" count="0" type="stmt"/>
+      <line num="893" count="0" type="stmt"/>
+      <line num="895" count="0" type="stmt"/>
+      <line num="896" count="0" type="stmt"/>
+      <line num="900" count="0" type="stmt"/>
+      <line num="901" count="0" type="stmt"/>
+      <line num="903" count="0" type="cond" truecount="0" falsecount="2"/>
+      <line num="904" count="0" type="stmt"/>
+      <line num="906" count="0" type="stmt"/>
+      <line num="910" count="0" type="stmt"/>
+      <line num="911" count="0" type="stmt"/>
+      <line num="915" count="0" type="stmt"/>
+      <line num="916" count="0" type="stmt"/>
+      <line num="919" count="0" type="stmt"/>
+      <line num="921" count="0" type="stmt"/>
+    </file>
+  </project>
+</coverage>