DEV Community: Justin Hewlett

To Annotate, or Not to Annotate?

Justin Hewlett — Thu, 10 Dec 2020 13:48:08 +0000

As a proud member of the ML family, F# has excellent type inference. This is generally a good thing. But as a newcomer to the language, it's often hard to know when you should use or omit type annotations. Some in the community suggest annotating everything, while others recommend to annotate as little as possible!

I've experimented with a variety of approaches. While there can be implications on the quality of your code¹, for me it was mostly a source of anxiety: "Am I doing it right?"

Strategies

Here are some common strategies I've seen or used:

Annotate the bare minimum

The usual argument here is that annotations are noisy, and they make it harder to refactor your code (because in addition to updating your code, you need to update the annotations as they become out of date)².

Some also argue that annotations can make your code unnecessarily specific, preventing reuse. (This is because F# will infer your types to be as generic as possible.)

All of this advice is reasonable if you're writing application code, where it's generally not a big deal if types change implicitly; you can just go update all the call sites and you're done.

No wait, annotate everything!

If you're writing a library, however, accidentally changing the signature of a function is a breaking change and is a much bigger deal.
In that context, it can make a lot more sense to annotate everything to pin down your types.

I could especially see this approach working well for a library that welcomes external contributors. "Annotate everything" is a simple rule to follow, and it also helps with viewing diffs in a context where you don't have your tooling to help show you the inferred types.

Annotate...some of the things?

A more nuanced position is to annotate all public, top-level functions, while allowing private functions to be inferred. This makes it easier to refactor your internals. It still manages to keep noise to a minimum, while keeping your public signatures locked in.

This is a nice middle ground, and could be used for both application code and libraries. Indeed, this seems to be the recommendation in the F# style guide:

Consider labeling argument names with explicit types in public APIs and do not rely on type inference for this.

Prototype with inference, then lock it in

In this approach, the general idea is that you start coding without any annotations. Then, as your code starts to take shape, you can check the type that was inferred (e.g. via your editor tooling). Assuming you agree, you can then add the annotation explicitly to pin it down.

This is similar to the argument that dynamic types are better for prototyping, while static types are better for building the real thing. This is a cool variation though because inference means you don't have to give up type safety!

Drive it out with types, then delete the annotations

This one is almost the exact opposite of the previous one. With this strategy, you design all your types upfront: records, unions, and even function signatures. Then you implement the function. The types help you make sure the implementation is correct (likely in addition to testing). Finally, after you've implemented it, you may actually decide to remove the type annotations! Partly a matter of style, and partly a matter of the context you're working in.

Use tests to lock in your types

Since it's often a good idea to write tests for your public functions anyway, what if you used those tests to pin down your types? In this way, the tests become your first consumers, documenting their signature through usage.

Admittedly, this strategy is a bit indirect. But I've observed this in my own code as one reason why I don't always feel the need to annotate my public functions.

The life of an annotation

A common theme throughout all this is that it's easy to add and remove annotations at will. Some annotations are helpful mostly in development (e.g. to pinpoint an error when you get a confusing error message), while some annotations are more permanent. My advice: embrace this dynamic, and don't be afraid to change your mind. Striving for perfect consistency in where you add annotations, or when you add them, is futile. Ultimately, you'll need to experiment to find the right approach that fits your context and style!

This post is part of the F# Advent Calendar 2020

The one place I can recall introducing a bug due to relying on type inference is when used in conjunction with reflection (e.g. JSON deserialization, or a library like Dapper). You should minimize the use of reflection where you can, and use explicit annotations where you can't. ↩
This is a case where some people argue the opposite: that a lack of annotations makes it harder to refactor your code. The main argument here is that you'll feel safer refactoring if you know that you're only changing types explicitly as you update the annotations. I believe this is mainly a perception of safety over actual safety. (Type inference is different than dynamic typing, after all!) The main caveat here is the combination of reflection and type inference as noted above. ↩

Creating a Functional Wrapper in F#

Justin Hewlett — Mon, 27 Jul 2020 02:53:26 +0000

One of the big selling points of F# is the wealth of .NET libraries available to you, both in the Base Class Library and NuGet.

Many of these libraries, however, are developed primarily with C# in mind. They can usually be consumed without issue, but I often find it helpful to write a little wrapper around them to provide a more idiomatic, functional interface. (Plus, it never hurts to build a facade around a third-party dependency!)

Let's walk through how we might build a wrapper around HttpClient from the Microsoft.Extensions.Http package.

To start off, here's how we could use HttpClient to make a GET request:

let (statusCode, body) =
    async {
        use httpClient = new HttpClient()

        httpClient.Timeout <- TimeSpan.FromSeconds 2.

        use requestMessage =
            new HttpRequestMessage(
                HttpMethod.Get,
                "https://hacker-news.firebaseio.com/v0/item/8863.json"
            )

        requestMessage.Headers.Add("Accept", "application/json")

        use! response = httpClient.SendAsync(requestMessage) |> Async.AwaitTask
        let! body = response.Content.ReadAsStringAsync() |> Async.AwaitTask

        return (response.StatusCode, body)
    }
    |> Async.RunSynchronously

This isn't awful, but I think we can do better. It'd be nice to encapsulate some of these details and make the code a bit more declarative.

Let's start by defining some types for the interface that we want:

type HttpMethod =
| Get
| Delete

type Request = {
    Url : string
    Method : HttpMethod
    Timeout : TimeSpan option
    Headers : (string * string) list
}

For now, we'll just support GETs and DELETEs, but it will be easy to add support for other methods as we need to. We'll require the user to specify a Url and Method, but Timeout and Headers are optional.

For our response, we can just capture the status code and body for now:

type Response = {
    StatusCode : int
    Body : string
}

Now that we have our types, let's think about what our function signature might look like:

module Http =
    let execute (httpClientFactory : IHttpClientFactory) (request : Request) : Async<Response> = ...

We'll take in an instance of IHttpClientFactory ¹ and Request, and return an Async<Response>.

Let's see how ergonomic it would be to use at this point:

let request =
    {
        Url = "https://hacker-news.firebaseio.com/v0/item/8863.json"
        Method = Get
        Timeout = Some (TimeSpan.FromSeconds 2.)
        Headers = [ ("Accept", "application/json") ]
    }

let response =
    request
    |> Http.execute httpClientFactory
    |> Async.RunSynchronously

Not too bad. One thing to note is that even if we don't want to provide a Timeout or Headers, we still have to set the properties:

let request =
    {
        Url = "https://hacker-news.firebaseio.com/v0/item/8863.json"
        Method = Get
        Timeout = None
        Headers = []
    }

Let's create a helper function to make a request with some default values:

module Http =
    let createRequest url method =
        {
            Url = url
            Method = method
            Timeout = None
            Headers = []
        }

Now we have:

let request = Http.createRequest "https://hacker-news.firebaseio.com/v0/item/8863.json" Get
let requestWithTimeout = { request with Timeout = Some (TimeSpan.FromSeconds 2.) }
let requestWithTimeoutAndHeaders = { requestWithTimeout with Headers = [ ("Accept", "application/json") ] }

Since records are immutable, we use with to create a new instance with some additional properties set.

This is more tedious than just creating the Request ourselves and setting all the properties. Let's create some more helper functions for adding a timeout and headers:

[<AutoOpen>]
module Request =
    let withTimeout timeout request =
        { request with Timeout = Some timeout }

    let withHeader header request =
        { request with Headers = header :: request.Headers }

Notice that request comes in as the last parameter. This is important to enable pipelining:

let request =
    Http.createRequest "https://hacker-news.firebaseio.com/v0/item/8863.json" Get
    |> withTimeout (TimeSpan.FromSeconds 2.)
    |> withHeader ("Accept", "application/json")

Pretty slick, right? We've created a little domain-specific language (DSL) to describe the different options, and we can pick and choose what we need.

From Overloads to DSLs

In C# land, you might use overloads, optional parameters, and mutable properties to capture the different configuration options. If you layer on dot chaining and some well-designed methods, you can create a fluent builder.

In F#, there's a strong focus on creating DSLs, using features like records, the pipeline operator, discriminated unions², and computation expressions³. We've created a builder here, not too different than something like LINQ, though it uses function pipelines instead of dot chaining.

Implementing 'execute'

Now that we've talked about the interesting bits, we can see what the implementation of our execute function might look like:

module HttpMethod =
    let value method =
        match method with
        | Get -> System.Net.Http.HttpMethod.Get
        | Delete -> System.Net.Http.HttpMethod.Delete

module Http =
    let execute (httpClientFactory : IHttpClientFactory) (request : Request) : Async<Response> =
        async {
            use httpClient = httpClientFactory.CreateClient()

            request.Timeout
            |> Option.iter (fun t -> httpClient.Timeout <- t)

            use requestMessage = new HttpRequestMessage(request.Method |> HttpMethod.value, request.Url)

            request.Headers
            |> List.iter requestMessage.Headers.Add

            use! response = httpClient.SendAsync(requestMessage) |> Async.AwaitTask
            let! body = response.Content.ReadAsStringAsync() |> Async.AwaitTask

            return
                {
                    StatusCode = int response.StatusCode
                    Body = body
                }
        }

Not too much different from our initial example. We did add a HttpMethod.value function to convert between our representation and System.Net.Http.HttpMethod, and we optionally set the timeout via Option.iter which only runs the callback if we have a value.

Modules vs. Objects

Where possible, I tends to use modules and functions over objects. For dependencies that would typically be passed into a class constructor, we just pass to the function directly (like IHttpClientFactory in our example). By positioning them at the beginning of the parameter list, you'll be able to use partial application if you want to.

Here's what that might look like with execute:

let makeRequest = Http.execute httpClientFactory    //only apply the first parameter

let request =
    Http.createRequest "https://hacker-news.firebaseio.com/v0/item/8863.json" Get
    |> withTimeout (TimeSpan.FromSeconds 2.)
    |> withHeader ("Accept", "application/json")

request
|> makeRequest    //pipe in the final parameter, 'request'
|> Async.RunSynchronously

We can even do the same thing with createRequest if we want:

let resource = Http.createRequest "https://hacker-news.firebaseio.com/v0/item/8863.json"

let get = resource Get
let delete = resource Delete

Perhaps this is overkill, but these are the kinds of things I think about when deciding how to order the parameters — from more general to more specific; dependencies first, data second.

Conclusion

We were able to create a nice wrapper around HttpClient that will play nicely with the rest of our code. It was no accident that we spent a good chunk of time upfront thinking about the types and the different interactions that we want our interface to support. That's the tricky part to get right; the implementation usually ends up just doing a bit of translation and delegation to the underlying library. Note that you don't have to expose the entire library — indeed, it's often easier on consumers if you just expose the stuff you actually use.

Here's a gist that shows the full example, including some additional code for handling other HTTP methods, request bodies, and dealing with query strings⁴. Enjoy!

Thanks to Isaac Abraham and Brett Rowberry for reviewing the draft of this post!

IHttpClientFactory is fairly new and basically acts as a pool for HttpClients. You need to use the built-in DI container to get an instance of it. ↩
You can do overloading and optional parameters in F#, too, if you use methods rather than functions. I tend to avoid them because they don't play very nicely with type inference, and discriminated unions are a great alternative. ↩
Take a look at Saturn and Farmer for two good examples of using computation expressions to create DSLs. ↩
I have successfully used this in production, but the wrapper is by no means exhaustive. Take a look at FsHttp for a more fully-featured library. ↩

F# Error Handling with 'Result'

Justin Hewlett — Fri, 03 Jan 2020 15:29:47 +0000

Handling errors with Result is a great way to model errors in your domain and force you to consider all the error cases¹. But if you're used to using exceptions for this sort of thing, it can be tricky to figure out the best way to glue all your Result-returning functions together.

To illustrate some different approaches, we'll go through a real-life example of making an HTTP request, checking the status code, then attempting to decode the response body.

Here are the types we'll be working with to make our request:

type Response = {
    Body : string
    StatusCode : int
}

type RequestError =
| NetworkError

let makeHttpRequest (url : string) : Async<Result<Response, RequestError>> = ...

This can return an Error in case there's a network issue. And even if the request does succeed, we need to consider the possibility of a non-200 status code.

Here's our User type and a function to decode a string. If it fails to parse, it will return an Error with a message.

type User = {
    Id : string
    Name : string
}

let decodeUser (body : string) : Result<User, string> = ...

I deliberately left out the contents of makeHttpRequest and decodeUser; we're only interested in the type signatures here.

The most interesting code we'll look at is the getUser function below. It ties everything together and allows us to explore all the different ways to combine the error-handling logic.

Pattern Matching

We'll start with a pretty straightforward variant:

type GetUserError =
| NetworkError
| Non200Response
| ParseError of string

let getUser (url : string) : Async<Result<User, GetUserError>> =
    async {
        let! result = makeHttpRequest url

        return
            match result with
            | Error _ -> Error NetworkError
            | Ok response ->
                match response.StatusCode with
                | 200 ->
                    match decodeUser response.Body with
                    | Error err -> Error (ParseError err)
                    | Ok user -> Ok user
                | _ ->
                    Error Non200Response
    }

We use an async computation expression, then pattern match to handle all the errors. This is simple and pretty easy to write, though there's a lot of nesting, and it's needlessly verbose in a few cases. All the plumbing is out there in the open, for better or worse.

Towards a Pipeline

We can eliminate some of the plumbing by embracing Result.bind and Result.mapError:

let getUser (url : string) : Async<Result<User, GetUserError>> =
    async {
        let! result = makeHttpRequest url

        return
            result
            |> Result.mapError (fun _ -> NetworkError)
            |> Result.bind (fun response ->
                match response.StatusCode with
                | 200 ->
                    response.Body
                    |> decodeUser
                    |> Result.mapError ParseError
                | _ ->
                    Error Non200Response
            )
    }

Result.bind chains actions together in the success case. Result.mapError takes any failures that occur along the way and maps them to a common GetUserError type.

Embrace the Pipeline

So far we have a bit of a hybrid, using a computation expression for async, and function pipelines for dealing with Result. That's fine, but let's see how it feels to go all-in.

Here we'll use the AsyncResult module from FsToolkit.ErrorHandling which allows us to drop the async computation expression:

let getUser (url : string) : Async<Result<User, GetUserError>> =
    makeHttpRequest url
    |> AsyncResult.mapError (fun _ -> NetworkError)
    |> AsyncResult.bind (fun response ->
        match response.StatusCode with
        | 200 ->
            response.Body
            |> decodeUser
            |> Result.mapError ParseError
            |> Async.singleton
        | _ ->
            AsyncResult.returnError Non200Response
    )

Not too much is different here. We use mapError and bind from AsyncResult instead of Result. We also have to use Async.singleton to lift our decode Result into Async<Result>.

Nesting is pretty minimal, and it's pretty easy to see how our data flows from request to status code checking to decoding the response.

Computation Expressions, My Old Friend

All right, let's see how things would look if we instead go the other way and lean harder into computation expressions. We'll use the asyncResult builder from FsToolkit.ErrorHandling:

let getUser (url : string) : Async<Result<User, GetUserError>> =
    asyncResult {
        let! response =
            makeHttpRequest url
            |> AsyncResult.mapError (fun _ -> NetworkError)

        do!
            response.StatusCode = 200
            |> Result.requireTrue Non200Response

        return!
            response.Body
            |> decodeUser
            |> Result.mapError ParseError
    }

Nesting is eliminated completely — computation expressions are good at that. We traded in our pattern matching on response.StatusCode for an interesting helper, Result.requireTrue. Part of me prefers the explicit pattern matching, but Result.requireTrue seems to fit the style better here.

Of all the variants, this one seems to do the best job of separating the distinct phases of making the request, checking the status code, and decoding the response. Unfortunately, it also seems to give the worst compiler errors, e.g. No overloads match for method 'Bind' if you forget to call AsyncResult.mapError on your response Result. Computation expressions are awesome, but you almost need to understand how they work under the hood to be able to understand errors like this.

Conclusion

Which of these approaches is the best? It's not clear to me. All of the variants seem to come with their own set of trade-offs. Some are easier to write, but harder to read (and vice versa). Some are friendlier to beginners, and others use more advanced language features.

But that's kind of the point. There's no one best way to do it. It depends on the context, and you need to play around with it to find something that feels right. In the end, it may come down to personal or team preference.

I encourage you to get comfortable with all of the approaches I outlined. Start simple, and if you're not happy with it, then try a different approach and compare.

Scott Wlaschin has written a lot on this topic. He coined the term Railway Oriented Programming to describe this style of monadic error handling. More recently, he cautioned about taking it too far. I like his distinction between domain errors, infrastructure errors, and panics as a guideline for whether you should use Result or exceptions. ↩

Dependency Injection in F# Web APIs

Justin Hewlett — Thu, 05 Dec 2019 14:34:03 +0000

I've spent a lot of time thinking about the best way to manage dependencies in F# web APIs built on top of ASP.NET Core. As you might expect from a .NET library, it makes heavy use of object-oriented patterns. For example, everything seems to be based around the built-in Inversion of Control (IoC) container.

In many ways, IoC containers appear to be antithetical to the F# ethos. For one, they are a bit magical, which runs counter to the F# philosophy of being explicit. You also give up a lot of compile-time checking and have to rely on runtime failures for your dependency wire-up. Further, usually IoC containers are used with classes and interfaces, while many F# programmers favor modules, functions, and algebraic types.

On the other hand, containers do give you a good way to manage resource lifetimes. Which things should be a singleton for the duration of the server, and which things should be created once per request?

And really, since the container is built-in to ASP.NET Core, it's hard to avoid it completely. If you use the built-in configuration or logging, you'll likely need to use it. It's actually impossible to create a HttpClientFactory without using the container!

A compromise

I've come up with a few strategies that allow me to be a good .NET citizen and get some of the benefits of containers, such as lifetime management, without giving up my desire to wire things up manually using partial application.

Manual wire-up with partial application

When registering classes, it's common to register all the parameters to a class constructor in the IoC container, then let the container construct the class automatically via reflection.

The problem with this approach is that the construction of your class is now implicit. If you add a parameter to your class constructor and forget to register it, you won't get a compile error — it will just fail at runtime. I think this is one of the biggest drawbacks of containers.

Instead, I use partial application to explicitly wire up my dependencies. Then I only register the top-level functions that will be injected into the controller.¹

Let's look at an example:

module Database =
    let readData (connectionString : string) (query : string) : Async<'a list> = ...

module Person =
    let getPerson (readData : string -> Async<'a list>) (personId : string) : Async<Person option> = ...

We have a Database.readData function that takes in a connection string and query and returns a list of results.

Then we have a Person.getPerson function that takes in a function that knows how to read data from the database and a personId, executes a query, and returns the result.

Notice that the readData parameter in getPerson is just Database.readData with the connection string already baked into it via partial application.

Here's what our container registration would like for this:

type GetPerson = string -> Async<Person option>

type Startup (configuration : IConfiguration) =
    member _.ConfigureServices(services : IServiceCollection) : unit =
        let readData = Database.readData configuration.["dbConnection"]    //partially apply the connection string
        let getPerson = Person.getPerson readData    //partially apply the readData function

        services
            .AddSingleton<GetPerson>(getPerson)
            .AddControllers()
        |> ignore

Yes, you can register plain functions in the container!

GetPerson is just a type alias to a function signature; we could have just as easily inlined it:

.AddSingleton<string -> Async<Person option>>(getPerson)

You'll note that we're doing all of the wiring manually via partial application². Then, we only register the top-level function, getPerson. The function readData becomes a supporting function for getPerson, but we have no need to register it because we won't inject it into our controller.

Injecting records and discriminated unions

Injecting bare functions is simple and lightweight, but you do risk having functions with the same signature collide. For that reason, it's probably best to wrap the function in a record or single-case discriminated union:

//Option 1: Record
type PersonControllerDependencies = {
    GetPerson : string -> Async<Person option>
}

//Option 2: Single-case DU
type GetPerson = GetPerson of (string -> Async<Person option>)

In the controller, you can inject the type into the constructor just like you would a class or interface:

[<ApiController>]
type PersonController(deps : PersonControllerDependencies) =
    inherit ControllerBase()

    [<HttpGet>]
    [<Route("people/{personId}")>]
    member _.Get(personId : string) =
        async {
            let! person = deps.GetPerson personId
            return OkObjectResult(person) :> IActionResult
        }

You may find it helpful to use destructuring:

let { GetPerson = getPerson } = deps
let! person = getPerson personId

This is especially true if you go the single-case union route because you can't just "dot" into it:

let (GetPerson getPerson) = GetPerson
let! person = getPerson personId

What about Giraffe?

Giraffe is a functional web framework built on top of ASP.NET Core. Interestingly, Giraffe doesn't do anything to try to hide or work around the IoC container. In your handlers, you use:

let service = ctx.GetService<T>()

This is a service locator pattern. In some ways, this is worse than using stock MVC because at least with MVC you have a constructor to inject your dependencies into. For this reason, I like to add in Giraffe.GoodRead, which provides a slick way of injecting the dependencies into your request handler functions.

For contrast, here is what the request handler would look like with Giraffe:

type GetPersonDependencies = {
    GetPerson : string -> Async<Person option>
}

let getPersonHandler { GetPerson = getPerson } personId =
    fun next ctx ->
        task {
            let! person = getPerson personId |> Async.StartAsTask

            return! json person next ctx
        }

let webApp =
    choose [
        routef "/people/%s" (fun personId ->
            //inject the dependency into getPersonHandler
            Require.services<GetPersonDependencies> (fun getPersonDeps ->
                getPersonHandler getPersonDeps personId
            )
        )
    ]

Final thoughts

I mentioned a few different approaches here. Let me give you a more concrete recommendation if you're still not sure where to start.

I recommend starting with stock MVC Web API first, especially for a simple app. Use partial application in ConfigureServices and inject a record of top-level functions. Records provide a nice grouping of related functions³ and provide an easy way to access the functions inside.

As your app grows and you become more comfortable, or if you anticipate needing request handler pipelines that compose easily, Giraffe with GoodRead is a good next step.

This post is part of the F# Advent Calendar 2019

It occurs to me that this strategy gives you less flexibility in managing lifetimes since you're not registering all the intermediate functions. I acknowledge this and am not sure how much of a problem this is in practice. It's also worth keeping in mind that you can manage lifetimes yourself outside of an IoC container. For example, you could have a singleton factory function that, when called, created a new resource every time. ↩
Well, most of it. The framework is still constructing the controllers themselves for us. If you really want to, you can create the controllers manually, too. Here's a good example of how to do this in C#. I haven't played around with this much, so I'm not sure whether it's worthwhile. ↩
Yes, a record of functions is basically equivalent to an interface. Those will work fine too, especially if you pair them with object expressions to implement the interface, but I prefer records because it's easy to remember the syntax to declare and create them. ↩