timkelty / node-get-config

Automagically builds a config object used throughout an application.

get-config

get-config is a Node.js library automagically building a config object used throughout an application.

var config = require('get-config').sync(__dirname + '/config');

• Both callback and promises (via Bluebird) styles are supported.
• Both asynchronous and synchronous (via deasync) functions are supported.
• get-env is used to parse process.env.NODE_ENV.

Supported Formats

• INI: .ini, .cfg, .conf → (requires npm install ini)
• JS: .js
• JSON: .json
• TOML: .toml → (requires npm install toml)
• XML: .xml → (requires npm install xml2json)
• YAML: .yaml, .yml → (requires npm install js-yaml)

How It Works

Take a look at the example structure.

It assumes you have a separate directory somewhere in your project that is devoted to static config values that are further manipulated and used by an application. It reads all files ending with one of the supported format extensions then constructs a config object for you using filenames with their extension dropped (ex: server.json or server.yaml becomes server) as the key and the loaded content from the file as value during the construction of the config object. You can have one or more of these files with any choice of file format among the supported list, and you can mix them as well.

For example, if you placed both client.json and server.yaml files in config/, it would return a config object looking like this:

{
  client: <content-from-client.json>,
  server: <content-from-server.yaml>
}

It also assumes you have an optional override directory (usually to override default values with environment-specific values based on process.env.NODE_ENV). The override directory path is a relative path to the (default) config directory. If you pass dev as the override directory, the library will read all the config files under config/dev/ in the same way explained above for the (default) config directory, then the values will be merged with the default config object.

For example, if you placed both client.json and server.yaml files in config/ and client.xml in config/dev, it would return a config object looking like this when you run your application in the dev environment (it would return the object same as the above example for the rest of environments):

{
  client: <content-from-client.json merged with content-from-config/client.xml>,
  server: <content-from-server.yaml>
}

Imagine you defined multiple environment names within your application and you created override directories for each of these environments under config/ with environment-specific config values organized into separate files (using the environment name as the override directory name). All you need to do now is to let the library know what environment you are in by passing the environment name as override directory path to let the library take care of environment-specific config object loading.

Check out get-env library for delegating NODE_ENV environment variable loading and environment definitions.

Installation

$ npm install get-config

You also need to install parser for your choice of formats:

• INI: npm install ini
• JSON: included
• TOML: npm install toml
• XML: npm install xml2json
• YAML: npm install js-yaml

Usage

Asynchronous

var env = require('get-env')();

// Option 1: Callback
require('get-config')(__dirname + '/config', env, function (err, config) {});

// Option 2: Promises (using Bluebird)
require('get-config')(__dirname + '/config', env)
  .then(function (config) {})
  .catch(function (err) {});

env is an optional parameter. If you do not pass the env value, it internally calls require('get-env')() then uses that value for you.

It is recommended to stay with get-env library's convention (dev and prod) to structure your config directory. If you follow the structure convention, your code can be simplified as the following:

// Option 1: Callback
require('get-config')(__dirname + '/config', function (err, config) {});

// Option 2: Promises (using Bluebird)
require('get-config')(__dirname + '/config')
  .then(function (config) {})
  .catch(function (err) {});

Synchronous

Replace require('get-config') with require('get-config').sync in the usage example above to use this library synchronously.

var config = require('get-config').sync(__dirname + '/config');

// OR

var env = require('get-env')();
var config = require('get-config').sync(__dirname + '/config', env);

Credits

Special thanks to:

• get-env: NODE_ENV parser
• ini: INI parser
• js-yaml: YAML parser
• toml: TOML parser
• xml2json: XML parser
• deasync: synchronous function wrapper

See the contributors.

License

The MIT License (MIT)

Copyright (c) 2014 Pilwon Huh

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.