redis-node

by bnoguchi

bnoguchi / redis-node

A Redis client for node.js

131 Stars 13 Forks Last release: Not found MIT License 97 Commits 1 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

redis-node - Complete Redis Client for Node.js


Blog post coming.

Features include:

  • FAST!!!! (See benchmarks)
  • A comprehensive test suite.
  • Fully asynchronous.
  • Support for all Redis commands.
  • PUBLISH and SUBSCRIBE support.
  • Full transactional support (including nested transactions) (i.e., MULTI/EXEC/DISCARD) (to my knowledge, not present in redis-node-client).
  • Idiomatic command syntax.
  • Automatic re-establishment of connections to the Redis server.

Installation

npm install redis-node

A Quick Tour

    // See ./examples/tour.js
    var sys = require("sys");
    var redis = require("redis-node");
    var client = redis.createClient();    // Create the client
    client.select(2);                     // Select database 2

// Assign the string "world" to the "hello" key.
// You can provide a callback to handle the response from Redis
// that gets asynchronously run upon seeing the response.
client.set("hello", "world", function (err, status) {
  if (err) throw err;
  console.log(status); // true
});

// ... but you don't have to provide a callback.
client.set("hello", "world");

// We may or may not be connected yet, but that's ok, since
// the client queues up any commands.

// The commands are also idiomatic
client.hmset("hash", { t: "rex", steg: "asaurus" }, function (err, status) {
  if (err) throw err;
  sys.log(status); // true
});

// Support for transactions
console.log("Transfer from checking to savings.");
client.transaction( function () {
  client.decrby("checking", 100, function (err, balance) {
    if (err) throw err;
    console.log("Checking Balance: " + balance);
  });
  client.incrby("savings", 100, function (err, balance) {
    if (err) throw err;
    console.log("Savings Balance: " + balance);
  });
});

// With automatic transaction discard if there are any syntactic errors
client.transaction( function () {
  client.set("I'm missing a 2nd argument"); // Our client with automatically discard the transaction
});

// Close the connection
setTimeout( function () {
    client.close();
}, 1000);

See test/ for examples of each command.

API Reference

redis.createClient(port, host, options)

Creates a new Client instance connected to the Redis server running on host:port.

host
defaults to
127.0.0.1
port
defaults to
6379
You can pass in an options hash, too. They default to: -
maxReconnectionAttempts
(10) The number of times to try reconnecting to the Redis server before giving up. -
reconnectionDelay
(500) How many milliseconds to wait before the 1st reconnection attempt. Using the strategy of exponential backoff, the delay doubles with every re-connection attempt.

Events

The redis-node client emits important events related to the connection with the Redis server. You can bind an event handler to any of the following events:

  • connected

Emitted when the client successfully makes a connection FOR THE FIRST TIME. You usually will not need to bind an event handler to

connected
because the client takes care of queueing up any commands you send it and flushes them to the Redis server once it is connected.
  • disconnected

Emitted when we drop a connection with the Redis server. This can happen if the connection times out due to no recent activity from the client.

  • reconnecting

Emitted just before the client attempts to reconnect to the Redis server.

  • reconnected

Emitted when the client successfully makes a successful reconnection.

  • noconnection

Emitted when the client gives up its connection attempts.

  • connection error

Emitted when the there is an error that is a result of the connection with the Redis server. The error object is passed to

callback
. If you do not register a listener with this event, then the error is thrown and the program exits.

Commands operating on all value types

client.exists(key, callback)

Test if a key exists. Passes

true
to callback if it exists. Passes
false
to callback if it does not.
javascript
    client.exists("some-key", function (err, doesExist) {
        console.log(doesExist);
    });

client.del(key1, key2, ..., keyn, callback)

Delete a key. Passes the number of keys that were deleted to

callback
.
javascript
    client.del("key1", "key2", function (err, numRemoved) {
        console.log(numRemoved); // 2
    });

client.type(key, callback)

Passes the type of value stored at key to

callback
. One of: -
none
if the key does not exist -
string
if the key contains a
String
value -
list
if the key contains a
List
value -
set
if the key contains a
Set
value -
zset
if the key contains a
Sorted Set
value -
hash
if the key contains a
Hash
value
    client.type("key-with-string", function (err, type) {
        console.log(type); // Either: 'none', 'string', 'list', 'set', 'zset', or 'hash'
    });

client.keys(pattern, callback)

Passes all the keys matching a given pattern to

callback
. ```javascript // The * pattern returns an array of all keys client.keys("*", function (err, arrayOfKeys) { arrayOfKeys.forEach( function (key) { console.log(key); }); });
// .* patterns
client.keys("key*", function (err, arrayOfKeys) {
    arrayOfKeys.forEach( function (key) {
        console.log(key);
    });
});

// ? patterns client.keys("?ar", function (err, arrayOfKeys) { arrayOfKeys.forEach( function (key) { console.log(key); // e.g., 'car', 'bar', 'far' }); });

### client.randomkey(callback)
Passes a random key from the key space to callback.

```javascript client.randomkey( function (err, key) { console.log(key); });

client.rename(oldName, newName, callback)

Renames the old key name

oldName
to the new key name
newName
Passes
true
to
callback
.
javascript
    client.rename("old", "new", function (err, didSucceed) {
        console.log(didSucceed); // true
    });

client.renamenx(oldName, newName, callback)

Renames the old key name

oldName
to the new key name
newName
, if the
newName
key does not already exist. Passes
1
if
newName
key did not already exist, to
callback
. Passes
0
if
newName
key did already exist, to
callback
.
javascript
    client.renamenx("old", "new", function (err, didSucceed) {
        console.log(!!didSucceed); // true
    });

client.dbsize(callback)

Passes the number of keys in the current db.

javascript
    client.dbsize( function (err, numKeys) {
        console.log(numKeys);
    });

client.expire(key, ttl, callback)

Tells Redis to delete the

key
after
ttl
seconds. If we are using Redis < 2.1.3 and if a
ttl
was already set with another prior
client.expire
invocation, then the new
ttl
does NOT override the old
ttl
. If we are using Redis >= 2.1.3 and if a
ttl
was already set with another prior
client.expire
invocation, then the new
ttl
DOES override the old
ttl
. The expiry can be removed from the key if the key is set to a new value using the
client.set(key, value)
command or when a key is destroyed via the
client.del(key)
command. Passes
1
to
callback
if
key
has no current
ttl
expiry. Passes
0
to
callback
if
key
does not exist or if we are using Redis < 2.1.3, and
key
already has a current
ttl
expiry.
javascript
    client.expire("key", 2, function (err, didSetExpiry) {
        console.log(!!didSetExpiry);
    });

client.expireat(key, unixtime, callback)

Tells Redis to delete the

key
at the
unixtime
datetime in the future. Works similarly to
client.expire(key, ttl, callback)
javascript
    client.expireat("key", parseInt((+new Date) / 1000, 10) + 2, function (err, didSetExpiry) {
        console.log(didSetExpiry);
    });

client.ttl(key, callback)

Gets the time to live (i.e., how many seconds before

key
expires) in seconds of
key
. Passes the number of seconds before
key
expires to
callback
. Passes
-1
to
callback
if
key
has no ttl expiry.
javascript
    client.ttl("key", function (err, ttl) {
        console.log(ttl);
    });

client.select(dbIndex, callback)

Selects the DB with the specified

dbIndex
. Passes
true
to
callback
.
javascript
    client.select(2, function (err, didSucceed) {
        console.log(didSucceed); // true
    });

client.move(key, dbIndex, callback)

Moves

key
from the currently selected DB to the
dbIndex
DB. You can use
client.move
as a locking primitive. Passes
1
to
callback
if
key
was moved successfully. Passes
0
if the target
key
was already there or if the source
key
was not found at all.
javascript
    client.move("key", 3, function (err, didSucceed) {
        console.log(!!didSucceed);
    });

client.flushdb(callback)

Deletes all the keys of the currently selected DB. The command never fails. Passes

true
to
callback
.
javascript
    client.flushdb( function (err, didSucceed) {
        console.log(didSucceed); // true
    });

client.flushall(callback)

Deletes all the keys of all the existing databases, not just the currently selected one. This command never fails. Passes

true
to
callback
.
javascript
    client.flushall( function (didSucceed) {
        console.log(didSucceed); // true
    });

Commands operating on all value types

client.set(key, value, callback)

Sets

key
to
value
.
value
can be a String, Number, or Buffer. Passes
true
to
callback
.
javascript
    client.set("key", "value", function (err, didSet) {
        console.log(didSet); // true
    });

client.get(key, callback)

Passes the Buffer value at

key
to callback if the key exists. Passes null to
callback
if
key
does not exist.

MULTI/EXEC (aka transactions)

client.transaction(transactionBlock)

Sends commands inside the function

transactionBlock
as a transaction. Behind the scenes, we precede the commands inside
transactionBlock
with a MULTI command and commit the commands with an EXEC command. If there is a syntax error with any of the commands sent in the transaction, EXEC will never be called; instead a DISCARD command will be sent to the Redis server to roll back the transaction.
javascript
    client.transaction( function () {
        client.rpush("txn", 1);
        client.rpush("txn", 2);
        client.rpush("txn", 3, function (err, count) {
          console.log(count); // 3
        });
    });

Test Coverage

See ./test/ for the list of tests. Currently, the tests are implemented via the Vows. However, the tests will only work with my fork of vows, so install my branch to see the tests pass: git clone git://github.com/bnoguchi/vows.git git checkout teardownFix npm install Then, to run the tests from the command line. make test You can also run the tests directly with the vows binary from the command line. vows test/*.vows.js

Coming Sooner or Later

  • A distributed API for interacting with a Redis cluster.
  • UDP Support

Contributors

Other Redis Clients for Node.js

3rd Party Libraries

License

MIT License


Author

Brian Noguchi

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.