DEV Community: Romain Deneau

Applying object-oriented design principles - In-memory configuration builder

Romain Deneau — Mon, 01 Sep 2025 13:45:16 +0000

Testing functionality that takes an XML or JSON file as input is no easy task. We'll see how to apply object-oriented design principles and modern programming language features to produce unit tests that are fun to write and easy to review. Code snippets will be written in C#.

Problem description

The functionality in question here consists of parsing a section of an ASP.NET application's configuration defined in appsettings*.json files. These files are read by the ASP.NET framework after configuring the application with an instruction such as builder.Configuration.AddJsonFile($"appsettings.json", optional: false, reloadOnChange: true).

The configuration can then be accessed in a variety of ways. In our case, parsing the configuration section leads to a higher-level object and, more importantly, one in a valid state. For this reason, the most suitable way is to use an IConfiguration object from the NuGet package Microsoft.Extensions.Configuration.Abstractions.

This object is not easily mockable for our unit tests, but Microsoft has thought of us: ConfigurationBuilder - from the NuGet package Microsoft.Extensions.Configuration - is a convenient way of creating an in-memory configuration from a key-value dictionary, especially useful for unit testing, as it avoids file I/O and external dependencies.

Dictionary<string, string> configuration = ...;
var jsonConfiguration = new ConfigurationBuilder()
    .AddInMemoryCollection(configuration)
    .Build();

The disadvantage is that the tree structure is lost: the path of entries in the configuration is encoded in the key, and in an atypical format: each level is separated from its parent by the ':' character. We'd like to build this configuration in a syntax that makes it easy to bridge the gap with the real configuration written in JSON, and that doesn't require knowledge of the subtleties of input path encoding.

The configuration to build here has the following JSON format:

{
  "AwsSecretManager" : {
    "RegionName": "***",
    "SecretName": "****",
    "PartnerKeyName": {               // Optional. Use default value if not defined  
      "Login": "MyPartnerLogin",      // default value is "Login" 
      "Password": "MyPartnerPassword" // default value is "Password" 
    },  
    "AwsCredentials": { 
        "Source": "Basic",
        "AccessKey": "~~~~",
        "SecretKey": "~~~~~~"
    },
    // or 
    "AwsCredentials": { "Source": "Environment" }
  }
}

To do this, there's nothing like experimentation: we write the construction code for this configuration section, testing this syntax from both sides: on the one hand, does the usage meet our needs? On the other hand, is it easy to implement, while at the same time preventing us from writing buggy code? The right compromise comes after a few attempts. Let's look at the result.

Syntax on the usage side

Let's start with an example:

var configuration =
    Configuration.Section("AwsSecretManager",
        Configuration.Value("RegionName", "***"),
        Configuration.Value("SecretName", "****"),
        Configuration.Section("PartnerKeyName",
            Configuration.Value("Login", "MyPartnerLogin"),
            Configuration.Value("Password", "MyPartnerPassword")),
        Configuration.Section("AwsCredentials",
            Configuration.Value("Source", "Environment"))
    ).ToConfiguration();

This syntax is based on two helpers and one method:

Configuration.Value(key, value) helper defines an entry in a section.
Configuration.Section(name, ..entries) helper defines a section with the specified name, containing the given entries. The entries parameter is a param array.
Both helpers use a short naming, eliminating verbs like Get, Make, Create to simplify the syntax without compromising the clarity.
ToConfiguration() is used to define the IConfiguration required as input to unit tests.

This approach offers several key advantages:

No JSON Required: Configuration is constructed directly in C#, eliminating the need to embed, parse, or comment JSON within your code. The resulting unit tests are more robust and have better performances.
Natural Nesting: The syntax's structure closely matches the nesting found in JSON. Sections can contain other sections or entries, making the configuration tree intuitive and easy to follow.
Lightweight Syntax: The syntax does not rely on the new keyword, braces {} or square brackets [], resulting in concise and readable code.
Code Clarity: The syntax is explicit: qualified use with Configuration. removes any doubt about the domain involved.

Implementation design

Let's take a look at the implementation behind this syntax.

public static class Configuration
{
    public record Entry(string Key, string Value) : IEntries
    {
        public IEnumerator<Entry> GetEnumerator()
        {
            yield return this;
        }
    }

    public interface IEntries : IEnumerable<Entry>
    {
        IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();

        IConfigurationRoot ToConfiguration() =>
            new ConfigurationBuilder()
                .AddInMemoryCollection(this.ToDictionary(x => x.Key, x => x.Value)!)
                .Build();
    }

    private class Entries : IEntries
    {
        private readonly IEnumerable<Entry> _entries;

        private Entries(IEnumerable<Entry> entries)
        {
            _entries = entries;
        }

        public IEnumerator<Entry> GetEnumerator() =>
            _entries.AsEnumerable().GetEnumerator();

        public static Entries Collect(Func<Entry, Entry> f, params IEntries[] entries) =>
            new(entries.SelectMany(x => x.Select(f)));
    }

    public static IEntries Section(string name, params IEntries[] children) =>
        Entries.Collect(entry => entry with { Key = $"{name}:{entry.Key}" }, children);

    public static IEntries Value(string key, string value) =>
        new Entry(key, value);
}

Here are the steps I followed to arrive at this design:

To encourage the qualified use of helpers, all the code is placed in a static class Configuration. This is similar to what we do in F# to gather helpers into a module, although we lack the RequireQualifiedAccess attribute to force qualification when using functions in the module.

Configuration will contain the two helpers Value and Section that are static methods. Value constructs an instance of an Entry record used to define a Key, Value entry in configuration. Section takes as input the name and content of the section, the content being entries and sub-sections. What should be the input and output parameter types?

The output type of Value and Section must be compatible with the input type of Section. So we need a common abstraction. The ConfigurationBuilder and its AddInMemoryCollection method allows us to consider a section as a simple collection of entries, hence the IEntries interface which extends IEnumerable<Entry>. A default implementation of IEnumerable.GetEnumerator is provided: derived classes need only to implement IEnumerable<T>.GetEnumerator.

We need a type implementing the IEntries interface. We could create a Section type, but we don't actually need one. As the section name can just be encoded in the entry keys, an Entries type is sufficient. This is a class that encapsulates an IEnumerable<Entry> in order to delegate the construction of the enumerator to it. This class can be private, hiding this implementation detail from Configuration users.

We have linked Section to IEntries. What can we do on the Entry side to link it to IEntries? The Composite design pattern points the way. Entry can be seen as a collection of a single entry: the type can thus implement the IEntries interface, with a GetEnumerator based on a simple yield return this;.

At this stage, we still need to manage the contents of a section, i.e. the aggregation of all entries and the encoding of the section name in the entry keys. This second aspect is handled directly by the Section helper, while entry aggregation is delegated to a Collect function in the Entries class, to keep responsibilities clearly separated. Collect creates a new instance of Entries wrapping a call to SelectMany to flatten the set of specified entries, each entry being mapped using the specified function f.

Design principles followed in the implementation

Key design aspects:

No Inheritance: The design avoids base classes, to favor composition over inheritance. For example, the Entries class does not inherit from an existing collection, but wraps it and delegates to it the implementation of the enumeration of its elements. The use of default implementations in the IEntries interface is at the limit of this principle, as it could be seen as inheritance, but it offers the advantage to avoid duplication.
Default Interface Methods and No Duplication: The use of default method implementations (such as GetEnumerator) in IEntries interface allows code sharing without inheritance. ToConfiguration could have been written as an extension method, but it's easier to centralize them all in one place.
Encapsulation: Implementation details are hidden. Only the IEntries interface and the Entry record are exposed, while the concrete classe Entries remains private. This would allow us to change our internal model, to rely on other implementations, without breaking the calling code.
Immutability: The objects involved in this design are all immutable, guaranteeing that they are supplied directly in a valid state that cannot be corrupted afterwards, in particular the key of an entry encoding the access path. The entry type relies on the C# 9 record to get the immutability for free.
Composite Pattern: The IEntries interface embodies the Composite design pattern. This gives us the flexibility to combine as many inputs as we like.

Conclusion

This configuration builder provides a robust and flexible way to build configuration objects in C#, leveraging modern language features and design principles for clarity and maintainability.

The investment in creating such APIs pays dividends in test maintainability—an area that is often overlooked in many codebases but crucial for long-term project health.

Are you familiar with this type of design? If you haven't written one yourself, has this article motivated you to give it a try?

Writing F# computation expressions

Romain Deneau — Fri, 22 Aug 2025 15:20:00 +0000

This final article in the series dedicated to F# computation expressions completes what we have seen regarding writing F# computation expressions of any kind: applicative, monadic, or monoidal.

Table of contents

Types
- M<T> wrapper type
- Delayed<T> type
- Internal<T> type
Builder-less CE
- Example: activity {}
Custom operations 🚀
Final words
- Benefits ✅
- Limits ⚠️
- Guidelines 📃
- Tips 💡
🍔 Quiz
🔗 Additional resources

Types

The CE builder method definitions can involve not 2 but 3 types:

The wrapper type M<T>
The Delayed<T> type
An Internal<T> type

☝️ Note: we continue to use the generic type notation Xxx<T> for these types for convenience, even though it's an approximation.

`M<T>` wrapper type

Candidates for this type are either generic types or "container" types like string as it contains chars. In fact, any type itself can be used as the wrapper type for a CE, as it can be written as the Identity<T> type: type Identity<'t> = 't. This was the case for the logger {} CE we saw in the first article of the series.

`Delayed<T>` type

Delayed<T> is the type returned by the Delay method. It is used when we want to delay the evaluation of an expression inside the CE's body.

The Delay input parameter already involves this deferred evaluation as its type is unit -> M<T>, the type of a thunk. Based on that, we have three possibilities:

Eager evaluation: Delay consists in executing the thunk: member _.Delay f = f(). In this case, type Delayed<T> = M<T>. It is the default implementation when Delay is not required and not specified.
Deferred evaluation with no additional type: Delay returns the thunk directly, without executing it. Delay is just the identity function: member _.Delay f = f. type Delayed<T> = unit -> M<T>.
Deferred evaluation with an additional type: Delay uses the thunk to build an instance of an additional type, usually just wrapping the thunk: member _.Delay f = Delayed f.

Once the Delay method is defined, some of the other methods of the builder must be adapted: Run, Combine, While, TryWith, TryFinally must take into account that their input parameter has the Delayed<T> type.

`Delayed<T>` type example: `eventually {}`

In this example, adapted from the Microsoft documentation, we define a union type Eventually<'t> used for both wrapper and delayed types:

type Eventually<'t> =
    | Done of 't
    | NotYetDone of (unit -> Eventually<'t>)

type EventuallyBuilder() =
    member _.Return x = Done x
    member _.ReturnFrom expr = expr
    member _.Zero() = Done()
    member _.Delay f = NotYetDone f

    member m.Bind(expr, f) =
        match expr with
        | Done x -> f x
        | NotYetDone work -> NotYetDone(fun () -> m.Bind(work (), f))

    member m.Combine(command, expr) = m.Bind(command, (fun () -> expr))

let eventually = EventuallyBuilder()

The output values are meant to be evaluated interactively, step by step:

let step = function
    | Done x -> Done x
    | NotYetDone func -> func ()

let delayPrintMessage i =
    NotYetDone(fun () -> printfn "Message %d" i; Done ())

let test = eventually {
    do! delayPrintMessage 1
    do! delayPrintMessage 2
    return 3 + 4
}

let step1 = test |> step   // val step1: Eventually<int> = NotYetDone <fun:Bind@14-1>
let step2 = step1 |> step  // Message 1 ↩ val step2: Eventually<int> = NotYetDone <fun:Bind@14-1>
let step3 = step2 |> step  // Message 2 ↩ val step3: Eventually<int> = Done 7

`Internal<T>` type

Return, ReturnFrom, Yield, YieldFrom, Zero methods can return a type internal to the CE. The Combine, Delay, and Run methods are adapted to handle this type.

For instance, we can review our list {} CE (link) to use a seq type internally, as it is done by the list comprehension:

type ListSeqBuilder() =
    member inline _.Zero() = Seq.empty
    member inline _.Yield(x) = Seq.singleton x
    member inline _.YieldFrom(xs) = Seq.ofList xs
    member inline _.Delay([<InlineIfLambda>] thunk) = Seq.delay thunk
    member inline _.Combine(xs, ys) = Seq.append xs ys
    member inline _.For(xs, [<InlineIfLambda>] f) = xs |> Seq.collect f
    member inline _.Run(xs) = xs |> Seq.toList

let listSeq = ListSeqBuilder()

💡 Note: the Internal<T> type highlights the usefulness of ReturnFrom and YieldFrom, implemented as an identity function until now.

Builder-less CE

Up to now, we've assumed that a specific type had to be defined to serve as a Builder to create a computation expression. It turns out that this isn't necessary. In fact, any type, even an existing one, can be extended to support CE syntax: simply extend it using extension methods of a CE builder.

Let's look at an example: the activity {} CE. It was written by my teammate Loïc/Tarmil, creator and maintainer of Bolero.

The purpose of the activity {} CE is to configure an Activity (from System.Diagnostics) with a lightweight convenient syntax.

Given an activity provided by any ActivitySource, we would like to write something like that:

use activity = Activities.source.StartActivity(...)

activity {
    setStartTime DateTime.UtcNow
    setTag "count" 2
}

Some preliminary remarks:

The type to extend to support CE syntax is System.Diagnostics.Activity.
The returned type is unit: the CE is only performing a side effect to change/mutate the activity.
The CE involves implicit yields for each call to helper methods like setStartTime, defined aside the extension methods.
The internal functioning of the CE is based on the type type ActivityAction = delegate of Activity -> unit.
Each helper creates an instance of ActivityAction that defines the delayed change on the activity. E.g. let inline setStartTime time = ActivityAction(fun ac -> ac.SetStartTime(time) |> ignore).
Internally, the CE combines every yielded ActivityAction that is created by the helpers. So, it's a monoidal CE.
Externally, the CE looks like a State monad, with a series of Set.

Here the full code listing:

type ActivityAction = delegate of Activity -> unit

// Helpers
let inline private action ([<InlineIfLambda>] f: Activity -> _) =
    ActivityAction(fun ac -> f ac |> ignore)

let inline addLink link = action _.AddLink(link)
let inline setTag name value = action _.SetTag(name, value)
let inline setStartTime time = action _.SetStartTime(time)

// CE Builder Methods
type ActivityExtensions =
    [<Extension; EditorBrowsable(EditorBrowsableState.Never)>]
    static member inline Zero(_: Activity | null) = ActivityAction(fun _ -> ())

    [<Extension; EditorBrowsable(EditorBrowsableState.Never)>]
    static member inline Yield(_: Activity | null, [<InlineIfLambda>] a: ActivityAction) = a

    [<Extension; EditorBrowsable(EditorBrowsableState.Never)>]
    static member inline Combine(_: Activity | null, [<InlineIfLambda>] a1: ActivityAction, [<InlineIfLambda>] a2: ActivityAction) =
        ActivityAction(fun ac -> a1.Invoke(ac); a2.Invoke(ac))

    [<Extension; EditorBrowsable(EditorBrowsableState.Never)>]
    static member inline Delay(_: Activity | null, [<InlineIfLambda>] f: unit -> ActivityAction) = f()

    [<Extension; EditorBrowsable(EditorBrowsableState.Never)>]
    static member inline Run(ac: Activity | null, [<InlineIfLambda>] f: ActivityAction) =
        match ac with
        | null -> ()
        | ac -> f.Invoke(ac)

// ---

let activity = new Activity("Tests")

activity {
    setStartTime DateTime.UtcNow
    setTag "count" 2
}

// Desugaring
let _desugar =
    ActivityExtensions.Run(activity,
        ActivityExtensions.Delay(activity, (fun () ->
            ActivityExtensions.Combine(activity,
                ActivityExtensions.Yield(activity, setStartTime DateTime.UtcNow),
                ActivityExtensions.Delay(activity, (fun () ->
                    ActivityExtensions.Yield(activity, setTag "count" 2)
                ))
            ))
        )
    )

☝️ Notes:

The Delay method evaluates the thunk f: unit -> ActivityAction to return the wrapped ActivityAction already involving a deferred action.
The Combine method is used to chain two ActivityActions into one, calling each one in series.
The final Run is the only method really using the input activity. It evaluates the built ActivityAction, resulting in the change/mutation of the activity.
The extension methods are marked as not EditorBrowsable to improve the developer experience: when we use dot notation on the activity, the extension methods are not suggested for code completion.

Custom operations 🚀

What: builder methods annotated with [<CustomOperation("myOperation")>]

Use cases: add new keywords, build a custom DSL. For example, the query core CE supports where and select keywords like LINQ.

⚠️ Warning: you may need additional things that are not well documented:

Additional properties for the CustomOperation attribute:
- AllowIntoPattern, MaintainsVariableSpace
- IsLikeJoin, IsLikeGroupJoin, JoinConditionWord
- IsLikeZip...
Additional attributes on the method parameters, like [<ProjectionParameter>]

This topic would deserve a complete article. Still, you can find additional information here:

Computation Expressions Workshop: 7 - Query Expressions | GitHub
The F# 4.1 Language Specification: search for SimpleSequenceBuilder to get all the examples that show how the translation works between the CE body and the custom operations defined on the builder.

Final words

Let's review the pros and cons of computation expressions to get the full picture and make the appropriate decision about writing our own computation expression.

Benefits ✅

Computation expressions offer significant advantages for F# developers. They provide increased readability through imperative-like code that feels natural while maintaining functional principles. They also reduce boilerplate by hiding complex "machinery" behind clean, expressive syntax. Additionally, their extensibility allows developers to extend existing CEs or even add the CE syntax support to any type. Finally, we can create domain-specific languages (DSLs) to reify domain concepts through custom operations.

Limits ⚠️

However, computation expressions come with certain limitations that developers should be aware of. Compiler error messages within CE bodies can often be cryptic and difficult to debug, making troubleshooting more challenging. Nesting different CEs can make code more cumbersome to work with—for example, combining async and result patterns. While custom combining CEs like asyncResult in FsToolkit offer alternatives, they add complexity. Finally, writing custom CEs can be challenging, requiring developers to implement the right methods correctly and understand the underlying functional programming concepts.

Guidelines 📃

Choose the main behaviour: monoidal? monadic? applicative?
- Prefer a single behaviour unless it's a generic/multi-purpose CE
Create a builder class
Implement the main methods to get the selected behaviour
Use/Test your CE to verify it compiles (see typical compilation errors below), produces the expected result, and performs well.

1. This control construct may only be used if the computation expression builder defines a 'Delay' method
   => Just implement the missing method in the builder.
2. Type constraint mismatch. The type ''b seq' is not compatible with type ''a list'
   => Inspect the builder methods and track an inconsistency.

Tips 💡

Get inspired by existing codebases that provide CEs - examples:
- FSharpPlus → monad
- FsToolkit.ErrorHandling → option, result, validation
- Expecto: Testing library (test "..." {...})
- Farmer: Infra as code for Azure (storageAccount {...})
- Saturn: Web framework on top of ASP.NET Core (application {...})
Overload methods to support more use cases like different input types
- Async<Result<_,_>> + Async<_> + Result<_,_>
- Option<_> and Nullable<_>

🍔 Quiz

Question 1: What is the primary purpose of computation expressions in F#?

A. To replace all functional programming patterns

B. To provide imperative-like syntax for sequencing and combining computations

C. To eliminate the need for type annotations

D. To make F# code compatible with C#

Answer

B. To provide imperative-like syntax for sequencing and combining computations ✅

Question 2: Which keywords identify a monadic computation expression?

A. yield and yield!

B. let! and return

C. let! and and!

D. do! and while

Answer

A. yield and yield! keywords identify a monoidal CE ❌

B. let! and return keywords identify a monadic CE ✅

C. let! and and! keywords identify a applicative CE ❌

D. do! and while keywords can be used with any kind of CE ❌

Question 3: In a computation expression builder, what does the `Bind` method correspond to?

A. The yield keyword

B. The return keyword

C. The let! keyword

D. The else keyword when omitted

Answer

A. The yield keyword corresponds to the Yield method ❌

B. The return keyword corresponds to the Return method ❌

C. The let! keyword corresponds to the Bind method ✅

D. The else keyword, when omitted, corresponds to the Zero method ❌

Question 4: What is the signature of a typical monadic `Bind` method?

A. M<T> -> M<T>

B. T -> M<T>

C. M<T> * (T -> M) -> M

D. M<T> * M -> M<T * U>

Answer

A. M<T> -> M<T> is the typical signature of ReturnFrom and YieldFrom methods ❌

B. T -> M<T> is the typical signature of Return and Yield methods ❌

C. M<T> * (T -> M) -> M is the typical signature of the Bind method ✅

D. M<T> * M -> M<T * U> is the typical signature of MergeSources method ❌

🔗 Additional resources

Code examples in FSharpTraining.sln —Romain Deneau
The "Computation Expressions" series —F# for Fun and Profit
All CE methods | Learn F# —Microsoft
Computation Expressions Workshop
The F# Computation Expression Zoo —Tomas Petricek and Don Syme
- Documentation | Try Joinads —Tomas Petricek
Extending F# through Computation Expressions: 📹 Video • 📜 Article

F# applicative computation expressions

Romain Deneau — Fri, 22 Aug 2025 14:42:00 +0000

This fifth article in the series dedicated to F# computation expressions is a guide to writing F# computation expressions (CE) with applicative behavior.

An applicative CE offers the widest variety of method combinations for the CE builder. We'll examine in detail when these are useful, based on compiler error messages and desugared versions of the expressions used in these tests.

Table of contents

Introduction
Builder method signatures
Applicative CE example: validation
- Base implementation
- Use case: validate a customer
- Other method combinations
- FsToolkit validation CE
Applicative CE example: async
Conclusion

Introduction

Applicative computation expressions are characterized by the use of the and! keyword introduced in F# 5.

Builder method signatures

An applicative CE builder typically defines the following methods:

// Method        | Signature                        | Comment
    MergeSources : mx: M<X> * my: M<Y> -> M<X * Y>  ; (* ≡ *) map2 (fun x y -> x, y) mx my
    BindReturn   : m: M<T> * f: (T -> U) -> M<U>    ; (* ≡ *) map f m

// Additional methods for performance optimization
// - MergeSourcesN, N >= 3:
    MergeSources3: mx: M<X> * my: M<Y> * mz: M<Z> -> M<X * Y * Z>
// - BindNReturn, N >= 2:
    Bind2Return  : mx: M<X> * my: M<Y> * f: (X * Y -> U) -> M<U> ; (* ≡ *) map2 f mx my
// - BindN, N >= 2:
    Bind2        : mx: M<X> * my: M<Y> * f: (X * Y -> M<U>) -> M<U>
    Bind3        : mx: M<X> * my: M<Y> * mz: M<Z> * f: (X * Y * Z -> M<U>) -> M<U>

Applicative CE example: validation

The purpose is to accumulate errors given by a group of results.

Base implementation

The implementation relies on the type Validation<'t, 'e> that is an alias of Result<'t, 'e list>. The Error case holds the list of accumulated errors.

The builder implements two essential methods to achieve applicative behavior: BindReturn and MergeSources.

type Validation<'t, 'e> = Result<'t, 'e list>

type ValidationBuilder() =
    member _.BindReturn(x: Validation<'t, 'e>, f: 't -> 'u) =
        Result.map f x

    member _.MergeSources(x: Validation<'t, 'e>, y: Validation<'u, 'e>) =
        match (x, y) with
        | Ok v1,    Ok v2    -> Ok(v1, v2)     // Merge both values in a pair
        | Error e1, Error e2 -> Error(e1 @ e2) // Merge errors into a single list
        | Error e, _ | _, Error e -> Error e   // Short-circuit on single error source

let validation = ValidationBuilder()

Use case: validate a customer

Let's create a smart constructor to get a valid customer: whose name is not null or empty, and whose height in centimeters is strictly positive. If both the name and height are invalid, we want to know both errors at once. This makes the use case ideal for the validation {} computation expression with a let! ... and! ... expression.

type [<Measure>] cm
type Customer = { Name: string; Height: int<cm> }

let validateHeight height =
    if height <= 0<cm>
    then Error ["Height must be positive"]
    else Ok height

let validateName name =
    if System.String.IsNullOrWhiteSpace name
    then Error ["Name can't be empty"]
    else Ok name

module Customer =
    let tryCreate name height : Validation<Customer, string> =
        validation {
            let! validName = validateName name
            and! validHeight = validateHeight height
            return { Name = validName; Height = validHeight }
        }

let c1 = Customer.tryCreate "Bob" 180<cm>  // Ok { Name = "Bob"; Height = 180 }
let c2 = Customer.tryCreate "Bob" 0<cm> // Error ["Height must be positive"]
let c3 = Customer.tryCreate "" 0<cm>    // Error ["Name can't be empty"; "Height must be positive"]

Desugaring:

validation {                                ; validation.BindReturn(
                                            ;     validation.MergeSources(
    let! name = validateName "Bob"          ;         validateName "Bob",
    and! height = validateHeight 0<cm>      ;         validateHeight 0<cm>
                                            ;     ),
    return { Name = name; Height = height } ;     (fun (name, height) -> { Name = name; Height = height })
}                                           ; )

Other method combinations

Let's explore different method combinations to see what the compiler requires and how the expressions are desugared.

For convenience, let's start by defining some helpers:

The Err active pattern simplifies pattern matching on Validation<_, _> tuples, distinguishing between Ok (all elements are valid) and Error (any element is invalid). Err is used in bind2 and bind3.
bind2 and bind3 are the base helpers used to implement the builder methods that deal with two and three Validation<_, _> parameters respectively.

let (|Err|) (vx: Validation<'x, 'e>) =
    match vx with
    | Ok _ -> []
    | Error errors -> errors

module Validation =
    let ok (x: 'x) : Validation<'x, 'e> = Ok x
    let error (e: 'e) : Validation<'x, 'e> = Error [ e ]
    let errors (e: 'e list) : Validation<'x, 'e> = Error e

    let bind2 (vx: Validation<'x, 'e>) (vy: Validation<'y, 'e>) (f: 'x -> 'y -> Validation<'u, 'e>) : Validation<'u, 'e> =
        match vx, vy with
        | Ok x, Ok y -> f x y
        | Err ex, Err ey -> Error(ex @ ey)

    let bind3 (vx: Validation<'x, 'e>) (vy: Validation<'y, 'e>) (vz: Validation<'z, 'e>) (f: 'x -> 'y -> 'z -> Validation<'u, 'e>) : Validation<'u, 'e> =
        match vx, vy, vz with
        | Ok x, Ok y, Ok z -> f x y z
        | Err ex, Err ey, Err ez -> Error(ex @ ey @ ez)

Two-element expression

To handle an expression like let! ... and! ..., the combination of Bind2 and Return is valid for the compiler:

type ValidationBuilder() =
    member _.Bind2(vx: Validation<'x, 'e>, vy: Validation<'y, 'e>, f: 'x * 'y -> Validation<'u, 'e>) : Validation<'u, 'e> =
        Validation.bind2 vx vy (fun x y -> f (x, y))

    member _.Return(x: 't) =
        Validation.ok x

let test =
    validation {
        let! x = Validation.ok 1
        and! y = Validation.ok 10
        return x + y
    }

let test_desugared =
    validation.Bind2(
        Validation.ok 1,
        Validation.ok 10,
        (fun (x, y) -> validation.Return(x + y))
    )

Examining the desugared version, we see that this method combination is not more efficient than the classic BindReturn and MergeSources approach. Let's try using only Bind2Return!

type ValidationBuilder() =
    member _.Bind2Return(vx: Validation<'x, 'e>, vy: Validation<'y, 'e>, f: 'x * 'y -> 'u) : Validation<'u, 'e> =
        Validation.bind2 vx vy (fun x y -> Validation.ok (f (x, y)))

let test =
    validation {
        let! x = Validation.ok 1
        and! y = Validation.ok 10
        return x + y
    }

let test_desugared =
    validation.Bind2Return(
        Validation.ok 1,
        Validation.ok 10,
        (fun (x, y) -> x + y)
    )

In this case, Bind2Return can be the only method needed by the compiler. The desugared result confirms that it's the only method call, leading to a more efficient builder implementation for handling let! ... and! ... expressions.

Three-element expression

The regular BindReturn and MergeSources method combination can handle an expression like let! ... and! ... and! ...:

type ValidationBuilder() =
    member _.BindReturn(x: Validation<'t, 'e>, f: 't -> 'u) : Validation<'u, 'e> =
        Result.map f x

    member _.MergeSources(vx: Validation<'x, 'e>, vy: Validation<'y, 'e>) : Validation<'x * 'y, 'e> =
        Validation.bind2 vx vy (fun x y -> Validation.ok (x, y))

let test =
    validation {
        let! x = Validation.ok 1
        and! y = Validation.ok 2
        and! z = Validation.ok 3
        return (z - x) * y
    }

let test_desugared =
    validation.BindReturn(
        validation.MergeSources(
            Validation.ok 1,
            validation.MergeSources(
                Validation.ok 2,
                Validation.ok 3
            )
        ),
        (fun (x, (y, z)) -> (z - x) * y)
    )

The desugared version shows that two MergeSources calls are needed to assemble the three values x, y and z required for the final calculation (z - x) * y. If the MergeSources3 method is provided, the compiler can replace this double call to MergeSources with a single call to MergeSources3, simplifying the parameter deconstruction to obtain x, y and z—from (x, (y, z)) to (x, y, z):

type ValidationBuilder() =
    member _.BindReturn(x: Validation<'t, 'e>, f: 't -> 'u) : Validation<'u, 'e> =
        Result.map f x

    member _.MergeSources(vx: Validation<'x, 'e>, vy: Validation<'y, 'e>) : Validation<'x * 'y, 'e> =
        Validation.bind2 vx vy (fun x y -> Validation.ok (x, y))

    member _.MergeSources3(vx: Validation<'x, 'e>, vy: Validation<'y, 'e>, vz: Validation<'z, 'e>) : Validation<'x * 'y * 'z, 'e> =
        Validation.bind3 vx vy vz (fun x y z -> Validation.ok (x, y, z))

let test =
    validation {
        let! x = Validation.ok 1
        and! y = Validation.ok 2
        and! z = Validation.ok 3
        return (z - x) * y
    }

let test_desugared =
    validation.BindReturn(
        validation.MergeSources3(
            Validation.ok 1,
            Validation.ok 2,
            Validation.ok 3
        ),
        (fun (x, y, z) -> (z - x) * y)
    )

Note that MergeSources is not used, but is still required for compilation 🤷

Finally, we can verify that the locally optimal builder only needs a single method, Bind3Return:

type ValidationBuilder() =
    member _.Bind3Return(vx: Validation<'x, 'e>, vy: Validation<'y, 'e>, vz: Validation<'z, 'e>, f: 'x * 'y * 'z -> 'u) : Validation<'u, 'e> =
        Validation.bind3 vx vy vz (fun x y z -> Validation.ok (f (x, y, z)))

let test =
    validation {
        let! x = Validation.ok 1
        and! y = Validation.ok 2
        and! z = Validation.ok 3
        return (z - x) * y
    }

let test_desugared =
    validation.Bind3Return(
        Validation.ok 1,
        Validation.ok 2,
        Validation.ok 3,
        (fun (x, y, z) -> (z - x) * y)
    )

Method combination conclusion

The regular BindReturn and MergeSources method combination can handle all cases, but requires one additional call to MergeSources per additional input value. You can optimize the number of builder method calls by providing additional builder methods. BindNReturn methods are the most efficient option. MergeSourcesN methods are less efficient but more versatile, as they can be combined to handle tuples with more elements.

FsToolkit validation CE

FsToolkit.ErrorHandling provides a similar validation {} implementation.

The desugaring reveals the definition of additional methods: Delay, Run, Source📍

validation {                                ;  validation.Run(
    let! name = validateName "Bob"          ;      validation.Delay(fun () ->
    and! height = validateHeight 0<cm>      ;          validation.BindReturn(
    return { Name = name; Height = height } ;              validation.MergeSources(
}                                           ;                  validation.Source(validateName "Bob"),
                                            ;                  validation.Source(validateHeight 0<cm>)
                                            ;              ),
                                            ;              (fun (name, height) -> { Name = name; Height = height })
                                            ;          )
                                            ;      )
                                            ;  )

`Source` methods

In FsToolkit's validation {}, there are a couple of Source methods defined:

The main definition is the id function.
Another overload is interesting: it converts a Result<'a, 'e> into a Validation<'a, 'e>. Because it's defined as an extension method, it has lower priority for the compiler, which improves type inference. Otherwise, type annotations would be required.

☝️ Note: Source documentation is scarce. The most valuable information comes from a Stack Overflow question referenced in the FsToolkit source code!

Applicative CE example: async

As of today, we have to use intermediary calls to Async.StartChild to get the tasks executed in parallel. This feature can be implemented as an applicative behavior behind the let! ... and and! ... syntax. Let's extend the AsyncBuilder class to support this feature.

module Async =
    let bind2 (tx: Async<'x>) (ty: Async<'y>) (f: 'x -> 'y -> Async<'u>) : Async<'u> =
        async {
            let! cx = Async.StartChild tx
            let! cy = Async.StartChild ty
            let! rx = cx
            let! ry = cy
            return! f rx ry
        }

    let bind3 (tx: Async<'x>) (ty: Async<'y>) (tz: Async<'z>) (f: 'x -> 'y -> 'z -> Async<'u>) : Async<'u> =
        async {
            let! cx = Async.StartChild tx
            let! cy = Async.StartChild ty
            let! cz = Async.StartChild tz
            let! rx = cx
            let! ry = cy
            let! rz = cz
            return! f rx ry rz
        }

type AsyncBuilder with
    member _.Bind2Return(tx: Async<'x>, ty: Async<'y>, f: 'x * 'y -> 'u) : Async<'u> =
        Async.bind2 tx ty (fun x y -> async { return f (x, y) })

    member _.Bind3Return(tx: Async<'x>, ty: Async<'y>, tz: Async<'z>, f: 'x * 'y * 'z -> 'u) : Async<'u> =
        Async.bind3 tx ty tz (fun x y z -> async { return f (x, y, z) })

    member _.MergeSources(tx: Async<'x>, ty: Async<'y>) : Async<'x * 'y> =
        Async.bind2 tx ty (fun x y -> async { return x, y })

    member _.MergeSources3(tx: Async<'x>, ty: Async<'y>, tz: Async<'z>) : Async<'x * 'y * 'z> =
        Async.bind3 tx ty tz (fun x y z -> async { return x, y, z })

The calls to Async.StartChild are done in Async.bind2. We provide an Async.bind3 to optimize the usage up to three parallel asynchronous tasks.

Let's test this by comparing the execution duration of three tasks run in series versus in parallel:

open System
open Swensen.Unquote
open Xunit

let returnAfter (t: TimeSpan) x =
    async {
        do! Async.Sleep t
        return x
    }

type Take =
    | LessThan of TimeSpan
    | MoreThan of TimeSpan

let should takes task =
    let sw = Diagnostics.Stopwatch.StartNew()
    let _ = Async.RunSynchronously task
    sw.Stop()
    let actualTime = sw.Elapsed

    test
        <@
            takes
            |> List.forall (
                function
                | Take.LessThan t -> actualTime < t
                | Take.MoreThan t -> actualTime > t
            )
        @>

[<Fact>]
let ``Should run the tasks in series`` () =
    let taskInSeries =
        async {
            let! x = 1 |> returnAfter (TimeSpan.FromMilliseconds 10)
            let! y = 2 |> returnAfter (TimeSpan.FromMilliseconds 15)
            let! z = 3 |> returnAfter (TimeSpan.FromMilliseconds 5)
            return x + y + z
        }

    taskInSeries |> should [ Take.MoreThan(TimeSpan.FromMilliseconds 40) ]

[<Fact>]
let ``Should run the 3 tasks in parallel`` () =
    let tasksInParallel =
        async {
            let! x = 1 |> returnAfter (TimeSpan.FromMilliseconds 10)
            and! y = 2 |> returnAfter (TimeSpan.FromMilliseconds 15)
            and! z = 3 |> returnAfter (TimeSpan.FromMilliseconds 5)
            return x + y + z
        }

    tasksInParallel |> should [ Take.MoreThan(TimeSpan.FromMilliseconds 15); Take.LessThan(TimeSpan.FromMilliseconds 40) ]

Conclusion

Applicative computation expressions in F# enable parallel computation and error accumulation using the and! syntax introduced in F# 5. By implementing MergeSources and BindReturn methods, you can create powerful validation workflows that collect all errors instead of stopping at the first failure, as well as efficient computations that leverage parallelism. This approach is particularly valuable for form validation, configuration parsing, and any scenario where you want to provide comprehensive feedback to users about multiple validation failures simultaneously. While applicative computation expressions are less versatile than monadic ones, they excel in specific scenarios where their unique capabilities make a significant difference.

F# monadic computation expressions

Romain Deneau — Fri, 22 Aug 2025 14:23:00 +0000

This fourth article in the series dedicated to F# computation expressions is a guide to writing F# computation expressions having a monadic behavior.

Table of contents

Introduction
Builder method signatures
- Monadic vs Monoidal
- CE monadic and delayed
CE monadic examples
- CE monadic example - result {}
- CE monadic: FSharpPlus monad {}
Monad stack, monad transformers
- 1. Academic style (with FSharpPlus)
- 2. Idiomatic style
Conclusion

Introduction

A monadic CE can be identified by the usage of let! and return keywords, revealing the monadic bind and return operations.

Builder method signatures

Behind the scenes, builders of these CEs should/can implement these methods:

// Method     | Signature                                     | CE syntax supported
    Bind      : M<T> * (T -> M<U>) -> M<U>                    ; let! x = xs in ...
                (* when T = unit *)                           ; do! command
    Return    : T -> M<T>                                     ; return x
    ReturnFrom: M<T> -> M<T>                                  ; return!

// Additional methods
    Zero      : unit -> M<T>                                  ; if // without `else` // Typically `unit -> M<unit>`
    Combine   : M<unit> * M<T> -> M<T>                        ; e1; e2  // e.g. one loop followed by another one
    TryWith   : M<T> -> (exn -> M<T>) -> M<T>                 ; try/with
    TryFinally: M<T> * (unit -> M<unit>) -> M<T>              ; try/finally
    While     : (unit -> bool) * (unit -> M<unit>) -> M<unit> ; while cond do command ()
    For       : seq<T> * (T -> M<unit>) -> M<unit>            ; for i in xs do command i ; for i = 0 to n do command i
    Using     : T * (T -> M<U>) -> M<U> when T :> IDisposable ; use! x = xs in ...

Monadic vs Monoidal

`Return` (monadic) vs `Yield` (monoidal)

Same signature: T -> M<T>
A series of return is not expected → Monadic Combine takes only a monadic command M<unit> as 1st param
CE enforces appropriate syntax by implementing one of these methods:
- seq {} allows yield but not return
- async {}: the reverse

`For` and `While`

Method	CE	Signature
`For`	Monoidal	`seq<T> * (T -> M<U>) -> M<U> or seq<M<U>>`
	Monadic	`seq<T> * (T -> M<unit>) -> M<unit>`
`While`	Monoidal	`(unit -> bool) * Delayed<T> -> M<T>`
	Monadic	`(unit -> bool) * (unit -> M<unit>) -> M<unit>`

👉 Different use cases:

Monoidal: Comprehension syntax
Monadic: Series of effectful commands

CE monadic and delayed

Like monoidal CE, monadic CE can use a Delayed<'t> type.
→ Impacts on the method signatures:

 Delay      : thunk: (unit -> M<T>) -> Delayed<T>
 Run        : Delayed<T> -> M<T>
 Combine    : M<unit> * Delayed<T> -> M<T>
 While      : predicate: (unit -> bool) * Delayed<unit> -> M<unit>
 TryFinally : Delayed<T> * finalizer: (unit -> unit) -> M<T>
 TryWith    : Delayed<T> * handler: (exn -> unit) -> M<T>

CE monadic examples

☝️ The initial CEs studied—logger {} and option {}—were monadic.

CE monadic example - `result {}`

Let's build a result {} CE to play with dice!

type ResultBuilder() =
    member _.Bind(rx, f) = rx |> Result.bind f
    member _.Return(x) = Ok x
    member _.ReturnFrom(rx) = rx

let result = ResultBuilder()

// ---

let rollDice =
    let random = Random(Guid.NewGuid().GetHashCode())
    fun () -> random.Next(1, 7)

let tryGetDice dice =
    result {
        if rollDice() <> dice then
            return! Error $"Not the expected dice {dice}."
    }

let tryGetAPairOf6 =
    result {
        let n = 6
        do! tryGetDice n
        do! tryGetDice n
        return true
    }

Desugaring:

let tryGetAPairOf6 =
    result {                ;
        let n = 6           ;   let n = 6
        do! tryGetDice n    ;   result.Bind(tryGetDice n, (fun () ->
        do! tryGetDice n    ;        result.Bind(tryGetDice n, (fun () ->
        return true         ;            result.Return(true)
    }                       ;        ))
                            ;   ))

CE monadic: FSharpPlus `monad {}`

FSharpPlus provides a monad CE

Works for all monadic types: Option, Result, ... and even Lazy 🎉
Supports monad stacks with monad transformers 📍

⚠️ Limits:

Confusing: the monad CE has 4 flavours to cover all cases: delayed or strict, embedded side-effects or not
Based on SRTP: can be very long to compile!
Documentation not exhaustive, relying on Haskell knowledges
Very Haskell-oriented: not idiomatic F#

Monad stack, monad transformers

A monad stack is a composition of different monads.
→ Example: Async+Option.

We can handle it with 2 styles: academic or F# idiomatic.

1. Academic style (with FSharpPlus)

Monad transformer (here MaybeT)
→ Extends Async to handle both effects
→ Resulting type: MaybeT<Async<'t>>

✅ Reusable with other inner monads
❌ Less easy to evaluate the resulting value
❌ Not idiomatic

2. Idiomatic style

Custom CE asyncOption, based on the async CE, handling the Async<Option<'t>> type

type AsyncOption<'T> = Async<Option<'T>> // Convenient alias, not required

type AsyncOptionBuilder() =
    member _.Bind(aoX: AsyncOption<'a>, f: 'a -> AsyncOption<'b>) : AsyncOption<'b> =
        async {
            match! aoX with
            | Some x -> return! f x
            | None -> return None
        }

    member _.Return(x: 'a) : AsyncOption<'a> =
        async { return Some x }

⚠️ Limits: Not reusable, just copiable for asyncResult, for instance

Conclusion

Monadic computation expressions in F# provide a familiar syntax—based on let! and return keywords—for sequencing effectful computations. While you can build custom monadic CEs for specific domain needs or leverage libraries like FSharpPlus for academic-style programming, the most practical approach is often creating idiomatic F# builders tailored to your specific monad combinations, such as Async<Option<'t>> or Async<Result<'t, 'e>>. This strikes the right balance between expressiveness and maintainability in typical F# codebases.

F# monoidal computation expressions

Romain Deneau — Fri, 22 Aug 2025 13:50:00 +0000

This third article in the series dedicated to F# computation expressions is a guide to writing F# computation expressions having a monoidal behavior.

Table of contents

Introduction
Builder method signatures
CE monoidal vs comprehension
- Comprehension definition
- Comparison
- Minimal set of methods expected for each
CE monoidal example: multiplication {}
- Exercise
- Desugaring
Delayed<T> type
CE monoidal kinds
- CE monoidal to generate a collection
Conclusion

Introduction

A monoidal CE can be identified by the usage of yield and yield! keywords.

Relationship with the monoid:
→ Hidden in the builder methods:

+ operation → Combine method
e neutral element → Zero method

Builder method signatures

Like we did for functional patterns, we use the generic type notation:

M<T>: type returned by the CE
Delayed<T>: presented later 📍

// Method     | Signature                           | CE syntax supported
    Yield     : T -> M<T>                           ; yield x
    YieldFrom : M<T> -> M<T>                        ; yield! xs
    Zero      : unit -> M<T>                        ; if // without `else`  // Monoid neutral element
    Combine   : M<T> * Delayed<T> -> M<T>                                   // Monoid + operation
    Delay     : (unit -> M<T>) -> Delayed<T>        ; // always required with Combine

// Other additional methods
    Run       : Delayed<T> -> M<T>
    For       : seq<T> * (T -> M<U>) -> M<U>        ; for i in seq do yield ... ; for i = 0 to n do yield ...
                              (* or *)  seq<M<U>>
    While     : (unit -> bool) * Delayed<T> -> M<T> ; while cond do yield...
    TryWith   : M<T> -> (exn -> M<T>) -> M<T>       ; try/with
    TryFinally: Delayed<T> * (unit -> unit) -> M<T> ; try/finally

CE monoidal vs comprehension

Comprehension definition

It is the concise and declarative syntax to build collections with control flow keywords if, for, while... and ranges start..end.

Comparison

Similar syntax from caller perspective
Distinct overlapping concepts

Minimal set of methods expected for each

Monoidal CE: Yield, Combine, Zero
Comprehension: For, Yield

CE monoidal example: `multiplication {}`

Let's build a CE that multiplies the integers yielded in the computation body:
→ CE type: M<T> = int • Monoid operation = * • Neutral element = 1

type MultiplicationBuilder() =
    member _.Zero() = 1
    member _.Yield(x) = x
    member _.Combine(x, y) = x * y
    member _.Delay(f) = f () // eager evaluation

    member m.For(xs, f) =
        (m.Zero(), xs)
        ||> Seq.fold (fun res x -> m.Combine(res, f x))

let multiplication = MultiplicationBuilder()

let shouldBe10 = multiplication { yield 5; yield 2 }
let factorialOf5 = multiplication { for i in 2..5 -> i } // 2 * 3 * 4 * 5

Exercise

Copy this snippet in vs code
Comment out builder methods
- To start with an empty builder, add this line let _ = () in the body.
- After adding the first method, this line can be removed.
Let the compiler errors in shouldBe10 and factorialOf5 guide you to add the relevant methods.

Desugaring

Desugared multiplication { yield 5; yield 2 }:

// Original
let shouldBe10 =
    multiplication.Delay(fun () ->
        multiplication.Combine(
            multiplication.Yield(5),
            multiplication.Delay(fun () ->
                multiplication.Yield(2)
            )
        )
    )

// Simplified (without Delay)
let shouldBe10 =
    multiplication.Combine(
        multiplication.Yield(5),
        multiplication.Yield(2)
    )

Desugared multiplication { for i in 2..5 -> i }:

// Original
let factorialOf5 =
    multiplication.Delay (fun () ->
        multiplication.For({2..5}, (fun _arg2 ->
            let i = _arg2 in multiplication.Yield(i))
        )
    )

// Simplified
let factorialOf5 =
    multiplication.For({2..5}, (fun i -> multiplication.Yield(i)))

`Delayed<T>` type

Delayed<T> represents a delayed computation and is used in these methods:

Delay returns this type, hence defines it for the CE
Combine, Run, While and TryFinally used it as input parameter

 Delay      : thunk: (unit -> M<T>) -> Delayed<T>
 Combine    : M<T> * Delayed<T> -> M<T>
 Run        : Delayed<T> -> M<T>
 While      : predicate: (unit -> bool) * Delayed<T> -> M<T>
 TryFinally : Delayed<T> * finalizer: (unit -> unit) -> M<T>

Delay is required by the presence of Combine.
Delay is called each time converting from M<T> to Delayed<T> is needed.
Delayed<T> is internal to the CE.
- Run is required at the end to get back the M<T>...
- ... only when Delayed<T> ≠ M<T>, otherwise it can be omitted.

👉 Enables to implement laziness and short-circuiting at the CE level.

Example: lazy multiplication {} with Combine optimized when x = 0

type MultiplicationBuilder() =
    member _.Zero() = 1
    member _.Yield(x) = x
    member _.Delay(thunk: unit -> int) = thunk // Lazy evaluation
    member _.Run(delayedX: unit -> int) = delayedX () // Required to get a final `int`

    member _.Combine(x: int, delayedY: unit -> int) : int =
        match x with
        | 0 -> 0 // 👈 Short-circuit for multiplication by zero
        | _ -> x * delayedY ()

    member m.For(xs, f) =
        (m.Zero(), xs) ||> Seq.fold (fun res x -> m.Combine(res, m.Delay(fun () -> f x)))

Difference	Eager	Lazy
`Delay` return type	`int`	`unit -> int`
`Run`	Omitted	Required to get back an `int`
`Combine` 2nd parameter	`int`	`unit -> int`
`For` calling `Delay`	Omitted	Explicit but not required here

CE monoidal kinds

With multiplication {}, we've seen a first kind of monoidal CE:
→ To reduce multiple yielded values into 1.

There is a second kind of monoidal CE:
→ To aggregate multiple yielded values into a collection.
→ Example: seq {} returns a 't seq.

CE monoidal to generate a collection

Let's build a list {} monoidal CE!

type ListBuilder() =
    member _.Zero() = [] // List.empty
    member _.Yield(x) = [x] // List.singleton
    member _.YieldFrom(xs) = xs
    member _.Delay(thunk: unit -> 't list) = thunk () // eager evaluation
    member _.Combine(xs, ys) = xs @ ys // List.append
    member _.For(xs, f: _ seq) = xs |> Seq.collect f |> Seq.toList

let list = ListBuilder()

💡 Notes:

M<T> is 't list → type returned by Yield and Zero

For uses an intermediary sequence to collect the values returned by f.

Let's test the CE to generate the list [begin; 16; 9; 4; 1; 2; 4; 6; 8; end]
(Desugared code simplified)

Comparison with the same expression in a list comprehension:

list { expr } vs [ expr ]:

[ expr ] uses a hidden seq all through the computation and ends with a toList
All methods are inlined:

Method	`list { expr }`	`[ expr ]`
`Combine`	`xs @ ys => List.append`	`Seq.append`
`Yield`	`[x] => List.singleton`	`Seq.singleton`
`Zero`	`[] => List.empty`	`Seq.empty`
`For`	`Seq.collect` & `Seq.toList`	`Seq.collect`

Conclusion

Monoidal computation expressions provide an elegant and powerful syntax for combining and aggregating values in F#. By implementing a builder with just a few key methods—Combine and Zero which correspond to the monoid's + operation and e neutral element, alongside Yield, YieldFrom, and For methods to support comprehension syntax—you can either reduce values to a single result (similar to the Composite design pattern) or build collections with natural, imperative-like code. Additionally, leveraging the Delayed<T> type enables optimization opportunities for both behavior and performance within your computation expressions.

Functional patterns for F# computation expressions

Romain Deneau — Fri, 22 Aug 2025 13:10:00 +0000

This second article in the series dedicated to F# computation expressions is an introduction to functional patterns for F# developers who wish to write or maintain computation expressions, i.e., applicative, functor, monad, and monoid.

☝️ Note: There are more functional patterns coming from category theory, but they are out of scope.

Table of contents

Introduction
- F# and functional patterns
- General definition
Monoid
- Monoid laws
- Monoid examples
Functor
- Functor definition
- Functor laws
- Functor examples
Monad
- Monad definition
- Monad laws
- Monad examples
- Monad vs Functor
- Monad alternative definition
- Regular functions vs monadic functions
- Monads vs Effects
- Other common monads
Applicative (Functor)
- Applicative definition
- Applicative laws
- Applicative vs Functor
- Applicative vs Monad
- Applicative: multi-param curried function
- Applicative styles
- Applicative vs Monadic behaviour
- Applicative parallel behaviour
Wrap up
- Functional patterns key points
- Functional patterns in F# language
- Additional resources 🔗

Introduction

F# and functional patterns

Unlike other strongly typed programming languages such as Haskell, OCaml and Scala, these functional patterns are not necessarily useful for writing code in F#. Indeed, Don Syme designed the language to be easily accessible, in order to reach a wider audience of developers and avoid too big a gap with other .NET languages, particularly C#, its flagship language. However, these patterns are an integral part of the F# language, without necessarily being realized. But if you want to understand the different kinds of computation expressions, these patterns are very useful.

F# uses these functional patterns under the hood:

Option and Result are monadic types
Async is monadic too
Collection types Array, List and Seq are both monadic and monoidal types!
Computation expressions can be monadic or applicative or monoidal

General definition

In F#, the functional patterns consist of:

A type
1 or 2 operations on this type
A possible special instance of this type
Some laws constraining/shaping the whole

The type is generally noted M<'T>, where M is a generic type and 'T its type parameter referring to the type of elements that can be contained in M.

Monoid

Etymology (Greek): monos (single, unique) • eidos (form, appearance)

≃ Type T defining a set with:

Binary operation +: T -> T -> T → To combine 2 elements into 1
Neutral element e (a.k.a. identity)

Monoid laws

1. Associativity

+ is associative
→ a + (b + c) ≡ (a + b) + c

2. Identity Element

e is combinable with any instance a of T without effect
→ a + e ≡ e + a ≡ a

Monoid examples

Type	Operator	Identity	Law 2
`int`	`+` (add)	`0`	`i + 0 = 0 + i = i`
`int`	`` (multiply)*	`1`	`i * 1 = 1 * i = i`
`string`	`+` (concat)	`""` (empty string)	`s + "" = "" + s = s`
`'a list`	`@` (`List.append`)	`[]` (empty list)	`l @ [] = [] @ l = l`
Functions	`>>` (compose)	`id` (`fun x -> x`)	`f >> id = id >> f = f`

💡 Note: The monoid is a generalization of the Composite OO design pattern - see
Composite as a monoid by Mark Seemann

Functor

Functor definition

≃ Any generic type, noted F<'T>, with a map operation:

Signature: map: (f: 'T -> 'U) -> F<'T> -> F<'U>

map preserves the structure: e.g. mapping a List returns another List.

Functor laws

Law 1 - Identity law

Mapping the id function over a Functor F should not change F.
→ map id F ≡ F

Law 2 - Composition law

Mapping the composition of 2 functions f and g is the same as mapping f and then mapping g over the result.
→ map (f >> g) ≡ map f >> map g

Functor examples

Type	Map
`Option<'T>`	`Option.map`
`Result<'T, _>`	`Result.map`
`List<'T>`	`List.map`
`Array<'T>`	`Array.map`
`Seq<'T>`	`Seq.map`

Async<'T> too, but through the async CE 📍

Monad

Monad definition

≃ Any generic type, noted M<'T>, with:

Construction function return
- Signature : (value: 'T) -> M<'T>
- ≃ Wrap (lift/elevate) a value
Chaining function bind
- Noted >>= (> > =) as an infix operator
- Signature : (f: 'T -> M<'U>) -> M<'T> -> M<'U>
- Take a monadic function f
- Call it with the eventual wrapped value(s)
- Get back a new monadic instance of this type

Monad laws

1. Left Identity

return then bind are neutral.
→ return >> bind f ≡ f

2. Right Identity

bind return is neutral, equivalent to the id function:
→ m |> bind return ≡ m |> id ≡ m

☝️ It's possible because return has the signature of a monadic function.

3. Associativity

bind is associative.

Given two monadic functions f: 'a -> M<'b> and g: 'b -> M<'c>
→ (m |> bind f) |> bind g ≡ m |> bind (f >> bind g)

💡 bind allows us to chain monadic functions, like the |> for regular functions

Monad examples

Type	Bind	Return
`Option<'T>`	`Option.bind`	`Some`
`Result<'T, _>`	`Result.bind`	`Ok`
`List<'T>`	`List.collect`	`List.singleton`
`Array<'T>`	`Array.collect`	`Array.singleton`
`Seq<'T>`	`Seq.collect`	`Seq.singleton`

Async<'T> too, but through the async CE 📍

Monad vs Functor

A monad is also a functor
map can be expressed in terms of bind and return: map f ≡ bind (f >> return)

☝️ Note: Contrary to the monad with its return operation, the functor concept does not need a "constructor" operation.

Monad alternative definition

A monad can be defined with the flatten operation instead of the bind
→ Signature: M<M<'T>> -> M<'T>

Then, the bind function can be expressed in terms of map and flatten:
→ bind ≡ map >> flatten

💡 This is why bind is also called flatMap.

Regular functions vs monadic functions

Function	Op	Signature
Pipeline
Regular	`▷` pipe	`(f: 'a -> 'b) -> (x: 'a) -> 'b`
Monadic	`>>=` bind	`(f: 'a -> M<'b>) -> (x: M<'a>) -> M<'b>`
Composition
Regular	`>>` comp.	`(f: 'a -> 'b) -> (g: 'b -> 'c) -> ('a -> 'c)`
Monadic	`>=>` fish	`(f: 'a -> M<'b>) -> (g: 'b -> M<'c>) -> ('a -> M<'c>)`

Fish operator definition: let (>=>) f g = fun x -> f x |> bind g ≡ f >> (bind g)
Composition of monadic functions is called Kleisli composition

Monads vs Effects

Effect (a.k.a. "side effect"):
→ change somewhere, inside the program (state) or outside
→ examples:

I/O (Input/Output): file read, console write, logging, network requests
State Management: global variable update, database/table/row delete
Exceptions/Errors: program crash
Non-determinism: same input → ≠ value: random number, current time
Concurrency/Parallelism: thread spawn, shared memory

Pure function causes no side effects → deterministic, predictable
→ FP challenge: separate pure/impure code (separation of concerns)

Monads purposes:

Encapsulate and sequence computations that involve effects,
Maintain purity of the surrounding functional code,
Provide a controlled environment in which effects can happen.

Dealing with a computation that has an effect using monads means:

Wrapping: we don't get a value directly, we get a monadic value that represents the computation and its associated effect.
Sequencing: bind (or let! in a monadic CE) allows you to chain together effectful computations in a sequential order.
Returning: return wraps a pure value → computation w/o effects. 👉 A monadic sequence can mix pure and effectful computations.

From the caller perspective, a function returning a monadic value is pure.
→ Encapsulated effects only "happen" when monadic value is evaluated.

Examples in F#:

Async: by calling Async.RunSynchronously/Start
Option/Result: by pattern matching and handle all cases
Seq: by iterating the delayed sequence of elements

👉 Monads effectively bridge the gap between:

mathematical elegance of pure functional programming
practical necessity of interacting with an impure, stateful world

Other common monads

☝️ Rarely used in F#, but common in Haskell

Reader: to access a read-only environment (like configuration) throughout a computation without explicitly passing it around
Writer: accumulates monoidal values (like logs) alongside a computation's primary result
State: manages a state that can be read and updated during a computation
IO: handles I/O effects (disk, network calls...)
Free: to build series of instructions, separated from their execution (interpretation phase)

Applicative (Functor)

Applicative definition

≃ Any generic type, noted F<'T>, with:

Construction function pure (≡ monad's return)
- Signature : (value: 'T) -> F<'T>
Application function apply
- Noted <*> (same * as in tuple types)
- Signature : (f: F<'T -> 'U>) -> F<'T> -> F<'U>
- Similar to functor's map, but where the mapping function 'T -> 'U is wrapped in the applicative object

Applicative laws

There are 4 laws:

Identity and Homomorphism relatively easy to grasp
Interchange and Composition more tricky

Law 1 - Identity

Same as the functor identity law applied to applicative:

Pattern	Equation
Functor	`map id F` ≡ `F`
Applicative	`apply (pure id) F` ≡ `F`

Law 2 - Homomorphism

💡 Homomorphism means a transformation that preserves the structure.

→ pure does not change the nature of values and functions so that we can apply the function to the value(s) either before or after being wrapped.

(pure f) <*> (pure x) ≡ pure (f x) apply (pure f) (pure x) ≡ pure (f x)

Law 3 - Interchange

We can provide the wrapped function Ff first or the value x, wrapped directly or captured in (|>) x (partial application of the |> operator used as function)

Ff <*> (pure x) ≡ pure ((|>) x) <*> Ff

💡 When Ff = pure f, we can verify this law with the homomorphism law:

apply Ff (pure x)       | apply (pure ((|>) x)) Ff
apply (pure f) (pure x) | apply (pure ((|>) x)) (pure f)
pure (f x)              | pure (((|>) x) f)
                        | pure (x |> f)
                        | pure (f x)

Law 4 - Composition

Cornerstone law: ensures that function composition works as expected within the applicative context.
Hardest law, involving to wrap the << operator (right-to-left compose)!

Ff <*> (Fg <*> Fx) ≡ (pure (<<) <*> Ff <*> Fg) <*> Fx

💡 Same verification:

(pure f) <*> ((pure g) <*> (pure x))    | (pure (<<) <*> (pure f) <*> (pure g)) <*> (pure x)
(pure f) <*> (pure g x)                 | (pure ((<<) f) <*> (pure g)) <*> (pure x)
pure (f (g x))                          | (pure ((<<) f g)) <*> (pure x)
pure ((f << g) x)                       | (pure (f << g)) <*> (pure x)
                                        | pure ((f << g) x)

Applicative vs Functor

Every applicative is a functor.
→ We can define map with pure and apply:

map f x ≡ apply (pure f) x

💡 It was implied by the 2 identity laws.

Applicative vs Monad

Every monad is also an applicative

pure and return are just synonyms
apply can be defined using bind
- given mx a wrapped value M<'a>
- and mf a wrapped function M<'a -> 'b>
- apply mf mx ≡ mf |> bind (fun f -> mx |> bind (fun x -> return (f x)))

apply vs bind 💡

Where apply unwraps both f and x, 2 nested binds are required.
bind extra power comes from its ability to let its first parameter — the function 'a -> M<'b> — create a whole new computational path.

Applicative: multi-param curried function

Applicative helps to apply a function to its arguments (e.g. f: 'x -> 'y -> 'res) when they are each wrapped (e.g. in an Option).

Let's try by hand:

let call f optionalX optionalY =
    match (optionalX, optionalY) with
    | Some x, Some y -> Some(f x y)
    | _ -> None

💡 We can recognize the Option.map2 function.

🤔 Is there a way to handle any number of parameters?

The solution is to use apply N times, for each of the N arguments, first wrapping the function using pure:

// apply and pure for the Option type
let apply optionalF optionalX =
    match (optionalF, optionalX) with
    | Some f, Some x -> Some(f x)
    | _ -> None

let pure x = Some x

// ---

let f x y z = x + y - z
let optionalX = Some 1
let optionalY = Some 2
let optionalZ = Some 3
let res = pure f |> apply optionalX |> apply optionalY |> apply optionalZ

Alternative syntax:

Using the operators for map <!> and apply <*>
Given we can replace the 1st combination of pure and apply with map

// ...
let res = f <!> optionalX <*> optionalY <*> optionalZ

Still, it's not ideal!

Applicative styles

The previous syntax is called ❝Style A❞ and is not recommended in modern F# by Don Syme - see his Nov. 2020 design note.

When we use the mapN functions, it's called ❝Style B❞.

The ❝Style C❞ relies on F# 5 let! ... and! ... in a CE like option from FsToolkit:

let res'' =
    option {
        let! x = optionalX
        and! y = optionalY
        and! z = optionalZ
        return f x y z
    }

👉 Avoid style A, prefer style C when a CE is available, otherwise style B.

Applicative vs Monadic behaviour

The monadic behaviour is sequential:
→ The computation #n+1 is done only after the computation #n.

The applicatives behave in parallel:
→ All the computations for the arguments are done before applying them to the wrapped function.

👉 Even if monads can do more things, applicatives can be more performant on what they can do.

Applicative parallel behaviour

The corollary is about the Result type and its bind function:

let bind (f: 'a -> Result<'b, _>) result =
    match result with
    | Ok x -> f x
    | Error e -> Error e

→ As soon as the current result is an Error case, f is ignored.
→ On the 1st error, we "unplug".

Given the Result<'ok, 'error list> type, apply can accumulate errors:

let apply (rf: Result<'a -> 'b, 'err list>) (result: Result<'a, 'err list>) : Result<'b, 'err list> =
    match rf, result with
    | Ok f, Ok x -> Ok(f x)
    | Error fErrors, Ok _ -> Error fErrors                      // (4)
    | Ok _, Error xErrors -> Error xErrors                      // (5)
    | Error fErrors, Error xErrors -> Error(xErrors @ fErrors)  // (6)

☝️ Notes:

Errors are either accumulated (line 6) or propagated (lines 4, 5).
At lines 4 and 6, rf is no longer a wrapped function but an Error. It happens after a first apply when there is an Error instead of a wrapped value (lines 5, 6).

💡 Handy for validating inputs and reporting all errors to the user.
🔗 Validation with F# 5 and FsToolkit, Compositional IT

Wrap up

Functional patterns key points

Pattern	Key words
Monoid	`+` (combine), composite design pattern ++
Functor	`map`, preserve structure
Monad	`bind`, functor, flatten, sequential composition, effects
Applicative	`apply`, functor, multi-params function, parallel composition

Functional patterns in F# language

In F#, these functional patterns are applied under the hood:

Monoids with int, string, list and functions
Monads with Async, List, Option, Result...
All patterns when using computation expressions

☝️ After the beginner level, it's best to know the principles of these patterns, in case we need to write computation expressions.

🤔 Make these patterns more explicit in F# codebases?

Meaning: what about F# codebases full of monad, Reader, State...?

Generally not recommended, at least by Don Syme
- Indeed, the F# language is not designed that way.
- Although, libraries such as FSharpPlus offer such extensions to F#.
To be evaluated for each team: idiomatic vs consistency ⚖️ → Examples:
- Idiomatic F# recommended in .NET teams using both C♯ and F# code
- Functional F# can be considered in FP teams using several functional languages: F#, Haskell, OCaml...

Additional resources 🔗

"Understanding monoids" series —F# for Fun and Profit
"Map and Bind and Apply, Oh my!" series —F# for Fun and Profit
Monads series —Mark Seemann
Applicatives IRL —Jeremie Chassaing

F# Computation Expressions 🧑‍🏫

Romain Deneau — Fri, 22 Aug 2025 13:09:00 +0000

Computation expressions—abbreviated as CE—are among the most powerful features of F#: they are not just syntactic sugar, but also an entry point for extending the F# language locally. They have been carefully designed to provide a great deal of flexibility, making them a unique and distinctive feature compared to what other programming languages offer.

This power and flexibility come at a price: the available literature on the topic is scarce. Scott Wlaschin has made a great effort to popularize the topic on F# for Fun and Profit, especially with the "Computation Expressions" series. Everything is accurate and still relevant; it just lacks coverage of the latest F# features such as the and! keyword. While the articles are designed to be educational, this material is not optimal as a reference when writing your own computation expressions.

As for the documentation on Microsoft Learn, it is concise and complementary to Scott Wlaschin's articles. This conciseness results in a lack of precision that makes it unsuitable for getting started with writing CEs.

This series of articles offers an alternative approach: it aims to present the concepts underlying CEs—which we call functional patterns—to F# programmers, in order to categorize the types of CEs that you might need to design. The base material comes from my F# training, available in this GitBook.

Table of contents

Introduction
- Syntax
- Functional patterns
Builder
- Builder example: logger {}
- Bind vs let!
- CE desugaring: tips 💡
- Constructor parameters
- Builder example: option {}
Conclusion

Introduction

The page on Microsoft Learn is the ideal entry point into the subject:

Computation expressions in F# provide a convenient syntax for writing computations that can be sequenced and combined using control flow constructs and bindings.

Depending on the kind of computation expression, they can be thought of as a way to express monads, monoids, monad transformers, and applicatives.

Syntax

With regard to the first point, as F# provides async, task, and seq computation expressions directly in FSharp.Core, you can quickly be led to use them and find that, indeed, CEs are relatively easy to use—I say relatively because they are still harder to master than C#'s async/await pattern.

The syntax of a CE can be summarized in a block of code such as myCE { body } where body looks like imperative F# code with:

Regular keywords: let, do, if/then/else, match, for...
Dedicated keywords: yield, return
"Banged" keywords: let!, do!, match!, yield!, return!

These keywords hide a ❝ machinery ❞ to perform background specific effects:

Asynchronous computations like with async and task
State management: e.g. a sequence with seq
Absence of a value with option
Error handling with result
...

Functional patterns

"Monads, monoids, monad transformers, and applicatives" are the functional patterns mentioned just above. These patterns are only mentioned in passing: they are not explained and are not used to organize the documentation. On the F# for Fun and Profit website, Scott deliberately avoids explicitly mentioning these functional patterns: with the exception of the monoid with the "Understanding monoids" series, the other patterns are not explained from the front, but from the point of view of their operations: map for functors, bind for monads, ... - see "Map and Bind and Apply, Oh my!" series.

The available literature about these patterns is extensive, but can be arduous to work through, especially for .NET developers with no experience of other strongly typed functional languages such as Haskell and Scala. We'll look at each of these patterns in detail, either because they're already built into the F# language, sometimes without us even realizing it, or to help us write a kind of CE related to one of these patterns.

Builder

A computation expression relies on an object called Builder.

⚠️ Warning: This is not exactly the Builder object-oriented design pattern.

For each supported keyword (let!, return...), the Builder implements one or more related methods. The compiler provides flexibility in the builder method signatures, as long as the methods can be chained together properly when the compiler evaluates the CE's body on the caller side. This versatility is powerful, but can lead to difficulties in designing and testing a CE.

Builder example: `logger {}`

Need: log the intermediate values of a calculation

// First version
let log value = printfn $"{value}"

let loggedCalc =
    let x = 42
    log x  // ❶
    let y = 43
    log y  // ❶
    let z = x + y
    log z  // ❶
    z

⚠️ Issues

Verbose: the log x interfere with reading
Error prone: forget a log, log wrong value...

💡 Solutions

Make logs implicit in a CE by implementing a custom let!/Bind():

type LoggerBuilder() =
    let log value = printfn $"{value}"; value
    member _.Bind(x, f) = x |> log |> f
    member _.Return(x) = x

let logger = LoggerBuilder()

//---

let loggedCalc = logger {
    let! x = 42     // 👈 Implicitly perform `log x`
    let! y = 43     // 👈                    `log y`
    let! z = x + y  // 👈                    `log z`
    return z
}

The three consecutive let! statements are desugared into three nested calls to Bind with:

1st argument: the right side of the let! (e.g. 42 with let! x = 42)
2nd argument: a lambda taking the variable defined at the left side of the let! (e.g. x) and returning the whole expression below the let! until the }

// let! x = 42
logger.Bind(42, (fun x ->
    // let! y = 43
    logger.Bind(43, (fun y ->
        // let! z = x + y
        logger.Bind(x + y, (fun z ->
            // return z
            logger.Return z)
        ))
    ))
)

`Bind` vs `let!`

logger { let! var = expr in cexpr } is desugared as:
logger.Bind(expr, fun var -> cexpr)

👉 Key points:

var and expr appear in reverse order
var is used in the rest of the computation cexpr → highlighted using the in keyword of the verbose syntax
the lambda fun var -> cexpr is a continuation function

CE desugaring: tips 💡

I found a simple way to desugar computation expressions:
→ Write a failing unit test and use Unquote - 🔗 Example

Constructor parameters

The builder can be constructed with additional parameters.
→ The CE syntax allows us to pass these arguments when using the CE:

type LoggerBuilder(prefix: string) =
    let log value = printfn $"{prefix}{value}"; value
    member _.Bind(x, f) = x |> log |> f
    member _.Return(x) = x

let logger prefix = LoggerBuilder(prefix)

//---

let loggedCalc = logger "[Debug] " {
    let! x = 42     // 👈 Output "[Debug] 42"
    let! y = 43     // 👈 Output "[Debug] 43"
    let! z = x + y  // 👈 Output "[Debug] 85"
    return z
}

Builder example: `option {}`

Need: successively try to find values in maps using identifiers
→ Steps:

Find policyCode by roomRateId in policyCodesByRoomRate map
Find policyType by policyCode in policyTypesByCode map
Build the "result" from both policyCode and policyType

Implementation #1: based on match expressions

match policyCodesByRoomRate.TryFind(roomRateId) with
| None -> None
| Some policyCode ->
    match policyTypesByCode.TryFind(policyCode) with  // ⚠️ Nesting
    | None -> None                                    // ⚠️ Duplicates line 2
    | Some policyType -> Some(buildResult policyCode policyType)

Implementation #2: based on `Option` module helpers

policyCodesByRoomRate.TryFind(roomRateId)
|> Option.bind (fun policyCode ->
    policyTypesByCode.TryFind(policyCode)
    |> Option.map (fun policyType -> buildResult policyCode policyType)
)

👉 Issues ⚠️:

Nesting too
Even more difficult to read because of parentheses

Implementation #3: based on the `option {}` CE

type OptionBuilder() =
    member _.Bind(x, f) = x |> Option.bind f
    member _.Return(x) = Some x

let option = OptionBuilder()

option {
    let! policyCode = policyCodesByRoomRate.TryFind(roomRateId)
    let! policyType = policyTypesByCode.TryFind(policyCode)
    return buildResult policyCode policyType
}

👉 Both terse and readable ✅🎉

Conclusion

After this introduction to computation expressions and their builders, illustrated with the logger {} and option {} CEs, let's study functional patterns. We'll then look at how to write monoidal CEs, monadic CEs, and applicative CEs.

Welcome, Commitji!

Romain Deneau — Wed, 16 Jul 2025 07:35:02 +0000

Commitji is a dotnet tool available on NuGet. I've created this CLI tool to complement our usual commit tool to help us write conventional commit messages that both include an emoji from Gitmoji and are compatible with semantic release.

Table of contents

Issues at stake
- Tools
- Conventions
Commitji message template
- Prefix
- Emoji
- Breaking change
Installation
- Run in a terminal
- Run in a dedicated windows
- Run in GitExtensions
Usage
- Steps
- Behaviors
Conclusion
Edit

Issues at stake

Tools

You may have a preferred tool to create commits. For instance, on Windows, I use GitExtensions 🤩 - powerful user-interface for git and very handy, as long as you don't mind using the mouse.

👉 Commitji is not a replacement for such a tool, it is complementary to it, to help you write commit messages:

You start in your usual tool to refine the changes you want to commit,
You run commitji in a (separate) terminal to get the commit message template,
You get back to your tool to paste the template, complete it to get a full commit message, and commit the changes.

Conventions

Following a convention in your commit messages helps to read the commit history. But there are several conventions:

Conventional Commits uses prefixes like feat, fix, etc.
Gitmoji uses emojis to indicate the type of change.

Both are interesting, but they are not compatible with each other. Moreover, only a subset of the conventional commits template is supported by semantic release.

Commitji message template

Commitji allows you to get the best of the three worlds, by following conventional commits compatible with semantic release, while using emojis to clarify the type of change, to end up with this template:

<prefix>: <emoji> #description
<BLANK LINE>
[BREAKING CHANGE: #explanation]

Prefix

The <prefix>, called type in conventional commits, indicates the type of change.

There are 9 prefixes available, almost all directly supported by semantic release:

The more important: feat, fix, refactor, test.
The other prefixes: chore, docs, perf, revert, wip.

Note that there are no build, ci, style:

build and ci can be included
- in the <scope> of the chore prefix, e.g. chore(build): ⬆️ bump dependencies
- in the #description, e.g. chore: 🐛 fix CI build
style is confusing and not needed:
- When it means a change in the code style, we can use refactor instead.
- When it's used for a change in the UI style, it's probably rather a feat or a fix that you can complement with an UI emoji:
- dizzy……… : 💫 Add or update animations and transitions.
- iphone…… : 📱 Work on responsive design.
- lipstick : 💄 Change the UI visually but not it's behaviour.

Emoji

The <emoji> complements the <prefix>. It is placed in front of the description to clarify the type of change.

There are 75 emojis available, most of them from Gitmoji. It is quite a lot.

If you know well some emojis, you may start by selecting the emoji, and then the prefix amongst those compatibles.
Otherwise, it is usually more convenient to start with the prefix, and then select the emoji amongst the shorter list of emojis compatible with the selected prefix.

👉 Commitji related features:

Start step:
- By default, you start by selecting the prefix.
- It's possible to switch to start by selecting the emoji.
Quick search: the selection is made with the keyboard, by starting to type the emoji/prefix code - e.g. type spa to select sparkles ✨.

Gitmoji indicates the emoji codes used on GitHub. But, they may differ on other platforms you are more accustomed to, like the OS of your mobile phone or the emoji picker on Windows 11 ([Windows]+[.]).
→ For instance, the Check Mark Button ✅ has the code :white_check_mark: on GitHub, but it is check mark button on Windows 11, and is also known as Green Tick.

👉 Commitji related features:

The emoji is inserted in the commit message as a Unicode character, not as a code.
Full-text search : what you type is searched inside the code and the description - e.g. type depe to select a change related to a dependency:
- arrow_down……………… : ⬇️ Downgrade dependencies.
- arrow_up…………………… : ⬆️ Upgrade dependencies.
- heavy_minus_sign : ➖ Remove a dependency.
- heavy_plus_sign… : ➕ Add a dependency.
- pushpin……………………… : 📌 Pin dependencies to specific versions.
[v1.2] support of more codes, including aliases specified in Emojipedia e.g. Type tick to select either lipstick 💄 or check_mark ✅.
[v1.3] auto-expanding search: if what you have typed does not match the current search mode or the current start step, before indicating that no match is found, the tool tries to auto-expand the search mode and/or the current start step to match the input.

Breaking change

The BREAKING CHANGE is an optional section to indicate a breaking change.

👉 Commitji ensures the compatibility with semantic release:

it's placed on a separate line
there are no ! at the end of type (e.g. feat!)
- 💡 the emoji boom 💥 is used instead to get the same effect

☝️ Indicate a breaking change wisely: it's not just about a technical change that may break the code; it should be related to an improvement in your product that is worth the migration cost for your users.

🔗 Practical vs. Strict Semantic Versioning

Installation

Commitji is available as a .NET global tool. You can install it using the following command:

dotnet tool install --global Commitji.Cli

Run in a terminal

You can run Commitji with the command commitji in a terminal. But notice that it will clear the console!

Run in a dedicated windows

There are several ways to run Commitji in a dedicated windows.

For instance on Windows you can use the command cmd.exe /c "title Commitji && commitji".

/c is to close the windows at the end. Use /k if you want to keep it open.
title Commitji is just to ensure that the windows will have a nice title.

Run in GitExtensions

GitExtensions allows to define a custom script and to attach a hotkey to run it.

In Settings > Scripts, add a script with the following properties. Then, press [OK] (and not [Apply]) to save the settings.
- Name: Commitji
- Command: $host.UI.RawUI.WindowTitle = 'Commitji'; commitji
- Is PowerShell script: True
In Settings > Hotkeys, attach a keyboard shortcut to run the previous script - e.g. [Ctrl]+[.] ([OemPeriod]), in reference to [Win]+[.] to open the emoji picker in Windows 11.

Then, when you want to commit your changes, you can press:

[Ctrl]+[Space] to open the Commit popup
[Ctrl]+[.] to open Commitji
complete all steps until the commit message template copied in the clipboard
paste it in the Commit message text area

Usage

Steps

The tool display a series of questions, mainly to allow you to choose:

a prefix (feat, fix...) and an emoji amongst a short list of relevant emojis (e.g. sparkles ✨ for feat)
or an emoji (lipstick 💄) and a prefix amongst a short list of relevant prefixes (e.g. feat or fix)

The default mode is to start with the prefix selection. You can switch to emoji selection by pressing [:].

When you have both the prefix and the emoji, you can indicate if it's a breaking change.

Afterward, the corresponding semantic version change is indicated (Major, Minor, Patch, None), and the commit message template is displayed. You can copy it to the clipboard by pressing [Enter].

Behaviors

The selection is made in various ways:

You can navigate through the list of available choices, using the arrow keys [↓]/[↑] to change the selected choice.
And/or you can start typing the number of the choice to select (when numbers are displayed: for prefixes and emojis).
And/or you can start typing some characters: the list of choices is filtered to match the input.
- If a single choice matches the input, the step is auto-completed, the input is cleared, and you go to the next step.
- If multiple choices match:
- The portions that match the input are highlighted.
- You can complete the step by pressing [Enter].

The search is case-insensitive, and has 2 modes:

Quick search: the input is matched against the beginning of the choice code.
Full-text search: the input is matched against the whole choice text.
You can switch to full-text search by pressing [Alt]+[F] (or [Ctrl]+[F] when it's not intercepted by the host).
You can exit the full-text search by pressing [Alt]+[F] again (or [Escape] when it's not intercepted by the host).

💡 In the quick search mode, if your input matches nothing, the mode is automatically expanded to full-text and a new search is performed. You will the new matches, if any. If not, the mode will automatically return to quick search mode.

At any time, you can press:

[Alt]+[Z] or [Backspace] to undo the last action (if any).
[Ctrl]+[C] to close the tool.

💡 These keystrokes are indicated in the hints panel that is updated to match the input and the selection.

Conclusion

Commitji bridges the gap between Conventional Commit, Gitmoji and Semantic Release to give us the very best in commit message quality. It's a micro-tool that doesn't seek to replace our usual tools, but rather to complement them.

It offers a single functionality, but in the most user-friendly way possible for a command-line tool. It also has the advantage of being optional: once you've used it for a while, you won't need it as long as you know how to write your commit messages in the right format, meaning with the right combination of a prefix, an emoji and an eventual breaking change. But it's still readily available in case of doubt.

💡 For the more curious, Commitji is written in F# to follow the functional programming principles, including the Elmish MVU pattern. It relies on Spectre.Console, a great library in particular for rendering in a command terminal.

🔗 Source code on GitHub

Edit

⚠️ I realized later that Commitji also refers to a Visual Studio Code extension that fortunately does roughly the same thing: the extension is light and fast, while the dotnet tool is more strict and covers more cases, which takes more keyboard strokes...

Sorry for the confusion of using the name of an existing tool 😓, which I would have avoided if I had known beforehand. Be free to test both tools.

DEV Community: Romain Deneau

Applying object-oriented design principles - In-memory configuration builder

Problem description

Syntax on the usage side

Implementation design

Design principles followed in the implementation

Conclusion

Writing F# computation expressions

Types

M<T> wrapper type

Delayed<T> type

Delayed<T> type example: eventually {}

Internal<T> type

Builder-less CE

Custom operations 🚀

Final words

Benefits ✅

Limits ⚠️

Guidelines 📃

Tips 💡

🍔 Quiz

Question 1: What is the primary purpose of computation expressions in F#?

Question 2: Which keywords identify a monadic computation expression?

Question 3: In a computation expression builder, what does the Bind method correspond to?

Question 4: What is the signature of a typical monadic Bind method?

🔗 Additional resources

F# applicative computation expressions

Introduction

Builder method signatures

Applicative CE example: validation

Base implementation

Use case: validate a customer

Other method combinations

Two-element expression

Three-element expression

Method combination conclusion

FsToolkit validation CE

Source methods

Applicative CE example: async

Conclusion

F# monadic computation expressions

Introduction

Builder method signatures

Monadic vs Monoidal

Return (monadic) vs Yield (monoidal)

For and While

CE monadic and delayed

CE monadic examples

CE monadic example - result {}

CE monadic: FSharpPlus monad {}

Monad stack, monad transformers

1. Academic style (with FSharpPlus)

2. Idiomatic style

Conclusion

F# monoidal computation expressions

Introduction

Builder method signatures

CE monoidal vs comprehension

Comprehension definition

Comparison

Minimal set of methods expected for each

CE monoidal example: multiplication {}

Exercise

Desugaring

Delayed<T> type

CE monoidal kinds

CE monoidal to generate a collection

Conclusion

Functional patterns for F# computation expressions

Introduction

F# and functional patterns

General definition

Monoid

Monoid laws

1. Associativity

2. Identity Element

Monoid examples

Functor

Functor definition

Functor laws

`M<T>` wrapper type

`Delayed<T>` type

`Delayed<T>` type example: `eventually {}`

`Internal<T>` type

Question 3: In a computation expression builder, what does the `Bind` method correspond to?

Question 4: What is the signature of a typical monadic `Bind` method?

`Source` methods

`Return` (monadic) vs `Yield` (monoidal)

`For` and `While`

CE monadic example - `result {}`

CE monadic: FSharpPlus `monad {}`

CE monoidal example: `multiplication {}`

`Delayed<T>` type

Builder example: `logger {}`

`Bind` vs `let!`

Builder example: `option {}`

Implementation #2: based on `Option` module helpers

Implementation #3: based on the `option {}` CE