Skip to main content

Option

Belt (ReScript) represents the existence and nonexistence of a value by wrapping it with the Option type. TS Belt does the same and provides utility-functions for convenient work with the Option type.

type Option<T> = T | undefined | null
warning

Adding noUncheckedIndexedAccess to your tsconfig.json is mandatory for the Option type!

Live Editor
Result
Loading...

contains

Checks if option is the Some variant and contains the given value.

function contains<A>(option: Option<A>, value: any): boolean
function contains<A>(value: any): (option: Option<A>) => boolean
pipe(O.fromNullable([3, 6, 9]), O.flatMap(A.head), O.contains(3)) // → true
pipe(O.fromNullable([3, 6, 9]), O.flatMap(A.get(1)), O.contains(3)) // → false

filter

Returns Some(value) if option is Some(value) and the result of predicateFn is truthy, otherwise, returns None.

function filter<A>(option: Option<A>, predicateFn: (value: A) => boolean): Option<A>
function filter<A>(predicateFn: (value: A) => boolean): (option: Option<A>) => Option<A>
pipe(
O.fromNullable([3, 6, 9]),
O.flatMap(A.get(0)),
O.filter(value => value === 3),
) // → Some(3)

pipe(
O.fromNullable([3, 6, 9]),
O.flatMap(A.get(0)),
O.filter(value => value === 0),
) // → None

flatMap

Returns the result of mapFn (it must have a return type of Option) if option is Some(value), otherwise, returns None.

function flatMap<A, B>(option: Option<A>, mapFn: (value: A) => Option<B>): Option<B>
function flatMap<A, B>(mapFn: (value: A) => Option<B>): (option: Option<A>) => Option<B>
pipe(
O.fromNullable('hello'),
O.flatMap(value => {
return value.endsWith('lo') ? O.Some(`${value} world!`) : O.None
}),
) // → Some('hello world!')

fromFalsy

Returns Some(value) if the provided value is not falsy, otherwise, returns None.

function fromFalsy<A>(value: A): Option<ExtractValue<A>>
O.fromFalsy(1) // → Some(1)
O.fromFalsy('hello world') // → Some('hello world')
O.fromFalsy([]) // → Some([])
O.fromFalsy(0) // → None
O.fromFalsy('') // → None

fromNullable

Returns Some(value) if the provided value is non-nullable, otherwise, returns None.

function fromNullable<A>(value: A): Option<ExtractValue<A>>
O.fromNullable(1) // → Some(1)
O.fromNullable('hello world') // → Some('hello world')
O.fromNullable([]) // → Some([])
O.fromNullable(false) // → Some(false)
O.fromNullable(null) // → None
O.fromNullable(undefined) // → None

fromPredicate

Returns Some(value) if the given predicate function returns true, otherwise, returns None.

function fromPredicate<A>(value: A, predicateFn: (value: NonNullable<A>) => boolean): Option<ExtractValue<A>>
function fromPredicate<A>(predicateFn: (value: NonNullable<A>) => boolean): (value: A) => Option<ExtractValue<A>>
O.fromPredicate(
[1, 2, 3],
A.some(x => x === 2),
) // → Some([1, 2, 3])

O.fromPredicate(
[1, 2, 3],
A.some(x => x === 4),
) // → None

getExn

Returns value if option is Some(value), otherwise, throws an exception.

function getExn<A>(option: Option<A>): A | never
pipe(
O.fromNullable('hello'),
O.map(value => `${value} world!`),
O.getExn,
) // → 'hello world!'

getWithDefault

Returns value if option is Some(value), otherwise, returns a default value.

function getWithDefault<A>(option: Option<A>, defaultValue: NonNullable<A>): A
function getWithDefault<A>(defaultValue: NonNullable<A>): (option: Option<A>) => A
pipe(
O.fromNullable('hello'),
O.map(value => `${value} world!`),
O.getWithDefault('error'),
) // → 'hello world!'

pipe(
O.fromNullable(null),
O.map(value => `${value} world!`),
O.getWithDefault('error'),
) // → 'error'

isNone

Returns true if the provided option is None, otherwise, returns false.

function isNone<A>(option: Option<A>): option is Option<never>
O.isNone(O.None) // → true
pipe(O.fromNullable(null), O.isNone) // → true
O.isNone(O.Some('hello world!')) // → false
pipe(O.fromNullable('hello world!'), O.isNone) // → false

isSome

Returns true if the provided option is Some(value), otherwise, returns false.

function isSome<A>(option: Option<A>): option is Option<A>
O.isSome(O.Some('hello world!')) // → true
pipe(O.fromNullable('hello world!'), O.isSome) // → true
O.isSome(O.None) // → false
pipe(O.fromNullable(null), O.isSome) // → false

map

Returns the result of mapFn if option is Some(value), otherwise, returns None and mapFn is not called.

function map<A, B>(option: Option<A>, mapFn: (value: A) => NonNullable<B>): Option<B>
function map<A, B>(mapFn: (value: A) => NonNullable<B>): (option: Option<A>) => Option<B>
pipe(
O.fromNullable([1, 2, 3]),
O.flatMap(A.get(0)),
O.map(n => `${n}. hello world!`),
) // → Some('1. hello world!')

pipe(
O.fromNullable([]),
O.flatMap(A.get(0)),
O.map(n => `${n}. hello world!`),
) // → None

mapNullable

Returns Some(value) if the result of mapFn is non-nullable, otherwise, returns None.

function mapNullable<A, B>(option: Option<A>, mapFn: (value: A) => B | null | undefined): Option<ExtractValue<B>>
function mapNullable<A, B>(mapFn: (value: A) => B | null | undefined): (option: Option<A>) => Option<ExtractValue<B>>
pipe(
O.fromNullable([1, 2, 3]),
O.mapNullable(value => value[0]),
) // → Some(1)

pipe(
O.fromNullable([undefined, 2, 3]),
O.mapNullable(value => value[0]),
) // → None

mapWithDefault

Returns the result of mapFn if option is Some(value), otherwise, returns a default value.

function mapWithDefault<A, B>(option: Option<A>, defaultValue: NonNullable<B>, mapFn: (value: A) => B): B
function mapWithDefault<A, B>(defaultValue: NonNullable<B>, mapFn: (value: A) => B): (option: Option<A>) => B
pipe(
O.fromNullable(['hello']),
O.flatMap(A.get(0)),
O.mapWithDefault('default value', value => `${value} world!`),
) // → 'hello world!'

pipe(
O.fromNullable([]),
O.flatMap(A.get(0)),
O.mapWithDefault('default value', value => `${value} world!`),
) // → 'default value'

match

Returns the result of someFn if option is Some(value), otherwise, returns the result of noneFn.

function match<A, B>(option: Option<A>, someFn: (value: A) => B, noneFn: () => B): B
function match<A, B>(someFn: (value: A) => B, noneFn: () => B): (option: Option<A>) => B
pipe(
O.fromNullable(['hello', 'world', 'lorem', 'ipsum']),
O.flatMap(A.takeExactly(2)),
O.map(A.join(' ')),
O.match(
str => `${str}!`,
() => 'oops!',
),
) // → 'hello world!'

pipe(
O.fromNullable([]),
O.flatMap(A.takeExactly(2)),
O.map(A.join(' ')),
O.match(
str => `${str}!`,
() => 'oops!',
),
) // → 'oops!'

tap

Applies a side-effect function to the value in Some, and returns the original option.

function tap<A>(option: Option<A>, someFn: (value: A) => void): Option<A>
function tap<A>(someFn: (value: A) => void): (option: Option<A>) => Option<A>
pipe(
O.fromNullable(['hello', 'world']),
O.flatMap(A.get(1)),
O.tap(str => {
console.log(str) // ⬅️ 'world'
}),
O.getWithDefault(''),
) // → 'world'

toNullable

Returns value if option is Some(value), otherwise, returns null.

function toNullable<A>(option: Option<A>): A | null
pipe(
O.fromNullable(['hello', 'world']),
O.flatMap(A.takeExactly(2)),
O.toNullable,
) // → ['hello', 'world']

pipe(O.fromNullable([]), O.flatMap(A.takeExactly(2)), O.toNullable) // → null

toResult

Returns Ok(value) if option is Some(value), otherwise, returns Error(errorValue), both Ok and Error come from the Result type.

function toResult<A, B>(option: Option<A>, errorValue: NonNullable<B>): Result<A, B>
function toResult<A, B>(errorValue: NonNullable<B>): (option: Option<A>) => Result<A, B>
pipe(
O.fromNullable(['hello', 'world']),
O.flatMap(A.takeExactly(2)),
O.toResult('oops!'),
) // → R.Ok(['hello', 'world'])

pipe(
O.fromNullable([]),
O.flatMap(A.takeExactly(2)),
O.toResult('oops!'),
) // → R.Error('oops!')

toUndefined

Returns value if option is Some(value), otherwise, returns undefined.

function toUndefined<A>(option: Option<A>): A | undefined
pipe(
O.fromNullable(['hello', 'world']),
O.flatMap(A.takeExactly(2)),
O.toUndefined,
) // → ['hello', 'world']

pipe(O.fromNullable([]), O.flatMap(A.takeExactly(2)), O.toUndefined) // → undefined

zip

Combines two Options into a single Option containing a tuple of their values, if both Options are Some variants, otherwise, returns None.

function zip<A, B>(sndOption: Option<B>): (fstOption: Option<A>) => Option<readonly [A, B]>
function zip<A, B>(fstOption: Option<A>, sndOption: Option<B>): Option<readonly [A, B]>
pipe(O.fromNullable('hello'), O.zip(O.fromNullable('world'))) // → Some(['hello', 'world'])

zipWith

Combines two Options into a single Option. The new value is produced by applying the given function to both values, if both Options are Some variants, otherwise, returns None.

function zipWith<A, B, C>(
fstOption: Option<A>,
sndOption: Option<B>,
mapFn: (arg0: A, arg1: B) => Option<C>
): Option<C>
function zipWith<A, B, C>(sndOption: Option<B>, mapFn: (arg0: A, arg1: B) => Option<C>): (fstOption: Option<A>) => Option<C>
pipe(
O.fromNullable('hello'),
O.zipWith(O.fromNullable('world'), S.concat),
) // → Some('helloworld')