0
# Redis Client
1

2
The Redis client is the core class for connecting to standalone Redis servers or Sentinel-managed deployments. It provides comprehensive Redis command support with full TypeScript typing and robust connection management.
3

4
## Capabilities
5

6
### Redis Class
7

8
Main client class for Redis connections supporting various connection patterns and configuration options.
9

10
```typescript { .api }
11
class Redis extends EventEmitter {
12
  constructor();
13
  constructor(port: number);
14
  constructor(path: string);
15
  constructor(options: RedisOptions);
16
  constructor(port: number, options: RedisOptions);
17
  constructor(port: number, host: string);
18
  constructor(port: number, host: string, options: RedisOptions);
19
  constructor(path: string, options: RedisOptions);
20
  
21
  // Connection management
22
  connect(callback?: Callback<void>): Promise<void>;
23
  disconnect(reconnect?: boolean): void;
24
  quit(callback?: Callback<"OK">): Promise<"OK">;
25
  duplicate(override?: Partial<RedisOptions>): Redis;
26
  
27
  // Properties
28
  readonly options: RedisOptions;
29
  readonly status: RedisStatus;
30
  readonly mode: ConnectionMode;
31
  readonly autoPipelineQueueSize: number;
32
  
33
  // Command execution
34
  sendCommand(command: Command, stream?: WriteableStream): void;
35
  call(command: string, ...args: any[]): Promise<unknown>;
36
}
37

38
type RedisStatus = "wait" | "reconnecting" | "connecting" | "connect" | "ready" | "close" | "end";
39
type ConnectionMode = "normal" | "subscriber" | "monitor";
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import Redis from "ioredis";
46

47
// Basic connection
48
const redis = new Redis(); // localhost:6379
49

50
// Connection with options
51
const redis2 = new Redis({
52
  host: "redis.example.com",
53
  port: 6380,
54
  password: "secret",
55
  db: 1,
56
  retryStrategy: (times) => Math.min(times * 50, 2000)
57
});
58

59
// Unix socket connection
60
const redis3 = new Redis("/tmp/redis.sock");
61

62
// Duplicate connection with overrides
63
const duplicate = redis.duplicate({ db: 2 });
64
```
65

66
### Factory Method
67

68
Node.js Redis compatibility factory method for creating Redis instances.
69

70
```typescript { .api }
71
static createClient(...args: any[]): Redis;
72
```
73

74
```typescript
75
// Node.js redis compatibility
76
const redis = Redis.createClient();
77
const redis2 = Redis.createClient({ url: "redis://localhost:6379" });
78
```
79

80
### Connection Events
81

82
The Redis client emits various events for connection lifecycle management.
83

84
```typescript { .api }
85
// Connection events
86
on(event: 'connect', listener: () => void): this;
87
on(event: 'ready', listener: () => void): this;
88
on(event: 'error', listener: (err: Error) => void): this;
89
on(event: 'close', listener: () => void): this;
90
on(event: 'reconnecting', listener: (ms: number) => void): this;
91
on(event: 'end', listener: () => void): this;
92

93
// Pub/Sub events
94
on(event: 'message', listener: (channel: string, message: string) => void): this;
95
on(event: 'pmessage', listener: (pattern: string, channel: string, message: string) => void): this;
96
on(event: 'messageBuffer', listener: (channel: Buffer, message: Buffer) => void): this;
97
on(event: 'pmessageBuffer', listener: (pattern: Buffer, channel: Buffer, message: Buffer) => void): this;
98
```
99

100
**Usage Examples:**
101

102
```typescript
103
const redis = new Redis();
104

105
redis.on('connect', () => {
106
  console.log('Connected to Redis');
107
});
108

109
redis.on('ready', () => {
110
  console.log('Redis is ready to receive commands');
111
});
112

113
redis.on('error', (err) => {
114
  console.error('Redis error:', err);
115
});
116

117
redis.on('reconnecting', (ms) => {
118
  console.log(`Reconnecting in ${ms}ms`);
119
});
120
```
121

122
### Monitor Mode
123

124
Monitor mode allows inspection of all commands processed by the Redis server.
125

126
```typescript { .api }
127
monitor(callback?: Callback<Redis>): Promise<Redis>;
128
```
129

130
```typescript
131
// Enter monitor mode
132
const monitor = await redis.monitor();
133

134
monitor.on('monitor', (time, args, source, database) => {
135
  console.log(`${time}: COMMAND ${args.join(' ')} (from ${source} on db ${database})`);
136
});
137
```
138

139
## Connection Management
140

141
### Connection Lifecycle
142

143
The Redis client provides precise control over connection establishment and termination.
144

145
```typescript { .api }
146
// Establish connection
147
connect(callback?: Callback<void>): Promise<void>;
148

149
// Immediate disconnection (may lose data)
150
disconnect(reconnect?: boolean): void;
151

152
// Graceful shutdown (waits for pending commands)
153
quit(callback?: Callback<"OK">): Promise<"OK">;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
const redis = new Redis({ lazyConnect: true });
160

161
// Manual connection
162
await redis.connect();
163

164
// Graceful shutdown
165
await redis.quit();
166

167
// Force disconnection
168
redis.disconnect();
169
```
170

171
### Connection Duplication
172

173
Create new Redis instances sharing configuration but with independent connections.
174

175
```typescript { .api }
176
duplicate(override?: Partial<RedisOptions>): Redis;
177
```
178

179
```typescript
180
const redis = new Redis({ host: "redis.example.com" });
181

182
// Duplicate with same config
183
const dup1 = redis.duplicate();
184

185
// Duplicate with overrides
186
const dup2 = redis.duplicate({ 
187
  db: 2,
188
  password: "different-password" 
189
});
190
```
191

192
## Types
193

194
```typescript { .api }
195
type Callback<T> = (err?: Error | null, result?: T) => void;
196

197
interface WriteableStream {
198
  writable: boolean;
199
  write(buffer: any, cb?: Function): boolean;
200
}
201
```