Using Config Utilities

Node-config comes with a handy set of utilities necessary for implementing node-config. These utilities are exposed in the config.util object for use in your own applications.

Below is a list of these utilities, in order of general usefulness - your mileage may vary.

extendDeep(mergeInto, mergeFrom..., depth)

Extend an object (and any object it contains) with one or more objects (and objects contained in them).

This does not replace deep objects as other extend functions do, but dives into them extending individual elements instead. If more than one of the extending objects define the same key, then:

• if all the respective values are objects, they are merged recursively by calling the same function.
• if none of the respective values are objects, then the latest one is respected.
• avoid mixing objects and non-objects for the same key as it can lead to unexpected behaviour.

param	type	description
mergeInto	object	The object to merge into
mergeFrom...	object	Any number of objects to merge from
depth	integer	An optional depth to prevent recursion. Default: 20.
(return)	object	The altered mergeInto object is returned

The following example merges the contents of two objects into a new object.

var newObject = config.util.extendDeep({}, baseObject, anotherObject);

cloneDeep(copyFrom, depth)

Return a deep copy of the specified object.

This returns a new object with all elements copied from the specified object. Deep copies are made of objects and arrays so you can do anything with the returned object without affecting the input object.

param	type	description
copyFrom	object	The original object to copy from
depth	integer	An optional depth to prevent recursion. Default: 20.
(return)	object	A new object with the elements copied from the copyFrom object

Example:

var copy = config.util.cloneDeep(fromObject);

equalsDeep(object1, object2, depth)

Return true if two objects have equal contents.

param	type	description
object1	object	The object to compare from
object2	object	The object to compare with
depth	integer	An optional depth to prevent recursion. Default: 20.
(return)	boolean	true if both objects have equivalent contents

Example:

var customerCopy = config.util.cloneDeep(myCustomer);
var same = config.util.equalsDeep(myCustomer, customerCopy); // <-- true
customerCopy.creditLimit = 7000;
var same = config.util.equalsDeep(myCustomer, customerCopy); // <-- false

diffDeep(object1, object2, depth)

Returns an object containing all elements that differ between two objects.

It works best when object2 originated by deep copying object1, then changes were made to object2, and you want an object that would give you the changes made to object1 which resulted in object2.

param	type	description
object1	object	The object to compare from
object2	object	The object to compare with
depth	integer	An optional depth to prevent recursion. Default: 20.
(return)	object	A differential object, which if extended onto object1 would result in object2.

makeImmutable(object, propertyName, propertyValue)

Make a javascript object property immutable (assuring it cannot be changed from the current value).

If the propertyName isn't supplied, all properties of the object are made immutable.

Properties which themselves are objects are called recursively, making sub-objects immutable.

New properties can be added to this (and sub) objects, and those properties will not be immutable unless this method is called after adding the properties.

This operation cannot be undone.

param	type	description
object	object	The object containing the properties to make immutable
propertyName	string | [string]	(optional) Property name (or array of names) to make immutable. If not specified, all properties of the object are made immutable
propertyValue	mixed	(optional) Property value to set the property to before making immutable. Retained for backward compatibility, and for use only when propertyName is not an array.
(return)	object	The original object, with the newly immutable attributes

Example:

var a = {hello:'world'};
config.util.makeImmutable(a);
a.hello = 'there';
console.log ('Sorry, hello is still ' + a.hello);

makeHidden(object, propertyName, propertyValue)

Make an object property hidden so it doesn't appear when enumerating elements of the object.

The property still exists and can be read from and written to, but it won't show up in for ... in loops, Object.keys(), or JSON.stringify() type methods.

param	type	description
object	object	The object containing the property to make hidden
propertyName	string	Name of the property to make hidden
propertyValue	string	(optional) Set the property to this value
(return)	object	The original object, with the newly hidden property

Example:

var a = {hello:'world'};
console.log ('Before hiding: ' + JSON.stringify(a));
config.util.makeHidden(a, 'hello');
console.log ('After hiding: ' + JSON.stringify(a));
console.log ('Hidden, but still there: ' + a.hello);

getEnv(varName)

Get the current value of a config environment variable

This method returns the value of the specified config environment variable, including any defaults or overrides.

Environment variables that you can inspect include NODE_ENV, NODE_CONFIG_DIR, NODE_CONFIG, HOSTNAME, NODE_APP_INSTANCE, and others listed in the environment variables wiki page.

param	type	description
varName	string	The environment variable name
(return)	string	The value of the environment variable

Example:

console.log('Configuration directory: ' + config.util.getEnv('NODE_CONFIG_DIR'));

loadFileConfigs(directory, options)

Reads the given directory using the same conventions as the main config directory (including environment variable reading, except for NODE_CONFIG) and returns an object with the result.

If no directory is given, reads the standard config directory and parses NODE_CONFIG.

This is useful for using with submodules, e.g.

import config from 'config'
const ourConfigDir = path.join(__dirname, 'config')
const baseConfig = config.util.loadFileConfigs(ourConfigDir)
config.util.setModuleDefaults('MyModule', baseConfig)

By default, all sources parsed as part of this operations are added to the global list of configuration Sources, despite not being added to the global configuration.

This may, in turn, increase the memory footprint of your application if the utility is called repeatedly. You can disable this behaviour by passing an options object with the skipConfigSources flag set to true

import config from 'config'
const ourConfigDir = path.join(__dirname, 'config')
const options = { skipConfigSources: true }
const baseConfig = config.util.loadFileConfigs(ourConfigDir, options)
config.util.setModuleDefaults('MyModule', baseConfig)

toObject(config)

Returns a new deep copy of the current config object, or any part of the config if provided.

If config is not provided (undefined), the current config object is dumped in its entirety.

param	type	description
config	object	The part of the config to copy and serialize. Omit this argument to return the entire config.
(return)	object	The cloned config or part of the config

var result = config.util.toObject(config.get('db'));