You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
# @joepie91/consumable
|
|
|
|
A simple wrapper for dealing with 'consumable' values, ie. values that are only supposed to be used once.
|
|
|
|
You might've found yourself writing something like this, at some point:
|
|
|
|
```js
|
|
let bufferedValue;
|
|
|
|
// ... some code ...
|
|
|
|
bufferedValue = "foo bar";
|
|
|
|
// ... more code ...
|
|
|
|
function takeBuffer() {
|
|
let takenValue = bufferedValue;
|
|
bufferedValue = null;
|
|
return takenValue;
|
|
}
|
|
```
|
|
|
|
This library is just a simple abstraction, that turns that into:
|
|
|
|
```js
|
|
let bufferedValue = consumable();
|
|
|
|
// ... some code ...
|
|
|
|
bufferedValue.set("foo bar");
|
|
|
|
// ... more code ...
|
|
|
|
function takeBuffer() {
|
|
return bufferedValue.consume();
|
|
}
|
|
```
|
|
|
|
... with some extra internal checks in place to throw an error when a value is unexpectedly missing.
|
|
|
|
## License, donations, and other boilerplate
|
|
|
|
Licensed under either the [WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), at your choice. In practice, that means it's more or less public domain, and you can do whatever you want with it. Giving credit is *not* required, but still very much appreciated! I'd love to [hear from you](mailto:admin@cryto.net) if this module was useful to you.
|
|
|
|
Creating and maintaining open-source modules is a lot of work. A donation is also not required, but much appreciated! You can donate [here](http://cryto.net/~joepie91/donate.html).
|
|
|
|
## Example
|
|
|
|
A runnable version of this example can be found in `example.js` in the repository.
|
|
|
|
```js
|
|
"use strict";
|
|
|
|
const consumable = require("@joepie91/consumable");
|
|
|
|
let singleUseValue = consumable(42);
|
|
|
|
console.log(singleUseValue.isSet()); // true
|
|
console.log(singleUseValue.peek()); // 42
|
|
console.log(singleUseValue.consume()); // 42
|
|
console.log(singleUseValue.peek()); // Throws!
|
|
console.log(singleUseValue.isSet()); // false
|
|
|
|
/* Now let's try with a different value, and using `replace`... */
|
|
singleUseValue.set(13);
|
|
console.log(singleUseValue.peek()); // 13
|
|
console.log(singleUseValue.replace(9001)); // 13
|
|
console.log(singleUseValue.peek()); // 9001
|
|
|
|
/* Note how it can distinguish between an explicitly-set `undefined`, and just nothing being set. */
|
|
singleUseValue.set(undefined);
|
|
console.log(singleUseValue.isSet()); // true
|
|
console.log(singleUseValue.peek()); // undefined
|
|
console.log(singleUseValue.consume()); // undefined
|
|
console.log(singleUseValue.isSet()); // false
|
|
console.log(singleUseValue.peek()); // Throws!
|
|
console.log(singleUseValue.consume()); // Throws!
|
|
```
|
|
|
|
## API
|
|
|
|
### consumable(initialValue)
|
|
|
|
Creates and returns a new `consumableValue`, optionally with an `initialValue`.
|
|
|
|
The consumable will be considered to have been 'set' if the `initialValue` is *not* `undefined`. If you intend to initialize it with `undefined` as an explicit value, you should use a separate `.set` call instead.
|
|
|
|
### consumableValue.consume()
|
|
|
|
Returns whatever value is currently set, and unsets it internally. Future calls to `.consume`, `.peek` and `.replace` will fail until a new value is `.set`.
|
|
|
|
Throws if no value is currently set.
|
|
|
|
### consumableValue.peek()
|
|
|
|
Returns the currently-set value, but does not unset it internally. This is a utility function for edge cases, and not intended as the main API - if you are only using `.peek` and not `.consume`, then you probably don't need this library at all.
|
|
|
|
Throws if no value is currently set.
|
|
|
|
### consumableValue.set(newValue)
|
|
|
|
Sets a new value, overriding the previous one if any.
|
|
|
|
- __newValue:__ The new value to set.
|
|
|
|
### consumableValue.replace(newValue)
|
|
|
|
A combination of `.consume` and `.set`; returns the previously-set value and sets the specified `newValue` as the new value.
|
|
|
|
- __newValue:__ The new value to set.
|
|
|
|
Throws if no value is currently set.
|
|
|
|
### consumableValue.isSet()
|
|
|
|
Returns `true` when a value is currently set, or `false` otherwise.
|