@onlineapps/conn-base-cache 1.0.0

package/API.md

@@ -0,0 +1,692 @@
+<a name="module_@onlineapps/conn-base-cache"></a>
+
+## @onlineapps/conn-base-cache
+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**: [GitHub Repository](https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-base-cache)  
+**Since**: 1.0.0  
+**Author**: OA Drive Team  
+**License**: MIT  
+
+* [@onlineapps/conn-base-cache](#module_@onlineapps/conn-base-cache)
+    * _static_
+        * [.VERSION](#module_@onlineapps/conn-base-cache.VERSION) : <code>string</code>
+    * _inner_
+        * [~CacheConnector](#module_@onlineapps/conn-base-cache..CacheConnector)
+            * [new CacheConnector()](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+            * [new CacheConnector([config])](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+        * [~CacheConnector](#module_@onlineapps/conn-base-cache..CacheConnector)
+            * [new CacheConnector()](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+            * [new CacheConnector([config])](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+        * [~connect()](#module_@onlineapps/conn-base-cache..connect) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~disconnect()](#module_@onlineapps/conn-base-cache..disconnect) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [~get(key)](#module_@onlineapps/conn-base-cache..get) ⇒ <code>Promise.&lt;(\*\|null)&gt;</code>
+        * [~set(key, value, [ttl])](#module_@onlineapps/conn-base-cache..set) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~delete(key)](#module_@onlineapps/conn-base-cache..delete) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~deleteByPattern(pattern)](#module_@onlineapps/conn-base-cache..deleteByPattern) ⇒ <code>Promise.&lt;number&gt;</code>
+        * [~exists(key)](#module_@onlineapps/conn-base-cache..exists) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~ttl(key)](#module_@onlineapps/conn-base-cache..ttl) ⇒ <code>Promise.&lt;number&gt;</code>
+        * [~expire(key, ttl)](#module_@onlineapps/conn-base-cache..expire) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~incr(key, [increment])](#module_@onlineapps/conn-base-cache..incr) ⇒ <code>Promise.&lt;number&gt;</code>
+        * [~decr(key, [decrement])](#module_@onlineapps/conn-base-cache..decr) ⇒ <code>Promise.&lt;number&gt;</code>
+        * [~mget(keys)](#module_@onlineapps/conn-base-cache..mget) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [~mset(keyValues, [ttl])](#module_@onlineapps/conn-base-cache..mset) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~flush([confirm])](#module_@onlineapps/conn-base-cache..flush) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~getStats()](#module_@onlineapps/conn-base-cache..getStats) ⇒ <code>CacheStats</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>string</code>
+        * [~resetStats()](#module_@onlineapps/conn-base-cache..resetStats) ⇒ <code>void</code>
+        * [~withNamespace(namespace)](#module_@onlineapps/conn-base-cache..withNamespace) ⇒ <code>CacheConnector</code>
+        * [~wrap(fn, [options])](#module_@onlineapps/conn-base-cache..wrap) ⇒ <code>function</code>
+        * [~healthCheck()](#module_@onlineapps/conn-base-cache..healthCheck) ⇒ <code>Promise.&lt;boolean&gt;</code>
+        * [~create(config)](#module_@onlineapps/conn-base-cache..create) ⇒ <code>CacheConnector</code>
+        * [~CacheConfig](#module_@onlineapps/conn-base-cache..CacheConfig) : <code>Object</code>
+        * [~CacheStats](#module_@onlineapps/conn-base-cache..CacheStats) : <code>Object</code>
+
+<a name="module_@onlineapps/conn-base-cache.VERSION"></a>
+
+### @onlineapps/conn-base-cache.VERSION : <code>string</code>
+Current version
+
+**Kind**: static constant of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+<a name="module_@onlineapps/conn-base-cache..CacheConnector"></a>
+
+### @onlineapps/conn-base-cache~CacheConnector
+**Kind**: inner class of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+
+* [~CacheConnector](#module_@onlineapps/conn-base-cache..CacheConnector)
+    * [new CacheConnector()](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+    * [new CacheConnector([config])](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+
+<a name="new_module_@onlineapps/conn-base-cache..CacheConnector_new"></a>
+
+#### new CacheConnector()
+Redis cache connector providing caching operations with automatic key management
+
+**Example** *(Basic Usage)*  
+```js
+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** *(With Namespace)*  
+```js
+const cache = new CacheConnector({
+  namespace: 'invoice-service'
+});
+await cache.set('inv:123', data); // Actual key: cache:invoice-service:inv:123
+```
+<a name="new_module_@onlineapps/conn-base-cache..CacheConnector_new"></a>
+
+#### new CacheConnector([config])
+Creates a new CacheConnector instance
+
+**Throws**:
+
+- <code>TypeError</code> If configuration is invalid
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [config] | <code>Object</code> | <code>{}</code> | Configuration options |
+| [config.host] | <code>string</code> | <code>&quot;&#x27;localhost&#x27;&quot;</code> | Redis server host |
+| [config.port] | <code>number</code> | <code>6379</code> | Redis server port |
+| [config.password] | <code>string</code> |  | Redis password for authentication |
+| [config.db] | <code>number</code> | <code>0</code> | Redis database number to use |
+| [config.defaultTTL] | <code>number</code> | <code>3600</code> | Default TTL in seconds for cached items |
+| [config.namespace] | <code>string</code> | <code>&quot;&#x27;&#x27;&quot;</code> | Namespace prefix for all keys |
+| [config.maxRetries] | <code>number</code> | <code>3</code> | Maximum connection retry attempts |
+| [config.retryDelay] | <code>number</code> | <code>100</code> | Initial retry delay in milliseconds |
+| [config.enableOfflineQueue] | <code>boolean</code> | <code>true</code> | Queue commands when disconnected |
+| [config.lazyConnect] | <code>boolean</code> | <code>false</code> | Delay connection until first operation |
+
+**Example** *(Full Configuration)*  
+```js
+const cache = new CacheConnector({
+  host: 'redis.example.com',
+  port: 6380,
+  password: 'secret',
+  namespace: 'my-service',
+  defaultTTL: 1800,
+  maxRetries: 5,
+  enableOfflineQueue: false
+});
+```
+<a name="module_@onlineapps/conn-base-cache..CacheConnector"></a>
+
+### @onlineapps/conn-base-cache~CacheConnector
+**Kind**: inner class of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+
+* [~CacheConnector](#module_@onlineapps/conn-base-cache..CacheConnector)
+    * [new CacheConnector()](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+    * [new CacheConnector([config])](#new_module_@onlineapps/conn-base-cache..CacheConnector_new)
+
+<a name="new_module_@onlineapps/conn-base-cache..CacheConnector_new"></a>
+
+#### new CacheConnector()
+Redis cache connector providing caching operations with automatic key management
+
+**Example** *(Basic Usage)*  
+```js
+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** *(With Namespace)*  
+```js
+const cache = new CacheConnector({
+  namespace: 'invoice-service'
+});
+await cache.set('inv:123', data); // Actual key: cache:invoice-service:inv:123
+```
+<a name="new_module_@onlineapps/conn-base-cache..CacheConnector_new"></a>
+
+#### new CacheConnector([config])
+Creates a new CacheConnector instance
+
+**Throws**:
+
+- <code>TypeError</code> If configuration is invalid
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [config] | <code>Object</code> | <code>{}</code> | Configuration options |
+| [config.host] | <code>string</code> | <code>&quot;&#x27;localhost&#x27;&quot;</code> | Redis server host |
+| [config.port] | <code>number</code> | <code>6379</code> | Redis server port |
+| [config.password] | <code>string</code> |  | Redis password for authentication |
+| [config.db] | <code>number</code> | <code>0</code> | Redis database number to use |
+| [config.defaultTTL] | <code>number</code> | <code>3600</code> | Default TTL in seconds for cached items |
+| [config.namespace] | <code>string</code> | <code>&quot;&#x27;&#x27;&quot;</code> | Namespace prefix for all keys |
+| [config.maxRetries] | <code>number</code> | <code>3</code> | Maximum connection retry attempts |
+| [config.retryDelay] | <code>number</code> | <code>100</code> | Initial retry delay in milliseconds |
+| [config.enableOfflineQueue] | <code>boolean</code> | <code>true</code> | Queue commands when disconnected |
+| [config.lazyConnect] | <code>boolean</code> | <code>false</code> | Delay connection until first operation |
+
+**Example** *(Full Configuration)*  
+```js
+const cache = new CacheConnector({
+  host: 'redis.example.com',
+  port: 6380,
+  password: 'secret',
+  namespace: 'my-service',
+  defaultTTL: 1800,
+  maxRetries: 5,
+  enableOfflineQueue: false
+});
+```
+<a name="module_@onlineapps/conn-base-cache..connect"></a>
+
+### @onlineapps/conn-base-cache~connect() ⇒ <code>Promise.&lt;boolean&gt;</code>
+Establishes connection to Redis server
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true when connection is established  
+**Throws**:
+
+- <code>Error</code> Throws error if connection fails after all retries
+
+**Emits**: [<code>connect</code>](#CacheConnector+event_connect), [<code>error</code>](#CacheConnector+event_error), [<code>close</code>](#CacheConnector+event_close)  
+**Example** *(Simple Connection)*  
+```js
+try {
+  await cache.connect();
+  console.log('Connected to Redis');
+} catch (error) {
+  console.error('Failed to connect:', error);
+}
+```
+**Example** *(With Event Handlers)*  
+```js
+cache.client.on('connect', () => {
+  console.log('Redis connected');
+});
+
+cache.client.on('error', (err) => {
+  console.error('Redis error:', err);
+});
+
+await cache.connect();
+```
+<a name="module_@onlineapps/conn-base-cache..disconnect"></a>
+
+### @onlineapps/conn-base-cache~disconnect() ⇒ <code>Promise.&lt;void&gt;</code>
+Disconnect from Redis server gracefully
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Example**  
+```js
+await cache.disconnect();
+console.log('Disconnected from Redis');
+```
+<a name="module_@onlineapps/conn-base-cache..get"></a>
+
+### @onlineapps/conn-base-cache~get(key) ⇒ <code>Promise.&lt;(\*\|null)&gt;</code>
+Retrieves a value from cache by key
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;(\*\|null)&gt;</code> - The cached value (parsed from JSON if applicable) or null if not found  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+**Emits**: <code>CacheConnector#event:hit - When cache hit occurs</code>, <code>CacheConnector#event:miss - When cache miss occurs</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | Cache key to retrieve |
+
+**Example** *(Get Simple Value)*  
+```js
+const value = await cache.get('user:123');
+if (value) {
+  console.log('User found:', value);
+}
+```
+**Example** *(Get with Fallback)*  
+```js
+let user = await cache.get('user:123');
+if (!user) {
+  user = await fetchFromDatabase(123);
+  await cache.set('user:123', user, 600);
+}
+```
+<a name="module_@onlineapps/conn-base-cache..set"></a>
+
+### @onlineapps/conn-base-cache~set(key, value, [ttl]) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Stores a value in cache with optional TTL
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true on successful storage  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | Cache key |
+| value | <code>\*</code> | Value to cache (will be JSON stringified if not a string) |
+| [ttl] | <code>number</code> | Time to live in seconds (uses defaultTTL if not specified) |
+
+**Example** *(Set with Default TTL)*  
+```js
+await cache.set('config', { theme: 'dark' });
+```
+**Example** *(Set with Custom TTL)*  
+```js
+await cache.set('session:abc', sessionData, 1800); // 30 minutes
+```
+**Example** *(Set Permanent (no expiry))*  
+```js
+await cache.set('permanent:data', data, 0);
+```
+<a name="module_@onlineapps/conn-base-cache..delete"></a>
+
+### @onlineapps/conn-base-cache~delete(key) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Delete a single key from cache
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true if key was deleted  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | Cache key to delete |
+
+**Example**  
+```js
+const deleted = await cache.delete('user:123');
+if (deleted) {
+  console.log('Key deleted');
+}
+```
+<a name="module_@onlineapps/conn-base-cache..deleteByPattern"></a>
+
+### @onlineapps/conn-base-cache~deleteByPattern(pattern) ⇒ <code>Promise.&lt;number&gt;</code>
+Deletes keys matching a pattern
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;number&gt;</code> - Number of deleted keys  
+**Throws**:
+
+- <code>Error</code> Throws error if pattern deletion fails
+
+**Warning**: This operation can be expensive on large datasets  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| pattern | <code>string</code> | Redis key pattern (e.g., "user:*", "session:*") |
+
+**Example** *(Delete All User Cache Entries)*  
+```js
+const deleted = await cache.deleteByPattern('user:*');
+console.log(`Deleted ${deleted} user entries`);
+```
+**Example** *(Delete Specific Session Pattern)*  
+```js
+await cache.deleteByPattern('session:user:123:*');
+```
+<a name="module_@onlineapps/conn-base-cache..exists"></a>
+
+### @onlineapps/conn-base-cache~exists(key) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Check if key exists in cache
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true if key exists  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | Cache key to check |
+
+**Example**  
+```js
+if (await cache.exists('user:123')) {
+  console.log('User is cached');
+}
+```
+<a name="module_@onlineapps/conn-base-cache..ttl"></a>
+
+### @onlineapps/conn-base-cache~ttl(key) ⇒ <code>Promise.&lt;number&gt;</code>
+Get remaining TTL for key
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;number&gt;</code> - TTL in seconds, -1 if no TTL, -2 if not exists  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | Cache key |
+
+**Example**  
+```js
+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');
+}
+```
+<a name="module_@onlineapps/conn-base-cache..expire"></a>
+
+### @onlineapps/conn-base-cache~expire(key, ttl) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Update TTL for existing key
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true if TTL was set  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | Cache key |
+| ttl | <code>number</code> | New TTL in seconds |
+
+**Example**  
+```js
+// Extend session by 30 minutes
+await cache.expire('session:abc', 1800);
+```
+<a name="module_@onlineapps/conn-base-cache..incr"></a>
+
+### @onlineapps/conn-base-cache~incr(key, [increment]) ⇒ <code>Promise.&lt;number&gt;</code>
+Increment numeric value atomically
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;number&gt;</code> - New value after increment  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| key | <code>string</code> |  | Cache key |
+| [increment] | <code>number</code> | <code>1</code> | Increment value |
+
+**Example** *(Simple Counter)*  
+```js
+const count = await cache.incr('page:views');
+console.log(`Page views: ${count}`);
+```
+**Example** *(Increment by Value)*  
+```js
+const score = await cache.incr('user:score', 10);
+```
+<a name="module_@onlineapps/conn-base-cache..decr"></a>
+
+### @onlineapps/conn-base-cache~decr(key, [decrement]) ⇒ <code>Promise.&lt;number&gt;</code>
+Decrement numeric value atomically
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;number&gt;</code> - New value after decrement  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| key | <code>string</code> |  | Cache key |
+| [decrement] | <code>number</code> | <code>1</code> | Decrement value |
+
+**Example**  
+```js
+const remaining = await cache.decr('inventory:count', 1);
+if (remaining < 0) {
+  console.log('Out of stock');
+}
+```
+<a name="module_@onlineapps/conn-base-cache..mget"></a>
+
+### @onlineapps/conn-base-cache~mget(keys) ⇒ <code>Promise.&lt;Object&gt;</code>
+Get multiple values at once
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;Object&gt;</code> - Key-value object with found values  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| keys | <code>Array.&lt;string&gt;</code> | Array of cache keys |
+
+**Example**  
+```js
+const result = await cache.mget(['user:1', 'user:2', 'user:3']);
+// Returns: { 'user:1': {...}, 'user:2': {...} }
+// Missing keys are not included in result
+```
+<a name="module_@onlineapps/conn-base-cache..mset"></a>
+
+### @onlineapps/conn-base-cache~mset(keyValues, [ttl]) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Set multiple values at once
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true on success  
+**Throws**:
+
+- <code>Error</code> Throws error if Redis operation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| keyValues | <code>Object</code> | Key-value pairs to set |
+| [ttl] | <code>number</code> | TTL in seconds for all keys |
+
+**Example**  
+```js
+await cache.mset({
+  'user:1': { name: 'Alice' },
+  'user:2': { name: 'Bob' },
+  'user:3': { name: 'Charlie' }
+}, 3600);
+```
+<a name="module_@onlineapps/conn-base-cache..flush"></a>
+
+### @onlineapps/conn-base-cache~flush([confirm]) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Flush all cache keys (dangerous!)
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true on success  
+**Throws**:
+
+- <code>Error</code> If confirmation not provided or flush fails
+
+**Warning**: This will delete ALL cache keys with the configured prefix  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [confirm] | <code>boolean</code> | <code>false</code> | Must be true to execute |
+
+**Example**  
+```js
+// Safety check required
+await cache.flush(true);
+console.log('All cache cleared');
+```
+<a name="module_@onlineapps/conn-base-cache..getStats"></a>
+
+### @onlineapps/conn-base-cache~getStats() ⇒ <code>CacheStats</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>string</code>
+Get cache statistics
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>CacheStats</code> - Current statistics<code>number</code> - stats.hits - Number of cache hits<code>number</code> - stats.misses - Number of cache misses<code>number</code> - stats.sets - Number of set operations<code>number</code> - stats.deletes - Number of delete operations<code>number</code> - stats.errors - Number of errors<code>string</code> - stats.hitRate - Hit rate percentage  
+**Example**  
+```js
+const stats = cache.getStats();
+console.log(`Hit rate: ${stats.hitRate}`);
+console.log(`Total operations: ${stats.hits + stats.misses}`);
+```
+<a name="module_@onlineapps/conn-base-cache..resetStats"></a>
+
+### @onlineapps/conn-base-cache~resetStats() ⇒ <code>void</code>
+Reset statistics counters
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Example**  
+```js
+cache.resetStats();
+// All counters set to 0
+```
+<a name="module_@onlineapps/conn-base-cache..withNamespace"></a>
+
+### @onlineapps/conn-base-cache~withNamespace(namespace) ⇒ <code>CacheConnector</code>
+Creates a new CacheConnector instance with additional namespace
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>CacheConnector</code> - New instance with combined namespace  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| namespace | <code>string</code> | Additional namespace to append |
+
+**Example**  
+```js
+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:*
+```
+<a name="module_@onlineapps/conn-base-cache..wrap"></a>
+
+### @onlineapps/conn-base-cache~wrap(fn, [options]) ⇒ <code>function</code>
+Wraps a function with caching (memoization)
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>function</code> - Wrapped function with caching  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| fn | <code>function</code> |  | Async function to wrap |
+| [options] | <code>Object</code> | <code>{}</code> | Wrapping options |
+| [options.ttl] | <code>number</code> |  | Cache TTL in seconds |
+| [options.keyPrefix] | <code>string</code> |  | Prefix for cache keys |
+| [options.keyGenerator] | <code>function</code> |  | Custom key generation function |
+
+**Example** *(Basic Function Wrapping)*  
+```js
+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** *(Custom Key Generation)*  
+```js
+const searchUsers = cache.wrap(async (filters) => {
+  return await db.searchUsers(filters);
+}, {
+  ttl: 300,
+  keyGenerator: (filters) => `search:${JSON.stringify(filters)}`
+});
+```
+<a name="module_@onlineapps/conn-base-cache..healthCheck"></a>
+
+### @onlineapps/conn-base-cache~healthCheck() ⇒ <code>Promise.&lt;boolean&gt;</code>
+Perform health check on Redis connection
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - Returns true if healthy  
+**Example**  
+```js
+if (await cache.healthCheck()) {
+  console.log('Redis is healthy');
+} else {
+  console.error('Redis is down');
+}
+```
+<a name="module_@onlineapps/conn-base-cache..create"></a>
+
+### @onlineapps/conn-base-cache~create(config) ⇒ <code>CacheConnector</code>
+Factory function to create cache instance
+
+**Kind**: inner method of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Returns**: <code>CacheConnector</code> - New cache connector instance  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| config | <code>CacheConfig</code> | Configuration object |
+
+**Example**  
+```js
+const cache = CacheConnector.create({
+  host: 'localhost',
+  namespace: 'my-service'
+});
+```
+<a name="module_@onlineapps/conn-base-cache..CacheConfig"></a>
+
+### @onlineapps/conn-base-cache~CacheConfig : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Properties**
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| [host] | <code>string</code> | <code>&quot;&#x27;localhost&#x27;&quot;</code> | Redis host |
+| [port] | <code>number</code> | <code>6379</code> | Redis port |
+| [password] | <code>string</code> |  | Redis password |
+| [db] | <code>number</code> | <code>0</code> | Redis database |
+| [defaultTTL] | <code>number</code> | <code>3600</code> | Default TTL in seconds |
+| [namespace] | <code>string</code> | <code>&quot;&#x27;&#x27;&quot;</code> | Key namespace |
+| [maxRetries] | <code>number</code> | <code>3</code> | Max connection retries |
+| [retryDelay] | <code>number</code> | <code>100</code> | Retry delay in ms |
+| [enableOfflineQueue] | <code>boolean</code> | <code>true</code> | Queue commands when disconnected |
+| [lazyConnect] | <code>boolean</code> | <code>false</code> | Delay connection |
+
+<a name="module_@onlineapps/conn-base-cache..CacheStats"></a>
+
+### @onlineapps/conn-base-cache~CacheStats : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-base-cache</code>](#module_@onlineapps/conn-base-cache)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| hits | <code>number</code> | Number of cache hits |
+| misses | <code>number</code> | Number of cache misses |
+| sets | <code>number</code> | Number of set operations |
+| deletes | <code>number</code> | Number of delete operations |
+| errors | <code>number</code> | Number of errors |
+| hitRate | <code>string</code> | Hit rate percentage |
+