Why Blueconfig ?
- Merge several config in one;
- Support environmental variables and Command-line arguments;
- Validate your config with your schema;
- Customize your schema and your validation (with custom format, type and type converter);
- Use your own file format (JSON, JSON5, YAML, TOML, XML...); (JSON5 allows comment)
- Only 3 dependancies (Blueconfig 7.0 will have only 2 dependancies).
Install: npm install blueconfig
Exemple
Schema
# Schema <blueconfig.js.org>
# database.yml
db:
name:
# db.name
format: 'String'
default: ''
password:
# db.password
format: 'String'
sensitive: true
required: true
env: PWD
host:
# db.host (require https://www.npmjs.com/package/blueconfig-format-with-validator)
format: 'ipaddress'
default: '127.0.0.1'
port:
# db.port
format: 'port'
default: 80
arg: 'port'
Code
config.js:
const yaml = require('yaml')
const blueconfig = require('blueconfig')
const blueconfigValidatorFormat = require('blueconfig-format-with-validator')
// add format with validator ( https://www.npmjs.com/package/validator )
blueconfig.addFormat(blueconfigValidatorFormat.ipaddress)
// add YAML parser
blueconfig.addParser([
{ extension: ['yml', 'yaml'], parse: yaml.parse }
])
// prepare config with schema.yml (and debug entries: opts.env)
const config = blueconfig('schema.yml', {
env: { PWD: 'football' } // opts.env: Replace process.env
})
// merge data
config.merge({ db: { name: 'example-db' } }, 'data')
// config.merge(['./config.yml', './prod.yml'], 'file')
// validate
config.validate()
module.exports = config // or config.getProperties()
console.log(config.toString())
// Debug output : { "db": { "name": "example-db", "password": "[Sensitive]", "host": "127.0.0.1", "port": 80 } }
server.js:
const config = require('./config.js')
const db = require('db').connect(config.get('db.host'), config.get('db.port'), config.get('db.password'), function () {
console.log('connected on ' + config.get('db.name'))
})
Blueconfig properties
- Type information: the
format
property specifies either a built-in blueconfig format (ipaddress
,port
,int
, etc.) or it can be a function to check a custom format. During validation, if a format check fails it will be added to the error report. - Default values: Is a default value before this value will be overwritten by another getter.
- Environmental variables: If the variable specified by
env
has a value, it will overwrite the setting's default value. An environment variable may not be mapped to more than one setting. - Command-line arguments: If the command-line argument specified by
arg
is supplied, it will overwrite the setting's default value or the value derived fromenv
. - Sensitive values and secrets: If
sensitive
is set totrue
, this value will be masked to"[Sensitive]"
whenconfig.toString()
is called. This helps avoid disclosing secret keys when printing configuration at application start for debugging purposes.
Schema parsing behavior
Coercion
Blueconfig will automatically coerce environmental variables from strings to their proper types when importing them.
For instance, values with the format int
, nat
, port
, or Number
will become numbers after a straight forward
parseInt
or parseFloat
.
Validation
Often developpers use tools to detect mistake oversight (like eslint
). Validate function do the same thing. In order to help detect misconfigurations, blueconfig allows you to define a format for each setting. By default, blueconfig checks if the value of the property has the same type (according to Object.prototype.toString.call
) as the default value specified in the schema. You can define a custom format checking function in the schema by setting the format
property.
Blueconfig provides several predefined formats for validation that you can use. Most of them are self-explanatory:
*
- any value is validint
port
windows_named_pipe
port_or_windows_named_pipe
nat
- positive integer (natural number)
You can find other format here.
If format
is set to one of the built-in JavaScript constructors, Object
, Array
, String
, Number
, RegExp
, or Boolean
, validation will use Object.prototype.toString.call to check that the setting is the proper type.