fp-ts

This site uses Just the Docs, a documentation theme for Jekyll.

Search

Option overview

type Option<A> = None | Some<A>

Option<A> is a container for an optional value of type A. If the value of type A is present, the Option<A> is an instance of Some<A>, containing the present value of type A. If the value is absent, the Option<A> is an instance of None.

An option could be looked at as a collection or foldable structure with either one or zero elements. Another way to look at Option is: it represents the effect of a possibly failing computation.

Added in v2.0.0

Table of contents

Alt

alt

Identifies an associative operation on a type constructor. It is similar to Semigroup, except that it applies to types of kind * -> *.

In case of Option returns the left-most non-None value.

Signature

export declare const alt: <A>(that: Lazy<Option<A>>) => (fa: Option<A>) => Option<A>

Example

import * as O from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

assert.deepStrictEqual(
  pipe(
    O.some('a'),
    O.alt(() => O.some('b'))
  ),
  O.some('a')
)
assert.deepStrictEqual(
  pipe(
    O.none,
    O.alt(() => O.some('b'))
  ),
  O.some('b')
)

Added in v2.0.0

Alternative

zero

Signature

export declare const zero: <A>() => Option<A>

Added in v2.7.0

Applicative

of

Signature

export declare const of: <A>(a: A) => Option<A>

Added in v2.7.0

Apply

ap

Apply a function to an argument under a type constructor.

Signature

export declare const ap: <A>(fa: Option<A>) => <B>(fab: Option<(a: A) => B>) => Option<B>

Added in v2.0.0

apFirst

Combine two effectful actions, keeping only the result of the first.

Signature

export declare const apFirst: <B>(fb: Option<B>) => <A>(fa: Option<A>) => Option<A>

Added in v2.0.0

apSecond

Combine two effectful actions, keeping only the result of the second.

Signature

export declare const apSecond: <B>(fb: Option<B>) => <A>(fa: Option<A>) => Option<B>

Added in v2.0.0

Compactable

compact

Signature

export declare const compact: <A>(fa: Option<Option<A>>) => Option<A>

Added in v2.0.0

separate

Signature

export declare const separate: <A, B>(ma: Option<Either<A, B>>) => Separated<Option<A>, Option<B>>

Added in v2.0.0

Extend

duplicate

Signature

export declare const duplicate: <A>(ma: Option<A>) => Option<Option<A>>

Added in v2.0.0

extend

Signature

export declare const extend: <A, B>(f: (wa: Option<A>) => B) => (wa: Option<A>) => Option<B>

Added in v2.0.0

Filterable

filter

Signature

export declare const filter: {
  <A, B extends A>(refinement: Refinement<A, B>): (fa: Option<A>) => Option<B>
  <A>(predicate: Predicate<A>): (fa: Option<A>) => Option<A>
}

Added in v2.0.0

filterMap

Signature

export declare const filterMap: <A, B>(f: (a: A) => Option<B>) => (fa: Option<A>) => Option<B>

Added in v2.0.0

partition

Signature

export declare const partition: {
  <A, B extends A>(refinement: Refinement<A, B>): (fa: Option<A>) => Separated<Option<A>, Option<B>>
  <A>(predicate: Predicate<A>): (fa: Option<A>) => Separated<Option<A>, Option<A>>
}

Added in v2.0.0

partitionMap

Signature

export declare const partitionMap: <A, B, C>(
  f: (a: A) => Either<B, C>
) => (fa: Option<A>) => Separated<Option<B>, Option<C>>

Added in v2.0.0

Foldable

foldMap

Signature

export declare const foldMap: <M>(M: Monoid<M>) => <A>(f: (a: A) => M) => (fa: Option<A>) => M

Added in v2.0.0

reduce

Signature

export declare const reduce: <A, B>(b: B, f: (b: B, a: A) => B) => (fa: Option<A>) => B

Added in v2.0.0

reduceRight

Signature

export declare const reduceRight: <A, B>(b: B, f: (a: A, b: B) => B) => (fa: Option<A>) => B

Added in v2.0.0

Functor

map

Signature

export declare const map: <A, B>(f: (a: A) => B) => (fa: Option<A>) => Option<B>

Added in v2.0.0

Monad

chain

Composes computations in sequence, using the return value of one computation to determine the next computation.

Signature

export declare const chain: <A, B>(f: (a: A) => Option<B>) => (ma: Option<A>) => Option<B>

Added in v2.0.0

chainFirst

Composes computations in sequence, using the return value of one computation to determine the next computation and keeping only the result of the first.

Signature

export declare const chainFirst: <A, B>(f: (a: A) => Option<B>) => (ma: Option<A>) => Option<A>

Added in v2.0.0

flatten

Signature

export declare const flatten: <A>(mma: Option<Option<A>>) => Option<A>

Added in v2.0.0

MonadThrow

throwError

Signature

export declare const throwError: <E, A>(e: E) => Option<A>

Added in v2.7.0

Traversable

sequence

Signature

export declare const sequence: Sequence1<'Option'>

Added in v2.6.3

traverse

Signature

export declare const traverse: PipeableTraverse1<'Option'>

Added in v2.6.3

Whitherable

wilt

Signature

export declare const wilt: PipeableWilt1<'Option'>

Added in v2.6.5

wither

Signature

export declare const wither: PipeableWither1<'Option'>

Added in v2.6.5

combinators

mapNullable

This is chain + fromNullable, useful when working with optional values

Signature

export declare function mapNullable<A, B>(f: (a: A) => B | null | undefined): (ma: Option<A>) => Option<B>

Example

import { some, none, fromNullable, mapNullable } from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

interface Employee {
  company?: {
    address?: {
      street?: {
        name?: string
      }
    }
  }
}

const employee1: Employee = { company: { address: { street: { name: 'high street' } } } }

assert.deepStrictEqual(
  pipe(
    fromNullable(employee1.company),
    mapNullable((company) => company.address),
    mapNullable((address) => address.street),
    mapNullable((street) => street.name)
  ),
  some('high street')
)

const employee2: Employee = { company: { address: { street: {} } } }

assert.deepStrictEqual(
  pipe(
    fromNullable(employee2.company),
    mapNullable((company) => company.address),
    mapNullable((address) => address.street),
    mapNullable((street) => street.name)
  ),
  none
)

Added in v2.0.0

constructors

fromEither

Signature

export declare const fromEither: <E, A>(ma: Either<E, A>) => Option<A>

Added in v2.0.0

fromNullable

Constructs a new Option from a nullable type. If the value is null or undefined, returns None, otherwise returns the value wrapped in a Some

Signature

export declare function fromNullable<A>(a: A): Option<NonNullable<A>>

Example

import { none, some, fromNullable } from 'fp-ts/lib/Option'

assert.deepStrictEqual(fromNullable(undefined), none)
assert.deepStrictEqual(fromNullable(null), none)
assert.deepStrictEqual(fromNullable(1), some(1))

Added in v2.0.0

fromPredicate

Returns a smart constructor based on the given predicate

Signature

export declare function fromPredicate<A, B extends A>(refinement: Refinement<A, B>): (a: A) => Option<B>
export declare function fromPredicate<A>(predicate: Predicate<A>): (a: A) => Option<A>

Example

import { none, some, fromPredicate } from 'fp-ts/lib/Option'

const getOption = fromPredicate((n: number) => n >= 0)

assert.deepStrictEqual(getOption(-1), none)
assert.deepStrictEqual(getOption(1), some(1))

Added in v2.0.0

getLeft

Returns an E value if possible

Signature

export declare function getLeft<E, A>(ma: Either<E, A>): Option<E>

Added in v2.0.0

getRight

Returns an A value if possible

Signature

export declare function getRight<E, A>(ma: Either<E, A>): Option<A>

Added in v2.0.0

none

Signature

export declare const none: Option<never>

Added in v2.0.0

some

Signature

export declare const some: <A>(a: A) => Option<A>

Added in v2.0.0

tryCatch

Transforms an exception into an Option. If f throws, returns None, otherwise returns the output wrapped in Some

Signature

export declare function tryCatch<A>(f: Lazy<A>): Option<A>

Example

import { none, some, tryCatch } from 'fp-ts/lib/Option'

assert.deepStrictEqual(
  tryCatch(() => {
    throw new Error()
  }),
  none
)
assert.deepStrictEqual(
  tryCatch(() => 1),
  some(1)
)

Added in v2.0.0

destructors

fold

Takes a default value, a function, and an Option value, if the Option value is None the default value is returned, otherwise the function is applied to the value inside the Some and the result is returned.

Signature

export declare function fold<A, B>(onNone: Lazy<B>, onSome: (a: A) => B): (ma: Option<A>) => B

Example

import { some, none, fold } from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

assert.strictEqual(
  pipe(
    some(1),
    fold(
      () => 'a none',
      (a) => `a some containing ${a}`
    )
  ),
  'a some containing 1'
)

assert.strictEqual(
  pipe(
    none,
    fold(
      () => 'a none',
      (a) => `a some containing ${a}`
    )
  ),
  'a none'
)

Added in v2.0.0

getOrElse

Extracts the value out of the structure, if it exists. Otherwise returns the given default value

Signature

export declare const getOrElse: <A>(onNone: Lazy<A>) => (ma: Option<A>) => A

Example

import { some, none, getOrElse } from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

assert.strictEqual(
  pipe(
    some(1),
    getOrElse(() => 0)
  ),
  1
)
assert.strictEqual(
  pipe(
    none,
    getOrElse(() => 0)
  ),
  0
)

Added in v2.0.0

getOrElseW

Less strict version of getOrElse.

Signature

export declare const getOrElseW: <B>(onNone: Lazy<B>) => <A>(ma: Option<A>) => B | A

Added in v2.6.0

toNullable

Extracts the value out of the structure, if it exists. Otherwise returns null.

Signature

export declare function toNullable<A>(ma: Option<A>): A | null

Example

import { some, none, toNullable } from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

assert.strictEqual(pipe(some(1), toNullable), 1)
assert.strictEqual(pipe(none, toNullable), null)

Added in v2.0.0

toUndefined

Extracts the value out of the structure, if it exists. Otherwise returns undefined.

Signature

export declare function toUndefined<A>(ma: Option<A>): A | undefined

Example

import { some, none, toUndefined } from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

assert.strictEqual(pipe(some(1), toUndefined), 1)
assert.strictEqual(pipe(none, toUndefined), undefined)

Added in v2.0.0

guards

isNone

Returns true if the option is None, false otherwise

Signature

export declare const isNone: <A>(fa: Option<A>) => fa is None

Example

import { some, none, isNone } from 'fp-ts/lib/Option'

assert.strictEqual(isNone(some(1)), false)
assert.strictEqual(isNone(none), true)

Added in v2.0.0

isSome

Returns true if the option is an instance of Some, false otherwise

Signature

export declare const isSome: <A>(fa: Option<A>) => fa is Some<A>

Example

import { some, none, isSome } from 'fp-ts/lib/Option'

assert.strictEqual(isSome(some(1)), true)
assert.strictEqual(isSome(none), false)

Added in v2.0.0

instances

URI

Signature

export declare const URI: 'Option'

Added in v2.0.0

URI (type alias)

Signature

export type URI = typeof URI

Added in v2.0.0

altOption

Signature

export declare const altOption: Alt1<'Option'>

Added in v2.7.0

alternativeOption

Signature

export declare const alternativeOption: Alternative1<'Option'>

Added in v2.7.0

applicativeOption

Signature

export declare const applicativeOption: Applicative1<'Option'>

Added in v2.7.0

compactableOption

Signature

export declare const compactableOption: Compactable1<'Option'>

Added in v2.7.0

extendOption

Signature

export declare const extendOption: Extend1<'Option'>

Added in v2.7.0

filterableOption

Signature

export declare const filterableOption: Filterable1<'Option'>

Added in v2.7.0

foldableOption

Signature

export declare const foldableOption: Foldable1<'Option'>

Added in v2.7.0

functorOption

Signature

export declare const functorOption: Functor1<'Option'>

Added in v2.7.0

getApplyMonoid

Signature

export declare function getApplyMonoid<A>(M: Monoid<A>): Monoid<Option<A>>

Added in v2.0.0

getApplySemigroup

Apply semigroup

x y concat(x, y)
none none none
some(a) none none
none some(a) none
some(a) some(b) some(concat(a, b))

Signature

export declare function getApplySemigroup<A>(S: Semigroup<A>): Semigroup<Option<A>>

Example

import { getApplySemigroup, some, none } from 'fp-ts/lib/Option'
import { semigroupSum } from 'fp-ts/lib/Semigroup'

const S = getApplySemigroup(semigroupSum)
assert.deepStrictEqual(S.concat(none, none), none)
assert.deepStrictEqual(S.concat(some(1), none), none)
assert.deepStrictEqual(S.concat(none, some(1)), none)
assert.deepStrictEqual(S.concat(some(1), some(2)), some(3))

Added in v2.0.0

getEq

Signature

export declare function getEq<A>(E: Eq<A>): Eq<Option<A>>

Example

import { none, some, getEq } from 'fp-ts/lib/Option'
import { eqNumber } from 'fp-ts/lib/Eq'

const E = getEq(eqNumber)
assert.strictEqual(E.equals(none, none), true)
assert.strictEqual(E.equals(none, some(1)), false)
assert.strictEqual(E.equals(some(1), none), false)
assert.strictEqual(E.equals(some(1), some(2)), false)
assert.strictEqual(E.equals(some(1), some(1)), true)

Added in v2.0.0

getFirstMonoid

Monoid returning the left-most non-None value

x y concat(x, y)
none none none
some(a) none some(a)
none some(a) some(a)
some(a) some(b) some(a)

Signature

export declare function getFirstMonoid<A = never>(): Monoid<Option<A>>

Example

import { getFirstMonoid, some, none } from 'fp-ts/lib/Option'

const M = getFirstMonoid<number>()
assert.deepStrictEqual(M.concat(none, none), none)
assert.deepStrictEqual(M.concat(some(1), none), some(1))
assert.deepStrictEqual(M.concat(none, some(1)), some(1))
assert.deepStrictEqual(M.concat(some(1), some(2)), some(1))

Added in v2.0.0

getLastMonoid

Monoid returning the right-most non-None value

x y concat(x, y)
none none none
some(a) none some(a)
none some(a) some(a)
some(a) some(b) some(b)

Signature

export declare function getLastMonoid<A = never>(): Monoid<Option<A>>

Example

import { getLastMonoid, some, none } from 'fp-ts/lib/Option'

const M = getLastMonoid<number>()
assert.deepStrictEqual(M.concat(none, none), none)
assert.deepStrictEqual(M.concat(some(1), none), some(1))
assert.deepStrictEqual(M.concat(none, some(1)), some(1))
assert.deepStrictEqual(M.concat(some(1), some(2)), some(2))

Added in v2.0.0

getMonoid

Monoid returning the left-most non-None value. If both operands are Somes then the inner values are concatenated using the provided Semigroup

x y concat(x, y)
none none none
some(a) none some(a)
none some(a) some(a)
some(a) some(b) some(concat(a, b))

Signature

export declare function getMonoid<A>(S: Semigroup<A>): Monoid<Option<A>>

Example

import { getMonoid, some, none } from 'fp-ts/lib/Option'
import { semigroupSum } from 'fp-ts/lib/Semigroup'

const M = getMonoid(semigroupSum)
assert.deepStrictEqual(M.concat(none, none), none)
assert.deepStrictEqual(M.concat(some(1), none), some(1))
assert.deepStrictEqual(M.concat(none, some(1)), some(1))
assert.deepStrictEqual(M.concat(some(1), some(2)), some(3))

Added in v2.0.0

getOrd

The Ord instance allows Option values to be compared with compare, whenever there is an Ord instance for the type the Option contains.

None is considered to be less than any Some value.

Signature

export declare function getOrd<A>(O: Ord<A>): Ord<Option<A>>

Example

import { none, some, getOrd } from 'fp-ts/lib/Option'
import { ordNumber } from 'fp-ts/lib/Ord'

const O = getOrd(ordNumber)
assert.strictEqual(O.compare(none, none), 0)
assert.strictEqual(O.compare(none, some(1)), -1)
assert.strictEqual(O.compare(some(1), none), 1)
assert.strictEqual(O.compare(some(1), some(2)), -1)
assert.strictEqual(O.compare(some(1), some(1)), 0)

Added in v2.0.0

getShow

Signature

export declare function getShow<A>(S: Show<A>): Show<Option<A>>

Added in v2.0.0

monadOption

Signature

export declare const monadOption: Monad1<'Option'>

Added in v2.7.0

monadThrowOption

Signature

export declare const monadThrowOption: MonadThrow1<'Option'>

Added in v2.7.0

option

Signature

export declare const option: Monad1<'Option'> &
  Foldable1<'Option'> &
  Alternative1<'Option'> &
  Extend1<'Option'> &
  Witherable1<'Option'> &
  MonadThrow1<'Option'>

Added in v2.0.0

traversableOption

Signature

export declare const traversableOption: Traversable1<'Option'>

Added in v2.7.0

witherableOption

Signature

export declare const witherableOption: Witherable1<'Option'>

Added in v2.7.0

model

None (interface)

Signature

export interface None {
  readonly _tag: 'None'
}

Added in v2.0.0

Option (type alias)

Signature

export type Option<A> = None | Some<A>

Added in v2.0.0

Some (interface)

Signature

export interface Some<A> {
  readonly _tag: 'Some'
  readonly value: A
}

Added in v2.0.0

utils

elem

Returns true if ma contains a

Signature

export declare function elem<A>(E: Eq<A>): (a: A, ma: Option<A>) => boolean

Example

import { some, none, elem } from 'fp-ts/lib/Option'
import { eqNumber } from 'fp-ts/lib/Eq'

assert.strictEqual(elem(eqNumber)(1, some(1)), true)
assert.strictEqual(elem(eqNumber)(2, some(1)), false)
assert.strictEqual(elem(eqNumber)(1, none), false)

Added in v2.0.0

exists

Returns true if the predicate is satisfied by the wrapped value

Signature

export declare function exists<A>(predicate: Predicate<A>): (ma: Option<A>) => boolean

Example

import { some, none, exists } from 'fp-ts/lib/Option'
import { pipe } from 'fp-ts/lib/function'

assert.strictEqual(
  pipe(
    some(1),
    exists((n) => n > 0)
  ),
  true
)
assert.strictEqual(
  pipe(
    some(1),
    exists((n) => n > 1)
  ),
  false
)
assert.strictEqual(
  pipe(
    none,
    exists((n) => n > 0)
  ),
  false
)

Added in v2.0.0

getRefinement

Returns a Refinement (i.e. a custom type guard) from a Option returning function. This function ensures that a custom type guard definition is type-safe.

import { some, none, getRefinement } from 'fp-ts/lib/Option'

type A = { type: 'A' }
type B = { type: 'B' }
type C = A | B

const isA = (c: C): c is A => c.type === 'B' // <= typo but typescript doesn't complain
const isA = getRefinement<C, A>((c) => (c.type === 'B' ? some(c) : none)) // static error: Type '"B"' is not assignable to type '"A"'

Signature

export declare function getRefinement<A, B extends A>(getOption: (a: A) => Option<B>): Refinement<A, B>

Added in v2.0.0