Browse Source

Add documentation and changelog, update donation text

master
Sven Slootweg 5 years ago
parent
commit
df6e08a318
  1. 18
      CHANGELOG.md
  2. 86
      README.md

18
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.

86
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
### 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.
Loading…
Cancel
Save