DEV Community: Matt Thornton

Typesafe F# configuration binding

Matt Thornton — Sun, 28 Nov 2021 09:34:51 +0000

At Symbolica we're building a symbolic execution service that explores every reachable state of a user's program and verifies assertions at each of these states to check that the program is correct. By default it will check for common undefined behaviours, such as out-of-bounds memory reads or divide by zero, but it can also be used with custom, application specific, assertions too just like the kind you'd write in a unit test. Seen from this perspective it's kind of like FsCheck (or Haskell's QuickCheck or Python's Hypothesis), but much more exhaustive and without the randomness.

As much as we like finding bugs with Symbolica, we prefer to not write any in the first place. Our first line of defence is a strong type system, so that we can try to design types that make invalid states impossible and let the compiler tell us off when we make a mistake. For that reason we've opted to build our service using F# as it also interops nicely with the core part of our symbolic executor which is written in C#.

One of the many things we love about F# is that, by default, it doesn't permit null as a regular value. This feature eliminates a whole class of errors caused by null values, most notably the cursed NullReferenceException. Another feature that we like is having access to the vast wealth of .NET libraries that exist. However, many of these are written in C# and so they are often places where null values can sneak into an F# program through the backdoor at runtime.

One area where this was frequently biting us was the binding of configuration data using the Microsoft.Extensions.Configuration library. Due to this and other problems that we'll go into below, we created a safer alternative for configuration binding for F# projects called Symbolica.Extensions.Configuration.FSharp and open-sourced it on GitHub.

Symbolica / Symbolica.Extensions.Configuration.FSharp

Provides a safe API for binding the dotnet IConfiguration to types in F#.

Symbolica.Extensions.Configuration.FSharp

Provides a safe API for binding an F# type from the dotnet IConfiguration interface. It is an F#-friendly alternative to using the reflection-based ConfigurationBinder.Bind.

Motivation

Out-of-the-box dotnet provides what it calls the "the Options pattern" which it describes as:

The options pattern uses classes to provide strongly typed access to groups of related settings.

Whilst this might be "strongly typed" in the sense that you're interacting with statically typed options objects, the binding mechanism is not strictly safe and so the static types are often a lie. This leads to a few notable problems, especially when working with it from F#.

It's a large source of NullReferenceExceptions because the binder will hapily set a value to null if it's missing in the underlying config. This means your F# type is probably lying to you about the fact its value cannot be null. F# developers would rather model…

View on GitHub

The problems with `Microsoft.Extensions.Configuration.Binder`

The best way to highlight the shortcomings of the defacto config binder is with an example. Let's say we want to model some logging options in our code. We might start out with a simple record type like this to represent the options.

type LoggingOptions = 
    { Level: string
      Sink: string }

Where Level represents how verbose we want the logging output to be, e.g. "Debug" or "Error" etc and Sink is where we want to send the logs, for example it might be "Console" or "File".

Let's test this out with a little fsx script that we can run with FSI.

#r "nuget: Microsoft.Extensions.Configuration.Binder"

open Microsoft.Extensions.Configuration

type LoggingOptions = { Level: string; Sink: string }

let config =
    ConfigurationBuilder()
        .AddInMemoryCollection(
            [ "Logging:Level", "Debug"
              "Logging:Sink", "Console" ]
            |> Map.ofList
        )
        .Build()

config.GetSection("Logging").Get<LoggingOptions>()

Here we're just seeding the in memory configuration provider with a dictionary of config data and then attempting to retrieve and bind the LoggingOptions.

Problem 1: Mutable data and `null` values

If we run the above script you might be expecting it to print out a LoggingOptions with a Level of "Debug" and a Sink of "Console". However, we actually hit a different problem. The above script throws the following exception.

System.InvalidOperationException: Cannot create instance of type 'FSI_0008+LoggingOptions' because it is missing a public parameterless constructor.

That's because an F# record doesn't contain a parameterless constructor, because all of the record’s properties must be properly initialised and null isn't an allowed value. To make matters worse, the defacto binder mandates that the properties of the type being bound must be settable too, breaking immutability and making the use of a record to model options kind of pointless.

There are two typical workarounds to this:

Define a mutable class instead of a record for the options type, like we would in C#.
Add the [<CLIMutable>] attribute to the LoggingOptions record.

Neither of these are particularly pleasing. The first one means we have to give up on having immutable options types and the rest of the code base has to deal with the added complexity of potential mutability. The second is basically a hack which provides a mutable backdoor at runtime to our immutable type.

Using [<CLIMutable>] actually opens up a can of worms because our types are now deceiving us. Our simple record purports to be immutable and never contain null values and so in the rest of the code base we program as if this is the case. On the other hand the config binder isn’t abiding by these compile time invariants and may in fact initialise the record’s properties as null at runtime.

To see this in action, let's rerun the above example, but this time with the [<CLIMutable>] attribute added to the LoggingOptions and a missing value for the Level In the raw config. The modified script looks like this.

#r "nuget: Microsoft.Extensions.Configuration.Binder"

open Microsoft.Extensions.Configuration

[<CLIMutable>]
type LoggingOptions = { Level: string; Sink: string }

let config =
    ConfigurationBuilder()
        .AddInMemoryCollection([ "Logging:Sink", "Console" ] |> Map.ofList)
        .Build()

config.GetSection("Logging").Get<LoggingOptions>()

Running it produces this output.

val it: LoggingOptions = { Level = null
                           Sink = "Console" }

We see that the type system has lied to us because the value of Level was actually null at runtime. In this case it's relatively harmless, but in a real application it's likely that we'll have a more complex hierarchy of option types and so we'd end up trying to dereference a potentially null object leading to the dreaded NullReferenceException.

When working in F# we'd rather the config binder returned a Result if the config couldn't be parsed and allow us to use an Option type for config data that is, well, optional. Which leads us to the next problem.

Problem 2: No native support for binding DUs

As the defacto binder uses reflection to bind the raw config to "strongly typed objects", it only has support for a limited set of types. This includes all the primitive types, like int and string and a few of the common BCL collection types like List and Dictionary. This is frustrating for both C# and F# developers that wish to use more complex types to model their options.

Particularly frustrating for F# developers though is that this means it doesn't support discriminated unions (DUs) and therefore doesn't support types like Option. To highlight this let's imagine we wanted to improve our LoggingOptions so that the Level was restricted to a discrete set of values. To do this we'll create a DU called LoggingLevel and use it as the type for the Level property.

#r "nuget: Microsoft.Extensions.Configuration.Binder"

open Microsoft.Extensions.Configuration

[<RequireQualifiedAccess>]
type LogLevel =
    | Debug
    | Info
    | Warning
    | Error

[<CLIMutable>]
type LoggingOptions = { Level: LogLevel; Sink: string }

let config =
    ConfigurationBuilder()
        .AddInMemoryCollection(
            [ "Logging:Level", "Debug"
              "Logging:Sink", "Console" ]
            |> Map.ofList
        )
        .Build()

config.GetSection("Logging").Get<LoggingOptions>()

We're now supplying a config dictionary that looks correct, it has properties for both of "Logging:Level" and "Logging:Sink", so let's run it and see what the output is.

val it: LoggingOptions = { Level = null
                           Sink = "Console" }

So we can see here that the binder has silently failed to bind the Level property now that its type is LoggingLevel.

If we want to bind more complex type, we'll first have to bind to a simple type, like a string, and then write a parser ourselves to turn that into a LoggingLevel. That’s a slippery slope because it then probably means having something like a ParsedLoggingConfig which we create from the more loosely typed LoggingConfig. Resulting in us needing to define a fair amount of config parsing “boilerplate” anyway.

Problem 3: Parse, don't validate

The defacto binder doesn't really give us much help when our configuration is faulty. We can write some options validators and wire these up with DI, but as Alexis King has taught us - parse, don't validate.

In short, "parse, don't validate" tells us that it's better to parse data into a type, that once constructed must be valid, than it is to read the data into a more loosely typed object and then run some post-validation actions over the values to make sure they're correct. The primary reason being that if we know that our type only permits valid values, then we no longer have to wonder whether or not it's already been validated.

The defacto configuration binder doesn't make it easy to adhere to this. It's easy to forget to register a validator for the options and then when they're accessed at runtime we instead get a rather unhelpful null value, like we observed earlier. What we'd prefer is for the compiler to prevent us from making such a mistake, by enforcing validation through the type system.

To give a specific example, let's imagine we want to be able to restrict the logging level to only have the values, "Info", "Debug", "Warning" and "Error". We've already seen we can't use a DU to model this. So we have no way of knowing whether or not Level is valid when we come to use it, all we know is that it's a string. So if we want to be sure, we're forced to keep validating the logging level at every point of use.

A better binder for F#

Given these shortcomings we decided to write our own config binder with the following design goals in mind:

Binding failures should be expected and be reflected in the type returned from the binder. We should be made to deal with the unhappy path.
Binding should not break immutability.
Binding should work for all types including complex user defined types.
Binding should be composable, such that if I can bind a type X which is then later used within Y, I should be able to reuse the binder for X when defining the binder for Y.
Error reporting should be greedy and descriptive so that developers can quickly fix as many errors as possible when binding fails.

To that end we opted to write a binder that didn't use any reflection. The trade-off we're making here is that we're forced to be much more explicit when we bind a type and so we end up with what some people might consider to be boilerplate. However, we'd personally rather have code that is explicit than have to read through documentation to discover the implicit behaviours of something magic, because when the magic thing breaks we usually spend more time debugging that than we would have spent writing the explicit "boilerplate" to begin with.

Also, thanks to the composable nature of functional programming languages and the power of F#'s computation expressions it's possible to be both explicit and terse. It's probably best appreciated with an example. So let's see how we'd bind the above LoggingOptions using our new approach.

#r "nuget: Symbolica.Extensions.Configuration.FSharp"

open Microsoft.Extensions.Configuration
open Symbolica.Extensions.Configuration.FSharp

[<RequireQualifiedAccess>]
type LogLevel =
    | Debug
    | Info
    | Warning
    | Error

module LogLevel =
    let bind =
        Binder(
            fun (s: string) -> s.ToLowerInvariant()
            >> (function
            | "info" -> Success LogLevel.Info
            | "debug" -> Success LogLevel.Debug
            | "warning" -> Success LogLevel.Warning
            | "error" -> Success LogLevel.Error
            | _ -> Failure ValueError.invalidType<LogLevel>)
        )

type LoggingOptions = { Level: LogLevel; Sink: string }

let bindConfig =
    Bind.section
        "Logging"
        (bind {
            let! level = Bind.valueAt "Level" LogLevel.bind
            and! sink = Bind.valueAt "Sink" Bind.string
            return { Level = level; Sink = sink }
         })

let config =
    ConfigurationBuilder()
        .AddInMemoryCollection(
            [ "Logging:Level", "Debug"
              "Logging:Sink", "Console" ]
            |> Map.ofList
        )
        .Build()

bindConfig
|> Binder.eval config
|> BindResult.mapFailure(fun e -> e.ToString())

Running this script produces the following output.

val it: BindResult<LoggingOptions,string> = 
    Success { Level = Debug
              Sink = "Console" }

From this example we can see that it's successfully bound our more complex LoggingOptions type that contains a DU. There's also zero magic, the binding process is clear to see and simple to customise. Let's check that it's met our design goals.

Failures are expected - We can see this by the fact that right at the end, after we've called eval on the Binder, it's produced a BindResult.
Binding doesn't break immutability - No [<CLIMutable>] required here.
Binding works for complex types - Binding a DU was no problem. We were also able to make it case insensitive just through a little function composition with ToLowerInvariant.
Binding is composable - We defined the binder for the LogLevel in isolation to the overall config binder.
Error reporting is greedy and informative - Let's simulate some failures and see what happens.

Let's run the script again but this time with the following input config.

[ "Logging:Level", "Critical" ]

So that the Level is invalid and the Sink is missing. We get the following output.

Failure(
  “@'Logging':
    all of these:
      @'Level':
        Value: 'Critical'
        Error:
          Could not parse value as type 'LogLevel'.
      @'Sink':
        The key was not found.”)

It's shown us all of the paths in the config for which it found errors and what those errors are.

The Implementation Details

At the heart of all of this is a Binder<'config, 'value, 'error> type. This type is just a wrapper around a function of the form 'config -> BindResult<'a,'error>. For the category theory inclined, it's just a reader monad whose return type has been specialised to a BindResult.

The BindResult type is very similar to a regular F# Result except that its applicative instance will accumulate errors, whereas the regular Result will typically short-circuit on the first error it encounters.

Binder and BindResult are defined generically to keep them as flexible as possible. However at some point we want to provide some specialisations for the common binding scenarios. There are really two primary specialisations to consider; one for binding sections and another for binding values.

Section binders are of the form Binder<#IConfiguration, 'a, Error> and value binders are of the form Binder<string, 'a, ValueError>. By fixing 'error to the custom types Error and ValueError it's easy to compose Binders and also ensure that the errors can be properly accumulated in both applicative and alternative computations.

One of the primary specialisations comes from the bind applicative computation expression. We saw in the example above how bind lets us compose a Binder for an IConfigurationSection by binding its properties using existing Binders and at the same time ensures all binding errors from this section are accumulated. The bind CE gives us a declarative looking DSL for defining new binders for our application specific config objects.

In the Bind module the library also provides various combinators for building new Binders. Such as Bind.section and Bind.valueAt which take an existing Binder and bind them to a section or a value at a particular key, which are typically used inside a bind CE. It also contains many binders for types like int, bool System.DateTime and System.Uri as well as more complex structures like List and IDictionary.

Try it out

The code is available on GitHub and you can install the library via NuGet. If you want to see even more sophisticated examples that shows how to do things like handle optional values, deal with alternatives and bind units of measure then check out the IntegrationTests. Of course if there's something that you think is missing then open an issue or a pull request. I'm sure there are plenty of other Binders that we can add to the Bind module to cover other common .NET types.

Future Improvements

If you want to use things like IOptionsSnapshot then it requires interaction with the IServiceCollection and a call to Configure<MyOptionsType>(configureAction). Unfortunately the way that Microsoft have designed this means that a parameterless public constructor is required on the options type being configured so that an instance can be passed to configureAction, which goes against our design principles here. So currently this library won't play nicely with things like reactive options updates. If this is something that you'd like then it should be possible to provide a way around this by providing an alternative IOptionsFactory, so please open an issue and let us know. See the README for more details.

Symbolica's Console Newsletter Interview

Matt Thornton — Tue, 26 Oct 2021 17:03:27 +0000

At Symbolica we’re building a cloud-hosted symbolic execution service. Symbolic execution lets you explore every reachable state of your program so that you can write tests without worrying about missing any edge cases. As a bonus we also automatically detect if any states can cause invalid memory access and other undefined behaviours, like divide by zero, without you having to write any additional tests.

The core of our symbolic executor is open source and this week we got to chat with Jackson Kelley for the latest edition of the Console newsletter about our project. We talk about our backgrounds and influences and get into the details of some of the technical challenges that we’ve been tackling as we continue to build Symbolica.

Symbolica / Symbolica

Symbolica's open-source symbolic execution engine.

Symbolica

NuGet Packages

Symbolica.Abstraction

Symbolica.Collection

Symbolica.Computation

Symbolica.Deserialization

Symbolica.Expression

Symbolica.Implementation

Symbolica.Representation

Docker Images

symbolica/build

docker build lib/build -t symbolica/build:latest

docker run -v <path-to-user-code>:/code symbolica/build:latest

symbolica/translate

docker build lib/translate -t symbolica/translate:latest

docker run -v <path-to-user-code>:/code symbolica/translate:latest <declarations>

Note, we don't publish a latest tag because we prefer to use SemVer instead, even if Docker doesn't natively support it. Our stable images will be tagged according to the tags in this repository and the versions are aligned with the NuGet package versions. If you're using the docker images in conjunction with the NuGet packages, it's best to make sure you're using a tag for the docker images that matches the NuGet package version you're using.

View on GitHub

Each edition of Console is a curated list of interesting open source projects along with an interview of the creators of one of the projects, delivered to your inbox every week. It’s a great way to discover new open source projects and hear from the creators behind the code. If you like open source it’s worth signing up.

Azure Functions with F# using .NET 5

Matt Thornton — Thu, 12 Aug 2021 11:12:12 +0000

Serverless computing promises to make it "easier" to just write some code, sling it at the cloud and voila, you're done. No more worrying about how your code is hosted, configuring application servers or writing hundreds of lines of "boilerplate" to get something running. The reality, however, is a little different, as we found out when trying to write an Azure function that targets the .NET 5 runtime.

The reason it failed to live up to this promise is that at this point in time the default Azure functions host supports .NET Core 3. So in order to target .NET 5 we have to get our hands dirty and write some boilerplate. Unfortunately, the documentation on how to do this and the project templates for .NET 5 Azure functions don't seem to cover all of the "quirks" that are necessary to make it work.

In this post I'm going to walk through the steps required to get a .NET 5 Azure function running both locally and in Azure and highlight the gotchas that tripped us up when trying to do this. The function itself will be written in F#, but all of the quirks are related to using a .NET 5 runtime and so would equally apply to a C# project. In fact, switching between the two languages is an extremely minimal code change.

The final version of the code shown in this blog post can be found on GitHub.

"In-process" vs "Out-of-process" hosting

First off, what's a host? In Azure functions the host is the term used to refer to the process that your function will be executed in. It includes a runtime, e.g. dotnet or Python, and all of the external libraries, e.g. DLLs or Python modules, that your code needs to be able to run.

By default Azure functions uses what it calls an "in-process" hosting model. In practice this means that when you deploy your code as a library, or a script, it runs it in a process with a pre-configured host.

The upside to this model is that you don't have to worry about infrastructure concerns. You just write your core logic and ship it. This supposedly frees developers from the burden of configuring a host in the entry point to their application, saving them time.

The downside is that if you don't like what's included in the box then your options for altering that are limited to whatever is exposed via the switches and dials they provide. Unfortunately there’s no .NET 5 switch available. This is where the "out-of-process" host comes in.

With out-of-process hosting you get explicit control over how the host is created allowing you to choose a dotnet runtime. When you ship an Azure function using this hosting model you're responsible for configuring the host and making sure it boots correctly. With that background out the way, let's get stuck into the code.

Create a new project

We're going to need an F# project to work with. It will be edited quite heavily, so the easiest way to create one is to just create a console app by running the following command from the root of your project directory.

dotnet new console -lang f# -n Function -o src/Function

Note, we've put the project under a src directory as is quite typical for dotnet projects, you don't have to follow this convention, but the rest of the steps will assume this project layout.

Configure the `.fsproj` file

The first step is to ensure the project file (.fsproj) is configured correctly. A minimal example looks like this.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
    <_FunctionsSkipCleanOutput>True</_FunctionsSkipCleanOutput>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.4.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Timer" Version="4.1.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.0.4" />
  </ItemGroup>
  <ItemGroup>
    <Compile Include="Execute.fs" />
    <Compile Include="Program.fs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Include="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

You can just go ahead and replace the contents of the generated Function.fsproj file with the above.

There are a few things to point out that are required to make this work which weren't documented or included in the official code templates.

The _FunctionsSkipCleanOutput must be set to True.
The directives for the host.json and local.settings.json must use <None Include=>. The functions templates generate these with <None Update=> which doesn't work.
The templates also don't include the correct package references. At a minimum we need the ones listed above, at their latest versions, in order to run on .NET 5.

Note this example is using Microsoft.Azure.Functions.Worker.Extensions.Timer because this basic example just uses a simple timer trigger, you might need a different extension package if you're using a different trigger, e.g. Blob triggers require Microsoft.Azure.Functions.Worker.Extensions.Storage.

Configure `host.json`

We need to add a host.json file to the project with the following contents.

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "samplingExcludedTypes": "Request"
      }
    }
  }
}

There aren't any quirks here, so just add that and move on.

Add a `local.settings.json`

We also need a local.settings.json file in the project which should look like this.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
  }
}

The crucial bit here is that we've set FUNCTIONS_WORKER_RUNTIME to "dotnet-isolated". This is how we specify that we want to use an out-of-process host.

Configure the host in `Program.fs`

Because we've opted to go out-of-process we need to write the host bootstrapping code in Program.fs.

open Microsoft.Extensions.Hosting

HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .Build()
    .Run()

As you can see, the boilerplate is actually very minimal for this simple function. Also, the nice thing about using the dotnet-isolated runtime and explicitly defining how the host is bootstrapped is that if the application grows and requires interaction with more azure services, such as blob storage or message queues, then we get complete control over how those services are configured. We're also able to specify exactly which NuGet packages, at which versions, are included in the runtime too. In my experience this leads to much fewer surprises and less time spent opaquely debugging in Azure, as compared to using an in-process host in which issues such as assembly conflicts occur at runtime. Give me that sweet, sweet, boilerplate every time.

Add your functions

We can now go ahead and write our functions. Our project is configured to expect a file called Execute.fs, which is where we're going to place them. There's nothing special about that file name, so feel free to call it whatever you want, or arrange your functions in multiple files if that suits your needs better.

Here's what our simple example timer function looks like in F#.

namespace My.Function

open Microsoft.Azure.Functions.Worker
open Microsoft.Extensions.Logging

type Execute(logger: ILogger<Execute>) =
    [<Function("Execute")>]
    member _.Run([<TimerTrigger("0 */5 * * * *")>] timer: TimerInfo) =
        logger.LogInformation($"Hello at {System.DateTime.UtcNow} from an Azure function using F# on .NET 5.")

Somewhat annoyingly, we have to add the TimerTrigger attribute to a method parameter, rather than being able to specify it at the method level. So even if we don't want to use the TimerInfo, we need to accept it as an argument.

Also, ironically, we have to create a class to write a "function" 😜

Building the code

This one should be fairly straight forward, but there's a gotcha here too. In order to build an Azure function running on .NET 5 you'll need the .NET Core 3.1 SDK installed. There's more information in this GitHub issue. Once you've got that installed you can just run dotnet build like usual.

Run it locally

At this point we can run the function locally using the Azure Function Tools and the Azurite storage emulator.

With these two tools installed you can run the following commands (in separate terminals or as background processes) to start the function.

azurite --location ~/.azurite --debug ~/.azurite/debug.log
func start

The output from func start should look something like this.

Deploy to Azure

In order to deploy to Azure we need to create some Azure resources. At a minimum we need a resource group containing a storage account, app service plan on the consumption billing tier and a function app. We can configure all of this from an ARM template. Whilst straight forward if you know how to use ARM templates, it's quite verbose, so instead of inlining it here, you can see it on GitHub instead.

Assuming you've got an Azure subscription and the Az CLI installed then we can deploy it with these commands.

# Create a resource group, only needs to be done the first time
az group create -n <resource-group-name> -l <location>

# Build the code, this will publish all the necessary files to the location specified by the -o argument
dotnet build src/Function -c Release -o .publish/func

# The template outputs the function app's name so we can use it in the next step to deploy the code
FUNCTION_NAME=$(az deployment group create \
    --no-prompt \
    --output tsv \
    --query properties.outputs.functionName.value \
    --resource-group <resource-group-name> \
    --template-file ./azuredeploy.json)

cd .publish/func

# Zip up the build output for deployment to the app
zip -r ./funtionapp.zip .

az functionapp deployment source config-zip \
    --resource-group <resource-group-name> \
    --name ${FUNCTION_NAME} \
    --src ./functionapp.zip

One quirk here is that you might have been expecting to use the dotnet publish command in order to create the deployable artefact, as is typical when developing an ASP.NET app. That's not the case here, for Azure functions the publishing happens automatically when running dotnet build.

Bonus: Build and Deploy from GitHub

Now that we've automated the build and deployment using CLI tools, it's actually very easy to turn this into a GitHub action. Especially if we create a script called deploy.sh that takes care of all of the Azure related steps from the previous section.

name: Build & Deploy
on:
  push:
    branches:
    - master
  pull_request:
env:
  FUNCTION_PACKAGE_PATH: .publish/function
  RESOURCE_GROUP: az-function-fsharp-net5
jobs:
  build-and-deploy:
    runs-on: ubuntu-18.04
    steps:
    - name: Checkout code
      uses: actions/checkout@master
      with:
        fetch-depth: 0
    - name: Setup dotnet SDK 3.1 (https://github.com/Azure/azure-functions-dotnet-worker/issues/480)
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: "3.1.409"
    - name: Setup dotnet SDK
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: "5.0.300"
    - name: Publish Function
      run: dotnet build src/Function -c Release -o ${{ env.FUNCTION_PACKAGE_PATH }}
    - name: Login to Azure
      uses: azure/login@v1
      with:
        creds: ${{ secrets.AZURE_RBAC_CREDENTIALS }}
    - name: Deploy to Azure
      uses: azure/CLI@v1
      with:
        inlineScript: ./deploy.sh ${{ env.FUNCTION_PACKAGE_PATH }} -g ${{ env.RESOURCE_GROUP }}

Note that we have to install both the .NET Core 3.1 and .NET 5 SDKs in order to build the code.

In order for this to work you'll need to set a GitHub secret called AZURE_RBAC_CREDENTIALS in your repo. More details about how to generate and set these credentials can be found on the Azure Login Action's page.

See the full example on GitHub

If you want to see the final example all in one place then you can check it out on GitHub. Feel free to clone it or fork it and use it as a starting template.

Choc13 / az-function-fsharp-net5

A minimal example of creating an Azure function using F# on .NET 5. with bonus GitHub actions deployment

Example Azure Function using F# on .NET 5

This repo shows a minimal example of how to write an Azure function using F# and run it on .NET 5 It also includes an example of deploying to Azure from your local machine and using GitHub actions.

Gotchas

There were several gotchas that were discovered when trying to get this to work which were often tricky to find in the existing documentation. In fact, all of these gotchas are related to using .NET 5 and apply equally to a C# project.

Isolated .NET Host

Running the function on .NET 5 requires an isolated .NET host Specifically, we have to set the environment variable FUNCTIONS_WORKER_RUNTIME to the value "dotnet-isolated" This is because the default host in the functions runtime is still using .NET Core 3.1. We have to set this in both the local.settings.json file for running locally and the …

View on GitHub

The state of Azure severless in 2021

Given the variety of triggers available and the consumption based billing model Azure functions are well suited for running reactive asynchronous background tasks. This is an important piece in the architecture of any reasonably sized distributed system hosted in the cloud. It also provides a complimentary role to that of the backend API, such as a REST API, which expects to make quick decisions and not spend its time chugging away at long running async computations.

It's a shame then that Azure functions seem to have conflated this feature set with the one of reducing-all-the-boilerplate. It's understandable that there is a use case that exists in which many people will just want to write some code and get it running somewhere with minimal fuss. Unfortunately, I think that's a completely different set of people to the ones who want to use Azure functions as part of the architecture of a larger distributed system.

As someone in the latter camp I care much more about being able to have explicit control over the environment in which my code runs than I do about eliminating a dozen lines of host configuration boilerplate. Spending time eliminating this boilerplate is a false economy because I probably spend less than 0.001% of my time when building such a system on those dozen lines of config code. The problem with trying to eliminate all the boilerplate is that if you don't nail the abstractions they end up creating more friction than the original boilerplate did, by forcing developers to figure out how to work around them.

Conclusion

Creating an Azure function targeting the latest .NET runtime is quite fiddly and insufficiently documented at present. Fortunately, with a bit of tinkering it is possible to make it work. Choosing between F# and C# is also just a matter of which language suits your project better as neither requires any extra Azure functions magic than the other.

In the future it would be great the see Microsoft focus more on building a solid pay-per-use background processing solution without all the magic, basically good old WebJobs on a consumption plan. The "in-process" use case should then be simple to build on top of this foundation for those that don't need such control and don't want to have to figure out how to configure a host. Better to try and walk before you can run.

Grokking Lenses

Matt Thornton — Fri, 28 May 2021 12:09:52 +0000

In most functional programming languages data structures are immutable by default, which is great because immutability eliminates a whole raft of issues from our code, freeing our brains up to worry about the higher level problems we're trying to solve. One of the drawbacks of immutability is how cumbersome it can be to modify nested data structures. In this post we're going to independently discover a better way of "updating" immutable data and in doing so re-invent lenses.

The scenario

In this post we'll imagine that we're working with the following data model.

type Postcode = Postcode of string

type Address =
    { HouseNumber: string
      Postcode: Postcode }

type CreditCard =
    { Number: string
      Expiry: string
      Cvv: string
      Address: Address }

type User = { CreditCard: CreditCard }

So a User has a CreditCard which has an Address. Now imagine that we've been asked to write some code that lets a user update their postcode for the address of their credit card. Pretty easy right?

let setCreditCardPostcode postcode user =
    { user with
          CreditCard =
              { user.CreditCard with
                    Address =
                        { user.CreditCard.Address with
                              Postcode = postcode } } }

Yikes! That's not pretty. Compare that to the imperative version in something like C#.

public static User SetCreditCardPostcode(User user, Postcode postcode)
{
    user.CreditCard.Address.Postcode = postcode;
    return user;
}

Ok, the data model might be mutable and there might be a bit more faff in the method declaration, but it's hard to argue with the fact that the actual set operation is much clearer in the imperative style.

Composing a solution 🎼

Instinctively, what we'd like to do is write functions that take care of setting their respective bits of the model and then compose them when we want to set data that is nested inside a larger structure. For example let's write some setters for Address, CreditCard and User in their respective modules.

module Address =
    let setPostcode postcode address = 
        { address with Postcode = postcode }

module CreditCard =
    let setAddress address card =
        { card with Address = address }

module User =
    let setCreditCard card user =
        { user with CreditCard = card }

I've omitted writing setters for every single property for brevity.

These functions are nice because they're very focused on a singular piece of the data model. Ideally, to write setCreditCardPostcode we'd be able to compose these individual functions to create a new function that can update the postcode inside a user's credit card. Something like this.

let setCreditCardPostcode: (Postcode -> User -> User) =
    Address.setPostcode
    >> CreditCard.setAddress
    >> User.setCreditCard

Aside: >> is the function composition operator, so that f >> g is equivalent to fun x -> x |> f |> g. More concretely if we had let addOne x = x + 1 then we could write let addTwo = addOne >> addOne.

But... it's not going to compile! The problem is that Address.setPostcode has the signature Postcode -> Address -> Address and CreditCard.setAddress has the signature Address -> CreditCard -> CreditCard. So when we write Address.setPostcode >> CreditCard.setAddress then the output of Address.setPostcode (which is Address -> Address) does not match the input to CreditCard.setAddress (which is just Address).

Aligning the types

Our first attempt, whilst not quite right, is pretty close. The types nearly line up. Let's see if we can align the types so that the output of one setter can feed straight in to the input of the next one.

If we look again at the output from Address.setPostcode postcode then we see it's a function whose signature is Address -> Address. That is, when we partially apply a postcode to setPostcode, it creates a function that can transform an address by setting the Postcode property to the value we partially applied. So how about if we change the input of CreditCard.setAddress to take an address transformation function, rather than just a new address value. In fact, there's nothing special about CreditCard.setAddress so let's make this change for all of our setters.

module Address =
    let setPostcode (transformer: Postcode -> Postcode) address =
        { address with
              Postcode = address.Postcode |> transformer }

module CreditCard =
    let setAddress (transformer: Address -> Address) card =
        { card with
              Address = card.Address |> transformer }

module User =
    let setCreditCard (transformer: CreditCard -> CreditCard) user =
        { user with
              CreditCard = user.CreditCard |> transformer }

You might feel like this is a hack in order to make composition work, but what we've actually done is made a much more powerful "setter" function. Each "setter" is now capable of taking any transformation function which it applies to the current value and then returns a new version of the data with this modification. If we think about it, setting a property is just a special case of this more general transformation where we ignore the existing value.

What we've actually created here are more like property modifiers than just setters. Each modifier has the signature ('child -> 'child) -> ('parent -> 'parent), which means given a function that can modify some child property, then I'll return you a function that updates the parent type. So let's rename them to modifyX instead and see if we can now create setCreditCardPostcode in the composition style that we wanted.

let setCreditCardPostcode: (Postcode -> User -> User) =
    Address.modifyPostcode
    >> CreditCard.modifyAddress
    >> User.modifyCreditCard

Hmmm, it's still not quite right. The type of setCreditCardPostcode is actually (Postcode -> Postcode) -> (User -> User), which in hindsight is obvious because all we've done is compose modifiers, not setters. So we've actually just created a new "modifier" here that lets us modify the postcode property of the user's credit card. In order to do a "set" operation we just apply the transformation that does the "set" to the "modifier".

let setCreditCardPostcode (postcode: Postcode): User -> User =
    (Address.modifyPostcode
     >> CreditCard.modifyAddress
     >> User.modifyCreditCard)
        (fun _ -> postcode)

So we compose our modifiers and then partially apply it with a transformer that just ignores the input and sets the value to the supplied postcode.

If you've followed up to this point then you've grokked the core principles, which is that if we have modifier functions that know how to update their one piece of the model, then we can chain them together to build modifiers that operate across many nested layers of a larger data structure. Everything that follows from now will be just tidying this up and extracting the generic parts.

Generic property modifiers

It should be clear from the last implementation of setCreditCardPostcode that in order to set a nested property we do two things.

Compose the necessary property modifiers to create one that can operates across many layers of a nested data structure.
Apply a transformation function that ignores the current value and just returns the new value that we want to set the property to.

Given that all of our property modifiers are of the form ('child -> 'child) -> ('parent -> 'parent), we should be able to write a set function that works for any modifier. It's really simple and just looks like this.

let set modifier (value: 'child) (parent: 'parent) =
    modifier (fun _ -> value) parent

We can even define the modifyCreditCardPostcode in the User module.

module User =
    let modifyCreditCardPostcode =
        Address.modifyPostcode
        >> CreditCard.modifyAddress
        >> modifyCreditCard

And then use it whenever we want to set a new value, as in user |> set User.modifyCreditCard "A POSTCODE" and we could also use it to transform a Postcode, as in user |> User.modifyCreditCardPostcode (fun (Postcode postcode) -> postcode |> String.toUpper |> PostCode). That's a nice separation of concerns.

Combing getters and setters

We might be tempted to stop here, and for the purposes of our initial problem regarding awkward data updates we've achieved our goal, but it would be nice if we could make this concept of property modifiers even more universal. In particular if we could combine the closely related acts of getting and setting a property in a single function.

If we look at Address.modifyPostcode again we'll see that it contains a "get" operation for the Postcode property.

module Address =
    let modifyPostcode (transformer: Postcode -> Postcode) address =
        { address with
              Postcode = address.Postcode |> transformer }
                       // ^ getting here ^

It's possible to rearrange this slightly and put the "get" first and pipe it in to a function that does the "setting".

let modifyPostcode transformer address =
    address.Postcode
    |> transformer
    |> (fun postcode -> { address with Postcode = postcode })

It's now clear to see that our modifiers perform the following operations.

Get the child data.
Transform the child data.
Update the parent with the transformed child value.

So if we could somehow find a way to skip the final step, then we'd have ourselves a getter. The only thing we can do to affect the behaviour of modifyPostcode though is to provide a different transformer. Unfortunately, try as we might there's no function we can supply here that will stop the final "setter" step from also running.

One trick we can do though is to make the transformer return a functor, see Grokking Functors if you need a recap. If we do this then in order to then call the final "setter" step we need to map it so that we can apply this "setter" to the contents of the functor we returned from the transformer. So, for example, modifyCodeProperty would look like this.

let modifyPostcode (transformer: Postcode -> '``Functor<Postcode>``) address =
    address.Postcode
    |> transformer
    // Everything's the same until the final line where we call map
    |> map (fun postcode -> { address with Postcode = postcode })

You might still be wondering how that lets us avoid calling the final "setter" step? Well, we can now exploit the map function to change the behaviour of modifyPostcode. If we remember how functors work then map is defined on a per functor basis, so by returning different functors from the transformer we can get different mapping behaviours at the end.

What we need then is a functor whose map instance just ignores the function being applied to it. One that just returns its input without transforming it. Fortunately for us such a functor already exists called Const and it's defined like this.

type Const<'Value, 'Ignored> =
    | Const of 'Value
    static member inline Map(Const x, _) = Const x

Map for Const just returns the input x. With that we're in a position to write a generic get function that will extract the child value from any of our modifiers.

let inline get modifier parent =
    let (Const value) = modifier Const parent
    value

What about our set function? Which functor should we return from the transformer in there? Well we need one that just runs the function without modification and that happens to also be a well known functor that goes by the name of Identity. Identity is defined like this.

type Identity<'t> =
    | Identity of 't
    static member inline Map(Identity x, f) = Identity(f x)

It's map instance just calls the function f on the input x and wraps the result back up in another Identity constructor. People often wonder why we'd need such a boring functor, but it comes in handy in these situations. With that set only requires a slight modification from before.

let inline set modifier value parent =
    let (Identity modifiedParent) =
        modifier (fun _ -> Identity value) parent

    modifiedParent

Putting it all together 🧩

We've made quite a few changes to things now, so let's see it all together. We'll start with the signature that a modifier must have, then show the get and set functions that work for any such modifier and finally show how we can use them to solve our original problem.

// Modifier signature - notice how the output is completely generic now which supports both our get and set use cases
('child -> '``Functor<child>``) -> ('parent -> 'a)

let inline get modifier parent =
    let (Const child) = modifier Const parent
    child

let inline set modifier value parent =
    let (Identity modifiedParent) =
        modifier (fun _ -> Identity value) parent

    modifiedParent

module Address =
    let modifyPostcode (transformer: Postcode -> '``Functor<Postcode>``) address =
        address.Postcode
        |> transformer
        |> map (fun postcode -> { address with Postcode = 
    postcode })

module CreditCard =
    let modifyAddress (transformer: Address -> '``Functor<Address>``) card =
        card.Address
        |> transformer
        |> map (fun address -> { card with Address = 
    address })

module User =
    let modifyCreditCard (transformer: CreditCard -> '``Functor<CreditCard>``) card =
        user.CreditCard
        |> transformer
        |> map (fun card -> { user with CreditCard = 
    card })

let setCreditCardPostcode postcode user =
    user
    |> set
        (User.modifyCreditCard
         << CreditCard.modifyAddress
         << Address.modifyPostcode)
        postcode

let getCreditCardPostcode user =
    user
    |> get (
        User.modifyCreditCard
        << CreditCard.modifyAddress
        << Address.modifyPostcode
    )

Our code is now very close to an imperative style setter. In fact, by reversing the composition operator, from >> to << and switching the order of the modifiers, we've even been able to order the property access in the same way that an imperative programmer would be familiar with, from the outermost to the innermost property. Using << is often frowned upon in general because it can be confusing, so use it at your own judgement.

You just discovered Lenses 🔍

These things we've been calling "modifiers", well they're better known as lenses. Lenses are a better name for them because they're not actually doing any modification, they're just composable functions that focus on a specific part of a data structure. We can define functions like get, typically called view, and set, usually called setl (for set lens), that let us read or write the value that any lens points to because the structure of a lens is completely generic.

There are also many more things that we can do with lenses, which is part of a broader topic called optics, which we haven't covered here. For instance we can easily work with data that might be missing, or focus our lens on specific parts of every element in a list.

Lenses are also about more than just composable getters and setters. They also provide an abstraction barrier for our code. If we access data through a lens rather than directly it means that if we later refactor a data structure we only have to modify the lens and the rest of the code will remain unaffected.

Lenses in the wild 🐗

There are a few lens "conventions" that are probably worth pointing out at this stage, as it's how you'll likely see them written in the wild. This is all just syntactic sugar on top of what we've already discovered, such as things like special operators which just make them a bit more pleasant to write. Below is the same example from above, but written using the FSharpPlus lens library.

#r "nuget: FSharpPlus"

open FSharpPlus.Lens // <- bring the lens operators in to scope

module Address =
    // Lenses are usually named with a leading underscore
    let inline _postcode f address =
        f address.Postcode <&> fun postcode -> { address with Postcode = postcode }

module CreditCard =
    // We also usually just name after the property they point to
    let inline _address f card =
        f card.Address
        <&> fun address -> { card with Address = address }

module User =
    // The <&> is just an infix version of map
    let inline _creditCard f user =
        f user.CreditCard
        <&> fun card -> { user with CreditCard = card }

let setCreditCardPostcode postcode user =
    // We can use the .-> as an infix version of setl
    user
    |> (User._creditCard
        << CreditCard._address
        << Address._postcode)
       .-> postcode

let getCreditCardPostcode user =
    // We can use the ^. operator as an infix version of view
    user
    ^. (User._creditCard
        << CreditCard._address
        << Address._postcode)

A few things to point out here:

Typically lenses are named like _propertyName.
What we used to call transformer we often just denote as f.
Instead of writing map it's common to write the lens using the <&> operator. This is just a flipped infix version of map and it lets us create the lens from a getter (to the left of the operator) and a setter (to the right of the operator).
We can use the .-> operator as an infix version of setl, which gives us an even more imperative style looking setter.
We can also use .^ instead of view to get the value, which is a kind of analogous to the . operator in OOP.

What did we learn? 🧑‍🎓

Lenses allow us to write property accessors which we can compose to focus on different parts of a large data model. We can then pass them to functions like view or setl to actually view the data or set it.

Lenses are also a great abstraction barrier that we can use to decouple our code from the specifics of our data models current structure. They also allow us do other useful transformations which we haven't gone into here. Lenses, and the broader topic of optics, is a large one, but with this intro you should find it much easier to explore what else they have to offer.

Interpreting Free Monads

Matt Thornton — Fri, 21 May 2021 11:13:11 +0000

In the last post in this series we grokked Free Monads and saw that they gave us a way to neatly build an abstract representation of a computation using only data. That’s all well and good when we’re writing our domain model, but eventually we need to actually do some real computing to run the side effects and produce the results. In this post we’ll learn how to write interpreters for free monads; first an interpreter to run the computation in the context of our application and then a different interpreter that lets us write “mockless” unit tests for our domain operations.

Recap 🧢

Let’s quickly remind ourselves of the problem we were solving last time. We wanted to write a chargeUser function which looked up a user by their id, then charged their card the specified amount and finally emailed them a receipt if they had an email address on their profile. Here's the domain model we were using.

type EmailAddress = EmailAddress of string

type Email = 
    { To: EmailAddress
      Body: string }

type CreditCard =
    { Number: string
      Expiry: string
      Cvv: string }

type TransactionId = TransactionId of string

type UserId = UserId of string

type User =
    { Id: UserId
      CreditCard: CreditCard
      EmailAddress: EmailAddress option }

We then wrote a discriminated union to represent the operations we needed to perform as part of the chargeUser computation which looked like this.

type ChargeUserOperation<'next> =
    | LookupUser of UserId * (User -> 'next)
    | ChargeCreditCard of (float * CreditCard) * (TransactionId -> 'next)
    | EmailReceipt of Email * (unit -> 'next)
    static member Map(op, f) =
        match op with
        | LookupUser (x, next) -> LookupUser(x, next >> f)
        | ChargeCreditCard (x, next) -> ChargeCreditCard(x, next >> f)
        | EmailReceipt (x, next) -> EmailReceipt(x, next >> f)

Finally, with the help of some smart constructors we could write the abstract version of chargeUser, which builds a free monad to represent the computation we want to eventually perform.

#r "nuget: FSharpPlus"

open FSharpPlus
open FSharpPlus.Data

let lookupUser userId = LookupUser(userId, id) |> Free.liftF

let chargeCreditCard amount card =
    ChargeCreditCard((amount, card), id) |> Free.liftF

let emailReceipt email = EmailReceipt(email, id) |> Free.liftF

let chargeUser (amount: float) (userId: UserId) =
    monad {
        let! user = lookupUser userId
        let! transactionId = chargeCreditCard amount user.CreditCard

        match user.EmailAddress with
        | Some emailAddress ->
            do!
                emailReceipt
                    { To = emailAddress
                      Body = $"TransactionId {transactionId}" }

            return transactionId

        | None -> return transactionId
    }

I've made use of FSharpPlus here for a couple of things:

The monad computation expression, which is just a generic computation expression that works for any monad.
The Free data type which uses the names Roll and Pure in place of the names Operation and Return that we made up last time. It also provides us with Free.liftF, meaning "lift functor", which lifts the operation functor to a free monad. As we discovered last time, as long as our operations are mappable we can always lift them into a free monad.

A trivial interpreter

Our goal previously, when writing the domain model, was to remove and "real" calls to infrastructure functions from the domain model. We're now going to shift focus to writing the application layer where we want to actually do the "real" work.

The application layer is responsible for receiving external requests (e.g. via a REST API) and then calling the domain model to process them. It should be able to "wire up" the actual infrastructure in order to implement the operations like LookupUser. So our job here is to take the abstract data structure output from chargeUser in the domain model and turn it into a real computation with real side effects - this is the job of the interpreter.

What we need to do is write a function called interpret which goes from Free<ChargeUserOperation<TransactionId>, TransactionId>, to TransactionId. That perhaps seems a bit tricky, so let's start by writing out chargeUser "long hand" to see more clearly what it is that we need to interpret.

let chargeUser amount userId =
    Roll(
        LookupUser(
            userId,
            fun user ->
                Roll(
                    ChargeCreditCard(
                        (amount, user.CreditCard),
                        fun transactionId ->
                            match user.EmailAddress with
                            | Some emailAddress ->
                                Roll(
                                    EmailReceipt(
                                        { To = emailAddress
                                          Body = $"TransactionId {transactionId}" },
                                        fun () -> Pure transactionId
                                    )
                                )
                            | None -> Pure transactionId
                    )
                )
        )
    )

Hopefully the strategy for writing interpret is clearer now that we've removed the syntactic sugar of the monad computation expression. We can see that we're going to need to recursively pattern matching on Roll operation until we hit a Pure value case. Let's give that a try.

let rec interpret chargeUserOutput : TransactionId =
    match chargeUserOutput with
    | Roll op ->
        match op with
        | LookupUser (userId, next) ->
            let user = // some hard coded user value
            user |> next |> interpret
        | ChargeCreditCard ((amount, card), next) ->
            TransactionId "123" |> next |> interpret
        | EmailReceipt (email, next) -> 
            () |> next |> interpret
    | Pure x -> x

Just as we'd planned, if we match on a Roll case then we unwrap a ChargeUserOperation which we can then pattern match on again. When we match on an operation the only sensible thing we can do is call next with the type of input it's expecting (for example next in LookupUser wants a User). This generates us another Free<_>, so we recursively call interpret to interpret that result until we hit a Pure case and we can just return the result. Note, if you want to play with this code then you'll actually need to write match Free.run chargeUserOutput due to the way FSharpPlus has implemented Free internally.

In this example we've just hardcoded a bunch of values, so we're still not doing any "real" work, but we can at least test this in the F# REPL now to see what happens.

> chargeUser 1.0 (UserId "1") |> interpret;;                                                            
val it : TransactionId = TransactionId "123"

👌 Great, it's produced the hard coded TransactionId.

One thing that stands out from this trivial implementation of interpret is that the outer pattern match doesn't depend on the type of operation at all. So let's see if we can refactor interpret such that it works for any type of operation.

let rec inline interpret interpretOp freeMonad =
    match freeMonad with
    | Roll op -> 
        let nextFreeMonad = op |> interpretOp 
        interpret interpretOp nextFreeMonad
    | Pure x -> x

In the Roll case we now delegate the job of interpreting the operation to the interpretOp function. Calling this with an op returns the nested callback, another free monad, which we can then pass back into interpret. As an example, let's write out interpretChargeUserOp, which is just the inner pattern match from our very first interpret function above.

let interpretChargeUserOp op =
    match op with
    | LookupUser (userId, next) ->
        let user = // some hard coded user value
        user |> next
    | ChargeCreditCard ((amount, card), next) -> 
        TransactionId "123" |> next
    | EmailReceipt (email, next) -> 
        () |> next

This is nice because we've now got a universal function for interpreting any free monad. We just have to supply it with a function for interpreting our use-case specific operations. We can interpret the free monad produced by chargeUser in the F# REPL like this now.

> chargeUser 1.0 (UserId "1") |> interpret interpretChargeUserOp;;                                                            
val it : TransactionId = TransactionId "123"

To make this more concrete, let's step through what happens when we interpret the first operation:

The interpret function sees Roll(LookupUser(...)), so it matches on Roll.
It then asks interpretChargeUserOp to deal with LookupUser, which it handles through its pattern matching. 1. In our trivial example this just passes a hard coded user to next, and we know (from writing chargeUser out "long hand") that next will be Roll(ChargeCreditCard(...)).
So when control returns to interpret it will recursively pass Roll(ChargeCreditCard(...)) back into itself along with the same interpretChargeUserOp function.
This will continue until it finds an operation whose continuation is just Pure. 🥵

If you've followed that then you've grokked it! We can now move on to writing a proper interpreter for our application 🙌

A real world interpreter

Enough of all of this abstract nonsense, we've got an application to ship. So let's get stuck in and write an actual interpreter that will do something useful. We'll assume we have the following infrastructure code already defined elsewhere in some appropriate projects or libraries.

module DB =
    let lookupUser userId =
        async {
            // Create a DB connection
            // Query the DB for the user
            // Return the user
        }

module PaymentGateway =
    let chargeCard amount card = 
        async {
            // Perform an async operation to charge the card
            // Return the transaction id
        }

module EmailClient = 
    let send email = async { // send the email }

With these already written, writing the interpreter for our operations is a straight forward job.

let interpretChargeUserOp (op: ChargeUserOperation<'a>): Async<'a> =
    match op with
    | LookupUser (userId, next) ->
        async {
            let! user = DB.lookupUser userId
            return user |> next
        }
    | ChargeCreditCard ((amount, card), next) ->
        async {
            let! transactionId = PaymentGateway.chargeCard amount card
            return transactionId |> next
        }
    | EmailReceipt (email, next) ->
        async {
            do! EmailClient.send email
            return () |> next
        }

We can see from the type of interpretChargeUserOp that we're turning each domain operation into an Async operation, which is exactly the separation that we wanted to achieve when we set out on our free monadic voyage. Our domain model doesn't even need to know that in reality the operations are going to be async, the only requirement is that they're monadic. The application is free to choose the monad it actually wants to work with, it could just have easily have used Task.

We're nearly home and dry, we just need to make sure this produces the correct result. We try and write chargeUser 1.0 (UserId "1") |> interpret interpretChargeUserOp, but the compiler says no! What's happened?

If we look at the signature of interpret more closely, we'll see that it's expecting interpretOp to return a Free<_>. The problem is that we're now returning Async<_> from interpretChargeCardOp. In general we're going to want to interpret our operations into other monads such as Async, Task, State etc, rather than just as plain values, because these operations are going to be performing side-effects. So we need to make a small change to interpret, what we now desire is for it to have the following signature.

let rec inline interpret
    (interpretOp: '``Functor<'T>`` -> '``Monad<'T>``)
    (freeMonad: Free<'``Functor<'U>``, 'U>)
    : '``Monad<'U>``

This is saying that, given some function that can turn functors (our operation is a functor) that contain a value of type T into some Monad that contains the same type T then we can use this to convert a free monad based on these operations into a different monad. In order to implement this we're going to have to fix the Roll case by this time unwrapping the monad produced by interpretOp before passing it back in to the recursive call to interpret.

let rec inline interpret
    (interpretOp: '``Functor<'T>`` -> '``Monad<'T>``)
    (freeMonad: Free<'``Functor<'U>``, 'U>)
    : '``Monad<'U>`` =
    match freeMonad with
    | Roll op ->
        monad {
            let! nextFreeMonad = interpretOp op
            return! interpret interpretOp nextFreeMonad
        }
    | Pure x -> monad { return x }

We've also had to change Pure slightly so that it basically lifts the value up into the target monad type too. For instance, if we were trying to convert the free monad to an async computation you could read the above like this instead.

let rec inline interpretAsync
    (interpretOp: '``Functor<'T>`` -> Async<_>)
    (freeMonad: Free<'``Functor<'U>``, 'U>)
    : Async<_> =
    match freeMonad with
    | Roll op ->
        async {
            let! nextFreeMonad = interpretOp op
            return! interpretAsync interpretOp nextFreeMonad
        }
    | Pure x -> async { return x }

Finally, let's make sure this new interpreter works now.

> chargeUser 1.0 (UserId "1")
-     |> interpret interpretChargeUserOp
-     |> Async.RunSynchronously;;
val it : TransactionId = TransactionId "123"

You've just discovered `Free.fold` 📃

What we've been calling interpret is actually the fold function for the Free data type. It replaces all of the abstract Roll operation elements of the data structure with the results of calling the function f that runs the operation function in a particular monad, like Async. We've seen here how we can use it in the application layer to turn the abstract domain computation into "real" calls to the database etc. The fun doesn't end there though, because we've decoupled the "what" from the "how", we can interpret our domain model in lots of different ways, let's take a look at another useful way of folding it.

A test interpreter 🧪

Let's imagine that we want to verify that chargeUser only sends an email if the user has an email address. How can we test this? Well we can just write a different interpreter of course, one that lets us track how many times the EmailReceipt case was present in the computation.

We're going to need our interpreter to do a couple of things:

Return a specific User object from LookupUser so that we can control whether or not there is an EmailAddress on the profile.
Count the number of times EmailReceipt is present in the computation.

Taking care of point 1 is easy because we already saw in the first trivial interpreter we wrote how to return hard coded values. What about point 2 though? Well we know that we can interpret our free monad as any other monad, so why not pick one that lets us track some state, where that state is a counter for the number of times EmailReceipt is called. For this we can use the Writer monad, which is just a monad that lets us update some value that gets passed through the entire computation. Using that our test could look like this.

module Tests =
    let shouldOnlySendReceiptWhenUserHasEmailAddress user =
        let output =
            chargeUser 1. (UserId "1")
            |> Free.fold
                (function
                | LookupUser (_, next) -> 
                    monad {
                        return user |> next
                    }
                | ChargeCreditCard (_, next) ->
                    monad {
                        return TransactionId "123" |> next
                    }
                | EmailReceipt (_, next) ->
                    monad {
                        do! Writer.tell ((+) 1)
                        return () |> next
                    })

        Writer.exec output 0

For the LookupUser operation we just pass the user argument that was passed to this test function into next. That allows us to have precise control over the User that is used in a particular test run. Interpreting ChargeCreditCard is boring here, we just hard code a TransactionId and pass it to next, because we're not interested in that part for this test. In EmailReceipt we use the Writer monad to increment the counter to track the fact that a call to EmailReceipt has been made. Finally we call Writer.exec output 0 to run the computation with an initial count of 0.

Let's give this a try in the REPL and see what results we get.

> let userNoEmail =                                       
-     { Id = UserId "1"
-       EmailAddress = None
-       CreditCard =
-           { Number = "1234"
-             Expiry = "12"
-             Cvv = "123" } };;

> Tests.shouldOnlySendReceiptWhenUserHasEmailAddress userNoEmail;;
val it : int = 0

✅ When the user doesn't have an email address the call count is 0.

> let userWithEmail =
-     { Id = UserId "1"
-       EmailAddress = Some(EmailAddress "a@example.com")
-       CreditCard =
-           { Number = "1234"
-             Expiry = "12"
-             Cvv = "123" } };;

> Tests.shouldOnlySendReceiptWhenUserHasEmailAddress userWithEmail;;  
val it : int = 1

✅ When the user does have an email address the call count is 1.

But I don't need a monad 🤷‍♀️

Sometimes, particularly when testing, you don't need to interpret the operations into a monad. For example, you might just want to check the output of the computation based on some inputs or based on the data returned from the call to the database. In that case you can use the Identity monad. Let's see what that looks like.

let shouldReturnTransactionIdFromPayment user =
    let output =
        chargeUser 1. (UserId "1")
        |> Free.fold
            (function
            | LookupUser (_, next) ->
                monad {
                    return user |> next
                }
            | ChargeCreditCard (_, next) ->
                monad {
                    return TransactionId "1" |> next
                }
            | EmailReceipt (_, next) ->
                monad {
                    return () |> next
                })

    output |> Identity.run

What did we learn? 🤓

We've seen that free monads provide an excellent means of decoupling the "what" from the "how". They allow us to write our domain model computations declaratively and leave the interpretation of how that should be done up to another layer of the application. In this post we learnt that we can use fold to interpret a free monad and all we have to do is supply it with a function to interpret our particular operations into some target monad.

This decoupling is particularly powerful when it comes to testing our domain models because it gives us precise control over the functions being tested. We don't have to worry about async calls in our test suite because we can choose to interpret the computation synchronously in the tests. It even eliminates the need for any mocking frameworks because it's trivial for us to check the number invocations for a particular operation or verify that particular arguments were supplied to a function.

Free monads might be abstract, but so should our domain models and the two go hand-in-hand very nicely.

Grokking Free Monads

Matt Thornton — Fri, 14 May 2021 19:33:19 +0000

In this post I’m going to try and demystify free monads and show you that they’re not some strange abstract creature, but in fact can be very useful for solving certain problems. Rather than focusing on the theory, our aim here will be to get a solid intuition about free monads, you'll then find learning the theory much easier. So in keeping with the rest of this series we’ll discover the free monad ourselves by solving a real software problem.

Pre-requisites

I try to keep these posts as independent from each other as possible, but in this case there's not much getting around the fact that you're probably going to need to have already grokked monads. If you haven't yet done so, then have a browse through Grokking Monads and once you're done you'll be all set to continue here.

The Scenario

Let's say we work at an e-commerce store and we need to implement a chargeUser function. This function should take a UserId and an amount. It should lookup the user's profile to get hold of the credit card, then it should charge the user's card the specified amount. If the user has an email address it should send them a receipt.

type EmailAddress = EmailAddress of string

type Email = 
    { To: EmailAddress
      Body: string }

type CreditCard =
    { Number: string
      Expiry: string
      Cvv: string }

type TransactionId = TransactionId of string

type UserId = UserId of string

type User =
    { Id: UserId
      CreditCard: CreditCard
      EmailAddress: EmailAddress option }

let chargeUser (amount: float) (userId: UserId): TransactionId =
    // TODO: Implement this as part of the domain model

Our main aim in this post is to be able to write the chargeUser function in our domain model. By domain model, we're referring to the very thing we're writing our program for in the first place. In this case as we're an e-commerce store that means our domain model includes things like user profiles, products and orders.

Typically when we write our application we want to keep our domain model completely decoupled from any infrastructure or application layer code, because those things are the incidental complexity that we have to solve. Our domain model should be pure and abstract in the sense that if we were to use a different database or a different cloud provider, the domain model should be unaffected.

It's easy to write types in our domain layer to represent the objects in the model without introducing any unwanted coupling, but what about the functions like chargeUser? On the one hand we know it's going to need to call external services, so does that mean we should define it outside of the domain model where we have access to the database etc? On the other hand it's not uncommon to want to take decisions in functions like this, such as whether or not we should email the user a receipt, and that logic definitely feels like domain logic that we'd want to test independent of the database.

Functions as data

There are several ways to make domain operations pure and agnostic to any infrastructure concerns. We've touched on one before in Grokking the Reader Monad. One interesting way to do it though is to treat functions as if they were data.

What do we mean by functions as data? The best way to understand this is to see some code. Let's take the chargeUser function and write a data model to describe the operations it needs to perform.

type ChargeUserOperations =
    | LookupUser of (UserId -> User)
    | ChargeCreditCard of (float -> CreditCard -> TransactionId)
    | EmailReceipt of (Email -> unit)

We've created a type called ChargeUserOperations that has a case for each of the operations we want to perform as part of chargeUser. Each case is parameterised by the function signature that we want it to have. So instead of being functions that we call, we've just got some abstract data representing the functions that we want to invoke and we'd like to use it like so.

let chargeUser amount userId: TransactionId =
    let user = LookupUser userId
    let transactionId = ChargeCreditCard amount user.CreditCard
    match user.EmailAddress with
    | Some emailAddress ->
        let email = 
          { To = emailAddress
            Body =  $"TransactionId {transactionId}" }
        EmailReceipt email
        return transactionId
    | None -> return transactionId

Obviously, this isn't going to work. We can't simply write LookupUser userId and assign that to something of type User. For starters LookupUser is expecting a function as an argument, not a UserId. This idea of functions as data is an interesting one though, so let's see if we can find a way to make it work.

It doesn't really make sense to try and extract a return value from data. All we can really do with data is create it. So what about if we instead created each operation with another operation nested inside it, kind of like a callback that would take the output of the current computation and produce a new output. Something like this.

type ChargeUserOperation =
    | LookupUser of (UserId * (User -> ChargeUserOperation)
    | ChargeCreditCard of (float * CreditCard * (TransactionId -> ChargeUserOperation)
    | EmailReceipt of (Email * (unit -> ChargeUserOperation)

We've made a couple of changes here. Firstly each operation is now parameterised by a tuple instead of a function. We can think of the tuple as the list of arguments to the function. Secondly, the final argument in the tuple is our callback. What that’s saying is that when you create an operation, you should tell it which operation you'd like to perform next that needs the result of this one. Let's give this new format a try.

let chargeUser (amount: float) (userId: UserId): TransactionId =
    LookupUser(
        userId,
        (fun user ->
            ChargeCreditCard(
                (amount, user.CreditCard),
                (fun transactionId ->
                    match user.EmailAddress with
                    | Some emailAddress ->
                        EmailReceipt(
                            { To = emailAddress
                              Body = $"TransactionId {transactionId}" },
                            (fun _ -> // Hmmm, how do we get out of this?)
                        )
                    | None -> // Hmmm, how do we get out of this?)
            ))
    )

Ok, it's getting better. We can see that this data structure is capturing the abstract logic of what the chargeUser function needs to do, without actually depending on any particular implementation. The only snag is we don't have a way to return a value at the end. Each of our operations has been defined such that it needs to be passed another callback, so how do we signal that we should actually just return a value?

What we need is a case in ChargeUserOperation that doesn't require a callback, one that just "returns" a value. Let's call it Return. We also need to make ChargeUserOperation generic on the return type to encapsulate the fact that each operation returns some value, but that the values returned by each operation might differ.

type ChargeUserOperation<'next> =
    | LookupUser of (UserId * (User -> ChargeUserOperation<'next>))
    | ChargeCreditCard of (float * CreditCard * (TransactionId -> ChargeUserOperation<'next>))
    | EmailReceipt of (Email * (unit -> ChargeUserOperation<'next>))
    | Return of 'next

We've chosen the name 'next for the generic parameter to signify the fact that it's the value returned by the "next" computation in the chain. In the case of Return then it's just immediately "returned". We're now finally in a position to write chargeUser.

let chargeUser (amount: float) (userId: UserId): ChargeUserOperation<TransactionId> =
    LookupUser(
        userId,
        (fun user ->
            ChargeCreditCard(
                (amount, user.CreditCard),
                (fun transactionId ->
                    match user.EmailAddress with
                    | Some emailAddress ->
                        EmailReceipt(
                            { To = emailAddress
                              Body = $"TransactionId {transactionId}" },
                            (fun _ -> Return transactionId)
                        )
                    | None -> Return transactionId)
            ))
    )

That's it! We've captured the logic of chargeUser in a completely abstract data structure. We know that it's got no dependence on any infrastructure because we fabricated it purely out of data types. We've taken our domain modelling to the next level, by modelling its computations as data too! ✅

One thing to note is that chargeUser now returns ChargeUserOperation<TransactionId>. This might seem weird, but we can think of it this way; chargeUser is now a function that produces a data structure which represents the the domain operation of charging and user and returning the TransactionId.

If you've grokked it this far, then you've made the fundamental mental leap; the fact that we're just representing a computation as data. The rest of this post is just going to be dedicated to cleaning this up to make it easier to read and write chargeUser. Things might get a bit abstract, but just keep in mind the fact that all we're doing is trying to build this data structure to represent our computation.

Flattening the pyramid ⏪

One problem with chargeUser in its current form is that we're back in nested callback hell, (a.k.a the Pyramid of Doom. We already know that monads are useful at flattening nested computations, so let's see if we can make ChargeUserOperation a monad.

The recipe for making something a monad is to implement bind for that type. We start by defining the types for the function signature and use that to guide us. In this case the signature is.

('a -> ChargeUserOperation<'b>) -> ChargeUserOperation<'a> -> ChargeUserOperation<'b>

So we're going to have to unwrap the ChargeUserOperation to get at the value 'a and then apply that the to the function we've been passed to generate a ChargeUserOperation<'b>. Let's get stuck in.

let bind (f: 'a -> ChargeUserOperation<'b>) (a: ChargeUserOperation<'a>) =
    match a with
    | LookupUser (userId, next) -> ??
    | ChargeCreditCard (amount, card, next) -> ??
    | EmailReceipt (unit, next) -> ??
    | Return x -> f x

As usual we've used a pattern match to unwrap the ChargeUserOperation in order to get at the inner value. In the case of Return it's a straight forward case of just calling f on the value x. But what about for those other operations? We don't have a value of type 'a to hand, so how can we invoke f?

Well what we do have to hand is next which is capable of producing a new ChargeUserOperation when supplied with a value. So what we can do is call that and recursively pass this new ChargeUserOperation to bind. The idea being that by recursively calling bind we'll eventually hit the Return case, at which point we can successfully extract the value and call f on it.

module ChargeUserOperation =
    let rec bind (f: 'a -> ChargeUserOperation<'b>) (a: ChargeUserOperation<'a>) =
        match a with
        | LookupUser (userId, next) -> LookupUser(userId, (fun user -> bind f (next user)))
        | ChargeCreditCard (amount, card, next) ->
            ChargeCreditCard(amount, card, (fun transactionId -> bind f (next transactionId)))
        | EmailReceipt (email, next) ->
            EmailReceipt(email, (fun () -> bind f (next())))
        | Return x -> f x

This might be a bit mind bending, but another way to view it is that we're just doing exactly the same callback nesting that we were forced to do by hand when we previously wrote chargeUser. Except now we've hidden the act of nesting these operations inside the bind function.

Each call to bind introduces another layer of nesting and pushes the Return down inside this new layer. For example if we had written LookupUser(userId, Return) |> bind (fun user -> ChargeCreditCard(amount, user.CreditCard, Return)) it would be equivalent to writing it in nested form like LookupUser(userId, (fun user -> ChargeCreditCard(amount, user.CreditCard, Return)).

With that we can easily write a computation expression called chargeUserOperation and use it to flatten that pyramid in chargeUser.

type ChargeUserOperationBuilder() =
    member _.Bind(a, f) = ChargeUserOperation.bind f a
    member x.Combine(a, b) = x.Bind(a, (fun () -> b))
    member _.Return(x) = Return x
    member _.ReturnFrom(x) = x
    member _.Zero() = Return()

let chargeUserOperation = ChargeUserOperationBuilder()

let chargeUser (amount: float) (userId: UserId) =
    chargeUserOperation {
        let! user = LookupUser(userId, Return)
        let! transactionId = ChargeCreditCard((amount, user.CreditCard), Return)

        match user.EmailAddress with
        | Some emailAddress ->
            let email =
                { To = emailAddress
                  Body = $"TransactionId {transactionId}" }

            do! EmailReceipt(email, Return)
            return transactionId
        | None -> return transactionId
    }

If do! is unfamiliar then it’s basically just let! except it ignores the result. Which we don’t care about when sending them email because it returns unit anyway.

Making data look like functions 🥸

The function is looking pretty nice now, but it's perhaps a bit unnatural to have to write LookupUser(userId, Return) instead of just lookupUser userId. It's also a bit annoying to have to constantly keep writing Return as the final argument to the ChargeUserOperation case constructors. Well it's easy to fix that, we can just write a "smart constructor" for each case that hides that detail away.

let lookupUser userId = LookupUser(userId, Return)

let chargeCreditCard amount card = ChargeCreditCard(amount, card, Return)

let emailReceipt email = EmailReceipt(email, Return)

let chargeUser (amount: float) (userId: UserId) =
    chargeUserWorkflow {
        let! user = lookupUser userId
        let! transactionId = chargeCreditCard amount user.CreditCard

        match user.EmailAdress with
        | Some emailAddress ->
            do!
                emailReceipt
                    { To = emailAddress
                      Body = $"TransactionId {transactionId}" }

            return transactionId

        | None -> return transactionId
    }

🔥 Nice! Now the function perfectly expresses the logic of our operation. It looks just like a regular monadic function, except under the hood it's actually building up an abstract data structure that represents our desired computation, rather than invoking any real calls to real infrastructure.

Factoring out a functor

Our chargeUser function is looking pretty good now, but there's some optimisations we can make to the definition of ChargeUserOperation. Let's consider what would happen if we wanted to write a different computation. We'd have to write a data type with a case for each operation we want to support, plus a case for Return and then finally implement bind for it. Wouldn't it be nice if we could implement bind once for any computation type?

Let's take a look at the definition of bind for ChargeUserOperation again and see if we can refactor it to something a bit more generic.

let rec bind (f: 'a -> ChargeUserOperation<'b>) (a: ChargeUserOperation<'a>) =
    match a with
    | LookupUser (userId, next) -> LookupUser(userId, (fun user -> bind f (next user)))
    | ChargeCreditCard (amount, card, next) ->
        ChargeCreditCard(amount, card, (fun transactionId -> bind f (next transactionId)))
    | EmailReceipt (email, next) ->
        EmailReceipt(email, (fun () -> bind f (next ())))
    | Return x -> f x

If we mandate that each operation must be of the form Operation of ('inputs * (‘output -> Operation<'next>) then they only differ by parameter types, which we could make generic. How should we do this for ChargeCreditCard though, because that currently has two inputs. Well we can combine the inputs into a single tuple like this ChargeCreditCard of ((float * CreditCard) * (TransactionId -> ChargeUserOperation<'next>)).

The form of bind for each operation is now identical, specifically it is Operation(inputs, next) -> Operation(inputs, (fun output -> bind f (next output)). So really, we actually only have two cases to consider, either it's an Operation or it's a Return. So let's create a type called Computation that encapsulates that.

type Computation<'op, 'next> =
    | Operation of 'op
    | Return of 'next

Which we can write bind for to turn it into a monad.

let rec inline bind (f: 'a -> Computation< ^op, 'b >) (a: Computation< ^op, 'a >) =
    match a with
    | Operation op -> Operation(op |> map (bind f))
    | Return x -> f x

The trick to making this work in the Operation case is to note that we require each Operation to be mappable. That is, we require it to be a functor. Mapping an operation is just a case of applying the function to the return value to transform it into something else. So by recursively calling bind f, as we did when writing for this ChargeUserOperation, we eventually hit the Return case, get access to the return value and just apply the current op to it by calling map.

So now when we're writing our operations we've reduced the task from having to implement bind to instead having to implement map, which is an easier task. For example we can express ChargeUserOperation like this.

type ChargeUserOperation<'next> =
    | LookupUser of UserId * (User -> 'next)
    | ChargeCreditCard of (float * CreditCard) * (TransactionId -> 'next)
    | EmailReceipt of Email * (unit -> 'next)
    static member Map(op, f) =
        match op with
        | LookupUser (x, next) -> LookupUser(x, next >> f)
        | ChargeCreditCard (x, next) -> ChargeCreditCard(x, next >> f)
        | EmailReceipt (x, next) -> EmailReceipt(x, next >> f)

Unfortunately, we can't eliminate any more boilerplate beyond here in F#. In other languages like Haskell it is possible to automatically derive the Map function for the operation functors, but in F# using FSharpPlus the best we can do today is write the static member Map ourselves. FSharpPlus then provides us the map function which will automatically pick the correct one by calling this static member Map when mapping an instance of ChargeUserOperation through the use of statically resolved type parameters.

We just have one final change to make to the smart constructors. Now that ChargeUserOperation is now just a functor, we need to lift them up into the Computation monad by wrapping them in an Operation.

let lookupUser userId = LookupUser(userId, Return) |> Operation

let chargeCreditCard amount card =
    ChargeCreditCard((amount, card), Return) |> Operation

let emailReceipt email =
    EmailReceipt(email, Return) |> Operation

let chargeUser (amount: float) (userId: UserId) =
    computation {
        let! user = lookupUser userId
        let! transactionId = chargeCreditCard amount user.CreditCard
        match user.EmailAddress with
        | Some emailAddress ->
            do!
                emailReceipt
                    { To = emailAddress
                      Body = $"TransactionId {transactionId}" }

            return transactionId
        | None -> return transactionId
    }

You just discovered the Free Monad 🥳

The data type we called Computation is usually called Free, the Operation case is often called Roll and the Return case is often called Pure. Other than that though we've discovered the basis of the free monad. It's just a data type and associated bind function that fundamentally describes sequential computations.

If you're a C# developer and you're familiar with LINQ then this might seem familiar to you. LINQ provides a way to build up a computation and defer its evaluation until sometime later. It's what allows LINQ to run in different environments, such as in a DB, because people are able to write interprets for it that turn the LINQ statements into SQL etc on the database server.

Should I use free monads 🤔

You might be wondering whether to use free monads in F# in your project. On the one hand they provide an excellent means of abstraction when it comes to defining computations in a domain model. They're also a joy to test because we can just interpret them as pure data and verify that for a given set of inputs we have produced the right data structure and hence computation; no more mocking 🙌.

Another plus is that with free monads we've actually achieved what object oriented programmers would call the interface segregation principle. Each computation only has access to the operations it needs to do its work. No more injecting wide interfaces into domain handlers and then having to write tests that verify we didn't call the wrong operation; it's literally impossible under this design!

On the other hand it seems to be pushing F# to the limits as it technically requires features like higher-kinded types, which F# doesn't technically support. So we have to resort to making heavy use of statically resolved type parameters to make it work. You might also find them to be quite abstract, although I hope that this post has at least helped to make their usage seem more intuitive, even if the internal implementation is still quite abstract.

On balance I don't think there's a one-size-fits-all answer here. You're going to have to weigh up the pros and cons for your project and team and decide whether this level of purity is worth it in order to warrant overcoming the initial learning curve and potentially cryptic compiler errors when things don't line up.

If you're thinking of taking the plunge and giving them a try then I would recommend using FSharpPlus which has done all the hard work of defining the free monad machinery for you. Also see the appendix at the end for a full example using FSharpPlus.

What did we learn 🧑‍🎓

The name free monad, might be cryptic and even misleading at first, but the concept is relatively straight forward. Free monads are just a data structure that represents a chain of computations that should be run sequentially. By building a data structure we're able to leave it up to someone else to come along and interpret it in anyway they see fit. They’re “free” to do it how they need to providing they respect the ordering of the computations in the data structure we have handed to them.

A free monad is just a way for us to describe our computation in very abstract terms. We're placing the fewest restrictions possible on what the computation has to do and making no assumptions about how it should be done. We've completely decoupled the "what" from the "how", which is one of the fundamental pillars of good Domain Driven Design, because it means that the domain model is a pure abstract representation of the problem at hand unburdened by the details of how it is hosted.

Next time ⏭

We've covered a lot in this post but we haven't talked about how we actually go about running these computations. So far we've just built some abstract representations of them in data. Next time we'll see how we can actually interpret them to do some real work.

Appendix

If you want to see a complete, top-to-bottom, example of writing a free monadic workflow using FSharpPlus, then I've included one in the section below.

#r "nuget: FSharpPlus"

open FSharpPlus
open FSharpPlus.Data

type ChargeUserOperation<'next> =
    | LookupUser of UserId * (User -> 'next)
    | ChargeCreditCard of (float * CreditCard) * (TransactionId -> 'next)
    | EmailReceipt of TransactionId * (TransactionId -> 'next)
    static member Map(op, f) =
        match op with
        | LookupUser (x, next) -> LookupUser(x, next >> f)
        | ChargeCreditCard (x, next) -> ChargeCreditCard(x, next >> f)
        | EmailReceipt (x, next) -> EmailReceipt(x, next >> f)

let lookupUser userId = LookupUser(userId, id) |> Free.liftF

let chargeCreditCard amount card =
    ChargeCreditCard((amount, card), id) |> Free.liftF

let emailReceipt email =
    EmailReceipt(email, id) |> Free.liftF

let chargeUser (amount: float) (userId: UserId) =
    monad {
        let! user = lookupUser userId
        let! transactionId = chargeCreditCard amount user.CreditCard
        match user.EmailAddress with
        | Some emailAddress ->
            do!
                emailReceipt
                    { To = emailAddress
                      Body = $"TransactionId {transactionId}" }

            return transactionId
        | None -> return transactionId
    }

When writing the smart constructors here, e.g lookUser we pass the identity function, id, as the second argument. The reason for this is because Free.liftF maps the functor with Pure and then lifts it up with Roll. So by using id and then writing Free.liftF we end up with the desired Roll (LookupUser(userId, Pure)). The other way to think of id here is that the default "callback" when creating an operation is to just return the value produced by this computation and not do anything else.

Grokking Monad Transformers

Matt Thornton — Fri, 07 May 2021 21:29:35 +0000

Earlier in this series, in Grokking Monads, we discovered that monads allowed us to abstract away the machinery of chaining computations. For example when dealing with optional values, they took care of the failure path for us in the background and freed us up to just write the code as if the data was always present. What happens though when we have multiple monads we'd like to use, how can we mix them together?

Just like in the rest of this series, we're going to invent monad transformers ourselves by solving a real software design problem. At the end we'll see that we've discovered the monad transformer and in doing so we'll understand it more intuitively.

The scenario

Let's revisit the same scenario we encountered in Grokking Monads where we want to charge a user's credit card. If the user exists and they have a credit card saved in their profile we can charge it and email them a receipt, otherwise we'll have to signal that nothing happened. This time however, we're going to make the lookupUser, chargeCard and emailReceipt functions async because they call external services.

We'll start with the following data model and operations.

type UserId = UserId of string

type TransactionId = TransactionId of string

type CreditCard =
    { Number: string
      Expiry: string
      Cvv: string }

type User = 
    { Id: UserId
      CreditCard: CreditCard option }

let lookupUser userId: Async<option<User>>

let chargeCard amount card: Async<option<TransactionId>>

let emailReceipt transactionId: Async<TransactionId>

The only difference from before is that lookupUser, chargeCard and emailReceipt return Async now, because in reality they'll be calling a database, external payment gateway and sending messages.

Our first implementation

Using our learnings from Grokking Monads, Imperatively then we might immediately reach for the async computation expression because that's the primary monad that we're dealing with here. So let's start with that.

let chargeUser amount userId = 
    async {
        let! user = lookupUser userId
        let card = user.CreditCard
        let! transactionId = chargeCard amount card
        return! emailReceipt transactionId
    }

Looks simple and it captures the essence of what we need to do, but it's not right. The line let card = user.CreditCard isn't going to compile, because at this point user is of type User option. We've also got a similar problem when writing chargeCard amount card because we'll actually have a CreditCard option there.

One way around this is to just start writing the pattern matching logic ourselves to get access to the values inside those options so that we can use them. Let's see what that looks like.

let chargeUser amount userId =
    async {
        match! lookupUser userId with 
        | Some user -> 
            match user.CreditCard with
            | Some card -> 
                match! chargeCard amount card with
                | Some transactionId -> return! (emailReceipt transactionId) |> Async.map Some
                | None -> return None
            | None -> return None
        | None -> return None
    }

This is much more cumbersome than before and the fairly simple logic of this function is obscured by the nested pattern matching (a.k.a. the pyramid of doom). We're basically back to the same situation that we found ourselves in when we first introduced this in Grokking Monads. It seems like once we've got more than one monad to deal with, everything inside the outer one has to fall back to manually dealing with the failure path again through continual pattern matching.

Inventing a new monad

At this point we might think to ourselves, why don't we invent a new monad? One that encapsulates the fact that we want to perform async computations that return optional results. It should behave like both the async monad when an async operation fails and the option monad when the async operation produces missing data. Let's call it AsyncOption.

What we need to do then is figure out how to implement bind for this new monad. Let's start with the types and then use them to guide us in writing it. In this case it will have the signature (a' -> Async<option<'b>>) -> Async<option<'a>> -> Async<option<'b>>.

So this is telling us that we're given a function that wants some value of type 'a and will return us a new value wrapped up in our Async<option<_>> type. We're also given an instance of this monad pair that encapsulates a value of type 'a. So intuitively, we need to unwrap both the Async and option layers to get at this value of type 'a and then apply it to the function.

let bind f x =
    async {
        match! x with
        | Some y -> return! f y
        | None -> return None
    }

Here we've achieved this by using the async computation expression. This allows us to use a match! which simultaneously unwraps the async value and pattern matches on the inner option to allow us to extract the value from that too.

We’ve had to deal with three possible cases:

In the case where x is a successful async computation that's returned Some value then we can apply the function f to the value.
In the case that the async operation successfully returns None then we just propagate the None value by wrapping it in a new async by using return.
Finally, if the async computation fails then we just let the async computation expression deal with that and propagate that failure without calling f.

So with bind in place it's easy to create an asyncOption computation expression and we can write our function using that.

let chargeUser amount userId =
    asyncOption {
        let! user = lookupUser userId
        let! card = user.CreditCard
        let! transactionId = chargeCard amount card
        return! emailReceipt transactionId
    }

Much better, but the eagle eyed might have already spotted a problem with our plan. When we try and call user.CreditCard it won't work. The problem is that user.CreditCard returns a vanilla option and our bind (and therefore let!) has been designed to work with Async<option<_>>.

On top of this, on the final line we have a similar problem. The emailReceipt function returns a plain Async<_> and so we can't just write return! because it's not producing an Async<option<_>>. It seems like we're stuck with needing everything to use exactly the same monad or things won't line up.

Lifting ourselves out of a hole 🏋️

A simple way to solve the first problem is to just wrap that vanilla option in a default Async value. What would a default Async be though? Well we want to just treat it as if it's a successful async computation that’s immediately resolved so let's just write a function called hoist that wraps its argument in an immediate async computation.

let hoist a =
    async {
        return a
    }

If you're a C# developer this is just like Task.FromResult and if you're a JavaScript developer then it's akin to Promise.resolve.

To solve the second problem we need a way to wrap up the value inside the Async in a default option value. The default option value would be Some in this case, and we saw in Grokking Functors that the way to modify the contents of a wrapped value is to use map. So let's create a function called lift that just calls map with Some.

let lift (a: Async<‘a>): Async<option<‘a>> = a |> Async.map Some

So with this in hand we can finally finish off our chargeUser function.

let chargeUser amount userId =
    asyncOption {
        let! user = lookupUser userId
        let! card = user.CreditCard |> hoist
        let! transactionId = chargeCard amount card
        return! (emailReceipt transactionId) |> lift
    }

This is now looking quite tidy and the logic is clear to see, no longer hidden amongst nested error handling code. So is that all there is to monad transformers? Well not quite...

A combinatorial explosion 🤯

Let's say for arguments sake that we wanted to use a Task instead of an Async computation. Or perhaps we want to start returning a Result now instead of an option. What about if we want to use a Reader too?

You can probably see how the combinations of all of these different monads is going to get out of hand if we need to create a new monad to represent each pair. Not to mention the fact that we might want to create combinations of more than two.

Wouldn't it be nice if we could find a way to write a universal monad transformer? One that could let us combine any two monads to create a new one. Let's see if we can invent that.

Where do we start? Well we know by now that to create a monad we need to implement bind for it. We've also seen how to do that for a new monad created from the Async and option pair of monads. All we basically need to do is peel back each of monad layers to access the value contained inside the inner one and then apply this value to the function to generate a new monad pair.

Let's imagine for a minute that we have a universal monad computation expression which invokes the correct bind, by figuring out which version to use, based on the particular monad instance that it's being called on. With that to hand then we should be able to peel off two monadic layers to access to the inner value quite easily.

let bindForAnyMonadPair (f: 'a -> 'Outer<'Inner<'b>>) (x: 'Outer<'Inner<'a>>) =
    monad {
        let! innerMonad = x
        monad {
            let! innerValue = innerMonad
            return! f innerValue
        }
    }

Unfortunately it turns out that this doesn't work. The problem is that when we write return! f value it's not quite right. At that point in the code we're in the context of the inner monad's computation expression and so return! is going to expect f to return a value that's the same as the inner monad, but we know that it returns 'Outer<'Inner<'b>> because that’s what we need it to have for our new bind.

It might seem like there would be a way out of this. After all, we have the value we need to supply to f, so surely we must be able to just call it and generate the value we need somehow. However, we have to remember that computation expressions and let! are just syntactic sugar for bind. So what we're really trying to write is this.

let bindForAnyMonadPair (f: 'a -> Outer<Inner<'b>>) (x: Outer<Inner<'a>>) =
    x 
    |> bind 
        (fun innerMonad ->
            innerMonad
            |> bind (fun value -> f value))

And then it's (maybe) more obvious to see that f can't be used with the inner monad's bind because it's not going to return the right type. So it seems we can dig inside both monads to get to the value in a generic way, but we don't have a generic way of putting them back together again.

There's still hope 🤞

We might have failed at creating a truly universal monad transformer, but we don't have to completely give up. If we could make even one of the monads in the pair generic then it would massively reduce the number of monad combinations we need to write.

Intuitively you might think about making the inner one generic, I know I did. However, you'll see that we fall into exactly the same trap that we did before when we tried to make both generic, so that won't work.

In that case our only hope is to try making the outer monad generic. Let's assume we've still got our universal monad computation expression to hand and see if we can write a version that works whenever the inner monad is an option.

let bindWhenInnerIsOption (f: 'a -> 'Outer<option<'b>>) (x: 'Outer<option<'a>>) =
    monad {
        match! option with
        | Some value -> return! f value
        | None -> return None
    }

🙌 It works! The reason we were able to succeed this time is because we could use return! when calling f because we were still in the context of the outer monad's computation expression. So return! is able to return a value that is of the type Outer<option<_>> which is precisely what f gives us back.

We're also going to need generic versions of hoist and lift too, but they're not too difficult to write.

let lift x = x |> map Some

let hoist = result x

In order to write lift we're assuming that the Outer monad has map defined for it and that map can select the correct one, because we don't know at this point in time which monad to call map on.

Also hoist is making use of a generic result function which is an alias for return because return is a reserved keyword in F#. Technically every monad should have return, as well as bind, defined for it. We haven't mentioned return before because it's so trivial, but it just wraps any plain value up in a monad. For example result for option would just be Some.

You just discovered the Monad Transformer 👏

With our invention of bind, lift and hoist, for the case when inner monad is an option, we've invented the option monad transformer. Normally this is called OptionT and is actually wrapped in a single case union to make it a new type, which I'll show in the appendix, but that's not an important detail when it comes to grokking the concept.

The important thing to realise is that when you need to deal with multiple monads you don't have to resort back to the pyramid of doom. Instead, you can use a monad transformer to represent the combination and easily create a new monad out of a pair of existing ones. Just remember that it's the inner monad that we define the transformer for.

Test yourself

See if you can implement bind, lift and hoist for the Result monad.

Solution

module ResultT =
    let inline bind (f: 'a -> '``Monad<Result<'b>>``) (m: '``Monad<Result<'a>>``) =
        monad {
            match! m with
            | Ok value -> return! f value
            | Error e -> return Error e
        }

    let inline lift (x: '``Monad<'a>``) = x |> map Ok

    let inline hoist (x: Result<'a, 'e>) : '``Monad<Result<'a>>`` = x |> result

Does this actually work? 😐

When we invented bind for OptionT we imagined that we had this all powerful monad computation expression to hand that would work for any monad. You might be wondering if such a thing exists? Particularly whether such a thing exists in F#.

It seems like we need to ability to work with generic generics. In other words, we need to be able to work with any monad which itself can contain any value. This is called higher kinded types and you might be aware of the fact that F# doesn't support them.

Fortunately for us, the excellent FSharpPlus has figured out a way to emulate higher kinded types and does have such an abstract monad computation expression defined. It also has plenty of monad transformers, like OptionT, ready to use.

Should I use a monad transformer?

Monad transformers are certainly quite powerful and can help us recover from having to write what would otherwise be heavily nested code. On the other hand though they're not exactly a free lunch. There are a few things to consider before using them.

If the monad stack gets large it can in itself become quite cumbersome to keep track of it. For instance the types can become large and the lifting across many layers can become tiring.
This is an area that pushes F# to its limits. Whilst FSharpPlus has done a fantastic job in figuring out how to emulate higher kinded types, it can lead to very cryptic compile time errors if you've got a type mismatch somewhere when using the monad transformer.
It can also slow down compile times due to the fact it's pushing type inference beyond what it was really designed for.

In some cases then you might be better off just defining a new monad and writing bind etc for it yourself. If your application typically deals with the same stack of monads then the improved compiler errors will probably outweigh the relatively small maintenance burden of writing the code yourself.

What did we learn? 🧑‍🎓

We've now discovered that it's possible to combine monads into new monads and that this lets us write tidier code when we would otherwise have to write nested pattern matches. We've also seen that while it's not possible to create a universal monad transformer for any pair, it is possible to at least define a monad transformer for a fixed inner type. That means we only need to write one transformer per monad in order to start creating more complex monad combinations.

Appendix
As mentioned above a monad transformer usually has a new type associated with it. Below I'll show what this looks like for the OptionT monad transformer and then use that along with the generic monad computation expression from FSharpPlus to implement the chargeUser function.

#r "nuget: FSharpPlus"

open FSharpPlus

type OptionT<'``Monad<option<'a>>``> = OptionT of '``Monad<option<'a>>``

module OptionT =
    let run (OptionT m) = m

    let inline bind (f: 'a -> '``Monad<option<'b>>``) (OptionT m: OptionT<'``Monad<option<'a>>``>) =
        monad {
            match! m with
            | Some value -> return! f value
            | None -> return None
        }
        |> OptionT

    let inline lift (x: '``Monad<'a>``) = x |> map Some |> OptionT

    let inline hoist (x: 'a option) : OptionT<'``Monad<option<'a>>``> = x |> result |> OptionT

let chargeUser amount userId : Async<option<TransactionId>> =
    monad {
        let! user = lookupUser userId |> OptionT
        let! card = user.CreditCard |> OptionT.hoist
        let! transactionId = (chargeCard amount card) |> OptionT
        return! (emailReceipt transactionId) |> lift
    }
    |> OptionT.run

If you're wondering about those type annotations like

'``Monad<'a>``

then they're really they're just fancy labels. We've used the

``

quotations to just give a more meaningful name to show that they represent some generic Monad. This acts as documentation, but unfortunately it's not really doing any meaningful type checking. As far as the compiler is concerned that just like any other generic type. We could have easily just written type OptionT<'a> = OptionT of 'a. So the onus is back on us when implementing these functions to make sure we do write it as if it's actually a generic monad and not just any generic value.

Grokking the Reader Monad

Matt Thornton — Sat, 01 May 2021 08:10:34 +0000

From its name the reader monad doesn’t give too many clues about where it would be useful. In this post we’ll grok it by inventing it ourselves in order to solve a real software problem. From this we’ll see that it’s actually one way of doing dependency injection in functional programming.

Prerequisites

There won’t really be any theory here, but it’ll be easier if you’ve already grokked monads. If you haven’t then check out Grokking Monads from earlier in this series and then head back over here.

The scenario

Let’s imagine we’ve been asked to write some code that charges a user’s credit card. To do this we’re going to need to lookup some information from a database and also call a payment provider.

Our domain model will look like this.

type CreditCard =
   { Number: string
     Expiry: string
     Cvv: string }

type EmailAddress = EmailAddress of string 
type UserId = UserId of string

type User =
    { Id: UserId
      CreditCard: CreditCard
      EmailAddress: EmailAddress }

We'll also start with a Database module containing a function that can read a User and a PaymentProvider module that contains a function that can charge a CreditCard. They look something like this.

type ISqlConnection =
    abstract Query : string -> 'T

module Database =

    let getUser (UserId id) : User =
        let connection = SqlConnection("my-connection-string")
        connection.Query($"SELECT * FROM User AS u WHERE u.Id = {id}")

type IPaymentClient =
    abstract Charge : CreditCard -> float -> PaymentId

module PaymentProvider =
    let chargeCard (card: CreditCard) amount = 
        let client = new PaymentClient("my-payment-api-secret")
        client.Charge card amount

Our first implementation

Let’s start off with the easiest solution we can think of. We’ll call the database to lookup the user, get the credit card from their profile and call the payment provider to charge it.

let chargeUser userId amount =
    let user = Database.getUser userId
    PaymentProvider.chargeCard user.CreditCard amount

Super easy, given that we already had Database.getUser and PaymentProvider.chargeCard ready to use.

The amount of coupling here is probably making you feel a bit queasy though. Invoking getUser and chargeCard functions directly isn't itself a problem. The problem really lies further down with how those functions themselves are implemented. In both cases they're instantiating new clients like SqlConnection and PaymentClient which creates a few problems:

Hard coded connection strings mean we're stuck talking to the same database instance in all environments.
Connection strings usually contain secrets which are now checked into source control.
Writing unit tests isn't possible because it's going to be calling the production database and payment provider. I suppose that's one way to foot the CI bill when running all of those unit tests 😜

Inversion of Control 🔄

You’re probably not surprised to learn that the solution to this is to invert those dependencies. Inversion of Control (IoC) transcends paradigms, it’s a useful technique in both OOP and FP. It’s just that whereas OOP tends to utilise constructor injection via reflection in FP we'll see there are other solutions available to us.

What’s the easiest IoC technique for a function then? Just pass those dependencies in as parameters. It's like OOP class dependencies, but at the function level.

module Database =
    let getUser (connection: ISqlConnection) (UserId id) : User =
        connection.Query($"SELECT * FROM User AS u WHERE u.Id = {id}")

module PaymentProvider =
    let chargeCard (client: IPaymentClient) (card: CreditCard) amount = 
        client.Charge card amount

let chargeUser sqlConnection paymentClient userId amount =
    let user = Database.getUser sqlConnection userId
    PaymentProvider.chargeCard paymentClient user.CreditCard amount

No surprises there. We’ve just supplied the necessary clients as parameters and passed them along to the function calls that need them. This solution does have it downsides though. The primary one being that as the number of dependencies grows the number of function parameters can become unruly.

On top of this most applications have some degree of layering to them. As we introduce more layers, to break down and isolate the responsibilities of individual functions, we start needing to pass some dependencies down through many layers. This is typical of any IoC solution, once you flip those dependencies it cascades right through all the layers of your application. It’s ~~turtles~~ inverted dependencies all the way down.

A partial solution

What we’d like to avoid is having to explicitly pass those transitive dependencies into functions like chargeUser where they’re not being used directly. On the other hand we don’t want to lose compile time checking by falling back to reflection based dependency injection.

What if we moved those dependency parameters to the end of the function signature? That way we can use partial application to defer supplying them until the last minute, when we're ready to "wire up the application". Let's try with those service modules first.

module Database =
    let getUser (UserId id) (connection: ISqlConnection) : User =
        connection.Query($"SELECT * FROM User AS u  WHERE u.Id = {id}")

module PaymentProvider =
    let chargeCard (card: CreditCard) amount (client: IPaymentClient) = 
        client.Charge card amount

With that we can create a new function that gets the user when passed a connection by simply writing the following.

let userFromConnection: (ISqlConnection -> User) = Database.getUser userId

And we can do a similar thing when charging the card.

let chargeCard: (IPaymentClient -> PaymentId) = PaymentProvider.chargeCard card amount

Alright, let's stick it together and re-write our chargeUser function.

let chargeUser userId amount =
    let user = Database.getUser userId
    // Problem, we haven’t got the user now, but a function that needs a ISqlConnection to get it
    PaymentProvider.chargeCard user.CreditCard amount
    // So the last line can’t access the CreditCard property

It's good, but it's not quite right! We've eliminated the two dependency parameters from the chargeUser function, but it won't compile. As the comment points out we don’t have a User like we need to, but rather a function that has the type ISqlConnection -> User. That's because we've only partially applied Database.getUser and to finish that call off and actually resolve a User, we still need to supply it with a ISqlConnection.

Does that mean we're going to need to pass in the ISqlConnection to chargeUser again? Well if we could find a way to lift up PaymentProvider.chargeCard so that it could work with ISqlConnection -> User instead of just User then we could get it to compile. In order to do this we need to create a new function that takes a ISqlConnection as well as the function to create a User given a ISqlConnection and the amount we want to charge the user.

We don't really have a good name for this function because outside of this context it doesn't really make sense to have a chargeCard function that depends on a ISqlConnection. So what we can do instead is create an anonymous function, a lambda, inside of chargeUser that does this lifting for us.

let chargeUser userId amount: (ISqlConnection -> IPaymentClient -> PaymentId) =
    let userFromConnection = Database.getUser userId

    fun connection ->
        let user = userFromConnection connection
        PaymentProvider.chargeCard user.CreditCard amount

I've annotated the return type of chargeUser to highlight the fact that it's now returning a new function, that when supplied with both dependencies of ISqlConnection and IPaymentClient, will charge the user.

At this point, we've managed to defer the application of any dependencies, but the solution is a bit cumbersome still. If, at a later date, we need to do more computations in chargeUser that require yet more dependencies, then we're going to be faced with even more lambda writing. For instance imagine we wanted to email the user a receipt with the PaymentId. Then we'd have to write something like this.

let chargeUser userId amount =
    let userFromConnection = Database.getUser userId

    fun connection ->
        let user = userFromConnection connection
        let paymentIdFromClient = PaymentProvider.chargeCard user.CreditCard amount

        fun paymentClient ->
            let (PaymentId paymentId) = paymentIdFromClient paymentClient
            let email = EmailBody $"Your payment id is {paymentId}"
            Email.sendMail user.EmailAddress email

😱

The nesting is getting out of hand, the code is becoming tiring to write and the number of dependencies we eventually need to supply to this function is getting unwieldy too. We're in a bit of a bind here.

Binding our way out of a bind

Let's see if we can write a function called injectSqlConnection that will allow us to simplify chargeUser by removing the need for us to write the lambda that supplies the ISqlConnection. The goal of this is to allow us to write chargeUser like this.

let chargeUser userId amount =
    Database.getUser userId
    |> injectSqlConnection (fun user -> PaymentProvider.chargeCard user.CreditCard amount)

So injectSqlConnection needs to take a function that requires a User as the first parameter and a function that can create a User given a ISqlConnection as the second parameter. Let's implement it.

let injectSqlConnection f valueFromConnection =
    fun connection ->
        let value = valueFromConnection connection
        f value

In fact, that function doesn't depend on the ISqlConnection in anyway. It works for any function f that needs a value a which can be created when passed some dependency. So let's just call it inject from now on to acknowledge that it works for any type of dependency.

You just discovered the reader monad 🤓

The inject function is letting us sequence computations that each depend on a wrapped value returned from the last computation. In this case the value is wrapped in a function that requires a dependency. That pattern should look familiar because we discovered it when Grokking Monads. It turns out that we've in fact discovered bind again, but this time for a new monad.

This new monad is normally called Reader because it can be thought of as reading some value from an environment. In our case we could call it DependencyInjector because it's applying some dependency to a function in order to return the value we want. The way to bridge the mental gap here it to just think of dependency injection as a way to read a value from some environment that contains the dependencies.

A little lie 🤥

Actually, the implementation of inject above isn't quite right. If we rewrite the more complex chargeUser, the one that also sends an email, using inject Then we’ll see how it breaks.

let chargeUser userId amount =
    Database.getUser userId
    |> inject (fun user -> PaymentProvider.chargeCard user.CreditCard amount)
    |> inject (fun (PaymentId paymentId) -> 
        let email =
            EmailBody $"Your payment id is {paymentId}"

        let address = EmailAddress "a.customer@example.com"
        Email.sendMail address email)

This actually fails on the second inject. That's because after the first call to inject it returns the following type ISqlConnection -> IPaymentClient -> PaymentId. Now on the second call to inject we have two dependencies to deal with, but our inject function has only been designed to supply one, so it all falls down.

The solution to this is to create a single type that can represent all of the dependencies. Basically we want the chargeUser function to have the signature UserId -> float -> Dependencies -> TransactionId rather than UserId -> float -> ISqlConnection -> IPaymentClient -> TransactionId. If we can do that then we just need to make one small adjustment to inject to make things work again.

let inject f valueThatNeedsDep =
    fun deps ->
        let value = valueThatNeedsDep deps
        f value deps

Notice how this time we also supply deps to f on the final line? It's subtle but it changes the return type of inject to be ('deps -> 'c), where 'deps is the type of dependencies also required by valueThatNeedsDep.

So what's happened here is that we've now constrained the output of inject to be a new function that requires the same type of 'deps as the original function. That's important because it means our dependencies are now unified to a single type and we can happily keep chaining computations that require those dependencies together.

Uniting dependencies 👭

There are several ways to unite all of the dependencies together in a single type, such as explicitly creating a type with fields to represent each one. One of the neatest with F# though is to use inferred inheritance. Inferred inheritance means we let the compiler infer a type that implements all of the dependency interfaces we require.

In order to use inferred inheritance we need to add a # to the front of the type annotations for each dependency. Let's make that change in the Database and PaymentProvider modules to see what that looks like.

module Database =
    let getUser (UserId id) (connection: #ISqlConnection) : User =
    // Implementation of getUser

module PaymentProvider =
    let chargeCard (card: CreditCard) amount (client: #IPaymentClient): TransactionId =
    // Implementation of chargeCard

All we've changed is to write #ISqlConnection instead of ISqlConnection and #IPaymentClient instead of IPaymentClient. From this F# can union these types together for us when it encounters something that needs to satisfy both constraints. Then at the root of the application we just have to create an object that implements both interfaces in order to satisfy the constraint.

The upshot of this is that F# infers the type signature of chargeUser to be UserId -> float -> ('deps -> unit) and it requires that 'deps inherit from both ISqlConnection and IPaymentProvider.

A final improvement

We've pretty much reached our stated goal now of eliminating all of the explicit dependency passing between functions. However, I think it's still a bit annoying that we have to keep creating lambdas to access the values like user and paymentId when calling inject to compose the operations. We've seen before, in Grokking Monads, Imperatively, that it's possible to write monadic code in an imperative style by using computation expressions.

All we have to do is create the computation expression builder using the inject function we wrote earlier, as that's our monadic bind. We'll call this computation expression injector because that's more relevant to our use case here, but typically it would be called reader.

type InjectorBuilder() =
    member _.Return(x) = fun _ -> x
    member _.Bind(x, f) = inject f x
    member _.Zero() = fun _ -> ()
    member _.ReturnFrom x = x

let injector = InjectorBuilder()

let chargeUser userId amount =
    injector {
        let! user = Database.getUser userId
        let! paymentId = PaymentProvider.chargeCard user.CreditCard amount
        let email =
            EmailBody $"Your payment id is {paymentId}"

        return! Email.sendMail user.Email email
    }

😍
By simply wrapping the implementation in injector { } we’re basically back to our very first naïve implementation, except this time all of the control is properly inverted. Whilst the transitive dependencies are nicely hidden from sight they’re still being type checked. In fact if we added more operations to this later that required new dependencies then F# would automatically add them to the list of required interfaces that must be implemented for the 'deps type in order to finally invoke this function.

When we're finally ready to call this function, say at the application root where we have all of the config to hand in order to create the dependencies, then we can do it like this.

type IDeps =
    inherit IPaymentClient
    inherit ISqlConnection
    inherit IEmailClient

let deps =
    { new IDeps with
        member _.Charge card amount =
            // create PaymentClient and call it

        member _.SendMail address body =
            // create SMTP client and call it

        member _.Query x =
            // create sql connection and invoke it 
            }

let paymentId = chargeUser (UserId "1") 2.50 deps

Where we use an object expression to implement our new IDeps interface on the fly so that it satisfies all of the inferred types required by chargeUser.

Quick recap 🧑‍🎓

We started off by trying to achieve inversion of control to remove hardcoded dependencies and config. We saw that doing this naïvely can lead to an explosion in the number of function parameters and that it can cascade right through the application. In order to solve this we started out with partial application to defer supplying those parameters until we were at the application root where we had the necessary config to hand. However, this solution meant that we couldn't easily compose functions that required dependencies and it was even more tricky when they required different types of dependencies.

So we invented an inject function that took care of this plumbing for us and realised that we'd actually discovered a new version of bind and hence a new type of monad. This new monad is commonly known as Reader and it's useful when you need to compose several functions that all require values (or dependencies) that can be supplied by some common environment type.

If you want to use the reader monad in practice then you can find an implementation that's ready to roll in the FSharpPlus library.

Appendix

The format of the reader monad is often a little different in practice to how it was presented here. Expand the section below if you want more details.

Usually when implementing the reader monad we create a new type to signify it, called Reader, in order to distinguish it from a regular function type. I left it out above because it's not an important detail when it comes to grokking the concept, but if you're looking to use the technique then you'll likely encounter it in this wrapped form. It's a trivial change and the code would just look like this instead.

type Reader<'env, 'a> = Reader of ('env -> 'a)

module Reader =
    let run (Reader x) = x
    let map f reader = Reader((run reader) >> f)

    let bind f reader =
        Reader
            (fun env ->
                let a = run reader env
                let newReader = f a
                run newReader env)

    let ask = Reader id

type ReaderBuilder() =
    member _.Return(x) = Reader (fun _ -> x)
    member _.Bind(x, f) = Reader.bind f x
    member _.Zero() = Reader (fun _ -> ())
    member _.ReturnFrom x = x

let reader = ReaderBuilder()

let chargeUser userId amount = 
    reader {
        let! (sqlConnection: #ISqlConnection) = Reader.ask
        let! (paymentClient: #IPaymentClient) = Reader.ask
        let! (emailClient: #IEmailClient) = Reader.ask
        let user = Database.getUser userId sqlConnection
        let paymentId = PaymentProvider.chargeCard user.CreditCard amount paymentClient

        let email =
            EmailBody $"Your payment id is {paymentId}"

        return Email.sendMail user.Email email emailClient
    }

The return type of chargeUser is now Reader<'deps, unit> where 'deps will have to satisfy all of those interfaces marked with # as before.

I've also had to use Reader.ask to actually get dependencies out of the environment in this case. The reason for this is because functions like Database.getUser do not return a Reader in their current form. We could create a Reader on the fly by doing Reader (Database.getUser userId) but sometimes that can also be cumbersome, especially if we're working with client classes rather than functions, which is often the case. So having ask in our toolkit can be a nice way to just get hold of the dependency and use it explicitly in the current scope.

Grokking Traversable

Matt Thornton — Fri, 23 Apr 2021 11:14:02 +0000

Once you've grokked traversable's you'll wonder how you ever lived without them. Trying to gain intuition about them by staring at the type signature never brought me much joy. So in this post we'll take a different approach and invent them ourselves by solving a real problem. This will help us get to that "aha" moment where we finally understand how they work and when to use them.

The scenario

Imagine we're working for an e-commerce site where we sell one-time offers, such that when all the stock is sold we never have anymore. When a user places an order we must check the stock levels. If there is availability we temporarily reserve the amount they requested before letting them proceed to the checkout.

Our specific task is to write a createCheckout function that will take a Basket and try to reserve the items in it. If they can be successfully reserved it will create a Checkout which includes the total price of the items along with other metadata we might need to take the payment.

Our domain model looks something like this.

type BasketItem = 
    { ItemId: ItemId
      Quantity: float }

type Basket = 
    { Id: BasketId; 
      Items: BasketItem list }

type ReservedBasketItem =
    { ItemId: ItemId
      Price: float }

type Checkout = 
    { Id: CheckoutId
      BasketId: BasketId
      Price: float }

The createCheckout function will return Checkout option. It will return Some if all of the items are available and None if any of them aren't. A better implementation would return Result and detail the specific errors, but we'll use option to keep the example simple.

let createCheckout (basket: Basket): Checkout option

Fortunately for us, someone else has already written a function which can reserve a BasketItem if it is in stock, which looks like this.

let reserveBasketItem (item: BasketItem): ReservedBasketItem option

Again, this will return None if there are not enough items in stock.

Our first implementation

So it seems that all we need to do is write a function that calls reserveBasketItem for each item in the basket. If they all succeed then it calculates the total price in order to create the Checkout. Let's try it.

let createCheckout basket =
    let reservedItems =
        basket.Items |> List.map reserveBasketItem

    let totalPrice =
        reservedItems
        |> List.sumBy (fun item -> item.Price)

    { Id = CheckoutId "some-checkout-id"
      BasketId = basket.Id
      Price = totalPrice }

Here we're just mapping over the items in the basket to reserve each one and then summing their individual prices to get the total basket price. Seems straight forward, except that's not going to compile, because it's not quite right.

The problem is that reservedItems has the type list<option<ReservedBasketItem>> but we need it to be option<list<ReservedBasketItem>>, where it is None if any one of the reservations fail. That way we'd only be able to calculate the total price and create the Checkout if all of the items are available. Let's imagine we've written such a function called reserveItems that does return this type instead and updated createCheckout to use it.

let reserveItems (items: BasketItem list): option<list<ReservedBasketItem>>

let createCheckout basket =
    let reservedItems = basket.Items |> reserveItems

    reservedItems
    |> Option.map
        (fun items ->
            { Id = CheckoutId "some-checkout-id"
              BasketId = basket.Id
              Price = items |> List.sumBy (fun x -> x.Price) })

That's better! Now if the items are all reserved and reservedItems returns Some then we can access the list of ReservedBasketItem and use them to create the Checkout. If any of the items can't be reserved then reservedItems returns None and the Option.map just short circuits meaning createCheckout will also return None, as we wanted.

So we've reduced the task to implementing reserveItems. We've already seen that we can't just call List.map reserveBasketItem because that gives us a list<option<ReservedBasketItem>> and so the list and the option are the wrong way around. We need a way to invert them.

An invertor 🙃

Let's invent a function called invert that converts list<option<ReservedBasketItem>> into option<list<ReservedBasketItem>>. If we can do that then we can implement reserveItems like this.

let invert (reservedItems: list<option<ReservedBasketItem>>) : option<list<ReservedBasketItem>>

let reserveItems (items: BasketItem list) : option<list<ReservedBasketItem>> =
    items 
    |> List.map reserveBasketItem 
    |> invert

In order to implement invert let's start off by pattern matching on the list.

let invert (reservedItems: list<option<ReservedBasketItem>>) : option<list<ReservedBasketItem>> =
    match reservedItems with
    | head :: tail -> // do something when the list isn't empty
    | [] -> // do something when the list is empty

So we've got two cases to deal with, when the list has at least one item and when the list is empty. Let's start with the base case because it's trivial. If the list is empty then it doesn't contain any failures, so we should just return Some [].

In the non empty case then we've got to do something with head which is a ReservedBaskedItem option and tail which is a list<option<ReservedBasketItem>>. Well we know that our goal is to turn list<option<ReservedBasketItem>> into option<list<ReservedBaskedItem>>, so we can just recursively call invert on the tail to do this.

let rec invert (reservedItems: list<option<ReservedBasketItem>>) : option<list<ReservedBasketItem>> =
    match reservedItems with
    | head :: tail -> 
        let invertedTail = invert tail
        // Need to recombine the head and the inverted tail
    | [] -> Some []

Now we just need a way to combine a ReservedBasketItem option with a option<list<ReservedBasketItem>>. If neither of these were wrapped in an option then we would just "cons" them using the :: operator, so let's write a consOptions function which does this but for option arguments.

let consOptions (head: option 'a) (tail: option<list<'a>>): option<list<'a>> = 
    match head, tail with 
    | Some h, Some t -> Some (h :: t) 
    | _ -> None

Nothing too complicated going on here. Simply check if both the head and tail are Some and if so cons them with :: operator and wrap that in a Some. Otherwise if either one is None then return None.

Putting it all together we can finally implement invert like this.

let rec invert (reservedItems: list<option<'a>>) : option<list<'a>> =
    match reservedItems with
    | head :: tail -> consOptions head (invert tail)
    | [] -> Some []

We've also been able to make it completely generic on the type inside the list as it doesn't depend on ReservedBasketItem in any way.

An Applicative clean up 🧽

If you're familiar with applicatives, perhaps because you've followed this series and read Grokking Applicatives then you might have spotted that consOptions looks sort of like a specialised version of apply. What consOptions is trying to do is take some values that are wrapped in options and apply them to a function, in this case cons.

Let's make use of apply and clean up invert.

let rec invert list =
    // An alias for :: so we can pass it as a function below
    let cons head tail = head :: tail

    match list with
    | head :: tail -> Some cons |> apply head |> apply (invert tail)
    | [] -> Some []

In fact, a proper Applicative instance should also have a pure function. All pure does is create a default value for the Applicative. In the case of option pure is just Some. Let's use pure to replace the Some uses.

let rec invert list =
    let cons head tail = head :: tail

    match list with
    | head :: tail -> pure cons |> apply head |> apply (invert tail)
    | [] -> pure []

This might not seem like much of a change, but what we've done is eliminate all direct dependencies on option. In theory this could work with any applicative, such as Result or Validation and what it would do is go from list<Applicative<_>> to Applicative<list<_>>. In practice however F# doesn't quite allow such an abstraction and so we have to create a version of invert for each applicative type we want to use it with.

You can technically get around this with statically resolved type parameters. I would recommend checking out FSharpPlus if you want this abstraction rather than rolling it yourself though.

You just discovered `sequence` 👏

invert is usually called sequence and it's one of the functions that a Traversable type gives us. As we can see sequence takes a collection of wrapped values like an option and turns it into wrapped collection instead. You can think of sequence as flipping the two types over.

sequence works for all sorts of other type combinations too. For example you can take a list<Result<'a>> and flip it into a Result<list<'a>>. You can even use it with different collection types and some that don't even seem like typical collections, for instance you could go from Result<option<'a>, 'e> to option<Result<'a, 'e>>.

Test yourself on `sequence` 🧑‍🏫

See if you can implement sequence for list<Result<_>> to Result<list<_>>.

Solution

module Result =
    let apply a f =
        match f, a with
        | Ok g, Ok x -> g x |> Ok
        | Error e, Ok _ -> e |> Error
        | Ok _, Error e -> e |> Error
        | Error e1, Error _ -> e1 |> Error

    let pure = Ok

let rec sequence list =
    let cons head tail = head :: tail

    match list with
    | head :: tail -> Result.pure cons |> Result.apply head |> Result.apply (sequence tail)
    | [] -> Result.pure []

That's right, it's exactly the same as for the list<option<_>> providing we use the applicative Result.apply and Result.pure functions for Result. I've included their definitions too in a Result module above.

There's still more land to discover 🏞

Let's go back to our original program and see how it looks with our new sequence discovery.

let createCheckout basket =
    let reservedItems = 
        basket.Items 
        |> List.map reserveBasketItem 
        |> sequence

    reservedItems
    |> Option.map
        (fun items ->
            { Id = CheckoutId "some-checkout-id"
              BasketId = basket.Id
              Price = items |> Seq.sumBy (fun x -> x.Price) })

It's pretty good, but we have to make two passes over the basket.Items when creating reservedItems. In the first pass we try and reserve each item and then in the second pass we combine all of those reservations together to determine whether the whole operation succeed or not. It would be nice if we could do that in one go.

Let's see if we can do it all within sequence. That means that we'll need to pass the reserveBasketItem function to sequence and we'll end up with the following signature.

let sequence (f: 'a -> 'b option) (list: 'a list): option<list<'b>>

So we start with a list and we want to apply the function f to each element of it. Although, rather than just mapping over the list and returning list<option<'b>> we want to accumulate all of the option values into a single option<list<'b>> where it is None if for any element f produces a None.

let rec sequence f list =
    let cons head tail = head :: tail

    match list with
    | head :: tail -> Some cons |> apply (f head) |> apply (sequence tail f)
    | [] -> Some []

This is basically the same as before, except now we just apply f to head and pass it into the recursive call in order to also transform the tail elements. All we've done is combine the operation that generates the option values with the act of combining them together into a single option of the list.

You just discovered `traverse` 🙌

It turns out we typically call the function traverse when we combine both the sequencing and the mapping at the same time. So a Traversable actually has two functions associated with it called sequence and traverse. In fact, sequence is just a special case of traverse where we supply the identity function, id, for f. So we could actually write it like this.

let sequence = traverse id

With traverse in place we can finally finish off our task and write checkoutBasket nicely like this.

let createCheckout basket =
    basket.Items 
    |> traverse reserveBasketItem
    |> Option.map
        (fun items ->
            { Id = CheckoutId "some-checkout-id"
              BasketId = basket.Id
              Price = items |> Seq.sumBy (fun x -> x.Price) })

Test yourself on `traverse` 🧑‍🏫

See if you can implement traverse when the input is option<'a> and the function is 'a -> Result<'b, 'c>, so that it returns a Result<option<'b>, 'c>.

Solution

module Result =
    let apply a f =
        match f, a with
        | Ok g, Ok x -> g x |> Ok
        | Error e, Ok _ -> e |> Error
        | Ok _, Error e -> e |> Error
        | Error e1, Error _ -> e1 |> Error

    let pure = Ok

let traverse f opt =
    match opt with
    | Some x -> Result.pure Some |> Result.apply (f x)
    | None -> Result.pure None

Here I've included the definitions of apply and pure for Result and then implemented traverse using those. Hopefully this makes it clearer which parts of the traverse operation relate to the outer option type and which ones relate to the inner Result type.

One concrete use case for this transformation might be if we're trying to write a parser. The parser function might say parse string into Result<int, ParseError> but we have to hand a string option. Of course we could pattern match on the option ourselves and then only run the parser in the Some case, but we could also write myOptionalValue |> traverse parseInt.

Another interesting case is when we're dealing with a regular function, say string which just converts the argument to a string. See if you can figure out what traverse should look like in this case. Specifically, if we want to write [1; 2; 3] |> traverse string and have it output ["1"; "2"; "3"].

Solution

module Identity = 
    let apply a f = f a
    let pure f = f

let rec traverse list f =
    let cons head tail = head :: tail

    match list with
    | head :: tail -> Identity.pure cons |> Identity.apply (f head) |> Identity.apply (traverse tail f)
    | [] -> Identity.pure []

I've written this in the same style as the others by extracting an Identity functor/applicative. Identity is actually the degenerate case for an applicative because all apply does is call the function with the argument and all pure does is return the function unaltered. So there is no wrapping going on like with the other applicatives. This is interesting though because traverse now has the type list<'a> -> ('a -> 'b) -> list<'b>, which you might recognise from Grokking Functors as map. So map is actually a special case of traverse when the inner type is just the Identity applicative.

Spotting `Traversable` in the wild 🐾

Whenever you've got some collection of values wrapped in something like option or Result and what you actually need is an option<list<'a>> or Result<list<'a>, 'e> etc then sequence is probably what you need to use. Similarly, if you have to run a computation over a collection that produces wrapped values then you can use traverse and combine the mapping and flipping into one operation.

Warning, two types of error handling ahead ⚠️

When we're sequencing a list<option<_>> we only need to know that at least one of the elements is None in order to return None. However, when working with something like list<Result<'a, 'e>> then we might actually care about gathering up all of the errors. As we pointed out in Grokking Applicative Validation there can be applicative instances that either short circuit on the first error or accumulate all errors. The same applies here with Traversable. Let's quickly run some experiments in the F# REPL with FSharpPlus to see how it handles things.

> [Ok 1; Error "first error"; Error "second error"] |> sequence;;
val it : Result<int list, string> = Error "first error"

[Success 1; Failure ["first error"]; Failure ["second error"]] |> sequence;;
val it : Validation<string list, int list> =
  Failure ["first error"; "second error"]

In the first case, when using Result we see that it just returns the first error it encounters, while with Validation it actually accumulates all the errors for us.

What did we learn 🧑‍🎓

Traversable is more powerful version of map that is particularly useful when we have a computation that either needs to be run (or has already been run) over a list of values and we want to treat it as a failure if any single one fails. We can also grok it by realising that it flips the two outer types over. We use traverse when we still need to run the computation and sequence when we've been given the list of computation results instead.

Grokking Applicative Validation

Matt Thornton — Fri, 16 Apr 2021 13:28:56 +0000

Previously in Grokking Applicatives we discovered Applicatives and more specifically invented the apply function. We did this by considering the example of validating the fields of a credit card. The apply function allowed us to easily combine the results we obtained from validating the number, expiry and CVV individually into a Result<CreditCard> that represented the validation status of an entire CreditCard. You might also remember we somewhat glossed over the error handling when multiple fields were invalid. We took the easy road and just returned the first error that occurred.

An unhappy customer 😡

In the spirit of agile we decided to ship our previous implementation, because, well it was better than nothing. A short while later, customers start complaining. All the complaints are along these lines.

"I entered my credit card details on your site and it took three attempts before it was finally accepted. I submitted the form and each time it gave me a new error. Why couldn't you tell me about all the errors at once?"

To see this more clearly consider a customer that enters the following data, in JSON form.

{
    “number”: “a bad number”,
    “expiry”: “invalid expiry”,
    “cvv”: “not a CVV”
}

The first time they submit the form they get an error like ”’a bad number’ is not a valid credit card number”. So they fix that and resubmit. Then they get a message like ”’invalid expiry’ is not a valid expiry date”. So they fix that and submit a third time and still receive an error along the lines of ”’not a CVV’ is not a valid CVV”. Pretty annoying!

We should be able to do better and return all of the errors at once. We even previously pointed out that all of the field level validation functions were independent of each other. So there was no good reason not to run all of the functions and aggregate the errors if there were any, we were just being lazy!

A better validation Applicative 💪

Let's start by updating the signature of validateCreditCard to signify our new desire to return all the validation errors that we find.

let validateCreditCard (card: CreditCard): Result<CreditCard, string list>

The only change here is that we’re now returning a list of error messages rather than a single one. How should we update our implementation to satisfy this new signature?

Let’s return to the apply function that we defined before and see if we can just fix it there. It would be very nice if all we had to do was modify apply and leave validateCreditCard otherwise unchanged.

For reference here’s the apply function that we wrote last time, the one that returns the first error it encounters.

let apply a f =
    match f, a with
    | Ok g, Ok x -> g x |> Ok
    | Error e, Ok _ -> e |> Error
    | Ok _, Error e -> e |> Error
    | Error e1, Error _ -> e1 |> Error

We can see from this that it’s only the final case where we have multiple errors to deal with and so it’s only there that we need to fix things. The simplest fix is to just concatenate both errors. This has the effect of building up a list of errors each time we call apply with invalid data. Let’s see what that looks like then.

let apply a f =
    match f, a with
    | Ok g, Ok x -> g x |> Ok
    | Error e, Ok _ -> e |> Error
    | Ok _, Error e -> e |> Error
    | Error e1, Error e2 -> (e1 @ e2) |> Error

That was easy, we just used @ to concatenate the two lists in the case where both sides were Error. Everything else remained the same.

Let’s walk through validating the credit card step-by-step with the example of the bad data that the customer was supplying earlier. First we call Ok (createCreditCard) |> apply (validateNumber card.Number). This hits the third case of the pattern match in apply because f is Ok, but the argument a is Error. That returns us something like an Error [ “Invalid number” ], but whose type is still Result<string -> string -> CreditCard, string list>.

We then pipe this like |> apply (validateExpiry card.Expiry). This hits the final case in the pattern match because now both f and a are Error. This means the @ operator is used to concat the errors together to create something like Error [ “Invalid expiry”; “Invalid number” ]. The type of which is now Result<string -> CreditCard, string list> because we now just need to supply a CVV to finish creating the CreditCard.

So in the final step we do exactly that and pipe this result like |> apply (validateCvv card.Cvv). Just like the last step we hit the case where both f and a are Error and so we concat them. Now we’ve got something with the type Result<CreditCard, string list> as we wanted with a value like Error [ “Invalid CVV”; “Invalid expiry”; “Invalid number” ].

A small compile time error

You might have spotted that we’ve actually changed the type of the apply function now. By using the @ operator F# has inferred that the errors must be a list. So now the signature of apply is Result<T, E list> -> Result<T -> V, E list> -> Result<V, E list>.

We now have an apply that works for Result<T, E list>. That is, it works for any results where the errors are contained in a list, rather than being single values like a string. There are a couple of interesting points to make about this:

The errors in the list can be any type, providing they’re all of the same type.
All of our validated results must now have a list of errors if we want to use them with apply.

Point 1 is useful because it allows us to model our errors in more meaningful ways than just using strings. Although for the rest of this post we’ll keep using string in order to keep it simple. Modelling errors deserves a blog post of its own.

Point 2 however causes us a little problem we have to solve here. Our original field level validation functions are still returning Result<string, string> so they no longer work with our new version of apply.

We have two choices when it comes to fixing this issue. We could keep the functions as they are and transform their outputs by wrapping the error, if it exists, of the result in a list. Which might look something like this.

let validateCreditCard (card: CreditCard): Result<CreditCard, string list> =
    let liftError result =
        match result with
        | Ok x -> Ok x
        | Error e -> Error [ e ]
    Ok (createCreditCard)
    |> apply (card.Number |> validateNumber |> liftError)
    |> apply (card.Expiry |> validateExpiry |> liftError)
    |> apply (card.Cvv |> validateCvv |> liftError)

The other choice is to update those field validation functions so that they return Result<string, string list> as required. It might be tempting to take the first choice and if we had no control over those functions we’d have to do that. However, by letting those field level functions return a list we give them the flexibility to do more complex validation and potentially indicate multiple errors.

For instance the validateNumber function could indicate both a problem with the length and the presence of invalid characters like this.

let validateNumber number: Result<string, string list> =
    let errors = 
        if String.length num > 16 then
            [ "Too long" ]
        else
            []
    let errors = 
        if num |> Seq.forall Char.IsDigit then
            errors
        else 
            "Invalid characters" :: errors

    if errors |> Seq.isEmpty then
        Ok num
    else
        Error errors

Using Result<T, E list> throughout gives us a more composable and flexible api that allows us to refactor the errors returned from those functions in the future without affecting the rest of the program.

So given that they’re functions in our domain, then we’ll take that approach. Let’s give that a try and see what it looks like all together when using this new version of apply.

let validateNumber num: Result<string, string list> =
    if String.length num > 16 then
        Error [ “Too long” ]
    else
        Ok num

let validateExpiry expiry: Result<string, string list> =
    // validate expiry and return all errors we find

let validateCvv cvv: Result<string, string list> =
    // validate cvv and return all cvv errors we find

let validateCreditCard (card: CreditCard): Result<CreditCard, string list> =
    Ok (createCreditCard)
    |> apply (validateNumber card.Number)
    |> apply (validateExpiry card.Expiry)
    |> apply (validateCvv card.Cvv)

Lovely job! Apart from a couple of small changes to lift the errors up into lists within validateNumber etc the rest has stayed the same. In particular, the body of validateCreditCard is completely unchanged.

Do I have to use list for the errors

The only requirement we’ve placed on the error type is that we can use the @ operator to concat the errors together. So as long as the errors are concat-able then we can use a different type here. The fancy category theory name for this is a semi-group. A semi-group is anything that has at least a concat operator defined for it. A common type to use here is a NonEmptyList, because we know that if the result is an Error then they’ll be at least one item in the list.

A tale of two applicatives 📗

We’ve seen two implementations of apply for Result now. Can we have both? Unfortunately not really, at least not both defined in the Result module of F#. In order to do this F# would have to be able to decide which one to use based on whether the error type supported concat, which might not even be obvious without an explicit type annotation. Even then we might get undesired results because strings support concat, but it’s unlikely we want to concat the individual error messages into one long string.

How should we decide which one is correct then? Well, we don’t have to. We can define another type called Validation which has a Success case and a Failure case, similar to Ok and Error for Result. The difference is that for Validation we can define apply using the version we’ve created in this post which accumulates errors and for Result use the apply function that short circuits and returns the first error, that we saw in the last post. Luckily for us the excellent FSharpPlus library has already done exactly that.

What did we learn 🧑‍🏫

We’ve seen that applicatives are a great tool to have at our disposal when writing validation code. They allow us to write validation functions for each field and then easily compose these to create functions for validating larger structures made up of those fields.

We’ve also seen that whilst applicative computations are usually independent of each other there’s nothing to guarantee that a particular implementation of apply will make full use of this. Specifically, when working with validation we want to make sure that apply accumulates all errors and so we should make sure to use a type like Validation from FSharpPlus to get this behaviour.

Grokking Applicatives

Matt Thornton — Fri, 09 Apr 2021 15:42:57 +0000

Applicatives are perhaps the less well-known sibling of the monad, but are equally important and solve a different, but related problem. Once you've discovered them you'll find they're a useful tool for writing code where we don't care about the order of the computations.

In this post we're going to grok applicatives by "discovering" them through a worked example.

Small F# primer

Skip this if you've got basic familiarity with F#.

It should be easy enough to follow along if you've not used F# before, you'll just need to understand the following bits:

F# has a Result<T, E> type. It represents the result of a computation that might fail. It has a Ok case constructor which contains a value of type T and a Error case constructor which contains an error value of type E.
We can pattern match on a Result like so:

match aResult with
| Ok x -> // expression based on the good value x
| Error e -> // expression based on the error value e

The Scenario

Let's say we've been asked to write a function that validates a credit card, which is modelled like this.

type CreditCard =
    { Number: string
      Expiry: string
      Cvv: string }

The function we need to implement is

let validateCreditCard (creditCard: CreditCard): Result<CreditCard, string>

Happily, someone else has already written some functions for validating a credit card number, expiry and CVV. They look like this.

let validateNumber number: Result<string, string> =
    if String.length number > 16 then
        Error "A credit card number must be less than 16 characters"
    else
        Ok number

let validateExpiry expiry: Result<string, string> =
    // Some validation checks for an expiry

let validateCvv cvv: Result<string, string> =
   // Some validation checks for a CVV

The details of the validation checks aren't crucial here, I've just shown a basic example for the card number, but in reality they’d be more complex. The main thing to take note of is that each function takes an unvalidated string and returns a Result<string, string> which indicates whether or not the value is valid. If the value is invalid then it will return a string containing the error message.

Our first attempt

What luck! All we've got to do is compose these functions somehow to validate a credit card instance. Let's give it a go!

let validateCreditCard card =
    let validatedNumber = validateNumber card.Number
    let validatedExpiry = validateExpiry card.Expiry
    let validatedCvv = validateCvv card.Cvv

    { Number = validatedNumber
      Expiry = validatedExpiry
      Cvv = validatedCvv }

Hmmm, that doesn't compile. The problem is that we're trying to pass Result<string, string> to the fields of the CreditCard at the end, but the fields of CreditCard have type string.

I spy, with my little eye, something beginning with M 👀

Seeing as we've now Grokked Monads we might notice that we could solve our problem using monads. Each validation functions takes a string and lifts it up to a Result<string, string> and we seemingly want to chain several of these functions together. We saw in 'Grokking Monads' that we can use bind for exactly this type of chaining. For reference, bind for a Result would look like this.

let bind f result =
    match result with
    | Ok x -> f x
    | Error e -> Error e

So let's try and write validateCreditCard as a chain using bind.

let validateCard card =
    validateNumber card.Number
    |> bind (validateExpiry card.Expiry)
    |> bind (validateCvv card.Cvv)
    |> fun number expiry cvv ->
        { Number = number
          Expiry = expiry
          Cvv = cvv }

Looks neat, but it still doesn't compile!

The calls to bind expect a function that take as input the validated value from the previous computation. In the first case it would be the validated number being passed to the validateExpiry function. However, validateExpiry doesn't need the validated number as input, it needs the unvalidated expiry, but we do need to keep track of that validated number somehow until the end so that we can use it to build the valid CreditCard instance.

It is possible to remedy these points by accumulating these intermediate validation results as we go.

let validateCard card =
    validateNumber card.Number
    |> bind
        (fun number ->
            validateExpiry card.Expiry
            |> Result.map (fun expiry -> number, expiry))
    |> bind
        (fun (number, expiry) ->
            validateCvv card.Cvv
            |> Result.map
                (fun cvv ->
                    { Number = number
                      Expiry = expiry
                      Cvv = cvv }))

Yikes! 😱 Pretty messy and definitely more confusing than we'd like. At each stage we have to create a lambda that takes as input the validated values from the previous step, validates one more piece of data and then accumulates it all in a tuple until we finally have all of the bits to build the whole CreditCard.

Our simple validation task has been lost in a sea of lambdas and intermediate tuple objects. Imagine the mess if we had even more fields on the CreditCard that required validation. What we need is a solution that avoids us having to create so many intermediate objects.

Applicatives to the rescue 🦸

Another way to accumulate values is through partial application. This allows us to take a function of n arguments and return a function of n - 1 arguments. For example let's define a function called createCreditCard that works with plain string inputs.

let createCreditCard number expiry cvv =
    { Number = number
      Expiry = expiry
      Cvv = cvv }

We can progressively accumulate the values by applying them to the function.

let number = "1234"
let numberApplied = createCreditCard number

numberApplied is a function with the signature string -> string -> CreditCard or to name those parameters expiry -> cvv -> CreditCard. So we've been able to "store" the number for later without having to create an intermediate tuple.

So let's invent a function called apply that makes use of partial application but for values that are wrapped in some other structure such as Result and put it before each argument like this.

let validateCreditCard card: Result<CreditCard, string> =
    Ok (createCreditCard)
    |> apply (validateNumber card.Number)
    |> apply (validateExpiry card.Expiry)
    |> apply (validateCvv card.Cvv)

You might be wondering why we need to wrap createCreditCard in Ok. That's because this function is going to return Result<CreditCard, string>, therefore apply must return Result. This means that in order to chain them together it must also accept a Result as input. Therefore we need to just initially "lift" the createCardFunction up into a Result to kick off the chain with the right type.

It might seem strange to have a Result of a function, but remember that we're going to be using partial application to gradually accumulate the state after each call to apply. So really what we're doing here is starting with an empty container that is Ok and progressively filling it with data, checking at each step whether the new data is Ok or not.

As usual we can let the types guide us in writing this function. At each stage of the chain what we need to do is take two arguments. The first is a Result<T, E> and the second is a Result<(T -> V), E>. We want to try and unwrap both the value of type T and the function of type T -> V and if they're both Ok, we can apply the value to the function.

The type T -> V might look like a function of only one argument, but there's nothing to say that V can't be another function itself. So whilst this might look like it only works when the function input has a single argument, in fact it works for functions of any number of arguments, providing that the first argument matches the type of value contained in the Result we wish to apply.

So apply should have the signature Result<T, E> -> Result<(T -> V), E> -> Result<V, E>, but we'll see that with just that, rather abstract, information it's quite straight forward to implement.

let apply a f =
    match f, a with
    | Ok g, Ok x -> g x |> Ok
    | Error e, Ok _ -> e |> Error
    | Ok _, Error e -> e |> Error
    | Error e1, Error _ -> e1 |> Error

Basically, all we can really do is pattern match on both the function f and the argument a and then do the case analysis, which gives us four cases to scrutinise. In the first case both values are Ok so we simply unwrap them both and apply the value to the function and then repackage in Ok. In all of the other cases we have at least one error so we return that. The final case is interesting because we have two errors, we decide to just keep the first one here.

Testing it out

Let's test the apply function in the FSharp repl to make sure it behaves correctly. It will also help us improve our understanding.

> Ok (createCreditCard) 
-    |> apply ((Ok "1234"): Result<string, string>) 
-    |> apply (Ok "08/19") 
-    |> apply (Ok "123")

val it : Result<CreditCard,string> = Ok { Number = "1234"
                                          Expiry = "08/19"
                                          Cvv = "123" }

Looks good, if all the inputs are valid then we get a valid CreditCard. Let's see what happens when one of the inputs is bad.

> Ok (createCreditCard) 
-    |> apply (Ok "1234") 
-    |> apply (Ok "08/19") 
-    |> apply (Error "Invalid CVV")

val it : Result<CreditCard,string> = Error "Invalid CVV"

Excellent, just as we'd hoped. Finally, what if we have multiple bad inputs.

> Ok (createCreditCard) 
-    |> apply (Error "Invalid card number") 
-    |> apply (Ok "08/19") 
-    |> apply (Error "Invalid CVV")

val it : Result<CreditCard,string> = Error "Invalid card number"

Again it's what we'd designed for. Here it's failed on the first bad input. Many of you might rightly be wondering whether this is desirable, surely it would be better to return all the errors. In the next post we'll see how we can do that.

You just discovered applicatives 👏

The apply function is what makes something applicative. Hopefully by seeing the problem that they solve you understand them more deeply and intuitively than by just staring at the type signature of apply and reading about the applicative laws.

Applicatives are similar to monads in that they provide a means to combine the outputs of several computations, but applicatives are useful when those computations are independent, whereas with monads we take the result of one and use it as the input of another.

A bit more tidy up 🧹

If you don't like the fact that you have to wrap the createCreditCard function in Ok, then we can get rid of this. If you've ready Grokking Functors then you'll see that map can be defined for Result to make it a functor. We know that map takes a function and calls it the contents of the Result if it's Ok. So we can actually use this to kick off the chain like so.

let validateCard card =
    (validateNumber card.Number)
    |> Result.map createCreditCard
    |> apply (validateExpiry card.Expiry)
    |> apply (validateCvv card.Cvv)

That's a little awkward though because the flow seems to be all mixed up with the createCreditCard function in the middle of the 3 arguments. To remedy this it's quite common to define an <!> infix operator for map, which then reads .

let validateCard card =
    createCreditCard 
    <!> validateNumber card.Number
    |> apply (validateExpiry card.Expiry)
    |> apply (validateCvv card.Cvv)

Finally, it's common to also use <*> for apply which gives us this.

let validateCard card =
    createCreditCard 
    <!> validateNumber card.Number
    <*> validateExpiry card.Expiry
    <*> validateCvv card.Cvv

Don't be put off by this if you find it confusing, they're just symbols. Grokking applicatives is about understanding how apply works and what problems it solves, not about this slightly esoteric syntax. I only point it out here as it's fairly common to see them used in this way.

Spotting Applicatives in the wild 🐗

Any time you find yourself needing to call a function with several arguments, but the values you have to hand are wrapped in something like a Result then applicatives are likely to help you solve the problem.

More types than just Result can be made applicative too, all we have to do is define the appropriate apply function for it. For example we could define it for option. As we hinted at above, there might be more than one way to implement such a function too, so make sure you've chosen the one with the semantics you need.

Test yourself 🧑‍🏫

See if you can write apply for the option type. The answers are below, no peeking until you've had a go first!

Option solution

let applyOpt a f =
    match f, a with
    | Some g, Some x -> g x |> Some
    | None, _
    | _, None -> None

This is just like for Result but because we have no additional information in the None case we can just combine all the patterns that contain at least one None into a single expression that returns None.

What did we learn? 🧑‍🎓

By defining an apply function we were able to apply arguments that were wrapped in a Result to a function expecting regular string arguments. We saw how doing this allowed us to use partial application as a means of progressively accumulating data and this effectively allowed us to write our code in a very similar style to how we'd have written it if we didn't have to deal with invalid inputs.

Grokking Functors

Matt Thornton — Wed, 31 Mar 2021 10:04:42 +0000

In this post we're going to grok functors by "discovering" them through a worked example.

Small F# primer

Skip this if you've got basic familiarity with F#.
It should be easy enough to follow along if you've not used F# before though. You'll only need to understand the following bits.

F# has an option type. It represents either the presence of Some value or its absence through a None value. It is typically used instead of null to indicate missing values.
Pattern matching on an option type looks like:

match anOptionalValue with
| Some x -> // expression when the value exists
| None -> // expression when the value doesn't exist.

F# has a pipe operator which is denoted as |>. It is an infix operator that applies the value on the left hand side to the function on the right. For example if toLower takes a string and converts it to lowercase then "ABC |> toLower would output "abc".

The scenario

Let's say we've been asked to write a function that will print a user's credit card details. The data model is straight forward, we have a CreditCard type and a User type.

type CreditCard =
    { Number: string
      Expiry: string
      Cvv: string }

type User =
    { Id: UserId
      CreditCard: CreditCard }

Our first implementation

We want a function that takes a User and returns a string representation of their CreditCard details. This is fairly easy to implement.

let printUserCreditCard (user: User): string =
    let creditCard = user.CreditCard

    $"Number: {creditCard.Number}
    Exiry: {creditCard.Expiry}
    Cvv: {creditCard.Cvv}"

We can even factor this out by writing a getCreditCard function and a printCreditCard function, which we can then just compose them whenever we want to print a user's credit card details.

let getCreditCard (user: User) : CreditCard = user.CreditCard

let printCreditCard (card: CreditCard) : string =
    $"Number: {card.Number}
    Exiry: {card.Expiry}
    Cvv: {card.Cvv}"

let printUserCreditCard (user: User) : string =
    user
    |> getCreditCard 
    |> printCreditCard

Beautiful! 👌

A twist 🌪

All is well, until we realise that we first need to lookup the user by their id from the database. Fortunately, there's already a function implemented for this.

let lookupUser (id: UserId): User option =
    // read user from DB, if they exist return Some, else None

Unfortunately, it returns a User option rather than a User so we can't just write

userId
|> lookupUser
|> getCreditCard
|> printCreditCard

because getCreditCard is expecting a User, not an option User.

Let's see if we can transform getCreditCard so that it can accept an option as input instead, without changing the original getCreditCard function itself. To do this we need to write a function that will wrap it. Let's call it liftGetCreditCard, because we can think of it as "lifting" the getCreditCard function to work with option inputs.

This might seem a bit tricky to write at first, but we know that we have two inputs to liftGetCreditCard. The first is the getCreditCard function and the second is the User option. We also know that we need to return a CreditCard option. So the signature should be (User -> CreditCard) -> User option -> CreditCard option.

By following the types there's only really one thing to do, try and apply the function to the User value by pattern matching on the option. If the user doesn't exist then we can't apply the function so we have to return None.

let liftGetCreditCard getCreditCard (user: User option): CreditCard option =
    match user with
    | Some u -> u |> getCreditCard |> Some
    | None -> None

Notice how in the Some case we have to wrap the output of getCreditCard in Some. This is because we have to make sure both branches return the same type and the only way to do that here is to make them return CreditCard option.

With this in place our pipeline is now

userId
|> lookupUser
|> liftGetCreditCard getCreditCard
|> printCreditCard

By partially applying getCreditCard to liftGetCreditCard we created a function whose signature was User option -> CreditCard option, which is what we wanted.

Well nearly, we've got the same issue as before except on the last line now. printCreditCard only knows how to deal with CreditCard values and not CreditCard option values. So let's apply the same trick again and write liftPrintCreditCard.

let liftPrintCreditCard printCreditCard (card: CreditCard option): CreditCard option =
    match card with
    | Some cc -> cc |> printCreditCard |> Some
    | None -> None

And our pipeline is now

userId
|> lookupUser
|> liftGetCreditCard getCreditCard
|> liftPrintCreditCard printCreditCard

Is that a functor I see 🔭

If we zoom out a bit, we might notice that the two lift... functions are remarkably similar. They both perform the same basic task, which is to unwrap the option, apply a function to the value if it exists and then package this value back up as a new option. They don't really depend on what's inside the option or what the function is. The only constraint is that the function accepts as input the value that might be inside the option.

Let's see if we can write a single version called lift which defines this behaviour for any valid pair of a function, which we'll call f and an option, which we'll call x. We can erase the type definitions for now and let F# infer them for us.

let lift f x =
    match x with
    | Some y -> y |> f |> Some
    | None -> None

Tidy, but perhaps a little bit abstract. Let's see what the inferred types tell us about this. F# has inferred it to have the type ('a -> 'b) -> 'a option -> 'b option. Where 'a and 'b are generic types. Let's place it side-by-side with liftGetCreditCard to help us make it more concrete.

(User -> CreditCard) -> User option -> CreditCard option

('a -> 'b) -> 'a option -> 'b option

The concrete User has been replaced by the generic type 'a and the concrete CreditCard type has been replaced with the generic type 'b. That's because lift doesn't care what's inside the option box, it's just saying "give me some function f and I'll apply this to the value contained within x if it exists and repackage it as a new option".

A more intuitive name for lift would be map, because we're just mapping the contents inside the option.

So with this new map function in place let's use it in our pipeline.

userId
|> lookupUser
|> map getCreditCard
|> map printCreditCard

Nice! This is nearly identical to the version we wrote before the option bombshell was dropped on us. So the code is still very readable.

You just discovered functors 👏

That map function we wrote is what makes option values functors. Functors are just a class of things that are "mappable". Lucky for us, F# has already defined map in the Option module, so we can actually just write our code using that instead

userId
|> lookupUser
|> Option.map getCreditCard
|> Option.map printCreditCard

Functors are just "mappable" containers 📦

Another good way to intuit functors is to think of them as value containers. For each type of container we just need to define a way to be able to map or transform its contents.

We've just discovered how to do that for options, but there are more containers that we can turn into functors too. A Result is a container which either has a value or an error and we want to be able to map the value regardless of what the error is.

The most common container though is a List or an Array. Most programmers have encountered a situation where they've needed to transform all the elements of a list before. If you've ever used Select in C# or map in JavaScript, Java etc then you've probably already grokked functors, even if you didn't realise it.

Test yourself 🧑‍🏫

See if you can write map for the Result<'a, 'b> and List<'a> types. The answers are below, no peeking until you've had a go first!

Result solution

let map f x =
    match x with
    | Ok y -> y |> f |> Ok
    | Error e -> Error e

This one is nearly identical to option in that we just apply the function to value of the Ok case otherwise we just propagate the Error.

List solution

let rec map f x =
    match x with
    | y:ys -> f y :: map f ys
    | [] -> []

This is a little trickier than the others, but the basic idea is the same. If the list has some items we pick off the head of the list, apply the function to the head and add it to the front of a new list created by mapping over the tail of this one. If the list is empty we just return another empty list. By reducing the list size by one each time we call map again we guarantee that eventually we hit the base case of the empty list which terminates the recursion.

What did we learn 🧑‍🎓

We learnt that functors are just types of containers that have a map function defined for them. We can use this function to transform the contents inside the container. This allows us to chain together functions that work with regular values even when those values are packaged in one of these container types.

This is useful because this pattern occurs in lots of different situations and by extracting a map function we can eradicate quite a bit of boilerplate that we'd otherwise have to do by constantly pattern matching.

Taking it further

If you enjoyed grokking functors, you'll love Grokking Monads. There we follow a similar recipe and discover a different type of function that's also very useful.

DEV Community: Matt Thornton

Typesafe F# configuration binding

Symbolica / Symbolica.Extensions.Configuration.FSharp

Provides a safe API for binding the dotnet IConfiguration to types in F#.

Symbolica.Extensions.Configuration.FSharp

Motivation

The problems with Microsoft.Extensions.Configuration.Binder

Problem 1: Mutable data and null values

Problem 2: No native support for binding DUs

Problem 3: Parse, don't validate

A better binder for F#

The Implementation Details

Try it out

Future Improvements

Symbolica's Console Newsletter Interview

Symbolica / Symbolica

Symbolica's open-source symbolic execution engine.

Symbolica

NuGet Packages

Symbolica.Abstraction

Symbolica.Collection

Symbolica.Computation

Symbolica.Deserialization

Symbolica.Expression

Symbolica.Implementation

Symbolica.Representation

Docker Images

symbolica/build

symbolica/translate

Azure Functions with F# using .NET 5

"In-process" vs "Out-of-process" hosting

Create a new project

Configure the .fsproj file

Configure host.json

Add a local.settings.json

Configure the host in Program.fs

Add your functions

Building the code

Run it locally

Deploy to Azure

Bonus: Build and Deploy from GitHub

See the full example on GitHub

Choc13 / az-function-fsharp-net5

A minimal example of creating an Azure function using F# on .NET 5. with bonus GitHub actions deployment

Example Azure Function using F# on .NET 5

Gotchas

Isolated .NET Host

The state of Azure severless in 2021

Conclusion

Grokking Lenses

The scenario

Composing a solution 🎼

Aligning the types

Generic property modifiers

Combing getters and setters

Putting it all together 🧩

You just discovered Lenses 🔍

Lenses in the wild 🐗

What did we learn? 🧑‍🎓

Interpreting Free Monads

Recap 🧢

A trivial interpreter

A real world interpreter

You've just discovered Free.fold 📃

A test interpreter 🧪

But I don't need a monad 🤷‍♀️

What did we learn? 🤓

Grokking Free Monads

Pre-requisites

The Scenario

Functions as data

Flattening the pyramid ⏪

Making data look like functions 🥸

Factoring out a functor

You just discovered the Free Monad 🥳

Should I use free monads 🤔

What did we learn 🧑‍🎓

Next time ⏭

Appendix

Grokking Monad Transformers

The problems with `Microsoft.Extensions.Configuration.Binder`

Problem 1: Mutable data and `null` values

Configure the `.fsproj` file

Configure `host.json`

Add a `local.settings.json`

Configure the host in `Program.fs`

You've just discovered `Free.fold` 📃

You just discovered `sequence` 👏

Test yourself on `sequence` 🧑‍🏫

You just discovered `traverse` 🙌

Test yourself on `traverse` 🧑‍🏫

Spotting `Traversable` in the wild 🐾