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.