npm package: @opuscapita/config
Description: Configuration API connector module for OpusCapita Business Network Portal.
Latest version: 3.1.17

# @opuscapita/config
This library was automatically build and published to npmjs after commit to the `master` branch but was re-configured for manual build instead.

This module provides easy access to instances of the **consul** service registry. It helps with accessing **key-value** stored configuration data, local data **encryption** and service **endpoint discovery** with health checking and change notifications.

It provides automatic key prefixing for *+key** storage **isolation** and **caching** for keys and endpoints. For further details, please have a look at the [wiki](https://github.com/OpusCapita/config/wiki).

[Minimum setup](#minimum-setup)
[Getting endpoints](#getting-endpoints)
[Automatic change events](#automatic-change-events)
[Requesting multiple keys](#requesting-multiple-keys)
[Minimum setup](#minimum-setup)
[Keys by prefix](#keys-by-prefix)
[Keys by list](#keys-by-list)
[Data encryption](#data-encryption)
[Default configuration](#default-configuration)
[Wiki](https://github.com/OpusCapita/config/wiki)

---

### Minimum setup

First got to your local code directory and run:

```
npm install @opuscapita/config
```

To go with the minimum setup, you'll need to have a consul instance up and running.
Now go to your code file and put in the minimum setup code.

```JS
const config = require('@opuscapita/config');

// You might want to pass a configuration object to the init method. A list of parameters and their default values
// can be found at the .DefaultConfig module property.
await config.init({});
await config.setProperty('my-key', 'my-value');
const value = await config.getProperty('my-key');

console.log(value);
```

If everything worked as expected, you will get a bluebird promise as result.

---

### Getting endpoints

```JS
const config = require('@opuscapita/config');

await config.init();
const endpoint = await config.getEndPoint('service-name');

console.log('Host: ' + endpoint.host);
console.log('Port: ' + endpoint.port);
```

### Automatic change events

The config module provides two different events that are emitted once a service health or a key-value setting has been changed. This is internally used to update the module's cache but it can also be used to write services, that react on changes in the environment. Smartly written, this can be used to change a service's configuration without restarting it.

```JS
const config = require('@opuscapita/config');

await config.init();

config.on('endpointChanged', (serviceName, endpoints) => console.log(serviceName, endpoints));
config.on('propertyChanged', (key, value) => console.log(key, value));
```

---

### Requesting multiple keys

In addition to single-key-requests, the config module provides **two different **methods** for **multi-key-requests**.

1. Key-prefixing (like paths).
2. List of keys.

#### Keys by prefix

Prefixing allows you to recursively fetch consul keys and their corresponding values by simply passing a **prefix** and the **recursive parameter** to the **getProperty()** method of the config module. After all keys have been retrieved successfully, the resulting promise contains an object in which the (full) consul keys represent the actual keys and their values represent the actual values inside consul.

```JS
const config = require('@opuscapita/config');

await config.init();

await Promise.all([
	config.setProperty("path/to/key1", "value1"),
	config.setProperty("path/to/key2", "value2"),
	config.setProperty("path/to/key3", "value3")
]);

const values = await config.getProperty("path/", true);

console.log(values);

/* Should output:
{ 'path/to/key1': 'value1',
  'path/to/key2': 'value2',
  'path/to/key3': 'value3' }
*/
```

#### Keys by list

The config module allows passing an **array** of **keys** or **prefixes** (but not mixed!) to the **getProperty()** method. After all keys have been retrieved successfully, the resulting promise contains an array of consul values each at the corresponding position of their input keys.

```JS
const config = require('@opuscapita/config');

await config.init();

await Promise.all([
	config.setProperty("path/to/key1", "value1"),
	config.setProperty("path/to/key2", "value2"),
	config.setProperty("path/to/key3", "value3")
]);

const values = await config.getProperty([ "key1", "key2", "key3" ]);

console.log(values);

/* Should output:
[ 'value1', 'value2', 'value3' ]
*/
```

---

### Data encryption

By using the **getPassword()** and **setPassword()** methods, the config module is capable of encrypting and decrypting data retrieved and or stored with this methods. It also exposes the **encryptData()** and **decryptData()** methods, which can be used to encrypt small amounts of local data.

The file storage of the encryption key can be configured using the **serviceSecretPath** property of available through the config object [.DefaultConfig](#default-configuration). This feature is mainly designed to use docker secrets but can of course be adjusted to any other key path.

**Notice:** *If the key path was not found at the configured location, a warning is emitted to the console and the key 'default' is used.*

---

### Default configuration

The default configuration object provides hints about what the module's standard behavior is like. It is mostly recommended to leave most settings as they are and treat them more as general conventions to a common structure
in order to maintain a common setup across different services. For further details, please have a look at the [wiki](https://github.com/OpusCapita/config/wiki).

```JS
{
	host : 'consul',
	port : 8500,
	retryCount : 50,
	retryTimeout : 1000,
	logger : null,
	serviceSecretPath : `/run/secrets/${ConfigClientBase.serviceName}-consul-key`
}
```