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

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

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

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

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

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

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

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

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.

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.

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

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

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

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.

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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.

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

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

Checks whether an Option contains a value equal to the given one, using default structural equality.

When to use

Use when you need a quick membership test for an Option value using standard equality.

Details

- Some where Equal.equals(value, a) is true → true - Some where not equal, or None → false

See

• containsWith for custom equality
• exists to test with a predicate

Checks whether an Option contains a value equivalent to the given one, using a custom Equivalence.

When to use

Use when you need to test whether an Option contains a value using a custom equality check.

Details

- Some where isEquivalent(value, a) is true → true - Some where not equivalent, or None → false

See

• contains for a version using default equality

Checks whether the value in a Some satisfies a predicate or refinement.

When to use

Use to check a condition on an optional value without unwrapping

Details

- None → false - Some where predicate(value) is true → true - Some where predicate(value) is false → false - With a refinement, narrows the Option type on true

See

• filter to keep or discard based on a predicate
• contains to test for a specific value

Chains a second computation onto an Option. The second value can be a plain value, an Option, or a function returning either.

When to use

Use when you need to chain an Option with a next step that may be another Option, a plain value, or a function.

Details

- If self is None, returns None immediately - If f is a function, calls it with the Some value - If f returns an Option, returns it as-is; if a plain value, wraps in Some - If f is not a function, uses it directly (same wrapping rules)

See

• flatMap for the standard monadic bind
• map when you always return a plain value

Adds an Option value to the do notation record under a given name. If the Option is None, the whole pipeline short-circuits to None.

When to use

Use when you need to sequence Option computations in do notation.

See

• Do for starting the chain
• let to add plain values
• bindTo to start by naming an existing Option

Composes two Option-returning functions into a single function that chains them together.

When to use

Use when you need to compose two functions that each return an Option, so None short-circuits without calling the next function.

Details

- Calls afb(a), then if Some, calls bfc with its value - Short-circuits to None if either function returns None

See

• flatMap for single-step chaining

Applies a function that returns an Option to the value of a Some, flattening the result. Returns None if the input is None.

When to use

Use when you need to chain dependent Option computations where each step may return None.

Details

- Some → applies f to the value and returns its Option result - None → returns None without calling f - Equivalent to map followed by flatten

See

• map when f returns a plain value
• andThen for a more flexible variant
• flatten to unwrap a nested Option<Option<A>>

Combines flatMap with fromNullishOr: applies a function that may return null/undefined to the value of a Some.

When to use

Use when you need to chain optional computations that use null or undefined instead of Option, such as nested property access.

Details

- None → None - Some → applies f, then wraps via fromNullishOr

See

• flatMap when the function already returns Option
• fromNullishOr for single-value conversion

Flattens a nested Option<Option<A>> into Option<A>.

When to use

Use when you need to remove one layer of nested Option.

Details

- Some(Some(value)) → Some(value) - Some(None) → None - None → None

See

• flatMap which is map + flatten

Runs a side-effecting Option-returning function on the value of a Some, returning the original Option if the function returns Some, or None if it returns None.

When to use

Use to validate an Option's present value without transforming it, such as adding a side-condition check in a pipeline.

Details

- None → None - Some → calls f(value); if result is Some, returns original self; if None, returns None

See

• flatMap when you want to transform the value
• filter for predicate-based filtering

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

When to use

Use when you need to sort Some and None values, with None ordered before present values and present values compared by a supplied ordering rule.

Details

- None is considered less than any Some - Two Some values are compared using the provided Order - Two None values are equal (returns 0)

Type lambda interface for higher-kinded type encodings with Option.

When to use

Use when defining higher-kinded abstractions that must accept optional-value types as one of their type-lambda inputs.

Sequences two Options, keeping the value from the first if both are Some.

When to use

Use when you need two Option values to both be Some, then keep only the first value.

Details

- Both Some → returns self - Either None → returns None

See

• zipRight to keep the second value instead
• zipWith to combine both values

Sequences two Options, keeping the value from the second if both are Some.

When to use

Use when you need two Option values to both be Some, then keep only the second value.

Details

- Both Some → returns that - Either None → returns None

See

• zipLeft to keep the first value instead
• zipWith to combine both values

Combines two Options using a provided function.

When to use

Use when you need to combine two present Option values into a computed result.

Details

- Both Some → applies f(a, b) and wraps in Some - Either None → None

See

• product to combine into a tuple instead
• lift2 to lift a binary function