config 4.4.0 → 5.0.0-alpha.0

package/lib/defer.js

@@ -1,4 +1,4 @@
-const { isAsyncFunction } = require('node:util/types');
+import { isAsyncFunction } from 'node:util/types';
 
 /** @typedef {import('./config').Config} Config */
 
@@ -66,5 +66,4 @@ function deferConfig(func) {
   return obj;
 }
 
-module.exports.deferConfig = deferConfig;
-module.exports.DeferredConfig = DeferredConfig;
+export { deferConfig, DeferredConfig };

package/lib/util.js

@@ -5,11 +5,13 @@
 
 // Dependencies
 /** @typedef {typeof import('./../parser')} Parser */
-const { deferConfig, DeferredConfig } = require('./defer.js');
-const { resolveAsyncConfigs } = require('../async');
-const Path = require('path');
-const FileSystem = require('fs');
-const OS = require("os");
+import Path from 'node:path';
+import FileSystem from 'node:fs';
+import OS from 'node:os';
+import { createRequire } from 'node:module';
+
+import defaultParser from '../parser.js';
+import { deferConfig, DeferredConfig } from './defer.js';
 
 const DEFAULT_CONFIG_DIR = Path.join( process.cwd(), 'config');
 const SEEN_ERRORS = {};
@@ -61,7 +63,7 @@ const DEFAULT_OPTIONS = {
   nodeEnv: ['development'],
   hostName: OS.hostname(),
   gitCrypt: true,
-  parser: require("../parser.js")
+  parser: defaultParser
 };
 
 /**
@@ -454,8 +456,6 @@ class Util {
   static async resolveAsyncConfigs(config) {
     const promises = [];
 
-    await resolveAsyncConfigs(config);
-
     function _iterate (prop) {
       if (prop == null || prop.constructor === String) {
         return;
@@ -713,7 +713,7 @@ class Util {
    * @method extendDeep
    * @param mergeInto {Object} The object to merge into
    * @param mergeFrom... {Object} - Any number of objects to merge from
-   * @param [depth] {number} An optional depth to prevent recursion.  Default: 20.
+   * @param {number} [depth=20] - An optional depth to prevent recursion.  Default: 20.
    * @return {Object} The altered mergeInto object is returned
    */
   static extendDeep(mergeInto, ...vargs) {
@@ -1357,7 +1357,6 @@ class Load {
    * This function exists in part to reduce the circular dependency of variable initializations
    * in the config.js file
    * @param {string} environments the NODE_CONFIG_ENVs you want to load
-   * @private
    * @returns {Load}
    */
   static fromEnvironment(environments) {
@@ -1396,7 +1395,6 @@ class Load {
     // Remove any . appendages, and default to null if not set
     try {
       if (!hostName) {
-        const OS = require('os');
         hostName = OS.hostname();
       }
     } catch (e) {
@@ -1454,15 +1452,17 @@ function _toAbsolutePath (configDir) {
   return configDir;
 }
 
-function _loadParser(name, dir) {
+function _loadParser(name, dir = process.cwd()) {
   if (name === undefined) {
-    return require("../parser.js");
+    return defaultParser;
   }
 
+  const require = createRequire(_toAbsolutePath(dir));
+
   try {
-    const parserModule = Path.isAbsolute(name) ? name : Path.join(dir, name);
+    const required = require(Path.resolve(dir, name));
 
-    return require(parserModule);
+    return required.default ?? required;
   }
   catch (e) {
     console.warn(`Failed to load config parser from ${name}`);
@@ -1470,4 +1470,4 @@ function _loadParser(name, dir) {
   }
 }
 
-module.exports = { Util, Load, RawConfig };
+export { Util, Load, RawConfig };

package/package.json

@@ -1,34 +1,17 @@
 {
   "name": "config",
-  "version": "4.4.0",
+  "version": "5.0.0-alpha.0",
   "main": "./lib/config.js",
+  "module": "./lib/config.mjs",
   "types": "types/lib/config.d.ts",
   "typesVersions": {
     "*": {
-      "async": [
-        "types/async.d.ts"
-      ],
-      "async.js": [
-        "types/async.d.ts"
-      ],
-      "defer": [
-        "types/defer.d.ts"
-      ],
-      "defer.js": [
-        "types/defer.d.ts"
-      ],
       "parser": [
         "types/parser.d.ts"
       ],
       "parser.js": [
         "types/parser.d.ts"
       ],
-      "raw": [
-        "types/raw.d.ts"
-      ],
-      "raw.js": [
-        "types/raw.d.ts"
-      ],
       "lib/defer": [
         "types/lib/defer.d.ts"
       ],
@@ -87,7 +70,7 @@
     "url": "http://github.com/node-config/node-config.git"
   },
   "engines": {
-    "node": ">= 20.0.0"
+    "node": ">= 20.11.0"
   },
   "c8": {
     "include": [

package/parser.js

@@ -1,16 +1,12 @@
 // External libraries are lazy-loaded only if these file types exist.
+import Path from 'path';
+import { createRequire } from 'node:module';
+import JSON5 from 'json5';
 
-// webpack can't solve dynamic module
-// @see https://github.com/node-config/node-config/issues/755
-// @see https://webpack.js.org/guides/dependency-management/#require-with-expression
-const JSON5Module = require('json5');
+const moduleRequire = createRequire(Path.join(process.cwd(), 'package.json'));
+const require = createRequire(process.cwd());
 
-// webpack resolves json5 with module field out of the box which lead to this usage
-// @see https://github.com/node-config/node-config/issues/755
-// @see https://github.com/json5/json5/issues/240
-const JSON5 = JSON5Module.default || JSON5Module;
-
-var Yaml = null,
+let Yaml = null,
     JSYaml = null,
     Coffee = null,
     Iced = null,
@@ -18,10 +14,11 @@ var Yaml = null,
     PPARSER = null,
     TOML = null,
     HJSON = null,
-    XML = null;
+    XML = null,
+    TS = null;
 
 // Define soft dependencies so transpilers don't include everything
-var COFFEE_2_DEP = 'coffeescript',
+let COFFEE_2_DEP = 'coffeescript',
     COFFEE_DEP = 'coffee-script',
     ICED_DEP = 'iced-coffee-script',
     JS_YAML_DEP = 'js-yaml',
@@ -38,7 +35,7 @@ var COFFEE_2_DEP = 'coffeescript',
  * @template [T=any]
  * @typedef {(filename: string, content: string) => T | undefined} ParserFn<T>
  */
-var Parser = module.exports;
+let Parser = {};
 
 /**
  * @param {string} filename
@@ -60,7 +57,7 @@ Parser.parse = function(filename, content) {
  */
 Parser.xmlParser = function(filename, content) {
   if (!XML) {
-    XML = require(XML_DEP);
+    XML = moduleRequire(XML_DEP);
   }
   var x2js = new XML();
   var configObject = x2js.xml2js(content);
@@ -91,15 +88,18 @@ Parser.jsParser = function(filename, content) {
  * @returns {object}
  */
 Parser.tsParser = function(filename, content) {
-  if (!require.extensions['.ts']) {
-    require(TS_DEP).register({
-      lazy: true,
-      ignore: ['(?:^|/)node_modules/', '.*(?<!\.ts)$'],
-      transpileOnly: true,
-      compilerOptions: {
-        allowJs: true,
-      }
-    });
+  if (require?.extensions?.['.ts'] === undefined) {
+    if (TS === null) {
+      TS = moduleRequire(TS_DEP);
+      TS.register({
+        lazy: true,
+        ignore: ['(?:^|/)node_modules/', '.*(?<!\.ts)$'],
+        transpileOnly: true,
+        compilerOptions: {
+          allowJs: true,
+        }
+      });
+    }
   }
 
   // Imports config if it is exported via module.exports = ...
@@ -126,21 +126,13 @@ Parser.coffeeParser = function(filename, content) {
   if (!Coffee) {
     Coffee = {};
 
-    // The following enables iced-coffee-script on .coffee files, if iced-coffee-script is available.
-    // This is commented as per a decision on a pull request.
-    //try {
-    //  Coffee = require('iced-coffee-script');
-    //}
-    //catch (e) {
-    //  Coffee = require('coffee-script');
-    //}
     try {
       // Try to load coffeescript
-      Coffee = require(COFFEE_2_DEP);
+      Coffee = moduleRequire(COFFEE_2_DEP);
     }
     catch (e) {
       // If it doesn't exist, try to load it using the deprecated module name
-      Coffee = require(COFFEE_DEP);
+      Coffee = moduleRequire(COFFEE_DEP);
     }
     // coffee-script >= 1.7.0 requires explicit registration for require() to work
     if (Coffee.register) {
@@ -157,7 +149,7 @@ Parser.coffeeParser = function(filename, content) {
  * @returns {object | undefined}
  */
 Parser.icedParser = function(filename, content) {
-  Iced = require(ICED_DEP);
+  Iced = moduleRequire(ICED_DEP);
 
   // coffee-script >= 1.7.0 requires explicit registration for require() to work
   if (Iced.register) {
@@ -174,10 +166,10 @@ Parser.yamlParser = function(filename, content) {
   if (!Yaml && !JSYaml) {
     // Lazy loading
     try {
-      Yaml = require(YAML_DEP);
+      Yaml = moduleRequire(YAML_DEP);
     } catch (e) {
       try {
-        JSYaml = require(JS_YAML_DEP);
+        JSYaml = moduleRequire(JS_YAML_DEP);
       } catch (e) {}
     }
   }
@@ -221,7 +213,7 @@ Parser.json5Parser = function(filename, content) {
  */
 Parser.hjsonParser = function(filename, content) {
   if (!HJSON) {
-    HJSON = require(HJSON_DEP);
+    HJSON = moduleRequire(HJSON_DEP);
   }
   return HJSON.parse(content);
 };
@@ -233,7 +225,7 @@ Parser.hjsonParser = function(filename, content) {
  */
 Parser.tomlParser = function(filename, content) {
   if(!TOML) {
-    TOML = require(TOML_DEP);
+    TOML = moduleRequire(TOML_DEP);
   }
   return TOML.parse(content);
 };
@@ -245,7 +237,7 @@ Parser.tomlParser = function(filename, content) {
  */
 Parser.csonParser = function(filename, content) {
   if (!CSON) {
-    CSON = require(CSON_DEP);
+    CSON = moduleRequire(CSON_DEP);
   }
   // Allow comments in CSON files
   if (typeof CSON.parseSync === 'function') {
@@ -261,7 +253,7 @@ Parser.csonParser = function(filename, content) {
  */
 Parser.propertiesParser = function(filename, content) {
   if (!PPARSER) {
-    PPARSER = require(PPARSER_DEP);
+    PPARSER = moduleRequire(PPARSER_DEP);
   }
   return PPARSER.parse(content, { namespaces: true, variables: true, sections: true });
 };
@@ -382,3 +374,5 @@ Parser.setFilesOrder = function(name, newIndex) {
 function isObject(arg) {
   return (arg !== null) && (typeof arg === 'object');
 }
+
+export default Parser;

package/types/lib/config.d.mts

@@ -0,0 +1,365 @@
+declare const _default: ConfigClass;
+export default _default;
+export type Util = import("./util.js").Util;
+export type Load = import("./util.js").Load;
+export type LoadOptions = import("./util.js").LoadOptions;
+export type Parser = typeof import("./../parser.js");
+/**
+ * The exported configuration instance type.
+ * This is here because the Config class is not a named export and this is how we get
+ * the exported configuration instance type.
+ */
+export type Config = ConfigClass;
+/**
+ * <p>Application Configurations</p>
+ * @class
+ */
+declare class ConfigClass {
+    /**
+     * <p>Get the configuration object.</p>
+     *
+     * <p>
+     * The configuration object is a shared singleton object within the application,
+     * attained by calling require('config').
+     * </p>
+     *
+     * <p>
+     * Usually you'll specify a CONFIG variable at the top of your .js file
+     * for file/module scope. If you want the root of the object, you can do this:
+     * </p>
+     * <pre>
+     * const CONFIG = require('config');
+     * </pre>
+     *
+     * <p>
+     * Sometimes you only care about a specific sub-object within the CONFIG
+     * object.  In that case you could do this at the top of your file:
+     * </p>
+     * <pre>
+     * const CONFIG = require('config').customer;
+     * or
+     * const CUSTOMER_CONFIG = require('config').customer;
+     * </pre>
+     *
+     * <script type="text/javascript">
+     *   document.getElementById("showProtected").style.display = "block";
+     * </script>
+     *
+     * @method constructor
+     */
+    constructor(load: any);
+    /**
+     * Non-enumerable field for util functions
+     *
+     * @type {ConfigUtils}
+     */
+    util: ConfigUtils;
+    /**
+     * <p>Get a configuration value</p>
+     *
+     * <p>
+     * This will return the specified property value, throwing an exception if the
+     * configuration isn't defined.  It is used to assure configurations are defined
+     * before being used, and to prevent typos.
+     * </p>
+     *
+     * @template T
+     * @param {string} property - The configuration property to get. Can include '.' sub-properties.
+     * @returns {T} The property value
+     */
+    get<T>(property: string): T;
+    /**
+     * Test that a configuration parameter exists
+     *
+     * <pre>
+     *    const config = require('config');
+     *    if (config.has('customer.dbName')) {
+     *      console.log('Customer database name: ' + config.customer.dbName);
+     *    }
+     * </pre>
+     *
+     * @method has
+     * @param {string} property - The configuration property to test. Can include '.' sub-properties.
+     * @return {boolean} - True if the property is defined, false if not defined.
+     */
+    has(property: string): boolean;
+    [LOAD_SYMBOL]: any;
+}
+/**
+ * The exported configuration instance type.
+ * This is here because the Config class is not a named export and this is how we get
+ * the exported configuration instance type.
+ * @typedef {ConfigClass} Config
+ */
+/**
+ * Source of config.util utility functions.
+ *
+ * In general, lib/util.js is what you are looking for.
+ *
+ * @class ConfigUtils
+ */
+declare class ConfigUtils {
+    /**
+     * @param {Config} config
+     */
+    constructor(config: Config);
+    /**
+     * <p>
+     * Set default configurations for a node.js module.
+     * </p>
+     *
+     * <p>
+     * This allows module developers to attach their configurations onto the
+     * default configuration object so they can be configured by the consumers
+     * of the module.
+     * </p>
+     *
+     * <p>Using the function within your module:</p>
+     * <pre>
+     *   const CONFIG = require("config");
+     *   CONFIG.util.setModuleDefaults("MyModule", {
+     *   &nbsp;&nbsp;templateName: "t-50",
+     *   &nbsp;&nbsp;colorScheme: "green"
+     *   });
+     * <br>
+     *   // Template name may be overridden by application config files
+     *   console.log("Template: " + CONFIG.MyModule.templateName);
+     * </pre>
+     *
+     * <p>
+     * The above example results in a "MyModule" element of the configuration
+     * object, containing an object with the specified default values.
+     * </p>
+     *
+     * @method setModuleDefaults
+     * @param {string} moduleName - Name of your module.
+     * @param {any} defaultProperties - The default module configuration.
+     * @return {any} moduleConfig - The module level configuration object.
+     * @see Load.scan() for loading more robust defaults
+     */
+    setModuleDefaults(moduleName: string, defaultProperties: any): any;
+    /**
+     * Set default configurations for a node.js module.
+     *
+     * This variant is provided to support handling loading of multiple versions
+     * of a library. This is meant for module developers to create a config snapshot
+     * for an old version of the code, particularly during a staged upgrade.
+     * Instead of adding the values to the configuration, it creates a new Config
+     * instance that contains the provided defaults.
+     *
+     * Note: This feature is primarily useful for adding, removing, or renaming
+     * properties. It will struggle to deal with changing the semantics of
+     * existing fields if you need to override those fields in your top level
+     * config/ directory. It is always best when versioning an API to change the
+     * names of fields when you change the meaning of the field.
+     *
+     * <p>Using the function within your module:</p>
+     * <pre>
+     *   const configModule = require("config");
+     *   const config = configModule.withModuleDefaults("MyModule", {
+     *   &nbsp;&nbsp;templateName: "t-50",
+     *   &nbsp;&nbsp;colorScheme: "green"
+     *   });
+     * <br>
+     *   // Template name may be overridden by application config files
+     *   console.log("Template: " + config.MyModule.templateName);
+     * </pre>
+     *
+     * <p>
+     * The above example results in a "MyModule" element of the configuration
+     * object, containing an object with the specified default values.
+     * </p>
+     *
+     * @method withModuleDefaults
+     * @param moduleName {string} - Name of your module.
+     * @param defaultProperties {Object} - The default module configuration.
+     * @returns {Config}
+     * @see Load.scan() for loading more robust defaults
+     */
+    withModuleDefaults(moduleName: string, defaultProperties: any): Config;
+    /**
+     * <p>Make a javascript object property immutable (assuring it cannot be changed
+     * from the current value).</p>
+     * <p>
+     * If the specified property is an object, all attributes of that object are
+     * made immutable, including properties of contained objects, recursively.
+     * If a property name isn't supplied, the object and all of its properties
+     * are made immutable.
+     * </p>
+     * <p>
+     * This operation cannot be undone.
+     * </p>
+     *
+     * <p>Example:</p>
+     * <pre>
+     *   const config = require('config');
+     *   const myObject = {hello:'world'};
+     *   config.util.makeImmutable(myObject);
+     * </pre>
+     *
+     * @method makeImmutable
+     * @deprecated see Util.makeImmutable()
+     * @param {any} object - The object to specify immutable properties for
+     * @param {string | string[]=} property - The name of the property (or array of names) to make immutable.
+     *        If not provided, the entire object is marked immutable.
+     * @param {any=} 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 {any} - The original object is returned - for chaining.
+     */
+    makeImmutable(object: any, property?: (string | string[]) | undefined, value?: any | undefined): any;
+    /**
+     * <p>Make a javascript object property immutable (assuring it cannot be changed
+     * from the current value).</p>
+     * <p>
+     * If the specified property is an object, all attributes of that object are
+     * made immutable, including properties of contained objects, recursively.
+     * If a property name isn't supplied, the object and all of its properties
+     * are made immutable.
+     * </p>
+     * <p>
+     * This operation cannot be undone.
+     * </p>
+     *
+     * <p>Example:</p>
+     * <pre>
+     *   const config = require('config');
+     *   const myObject = {hello:'world'};
+     *   config.util.makeImmutable(myObject);
+     * </pre>
+     *
+     * @method makeImmutable
+     * @protected
+     * @deprecated - partial immutability will no longer be supported by this project
+     * @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, the entire object is marked 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.
+     */
+    protected makeImmutablePartial(object: any, property: string | [string], value?: any | [any]): any;
+    /**
+     * Return the sources for the configurations
+     *
+     * <p>
+     * All sources for configurations are stored in an array of objects containing
+     * the source name (usually the filename), the original source (as a string),
+     * and the parsed source as an object.
+     * </p>
+     *
+     * @method getConfigSources
+     * @return {import('./util.js').ConfigSource[]} configSources - An array of objects containing
+     *    name, original, and parsed elements
+     */
+    getConfigSources(): import("./util.js").ConfigSource[];
+    /**
+     * Load the individual file configurations.
+     *
+     * <p>
+     * This method builds a map of filename to the configuration object defined
+     * by the file.  The search order is:
+     * </p>
+     *
+     * <pre>
+     *   default.EXT
+     *   (deployment).EXT
+     *   (hostname).EXT
+     *   (hostname)-(deployment).EXT
+     *   local.EXT
+     *   local-(deployment).EXT
+     * </pre>
+     *
+     * <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
+     * 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>
+     *
+     * <p>
+     * hostname is the $HOST environment variable (or --HOST command line parameter)
+     * if set, otherwise the $HOSTNAME environment variable (or --HOSTNAME command
+     * line parameter) if set, otherwise the hostname found from
+     * require('os').hostname().
+     * </p>
+     *
+     * <p>
+     * Once a hostname is found, everything from the first period ('.') onwards
+     * is removed. For example, abc.example.com becomes abc
+     * </p>
+     *
+     * <p>
+     * (deployment) is the deployment type, found in the $NODE_ENV environment
+     * variable (which can be overridden by using $NODE_CONFIG_ENV
+     * environment variable). Defaults to 'development'.
+     * </p>
+     *
+     * <p>
+     * If the $NODE_APP_INSTANCE environment variable (or --NODE_APP_INSTANCE
+     * command line parameter) is set, then files with this appendage will be loaded.
+     * See the Multiple Application Instances section of the main documentation page
+     * for more information.
+     * </p>
+     *
+     * @see Util.loadFileConfigs for discrete execution of most of this functionality
+     * @method loadFileConfigs
+     * @param {string=} configDir the path to the directory containing the configurations to load
+     * @param {LoadOptions=} options parsing options
+     * @return {Record<string, any>} The configuration object
+     */
+    loadFileConfigs(configDir?: string | undefined, options?: LoadOptions | undefined): Record<string, any>;
+    /**
+     * Attach the Config class prototype to all config objects recursively.
+     *
+     * <p>
+     * This allows you to do anything with CONFIG sub-objects as you can do with
+     * the top-level CONFIG object.  It's so you can do this:
+     * </p>
+     *
+     * <pre>
+     *   const CUST_CONFIG = require('config').Customer;
+     *   CUST_CONFIG.get(...)
+     * </pre>
+     *
+     * @method attachProtoDeep
+     * @param {object} toObject
+     * @param {number} [depth=20]
+     * @return {object}
+     */
+    attachProtoDeep(toObject: object, depth?: number): object;
+    /**
+     * <p>Get a Config Environment Variable Value</p>
+     *
+     * <p>
+     * This method returns the value of the specified config environment variable,
+     * including any defaults or overrides.
+     * </p>
+     *
+     * @method getEnv
+     * @param varName {String} The environment variable name
+     * @return {String} The value of the environment variable
+     */
+    getEnv(varName: string): string;
+    /**
+     * Returns a new deep copy of the current config object, or any part of the config if provided.
+     *
+     * @param {object} [config] The part of the config to copy and serialize. Omit this argument to return the entire config.
+     * @returns {object} The cloned config or part of the config
+     */
+    toObject(config?: object): object;
+    /**
+     * Run strictness checks on NODE_ENV and NODE_APP_INSTANCE and throw an error if there's a problem.
+     * @param {Config} [config]
+     */
+    runStrictnessChecks(config?: Config): void;
+    /**
+     * @deprecated please use Parser.stripYamlComments
+     * @param {string} fileStr The string to strip comments from
+     */
+    stripYamlComments(fileStr: string): any;
+    #private;
+}
+declare const LOAD_SYMBOL: unique symbol;