default-value

Lets you easily define a default value for undefined options, with optional support for Promises and lazy evaluation.

More or less the equivalent of CoffeeScript's existential operator, when used for fallback values.

License

WTFPL or CC0, whichever you prefer. A donation and/or attribution are appreciated, but not required.

Donate

Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider making a donation!

You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!

Contributing

Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in src/, not those in lib/.

Build tool of choice is gulp; simply run gulp while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.

Usage

For synchronous values:

var defaultValue = require("default-value");

defaultValue("hello", "world");     // Result: "hello"
defaultValue(null, "world");        // Result: "world"
defaultValue(undefined, "world");   // Result: "world"

When used for default function arguments, that might look like this:

var defaultValue = require("default-value");

function doThing(speed) {
	var effectiveSpeed = defaultValue(speed, 10);
	console.log("Effective speed:", effectiveSpeed);
}

For asynchronous values, using Promises:

var Promise = require("bluebird");
var defaultValue = require("default-value");

Promise.try(() => {
	return defaultValue.async(getCurrentUser(), {id: 0});
}).then((user) => {
	/* `user` will be either the result of getCurrentUser or, if that result
	 * is `null` or `undefined`, it will be {id: 0}. */
});

Using evaluation:

var defaultValue = require("default-value");

defaultValue(config.delay, () => {
	/* This function will only be run if `config.delay` isn't set. */
	return getDelay();
}, {evaluate: true});

Using asynchronous evaluation:

var Promise = require("bluebird");
var defaultValue = require("default-value");

Promise.try(() => {
	return defaultValue.async(config.delay, database.table("config_options").get("delay"), {evaluate: true});
}).then((delay) => {
	/* `delay` will be either the value of `config.delay` or, if that
	 * isn't set, the value will be the result of the (hypothetical)
	 * database query above. The query itself will only happen if
	 * `config.delay` isn't set. */
});

API

defaultValue(value, fallbackValue, [options])

Returns the value synchronously - but when the value is null or undefined, it will return the fallbackValue instead.

• value: The value you intend to use.
• fallbackValue: The fallback value to use if the value isn't set.
• options:
  • evaluate: Defaults to false. If this is set to true, then if either the value or fallbackValue is a function, it will be executed and its return value will be used as the value, rather than the function itself. This is especially useful in cases where the fallback value is expensive to obtain.

defaultValue.async(value, fallbackValue, [options])

Equivalent to defaultValue, but this function will return a Promise. Similarly, value and fallbackValue may return a Promise as well, and the resulution of value will be awaited before deciding what to return.

The evaluate option is also available for this asynchronous variant, and works essentially the same - but now the evaluated functions can return a Promise as well.