@highly-attractive-people/conman

1.1.0 • Public • Published

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
  };
};

Readme

Keywords

none

Package Sidebar

Install

npm i @highly-attractive-people/conman

Weekly Downloads

0

Version

1.1.0

License

ISC

Unpacked Size

39.9 kB

Total Files

11

Last publish

Collaborators

  • helior
  • jepz20