npm package: @opuscapita/redis-client
Description: Andariel specific redis client implementation.
Author: Christian Drengenberg
Latest version: 1.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](https://github.com/OpusCapita/redis-client/wiki).

This library provides two main classes:
 * [RedisClient](#example-single-getset)
 * [RedisEventClient](#example-rediseventclient-pubsub)


### 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](#default-configuration)** will tell you which settings are required for that.

#### Example (single get/set)

```JS
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)

```JS
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.

```JS
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](https://github.com/OpusCapita/redis-client/wiki#RedisEventClient).

```JS
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.

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