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

function() {
  // ⬇️ remove all elements in the array below in order to see the default value
  const xs = ['hello', 'world', 'ts', 'belt']
  const value = pipe(
    O.fromNullable(xs), // → Some(['hello', 'world', 'ts', 'belt'])
    O.flatMap(A.dropExactly(2)), // → Some(['ts', 'belt'])
    O.map(A.join('-')), // → Some('ts-belt')
    O.getWithDefault('default value'), // returns `default value` if `None`
  )

  return value
}

function() {
  // ⬇️ remove all elements in the array below in order to see the default value
  const xs = ['hello', 'world', 'ts', 'belt']
  const value = pipe(
    O.fromNullable(xs), // → Some(['hello', 'world', 'ts', 'belt'])
    O.flatMap(A.dropExactly(2)), // → Some(['ts', 'belt'])
    O.map(A.join('-')), // → Some('ts-belt')
    O.getWithDefault('default value'), // returns `default value` if `None`
  )

  return value
}

Result

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!')

fromExecution

Returns Some(value) (value is the result of fn) if fn didn't throw an error, otherwise, returns None.

function fromExecution<A>(fn: () => A): Option<ExtractValue<A>>

type User = { readonly name: string }
const parseJSON = <T>(value: string) => () => JSON.parse(value) as T
const okJSON = `{"name": "John"}`
const badJSON = `{name": John}`

O.fromExecution(parseJSON<User>(okJSON)) // → Some({ name: 'John' })

O.fromExecution(parseJSON<User>(badJSON)) // → None

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

fromPromise

Returns Some(value) if promise is resolved successfully, otherwise, returns None.

function fromPromise<A>(promise: Promise<A>): Promise<Option<ExtractValue<A>>>

await O.fromPromise(Promise.resolve('hello world')) // → Some('hello world')
await O.fromPromise(Promise.reject('oops')) // → 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')

warning

contains​

filter​

flatMap​

fromExecution​

fromFalsy​

fromNullable​

fromPredicate​

fromPromise​

getExn​

getWithDefault​

isNone​

isSome​

map​

mapNullable​

mapWithDefault​

match​

tap​

toNullable​

toResult​

toUndefined​

zip​

zipWith​

contains

filter

flatMap

fromExecution

fromFalsy

fromNullable

fromPredicate

fromPromise

getExn

getWithDefault

isNone

isSome

map

mapNullable

mapWithDefault

match

tap

toNullable

toResult

toUndefined

zip

zipWith