FsToolkit.ErrorHandling

FsToolkit.ErrorHandling is a utility library for F# designed to simplify error handling using the Result<'a, 'b> type. It provides a suite of functional programming tools to manage success and failure paths without manual pattern matching at every step.

Key capabilities include:

• Utility Functions: map, bind, apply, traverse, and sequence.
• Computation Expressions: Specialized expressions like asyncResult { ... } to compose asynchronous error-prone operations.
• Infix Operators: For concise manipulation of result types.
• Supported Types: Works with Result<'a, 'b>, Result<'a option, 'b>, Async<Result<'a, 'b>>, Async<Result<'a option, 'b>>, Result<'a, 'b list>, and (via the TaskResult package) Task<Result<'a, 'b>>.

FsToolkit.ErrorHandling is a utility library for F# designed to facilitate clear, simple, and powerful error handling using the Result type. It provides a suite of functional utilities and abstractions to manage success and failure states without relying on exceptions.

Key features include:

• Utility Functions: map, bind, apply, traverse, and sequence.
• Supported Types: Works with Result<'a, 'b>, Result<'a option, 'b>, Async<Result<'a, 'b>>, Async<Result<'a option, 'b>>, and Result<'a, 'b list>.
• Abstractions: Provides computation expressions and infix operators for composing error-prone logic.
• Compatibility: Targets .NET Standard 2.0, .NET Standard 2.1, and supports Fable (F# to JavaScript/Python).

This library is inspired by Railway Oriented Programming (ROP).

The library is structured into several specialized modules. You can find specific functional combinators (like map, bind, zip, and traverse) within each type's documentation.

Key functional patterns available across most types include:

• Mapping: map, map2, map3 to transform successful values.
• Chaining: bind to sequence computations.
• Error Handling: mapError, catch, orElse to manage failure paths.
• Combining: zip, apply, and zipError to merge multiple effects.
• Sequencing Collections: traverse and sequence functions for Lists, Sequences, and Arrays to turn a collection of effects into an effect containing a collection.

While both functions sequence a collection of results, Seq.sequenceResultM is monadic and short-circuits on the first error. In contrast, Seq.sequenceResultA (Applicative) typically collects all errors encountered in the sequence rather than stopping at the first one.

Choose Seq.sequenceResultM when you want to fail fast.

The taskOption CE supports for .. in .. iteration over IAsyncEnumerable<'T> sequences.

Behavior: If any iteration step results in a None value, the computation expression immediately stops iteration and returns None. It will not consume any further elements from the sequence once a None is encountered.

// Task<string option>
let processItems () =
  taskOption {
    for item in getItemsAsync () do
      do! tryProcessItem item
    return "done"
  }
// Returns None and stops iteration on the first None result

The taskValueOption CE supports for .. in .. iteration over IAsyncEnumerable<'T> sequences. If any item processed within the loop results in a ValueNone (via a let! or do! binding), the iteration stops immediately, no further elements are consumed, and the computation returns ValueNone.

// Task<string voption>
let processItems () =
  taskValueOption {
    for item in getItemsAsync () do
      do! tryProcessItem item
    return "done"
  }
// Returns ValueNone and stops iteration on the first ValueNone result

The cancellableTaskValidation computation expression (CE) uses let! to perform bind operations implicitly. This is often more readable for complex sequential workflows. If a let! binding fails, the CE short-circuits and returns the error immediately.

let createUser (input: CreateUserInput) : CancellableTaskValidation<UserId, string> =
    cancellableTaskvalidation {
        let! validatedEmail = validateEmail input.Email
        // bind is used implicitly here — short-circuits if validateEmail fails
        let! userId = createUserRecord validatedEmail input.Name
        return userId
    }