Chapter 6. Functional error handling

Error handling is an important part of our applications, and one aspect in which the functional and imperative programming styles differ starkly:

There are lots of problems with the imperative, exception-based approach. It has been said that throw has similar semantics to goto, and this begs the question of why imperative programmers have banished goto but not throw.^[1] There’s also a lot of confusion around when to use exceptions and when to use other error-handling techniques. I feel that the functional approach brings a lot more clarity to the complex area of error handling, and I hope to convince you of this through the examples in this chapter.

¹In fact, I think throw is much worse than goto. The latter at least jumps to a well-defined location; with throw, you don’t really know what code will execute next, unless you explore all possible paths into the code where throw occurs.

We’ll look at how the functional approach can be put into practice, and how you can make explicit that a function can fail through its signature, by using types that include error information in their payload. Errors can then be consumed in the calling function just like any other value.

6.1. A safer way to represent outcomes

In chapter 3, you saw that you could use Option not just to represent the absence of a value, but also the absence of a valid value. That is, you can use Some to signal that everything went OK, and None to signal that something went wrong. In other words, functional error handling can sometimes be satisfactorily achieved by using the Option type. Here are a couple of examples:

In scenarios like these, there’s really only one way for the function to not return a valid result, and that’s represented with None. Functions that return Option<T>, rather than just T, are acknowledging in their signature that the operation may fail, and you could take the isSome flag that indicates the state of the Option (see listing 3.7) as the additional payload that signals success or failure.

What if there are several ways in which an operation could fail? What if, for instance, the BOC application receives a complex request, such as a request to make a money transfer? Surely the user would need to know not only whether the transfer was successfully booked, but also, in case of failure, the reason(s) for failure.

In such scenarios, Option is too limited, because it doesn’t convey any details about why an operation has failed. Accordingly, we’ll need a richer way to represent outcomes—one that includes information about what exactly has gone wrong.

6.1.1. Capturing error details with Either

A classic functional approach to this problem is to use the Either type, which, in the context of an operation with two possible outcomes, captures details about the outcome that has taken place. By convention, the two possible outcomes are indicated with Left and Right (as shown in figure 6.1), likening the Either-producing operation to a fork: things can go one way or another.

Although Left and Right can be seen in a neutral light, by far the most common use of Either is to represent the outcome of an operation that may fail, in which case Left is used to indicate failure and Right to indicate success. So, remember this:

In this biased acceptation, Either is just like an Option that has been enriched with some data about the error. An Option can be in the None or Some state, and Either can similarly be in the Left or Right state, as summarized in table 6.1.

If Option can be symbolically defined as

then Either can similarly be defined like this:

Notice that Either has two generic parameters and can be in one of two states:

Let’s see how an Option-based interface may differ from an Either-based one. Imagine you’re doing some DIY and go to the store to get a tool you need. If the item isn’t available, an Option-based shopkeeper would just say, “Sorry, it’s not available,” and that’s it. An Either-based shopkeeper would give you more information, such as, “We’re out of stock until next week,” or “This product has been discontinued”; you can base your further decisions on this information.

What about a deceiving shopkeeper who, having run out of stock, will sell you a product that looks just like the one you’re after, but which will explode in your face when you put it to use? Well, that’s the imperative, exception-throwing interface.

Because the definition of Either is so similar to Option, it can be implemented using the same techniques. In my LaYumba.Functional library, I have two generic types, Left<L> and Right<R>, that wrap a single value, and both are implicitly convertible to Either<L, R>. For convenience, values of type L and R are also implicitly convertible to Either<L, R>.

You can see the full implementation in the code samples, but I won’t include it here because there’s nothing new compared to what was discussed in section 3.4.3 about the implementation of Option. Instead, let’s play around with Either in the REPL. As usual, you need to start by referencing LaYumba.Functional:

Now create some Eithers:

That was easy! Now let’s write a function that uses Match to compute a different value depending on the state of an Either:

Now that you know how to create and consume an Either, let’s look at a slightly more interesting example. Imagine a function that performs a simple calculation:

For the calculation to be performed correctly, we need to ensure that y is non-zero and that the ratio x/y is non-negative. If one of these conditions isn’t met, we’d like to know which one. So the calculation returns, let’s say, a double in the happy path, and a string with an error message otherwise. That means the return of this function should be Either<string, double>—remember, the successful type is the one on the right. Here’s the implementation.

The signature of Calc clearly declares that it will return a structure wrapping “either a string, or a double,” and indeed the implementation returns either a string (an error message) or a double (the result of the computation). In either case, the returned value will be implicitly lifted into an Either.

Let’s test it out in the REPL:

Because Either is so similar to Option, you might guess that the core functions you’ve seen in relation to Option will have counterparts for Either. Let’s find out.

6.1.2. Core functions for working with Either

Like with Option, we can define Map, ForEach, and Bind in terms of Match. The Left case is used to signal failure, so the computation is skipped in the Left case:

There are a couple of things to point out here. In all cases, the function is applied only if the Either is Right.^[2] This means that if we think of Either as a fork, then whenever we take the left path, we go to a dead end.

²This is what’s called a biased implementation of Either. There are also different, unbiased implementations of Either that aren’t used to represent error/success disjunctions, but two equally valid paths. In practice, the biased implementations are much more widely used.

Also notice that when you use Map and Bind, the R type changes. Just as Option<T> is a functor on T, Either<L, R> is a functor on R, meaning that you can use Map to apply functions to R. The L type, on the other hand, remains the same.

What about Where? Remember, you can call Where with a predicate and “filter out” the inner value of an Option if it fails to satisfy the predicate:

With Either, you can’t do that: failure to meet a condition should yield a Left, but because Where takes a predicate, and a predicate only returns a Boolean, there’s no reasonable value type L with which you can populate the Left value. It’s probably easier to see if you try to implement Where for Either:

As you can see, if the Either is Right, but its inner value doesn’t satisfy the predicate, you should return a Left, but there’s no available value of type L with which you could populate a Left.

You’ve just learned that Where is less general than Map and Bind: it can only be defined for structures for which a zero value exists (such as an empty sequence for IEnumerable, or None for Option). There’s no zero value for Either<L, R> because L is an arbitrary type. You can only cause an Either to fail by explicitly creating a Left, or by calling Bind with a function that may return a suitable L value.

You’ll see this in practice in the next example, where I’ll show you an Option-based implementation and an Either-based one side by side.

6.1.3. Comparing Option and Either

Imagine we’re modeling a recruitment process. We’ll start with an Option-based implementation, in which Some(Candidate) represents a candidate that has passed the interview process so far, whereas None represents rejection.

The recruitment process consists of a technical test first, and then an interview. Fail the test, and the interview won’t take place. But even prior to the test, we’ll check that the candidate is eligible to work. With Option, we can apply the IsEligible predicate with Where so that if the candidate isn’t eligible, the subsequent steps won’t take place.

Now, imagine that HR isn’t happy to just know whether a candidate has passed or not; they also want to know details about the reasons for failure because this information allows them to refine the recruitment process. We can refactor to an Either-based implementation, capturing the reasons for rejection with a Rejection object. The Right type will be Candidate as before, and the Left type will be Rejection.

We now need to be more explicit about failing the IsEligible test, so we turn this predicate into an Either-returning function, CheckEligibility, providing a suitable Left value (the Rejection) for when the predicate isn’t passed. We can now compose CheckEligibility into the workflow using Bind.

Notice that the Either-based implementation is more verbose, and this makes sense, since we choose Either when we need to be explicit about failure conditions.

6.2. Chaining operations that may fail

Either lends itself particularly well to representing a chain of operations where any operation may cause a deviation from the happy path. For example, once every so often, you prepare your boy- or girl-friend’s favorite dish. The workflow may look like this:

At each step of the way, something may go wrong: you could oversleep, you could wake up to stormy weather that prevents you from getting to the shops, you could get distracted and let everything burn... In short, only if everything goes well do you get to a happy meal together.

Using Either, we can model the preceding workflow like so.

Remember from the definition of Bind that if the state is Left, the Left value just gets passed along. So in the preceding listing, when we say ComplainAbout(reason), the reason is whatever failed in any of the previous steps: if we failed to wake up, ComplainAbout will receive the reason for that; likewise if we failed to shop, and so on.

The previous tree-like diagram is a correct logical representation of the workflow; another way to look at it, closer to the implementation details, is shown in figure 6.2.

Each function returns a two-part structure, the Either, and is chained with the next function via Bind. A workflow obtained by chaining several Either-returning functions can be seen as a two-track system:^[3]

³In a tutorial on this style of error handling, F# evangelist Scott Wlaschin builds a “railway” analogy. I encourage you to look at his “Railway Oriented Programming” article and video conference, available on his site at http://fsharpforfunandprofit.com/rop/.

Although the “favorite dish” example is rather frivolous, it’s representative of many programming scenarios. For example, imagine a stateless server that, upon receiving a request, must perform the following steps:

Any of these operations could potentially fail, and failure at any step should prevent the workflow from continuing, and the response should include details about the success or failure of the requested operation.

Next, we’ll look at using Either in such a scenario.

6.3. Validation: a perfect use case for Either

Let’s revisit the scenario of requesting a money transfer, but in this case we’ll address the simpler scenario in which a client explicitly requests a transfer to be carried out on some future date.

The application should do the following:

We can model the fact that the operation may fail with Either. If the transfer request is successfully stored, there’s no meaningful data to return to the client, so the Right type parameter will be Unit. What should the Left type be?

6.3.1. Choosing a suitable representation for errors

Let’s look at a few types you could use to capture error details. You saw that when applying functions to Either via Map or Bind, the Right type changes, while the Left type remains the same. So once you choose a type for Left, this type will remain the same throughout the workflow.

I’ve used string in some of the previous examples, but this seems limiting; you might want to add more structured details about the errors. What about Exception? It’s a base class that can be extended with arbitrarily rich subtypes. Here, however, the semantics are wrong: Exception denotes that something exceptional has occurred. Instead, here we’re coding for errors that are “business as usual.”

Instead, I’ve included a very simple base Error class, exposing just a Message property. We can subclass this for specific errors.

Although, strictly speaking, the representation of Error is part of the domain, this is a general enough requirement that I’ve added the type to the functional library. My recommended approach is to create one subclass for each error type.

For example, here are some error types we’ll need in order to represent some cases of failed validation.

And, for convenience, we’ll add a static class, Errors, that contains factory functions for creating specific subclasses of Error:

This is a trick that will help us keep the code where the business decisions are made cleaner, as you’ll see below. It also provides good documentation, because it gives us an overview of all the specific errors defined for the domain.

6.3.2. Defining an Either-based API

Let’s assume that the details about the transfer request are captured in a data-transfer object of type BookTransfer: this is what we receive from the client, and it’s the input data for our workflow. We’ve also established that the workflow should return an Either<Error, Unit>; that is, nothing of note in case of success, or an Error with details of failure.

That means the main function we need to implement to represent this workflow has type

We’re now ready to introduce a skeleton of the implementation. Notice the preceding signature is captured in Handle:

The Handle method defines the high-level workflow: first validate, then persist. Both Validate and Save return an Either to acknowledge that the operation may fail. Also note that the signature of Validate is Either<Error, BookTransfer>. That is, we need the BookTransfer command on the right side, so that the transfer data is available and can be piped to Save.

Next, let’s add some validation.

6.3.3. Adding validation logic

Let’s start by validating a couple of simple conditions about the request:

We can have a function perform each validation. The typical scheme will be as follows:

That is, each validator function takes a request as input and returns either the (validated) request or the appropriate error. (I would normally use the ternary if operator here, but it doesn’t work well with implicit conversion.)

Each validation function is a world-crossing function (going from a “normal” value, BookTransfer, to an “elevated” value, Either<Error, BookTransfer>), so we can combine several of these functions using Bind.

In summary, use Either to acknowledge that an operation may fail and Bind to chain several operations that may fail. But if the application internally uses Either to represent outcomes, how should it represent outcomes to client applications that communicate with it over some protocol such as HTTP? This is a question that also applies to Option. Whenever you use these elevated types, you’ll need to define a translation when communicating with other applications. We’ll look at this next.

6.4. Representing outcomes to client applications

You’ve now seen quite a few use cases for using Option and Either. Both types can be seen as representing outcomes: in the case of Option, None can signify failure; in the case of Either, it’s Left. We’ve defined Option and Either as C# types, but in this section you’ll see how you can translate them to the outside world.

Although we’ve defined Match for both types, we’ve used it quite rarely, relying instead on Map, Bind, and Where to define workflows. Remember, the key difference here is that the latter work within the abstraction (you start with, say, Option<T>, and end up with an Option<R>). Match, on the other hand, allows you to leave the abstraction (you start with Option<T> and end up with an R). See figure 6.3.

As a general rule, once you’ve introduced an abstraction like Option, it’s best to stick with it as long as possible. What does “as long as possible” mean? Ideally, it means that you’ll leave the abstract world when you cross application boundaries.

It’s good practice to design applications with some separation between the application core, which contains services and domain logic, and an outer layer containing a set of adapters, through which your application interacts with the outside world. You can see your application as an orange, where the skin is composed of a layer of adapters, as shown in figure 6.4.

Abstractions such as Option and Either are useful within the application core, but they may not translate well to the message contract expected by the interacting applications. Thus, the outer layer is where you need to leave the abstraction and translate to the representation expected by your client applications.

6.4.1. Exposing an Option-like interface

Imagine that within our banking scenario we have an API that, given a “ticker” (an identifier for a stock or other financial instrument, such as AAPL, GOOG, or MSFT), returns details about the requested financial instrument. These details could include the market on which the instrument is traded, the current price level, and so on.

Within the application core, we could have a service that exposes this functionality:

We can’t know whether the string given as ticker actually identifies a valid instrument, so this is modeled within the application core with Option.

Next, let’s see how we can expose this data to the outer world. We’ll create an API endpoint by mapping it to a method on a class extending Controller. The controller effectively acts as an adapter between the application core and the clients consuming the API.

The API returns, let’s say, JSON over HTTP—a format and protocol that doesn’t deal in Options—so the controller is the last point where we can “translate” our Option into something that’s supported by that protocol. This is where we’ll use Match. We could implement the controller as in the following listing.

In fact, the preceding method body can be written more tersely:

(It could be written even more tersely, without the parameter names.)

Let’s pause and see why we can write this so concisely. Remember, Match expects the following:

Particularized for the current case, where T is InstrumentDetails and the desired result type is IActionResult, we need functions of these types:

Here we use two methods defined on the base Controller class:

Let’s look at the types of these methods:

The types line up because both HttpOkObjectResult and HttpNotFoundResult implement IActionResult, and naturally InstrumentDetails is an object.

You’ve now seen how you can take a workflow modeled with an Option-based interface and expose it through an HTTP API. Next, let’s see about an Either-based interface.

6.4.2. Exposing an Either-like interface

Just like with Option, once you’ve lifted your value to the elevated world of Either, it’s best to stay there until the end of the workflow. But all good things must come to an end, so at some point you’ll need to leave your application domain and expose a representation of your Either to the external world.

Let’s go back to the banking scenario we looked at in this chapter—that of a request from a client to book a transfer on a future date. Our service layer returns an Either<Error, Unit> and we must translate that to, say, JSON over HTTP.

One approach is similar to what we just looked at for Option: we can use HTTP status code 400 to signal that we received a bad request.

This works. The only downside is that the convention of how business validation relates to HTTP error codes is very shaky. Some people will argue that 400 signals a syntactically incorrect request—not a semantically incorrect request, as is the case here.

In situations of concurrency, a request that’s valid when the request is made may no longer be valid when the server receives it (for example, the account balance may have gone down). Does a 400 convey this?

Instead of trying to figure out which HTTP status code best suits a particular error scenario (after all, HTTP wasn’t designed with RESTful APIs in mind), another approach is to return a representation of the outcome in the response. We’ll explore this option next.

6.4.3. Returning a result DTO

This approach involves always returning a successful status code (because, at a low level, the response was correctly received and processed), along with an arbitrarily rich representation of the outcome in the response body.

This representation is just a simple data transfer object (DTO) that represents the full result, with its left and right components.

This ResultDto is very similar to Either. But unlike Either, whose internal values are only accessible via higher-order functions, the DTO exposes them for easy serialization and access on the client side.

We can then define a utility function that translates an Either to a ResultDto:

Now we can just expose the Result in our API method, as follows.

This approach means, overall, less code in your controllers. More importantly, it means you’re not relying on the idiosyncrasies of the HTTP protocol in your representation of results, but can instead create the structure that best suits you to represent whatever conditions you choose to see as Left.

In the end, both approaches are viable and both are used in APIs in the wild. Which approach you choose has more to do with API design than with functional programming. The point is that you’ll generally have to make some choices when exposing to client applications outcomes that you can model with Either in your application.

I’ve illustrated “lowering” values from abstractions through the example of an HTTP API, since this is such a common requirement, but the concepts don’t change if you expose another kind of endpoint. In summary, use Match if you’re in the skin of the orange; stay with the juicy abstractions within the core of the orange.

6.5. Variations on the Either theme

Either takes us a long way toward functional error handling. In contrast to exceptions, which cause the program to “jump” out of its normal execution flow and into an exception handling block in some arbitrary function up the stack, Either maintains the normal program execution flow and instead returns a representation of the outcome.

So there’s a lot to be liked about Either. There are also some possible objections:

In this section, I’ll address these concerns and see how they can be mitigated with some variations on the Either pattern.

6.5.1. Changing between different error representations

As you saw, Map and Bind allow you to change the R type, but not the L type. Although having a homogeneous representation for errors is preferable, it may not always be possible. What if you write a library where the L type is always Error, and someone else writes a library where it’s always string? How can you to integrate the two?

It turns out this can be resolved simply with an overload of Map that allows you to apply a function to the left value as well as the right one. This overload takes an Either<L, R>, and then not one but two functions: one of type (L → LL), which will be applied to the left value (if present), and another one of type (R → RR) to be applied to the right value:

This variation of Map allows you to arbitrarily change both types, so that you can interoperate between functions where the L types are different.^[5] Here’s an example:

⁵Because there’s no shortage of terminology in FP, functors for which a Map in this form is defined are called bifunctors, and in languages without method overloading, the function is called BiMap.

It’s best to avoid the noise and stick to a consistent representation for errors, but different representations aren’t a stumbling block.

6.5.2. Specialized versions of Either

Let’s look at the other shortcomings of using Either in C#.

First, having two generic arguments adds noise to the code.^[6] For example, imagine you want to capture multiple validation errors, and for this you choose IEnumerable <Error> as your Left type. You’d end up with signatures that look like this:

⁶You can look at this as a shortcoming of Either, or of C#’s type system. Either is successfully used in the ML-languages, where types can (nearly) always be inferred, so even complex generic types don’t add any noise to the code. This is a classic example showing that although the principles of FP are language-independent, they need to be adapted based on the strengths and weaknesses of each particular language.

You now have to read through three things (Either, IEnumerable, and Error) before you get to the most meaningful part, the desired return type Rates. Compared to signatures that say nothing about failure, as we discussed in chapter 3, it seems we’ve fallen into the opposite extreme.

Second, the very names Either, Left, and Right are too abstract. Software development is complex enough, so we should opt for the most intuitive names possible.

Both issues can be addressed by using more specialized versions of Either that have a fixed type to represent failure (hence, a single generic parameter), and more user-friendly names. Note that such variations on Either are common, but not standardized. You’ll find a multitude of different libraries and tutorials that each have their own minor variations in terminology and behavior.

For this reason, I thought it best to first give you a thorough understanding of Either, which is ubiquitous and well established in the literature and will allow you to grasp any variations you may encounter. (You can then choose the representation that serves you best, or even implement your own type for representing outcomes if you’re so inclined.)

LaYumba.Functional includes the following two variations for representing outcomes:

Table 6.2 shows these variations side by side.

These new types have friendlier, more intuitive names than Either, and you’ll see an example of using them next.

6.5.3. Refactoring to Validation and Exceptional

Let’s go back to the scenario of a user booking a money transfer for future execution. Previously we modeled the simple workflow that included validation and persistence—both of which could fail—with Either. Let’s now see how the implementation would change by using the more specific Validation and Exceptional instead.

A function that performs validation should, naturally, yield a Validation. In our scenario, its type would be

Because Validation is just like Either, particularized to the Error type, the implementation of the validation functions would be the same as in the previous Either-based implementation, except for the change in signature. Here’s an example:

As usual, implicit conversion is defined, so in this example you could omit the calls to Valid and Invalid.

Bridging between an exception-based API and functional error handling

Next, let’s look at persistence. Unlike validation, failure here would indicate a fault in the infrastructure or configuration, or another technical error. We consider such errors exceptional,^[7] so we can model this with Exceptional:

⁷In this context, exceptional doesn’t necessarily mean “occurring very rarely”; it denotes a technical error, as opposed to an error from the point of view of the business logic.

The implementation of Save could look something like the following.

Notice that the scope of the try/catch is as small as possible: we want to catch any exceptions that may be raised when connecting to the database, and immediately translate to the functional style, wrapping the result in an Exceptional. As usual, implicit conversion will create an appropriately initialized Exceptional.

Notice how this pattern allows us to go from a third-party exception-throwing API to a functional API, where errors are handled as payload and the possibility of errors is reflected in the return type.

Failed validation and technical errors should be handled differently

The nice thing about using Validation and Exceptional is that they have distinct semantic connotations:

We’ll now look at how using these different representations allows us to handle each case appropriately. We still need to combine validation and persistence; this is done in Handle here:

Because Validate returns a Validation, whereas Save returns an Exceptional, we can’t compose these types with Bind. But that’s OK: we can use Map instead, and end up with the return type Validation<Exceptional<Unit>>. This is a nested type expressing the fact that we’re combining the effect of validation (that is, we may get validation errors instead of the desired return value) with the effect of exception handling (that is, even after validation passes, we may get an exception instead of the return value).^[8]

⁸Remember, these are “monadic effects,” not “side effects,” but in FP-speak they’re simply called “effects.”

As a result, Handle is acknowledging that the operation may fail for business reasons as well as technical reasons by “stacking” the two monadic effects. Figure 6.5 illustrates how in both cases we express errors by including them as part of the payload.

To complete the end-to-end scenario, we need only add the entry point. This is where the controller receives a BookTransfer command from the client, invokes Handle as defined previously, and translates the resulting Validation<Exceptional<Unit>> into a result to send back to the client (see listing 6.13).

Here we use two nested calls to Match to first unwrap the value inside the Validation, and then the value inside the Exceptional:

As you can see, an explicit return type from each of the functions involved allows you to clearly distinguish and customize how you treat failures related to business rules versus those related to technical issues.

In summary, Either gives you an explicit, functional way to handle errors without introducing side effects (unlike throwing/catching exceptions). But as our relatively simple banking scenario illustrates, using specialized versions of Either, such as Validation and Exceptional, leads to an even more expressive and readable implementation.

6.5.4. Leaving exceptions behind?

In this chapter you’ve gained a solid understanding of the ideas behind functional error handling.^[9] You may feel this is a radical departure from the exception-based approach, and indeed it is.

⁹We’ll revisit error handling in part 3, in the context of laziness and asynchrony, but the fundamental aspects have all been covered in this chapter.

I mentioned that throwing exceptions disrupts the normal program flow, introducing side effects. More pragmatically, it makes your code more difficult to maintain and reason about: if a function throws an exception, the only way to analyze the implications of this for the application is to follow all possible code paths into the function, and then look for the first exception handler up the stack. With functional error handling, errors are just part of the return type of the function, so you can still reason about the function in isolation.

Having realized the detrimental effects of using exceptions, several younger programming languages such as Go, Elixir, and Elm have embraced the idea that errors should simply be treated as values, so that equivalents to the throw and try/catch statements are used only very rarely (Elixir), or are absent from the language altogether (Go, Elm). The fact that C# includes exceptions doesn’t mean you need to use them for error handling; instead, you can use functional error handling within your application, and use adapter functions to convert the outcomes of calls to exception-based APIs to something like Exceptional, as shown previously.

Are there any cases in which exceptions are still useful? I believe so:

Exercises

Summary