Skip to main content Link Search Menu Expand Document (external link)
core

Option overview

Added in v1.0.0

Table of contents

combining

all

Similar to Promise.all but operates on Options.

Iterable<Option<A>> -> Option<A[]>

Flattens a collection of Options into a single Option that contains a list of all the Some values. If there is a None value in the collection, it returns None as the result.

Signature

export declare const all: <A>(collection: Iterable<Option<A>>) => Option<A[]>

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.all([O.some(1), O.some(2), O.some(3)]), O.some([1, 2, 3]))
assert.deepStrictEqual(O.all([O.some(1), O.none(), O.some(3)]), O.none())

Added in v1.0.0

ap

Signature

export declare const ap: {
  <A, B>(self: Option<(a: A) => B>, that: Option<A>): Option<B>
  <A>(that: Option<A>): <B>(self: Option<(a: A) => B>) => Option<B>
}

Added in v1.0.0

getFailureMonoid

Monoid that models the combination of computations that can fail, if at least one element is None then the resulting combination is None, otherwise if all elements are Some then the resulting combination is the combination of the wrapped elements using the provided Monoid.

The empty value is some(M.empty).

See also getFailureSemigroup if you need a Semigroup instead of a Monoid.

Signature

export declare const getFailureMonoid: <A>(M: Monoid<A>) => Monoid<Option<A>>

Added in v1.0.0

getFailureSemigroup

Semigroup that models the combination of computations that can fail, if at least one element is None then the resulting combination is None, otherwise if all elements are Some then the resulting combination is the combination of the wrapped elements using the provided Semigroup.

See also getFailureMonoid if you need a Monoid instead of a Semigroup.

Signature

export declare const getFailureSemigroup: <A>(S: Semigroup<A>) => Semigroup<Option<A>>

Added in v1.0.0

getFirstSomeSemigroup

Semigroup returning the first Some value encountered.

Signature

export declare const getFirstSomeSemigroup: <A>() => Semigroup<Option<A>>

Added in v1.0.0

sequence

Combines an Option of an F-structure to an F-structure of an Option with the same inner type.

Signature

export declare const sequence: <F extends TypeLambda>(
  F: applicative.Applicative<F>
) => <R, O, E, A>(self: Option<Kind<F, R, O, E, A>>) => Kind<F, R, O, E, Option<A>>

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

const sequence = O.sequence(E.Applicative)

assert.deepStrictEqual(sequence(O.some(E.right(1))), E.right(O.some(1)))
assert.deepStrictEqual(sequence(O.some(E.left('error'))), E.left('error'))
assert.deepStrictEqual(sequence(O.none()), E.right(O.none()))

Added in v1.0.0

struct

Takes a struct of Options and returns an Option of a struct of values.

Signature

export declare const struct: <R extends Record<string, Option<any>>>(
  fields: R
) => Option<{ [K in keyof R]: [R[K]] extends [Option<infer A>] ? A : never }>

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.struct({ a: O.some(1), b: O.some('hello') }), O.some({ a: 1, b: 'hello' }))
assert.deepStrictEqual(O.struct({ a: O.some(1), b: O.none() }), O.none())

Added in v1.0.0

traverse

Applies an Option value to an effectful function that returns an F value.

Signature

export declare const traverse: <F extends TypeLambda>(
  F: applicative.Applicative<F>
) => {
  <A, R, O, E, B>(f: (a: A) => Kind<F, R, O, E, B>): (self: Option<A>) => Kind<F, R, O, E, Option<B>>
  <A, R, O, E, B>(self: Option<A>, f: (a: A) => Kind<F, R, O, E, B>): Kind<F, R, O, E, Option<B>>
}

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

const traverse = O.traverse(E.Applicative)
const f = (n: number) => (n >= 0 ? E.right(1) : E.left('negative'))

assert.deepStrictEqual(traverse(O.some(1), f), E.right(O.some(1)))
assert.deepStrictEqual(traverse(O.some(-1), f), E.left('negative'))
assert.deepStrictEqual(traverse(O.none(), f), E.right(O.none()))

Added in v1.0.0

traverseTap

Signature

export declare const traverseTap: <F extends TypeLambda>(
  F: applicative.Applicative<F>
) => {
  <A, R, O, E, B>(self: Option<A>, f: (a: A) => Kind<F, R, O, E, B>): Kind<F, R, O, E, Option<A>>
  <A, R, O, E, B>(f: (a: A) => Kind<F, R, O, E, B>): (self: Option<A>) => Kind<F, R, O, E, Option<A>>
}

Added in v1.0.0

tuple

Similar to Promise.all but operates on Options.

[Option<A>, Option<B>, ...] -> Option<[A, B, ...]>

Takes a tuple of Options and returns an Option of a tuple of values.

Signature

export declare const tuple: <T extends readonly Option<any>[]>(
  ...elements: T
) => Option<{ [I in keyof T]: [T[I]] extends [Option<infer A>] ? A : never }>

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.tuple(O.some(1), O.some('hello')), O.some([1, 'hello']))
assert.deepStrictEqual(O.tuple(O.some(1), O.none()), O.none())

Added in v1.0.0

zipWith

Zips two Option values together using a provided function, returning a new Option of the result.

Signature

export declare const zipWith: {
  <A, B, C>(self: Option<A>, that: Option<B>, f: (a: A, b: B) => C): Option<C>
  <B, A, C>(that: Option<B>, f: (a: A, b: B) => C): (self: Option<A>) => Option<C>
}

Added in v1.0.0

constructors

none

Creates a new Option that represents the absence of a value.

Signature

export declare const none: <A = never>() => Option<A>

Added in v1.0.0

of

Alias of {@link some}.

Signature

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

Added in v1.0.0

some

Creates a new Option that wraps the given value.

Signature

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

Added in v1.0.0

conversions

fromEither

Converts a Either to an Option discarding the error.

Signature

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

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

assert.deepStrictEqual(O.fromEither(E.right(1)), O.some(1))
assert.deepStrictEqual(O.fromEither(E.left('error message')), O.none())

Added in v1.0.0

fromIterable

Converts an Iterable of values into an Option. Returns the first value of the Iterable wrapped in a Some if the Iterable is not empty, otherwise returns None.

Signature

export declare const fromIterable: <A>(collection: Iterable<A>) => Option<A>

Example

import { fromIterable, some, none } from '@fp-ts/core/Option'

assert.deepStrictEqual(fromIterable([1, 2, 3]), some(1))
assert.deepStrictEqual(fromIterable([]), none())

Added in v1.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 const fromNullable: <A>(nullableValue: A) => Option<NonNullable<A>>

Example

import * as O from '@fp-ts/core/Option'

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

Added in v1.0.0

getLeft

Converts a Either to an Option discarding the value.

Signature

export declare const getLeft: <E, A>(self: Either<E, A>) => Option<E>

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

assert.deepStrictEqual(O.getLeft(E.right('ok')), O.none())
assert.deepStrictEqual(O.getLeft(E.left('error')), O.some('error'))

Added in v1.0.0

getOrThrow

Extracts the value of an Option or throws if the Option is None.

The thrown error is a default error. To configure the error thrown, see {@link getOrThrowWith}.

Signature

export declare const getOrThrow: <A>(self: Option<A>) => A

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.getOrThrow(O.some(1)), 1)
assert.throws(() => O.getOrThrow(O.none()))

Added in v1.0.0

getOrThrowWith

Extracts the value of an Option or throws if the Option is None.

If a default error is sufficient for your use case and you don’t need to configure the thrown error, see {@link getOrThrow}.

Signature

export declare const getOrThrowWith: {
  (onNone: () => unknown): <A>(self: Option<A>) => A
  <A>(self: Option<A>, onNone: () => unknown): A
}

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(
  O.getOrThrowWith(O.some(1), () => new Error('Unexpected None')),
  1
)
assert.throws(() => O.getOrThrowWith(O.none(), () => new Error('Unexpected None')))

Added in v1.0.0

getRight

Converts a Either to an Option discarding the error.

Alias of {@link fromEither}.

Signature

export declare const getRight: <E, A>(self: Either<E, A>) => Option<A>

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

assert.deepStrictEqual(O.getRight(E.right('ok')), O.some('ok'))
assert.deepStrictEqual(O.getRight(E.left('err')), O.none())

Added in v1.0.0

liftNullable

This API is useful for lifting a function that returns null or undefined into the Option context.

Signature

export declare const liftNullable: <A extends readonly unknown[], B>(
  f: (...a: A) => B | null | undefined
) => (...a: A) => Option<NonNullable<B>>

Example

import * as O from '@fp-ts/core/Option'

const parse = (s: string): number | undefined => {
  const n = parseFloat(s)
  return isNaN(n) ? undefined : n
}

const parseOption = O.liftNullable(parse)

assert.deepStrictEqual(parseOption('1'), O.some(1))
assert.deepStrictEqual(parseOption('not a number'), O.none())

Added in v1.0.0

liftThrowable

A utility function that lifts a function that throws exceptions into a function that returns an Option.

This function is useful for any function that might throw an exception, allowing the developer to handle the exception in a more functional way.

Signature

export declare const liftThrowable: <A extends readonly unknown[], B>(f: (...a: A) => B) => (...a: A) => Option<B>

Example

import * as O from '@fp-ts/core/Option'

const parse = O.liftThrowable(JSON.parse)

assert.deepStrictEqual(parse('1'), O.some(1))
assert.deepStrictEqual(parse(''), O.none())

Added in v1.0.0

toArray

Transforms an Option into an Array. If the input is None, an empty array is returned. If the input is Some, the value is wrapped in an array.

Signature

export declare const toArray: <A>(self: Option<A>) => A[]

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.toArray(O.some(1)), [1])
assert.deepStrictEqual(O.toArray(O.none()), [])

Added in v1.0.0

toEither

Converts an Option to an Either, allowing you to provide a value to be used in the case of a None.

Signature

export declare const toEither: {
  <A, E>(self: Option<A>, onNone: () => E): Either<E, A>
  <E>(onNone: () => E): <A>(self: Option<A>) => Either<E, A>
}

Example

import { pipe } from '@fp-ts/core/Function'
import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

const onNone = () => 'error'
assert.deepStrictEqual(pipe(O.some(1), O.toEither(onNone)), E.right(1))
assert.deepStrictEqual(pipe(O.none(), O.toEither(onNone)), E.left('error'))

Added in v1.0.0

toRefinement

Returns a type guard from a Option returning function. This function ensures that a type guard definition is type-safe.

Signature

export declare const toRefinement: <A, B extends A>(f: (a: A) => Option<B>) => (a: A) => a is B

Example

import * as O from '@fp-ts/core/Option'

const parsePositive = (n: number): O.Option<number> => (n > 0 ? O.some(n) : O.none())

const isPositive = O.toRefinement(parsePositive)

assert.deepStrictEqual(isPositive(1), true)
assert.deepStrictEqual(isPositive(-1), false)

Added in v1.0.0

debugging

inspectNone

Useful for debugging purposes, the onNone callback is is called if self is a None.

Signature

export declare const inspectNone: {
  (onNone: () => void): <A>(self: Option<A>) => Option<A>
  <A>(self: Option<A>, onNone: () => void): Option<A>
}

Added in v1.0.0

inspectSome

Useful for debugging purposes, the onSome callback is called with the value of self if it is a Some.

Signature

export declare const inspectSome: {
  <A>(onSome: (a: A) => void): (self: Option<A>) => Option<A>
  <A>(self: Option<A>, onSome: (a: A) => void): Option<A>
}

Added in v1.0.0

do notation

Do

Signature

export declare const Do: Option<{}>

Added in v1.0.0

andThenBind

A variant of bind that sequentially ignores the scope.

Signature

export declare const andThenBind: {
  <N extends string, A extends object, B>(name: Exclude<N, keyof A>, that: Option<B>): (
    self: Option<A>
  ) => Option<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
  <A extends object, N extends string, B>(self: Option<A>, name: Exclude<N, keyof A>, that: Option<B>): Option<{
    [K in N | keyof A]: K extends keyof A ? A[K] : B
  }>
}

Added in v1.0.0

appendElement

Appends an element to the end of a tuple wrapped in an Option type.

Signature

export declare const appendElement: {
  <A extends readonly any[], B>(self: Option<A>, that: Option<B>): Option<[...A, B]>
  <B>(that: Option<B>): <A extends readonly any[]>(self: Option<A>) => Option<[...A, B]>
}

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.appendElement(O.some([1, 2]), O.some(3)), O.some([1, 2, 3]))
assert.deepStrictEqual(O.appendElement(O.some([1, 2]), O.none()), O.none())

Added in v1.0.0

bind

Signature

export declare const bind: {
  <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: A) => Option<B>): (
    self: Option<A>
  ) => Option<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
  <A extends object, N extends string, B>(self: Option<A>, name: Exclude<N, keyof A>, f: (a: A) => Option<B>): Option<{
    [K in N | keyof A]: K extends keyof A ? A[K] : B
  }>
}

Added in v1.0.0

bindTo

Signature

export declare const bindTo: {
  <N extends string>(name: N): <A>(self: Option<A>) => Option<{ [K in N]: A }>
  <A, N extends string>(self: Option<A>, name: N): Option<{ [K in N]: A }>
}

Added in v1.0.0

let

Signature

export declare const let: {
  <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: A) => B): (
    self: Option<A>
  ) => Option<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
  <A extends object, N extends string, B>(self: Option<A>, name: Exclude<N, keyof A>, f: (a: A) => B): Option<{
    [K in N | keyof A]: K extends keyof A ? A[K] : B
  }>
}

Added in v1.0.0

tupled

Signature

export declare const tupled: <A>(self: Option<A>) => Option<[A]>

Added in v1.0.0

equivalence

getEquivalence

Signature

export declare const getEquivalence: <A>(E: Equivalence<A>) => Equivalence<Option<A>>

Example

import { none, some, getEquivalence } from '@fp-ts/core/Option'
import * as N from '@fp-ts/core/Number'

const isEquivalent = getEquivalence(N.Equivalence)
assert.deepStrictEqual(isEquivalent(none(), none()), true)
assert.deepStrictEqual(isEquivalent(none(), some(1)), false)
assert.deepStrictEqual(isEquivalent(some(1), none()), false)
assert.deepStrictEqual(isEquivalent(some(1), some(2)), false)
assert.deepStrictEqual(isEquivalent(some(1), some(1)), true)

Added in v1.0.0

error handling

firstSomeOf

Given an Iterable collection of Options, returns the first Some found in the collection.

Signature

export declare const firstSomeOf: <A>(collection: Iterable<Option<A>>) => Option<A>

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.firstSomeOf([O.none(), O.some(1), O.some(2)]), O.some(1))

Added in v1.0.0

orElse

Returns the provided Option that if self is None, otherwise returns self.

Signature

export declare const orElse: {
  <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<B | A>
  <A, B>(self: Option<A>, that: LazyArg<Option<B>>): Option<A | B>
}

Example

import * as O from '@fp-ts/core/Option'
import { pipe } from '@fp-ts/core/Function'

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

Added in v1.0.0

orElseEither

Similar to orElse, but instead of returning a simple union, it returns an Either object, which contains information about which of the two Options has been chosen.

This is useful when it’s important to know whether the value was retrieved from the first Option or the second option.

Signature

export declare const orElseEither: {
  <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<Either<A, B>>
  <A, B>(self: Option<A>, that: LazyArg<Option<B>>): Option<Either<A, B>>
}

Added in v1.0.0

filtering

filter

Filters an Option using a predicate. If the predicate is not satisfied or the Option is None returns None.

If you need to change the type of the Option in addition to filtering, see filterMap.

Signature

export declare const filter: {
  <C extends A, B extends A, A = C>(self: Option<C>, refinement: (a: A) => a is B): Option<B>
  <B extends A, A = B>(self: Option<B>, predicate: (a: A) => boolean): Option<B>
  <C extends A, B extends A, A = C>(refinement: (a: A) => a is B): (self: Option<C>) => Option<B>
  <B extends A, A = B>(predicate: (a: A) => boolean): (self: Option<B>) => Option<B>
}

Added in v1.0.0

filterMap

Maps over the value of an Option and filters out Nones.

Useful when in addition to filtering you also want to change the type of the Option.

Signature

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

Added in v1.0.0

partitionMap

Signature

export declare const partitionMap: {
  <A, B, C>(f: (a: A) => Either<B, C>): (self: Option<A>) => [Option<B>, Option<C>]
  <A, B, C>(self: Option<A>, f: (a: A) => Either<B, C>): [Option<B>, Option<C>]
}

Added in v1.0.0

folding

reduceCompact

Reduces an Iterable of Option<A> to a single value of type B, elements that are None are ignored.

Signature

export declare const reduceCompact: {
  <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<Option<A>>) => B
  <A, B>(self: Iterable<Option<A>>, b: B, f: (b: B, a: A) => B): B
}

Example

import { some, none, reduceCompact } from '@fp-ts/core/Option'
import { pipe } from '@fp-ts/core/Function'

const iterable = [some(1), none(), some(2), none()]
assert.deepStrictEqual(
  pipe(
    iterable,
    reduceCompact(0, (b, a) => b + a)
  ),
  3
)

Added in v1.0.0

getters

getOrElse

Returns the value of the Option if it is Some, otherwise returns onNone

Signature

export declare const getOrElse: {
  <B>(onNone: LazyArg<B>): <A>(self: Option<A>) => B | A
  <A, B>(self: Option<A>, onNone: LazyArg<B>): A | B
}

Example

import { some, none, getOrElse } from '@fp-ts/core/Option'
import { pipe } from '@fp-ts/core/Function'

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

Added in v1.0.0

getOrNull

Returns the value of the Option if it is a Some, otherwise returns null.

Signature

export declare const getOrNull: <A>(self: Option<A>) => A | null

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.getOrNull(O.some(1)), 1)
assert.deepStrictEqual(O.getOrNull(O.none()), null)

Added in v1.0.0

getOrUndefined

Returns the value of the Option if it is a Some, otherwise returns undefined.

Signature

export declare const getOrUndefined: <A>(self: Option<A>) => A | undefined

Example

import * as O from '@fp-ts/core/Option'

assert.deepStrictEqual(O.getOrUndefined(O.some(1)), 1)
assert.deepStrictEqual(O.getOrUndefined(O.none()), undefined)

Added in v1.0.0

guards

isNone

Determine if a Option is a None.

Signature

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

Example

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

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

Added in v1.0.0

isOption

Tests if a value is a Option.

Signature

export declare const isOption: (input: unknown) => input is Option<unknown>

Example

import { some, none, isOption } from '@fp-ts/core/Option'

assert.deepStrictEqual(isOption(some(1)), true)
assert.deepStrictEqual(isOption(none()), true)
assert.deepStrictEqual(isOption({}), false)

Added in v1.0.0

isSome

Determine if a Option is a Some.

Signature

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

Example

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

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

Added in v1.0.0

lifting

lift2

Lifts a binary function into Option.

Signature

export declare const lift2: <A, B, C>(
  f: (a: A, b: B) => C
) => { (self: Option<A>, that: Option<B>): Option<C>; (that: Option<B>): (self: Option<A>) => Option<C> }

Added in v1.0.0

liftEither

Lifts an Either function to an Option function.

Signature

export declare const liftEither: <A extends readonly unknown[], E, B>(
  f: (...a: A) => Either<E, B>
) => (...a: A) => Option<B>

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'

const parse = (s: string) => (isNaN(+s) ? E.left(`Error: ${s} is not a number`) : E.right(+s))

const parseNumber = O.liftEither(parse)

assert.deepEqual(parseNumber('12'), O.some(12))
assert.deepEqual(parseNumber('not a number'), O.none())

Added in v1.0.0

liftPredicate

Transforms a Predicate function into a Some of the input value if the predicate returns true or None if the predicate returns false.

Signature

export declare const liftPredicate: {
  <C extends A, B extends A, A = C>(refinement: Refinement<A, B>): (c: C) => Option<B>
  <B extends A, A = B>(predicate: Predicate<A>): (b: B) => Option<B>
}

Example

import * as O from '@fp-ts/core/Option'

const getOption = O.liftPredicate((n: number) => n >= 0)

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

Added in v1.0.0

math

divide

Signature

export declare const divide: {
  (self: Option<number>, that: Option<number>): Option<number>
  (that: Option<number>): (self: Option<number>) => Option<number>
}

Added in v1.0.0

multiply

Signature

export declare const multiply: {
  (self: Option<number>, that: Option<number>): Option<number>
  (that: Option<number>): (self: Option<number>) => Option<number>
}

Added in v1.0.0

multiplyCompact

Multiply all numbers in an iterable of Option<number> ignoring the None values.

Signature

export declare const multiplyCompact: (self: Iterable<Option<number>>) => number

Example

import { multiplyCompact, some, none } from '@fp-ts/core/Option'

const iterable = [some(2), none(), some(3), none()]
assert.deepStrictEqual(multiplyCompact(iterable), 6)

Added in v1.0.0

subtract

Signature

export declare const subtract: {
  (self: Option<number>, that: Option<number>): Option<number>
  (that: Option<number>): (self: Option<number>) => Option<number>
}

Added in v1.0.0

sum

Signature

export declare const sum: {
  (self: Option<number>, that: Option<number>): Option<number>
  (that: Option<number>): (self: Option<number>) => Option<number>
}

Added in v1.0.0

sumCompact

Sum all numbers in an iterable of Option<number> ignoring the None values.

Signature

export declare const sumCompact: (self: Iterable<Option<number>>) => number

Example

import { sumCompact, some, none } from '@fp-ts/core/Option'

const iterable = [some(2), none(), some(3), none()]
assert.deepStrictEqual(sumCompact(iterable), 5)

Added in v1.0.0

models

None (interface)

Signature

export interface None {
  readonly _tag: 'None'
}

Added in v1.0.0

Option (type alias)

Signature

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

Added in v1.0.0

Some (interface)

Signature

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

Added in v1.0.0

pattern matching

match

Matches the given Option and returns either the provided onNone value or the result of the provided onSome function when passed the Option’s value.

Signature

export declare const match: {
  <B, A, C = B>(onNone: LazyArg<B>, onSome: (a: A) => C): (self: Option<A>) => B | C
  <A, B, C = B>(self: Option<A>, onNone: LazyArg<B>, onSome: (a: A) => C): B | C
}

Example

import { some, none, match } from '@fp-ts/core/Option'
import { pipe } from '@fp-ts/core/Function'

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

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

Added in v1.0.0

sorting

getOrder

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

None is considered to be less than any Some value.

Signature

export declare const getOrder: <A>(O: Order<A>) => Order<Option<A>>

Example

import { none, some, getOrder } from '@fp-ts/core/Option'
import * as N from '@fp-ts/core/Number'
import { pipe } from '@fp-ts/core/Function'

const O = getOrder(N.Order)
assert.deepStrictEqual(O.compare(none(), none()), 0)
assert.deepStrictEqual(O.compare(none(), some(1)), -1)
assert.deepStrictEqual(O.compare(some(1), none()), 1)
assert.deepStrictEqual(O.compare(some(1), some(2)), -1)
assert.deepStrictEqual(O.compare(some(1), some(1)), 0)

Added in v1.0.0

transforming

andThen

Signature

export declare const andThen: {
  <_, B>(self: Option<_>, that: Option<B>): Option<B>
  <B>(that: Option<B>): <_>(self: Option<_>) => Option<B>
}

Added in v1.0.0

andThenDiscard

Sequences the specified that Option but ignores its value.

It is useful when we want to chain multiple operations, but only care about the result of self.

Signature

export declare const andThenDiscard: {
  <A, _>(self: Option<A>, that: Option<_>): Option<A>
  <_>(that: Option<_>): <A>(self: Option<A>) => Option<A>
}

Added in v1.0.0

as

Maps the Some value of this Option to the specified constant value.

Signature

export declare const as: { <_, B>(self: Option<_>, b: B): Option<B>; <B>(b: B): <_>(self: Option<_>) => Option<B> }

Added in v1.0.0

asUnit

Returns the Option resulting from mapping the Some value to void.

This is useful when the value of the Option is not needed, but the presence or absence of the value is important.

Signature

export declare const asUnit: <_>(self: Option<_>) => Option<void>

Added in v1.0.0

composeKleisliArrow

Signature

export declare const composeKleisliArrow: {
  <A, B, C>(afb: (a: A) => Option<B>, bfc: (b: B) => Option<C>): (a: A) => Option<C>
  <B, C>(bfc: (b: B) => Option<C>): <A>(afb: (a: A) => Option<B>) => (a: A) => Option<C>
}

Added in v1.0.0

flap

Signature

export declare const flap: {
  <A, B>(a: A, self: Option<(a: A) => B>): Option<B>
  <A, B>(self: Option<(a: A) => B>): (a: A) => Option<B>
}

Added in v1.0.0

flatMap

Applies a function to the value of an Option and flattens the result, if the input is Some.

Signature

export declare const flatMap: {
  <A, B>(f: (a: A) => Option<B>): (self: Option<A>) => Option<B>
  <A, B>(self: Option<A>, f: (a: A) => Option<B>): Option<B>
}

Added in v1.0.0

flatMapEither

Applies a provided function that returns an Either to the contents of an Option, flattening the result into another Option.

Signature

export declare const flatMapEither: {
  <A, E, B>(f: (a: A) => Either<E, B>): (self: Option<A>) => Option<B>
  <A, E, B>(self: Option<A>, f: (a: A) => Either<E, B>): Option<B>
}

Example

import * as O from '@fp-ts/core/Option'
import * as E from '@fp-ts/core/Either'
import { pipe } from '@fp-ts/core/Function'

const f = (n: number) => (n > 2 ? E.left('Too big') : E.right(n + 1))

assert.deepStrictEqual(pipe(O.some(1), O.flatMapEither(f)), O.some(2))
assert.deepStrictEqual(pipe(O.some(3), O.flatMapEither(f)), O.none())

Added in v1.0.0

flatMapNullable

This is flatMap + fromNullable, useful when working with optional values.

Signature

export declare const flatMapNullable: {
  <A, B>(f: (a: A) => B | null | undefined): (self: Option<A>) => Option<NonNullable<B>>
  <A, B>(self: Option<A>, f: (a: A) => B | null | undefined): Option<NonNullable<B>>
}

Example

import { some, none, flatMapNullable } from '@fp-ts/core/Option'
import { pipe } from '@fp-ts/core/Function'

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

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

assert.deepStrictEqual(
  pipe(
    some(employee1),
    flatMapNullable((employee) => employee.company?.address?.street?.name)
  ),
  some('high street')
)

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

assert.deepStrictEqual(
  pipe(
    some(employee2),
    flatMapNullable((employee) => employee.company?.address?.street?.name)
  ),
  none()
)

Added in v1.0.0

flatten

Signature

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

Added in v1.0.0

map

Maps the Some side of an Option value to a new Option value.

Signature

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

Added in v1.0.0

tap

Applies the provided function f to the value of the Option if it is Some and returns the original Option unless f returns None, in which case it returns None.

This function is useful for performing additional computations on the value of the input Option without affecting its value.

Signature

export declare const tap: {
  <A, _>(self: Option<A>, f: (a: A) => Option<_>): Option<A>
  <A, _>(f: (a: A) => Option<_>): (self: Option<A>) => Option<A>
}

Added in v1.0.0

type lambdas

OptionTypeLambda (interface)

Signature

export interface OptionTypeLambda extends TypeLambda {
  readonly type: Option<this['Target']>
}

Added in v1.0.0

utils

Alternative

Signature

export declare const Alternative: alternative.Alternative<OptionTypeLambda>

Added in v1.0.0

Applicative

Signature

export declare const Applicative: applicative.Applicative<OptionTypeLambda>

Added in v1.0.0

Chainable

Signature

export declare const Chainable: chainable.Chainable<OptionTypeLambda>

Added in v1.0.0

Coproduct

Signature

export declare const Coproduct: coproduct_.Coproduct<OptionTypeLambda>

Added in v1.0.0

Covariant

Signature

export declare const Covariant: covariant.Covariant<OptionTypeLambda>

Added in v1.0.0

Filterable

Signature

export declare const Filterable: filterable.Filterable<OptionTypeLambda>

Added in v1.0.0

FlatMap

Signature

export declare const FlatMap: flatMap_.FlatMap<OptionTypeLambda>

Added in v1.0.0

Foldable

Signature

export declare const Foldable: foldable.Foldable<OptionTypeLambda>

Added in v1.0.0

Invariant

Signature

export declare const Invariant: invariant.Invariant<OptionTypeLambda>

Added in v1.0.0

Monad

Signature

export declare const Monad: monad.Monad<OptionTypeLambda>

Added in v1.0.0

Of

Signature

export declare const Of: of_.Of<OptionTypeLambda>

Added in v1.0.0

Pointed

Signature

export declare const Pointed: pointed.Pointed<OptionTypeLambda>

Added in v1.0.0

Product

Signature

export declare const Product: product_.Product<OptionTypeLambda>

Added in v1.0.0

SemiAlternative

Signature

export declare const SemiAlternative: semiAlternative.SemiAlternative<OptionTypeLambda>

Added in v1.0.0

SemiApplicative

Signature

export declare const SemiApplicative: semiApplicative.SemiApplicative<OptionTypeLambda>

Added in v1.0.0

SemiCoproduct

Signature

export declare const SemiCoproduct: semiCoproduct.SemiCoproduct<OptionTypeLambda>

Added in v1.0.0

SemiProduct

Signature

export declare const SemiProduct: semiProduct.SemiProduct<OptionTypeLambda>

Added in v1.0.0

Traversable

Signature

export declare const Traversable: traversable.Traversable<OptionTypeLambda>

Added in v1.0.0

contains

Returns a function that checks if an Option contains a given value using a provided Equivalence instance.

Signature

export declare const contains: <A>(isEquivalent: (self: A, that: A) => boolean) => {
  (a: A): (self: Option<A>) => boolean
  (self: Option<A>, a: A): boolean
}

Example

import { some, none, contains } from '@fp-ts/core/Option'
import { Equivalence } from '@fp-ts/core/Number'
import { pipe } from '@fp-ts/core/Function'

assert.deepStrictEqual(pipe(some(2), contains(Equivalence)(2)), true)
assert.deepStrictEqual(pipe(some(1), contains(Equivalence)(2)), false)
assert.deepStrictEqual(pipe(none(), contains(Equivalence)(2)), false)

Added in v1.0.0

exists

Check if a value in an Option type meets a certain predicate.

Signature

export declare const exists: {
  <A>(predicate: Predicate<A>): (self: Option<A>) => boolean
  <A>(self: Option<A>, predicate: Predicate<A>): boolean
}

Example

import { some, none, exists } from '@fp-ts/core/Option'
import { pipe } from '@fp-ts/core/Function'

const isEven = (n: number) => n % 2 === 0

assert.deepStrictEqual(pipe(some(2), exists(isEven)), true)
assert.deepStrictEqual(pipe(some(1), exists(isEven)), false)
assert.deepStrictEqual(pipe(none(), exists(isEven)), false)

Added in v1.0.0

getOptionalMonoid

Monoid that models the combination of values that may be absent, elements that are None are ignored while elements that are Some are combined using the provided Semigroup.

The empty value is none().

Signature

export declare const getOptionalMonoid: <A>(Semigroup: Semigroup<A>) => Monoid<Option<A>>

Example

import * as O from '@fp-ts/core/Option'
import * as N from '@fp-ts/core/Number'
import { pipe } from '@fp-ts/core/Function'

const M = O.getOptionalMonoid(N.SemigroupSum)

assert.deepStrictEqual(M.combine(O.none(), O.none()), O.none())
assert.deepStrictEqual(M.combine(O.some(1), O.none()), O.some(1))
assert.deepStrictEqual(M.combine(O.none(), O.some(1)), O.some(1))
assert.deepStrictEqual(M.combine(O.some(1), O.some(2)), O.some(3))

Added in v1.0.0

unit

Signature

export declare const unit: Option<void>

Added in v1.0.0