node-default-value/README.md

# 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](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), 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](http://cryto.net/~joepie91/donate.html)!

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:

```javascript
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:

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

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

For asynchronous values, using Promises:

```javascript
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:

```javascript
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:

```javascript

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.