Source

snip / deps / redis-node-client / README.md

Diff from to

File deps/redis-node-client/README.md

-# redis-node-client
+# Redis client for Node.js
 
-A Redis client implementation for Node.js which runs atop Google V8.
+## In a nutshell
 
-This project lets you access a Redis instance using server-side JavaScript.
+- Talk to Redis from Node.js 
+- Fully asynchronous; your code is called back when an operation completes
+- [Binary-safe](http://github.com/fictorial/redis-node-client/blob/master/test/test.js#L353-363); uses Node.js Buffer objects for request serialization and reply parsing
+- Client API directly follows Redis' [command specification](http://code.google.com/p/redis/wiki/CommandReference) 
+- *You have to understand how Redis works and the semantics of its command set to most effectively use this client*
+- Supports Redis' new exciting PUBSUB commands
 
-## Asynchronicity
+Recent changes completely break backwards compatibility.  Sorry, it was time.
 
-Node.js does not block on I/O operations.
+## Synopsis
 
-This means that while a typical Redis client might have code that accesses a
-Redis server in a blocking call, Node.js-based code cannot.
+When working from a git clone:
 
-Typical Redis client (e.g. Python):
-
-    foo = client.get('counter')
-
-This Node.js-based Redis client:
-
+    var client = require("./lib/redis-client").createClient(); 
     var sys = require("sys");
-    var redis = require("./redis");
-
-    var client = new redis.Client();
-    client.connect(learn_to_count);
-
-    function learn_to_count () {
-        client.incr('counter').addCallback(function (value) {
-            sys.puts("counter is now " + value);
+    client.stream.addListener("connect", function () {
+        client.info(function (err, info) {
+            if (err) throw new Error(err);
+            sys.puts("Redis Version is: " + info.redis_version);
             client.close();
         });
-    }
+    });
 
-Running this example, we'd see:
+When working with a Kiwi-based installation:
 
-    $ node counter-example.js
-    counter is now 1
-    $ node counter-example.js
-    counter is now 2
-    $ node counter-example.js
-    counter is now 3
+    // $ kiwi install redis-client
 
-That is, you must supply a callback function that is called when Redis returns,
-even if Redis queries are extremely fast.
+    var sys = require("sys"), 
+        kiwi = require("kiwi"),
+        client = kiwi.require("redis-client").createClient();
 
-A potential upside to this slightly awkward requirement is that you can enjoy
-the benefits of pipelining many Redis queries in a non-blocking way.  Redis
-returns replies for requests in the order received.
+    client.stream.addListener("connect", function () {
+        client.info(function (err, info) {
+            if (err) throw new Error(err);
+            sys.puts("Redis Version is: " + info.redis_version);
+            client.close();
+        });
+    });
 
-See the [test.js](http://github.com/fictorial/redis-node-client/raw/master/test.js) 
-file as a good example of this.
+- Refer to the many tests in `test/test.js` for many usage examples.
+- Refer to the `examples/` directory for focused examples.
 
-## Status
+## Installation
 
-* The full Redis 1.1 command specification is supported.
-* All tests pass using Redis HEAD at commit (09f6f7020952cd93e178da11e66e36f8a98398d1; Dec 1 2009) 
-* All tests pass using Node.js v0.1.20-3-g5b1a535 (Dec 1 2009)
-* See the TODO file for known issues.
+This version requires at least `Node.js v0.1.90` and Redis `1.3.8`.
 
-## Testing
+Tested with node `v0.1.91-20-g6e715b8`.
 
-To test:
+You have a number of choices:
 
-1. fire up redis-server on 127.0.0.1:6379 (the default)
-1. install node.js 
-1. run `node test.js`
+- git clone this repo or download a tarball and simply copy `lib/redis-client.js` into your project
+- use git submodule
+- use the [Kiwi](http://github.com/visionmedia/kiwi) package manager for Node.js
+- use the [NPM](http://github.com/isaacs/npm) package manager for Node.js
 
-## Author
+Please let me know if the package manager "seeds" and/or metadata have issues.
+Installation via Kiwi or NPM at this point isn't really possible since this repo
+depends on a unreleased version of Node.js.
 
-Brian Hammond, Fictorial (brian at fictorial dot com)
+## Running the tests
 
-## Copyright
+A good way to learn about this client is to read the test code.
 
-Copyright (C) 2009 Fictorial LLC
+To run the tests, install and run redis on the localhost on port 6379 (defaults).
+Then run `node test/test.js [-v|-q]` where `-v` is for "verbose" and `-q` is for "quiet".
 
-## License
+    $ node test/test.js
+    ..................................................................
+    ...........................++++++++++++++++++++++++++++++++++++
 
-See LICENSE (it's MIT; go nuts).
+    [INFO] All tests have passed.
+
+If you see something like "PSUBSCRIBE: unknown command" then it is time to upgrade
+your Redis installation.
+
+## Documentation
+
+There is a method per Redis command.  E.g. `SETNX` becomes `client.setnx`.
+
+For example, the Redis command [INCRBY](http://code.google.com/p/redis/wiki/IncrCommand)
+is specified as `INCRBY key integer`.  Also, the INCRBY spec says that the reply will
+be "... the new value of key after the increment or decrement."
+
+This translates to the following client code which increments key 'foo' by 42.  If
+the value at key 'foo' was 0 or non-existent, 'newValue' will take value 42 when
+the callback function is called.
+
+    client.incrby('foo', 42, function (err, newValue) {
+        // ...
+    });
+
+This can get [a little wacky](http://github.com/fictorial/redis-node-client/blob/master/test/test.js#L1093-1097). 
+I'm open to suggestions for improvement here.
+
+Note: for PUBSUB, you should use `subscribeTo` and `unsubscribeFrom` instead of the generated
+methods for Redis' `SUBSCRIBE` and `UNSUBSCRIBE` commands.  See [this](http://github.com/fictorial/redis-node-client/blob/master/lib/redis-client.js#L682-694)
+and [this](http://github.com/fictorial/redis-node-client/blob/master/examples/subscriber.js#L14).
+
+## Notes
+
+All commands/requests use the Redis *multi-bulk request* format which will be
+the only accepted request protocol come Redis 2.0.
+
+## Metadata
+
+- *Author*: Brian Hammond (brian at fictorial dot com) with various patches 
+  from nice people everywhere.
+- *Copyright*: Copyright (C) 2010 Fictorial LLC.
+- *License*: MIT
+