config 4.0.0 → 4.0.1

package/lib/config.js

@@ -4,24 +4,12 @@
 // http://lorenwest.github.com/node-config
 
 // Dependencies
-const DeferredConfig = require('../defer').DeferredConfig;
 const RawConfig = require('../raw').RawConfig;
-let Parser = require('../parser');
+const { Util, Load } = require('./util.js');
 const Path = require('path');
-const FileSystem = require('fs');
 
-// Static members
 const DEFAULT_CLONE_DEPTH = 20;
-let CONFIG_DIR;
-let NODE_ENV;
-let APP_INSTANCE;
-let CONFIG_SKIP_GITCRYPT;
-let NODE_ENV_VAR_NAME;
-let NODE_CONFIG_PARSER;
-const env = {};
-const configSources = [];          // Configuration sources - array of {name, original, parsed}
 let checkMutability = true;      // Check for mutability/immutability on first get
-const gitCryptTestRegex = /^.GITCRYPT/; // regular expression to test for gitcrypt files.
 
 /**
  * <p>Application Configurations</p>
@@ -99,7 +87,7 @@ const gitCryptTestRegex = /^.GITCRYPT/; // regular expression to test for gitcry
  * </script>
  *
  * @method constructor
- * @return CONFIG {object} - The top level configuration object
+ * @return CONFIG {Object} - The top level configuration object
  */
 const Config = function() {
   const t = this;
@@ -112,7 +100,8 @@ const Config = function() {
   }
 
   // Merge configurations into this
-  util.extendDeep(t, util.loadFileConfigs());
+  _init(FIRST_LOAD);
+  Util.extendDeep(t, FIRST_LOAD.config);
   util.attachProtoDeep(t);
 
   // Perform strictness checks and possibly throw an exception.
@@ -124,30 +113,6 @@ const Config = function() {
  */
 const util = Config.prototype.util = {};
 
-/**
- * Underlying get mechanism
- *
- * @private
- * @method getImpl
- * @param object {object} - Object to get the property for
- * @param property {string|string[]} - The property name to get (as an array or '.' delimited string)
- * @return value {*} - Property value, including undefined if not defined.
- */
-const getImpl= function(object, property) {
-  const t = this;
-  const elems = Array.isArray(property) ? property : property.split('.');
-  const name = elems[0];
-  const value = object[name];
-  if (elems.length <= 1) {
-    return value;
-  }
-  // Note that typeof null === 'object'
-  if (value === null || typeof value !== 'object') {
-    return undefined;
-  }
-  return getImpl(value, elems.slice(1));
-};
-
 /**
  * <p>Get a configuration value</p>
  *
@@ -168,13 +133,13 @@ Config.prototype.get = function(property) {
 
   // Make configurations immutable after first get (unless disabled)
   if (checkMutability) {
-    if (!util.initParam('ALLOW_CONFIG_MUTATIONS', false)) {
+    if (!FIRST_LOAD.initParam('ALLOW_CONFIG_MUTATIONS', false)) {
       util.makeImmutable(config);
     }
     checkMutability = false;
   }
   const t = this;
-  const value = getImpl(t, property);
+  const value = Util.getPath(t, property);
 
   // Produce an exception if the property doesn't exist
   if (typeof value === "undefined") {
@@ -197,7 +162,7 @@ Config.prototype.get = function(property) {
  *
  * @method has
  * @param property {string} - The configuration property to test. Can include '.' sub-properties.
- * @return isPresent {boolean} - True if the property is defined, false if not defined.
+ * @return {boolean} - True if the property is defined, false if not defined.
  */
 Config.prototype.has = function(property) {
   // While get() throws an exception for undefined input, has() is designed to test validity, so false is appropriate
@@ -205,7 +170,7 @@ Config.prototype.has = function(property) {
     return false;
   }
   const t = this;
-  return typeof getImpl(t, property) !== "undefined";
+  return typeof Util.getPath(t, property) !== "undefined";
 };
 
 /**
@@ -238,43 +203,32 @@ Config.prototype.has = function(property) {
  *
  * @method setModuleDefaults
  * @param moduleName {string} - Name of your module.
- * @param defaultProperties {object} - The default module configuration.
- * @return moduleConfig {object} - The module level configuration object.
+ * @param defaultProperties {Object} - The default module configuration.
+ * @return moduleConfig {Object} - The module level configuration object.
  */
 util.setModuleDefaults = function (moduleName, defaultProperties) {
 
   // Copy the properties into a new object
   const t = this;
-  const moduleConfig = util.cloneDeep(defaultProperties);
+  const path = moduleName.split('.');
+  const moduleConfig = FIRST_LOAD.setModuleDefaults(moduleName, defaultProperties);
+  let existing = Util.getPath(t, path);
 
-  // Set module defaults into the first sources element
-  if (configSources.length === 0 || configSources[0].name !== 'Module Defaults') {
-    configSources.splice(0, 0, {
-      name: 'Module Defaults',
-      parsed: {}
-    });
+  if (existing === undefined) {
+    Util.setPath(t, path, Util.cloneDeep(moduleConfig));
+  } else {
+    Util.extendDeep(existing, moduleConfig);
   }
-  util.setPath(configSources[0].parsed, moduleName.split('.'), {});
-  util.extendDeep(getImpl(configSources[0].parsed, moduleName), defaultProperties);
-
-  // Create a top level config for this module if it doesn't exist
-  util.setPath(t, moduleName.split('.'), getImpl(t, moduleName) || {});
-
-  // Extend local configurations into the module config
-  util.extendDeep(moduleConfig, getImpl(t, moduleName));
-
-  // Merge the extended configs without replacing the original
-  util.extendDeep(getImpl(t, moduleName), moduleConfig);
 
   // reset the mutability check for "config.get" method.
   // we are not making t[moduleName] immutable immediately,
   // since there might be more modifications before the first config.get
-  if (!util.initParam('ALLOW_CONFIG_MUTATIONS', false)) {
+  if (!FIRST_LOAD.initParam('ALLOW_CONFIG_MUTATIONS', false)) {
     checkMutability = true;
   }
 
   // Attach handlers & watchers onto the module config object
-  return util.attachProtoDeep(getImpl(t, moduleName));
+  return util.attachProtoDeep(Util.getPath(t, path));
 };
 
 /**
@@ -306,29 +260,15 @@ util.setModuleDefaults = function (moduleName, defaultProperties) {
  *   CONFIG.util.makeHidden(CONFIG.amazonS3, 'secret_key');
  * </pre>
  *
+ * @deprecated use Util.makeHidden
  * @method makeHidden
- * @param object {object} - The object to make a hidden property into.
+ * @param object {Object} - The object to make a hidden property into.
  * @param property {string} - The name of the property to make hidden.
  * @param value {*} - (optional) Set the property value to this (otherwise leave alone)
- * @return object {object} - The original object is returned - for chaining.
+ * @return object {Object} - The original object is returned - for chaining.
  */
 util.makeHidden = function(object, property, value) {
-
-  // If the new value isn't specified, just mark the property as hidden
-  if (typeof value === 'undefined') {
-    Object.defineProperty(object, property, {
-      enumerable : false
-    });
-  }
-  // Otherwise set the value and mark it as hidden
-  else {
-    Object.defineProperty(object, property, {
-      value      : value,
-      enumerable : false
-    });
-  }
-
-  return object;
+  return Util.makeHidden(object, property, value);
 }
 
 /**
@@ -359,13 +299,13 @@ util.makeHidden = function(object, property, value) {
  * </pre>
  *
  * @method makeImmutable
- * @param object {object} - The object to specify immutable properties for
+ * @param object {Object} - The object to specify immutable properties for
  * @param [property] {string | [string]} - The name of the property (or array of names) to make immutable.
  *        If not provided, all owned properties of the object are made immutable.
  * @param [value] {* | [*]} - Property value (or array of values) to set
  *        the property to before making immutable. Only used when setting a single
  *        property. Retained for backward compatibility.
- * @return object {object} - The original object is returned - for chaining.
+ * @return object {Object} - The original object is returned - for chaining.
  */
 util.makeImmutable = function(object, property, value) {
   if (Buffer.isBuffer(object)) {
@@ -403,21 +343,21 @@ util.makeImmutable = function(object, property, value) {
       });
     } else if (Array.isArray(value)) {
       // Ensure object items of this array are also immutable.
-      value.forEach((item, index) => { if (util.isObject(item) || Array.isArray(item)) util.makeImmutable(item) })
+      value.forEach((item, index) => { if (Util.isObject(item) || Array.isArray(item)) util.makeImmutable(item) })
 
       Object.defineProperty(object, propertyName, {
         value: Object.freeze(value)
       });
     } else {
       // Call recursively if an object.
-      if (util.isObject(value)) {
+      if (Util.isObject(value)) {
         // Create a proxy, to capture user updates of configuration options, and throw an exception for awareness, as per:
         // https://github.com/lorenwest/node-config/issues/514
         value = new Proxy(util.makeImmutable(value), {
           get(target, property, receiver) {
             // Config's own defined prototype properties and methods (e.g., `get`, `has`, etc.)
             const ownProps = [
-              ...Object.getOwnPropertyNames(Config.prototype),
+              ...Object.getOwnPropertyNames(Config.prototype), //TODO: This keeps us from moving this function to util.js where it belongs
               ...Object.getOwnPropertyNames(target),
             ]
 
@@ -445,11 +385,15 @@ util.makeImmutable = function(object, property, value) {
         })
       }
 
-      Object.defineProperty(object, propertyName, {
-        value: value,
-        writable : false,
-        configurable: false
-      });
+      // Check if property already has writable: false and configurable: false
+      const currentDescriptor = Object.getOwnPropertyDescriptor(object, propertyName);
+      if (!currentDescriptor || currentDescriptor.writable !== false || currentDescriptor.configurable !== false) {
+        Object.defineProperty(object, propertyName, {
+          value: value,
+          writable : false,
+          configurable: false
+        });
+      }
 
       // Ensure new properties can not be added, as per:
       // https://github.com/lorenwest/node-config/issues/505
@@ -474,8 +418,7 @@ util.makeImmutable = function(object, property, value) {
  *    name, original, and parsed elements
  */
 util.getConfigSources = function() {
-  const t = this;
-  return configSources.slice(0);
+  return FIRST_LOAD.getSources();
 };
 
 /**
@@ -487,17 +430,14 @@ util.getConfigSources = function() {
  * </p>
  *
  * @method getOption
+ * @deprecated use Util.getOption
  * @param options {Object | undefined} the options object
  * @param optionName {string} the attribute name to look for
  * @param defaultValue { any } the default in case the options object is empty, or the attribute does not exist.
  * @return options[optionName] if defined, defaultValue if not.
  */
 util.getOption = function(options, optionName, defaultValue) {
-  if (options !== undefined && typeof options[optionName] !== 'undefined'){
-    return options[optionName];
-  } else {
-    return defaultValue;
-  }
+  return Util.getOption(options, optionName, defaultValue);
 };
 
 
@@ -521,7 +461,7 @@ util.getOption = function(options, optionName, defaultValue) {
  * <p>
  * EXT can be yml, yaml, coffee, iced, json, jsonc, cson or js signifying the file type.
  * yaml (and yml) is in YAML format, coffee is a coffee-script, iced is iced-coffee-script,
- * json is in JSON format, jsonc is in JSONC format, cson is in CSON format, properties is 
+ * json is in JSON format, jsonc is in JSONC format, cson is in CSON format, properties is
  * in .properties format (http://en.wikipedia.org/wiki/.properties), and js is a javascript
  * executable file that is require()'d with module.exports being the config object.
  * </p>
@@ -552,246 +492,98 @@ util.getOption = function(options, optionName, defaultValue) {
  * </p>
  *
  * @protected
+ * @see Util.loadFileConfigs for discrete execution of (most of this functionality
  * @method loadFileConfigs
  * @param configDir { string | null } the path to the directory containing the configurations to load
- * @param options { object | undefined } parsing options. Current supported option: skipConfigSources: true|false
- * @return config {Object} The configuration object
+ * @param options { LoadOptions | undefined } parsing options
+ * @return {Object} The configuration object
  */
 util.loadFileConfigs = function(configDir, options) {
+  let newLoad;
 
-  // Initialize
-  const t = this;
-  const config = {};
+  if (configDir) {
+    let opts = {...FIRST_LOAD.options, configDir, ...options};
+    newLoad = new Load(opts);
+    newLoad.scan();
 
-  // Specify variables that can be used to define the environment
-  const node_env_var_names = ['NODE_CONFIG_ENV', 'NODE_ENV'];
-
-  // Loop through the variables to try and set environment
-  for (const node_env_var_name of node_env_var_names) {
-    NODE_ENV = util.initParam(node_env_var_name);
-    if (!!NODE_ENV) {
-      NODE_ENV_VAR_NAME = node_env_var_name;
-      break;
-    }
-  }
+    FIRST_LOAD.sourcesBug(newLoad.getSources());
+  } else {
+    newLoad = new Load({...FIRST_LOAD.options, ...options});
+    _init(newLoad);
 
-  // If we haven't successfully set the environment using the variables, we'll default it
-  if (!NODE_ENV) {
-    NODE_ENV = 'development';
+    FIRST_LOAD.sourcesBug(newLoad.getSources());
   }
 
-  node_env_var_names.forEach(node_env_var_name => {
-    env[node_env_var_name] = NODE_ENV;
-  });
+  return newLoad.config;
+}
 
-  // Split files name, for loading multiple files.
-  NODE_ENV = NODE_ENV.split(',');
+/**
+ * Scan with the default config dir (usually only at startup.
+ * This adds a bit more data from NODE_CONFIG that _load() skips
+ *
+ * @param load {Load}
+ * @private
+ */
+function _init(load) {
+  let options = load.options;
+  let additional = [];
 
-  let dir = configDir || util.initParam('NODE_CONFIG_DIR', Path.join( process.cwd(), 'config') );
-  dir = _toAbsolutePath(dir);
+  // Override configurations from the $NODE_CONFIG environment variable
+  let envConfig = {};
 
-  APP_INSTANCE = util.initParam('NODE_APP_INSTANCE');
-  CONFIG_SKIP_GITCRYPT = util.initParam('CONFIG_SKIP_GITCRYPT');
+  load.setEnv("CONFIG_DIR", options.configDir);
 
-  NODE_CONFIG_PARSER = util.initParam('NODE_CONFIG_PARSER');
-  if (NODE_CONFIG_PARSER) {
+  if (process.env.NODE_CONFIG) {
     try {
-      const parserModule = Path.isAbsolute(NODE_CONFIG_PARSER)
-        ? NODE_CONFIG_PARSER
-        : Path.join(dir, NODE_CONFIG_PARSER);
-      Parser = require(parserModule);
-    }
-    catch (e) {
-      console.warn('Failed to load config parser from ' + NODE_CONFIG_PARSER);
-      console.log(e);
+      envConfig = JSON.parse(process.env.NODE_CONFIG);
+    } catch(e) {
+      console.error('The $NODE_CONFIG environment variable is malformed JSON');
     }
-  }
-
-  const HOST = util.initParam('HOST');
-  const HOSTNAME = util.initParam('HOSTNAME');
-
-  // Determine the host name from the OS module, $HOST, or $HOSTNAME
-  // Remove any . appendages, and default to null if not set
-  let hostName = HOST || HOSTNAME;
-  try {
-    if (!hostName) {
-        const OS = require('os');
-        hostName = OS.hostname();
-    }
-  } catch (e) {
-    hostName = '';
-  }
 
-  // Store the hostname that won.
-  env.HOSTNAME = hostName;
-
-  // Read each file in turn
-  const baseNames = ['default'].concat(NODE_ENV);
-
-  // #236: Also add full hostname when they are different.
-  if (hostName) {
-    const firstDomain = hostName.split('.')[0];
-
-    NODE_ENV.forEach(function(env) {
-      // Backward compatibility
-      baseNames.push(firstDomain, firstDomain + '-' + env);
-
-      // Add full hostname when it is not the same
-      if (hostName !== firstDomain) {
-        baseNames.push(hostName, hostName + '-' + env);
-      }
-    });
+    additional.push({ name: "$NODE_CONFIG", config: envConfig });
   }
 
-  NODE_ENV.forEach(function(env) {
-    baseNames.push('local', 'local-' + env);
-  });
-
-  const allowedFiles = {};
-  let resolutionIndex = 1;
-  const extNames = Parser.getFilesOrder();
-  baseNames.forEach(function(baseName) {
-    const fileNames = [baseName];
-    if (APP_INSTANCE) {
-      fileNames.push(baseName + '-' + APP_INSTANCE);
-    }
-    fileNames.forEach(function(fileName) {
-      extNames.forEach(function(extName) {
-        allowedFiles[fileName + '.' + extName] = resolutionIndex++;
-      });
-    })
-  });
-
-  const locatedFiles = util.locateMatchingFiles(dir, allowedFiles);
-  locatedFiles.forEach(function(fullFilename) {
-    const configObj = util.parseFile(fullFilename, options);
-    if (configObj) {
-      util.extendDeep(config, configObj);
-    }
-  });
-
-  // Override configurations from the $NODE_CONFIG environment variable
-  // NODE_CONFIG only applies to the base config
-  if (!configDir) {
-    let envConfig = {};
-
-    CONFIG_DIR = dir;
-
-    if (process.env.NODE_CONFIG) {
-      try {
-        envConfig = JSON.parse(process.env.NODE_CONFIG);
-      } catch(e) {
-        console.error('The $NODE_CONFIG environment variable is malformed JSON');
-      }
-      util.extendDeep(config, envConfig);
-      const skipConfigSources = util.getOption(options,'skipConfigSources', false);
-      if (!skipConfigSources){
-        configSources.push({
-          name: "$NODE_CONFIG",
-          parsed: envConfig,
-        });
-      }
-    }
-
-    // Override configurations from the --NODE_CONFIG command line
-    let cmdLineConfig = util.getCmdLineArg('NODE_CONFIG');
-    if (cmdLineConfig) {
-      try {
-        cmdLineConfig = JSON.parse(cmdLineConfig);
-      } catch(e) {
-        console.error('The --NODE_CONFIG={json} command line argument is malformed JSON');
-      }
-      util.extendDeep(config, cmdLineConfig);
-      const skipConfigSources = util.getOption(options,'skipConfigSources', false);
-      if (!skipConfigSources){
-        configSources.push({
-          name: "--NODE_CONFIG argument",
-          parsed: cmdLineConfig,
-        });
-      }
+  // Override configurations from the --NODE_CONFIG command line
+  let cmdLineConfig = load.getCmdLineArg('NODE_CONFIG');
+  if (cmdLineConfig) {
+    try {
+      cmdLineConfig = JSON.parse(cmdLineConfig);
+    } catch(e) {
+      console.error('The --NODE_CONFIG={json} command line argument is malformed JSON');
     }
 
-    // Place the mixed NODE_CONFIG into the environment
-    env['NODE_CONFIG'] = JSON.stringify(util.extendDeep(envConfig, cmdLineConfig, {}));
+    additional.push({ name: "--NODE_CONFIG argument", config: cmdLineConfig });
   }
 
-  // Override with environment variables if there is a custom-environment-variables.EXT mapping file
-  const customEnvVars = util.getCustomEnvVars(dir, extNames);
-  util.extendDeep(config, customEnvVars);
+  // Place the mixed NODE_CONFIG into the environment
+  load.setEnv('NODE_CONFIG', JSON.stringify(Util.extendDeep(envConfig, cmdLineConfig, {})));
 
-  util.resolveDeferredConfigs(config);
-
-  // Return the configuration object
-  return config;
-};
+  load.scan(additional);
+}
 
 /**
  * Return a list of fullFilenames who exists in allowedFiles
  * Ordered according to allowedFiles argument specifications
  *
  * @protected
+ * @deprecated use Util.locateMatchingFiles
  * @method locateMatchingFiles
  * @param configDirs {string}   the config dir, or multiple dirs separated by a column (:)
- * @param allowedFiles {object} an object. keys and supported filenames
+ * @param allowedFiles {Object} an object. keys and supported filenames
  *                              and values are the position in the resolution order
  * @returns {string[]}          fullFilenames - path + filename
  */
 util.locateMatchingFiles = function(configDirs, allowedFiles) {
-  return configDirs.split(Path.delimiter)
-    .filter(Boolean)
-    .reduce(function(files, configDir) {
-      configDir = _toAbsolutePath(configDir);
-      try {
-        FileSystem.readdirSync(configDir)
-          .filter(file => allowedFiles[file])
-          .forEach(function(file) {
-            files.push([allowedFiles[file], Path.join(configDir, file)]);
-        });
-      }
-      catch(e) {}
-      return files;
-    }, [])
-    .sort(function(a, b) { return a[0] - b[0]; })
-    .map(function(file) { return file[1]; });
+  return Util.locateMatchingFiles(configDirs, allowedFiles);
 };
 
+/**
+ * @deprecated use Util.resolveDeferredConfigs
+ * @param config
+ */
 // Using basic recursion pattern, find all the deferred values and resolve them.
 util.resolveDeferredConfigs = function (config) {
-  const deferred = [];
-
-  function _iterate (prop) {
-    if (prop.constructor === String) {
-      return;
-    }
-
-    // We put the properties we are going to look it in an array to keep the order predictable
-    const propsToSort = Object.keys(prop).filter((property) => prop[property] != null);
-
-    // Second step is to iterate of the elements in a predictable (sorted) order
-    propsToSort.sort().forEach(function (property) {
-      if (prop[property].constructor === Object) {
-        _iterate(prop[property]);
-      } else if (prop[property].constructor === Array) {
-        for (let i = 0; i < prop[property].length; i++) {
-          if (prop[property][i] instanceof DeferredConfig) {
-            deferred.push(prop[property][i].prepare(config, prop[property], i));
-          }
-          else {
-            _iterate(prop[property][i]);
-          }
-        }
-      } else {
-        if (prop[property] instanceof DeferredConfig) {
-          deferred.push(prop[property].prepare(config, prop, property));
-        }
-        // else: Nothing to do. Keep the property how it is.
-      }
-    });
-  }
-
-  _iterate(config);
-
-  deferred.forEach(function (defer) { defer.resolve(); });
+  return Util.resolveDeferredConfigs(config);
 };
 
 /**
@@ -805,7 +597,7 @@ util.resolveDeferredConfigs = function (config) {
  * .js = File to run that has a module.exports containing the config object
  * .coffee = File to run that has a module.exports with coffee-script containing the config object
  * .iced = File to run that has a module.exports with iced-coffee-script containing the config object
- * All other supported file types (yaml, toml, json, jsonc, cson, hjson, json5, properties, xml)
+ * All other supported file types (yaml, toml, json, cson, hjson, json5, properties, xml)
  * are parsed with util.parseString.
  *
  * If the file doesn't exist, a null will be returned.  If the file can't be
@@ -815,73 +607,31 @@ util.resolveDeferredConfigs = function (config) {
  * after synchronous module loading.
  *
  * @protected
+ * @deprecated
  * @method parseFile
  * @param fullFilename {string} The full file path and name
  * @param options { object | undefined } parsing options. Current supported option: skipConfigSources: true|false
  * @return configObject {object|null} The configuration object parsed from the file
  */
-util.parseFile = function(fullFilename, options) {
-  const t = this;  // Initialize
-  let configObject = null;
-  let fileContent = null;
-  const stat = null;
-
-  // Note that all methods here are the Sync versions.  This is appropriate during
-  // module loading (which is a synchronous operation), but not thereafter.
-
-  try {
-    // Try loading the file.
-    fileContent = FileSystem.readFileSync(fullFilename, 'utf-8');
-    fileContent = fileContent.replace(/^\uFEFF/, '');
-  }
-  catch (e2) {
-    if (e2.code !== 'ENOENT') {
-      throw new Error('Config file ' + fullFilename + ' cannot be read. Error code is: '+e2.code
-                        +'. Error message is: '+e2.message);
-    }
-    return null;  // file doesn't exists
-  }
+util.parseFile = function(fullFilename, options = {}) {
+  let loadOpts = {...FIRST_LOAD.options}; //TODO: Support full LoadOptions?
+  let loadInfo = new Load(loadOpts);
 
-  // Parse the file based on extension
-  try {
+  loadInfo.loadFile(fullFilename);
 
-    // skip if it's a gitcrypt file and CONFIG_SKIP_GITCRYPT is true
-    if (CONFIG_SKIP_GITCRYPT) {
-      if (gitCryptTestRegex.test(fileContent)) {
-        console.error('WARNING: ' + fullFilename + ' is a git-crypt file and CONFIG_SKIP_GITCRYPT is set. skipping.');
-        return null;
-      }
-    }
-
-    configObject = Parser.parse(fullFilename, fileContent);
-  }
-  catch (e3) {
-    if (gitCryptTestRegex.test(fileContent)) {
-      console.error('ERROR: ' + fullFilename + ' is a git-crypt file and CONFIG_SKIP_GITCRYPT is not set.');
-    }
-    throw new Error("Cannot parse config file: '" + fullFilename + "': " + e3);
+  if (!options.skipConfigSources) {
+    FIRST_LOAD.sourcesBug(loadInfo.getSources());
   }
 
-  // Keep track of this configuration sources, including empty ones, unless the skipConfigSources flag is set to true in the options
-  const skipConfigSources = util.getOption(options,'skipConfigSources', false);
-  if (typeof configObject === 'object' && !skipConfigSources) {
-    configSources.push({
-      name: fullFilename,
-      original: fileContent,
-      parsed: configObject,
-    });
-  }
-
-  return configObject;
-};
+  return loadInfo.config;
+}
 
 /**
  * Parse and return the specified string with the specified format.
  *
  * The format determines the parser to use.
  *
- * json = Parsed with a JSON5 parser
- * jsonc = Parsed with a JSON5 parser
+ * json = File is parsed using JSON.parse()
  * yaml (or yml) = Parsed with a YAML parser
  * toml = Parsed with a TOML parser
  * cson = Parsed with a CSON parser
@@ -897,16 +647,14 @@ util.parseFile = function(fullFilename, options) {
  * after synchronous module loading.
  *
  * @protected
+ * @deprecated
  * @method parseString
  * @param content {string} The full content
  * @param format {string} The format to be parsed
  * @return {configObject} The configuration object parsed from the string
  */
 util.parseString = function (content, format) {
-  const parser = Parser.getParser(format);
-  if (typeof parser === 'function') {
-    return parser(null, content);
-  }
+  return FIRST_LOAD.parseString(content, format);
 };
 
 /**
@@ -924,9 +672,9 @@ util.parseString = function (content, format) {
  *
  * @protected
  * @method attachProtoDeep
- * @param toObject
- * @param depth
- * @return toObject
+ * @param toObject {Object}
+ * @param depth {number=20}
+ * @return {Object}
  */
 util.attachProtoDeep = function(toObject, depth) {
   if (toObject instanceof RawConfig) {
@@ -934,7 +682,6 @@ util.attachProtoDeep = function(toObject, depth) {
   }
 
   // Recursion detection
-  const t = this;
   depth = (depth === null ? DEFAULT_CLONE_DEPTH : depth);
   if (depth < 0) {
     return toObject;
@@ -944,13 +691,13 @@ util.attachProtoDeep = function(toObject, depth) {
   // because adding to toObject.__proto__ exposes the function in toObject
   for (const fnName in Config.prototype) {
     if (!toObject[fnName]) {
-      util.makeHidden(toObject, fnName, Config.prototype[fnName]);
+      Util.makeHidden(toObject, fnName, Config.prototype[fnName]);
     }
   }
 
   // Add prototypes to sub-objects
   for (const prop in toObject) {
-    if (util.isObject(toObject[prop])) {
+    if (Util.isObject(toObject[prop])) {
       util.attachProtoDeep(toObject[prop], depth - 1);
     }
   }
@@ -967,119 +714,29 @@ util.attachProtoDeep = function(toObject, depth) {
  * with the returned object without affecting the input object.
  *
  * @protected
+ * @deprecated please see Util.cloneDeep
  * @method cloneDeep
- * @param parent {object} The original object to copy from
- * @param [depth=20] {Integer} Maximum depth (default 20)
- * @return {object} A new object with the elements copied from the copyFrom object
- *
- * This method is copied from https://github.com/pvorb/node-clone/blob/17eea36140d61d97a9954c53417d0e04a00525d9/clone.js
- *
- * Copyright © 2011-2014 Paul Vorbach and contributors.
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the “Software”), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
- * of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions: The above copyright notice and this permission
- * notice shall be included in all copies or substantial portions of the Software.
+ * @param parent {Object} The original object to copy from
+ * @param [depth=20] {number} Maximum depth (default 20)
+ * @return {Object} A new object with the elements copied from the copyFrom object
  */
 util.cloneDeep = function cloneDeep(parent, depth, circular, prototype) {
-  // maintain two arrays for circular references, where corresponding parents
-  // and children have the same index
-  const allParents = [];
-  const allChildren = [];
-
-  const useBuffer = typeof Buffer !== 'undefined';
-
-  if (typeof circular === 'undefined')
-    circular = true;
-
-  if (typeof depth === 'undefined')
-    depth = 20;
-
-  // recurse this function so we don't reset allParents and allChildren
-  function _clone(parent, depth) {
-    // cloning null always returns null
-    if (parent === null)
-      return null;
-
-    if (depth === 0)
-      return parent;
-
-    let child;
-    if (typeof parent != 'object') {
-      return parent;
-    }
-
-    if (Array.isArray(parent)) {
-      child = [];
-    } else if (parent instanceof RegExp) {
-      child = new RegExp(parent.source, util.getRegExpFlags(parent));
-      if (parent.lastIndex) child.lastIndex = parent.lastIndex;
-    } else if (parent instanceof Date) {
-      child = new Date(parent.getTime());
-    } else if (useBuffer && Buffer.isBuffer(parent)) {
-      child = Buffer.alloc(parent.length);
-      parent.copy(child);
-      return child;
-    } else {
-      if (typeof prototype === 'undefined') child = Object.create(Object.getPrototypeOf(parent));
-      else child = Object.create(prototype);
-    }
-
-    if (circular) {
-      const index = allParents.indexOf(parent);
-
-      if (index != -1) {
-        return allChildren[index];
-      }
-      allParents.push(parent);
-      allChildren.push(child);
-    }
-
-    for (const i in parent) {
-      const propDescriptor  = Object.getOwnPropertyDescriptor(parent,i);
-      const hasGetter = ((typeof propDescriptor !== 'undefined') && (typeof propDescriptor.get !== 'undefined'));
-
-      if (hasGetter){
-        Object.defineProperty(child,i,propDescriptor);
-      } else if (util.isPromise(parent[i])) {
-        child[i] = parent[i];
-      } else {
-        child[i] = _clone(parent[i], depth - 1);
-      }
-    }
-
-    return child;
-  }
-
-  return _clone(parent, depth);
+  return Util.cloneDeep(parent, depth, circular, prototype);
 };
 
 /**
  * Set objects given a path as a string list
  *
  * @protected
+ * @deprecated see Util.setPath()
+ *
  * @method setPath
- * @param object {object} - Object to set the property on
+ * @param object {Object} - Object to set the property on
  * @param path {array[string]} - Array path to the property
  * @param value {*} - value to set, ignoring null
  */
 util.setPath = function (object, path, value) {
-  let nextKey = null;
-  if (value === null || path.length === 0) {
-    return;
-  }
-  else if (path.length === 1) { // no more keys to make, so set the value
-    object[path.shift()] = value;
-  }
-  else {
-    nextKey = path.shift();
-    if (!Object.hasOwnProperty.call(object, nextKey)) {
-      object[nextKey] = {};
-    }
-    util.setPath(object[nextKey], path, value);
-  }
+  Util.setPath(object, path, value);
 };
 
 /**
@@ -1089,133 +746,53 @@ util.setPath = function (object, path, value) {
  * 3. And parent keys are created as necessary to retain the structure of substitutionMap.
  *
  * @protected
+ * @deprecated
+ *
  * @method substituteDeep
- * @param substitutionMap {object} - an object whose terminal (non-subobject) values are strings
+ * @param substitutionMap {Object} - an object whose terminal (non-subobject) values are strings
  * @param variables {object[string:value]} - usually process.env, a flat object used to transform
  *      terminal values in a copy of substitutionMap.
- * @returns {object} - deep copy of substitutionMap with only those paths whose terminal values
+ * @returns {Object} - deep copy of substitutionMap with only those paths whose terminal values
  *      corresponded to a key in `variables`
  */
 util.substituteDeep = function (substitutionMap, variables) {
-  const result = {};
-
-  function _substituteVars(map, vars, pathTo) {
-    let parsedValue;
-    for (const prop in map) {
-      const value = map[prop];
-      if (typeof(value) === 'string') { // We found a leaf variable name
-        if (typeof vars[value] !== 'undefined' && vars[value] !== '') { // if the vars provide a value set the value in the result map
-          util.setPath(result, pathTo.concat(prop), vars[value]);
-        }
-      }
-      else if (util.isObject(value)) { // work on the subtree, giving it a clone of the pathTo
-        if ('__name' in value && '__format' in value && typeof vars[value.__name] !== 'undefined' && vars[value.__name] !== '') {
-          let parsedValue;
-          try {
-            parsedValue = util.parseString(vars[value.__name], value.__format);
-          } catch(err) {
-            err.message = '__format parser error in ' + value.__name + ': ' + err.message;
-            throw err;
-          }
-          util.setPath(result, pathTo.concat(prop), parsedValue);
-        } else {
-          _substituteVars(value, vars, pathTo.concat(prop));
-        }
-      }
-      else {
-        msg = "Illegal key type for substitution map at " + pathTo.join('.') + ': ' + typeof(value);
-        throw Error(msg);
-      }
-    }
-  }
-
-  _substituteVars(substitutionMap, variables, []);
-  return result;
-
+  return FIRST_LOAD.substituteDeep(substitutionMap, variables);
 };
 
-/* Map environment variables into the configuration if a mapping file,
+/**
+ *  Map environment variables into the configuration if a mapping file,
  * `custom-environment-variables.EXT` exists.
  *
  * @protected
+ * @deprecated
  * @method getCustomEnvVars
  * @param configDir {string} - the passed configuration directory
  * @param extNames {Array[string]} - acceptable configuration file extension names.
- * @returns {object} - mapped environment variables or {} if there are none
+ * @returns {Object} - mapped environment variables or {} if there are none
  */
 util.getCustomEnvVars = function (configDir, extNames) {
-  const result = {};
-  let resolutionIndex = 1;
-  const allowedFiles = {};
-  extNames.forEach(function (extName) {
-    allowedFiles['custom-environment-variables' + '.' + extName] = resolutionIndex++;
-  });
-  const locatedFiles = util.locateMatchingFiles(configDir, allowedFiles);
-  locatedFiles.forEach(function (fullFilename) {
-    const configObj = util.parseFile(fullFilename);
-    if (configObj) {
-      const environmentSubstitutions = util.substituteDeep(configObj, process.env);
-      util.extendDeep(result, environmentSubstitutions);
-    }
-  });
-  return result;
+  let options = {...FIRST_LOAD.options, configDir};
+  let load = new Load(options);
+
+  load.loadCustomEnvVars(extNames);
+
+  return load.config;
 };
 
 /**
  * Return true if two objects have equal contents.
  *
  * @protected
+ * @deprecated see Util.equalsDeep()
+ *
  * @method equalsDeep
- * @param object1 {object} The object to compare from
- * @param object2 {object} The object to compare with
+ * @param object1 {Object} The object to compare from
+ * @param object2 {Object} The object to compare with
  * @param depth {integer} An optional depth to prevent recursion.  Default: 20.
  * @return {boolean} True if both objects have equivalent contents
  */
 util.equalsDeep = function(object1, object2, depth) {
-
-  // Recursion detection
-  const t = this;
-  depth = (depth === null ? DEFAULT_CLONE_DEPTH : depth);
-  if (depth < 0) {
-    return {};
-  }
-
-  // Fast comparisons
-  if (!object1 || !object2) {
-    return false;
-  }
-  if (object1 === object2) {
-    return true;
-  }
-  if (typeof(object1) != 'object' || typeof(object2) != 'object') {
-    return false;
-  }
-
-  // They must have the same keys.  If their length isn't the same
-  // then they're not equal.  If the keys aren't the same, the value
-  // comparisons will fail.
-  if (Object.keys(object1).length != Object.keys(object2).length) {
-    return false;
-  }
-
-  // Compare the values
-  for (const prop in object1) {
-
-    // Call recursively if an object or array
-    if (object1[prop] && typeof(object1[prop]) === 'object') {
-      if (!util.equalsDeep(object1[prop], object2[prop], depth - 1)) {
-        return false;
-      }
-    }
-    else {
-      if (object1[prop] !== object2[prop]) {
-        return false;
-      }
-    }
-  }
-
-  // Test passed.
-  return true;
+  return Util.equalsDeep(object1, object2, depth);
 };
 
 /**
@@ -1230,18 +807,19 @@ util.equalsDeep = function(object1, object2, depth) {
  * the changes made to object1 which resulted in object2.
  * </p>
  *
+ * <b>This function has a number of issues and you may be better off with lodash</b>
+ *
  * @protected
+ * @deprecated please investigate lodash or similar tools for object traversal
  * @method diffDeep
- * @param object1 {object} The base object to compare to
- * @param object2 {object} The object to compare with
+ * @param object1 {Object} The base object to compare to
+ * @param object2 {Object} The object to compare with
  * @param depth {integer} An optional depth to prevent recursion.  Default: 20.
- * @return {object} A differential object, which if extended onto object1 would
+ * @return {Object} A differential object, which if extended onto object1 would
  *                  result in object2.
  */
 util.diffDeep = function(object1, object2, depth) {
-
   // Recursion detection
-  const t = this;
   const diff = {};
   depth = (depth === null ? DEFAULT_CLONE_DEPTH : depth);
   if (depth < 0) {
@@ -1253,13 +831,13 @@ util.diffDeep = function(object1, object2, depth) {
   for (const parm in object2) {
     const value1 = object1[parm];
     const value2 = object2[parm];
-    if (value1 && value2 && util.isObject(value2)) {
-      if (!(util.equalsDeep(value1, value2))) {
+    if (value1 && value2 && Util.isObject(value2)) {
+      if (!(Util.equalsDeep(value1, value2))) {
         diff[parm] = util.diffDeep(value1, value2, depth - 1);
       }
     }
     else if (Array.isArray(value1) && Array.isArray(value2)) {
-      if(!util.equalsDeep(value1, value2)) {
+      if(!Util.equalsDeep(value1, value2)) {
         diff[parm] = value2;
       }
     }
@@ -1270,7 +848,6 @@ util.diffDeep = function(object1, object2, depth) {
 
   // Return the diff object
   return diff;
-
 };
 
 /**
@@ -1280,67 +857,15 @@ util.diffDeep = function(object1, object2, depth) {
  * replacing individual elements instead.
  *
  * @protected
+ * @deprecated please use Util.extendDeep()
  * @method extendDeep
- * @param mergeInto {object} The object to merge into
- * @param mergeFrom... {object...} - Any number of objects to merge from
+ * @param mergeInto {Object} The object to merge into
+ * @param mergeFrom... {object[]} - Any number of objects to merge from
  * @param depth {integer} An optional depth to prevent recursion.  Default: 20.
- * @return {object} The altered mergeInto object is returned
+ * @return {Object} The altered mergeInto object is returned
  */
 util.extendDeep = function(mergeInto, ...vargs) {
-
-  // Initialize
-  let depth = vargs.pop();
-  if (typeof(depth) != 'number') {
-    vargs.push(depth);
-    depth = DEFAULT_CLONE_DEPTH;
-  }
-
-  // Recursion detection
-  if (depth < 0) {
-    return mergeInto;
-  }
-
-  // Cycle through each object to extend
-  vargs.forEach(function(mergeFrom) {
-
-    // Cycle through each element of the object to merge from
-    for (const prop in mergeFrom) {
-
-      // save original value in deferred elements
-      const fromIsDeferredFunc = mergeFrom[prop] instanceof DeferredConfig;
-      const isDeferredFunc = mergeInto[prop] instanceof DeferredConfig;
-
-      if (fromIsDeferredFunc && Object.hasOwnProperty.call(mergeInto, prop)) {
-        mergeFrom[prop]._original = isDeferredFunc ? mergeInto[prop]._original : mergeInto[prop];
-      }
-      // Extend recursively if both elements are objects and target is not really a deferred function
-      if (mergeFrom[prop] instanceof Date) {
-        mergeInto[prop] = mergeFrom[prop];
-      } if (mergeFrom[prop] instanceof RegExp) {
-        mergeInto[prop] = mergeFrom[prop];
-      } else if (util.isObject(mergeInto[prop]) && util.isObject(mergeFrom[prop]) && !isDeferredFunc) {
-        util.extendDeep(mergeInto[prop], mergeFrom[prop], depth - 1);
-      }
-      else if (util.isPromise(mergeFrom[prop])) {
-        mergeInto[prop] = mergeFrom[prop];
-      }
-      // Copy recursively if the mergeFrom element is an object (or array or fn)
-      else if (mergeFrom[prop] && typeof mergeFrom[prop] === 'object') {
-        mergeInto[prop] = util.cloneDeep(mergeFrom[prop], depth -1);
-      }
-
-      // Copy property descriptor otherwise, preserving accessors
-      else if (Object.getOwnPropertyDescriptor(Object(mergeFrom), prop)){
-          Object.defineProperty(mergeInto, prop, Object.getOwnPropertyDescriptor(Object(mergeFrom), prop));
-      } else {
-          mergeInto[prop] = mergeFrom[prop];
-      }
-    }
-  });
-
-  // Chain
-  return mergeInto;
-
+  return Util.extendDeep(mergeInto, ...vargs);
 };
 
 /**
@@ -1349,24 +874,26 @@ util.extendDeep = function(mergeInto, ...vargs) {
  * The argument is an object if it's a JS object, but not an array.
  *
  * @protected
+ * @deprecated please use Util.isObject()
  * @method isObject
  * @param obj {*} An argument of any type.
  * @return {boolean} TRUE if the arg is an object, FALSE if not
  */
 util.isObject = function(obj) {
-  return (obj !== null) && (typeof obj === 'object') && !(Array.isArray(obj));
+  return Util.isObject(obj);
 };
 
 /**
  * Is the specified argument a javascript promise?
  *
  * @protected
+ * @deprecated please use Util.isPromise()
  * @method isPromise
  * @param obj {*} An argument of any type.
  * @returns {boolean}
  */
 util.isPromise = function(obj) {
-  return Object.prototype.toString.call(obj) === '[object Promise]';
+  return Util.isPromise(obj);
 };
 
 /**
@@ -1379,17 +906,13 @@ util.isPromise = function(obj) {
  * </p>
  *
  * @method initParam
+ * @deprecated
  * @param paramName {String} Name of the parameter
- * @param [defaultValue] {Any} Default value of the parameter
- * @return {Any} The found value, or default value
+ * @param [defaultValue] {*} Default value of the parameter
+ * @return {*} The found value, or default value
  */
 util.initParam = function (paramName, defaultValue) {
-  const t = this;
-
-  // Record and return the value
-  const value = util.getCmdLineArg(paramName) || process.env[paramName] || defaultValue;
-  env[paramName] = value;
-  return value;
+  return FIRST_LOAD.initParam(paramName, defaultValue);
 }
 
 /**
@@ -1404,22 +927,15 @@ util.initParam = function (paramName, defaultValue) {
  * </p>
  *
  * @method getCmdLineArg
+ * @deprecated
  * @param searchFor {String} The argument name to search for
  * @return {*} false if the argument was not found, the argument value if found
  */
 util.getCmdLineArg = function (searchFor) {
-    const cmdLineArgs = process.argv.slice(2, process.argv.length);
-    const argName = '--' + searchFor + '=';
-
-    for (let argvIt = 0; argvIt < cmdLineArgs.length; argvIt++) {
-      if (cmdLineArgs[argvIt].indexOf(argName) === 0) {
-        return cmdLineArgs[argvIt].substr(argName.length);
-      }
-    }
-
-    return false;
+  return FIRST_LOAD.getCmdLineArg(searchFor);
 }
 
+
 /**
  * <p>Get a Config Environment Variable Value</p>
  *
@@ -1429,11 +945,12 @@ util.getCmdLineArg = function (searchFor) {
  * </p>
  *
  * @method getEnv
+ * @deprecated
  * @param varName {String} The environment variable name
  * @return {String} The value of the environment variable
  */
 util.getEnv = function (varName) {
-  return env[varName];
+  return FIRST_LOAD.getEnv(varName);
 }
 
 
@@ -1441,15 +958,13 @@ util.getEnv = function (varName) {
 /**
  * Returns a string of flags for regular expression `re`.
  *
+ * @protected
+ * @deprecated This is an internal implementation detail
  * @param {RegExp} re Regular expression
  * @returns {string} Flags
  */
 util.getRegExpFlags = function (re) {
-  let flags = '';
-  re.global && (flags += 'g');
-  re.ignoreCase && (flags += 'i');
-  re.multiline && (flags += 'm');
-  return flags;
+  return Util.getRegExpFlags(re);
 };
 
 /**
@@ -1459,12 +974,12 @@ util.getRegExpFlags = function (re) {
  * @returns {Object} The cloned config or part of the config
  */
 util.toObject = function(config) {
-  return JSON.parse(JSON.stringify(config || this));
+  return Util.toObject(config || this);
 };
 
 // Run strictness checks on NODE_ENV and NODE_APP_INSTANCE and throw an error if there's a problem.
 util.runStrictnessChecks = function (config) {
-  if (util.initParam('SUPPRESS_STRICTNESS_CHECK')) {
+  if (FIRST_LOAD.initParam('SUPPRESS_STRICTNESS_CHECK')) {
     return;
   }
 
@@ -1473,27 +988,32 @@ util.runStrictnessChecks = function (config) {
     return Path.basename(src.name);
   });
 
-  NODE_ENV.forEach(function(env) {
+  FIRST_LOAD.options.nodeEnv.forEach(function(env) {
     // Throw an exception if there's no explicit config file for NODE_ENV
     const anyFilesMatchEnv = sourceFilenames.some(function (filename) {
         return filename.match(env);
     });
     // development is special-cased because it's the default value
     if (env && (env !== 'development') && !anyFilesMatchEnv) {
-      _warnOrThrow(NODE_ENV_VAR_NAME+" value of '"+env+"' did not match any deployment config file names.");
+      _warnOrThrow(`${FIRST_LOAD.getEnv("nodeEnv")} value of '${env}' did not match any deployment config file names.`);
     }
     // Throw if NODE_ENV matches' default' or 'local'
     if ((env === 'default') || (env === 'local')) {
-      _warnOrThrow(NODE_ENV_VAR_NAME+" value of '"+env+"' is ambiguous.");
+      _warnOrThrow(`${FIRST_LOAD.getEnv("nodeEnv")} value of '${env}' is ambiguous.`);
     }
   });
 
-  // Throw an exception if there's no explicit config file for NODE_APP_INSTANCE
-  const anyFilesMatchInstance = sourceFilenames.some(function (filename) {
-      return filename.match(APP_INSTANCE);
-  });
-  if (APP_INSTANCE && !anyFilesMatchInstance) {
-    _warnOrThrow("NODE_APP_INSTANCE value of '"+APP_INSTANCE+"' did not match any instance config file names.");
+  let appInstance = FIRST_LOAD.options.appInstance;
+
+  if (appInstance) {
+    // Throw an exception if there's no explicit config file for NODE_APP_INSTANCE
+    const anyFilesMatchInstance = sourceFilenames.some(function (filename) {
+      return filename.match(appInstance);
+    });
+
+    if (!anyFilesMatchInstance) {
+      _warnOrThrow(`NODE_APP_INSTANCE value of '${appInstance}' did not match any instance config file names.`);
+    }
   }
 
   function _warnOrThrow (msg) {
@@ -1511,24 +1031,18 @@ util.runStrictnessChecks = function (config) {
   }
 };
 
-// Helper functions shared accross object members
-function _toAbsolutePath (configDir) {
-  if (configDir.indexOf('.') === 0) {
-    return Path.join(process.cwd(), configDir);
-  }
-
-  return configDir;
-}
+/** @type {Load} */
+const FIRST_LOAD = Load.fromEnvironment();
 
 // Instantiate and export the configuration
 const config = module.exports = new Config();
 
 // copy method to util for backwards compatibility
-util.stripYamlComments = Parser.stripYamlComments;
+util.stripYamlComments = FIRST_LOAD.parser.stripYamlComments;
 
 // Produce warnings if the configuration is empty
-const showWarnings = !(util.initParam('SUPPRESS_NO_CONFIG_WARNING'));
+const showWarnings = !(FIRST_LOAD.initParam('SUPPRESS_NO_CONFIG_WARNING'));
 if (showWarnings && Object.keys(config).length === 0) {
-  console.error('WARNING: No configurations found in configuration directory:' +CONFIG_DIR);
+  console.error('WARNING: No configurations found in configuration directory:' + FIRST_LOAD.options.configDir);
   console.error('WARNING: To disable this warning set SUPPRESS_NO_CONFIG_WARNING in the environment.');
 }