Option

Combines a structure of Options (tuple, struct, or iterable) into a single Option containing the unwrapped structure.

When to use

Use when you need to combine multiple Option values into one while preserving the input shape, with any None making the result None.

Details

• Tuple input → Option of a tuple with the same length
• Struct input → Option of a struct with the same keys
• Iterable input → Option of an Array
• Any None in the input → entire result is None

See

• product for combining exactly two
• productMany for a homogeneous collection

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

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.some(25)

//      ┌─── Option<[string, number]>
//      ▼
const tuple = Option.all([maybeName, maybeAge]) // => Option.some(["John", 25])

//      ┌─── Option<{ name: string; age: number; }>
//      ▼
const struct = Option.all({ name: maybeName, age: maybeAge }) // => Option.some({ name: "John", age: 25 })

Combines two Options into a Some containing a tuple [A, B] if both are Some.

When to use

Use when you need to require two Option values to both be Some and keep both values as a tuple.

Details

• Both Some → Some([a, b])
• Either None → None

See

• zipWith to combine with a function instead of a tuple
• all to combine many Options

declare function product<A, B>(self: Option<A>, that: Option<B>): Option<[A, B]>

import { Option } from "effect"

Option.product(Option.some("hello"), Option.some(42)) // => Option.some(["hello", 42])
Option.product(Option.none(), Option.some(42)) // => Option.none()

Combines a primary Option with an iterable of Options into a tuple if all are Some.

When to use

Use when you need several Option values of the same type to all be Some and return them as a non-empty tuple.

Details

• All Some → Some([self.value, ...rest])
• Any None → None

See

• product for combining exactly two
• all for tuples, structs, and iterables

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

import { Option } from "effect"

const first = Option.some(1)
const rest = [Option.some(2), Option.some(3)]

Option.productMany(first, rest) // => Option.some([1, 2, 3])
Option.productMany(first, [Option.some(2), Option.none()]) // => Option.none()

Provides an Option containing an empty record {}, used as the starting point for do notation chains.

When to use

Use when you need to start an Option do notation pipeline before adding bindings.

See

• bind to add Option values
• let to add plain values
• bindTo to start by naming an existing Option

declare const Do: Option<{}>

import { Option, pipe } from "effect"

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)
) // => Option.some({ x: 2, y: 3, sum: 5 })

Wraps the first element of an Iterable in a Some, or returns None if the iterable is empty.

When to use

Use when you need to safely extract the head of a collection, including generators or lazy iterables.

Details

• Only consumes the first element; does not iterate the rest
• Returns None for empty iterables

See

• toArray for the inverse direction

declare function fromIterable<A>(collection: Iterable<A>): Option<A>

import { Option } from "effect"

Option.fromIterable([1, 2, 3]) // => Option.some(1)
Option.fromIterable([]) // => Option.none()

Creates a Combiner for Option<A> with fail-fast semantics: returns None if either operand is None.

When to use

Use when you need an Option combiner that returns None unless both operands are Some.

Details

• None + anything → None
• anything + None → None
• Some(a) + Some(b) → Some(combine(a, b))

See

• makeReducerFailFast to get a full Reducer

declare function makeCombinerFailFast<A>(combiner: Combiner<A>): Combiner<Option<A>>

import { Number, Option } from "effect"

const combiner = Option.makeCombinerFailFast(Number.ReducerSum)
combiner.combine(Option.some(1), Option.some(2)) // => Option.some(3)
combiner.combine(Option.some(1), Option.none()) // => Option.none()

Creates a Reducer for Option<A> that prioritizes the first non-None value and combines values when both are Some.

When to use

Use to build an Option reducer that falls back to the first available value when either side may be absent.

Details

• None + None → None
• Some(a) + None → Some(a)
• None + Some(b) → Some(b)
• Some(a) + Some(b) → Some(combine(a, b))
• Initial value is None

See

• makeReducerFailFast for fail-fast semantics

declare function makeReducer<A>(combiner: Combiner<A>): Reducer<Option<A>>

import { Number, Option } from "effect"

const reducer = Option.makeReducer(Number.ReducerSum)
reducer.combineAll([Option.some(1), Option.none(), Option.some(2)]) // => Option.some(3)

Creates a Reducer for Option<A> by lifting an existing Reducer with fail-fast semantics.

When to use

Use when you need to reduce Option values with fail-fast semantics, where any None aborts the entire result instead of being skipped.

Details

• Initial value is Some(reducer.initialValue)
• Combines only when both operands are Some
• Any None causes the result to become None immediately

See

• makeCombinerFailFast for just the combiner
• makeReducer for non-fail-fast semantics

declare function makeReducerFailFast<A>(reducer: Reducer<A>): Reducer<Option<A>>

import { Number, Option } from "effect"

const reducer = Option.makeReducerFailFast(Number.ReducerSum)
reducer.combineAll([Option.some(1), Option.some(2)]) // => Option.some(3)
reducer.combineAll([Option.some(1), Option.none()]) // => Option.none()

Creates an Option representing the absence of a value.

When to use

Use to represent a missing or uninitialized value, such as returning "no result" from a function.

Details

• Returns Option<never>, which is a subtype of Option<A> for any A
• Always returns the same singleton instance

See

• some for the opposite operation.

declare function none<A = never>(): Option<A>

import { Option } from "effect"

//      ┌─── Option<never>
//      ▼
const noValue = Option.none() // => Option.none()

Wraps the given value into an Option to represent its presence.

When to use

Use to wrap a known present value as Option

• Returning a successful result from a partial function

Details

• Always returns Some<A>
• Does not filter null or undefined; use fromNullishOr for that

See

• none for the opposite operation.

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

import { Option } from "effect"

//      ┌─── Option<number>
//      ▼
const value = Option.some(1) // => Option.some(1)

Converts a nullable value (null or undefined) into an Option.

When to use

Use when you need JavaScript nullish values to become absence at an API boundary while all other values, including falsy ones, remain present.

Details

• null or undefined → None
• Any other value → Some (typed as NonNullable<A>)

See

• fromNullOr to only treat null as absent
• fromUndefinedOr to only treat undefined as absent
• liftNullishOr to lift a nullable-returning function

declare function fromNullishOr<A>(a: A): Option<NonNullable<A>>

import { Option } from "effect"

Option.fromNullishOr(undefined) // => Option.none()
Option.fromNullishOr(null) // => Option.none()
Option.fromNullishOr(1) // => Option.some(1)

Converts a possibly null value into an Option, leaving undefined as a valid Some.

When to use

Use when you want to treat only null as absent while preserving undefined as a meaningful value.

Details

• null → None
• Any other value (including undefined) → Some

See

• fromNullishOr to treat both null and undefined as absent
• fromUndefinedOr to only treat undefined as absent

declare function fromNullOr<A>(a: A): Option<Exclude<A, null>>

import { Option } from "effect"

Option.fromNullOr(null) // => Option.none()
Option.fromNullOr(undefined) // => Option.some(undefined)
Option.fromNullOr(42) // => Option.some(42)

Converts a possibly undefined value into an Option, leaving null as a valid Some.

When to use

Use when you want to treat only undefined as absent while preserving null as a meaningful value.

Details

• undefined → None
• Any other value (including null) → Some

See

• fromNullishOr to treat both null and undefined as absent
• fromNullOr to only treat null as absent

declare function fromUndefinedOr<A>(a: A): Option<Exclude<A, undefined>>

import { Option } from "effect"

Option.fromUndefinedOr(undefined) // => Option.none()
Option.fromUndefinedOr(null) // => Option.some(null)
Option.fromUndefinedOr(42) // => Option.some(42)

Converts a Result into an Option, keeping only the failure value.

When to use

Use when you need to discard a Result success and keep only the failure value as an Option.

Details

• Failure becomes Some with the failure value
• Success becomes None and the success value is discarded

See

• getSuccess for the opposite operation.

declare const getFailure: <A, E>(self: Result<A, E>) => Option<E>

import { Option, Result } from "effect"

Option.getFailure(Result.succeed("ok")) // => Option.none()
Option.getFailure(Result.fail("err")) // => Option.some("err")

Extracts the value from a Some, or throws a default Error for None.

When to use

Use when you need quick fail-fast unwrapping of an Option and a generic error is acceptable.

Details

• Some → returns the inner value
• None → throws new Error("getOrThrow called on a None")

See

• getOrThrowWith for a custom error
• getOrElse for a non-throwing alternative

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

import { Option, Result } from "effect"

Option.getOrThrow(Option.some(1)) // => 1

const failure = Result.try({
  try: () => Option.getOrThrow(Option.none()),
  catch: (error) => (error as Error).message
})
Result.getFailure(failure).pipe(Option.getOrElse(() => "no error")) // => "getOrThrow called on a None"

Extracts the value from a Some, or throws a custom error for None.

When to use

Use when you need fail-fast unwrapping of an Option for unexpected absence and want to provide a descriptive debugging error.

Details

• Some → returns the inner value
• None → throws the value returned by onNone()

See

• getOrThrow for a version with a default error
• getOrElse for a non-throwing alternative

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

import { Option, Result } from "effect"

Option.getOrThrowWith(Option.some(1), () => new Error("missing")) // => 1

const failure = Result.try({
  try: () => Option.getOrThrowWith(Option.none(), () => new Error("missing")),
  catch: (error) => (error as Error).message
})
Result.getFailure(failure).pipe(Option.getOrElse(() => "no error")) // => "missing"

Converts a Result into an Option, keeping only the success value.

When to use

Use when you need to discard a Result failure and keep only the success value as an Option.

Details

• Success becomes Some with the success value
• Failure becomes None and the failure value is discarded

See

• getFailure for the opposite operation.

declare const getSuccess: <A, E>(self: Result<A, E>) => Option<A>

import { Option, Result } from "effect"

Option.getSuccess(Result.succeed("ok")) // => Option.some("ok")
Option.getSuccess(Result.fail("err")) // => Option.none()

Lifts a function that may return null or undefined into one that returns an Option.

When to use

Use to wrap existing nullable-returning functions for use in Option pipelines

Details

• Calls the original function with the given arguments
• Wraps the result via fromNullishOr

See

• fromNullishOr for converting a single value
• liftThrowable for functions that throw instead

declare function liftNullishOr<A extends readonly Array<unknown>, B>(f: (...a: A) => B): (...a: A) => Option<NonNullable<B>>

import { Option } from "effect"

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

const parseOption = Option.liftNullishOr(parse)

parseOption("1") // => Option.some(1)
parseOption("not a number") // => Option.none()

Lifts a function that may throw into one that returns an Option.

When to use

Use to wrap exception-throwing APIs (e.g. JSON.parse) for safe usage

Details

• If the function returns normally → Some with the result
• If the function throws → None (exception is swallowed)

See

• liftNullishOr for nullable-returning functions

declare function liftThrowable<A extends readonly Array<unknown>, B>(f: (...a: A) => B): (...a: A) => Option<B>

import { Option } from "effect"

const parse = Option.liftThrowable(JSON.parse)

parse("1") // => Option.some(1)
parse("") // => Option.none()

Converts an Option into an Array.

When to use

Use when you need to pass an Option to array-based APIs or spread optional values into collections.

Details

• Some → single-element array [value]
• None → empty array []

See

• fromIterable for the inverse direction

declare function toArray<A>(self: Option<A>): Array<A>

import { Option } from "effect"

Option.toArray(Option.some(1)) // => [1]
Option.toArray(Option.none()) // => []

Converts an Option-returning function into a type guard (refinement).

When to use

Use when you need to turn an Option-returning parser into a type-narrowing predicate, such as for Array.prototype.filter.

Details

• Returns true when the original function returns Some
• Returns false when the original function returns None
• Narrows the input type to B on success

See

• liftPredicate for the reverse direction

declare function toRefinement<A, B>(f: (a: A) => Option<B>): (a: A) => a is B

import { Option } from "effect"

type MyData = string | number

const parseString = (data: MyData): Option.Option<string> =>
  typeof data === "string" ? Option.some(data) : Option.none()

//      ┌─── (a: MyData) => a is string
//      ▼
const isString = Option.toRefinement(parseString)

isString("a") // => true
isString(1) // => false

Returns the first Some found in an iterable of Options, or None if all are None.

When to use

Use when you need the first available Some value from a priority list.

Details

• Short-circuits on the first Some
• Returns None only when every element is None

See

• orElse for a two-option fallback

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

import { Option } from "effect"

Option.firstSomeOf([
  Option.none(),
  Option.some(1),
  Option.some(2)
]) // => Option.some(1)

Returns the fallback Option if self is None; otherwise returns self.

When to use

Use when you need a lazy fallback Option, such as when building priority chains of optional values.

Details

• Some → returns self unchanged
• None → evaluates and returns that()
• that is lazily evaluated

See

• orElseSome to wrap the fallback value in Some automatically
• firstSomeOf to pick the first Some from a collection

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

import { Option } from "effect"

Option.none().pipe(Option.orElse(() => Option.some("b"))) // => Option.some("b")
Option.some("a").pipe(Option.orElse(() => Option.some("b"))) // => Option.some("a")

Returns the first available value and marks whether it came from the fallback.

When to use

Use when you need to know whether a present value came from the primary or fallback Option.

Details

• self is Some → Some(Result.fail(value)) (value from primary)
• self is None, that() is Some → Some(Result.succeed(value)) (value from fallback)
• Both None → None

See

• orElse for the simpler variant without source tracking

declare const orElseResult: {
  <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<Result<B, A>>;
  <A, B>(self: Option<A>, that: LazyArg<Option<B>>): Option<Result<B, A>>;
}

import { Option, Result } from "effect"

const fallback = () => Option.some("fallback")

Option.orElseResult(Option.some("primary"), fallback) // => Option.some(Result.fail("primary"))
Option.orElseResult(Option.none(), fallback) // => Option.some(Result.succeed("fallback"))

Returns Some of the fallback value if self is None; otherwise returns self.

When to use

Use when providing a default plain value (not an Option) as fallback

Details

• Some → returns self unchanged
• None → calls onNone(), wraps result in Some, and returns it

See

• orElse when the fallback is itself an Option

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

import { Option } from "effect"

Option.none().pipe(Option.orElseSome(() => "b")) // => Option.some("b")
Option.some("a").pipe(Option.orElseSome(() => "b")) // => Option.some("a")

Filters an Option using a predicate. Returns None if the predicate is not satisfied or the input is None.

When to use

Use when you need to discard an Option's present value when it does not meet a condition, while narrowing the type via a refinement predicate.

Details

• None → None
• Some where predicate(value) is true → Some(value)
• Some where predicate(value) is false → None
• Supports refinements for type narrowing

See

• filterMap to transform and filter simultaneously
• exists to test without filtering

declare const filter: {
  <A, B>(refinement: Refinement<A, B>): (self: Option<A>) => Option<B>;
  <A>(predicate: Predicate<A>): <B>(self: Option<B>) => Option<B>;
  <A, B>(self: Option<A>, refinement: Refinement<A, B>): Option<B>;
  <A>(self: Option<A>, predicate: Predicate<A>): Option<A>;
}

import { Option } from "effect"

const removeEmpty = (input: Option.Option<string>) =>
  Option.filter(input, (value) => value !== "")

removeEmpty(Option.some("hello")) // => Option.some("hello")
removeEmpty(Option.some("")) // => Option.none()
removeEmpty(Option.none()) // => Option.none()

Transforms and filters an Option using a Filter callback.

When to use

Use to transform an Option's present value and discard it when the Filter fails.

Details

The callback returns a Result: Result.succeed keeps and transforms the value, while Result.fail discards it.

See

• filter for predicate-based filtering

declare const filterMap: {
  <A, B, X>(f: Filter<A, B, X>): (self: Option<A>) => Option<B>;
  <A, B, X>(self: Option<A>, f: Filter<A, B, X>): Option<B>;
}

import { Option, Result } from "effect"

Option.filterMap(
  Option.some(2),
  (n) => (n % 2 === 0 ? Result.succeed(`Even: ${n}`) : Result.failVoid)
) // => Option.some("Even: 2")

Splits an Option into two Options using a function that returns a Result.

When to use

Use when you need to split an optional value into "left" and "right" channels using a Result-returning function.

Details

• None → [None, None]
• Some where f returns Err → [Some(error), None]
• Some where f returns Ok → [None, Some(value)]

See

• filter for simple predicate-based filtering

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

import { Option, Result } from "effect"

const parseNumber = (s: string): Result.Result<number, string> => {
  const n = Number(s)
  return isNaN(n) ? Result.fail("Not a number") : Result.succeed(n)
}

Option.partitionMap(Option.some("42"), parseNumber) // => [Option.none(), Option.some(42)]
Option.partitionMap(Option.some("abc"), parseNumber) // => [Option.some("Not a number"), Option.none()]
Option.partitionMap(Option.none(), parseNumber) // => [Option.none(), Option.none()]

Reduces an iterable of Options to a single value, skipping None entries.

When to use

Use when you need to aggregate values from a collection where some may be absent.

Details

• Iterates through the collection, applying f only to Some values
• None values are skipped entirely
• Returns the accumulated result

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

import { Option, pipe } from "effect"

const items = [Option.some(1), Option.none(), Option.some(2), Option.none()]

pipe(items, Option.reduceCompact(0, (b, a) => b + a)) // => 3

Provides generator-based syntax for Option, similar to async/await but for optional values. Yielding a None short-circuits the generator to None.

When to use

Use when you need generator syntax for a sequence of Option steps that should short-circuit on None.

Details

• Each yield* unwraps a Some value or short-circuits to None
• The return value is wrapped in Some
• No Effect runtime is needed

See

• Do / bind for the do notation alternative

declare const gen: Gen.Gen<OptionTypeLambda>

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.some(25)

Option.gen(function*() {
  const name = (yield* maybeName).toUpperCase()
  const age = yield* maybeAge
  return { name, age }
}) // => Option.some({ name: "JOHN", age: 25 })

Iterator protocol used to yield an Option inside gen, returning the contained value type back to the generator.

When to use

Use when defining or typing [Symbol.iterator]() for Option values so yield* can pass the contained value type back into Option.gen.

See

• gen for writing generator-based Option code that consumes this iterator protocol

interface OptionIterator<T extends Option<any>> {
  next(...args: readonly Array<any>): IteratorResult<T, Value<T>>;
}

Extracts the value from a Some, or evaluates a fallback thunk on None.

When to use

Use when providing a default value for an absent Option

• Unwrapping with lazy evaluation of the fallback

Details

• Some → returns the inner value
• None → calls onNone() and returns its result
• onNone is only called when needed (lazy)

See

• getOrNull to fall back to null
• getOrUndefined to fall back to undefined
• getOrThrow to throw on None

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

import { Option } from "effect"

Option.some(1).pipe(Option.getOrElse(() => 0)) // => 1
Option.none().pipe(Option.getOrElse(() => 0)) // => 0

Extracts the value from a Some, or returns null for None.

When to use

Use when you need to pass absent Option values to APIs that expect null.

Details

• Some → the inner value
• None → null

See

• getOrUndefined to return undefined instead
• getOrElse for a custom fallback

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

import { Option } from "effect"

Option.getOrNull(Option.some(1)) // => 1
Option.getOrNull(Option.none()) // => null

Extracts the value from a Some, or returns undefined for None.

When to use

Use when you need to pass absent Option values to APIs that expect undefined.

Details

• Some → the inner value
• None → undefined

See

• getOrNull to return null instead
• getOrElse for a custom fallback

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

import { Option } from "effect"

Option.getOrUndefined(Option.some(1)) // => 1
Option.getOrUndefined(Option.none()) // => undefined

Checks whether an Option is None (absent).

When to use

Use when you need to branch on an absent Option before accessing .value.

Details

• Acts as a type guard, narrowing to None<A>

See

• isSome for the opposite check.

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

import { Option } from "effect"

Option.isNone(Option.some(1)) // => false
Option.isNone(Option.none()) // => true

Determines whether the given value is an Option.

When to use

Use to validate unknown values at runtime boundaries, such as type-narrowing in union types.

Details

• Returns true for both Some and None instances
• Acts as a type guard, narrowing the input to Option<unknown>

See

• isNone to check for None specifically
• isSome to check for Some specifically

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

import { Option } from "effect"

Option.isOption(Option.some(1)) // => true
Option.isOption(Option.none()) // => true
Option.isOption({}) // => false

Checks whether an Option contains a value (Some).

When to use

Use when you need to branch on a present Option before accessing .value.

Details

• Acts as a type guard, narrowing to Some<A>

See

• isNone for the opposite check.

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

import { Option } from "effect"

Option.isSome(Option.some(1)) // => true
Option.isSome(Option.none()) // => false

Creates an Equivalence for Option<A> from an Equivalence for A.

When to use

Use when you need equality to treat two None values as equal and compare two Some values with a supplied equality rule.

Details

• None vs None → true
• Some vs None (or vice versa) → false
• Some(a) vs Some(b) → delegates to the provided Equivalence

declare function makeEquivalence<A>(isEquivalent: Equivalence<A>): Equivalence<Option<A>>

import { Equivalence, Option } from "effect"

const eq = Option.makeEquivalence(Equivalence.strictEqual<number>())

eq(Option.some(1), Option.some(1)) // => true
eq(Option.some(1), Option.some(2)) // => false
eq(Option.none(), Option.none()) // => true

Lifts a binary function to operate on two Option values.

When to use

Use when you need to reuse an existing binary function with two Option values.

Details

• Both Some → applies f and wraps in Some
• Either None → None

See

• zipWith for a non-lifted variant

declare function 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>;
}

import { Option } from "effect"

const addOptions = Option.lift2((a: number, b: number) => a + b)

addOptions(Option.some(2), Option.some(3)) // => Option.some(5)
addOptions(Option.some(2), Option.none()) // => Option.none()

Lifts a Predicate or Refinement into the Option context: returns Some(value) when the predicate holds, None otherwise.

When to use

Use to convert a boolean check into an Option-returning function

• Validating input and wrapping it in Option

Details

• predicate(value) is true → Some(value)
• predicate(value) is false → None
• Supports refinements for type narrowing

See

• filter to apply a predicate to an existing Option
• toRefinement for the inverse direction

declare const liftPredicate: {
  <A, B>(refinement: Refinement<A, B>): (a: A) => Option<B>;
  <B, A = B>(predicate: Predicate<A>): (b: B) => Option<B>;
  <A, B>(self: A, refinement: Refinement<A, B>): Option<B>;
  <B, A = B>(self: B, predicate: Predicate<A>): Option<B>;
}

import { Option } from "effect"

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

parsePositive(1) // => Option.some(1)
parsePositive(-1) // => Option.none()

Replaces the value inside a Some with a constant, leaving None unchanged.

When to use

Use when you need to replace a present Option value while preserving whether it was Some or None.

See

• asVoid to replace with undefined
• map for a general transformation

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

import { Option } from "effect"

Option.as(Option.some(42), "new value") // => Option.some("new value")
Option.as(Option.none(), "new value") // => Option.none()

Replaces the value inside a Some with void (undefined), leaving None unchanged.

When to use

Use when you need to discard a present Option value while preserving whether it was Some or None.

See

• as to replace with a specific constant

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

import { Option } from "effect"

Option.asVoid(Option.some(42)) // => Option.some(undefined)
Option.asVoid(Option.none()) // => Option.none()

Gives a name to the value of an Option, creating a single-key record inside Some. Starting point for the do notation pipeline.

When to use

Use when you need to start an Option do notation chain by naming the first value.

See

• Do for starting with an empty record
• bind to add Option values
• let to add plain values

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

import { Option, pipe } from "effect"

pipe(
  Option.some(2),
  Option.bindTo("x"),
  Option.bind("y", () => Option.some(3)),
  Option.let("sum", ({ x, y }) => x + y)
) // => Option.some({ x: 2, y: 3, sum: 5 })

Transforms the value inside a Some using the provided function, leaving None unchanged.

When to use

Use to apply a pure transformation to an Option's present value, especially when chaining transformations in a pipeline.

Details

• Some → applies f and wraps the result in a new Some
• None → returns None unchanged

See

• flatMap when f returns an Option
• as to replace the value with a constant

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

import { Option } from "effect"

Option.map(Option.some(2), (n) => n * 2) // => Option.some(4)
Option.map(Option.none(), (n: number) => n * 2) // => Option.none()

Represents the absence of a value within an Option.

When to use

Use as a type guard target when narrowing via isNone

Details

• _tag is always "None"
• Implements Pipeable, Inspectable, and structural equality

See

• isNone to check if an Option is None
• none to construct a None

interface None<out A> extends Pipeable, Inspectable {
  readonly _op: "None";
  readonly _tag: "None";
  [ignoreSymbol]?: OptionUnifyIgnore;
  [typeSymbol]?: unknown;
  [unifySymbol]?: OptionUnify<None<A>>;
  readonly "~effect/data/Option": {
    readonly _A: Covariant<A>;
  };
  readonly valueOrUndefined: undefined;
  [iterator](): OptionIterator<Option<A>>;
}

The Option data type represents optional values. An Option<A> is either Some<A>, containing a value of type A, or None, representing absence.

When to use

Use to represent initial values that may not yet exist

• Returning from partial functions (not defined for all inputs)
• Managing optional fields in data structures

See

• some for creating a Some
• none for creating a None
• match for pattern matching

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

Type-level unification support for Option values.

When to use

Use when extending Effect's type-level unification support for Option.

Details

This is used by Effect's Unify machinery to preserve the contained value type when generic code returns or combines Option values. Users normally do not need to reference this interface directly.

interface OptionUnify<A extends {
  [typeSymbol]?: any;
}> {
  Option?: () => A[typeof typeSymbol] extends Option<A0> | _ ? Option<A0> : never;
}

Marker interface used by Effect's Unify machinery for Option values.

When to use

Use when marking generic code so Option unification should be ignored.

Details

This supports type-level unification behavior for Option. Users normally do not need to reference this interface directly.

interface OptionUnifyIgnore {}

Represents the presence of a value within an Option.

When to use

Use as a type guard target when narrowing via isSome

• Access the inner value via .value

Details

• _tag is always "Some"
• .value holds the contained value of type A
• Implements Pipeable, Inspectable, and structural equality

See

• isSome to check if an Option is Some
• some to construct a Some

interface Some<out A> extends Pipeable, Inspectable {
  readonly _op: "Some";
  readonly _tag: "Some";
  [ignoreSymbol]?: OptionUnifyIgnore;
  [typeSymbol]?: unknown;
  [unifySymbol]?: OptionUnify<Some<A>>;
  readonly "~effect/data/Option": {
    readonly _A: Covariant<A>;
  };
  readonly value: A;
  readonly valueOrUndefined: A;
  [iterator](): OptionIterator<Option<A>>;
}

Namespace containing utility types for Option.

When to use

Use to access type-level helpers associated with Option.

Pattern-matches on an Option, handling both None and Some cases.

When to use

Use when you need to handle both Some and None in one expression and transform an Option into a plain value.

Details

• If None, calls onNone and returns its result
• If Some, calls onSome with the value and returns its result
• Supports the dual API (data-last and data-first)

See

• getOrElse for unwrapping with a default

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