CONMAN

Conman is a plugabble configuration management library.

• Centralize: Add as many sources in the order you prefer to your config. You can use existing sources or define your own.

• Dependable: You are guaranteed the sources are built in order from first to last, overriding any overlapping key. Your configuration can be stored in a file, for persistence and audibility.

• Refreshable: Based on a TTL, the config rebuilds in the background, or you can trigger a rebuild manually at any point in time.

Getting Started

// Require conman
const Conman = require('@highly-attractive-people/conman');

// Require the sources you will need in your config
const s3 = require('@highly-attractive-people/conman-s3-source');
const memory = require('@highly-attractive-people/conman-memory-source');

// if your source requires it initialize it
const s3Source = s3({ Bucket: 'Your Bucker' });
const memorySource = memory({ key: 'value' });

const conman = Conman({ ttl: 1000 * 60 * 15 }) // Create a new instance and initialize conman with your options
conman
  .addSource(s3Source) // add all the sources you need by priority
  .addSource(memorySource) // if a key exists in s3Source and memorySource, memorySource will take precedence
  .build() // returns a promise that re$solves when the build process is completed
  .then(config => {
    const key = conman.get('key'); // retreive a key from the store
    // initialize your app, for example a http server
    let requestHandler = function(request, response) {
      if (request.url === '/') {
        conman.build(); // you can rebuild the config at demand
        response.end('👋 BYE');
      }
    };
    let server = http.createServer(requestHandler);

    server.listen(3000);
  });

API

initialize

conman(options) initialize conman with the given options. This is required before you can build or get a value from conman

Options

| Options | Description | Type | Default | | ------------- | ------------------------------------------------------------------------------ | ------- | ------------------------------- | | ttl | time in microseconds to rebuild the config. if set to 0 no rebuild is schedule | number | 60000( 10 minutes) | | logEnabled | if conman should log info and errors | boolean | false | | logger | object that contains at least a log and error function for logging | object | console | | useFile | should it write the config to file and read from it if it exists | boolean | true | | cacheFileName | name of the cache file with the built config | string | YOUR_APP_ROOT/conman.cache.json |

addSource

conman.addSource(source) adds a source to conman. The source should at least contain a build function and a type.

build

conman.build() Build the sources added by the addSource method in order from all the added sources and returns promise the resolves when the build is completed and schedules a new build base on the ttl option. If ttl is 0 a new built is NOT schedule.

If useFile option is true, it will try to read a cache file and write the new config to the cache file. The cache file has the following format:

• lastModified: timestamp when the file was created,
• data: configuration object

  {
    "lastModified": 498787200000,
    "data": {
      "key": "value"
    }

if lastModified exceeds the TTL the data will be ignored and the config will be rebuilt base on the sources

get

conman(key) gets a single key, an array of keys, or the complete config from the configuration object. If you want to retrieve a nested key add a . between each key Examples, if your config looks like:

{
  "my": {
    "precious": {
      "key": "value"
    }
  },
  "another": "another value"
}

to retrieve a key

const key = conman.get('my');
// returns { "precious": "key": "value } }

to retrieve a nested key

const key = conman.get('my.precious.key');
// returns "value"

to retrieve several keys

const key = conman.get(['my.precious.key', 'another']);
// returns ["value","another value"]

to retrieve the complete config file

const key = conman.get();
/* returns
  {
    "my": {
      "precious": {
        "key": "value"
      }
    },
    "another": "another value"
  }
  */

getObfuscate

conman.getObfuscate(key, options) behaves exactly as conman.get but returns an obfuscated version of the value.

| Options | Description | Type | Default | | ------------- | ------------------------------------------------------------------------------ | ------- | ------------------------------- | | percentage | percentage of the values that should be obfuscated (replaced by the character option | float | 0.5 | | separator| how to divide the value that will be obfuscated | string | '' (empty string) | | position | What part of the value to obfuscate start or end | string | end | | character | what character should be used to obfuscate the value | string | '*' |

Examples, if your config looks like:

{
  "my": {
    "precious": {
      "key": "value"
    }
  },
  "another": "another-value"
}

if you retreive a string value

const key = conman.getObfuscated('my.precious.key');
// returns "***ue"

if you retrieve an object value

const key = conman.getObfuscated('my.precious');
// returns { "**y": "***ue" }

if you separate by -

const key = conman.getObfuscated('another', { separator: '-' });
// returns "*******-value"

stop

conman.stop() stops the rebuilt interval schedule base on the TTL

reset

conman.reset() clears all the sources, the configuration cache and resets all defaults options

Creating your own source

A source can be as simple as an object that contains a build and type properties.

Source interface

• build(mandatory): a function that returns an object or a promise that returns an object. The build method receives the config built from the sources until that point.
• type(mandatory): a string which identifies the type of source
• name(optional): in case you want to identify each instance of your source you can include a name. If a name exists it would be used instead of the type

Example

const source = (obj, { key, name } = {}) => {
  return {
    build(config) { // recieves the config up until that point
      if (config.extra) {
        return { ...obj, extra: config.extra };
      }
      return obj;
    },
    type: 'syncSource',
    key,
    name
  };
};