Some<T>(T) -> Option<T>

To lift a value into the world of Option<T> the main functions we use are all called Some.

The following snippets all do the same thing, which is wrap a value in Some<T> (you should be able to run this code in C# interactive):

int number = 42;

// use a pure function to return a value as an Option<T>
Option<int> option = F.OptionF.Some(number);

// use the same function, but in my preferred style
using static F.OptionF;
Option<int> option = Some(value);

// use implicit operator - which calls F.OptionF.Some
Option<int> option = number;

// use an extension method - which calls F.OptionF.Some
Option<int> option = number.Some();

In each case the variable option is of type Option<int>, but specifically Some<int>, which means you can do the following:

if (option is Some<int> number)
{
    Console.Write("The answer to the question is '{0}'.", number.Value);
}

// The answer to the question is '42'.

This is nice and simple, but what if your value comes from another function? Wouldn't it be nice if you could pass a Func<T> instead of a T, and wouldn't it be nice if it caught any exceptions for you, so don't have to wrap it in a try..catch block?

Yes, it would.

But first, we need to explore how we return None<T>

None<T>(IMsg) -> Option<T>

Where Some<T> wraps a value, None<T> is a null-safe way of representing no value, with a helpful reason why there is no value: some input was invalid, an exception occurred, and so on. Note that we _always_** need to give a reason for a None<T>** - another key principle in the world of Option<T>.

Let's dive right in!

var none = Divide(42, 0);
if (none is None<int> failed)
{
    Console.WriteLine("Something went wrong: {0}.", failed.Reason);
}

var some = Divide(42, 6);
if (some is Some<int> succeeded)
{
    Console.WriteLine("The result is: {0}.", succeeded.Value);
}

// Something went wrong: YouCannotDivideByZeroMsg { }.
// The result is: 7.

Option<int> Divide(int x, int y)
{
    if (y == 0)
    {
        return None<int>(new Msg.YouCannotDivideByZeroMsg());
    }

    return x / y;
}

public static class Msg
{
    public sealed record class YouCannotDivideByZeroMsg : IMsg { }
}

My pattern is for each class I write to have a Msg static class, which contains all the messages relating to that class. My practice is to implement my messages as record types - you don't have to do that, unless you want to use the built-in message types from the Jeebs NuGet package.

(If your message has a public parameterless constructor you can use the function None<T, IMsg>() -> Option<T> to create your None<T>.)

Jeebs.Option comes with two message interfaces: IMsg (which has no properties or methods) and IExceptionMsg (which has one property: the exception). We'll explore exception handling in the next section - but another way of writing the code block above would be like this:

var none = Divide(42, 0);
if (none is None<int> failed)
{
    Console.WriteLine("Something went wrong: {0}.", failed.Reason);
}

var some = Divide(42, 6);
if (some is Some<int> succeeded)
{
    Console.WriteLine("The result is: {0}.", succeeded.Value);
}

// Something went wrong: DivisionExceptionMsg { Exception = ... }.
// The result is: 7.

Option<int> Divide(int x, int y)
{
    try
    {
        return x / y;
    }
    catch (Exception e)
    {
        return None<int>(new Msg.DivisionExceptionMsg(e));
    }
}

public static class Msg
{
    public sealed record class DivisionExceptionMsg(Exception Exception) : IExceptionMsg { }
}

Now we've seen IExceptionMsg we can turn to the other Return function, which takes a Func<T> instead of a T.

Some<T>(Func<T>, Handler) -> Option<T>

A key principle of Option<T> is that we always handle our exceptions. Therefore whenever we try to 'lift' a function instead of a value into the world of Option<T>, we need to catch things that go wrong.

This is where the delegate F.OptionF.Handler comes in, well, handy. Here is the definition of Handler:

public delegate IExceptionMsg Handler(Exception e);

It takes an Exception and returns an IExceptionMsg. The handler is used by Return<T>(Func<T>, Handler), which creates a None<T> and adds the reason message created by the handler.

So, this snippet does exactly what the Divide(int, int) -> Option<int> function did in the previous example, but without the try..catch block:

int number = 42;
Option<int> option = Some(
    () => number / 0,
    e => new Msg.DivisionExceptionMsg(e)
);

if (option is None<int> failed)
{
    Console.Write("Failed with {0}.", failed.Reason);
}

// Failed with Msg.DivisionExceptionMsg { Exception = ... }.

public static class Msg
{
    public sealed record class DivisionExceptionMsg(Exception Exception) : IExceptionMsg { }
}

Messages

Messages are a simple but incredibly powerful way of describing everything that can go wrong in your system. You could have your own namespace for them all, but I prefer to define the messages right next to the class that uses them.

To realise the true power of Messages, you need to be disciplined about never reusing them (or only rarely - I reuse mine only when I have two versions of the same function, for example sync / async).

This means:

• when you log a None<T> with its Reason, you know exactly where the problem occurred

• if you want to provide user feedback and translations, you can have specific error messages based on where the problem occurred

The messages we've used so far have been pretty simple, but here is an example of one from Jeebs.Data.Mapping:

public sealed record class UpdateErrorMsg<T>(string Method, long Id)
    : LogMsg(LogLevel.Warning, "{Method} {Id}")
{
    public override Func<object[]> Args =>
        () => new object[] { Method, Id };
}

This message captures various important pieces of information:

• the type T is the type of the entity being updated

• Method is the name of the update method

• Id is the ID of the entity being updated

UpdateErrorMsg<T> extends the LogMsg abstract record from the Jeebs package to set the log level, and provide a custom log message using the update values. Then in the Update() function I can do something like this:

return rowsAffected switch
{
    1 =>
        True,

    _ =>
        None<bool>(new Msg.UpdateErrorMsg<T>(nameof(UpdateAsync), entity.Id))
}

True and False

In that last code snippet you may have True. That isn't a typo - there are two properties of F.OptionF:

• F.OptionF.True which returns Some<bool> with Value true

• F.OptionF.False which returns Some<bool> with Value false

They are identical to writing Some(true) or Some(false) - but I like the shorthands.

They exist because you don't want to return a None<bool> when something fails - you want to return a Some<bool> with a false value, so you can continue processing. This is what F.OptionF.False is for (or simply False if you have using static F.OptionF).

The world of Option<T>

What if you could get away from huge classes with monster methods? What if you didn't have to worry about handling null values?

What if you could wrap values in a consistent way, have helpful feedback when something goes wrong, and chain small reusable testable reliable functions to provide stable functionality?

You can: in the world of Option<T>!

What can it do?

To whet your appetite for what using Option<T> enables you to write, check out the following snippets - you'll notice that Option<T> supports mixing sync and async functions.

The first is from my website's BlogController. Each of the GetXXX(query) methods returns Option<T>, which are joined together via a Linq SelectMany, and used to build the model for the List view.

Or this, which builds a SQL query, executes it, and then processes the results:

In both situations there cannot be an unhandled exception, there cannot be any null values, and if something does go wrong an object with a helpful error message is return.

Key principles

In the world of Option<T> the following key principles are followed:

1. the return type is always Option<T> (rather than Some<T> or None<T>)

2. if a function returns Option<T> it means all exceptions have been handled

3. when returning None<T> we must give a reason

4. everything that can go wrong in your system has an IMsg which describes it

5. once in the async world, we must stay in the async world

Why?

F# contains a built-in Option type, and I wanted to be able to code in that style but using C#. Over a year or so I have designed Option<T> to mimic some of F#'s behaviour using C# way. It works best when you chain pure (and small) functions together - and if you use it well your exception handler will have very little to do!

Concepts

The following serves as an introduction to the concepts behind Option<T> which are likely to be a little alien to most C# developers. However, if you want to skip ahead straight to the code, feel free!

Namespaces

Option<T> and all its extension methods live in the Jeebs namespace (and some useful features in Jeebs.Linq). However the actual 'pure' functions live in F.OptionF - I put all my functional-style code in the F namespace, and add an F suffix to the class type. My preferred style is then to add using static F.OptionF so the functions can be accessed directly.

Pure functions

'Pure' functions have no effect outside themselves. In other words, they receive an input, act on it, and return an output. They don't affect state, and they don't affect the input object.

In the OO world of C#, I'll admit, this is odd. There's not really any such thing as a 'function' - at least not one that exists outside a class definition. However as far as I can, Option<T> is written as a series of pure functions, so even the methods in the Option<T> class and the extension methods are simply wrappers for the functions, which all live in the F.OptionF namespace.

Some<T> and None<T>

Option<T> is an abstract class with two implementations. The return type for a function is always Option<T>, but the actual object will be one of these:

• Some<T> which contains a Value property of type T

• None<T> which contains a Reason property of type IMsg?

Think of None<T> as a more useful nullable, because it comes with a reason why it has no value.

No More Exceptions

Within the Jeebs library - and I encourage you to follow the same discipline if you decide to you Option<T>, the contract is that if a function returns Option<T> it has handled all its exceptions so you don't have to.

This is a critical part of the usefulness of Option<T>, and to be honest if you prefer having and handling exceptions I suggest you stop reading! However, I do believe there is a better way...

To enter the world we need to 'lift' values into it so we can benefit from all its features.

Function signatures

As Option<T> is a mix of OO and functional programming styles I will be using the following notation across the documentation: function signature -> return type, for example AddTwoNumbers(int, int) -> int. This is partly for brevity, and partly because it is similar to how function signatures are written in F#, which will become useful as the functions get more complex.

LINQPad settings

All the code snippets are tested in LINQPad (v6.12, with .NET 5 support). If you want to try them out for yourself:

1. Add Jeebs.Option NuGet package (Ctrl+Shift+P)

2. Add the following namespaces to the query (Ctrl+Shift+M):

What's the difference?

Like Map, the Bind functions receive the value of the input Option<T> if it's a Some<T>, and are bypassed if it's a None<T>.

However, there are two important differences:

1. Bind functions return an Option<T> (Map functions return T which is wrapped by Some).

2. Therefore they are expected to handle their own exceptions - one of our key principles is the contract that if a function returns Option<T> its exceptions have been handled. (The method signature therefore does not have a Handler in it.)

That said, you can be naughty because your binding function is still wrapped in a try..catch block. However all exceptions caught in that block will return None<T> with a Msg.UnhandledExceptionMsg as the Reason.

Bind<U>(Func<T, Option<U>>) -> Option<U>

Bind does a switch and behaves like this:

• if the input Option<T> is None<T>, return None<U> with the original Reason

• if the input Option<T> is Some<T>...

  • get the Value T

  • use that as the input and execute Func<T, Option<U>>, then return the result

  • catch any unhandled exceptions using DefaultHandler

See it in action here:

Bind comes into its own in more complex scenarios, for example data access:

If db.GetCustomer() fails, the next two operations are skipped, AuditSwitch is run with the none option, and a None<OrderPlacedModel> is returned with the reason from db.GetCustomer().

You can of course also return Tuples instead of single values, and C# is clever enough to give Tuples automatic names now as well:

Adding it all together

In the next section we will actually make a simple test app with everything you need to play around with Map and Bind. Before then here is an example of what this can look like in practice:

Here we have two potentially problem-ridden methods - returning a complex SQL query from a given input and executing a database query - that are now pure functions: notice they are declared static. This is best practice, think of it like Dependency Injection but functional. The functions require no state, and interact with nothing else, so given the same input they will always return the same output.

This means they can be tested easily, and once they work correctly they will always work in the same way so you can rely on them.

You will also notice the use of the -Async variations of Map and Bind - we will come to these later, but for now note that although x.ToList() is not doing anything asynchronously, because the input is a Task<Option<T>> we must use the -Async variant. This leads to another of our key principles: once we are in the async world we stay in the async world.

Functional or fluent?

Once we have used Some<T>(T) -> Option<T> to lift a value into the world of Option<T>, we need to do something with it by chaining our functions together. The Option<T> class comes with a load of methods which are actually wrappers for the functions that do the work.

So, although you can use the functions directly, you'll find it much more convenient to write chains using the common C# fluent syntax. These two are functionally identical:

In that snippet, functional and fluent are both Some<string> with Value "42".

From now on, I will give function signatures as their equivalent method on Option<T> because that should help keep things a little clearer, and it's what you will actually use.

Map<U>(Func<T, U>, Handler) -> Option<U>

Map does a switch and behaves like this:

• if the input Option<T> is None<T>, return None<U> with the original Reason

• if the input Option<T> is Some<T>...

  • get the Value T

  • use that as the input and execute Func<T, U>, then wrap the result in Some<U>

  • catch any exceptions using Handler

See it in action here:

If you are using LINQPad to to you change the second Map in that sample so you have x / 0 instead of x / 2 and re-run the snippet, you will see that you still end up with an Option<string>, only this time it's None<string> with a DivisionFailedMsg as the Reason.

There are two additional things to note here:

1. DefaultHandler is available for you to use, but you should use it sparingly, and not rely on it, unless you really don't care about having helpful messages.

2. AuditSwitch(Action<T> some, Action<IMsg> none) is useful for logging - the 'some' action receives the current Value (if the input is Some<T>) and the 'none' action receives the current Reason (if the input is None<T>).