confirge

Flexible configuration!


Keywords
config, configuration, flexible, easy, json, yaml, variable, variables, deep-extend, extend, merge
License
GPL-2.0+
Install
npm install confirge@0.4.0

Documentation

confirge

NPM Version Linux Build Windows Build Test Coverage Dependency Status

Flexible configuration!

Confirge aims to make configuration of modules easy and flexible. It supports different ways of creating config objects or reading config files. To make things even more flexible you can make use of a simple 'variable template system' to replace often used strings (eg. directories/names) in your config objects.

Installation

npm install --save confirge

How to use

var confirge = require('confirge');

// basic usage, load from a file (YAML or JSON)
var config = confirge('config.yml');

// load from a file, returned by a function
config = confirge(function()
{
    return 'config.json';
});

// extend objects
config = confirge.extend(config, {
    'example': '%var1% and %var2%'
});

// will replace vars inside the config obj, eg. %var1%, %var2%
// this will result in { 'example': 'value1 and value2' }
config = confirge.replace(config, {
    'var1': 'value1',
    'var2': 'value2'
});

API


confirge(source)

Handles a string (file path), function, or object source and returns an object.

argument type description
source string, function or object The source to read from.

When passing a string, it is assumed it is the path to a file. When not absolute, the path will be used relative from process.cwd(). A function will be executed and it's result will be used. This result can be one of the accepted values, string, function or object. Objects are just returned the same as they came in.


confirge.read(file, extensions)

Reads a file and returns an object. Returns false on failure. When a function is passed, it is assumed it returns the path to a file wich should be read.

argument type description
file string or function The source to read from.
extensions array Optional alternative file extensions to read.

When passing a string, it is assumed it is the path to a file. When not absolute, the path will be used relative from process.cwd(). A function will be executed and it's result will be used. This result can be one of the accepted values, string or function.

When reading the main file failes and the optional parameter extensions is passed, the function will try to read alternative files with the specified extensions from this array. Example:

confirge.read('.awesome-config', ['json', 'yml', 'js']);

When .awesome-config does not exist, it will try to read a file with any of the alternative file extensions, in order of the values in the array: .awesome-config.json then .awesome-config.yml and finally .awesome-config.js. The first file that succeeds will be returned.


confirge.replace(source, vars)

Loops through all (nested) source values and replaces any found variables.

argument type description
source object or array The function will loop through the values and replace any found vars (eg. %dir%) for their values. Multilevel objects and arrays are supported.
vars object An object with variables. Multilevel objects are supported.
var source = {
    'config-option':   '%some-var%',
    'config-option2':  '%another.var%',
    'other-option':    true,
    'supported-types': ['object', '%types.a%']
};

var vars = {
    'some-var':    'some-value',    // %some-var%
    'another.var': 'another value', // %another.var%
    'types':       { 'a': 'array' } // %types.a%
};

var result = confirge.replace(source, vars);

// the result will be:
result = {
    'config-option':   'some-value',
    'config-option2':  'another value',
    'other-option':    true,
    'supported-types': ['object', 'array']
};

confirge.extend(source...)

Extend a base object with the given sources. These sources are handled by the main confirge function and are only used if objects are returned.

argument type description
source string, function or object A base object.
... string, function or object A source to extend the base object with.