node-etc
Configuration loader for node.js applications.
Idea
Your application probably needs to load configuration from multiple sources and make them available as one object. Etc is here to help!
Etc provides a fairly complete API for loading configuration from a
variety of sources, however, its been engineered to easily load config from
(in order of precedence): argv, environment, files in ./etc, package.json, and
defaults. Etc. also supports a simple plugin system so new file parsers or other
sources of configuration can be handled.
Examples
Easy Mode
var conf = require('etc')().all().toJSON();Easy Mode done manually
var etc = require('etc')();
etc
.argv()
.env()
.etc()
.pkg();
var conf = etc.toJSON();Load configuration from argv, env, a file, and defaults.
var etc = require('etc')();
etc.argv();
etc.env();
etc.file('/path/to/you/file/config.json');
etc.add({
my: 'defaults'
});
var conf = etc.toJSON();Load configuration from /etc/myapp/*
var etc = require('etc')();
etc.folder('/etc/myapp');
var conf = etc.toJSON();Work with configuration using deliminated keys
var etc = require('etc')();
etc.add({
host: 'localhost',
port: 3000,
meta: {
title: 'Cool title'
}
});
console.log(etc.get('meta:title'));
// Cool title
etc.set('meta:description', 'This is a really cool app');
console.log(etc.get('meta'));
// { title: 'Cool title',
// description: 'This is a really cool app' }API
require('etc')([delim])
Etc exports a factory function the creates instances of Etc objects. You can
optionally specify the key delimiter to use (defaults to :)
etc.get(key)
Fetch a value from the configuration stack. Keys can be simple strings or
deliminated strings such as db:host, which will dive into the configuration
to grab a nested value.
etc.set(key, value)
Set a new configuration value. Primitives will override exsting values whereas Objects and Arrays will merge. The key can be a simple string or a deliminated string. (Chainable)
etc.reset(key, value)
Set a configuration value, overriding whatever was there. The key can be a simple string or a deliminated string. (Chainable)
etc.clear(key)
Clear the configuration stored under a given key. The key can be a simple string or a deliminated string. (Chainable)
etc.toJSON()
Returns all of the configuration, deep-merged into a single object.
etc.use(plugin, options)
Attach an etc plugin. See more below. (Chainable)
etc.all()
Alias for etc.argv().env().etc().pkg() (Chainable)
etc.argv()
Parses argv using optimist and adds it to the configuration. (Chainable)
etc.env(prefix [app], delim [_])
Adds any environment variables that start with the prefix (defaults to 'app_') to the configuration. The prefix is stripped from the key. (Chainable)
etc.add(obj)
Add configuration from an object literal. (Chainable)
etc.file(filePath, [nameed])
Add configuration from a file. A suitable parser must be registered
in etc.parsers ('.json' and '.js' supported by default). If named is true
then the extension will be stripped from the filename and the contents will
be added nested under that name.
For example, if your filename is /path/to/conf/db.json, then the configuration
will be added like:
{
"db": { [contents of db.json ] }
}
(Chainable)
etc.folder(dir)
Loops through the files in dir and adds them to the configuration.
All files will be added with named=true (see etc.file()), except for one
special case when the filename is config.*. (Chainable)
etc.pkg()
Try to find the local package.json for the consumer of etc and
look for an etc key in it. If it exists then add the contents to the
configuration.
Example:
{
"name": "etc-example",
"description": "Etc example",
"main": "example.js",
"dependencies": {
"etc": "*"
},
"etc": {
"db": {
"host": "localhost",
"port": 3000
}
}
}
(Chainable)
etc.etc()
Look for [app root]/etc (based on location of package.json) and
load it using etc.folder(). (Chainable)
etc.reverse()
By default, each call to etc that adds more configuration pushes it on the
bottom of the stack. If you wish to unshift conf onto the top of the stack
instead you can call etc.reverse() followed by any other etc commands.
Until you call etc.reverse() again all subsequent etc methods will continue
to unshift.
Plugins
Etc supports a simple plugin system, primarily useful for adding new file
parsers. Plugins should implement an attach method like so:
exports.attach = function(options) {
options = options || {};
// Plugin will be attached with the scope set to an etc instance.
var etc = this;
etc.parsers['xml'] = xmlparser;
}
function xmlparser(filePath) {
// Parse the file and return an object literal.
}etc-yaml
Support for YAML configuration files can be added via etc-yaml.
var etc = require('etc'),
path = require('path'),
conf = etc();
conf.use(require('etc-yaml'));
// Load a yaml file.
conf.file(path.join(__dirname, 'config.yaml'));
// Print the config.
console.log(conf.toJSON());etc-redis
Maybe eventually if I need it :) (or make it yourself).
Credits
Inspired by dominictarr/rc and dominictarr/config-chain, but with deep-merging and less trolling in the README :)
Developed by Terra Eclipse
Terra Eclipse, Inc. is a nationally recognized political technology and strategy firm located in Aptos, CA and Washington, D.C.
License: MIT
Copyright (C) 2015 Terra Eclipse, Inc.
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.