JavaScript implementation of the Maybe type, inspired by java.lang.Optional.
The library supports both Node.js and browser environments.
- Node:
npm install optional2 --save
- Browser:
<script src="https://raw.githubusercontent.com/rideg/Optional/v1.0.3/optional.min.js" type="text/javascript"> </script>
When using with Node.js you need to import the library first:
const Optional = require('optional2');
In the browser, the initialization script creates the global Optional object which can be used later on.
There are two states of the Optional type: present and absent. In the following example, you can see how to create them:
const present = Optional.of('value');
const absent = Optional.absent();
// If the given value is null or undefined then
// the returned Optional will be absent.
const absent2 = Optional.of(null);
const absent3 = Optional.of(undefined);
The resulting objects will be immutable, moreover the absent will always be the same instance.
There are two methods to check the state of the Optional (isPresent() and isAbsent()), both returns a boolean:
const present = Optional.of('value');
present.isPresent(); // => true
present.isAbsent(); // => false
const basent = Optional.absent();
absent.isPresent(); // => false
absent.isAbsent(); // => true
If a function is required to be executed conditionally the ifPresent(callback) function can be used. If the value is present then the callback will be called with the value, otherwise, the callback will be ignored.
const present = Optional.of('value');
present.ifPresent((value) => console.log(value)); // => "value" will be printed.
const absent = Optional.absent();
absent.ifPresent((value) => doSomeCrazyThing(value)); // => nothing crazy will happend.
The contained value can be retrieved if it is present, otherwise, an error will be thrown.
Optional.of('value').get(); // => "value"
Optional.absent().get(); // => Error('Value is absent') will be thrown.
If the value is absent, there are multiple ways to supply defaults.
Optional.absent().orElse('value'); // => "value"
Optional.absent().orElseGet(() => 'value') // => "value"
The optional value can be mapped to something else if is present. If it is absent, the result will be absent as well.
Optional.of('value').map((value) => value.toUpperCase()).get(); // => "VALUE"
Optional.absent().map((value) => transform(value)).isPresent(); // => false
The filter() method returns the instance itself if the value is present and the given predicate succeeds.
Optional.of(10).filter((value) => value > 5); // => "Optional['10']"
Optional.of(5).filter((value) => value > 5); // => "Optional[absent]"
Optional.absent().filter(() => true); // => "Optional[absent]"
If the global Promise object is available the Optional will have the promise() method which returns a promise of the value. The promise will be resolved immediately if the value is present, or will be rejected otherwise.
Optional.of('value').promise().then((value) => console.log('value')); // => "value" will be printed.
Optional.absent().promis()
.then((value) => console.log('got it'),
() => console.log('rejected')); // => "rejected" will be printed.
It also has the toString() method:
Optional.of('value').toString(); // => "Optional['value']"
Optional.absent().toString(); // => "Optional[absent]"