consumable/README.md

# @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.