Implement Typed Error Handling with fp-ts Either

This is a compact cheat sheet for fp-ts's Either type: a value that is either a success, Right(value), or a failure, Left(error). It groups the API into create, transform, and extract functions rather than a long tutorial.

To create an Either, it lists E.right(value) for success, E.left(error) for failure, E.fromNullable(err)(x) which turns a nullable value into Left(err) on null or Right(x) otherwise, and E.tryCatch(fn, toError) which wraps a try/catch into an Either. To transform one, it lists E.map(fn) to transform the Right value, E.mapLeft(fn) to transform the Left error, E.flatMap(fn) to chain a function that itself returns an Either, and E.filterOrElse(pred, toErr) to turn a Right into a Left when a predicate fails. To extract a result, it lists E.getOrElse(err => default) to get the Right value or a default, E.match(onLeft, onRight) to pattern match on both branches, and E.toUnion(either) to collapse to a plain union type, noted as losing type information.

Its common-patterns example validates an email and an age in sequence, stopping at the first error, using pipe and E.flatMap:

import { pipe } from 'fp-ts/function'
import * as E from 'fp-ts/Either'

// Validation
const validateEmail = (s: string): E.Either<string, string> =>
  s.includes('@') ? E.right(s) : E.left('Invalid email')

// Chain validations (stops at first error)
pipe(
  E.right({ email: 'test@example.com', age: 25 }),
  E.flatMap(d => pipe(validateEmail(d.email), E.map(() => d))),
  E.flatMap(d => d.age >= 18 ? E.right(d) : E.left('Must be 18+'))
)

It also compares Either against a plain try/catch, arguing that try/catch leaves errors out of the type system while Either keeps them explicit in the type, and gives its own guidance: use Either when the error type matters and you want to chain operations.

Use it when you need a quick fp-ts reference for typed synchronous error handling, when the task involves validation, fallible operations, or converting throwing code to Either, or when you want a compact cheat sheet rather than a long tutorial.

Inputs are TypeScript code that currently throws, returns null, or needs chained validation. Outputs are Either-typed values and chains built from the create, transform, and extract functions listed above, such as E.tryCatch wrapping a JSON.parse call or a pipe of validation steps.

It is for TypeScript developers using fp-ts who want typed, chainable error handling instead of try/catch, and who want a quick lookup rather than a full functional-programming tutorial.