Merge pull request #943 from NodeRedis/new-stuff

Deprecate null / undefined arguments
Deprecate .end()
Drop support for redis < 2.6.11
Improve redis url parsing
Add retry_unfullfilled_commands option
Always refresh server_info after running info
Improve arguments parsing

Fixes #927 
Fixes #442 
Fixes #70 
Fixes #921

Author: BridgeAR

.gitignore

@@ -5,4 +5,5 @@ coverage
 *.log
 *.rdb
 stunnel.conf
-stunnel.pid
+stunnel.pid
+*.out

.travis.yml

@@ -11,6 +11,6 @@ addons:
 node_js:
   - "0.10"
   - "0.12"
-  - "4.0"
-  - "5.0"
+  - "4"
+  - "5"
 after_success: npm run coveralls

README.md

@@ -50,9 +50,7 @@ This will display:
         1: hashtest 2
     mjr:~/work/node_redis (master)$
 
-Note that the API is entire asynchronous. To get data back from the server,
-you'll need to use a callback. The return value from most of the API is a
-backpressure indicator.
+Note that the API is entire asynchronous. To get data back from the server, you'll need to use a callback.
 
 ### Promises
 
@@ -115,9 +113,8 @@ For a list of Redis commands, see [Redis Command Reference](http://redis.io/comm
 
 The commands can be specified in uppercase or lowercase for convenience. `client.get()` is the same as `client.GET()`.
 
-Minimal parsing is done on the replies. Commands that return a single line reply return JavaScript Strings,
-integer replies return JavaScript Numbers, "bulk" replies return node Buffers, and "multi bulk" replies return a
-JavaScript Array of node Buffers. `HGETALL` returns an Object with Buffers keyed by the hash keys.
+Minimal parsing is done on the replies. Commands that return a integer return JavaScript Numbers, arrays return JavaScript Array. `HGETALL` returns an Object keyed by the hash keys. All strings will either be returned as string or as buffer depending on your setting.
+Please be aware that sending null, undefined and Boolean values will result in the value coerced to a string!
 
 # API
 
@@ -173,23 +170,20 @@ port and host are probably fine and you don't need to supply any arguments. `cre
 * `redis.createClient()`
 * `redis.createClient(options)`
 * `redis.createClient(unix_socket, options)`
-* `redis.createClient('redis://user:pass@host:port', options)`
+* `redis.createClient(redis_url, options)`
 * `redis.createClient(port, host, options)`
 
 #### `options` is an object with the following possible properties:
 * `host`: *127.0.0.1*; The host to connect to
 * `port`: *6370*; The port to connect to
 * `path`: *null*; The unix socket string to connect to
-* `url`: *null*; The redis url to connect to
+* `url`: *null*; The redis url to connect to (`[redis:]//[user][:password@][host][:port][/db-number][?db=db-number[&password=bar[&option=value]]]` For more info check [IANA](http://www.iana.org/assignments/uri-schemes/prov/redis))
 * `parser`: *hiredis*; Which Redis protocol reply parser to use. If `hiredis` is not installed it will fallback to `javascript`.
 * `return_buffers`: *false*; If set to `true`, then all replies will be sent to callbacks as Buffers instead of Strings.
 * `detect_buffers`: *false*; If set to `true`, then replies will be sent to callbacks as Buffers. Please be aware that this can't work properly with the pubsub mode. A subscriber has to either always return strings or buffers.
 if any of the input arguments to the original command were Buffers.
 This option lets you switch between Buffers and Strings on a per-command basis, whereas `return_buffers` applies to
 every command on a client.
-* `socket_nodelay`: *true*; Disables the [Nagle algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm).
-Setting this option to `false` can result in additional throughput at the cost of more latency.
-Most applications will want this set to `true`.
 * `socket_keepalive` *true*; Whether the keep-alive functionality is enabled on the underlying socket.
 * `no_ready_check`: *false*; When a connection is established to the Redis server, the server might still
 be loading the database from disk. While loading the server will not respond to any commands. To work around this,
@@ -208,7 +202,9 @@ The value is provided in milliseconds and is counted from the moment on a new cl
 Default is to try connecting until the default system socket timeout has been exceeded and to try reconnecting until 1h passed.
 * `max_attempts`: *0*; By default client will try reconnecting until connected. Setting `max_attempts`
 limits total amount of connection tries. Setting this to 1 will prevent any reconnect tries.
-* `auth_pass`: *null*; If set, client will run redis auth command on connect.
+* `retry_unfulfilled_commands`: *false*; If set to true, all commands that were unfulfulled while the connection is lost will be retried after the connection has reestablished again. Use this with caution, if you use state altering commands (e.g. *incr*). This is especially useful if you use blocking commands.
+* `password`: *null*; If set, client will run redis auth command on connect. Alias `auth_pass`
+* `db`: *null*; If set, client will run redis select command on connect. This is [not recommended](https://groups.google.com/forum/#!topic/redis-db/vS5wX8X4Cjg).
 * `family`: *IPv4*; You can force using IPv6 if you set the family to 'IPv6'. See Node.js [net](https://nodejs.org/api/net.html) or [dns](https://nodejs.org/api/dns.html) modules how to use the family type.
 * `disable_resubscribing`: *false*; If set to `true`, a client won't resubscribe after disconnecting
 * `rename_commands`: *null*; pass a object with renamed commands to use those instead of the original functions. See the [redis security topics](http://redis.io/topics/security) for more info.
@@ -245,12 +241,13 @@ NOTE: Your call to `client.auth()` should not be inside the ready handler. If
 you are doing this wrong, `client` will emit an error that looks
 something like this `Error: Ready check failed: ERR operation not permitted`.
 
-## client.end([flush])
+## client.end(flush)
 
 Forcibly close the connection to the Redis server. Note that this does not wait until all replies have been parsed.
 If you want to exit cleanly, call `client.quit()` to send the `QUIT` command after you have handled all replies.
 
-If flush is set to true, all still running commands will be rejected instead of ignored after using `.end`.
+You should set flush to true, if you are not absolutly sure you do not care about any other commands.
+If you set flush to false all still running commands will silently fail.
 
 This example closes the connection to the Redis server before the replies have been read. You probably don't
 want to do this:
@@ -259,12 +256,15 @@ want to do this:
 var redis = require("redis"),
     client = redis.createClient();
 
-client.set("foo_rand000000000000", "some fantastic value");
-client.end(); // No further commands will be processed
-client.get("foo_rand000000000000", function (err, reply) {
-    // This won't be called anymore, since flush has not been set to true!
+client.set("foo_rand000000000000", "some fantastic value", function (err, reply) {
+    // This will either result in an error (flush parameter is set to true)
+    // or will silently fail and this callback will not be called at all (flush set to false)
     console.log(err);
 });
+client.end(true); // No further commands will be processed
+client.get("foo_rand000000000000", function (err, reply) {
+    console.log(err); // => 'The connection has already been closed.'
+});
 ```
 
 `client.end()` without the flush parameter should not be used in production!

changelog.md

@@ -1,12 +1,45 @@
 Changelog
 =========
 
-## v.2.5.0 - xx Dez, 2015
+## v.2.5.0-0 - xx Dez, 2015
 
 Features
 
--  The parsers moved into the [redis-parser](https://github.com/NodeRedis/node-redis-parser) module and will be maintained in there from now on ([@BridgeAR](https://github.com/BridgeAR))
- -  Improve js parser speed significantly for big SUNION/SINTER/LRANGE/ZRANGE ([@BridgeAR](https://github.com/BridgeAR))
+-  The parsers moved into the [redis-parser](https://github.com/NodeRedis/node-redis-parser) module and will be maintained in there from now on
+ -  Improve js parser speed significantly for big SUNION/SINTER/LRANGE/ZRANGE
+-  Improve redis-url parsing to also accept the database-number and options as query parameters as suggested in the [IANA](http://www.iana.org/assignments/uri-schemes/prov/redis)
+-  Added a `retry_unfulfilled_commands` option
+ -  Setting this to 'true' results in retrying all commands that were not fulfilled on a connection loss after the reconnect. Use with caution
+-  Added a `db` option to select the database while connecting (this is [not recommended](https://groups.google.com/forum/#!topic/redis-db/vS5wX8X4Cjg))
+-  Added a `password` option as alias for auth_pass
+-  The client.server_info is from now on updated while using the info command
+
+Bugfixes
+
+-  Fixed explicit undefined as a command callback in a multi context
+-  Fixed hmset failing to detect the first key as buffer or date if the key is of that type
+-  Fixed do not run toString on an array argument and throw a "invalid data" error instead
+ -  This is not considered as breaking change, as this is likely a error in your code and if you want to have such a behavior you should handle this beforehand
+ -  The same applies to Map / Set and individual Object types
+-  Fixed redis url not accepting the protocol being omitted or protocols other than the redis protocol for convienence
+-  Fixed parsing the db keyspace even if the first database does not begin with a zero
+-  Fixed handling of errors occuring while receiving pub sub messages
+
+Deprecations
+
+-  Using any command with a argument being set to null or undefined is deprecated
+ -  From v.3.0.0 on using a command with such an argument will return an error instead
+ -  If you want to keep the old behavior please use a precheck in your code that converts the arguments to a string.
+ -  Using SET or SETEX with a undefined or null value will from now on also result in converting the value to "null" / "undefined" to have a consistent behavior. This is not considered as breaking change, as it returned an error earlier.
+-  Using .end(flush) without the flush parameter deprecated and the flush parameter should explicitly be used
+ -  From v.3.0.0 on using .end without flush will result in an error
+ -  Using .end without flush means that any command that did not yet return is going to silently fail. Therefor this is considered harmfull and you should explicitly silence such errors if you are sure you want this
+-  Depending on the return value of a command to detect the backpressure is deprecated
+ -  From version 3.0.0 on node_redis might not return true / false as a return value anymore. Please rely on client.should_buffer instead
+-  The socket_nodelay option is deprecated and will be removed in v.3.0.0
+ -  If you want to buffer commands you should use [.batch or .multi](./README.md) instead. This is necessary to reduce the amount of different options and this is very likely reducing your throughput if set to false.
+ -  If you are sure you want to activate the NAGLE algorithm you can still activate it by using client.stream.setNoDelay(false)
+-  Redis < v. 2.6.11 is not supported anymore and will not work in all cases. Please update to a newer redis version
 
 ## v.2.4.2 - 27 Nov, 2015