Interface EitherBase<L, R>

Shared interface for Either variants. Contains all methods and type guards but does NOT include the discriminant _tag or value — those are declared on the variant interfaces (LeftOf / RightOf) so that Either acts as a true discriminated union. After if (e.isLeft()), the else branch narrows e to RightOf<L,R> and e.value narrows to R without a cast.

interface EitherBase<out L extends Type, out R extends Type> {
 _tag: "Left" | "Right";
 "[iterator]": () => Iterator<R>;
 "[toStringTag]": string;
 ap: <L2 extends unknown, U extends unknown>(
 ff: Either<L2, (value: R) => U>,
 ) => Either<L | L2, U>;
 bimap: <L2 extends unknown, R2 extends unknown>(
 fl: (value: L) => L2,
 fr: (value: R) => R2,
 ) => Either<L2, R2>;
 expect: (handler: (value: L) => never) => R;
 filterOrElse: <L2 extends unknown>(
 predicate: (value: R) => boolean,
 onUnsatisfied: (value: R) => L2,
 ) => Either<L | L2, R>;
 flatMap: <L2 extends unknown, U extends unknown>(
 f: (value: R) => Either<L2, U>,
 ) => Either<L | L2, U>;
 flatMapAsync: <L2 extends unknown, U extends unknown>(
 f: (value: R) => Promise<Either<L2, U>>,
 ) => Promise<Either<L | L2, U>>;
 fold: <T extends unknown>(
 onLeft: (value: L) => T,
 onRight: (value: R) => T,
 ) => T;
 foldAsync: <T extends unknown>(
 onLeft: (value: L) => T | Promise<T>,
 onRight: (value: R) => T | Promise<T>,
 ) => Promise<T>;
 map: (f: (value: R) => U) => Either<L, U>;
 mapAsync: (
 f: (value: R) => Promise,
 ) => Promise<Either<L, U>>;
 mapLeft: <L2 extends unknown>(f: (value: L) => L2) => Either<L2, R>;
 merge: <L1 extends unknown, R1 extends unknown>(
 other: Either<L1, R1>,
 ) => Either<L | L1, [R, R1]>;
 orNull: () => R | null;
 orThrow: (error?: Error | ((left: L) => Error)) => R;
 orUndefined: () => R | undefined;
 swap: () => Either<R, L>;
 tap: (f: (value: R) => void) => Either<L, R>;
 tapLeft: (f: (value: L) => void) => Either<L, R>;
 toOption: () => Option<R>;
 toString: () => string;
 traverse: <L2 extends unknown, U extends unknown>(
 f: (value: R) => Either<L2, U>,
 ) => Either<L | L2, U[]>;
 yield: () => Generator<R, void, unknown>;
 contains(value: R): boolean;
 doUnwrap(): DoResult<R>;
 exists(p: (a: R) => boolean): boolean;
 foldLeft(z: B): (op: (b: B, a: R) => B) => B;
 foldRight(z: B): (op: (a: R, b: B) => B) => B;
 forEach(f: (a: R) => void): void;
 isLeft(): this is LeftOf<L, R>;
 isRight(): this is RightOf<L, R>;
 match<T>(patterns: { Left: (value: L) => T; Right: (value: R) => T }): T;
 or<L2 extends unknown, R2 extends unknown>(
 alternative: Either<L2, R2>,
 ): Either<L | L2, R | R2>;
 orElse<R2 extends unknown>(defaultValue: R2): R | R2;
 pipe(f: (value: L | R) => U): U;
 pipeEither(
 onLeft: (value: L) => U,
 onRight: (value: R) => U,
 ): U;
 serialize(): SerializationMethods<R>;
 toEither<E extends unknown>(leftValue: E): Either<E, R>;
 toJSON(): { _tag: "Left" | "Right"; "@functype": "Either"; value: L | R };
 toList(): List<R>;
 toPromise(): Promise<R>;
 toTry(): Try<R>;
 toValue(): { _tag: "Left" | "Right"; value: L | R };
}

Type Parameters

out L extends Type
out R extends Type

Hierarchy (View Summary)

FunctypeSum<R, "Left" | "Right">
Promisable<R>
Doable<R>
Reshapeable<R>
Extractable<R>
- EitherBase
 - LeftOf
 - RightOf

Properties

`Readonly`_tag

_tag: "Left" | "Right"

[iterator]

"[iterator]": () => Iterator<R>

`Readonly`[toStringTag]

"[toStringTag]": string

ap

ap: <L2 extends unknown, U extends unknown>(
ff: Either<L2, (value: R) => U>,
) => Either<L | L2, U>

bimap

bimap: <L2 extends unknown, R2 extends unknown>(
fl: (value: L) => L2,
fr: (value: R) => R2,
) => Either<L2, R2>

expect

expect: (handler: (value: L) => never) => R

Returns the right value, or calls the never-returning handler with the Left's value. Use this when you have a helper like (msg) => fail(msg, 2) that terminates the program — the result type is unconditionally R, so you avoid the TypeScript narrowing trap where if (e.isLeft()) fail(...) fails to narrow e.value when fail is an arrow function typed as (...): never.

filterOrElse

filterOrElse: <L2 extends unknown>(
predicate: (value: R) => boolean,
onUnsatisfied: (value: R) => L2,
) => Either<L | L2, R>

Applies a predicate to the Right value. If the predicate fails, short-circuits to a Left carrying the value produced by onUnsatisfied. Left passes through unchanged (predicate not evaluated). Lets you turn a value-level guard into the Left channel without breaking the chain with an if/return Left(...) ladder.

Type Declaration

- <L2 extends unknown>(
 predicate: (value: R) => boolean,
 onUnsatisfied: (value: R) => L2,
 ): Either<L | L2, R>
- Type Parameters
 - L2 extends unknown
 Parameters
 - predicate: (value: R) => boolean
 The predicate to test the Right value
 - onUnsatisfied: (value: R) => L2
 Builds the new Left value when the predicate fails
 Returns Either<L | L2, R>
 Right if the predicate holds, Left(onUnsatisfied(value)) otherwise

flatMap

flatMap: <L2 extends unknown, U extends unknown>(
f: (value: R) => Either<L2, U>,
) => Either<L | L2, U>

flatMapAsync

flatMapAsync: <L2 extends unknown, U extends unknown>(
f: (value: R) => Promise<Either<L2, U>>,
) => Promise<Either<L | L2, U>>

Chains an async function that returns an Either. A Left resolves unchanged. If f rejects or throws, the returned Promise rejects with the same reason, as with mapAsync.

fold

fold: <T extends unknown>(
onLeft: (value: L) => T,
onRight: (value: R) => T,
) => T

foldAsync

foldAsync: <T extends unknown>(
onLeft: (value: L) => T | Promise<T>,
onRight: (value: R) => T | Promise<T>,
) => Promise<T>

Async variant of fold. Accepts sync or async handlers on either branch and always returns a Promise, keeping chains fluent when at least one branch is async.

`Readonly`map

map: (f: (value: R) => U) => Either<L, U>

mapAsync

mapAsync: (
f: (value: R) => Promise,
) => Promise<Either<L, U>>

Maps the Right value with an async function. A Left resolves unchanged. If f rejects or throws, the returned Promise rejects with the same reason: it does not become a Left, and it never throws synchronously. To turn a rejection into a Left, use Either.fromPromise(p, onRejected) or tryCatchAsync, which take a function from the reason to L.

mapLeft

mapLeft: <L2 extends unknown>(f: (value: L) => L2) => Either<L2, R>

merge

merge: <L1 extends unknown, R1 extends unknown>(
other: Either<L1, R1>,
) => Either<L | L1, [R, R1]>

orNull

orNull: () => R | null

Returns the contained value or null

Type Declaration

- (): R | null
- Returns R | null
  The contained value or null

orThrow

orThrow: (error?: Error | ((left: L) => Error)) => R

Returns the Right value, or throws on a Left. Pass an Error to throw it, or a builder to make one from the Left value — for code that must throw for a host (a retrying step runner, an MCP tool, a React Query queryFn). With no argument, throws the Left value itself.

orUndefined

orUndefined: () => R | undefined

Returns the contained value or undefined

Type Declaration

- (): R | undefined
- Returns R | undefined
  The contained value or undefined

swap

swap: () => Either<R, L>

tap

tap: (f: (value: R) => void) => Either<L, R>

tapLeft

tapLeft: (f: (value: L) => void) => Either<L, R>

toOption

toOption: () => Option<R>

Converts this monad to an Option.

Conversion rules:

Option: returns self
Either: Right → Some, Left → None
List: non-empty → Some(head), empty → None
Try: Success → Some, Failure → None

Type Declaration

- (): Option<R>
- Returns Option<R>
 An Option containing the value if present, None otherwise

toString

toString: () => string

Returns a string representation of an object.

traverse

traverse: <L2 extends unknown, U extends unknown>(
f: (value: R) => Either<L2, U>,
) => Either<L | L2, U[]>

yield

yield: () => Generator<R, void, unknown>

Methods

contains

contains(value: R): boolean
Parameters
- value: R
Returns boolean

Inherited from FunctypeSum.contains

doUnwrap

doUnwrap(): DoResult<R>

Returns DoResult<R>

Inherited from Doable.doUnwrap

exists

exists(p: (a: R) => boolean): boolean
Parameters
- p: (a: R) => boolean
Returns boolean

Inherited from FunctypeSum.exists

foldLeft

foldLeft(z: B): (op: (b: B, a: R) => B) => B
Left-associative fold using the provided zero value and operation
Type Parameters
- B
Parameters
- z: B
 Zero/identity value
Returns (op: (b: B, a: R) => B) => B
A function that takes an operation to apply

Inherited from FunctypeSum.foldLeft

foldRight

foldRight(z: B): (op: (a: R, b: B) => B) => B
Right-associative fold using the provided zero value and operation
Type Parameters
- B
Parameters
- z: B
 Zero/identity value
Returns (op: (a: R, b: B) => B) => B
A function that takes an operation to apply

Inherited from FunctypeSum.foldRight

forEach

forEach(f: (a: R) => void): void
Parameters
- f: (a: R) => void
Returns void

Inherited from FunctypeSum.forEach

isLeft

isLeft(): this is LeftOf<L, R>

Returns this is LeftOf<L, R>

isRight

isRight(): this is RightOf<L, R>

Returns this is RightOf<L, R>

match

match<T>(patterns: { Left: (value: L) => T; Right: (value: R) => T }): T
Pattern matches over the Either, applying a handler function based on the variant
Type Parameters
- T
Parameters
- patterns: { Left: (value: L) => T; Right: (value: R) => T }
Returns T

or

or<L2 extends unknown, R2 extends unknown>(
alternative: Either<L2, R2>,
): Either<L | L2, R | R2>
Returns this container if it has a value, otherwise returns the alternative container. The alternative may carry a different type; the result widens to Extractable<T | T2>.
Type Parameters
- L2 extends unknown
- R2 extends unknown
Parameters
- alternative: Either<L2, R2>
 The alternative container
Returns Either<L | L2, R | R2>
This container or the alternative

Overrides Extractable.or

orElse

orElse<R2 extends unknown>(defaultValue: R2): R | R2
Returns the contained value or a default value. The default may be of a different type; the result widens to T | T2.
Type Parameters
- R2 extends unknown
Parameters
- defaultValue: R2
 The value to return if extraction fails
Returns R | R2
The contained value or defaultValue

Overrides Extractable.orElse

pipe

pipe(f: (value: L | R) => U): U
Pipes the Either value through the provided function
Type Parameters
- U extends unknown
Parameters
- f: (value: L | R) => U
Returns U

pipeEither

pipeEither(
onLeft: (value: L) => U,
onRight: (value: R) => U,
): U
Pipes the value through the provided function based on whether this is a Left or Right
Type Parameters
- U extends unknown
Parameters
- onLeft: (value: L) => U
- onRight: (value: R) => U
Returns U

serialize

serialize(): SerializationMethods<R>

Returns SerializationMethods<R>

Inherited from FunctypeSum.serialize

toEither

toEither<E extends unknown>(leftValue: E): Either<E, R>
Converts this monad to an Either.

Conversion rules:
- Option: Some → Right, None → Left(leftValue)
- Either: returns self
- List: non-empty → Right(head), empty → Left(leftValue)
- Try: Success → Right, Failure → Left(leftValue). Try also accepts a builder (err: Error) => E to thread the underlying Error's context into the Left.
Type Parameters
- E extends unknown
Parameters
- leftValue: E
 The value to use for the Left case when the source is empty/none/failure
Returns Either<E, R>
An Either with the value as Right or the provided leftValue as Left

Inherited from Reshapeable.toEither

toJSON

toJSON(): { _tag: "Left" | "Right"; "@functype": "Either"; value: L | R }

Custom JSON serialization that excludes getter properties. Emits the canonical functype envelope with @functype: "Either" so native JSON.stringify recursion (e.g. inside a plain object body) produces a marker-bearing envelope that survives a round-trip through Serialization.deserialize.

Returns { _tag: "Left" | "Right"; "@functype": "Either"; value: L | R }

Overrides FunctypeSum.toJSON

toList

toList(): List<R>
Converts this monad to a List.

Conversion rules:
- Option: Some → List([value]), None → List([])
- Either: Right → List([value]), Left → List([])
- List: returns self
- Try: Success → List([value]), Failure → List([])
Returns List<R>
A List containing the value(s) if present, empty List otherwise

Inherited from Reshapeable.toList

toPromise

toPromise(): Promise<R>
Converts this container to a Promise

The behavior depends on the implementing container:
- Success/Right/Some containers resolve with their value
- Failure/Left/None containers reject with their error/default error
Returns Promise<R>
A Promise that resolves or rejects based on the container's state

Inherited from Promisable.toPromise

toTry

toTry(): Try<R>
Converts this monad to a Try.

Conversion rules:
- Option: Some → Success, None → Failure(Error("None"))
- Either: Right → Success, Left → Failure(Error(leftValue))
- List: non-empty → Success(head), empty → Failure(Error("Empty list"))
- Try: returns self
Returns Try<R>
A Try containing Success with the value or Failure with an appropriate error

Inherited from Reshapeable.toTry

toValue

toValue(): { _tag: "Left" | "Right"; value: L | R }

Returns the value and tag for inspection

Returns { _tag: "Left" | "Right"; value: L | R }

Interface EitherBase<L, R>

Type Parameters

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonly_tag

[iterator]

Readonly[toStringTag]

ap

bimap

expect

filterOrElse

Type Declaration

Type Parameters

Parameters

Returns Either<L | L2, R>

flatMap

flatMapAsync

fold

foldAsync

Readonlymap

mapAsync

mapLeft

merge

orNull

Type Declaration

Returns R | null

orThrow

orUndefined

Type Declaration

Returns R | undefined

swap

tap

tapLeft

toOption

Type Declaration

Returns Option<R>

toString

traverse

yield

Methods

contains

Parameters

Returns boolean

doUnwrap

Returns DoResult<R>

exists

Parameters

Returns boolean

foldLeft

Type Parameters

Parameters

Returns (op: (b: B, a: R) => B) => B

foldRight

Type Parameters

Parameters

Returns (op: (a: R, b: B) => B) => B

forEach

Parameters

Returns void

isLeft

Returns this is LeftOf<L, R>

isRight

Returns this is RightOf<L, R>

match

Type Parameters

Parameters

Returns T

or

Type Parameters

Parameters

Returns Either<L | L2, R | R2>

orElse

Type Parameters

Parameters

Returns R | R2

pipe

Type Parameters

`Readonly`_tag

`Readonly`[toStringTag]

`Readonly`map