NeatUtil.Optional
A TypeScript isomorphic adaptation of Java's Optional.
All methods of Java's Optional
class are implemented except for hashCode
and stream
.
Installation
npm:
$ npm install neatutil.optional
yarn:
$ yarn add neatutil.optional
Basic usage
import { 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)); // => true
API
Optional<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>): boolean
Indicates 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(): TValue
If 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): void
If 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): void
If 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(): boolean
If a value is not present, returns true
, otherwise false
.
Returns:
true
if a value is not present, otherwise false
.
isPresent(): boolean
If 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 | null
If 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 | null
If 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(): TValue
If 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): TValue
If 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(): string
Returns a non-empty string
representation of this Optional
suitable for debugging.
Returns:
The string representation of this instance.
Copyright & license
Copyright (c) 2023 Alexis Loïc A. Menest - Released under the MIT license.