Options
All
  • Public
  • Public/Protected
  • All
Menu

Represents a value of one of two possible types (a disjoint union).

A common use of Either is as an alternative to Option for dealing with possible missing values. In this usage Option.none is replaced with Either.left which can contain useful information and Option.some is replaced with Either.right.

Convention dictates that left is used for failure and right is used for success. Note that this Either type is right-biased, meaning that operations such as map, flatMap and filter work on the right value and if you want to work on the left value, then you need to do a swap.

For example, you could use Either<String, Int> to detect whether an input is a string or an number:

function tryParseInt(str: string): Either<string, number> {
  const i = parseInt(value)
  return isNaN(i) ? Left(str) : Right(i)
}

const result = tryParseInt("not an int")
if (result.isRight()) {
  console.log(`Increment: ${result.get}`)
} else {
  console.log(`ERROR: could not parse ${result.swap.get}`)
}
final

Type parameters

  • L

  • R

Hierarchy

Implements

Index

Constructors

Protected constructor

  • new Either(value: L | R, tag: "left" | "right"): Either

Properties

value

value: L | R

Methods

ap

  • Applicative apply operator.

    Resembles map, but the passed mapping function is lifted in the Either context.

    Type parameters

    • S

    Parameters

    Returns Either<L, S>

chain

  • chain<S>(f: function): Either<L, S>

contains

  • contains(elem: R): boolean
  • Returns true if this is a Right and its value is equal to elem (as determined by the equals protocol), returns false otherwise.

    // True
    Right("something").contains("something")
    
    // False because the values are different
    Right("something").contains("anything") // false
    
    // False because the source is a `left`
    Left("something").contains("something") // false
    

    Parameters

    • elem: R

    Returns boolean

equals

  • equals(that: Either<L, R>): boolean

exists

  • exists(p: function): boolean
  • Returns false if the source is a left, or returns the result of the application of the given predicate to the right value.

    // True, because it is a right and predicate holds
    Right(20).exists(n => n > 10)
    
    // False, because the predicate returns false
    Right(10).exists(n => n % 2 != 0)
    
    // False, because it is a left
    Left(10).exists(n => n == 10)
    

    Parameters

    • p: function
        • (r: R): boolean
        • Parameters

          • r: R

          Returns boolean

    Returns boolean

filterOrElse

  • filterOrElse<LL>(p: function, zero: function): Either<L | LL, R>
  • Filters right values with the given predicate, returning the value generated by zero in case the source is a right value and the predicate doesn't hold.

    Possible outcomes:

    • Returns the existing value of right if this is a right value and the given predicate p holds for it
    • Returns Left(zero()) if this is a right value and the given predicate p does not hold
    • Returns the current "left" value, if the source is a Left
    Right(12).filterOrElse(x => x > 10, () => -1) // Right(12)
    Right(7).filterOrElse(x => x > 10, () => -1)  // Left(-1)
    Left(7).filterOrElse(x => false, () => -1)    // Left(7)
    

    Type parameters

    • LL

    Parameters

    • p: function
        • (r: R): boolean
        • Parameters

          • r: R

          Returns boolean

    • zero: function
        • (): LL
        • Returns LL

    Returns Either<L | LL, R>

flatMap

  • flatMap<S>(f: function): Either<L, S>
  • Binds the given function across right values.

    This operation is the monadic "bind" operation. It can be used to chain multiple Either references.

    Type parameters

    • S

    Parameters

    • f: function

    Returns Either<L, S>

fold

  • fold<S>(left: function, right: function): S
  • Applies the left function to Left values, and the right function to Right values and returns the result.

    const maybeNum: Either<string, number> =
      tryParseInt("not a number")
    
    const result: string =
      maybeNum.fold(
        str => `Could not parse string: ${str}`,
        num => `Success: ${num}`
      )
    

    Type parameters

    • S

    Parameters

    • left: function
        • (l: L): S
        • Parameters

          • l: L

          Returns S

    • right: function
        • (r: R): S
        • Parameters

          • r: R

          Returns S

    Returns S

forAll

  • forAll(p: function): boolean
  • Returns true if the source is a left or returns the result of the application of the given predicate to the right value.

    // True, because it is a `left`
    Left("hello").forAll(x => x > 10)
    
    // True, because the predicate holds
    Right(20).forAll(x => x > 10)
    
    // False, it's a right and the predicate doesn't hold
    Right(7).forAll(x => x > 10)
    

    Parameters

    • p: function
        • (r: R): boolean
        • Parameters

          • r: R

          Returns boolean

    Returns boolean

forEach

  • forEach(cb: function): void
  • Executes the given side-effecting function if the source is a right value.

    Right(12).forAll(console.log) // prints 12
    Left(10).forAll(console.log)  // silent
    

    Parameters

    • cb: function
        • (r: R): void
        • Parameters

          • r: R

          Returns void

    Returns void

get

  • get(): R
  • Returns the Right value, if the source has one, otherwise throws an exception.

    WARNING!

    This function is partial, the Either must be a Right, otherwise a runtime exception will get thrown. Use with care.

    throws

    NoSuchElementError in case the the Either is a Left

    Returns R

getOrElse

  • getOrElse<RR>(fallback: RR): R | RR
  • Returns the value from this right or the given fallback value if this is a left.

    Right(10).getOrElse(27) // 10
    Left(10).getOrElse(27)  // 27
    

    Type parameters

    • RR

    Parameters

    • fallback: RR

    Returns R | RR

getOrElseL

  • getOrElseL<RR>(thunk: function): R | RR
  • Returns the value from this right or a value generated by the given thunk if this is a left.

    Right(10).getOrElseL(() => 27) // 10
    Left(10).getOrElseL(() => 27)  // 27
    

    Type parameters

    • RR

    Parameters

    • thunk: function
        • (): RR
        • Returns RR

    Returns R | RR

hashCode

  • hashCode(): number

isLeft

  • isLeft(): boolean
  • Returns true if this is a left, false otherwise.

    Left("hello").isLeft() // true
    Right(10).isLeft() // false
    

    Returns boolean

isRight

  • isRight(): boolean
  • Returns true if this is a right, false otherwise.

    Left("hello").isRight() // false
    Right(10).isRight() // true
    

    Returns boolean

map

  • map<C>(f: function): Either<L, C>
  • Transform the source if it is a right with the given mapping function.

    Right(10).map(x => x + 17) // right(27)
    Left(10).map(x => x + 17)  // left(10)
    

    Type parameters

    • C

    Parameters

    • f: function
        • (r: R): C
        • Parameters

          • r: R

          Returns C

    Returns Either<L, C>

swap

  • If this is a left, then return the left value as a right or vice versa.

    Right(10).swap() // left(10)
    Left(20).swap()  // right(20)
    

    Returns Either<R, L>

toOption

  • Returns an Option.some(right) if the source is a right value, or Option.none in case the source is a left value.

    Returns Option<R>

Static left

  • left<L, R>(value: L): Either<L, R>

Static map2

  • Maps 2 Either values by the mapping function, returning a new Either reference that is a Right only if both Either values are Right values, otherwise it returns the first Left value noticed.

    // Yields Right(3)
    Try.map2(Right(1), Right(2),
      (a, b) => a + b
    )
    
    // Yields Left, because the second arg is a Left
    Try.map2(Right(1), Left("error"),
      (a, b) => a + b
    )
    

    This operation is the Applicative.map2.

    Type parameters

    • A1

    • A2

    • L

    • R

    Parameters

    • fa1: Either<L, A1>
    • fa2: Either<L, A2>
    • f: function
        • (a1: A1, a2: A2): R
        • Parameters

          • a1: A1
          • a2: A2

          Returns R

    Returns Either<L, R>

Static map3

  • Maps 3 Either values by the mapping function, returning a new Either reference that is a Right only if all 3 Either values are Right values, otherwise it returns the first Left value noticed.

    // Yields Right(6)
    Try.map3(Right(1), Right(2), Right(3),
      (a, b, c) => a + b + c
    )
    
    // Yields Left, because the second arg is a Left
    Try.map3(Right(1), Left("error"), Right(3),
      (a, b, c) => a + b + c
    )
    

    Type parameters

    • A1

    • A2

    • A3

    • L

    • R

    Parameters

    • fa1: Either<L, A1>
    • fa2: Either<L, A2>
    • fa3: Either<L, A3>
    • f: function
        • (a1: A1, a2: A2, a3: A3): R
        • Parameters

          • a1: A1
          • a2: A2
          • a3: A3

          Returns R

    Returns Either<L, R>

Static map4

  • Maps 4 Either values by the mapping function, returning a new Either reference that is a Right only if all 4 Either values are Right values, otherwise it returns the first Left value noticed.

    // Yields Right(10)
    Try.map4(Right(1), Right(2), Right(3), Right(4),
      (a, b, c, d) => a + b + c + d
    )
    
    // Yields Left, because the second arg is a Left
    Try.map4(Right(1), Left("error"), Right(3), Right(4),
      (a, b, c, d) => a + b + c + d
    )
    

    Type parameters

    • A1

    • A2

    • A3

    • A4

    • L

    • R

    Parameters

    • fa1: Either<L, A1>
    • fa2: Either<L, A2>
    • fa3: Either<L, A3>
    • fa4: Either<L, A4>
    • f: function
        • (a1: A1, a2: A2, a3: A3, a4: A4): R
        • Parameters

          • a1: A1
          • a2: A2
          • a3: A3
          • a4: A4

          Returns R

    Returns Either<L, R>

Static map5

  • Maps 5 Either values by the mapping function, returning a new Either reference that is a Right only if all 5 Either values are Right values, otherwise it returns the first Left value noticed.

    // Yields Right(15)
    Try.map5(Right(1), Right(2), Right(3), Right(4), Right(5),
      (a, b, c, d, e) => a + b + c + d + e
    )
    
    // Yields Left, because the second arg is a Left
    Try.map5(Right(1), Left("error"), Right(3), Right(4), Right(5),
      (a, b, c, d, e) => a + b + c + d + e
    )
    

    Type parameters

    • A1

    • A2

    • A3

    • A4

    • A5

    • L

    • R

    Parameters

    • fa1: Either<L, A1>
    • fa2: Either<L, A2>
    • fa3: Either<L, A3>
    • fa4: Either<L, A4>
    • fa5: Either<L, A5>
    • f: function
        • (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5): R
        • Parameters

          • a1: A1
          • a2: A2
          • a3: A3
          • a4: A4
          • a5: A5

          Returns R

    Returns Either<L, R>

Static map6

  • Maps 6 Either values by the mapping function, returning a new Either reference that is a Right only if all 6 Either values are Right values, otherwise it returns the first Left value noticed.

    // Yields Right(21)
    Try.map5(Right(1), Right(2), Right(3), Right(4), Right(5), Right(6),
      (a, b, c, d, e, f) => a + b + c + d + e + f
    )
    
    // Yields Left, because the second arg is a Left
    Try.map5(Right(1), Left("error"), Right(3), Right(4), Right(5), Right(6),
      (a, b, c, d, e, f) => a + b + c + d + e + f
    )
    

    Type parameters

    • A1

    • A2

    • A3

    • A4

    • A5

    • A6

    • L

    • R

    Parameters

    • fa1: Either<L, A1>
    • fa2: Either<L, A2>
    • fa3: Either<L, A3>
    • fa4: Either<L, A4>
    • fa5: Either<L, A5>
    • fa6: Either<L, A6>
    • f: function
        • (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6): R
        • Parameters

          • a1: A1
          • a2: A2
          • a3: A3
          • a4: A4
          • a5: A5
          • a6: A6

          Returns R

    Returns Either<L, R>

Static pure

  • pure<A>(value: A): Either<never, A>
  • Builds a pure Either value.

    This operation is the pure Applicative operation for lifting a value in the Either context.

    Type parameters

    • A

    Parameters

    • value: A

    Returns Either<never, A>

Static right

  • right<L, R>(value: R): Either<L, R>

Static tailRecM

  • tailRecM<L, A, B>(a: A, f: function): Either<L, B>

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc