Configuration via process.env, with warnings

Get configuration from process.env (or other objects), loading defaults from a last resort declaration.

Retrieving the default value from the last resort object will trigger a warning when retrieved for the first time and one of the following is true:

• NODE_ENV=production - in production, supply full configuration
• DEBUG=convig - standard debug

Usage

convig = require("convig");
CONFIG = convig.chain(process.env, {foo: "FOO", bool: "on", dne: 0}, {
  foo: "foo"
  ,bar: function(){ return this.foo + ", and bar, too"; }
  ,baz: function(){ throw new Error("baz may NOT fallback!"); }
  ,numInt: 42
  ,numFloat: Math.PI
  ,infinite: Infinity
  ,bool: false
  ,noWarning: null
  ,csv: ["a", "b", "c"]
});

The above says to get values from process.env, then an object literal, and as a last resort from the default object at the end -- which also declares the types. When the last resort value is used, a warning will be written on stderr (but only the first time, and only if the last resort value isn't null).

NOTE: you can trigger warnings by calling the special function "warn", which returns the configuration object:

CONFIG = config.chain(process.env, {
  foo: "foo"
}).warn()

In the (contrived) example above, the CONFIG return value provides getters which behave as follows:

• process.env will be tried first, then the second object literal, then the last resort.
• the CONFIG only has getters from "last resort"
  • e.g. the dne property of the object literal is not reachable via CONFIG.
• values retrieved in the chain before "last resort" are cast to the same type as those in the last resort. This allows ENV vars (always strings) to be cast as either numbers, or (more helpfully) booleans or even arrays.
  • "on", "true", "yes" & "1" are cast to true, anything else is false
  • if last resort value is an array, and retrieved value is a string, it will be split by commas (or another separator - keep reading) into array of strings
  • if last resort is an integer, strings "Infinity" and "-Infinity" cast as expected (e.g. you get the javascript Infinity)
  • if last resort is +/-Infinity, strings and literal Infinity-values work, everything else will be cast to an integer
  • if last resort is RegExp, values will be cast into RegExp objects. flags are parsed when strings start & end with "/" (plus optional flags).
• instead of literals, functions may be provided, in which case they will be called with this scoped to the CONFIG object.

Assuming no matches on process.env set above:

CONFIG.foo;       // "FOO"
CONFIG.bar;       // "FOO, and bar, too"
CONFIG.baz;       // throws Error! do this to require e.g. process.env to be set
CONFIG.bool;      // true (from "on" in object literal)
CONFIG.numInt;    // 42
CONFIG.numFloat;  // Math.PI
CONFIG.infinite;  // Infinity
CONFIG.dne;       // undefined
CONFIG.noWarning; // null (will not output a warning)
CONFIG.csv        // ["a", "b", "c"]

Another way to declare process.env as first preference is:

require("convig").env(nonWarningDefaults, lastResort)

More likely, you are only interested in the last resort definition: require("convig").env(lastResort)

Split string into array

You can change the character used to split strings into an array (when the last resort entry is an array) using the setter property split.

CONFIG = convig.chain({mylist: "click;clack;zoom"}, {
  mylist: ["these", "are a", "few of my", "favourite", "strings"]
})
CONFIG.mylist      // ["click;clack;zoom"] - array, but not quite right
CONFIG.split = ";" // use a semicolon when splitting arrays from here on out
CONFIG.mylist      // ["click", "clack", "zoom"]
CONFIG.split = "," // you can even set it back if you want to
CONFIG.mylist      // ["click;clack;zoom"] - still an array, but no comma!