diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..dfe5d58 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +## 1.0.0 (August 17, 2016) + +First stable and documented release - however, the functionality or API has not changed from `0.0.3`. + +* __Documentation:__ Updated donation text. +* __Documentation:__ Added documentation and a changelog. + +## 0.0.3 (April 17, 2016) + +* __Patch:__ Updated test script to use new `evaluate` option. + +## 0.0.2 (April 17, 2016) + +* __Major:__ Maked value evaluation opt-in. + +## 0.0.1 (April 17, 2016) + +Initial release. \ No newline at end of file diff --git a/README.md b/README.md index fba1839..6b84102 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # default-value -TODO +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 @@ -8,9 +10,9 @@ TODO ## Donate -My income consists largely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)! +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. +You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you! ## Contributing @@ -22,8 +24,82 @@ Be aware that by making a pull request, you agree to release your modifications ## Usage -TODO +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 -TODO \ No newline at end of file +### 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. \ No newline at end of file