flex_conf

Flexible configuration file management.

Based on the nconf package, the flex_conf package provides tag-based, hierarchical configuration file loading with atomic object merging. It is possible to register one or more "tags" e.g., env for environment-specific configuration files. These tags can then be used inside the configuration file's filename and/ or in folder names to conditionally load the configuration file.

Installation

Installation is straight forward with npm:

npm install flex_conf

Example

A minimal config module using flex_conf looks like this:

# config.js
const FlexConf = require('flex-conf');

const conf = new FlexConf('configs', {
  tagDefinitions: {
    env: {
      applies: value => process.env.NODE_ENV === value,
      map: (value) => {
        switch (value) {
          case 'dev': return 'development';
          case 'prod': return 'production';
          case 'test': return 'test';
          default: throw Error(`Unknown NODE_ENV in configfile name: '${value}'`);
        }
      },
    },
  },
});

module.exports = conf.final();

We can now create various configuration files inside the configs/ directory that will be parsed based on the value of the NODE_ENV environment variable:

configs/
├── database.env-dev.json
├── database.env-prod.json
└── database.json

For example, NODE_ENV=development would result in the database.env-dev.json file being loaded first, followed by the database.json as it is unconditionally loaded in any case (as no tags are specified).

To access the final configuration object in another module, we simply require the config module:

# example.js
const config = require('./config');

function connect() {
  console.log(`Connection to database '${config.database.username}@${config.database.host}:${config.database.port}'`);
}

connect();

Note: This example is also included in the Bitbucket repository under example/.

API Documentation

FlexConf

FlexConf class, representing the entire config of the config folder

TagDefinition

FlexConf

FlexConf class, representing the entire config of the config folder

Kind: global class

• FlexConf
  • new FlexConf(configFolder, options)
  • .loadConfigFiles()
  • .saveToFile(namespace, [options]) ⇒ string
  • .final()

new FlexConf(configFolder, options)

Create a new configuration instance.

Param	Type	Default	Description
configFolder	string		Path to the folder that holds all configuration files.
options	Object		Configuration options.
[options.tagDefinitions]	Object	{}	Tag definitions.
[options.loadRecursive]	boolean	true	Whether to load sub-folders of the configuration folder recursively.
[options.folderTags]	boolean	true	Whether to parse sub-folder names as tags if applicable.
[options.parseArgv]	boolean	true	Whether to parse command line arguments.
[options.parseEnv]	boolean	true	Whether to parse environment variables.
[options.separator]	string	"'__'"	Seperator for environment variables.
[options.postfix]	string	"'json'"	Seperator for environment variables.
[options.lowerCase]	boolean	true	Whether to lower-case environment variables.
[options.autoload]	boolean	true	Whether to automatically load all configuration files on instantiation.

flexConf.loadConfigFiles()

Load all configuration files inside the root config folder and it's sub-folders if loadRecursive is activated.

Kind: instance method of FlexConf

flexConf.saveToFile(namespace, [options]) ⇒ string

Save a config namespace to a file.

Kind: instance method of FlexConf Returns: string - Path of the saved config file.

Param	Type	Default	Description
namespace	string		Config namespace to save to a file.
[options]	Object	{}	Options object.
[options.filepath]	string		Path to save the config file to, defaults to "[os.tmpdir()]/[namespace].json".
[options.space]	string | number		A String or Number object that's used to insert white space into the output JSON string for readability purposes.
[options.encoding]	string	""utf8""	File encoding, default to "utf8".
[options.flag]	string	""w""	Write operation flags, defaults to "w".
[options.mode]	number	0o600	File permissions, default to read-only for the owner.

flexConf.final()

Return a final configuration object.

Kind: instance method of FlexConf

TagDefinition

Kind: global class

new TagDefinition(name, options)

Create a new TagDefinition instance.

Param	Type	Description
name	string	Name of the tag.
options	Object	Tag options.
[options.applies]	function	Function to check whether the tag value applies -> the configuration file is loaded.
[options.map]	function	Function to transform a tag value before further processing it.
[options.score]	function	Function to compute a score value for the tag.