Skip to content

Commit 79eb8fb

Browse files
bobymicrobybobymicroby
committed
Update README.MD
1 parent 4d659f0 commit 79eb8fb

File tree

1 file changed

+244
-6
lines changed

1 file changed

+244
-6
lines changed

Diff for: ‎README.md

+244-6
Original file line numberDiff line numberDiff line change
@@ -27,24 +27,24 @@ node-redis is a modern, high performance [Redis](https://redis.io) client for No
2727

2828
## Installation
2929

30-
Start a redis-server via docker (or any other method you prefer):
30+
Start a redis via docker:
3131

3232
```bash
33-
docker run -p 6379:6379 -it redis/redis-stack-server:latest
33+
docker run -p 6379:6379 -d redis:8.0-rc1
3434
```
3535

3636
To install node-redis, simply:
3737

3838
```bash
3939
npm install redis
4040
```
41-
42-
> "redis" is the "whole in one" package that includes all the other packages. If you only need a subset of the commands, you can install the individual packages. See the list below.
41+
> "redis" is the "whole in one" package that includes all the other packages. If you only need a subset of the commands,
42+
> you can install the individual packages. See the list below.
4343
4444
## Packages
4545

4646
| Name | Description |
47-
|------------------------------------------------|---------------------------------------------------------------------------------------------|
47+
| ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
4848
| [`redis`](./packages/redis) | The client with all the ["redis-stack"](https://github.com/redis-stack/redis-stack) modules |
4949
| [`@redis/client`](./packages/client) | The base clients (i.e `RedisClient`, `RedisCluster`, etc.) |
5050
| [`@redis/bloom`](./packages/bloom) | [Redis Bloom](https://redis.io/docs/data-types/probabilistic/) commands |
@@ -53,7 +53,245 @@ npm install redis
5353
| [`@redis/time-series`](./packages/time-series) | [Redis Time-Series](https://redis.io/docs/data-types/timeseries/) commands |
5454
| [`@redis/entraid`](./packages/entraid) | Secure token-based authentication for Redis clients using Microsoft Entra ID |
5555

56-
> Looking for a high-level library to handle object mapping? See [redis-om-node](https://github.com/redis/redis-om-node)!
56+
> Looking for a high-level library to handle object mapping?
57+
> See [redis-om-node](https://github.com/redis/redis-om-node)!
58+
59+
60+
## Usage
61+
62+
### Basic Example
63+
64+
```typescript
65+
import { createClient } from "redis";
66+
67+
const client = await createClient()
68+
.on("error", (err) => console.log("Redis Client Error", err))
69+
.connect();
70+
71+
await client.set("key", "value");
72+
const value = await client.get("key");
73+
client.destroy();
74+
```
75+
76+
The above code connects to localhost on port 6379. To connect to a different host or port, use a connection string in
77+
the format `redis[s]://[[username][:password]@][host][:port][/db-number]`:
78+
79+
```typescript
80+
createClient({
81+
url: "redis://alice:[email protected]:6380",
82+
});
83+
```
84+
85+
You can also use discrete parameters, UNIX sockets, and even TLS to connect. Details can be found in
86+
the [client configuration guide](./docs/client-configuration.md).
87+
88+
To check if the the client is connected and ready to send commands, use `client.isReady` which returns a boolean.
89+
`client.isOpen` is also available. This returns `true` when the client's underlying socket is open, and `false` when it
90+
isn't (for example when the client is still connecting or reconnecting after a network error).
91+
92+
### Redis Commands
93+
94+
There is built-in support for all of the [out-of-the-box Redis commands](https://redis.io/commands). They are exposed
95+
using the raw Redis command names (`HSET`, `HGETALL`, etc.) and a friendlier camel-cased version (`hSet`, `hGetAll`,
96+
etc.):
97+
98+
```typescript
99+
// raw Redis commands
100+
await client.HSET("key", "field", "value");
101+
await client.HGETALL("key");
102+
103+
// friendly JavaScript commands
104+
await client.hSet("key", "field", "value");
105+
await client.hGetAll("key");
106+
```
107+
108+
Modifiers to commands are specified using a JavaScript object:
109+
110+
```typescript
111+
await client.set("key", "value", {
112+
EX: 10,
113+
NX: true,
114+
});
115+
```
116+
117+
Replies will be transformed into useful data structures:
118+
119+
```typescript
120+
await client.hGetAll("key"); // { field1: 'value1', field2: 'value2' }
121+
await client.hVals("key"); // ['value1', 'value2']
122+
```
123+
124+
`Buffer`s are supported as well:
125+
126+
```typescript
127+
await client.hSet("key", "field", Buffer.from("value")); // 'OK'
128+
await client.hGetAll(commandOptions({ returnBuffers: true }), "key"); // { field: <Buffer 76 61 6c 75 65> }
129+
```
130+
131+
### Unsupported Redis Commands
132+
133+
If you want to run commands and/or use arguments that Node Redis doesn't know about (yet!) use `.sendCommand()`:
134+
135+
```typescript
136+
await client.sendCommand(["SET", "key", "value", "NX"]); // 'OK'
137+
138+
await client.sendCommand(["HGETALL", "key"]); // ['key1', 'field1', 'key2', 'field2']
139+
```
140+
141+
### Transactions (Multi/Exec)
142+
143+
Start a [transaction](https://redis.io/topics/transactions) by calling `.multi()`, then chaining your commands. When
144+
you're done, call `.exec()` and you'll get an array back with your results:
145+
146+
```typescript
147+
await client.set("another-key", "another-value");
148+
149+
const [setKeyReply, otherKeyValue] = await client
150+
.multi()
151+
.set("key", "value")
152+
.get("another-key")
153+
.exec(); // ['OK', 'another-value']
154+
```
155+
156+
You can also [watch](https://redis.io/topics/transactions#optimistic-locking-using-check-and-set) keys by calling
157+
`.watch()`. Your transaction will abort if any of the watched keys change.
158+
159+
160+
### Blocking Commands
161+
162+
In v4, `RedisClient` had the ability to create a pool of connections using an "Isolation Pool" on top of the "main"
163+
connection. However, there was no way to use the pool without a "main" connection:
164+
165+
```javascript
166+
const client = await createClient()
167+
.on("error", (err) => console.error(err))
168+
.connect();
169+
170+
await client.ping(client.commandOptions({ isolated: true }));
171+
```
172+
173+
In v5 we've extracted this pool logic into its own class—`RedisClientPool`:
174+
175+
```javascript
176+
const pool = await createClientPool()
177+
.on("error", (err) => console.error(err))
178+
.connect();
179+
180+
await pool.ping();
181+
```
182+
183+
184+
### Pub/Sub
185+
186+
See the [Pub/Sub overview](./docs/pub-sub.md).
187+
188+
### Scan Iterator
189+
190+
[`SCAN`](https://redis.io/commands/scan) results can be looped over
191+
using [async iterators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator):
192+
193+
```typescript
194+
for await (const key of client.scanIterator()) {
195+
// use the key!
196+
await client.get(key);
197+
}
198+
```
199+
200+
This works with `HSCAN`, `SSCAN`, and `ZSCAN` too:
201+
202+
```typescript
203+
for await (const { field, value } of client.hScanIterator("hash")) {
204+
}
205+
for await (const member of client.sScanIterator("set")) {
206+
}
207+
for await (const { score, value } of client.zScanIterator("sorted-set")) {
208+
}
209+
```
210+
211+
You can override the default options by providing a configuration object:
212+
213+
```typescript
214+
client.scanIterator({
215+
TYPE: "string", // `SCAN` only
216+
MATCH: "patter*",
217+
COUNT: 100,
218+
});
219+
```
220+
221+
### Disconnecting
222+
223+
The `QUIT` command has been deprecated in Redis 7.2 and should now also be considered deprecated in Node-Redis. Instead
224+
of sending a `QUIT` command to the server, the client can simply close the network connection.
225+
226+
`client.QUIT/quit()` is replaced by `client.close()`. and, to avoid confusion, `client.disconnect()` has been renamed to
227+
`client.destroy()`.
228+
229+
```typescript
230+
client.destroy();
231+
```
232+
233+
### Auto-Pipelining
234+
235+
Node Redis will automatically pipeline requests that are made during the same "tick".
236+
237+
```typescript
238+
client.set("Tm9kZSBSZWRpcw==", "users:1");
239+
client.sAdd("users:1:tokens", "Tm9kZSBSZWRpcw==");
240+
```
241+
242+
Of course, if you don't do something with your Promises you're certain to
243+
get [unhandled Promise exceptions](https://nodejs.org/api/process.html#process_event_unhandledrejection). To take
244+
advantage of auto-pipelining and handle your Promises, use `Promise.all()`.
245+
246+
```typescript
247+
await Promise.all([
248+
client.set("Tm9kZSBSZWRpcw==", "users:1"),
249+
client.sAdd("users:1:tokens", "Tm9kZSBSZWRpcw=="),
250+
]);
251+
```
252+
253+
### Clustering
254+
255+
Check out the [Clustering Guide](./docs/clustering.md) when using Node Redis to connect to a Redis Cluster.
256+
257+
### Events
258+
259+
The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:
260+
261+
| Name | When | Listener arguments |
262+
| ----------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------- |
263+
| `connect` | Initiating a connection to the server | _No arguments_ |
264+
| `ready` | Client is ready to use | _No arguments_ |
265+
| `end` | Connection has been closed (via `.disconnect()`) | _No arguments_ |
266+
| `error` | An error has occurred—usually a network issue such as "Socket closed unexpectedly" | `(error: Error)` |
267+
| `reconnecting` | Client is trying to reconnect to the server | _No arguments_ |
268+
| `sharded-channel-moved` | See [here](./docs/pub-sub.md#sharded-channel-moved-event) | See [here](./docs/pub-sub.md#sharded-channel-moved-event) |
269+
270+
> :warning: You **MUST** listen to `error` events. If a client doesn't have at least one `error` listener registered and
271+
> an `error` occurs, that error will be thrown and the Node.js process will exit. See the [ > `EventEmitter` docs](https://nodejs.org/api/events.html#events_error_events) for more details.
272+
273+
> The client will not emit [any other events](./docs/v3-to-v4.md#all-the-removed-events) beyond those listed above.
274+
275+
## Supported Redis versions
276+
277+
Node Redis is supported with the following versions of Redis:
278+
279+
| Version | Supported |
280+
| ------- | ------------------ |
281+
| 8.0.z | :heavy_check_mark: |
282+
| 7.0.z | :heavy_check_mark: |
283+
| 6.2.z | :heavy_check_mark: |
284+
| 6.0.z | :heavy_check_mark: |
285+
| 5.0.z | :heavy_check_mark: |
286+
| < 5.0 | :x: |
287+
288+
> Node Redis should work with older versions of Redis, but it is not fully tested and we cannot offer support.
289+
290+
## Migration
291+
292+
- [From V3 to V4](docs/v3-to-v4.md)
293+
- [From V4 to V5](docs/v4-to-v5.md)
294+
- [V5](docs/v5.md)
57295

58296
## Contributing
59297

0 commit comments

Comments
 (0)