Option overview

Added in v2.0.0

combining
- all
- ap
- product
- productMany
constructors
- fromIterable
- none
- some
conversions
- fromNullable
- getLeft
- getOrThrow
- getOrThrowWith
- getRight
- liftNullable
- liftThrowable
- toArray
- toRefinement
do notation
- Do
- bind
- bindTo
- let
elements
- contains
- containsWith
equivalence
- getEquivalence
error handling
- firstSomeOf
- orElse
- orElseEither
- orElseSome
filtering
- filter
- filterMap
- partitionMap
folding
- reduceCompact
generators
- gen
getters
- getOrElse
- getOrNull
- getOrUndefined
guards
- isNone
- isOption
- isSome
lifting
- lift2
- liftPredicate
mapping
- as
- asVoid
- map
models
- None (interface)
- Option (type alias)
- OptionUnify (interface)
- OptionUnifyIgnore (interface)
- Some (interface)
pattern matching
- match
sequencing
- andThen
- composeK
- flatMap
- flatMapNullable
- flatten
- tap
sorting
- getOrder
symbols
- TypeId
- TypeId (type alias)
type lambdas
- OptionTypeLambda (interface)
utils
- Option (namespace)
  - Value (type alias)
- exists
- void
zipping
- zipLeft
- zipRight
- zipWith

combining

all

Takes a structure of Options and returns an Option of values with the same structure.

If a tuple is supplied, then the returned Option will contain a tuple with the same length.
If a struct is supplied, then the returned Option will contain a struct with the same keys.
If an iterable is supplied, then the returned Option will contain an array.

Signature

export declare const all: <const I extends Iterable<Option<any>> | Record<string, Option<any>>>(
  input: I
) => [I] extends [ReadonlyArray<Option<any>>]
  ? Option<{ -readonly [K in keyof I]: [I[K]] extends [Option<infer A>] ? A : never }>
  : [I] extends [Iterable<Option<infer A>>]
    ? Option<Array<A>>
    : Option<{ -readonly [K in keyof I]: [I[K]] extends [Option<infer A>] ? A : never }>

Example

import { Option } from "effect"

assert.deepStrictEqual(Option.all([Option.some(1), Option.some(2)]), Option.some([1, 2]))
assert.deepStrictEqual(Option.all({ a: Option.some(1), b: Option.some("hello") }), Option.some({ a: 1, b: "hello" }))
assert.deepStrictEqual(Option.all({ a: Option.some(1), b: Option.none() }), Option.none())

Added in v2.0.0

ap

Signature

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

Added in v2.0.0

product

Signature

export declare const product: <A, B>(self: Option<A>, that: Option<B>) => Option<[A, B]>

Added in v2.0.0

productMany

Signature

export declare const productMany: <A>(self: Option<A>, collection: Iterable<Option<A>>) => Option<[A, ...Array<A>]>

Added in v2.0.0

constructors

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 { Option } from "effect"

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

Added in v2.0.0

none

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

Signature

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

Added in v2.0.0

some

Creates a new Option that wraps the given value.

Signature

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

Added in v2.0.0

conversions

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 { Option } from "effect"

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

Added in v2.0.0

getLeft

Converts a Either to an Option discarding the value.

Signature

export declare const getLeft: <R, L>(self: Either<R, L>) => Option<L>

Example

import { Option, Either } from "effect"

assert.deepStrictEqual(Option.getLeft(Either.right("ok")), Option.none())
assert.deepStrictEqual(Option.getLeft(Either.left("a")), Option.some("a"))

Added in v2.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 { Option } from "effect"

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

Added in v2.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 { Option } from "effect"

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

Added in v2.0.0

getRight

Converts a Either to an Option discarding the error.

Signature

export declare const getRight: <R, L>(self: Either<R, L>) => Option<R>

Example

import { Option, Either } from "effect"

assert.deepStrictEqual(Option.getRight(Either.right("ok")), Option.some("ok"))
assert.deepStrictEqual(Option.getRight(Either.left("err")), Option.none())

Added in v2.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 ReadonlyArray<unknown>, B>(
  f: (...a: A) => B | null | undefined
) => (...a: A) => Option<NonNullable<B>>

Example

import { Option } from "effect"

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

const parseOption = Option.liftNullable(parse)

assert.deepStrictEqual(parseOption("1"), Option.some(1))
assert.deepStrictEqual(parseOption("not a number"), Option.none())

Added in v2.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 ReadonlyArray<unknown>, B>(f: (...a: A) => B) => (...a: A) => Option<B>

Example

import { Option } from "effect"

const parse = Option.liftThrowable(JSON.parse)

assert.deepStrictEqual(parse("1"), Option.some(1))
assert.deepStrictEqual(parse(""), Option.none())

Added in v2.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>) => Array<A>

Example

import { Option } from "effect"

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

Added in v2.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 { Option } from "effect"

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

const isPositive = Option.toRefinement(parsePositive)

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

Added in v2.0.0

do notation

Do

The “do simulation” in Effect allows you to write code in a more declarative style, similar to the “do notation” in other programming languages. It provides a way to define variables and perform operations on them using functions like bind and let.

Here’s how the do simulation works:

Start the do simulation using the Do value
Within the do simulation scope, you can use the bind function to define variables and bind them to Option values
You can accumulate multiple bind statements to define multiple variables within the scope
Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Signature

export declare const Do: Option<{}>

Example

import { Option, pipe } from "effect"

const result = pipe(
  Option.Do,
  Option.bind("x", () => Option.some(2)),
  Option.bind("y", () => Option.some(3)),
  Option.let("sum", ({ x, y }) => x + y),
  Option.filter(({ x, y }) => x * y > 5)
)
assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))

Added in v2.0.0

bind

Here’s how the do simulation works:

Start the do simulation using the Do value
Within the do simulation scope, you can use the bind function to define variables and bind them to Option values
You can accumulate multiple bind statements to define multiple variables within the scope
Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Signature

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

Example

import { Option, pipe } from "effect"

const result = pipe(
  Option.Do,
  Option.bind("x", () => Option.some(2)),
  Option.bind("y", () => Option.some(3)),
  Option.let("sum", ({ x, y }) => x + y),
  Option.filter(({ x, y }) => x * y > 5)
)
assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))

Added in v2.0.0

bindTo

Here’s how the do simulation works:

Start the do simulation using the Do value
Within the do simulation scope, you can use the bind function to define variables and bind them to Option values
You can accumulate multiple bind statements to define multiple variables within the scope
Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

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 }>
}

Example

import { Option, pipe } from "effect"

const result = pipe(
  Option.Do,
  Option.bind("x", () => Option.some(2)),
  Option.bind("y", () => Option.some(3)),
  Option.let("sum", ({ x, y }) => x + y),
  Option.filter(({ x, y }) => x * y > 5)
)
assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))

Added in v2.0.0

let

Here’s how the do simulation works:

Start the do simulation using the Do value
Within the do simulation scope, you can use the bind function to define variables and bind them to Option values
You can accumulate multiple bind statements to define multiple variables within the scope
Inside the do simulation scope, you can also use the let function to define variables and bind them to simple values
Regular Option functions like map and filter can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope

Signature

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

Example

import { Option, pipe } from "effect"

const result = pipe(
  Option.Do,
  Option.bind("x", () => Option.some(2)),
  Option.bind("y", () => Option.some(3)),
  Option.let("sum", ({ x, y }) => x + y),
  Option.filter(({ x, y }) => x * y > 5)
)
assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))

Added in v2.0.0

elements

contains

Returns a function that checks if an Option contains a given value using the default Equivalence.

Signature

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

Added in v2.0.0

containsWith

Returns a function that checks if a Option contains a given value using a provided isEquivalent function.

Signature

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

Example

import { pipe, Option, Number } from "effect"

assert.deepStrictEqual(pipe(Option.some(2), Option.containsWith(Number.Equivalence)(2)), true)
assert.deepStrictEqual(pipe(Option.some(1), Option.containsWith(Number.Equivalence)(2)), false)
assert.deepStrictEqual(pipe(Option.none(), Option.containsWith(Number.Equivalence)(2)), false)

Added in v2.0.0

equivalence

getEquivalence

Signature

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

Example

import { Option, Number } from "effect"

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

Added in v2.0.0

error handling

firstSomeOf

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

Signature

export declare const firstSomeOf: <T, C extends Iterable<Option<T>> = Iterable<Option<T>>>(
  collection: C
) => [C] extends [Iterable<Option<infer A>>] ? Option<A> : never

Example

import { Option } from "effect"

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

Added in v2.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 { pipe, Option } from "effect"

assert.deepStrictEqual(
  pipe(
    Option.none(),
    Option.orElse(() => Option.none())
  ),
  Option.none()
)
assert.deepStrictEqual(
  pipe(
    Option.some("a"),
    Option.orElse(() => Option.none())
  ),
  Option.some("a")
)
assert.deepStrictEqual(
  pipe(
    Option.none(),
    Option.orElse(() => Option.some("b"))
  ),
  Option.some("b")
)
assert.deepStrictEqual(
  pipe(
    Option.some("a"),
    Option.orElse(() => Option.some("b"))
  ),
  Option.some("a")
)

Added in v2.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<B, A>>
  <A, B>(self: Option<A>, that: LazyArg<Option<B>>): Option<Either<B, A>>
}

Added in v2.0.0

orElseSome

Returns the provided default value as Some if self is None, otherwise returns self.

Signature

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

Example

import { pipe, Option } from "effect"

assert.deepStrictEqual(
  pipe(
    Option.none(),
    Option.orElseSome(() => "b")
  ),
  Option.some("b")
)
assert.deepStrictEqual(
  pipe(
    Option.some("a"),
    Option.orElseSome(() => "b")
  ),
  Option.some("a")
)

Added in v2.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: {
  <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => Option<B>
  <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => Option<A>
  <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): Option<B>
  <A>(self: Option<A>, predicate: Predicate<A>): Option<A>
}

Example

import { Option } from "effect"

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

assert.deepStrictEqual(Option.filter(Option.none(), isEven), Option.none())
assert.deepStrictEqual(Option.filter(Option.some(3), isEven), Option.none())
assert.deepStrictEqual(Option.filter(Option.some(2), isEven), Option.some(2))

// refinement
const isNumber = (v: unknown): v is number => typeof v === "number"

assert.deepStrictEqual(Option.filter(Option.none(), isNumber), Option.none())
assert.deepStrictEqual(Option.filter(Option.some("hello"), isNumber), Option.none())
assert.deepStrictEqual(Option.filter(Option.some(2), isNumber), Option.some(2))

Added in v2.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>
}

Example

import { Option } from "effect"

const evenNumber = (n: number) => (n % 2 === 0 ? Option.some(n) : Option.none())

assert.deepStrictEqual(Option.filterMap(Option.none(), evenNumber), Option.none())
assert.deepStrictEqual(Option.filterMap(Option.some(3), evenNumber), Option.none())
assert.deepStrictEqual(Option.filterMap(Option.some(2), evenNumber), Option.some(2))

Added in v2.0.0

partitionMap

Signature

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

Added in v2.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 { pipe, Option } from "effect"

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

Added in v2.0.0

generators

gen

Signature

export declare const gen: Gen.Gen<OptionTypeLambda, Gen.Adapter<OptionTypeLambda>>

Added in v2.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 { pipe, Option } from "effect"

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

Added in v2.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 { Option } from "effect"

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

Added in v2.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 { Option } from "effect"

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

Added in v2.0.0

guards

isNone

Determine if a Option is a None.

Signature

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

Example

import { Option } from "effect"

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

Added in v2.0.0

isOption

Tests if a value is a Option.

Signature

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

Example

import { Option } from "effect"

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

Added in v2.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 { Option } from "effect"

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

Added in v2.0.0

lifting

lift2

Lifts a binary function into Option.

Signature

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

Added in v2.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: {
  <A, B extends A>(refinement: Refinement<A, B>): (a: A) => Option<B>
  <B extends A, A = B>(predicate: Predicate<A>): (b: B) => Option<B>
  <A, B extends A>(self: A, refinement: Refinement<A, B>): Option<B>
  <B extends A, A = B>(self: B, predicate: Predicate<A>): Option<B>
}

Example

import { Option } from "effect"

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

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

Added in v2.0.0

mapping

as

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

Signature

export declare const as: <B>(b: B) => <X>(self: Option<X>) => Option<B>

Added in v2.0.0

asVoid

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

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 asVoid: <_>(self: Option<_>) => Option<void>

Added in v2.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 v2.0.0

models

None (interface)

Signature

export interface None<out A> extends Pipeable, Inspectable {
  readonly _tag: "None"
  readonly _op: "None"
  readonly [TypeId]: {
    readonly _A: Covariant<A>
  }
  [Unify.typeSymbol]?: unknown
  [Unify.unifySymbol]?: OptionUnify<this>
  [Unify.ignoreSymbol]?: OptionUnifyIgnore
}

Added in v2.0.0

Option (type alias)

Signature

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

Added in v2.0.0

OptionUnify (interface)

Signature

export interface OptionUnify<A extends { [Unify.typeSymbol]?: any }> {
  Option?: () => A[Unify.typeSymbol] extends Option<infer A0> | infer _ ? Option<A0> : never
}

Added in v2.0.0

OptionUnifyIgnore (interface)

Signature

export interface OptionUnifyIgnore {}

Added in v2.0.0

Some (interface)

Signature

export interface Some<out A> extends Pipeable, Inspectable {
  readonly _tag: "Some"
  readonly _op: "Some"
  readonly value: A
  readonly [TypeId]: {
    readonly _A: Covariant<A>
  }
  [Unify.typeSymbol]?: unknown
  [Unify.unifySymbol]?: OptionUnify<this>
  [Unify.ignoreSymbol]?: OptionUnifyIgnore
}

Added in v2.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>(options: { readonly onNone: LazyArg<B>; readonly onSome: (a: A) => C }): (self: Option<A>) => B | C
  <A, B, C = B>(self: Option<A>, options: { readonly onNone: LazyArg<B>; readonly onSome: (a: A) => C }): B | C
}

Example

import { pipe, Option } from "effect"

assert.deepStrictEqual(
  pipe(Option.some(1), Option.match({ onNone: () => "a none", onSome: (a) => `a some containing ${a}` })),
  "a some containing 1"
)

assert.deepStrictEqual(
  pipe(Option.none(), Option.match({ onNone: () => "a none", onSome: (a) => `a some containing ${a}` })),
  "a none"
)

Added in v2.0.0

sequencing

andThen

Executes a sequence of two Options. The second Option can be dependent on the result of the first Option.

Signature

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

Added in v2.0.0

composeK

Signature

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

Added in v2.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 v2.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 { pipe, Option } from "effect"

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

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

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

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

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

Added in v2.0.0

flatten

Signature

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

Added in v2.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, X>(f: (a: A) => Option<X>): (self: Option<A>) => Option<A>
  <A, X>(self: Option<A>, f: (a: A) => Option<X>): Option<A>
}

Example

import { Option } from "effect"

const getInteger = (n: number) => (Number.isInteger(n) ? Option.some(n) : Option.none())

assert.deepStrictEqual(Option.tap(Option.none(), getInteger), Option.none())
assert.deepStrictEqual(Option.tap(Option.some(1), getInteger), Option.some(1))
assert.deepStrictEqual(Option.tap(Option.some(1.14), getInteger), Option.none())

Added in v2.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 { pipe, Option, Number } from "effect"

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

Added in v2.0.0

symbols

TypeId

Signature

export declare const TypeId: typeof TypeId

Added in v2.0.0

TypeId (type alias)

Signature

export type TypeId = typeof TypeId

Added in v2.0.0

type lambdas

OptionTypeLambda (interface)

Signature

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

Added in v2.0.0

utils

Option (namespace)

Added in v2.0.0

Value (type alias)

Signature

export type Value<T extends Option<any>> = [T] extends [Option<infer _A>] ? _A : never

Added in v2.0.0

exists

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

Signature

export declare const exists: {
  <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => self is Option<B>
  <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => boolean
  <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): self is Option<B>
  <A>(self: Option<A>, predicate: Predicate<A>): boolean
}

Example

import { pipe, Option } from "effect"

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

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

Added in v2.0.0

void

Signature

export declare const void: Option<void>

Added in v2.0.0

zipping

zipLeft

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 zipLeft: {
  <_>(that: Option<_>): <A>(self: Option<A>) => Option<A>
  <A, X>(self: Option<A>, that: Option<X>): Option<A>
}

Added in v2.0.0

zipRight

Signature

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

Added in v2.0.0

zipWith

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

Signature

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

Example

import { Option } from "effect"

type Complex = [real: number, imaginary: number]

const complex = (real: number, imaginary: number): Complex => [real, imaginary]

assert.deepStrictEqual(Option.zipWith(Option.none(), Option.none(), complex), Option.none())
assert.deepStrictEqual(Option.zipWith(Option.some(1), Option.none(), complex), Option.none())
assert.deepStrictEqual(Option.zipWith(Option.none(), Option.some(1), complex), Option.none())
assert.deepStrictEqual(Option.zipWith(Option.some(1), Option.some(2), complex), Option.some([1, 2]))

assert.deepStrictEqual(Option.zipWith(Option.some(1), complex)(Option.some(2)), Option.some([2, 1]))

Added in v2.0.0

Option overview

Table of contents

combining

all

ap

product

productMany

constructors

fromIterable

none

some

conversions

fromNullable

getLeft

getOrThrow

getOrThrowWith

getRight

liftNullable

liftThrowable

toArray

toRefinement

do notation

Do

bind

bindTo

let

elements

contains

containsWith

equivalence

getEquivalence

error handling

firstSomeOf

orElse

orElseEither

orElseSome

filtering

filter

filterMap

partitionMap

folding

reduceCompact

generators

gen

getters

getOrElse

getOrNull

getOrUndefined

guards

isNone

isOption

isSome

lifting

lift2

liftPredicate

mapping

as

asVoid

map

models

None (interface)

Option (type alias)

OptionUnify (interface)

OptionUnifyIgnore (interface)

Some (interface)

pattern matching

match

sequencing

andThen

composeK

flatMap

flatMapNullable

flatten

tap

sorting

getOrder

symbols

TypeId

TypeId (type alias)

type lambdas