@@ -4,9 +4,8 @@ redis - a node.js redis client
4
4
[ ![ Build Status] ( https://travis-ci.org/NodeRedis/node_redis.png )] ( https://travis-ci.org/NodeRedis/node_redis )
5
5
[ ![ Coverage Status] ( https://coveralls.io/repos/NodeRedis/node_redis/badge.svg?branch= )] ( https://coveralls.io/r/NodeRedis/node_redis?branch= )
6
6
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.
10
9
11
10
Install with:
12
11
@@ -81,11 +80,11 @@ If the key is missing, reply will be null (probably):
81
80
82
81
For a list of Redis commands, see [ Redis Command Reference] ( http://redis.io/commands )
83
82
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() ` .
85
84
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,
87
86
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.
89
88
90
89
# API
91
90
@@ -96,21 +95,21 @@ JavaScript Array of node Buffers. `HGETALL` returns an Object with Buffers keye
96
95
### "ready"
97
96
98
97
` 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,
100
99
then replayed just before this event is emitted.
101
100
102
101
### "connect"
103
102
104
103
` 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
106
105
you are free to try to send commands.
107
106
108
107
### "error"
109
108
110
109
` client ` will emit ` error ` when encountering an error connecting to the Redis server.
111
110
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
114
113
cryptic error messages like this:
115
114
116
115
mjr:~/work/node_redis (master)$ node example.js
@@ -135,8 +134,8 @@ It would be nice to distinguish these two cases.
135
134
### "drain"
136
135
137
136
` 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
140
139
resume sending when you get ` drain ` .
141
140
142
141
### "idle"
@@ -155,22 +154,22 @@ port and host are probably fine and you don't need to supply any arguments. `cre
155
154
156
155
` options ` is an object with the following possible properties:
157
156
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.
159
158
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
161
160
objects instead of JavaScript Strings.
162
161
* ` detect_buffers ` : default to ` false ` . If set to ` true ` , then replies will be sent to callbacks as node Buffer objects
163
162
if any of the input arguments to the original command were Buffer objects.
164
163
This option lets you switch between Buffers and Strings on a per-command basis, whereas ` return_buffers ` applies to
165
164
every command on a client.
166
165
* ` 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 ` .
169
168
* ` socket_keepalive ` defaults to ` true ` . Whether the keep-alive functionality is enabled on the underlying socket.
170
169
* ` 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.
174
173
Setting ` no_ready_check ` to ` true ` will inhibit this check.
175
174
* ` enable_offline_queue ` : defaults to ` true ` . By default, if there is no active
176
175
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
211
210
## client.auth(password, callback)
212
211
213
212
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
217
216
` AUTH ` command sent.
218
217
NOTE: Your call to ` client.auth() ` should not be inside the ready handler. If
219
218
you are doing this wrong, ` client ` will emit an error that looks
220
219
something like this ` Error: Ready check failed: ERR operation not permitted ` .
221
220
222
221
## client.end()
223
222
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.
225
224
If you want to exit cleanly, call ` client.quit() ` to send the ` QUIT ` command after you have handled all replies.
226
225
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
228
227
want to do this:
229
228
230
229
``` js
@@ -268,7 +267,7 @@ When dealing with hash values, there are a couple of useful exceptions to this.
268
267
269
268
### client.hgetall(hash)
270
269
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
272
271
with the responses using JavaScript syntax.
273
272
274
273
Example:
@@ -302,7 +301,7 @@ Multiple values may also be set by supplying a list:
302
301
303
302
## Publish / Subscribe
304
303
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
306
305
client connections, subscribes to a channel on one of them, and publishes to that
307
306
channel on the other:
308
307
@@ -332,7 +331,7 @@ channel on the other:
332
331
```
333
332
334
333
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
336
335
set is empty, the connection is put back into regular mode.
337
336
338
337
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`.
354
353
355
354
### "subscribe" (channel, count)
356
355
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
358
357
channel name as ` channel ` and the new count of subscriptions for this client as ` count ` .
359
358
360
359
### "psubscribe" (pattern, count)
361
360
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
363
362
original pattern as ` pattern ` , and the new count of subscriptions for this client as ` count ` .
364
363
365
364
### "unsubscribe" (channel, count)
366
365
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
369
368
` count ` is 0, this client has left subscriber mode and no more subscriber events will be emitted.
370
369
371
370
### "punsubscribe" (pattern, count)
372
371
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
375
374
` count ` is 0, this client has left subscriber mode and no more subscriber events will be emitted.
376
375
377
376
## client.multi([ commands] )
378
377
379
378
` 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() ` .
381
380
382
381
``` js
383
382
var redis = require (" ./index" ),
@@ -411,8 +410,8 @@ Redis. The interface in `node_redis` is to return an individual `Multi` object
411
410
412
411
### Multi.exec( callback )
413
412
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
416
415
until ` Multi.exec() ` is invoked.
417
416
418
417
The ` callback ` of ` .exec() ` will get invoked with two arguments:
@@ -469,8 +468,8 @@ of commands and arguments to the constructor:
469
468
Redis supports the ` MONITOR ` command, which lets you see all commands received by the Redis server
470
469
across all client connections, including from other client libraries and other computers.
471
470
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
474
473
` monitor ` event takes a timestamp from the Redis server and an array of command arguments.
475
474
476
475
Here is a simple example:
@@ -506,7 +505,7 @@ The `versions` key contains an array of the elements of the version string for e
506
505
507
506
## redis.print()
508
507
509
- A handy callback function for displaying return values when testing. Example:
508
+ A handy callback function for displaying return values when testing. Example:
510
509
511
510
``` js
512
511
var redis = require (" redis" ),
@@ -566,36 +565,36 @@ the second word as first parameter:
566
565
567
566
## client.send_command(command_name, args, callback)
568
567
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
571
570
this library is updated, you can use ` send_command() ` to send arbitrary commands to Redis.
572
571
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.
574
573
575
574
## client.connected
576
575
577
576
Boolean tracking the state of the connection to the Redis server.
578
577
579
578
## client.command_queue.length
580
579
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
582
581
enforce some kind of maximum queue depth for commands while connected.
583
582
584
583
Don't mess with ` client.command_queue ` though unless you really know what you are doing.
585
584
586
585
## client.offline_queue.length
587
586
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
589
588
some kind of maximum queue depth for pre-connection commands.
590
589
591
590
## client.retry_delay
592
591
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 ` .
594
593
595
594
## client.retry_backoff
596
595
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.
599
598
600
599
### Commands with Optional and Keyword arguments
601
600
@@ -633,7 +632,7 @@ operations. As pipelining happens naturally from shared connections, overall
633
632
efficiency goes up.
634
633
635
634
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
637
636
and shows the difference between pipelines of 1 and 50.
638
637
639
638
JavaScript parser:
@@ -682,7 +681,7 @@ If the `hiredis` npm module is installed, `node_redis` will use it by default.
682
681
Otherwise, the pure JavaScript parser will be used.
683
682
684
683
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
686
685
code modules after a node upgrade.
687
686
688
687
Most users find that the JS parser is faster than the ` hiredis ` parser. Because
@@ -727,65 +726,20 @@ hiredis parser:
727
726
728
727
## TODO
729
728
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.
737
733
738
734
## 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
742
736
743
737
## 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!
785
739
786
740
## LICENSE - "MIT License"
787
741
788
- Copyright (c) 2010 Matthew Ranney, http://ranney.com/
742
+ Copyright (c) 2015 Matthew Ranney, http://ranney.com/
789
743
790
744
Permission is hereby granted, free of charge, to any person
791
745
obtaining a copy of this software and associated documentation
0 commit comments