A TypeScript isomorphic adaptation of Java's Optional.
All methods of Java's Optional class are implemented except for hashCode and stream.
npm:
$ npm install neatutil.optionalyarn:
$ yarn add neatutil.optionalimport { Optional } from 'neatutil.optional';
const emptyInstance = Optional.empty();
console.log(emptyInstance.isPresent()); // => false
console.log(emptyInstance.isEmpty()); // => true
console.log(emptyInstance.toString()); // => 'Optional.empty'
const nonEmptyInstance = Optional.of<string>('I love Espresso coffee.');
console.log(nonEmptyInstance.isPresent()); // => true
console.log(nonEmptyInstance.isEmpty()); // => false
console.log(nonEmptyInstance.get()); // => 'I love Espresso coffee.'
console.log(nonEmptyInstance.toString()); // => 'Optional[I love Espresso coffee.]'
const anotherEmptyInstance = Optional.ofNullable(null);
console.log(anotherEmptyInstance.isPresent()); // => false
console.log(anotherEmptyInstance.isEmpty()); // => true
console.log(anotherEmptyInstance.toString()); // => 'Optional.empty'
const anotherNonEmptyInstance = Optional.ofNullable<string>('I love Espresso coffee.');
console.log(anotherNonEmptyInstance.isPresent()); // => true
console.log(anotherNonEmptyInstance.isEmpty()); // => false
console.log(anotherNonEmptyInstance.get()); // => 'I love Espresso coffee.'
console.log(anotherNonEmptyInstance.toString()); // => 'Optional[I love Espresso coffee.]'
console.log(emptyInstance.equals(nonEmptyInstance)); // => false
console.log(emptyInstance.equals(anotherEmptyInstance)); // => true
console.log(nonEmptyInstance.equals(anotherNonEmptyInstance)); // => trueOptional<TValue>A container object which may or may not contain a non-nullish value. If a value is present, isPresent() returns true. If no value is present, the object is considered empty and isPresent() returns false.
This is a value-based class; instances that are equal should be treated as interchangeable.
Optional is primarily intended for use as a method return type where there is a clear need to represent "no result", and where using null or undefined is likely to cause errors. A variable whose type is Optional should never itself be null or undefined; it should always point to an Optional instance.
Type Parameters:
TValue - The type of value.
static empty<TValue>(): Optional<TValue>Returns an empty Optional instance. No value is present for this Optional.
Type Parameters:
TValue - The type of value.
Returns:
An empty Optional instance.
static of<TValue>(value: TValue): Optional<TValue>Returns an Optional instance describing the given non-nullish value.
Type Parameters:
TValue - The type of value.
Parameters:
value - The value to describe, which must be non-nullish.
Returns:
An Optional instance with the value present.
Throws:
TypeError - If value is nullish.
static ofNullable<TValue>(value?: TValue): Optional<TValue>Returns an Optional instance describing the given value, if non-nullish, otherwise returns an empty Optional instance.
Type Parameters:
TValue - The type of value.
Parameters:
value - The possibly-nullish value to describe.
Returns:
An Optional instance with a present value if the specified value is non-nullish, otherwise an empty Optional instance.
equals(other: Optional<TValue>): booleanIndicates whether some other Optional instance is "equal to" this Optional instance.
The other Optional instance is considered equal if:
- both instances have no value present or;
- the present values are "equal to" each other.
Parameters:
other - An Optional instance to be tested for equality.
Returns:
true if the other Optional instance is "equal to" this Optional instance, otherwise false.
filter(predicate: (value: TValue) => boolean): Optional<TValue>If a value is present, and the value matches the given predicate, returns an Optional instance describing the value, otherwise returns an empty Optional instance.
Parameters:
predicate - The predicate to apply to the value, if present.
Returns:
An Optional instance describing the value of this Optional, if a value is present and the value matches the given predicate, otherwise an empty Optional instance.
Throws:
TypeError - If predicate is not a function.
flatMap<UValue>(mapper: (value: TValue) => Optional<UValue>): Optional<UValue>If a value is present, returns the result of applying the given Optional-bearing mapping function to the value, otherwise returns an empty Optional instance.
Type Parameters:
UValue - The type of value of the Optional instance returned by the mapping function.
Parameters:
mapper - The mapping function to apply to the value, if present.
Returns:
The result of applying an Optional-bearing mapping function to the value of this Optional, if a value is present, otherwise an empty Optional instance.
Throws:
TypeError - If mapper is not a function or does not return an Optional instance.
get(): TValueIf a value is present, returns the value, otherwise throws.
Returns:
The non-nullish value described by this Optional instance.
Throws:
Error - If no value is present.
ifPresent(action: (value: TValue) => void): voidIf a value is present, performs the given action with the value, otherwise does nothing.
Parameters:
action - The action to be performed, if a value is present.
Throws:
TypeError - If action is not a function.
ifPresentOrElse(action: (value: TValue) => void, emptyAction: () => void): voidIf a value is present, performs the given action with the value, otherwise performs the given empty-based action.
Parameters:
action - The action to be performed, if a value is present.
emptyAction - The empty-based action to be performed, if no value is present.
Throws:
TypeError - If action or emptyAction is not a function.
isEmpty(): booleanIf a value is not present, returns true, otherwise false.
Returns:
true if a value is not present, otherwise false.
isPresent(): booleanIf a value is present, returns true, otherwise false.
Returns:
true if a value is present, otherwise false.
map<UValue>(mapper: (value: TValue) => UValue): Optional<UValue>If a value is present, returns an Optional instance describing the result of applying the given mapping function to the value, otherwise returns an empty Optional instance.
Type Parameters:
UValue - The type of the value returned from the mapping function.
Parameters:
mapper - The mapping function to apply to a value, if present.
Returns:
An Optional instance describing the result of applying a mapping function to the value of this Optional, if a value is present, otherwise an empty Optional instance.
Throws:
TypeError - If mapper is not a function.
or(supplier: () => Optional<TValue>): Optional<TValue>If a value is present, returns an Optional instance describing the value, otherwise returns an Optional instance produced by the supplying function.
Parameters:
supplier - The supplying function that produces an Optional instance to be returned.
Returns:
An Optional instance describing the value of this Optional, if a value is present, otherwise an Optional instance produced by the supplying function.
Throws:
TypeError - If supplier is not a function or does not return an Optional instance.
orElse(other: TValue | null = null): TValue | nullIf a value is present, returns the value, otherwise returns other.
Parameters:
other - The value to be returned, if no value is present. May be nullish.
Returns:
The value, if present, otherwise other.
orElseGet(supplier: () => TValue | null): TValue | nullIf a value is present, returns the value, otherwise returns the result produced by the supplying function.
Parameters:
supplier - The supplying function that produces a value to be returned.
Returns:
The value, if present, otherwise the result produced by the supplying function.
Throws:
TypeError - If supplier is not a function.
orElseThrow(): TValueIf a value is present, returns the value, otherwise throws.
Returns:
The non-nullish value described by this Optional.
Throws:
Error - If no value is present.
orElseGetThrow<TError extends Error>(errorSupplier: () => TError): TValueIf a value is present, returns the value, otherwise throws an error produced by the error supplying function.
Type Parameters:
TError - Type of the error to be thrown.
Parameters:
errorSupplier - The supplying function that produces an error to be thrown.
Returns:
The value, if present.
Throws:
TError - If no value is present.
TypeError - If errorSupplier is not a function or does not return an Error instance.
toString(): stringReturns a non-empty string representation of this Optional suitable for debugging.
Returns:
The string representation of this instance.
Copyright (c) 2023 Alexis Loïc A. Menest - Released under the MIT license.