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: 4070
baseLocationUrl: https://telefonica.com
basePath: /sample
logFormat: json
database:
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 = require('merge-config');
var config = new Config();
config.file(path.join(__dirname, 'config', 'config.json'));
config.file(process.env.CONFIG_DIR);
config.argv(['logFormat']);
config.env(['LOG_LEVEL']);
console.log("Merged configuration: %j", config.get());
console.log("Log level: %s", config.get('logLevel'));
API
new Config(options)
Constructor of a configuration instance.
var config = new Configuration();
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 = new Configuration({delimiter: '.'});
get(path)
Retrieve the configuration.
config.get();
It is possible to get a specific element in the configuration object:
config.get('database:uri');
set(path, value)
Set a value (string, number, object, array).
config.set('database:uri', 'mongodb://mongodb-1:27017/sample');
merge(...sources)
Merge a set of sources with the configuration object. These sources must be objects.
config.merge({
database: {
uri: 'mongodb://mongodb-1:27017/sample'
}
});
env(whitelist)
Load the environment variables into the configuration.
config.env();
It is possible to restrict which environment variables are to be added to the configuration with optional parameter whitelist
(array of strings).
config.env(['LOG_LEVEL', 'PORT']);
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.
config.argv();
It is possible to restrict which command-line arguments are to be added to the configuration with optional parameter whitelist
(array of strings).
config.argv(['logLevel', 'port']);
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.