fp-either-ref_skill

Overview

This skill is a concise quick-reference for the Either type from fp-ts, focused on practical patterns for error handling, validation, and composable fallible operations. It shows how to create, transform, and extract Either values and demonstrates common idioms like chaining validations and converting throwing code into typed results. Use it when you want explicit error types and predictable control flow in TypeScript functional code.

How this skill works

The skill presents core constructors (Right, Left, fromNullable, tryCatch), transformation helpers (map, mapLeft, flatMap, filterOrElse), and extraction helpers (getOrElse, match, toUnion). It illustrates piping patterns with fp-ts/function to compose steps that return Either, stopping at the first failure. Examples include validating shapes, chaining checks, and wrapping JSON parsing into a typed Either.

When to use it

• When you need explicit, typed errors instead of throwing exceptions.
• When composing multiple validations or operations that can fail and you want early exit on first error.
• When converting imperative try/catch code to a functional, composable approach.
• When you want predictable error handling across async or sync flows in Node.js or browser code.
• When integrating fp-ts patterns (pipe, TaskEither) and you need a simple Either reference.

Best practices

• Prefer E.right/E.left and E.tryCatch for converting existing throwing APIs into typed results.
• Use pipe with E.flatMap to chain steps that return Either; it stops on the first Left.
• Transform error values with E.mapLeft to keep error types meaningful and consistent.
• Use E.filterOrElse for simple predicate checks that should produce a Left when falsy.
• Extract results with E.match or E.getOrElse to handle both success and failure explicitly.

Example use cases

• Email and age validation pipeline that stops at the first failing check and returns a descriptive error.
• Parsing JSON from an external source using E.tryCatch and mapping the parsed object if successful.
• Wrapping a synchronous library that throws into an Either to surface errors in types instead of runtime exceptions.
• Composing several data transformations where each step may fail, using E.flatMap to sequence them.
• Converting an Either into a union or default value at the boundary of an API using E.toUnion or E.getOrElse.