@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:

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:

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 or CC0, 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 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.

Example

A runnable version of this example can be found in example.js in the repository.

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