Environmentalist
================

A simple module for configuring your node application. Defaults are provided
and can then be overridden by environment variables.

CI STATUS: https://travis-ci.org/BrandwatchLtd/environmentalist.svg

Usage
-----

A new config object is created using the Config constructor. Pass in your
application defaults and the environment object.

    var Config = require('environmentalist');
    var defaults = {DATABASE_URL: 'postgres://user:pass@localhost/database'};
    var config = new Config(defaults, process.env);

    config.get('DATABASE_URL');

You can load your defaults any way you like, JSON is one example, but we prefer
to use a plain old module. This allows you to have local variables and comments
in your config file.

    var defaults = require('./config.json');
    var defaults = require('./config');
    var defaults = require('./package.json').config;

Retrieving Settings
-------------------

The .get() method can be used to retrieve values. This takes a key (always
uppercase) and an optional fallback. If no fallback is provided the method
will raise an error ensuring that you always have a value.

    config.get('REQUIRED_VALUE');
    config.get('OPTIONAL_VALUE', 'fallback string');
    config.get('MISSING_VALUE'); // Will raise an Error.

Overriding defaults
-------------------

Defaults are overridden using environment variables. For example you can change
the DEFAULT_VALUE using the following:

    $ DEFAULT_VALUE=new node app.js

Then in the app:

    config.get('DEFAULT_VALUE'); //=> 'new'

All values passed by environment variables are treated as strings except for
integers and booleans which will be coerced by the config into JavaScript
values. So ENABLE_EMAIL=true will return a true literal.

NODE_ENV
--------

The config is also aware of the NODE_ENV variable and can be used to check
which environment the code is running in. There are four environments supported.

    config.isProduction();
    config.isDevelopment();
    config.isTest();
    config.isIntegration();
    config.isTestOrIntegration();

VERSION
-------

It's often useful to be able to access the current version of the app. This
can be provided during instantiation and retrieved with the version() method.

    var config = new Config(defaults, process.env, {
        version: require('./package.json').version
    });
    config.version() //=> '1.0.0'

Configuration
-------------

A number of configuration options can be provided as a third argument to
the constructor:

    var config = new Config(defaults, process.env, {
        prefix: 'MY_APP',
        unprefixed: ['PORT', 'NODE_ENV', 'DATABASE_URL'],
        version: require('./package.json').version
    });

  * prefix:

    This key allows environment variables to be scoped under a namespace:

        $ MY_APP_CONFIG_VAR=override node app.js

    In code:

        var config = new Config({CONFIG_VAR: 'original'}, process.env, {
            prefix: 'MY_APP'
        });
        config.get('CONFIG_VAR'); //=> 'override'

  * unprefixed:

    Common node environment variables can be excluded from the prefix. By
    default PORT and NODE_ENV do not require a prefix to override them.

  * version:

    A version number or string can be provided for use in the app. It can be
    accessed via the special .version() method.

Development
-----------

All package code currently lives in index.js and tests in test/index_test.js.

Development should be done in a separate branch. Branch names should be lower
case and use hyphens to separate words.

All code should have unit tests and pass linting. When ready for review open a
pull request against master.

Testing
-------

Unit tests can be run using npm:

    $ npm test

Tests are located in the test directory and run using Mocha[1] and we use the
standard node assertion library[2] and sinon[3].

[1]: http://visionmedia.github.io/mocha/
[2]: http://nodejs.org/api/assert.html
[3]: http://sinonjs.org/docs/#assertions

Travis CI
---------

We use Travis CI to verify every build. This can be viewed at any time at:

    https://travis-ci.org/BrandwatchLtd/environmentalist

The script runner can be run before push by running:

    $ ./script/cibuild

Coding Style
----------

Code standards are upheld by JSHint[1]. This will check for errors and syntactic
issues in the code. The configuration can be found in the .jshintrc file and
documentation is on the website[2].

JSCS is used to enforce coding style. More details on the rules can be found
on the JSCS webpage[3] and the Crockford styleguide[4]. The linter options
can be found in the .jscsrc and run using:

    $ npm run lint && npm run checkstyle

[1]: http://www.jshint.com
[2]: http://www.jshint.com/docs/options/
[3]: https://github.com/mdevils/node-jscs
[4]: http://javascript.crockford.com/code.html

License
-------

Released under the MIT license. Copyright Brandwatch Ltd 2014