Option
An Option
is either Some
(contains a value of type T
inside) or None
(no value).
Option<T> = Some<T> | None
Necessary imports:
import { None, Option, Some } from 'ts-results-es'
Construction:
const some = Some('some value')
// None is a singleton, no construction necessary
andThen()
andThen<T2>(mapper: (val: T) => Option<T2>): Option<T2>
Calls mapper
if the Option
is Some
, otherwise returns None
.
This function can be used for control flow based on Option
values.
value
The value contained in Some
. Only present on Some
objects.
expect()
expect(msg: string): T
Returns the contained Some
value, if exists. Throws an error if not.
If you know you’re dealing with Some
and the compiler knows it too (because you tested
isSome() or isNone()) you should use value instead. While Some
’s expect() and value will
both return the same value using value is preferable because it makes it clear that
there won’t be an exception thrown on access.
msg
: the message to throw if no Some
value.
isNone()
isNone(): this is None
true
when the Option
is None
.
isSome()
isSome(): this is Some<T>
true
when the Option
is Some
.
map()
map<U>(mapper: (val: T) => U): Option<U>
Maps an Option<T>
to Option<U>
by applying a function to a contained Some
value,
leaving a None
value untouched.
This function can be used to compose the Options of two functions.
mapOr()
mapOr<U>(default_: U, mapper: (val: T) => U): U
Maps an Option<T>
to Option<U>
by either converting T
to U
using mapper
(in case
of Some
) or using the default_
value (in case of None
).
If default_
is a result of a function call consider using mapOrElse() instead, it will
only evaluate the function when needed.
mapOrElse()
mapOrElse<U>(default_: () => U, mapper: (val: T) => U): U
Maps an Option<T>
to Option<U>
by either converting T
to U
using mapper
(in case
of Some
) or producing a default value using the default_
function (in case of None
).
or()
or(other: Option<T>): Option<T>
Returns Some()
if we have a value, otherwise returns other
.
other
is evaluated eagerly. If other
is a result of a function
call try orElse() instead – it evaluates the parameter lazily.
Example:
Some(1).or(Some(2)) // => Some(1)
None.or(Some(2)) // => Some(2)
orElse()
orElse(other: () => Option<T>): Option<T>
Returns Some()
if we have a value, otherwise returns the result
of calling other()
.
other()
is called only when needed.
Example:
Some(1).orElse(() => Some(2)) // => Some(1)
None.orElse(() => Some(2)) // => Some(2)
toAsyncOption()
toAsyncOption(): AsyncOption<T>
Creates an AsyncOption based on this Option.
Useful when you need to compose results with asynchronous code.
toResult()
toResult<E>(error: E): Result<T, E>
Maps an Option<T>
to a Result<T, E>
.
unwrap()
unwrap(): T
Returns the contained Some
value.
Because this function may throw, its use is generally discouraged.
Instead, prefer to handle the None
case explicitly.
If you know you’re dealing with Some
and the compiler knows it too (because you tested
isSome() or isNone()) you should use value instead. While Some
’s unwrap() and value will
both return the same value using value is preferable because it makes it clear that
there won’t be an exception thrown on access.
Throws if the value is None
.
unwrapOr()
unwrapOr<T2>(val: T2): T | T2
Returns the contained Some
value or a provided default.