@cortec/redis

Module Overview

@cortec/redis provides a flexible Redis integration for Node.js applications, supporting both single-node and cluster setups. It offers convenient methods for accessing Redis caches, performing health checks, and transforming objects for hash operations. The module is designed to work seamlessly with the Cortec context and configuration system.

Configuration Options

Where to put config: Place your Redis config in config/default.yml (or your environment-specific config file).

Schema:

redis:
  cache:
    connection:
      host: 'localhost'
      port: 6379
      password: 'secret' # optional
      db: 0 # optional, default: 0
    maxRetries: 5 # optional, default: 5
    encryption: false # optional, enables TLS if true
    cluster: # optional, enables Redis Cluster mode
      nodes:
        - host: 'localhost'
          port: 6379
        - host: 'localhost'
          port: 6380

Field-by-field explanation:

• redis: Root key for Redis config.
• cache: Identity/name for this Redis instance (can be any string, e.g. "session", "main", etc.).
• connection: Connection options for ioredis.
  • host: Redis server hostname or IP.
  • port: Redis server port.
  • password: Password for authentication (optional).
  • db: Database index (optional, default is 0).
• maxRetries: Maximum number of retry attempts before giving up (optional, default is 5).
• encryption: If true, enables TLS/SSL for secure connections (optional).
• cluster: If present, enables Redis Cluster mode.
  • nodes: List of cluster node objects, each with host and port.

How config is loaded: The config is loaded automatically by the @cortec/config module and validated at runtime. Access it in code via:

const config = ctx.provide<IConfig>('config');
const redisConfig = config?.get<any>('redis');

If config is missing or invalid, an error is thrown at startup.

Example Usage

Basic Usage

import CortecRedis from '@cortec/redis';

// Instantiate with optional object transformation for hash operations
const redisModule = new CortecRedis(true);

// After loading the context and configuration:
const cache = redisModule.cache('cache'); // 'cache' is the identity from config

// Set and get a value
await cache.set('key', 'value');
const value = await cache.get('key');
console.log(value); // 'value'

Health Check

await redisModule.healthCheck(); // Throws if any Redis instance is unreachable

Cluster Usage

If your configuration includes a cluster section, you can access the cluster instance in the same way:

const clusterCache = redisModule.cache('clusteredCache');
await clusterCache.set('key', 'value');

Advanced: Object Transformation for Hashes

If you instantiate CortecRedis with transformObjects = true, you can use objects directly with hset and get parsed objects from hgetall:

const redisModule = new CortecRedis(true);
const cache = redisModule.cache('cache');

await cache.hset('user:1', { name: 'Alice', age: 30 });
const user = await cache.hgetall('user:1');
console.log(user); // { name: 'Alice', age: 30 }

Disposal

To gracefully close all Redis connections:

await redisModule.dispose();

Testing: Using TestableCortecRedis

For integration or unit tests, you can use TestableCortecRedis to spin up a disposable Redis container using testcontainers. This allows you to run tests against a real Redis instance without needing a local or shared Redis server.

Testing

You can use TestableCortecRedis together with Cortec core to run integration tests against a real, disposable Redis instance—no manual setup required.

import Cortec from '@cortec/core';
import TestableCortecRedis from '@cortec/redis/testable';

const cortec = new Cortec({ name: 'test-app', version: '1.0.0' });
const redis = new TestableCortecRedis({ version: '7.2' }, true);

cortec.use(redis);

// After Cortec is loaded:
const cache = redis.cache('cache');
await cache.set('key', 'value');
const value = await cache.get('key');
console.log(value); // 'value'

• The Redis container is managed automatically by Cortec during the test lifecycle.
• No need to manually configure host/port for tests—connection details are injected.

For more details, see the implementation in src/index.ts and ensure your configuration matches your deployment needs (single-node or cluster).