Skip to content
Effect Days 2026 Get your ticket

UndefinedOr

Works with values that may be undefined.

Use this module for plain TypeScript values of type A | undefined when undefined is the only absence marker. It is a small alternative to wrapping values in Option when your data already uses undefined to mean "no value". The module includes helpers for mapping defined values, matching both cases, throwing when a value is missing, adapting throwing functions, and building reducers or combiners.

8 exports Added in v4.0.0 Source

Constructors

makeCombinerFailFast

Added in v4.0.0 Source

Creates a Combiner for A | undefined that combines values only when both operands are defined.

When to use

Use to lift a Combiner so any undefined operand makes the combined result undefined.

Details

  • undefined combined with any value returns undefined
  • Any value combined with undefined returns undefined
  • a combined with b returns combiner.combine(a, b)

See

Signature

declare function makeCombinerFailFast<A>(combiner: Combiner<A>): Combiner<A | undefined>

makeReducer

Added in v4.0.0 Source

Creates a Reducer for UndefinedOr<A> that prioritizes the first non-undefined value and combines values when both operands are present.

When to use

Use when you need to reduce values that may be undefined, keeping the first defined value as a fallback and combining only when both operands are defined.

Details

Combining undefined with undefined returns undefined. Combining a defined value with undefined keeps the defined value, so the first defined value wins when only one side is present. When both values are defined, they are combined with combiner.combine. The reducer's initial value is undefined.

Signature

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

makeReducerFailFast

Added in v4.0.0 Source

Creates a Reducer for A | undefined by wrapping an existing reducer with fail-fast semantics.

When to use

Use to wrap an existing Reducer so any undefined value aborts the entire reduction result.

Details

  • Initial value is the wrapped reducer's initialValue
  • Combining two defined values delegates to the wrapped reducer
  • If the accumulator or next value is undefined, the reduction returns undefined

See

Signature

declare function makeReducerFailFast<A>(reducer: Reducer<A>): Reducer<A | undefined>

Converting

liftThrowable

Added in v4.0.0 Source

Converts a throwing function into one that returns successful results unchanged and returns undefined when the function throws.

When to use

Use to adapt exception-throwing functions when undefined is the absence value you want to return for failures.

Gotchas

Thrown values are discarded. If the wrapped function can successfully return undefined, that success is indistinguishable from a thrown failure.

Signature

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

Getters

getOrThrow

Added in v4.0.0 Source

Returns the defined value, or throws a default Error when the input is undefined.

When to use

Use when you need to unwrap a value that should already be defined and a generic missing-value Error is acceptable.

Details

Defined inputs are returned unchanged. undefined throws new Error("getOrThrow called on a undefined").

See

  • getOrThrowWith for the sibling that lets callers choose the thrown value
  • match for handling defined and undefined cases without throwing

Signature

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

getOrThrowWith

Added in v4.0.0 Source

Returns the defined value, or throws the value produced by onUndefined when the input is undefined.

When to use

Use when you need fail-fast unwrapping of an A | undefined value and want to provide the thrown error for the undefined case.

Details

Defined values are returned unchanged. When the input is undefined, onUndefined is called and its result is thrown.

See

  • getOrThrow for the default-error sibling
  • match for handling defined and undefined cases without throwing

Signature

declare const getOrThrowWith: {
  (onUndefined: () => unknown): <A>(self: A | undefined) => A;
  <A>(self: A | undefined, onUndefined: () => unknown): A;
}

Mapping

map

Added in v4.0.0 Source

Maps a defined value with f, or returns undefined unchanged.

When to use

Use to apply a pure transformation to an A | undefined value while preserving undefined as absence.

See

  • match when you need to handle the undefined case explicitly

Signature

declare const map: {
  <A, B>(f: (a: A) => B): (self: A | undefined) => B | undefined;
  <A, B>(self: A | undefined, f: (a: A) => B): B | undefined;
}

Pattern Matching

match

Added in v4.0.0 Source

Pattern matches on an A | undefined value, running onDefined when the value is present or evaluating onUndefined when the value is undefined.

When to use

Use when you need to turn an A | undefined into a non-optional result by handling both the defined and undefined branches in one expression.

See

  • map for transforming defined values while preserving undefined
  • getOrThrowWith for throwing when the value is undefined instead of returning a fallback branch

Signature

declare const match: {
  <B, A, C = B>(options: {
    readonly onDefined: (a: A) => C;
    readonly onUndefined: LazyArg<B>;
  }): (self: A | undefined) => B | C;
  <A, B, C = B>(self: A | undefined, options: {
    readonly onDefined: (a: A) => C;
    readonly onUndefined: LazyArg<B>;
  }): B | C;
}