@opuscapita/redis-client v1.0.12

RedisClient / RedisEventClient

This module provides simplified and Andariel specific redis client access. It uses Consul in order to determine the required server endpoint and further configuration and applies a certain reconnect and host change behavior. In order to have a look at the full API, please visit the related wiki page.

This library provides two main classes:

• RedisClient
• RedisEventClient

Minimum setup

To install RedisClient simply type:

npm install @opuscapita/redis-client

There are two different setups you can run RedisClient with.

Setup using Consul

To go with the minimum setup using, you need to have access to a running Consul server to get your endpoint configuration for redis. In addition, redis has to be registered inside Consul. If a password authentication is required to access redis, Consul has to provide the configuration key {{your-service-name}}/redis/password where {{your-service-name}} is the least name of the directory your code runs in. If authentication is not used, you can set the consul.passwordKey to null or false when creating a new instance of EventClient.

Manual setup without Consul

As it is possible to completely run RedisClient without Consul, you will have to provide all required connection information on your own. The consulOverride object found in the DefaultConfig will tell you which settings are required for that.

Example (single get/set)

const RedisClient = require('@opuscapita/redis-client');

(async () =>
{
    // Factory method creating and initializing a new RedisClient for you.
    const client = await RedisClient.getClient();

    // Get non-existing value.
    let value = await client.get('hello'); // -> null

    // Set single value.
    await client.set('hello', 'Hello, world!'); // -> "OK"

    // Get existing value.
    value = await client.get('hello'); // -> "Hello, world!"

    // Delete key and value.
    await client.delete('hello'); // -> 1

    // If not used anymore, close the client in order to free resources.
    await client.close();
})();

Example (multi get/set)

const RedisClient = require('@opuscapita/redis-client');

(async () =>
{
    // Factory method creating and initializing a new RedisClient for you.
    const client = await RedisClient.getClient();

    // Get non-existing values.
    let value = await client.get('hello', 'world'); // -> [ null, null ]

    // Set multiple values (key, value, key, value).
    await client.set('hello', 1337, 'world', 42); // -> "OK"

    // Get existing values.
    value = await client.get('hello', 'world'); // -> [ 1337, 42 ]

    // Delete key and value.
    await client.delete('hello', 'world'); // -> 2

    // If not used anymore, close the client in order to free resources.
    await client.close();
})();

Example (transactions)

The same as shown in the above examples can be archived using pipelined transactions.

const RedisClient = require('@opuscapita/redis-client');

(async () =>
{
    // Factory method creating and initializing a new RedisClient for you.
    const client = await RedisClient.getClient();
    const transaction = client.getTransaction();

    // Get non-existing value.
    await transaction.get('hello'); // -> Pipeline

    // Set single value.
    await transaction.set('hello', 'Hello, world!'); // -> Pipeline

    // Get existing value.
    await transaction.get('hello'); // -> Pipeline

    // Delete key and value.
    await transaction.delete('hello'); // -> Pipeline

    // Transactions can be executed (exec) or discarded (discard).
    // Running exec() or discard() will invalidate the transaction object so it cannot be used a second time.
    const results = await transaction.exec() // -> [ null, "OK", "Hello, world!", 1 ]

    // If not used anymore, close the client in order to free resources.
    await client.close();
})();

Example RedisEventClient (pub/sub)

The sub class RedisEventClient uses RedisClient to provide a more reliable working with redis pub/sub. For further information please have a look at the wiki.

const { RedisEventClient } = require('@opuscapita/redis-client/lib');

(async () =>
{
    // Create a client instance for subscribing and publishing. These have two be two different instances as redis requires this.
    // You can also pass a config object to both methods.
    const subClient = RedisEventClient.getSubscriberClient();
    const pubClient = RedisEventClient.getPublisherClient();

    // Subscribe to a channel. Should later output: my-channel { hello : 'world!' }
    await subClient.subscribe('my-channel', (channel, message) => console.log(channel, message)) // -> undefined
    // Subscribe to a pattern. Should later output: my-?-channel my-pattern-channel { hello : 'world!' }
    await subClient.subscribe('my-?-channel', (pattern, channel, message) => console.log(pattern channel, message)) // -> undefined

    // Publish events.
    await pubClient.publish('my-channel', { hello : 'world!' });
    await pubClient.publish('my-pattern-channel', { hello : 'world!' });

    // Close the client(s) that you do not use anymore in order to free resources.
    await subClient.close();
    await pubClient.close();
})();

Default configuration

The default configuration object provides hints about what the lib's standard behavior is like.

{
    keyPrefix : null,
    db : 0,
    logger : new Logger(),
    retryCount : 50,
    consul : {
        host : 'consul',
        endpointName : 'redis',
        passwordKey : 'redis/password'
    },
    consulOverride : {
        host : null,
        port : 6379,
        password : null
    }
}