configurator-js v0.0.5

configurator-js

Configuration management.

As a new instance of Configurator is created, it loads a configuration file and resolve its expressions, if any. A configuration file can be a JSON file or a YAML file.

Modules and versions

A configuration file can hold configurations for multiple modules, so each one can access its own configs. Also each module can evolve and increase its versions. Sometimes though there is the need to keep the configuration for old modules.

Imagine a situation in that a machine has a module that offers APIs. The API module is then modified to use some other configurations, although you don't want to shut down the old version, but keep both running in parallel. In this case they will need to access different configurations, that is made possible using versions.

A version must be specified with curl braces, like {0.0.1}.

Example:

{
  "module1": {
    "{1.0.0}": {
      "hostname": "localhost",
      "port": 8000  
    },
    "{1.1.0}": {
      "hostname": "localhost",
      "port": 8001  
    }
  },
  "module2": {
  	...
  }
}

A configuration can also be generic, so to be used by multiple modules, as amqp configuration, for example.

Example:

{
  "module2": {
    "{0.0.1}":
  	  ...
  },
  "amqp": {
  	"host": "localhost",
    "port": "5672"
  }
}

Expressions

Expressions are special strings that points to other configurations. Example:

"config1": "@{config2.value2}"
"config2": {
  "value1": "foo",
  "value2": "bar"
}

The expression under config1 will resolve to the config under config2.value2, resulting in the value bar.

There are three types of expression:

Environment expressions

Environment expressions are those with format [[...]] and resolve to environment variables. It can be also specified inside of other types of expression.

Strict expressions

Strict expressions are the ones with format @{...} and will resolve to generic configurations (those whose not belongs to modules configuration).

Module expressions

Strict expressions are the ones with format ${...} and will resolve to configurations related to a module. A module expression must contain ${<module>.<version>.<config_path>}, where:

• module: which module to get the config from. The word $this can be used to use the current module (the one that instantiated the configuration library).
• version: which module version to get the config from. The word $this can be used to use the current version. An sterisk (*) can also be used to use the last version. A version in an expression must be surrounded by [], () or {}. Example: [1.0.0].
• config_path: path to the desired configuration value.

Example:

{
  "apis": {
  	"{1.2.1}": {
  	  "amqp": "@{rabbitMQ}",
      "mainDir": "/opt/apis"
    }
  },
  "rabbitMQ": {
  	"host": "localhost",
    "port": "[[RABBITMQ_PORT]]",
    "logPath": "${$this.$this.mainDir}"
  }
}

In this example, the amqp configuration from the module apis points to the generic configuration rabbitMQ.

The logPath config from the rabbitMQ configuration points to the mainDir config of the current module. If the apis module has loaded the configuration in this case, it will resolve to /opt/apis.

The port attribute from the rabbitMQ module will resolve to the value specified in the environment variable RABBITMQ_PORT.

How to use

In the package.json of your module declare under the dependencies:

npm install --save configurator

The Configurator class can be imported as:

var Configurator = require('configurator');

The constructor receives three parameters (parameters with [] are optional):

• configPath {String} Path to the configuration file that will be used.
• [module] {String} Name of the module to which the configuration belongs.
• [version] {String} Version of the module to which the configuration belongs.

If the module and version parameters are given, then when getting configurations, the configurator will get the config from the given module and version. Both parameters are required if some expression with $this is used in the config file.

Example:

var configurator = new Configurator("/config", "apis", "0.1.0");

A in a more real scenario, the module name and version would be gotten from the package.json file. Example:

var Configurator = require('configurator');
var moduleInfo = require('./package.json');
var configurator = new Configurator(null, moduleInfo.name,
moduleInfo.version);

Getting a config value

A value can be retrieved from the configuration using the get method. It expects three parameters:

• key {String} Path to the configuration value to be retrieved.
• [module] {String} Name of the module to which the configuration belongs. If specified, overrides the module given in the constructor.
• [version] {String} Version of the module to which the configuration belongs. If specified, overrides the version given in the constructor.

The module and version parameters are optional, and can be used when trying to get a configuration from another module. If null is passed (null, not undefined) in the module parameter, a generic configuration is selected.

Example:

Suppose the apis module is trying to get a configuration from the database module. Having the configuration file as:

{
  "apis": {
  	"{1.2.1}": {
  	  "amqp": "@{rabbitMQ}",
      "mainDir": "/opt/apis"
    }
  },
  "database": {
  	"{0.1.1}": {
    	"url": "mysql://localhost:3306"
    }
  },
  "rabbitMQ": {
  	"host": "localhost",
    "port": "5672",
    "logPath": "${$this.$this.mainDir}"
  }
}

The apis module could do:

var amqpConfig = configurator.get("amqp");
var databaseUrl = configurator.get("url", "database", "0.1.1")

In this example, amqpConfig would receive the value under the amqp config of the module apis. The databaseUrl will receive the value under the url config of the module database configuration, whose version is 0.1.1. The version could be just ommited so to use the last version from the database module:

var databaseUrl = configurator.get("url", "database");