milieu
v2.0.0
Published
A config loader in the spirit of rc with a few additional features
Downloads
76
Maintainers
Readme
Milieu
One could say it is one's milieu that shapes their future
Install with NPM
npm install milieu
Introduction
Milieu is a config loader in the spirit of rc It shares the same features as RC, but goes a few steps further.
Milieu loads config values from argv flags, environment variables, and config files. The values are compiled into a single config object which you can use in your application. You can trace the sources of these values using Milieu's explain feature.
Milieu can parse JSON config files out of the box. You can also use INI and YAML files by installing the optional dependencies ini and/or js-yaml modules.
The word milieu is defined as the physical or social setting in which people live or in which something happens or develops.
var milieu = require('milieu');
var config = milieu('application-name', {
server: {
port: 8001
},
mongo: {
url: 'mongodb://localhost'
}
});
Milieu Compile Order
Milieu looks in the following places and compiles a config by merging upward through the following sources. Items highest in the list get the highest priority, and override config values in the sources below.
- argv flags - Ex.
--test--my-key val
becomesconfig.test.myKey === 'val'
in the config. Anything after -- is ignored. - environment variables - Ex.
APPLICATION_NAME__TEST__MY_KEY="val"
becomesconfig.test.myKey === 'val'
- config files (replace {appname} with the name of your application) (Accepts JSON, INI, or YAML) (File extensions are optional)
- ~/.{appname}rc
- ~/.{appname}/config
- ~/.config/{appname}
- ~/.config/{appname}/config
- /etc/{appname}rc
- /etc/{appname}/config
- /usr/local/etc/{appname}rc
- /usr/local/etc/{appname}/config
- ./.{appname}rc
- ../.{appname}rc
- ../../.{appname}rc
- ../../../.{appname}rc
- ...
Milieu Templating and Type Casting
Milieu provides both file and environment variable templating. It also provides syntax for type casting. Below are a few examples.
To load values from a file use the $(path/to/file)
syntax. If the path is not
absolute, it will be relative to the current working directory. You can use
these tokens as many times as you need within a single value.
var config = milieu('application-name', {
specialFile: 'part1: $(path/to/specialFile-part-1.txt)\npart2: $(path/to/specialFile-part-2.txt)'
});
To load values from environment variables use the ${VAR_NAME}
syntax. You can
use these tokens as many times as you need within a single value.
var config = milieu('application-name', {
secretTokens: '1:${SECRET_TOKEN_1}2:${SECRET_TOKEN_2}3:${SECRET_TOKEN_3}'
});
Type casting can be achieved with filters. To cast a value simply add the type
name and a colon to the beginning of your string. Types supported are number
and boolean
. JSON can also be parsed using json
as the type.
var config = milieu('application-name', {
secretNumber: 'number:${SECRET_NUMBER}'
secretBool : 'boolean:${SECRET_BOOL}'
secretObj : 'json:${SECRET_JSON}'
});
Milieu Explain
Milieu has a feature called explain. There are explain two methods;
config.explain()
and config.printExplainTable()
. config.explain()
returns
an object indicating the origin of each config value.
config.printExplainTable()
prints a table to stdout which can be used
to inspect your config from the cli. This is great for understanding how your
configuration was resolved, and can be helpful for debugging production systems.
Lets suppose we have a config for our server at /etc/application-name/config
.
In it we set the value of server.port
and nothing else. We also execute our
application below passing the flag --debug true
. Our explanation object will
contain the origin of each config key as shown below.
var milieu = require('milieu');
var explanation = milieu('application-name', {
server: {
port: 8001
},
mongo: {
url: 'mongodb://localhost'
},
debug: false
}).explain();
explanation === {
server: {
port: '/etc/application-name/config'
},
mongo: {
url: 'default'
},
debug: 'flag'
}
If you wish to generate a table on the command line instead of working with an
explanation object, call config.printExplainTable
.
var milieu = require('milieu');
// prints table to stdout
milieu('application-name', {
server: {
port: 8001
},
mongo: {
url: 'mongodb://localhost'
},
debug: false
}).printExplainTable();
API Docs
milieuFactory
milieuFactory(applicationName String, defaultConfig Object, opts Object) -> config Object
Internally creates an instance of Milieu instance and returns it.
Accepts a applicationName
and a defaultConfig
. It also
optionally accepts an opts
object to configure Milieu. See
Milieu's load order to understand how the config object
is resolved. These does refer to milieuFactory as milieuFactory
but It is
recommended that the name milieu
be used instead as most users will not
interact with Milieu
constructor or it's instance directly.
Milieu Options
opts.argv
Pass a custom argv array. Defaults toprocess.argv
.opts.env
Pass a custom env object. Defaults toprocess.env
.opts.platform
Pass a custom platform string. Defaults toprocess.platform
.opts.unsetEnvValues
If true, deletes env values that belong to the config. Defaults tofalse
.opts.parseValues
If true, parses strings'null'
,'true'
,'false'
, and'NaN'
intonull
,true
,false
, andNaN
. Defaults totrue
.
var milieuFactory = require('milieu');
var config = milieuFactory('application-name', {
defaultKey: 'value'
});
Milieu
new Milieu(applicationName String, defaultConfig Object, opts Object) -> Milieu
The Milieu constructor. Accepts the same arguments as milieuFactory.
var Milieu = require('milieu').Milieu;
var milieu = new Milieu('application-name', {
defaultKey: 'value'
});
Milieu#toObject
milieu.toObject() -> config Object
Resolves the config object. Use this method to retrieve your config if using a Milieu instance directly.
var Milieu = require('milieu').Milieu;
var milieu = new Milieu('application-name', {
defaultKey: 'value'
});
var config = milieu.toObject();
Milieu#explain
milieu.explain() -> explanation Object
Returns an explanation object.
var Milieu = require('milieu').Milieu;
var milieu = new Milieu('application-name', {
defaultKey: 'value'
});
var explanation = milieu.explain();
Milieu#printExplainTable
milieu.explain() -> explanation Object
Prints an explanation table to stdout.
var Milieu = require('milieu').Milieu;
var milieu = new Milieu('application-name', {
defaultKey: 'value'
});
// prints to stdout
milieu.printExplainTable();