Skip to content

Commit 37866b0

Browse files
author
Ruben Bridgewater
committed
Update readme
1 parent ac63e85 commit 37866b0

File tree

1 file changed

+55
-101
lines changed

1 file changed

+55
-101
lines changed

README.md

Lines changed: 55 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,8 @@ redis - a node.js redis client
44
[![Build Status](https://travis-ci.org/NodeRedis/node_redis.png)](https://travis-ci.org/NodeRedis/node_redis)
55
[![Coverage Status](https://coveralls.io/repos/NodeRedis/node_redis/badge.svg?branch=)](https://coveralls.io/r/NodeRedis/node_redis?branch=)
66

7-
This is a complete Redis client for node.js. It supports all Redis commands,
8-
including many recently added commands like EVAL from experimental Redis server
9-
branches.
7+
This is a complete Redis client for node.js. It supports all Redis commands,
8+
including many recently added commands.
109

1110
Install with:
1211

@@ -81,11 +80,11 @@ If the key is missing, reply will be null (probably):
8180

8281
For a list of Redis commands, see [Redis Command Reference](http://redis.io/commands)
8382

84-
The commands can be specified in uppercase or lowercase for convenience. `client.get()` is the same as `client.GET()`.
83+
The commands can be specified in uppercase or lowercase for convenience. `client.get()` is the same as `client.GET()`.
8584

86-
Minimal parsing is done on the replies. Commands that return a single line reply return JavaScript Strings,
85+
Minimal parsing is done on the replies. Commands that return a single line reply return JavaScript Strings,
8786
integer replies return JavaScript Numbers, "bulk" replies return node Buffers, and "multi bulk" replies return a
88-
JavaScript Array of node Buffers. `HGETALL` returns an Object with Buffers keyed by the hash keys.
87+
JavaScript Array of node Buffers. `HGETALL` returns an Object with Buffers keyed by the hash keys.
8988

9089
# API
9190

@@ -96,21 +95,21 @@ JavaScript Array of node Buffers. `HGETALL` returns an Object with Buffers keye
9695
### "ready"
9796

9897
`client` will emit `ready` once a connection is established to the Redis server and the server reports
99-
that it is ready to receive commands. Commands issued before the `ready` event are queued,
98+
that it is ready to receive commands. Commands issued before the `ready` event are queued,
10099
then replayed just before this event is emitted.
101100

102101
### "connect"
103102

104103
`client` will emit `connect` at the same time as it emits `ready` unless `client.options.no_ready_check`
105-
is set. If this options is set, `connect` will be emitted when the stream is connected, and then
104+
is set. If this options is set, `connect` will be emitted when the stream is connected, and then
106105
you are free to try to send commands.
107106

108107
### "error"
109108

110109
`client` will emit `error` when encountering an error connecting to the Redis server.
111110

112-
Note that "error" is a special event type in node. If there are no listeners for an
113-
"error" event, node will exit. This is usually what you want, but it can lead to some
111+
Note that "error" is a special event type in node. If there are no listeners for an
112+
"error" event, node will exit. This is usually what you want, but it can lead to some
114113
cryptic error messages like this:
115114

116115
mjr:~/work/node_redis (master)$ node example.js
@@ -135,8 +134,8 @@ It would be nice to distinguish these two cases.
135134
### "drain"
136135

137136
`client` will emit `drain` when the TCP connection to the Redis server has been buffering, but is now
138-
writable. This event can be used to stream commands in to Redis and adapt to backpressure. Right now,
139-
you need to check `client.command_queue.length` to decide when to reduce your send rate. Then you can
137+
writable. This event can be used to stream commands in to Redis and adapt to backpressure. Right now,
138+
you need to check `client.command_queue.length` to decide when to reduce your send rate. Then you can
140139
resume sending when you get `drain`.
141140

142141
### "idle"
@@ -155,22 +154,22 @@ port and host are probably fine and you don't need to supply any arguments. `cre
155154

156155
`options` is an object with the following possible properties:
157156

158-
* `parser`: which Redis protocol reply parser to use. Defaults to `hiredis` if that module is installed.
157+
* `parser`: which Redis protocol reply parser to use. Defaults to `hiredis` if that module is installed.
159158
This may also be set to `javascript`.
160-
* `return_buffers`: defaults to `false`. If set to `true`, then all replies will be sent to callbacks as node Buffer
159+
* `return_buffers`: defaults to `false`. If set to `true`, then all replies will be sent to callbacks as node Buffer
161160
objects instead of JavaScript Strings.
162161
* `detect_buffers`: default to `false`. If set to `true`, then replies will be sent to callbacks as node Buffer objects
163162
if any of the input arguments to the original command were Buffer objects.
164163
This option lets you switch between Buffers and Strings on a per-command basis, whereas `return_buffers` applies to
165164
every command on a client.
166165
* `socket_nodelay`: defaults to `true`. Whether to call setNoDelay() on the TCP stream, which disables the
167-
Nagle algorithm on the underlying socket. Setting this option to `false` can result in additional throughput at the
168-
cost of more latency. Most applications will want this set to `true`.
166+
Nagle algorithm on the underlying socket. Setting this option to `false` can result in additional throughput at the
167+
cost of more latency. Most applications will want this set to `true`.
169168
* `socket_keepalive` defaults to `true`. Whether the keep-alive functionality is enabled on the underlying socket.
170169
* `no_ready_check`: defaults to `false`. When a connection is established to the Redis server, the server might still
171-
be loading the database from disk. While loading, the server not respond to any commands. To work around this,
172-
`node_redis` has a "ready check" which sends the `INFO` command to the server. The response from the `INFO` command
173-
indicates whether the server is ready for more commands. When ready, `node_redis` emits a `ready` event.
170+
be loading the database from disk. While loading, the server not respond to any commands. To work around this,
171+
`node_redis` has a "ready check" which sends the `INFO` command to the server. The response from the `INFO` command
172+
indicates whether the server is ready for more commands. When ready, `node_redis` emits a `ready` event.
174173
Setting `no_ready_check` to `true` will inhibit this check.
175174
* `enable_offline_queue`: defaults to `true`. By default, if there is no active
176175
connection to the redis server, commands are added to a queue and are executed
@@ -211,20 +210,20 @@ You can force an IPv6 if you set the family to 'IPv6'. See nodejs net or dns mod
211210
## client.auth(password, callback)
212211

213212
When connecting to Redis servers that require authentication, the `AUTH` command must be sent as the
214-
first command after connecting. This can be tricky to coordinate with reconnections, the ready check,
215-
etc. To make this easier, `client.auth()` stashes `password` and will send it after each connection,
216-
including reconnections. `callback` is invoked only once, after the response to the very first
213+
first command after connecting. This can be tricky to coordinate with reconnections, the ready check,
214+
etc. To make this easier, `client.auth()` stashes `password` and will send it after each connection,
215+
including reconnections. `callback` is invoked only once, after the response to the very first
217216
`AUTH` command sent.
218217
NOTE: Your call to `client.auth()` should not be inside the ready handler. If
219218
you are doing this wrong, `client` will emit an error that looks
220219
something like this `Error: Ready check failed: ERR operation not permitted`.
221220

222221
## client.end()
223222

224-
Forcibly close the connection to the Redis server. Note that this does not wait until all replies have been parsed.
223+
Forcibly close the connection to the Redis server. Note that this does not wait until all replies have been parsed.
225224
If you want to exit cleanly, call `client.quit()` to send the `QUIT` command after you have handled all replies.
226225

227-
This example closes the connection to the Redis server before the replies have been read. You probably don't
226+
This example closes the connection to the Redis server before the replies have been read. You probably don't
228227
want to do this:
229228

230229
```js
@@ -268,7 +267,7 @@ When dealing with hash values, there are a couple of useful exceptions to this.
268267

269268
### client.hgetall(hash)
270269

271-
The reply from an HGETALL command will be converted into a JavaScript Object by `node_redis`. That way you can interact
270+
The reply from an HGETALL command will be converted into a JavaScript Object by `node_redis`. That way you can interact
272271
with the responses using JavaScript syntax.
273272

274273
Example:
@@ -302,7 +301,7 @@ Multiple values may also be set by supplying a list:
302301

303302
## Publish / Subscribe
304303

305-
Here is a simple example of the API for publish / subscribe. This program opens two
304+
Here is a simple example of the API for publish / subscribe. This program opens two
306305
client connections, subscribes to a channel on one of them, and publishes to that
307306
channel on the other:
308307

@@ -332,7 +331,7 @@ channel on the other:
332331
```
333332

334333
When a client issues a `SUBSCRIBE` or `PSUBSCRIBE`, that connection is put into a "subscriber" mode.
335-
At that point, only commands that modify the subscription set are valid. When the subscription
334+
At that point, only commands that modify the subscription set are valid. When the subscription
336335
set is empty, the connection is put back into regular mode.
337336

338337
If you need to send regular commands to Redis while in subscriber mode, just open another connection.
@@ -354,30 +353,30 @@ name as `channel`, and the message Buffer as `message`.
354353

355354
### "subscribe" (channel, count)
356355

357-
Client will emit `subscribe` in response to a `SUBSCRIBE` command. Listeners are passed the
356+
Client will emit `subscribe` in response to a `SUBSCRIBE` command. Listeners are passed the
358357
channel name as `channel` and the new count of subscriptions for this client as `count`.
359358

360359
### "psubscribe" (pattern, count)
361360

362-
Client will emit `psubscribe` in response to a `PSUBSCRIBE` command. Listeners are passed the
361+
Client will emit `psubscribe` in response to a `PSUBSCRIBE` command. Listeners are passed the
363362
original pattern as `pattern`, and the new count of subscriptions for this client as `count`.
364363

365364
### "unsubscribe" (channel, count)
366365

367-
Client will emit `unsubscribe` in response to a `UNSUBSCRIBE` command. Listeners are passed the
368-
channel name as `channel` and the new count of subscriptions for this client as `count`. When
366+
Client will emit `unsubscribe` in response to a `UNSUBSCRIBE` command. Listeners are passed the
367+
channel name as `channel` and the new count of subscriptions for this client as `count`. When
369368
`count` is 0, this client has left subscriber mode and no more subscriber events will be emitted.
370369

371370
### "punsubscribe" (pattern, count)
372371

373-
Client will emit `punsubscribe` in response to a `PUNSUBSCRIBE` command. Listeners are passed the
374-
channel name as `channel` and the new count of subscriptions for this client as `count`. When
372+
Client will emit `punsubscribe` in response to a `PUNSUBSCRIBE` command. Listeners are passed the
373+
channel name as `channel` and the new count of subscriptions for this client as `count`. When
375374
`count` is 0, this client has left subscriber mode and no more subscriber events will be emitted.
376375

377376
## client.multi([commands])
378377

379378
`MULTI` commands are queued up until an `EXEC` is issued, and then all commands are run atomically by
380-
Redis. The interface in `node_redis` is to return an individual `Multi` object by calling `client.multi()`.
379+
Redis. The interface in `node_redis` is to return an individual `Multi` object by calling `client.multi()`.
381380

382381
```js
383382
var redis = require("./index"),
@@ -411,8 +410,8 @@ Redis. The interface in `node_redis` is to return an individual `Multi` object
411410

412411
### Multi.exec( callback )
413412

414-
`client.multi()` is a constructor that returns a `Multi` object. `Multi` objects share all of the
415-
same command methods as `client` objects do. Commands are queued up inside the `Multi` object
413+
`client.multi()` is a constructor that returns a `Multi` object. `Multi` objects share all of the
414+
same command methods as `client` objects do. Commands are queued up inside the `Multi` object
416415
until `Multi.exec()` is invoked.
417416

418417
The `callback` of `.exec()` will get invoked with two arguments:
@@ -469,8 +468,8 @@ of commands and arguments to the constructor:
469468
Redis supports the `MONITOR` command, which lets you see all commands received by the Redis server
470469
across all client connections, including from other client libraries and other computers.
471470

472-
After you send the `MONITOR` command, no other commands are valid on that connection. `node_redis`
473-
will emit a `monitor` event for every new monitor message that comes across. The callback for the
471+
After you send the `MONITOR` command, no other commands are valid on that connection. `node_redis`
472+
will emit a `monitor` event for every new monitor message that comes across. The callback for the
474473
`monitor` event takes a timestamp from the Redis server and an array of command arguments.
475474

476475
Here is a simple example:
@@ -506,7 +505,7 @@ The `versions` key contains an array of the elements of the version string for e
506505

507506
## redis.print()
508507

509-
A handy callback function for displaying return values when testing. Example:
508+
A handy callback function for displaying return values when testing. Example:
510509

511510
```js
512511
var redis = require("redis"),
@@ -566,36 +565,36 @@ the second word as first parameter:
566565

567566
## client.send_command(command_name, args, callback)
568567

569-
Used internally to send commands to Redis. For convenience, nearly all commands that are published on the Redis
570-
Wiki have been added to the `client` object. However, if I missed any, or if new commands are introduced before
568+
Used internally to send commands to Redis. For convenience, nearly all commands that are published on the Redis
569+
Wiki have been added to the `client` object. However, if I missed any, or if new commands are introduced before
571570
this library is updated, you can use `send_command()` to send arbitrary commands to Redis.
572571

573-
All commands are sent as multi-bulk commands. `args` can either be an Array of arguments, or omitted.
572+
All commands are sent as multi-bulk commands. `args` can either be an Array of arguments, or omitted.
574573

575574
## client.connected
576575

577576
Boolean tracking the state of the connection to the Redis server.
578577

579578
## client.command_queue.length
580579

581-
The number of commands that have been sent to the Redis server but not yet replied to. You can use this to
580+
The number of commands that have been sent to the Redis server but not yet replied to. You can use this to
582581
enforce some kind of maximum queue depth for commands while connected.
583582

584583
Don't mess with `client.command_queue` though unless you really know what you are doing.
585584

586585
## client.offline_queue.length
587586

588-
The number of commands that have been queued up for a future connection. You can use this to enforce
587+
The number of commands that have been queued up for a future connection. You can use this to enforce
589588
some kind of maximum queue depth for pre-connection commands.
590589

591590
## client.retry_delay
592591

593-
Current delay in milliseconds before a connection retry will be attempted. This starts at `250`.
592+
Current delay in milliseconds before a connection retry will be attempted. This starts at `250`.
594593

595594
## client.retry_backoff
596595

597-
Multiplier for future retry timeouts. This should be larger than 1 to add more time between retries.
598-
Defaults to 1.7. The default initial connection retry is 250, so the second retry will be 425, followed by 723.5, etc.
596+
Multiplier for future retry timeouts. This should be larger than 1 to add more time between retries.
597+
Defaults to 1.7. The default initial connection retry is 250, so the second retry will be 425, followed by 723.5, etc.
599598

600599
### Commands with Optional and Keyword arguments
601600

@@ -633,7 +632,7 @@ operations. As pipelining happens naturally from shared connections, overall
633632
efficiency goes up.
634633

635634
Here are typical results of `multi_bench.js` which is similar to
636-
`redis-benchmark` from the Redis distribution. It uses 5 concurrent connections
635+
`redis-benchmark` from the Redis distribution. It uses 5 concurrent connections
637636
and shows the difference between pipelines of 1 and 50.
638637

639638
JavaScript parser:
@@ -682,7 +681,7 @@ If the `hiredis` npm module is installed, `node_redis` will use it by default.
682681
Otherwise, the pure JavaScript parser will be used.
683682

684683
If you use `hiredis`, be sure to rebuild it whenever you upgrade your version of
685-
node. There are mysterious failures that can happen between node and native
684+
node. There are mysterious failures that can happen between node and native
686685
code modules after a node upgrade.
687686

688687
Most users find that the JS parser is faster than the `hiredis` parser. Because
@@ -727,65 +726,20 @@ hiredis parser:
727726

728727
## TODO
729728

730-
Better tests for auth, disconnect/reconnect, and all combinations thereof.
731-
732-
Stream large set/get values into and out of Redis. Otherwise the entire value must be in node's memory.
733-
734-
Performance can be better for very large values.
735-
736-
I think there are more performance improvements left in there for smaller values, especially for large lists of small values.
729+
1. 100% coverage
730+
2. More performance improvements
731+
3. Stream large set/get values into and out of Redis. Otherwise the entire value must be in node's memory.
732+
4. Performance can be better for very large values in the js parser.
737733

738734
## How to Contribute
739-
- open a pull request and then wait for feedback (if
740-
[DTrejo](http://github.com/dtrejo) does not get back to you within 2 days,
741-
comment again with indignation!)
735+
- open a pull request and then wait for feedback
742736

743737
## Contributors
744-
Many people have have added features and fixed bugs in `node_redis`.
745-
746-
Ordered by date of first contribution.
747-
[Auto-generated](http://github.com/dtrejo/node-authors) on Wed Jul 25 2012 19:14:59 GMT-0700 (PDT).
748-
749-
- [Matt Ranney aka `mranney`](https://github.com/mranney)
750-
- [Tim-Smart aka `tim-smart`](https://github.com/tim-smart)
751-
- [Tj Holowaychuk aka `visionmedia`](https://github.com/visionmedia)
752-
- [rick aka `technoweenie`](https://github.com/technoweenie)
753-
- [Orion Henry aka `orionz`](https://github.com/orionz)
754-
- [Aivo Paas aka `aivopaas`](https://github.com/aivopaas)
755-
- [Hank Sims aka `hanksims`](https://github.com/hanksims)
756-
- [Paul Carey aka `paulcarey`](https://github.com/paulcarey)
757-
- [Pieter Noordhuis aka `pietern`](https://github.com/pietern)
758-
- [nithesh aka `nithesh`](https://github.com/nithesh)
759-
- [Andy Ray aka `andy2ray`](https://github.com/andy2ray)
760-
- [unknown aka `unknowdna`](https://github.com/unknowdna)
761-
- [Dave Hoover aka `redsquirrel`](https://github.com/redsquirrel)
762-
- [Vladimir Dronnikov aka `dvv`](https://github.com/dvv)
763-
- [Umair Siddique aka `umairsiddique`](https://github.com/umairsiddique)
764-
- [Louis-Philippe Perron aka `lp`](https://github.com/lp)
765-
- [Mark Dawson aka `markdaws`](https://github.com/markdaws)
766-
- [Ian Babrou aka `bobrik`](https://github.com/bobrik)
767-
- [Felix Geisendörfer aka `felixge`](https://github.com/felixge)
768-
- [Jean-Hugues Pinson aka `undefined`](https://github.com/undefined)
769-
- [Maksim Lin aka `maks`](https://github.com/maks)
770-
- [Owen Smith aka `orls`](https://github.com/orls)
771-
- [Zachary Scott aka `zzak`](https://github.com/zzak)
772-
- [TEHEK Firefox aka `TEHEK`](https://github.com/TEHEK)
773-
- [Isaac Z. Schlueter aka `isaacs`](https://github.com/isaacs)
774-
- [David Trejo aka `DTrejo`](https://github.com/DTrejo)
775-
- [Brian Noguchi aka `bnoguchi`](https://github.com/bnoguchi)
776-
- [Philip Tellis aka `bluesmoon`](https://github.com/bluesmoon)
777-
- [Marcus Westin aka `marcuswestin2`](https://github.com/marcuswestin2)
778-
- [Jed Schmidt aka `jed`](https://github.com/jed)
779-
- [Dave Peticolas aka `jdavisp3`](https://github.com/jdavisp3)
780-
- [Trae Robrock aka `trobrock`](https://github.com/trobrock)
781-
- [Shankar Karuppiah aka `shankar0306`](https://github.com/shankar0306)
782-
- [Ignacio Burgueño aka `ignacio`](https://github.com/ignacio)
783-
784-
Thanks.
738+
Many people have have added features and fixed bugs in `node_redis`. Thanks to all of them!
785739

786740
## LICENSE - "MIT License"
787741

788-
Copyright (c) 2010 Matthew Ranney, http://ranney.com/
742+
Copyright (c) 2015 Matthew Ranney, http://ranney.com/
789743

790744
Permission is hereby granted, free of charge, to any person
791745
obtaining a copy of this software and associated documentation

0 commit comments

Comments
 (0)