npm package: @origins-digital/nestjs-redis
Description: Origins Digital NestJS Redis Module
Author: Origins Digital
Latest version: 2.1.4

# @origins-digital/redis

A NestJS module for Redis integration using ioredis.

## Installation

```bash
npm install @origins-digital/redis
```

## Features

- Seamless Redis integration with NestJS
- Automatic reconnection handling
- Configurable retry strategy
- Global module support
- Environment-based configuration
- Event handling for connection status

## Usage

### Basic Setup

```typescript
import { Module } from '@nestjs/common';
import { RedisModule } from '@origins-digital/redis';

@Module({
  imports: [
    RedisModule.registerAsync({
      useFactory: () => ({
        connectionOptions: {
          host: process.env.REDIS_HOST,
          port: parseInt(process.env.REDIS_PORT),
          password: process.env.REDIS_PASSWORD,
        },
        onClientReady: (client) => {
          console.log('Redis client ready');
        },
      }),
    }),
  ],
})
export class AppModule {}
```

### Using Environment Variables

```typescript
import { Module } from '@nestjs/common';
import { RedisModule, redisRetryStrategy } from '@origins-digital/redis';

@Module({
  imports: [
    RedisModule.registerAsync({
      useFactory: redisRetryStrategy,
    }),
  ],
})
export class AppModule {}
```

### Using Redis in Services

```typescript
import { Injectable } from '@nestjs/common';
import { Inject } from '@nestjs/common';
import { IO_REDIS_CACHE } from '@origins-digital/redis';
import Redis from 'ioredis';

@Injectable()
export class CacheService {
  constructor(
    @Inject(IO_REDIS_CACHE)
    private readonly redis: Redis,
  ) {}

  async set(key: string, value: string, ttl?: number): Promise<void> {
    if (ttl) {
      await this.redis.setex(key, ttl, value);
    } else {
      await this.redis.set(key, value);
    }
  }

  async get(key: string): Promise<string | null> {
    return this.redis.get(key);
  }

  async del(key: string): Promise<void> {
    await this.redis.del(key);
  }
}
```

### Retry Strategy Configuration

The package includes a built-in retry strategy that:

- Attempts to reconnect up to 10 times
- Implements exponential backoff with a maximum delay of 5 seconds
- Skips retries in local environment
- Handles connection errors appropriately

```typescript
const retryStrategy = {
  retryStrategy: (retries) => {
    if (retries > maxConnectRetry || process.env.APP_ENV === 'local') {
      return;
    }
    const delay = Math.min(retries * 500, 5000);
    return delay;
  },
};
```

### Event Handling

The Redis client emits various events that you can listen to:

```typescript
client.on('error', (err) => {
  console.error('Redis error:', err);
});

client.on('connect', () => {
  console.log('Connected to Redis');
});

client.on('disconnect', () => {
  console.log('Disconnected from Redis');
});
```

## Configuration Options

### RedisModuleOptions

```typescript
type RedisModuleOptions = {
  connectionOptions: RedisOptions;
  onClientReady?: (client: Redis) => void;
};
```

### RedisOptions

```typescript
interface RedisOptions {
  host?: string;
  port?: number;
  password?: string;
  db?: number;
  retryStrategy?: (retries: number) => number | null;
  reconnectOnError?: (err: Error) => boolean;
  // ... other ioredis options
}
```

## Environment Variables

The package expects the following environment variables:

- `REDIS_ENDPOINT`: Redis server endpoint (e.g., 'redis://localhost:6379')
- `REDIS_PORT`: Redis server port
- `REDIS_PASSWORD`: Redis server password (optional)
- `APP_ENV`: Application environment (e.g., 'local', 'development', 'production')

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.