merge-config
Merge multiple configuration sources: configuration files (json and yaml), command-line arguments, and environment properties.
It is inspired on nconf library, offering a compatible API. However, there are some important differences:
- The order of preference is reversed. For example, the default values have to be merged before the custom values so that custom values overwrite the default ones.
- Support for multiple instances. It is possible to handle several configurations (e.g. to handle the configuration of several plugins independently).
- Both json and yaml formats are supported when merging configuration files.
- It is possible to merge a directory of configuration files, merging each configuration file alphabetically.
- JSON files are parsed with hjson to support comments.
- The environment variable names are converted into camelCase when merging them into the configuration. The goal is to have a common notation with keys in JSON documents.
This module works with a single configuration object. This configuration object is updated with each merge (with preference for the last merge over the first one). The recursive merge is implemented with lodash. This approach is useful to merge a default configuration with a custom configuration where only the configuration properties to be modified are included.
For example, with the following default configuration:
serverPort: 4070baseLocationUrl: https://telefonica.combasePath: /samplelogFormat: jsondatabase: uri: "mongodb://localhost:27017/sample" options: db: bufferMaxEntries: 0 config: defaultLimit: 100 maxLimit: 1000
To only change the database URI, just merge the following configuration file:
database: uri: "mongodb://mongodb-1:27017/sample"
Installation
npm install merge-config
Basic usage
var Config = ; // Create a config instancevar config = ; // Add a default configuration file (at __dirname/config/config.json)config;// Add all the JSON files in config directory (added in alphabetically order)config;// Add a command-line argument.config;// Add an environment variable (LOG_LEVEL).config; // Get the whole merged configurationconsole;// Get a single configuration propertyconsole;
API
new Config(options)
Constructor of a configuration instance.
var config = ;
It is possible to specify the delimiter when using keys that refer to an element in the hierarchy of the configuration object. By default, the delimiter is :
to keep compatibility with nconf. It is possible to change the delimiter:
var config = delimiter: '.';
get(path)
Retrieve the configuration.
// Get the whole merged configuration as an objectconfig;
It is possible to get a specific element in the configuration object:
// Get the whole merged configuration as an objectconfig;
set(path, value)
Set a value (string, number, object, array).
// Get the whole merged configuration as an objectconfig;
merge(...sources)
Merge a set of sources with the configuration object. These sources must be objects.
// Get the whole merged configuration as an objectconfig;
env(whitelist)
Load the environment variables into the configuration.
// Add all environment variables into merged configurationconfig;
It is possible to restrict which environment variables are to be added to the configuration with optional parameter whitelist
(array of strings).
// Add only environment variables: LOG_LEVEL and PORTconfig;
The keys from environment variables are transformed into camelCase to keep coherence with JSON format.
argv(whitelist)
Load the command-line arguments into the configuration.
// Add all command-line arguments into merged configurationconfig;
It is possible to restrict which command-line arguments are to be added to the configuration with optional parameter whitelist
(array of strings).
// Add only environment variables: logLevel and portconfig;
file(path)
Loads a configuration file (if path targets a file), a set of configuration files located in a directory (if path targets a directory), or raises an error (if path is invalid).
NOTE: If path targets a directory, the library merges any configuration file located in the directory, in alphabetical order, and without subdirectory recursion.
It support json and yaml configuration files which are identified by the file extension. JSON configuration files are parsed with hjson format to support comments in the JSON document.
License
Copyright 2015 Telefónica Investigación y Desarrollo, S.A.U
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.