Master Async Error Handling with fp-ts

Practical Async Patterns with fp-ts is a skill for writing TypeScript async code with fp-ts's TaskEither type instead of nested try/catch blocks. TaskEither<Error, A> represents an async operation that either fails with an Error or succeeds with a value of type A. The skill walks through wrapping promises safely with TE.tryCatch (which takes an async function and a function converting any thrown value into your error type), creating success/failure values directly with TE.right and TE.left, and deriving TaskEither from nullable values (TE.fromNullable) or conditions (TE.fromPredicate).

Use it when you need typed async error handling in TypeScript, are wrapping Promises or composing multiple API calls, or want to replace deeply nested try/catch chains with a flat pipeline built from TE.chain and pipe. It also covers choosing between parallel and sequential execution: run independent operations concurrently with sequenceT(TE.ApplyPar) or TE.traverseArray (noting that traverseArray fails fast, so errors after the first are lost), cap concurrency by chunking an array into fixed-size batches and processing batches sequentially while items within each batch run in parallel, or force sequential chaining when one step's result feeds the next - for example, creating a user record before creating its dependent profile, where running both in parallel would race. Use TE.chain over TE.map specifically when a step can fail or is itself async; TE.map is for synchronous, infallible transforms only.

Inputs are async functions or Promises being wrapped, such as a fetch call or a database query. Outputs are TaskEither values that carry either a typed error or the resolved value, composed via pipe with TE.chain, TE.map, TE.bind (Do-notation for accumulating context across steps), TE.orElse for fallback recovery, TE.getOrElse to collapse into a plain Task with a default value once the error channel is no longer needed, and TE.fold for exhaustively handling both the success and failure branches at the end of a pipeline, such as producing an HTTP response, or awaiting the TaskEither directly to get the raw Either and pattern-match on it. The skill also demonstrates typed error unions, using a discriminated tag field to distinguish variants like NotFound, NetworkError, Unauthorized, UniqueViolation, and ConnectionError, so different failures can be recovered from differently, plus a retry helper with exponential backoff built from TE.orElse and a delay Task. A quick-reference set of smaller combinators rounds this out: TE.map/TE.mapLeft/TE.bimap for transforming the success value, error value, or both at once, TE.filterOrElse to fail a pipeline when a value doesn't satisfy a predicate, TE.tap/TE.chainFirst for side effects like logging that don't change the piped value, and TE.fromEither/TE.fromOption for lifting an existing Either or Option into a TaskEither.

Worked examples cover a fetch-based JSON API wrapper (with a typed ApiError and handling for 204 No Content responses), a Prisma-based database repository layer that maps PrismaClientKnownRequestError codes - P2002 for a unique-constraint violation, P2025 for not-found - into a typed DbError union, and Node.js file operations via fs/promises with error mapping for ENOENT and EACCES. It also shows wiring a TaskEither pipeline into Express/Hono route handlers with TE.fold, converting the final Either into an HTTP status code and JSON body.

TypeScript developers already using or adopting fp-ts who want composable, typed async error handling instead of nested try/catch - particularly useful for API clients, database repository layers, and request handlers where consistent error typing and recovery, such as falling back to a cache, retrying, or returning a default value, matters more than academic functional-programming theory.