config 4.2.1 → 4.4.0

package/package.json

@@ -1,7 +1,48 @@
 {
   "name": "config",
-  "version": "4.2.1",
+  "version": "4.4.0",
   "main": "./lib/config.js",
+  "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"
+      ],
+      "lib/defer.js": [
+        "types/lib/defer.d.ts"
+      ],
+      "lib/util": [
+        "types/lib/util.d.ts"
+      ],
+      "lib/util.js": [
+        "types/lib/util.d.ts"
+      ]
+    }
+  },
   "description": "Configuration control for production node deployments",
   "author": "Loren West <open_source@lorenwest.com>",
   "homepage": "http://github.com/node-config/node-config.git",
@@ -25,17 +66,18 @@
     "json5": "^2.2.3"
   },
   "devDependencies": {
-    "@types/node": "^7.0.8",
+    "@types/node": "^20.11.30",
     "c8": "^10.1.3",
     "coffeescript": "2.2.4",
     "cson": "^3.0.1",
+    "faceoff": "^1.3.0",
     "hjson": "^1.2.0",
     "properties": "~1.2.1",
     "request": "^2.88.2",
     "semver": "5.3.0",
     "toml": "^2.0.6",
-    "ts-node": "^3.3.0",
-    "typescript": "^2.4.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.9.3",
     "underscore": "^1.8.3",
     "x2js": "^2.0.1",
     "yaml": "^2.8.2"
@@ -56,6 +98,12 @@
     "reporter": "lcov"
   },
   "scripts": {
-    "test": "NODE_OPTIONS='--no-experimental-strip-types' c8 node --test"
+    "build:types": "tsc -p tsconfig.json",
+    "checkTypes": "npx -y @arethetypeswrong/cli --pack .",
+    "types": "npm run build:types && npm run checkTypes",
+    "prepublishOnly": "npm run build:types",
+    "ci": "npm run types && npm run test",
+    "test": "c8 node --no-experimental-strip-types --test",
+    "benchmarks": "node --allow-natives-syntax --expose-gc benchmarks/index.js"
   }
 }

package/parser.js

@@ -35,10 +35,16 @@ var COFFEE_2_DEP = 'coffeescript',
     TS_DEP = 'ts-node';
 
 /**
- * @typedef Parser {Object}
+ * @template [T=any]
+ * @typedef {(filename: string, content: string) => T | undefined} ParserFn<T>
  */
 var Parser = module.exports;
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object | undefined}
+ */
 Parser.parse = function(filename, content) {
   var parserName = filename.substr(filename.lastIndexOf('.') +1);  // file extension
   if (typeof definitions[parserName] === 'function') {
@@ -47,6 +53,11 @@ Parser.parse = function(filename, content) {
   // TODO: decide what to do in case of a missing parser
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.xmlParser = function(filename, content) {
   if (!XML) {
     XML = require(XML_DEP);
@@ -60,6 +71,11 @@ Parser.xmlParser = function(filename, content) {
   return configObject;
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.jsParser = function(filename, content) {
   var configObject = require(filename);
 
@@ -69,6 +85,11 @@ Parser.jsParser = function(filename, content) {
   return configObject;
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.tsParser = function(filename, content) {
   if (!require.extensions['.ts']) {
     require(TS_DEP).register({
@@ -93,6 +114,11 @@ Parser.tsParser = function(filename, content) {
   return configObject;
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.coffeeParser = function(filename, content) {
   // .coffee files can be loaded with either coffee-script or iced-coffee-script.
   // Prefer iced-coffee-script, if it exists.
@@ -125,6 +151,11 @@ Parser.coffeeParser = function(filename, content) {
   return require(filename);
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object | undefined}
+ */
 Parser.icedParser = function(filename, content) {
   Iced = require(ICED_DEP);
 
@@ -134,6 +165,11 @@ Parser.icedParser = function(filename, content) {
   }
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object | undefined}
+ */
 Parser.yamlParser = function(filename, content) {
   if (!Yaml && !JSYaml) {
     // Lazy loading
@@ -155,6 +191,11 @@ Parser.yamlParser = function(filename, content) {
   }
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.jsonParser = function(filename, content) {
   /**
    * Default JSON parsing to JSON5 parser.
@@ -164,10 +205,20 @@ Parser.jsonParser = function(filename, content) {
   return JSON5.parse(content);
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.json5Parser = function(filename, content) {
   return JSON5.parse(content);
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.hjsonParser = function(filename, content) {
   if (!HJSON) {
     HJSON = require(HJSON_DEP);
@@ -175,6 +226,11 @@ Parser.hjsonParser = function(filename, content) {
   return HJSON.parse(content);
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.tomlParser = function(filename, content) {
   if(!TOML) {
     TOML = require(TOML_DEP);
@@ -182,6 +238,11 @@ Parser.tomlParser = function(filename, content) {
   return TOML.parse(content);
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.csonParser = function(filename, content) {
   if (!CSON) {
     CSON = require(CSON_DEP);
@@ -193,6 +254,11 @@ Parser.csonParser = function(filename, content) {
   return CSON.parse(content);
 };
 
+/**
+ * @param {string} filename
+ * @param {string} content
+ * @returns {object}
+ */
 Parser.propertiesParser = function(filename, content) {
   if (!PPARSER) {
     PPARSER = require(PPARSER_DEP);
@@ -207,7 +273,7 @@ Parser.propertiesParser = function(filename, content) {
  *
  * @protected
  * @method stripYamlComments
- * @param fileStr {string} The string to strip comments from
+ * @param {string} fileStr The string to strip comments from
  * @return {string} The string with comments stripped.
  */
 Parser.stripYamlComments = function(fileStr) {
@@ -220,7 +286,8 @@ Parser.stripYamlComments = function(fileStr) {
  * Parses the environment variable to the boolean equivalent.
  * Defaults to false
  *
- * @param {String} content - Environment variable value
+ * @param {string} filename - Filename of the env variable (not used)
+ * @param {string} content - Environment variable value
  * @return {boolean} - Boolean value fo the passed variable value
  */
 Parser.booleanParser = function(filename, content) {
@@ -231,8 +298,9 @@ Parser.booleanParser = function(filename, content) {
  * Parses the environment variable to the number equivalent.
  * Defaults to undefined
  *
- * @param {String} content - Environment variable value
- * @return {Number} - Number value fo the passed variable value
+ * @param {string} filename - Filename of the env variable (not used)
+ * @param {string} content - Environment variable value
+ * @return {number} - Number value fo the passed variable value
  */
 Parser.numberParser = function(filename, content) {
   const numberValue = Number(content);
@@ -262,10 +330,18 @@ var definitions = {
   number: Parser.numberParser
 };
 
+/**
+ * @param {string} name
+ * @returns {ParserFn | undefined}
+ */
 Parser.getParser = function(name) {
   return definitions[name];
 };
 
+/**
+ * @param {string} name
+ * @param {ParserFn} parser
+ */
 Parser.setParser = function(name, parser) {
   definitions[name] = parser;
   if (order.indexOf(name) === -1) {
@@ -273,6 +349,10 @@ Parser.setParser = function(name, parser) {
   }
 };
 
+/**
+ * @param {string=} name
+ * @returns {string[] | number}
+ */
 Parser.getFilesOrder = function(name) {
   if (name) {
     return order.indexOf(name);
@@ -280,6 +360,11 @@ Parser.getFilesOrder = function(name) {
   return order;
 };
 
+/**
+ * @param {string|string[]} name
+ * @param {number=} newIndex
+ * @returns {string[]}
+ */
 Parser.setFilesOrder = function(name, newIndex) {
   if (Array.isArray(name)) {
     return order = name;

package/raw.js

@@ -1,15 +1,16 @@
+const { Util, RawConfig } = require('./lib/util')
+
 /**
- * This is meant to wrap configuration objects that should be left as is,
- * meaning that the object or its prototype will not be modified in any way
+ * @param {any} rawObj
+ * @returns {RawConfig & { resolve: () => any }}
  */
-function RawConfig () {
-}
-
 function raw(rawObj) {
-  var obj = Object.create(RawConfig.prototype);
-  obj.resolve = function () { return rawObj; }
-  return obj;
+  Util.errorOnce('RAW_CONFIG', 'node-config now supports config file callbacks in place of raw(), which is deprecated.');
+
+  return RawConfig.raw(rawObj);
 }
 
+/** @deprecated please use callback function */
 module.exports.RawConfig = RawConfig;
+/** @deprecated please use callback function */
 module.exports.raw = raw;

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "rootDir": ".",
+    "module": "commonjs",
+    "target": "es2020",
+    "skipLibCheck": true
+  },
+  "include": ["*.js", "lib/**/*.js"],
+  "exclude": ["test/**", "tools/**", "coverage/**", "node_modules/**"]
+}

package/types/async.d.ts

@@ -0,0 +1,23 @@
+export type Config = import("./lib/config").Config;
+export type DeferredConfig = import("./defer").DeferredConfig;
+/**
+ * @template T
+ * @overload
+ * @param {Promise<T>} promiseOrFunc
+ * @returns {Promise<T>}
+ */
+export function asyncConfig<T>(promiseOrFunc: Promise<T>): Promise<T>;
+/**
+ * @template T
+ * @overload
+ * @param {(config: Config, original: any) => Promise<T>} promiseOrFunc
+ * @returns {DeferredConfig}
+ */
+export function asyncConfig<T>(promiseOrFunc: (config: Config, original: any) => Promise<T>): DeferredConfig;
+/**
+ * Do not use `config.get` before executing this method, it will freeze the config object.
+ * @param {Config} config the main config object, returned from require('config')
+ * @returns {Promise<Config>}   once all promises are resolved, return the original config object
+ * @deprecated please use async functions with defer and Util.resolveAsyncConfigs
+ */
+export function resolveAsyncConfigs(config: Config): Promise<Config>;

package/types/defer.d.ts

@@ -0,0 +1,3 @@
+export const deferConfig: typeof import("./lib/defer").deferConfig;
+export { DeferredConfig };
+import { DeferredConfig } from "./lib/defer.js";