0
# Redis
1

2
Redis is a modern, high-performance Redis client for Node.js applications, built with TypeScript and designed for optimal performance and developer experience. It serves as a comprehensive Redis client library that includes all Redis Stack modules by bundling the core Redis client with specialized extensions for Bloom filters, JSON operations, search capabilities, and time-series data handling.
3

4
## Package Information
5

6
- **Package Name**: redis
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install redis`
10

11
## Core Imports
12

13
```typescript
14
import { createClient, createCluster, createSentinel } from "redis";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createClient, createCluster, createSentinel } = require("redis");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createClient } from "redis";
27

28
// Create and connect client
29
const client = createClient({
30
  url: "redis://localhost:6379"
31
});
32

33
await client.connect();
34

35
// Basic operations
36
await client.set("key", "value");
37
const value = await client.get("key");
38

39
// Disconnect
40
await client.disconnect();
41
```
42

43
## Architecture
44

45
Redis client is built around several key components:
46

47
- **Core Client**: The main `RedisClientType` providing connection management and all Redis commands
48
- **Connection Types**: Support for single Redis instances, clusters, and sentinel configurations  
49
- **Module System**: Extensible architecture with built-in Redis Stack modules (JSON, Search, Time Series, Bloom)
50
- **Type Safety**: Full TypeScript support with strongly typed command parameters and return values
51
- **RESP Protocol**: Support for both RESP2 and RESP3 protocols with automatic type mapping
52
- **Connection Pooling**: Built-in connection pooling for high-performance applications
53
- **Client-Side Caching**: Optional client-side caching with configurable strategies
54

55
## Capabilities
56

57
### Client Creation and Connection Management
58

59
Core functionality for creating Redis clients and managing connections, including support for clusters and sentinel configurations.
60

61
```typescript { .api }
62
function createClient<
63
  M extends RedisModules = {},
64
  F extends RedisFunctions = {},
65
  S extends RedisScripts = {},
66
  RESP extends RespVersions = 2,
67
  TYPE_MAPPING extends TypeMapping = {}
68
>(
69
  options?: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING>
70
): RedisClientType<RedisDefaultModules & M, F, S, RESP, TYPE_MAPPING>;
71

72
function createCluster<
73
  M extends RedisModules = {},
74
  F extends RedisFunctions = {},
75
  S extends RedisScripts = {},
76
  RESP extends RespVersions = 2,
77
  TYPE_MAPPING extends TypeMapping = {}
78
>(
79
  options: RedisClusterOptions<M, F, S, RESP, TYPE_MAPPING>
80
): RedisClusterType<RedisDefaultModules & M, F, S, RESP, TYPE_MAPPING>;
81

82
function createSentinel<
83
  M extends RedisModules = {},
84
  F extends RedisFunctions = {},
85
  S extends RedisScripts = {},
86
  RESP extends RespVersions = 2,
87
  TYPE_MAPPING extends TypeMapping = {}
88
>(
89
  options: RedisSentinelOptions<M, F, S, RESP, TYPE_MAPPING>
90
): RedisSentinelType<RedisDefaultModules & M, F, S, RESP, TYPE_MAPPING>;
91
```
92

93
[Client Management](./client-management.md)
94

95
### Redis Commands
96

97
Complete implementation of all Redis commands with type-safe parameters and return values. Includes string, hash, list, set, sorted set, stream, pub/sub, transaction, and server commands.
98

99
```typescript { .api }
100
// String commands
101
get(key: RedisArgument): Promise<BlobStringReply | null>;
102
set(key: RedisArgument, value: RedisArgument, options?: SetOptions): Promise<SimpleStringReply<'OK'> | null>;
103
incr(key: RedisArgument): Promise<NumberReply>;
104

105
// Hash commands  
106
hGet(key: RedisArgument, field: RedisArgument): Promise<BlobStringReply | null>;
107
hSet(key: RedisArgument, field: RedisArgument, value: RedisArgument): Promise<NumberReply>;
108
hGetAll(key: RedisArgument): Promise<Record<string, BlobStringReply>>;
109

110
// List commands
111
lPush(key: RedisArgument, ...elements: RedisArgument[]): Promise<NumberReply>;
112
rPop(key: RedisArgument): Promise<BlobStringReply | null>;
113
lRange(key: RedisArgument, start: number, stop: number): Promise<ArrayReply<BlobStringReply>>;
114
```
115

116
[Redis Commands](./redis-commands.md)
117

118
### JSON Operations  
119

120
JSON path-based operations for storing, retrieving, and manipulating JSON documents in Redis using RedisJSON.
121

122
```typescript { .api }
123
namespace json {
124
  function get(key: RedisArgument, options?: JsonGetOptions): Promise<RedisJSON | null>;
125
  function set(key: RedisArgument, path: string, value: RedisJSON, options?: JsonSetOptions): Promise<SimpleStringReply<'OK'> | null>;
126
  function del(key: RedisArgument, path?: string): Promise<NumberReply>;
127
  function type(key: RedisArgument, path?: string): Promise<BlobStringReply | null>;
128
}
129
```
130

131
[JSON Operations](./json-operations.md)
132

133
### Search and Indexing
134

135
Full-text search, indexing, and aggregation capabilities using RediSearch for complex query operations.
136

137
```typescript { .api }
138
namespace ft {
139
  function create(index: string, schema: RediSearchSchema, options?: FtCreateOptions): Promise<SimpleStringReply<'OK'>>;
140
  function search(index: string, query: string, options?: FtSearchOptions): Promise<SearchReply>;
141
  function aggregate(index: string, query: string, options?: FtAggregateOptions): Promise<ArrayReply>;
142
  function dropIndex(index: string, options?: FtDropIndexOptions): Promise<SimpleStringReply<'OK'>>;
143
}
144
```
145

146
[Search and Indexing](./search-indexing.md)
147

148
### Time Series Data
149

150
Time series data operations for storing and querying time-stamped data with aggregation rules and downsampling.
151

152
```typescript { .api }
153
namespace ts {
154
  function create(key: RedisArgument, options?: TsCreateOptions): Promise<SimpleStringReply<'OK'>>;
155
  function add(key: RedisArgument, timestamp: number, value: number, options?: TsAddOptions): Promise<NumberReply>;
156
  function get(key: RedisArgument): Promise<ArrayReply | null>;
157
  function range(key: RedisArgument, fromTimestamp: number, toTimestamp: number, options?: TsRangeOptions): Promise<ArrayReply>;
158
}
159
```
160

161
[Time Series](./time-series.md)
162

163
### Bloom Filters and Probabilistic Data Structures
164

165
Probabilistic data structures including Bloom filters, Count-Min Sketch, Cuckoo filters, T-Digest, and Top-K.
166

167
```typescript { .api }
168
namespace bf {
169
  function add(key: RedisArgument, item: RedisArgument): Promise<BooleanReply>;
170
  function exists(key: RedisArgument, item: RedisArgument): Promise<BooleanReply>;
171
  function reserve(key: RedisArgument, errorRate: number, capacity: number, options?: BfReserveOptions): Promise<SimpleStringReply<'OK'>>;
172
}
173
```
174

175
[Bloom Filters](./bloom-filters.md)
176

177
## Core Types  
178

179
```typescript { .api }
180
// Client types
181
type RedisClientType<M = RedisDefaultModules, F = {}, S = {}, RESP = 2, TYPE_MAPPING = {}> = {
182
  connect(): Promise<RedisClientType<M, F, S, RESP, TYPE_MAPPING>>;
183
  disconnect(): Promise<void>;
184
  quit(): Promise<string>;
185
  isOpen: boolean;
186
  isReady: boolean;
187
} & RedisCommands & M;
188

189
type RedisClusterType<M = RedisDefaultModules, F = {}, S = {}, RESP = 2, TYPE_MAPPING = {}> = RedisClientType<M, F, S, RESP, TYPE_MAPPING>;
190

191
type RedisSentinelType<M = RedisDefaultModules, F = {}, S = {}, RESP = 2, TYPE_MAPPING = {}> = RedisClientType<M, F, S, RESP, TYPE_MAPPING>;
192

193
// Configuration types
194
interface RedisClientOptions<M = RedisModules, F = RedisFunctions, S = RedisScripts, RESP = RespVersions, TYPE_MAPPING = TypeMapping> {
195
  url?: string;
196
  socket?: RedisSocketOptions;
197
  username?: string;
198
  password?: string;
199
  name?: string;
200
  database?: number;
201
  modules?: M;
202
  functions?: F;
203
  scripts?: S;
204
  readonly?: boolean;
205
  legacyMode?: boolean;
206
  isolationPoolOptions?: RedisPoolOptions;
207
}
208

209
interface RedisClusterOptions<M = RedisModules, F = RedisFunctions, S = RedisScripts, RESP = RespVersions, TYPE_MAPPING = TypeMapping> {
210
  rootNodes: Array<RedisClusterNode>;
211
  defaults?: Partial<RedisClientOptions<M, F, S, RESP, TYPE_MAPPING>>;
212
  minimizeConnections?: boolean;
213
  useReplicas?: boolean;
214
  maxCommandRedirections?: number;
215
  modules?: M;
216
  functions?: F;
217
  scripts?: S;
218
}
219

220
// Basic argument and reply types
221
type RedisArgument = string | Buffer;
222
type RedisJSON = string | number | boolean | null | RedisJSON[] | { [key: string]: RedisJSON };
223

224
// Reply types
225
type BooleanReply<T = boolean> = T;
226
type NumberReply<T = number> = T;
227
type BlobStringReply<T = Buffer> = T;
228
type SimpleStringReply<T = string> = T;
229
type ArrayReply<T> = T[];
230
type NullReply = null;
231

232
// Default modules type
233
type RedisDefaultModules = {
234
  bf: typeof import('@redis/bloom').bf;
235
  cf: typeof import('@redis/bloom').cf;
236
  cms: typeof import('@redis/bloom').cms;
237
  topK: typeof import('@redis/bloom').topK;
238
  tDigest: typeof import('@redis/bloom').tDigest;
239
  json: typeof import('@redis/json');
240
  ft: typeof import('@redis/search');
241
  ts: typeof import('@redis/time-series');
242
};
243
```