What is the best practice to pass global like values, like correlationId, between methods

[Andras-Csanyi]

Hi All,

I am very new in the functional world and it takes a lot of mental energy to wrap my head around things, but I am trying to progress.

I have two questions.
The first one is can you recommend projects written in functional C#? I'd like to take a look at them and making myself more familiar with this type of programming.
The second question is below.

Imagine the situation where you want to log all operation failure in your business process and these log entries are connected by correlationId, when you debug this value helps you to see the sequence of events.

The business process has the following steps:

• input value validation
• mapping
• save to database
• map back to dto

In imperative would look like this:

InputValidation(input, correlationId);
BusinessObject bo = mapper.ToBo(input, correlationId);
BusinessObject boResult = saveToDatabase(bo, correlationId);
BusinessObjectDto result = mapper.ToDto(boResult, correlationId);

What is the good practice in functional world to do this? What I did is I created a context object and all the phases has its own entry in it (input, mapped, saved) and the whole is part of Either looks like the below example. Changing the right type between methods didn't feel right.

    public async Task<Either<ErrorResult, AddRelationScenarioContext>> ExecuteAsync(
        AddRelationScenarioContext addRelationScenarioContext,
        CancellationToken cancellationToken = default)
    {
        Either<ErrorResult, AddRelationScenarioContext> prepareForSave = Handle(addRelationScenarioContext)
            .ValidateScenarioInput(validator)
            .MapToRelation(mapper);
        return Save(prepareForSave)
            .ToApplicationResult(mapper);
    }

    public static Either<ErrorResult, AddRelationScenarioContext> MapToRelation(
        this Either<ErrorResult, AddRelationScenarioContext> either,
        RelationMapper mapper)
    {
        return either.Match(
            Left: Either<ErrorResult, AddRelationScenarioContext>.Left,
            Right: addRelationScenarioContext =>
            {
                Entity.Relation mapped = mapper.MapRelationInputToRelation(addRelationScenarioContext.Payload);
                return addRelationScenarioContext with { Mapped = mapped };
            });
    }

public record AddRelationScenarioContext(
    string CorrelationId,
    RelationInput Payload,
    Entity.Relation Mapped,
    Entity.Relation Saved,
    RelationResult Result);

[StefanBertels]

Changing the right type of Either is fine, just stay with same left type (e.g. ErrorResult or Error).
BTW: You can use Fin<T> instead of Either<Error,T>. Error is LanguageExt built-in and a quite good solution in general.

var x = 
  from validatedInput in InputValidation(input, correlationId)
  from bo in mapper.ToBo(validatedInput , correlationId)
  from boResult in saveToDatabase(bo, correlationId)
  from result in mapper.ToDto(boResult, correlationId)
  select result;

If every method returns Either<Error, ...> then you get an Either<Error, T> with same type as result of
mapper.ToDto.

Basically the above is the (nice) LINQ version of .Bind(...) method chaining (which is semantically the same as .SelectMany() extension). You can read details here: https://github.com/louthy/language-ext/wiki/Thinking-Functionally:-What-is-LINQ-really%3F

var x = InputValidation(input, correlationId)
  .Bind(validatedInput => mapper.ToBo(validatedInput, correlationId))
  .Bind(bo => ...)
  .Bind(boResult => ...);

Method signature for example:

Either<ErrorResult, string> InputValidation(string originalInput, int correlationId)
{
}

As a general rule of thumb you probably don't want Either or Option as parameter type in methods if you want to handle the "left" (or None) in a special way. The method gets valid input and outputs either an error or the correct result. Bind() as used above will chain the good path and return early on the first error.

[Andras-Csanyi]

Thank you very much for the help and advise. It helps me a lot to take these initial steps.
Honestly, the LINQ part felt like way above my head, but now it feels less like that.

[louthy]

@Andras-Csanyi there are a number of quite 'big' questions there. I think it's important to take a step back and remember the motivation for doing FP in C# (or any language). My reasons were that the large OO project I was running had hit a complexity limit. Not so much for the computer, but for our minds. I think OOP is OK at a small scale, but hidden mutable state without proper compositional capabilities, and a lack of declarativity, becomes quite difficult for the human mind to keep track of. This leads to bugs, more difficult refactoring, slower moving teams, etc.

This is only getting worse as our OO programs get bigger and more complex. The grey-matter between our ears stays the same but our programs get more complex. The fact we've had to invent AI to help us write code shows we're struggling.

Pure Functional Programming discards the notion of mutable-state, welcomes in true composition, and treats everything like a mathematical expression, so that we can use the power of mathematical reasoning and proofs to give our weak and feeble brains a chance of understanding.

So, those are the critical elements that we need to work with:

• Everything is immutable
• Behaviour is in functions (usually static), that transform one immutable type to another
  • Pure functions compose into more pure functions, perfectly
• Everything is an expression
  • This isn't a requirement, but usually confirms to our brains that we've "done it right"
  • An expression that uses pure functions and local immutable data structures is guaranteed to be pure itself

Everything naturally falls out of these guidelines. What happens to your code is that it becomes more robust, easier to maintain, it doesn't bit-rot in the same way, and generally you get to a point where you can 'see' the structure of your code in your mind's eye with much more clarity. And also, everything composes in the same way as terms in a mathematical expression.

The 'structure' point above is actually quite profound once you get comfortable with pure-FP. Because you start to see structure everywhere. Not just layers, or services, but between types (natural transformations, functors, etc.)

I won't lie and tell you that you will get this straight-away, nobody does, especially if you're coming from an OO world. It takes a little time for your brain to switch into pure-mathematical-expression mode. But, when it does, and it will, you will have that "aha!" moment and it will all become very easy. Much easier than OO. But it does take time.

Just as with anything you will need to make your own mistakes and learn the best way to do it. The guidelines are the key checklist to keep with you.

btw, if you're just starting with language-ext, I would recommend starting the the v5-beta as it's the first large refactor in a decade and changes the library in some quite profound ways. It's a better starting point.

On to your questions:

The first one is can you recommend projects written in functional C#?

I know of many private projects, but not many public, so the best place to start is with the Samples. Some sample projects are older than others however, so a good starting point would be:

• CardGame - This is a game of pontoon that leverages many of the more modern features of language-ext (which makes it easier to build applications). It was discussed as part of my StateT blog article. This literally does handling of "global like values" when managing immutable GameState and PlayerState. It also abstracts away from IO to allow the capturing of pure side-effects, a key tenet of pure FP.
• EffectsExample - This demonstrates the use of declarative side-effects. This takes the idea of pure IO to its extreme. It's not for everyone, because it adds quite a bit of declarative overhead for the programmer, because it requires you to state exactly what IO each function or module does. But, it does also enable the handling "global like values", in that it has a 'runtime' that is automatically threaded through the application. The runtime contains access to behaviours and local state. This leads to a solution for dependency-injection and easy management of local state, like a transaction, or in your case a correlationId. The idea is that you build at least one Runtime type for your application, decide what its capabilities are, and then inject it through your application. You can also build test runtimes, or smaller runtimes for smaller part of your application, it's really about how much effort you're willing to put in to go fully declarative.
• Newsletter - This is a real program that I use to send the email newsletters for my blog. It uses a bespoke runtime to be used with the Eff<RT, A> monad to have injectable IO and state. Instead of having a test runtime and a live runtime, this has one runtime that can be switched into test or live mode. This is so I can send a test-newsletter to myself before sending it out the the full mailing list. The vast majority of the application uses the K<M, A> type, which is a completely abstract representation of a higher-kinded type. It has no capabilities of its own, it only gains capabilities through the use of constraints on M. So, even though the code is run (from Program.cs) with the Eff monad, it could, in theory, be run using any monad you like, as long as its trait-implementations support the same constraints. This is the most extreme form of abstraction. It comes with some benefits and some trade-offs. The benefits are the ability to swap out the implementation at any time without changing the code, the trade-offs are having to specify the constraints for M everywhere.
• Streams - Another new sample that demonstrates the streaming IO functionality. It's useful to see the other end of the spectrum to EffectsExamples, this uses the much simpler IO monad instead of going all in with fully declarative side-effects.
• DomainTypesExamples - This is less useful from an application point-of-view. But, it shows how the new domain-type traits work. Which is interesting, but the main reason I list it is that I have created a type called Vector<D, A> that implements DomainType and VectorSpace which forces it to implement certain methods. If you look at those methods, you'll notice they've been tuned to use SIMD functions internally. There's lots of classic mutation and imperative code, which might seem wrong for the pure-FP world. But the critical thing is that the methods are still pure. So, just remember, with C# we always have a local 'get out of jail free card' that allows us to write parts of our code in an imperative manner and wrap it up in a way that makes it pure. You just have to take more care over those things and know why you're doing it.

@StefanBertels answer is correct by the way, but the one thing you will want to consider as you get better at FP is the fact that you're mixing IO and pure code without any declaration of that. IO is one of the 'big problem' issues that makes code unreliable. The ultimate goal is to make our function signatures talk to us and to put IO in a box where we know what it's doing and when it's doing it. A function that returns Either is saying "the only side-effect in this function is that we might return an alternative value", it says nothing about that IO that you're doing.

To get the absolute maximum out of this approach you'll want to wrap your IO up. Either using the IO monad, the Eff monads, or by building your own domain-specific types.

Here's an example from my new startup's code. I am writing my own layer for FoundationDB. FoundationDB is a toolkit for building databases, so needs a lot of simple functions. So, I wrapped those up in a Db monad:

public record Db<A>(StateT<DbEnv, IO, A> runDB) : K<Db, A>
{
    public IO<(A Value, DbEnv Env)> Run(DbEnv env) =>
        runDB.Run(env).As();

    public K<Db, B> MapIO<B>(Func<IO<A>, IO<B>> f) =>
        from e in Db.dbEnv
        from r in f(runDB.Run(e).Map(vs => vs.Value).As())
        select r;

    public K<Db, A> IfFail(Func<Error, Db<A>> OnFail) =>
        from e in Db.dbEnv
        from r in MapIO(io => io.As()
                                .Match(Succ: x => IO.Pure((Value: x, Env: e)), 
                                       Fail: x => OnFail(x).Run(e)).Flatten())
        from _ in Db.put(r.Env)
        select r.Value;

    public static Db<A> LiftIO(IO<A> ma) =>
        new (StateT<DbEnv, IO, A>.LiftIO(ma));

    public static Db<A> operator |(Db<A> ma, Db<A> mb) =>
        ma.IfFail(_ => mb).As();

    public Db<B> Map<B>(Func<A, B> f) =>
        this.Kind().Map(f).As();

    public Db<B> Bind<B>(Func<A, Db<B>> f) =>
        this.Kind().Bind(f).As();
    
    public Db<C> SelectMany<B, C>(Func<A, Db<B>> bind, Func<A, B, C> project) =>
        this.Kind().SelectMany(bind, project).As();
    
    public Db<C> SelectMany<B, C>(Func<A, IO<B>> bind, Func<A, B, C> project) =>
        this.Kind().SelectMany(bind, project).As();

    public static implicit operator Db<A>(Pure<A> ma) =>
        Db.pure(ma.Value).As();
    
    public static implicit operator Db<A>(Fail<Error> ma) =>
        Db.fail<A>(ma.Value);
    
    public static implicit operator Db<A>(Fail<string> ma) =>
        Db.fail<A>(ma.Value);
    
    public static implicit operator Db<A>(Error ma) =>
        Db.fail<A>(ma);
}

It wraps up the StateT and IO monads. So, its effects are 'managing state' and 'IO side-effects'.

I then implement the Monad and Stateful traits:

public partial class Db : Monad<Db>, Stateful<Db, DbEnv>
{
    static K<Db, B> Monad<Db>.Bind<A, B>(K<Db, A> ma, Func<A, K<Db, B>> f) =>
        new Db<B>(ma.As().runDB.Bind(x => f(x).As().runDB));

    static K<Db, B> Functor<Db>.Map<A, B>(Func<A, B> f, K<Db, A> ma) => 
        new Db<B>(ma.As().runDB.Map(f));

    static K<Db, A> Applicative<Db>.Pure<A>(A value) =>
        new Db<A>(StateT<DbEnv, IO, A>.Pure(value));

    static K<Db, B> Applicative<Db>.Apply<A, B>(K<Db, Func<A, B>> mf, K<Db, A> ma) =>
        new Db<B>(mf.As().runDB.Apply(ma.As().runDB).As());

    static K<Db, Unit> Stateful<Db, DbEnv>.Put(DbEnv value) =>
        new Db<Unit>(StateT.put<IO, DbEnv>(value).As());

    static K<Db, Unit> Stateful<Db, DbEnv>.Modify(Func<DbEnv, DbEnv> f) => 
        new Db<Unit>(StateT.modify<IO, DbEnv>(f).As());

    static K<Db, A> Stateful<Db, DbEnv>.Gets<A>(Func<DbEnv, A> f) => 
        new Db<A>(StateT.gets<IO, DbEnv, A>(f).As());

    static K<Db, A> MonadIO<Db>.LiftIO<A>(IO<A> ma) =>
        new Db<A> (StateT<DbEnv, IO, A>.LiftIO(ma));

    public static K<Db, IO<A>> ToIO<A>(K<Db, A> ma) => 
        throw new NotImplementedException(); // TODO
}

Then I create a 'module' of lightweight functions that interact with the database:

public partial class Db
{
    /// <summary>
    /// Fail constructor
    /// </summary>
    public static Db<A> pure<A>(A value) =>
        new (StateT<DbEnv, IO, A>.Pure(value));

    /// <summary>
    /// Fail constructor
    /// </summary>
    public static Db<A> fail<A>(string error) =>
        fail<A>((Error)error);

    /// <summary>
    /// Fail constructor
    /// </summary>
    public static Db<A> fail<A>(Error error) =>
        new (StateT<DbEnv, IO, A>.Lift(IO.fail<A>(error)));

    /// <summary>
    /// Get the database environment
    /// </summary>
    public static readonly Db<DbEnv> dbEnv = 
        Stateful.get<Db, DbEnv>().As(); 
    
    /// <summary>
    /// Map the database environment
    /// </summary>
    internal static Db<A> gets<A>(Func<DbEnv, A> f) => 
        Stateful.gets<Db, DbEnv, A>(f).As();
    
    /// <summary>
    /// Put the database environment
    /// </summary>
    public static Db<Unit> put(DbEnv env) => 
        Stateful.put<Db, DbEnv>(env).As();

    /// <summary>
    /// lift an IO operation onto the monad
    /// </summary>
    public static Db<A> liftIO<A>(IO<A> ma) =>
        new (StateT<DbEnv, IO, A>.LiftIO(ma));

    /// <summary>
    /// lift an IO operation onto the monad
    /// </summary>
    internal static Db<A> liftIO<A>(Func<DbEnv, EnvIO, A> f) =>
        dbEnv.Bind(env => IO.lift(envIO => f(env, envIO))).As();

    /// <summary>
    /// lift an IO operation onto the monad
    /// </summary>
    internal static Db<A> liftIO<A>(Func<EnvIO, A> f) =>
        MonadIO.liftIO<Db, A>(IO.lift(f)).As();

    /// <summary>
    /// lift an IO operation onto the monad
    /// </summary>
    internal static Db<A> liftIO<A>(Func<DbEnv, EnvIO, Task<A>> f) =>
        dbEnv.Bind(env => IO.liftAsync(async envIO => await f(env, envIO).ConfigureAwait(false))).As();

    /// <summary>
    /// lift an IO operation onto the monad
    /// </summary>
    internal static Db<A> liftIO<A>(Func<EnvIO, Task<A>> f) =>
        MonadIO.liftIO<Db, A>(IO.liftAsync(async e => await f(e).ConfigureAwait(false))).As();

    /// <summary>
    /// Get the Foundation DB version
    /// </summary>
    static Db<Unit> fdbVersion =
        liftIO(_ =>
               {
                    Fdb.Start(710);
                    return unit;
               }).Memo();
    
    /// <summary>
    /// Shutdown the database connection
    /// </summary>
    /// <remarks>
    /// Only shutdown if you're quitting the application
    /// </remarks>
    public static Db<Unit> shutdown =
        liftIO(_ =>
               {
                   Fdb.Stop();
                   return unit;
               });
    
    /// <summary>
    /// Connect to the database
    /// </summary>
    /// <remarks>
    /// This is memoised, so it only ever connects *once*.  So, never `shutdown` unless you're quitting.
    /// </remarks>
    public static readonly Db<Unit> connect =
        (from ver in fdbVersion
         from env in dbEnv
         from con in liftIO(async envIO =>
             await (env.ClusterFile.IsSome
                 ? Fdb.OpenAsync(new FdbConnectionOptions { ClusterFile = env.ClusterFile.ValueUnsafe()! }, envIO.Token)
                      .ConfigureAwait(false)
                 : Fdb.OpenAsync(envIO.Token).ConfigureAwait(false)))
         from res in put(env with { Database = Some(con) })
         select unit)
        .Memo();

    /// <summary>
    /// Access the database from the monad state
    /// </summary>
    static readonly Db<IFdbDatabase> db =
        gets<IFdbDatabase>(e => e.Database.IsSome
            ? e.Database.ValueUnsafe()!
            : throw new IOException("no connection to database, make sure you call `connect` first"));

    /// <summary>
    /// Access the transaction from the monad state
    /// </summary>
    static readonly Db<IFdbTransaction> transaction =
        gets<IFdbTransaction>(e => e.Transaction.IsSome && e.Transaction.ValueUnsafe() is IFdbTransaction t  
            ? t
            : throw new IOException("not in a readWrite transaction"));
    
    /// <summary>
    /// Access the read-only transaction from the monad state
    /// </summary>
    static readonly Db<IFdbReadOnlyTransaction> readOnlyTransaction =
        gets<IFdbReadOnlyTransaction>(e => e.Transaction.IsSome
            ? e.Transaction.ValueUnsafe()!
            : throw new IOException("not in a readOnly transaction"));

    /// <summary>
    /// Set the subspace we're working in
    /// </summary>
    public static Db<A> subspace<A>(string leaf, K<Db, A> ma) =>
        subspace(FdbPath.Relative(leaf), ma);

    /// <summary>
    /// Set the subspace we're working in
    /// </summary>
    public static Db<A> subspace<A>(FdbPath path, K<Db, A> ma) =>
       (from t in readOnlyTransaction
        from r in liftIO(async (env, eio) => 
               {
                   var provider = env.Provider.ValueUnsafe() ?? 
                                  throw new IOException("no provider make sure you call `subspace` within a transaction");

                   var subspace = env.Subspace.IsSome
                                      ? t is IFdbTransaction mutableTrans1
                                            ? await env.Subspace.ValueUnsafe().CreateOrOpenAsync(mutableTrans1, path)
                                            : await env.Subspace.ValueUnsafe().OpenAsync(t, path)
                                      : t is IFdbTransaction mutableTrans2
                                          ? await provider.Root.CreateOrOpenAsync(mutableTrans2, path)
                                          : await provider.Root.OpenAsync(t, path);
                   
                   var (v, _) = ma.As().Run(env with { Subspace = Some(subspace) }).Run(eio);
                   return v;
               })
        select r)
       .As();

    /// <summary>
    /// Read only transaction
    /// </summary>
    public static Db<A> readOnly<A>(FdbPath subspacePath, K<Db, A> ma) =>
        readOnly(subspace(subspacePath, ma));

    /// <summary>
    /// Read only transaction
    /// </summary>
    public static Db<A> readOnly<A>(K<Db, A> ma) =>
        connect.Bind(
            _ =>
                liftIO(async (env, eio) =>
                       {
                           var db = env.Database.ValueUnsafe() ??
                                    throw new IOException(
                                        "no connection to database, make sure you call `connect` first");

                           var p = db.AsDatabaseProvider(eio.Token);
                           var (v, _) = await p.ReadAsync(
                                            t => ma.As().Run(env with { Transaction = Some(t), Provider = Some(p) }).Run(eio).AsTask(),
                                            eio.Token);
                           return v;
                       })).As();

    /// <summary>
    /// Read-write transaction
    /// </summary>
    public static Db<A> readWrite<A>(FdbPath subspacePath, K<Db, A> ma) =>
        readWrite(subspace(subspacePath, ma));

    /// <summary>
    /// Read-write transaction
    /// </summary>
    public static Db<A> readWrite<A>(K<Db, A> ma) =>
        connect.Bind(
            _ => liftIO(async (env, eio) =>
                        {
                            var db = env.Database.ValueUnsafe() ??
                                     throw new IOException(
                                         "no connection to database, make sure you call `connect` first");

                            var p = db.AsDatabaseProvider(eio.Token);

                            var (v, _) = await p.ReadWriteAsync(
                                             t => ma.As()
                                                    .Run(env with
                                                         {
                                                             Transaction = Some<IFdbReadOnlyTransaction>(t),
                                                             Provider = Some(p)
                                                         }).Run(eio).AsTask(),
                                             eio.Token);

                            return v;
                        })).As();

    /// <summary>
    /// get a value from the database
    /// </summary>
    public static Db<Slice> get(string name) =>
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.IsSome
                               ? env.Transaction.ValueUnsafe()!
                               : throw new IOException("not in a readOnly transaction");
                   var k = env.MakeKeySlice(name);
                   var s = await t.GetAsync(k);
                   return s == Slice.Nil
                              ? throw new KeyNotFound(k.ToStringUtf8() ?? "[null]")
                              : s;
               });
    
    /// <summary>
    /// get a value from the database
    /// </summary>
    public static Db<Slice> get<ID>(string name, ID id) =>
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.IsSome
                               ? env.Transaction.ValueUnsafe()!
                               : throw new IOException("not in a readOnly transaction");
                   var k = env.MakeKeySlice(name, id);
                   var s = await t.GetAsync(k);
                   return s == Slice.Nil
                              ? throw new KeyNotFound(k.ToStringUtf8() ?? "[null]")
                              : s;
               });

    /// <summary>
    /// get a value from the database
    /// </summary>
    public static Db<Slice> get<ID1, ID2>(string name, ID1 id1, ID2 id2) =>
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.IsSome
                               ? env.Transaction.ValueUnsafe()!
                               : throw new IOException("not in a readOnly transaction");
                   var k = env.MakeKeySlice(name, id1, id2);
                   var s = await t.GetAsync(k);
                   return s == Slice.Nil
                              ? throw new KeyNotFound(k.ToStringUtf8() ?? "[null]")
                              : s;
               });

    /// <summary>
    /// Set a value in the database
    /// </summary>
    public static Db<Unit> set<A>(string name, A value) =>  
        liftIO((env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   t.Set(env.MakeKeySlice(name), value.AsSlice());
                   return unit;
               });

    /// <summary>
    /// Set a value in the database
    /// </summary>
    public static Db<Unit> set<ID1, A>(string name, ID1 id1, A value) =>  
        liftIO((env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   t.Set(env.MakeKeySlice(name, id1), value.AsSlice());
                   return unit;
               });

    /// <summary>
    /// Set a value in the database
    /// </summary>
    public static Db<Unit> set<ID1, ID2, A>(string name, ID1 id1, ID2 id2, A value) =>  
        liftIO((env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   t.Set(env.MakeKeySlice(name, id1, id2), value.AsSlice());
                   return unit;
               });
    
    public static Db<uint> increment32(string name) =>  
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   var k = env.MakeKeySlice(name);
                   t.AtomicIncrement32(k);
                   var v = await t.GetAsync(k);
                   return v.As<uint>().ValueUnsafe();
               });
    
    public static Db<uint> increment32<ID1>(string name, ID1 id1) =>  
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   var k = env.MakeKeySlice(name, id1);
                   t.AtomicIncrement32(k);
                   var v = await t.GetAsync(k);
                   return v.As<uint>().ValueUnsafe();
               });
    
    public static Db<uint> increment32<ID1, ID2>(string name, ID1 id1, ID2 id2) =>  
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   var k = env.MakeKeySlice(name, id1, id2);
                   t.AtomicIncrement32(k);
                   var v = await t.GetAsync(k);
                   return v.As<uint>().ValueUnsafe();
               });
    
    public static Db<ulong> increment64(string name) =>  
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   var k = env.MakeKeySlice(name);
                   t.AtomicIncrement64(k);
                   var v = await t.GetAsync(k);
                   return v.As<ulong>().ValueUnsafe();
               });
    
    public static Db<ulong> increment64<ID1>(string name, ID1 id1) =>  
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   var k = env.MakeKeySlice(name, id1);
                   t.AtomicIncrement64(k);
                   var v = await t.GetAsync(k);
                   return v.As<ulong>().ValueUnsafe();
               });
    
    public static Db<ulong> increment64<ID1, ID2>(string name, ID1 id1, ID2 id2) =>  
        liftIO(async (env, _) =>
               {
                   var t = env.Transaction.ValueUnsafe() as IFdbTransaction ?? throw new IOException("not in a write transaction");
                   var k = env.MakeKeySlice(name, id1, id2);
                   t.AtomicIncrement64(k);
                   var v = await t.GetAsync(k);
                   return v.As<ulong>().ValueUnsafe();
               });
}

This wraps up calls to the FoundationDB.Client (which is an imperative library for interacting with FoundationDB). It also manages connections and configuration internally in its state.

With all of that wrapped up into its own type, I now have an abstraction away from my database that:

• Manages IO (including cancellation tokens, synchronisation contexts, etc.)
• Manages configuration
• Manages transactions and local state
• Automatically tracks and manages resources (disposables)

The key is that I've wrapped up all the messy IO stuff into something declarative. Every time I interact with the database I work with the Db monad. This is then clear to everyone that reads the code.

The other thing is that every interaction with the database is now composable. So, I can then write functions like these (below) which just return more Db types, which are also composable:

public class Workspace
{
    public static Db<WorkspaceId> registerPerson(EmailAddress email) =>
        
        // Generate a workspace ID
        from w in Db.liftIO(MakeId.generate)
        
        // Create an index from the credential to the workspace and mark the 
        // index as an authenticated owner
        from c in Db.subspace(Subspaces.CredentialWorkspaceIndex,
                              Db.set(email.To(), w, new CredentialWorkspaceIndex(true, true)))
        
        // Make a /w/<id>/s entry that specifies where the spec data used to compile
        // the workspace is (folder in this case).
        from _ in Db.subspace(Subspaces.Workspace, 
                              Db.subspace(w, 
                                          Db.subspace(WorkspaceSubspaces.Spec, makeFolder(w))))
        
        select WorkspaceId.From(w);

    public static Db<Unit> makeFolder(string wid) =>
        from _1 in Db.set("type", "folder")
        from _2 in Db.set("repo", $"/{wid}")
        select unit;
}

NOTE: how Db<WorkspaceId> registerPerson(EmailAddress email) talks to the programmer reading the code. You don't have to look inside that function to know that it's going to do something with the database. This is the difference between returning Either and something more declarative.

To structure an application you might make several of these types that wrap up domains/sub-systems within your app (UI, Services, APIs, etc.)

For example, I have an Api monad that works in a similar way. Except this time, instead of wrapping up StateT and IO, it wraps up a Free monad that contains a DSL:

public record Api<A>(Free<ApiDsl, A> runApi) : K<Api, A>
{
    ...

That DSL encapsulates access to the Db type (as well as a Service monad):

public abstract record ApiDsl<A> : K<ApiDsl, A>;
public record ApiFail<A>(Error Error) : ApiDsl<A>;
public record ApiDb<A>(Db<A> Action) : ApiDsl<A>;
public record ApiService<A>(Service<A> Action) : ApiDsl<A>;

With that I can write my API behaviours that access underlying databases or services:

public class Registration
{
    /// <summary>
    /// Create the user in an invalid state
    /// Create the email verification token
    /// Email the verification token
    /// </summary>
    /// <param name="email">User email address</param>
    /// <param name="phone">Phone number</param>
    /// <param name="password">Hashed and salted password</param>
    /// <returns>Unit</returns>
    public static Api<Unit> register(EmailAddress email, PhoneNumber phone, Password password) =>
        from id in Api.readWrite(from _ in Credential.createUser(email, phone, password)
                                 from t in Verification.generateEmailVerifyId(email)
                                 select t)
        from _  in Api.lift(Email.sendVerifyEmail(email, id))
        select unit;

    /// <summary>
    /// Verify the user account using the verification ID (make its `Valid` property `true`)
    /// </summary>
    /// <param name="verifyId">Verification ID</param>
    /// <returns>Unit</returns>
    public static Api<Unit> verifyEmail(VerificationId verifyId) =>
        from wid in Api.readWrite(from e in Verification.emailFromVerifyId(verifyId)
                                  from _ in Credential.makeUserValid(e)
                                  from w in DAT.Workspace.registerPerson(e)
                                  select w)
        from _ in Api.lift(Clone.personWorkspaceFolder(wid))
        select unit;
}

This automatically manages: security, state, configuration, resource-tracking, DB access, IO, etc. All without having to manually pass values around as arguments. The only arguments you see to functions are the ones needed by the functions themselves. That means it's easy to refactor and restructure based on the changing needs of your application and it usually means a reduction of boilerplate, making everything more declarative.

The other thing you may notice is how all of the async code is wrapped up. You're already hitting the problems of trying to compose Task<Either<..>> with Either<..>; this is a big push for the changes in v5 of language-ext. Trying to make async go away as much as possible so you don't have to deal with these type mismatches.

This is obviously taking the idea as far as it can go. And I certainly wouldn't go all in on this approach until you're comfortable with the guidelines and the motivations. It takes a while for this to all sink in, just remember that passing Option and Either around are the foothills of functional-programming, there's a lot more to learn to really become fluent.

If you're really interested in seeing how far this can go, then it's worth starting my 'Higher Kinds in C# with language-ext' series, it introduces many of the concepts I list above and talks a little about the philosophy too.

I wish I could shortcut the learning, but believe me, that "aha!" moment will come! 👍

[Andras-Csanyi]

Sweet Jesus, what an answer! Thank you very much! I'll read it through a few times and do my best to understand it and extend the world, a very small world in my head in terms of functional programming, in my mind and come back with further questions.
I am really looking for that "aha!" moment and I know it will come and it requires a lot of trial and error. But, this is the natural way of learning. I don't have any intention to find shortcuts. At the moment, I feel that I learn the concepts and how these concepts relate to each other and can be represented. I believe the hardest part of the learning when you discover what is that you don't know, you don't have definitions for and you can't even ask questions or the questions are not straightforward enough. This is where I am now.