configya
Stupid simple configuration.
What & How
configya
reads the following:
- environment variables
- optional configuration
- defaults hash
Note: you can now provide both a configuration file and a defaults object
Unless you've set a deploy-type
environment variable = 'DEV', configya
will always overwrite keys from a configuration file and defaults hash with duplicates found in the environment.
Key Parsing
configya
parses all sources into an object hierarchy based on _
delimited key names (If camelCase support is desired, see below). For example, if you have a key named RABBIT_BROKER_IP
set to '127.0.0.1', and another named RABBIT_BROKER_PORT
set to 5672, the resulting configuration object will be:
{
rabbit: {
broker: {
ip: "127.0.0.1",
port: "5672"
}
}
}
Note: When using a single _
delimeter, all keys are lower-cased to eliminate the need for guessing games (and capslock)
Camel case is supported when configya detects a double underscore __
in the key. Once found, _
will be treated as a word boundary instead of a nesting separator. If you have a key named SQL__USER_NAME
(notice the single underscore _
between USER
and NAME
) set to 'siteuser', and another named TARGET_SERVER__
set to 'localhost', the resulting configuration object will be:
{
sql: {
userName: "siteuser"
},
targetServer: "localhost"
}
In order to support top level keys with camelCase, you'll need to use a prefix, or start or end your key with __
(as shown above with TARGET_SERVER__
).
Key Prefixing
configya
lets you specify a prefix for your environment variables to be removed when your configuration is created. For example, if you have an environment variable LK_RABBIT_BROKER_PORT
set to 5672, and call configya with the prefix
option var cfg = require( 'configya' )({prefix:'lk'});
, the resulting configuration object will be:
{
rabbit: {
broker: {
port: "5672"
}
}
}
Note: If you are overriding a key that needs camelCase support, be sure to separate your prefix with __
intead of _
: LK__CAMEL_CASE
.
Value Parsing
Under the hood, configya uses JSON.parse
to attempt to parse the values so "true"
and "false"
will become actual booleans, and "123"
will be a number.
The following enviroment variables HOST_CACHE=false HOST_PORT=1234 FONTSIZE=10p
would be parsed as follows:
{
host: {
cache: false,
port: 1234
},
fontsize: "10p"
}
This means you can also use JSON as the value for an environment variable and it will be correctly parsed into an object.
Original Keys
The original keys are technically still stored on the object based on their source.
- _env_ for original environment keys
- _defaults_ for keys coming from a defaults hash
- _file_ for keys coming from a file
Note: These are really here for diagnostic/backwards compatibility. You shouldn't use/rely on them in your code.
Usage
var cfg = require( 'configya' )();
var cfg = require( 'configya' )({prefix: 'lk'});
var cfg = require( 'configya' )({file: './path/to/configuration.json'});
var cfg = require( 'configya' )({
defaults: { RABBIT_BROKER_PORT: 5672 }
});
var cfg = require( 'configya' )({
defaults:{
rabbit: { broker: { port: 5672 } }
},
file: './path/to/configuration.json'
});
var port = cfg.rabbit.broker.port;
Backwards Compatibility
The previous version of configya
accepted multiple arguments of either a string for the file path or an object literal for defaults.
var cfg = require( 'configya' )();
var cfg = require( 'configya' )( './path/to/configuration.json' );
var cfg = require( 'configya' )( { RABBIT_BROKER_PORT: 5672 } );
var cfg = require( 'configya' )( { rabbit: { broker: { port: 5672 } } }, './path/to/configuration.json' );
var port = cfg.rabbit.broker.port;
The original version of configya
used a get
method to retrieve configuration values with the ability to specify a default/fallback if the key were missing. This is technically still supported, but we think the new approach (nested keys) is nicer. Here's an example of the original API:
var config = require( 'configya' )( './path/config.json' );
config.get( 'key' );
config.get( 'key', defaultValue );