Either<L, R>

Express success/failure with values.

Overview

Either represents a value that can be one of two types: Left (typically for errors) or Right (for success values). It’s perfect for operations that can fail with meaningful error information.

Basic Usage

import { Either, Left, Right } from "functype/either"

// Creating Either values
const success = Right(42) // Right(42)
const failure = Left("error") // Left("error")

// Checking state
success.isRight() // true
failure.isLeft() // true

// Extracting values
success.orElse(0) // 42
failure.orElse(0) // 0
success.orThrow() // 42
failure.orThrow() // throws Error

Constructors

Method	Description
Right(value)	Create a Right (success) value
Left(error)	Create a Left (error) value
Either.right(value)	Same as Right()
Either.left(error)	Same as Left()

Transformations

// Map - transform the Right value
Right(5).map((x) => x * 2) // Right(10)
Left("err").map((x) => x * 2) // Left("err") - unchanged

// MapLeft - transform the Left value
Left("err").mapLeft((e) => e.toUpperCase()) // Left("ERR")
Right(5).mapLeft((e) => e.toUpperCase()) // Right(5) - unchanged

// FlatMap - chain operations
Right(5).flatMap((x) => (x > 0 ? Right(x * 2) : Left("negative")))

// Bimap - transform both sides
either.bimap(
  (left) => `Error: ${left}`,
  (right) => right * 2,
)

Pattern Matching

// Using fold
const result = either.fold(
  (error) => `Failed: ${error}`,
  (value) => `Success: ${value}`,
)

// Using match pattern
const message = validateUser(input).fold(
  (errors) => `Validation failed: ${errors.join(", ")}`,
  (user) => `Welcome, ${user.name}!`,
)

Validation Pipeline

const validateAge = (age: number): Either<string, number> => (age >= 0 && age <= 120 ? Right(age) : Left("Invalid age"))

const validateName = (name: string): Either<string, string> => (name.length > 0 ? Right(name) : Left("Name required"))

// Chain validations
const validateUser = (data: UserInput) =>
  validateName(data.name).flatMap((name) => validateAge(data.age).map((age) => ({ name, age })))

Do-Notation

import { Do, $ } from "functype/do"

const result = Do(function* () {
  const name = yield* $(validateName(input.name))
  const age = yield* $(validateAge(input.age))
  const email = yield* $(validateEmail(input.email))
  return { name, age, email }
})

// Short-circuits on first Left

Key Features

• Error Information: Preserve detailed error context instead of losing it with try-catch
• Railway Oriented: Operations automatically short-circuit on Left
• Composable Errors: Chain operations with mapLeft to transform errors
• Type-Safe: Both success and error types are known at compile time

When to Use Either

• Operations that can fail with detailed error info (validation, parsing, API calls)
• Multiple validation steps in a pipeline
• Railway-oriented programming (happy path and error path handled separately)
• When you need typed errors at compile time

Type Conversions

either.toOption() // None for Left, Some(value) for Right
either.toTry() // Failure for Left, Success for Right
either.toPromise() // Rejected for Left, Resolved for Right

API Reference

See full API documentation at functype API docs