thinkbeforecoding

Functional Event Sourcing Decider

2021-12-17T08:55:54.2019611+00:00

this post is part of the F# Advent Calendar 2021

After years of talks and workshops about Functional Event Sourcing, I noticed that I published only 4 posts on the topic.

The first is a rant in 2013 about Martin Fowler's article from 2005 describing something that could be called Command Sourcing and is misleading people into thinking they are doing Event Sourcing.

The second is a simple drawing describing the flow of Functional Event Sourcing. Really useful, many people told me something clicked once they saw this picture. But still a bit short. I made a few wording changes since then.

I then made two posts about Monoidal Event Sourcing trying theoretical ideas to change this external monoid to a plain monoid.

It was accompanied by many samples on github, such as the various FsUno implementations, the crazyeights workshop as well as the source code of Crazy Farmers' port for Board Game Arena that uses both Server Side and Client Side event sourcing -- the client side being transpiled to JS using Fable, and the server side to PHP using peeble.

I'm currently working on a book about it, but writing books takes time. And digging deep into the topic led me to discover new things that make it even longer to write.

So here it is, a beginner's introduction to Functional Event Sourcing and its main pattern, the Decider.

Anatomy of a Service

Let's look at a System. Any System.

Without interactions with the outside, such a system would be pretty useless. We can represent these interactions in a generic way as inputs and outputs

A system that accepts inputs but produces no outputs would be a kind of black hole.

this is not totally useless (cf /dev/null), but quite limited.

On the other hand, a system that produces outputs without inputs seems also very simplistic. Without introducing time, it would necessarily be a constant:

So, let's introduce time; let's add a clock to our system:

The problem with a clock is that it's (obviously) changing over time, so let's refactor to treat clock as an input (it also becomes a trigger):

Here, our system is a pure function of time. This can be useful; however, most of the systems we deal with are a bit more complicated.

As we wanted interactions, we can reintroduce inputs as triggers. For instance a user action.

To go back on the question of time, some time is passed in the system during code execution. But at today’s execution speed, especially outside of inputs/outputs, code execution can be considered as instant. To be executed the code needs some trigger to be called and run.

A user action can be such a trigger, in this case, the current time can be seen as one parameter of the action.

The trigger can also be the clock (a timer, an alarm..), but still the code is called for some reason (it's time for the Market to close, a check must be made every 5 minutes...). In this case, this is a scheduled automatic action, but it's still an action with current time as additional data.

Most of the time, the output not only depends on the input action, but also on what happened before.

The system needs a way to keep a trace of the effects of previous actions to react accordingly.

Without such memory, the system is always reacting the same way to the same input action, regardless of anything that happened in the past. Some systems behave like this, but are a constrained case of more general systems that keep a trace of past actions.

This memory is called state and is accessed and modified by the system code. It can be stored in memory (RAM) or saved to a database. Reading it can be considered a sort of input, changing it a sort of output:

This is a useful step. The subsystem can be cleared of a lot of technical concerns. The input interfaces can be abstracted (HTTP API, message queue, UI events, command line arguments, timers or alarms...) and parameters can be passed to the subsystem directly. The output interaction can also be abstracted and hidden behind interfaces (Outbound HTTP calls, messages or notification sending...). State loading and saving can also be hidden behind an interface to protect the subsystem from implementation details.

Once carefully stripped of technical concerns, the code in the subsystem is merely composed of the system logic; what we commonly call the business logic, or the Domain. We call the rest of the code the Application layer.

We described here the hexagonal architecture where the application core and the Domain are loosely coupled to their environment through port interfaces, implemented as adapters to the technical infrastructure.

Functional Core

We can go a bit further by applying Functional Core to our model. The idea is to write the Subsystem as a pure function.

The input Actions and Clock will be passed as input values (the current time, if needed, in the case of the clock). Actually we can consider current time as being a parameter of the action, and will not mention it again.

For state, we can also load its current value, and pass it to the function. The function will return a new state that can be stored.

Outputs and side effects can also be returned as values by the functions, and the side effects will be performed by the application layer:

let subsystem (action: Action) (state: State) : State * Output list =
    state, []

This is here, obviously a system that does nothing. By returning a new state, it will be persisted for the next call, and by returning output, it will be able to product other side effects.

Actions and Commands

The Functional Core Domain is called on external triggers we called Actions. We can split them initially into two groups we'll call Commands and Events.

A command is an action on the system with an intention to change it. A user places an order, cancels a subscription or books a hotel room. It can succeed or fail, but should have an effect on the system.

On the other side, something can happen outside of the system that should have an effect on it. The weather changed, a customer checked out, a cargo left a harbor, a scheduled alarm expired. Those things happened and there's nothing we can do to change the fact. This can trigger a change in the system. We call them External Events.

Our Functional Core domain could directly take External Events as an input, be we can find in the Domain internal Commands associated. The WeatherChanged event leads to a PrepareForRain command. It's 4PM, the market bell rang; that's a CloseMarket command.

In the same way, in user interface code, it is advised to not take action directly in event handler's code. In the onButtonClicked function, it is better to call another DoAction() function that does the actual action. The code is clearer and the action can then be called on different triggers, and just tested without having to raise the event itself.

There is also a distinction between External Commands and Internal Commands. Current time can be important to process a command, and will be part of input data. However, current time will not be provided by the Command sender as that would be highly unsafe: caller could ante/postdate the Command. The External Command is instead enriched with current time in the Application layer. Similarly for external data such as exchange rates, weather conditions or resources protected by access rights. Caller identity should also be used with care, it can be either validated using a password, access-key, signature or a login check.

We will now consider any Domain input action as an internal Command containing all enrichment data and call it a Command for brevity. A Command can be implemented as a data structure with a name indicating its intent and containing the associated data. Its name is always a verb phrase in the imperative tense.

Decision

The next step is to look inside the Functional Core Domain and split it even further.

It's a pure function that takes a Command and current State, and returns a State and some Outputs.

The typical way to proceed in fulfilling a Command given current State is to modify State according to business rules. The code checks what the situation is and follows the rules defined by the domain to modify the State in a consistent way.

Doing this, we're going a bit too fast. We take some shortcuts. We take decisions and apply the effects of these decisions at the same time. These are two quite different steps, and conflating them obscures the actual decision process.

Leaving the decision process implicit proves to be problematic. Looking at data, the business is wondering why we ended up in the current state. Is it a bug, or did a legitimate chain of actions produce this unexpected result? Tracing back observable side effects and saved intermediate state is time consuming and cannot always give definitive answers.

Against logging

This often leads to bloating the code with logs. Logs are initially useful, but they don't age well. They are added on second thought, and seldom tested. Like commands, after a few refactorings, they most often end up outdated, reporting incorrect and/or partial traces. Having up correct logging in sync with the model requires a lot of care. The first slip in that care erodes trust in the traces. This quickly becomes a time hog during diagnosis. Especially when unexpected cases happen, everything needs to be double checked, in the traces and in the code that may have changed in-between.

As an afterthought, their operation is also not designed with care. Log retention is costly, and choosing the right log level is difficult. Too verbose, and the expense of log storage can become prohibitive, forcing a short retention period. Not verbose enough, and critical information can be missing. Cleaning logs is also difficult because not all logs are of equal importance, nor is everything equally relevant over the same timespan. Sadly, log systems rarely give much flexibility in the cleaning/archiving process. All this becomes useless anyway if the log cannot be trusted.

Events

To avoid these conflicts, we untangle decision making from the changing of the state. We'll be explicit about what happens by materializing decision outcomes before changing state, and changing state based only on the decision outcome data.

We can express these Commands processing outcomes as Events. Each one expresses what just happened to the system as a past tense verb, which then leads to a new state.

A Switch Light On Command will, if valid, produce a Light Switched On Event. A Transfer Money Command will produce a Money Transferred Event, or a Money Transfer Rejected Event due to insufficient funds.

A Decision process then takes this simple form:

If we use simple data structures for Commands, State and Events, the decision can be implemented as a function with the following signature:

type Decide = Command -> State -> Event list

Since we decided to not modify state at this stage, the State can be immutable (read only), as the Commands and Events should also be.

This function has no reason to produce any side effects, such as reading or writing external state, or calling external services. We've seen how to deal with external data like current time or exchange rates already. So it can be implemented as a pure function:

Its return value should depend only on the input parameters
It should not produce any noticeable external side effect.

The first point is really interesting for testing and reasoning about the code. Given a current State and a Command, the resulting Event list is always identical. This is true whatever the day and time and whatever the current state anywhere else. It eases the testing as they will never be dependent on external concerns. It also eases debugging; if we logged the Command data and have a way to know the State at that point in time - which we’ll do - there is only a single possible outcome. This forces us to not depend on any external data that is not already in State or Command parameters, such as current time or external data retrieval.

The second point stems from our choice to make decisions outcomes explicit. If the function produces any side effect, that breaks our principle of first expressing the decision made before applying any change. We’ll also see why even logging is useless inside this function.

These constraints give rise to many interesting properties.

In summary, a decision function is a way to write:

When asked to process this Command in a given State, here is what happens, expressed as Events.

Evolution

We’ve decided to split taking a decision and applying the resulting changes. The goal was to make the actual decision taken more explicit in the code base. So, in the previous part, we devised a Decide function that returns Events but does not actually change State. Now, let’s see how to capture change in a simple and highly testable way. This will actually be quite straight forward.

To compute the new State, we need the current State and the Event that just happened.

We could modify the current State, mutating it so it becomes the new State, but this is not how we’ll proceed. Mutation will not automatically lead you to bad code and bugs, but we can consider it a premature optimization at this point. If you’re not familiar with Functional Programming, immutability can seem very costly and inefficient (and this can be correct in some contexts). But most modern languages, functional or not, are fast enough in immutable scenarios compared to querying a database or making a network call. The result is that the overhead of immutability at the level of Domain code can often be ignored. We’ll see how using immutable data structures for State enables reasoning about the code, and how it has interesting composition properties. So let’s proceed with immutable State, and you’ll decide your implementation strategy based on your own stack constraints later.

Earlier, our Decision function was returning an Event list containing zero, one or more events. We will focus first on how to deal with a single Event. It will be easy to extend from there to handling multiple events.

With immutable read only State data structures and read only Events, it becomes obvious that computing new State will also be implemented as a pure function. There is no way to change the supplied current State and Event; they are read only. The Event and the State must contain all the data we need, so there is no point fetching data from somewhere else. No external service calls. In that structure, mutating data outside would be akin to using global state, which would defeat the purpose of all this. We have all the required data at hand, and just have to compute the new State to return it. We’ll see further that there is also no reason for things like logging or tracing in this code.

Let’s call this function evolve; its signature is:

type Evolve = State -> Event -> State

It takes a State and an Event and returns a State. Its meaning is: Given a current State, when Event occurs, here is the new State.

The code of the evolve function should be extremely simple; the Decision has already been taken. It should probably not be more that setting a field, adding a element to a list, incrementing a value, or setting/resetting a flag.

The evolve function is central to Event Sourcing but will rarely be more complicated than a few lines of codes.

Initial State

For the first Command, we find ourselves in a specific situation. We have a Command and a decide function. But the decide function needs an input state, and we have no State yet that we can pass as a parameter. It's the same situation with the evolve function on the first Event.

If we consider the state returned by the evolve function and this first Event, we can obviously say that it's the State after the first Event occurs. So the input state is the State before the first Event occurs, when nothing occurred yet. We will call this the Initial State.

The Initial State is important as it has to be explicitly defined. Sometimes we may opt to use a possible future State for it. For a light, for instance, it could be On or Off. For an account, it could be defined with a 0 balance. It will just use specific values for the properties, and it is totally possible that it will be back in the same state later. The light will be Off again, and the account could return to a 0 balance in the future.

However, the first Event is sometimes irreversible. For a card game, before the first event happens, the game is not yet started. After the first event, it is started. It will eventually end, but will not return to the "not started yet state" anymore. This situation often arises when some initial properties have to be defined; some initial actions sets the system up. In a card game, the dealer will place the first card on the table. This is an action that can only happen at the beginning, it's the game setup. It marks the actual start of the game; before that, no other action can take place.

In this case, the initial State has no other purpose than representing that we are ready to handle the initial action. It doesn't need to contain more information. It is easy to represent such state in languages with sum types or discriminated unions:

  type State =
      | InitialState
      | Started of topCard: Card

  let initialState = InitialState

This indicates that the state is always either a) InitialState (without any more information), or b) the game is in progress, with the specified card on top of the pile.

In languages without sum types, we'll usually use a boolean or enum value to mark the difference:

  type State =
    { Started: bool
      TopCard: Card}
  let initialState =
    { Started = false
      TopCard = Unchecked.defaultof<Card> }

You can notice here that two problems arise. First, we have to be careful not to use the TopCard property when Started is false. Should we use an exception or a similar error mechanism to prevent this from happening? Probably, but it would be far better to not be able to write such code in the first place. Second, what is a good value for TopCard in the initial state when Started is false? Here I chose a three of clubs, which seems a bit arbitrary; but any value would be. There is no good value of the Card type that naturally represents a default value. In some languages, an option might be to use null, but this is also dangerous if null is never a valid value once started. Null Reference Exceptions are frequent errors that are better avoided from the start. If we are prepared to use null, the next option would be to use it and get rid of Started altogether.

On the pro side, this makes state more compact, and avoids requiring a check on a property to know if the other is valid, potentially leading to consistency problems. On the con side, the initial state is less explicit. The code doesn’t clearly express when it is valid to have a TopCard or not.

Stitching it together

Now we have all the parts needed for Event Sourcing. Let's put them together. We described three types and three elements in the previous sections, with the following signatures:

type Command
type Event
type State
initialState: State
decide: Command -> State -> Event list
evolve: State -> Event -> State

The Command will come from the outside, but the State and Event list will be fed from the decide function output to the evolve function input while the output State from the evolve function will be passed to the next call to the decide function. The same output State will also be used as an input parameter for the next call to the evolve function.

When processing in the system begins, it is in the Initial State. For now, nothing has happened yet.

When the first command arrives, we have a Command and a State that we can pass to the decide function. It will return the outcomes of the Command as a list of Events: the things that happened in reaction to the input Command.

If the output Event list is empty, nothing happened; there's no need to compute a new state and we are ready for the next Command. This should not happen frequently for at least two reasons. A system that does mostly nothing is not very interesting and can probably be implemented without Event Sourcing... But doing nothing can also make some situations harder to diagnose. When a Command was intended to do something but resulted in no change, it can be interesting to know the reasons. Emitting no Events will make the distinction between an infrastructure problem and a motivated decision to do nothing harder to find. Did the system crash, or did it just decide to do nothing?

It is still possible to know by taking a copy of the Command that has been persisted for diagnostic purposes, and a State reconstructed from past Events, passing them to the decide function and examining the result, but it will require careful code analysis or creating a new test with this specific data. This drains developers time and is better avoided.

If the decision to do nothing results from a business rule, it is advised to make it explicit, returning an Event that will not affect State. It will clearly appear in the produced Events and diagnostics will be trivial. This validation can be done by support teams without any access to the code.

However, if nothing happened simply because we are already in some expected state, that's a case of an idempotent Command. In such cases, it is actually better to return no Events. This avoids bloating the Event Store with useless duplicate Events.

When the Event list contains an Event, we can call the evolve function with current State and that Event. The resulting new State is then used for the next Command instead of the Initial State.

Sometimes the Event list will contain several Events. In this case we will call the evolve function for each Event, passing previous computed State along.

This could give something like:

let newState1 = evolve currentState event1
let newState2 = evolve newState1 event2
let newState3 = evolve newState2 event3

We can do better, but we now have the next current State and we are ready to process the next Command.

Fold

When we have several events, we have to call the evolve function for each.

A simple way to do that is to use a loop:

let computeNextState currentState events =
    let mutable state = currentState
    for event in events do
        state <- evolve state event
    state

As you can see, F# makes mutability explicit through the mutable keyword. Without it, state cannot be changed to a new value... It also uses this backward looking left arrow <- which seems to suggest that we're going in the wrong direction. F# IDEs also tend to display mutable variables in orange to signal them as a kind of warning...

Another way to proceed without mutation is to use a recursive function that we will call fold:

let rec fold state events =
    match events with
    | [] ->     // there are no events..
        state   // nothing changed
    | event :: rest ->
        // compute state after first event
        let newState = evolve state event
        // do it again with next events
        fold newState rest

When the list is empty [] we just return the input state. When the list is not empty, we deconstruct the list as event :: rest, event is first Event, and rest is rest of the list. We can then compute the new intermediate State using evolve and call fold again with this newState and the remaining events rest, until we have applied them all.

let rec fld f s es =
    match es with
    |[] ->
        s
    | e :: es ->
        let ns = f s e
        fld f ns es

Most languages provide libraries containing an implementation of this function. It is called fold, left fold or aggregate. It takes a list, an aggregation function, and an initial value. It calls the aggregation function for each item in the list with this item and previous result. In F# its signature is:

List.fold: ('s -> 'e -> 's) -> 's -> 'e list -> 's

It seems a bit cryptic at first, but bear with me. The tick (') marks generic type names that can be any actual type. The only constraint is that all 's should have the same type, and same thing for all 'e. The first argument is a 's -> 'e -> 's - a function that takes a 's and an 'e and returns a 's. We can notice that it’s the same form as our evolve function when replacing 's with State and 'e with Event. The second argument is a 's, in our case a State. That's the initial value. The 'e list in our case is the Event list. Finally, the result is a 's, which will be a State.

Computing a new state after events when initially in a given state is simply:

let newState = List.fold evolve state events

It will work as expected with no event in the list, in which case it will return the input state. It will also process a single event as we did by calling the evolve function once.

The nice thing it that it is also useful for rebuilding the current State from the Initial State and the full list of Events that happened:

let currentState = List.fold evolve initialState events

This is exactly what we’ll need when restarting the system from a persisted Event Log.

Or not fold

While the previous description represents a vast majority of event sourced systems, we should still consider a possibility that could be useful in some cases.

It would be totally legit to use the following evolve function:

type State = Event list
let initialState = []

let evolve state (event: Event) =
    List.append state [event]

The state would then just be the full list of all events that happened so far. That would definitely contain all the information needed by the decide function:

let decide command (state: Event list) =
    (* ... *)

This decide function can now work through the event list to find relevant data to take decision.

Once going this direction, the evolve function looks rather useless. Folding the state would look like:

events |> List.fold evolve initialState

Which is equivalent to:

events |> List.fold (fun state event -> List.append state [event]) []

This rebuilds an exact copy of the initial events list! We can just pass the events list directly to the decide function.

In that setting, there is just a decide function with the following signature:

decide: Command -> Event list -> Event list

A function that takes a command and a list of Events and returns a list of new Events.

There's no need for state nor an evolve function.

This can definitely be of use in contexts with few events, or when performance doesn’t come into play.

State built by the evolve function is just a projection to compact the information contained in the events to make it easier and/or faster for the decide function to take decisions. If it does not make it easier/faster, just use the raw event list.

The full list of past Events is the form of the State that contains maximal information. This represents the full history.

Terminal State

For now our system has an Initial State to start, and the decide and evolve functions, to handle change over time.

At first it seems enough, but this is due to one of our typical engineer’s bias… We’re very good at setting things up, but bad at disposing them. I’ve seen many systems where loads of data remained in the system mostly because nobody knew if it was safe to get rid of it.

This can be seen in the industry at large. Mobile phones have been produced in astronomical numbers before realizing something should be done to dispose them properly, and this is still not handled by the manufacturers. Similarly for nuclear power plants that have not been designed considering how they can be dismantled.

Whether you consider using event sourcing or not, it is best to consider this up front and explicitly design for disposal.

Some things naturally have a definite lifetime. For instance, once an order has been shipped and every post shipment task have been processed, it should never change anymore. Same thing for a card game; when the game is over, the result can be taken into account for statistics etc, but the game will not change anymore, the decide function will never be called again.

This can have many implications. For instance, if you keep state in memory for fast response, you can now unload it to save space. It also means that the history can be archived or deleted depending on your retention needs.

Removing old data from your system (or at least moving it to a colder area) will keep your hot area slim and far more manageable. This is an efficient way to lower costs and simplify updates and migrations.

Even parts that have a definite lifetime are sometimes hard to dispose. For instance, what happens when an order shipment was lost and there’s nobody to reclaim it? or where all players in a game left the table to never return? That could lead to data dangling forever. To avoid this, you have to determine a policy with domain experts. Appropriate solutions probably already exist in the domain. For instance, lost shipment cases are considered closed after 1 month in absence of reclamation. Or you could establish a new one. For a card game, players have a maximum time to play. That could range from a few hours for a real time game, to a few weeks for turn by turn. A process could be put in place to alert users, but after this delay a command is sent to the system to close it, and it then transitions to a terminal state.

The question is more tricky for systems whose behavior can span continuously over many years with no foreseeable end. But this is something that has already been solved by accountants. Accounting records for a company can easily span decades. The current balance is impacted by all the records since the beginning, but it would be impractical to recompute everything from the first record. Especially after a few years, the relevance of such records to the current state drops significantly. This is where accountants define an accounting period. At the end of the period, a book balance is computed, and reconciled with the bank balances. The current book is closed and a new one is opened, starting from previous book balance. This way, once a book is closed, it is never changed anymore and can be archived for reference. If an error is found after closing the book, a compensation record is added in the current book.

It is highly advised to put such mechanisms in place for your own system, especially if you keep data over time, like saving events. Even if storage is getting cheaper over time, your system will evolve, and since data that is considered hot can change at any time, it must be migrated and evolved in a transactional or high availability, zero downtime way. This places a high burden on operations. For streams of events, the time takes to recompute the current state with such strategy will depend on your business size. Without it, it will be dependent on both business size and time since it started (it’s actually an integral of business size over time).

Once we’ve defined a condition for disposability, we can implement it with a simple function:

IsTerminal: 'state -> bool

This function takes a state, and returns a bool indicating if it is a terminal state. I really encourage you to make it part of your design to avoid maintenance problems later.

Decider

We’ve seen that State and the evolve function are just an optimization to compact information, to avoid going through the full list of Events at each call of the decide function. This clearly indicates that the most important part in what we’ve seen so far is the decide function.

We will call a Decider the combination of the seven elements we’ve identified so far:

A Command type that represents all commands that can be submitted to the Decider
An Event type that represents all events that can be produced by the Decider
A State type that represents all possible states of the Decider (can just be the list of all events)
An Initial State that is the state of the Decider before anything happens
A decide function that takes a Command and a State and returns a list of Event
An evolve function that takes a State and an Event and returns a new State
An isTerminal function that takes a State and returns a boolean value

In F# this can be modeled as:

type Decider<'c,'e,'s> =
    { decide: 'c -> 's -> 'e list
      evolve: 's -> 'e -> 's
      initialState: 's
      isTerminal: 's -> bool }

The Decider is a conceptual way to think about systems that change in time; a concepty interface between the Application layer and the Domain code. It ensures extremely low friction between them.

Run in memory

We can easily make a decider run in memory on a mutable State variable:

module InMemory =
    let start (decider: Decider<'c,'e,'s>) =
        let mutable state = decider.initialState

        fun (command: 'c) ->
            let events = decider.decide command state
            state <- List.fold decider.evolve state events
            events

For any decider we can now call the start function. It will return a function which given a command, returns the list of Events and is ready to handle the next command.

Run on a database

The previous implementation is not persistent, and will lose any state once closed. We can persist state in a database like any classic application:

module WithPersistence =
    let start (decider: Decider<'c,'e,'s>) =
        fun id (command: 'c) ->
            // load state from database
            let state = Storage.loadState(id)
            // this is the decision
            let events = decider.decide command state
            // compute new state
            let newState = List.fold decider.evolve state events
            // save state in database
            Storage.saveState(id, newState)
            events

This version is simple, but can be dangerous if the state can be modified concurrently. If operations can never be concurrent, this code is simple and perfectly fine.

It is then easily protected using an etag. This is usually a string returned by the database that is modified on each change. The database can check that the provided etag matches the actual etag before applying the update.

module PersistenceWithEtag =
    let start (decider: Decider<'c,'e,'s>) =
        fun id (command: 'c) ->
            let rec handle() =
                // load state and etag
                let etag, state = StorageWithEtag.loadState(id)
                // this is the decision
                let events = decider.decide command state
                // compute the new state
                let newState = List.fold decider.evolve state events
                // try to save, checking the state still match etag
                if StorageWithEtag.trySaveState(id, etag, newState) then
                    events
                else
                    handle()
            handle()

This version will stubbornly retry until we avoid the concurrency problem.

It is also possible to keep state in memory to avoid loading state on each call. However in case of conflict, we will reload the state as well as the current Etag

module PersistenceWithEtagAndRetry =
    let start (decider: Decider<'c,'e,'s>) =
        // load initial state
        let mutable etagAndState = StorageWithEtagAndRetry.loadState(id)
        fun id (command: 'c) ->
            let rec handle (etag, state) =
                let (etag, state) = etagAndState
                // this is the decision
                let events = decider.decide command state
                // compute new state
                let newState = List.fold decider.evolve state events
                // try to save, checking the state still matches the etag
                match StorageWithEtagAndRetry.trySaveState(id, etag, state)  with
                | Some newEtag ->
                    // state has been saved
                    etagAndState <- (newEtag, newState)
                    events
                | None ->
                    // a conflict occurred, reload etag and state
                    // from database and retry
                    handle (StorageWithEtagAndRetry.loadState(id))
            handle etagAndState

It is possible to also store events in an Event Store, but still load/save state on each call. In this case, events can be used to recompute the current State when a refactoring alters its shape. Instead of migrating the old state version to new version using a one time script, you can fold all saved events through the evolve function and save state with this new version. This is actually the equivalent of saving a snapshot on each call.

Run on an event store

It can also easily be implemented using an event store

module WithEventStore =
    let start (decider: Decider<'c,'e,'s>) =
        fun stream (command: 'c) ->
            // load all past events to compute current state
            let state =
                EventStore.loadEvents(stream, 0)
                |> List.fold decider.evolve decider.initialState
            // get events from the decision
            let events = decider.decide command state
            // append events to stream
            EventStore.appendEvents(stream, events)
            events

This version is reloading all the events from the beginning on each command. This is perfectly reasonable for short streams. Since events are usually small in size, loading less that 100 events is very fast and folding them, almost instant (think of it as a loop of 100 iterations that does a few basic operations).

As with the database-backed version, we can protect it against concurrent appends to the stream. Here we use stream version which is usually provided by the Event Store. The appendEvents function now takes an expected version and will reject append if the stream version is not matching. If it is not matching it will return the new version as well as events that have been appended since the one anticipated.

module WithEventStoreAndVersion =
    let start (decider: Decider<'c,'e,'s>) =
        fun stream (command: 'c) ->
            let rec handle version state =
                // get events from decision
                let events = decider.decide command state
                match EventStoreWithVersion.tryAppendEvents(stream, version, events) with
                | Ok version ->
                    // save succeeded, we can return events
                    events
                | Error (actualVersion, catchupEvents) ->
                    // it failed, but we now have the events that we missed
                    // catch up the current state to the actual state in the database
                    let actualState = List.fold decider.evolve state catchupEvents
                    // and try again
                    handle actualVersion actualState
            // load past events
            let version, pastEvents = EventStoreWithVersion.loadEvents(stream)
            // compute current state
            let state = List.fold decider.evolve decider.initialState pastEvents
            handle version state

This can obviously be extended to keep state in memory:

module WithEventStoreInMemory =
    let start stream (decider: Decider<'c,'e,'s>) =
        let mutable versionAndState =
            let version, pastEvents = EventStoreWithVersion.loadEvents(stream)
            // compute current state
            let state = List.fold decider.evolve decider.initialState pastEvents
            version, state

        fun (command: 'c) ->
            let rec handle (version, state) =
                // get events from decision
                let events = decider.decide command state
                match EventStoreWithVersion.tryAppendEvents(stream, version, events) with
                | Ok newVersion ->
                    // save succeeded, we can return events
                    let newState = List.fold decider.evolve state events
                    versionAndState <- (newVersion, newState)
                    events
                | Error (actualVersion, catchupEvents) ->
                    // it failed, but we have events that we missed
                    // compute current state
                    let actualState = List.fold decider.evolve state catchupEvents
                    // and try again
                    handle (actualVersion, actualState)

            handle versionAndState

Snapshots

Once you have many events, it can start taking a long time to reload everything. It is then possible to save the state periodically along with the version of the stream that produced this state. The snapshots can be saved in a key value store:

module WithSnapshots =
    let start (decider: Decider<'c,'e,'s>) =
        // load state using snapshot if any
        let loadState stream =
            // load snapshot
            let snapVersion, snapState =
                Snapshots.tryLoadSnapshot(stream)
                    // fallback to version 0 and initialState if not found
                |> Option.defaultValue (0, decider.initialState)

            // load version and events after snapshot
            let version, events =
                EventStoreWithVersion.loadEvents(stream, snapVersion)
            // fold events after snapshot
            let state = List.fold decider.evolve snapState events
            version, state

        fun stream (command: 'c) ->
            let rec handle (version, state) =
                // get events from the decision
                let events = decider.decide command state
                // append events to stream
                match EventStoreWithVersion.tryAppendEvents(stream, version, events) with
                | Ok newVersion ->
                    if isTimeToSnapshot version then
                        // it is time to save snapshot
                        // compute state
                        let newState = List.fold decider.evolve state events
                        // save it
                        Snapshots.saveSnapshot(stream, newVersion, newState)
                    events
                | Error(actualVersion, catchupEvents) ->
                    // there was a concurrent write
                    // catch-up missing events and retry
                    let actualState = List.fold decider.evolve state catchupEvents
                    handle (actualVersion, actualState)


            // load all past events to compute current state
            // using snapshot if any
            let version, state = loadState stream
            handle (version, state)

Here again we have the problem of snapshot invalidation. The easiest way to deal with it is to store all snapshots for a same version of the code in a same collection, container or database, and change it when snapshots are not valid anymore. This happens when the structure of the state changes after a refactoring. The saved snapshots won't have the expected shape which could cause some errors.

You can just change the collection/container/database name when this happen. The collection will be empty on start and snapshots will be recomputed. You may even opt to recompute snapshots in advance before deploying a new version.

Once we've deployed and verified that old version is not needed anymore, you can just delete the old collection.

Conceptually, you would compute the collection name as a hash of the evolve function. This way, snapshots will be automatically invalidated when the evolve function changes (which always happens when the state structure changes)

module WithSnapshotsInContainers =
    let start (decider: Decider<'c,'e,'s>) =
        let container = getContainerFromDecideHash(decider)
        // load state using snapshot if any
        let loadState stream =
            // load snapshot.. it will not be found if container has
            // changed since last run
            let snapVersion, snapState =
                SnapshotsWithContainer.tryLoadSnapshot(stream, container)
                    // fallback to version 0 and initialState if not found
                |> Option.defaultValue (0, decider.initialState)

            // load version and events after snapshot
            let version, events =
                EventStoreWithVersion.loadEvents(stream, snapVersion)
            // fold events after snapshot
            let state = List.fold decider.evolve snapState events
            version, state

        fun stream (command: 'c) ->
            let rec handle (version, state) =
                // get events from the decision
                let events = decider.decide command state
                // append events to stream
                match EventStoreWithVersion.tryAppendEvents(stream, version, events) with
                | Ok newVersion ->
                    if isTimeToSnapshot version then
                        // it is time to save snapshot
                        // compute state
                        let newState = List.fold decider.evolve state events
                        // save it
                        SnapshotsWithContainer.saveSnapshot(stream, container, newVersion, newState)
                    events
                | Error(actualVersion, catchupEvents) ->
                    // there was a concurrent write
                    // catch-up missing events and retry
                    let actualState = List.fold decider.evolve state catchupEvents
                    handle (actualVersion, actualState)


            // load all past events to compute current state
            // using snapshot if any
            let version, state = loadState stream
            handle (version, state)

Conclusion

You may have noticed that all the infrastructure code we wrote to run the Decider is totally agnostic of the actual Domain Code. It could be running a simple game or a complex business system, it will still stay the same.

The other interesting point is that decider can be run in many ways. Purely in memory, storing state in a database or an event store. No changes to the domain code were required. This indicates a high level of independence from infrastructure concerns.

You can write the Domain code as Deciders, and choose afterward which kind of persistence you want to use, if any.

The last interesting point, is that Deciders can be composed. But that's another story...

Credits: Special thanks to Greg Young and Ruben Bartelink, Adam Dymitruk and Mathias Verraes for their time and insight on the topic.

namespace System

Multiple items
union case Action.Action: Action

--------------------
type Action = | Action

--------------------
type Action<'T> = new: object: obj * method: nativeint -> unit member BeginInvoke: obj: 'T * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: obj: 'T -> unit
<summary>Encapsulates a method that has a single parameter and does not return a value.</summary>
<param name="obj">The parameter of the method that this delegate encapsulates.</param>
<typeparam name="T">The type of the parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 -> unit
<summary>Encapsulates a method that has two parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 -> unit
<summary>Encapsulates a method that has three parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 -> unit
<summary>Encapsulates a method that has four parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 -> unit
<summary>Encapsulates a method that has five parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 -> unit
<summary>Encapsulates a method that has six parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 -> unit
<summary>Encapsulates a method that has seven parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 -> unit
<summary>Encapsulates a method that has eight parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 -> unit
<summary>Encapsulates a method that has nine parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 -> unit
<summary>Encapsulates a method that has 10 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10,'T11> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 -> unit
<summary>Encapsulates a method that has 11 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<param name="arg11">The eleventh parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T11">The type of the eleventh parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10,'T11,'T12> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 -> unit
<summary>Encapsulates a method that has 12 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<param name="arg11">The eleventh parameter of the method that this delegate encapsulates.</param>
<param name="arg12">The twelfth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T11">The type of the eleventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T12">The type of the twelfth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10,'T11,'T12,'T13> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 -> unit
<summary>Encapsulates a method that has 13 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<param name="arg11">The eleventh parameter of the method that this delegate encapsulates.</param>
<param name="arg12">The twelfth parameter of the method that this delegate encapsulates.</param>
<param name="arg13">The thirteenth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T11">The type of the eleventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T12">The type of the twelfth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T13">The type of the thirteenth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10,'T11,'T12,'T13,'T14> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * arg14: 'T14 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * arg14: 'T14 -> unit
<summary>Encapsulates a method that has 14 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<param name="arg11">The eleventh parameter of the method that this delegate encapsulates.</param>
<param name="arg12">The twelfth parameter of the method that this delegate encapsulates.</param>
<param name="arg13">The thirteenth parameter of the method that this delegate encapsulates.</param>
<param name="arg14">The fourteenth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T11">The type of the eleventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T12">The type of the twelfth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T13">The type of the thirteenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T14">The type of the fourteenth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10,'T11,'T12,'T13,'T14,'T15> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * arg14: 'T14 * arg15: 'T15 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * arg14: 'T14 * arg15: 'T15 -> unit
<summary>Encapsulates a method that has 15 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<param name="arg11">The eleventh parameter of the method that this delegate encapsulates.</param>
<param name="arg12">The twelfth parameter of the method that this delegate encapsulates.</param>
<param name="arg13">The thirteenth parameter of the method that this delegate encapsulates.</param>
<param name="arg14">The fourteenth parameter of the method that this delegate encapsulates.</param>
<param name="arg15">The fifteenth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T11">The type of the eleventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T12">The type of the twelfth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T13">The type of the thirteenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T14">The type of the fourteenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T15">The type of the fifteenth parameter of the method that this delegate encapsulates.</typeparam>

--------------------
type Action<'T1,'T2,'T3,'T4,'T5,'T6,'T7,'T8,'T9,'T10,'T11,'T12,'T13,'T14,'T15,'T16> = new: object: obj * method: nativeint -> unit member BeginInvoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * arg14: 'T14 * arg15: 'T15 * arg16: 'T16 * callback: AsyncCallback * object: obj -> IAsyncResult member EndInvoke: result: IAsyncResult -> unit member Invoke: arg1: 'T1 * arg2: 'T2 * arg3: 'T3 * arg4: 'T4 * arg5: 'T5 * arg6: 'T6 * arg7: 'T7 * arg8: 'T8 * arg9: 'T9 * arg10: 'T10 * arg11: 'T11 * arg12: 'T12 * arg13: 'T13 * arg14: 'T14 * arg15: 'T15 * arg16: 'T16 -> unit
<summary>Encapsulates a method that has 16 parameters and does not return a value.</summary>
<param name="arg1">The first parameter of the method that this delegate encapsulates.</param>
<param name="arg2">The second parameter of the method that this delegate encapsulates.</param>
<param name="arg3">The third parameter of the method that this delegate encapsulates.</param>
<param name="arg4">The fourth parameter of the method that this delegate encapsulates.</param>
<param name="arg5">The fifth parameter of the method that this delegate encapsulates.</param>
<param name="arg6">The sixth parameter of the method that this delegate encapsulates.</param>
<param name="arg7">The seventh parameter of the method that this delegate encapsulates.</param>
<param name="arg8">The eighth parameter of the method that this delegate encapsulates.</param>
<param name="arg9">The ninth parameter of the method that this delegate encapsulates.</param>
<param name="arg10">The tenth parameter of the method that this delegate encapsulates.</param>
<param name="arg11">The eleventh parameter of the method that this delegate encapsulates.</param>
<param name="arg12">The twelfth parameter of the method that this delegate encapsulates.</param>
<param name="arg13">The thirteenth parameter of the method that this delegate encapsulates.</param>
<param name="arg14">The fourteenth parameter of the method that this delegate encapsulates.</param>
<param name="arg15">The fifteenth parameter of the method that this delegate encapsulates.</param>
<param name="arg16">The sixteenth parameter of the method that this delegate encapsulates.</param>
<typeparam name="T1">The type of the first parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T2">The type of the second parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T3">The type of the third parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T4">The type of the fourth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T5">The type of the fifth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T6">The type of the sixth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T7">The type of the seventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T8">The type of the eighth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T9">The type of the ninth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T10">The type of the tenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T11">The type of the eleventh parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T12">The type of the twelfth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T13">The type of the thirteenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T14">The type of the fourteenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T15">The type of the fifteenth parameter of the method that this delegate encapsulates.</typeparam>
<typeparam name="T16">The type of the sixteenth parameter of the method that this delegate encapsulates.</typeparam>

Multiple items
union case State.State: State

--------------------
type State = | State

Multiple items
union case Output.Output: Output

--------------------
type Output = | Output

val subsystem: action: Action -> state: State -> State * Output list

val action: Action

val state: State

type 'T list = List<'T>

Multiple items
union case Command.Command: Command

--------------------
type Command = | Command

Multiple items
union case Event.Event: Event

--------------------
module Event from Microsoft.FSharp.Control

--------------------
type Event = | Event

--------------------
type Event<'T> = new: unit -> Event<'T> member Trigger: arg: 'T -> unit member Publish: IEvent<'T>

--------------------
type Event<'Delegate,'Args (requires delegate and 'Delegate :> Delegate and reference type)> = new: unit -> Event<'Delegate,'Args> member Trigger: sender: objnull * args: 'Args -> unit member Publish: IEvent<'Delegate,'Args>

--------------------
new: unit -> Event<'T>

--------------------
new: unit -> Event<'Delegate,'Args>

type Decide = Command -> State -> Event list

type Evolve = State -> Event -> State

Multiple items
union case Card.Card: Card

--------------------
type Card = | Card

Multiple items
union case State.State: State

--------------------
type State = | InitialState | Started of topCard: Card

val initialState: State

union case State.InitialState: State

Multiple items
union case State.State: State

--------------------
type State = { Started: bool TopCard: Card }

type bool = Boolean

module Unchecked from Microsoft.FSharp.Core.Operators

val defaultof<'T> : 'T

type Command

Multiple items
module Event from Microsoft.FSharp.Control

--------------------
type Event

--------------------
type Event<'T> = new: unit -> Event<'T> member Trigger: arg: 'T -> unit member Publish: IEvent<'T>

--------------------
type Event<'Delegate,'Args (requires delegate and 'Delegate :> Delegate and reference type)> = new: unit -> Event<'Delegate,'Args> member Trigger: sender: objnull * args: 'Args -> unit member Publish: IEvent<'Delegate,'Args>

--------------------
new: unit -> Event<'T>

--------------------
new: unit -> Event<'Delegate,'Args>

type State

val evolve: state: State -> event: Event -> State

val event: Event

val failwith: message: string -> 'T

val computeNextState: currentState: State -> events: Event seq -> State

val currentState: State

val events: Event seq

val mutable state: State

val fold: state: State -> events: Event list -> State

val events: Event list

val rest: Event list

val newState: State

val fld: f: ('a -> 'b -> 'a) -> s: 'a -> es: 'b list -> 'a

val f: ('a -> 'b -> 'a)

val s: 'a

val es: 'b list

val e: 'b

val ns: 'a

Multiple items
module List from Microsoft.FSharp.Collections

--------------------
type List<'T> = | op_Nil | op_ColonColon of Head: 'T * Tail: 'T list interface IReadOnlyList<'T> interface IReadOnlyCollection<'T> interface IEnumerable interface IEnumerable<'T> member Equals: List<'T> * IEqualityComparer -> bool member GetReverseIndex: rank: int * offset: int -> int member GetSlice: startIndex: int option * endIndex: int option -> 'T list static member Cons: head: 'T * tail: 'T list -> 'T list member Head: 'T member IsEmpty: bool ...

val fold<'T,'State> : folder: ('State -> 'T -> 'State) -> state: 'State -> list: 'T list -> 'State

val append: list1: 'T list -> list2: 'T list -> 'T list

type bool = System.Boolean

type Decider<'c,'e,'s> = { decide: ('c -> 's -> 'e list) evolve: ('s -> 'e -> 's) initialState: 's isTerminal: ('s -> bool) }

val start: decider: Decider<'c,'e,'s> -> ('c -> 'e list)

val decider: Decider<'c,'e,'s>

val mutable state: 's

Decider.initialState: 's

val command: 'c

val events: 'e list

Decider.decide: 'c -> 's -> 'e list

Decider.evolve: 's -> 'e -> 's

val loadState: id: 'a -> 's

val id: 'a

val saveState: id: 'a * state: 's -> unit

val state: 's

type unit = Unit

val start: decider: Decider<'c,'e,'s> -> id: 'a -> command: 'c -> 'e list

module Storage from 2021-12-17-functional-event-sourcing-decider

val newState: 's

Multiple items
union case Etag.Etag: Etag

--------------------
type Etag = | Etag

val loadState: id: 'a -> Etag * 's

val trySaveState: id: 'a * etag: Etag * state: 's -> bool

val etag: Etag

val handle: unit -> 'e list

module StorageWithEtag from 2021-12-17-functional-event-sourcing-decider

val trySaveState: id: 'a * etag: Etag * state: 's -> Etag option

type 'T option = Option<'T>

val start: decider: Decider<'c,'e,'s> -> ('a -> 'c -> 'e list)

val mutable etagAndState: Etag * 's

module StorageWithEtagAndRetry from 2021-12-17-functional-event-sourcing-decider

val id: x: 'T -> 'T

val handle: etag: Etag * state: 'b -> 'e list

val state: 'b

union case Option.Some: Value: 'T -> Option<'T>

val newEtag: Etag

union case Option.None: Option<'T>

type Version = int

Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int

val loadEvents: stream: 'a * version: Version -> 'e list

val stream: 'a

val version: Version

val appendEvents: stream: 'a * events: 'e list -> 'b

val start: decider: Decider<'c,'e,'s> -> stream: 'a -> command: 'c -> 'e list

module EventStore from 2021-12-17-functional-event-sourcing-decider

val loadEvents: stream: 'a -> Version * 'e list

val tryAppendEvents: stream: 'a * expectedVersion: Version * events: 'e list -> Result<Version,(Version * 'e list)>

val expectedVersion: Version

Multiple items
module Result from Microsoft.FSharp.Core

--------------------
[<Struct>] type Result<'T,'TError> = | Ok of ResultValue: 'T | Error of ErrorValue: 'TError member Equals: Result<'T,'TError> * IEqualityComparer -> bool member IsError: bool member IsOk: bool

val handle: version: Version -> state: 's -> 'e list

module EventStoreWithVersion from 2021-12-17-functional-event-sourcing-decider

union case Result.Ok: ResultValue: 'T -> Result<'T,'TError>

union case Result.Error: ErrorValue: 'TError -> Result<'T,'TError>

val actualVersion: Version

val catchupEvents: 'e list

val actualState: 's

val pastEvents: 'e list

val start: stream: 'a -> decider: Decider<'c,'e,'s> -> ('c -> 'e list)

val mutable versionAndState: Version * 's

val handle: version: Version * state: 's -> 'e list

val newVersion: Version

val tryLoadSnapshot: stream: 'a -> (Version * 's) option

val saveSnapshot: stream: 'a * version: Version * state: 's -> unit

val isTimeToSnapshot: version: 'a -> bool

val version: 'a

val loadState: stream: 'b -> Version * 's

val stream: 'b

val snapVersion: Version

val snapState: 's

module Snapshots from 2021-12-17-functional-event-sourcing-decider

module Option from Microsoft.FSharp.Core

val defaultValue: value: 'T -> option: 'T option -> 'T

val tryLoadSnapshot: stream: 'a * container: 'b -> (Version * 's) option

val container: 'b

val saveSnapshot: stream: 'a * container: 'b * version: Version * state: 's -> unit

val getContainerFromDecideHash: 'a -> 'b

module WithSnapshotsInContainers from 2021-12-17-functional-event-sourcing-decider

val container: obj

module SnapshotsWithContainer from 2021-12-17-functional-event-sourcing-decider

Applicative Computation Expressions - 3

2020-12-03T09:21:51.2547358+00:00

this post is part of the F# Advent Calendar 2020

In this third installment of our series about applicative computation experessions, we'll jump to practice with Lego Mindstorm Ev3. This should demonstrate a non trivial, real life use case for applicatives.

Even if you don't have a mindstorm set at home, follow this post. We'll mix binary protocols and category theory - lightly explained - to provide a nice and safe API.

Mindstorm control over bluetooth

A few years back, I wrote a quick fsx script to control lego mindstorm in F#. I worked again on it recently to port it to net5.0.

Once paired and connected, the brick - the central component of Mindstom used to drive motors and read sensors - appears as a serial port, COM9 on my machine. If you're using a linux system, it should appear as /dev/ttyS9 (or another number).

System.IO.SerialPort is available directly in Net framework, and as a nuget in netcore and net5.0. Add the reference to your project, or use the #r nuget reference in a F# 5.0 script:

#r "nuget: System.IO.Ports"

We will read/write bytes using the SerialPort and ReadOnlyMemory buffers. We'll soon go in more details.

Request/Response

The most interesting part is the Request/Response mechanism used for sensors. We write the request on the serial port by using port.Write, but get the response through an notification of the port.DataReceived event.

The request response is asynchronous, and it would be far easier to present it in the API as an Async construct.

When sending a request, we must include a mandatory sequence number in int. This sequence number will the be transmitted in the corresponding response for correlation.

type Sequence = uint16

We will use this sequence number and a MailboxProcessor to implement Async in a responseDispatcher. It accepts two kinds of messages.

Request contains a Sequence number and a callback to call when the response bytes are available.

Forward contains a Sequence number and corresponding bytes.

open System
open System.Threading
open System.Text
open System.Buffers
open System.Buffers.Binary

type Dispatch =
    | Request of sequence: Sequence * (ReadOnlyMemory<byte> -> unit)
    | Forward of sequence: Sequence * ReadOnlyMemory<byte>

The mailbox processor is using an async rec function to process messages. On a Request message, it adds the callback to a Map under the sequence number key. On a Forward message, it finds the callback corresponding to the sequence number and call it with the data:

let responseDispatcher() =
    MailboxProcessor.Start
    <| fun mailbox ->
        let rec loop requests =
            async {
                let! message = mailbox.Receive()
                let newMap =
                    match message with
                    | Request(sequence, reply) ->
                        Map.add sequence reply requests
                    | Forward(sequence, response) ->
                        match Map.tryFind sequence requests with
                        | Some reply -> 
                            reply response
                            Map.remove sequence requests
                        | None -> requests
                return! loop newMap }
        loop Map.empty

The callback in the Request message is create using PostAndAsyncReply. The result is an Async that is competed when the callback is called.

With this in place we can implement the Brick:

type Brick( name ) =
    // create the port
    let port = new IO.Ports.SerialPort(name,115200)

    // the dispatcher for request/response async
    let dispatcher = responseDispatcher()

    // the mutable sequence number to provide unique numbers 
    let mutable sequence = 0


    member _.Connect() =
        // open the port
        port.Open()
        let reader = new IO.BinaryReader(port.BaseStream)

        // register to receive data notifications
        port.DataReceived |> Event.add (fun e ->
            if e.EventType = IO.Ports.SerialData.Chars then
                //the response start with the size
                let size = reader.ReadInt16()
                let response = reader.ReadBytes(int size)
                // and contains the sequence number as first 2 bytes
                let sequence = BitConverter.ToUInt16(response, 0)
                // we can then send it to the dispatcher
                dispatcher.Post(Forward(sequence, ReadOnlyMemory response))
            ) 

    // gets new sequence number
    member _.GetNextSequence() =
        Interlocked.Increment(&sequence) |> uint16

    // write to the SerialPort
    member _.AsyncWrite (data: ReadOnlyMemory<byte>) = 
        let task = port.BaseStream.WriteAsync(data)
        // check synchronously if the ValueTask is completed
        if task.IsCompleted then
            async.Return ()
        else
            // else fallback on Task
            Async.AwaitTask (task.AsTask())

    // send a request using specified sequence number
    // and await the corresponding response
    member this.AsyncRequest(sequence, data: ReadOnlyMemory<byte>) =
        async {
            do! this.AsyncWrite(data)
            return!  dispatcher.PostAndAsyncReply(fun reply -> Request(sequence, fun response -> reply.Reply(response)))
        }

    interface IDisposable with
        member __.Dispose() = port.Close()

Commands Serialization

Now that we can easily send bytes over the serial port, we need to serialize commands.

the format is :

0 - ushort : bytes size
2 - ushort : sequence number
4 - byte   : command type (direct/system, reply/noreply)
5 - ushort : global size (size of return values)
7 ...      : commands bytes

It is possible to send several commands in a single call.

Command type

The command type is encoded on a single byte. bit 0 indicates whether it's a direct command (activating motors/sensors) or system command (uploading/downloading files). Bit 7 indicates whether we expect a reply. We'll not use system commands in this post.

module CommandType =
    let directReply = 0x00uy
    let directNoReply = 0x80uy
    let systemReply = 0x01uy
    let systemNoReply = 0x81uy

OpCode

The type of command is indicated by a 1 or 2 bytes opcode. Here is an enum of the different opcodes supported by Ev3:

type Opcode =
    | UIRead_GetFirmware = 0x810a
    | UIWrite_LED = 0x821b
    | UIButton_Pressed = 0x8309
    | UIDraw_Update = 0x8400
    | UIDraw_Clean = 0x8401
    | UIDraw_Pixel = 0x8402
    | UIDraw_Line = 0x8403
    | UIDraw_Circle = 0x8404
    | UIDraw_Text = 0x8405
    | UIDraw_FillRect = 0x8409
    | UIDraw_Rect = 0x840a
    | UIDraw_InverseRect = 0x8410
    | UIDraw_SelectFont = 0x8411
    | UIDraw_Topline = 0x8412
    | UIDraw_FillWindow = 0x8413
    | UIDraw_DotLine = 0x8415
    | UIDraw_FillCircle = 0x8418
    | UIDraw_BmpFile = 0x841c
    | Sound_Break = 0x9400
    | Sound_Tone = 0x9401
    | Sound_Play = 0x9402
    | Sound_Repeat = 0x9403
    | Sound_Service = 0x9404
    | InputDevice_GetTypeMode = 0x9905
    | InputDevice_GetDeviceName = 0x9915
    | InputDevice_GetModeName = 0x9916
    | InputDevice_ReadyPct = 0x991b
    | InputDevice_ReadyRaw = 0x991c
    | InputDevice_ReadySI = 0x991d
    | InputDevice_ClearAll = 0x990a
    | InputDevice_ClearChanges = 0x991a
    | InputRead = 0x9a
    | InputReadExt = 0x9e
    | InputReadSI = 0x9d
    | OutputStop = 0xa3
    | OutputPower = 0xa4
    | OutputSpeed = 0xa5
    | OutputStart = 0xa6
    | OutputPolarity = 0xa7
    | OutputReady = 0xaa
    | OutputStepPower = 0xac
    | OutputTimePower = 0xad
    | OutputStepSpeed = 0xae
    | OutputTimeSpeed = 0xaf
    | OutputStepSync = 0xb0
    | OutputTimeSync = 0xb1

and the list of system opcodes (not used)

type SystemOpcode =
    | BeginDownload = 0x92
    | ContinueDownload = 0x93
    | CloseFileHandle = 0x98
    | CreateDirectory = 0x9b
    | DeleteFile = 0x9c

To help with the serialization in a Span we define some inline helpers:

module Buffer =
    let inline write value (buffer: Span<byte>) =
        buffer.[0] <- value
        buffer.Slice(1)

    let inline writeUint16 (value:uint16) (buffer: Span<byte>) =
        BinaryPrimitives.WriteUInt16LittleEndian(buffer, value)
        buffer.Slice(2)

    let inline writeUint16BE (value:uint16) (buffer: Span<byte>) =
        BinaryPrimitives.WriteUInt16BigEndian(buffer, value)
        buffer.Slice(2)

    let inline writeUInt32 (value:uint32) (buffer:Span<byte>) =
        BinaryPrimitives.WriteUInt32LittleEndian(buffer, value)
        buffer.Slice(4)

    let inline writeString (s: string) (buffer: Span<byte>) =
        let len = Encoding.UTF8.GetBytes(s.AsSpan(), buffer)
        buffer.Slice(len)

Each of these functions writes a value at the beginning of the span and slices the appropriate size to return a new span starting just after the value that was just written.

Using this we can write the serializeOpcode function:

let serializeOpcode op buffer =
    if op > enum 0xff then
        // this is a 2 bytes opcode
        // it is serialized in big endian format
        Buffer.writeUint16BE (uint16 op) buffer
    else
        // this is a 1 byte opode
        Buffer.write (byte op) buffer

In order to allocate the buffer, we need to compute the total size. The following functions returns the size for an opcode:

let opcodeLength code =
    if code > enum 0xff then 2 else 1

Parameters

Each opcode is followed by a given number of parameters containing the mandatory values for the operation.

We define a union type to represents different parameter types and their values:

type Parameter =
    | Byte of uint8
    | UShort of uint16
    | UInt of uint32
    | String of string
    | GlobalIndex of uint8

All types are pretty explicit except the last one. GlobalIndex is used to indicate a byte offset in a response data. We'll use it later.

Each argument is composed of a 1 byte prefix indicating it's type/size, followed by the value itself. Here are the different prefixes:

module ParamSize =
    let byte = 0x81uy
    let short = 0x82uy
    let int = 0x83uy
    let string = 0x84uy
    let globalIndex = 0xe1uy

Now we can serialize a parameter and get its length:

let serializeParam p (buffer: Span<byte>) =
    match p with
    | Byte v ->
        let b = Buffer.write ParamSize.byte buffer
        Buffer.write v b
    | UShort v ->
        let b = Buffer.write ParamSize.short buffer
        Buffer.writeUint16 v b
    | UInt v ->
        let b = Buffer.write ParamSize.int buffer
        Buffer.writeUInt32 v b
    | String s ->
        let b = Buffer.write ParamSize.string buffer
        let b =  Buffer.writeString s b
        Buffer.write 0uy b
    | GlobalIndex v -> 
        let b = Buffer.write ParamSize.globalIndex buffer
        Buffer.write v b

let paramLength = function
    | Byte _ | GlobalIndex _ -> 2
    | UShort _ -> 3
    | UInt _ -> 5
    | String l -> Encoding.UTF8.GetByteCount l + 2

So we can define a command as a union:

type Command =
    | Direct of Opcode * Parameter list
    // we will not model SystemCommand here
    // | SystemCommand of SystemOpcode * Parameter list

Computing the size of a command is fairly straightforward:

let length =
    function
    | Direct(code, parameters) ->
        opcodeLength code + List.sumBy paramLength parameters

The serialization is a bit more complicated if we want to loop on parameters using a recursive function. The reason is that F# doesn't currently support Span<T> -> Span<T> function parameters. This signature is used by our serializers that take a Span, write at the beginning an returns a shorter span starting after written bytes. To workaround this problem we have to use a plain delegate:

type Serializer<'t> = delegate of 't * Span<byte> -> Span<byte>

let rec serializeAll (f: 't Serializer) (ps: 't list) (b: Span<byte>) =
    match ps with
    | [] -> b
    | p :: t ->
        let b' = f.Invoke(p, b)
        serializeAll f t b'

The serializeAll function takes a Serializer, a list of values and a buffer. It serializes all elements in the list using the serializer and returns a span that starts just after the bytes we just wrote.

We use it to implement serializeCommand:

let serializeCommand command (buffer: Span<byte>) =
    match command with
    | Direct (op, p) ->
        let b = serializeOpcode op buffer
        serializeAll (Serializer serializeParam) p b

Putting it all together

We can now proceed to the serialize function that allocates memory from the MemoryPool, writes each part using the functions we defined above, and returns a memory owner. The memory owner has to be disposed to return the memory to the pool.

It takes a command list and serialize all the commands using serializeAll:

let serialize sequence commandType globalSize commands =
    let length = 5 + List.sumBy length commands // there is a 5 bytes header
    let rental = MemoryPool.Shared.Rent(length+2) // plus the 2 bytes for size
    let mem = rental.Memory.Slice(0,length+2)
    

    let buffer = mem.Span
    let b = Buffer.writeUint16 (uint16 length) buffer // 2 bytes size
    let b = Buffer.writeUint16 sequence b   // 2 bytes sequence number
    let b = Buffer.write commandType b      // 1 byte command type
    let b = Buffer.writeUint16 globalSize b // 2 bytes globalSize of response
    let _ = serializeAll (Serializer serializeCommand) commands b // commands bytes
    { new IMemoryOwner<byte> with 
        member _.Memory = mem
        member _.Dispose() = rental.Dispose() }

And we write a send function that takes a list of commands, serialize them and sends the result to the brick:

let send commands =
    fun (brick: Brick) ->
        async {
            // generates a sequence number
            let sequence = brick.GetNextSequence()
            // serialize the commands in a Memory buffer
            // (that will be disposed at the end of the call)
            use memory =
                commands
                |> serialize sequence CommandType.directNoReply 0us
      
            // send it to the brick
            do! brick.AsyncWrite(Memory.op_Implicit memory.Memory)
        }

Defining commands

We're now ready to define commands in a more friendly way.

For instance the startMotor command can be called with a list of output ports (the ones on the top of the brick calls A, B, C and D):

type OutputPort =
    | A 
    | B
    | C
    | D

Ports are encoded as a Byte parameter with bit 0 set for A, 1 for B, 2 for C, and 3 for D:

let port p =
    p
    |> List.fold (fun v p ->
        v ||| match p with
              | A -> 0x01uy
              | B -> 0x02uy
              | C -> 0x04uy
              | D -> 0x08uy) 0uy
    |> Byte

startMotor is using the OutputStart opcode followed by two parameters: a 0 byte , and a port byte.

let startMotor ports =
    Direct(Opcode.OutputStart,
            [Byte 0uy; port ports])

stopMotor is using the OutputStop opcode followed by the same parameters, and an extra Break value encoded as a 0 or 1 byte:

type Brake =
    | Brake
    | NoBrake
    with
    static member toByte b =
        match b with
        | Brake -> 0x01uy
        | NoBrake -> 0x00uy
        |> Byte 

let stopMotor ports brake = 
    Direct(Opcode.OutputStop, 
            [Byte 0uy; port ports; Brake.toByte brake ])

Here are a few more commands:

type Power = Power of uint8
let power p =
    if p < -100 || p > 100 then
        invalidArg "p" "Power should be between -100 and 100"
    Power (uint8 p)

/// wait for the end of previous command
let outputReady ports =
    Direct(Opcode.OutputReady,
            [ Byte 0uy; port ports;])

let turnMotorAtPower ports (Power power) =
    Direct(Opcode.OutputPower,
            [Byte 0uy; port ports; Byte power])

let turnMotorAtSpeedForTime' ports speed msRampUp msConstant msRampDown brake =
    Direct(Opcode.OutputTimeSpeed,
            [Byte 0uy
             port ports
             Byte (byte speed)
             UInt msRampUp
             UInt msConstant
             UInt msRampDown
             Brake.toByte brake])

let turnMotorAtSpeedForTime ports speed msDuration brake =
    turnMotorAtSpeedForTime' ports speed 0u msDuration 0u brake

// yes, you can also play music :)
let playTone volume frequency duration =
    Direct(Opcode.Sound_Tone,
        [Byte volume
         UShort frequency
         UShort duration ])

You can try to put a few commands in the list and send them to the brick. It should work.

Computation Expression

To make it better, we continue with a lego computation expression that builds a full program taking commands and async local computations.

It is used to compose functions that takes a Brick and return an async:

type Lego<'a> = Brick -> Async<'a>

This is a classic Computation expression (not an applicative).

type LegoBuilder() =

The Bind method takes a Lego<'a> and a function that takes a 'a as an input to return a Lego<'b>. The result should be a Lego<'b>, so we write a lambda that takes a Brick.

We pass this brick to x, to get an Async<'a>, we pass the value from this async to f using async.Bind.

    member __.Bind(x : Lego<'a>, f : 'a -> Lego<'b> ) : Lego<'b> = 
        fun brick ->
            async.Bind(x brick, fun v -> f v brick)

This overload does quite the same but directly takes a Command list and send it

    member __.Bind(command : Command list, f : unit -> Lego<'b> ) : Lego<'b> = 
        fun brick ->
            async.Bind(send command brick, fun () -> f () brick)

Same thing for a single command

    member __.Bind(command : Command, f : unit -> Lego<'b> ) : Lego<'b> = 
        fun brick ->
            async.Bind(send [command] brick, fun () -> f () brick)

We can also do it for simple Async<'a> (for instance Async.Sleep(1000)). In this case we just bind it directly.

    member __.Bind(x : Async<'a>, f : 'a -> Lego<'b> ) : Lego<'b> = 
        fun brick ->
            async.Bind(x, fun v -> f v brick)

Return creates a Lego<'a> from a value. It just takes a brick that it will not use and returns an Async with the value.

    member __.Return x : Lego<'a> = fun _ -> async.Return x

Other methods implement return!, for, combination sequenced calls, etc.

    // needed for return!
    member __.ReturnFrom x = x 

    // needed for for .. in .. do expressions
    member __.For<'T>(values : 'T seq, body: 'T -> Lego<unit>) = 
        fun brick ->
            async.For(values, fun t -> body t brick)

    // needed to have several do! combined
    member __.Combine(x, y) : Lego<'a>=
        fun ctx ->
            async.Combine(x ctx, y ctx)
    
    member __.Delay(f: unit -> Lego<'a>) =
        fun ctx ->
            async.Delay(fun () -> f () ctx)

    // needed for if without else
    member __.Zero() = fun ctx -> async.Zero()

    // needed for use
    member __.Using(d, f) = fun ctx ->
        async.Using(d, f ctx)

The run functions takes a Lego function, starts it asynchronously and returns a cancellation token to stop it.

let run brick (f: Lego<unit>) = 
    let cancelToken = new CancellationTokenSource()
    Async.Start(f brick, cancelToken.Token)
    cancelToken

The runSynchronously functions takes a Lego<'a> function, and runs it synchronously

let runSynchronously brick (f: Lego<'a>) = 
    Async.RunSynchronously(f brick)

We choose lego for our Computation Expression name

let lego = LegoBuilder()

Let's play

Here is a sample that connects to COM9 and repeat 3 times a batch of commands to turn motor in port A in one direction for 1 second, then in the other direction for another second. It stops motors once done.

let sample() =
    use brick = new Brick("COM9")
    brick.Connect()

    lego {
            for i in 0..3 do
               do! [ turnMotorAtSpeedForTime [A] 50 1000u NoBrake
                     outputReady [A]
                     turnMotorAtSpeedForTime [A] -50 1000u NoBrake
                     outputReady [A] ] 
            do! stopMotor [A] NoBrake }
            |> runSynchronously brick

Sensors

The Ev3 comes with 3 default sensors, Color, Touch and IR. Extra gyroscopic and ultrasound sensors can be acquired separately.

Sensors are connected to input ports (1 to 4). Motor ports (A to D) can also be read to get the rotation of the motors:

type InputPort =
    | In1
    | In2
    | In3
    | In4
    | InA
    | InB
    | InC
    | InD

/// gets the binary code for an input port
let inputPort = function 
                | In1 -> 0x00uy
                | In2 -> 0x01uy 
                | In3 -> 0x02uy
                | In4 -> 0x03uy
                | InA -> 0x10uy
                | InB -> 0x11uy
                | InC -> 0x12uy 
                | InD -> 0x13uy
                >> Byte

Sensors can return different values

Color, ambient light, reflected light for the color sensor
Touch can return pressed/released state or bumps
IR can return proximity, and remote buttons state...

each of this mode correspond to a 1 byte value

type Mode =
    | TouchMode of TouchMode
    | ColorMode of ColorMode
    | IRMode of IRMode
and TouchMode = Touch | Bumps
and ColorMode = Reflective | Ambient | Color | ReflectiveRaw | ReflectiveRgb | Calibration
and IRMode = Proximity | Seek | Remote | RemoteA | SAlt | Calibrate

let modeToUInt8 = function
    | TouchMode Touch -> 0uy
    | TouchMode Bumps -> 1uy   
    | ColorMode Reflective -> 0uy
    | ColorMode Ambient -> 1uy
    | ColorMode Color -> 2uy
    | ColorMode ReflectiveRaw -> 3uy
    | ColorMode ReflectiveRgb -> 4uy
    | ColorMode Calibration -> 5uy
    | IRMode Proximity -> 0uy
    | IRMode Seek -> 1uy
    | IRMode Remote -> 2uy
    | IRMode RemoteA -> 3uy
    | IRMode SAlt -> 4uy
    | IRMode Calibrate -> 5uy

Different units are used depending on the sensor value:

type ReadDataType =
    | SI            // a 4 bytes single (floating) value
    | Raw           // a 4 bytes integer
    | Percent       // a 1 byte percent
    | RGB           // 3 2 bytes integers

/// gets the byte length for each data type
let readDataTypeLen = function
    | ReadDataType.SI -> 4
    | ReadDataType.Raw -> 4
    | ReadDataType.Percent -> 1
    | ReadDataType.RGB -> 6

Read command

Each of the datatypes corresponds to a different read opcode:

let readOpcode = function
    | ReadDataType.SI -> Opcode.InputDevice_ReadySI
    | ReadDataType.Raw -> Opcode.InputDevice_ReadyRaw
    | ReadDataType.RGB -> Opcode.InputDevice_ReadyRaw // rgb is a specific Raw read
    | ReadDataType.Percent -> Opcode.InputDevice_ReadyPct

With this opcode we can create a read command as we did previously. The position parameter is the position of the corresponding value in the response bytes.

let readCommand (inPort, dataType, mode) position =
    Direct(readOpcode dataType ,
            [Byte 0uy
             inputPort inPort
             Byte 0uy
             Byte (modeToUInt8 mode)
             Byte 1uy
             GlobalIndex (uint8 position)])

For a single sensor request, it's easy, just pass 0 for position, and read the value at the start of the response.

The send function defined before was not waiting for a response. We create a request function the same way, but asks for a reply and use AsyncRequest to get a response. It checks the reply type (a byte just after response length).

type ReplyType =
| DirectReply = 0x02
| SystemReply = 0x03
| DirectReplyError = 0x04
| SystemReplyError = 0x05

let request commands globalSize =
    fun (brick: Brick) ->
        async {
            let sequence = brick.GetNextSequence()
            use data =
                commands
                |> serialize sequence CommandType.directReply globalSize

            let! response = brick.AsyncRequest(sequence, Memory.op_Implicit data.Memory)
            let replyType = enum<ReplyType> (int response.Span.[2])
            if replyType = ReplyType.DirectReplyError || replyType = ReplyType.SystemReplyError then
                failwith "An error occurred"
            return response
        }

To query multiple sensors at once, we can create multiple read commands with different positions, and send them in a single batch. It avoids multiple roundtrip through bluetooth which can be expensive. The problem is that setting response value position can be error prone.

With the readDataTypeLen we can know the size of the value, and accumulate them to compute the offset. A readLength function that extracts the length from the triplet will make our life easier:

let readLength (_,dataType,_) = readDataTypeLen dataType

We accumulate the sizes as offsets using a mapFold. The accumulator in mapFold takes a state (the offset) and an input (the sensor parameters), and outputs a value (the command built using the offset) and a new state (the new offset computed by adding the value length).

This way we get a list of command with the rights offsets as well as the total length passed as globalSize.

To interpret the result, we use mapFold again. Now the state is a ReadOnlyMemory<byte> starting at the 3rd byte (to skip the size and response status, the reason for the Slice(3)). For each item, we compute its length. The item is a pair of the sensors parameter and a slice containing the value. The state is sliced to skip the bytes from current value and start at the next one.

We combine it with a call to request to have this function that takes a brick and a list of sensor parameters and returns a map of sensor parameters and their value as a ReadOnlyMemory<byte>.

let readAux brick inputs =
    async {
        if List.isEmpty inputs then
            return Map.empty
        else
            let commands, globalSize =
                inputs
                |> List.mapFold (fun offset input -> 
                    readCommand input offset, (offset + readLength input)
                    ) 
                    0

            let! data = 
                request commands (uint16 globalSize) brick

            let sensorsData = data.Slice(3)
            let response =
                inputs
                |> List.mapFold (fun (data: ReadOnlyMemory<byte>) input ->
                    let length = readLength input 
                    (input, data.Slice(0, length)),
                    data.Slice(length))
                    sensorsData
                        
                            
                |> fst
                |> Map.ofList
            return response
        }

Applicative

We solved the problem of values offsets, but a few challenge remain. First the result is still in the form of a ReadOnlyMemory<byte>, and we should be careful to read it accordingly to the requested data. Then we have to be sure we don't try to look for values in the result that we did not request.

If you've read previous posts already, you'll recognize the Query<'t> applicative. Here we will create a Sensor<'t> type:

type InputRequest = InputPort * ReadDataType * Mode

type Sensor<'t> =
    { Inputs: InputRequest Set 
      Get: Map<InputRequest, ReadOnlyMemory<byte>> -> 't }

It contains a set of inputs to request, and a function to extract a value of type 't from the result of our readAux function.

For instance the simplest way to create a sensor from an input:

let input (req: InputRequest) =
    { Inputs = Set.singleton req 
      Get = fun m -> m.[req] }

It indicates that it should request the given input and gets it from the map. The result will be a ReadOnlyMemory<byte>.

Creating a read functions that takes a Sensor<'t> and calls readAux is straightforward:

let read (sensor: Sensor<'t>)  =
    fun brick ->
        async {
            let inputs = Set.toList sensor.Inputs 
            // gets the Map response for requested inputs
            let! response = readAux brick inputs 
            // use the sensor.Get to extract value from response
            return sensor.Get response
        }

Using a Sensor<'t> and read, no way to get it wrong.

Now we want to create more complex sensors by combining simple ones.

Ret

We can create a pure sensor, a sensor that request no inputs and return a given value:

let ret x =
    { Inputs = Set.empty 
      Get = fun _ -> x }

It will be useful later.

Map

We can define a map operation on it (yes, it's a functor). It takes a 'a -> 'b functions and changes a Sensor<'a> to a Sensor<'b>:

let map (f: 'a -> 'b) (s: Sensor<'a>) : Sensor<'b> =
    { Inputs = s.Inputs 
      Get = fun m -> s.Get m |> f }

It requests the same inputs at the given sensor, gets its value and pass it to f.

Map2

More interesting, we can define a map2 that takes to sensors, and pass their values to a function to compute a single result. This result will also be a sensor that request for inputs of both, and combine their results using f:

let map2 f sx sy =
    { Inputs = sx.Inputs + sy.Inputs  // union of inputs
      Get = fun m ->
        let x = sx.Get m    // get value for sensor sx
        let y = sy.Get m    // get value for sensor sy
        f x y }             // combine the values using f

We can use map2 to zip sensors. It takes to sensors and create a single sensor that contains both values as a tuple:

let zip sx sy = map2 (fun x y -> x,y) sx sy

Apply

The problem with map2, is that it works only with 2 sensors. For 3 sensors we would have to create a map3. And a map4, map5 etc.

But in F#, every function is a function of 1 argument due to currying. A function of type int -> bool -> string can be used as a int -> (bool -> string), it takes a single int argument and returns a function that takes a bool and returns a string.

Passing this function to map with a sensor of type Sensor<int>, we get a Sensor<bool -> string>. The meaning of this signature can seem obscure at first. It says that if you give this to the read function above, it will make a request and use the response values to build a bool -> string result. if you pass a bool to this result, you get a string.

But we would like the bool to also be read from a sensor. So we have a Sensor<bool -> string> and a Sensor<bool>. We can obviously use map2 on this pair of sensors. map2 will pass the values of the sensors to the function passed as an argument. The first argument of this function will be a bool -> string, the second a bool. We can pass the bool value to the bool -> string function to get a string. The result will be a Sensor<string>.

I used specific types to make it simpler by it works for any type:

let apply (sf: Sensor<'a -> 'b>) (sx: Sensor<'a>) : Sensor<'b> =
    map2 (fun f x -> f x) sf sx

Typed basic sensors

For a given data type, the conversion should always be the same. We create a function for each data type.

Each of the inputXXX functions take a port and a mode are returns a typed sensor.

let typedInput dataType convert =
    fun port mode ->
        input (port, dataType, mode) |> map convert

        
let inputSi = typedInput ReadDataType.SI (fun data -> BitConverter.ToSingle(data.Span))
let inputRaw = typedInput ReadDataType.Raw (fun data -> BitConverter.ToInt32(data.Span))
let inputPct = typedInput ReadDataType.Percent (fun data -> int data.Span.[0])
let inputRgb = typedInput ReadDataType.RGB (fun data -> 
    let span = data.Span
    let r = BitConverter.ToUInt16(span)
    let g = BitConverter.ToUInt16(span.Slice(2))
    let b = BitConverter.ToUInt16(span.Slice(4))
    int r, int g, int b
    )

Using this functions we define more interesting sensors

// the state of the touch sensor
type ButtonState =
    | Pushed
    | Released

// the colors of the color sensor
type Color =
    | Transparent
    | Black
    | Blue
    | Green
    | Yellow
    | Red
    | White
    | Brown

module Sensors =
    module Color =
        let reflective port = inputPct port (ColorMode ColorMode.Reflective)
        let ambient port = inputPct port (ColorMode ColorMode.Ambient)

        // here we use the SI single result
        // and map it to a Color
        let color port =
            inputSi port (ColorMode ColorMode.Color)
            |> map (function
                    | 1.f -> Black
                    | 2.f -> Blue
                    | 3.f -> Green
                    | 4.f -> Yellow
                    | 5.f -> Red
                    | 6.f -> White
                    | 7.f -> Brown
                    | _ -> Transparent)
        module Raw =
            let reflective port = inputRaw port (ColorMode ColorMode.ReflectiveRaw)
            // this one use a RGB type, the result is read as a RGB triplet
            let rgb port = inputRgb port (ColorMode ColorMode.ReflectiveRgb)


    module IR =
        let proximity port = inputPct port (IRMode Proximity)

    module Touch =
        // the SI single result is mapped to Pushed/Released
        let button port = 
            inputSi port (TouchMode Touch)
            |> map (function 1.f -> Pushed | _ -> Released)

Operators

Prior to F# 5.0 it is not possible to implement applicatives with computation expressions. Instead we can define <!> for map and <*> for apply to get infix syntax.

<!> takes a function on a left and a sensor on the right. We get a sensor with the argument applied. If it was a simple 1 argument function, we get a sensor of the result:

let (<!>) = map
let (<*>) = apply


let isRed port : Sensor<bool> =
    (fun c -> c = Red) 
    <!> Sensors.Color.color port

If the function take several parameters, we get a sensor of a function as a result. We can use it with <*>, the operator for apply:

let colorAndProximityIfPushed : Sensor<(Color * int) option> =
    (fun color proximity button ->
        match button with
        | Pushed -> Some (color, proximity)
        | Released -> None)
    <!> Sensors.Color.color In1
    <*> Sensors.IR.proximity In2
    <*> Sensors.Touch.button In3

This is a composite sensor that gets the state from the Touch sensor in input 3, color from Color sensor in input 1, and proximity from IR sensor on input 2. It returns None when the button is released, and Some(color, proximity) when the button is pushed.

Sensor Computation Expression

With F# 5.0 we can replace these operators by a computation expression.

We create a builder type as usual but implement BindReturn as map (with arguments swapped), and MergeSources as zip.

We can also provide a Bind2Return for the 2 parameter cases as map2.

The Return is implemented using ret, the pure value sensor:

type SensorBuilder() =
    member _.BindReturn(x: 'a Sensor,f : 'a -> 'b) : 'b Sensor = map f x

    member _.MergeSources(x: 'a Sensor, y: 'b Sensor) : ('a * 'b) Sensor = zip x y

    member _.Bind2Return(x: 'a Sensor,y: 'b Sensor,f : 'a*'b -> 'c) : 'c Sensor = 
        map2 (fun x y -> f(x,y)) x y

    member _.Return x = ret x

let sensor = SensorBuilder()

Let's rewrite colorAndProximityIfPushed sensor with this computation expression:

let colorWhenPushed =
    sensor {
        let! color = Sensors.Color.color In1
        and! proximity = Sensors.IR.proximity In2
        and! button = Sensors.Touch.button In3

        return match button with
               | Pushed -> Some (color, proximity)
               | Released -> None
    }

Notice the usage of and! to combine all the sensors together.

We put it all together in a final sample:

let sample2() =
    use brick = new Brick("COM9")
    brick.Connect()

    lego {

        for i in 0 .. 100 do
            let! value = read (
                            sensor {
                                let! color = Sensors.Color.Raw.rgb In1
                                and! b = Sensors.Touch.button In2
                                and! prox = Sensors.IR.proximity In3

                                match b with
                                | Pushed -> return Some (color,prox)
                                | Released -> return None
                                    }
                                )
            printfn "%A" value

    } |> runSynchronously brick

Take your time to extend it to send any command and combine any sensors in a friendly and readable way.

The applicative computation expression for sensors provide a safe API over an error prone low level protocol. The syntax of computation expressions is also less obscure to newcomers than the <!> and <*> operators that can be a bit hard to explain.

Now you know what to ask Santa for Xmas ! Happy Xmas !

type Sequence = uint16

Multiple items
val uint16: value: 'T -> uint16 (requires member op_Explicit)

--------------------
type uint16 = System.UInt16

--------------------
type uint16<'Measure> = uint16

namespace System

namespace System.Threading

namespace System.Text

namespace System.Buffers

namespace System.Buffers.Binary

type Dispatch = | Request of sequence: Sequence * (ReadOnlyMemory<byte> -> unit) | Forward of sequence: Sequence * ReadOnlyMemory<byte>

Multiple items
[<Struct>] type ReadOnlyMemory<'T> = new: array: 'T array -> unit + 1 overload member CopyTo: destination: Memory<'T> -> unit member Equals: obj: obj -> bool + 1 overload member GetHashCode: unit -> int member Pin: unit -> MemoryHandle member Slice: start: int -> ReadOnlyMemory<'T> + 1 overload member ToArray: unit -> 'T array member ToString: unit -> string member TryCopyTo: destination: Memory<'T> -> bool static member op_Implicit: segment: ArraySegment<'T> -> ReadOnlyMemory<'T> + 1 overload ...
<summary>Represents a contiguous region of memory, similar to <see cref="T:System.ReadOnlySpan`1" />. Unlike <see cref="T:System.ReadOnlySpan`1" />, it is not a byref-like type.</summary>
<typeparam name="T">The object type from which the contiguous region of memory will be read.</typeparam>

--------------------
ReadOnlyMemory ()
ReadOnlyMemory(array: 'T array) : ReadOnlyMemory<'T>
ReadOnlyMemory(array: 'T array, start: int, length: int) : ReadOnlyMemory<'T>

Multiple items
val byte: value: 'T -> byte (requires member op_Explicit)

--------------------
type byte = Byte

--------------------
type byte<'Measure> = byte

type unit = Unit

val responseDispatcher: unit -> MailboxProcessor<Dispatch>

Multiple items
type MailboxProcessor<'Msg> = interface IDisposable new: body: (MailboxProcessor<'Msg> -> Async<unit>) * ?cancellationToken: CancellationToken -> MailboxProcessor<'Msg> + 1 overload member Dispose: unit -> unit member Post: message: 'Msg -> unit member PostAndAsyncReply: buildMessage: (AsyncReplyChannel<'Reply> -> 'Msg) * ?timeout: int -> Async<'Reply> member PostAndReply: buildMessage: (AsyncReplyChannel<'Reply> -> 'Msg) * ?timeout: int -> 'Reply member PostAndTryAsyncReply: buildMessage: (AsyncReplyChannel<'Reply> -> 'Msg) * ?timeout: int -> Async<'Reply option> member Receive: ?timeout: int -> Async<'Msg> member Scan: scanner: ('Msg -> Async<'T> option) * ?timeout: int -> Async<'T> member TryPostAndReply: buildMessage: (AsyncReplyChannel<'Reply> -> 'Msg) * ?timeout: int -> 'Reply option ...

--------------------
new: body: (MailboxProcessor<'Msg> -> Async<unit>) * ?cancellationToken: CancellationToken -> MailboxProcessor<'Msg>
new: body: (MailboxProcessor<'Msg> -> Async<unit>) * isThrowExceptionAfterDisposed: bool * ?cancellationToken: CancellationToken -> MailboxProcessor<'Msg>

static member MailboxProcessor.Start: body: (MailboxProcessor<'Msg> -> Async<unit>) * ?cancellationToken: CancellationToken -> MailboxProcessor<'Msg>
static member MailboxProcessor.Start: body: (MailboxProcessor<'Msg> -> Async<unit>) * isThrowExceptionAfterDisposed: bool * ?cancellationToken: CancellationToken -> MailboxProcessor<'Msg>

val mailbox: MailboxProcessor<Dispatch>

val loop: requests: Map<Sequence,(ReadOnlyMemory<byte> -> unit)> -> Async<'a>

val requests: Map<Sequence,(ReadOnlyMemory<byte> -> unit)>

val async: AsyncBuilder

val message: Dispatch

member MailboxProcessor.Receive: ?timeout: int -> Async<'Msg>

val newMap: Map<Sequence,(ReadOnlyMemory<byte> -> unit)>

union case Dispatch.Request: sequence: Sequence * (ReadOnlyMemory<byte> -> unit) -> Dispatch

val sequence: Sequence

val reply: (ReadOnlyMemory<byte> -> unit)

Multiple items
module Map from Microsoft.FSharp.Collections

--------------------
type Map<'Key,'Value (requires comparison)> = interface IReadOnlyDictionary<'Key,'Value> interface IReadOnlyCollection<KeyValuePair<'Key,'Value>> interface IEnumerable interface IStructuralEquatable interface IComparable interface IEnumerable<KeyValuePair<'Key,'Value>> interface ICollection<KeyValuePair<'Key,'Value>> interface IDictionary<'Key,'Value> new: elements: ('Key * 'Value) seq -> Map<'Key,'Value> member Add: key: 'Key * value: 'Value -> Map<'Key,'Value> ...

--------------------
new: elements: ('Key * 'Value) seq -> Map<'Key,'Value>

val add: key: 'Key -> value: 'T -> table: Map<'Key,'T> -> Map<'Key,'T> (requires comparison)

union case Dispatch.Forward: sequence: Sequence * ReadOnlyMemory<byte> -> Dispatch

val response: ReadOnlyMemory<byte>

val tryFind: key: 'Key -> table: Map<'Key,'T> -> 'T option (requires comparison)

union case Option.Some: Value: 'T -> Option<'T>

val remove: key: 'Key -> table: Map<'Key,'T> -> Map<'Key,'T> (requires comparison)

union case Option.None: Option<'T>

val empty<'Key,'T (requires comparison)> : Map<'Key,'T> (requires comparison)

Multiple items
type Brick = interface IDisposable new: name: string -> Brick member AsyncRequest: sequence: Sequence * data: ReadOnlyMemory<byte> -> Async<ReadOnlyMemory<byte>> member AsyncWrite: data: ReadOnlyMemory<byte> -> Async<unit> member Connect: unit -> unit member GetNextSequence: unit -> uint16

--------------------
new: name: string -> Brick

val name: string

val port: IO.Ports.SerialPort

namespace System.IO

namespace System.IO.Ports

Multiple items
type SerialPort = inherit Component new: unit -> unit + 6 overloads member Close: unit -> unit member DiscardInBuffer: unit -> unit member DiscardOutBuffer: unit -> unit member Open: unit -> unit member Read: buffer: byte array * offset: int * count: int -> int + 1 overload member ReadByte: unit -> int member ReadChar: unit -> int member ReadExisting: unit -> string ...

--------------------
IO.Ports.SerialPort() : IO.Ports.SerialPort
IO.Ports.SerialPort(container: ComponentModel.IContainer) : IO.Ports.SerialPort
IO.Ports.SerialPort(portName: string) : IO.Ports.SerialPort
IO.Ports.SerialPort(portName: string, baudRate: int) : IO.Ports.SerialPort
IO.Ports.SerialPort(portName: string, baudRate: int, parity: IO.Ports.Parity) : IO.Ports.SerialPort
IO.Ports.SerialPort(portName: string, baudRate: int, parity: IO.Ports.Parity, dataBits: int) : IO.Ports.SerialPort
IO.Ports.SerialPort(portName: string, baudRate: int, parity: IO.Ports.Parity, dataBits: int, stopBits: IO.Ports.StopBits) : IO.Ports.SerialPort

val dispatcher: MailboxProcessor<Dispatch>

val mutable sequence: int

IO.Ports.SerialPort.Open() : unit

val reader: IO.BinaryReader

Multiple items
type BinaryReader = interface IDisposable new: input: Stream -> unit + 2 overloads member Close: unit -> unit member Dispose: unit -> unit member PeekChar: unit -> int member Read: unit -> int + 4 overloads member Read7BitEncodedInt: unit -> int member Read7BitEncodedInt64: unit -> int64 member ReadBoolean: unit -> bool member ReadByte: unit -> byte ...
<summary>Reads primitive data types as binary values in a specific encoding.</summary>

--------------------
IO.BinaryReader(input: IO.Stream) : IO.BinaryReader
IO.BinaryReader(input: IO.Stream, encoding: Encoding) : IO.BinaryReader
IO.BinaryReader(input: IO.Stream, encoding: Encoding, leaveOpen: bool) : IO.BinaryReader

property IO.Ports.SerialPort.BaseStream: IO.Stream with get

event IO.Ports.SerialPort.DataReceived: IEvent<IO.Ports.SerialDataReceivedEventHandler,IO.Ports.SerialDataReceivedEventArgs>

Multiple items
module Event from Microsoft.FSharp.Control

--------------------
type Event<'T> = new: unit -> Event<'T> member Trigger: arg: 'T -> unit member Publish: IEvent<'T>

--------------------
type Event<'Delegate,'Args (requires delegate and 'Delegate :> Delegate and reference type)> = new: unit -> Event<'Delegate,'Args> member Trigger: sender: objnull * args: 'Args -> unit member Publish: IEvent<'Delegate,'Args>

--------------------
new: unit -> Event<'T>

--------------------
new: unit -> Event<'Delegate,'Args>

val add: callback: ('T -> unit) -> sourceEvent: IEvent<'Del,'T> -> unit (requires delegate and 'Del :> Delegate)

val e: IO.Ports.SerialDataReceivedEventArgs

property IO.Ports.SerialDataReceivedEventArgs.EventType: IO.Ports.SerialData with get

[<Struct>] type SerialData = | Chars = 1 | Eof = 2

field IO.Ports.SerialData.Chars: IO.Ports.SerialData = 1

val size: int16

IO.BinaryReader.ReadInt16() : int16

val response: byte array

IO.BinaryReader.ReadBytes(count: int) : byte array

Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int

val sequence: uint16

type BitConverter = static member DoubleToInt64Bits: value: float -> int64 static member DoubleToUInt64Bits: value: float -> uint64 static member GetBytes: value: bool -> byte array + 12 overloads static member HalfToInt16Bits: value: Half -> int16 static member HalfToUInt16Bits: value: Half -> uint16 static member Int16BitsToHalf: value: int16 -> Half static member Int32BitsToSingle: value: int -> float32 static member Int64BitsToDouble: value: int64 -> float static member SingleToInt32Bits: value: float32 -> int static member SingleToUInt32Bits: value: float32 -> uint32 ...
<summary>Converts base data types to an array of bytes, and an array of bytes to base data types.</summary>

BitConverter.ToUInt16(value: ReadOnlySpan<byte>) : uint16
BitConverter.ToUInt16(value: byte array, startIndex: int) : uint16

member MailboxProcessor.Post: message: 'Msg -> unit

type Interlocked = static member Add: location1: byref<int> * value: int -> int + 3 overloads static member And: location1: byref<int> * value: int -> int + 3 overloads static member CompareExchange: location1: byref<float> * value: float * comparand: float -> float + 13 overloads static member Decrement: location: byref<int> -> int + 3 overloads static member Exchange: location1: byref<float> * value: float -> float + 13 overloads static member Increment: location: byref<int> -> int + 3 overloads static member MemoryBarrier: unit -> unit static member MemoryBarrierProcessWide: unit -> unit static member Or: location1: byref<int> * value: int -> int + 3 overloads static member Read: location: byref<int64> -> int64 + 1 overload
<summary>Provides atomic operations for variables that are shared by multiple threads.</summary>

Interlocked.Increment(location: byref<uint64>) : uint64
Interlocked.Increment(location: byref<uint32>) : uint32
Interlocked.Increment(location: byref<int64>) : int64
Interlocked.Increment(location: byref<int>) : int

Multiple items
val uint16: value: 'T -> uint16 (requires member op_Explicit)

--------------------
type uint16 = UInt16

--------------------
type uint16<'Measure> = uint16

val data: ReadOnlyMemory<byte>

val task: Tasks.ValueTask

IO.Stream.WriteAsync(buffer: ReadOnlyMemory<byte>, ?cancellationToken: CancellationToken) : Tasks.ValueTask
IO.Stream.WriteAsync(buffer: byte array, offset: int, count: int) : Tasks.Task
IO.Stream.WriteAsync(buffer: byte array, offset: int, count: int, cancellationToken: CancellationToken) : Tasks.Task

property Tasks.ValueTask.IsCompleted: bool with get
<summary>Gets a value that indicates whether this object represents a completed operation.</summary>
<returns><see langword="true" /> if this object represents a completed operation; otherwise, <see langword="false" />.</returns>

member AsyncBuilder.Return: value: 'T -> Async<'T>

Multiple items
type Async = static member AsBeginEnd: computation: ('Arg -> Async<'T>) -> ('Arg * AsyncCallback * objnull -> IAsyncResult) * (IAsyncResult -> 'T) * (IAsyncResult -> unit) static member AwaitEvent: event: IEvent<'Del,'T> * ?cancelAction: (unit -> unit) -> Async<'T> (requires delegate and 'Del :> Delegate) static member AwaitIAsyncResult: iar: IAsyncResult * ?millisecondsTimeout: int -> Async<bool> static member AwaitTask: task: Task<'T> -> Async<'T> + 1 overload static member AwaitWaitHandle: waitHandle: WaitHandle * ?millisecondsTimeout: int -> Async<bool> static member CancelDefaultToken: unit -> unit static member Catch: computation: Async<'T> -> Async<Choice<'T,exn>> static member Choice: computations: Async<'T option> seq -> Async<'T option> static member FromBeginEnd: beginAction: (AsyncCallback * objnull -> IAsyncResult) * endAction: (IAsyncResult -> 'T) * ?cancelAction: (unit -> unit) -> Async<'T> + 3 overloads static member FromContinuations: callback: (('T -> unit) * (exn -> unit) * (OperationCanceledException -> unit) -> unit) -> Async<'T> ...

--------------------
type Async<'T>

static member Async.AwaitTask: task: Tasks.Task -> Async<unit>
static member Async.AwaitTask: task: Tasks.Task<'T> -> Async<'T>

Tasks.ValueTask.AsTask() : Tasks.Task

val this: Brick

member Brick.AsyncWrite: data: ReadOnlyMemory<byte> -> Async<unit>

member MailboxProcessor.PostAndAsyncReply: buildMessage: (AsyncReplyChannel<'Reply> -> 'Msg) * ?timeout: int -> Async<'Reply>

val reply: AsyncReplyChannel<ReadOnlyMemory<byte>>

member AsyncReplyChannel.Reply: value: 'Reply -> unit

type IDisposable = override Dispose: unit -> unit
<summary>Provides a mechanism for releasing unmanaged resources.</summary>

IO.Ports.SerialPort.Close() : unit

Multiple items
val byte: value: 'T -> byte (requires member op_Explicit)

--------------------
type byte = System.Byte

--------------------
type byte<'Measure> = byte

val directReply: byte

val directNoReply: byte

val systemReply: byte

val systemNoReply: byte

type Buffer = static member BlockCopy: src: Array * srcOffset: int * dst: Array * dstOffset: int * count: int -> unit static member ByteLength: array: Array -> int static member GetByte: array: Array * index: int -> byte static member MemoryCopy: source: voidptr * destination: voidptr * destinationSizeInBytes: int64 * sourceBytesToCopy: int64 -> unit + 1 overload static member SetByte: array: Array * index: int * value: byte -> unit
<summary>Manipulates arrays of primitive types.</summary>

val write: value: byte -> buffer: Span<byte> -> Span<byte>

val value: byte

val buffer: Span<byte>

Span.Slice(start: int) : Span<byte>
Span.Slice(start: int, length: int) : Span<byte>

val writeUint16: value: uint16 -> buffer: Span<byte> -> Span<byte>

val value: uint16

type BinaryPrimitives = static member ReadDoubleBigEndian: source: ReadOnlySpan<byte> -> float static member ReadDoubleLittleEndian: source: ReadOnlySpan<byte> -> float static member ReadHalfBigEndian: source: ReadOnlySpan<byte> -> Half static member ReadHalfLittleEndian: source: ReadOnlySpan<byte> -> Half static member ReadInt128BigEndian: source: ReadOnlySpan<byte> -> Int128 static member ReadInt128LittleEndian: source: ReadOnlySpan<byte> -> Int128 static member ReadInt16BigEndian: source: ReadOnlySpan<byte> -> int16 static member ReadInt16LittleEndian: source: ReadOnlySpan<byte> -> int16 static member ReadInt32BigEndian: source: ReadOnlySpan<byte> -> int static member ReadInt32LittleEndian: source: ReadOnlySpan<byte> -> int ...
<summary>Reads bytes as primitives with specific endianness.</summary>

BinaryPrimitives.WriteUInt16LittleEndian(destination: Span<byte>, value: uint16) : unit

val writeUint16BE: value: uint16 -> buffer: Span<byte> -> Span<byte>

BinaryPrimitives.WriteUInt16BigEndian(destination: Span<byte>, value: uint16) : unit

val writeUInt32: value: uint32 -> buffer: Span<byte> -> Span<byte>

val value: uint32

Multiple items
val uint32: value: 'T -> uint32 (requires member op_Explicit)

--------------------
type uint32 = UInt32

--------------------
type uint32<'Measure> = uint<'Measure>

BinaryPrimitives.WriteUInt32LittleEndian(destination: Span<byte>, value: uint32) : unit

val writeString: s: string -> buffer: Span<byte> -> Span<byte>

val s: string

Multiple items
val string: value: 'T -> string

--------------------
type string = String

val len: int

type Encoding = interface ICloneable member Clone: unit -> obj member Equals: value: obj -> bool member GetByteCount: chars: nativeptr<char> * count: int -> int + 5 overloads member GetBytes: chars: nativeptr<char> * charCount: int * bytes: nativeptr<byte> * byteCount: int -> int + 7 overloads member GetCharCount: bytes: nativeptr<byte> * count: int -> int + 3 overloads member GetChars: bytes: nativeptr<byte> * byteCount: int * chars: nativeptr<char> * charCount: int -> int + 4 overloads member GetDecoder: unit -> Decoder member GetEncoder: unit -> Encoder member GetHashCode: unit -> int ...
<summary>Represents a character encoding.</summary>

property Encoding.UTF8: Encoding with get
<summary>Gets an encoding for the UTF-8 format.</summary>
<returns>An encoding for the UTF-8 format.</returns>

(extension) Encoding.GetBytes(chars: inref<ReadOnlySequence<char>>) : byte array
   (+0 other overloads)
Encoding.GetBytes(s: string) : byte array
   (+0 other overloads)
Encoding.GetBytes(chars: char array) : byte array
   (+0 other overloads)
(extension) Encoding.GetBytes(chars: inref<ReadOnlySequence<char>>, writer: IBufferWriter<byte>) : int64
   (+0 other overloads)
(extension) Encoding.GetBytes(chars: inref<ReadOnlySequence<char>>, bytes: Span<byte>) : int
   (+0 other overloads)
(extension) Encoding.GetBytes(chars: ReadOnlySpan<char>, writer: IBufferWriter<byte>) : int64
   (+0 other overloads)
Encoding.GetBytes(chars: ReadOnlySpan<char>, bytes: Span<byte>) : int
   (+0 other overloads)
Encoding.GetBytes(s: string, index: int, count: int) : byte array
   (+0 other overloads)
Encoding.GetBytes(chars: char array, index: int, count: int) : byte array
   (+0 other overloads)
Encoding.GetBytes(chars: nativeptr<char>, charCount: int, bytes: nativeptr<byte>, byteCount: int) : int
   (+0 other overloads)

(extension) String.AsSpan() : ReadOnlySpan<char>
(extension) String.AsSpan(start: int) : ReadOnlySpan<char>
(extension) String.AsSpan(startIndex: Index) : ReadOnlySpan<char>
(extension) String.AsSpan(range: Range) : ReadOnlySpan<char>
(extension) String.AsSpan(start: int, length: int) : ReadOnlySpan<char>

val serializeOpcode: op: Opcode -> buffer: Span<byte> -> Span<byte>

val op: Opcode

val enum: value: int32 -> 'U (requires enum)

val opcodeLength: code: 'a -> int (requires enum and comparison)

val code: 'a (requires enum and comparison)

[<Struct>] type Byte = member CompareTo: value: byte -> int + 1 overload member Equals: obj: byte -> bool + 1 overload member GetHashCode: unit -> int member GetTypeCode: unit -> TypeCode member ToString: unit -> string + 3 overloads member TryFormat: utf8Destination: Span<byte> * bytesWritten: byref<int> * ?format: ReadOnlySpan<char> * ?provider: IFormatProvider -> bool + 1 overload static member Clamp: value: byte * min: byte * max: byte -> byte static member CreateChecked<'TOther (requires 'TOther :> INumberBase<'TOther>)> : value: 'TOther -> byte static member CreateSaturating<'TOther (requires 'TOther :> INumberBase<'TOther>)> : value: 'TOther -> byte static member CreateTruncating<'TOther (requires 'TOther :> INumberBase<'TOther>)> : value: 'TOther -> byte ...
<summary>Represents an 8-bit unsigned integer.</summary>

Multiple items
val uint8: value: 'T -> uint8 (requires member op_Explicit)

--------------------
type uint8 = Byte

--------------------
type uint8<'Measure> = byte<'Measure>

Multiple items
type String = interface IEnumerable<char> interface IEnumerable interface ICloneable interface IComparable interface IComparable<string> interface IConvertible interface IEquatable<string> interface IParsable<string> interface ISpanParsable<string> new: value: nativeptr<char> -> unit + 8 overloads ...
<summary>Represents text as a sequence of UTF-16 code units.</summary>

--------------------
String(value: nativeptr<char>) : String
String(value: char array) : String
String(value: ReadOnlySpan<char>) : String
String(value: nativeptr<sbyte>) : String
String(c: char, count: int) : String
String(value: nativeptr<char>, startIndex: int, length: int) : String
String(value: char array, startIndex: int, length: int) : String
String(value: nativeptr<sbyte>, startIndex: int, length: int) : String
String(value: nativeptr<sbyte>, startIndex: int, length: int, enc: Encoding) : String

Multiple items
val byte: byte

--------------------
type byte = Byte

--------------------
type byte<'Measure> = byte

val short: byte

Multiple items
val int: byte

--------------------
type int = int32

--------------------
type int<'Measure> = int

Multiple items
val string: byte

--------------------
type string = String

val globalIndex: byte

val serializeParam: p: Parameter -> buffer: Span<byte> -> Span<byte>

val p: Parameter

Multiple items
union case Parameter.Byte: uint8 -> Parameter

--------------------
[<Struct>] type Byte = member CompareTo: value: byte -> int + 1 overload member Equals: obj: byte -> bool + 1 overload member GetHashCode: unit -> int member GetTypeCode: unit -> TypeCode member ToString: unit -> string + 3 overloads member TryFormat: utf8Destination: Span<byte> * bytesWritten: byref<int> * ?format: ReadOnlySpan<char> * ?provider: IFormatProvider -> bool + 1 overload static member Clamp: value: byte * min: byte * max: byte -> byte static member CreateChecked<'TOther (requires 'TOther :> INumberBase<'TOther>)> : value: 'TOther -> byte static member CreateSaturating<'TOther (requires 'TOther :> INumberBase<'TOther>)> : value: 'TOther -> byte static member CreateTruncating<'TOther (requires 'TOther :> INumberBase<'TOther>)> : value: 'TOther -> byte ...
<summary>Represents an 8-bit unsigned integer.</summary>

val v: uint8

val b: Span<byte>

module ParamSize from 2020-12-03-applicative-computation-expressions-3

val byte: byte

union case Parameter.UShort: uint16 -> Parameter

val v: uint16

union case Parameter.UInt: uint32 -> Parameter

val v: uint32

val int: byte

Multiple items
union case Parameter.String: string -> Parameter

--------------------
type String = interface IEnumerable<char> interface IEnumerable interface ICloneable interface IComparable interface IComparable<string> interface IConvertible interface IEquatable<string> interface IParsable<string> interface ISpanParsable<string> new: value: nativeptr<char> -> unit + 8 overloads ...
<summary>Represents text as a sequence of UTF-16 code units.</summary>

--------------------
String(value: nativeptr<char>) : String
String(value: char array) : String
String(value: ReadOnlySpan<char>) : String
String(value: nativeptr<sbyte>) : String
String(c: char, count: int) : String
String(value: nativeptr<char>, startIndex: int, length: int) : String
String(value: char array, startIndex: int, length: int) : String
String(value: nativeptr<sbyte>, startIndex: int, length: int) : String
String(value: nativeptr<sbyte>, startIndex: int, length: int, enc: Encoding) : String

val string: byte

union case Parameter.GlobalIndex: uint8 -> Parameter

val paramLength: _arg1: Parameter -> int

val l: string

Encoding.GetByteCount(s: string) : int
Encoding.GetByteCount(chars: ReadOnlySpan<char>) : int
Encoding.GetByteCount(chars: char array) : int
Encoding.GetByteCount(chars: nativeptr<char>, count: int) : int
Encoding.GetByteCount(s: string, index: int, count: int) : int
Encoding.GetByteCount(chars: char array, index: int, count: int) : int

type Command = | Direct of Opcode * Parameter list

type 'T list = List<'T>

val length: _arg1: Command -> int

union case Command.Direct: Opcode * Parameter list -> Command

val code: Opcode

val parameters: Parameter list

val sumBy: projection: ('T -> 'U) -> list: 'T list -> 'U (requires member (+) and member Zero)

type Serializer<'t> = delegate of 't * Span<byte> -> Span<byte>

val serializeAll: f: Serializer<'t> -> ps: 't list -> b: Span<byte> -> Span<byte>

val f: Serializer<'t>

val ps: 't list

val p: 't

val t: 't list

val b': Span<byte>

abstract Serializer.Invoke: 't * Span<byte> -> Span<byte>

val serializeCommand: command: Command -> buffer: Span<byte> -> Span<byte>

val command: Command

val p: Parameter list

val serialize: sequence: uint16 -> commandType: byte -> globalSize: uint16 -> commands: Command list -> IMemoryOwner<byte>

val commandType: byte

val globalSize: uint16

val commands: Command list

val length: int

val rental: IMemoryOwner<byte>

type MemoryPool<'T> = interface IDisposable member Dispose: unit -> unit override Rent: ?minBufferSize: int -> IMemoryOwner<'T> member MaxBufferSize: int static member Shared: MemoryPool<'T>
<summary>Represents a pool of memory blocks.</summary>
<typeparam name="T">The type of the items in the memory pool.</typeparam>

property MemoryPool.Shared: MemoryPool<'T> with get
<summary>Gets a singleton instance of a memory pool based on arrays.</summary>
<returns>A singleton instance of a memory pool.</returns>

MemoryPool.Rent(?minBufferSize: int) : IMemoryOwner<'T>

val mem: Memory<byte>

property IMemoryOwner.Memory: Memory<byte> with get
<summary>Gets the memory belonging to this owner.</summary>
<returns>The memory belonging to this owner.</returns>

Memory.Slice(start: int) : Memory<byte>
Memory.Slice(start: int, length: int) : Memory<byte>

property Memory.Span: Span<byte> with get
<summary>Returns a span from the current instance.</summary>
<returns>A span created from the current <see cref="T:System.Memory`1" /> object.</returns>

type IMemoryOwner<'T> = inherit IDisposable member Memory: Memory<'T>
<summary>Identifies the owner of a block of memory who is responsible for disposing of the underlying memory appropriately.</summary>
<typeparam name="T">The type of elements to store in memory.</typeparam>

Multiple items
[<Struct>] type Memory<'T> = new: array: 'T array -> unit + 1 overload member CopyTo: destination: Memory<'T> -> unit member Equals: other: Memory<'T> -> bool + 1 overload member GetHashCode: unit -> int member Pin: unit -> MemoryHandle member Slice: start: int -> Memory<'T> + 1 overload member ToArray: unit -> 'T array member ToString: unit -> string member TryCopyTo: destination: Memory<'T> -> bool static member op_Implicit: segment: ArraySegment<'T> -> Memory<'T> + 2 overloads ...
<summary>Represents a contiguous region of memory.</summary>
<typeparam name="T">The type of items in the <see cref="T:System.Memory`1" />.</typeparam>

--------------------
Memory ()
Memory(array: 'T array) : Memory<'T>
Memory(array: 'T array, start: int, length: int) : Memory<'T>

IDisposable.Dispose() : unit

val send: commands: Command list -> brick: Brick -> Async<unit>

val brick: Brick

member Brick.GetNextSequence: unit -> uint16

val memory: IMemoryOwner<byte>

module CommandType from 2020-12-03-applicative-computation-expressions-3

Memory.op_Implicit(array: 'T array) : Memory<'T>
Memory.op_Implicit(memory: Memory<'T>) : ReadOnlyMemory<'T>
Memory.op_Implicit(segment: ArraySegment<'T>) : Memory<'T>

type OutputPort = | A | B | C | D

union case OutputPort.A: OutputPort

union case OutputPort.B: OutputPort

union case OutputPort.C: OutputPort

union case OutputPort.D: OutputPort

val port: p: OutputPort list -> Parameter

val p: OutputPort list

val fold<'T,'State> : folder: ('State -> 'T -> 'State) -> state: 'State -> list: 'T list -> 'State

val v: byte

val p: OutputPort

val startMotor: ports: OutputPort list -> Command

val ports: OutputPort list

Opcode.OutputStart: Opcode = 166

type Brake = | Brake | NoBrake static member toByte: b: Brake -> Parameter

val b: Brake

Multiple items
union case Brake.Brake: Brake

--------------------
type Brake = | Brake | NoBrake static member toByte: b: Brake -> Parameter

union case Brake.NoBrake: Brake

val stopMotor: ports: OutputPort list -> brake: Brake -> Command

val brake: Brake

Opcode.OutputStop: Opcode = 163

static member Brake.toByte: b: Brake -> Parameter

Multiple items
union case Power.Power: uint8 -> Power

--------------------
type Power = | Power of uint8

type Power = | Power of uint8

val power: p: int -> Power

val p: int

val invalidArg: argumentName: string -> message: string -> 'T

val outputReady: ports: OutputPort list -> Command
wait for the end of previous command

Opcode.OutputReady: Opcode = 170

val turnMotorAtPower: ports: OutputPort list -> Power -> Command

val power: uint8

Opcode.OutputPower: Opcode = 164

val turnMotorAtSpeedForTime': ports: OutputPort list -> speed: int -> msRampUp: uint32 -> msConstant: uint32 -> msRampDown: uint32 -> brake: Brake -> Command

val speed: int

val msRampUp: uint32

val msConstant: uint32

val msRampDown: uint32

Opcode.OutputTimeSpeed: Opcode = 175

val turnMotorAtSpeedForTime: ports: OutputPort list -> speed: int -> msDuration: uint32 -> brake: Brake -> Command

val msDuration: uint32

val playTone: volume: uint8 -> frequency: uint16 -> duration: uint16 -> Command

val volume: uint8

val frequency: uint16

val duration: uint16

Opcode.Sound_Tone: Opcode = 37889

type Lego<'a> = Brick -> Async<'a>

Multiple items
type LegoBuilder = new: unit -> LegoBuilder member Bind: x: Async<'a> * f: ('a -> Brick -> Async<'b>) -> Lego<'b> + 3 overloads member Combine: x: (Brick -> Async<unit>) * y: (Brick -> Async<'a>) -> Lego<'a> member Delay: f: (unit -> Brick -> Async<'a>) -> (Brick -> Async<'a>) member For: values: 'T seq * body: ('T -> Brick -> Async<unit>) -> (Brick -> Async<unit>) member Return: x: 'a -> Lego<'a> member ReturnFrom: x: 'e -> 'e member Using: d: 'a * f: ('b -> 'a -> Async<'c>) -> ('b -> Async<'c>) (requires 'a :> IDisposable) member Zero: unit -> ('d -> Async<unit>)

--------------------
new: unit -> LegoBuilder

val x: Lego<'a>

val f: ('a -> Brick -> Async<'b>)

member AsyncBuilder.Bind: computation: Async<'T> * binder: ('T -> Async<'U>) -> Async<'U>

val v: 'a

val __: LegoBuilder

val command: Command list

val f: (unit -> Brick -> Async<'b>)

val x: Async<'a>

val x: 'a

val x: 'e

val values: 'T seq

Multiple items
val seq: sequence: 'T seq -> 'T seq

--------------------
type 'T seq = Collections.Generic.IEnumerable<'T>

val body: ('T -> Brick -> Async<unit>)

member AsyncBuilder.For: sequence: 'T seq * body: ('T -> Async<unit>) -> Async<unit>

val t: 'T

val x: (Brick -> Async<unit>)

val y: (Brick -> Async<'a>)

val ctx: Brick

member AsyncBuilder.Combine: computation1: Async<unit> * computation2: Async<'T> -> Async<'T>

val f: (unit -> Brick -> Async<'a>)

member AsyncBuilder.Delay: generator: (unit -> Async<'T>) -> Async<'T>

val ctx: 'd

member AsyncBuilder.Zero: unit -> Async<unit>

val d: #IDisposable

val f: ('b -> #IDisposable -> Async<'c>)

val ctx: 'b

member AsyncBuilder.Using: resource: 'T * binder: ('T -> Async<'U>) -> Async<'U> (requires 'T :> IDisposable)

val run: brick: Brick -> f: Lego<unit> -> CancellationTokenSource

val f: Lego<unit>

val cancelToken: CancellationTokenSource

Multiple items
type CancellationTokenSource = interface IDisposable new: unit -> unit + 3 overloads member Cancel: unit -> unit + 1 overload member CancelAfter: millisecondsDelay: int -> unit + 1 overload member CancelAsync: unit -> Task member Dispose: unit -> unit member TryReset: unit -> bool static member CreateLinkedTokenSource: token: CancellationToken -> CancellationTokenSource + 3 overloads member IsCancellationRequested: bool member Token: CancellationToken
<summary>Signals to a <see cref="T:System.Threading.CancellationToken" /> that it should be canceled.</summary>

--------------------
CancellationTokenSource() : CancellationTokenSource
CancellationTokenSource(millisecondsDelay: int) : CancellationTokenSource
CancellationTokenSource(delay: TimeSpan) : CancellationTokenSource
CancellationTokenSource(delay: TimeSpan, timeProvider: TimeProvider) : CancellationTokenSource

static member Async.Start: computation: Async<unit> * ?cancellationToken: CancellationToken -> unit

property CancellationTokenSource.Token: CancellationToken with get
<summary>Gets the <see cref="T:System.Threading.CancellationToken" /> associated with this <see cref="T:System.Threading.CancellationTokenSource" />.</summary>
<exception cref="T:System.ObjectDisposedException">The token source has been disposed.</exception>
<returns>The <see cref="T:System.Threading.CancellationToken" /> associated with this <see cref="T:System.Threading.CancellationTokenSource" />.</returns>

val runSynchronously: brick: Brick -> f: Lego<'a> -> 'a

val f: Lego<'a>

static member Async.RunSynchronously: computation: Async<'T> * ?timeout: int * ?cancellationToken: CancellationToken -> 'T

val lego: LegoBuilder

val sample: unit -> unit

member Brick.Connect: unit -> unit

val i: int

type InputPort = | In1 | In2 | In3 | In4 | InA | InB | InC | InD

val inputPort: (InputPort -> Parameter)
gets the binary code for an input port

union case InputPort.In1: InputPort

union case InputPort.In2: InputPort

union case InputPort.In3: InputPort

union case InputPort.In4: InputPort

union case InputPort.InA: InputPort

union case InputPort.InB: InputPort

union case InputPort.InC: InputPort

union case InputPort.InD: InputPort

type Mode = | TouchMode of TouchMode | ColorMode of ColorMode | IRMode of IRMode

type TouchMode = | Touch | Bumps

val modeToUInt8: _arg1: Mode -> byte

Multiple items
union case Mode.TouchMode: TouchMode -> Mode

--------------------
type TouchMode = | Touch | Bumps

union case TouchMode.Touch: TouchMode

union case TouchMode.Bumps: TouchMode

union case ColorMode.Reflective: ColorMode

union case ColorMode.Ambient: ColorMode

union case ColorMode.Color: ColorMode

union case ColorMode.ReflectiveRaw: ColorMode

union case ColorMode.ReflectiveRgb: ColorMode

union case ColorMode.Calibration: ColorMode

union case IRMode.Proximity: IRMode

union case IRMode.Seek: IRMode

union case IRMode.Remote: IRMode

union case IRMode.RemoteA: IRMode

union case IRMode.SAlt: IRMode

union case IRMode.Calibrate: IRMode

type ReadDataType = | SI | Raw | Percent | RGB

val readDataTypeLen: _arg1: ReadDataType -> int
gets the byte length for each data type

union case ReadDataType.SI: ReadDataType

union case ReadDataType.Raw: ReadDataType

union case ReadDataType.Percent: ReadDataType

union case ReadDataType.RGB: ReadDataType

val readOpcode: _arg1: ReadDataType -> Opcode

Opcode.InputDevice_ReadySI: Opcode = 39197

Opcode.InputDevice_ReadyRaw: Opcode = 39196

Opcode.InputDevice_ReadyPct: Opcode = 39195

val readCommand: inPort: InputPort * dataType: ReadDataType * mode: Mode -> position: int -> Command

val inPort: InputPort

val dataType: ReadDataType

val mode: Mode

val position: int

[<Struct>] type ReplyType = | DirectReply = 2 | SystemReply = 3 | DirectReplyError = 4 | SystemReplyError = 5

val request: commands: Command list -> globalSize: uint16 -> brick: Brick -> Async<ReadOnlyMemory<byte>>

val data: IMemoryOwner<byte>

member Brick.AsyncRequest: sequence: Sequence * data: ReadOnlyMemory<byte> -> Async<ReadOnlyMemory<byte>>

val replyType: ReplyType

property ReadOnlyMemory.Span: ReadOnlySpan<byte> with get
<summary>Gets a span from the memory region.</summary>
<returns>A memory span.</returns>

ReplyType.DirectReplyError: ReplyType = 4

ReplyType.SystemReplyError: ReplyType = 5

val failwith: message: string -> 'T

val readLength: 'a * dataType: ReadDataType * 'b -> int

val readAux: brick: Brick -> inputs: (InputPort * ReadDataType * Mode) list -> Async<Map<(InputPort * ReadDataType * Mode),ReadOnlyMemory<byte>>>

val inputs: (InputPort * ReadDataType * Mode) list

val isEmpty: list: 'T list -> bool

val globalSize: int

val mapFold<'T,'State,'Result> : mapping: ('State -> 'T -> 'Result * 'State) -> state: 'State -> list: 'T list -> 'Result list * 'State

val offset: int

val input: InputPort * ReadDataType * Mode

val sensorsData: ReadOnlyMemory<byte>

ReadOnlyMemory.Slice(start: int) : ReadOnlyMemory<byte>
ReadOnlyMemory.Slice(start: int, length: int) : ReadOnlyMemory<byte>

val response: Map<(InputPort * ReadDataType * Mode),ReadOnlyMemory<byte>>

val fst: tuple: ('T1 * 'T2) -> 'T1

val ofList: elements: ('Key * 'T) list -> Map<'Key,'T> (requires comparison)

type InputRequest = InputPort * ReadDataType * Mode

type Sensor<'t> = { Inputs: Set<InputRequest> Get: (Map<InputRequest,ReadOnlyMemory<byte>> -> 't) }

Multiple items
module Set from Microsoft.FSharp.Collections

--------------------
type Set<'T (requires comparison)> = interface IReadOnlyCollection<'T> interface IStructuralEquatable interface IComparable interface IEnumerable interface IEnumerable<'T> interface ICollection<'T> new: elements: 'T seq -> Set<'T> member Add: value: 'T -> Set<'T> member Contains: value: 'T -> bool override Equals: objnull -> bool ...

--------------------
new: elements: 'T seq -> Set<'T>

val input: InputPort * ReadDataType * Mode -> Sensor<ReadOnlyMemory<byte>>

val req: InputRequest

val singleton: value: 'T -> Set<'T> (requires comparison)

val m: Map<InputRequest,ReadOnlyMemory<byte>>

val read: sensor: Sensor<'t> -> brick: Brick -> Async<'t>

val sensor: Sensor<'t>

val inputs: InputRequest list

val toList: set: Set<'T> -> 'T list (requires comparison)

Sensor.Inputs: Set<InputRequest>

Sensor.Get: Map<InputRequest,ReadOnlyMemory<byte>> -> 't

val ret: x: 'a -> Sensor<'a>

val empty<'T (requires comparison)> : Set<'T> (requires comparison)

val map: f: ('a -> 'b) -> s: Sensor<'a> -> Sensor<'b>

val f: ('a -> 'b)

val s: Sensor<'a>

Sensor.Get: Map<InputRequest,ReadOnlyMemory<byte>> -> 'a

val map2: f: ('a -> 'b -> 'c) -> sx: Sensor<'a> -> sy: Sensor<'b> -> Sensor<'c>

val f: ('a -> 'b -> 'c)

val sx: Sensor<'a>

val sy: Sensor<'b>

val y: 'b

Sensor.Get: Map<InputRequest,ReadOnlyMemory<byte>> -> 'b

val zip: sx: Sensor<'a> -> sy: Sensor<'b> -> Sensor<'a * 'b>

val apply: sf: Sensor<('a -> 'b)> -> sx: Sensor<'a> -> Sensor<'b>

val sf: Sensor<('a -> 'b)>

val typedInput: dataType: ReadDataType -> convert: (ReadOnlyMemory<byte> -> 'a) -> port: InputPort -> mode: Mode -> Sensor<'a>

val convert: (ReadOnlyMemory<byte> -> 'a)

val port: InputPort

val inputSi: (InputPort -> Mode -> Sensor<float32>)

BitConverter.ToSingle(value: ReadOnlySpan<byte>) : float32
BitConverter.ToSingle(value: byte array, startIndex: int) : float32

val inputRaw: (InputPort -> Mode -> Sensor<int>)

BitConverter.ToInt32(value: ReadOnlySpan<byte>) : int
BitConverter.ToInt32(value: byte array, startIndex: int) : int

val inputPct: (InputPort -> Mode -> Sensor<int>)

val inputRgb: (InputPort -> Mode -> Sensor<int * int * int>)

val span: ReadOnlySpan<byte>

val r: uint16

val g: uint16

ReadOnlySpan.Slice(start: int) : ReadOnlySpan<byte>
ReadOnlySpan.Slice(start: int, length: int) : ReadOnlySpan<byte>

val b: uint16

type ButtonState = | Pushed | Released

val reflective: port: InputPort -> Sensor<int>

val ambient: port: InputPort -> Sensor<int>

val color: port: InputPort -> Sensor<Color>

union case Color.Black: Color

union case Color.Blue: Color

union case Color.Green: Color

union case Color.Yellow: Color

union case Color.Red: Color

union case Color.White: Color

union case Color.Brown: Color

union case Color.Transparent: Color

val rgb: port: InputPort -> Sensor<int * int * int>

val proximity: port: InputPort -> Sensor<int>

val button: port: InputPort -> Sensor<ButtonState>

union case ButtonState.Pushed: ButtonState

union case ButtonState.Released: ButtonState

val isRed: port: InputPort -> Sensor<bool>

type bool = Boolean

val c: Color

module Sensors from 2020-12-03-applicative-computation-expressions-3

module Color from 2020-12-03-applicative-computation-expressions-3.Sensors

val colorAndProximityIfPushed: Sensor<(Color * int) option>

type 'T option = Option<'T>

val color: Color

val proximity: int

val button: ButtonState

module IR from 2020-12-03-applicative-computation-expressions-3.Sensors

module Touch from 2020-12-03-applicative-computation-expressions-3.Sensors

Multiple items
type SensorBuilder = new: unit -> SensorBuilder member Bind2Return: x: Sensor<'a> * y: Sensor<'b> * f: ('a * 'b -> 'c) -> Sensor<'c> member BindReturn: x: Sensor<'a> * f: ('a -> 'b) -> Sensor<'b> member MergeSources: x: Sensor<'a> * y: Sensor<'b> -> Sensor<'a * 'b> member Return: x: 'a -> Sensor<'a>

--------------------
new: unit -> SensorBuilder

val x: Sensor<'a>

val y: Sensor<'b>

val f: ('a * 'b -> 'c)

val sensor: SensorBuilder

val colorWhenPushed: Sensor<(Color * int) option>

val sample2: unit -> unit

val value: ((int * int * int) * int) option

val color: int * int * int

module Raw from 2020-12-03-applicative-computation-expressions-3.Sensors.Color

val b: ButtonState

val prox: int

val printfn: format: Printf.TextWriterFormat<'T> -> 'T

Applicative Computation Expressions - 2

2020-10-08T08:18:10.7839774+00:00

In the last post we used BindReturnand MergeSources to implement the applicative. The advantage of implementing them is that it will work for any number of and!.

When using let! with a single and!, it makes one call to MergeSources to pair arguments and one call to BindReturn to pass values to the function.

When using let! with two and!, it makes two calls to MergeSources to tuple arguments and one call to BindReturn to pass values to the function.

This can be expensive, so you can provide specific implementations for given numbers of parameters to reduce the number of calls.

For two arguments, you can implement Bind2Return:

type AsyncBuilder with
    member this.Bind2Return(x: 'a Async,y: 'b Async,f: 'a * 'b -> 'c) : 'c Async =
        this.Bind(Async.StartChild x, fun xa ->
            this.Bind(Async.StartChild y, fun ya ->
                this.Bind(xa, fun xv ->
                    this.Bind(ya, fun yv -> this.Return (f(xv, yv)))
                    )
                )
            
            )

its signature is:

M<'a> * M<'b> * ('a * 'b -> 'c) -> M<'c>

Notice that it is similar to map2 signature.

We can check that it's working as expected:

async {
    let! parisCoords = 
        async {
            let! paris = ZipCode.AsyncLoad "http://api.zippopotam.us/fr/75020"
            return coord paris }
    and! londonCoords = 
        async { 
            let! london = ZipCode.AsyncLoad "http://api.zippopotam.us/GB/EC1"
            return coord london}
                
    return dist parisCoords londonCoords

}
|> Async.RunSynchronously

To handle a let! and! and! case you have to provide a Bind3Return member that takes 3 values and a function. You can also provide a Bind4Return, Bind5Return... and from my tests there is no limit in the number of arguments you can test. F# would happily call a Bind265Return if it had to.

Those additional functions are occasions to optimize the implementation by reducing the number of intermediate allocations and function calls.

Obviously, it's advised to provide only a few special cases and fall back to BindReturn and MergeSources for the rest.

Other options for implementation is to provide MergeSources3, MergeSources4 to reduce the number of intermediate tuples. The signature will be for MergeSources3:

M<'a> * M<'b> * M<'c> -> M<'a * 'b * 'c>

It's also possible to define Bind2, Bind3 with the following signatures:

M<'a> * M<'b> * ('a * 'b -> M<'c>) -> M<'c>

This looks like the Bind2Return except that the function already returns a wrapped value.

You can find the complete documentation in the RFC

namespace System

Multiple items
namespace FSharp

--------------------
namespace Microsoft.FSharp

Multiple items
namespace FSharp.Data

--------------------
namespace Microsoft.FSharp.Data

type ZipCode = JsonProvider<...>

type JsonProvider
<summary>Typed representation of a JSON document.</summary> <param name='Sample'>Location of a JSON sample file or a string containing a sample JSON document.</param> <param name='SampleIsList'>If true, sample should be a list of individual samples for the inference.</param> <param name='RootName'>The name to be used to the root type. Defaults to `Root`.</param> <param name='Culture'>The culture used for parsing numbers and dates. Defaults to the invariant culture.</param> <param name='Encoding'>The encoding used to read the sample. You can specify either the character set name or the codepage number. Defaults to UTF8 for files, and to ISO-8859-1 the for HTTP requests, unless `charset` is specified in the `Content-Type` response header.</param> <param name='ResolutionFolder'>A directory that is used when resolving relative file references (at design time and in hosted execution).</param> <param name='EmbeddedResource'>When specified, the type provider first attempts to load the sample from the specified resource (e.g. 'MyCompany.MyAssembly, resource_name.json'). This is useful when exposing types generated by the type provider.</param> <param name='InferTypesFromValues'> This parameter is deprecated. Please use InferenceMode instead. If true, turns on additional type inference from values. (e.g. type inference infers string values such as "123" as ints and values constrained to 0 and 1 as booleans.)</param> <param name='PreferDictionaries'>If true, json records are interpreted as dictionaries when the names of all the fields are inferred (by type inference rules) into the same non-string primitive type.</param> <param name='InferenceMode'>Possible values: | NoInference -> Inference is disabled. All values are inferred as the most basic type permitted for the value (i.e. string or number or bool). | ValuesOnly -> Types of values are inferred from the Sample. Inline schema support is disabled. This is the default. | ValuesAndInlineSchemasHints -> Types of values are inferred from both values and inline schemas. Inline schemas are special string values that can define a type and/or unit of measure. Supported syntax: typeof<type> or typeof{type} or typeof<type<measure>> or typeof{type{measure}}. Valid measures are the default SI units, and valid types are <c>int</c>, <c>int64</c>, <c>bool</c>, <c>float</c>, <c>decimal</c>, <c>date</c>, <c>datetimeoffset</c>, <c>timespan</c>, <c>guid</c> and <c>string</c>. | ValuesAndInlineSchemasOverrides -> Same as ValuesAndInlineSchemasHints, but value inferred types are ignored when an inline schema is present. </param>

val dist: lata: decimal * longa: decimal -> latb: decimal * longb: decimal -> decimal

val lata: decimal

Multiple items
val decimal: value: 'T -> decimal (requires member op_Explicit)

--------------------
type decimal = Decimal

--------------------
type decimal<'Measure> = decimal

val longa: decimal

val latb: decimal

val longb: decimal

val x: float

Multiple items
val float: value: 'T -> float (requires member op_Explicit)

--------------------
type float = Double

--------------------
type float<'Measure> = float

val cos: value: 'T -> 'T (requires member Cos)

Multiple items
val double: value: 'T -> double (requires member op_Explicit)

--------------------
type double = Double

--------------------
type double<'Measure> = float<'Measure>

type Math = static member Abs: value: decimal -> decimal + 7 overloads static member Acos: d: float -> float static member Acosh: d: float -> float static member Asin: d: float -> float static member Asinh: d: float -> float static member Atan: d: float -> float static member Atan2: y: float * x: float -> float static member Atanh: d: float -> float static member BigMul: a: int * b: int -> int64 + 5 overloads static member BitDecrement: x: float -> float ...
<summary>Provides constants and static methods for trigonometric, logarithmic, and other common mathematical functions.</summary>

field Math.PI: float = 3.14159265359

val y: float

val z: float

val sqrt: value: 'T -> 'U (requires member Sqrt)

val coord: zip: JsonProvider<...>.Root -> decimal * decimal
Gets latitude/longitude for a returned zip info

val zip: JsonProvider<...>.Root

type Root = inherit IJsonDocument new: postCode: string * country: string * countryAbbreviation: string * places: Placis array -> Root + 1 overload member Country: string member CountryAbbreviation: string member Places: Placis array member PostCode: string

property JsonProvider<...>.Root.Places: JsonProvider<...>.Placis array with get

type AsyncBuilder = member Bind: computation: Async<'T> * binder: ('T -> Async<'U>) -> Async<'U> member Combine: computation1: Async<unit> * computation2: Async<'T> -> Async<'T> member Delay: generator: (unit -> Async<'T>) -> Async<'T> member For: sequence: 'T seq * body: ('T -> Async<unit>) -> Async<unit> member Return: value: 'T -> Async<'T> member ReturnFrom: computation: Async<'T> -> Async<'T> member TryFinally: computation: Async<'T> * compensation: (unit -> unit) -> Async<'T> member TryWith: computation: Async<'T> * catchHandler: (exn -> Async<'T>) -> Async<'T> member Using: resource: 'T * binder: ('T -> Async<'U>) -> Async<'U> (requires 'T :> IDisposable) member While: guard: (unit -> bool) * computation: Async<unit> -> Async<unit> ...

val this: AsyncBuilder

val x: Async<'a>

val y: Async<'b>

val f: ('a * 'b -> 'c)

member AsyncBuilder.Bind: computation: Async<'T> * binder: ('T -> Async<'U>) -> Async<'U>

static member Async.StartChild: computation: Async<'T> * ?millisecondsTimeout: int -> Async<Async<'T>>

val xa: Async<'a>

val ya: Async<'b>

val xv: 'a

val yv: 'b

member AsyncBuilder.Return: value: 'T -> Async<'T>

val async: AsyncBuilder

val parisCoords: decimal * decimal

val paris: JsonProvider<...>.Root

JsonProvider<...>.AsyncLoad(uri: string) : Async<JsonProvider<...>.Root>
Loads JSON from the specified uri

val london: JsonProvider<...>.Root

static member Async.RunSynchronously: computation: Async<'T> * ?timeout: int * ?cancellationToken: Threading.CancellationToken -> 'T

Applicative Computation Expressions

2020-10-07T18:55:59.8453833+00:00

In the last post we saw how to implement applicatives using map, map2 and apply to define <!> and <*> operators.

This time, we will use Computation Expressions to achieve the same result. This is not yet part of F# 5.0, you need the --langversion:preview flag to compile the following code.

Let's start again with our Query<'t> type.

As a reminder, we created it to access a service that is called with a list of properties to return for a given document.

This is a mock version of such a service. In the real world, you'll call Elastic Search indicating the document id and the properties you need:

let queryService (properties: string Set) : Map<string,string> =
    Map.ofList [
        if Set.contains "firstname" properties then
            "firstname", "John"
        if Set.contains "lastname" properties then
            "lastname", "Doe"
        if Set.contains "age" properties then
            "age", "42"
        if Set.contains "favoritelanguage" properties then
            "favoritelanguage", "F#"
    ]

The problem with this kind of service is that there is usually no way to be sure that all properties used in the result have been correctly requested. This type contains both a list of properties to query from an external service as well as the code using fetched properties to build the result.

type Query<'t> = 
    { Properties: string Set
      Get: Map<string,string> -> 't }

It can be used to call the service:

let callService (query: Query<'t>) : 't =
    queryService query.Properties
    |> query.Get

From here we defined a function to create a query from a single column:

module Query =
    let prop name =
        { Properties = Set.singleton name 
          Get = fun m ->
            m.[name] }

And the map function that applies a given function to the result.

    let map f q =
        { Properties = q.Properties
          Get = fun m -> 
            let value = q.Get m
            f value }

We also defined a map2 to combine two queries as a single one. This query will request the unions of the argument queries properties, and call the first query to get its result, the second to get the other result, and pass both to the given function to combine them:

    let map2 f x y =
        { Properties = x.Properties + y.Properties
          Get = fun m ->
          let vx = x.Get m
          let vy = y.Get m
          f vx vy }

With map2 we can define a zip function that takes two Query arguments and combine their results as a pair. We will use this function in our builder.

    let zip x y =
        map2 (fun vx vy -> vx,vy) x y

Computation Expressions are created using types that implement specific members corresponding to the different operations. For applicatives, we need to implement BindReturn with the following signature:

M<'a> * ('a -> 'b) -> M<'b>

Where M in our case is Query. You should spot that it's the same signature as map (with the function as the second argument).

The second one is MergeSources and is used to zip parameter together:

M<'a> * M<'b> -> M<'a * 'b>

Here we will use the zip function we defined before.

Here is the builder definition:

type QueryBuilder() =
    
    member _.BindReturn(x : Query<'a>,f: 'a -> 'b) : Query<'b> = 
        Query.map f x
    
    member _.MergeSources(x : Query<'a>,y: Query<'b>) : Query<'a * 'b> = 
        Query.zip x y

let query = QueryBuilder()

For our sample, use define a User and the basic properties defined by the service:

type User =
    { FullName: string 
      Age: int
      FavoriteLanguage: string}

module Props =
    let firstname = Query.prop "firstname"
    let lastname = Query.prop "lastname"
    let age = Query.prop "age" |> Query.map int
    let favoriteLanguage = Query.prop "favoritelanguage"

Is is now possible to use the query computation expression to compute new derived properties. Here we define fullname that queries firstname and lastname and appends them together. When using this derived property, it will request both firstname and lastname properties from the service.

module DerivedProps =
    let fullname = 
        query {
            let! firstname = Props.firstname
            and! lastname = Props.lastname
            return firstname + " " + lastname
        }

you can notice that we use let! and and! here.

The meaning of let! is: Give this name (here firstname) to the value inside the structure on the right (the query). Since we have a Query<string> on the right, firstname will be a string.

The and! means: and at the same time, give this name to this value inside this other structure on the right.

This is at the same time extracting both values with zip. The actual code looks like this:

query.BindReturn(
    query.MergeSources(Props.firstname, Props.lastname), 
    fun (firstname, lastname) -> firstname + " " + lastname)

We can then compose queries further by reusing derived properties inside new queries:

let user =
    query {
        let! fullname = DerivedProps.fullname
        and! age = Props.age
        and! favoriteLanguage = Props.favoriteLanguage
        return 
            { FullName = fullname
              Age = age 
              FavoriteLanguage = favoriteLanguage }
    }

callService user

Let's use it for async.

We define a BindReturn and a MergeSources member. Using a type extension, it is not advised to use async {} blocks in the implementation because it can go recursive...

I still put the equivalent construct as a comment:

type AsyncBuilder with
    member _.BindReturn(x: 'a Async,f: 'a -> 'b) : 'b Async = 
        // this is the same as:
        // async { return f v }
        async.Bind(x, fun v -> async.Return (f v))

    member _.MergeSources(x: 'a Async, y: 'b Async) : ('a * 'b) Async =
        // this is the same as:
        // async {
        //    let! xa = Async.StartChild x
        //    let! ya = Async.StartChild y
        //    let! xv = xa  // wait x value
        //    let! yv = ya  // wait y value
        //    return xv, yv // pair values
        // }
        async.Bind(Async.StartChild x,
            fun xa ->
                async.Bind(Async.StartChild y,
                    fun ya ->
                        async.Bind(xa, fun xv ->
                            async.Bind(ya, fun yv ->
                                async.Return (xv,yv)
                            
                            )
                        )
                )
            )

The zippopotam.us service returns informations about zip codes. We will use the JsonProvider to load the data asynchronously and parse the result.

open FSharp.Data
type ZipCode = FSharp.Data.JsonProvider<"http://api.zippopotam.us/GB/EC1">

/// Gets latitude/longitude for a returned zip info
let coord (zip: ZipCode.Root) =
    zip.Places.[0].Latitude, zip.Places.[0].Longitude

We use The pythagorean theorem to compute the distance given the latitude and longitude of two points:

let dist (lata: decimal,longa: decimal) (latb: decimal, longb: decimal) =
    let x = float (longb - longa) * cos (double (latb + lata)  / 2. * Math.PI / 360.)
    let y = float (latb - lata)
    let z = sqrt (x*x + y*y)
    z * 1.852 * 60. |> decimal

Now using let! and! we fetch and compute the coordinates of Paris and London in parallel and then use both results to get the distance:

async {
    let! parisCoords = 
        async {
            let! paris = ZipCode.AsyncLoad "http://api.zippopotam.us/fr/75020"
            return coord paris }
    and! londonCoords = 
        async { 
            let! london = ZipCode.AsyncLoad "http://api.zippopotam.us/GB/EC1"
            return coord london }
    
    return dist parisCoords londonCoords
}
|> Async.RunSynchronously

It's obviously possible to use both Computation Expressions and the approach with operators from the last post for more fun!

namespace System

val queryService: properties: Set<string> -> Map<string,string>

val properties: Set<string>

Multiple items
val string: value: 'T -> string

--------------------
type string = String

val ofList: elements: ('Key * 'T) list -> Map<'Key,'T> (requires comparison)

val contains: element: 'T -> set: Set<'T> -> bool (requires comparison)

type Query<'t> = { Properties: Set<string> Get: (Map<string,string> -> 't) }

val callService: query: Query<'t> -> 't

val query: Query<'t>

Query.Properties: Set<string>

Query.Get: Map<string,string> -> 't

val prop: name: string -> Query<string>

val name: string

val singleton: value: 'T -> Set<'T> (requires comparison)

val m: Map<string,string>

val map: f: ('a -> 'b) -> q: Query<'a> -> Query<'b>

val f: ('a -> 'b)

val q: Query<'a>

val value: 'a

Query.Get: Map<string,string> -> 'a

val map2: f: ('a -> 'b -> 'c) -> x: Query<'a> -> y: Query<'b> -> Query<'c>

val f: ('a -> 'b -> 'c)

val x: Query<'a>

val y: Query<'b>

val vx: 'a

val vy: 'b

Query.Get: Map<string,string> -> 'b

val zip: x: Query<'a> -> y: Query<'b> -> Query<'a * 'b>

Multiple items
type QueryBuilder = new: unit -> QueryBuilder member BindReturn: x: Query<'a> * f: ('a -> 'b) -> Query<'b> member MergeSources: x: Query<'a> * y: Query<'b> -> Query<'a * 'b>

--------------------
new: unit -> QueryBuilder

Multiple items
module Query from 2020-10-07-applicative-computation-expressions

--------------------
type Query<'t> = { Properties: Set<string> Get: (Map<string,string> -> 't) }

val query: QueryBuilder

type User = { FullName: string Age: int FavoriteLanguage: string }

Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int

val firstname: Query<string>

val lastname: Query<string>

val age: Query<int>

val favoriteLanguage: Query<string>

val fullname: Query<string>

val firstname: string

module Props from 2020-10-07-applicative-computation-expressions

val lastname: string

member QueryBuilder.BindReturn: x: Query<'a> * f: ('a -> 'b) -> Query<'b>

member QueryBuilder.MergeSources: x: Query<'a> * y: Query<'b> -> Query<'a * 'b>

val user: Query<User>

val fullname: string

module DerivedProps from 2020-10-07-applicative-computation-expressions

val age: int

val favoriteLanguage: string

val x: Async<'a>

val async: AsyncBuilder

member AsyncBuilder.Bind: computation: Async<'T> * binder: ('T -> Async<'U>) -> Async<'U>

val v: 'a

member AsyncBuilder.Return: value: 'T -> Async<'T>

val y: Async<'b>

static member Async.StartChild: computation: Async<'T> * ?millisecondsTimeout: int -> Async<Async<'T>>

val xa: Async<'a>

val ya: Async<'b>

val xv: 'a

val yv: 'b

Multiple items
namespace FSharp

--------------------
namespace Microsoft.FSharp

Multiple items
namespace FSharp.Data

--------------------
namespace Microsoft.FSharp.Data

type ZipCode = JsonProvider<...>

val coord: zip: JsonProvider<...>.Root -> decimal * decimal
Gets latitude/longitude for a returned zip info

val zip: JsonProvider<...>.Root

property JsonProvider<...>.Root.Places: JsonProvider<...>.Placis array with get

val dist: lata: decimal * longa: decimal -> latb: decimal * longb: decimal -> decimal

val lata: decimal

Multiple items
val decimal: value: 'T -> decimal (requires member op_Explicit)

--------------------
type decimal = Decimal

--------------------
type decimal<'Measure> = decimal

val longa: decimal

val latb: decimal

val longb: decimal

val x: float

Multiple items
val float: value: 'T -> float (requires member op_Explicit)

--------------------
type float = Double

--------------------
type float<'Measure> = float

val cos: value: 'T -> 'T (requires member Cos)

Multiple items
val double: value: 'T -> double (requires member op_Explicit)

--------------------
type double = Double

--------------------
type double<'Measure> = float<'Measure>

field Math.PI: float = 3.14159265359

val y: float

val z: float

val sqrt: value: 'T -> 'U (requires member Sqrt)

val parisCoords: decimal * decimal

val paris: JsonProvider<...>.Root

JsonProvider<...>.AsyncLoad(uri: string) : Async<JsonProvider<...>.Root>
Loads JSON from the specified uri

val london: JsonProvider<...>.Root

static member Async.RunSynchronously: computation: Async<'T> * ?timeout: int * ?cancellationToken: Threading.CancellationToken -> 'T

Applicatives IRL

2020-10-03T16:33:28.5620501+00:00

This is the content of the presentation of the same name I did at Open FSharp (San Francisco) and NewCrafts (Paris)

Monads are all the rage in FP land... but Applicatives are also very useful and quite easy to get. We'll go through 3 real use cases to discover what they're up to.

Examples will be in F#. This is of course applicable in other languages with currying.

Options

We start with a simple structure: Option<'t>. As a reminder, its definition is

 type Option<'t> =
     | Some of 't
     | None

It's a value that either contains a value of type 't (the Some case) or doesn't contain a value (None)

map

We can easily write a map function for this structure.

map takes a 'a -> 'b function and applies it to the inner value of the option if any. If the option is None, it simply returns None.

 let map (f: 'a -> 'b) (x: Option<'a>) : Option<'b> =
     match x with
     | Some value -> Some (f value)
     | None -> None

when looking at map as a function taking a single parameter its signature is

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

map takes a ('a -> 'b) function and changes it in a (Option<'a> -> Option<'b>) function.

map2

map takes a single argument function f and makes it Option aware. But what about a function taking two arguments?

We can define a map2 function with the following signature:

('a -> 'b -> 'c) -> (Option<'a> -> Option<'b> -> Option<'c>)

It takes the function and calls it with the values of the two other Option parameters if they both have a value. It returns None if any is None.

 let map2 (f: 'a -> 'b -> 'c) (x: Option<'a>) (y: Option<'b>) : Option<'c> =
     match x,y with
     | Some xvalue, Some yvalue -> Some (f xvalue yvalue)
     | _ -> None

map3, map4...

For a 3 arguments function, a 4 arguments function we'd then have to write extra map functions. That would be doable but tedious. And where should we stop?

Let's take a simple two arguments function and see what happens when we use map on it:

 let add x y = x + y

 let mappedAdd = map add

Notice first that it compiles because add can be seen as a one argument function returning another one argument function:

let add x =
    fun y -> x + y

So its signature can be read as (int -> (int -> int))

Using map, it will become:

Option<int> -> Option<int -> int>

If you call it with the value Some 3, the result will be Some function that takes an int and adds 3 to it. Called with None, you get no function.

Lets take the most basic function application:

 let basicApply f x = f x

basicApply is a function that takes a function f, a value v, and passes the value v to the function f (this is the F# <| operator).

we can make it work with Option using map2:

 let apply f x = map2 basicApply f x

basicApply signature is

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

and we can look at it as a 2 arguments function:

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

And map2 will change it to:

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

This is a function that takes an optional function as first argument and an optional value as a second argument. If both have a value, the value is passed to the function. If any is None the result is None.

 let partialAdd = map add (Some 3) // Some(fun y -> 3 + Y)
 apply partialAdd (Some 5) // Some(3 + 5) => Some 8

Some 8

The nice thing is that it works for functions with more than 2 arguments since any function can be considered as a function of 1 argument.

 type User =
     { FirstName: string
       LastName: string
       Age: int
       FavoriteLanguage: string }
 let user firstname lastname age favoriteLang =
     { FirstName = firstname
       LastName = lastname
       Age = age
       FavoriteLanguage = favoriteLang }

 let user' = map user (Some "John") // Option<string -> int -> string -> User>
 let user'' = apply user' (Some "Doe") // Option<int -> string -> User>
 let user''' = apply user'' (Some 42) // Option<string -> User>
 apply user''' (Some "F#") // Option<User>

Some { FirstName = "John"
       LastName = "Doe"
       Age = 42
       FavoriteLanguage = "F#" }

Luckily we can simplify the writing by defining two infix operators for map and apply.

 let (<!>) = map
 let (<*>) = apply

Now we can write

 user
 <!> Some "John"
 <*> Some "Doe"
 <*> Some 42
 <*> Some "F#"

this is very useful with validation, and you can easily do the same thing for Result<'a,string> type, a type that has either a value of type 'a, or an error message. map is already defined and we have to write a map2:

 let map2 (f: 'a -> 'b -> 'c) 
          (xresult: Result<'a, string>)
          (yresult: Result<'b, string>) 
          : Result<'c, string> =
    match xresult, yresult with
    | Ok x, Ok y -> Ok (f x y)
    | Error fe, Ok _ -> Error fe
    | Ok _, Error xe -> Error xe
    | Error fe, Error xe -> Error (fe + "\n" + xe)

 let apply f x = map2 basicApply f x

 let (<!>) = Result.map
 let (<*>) = apply

 open System

 let notEmpty prop value =
     if String.IsNullOrEmpty value then
         Error (sprintf "%s should not be empty" prop)
     else
         Ok value
 
 let tryParse prop input =
    match Int32.TryParse(input: string) with
    | true, value -> Ok value
    | false, _ -> Error (sprintf "%s should be an number" prop)

  // define a user as previously
 type User =
     { FirstName: string
       LastName: string
       Age: int
       FavoriteLanguage: string }
 let user firstname lastname age favoriteLang =
     { FirstName = firstname
       LastName = lastname
       Age = age
       FavoriteLanguage = favoriteLang }


 user
 <!> notEmpty "firstname" "John"
 <*> notEmpty "lastname" "Doe"
 <*> tryParse "age" "42"
 <*> notEmpty "favorite language" "F#"

Now try to play with the input values and look at the result. Instead of getting Ok with a typed user, you'll get an error with a message describing why the user could not be constructed. Neat!

Series

Applicatives can be defined on anything on which we can write a map2 function. Any construct that is zippable.

A good example of a zippable, non trivial structure is a time series. Let's define one:

 type Series<'a> = Series of 'a * (DateTime * 'a) list

It has an initial value of type 'a and a list of changes consisting of the date of change and the new value.

For instance we can easily build constant series like this:

 let always x = Series(x, [])

it defines a Series with initial value x that never changes.

We can also define a map:

 let map f (Series(initial, changes)) =
    Series( f initial, List.map (fun (d,v) -> d, f v) changes)

It applies the function f to the initial value and every change values.

map2 is a bit more convoluted. The two series start with an initial value that can be fed to the given function. After that, one of the series changes, and we call f with the initial value of the one that didn't change and the new value of the other one.. each time a value changes, we use this value and the last known value of the other one. We use a recursive function for this.

 let map2 f (Series(ix, cx)) (Series(iy, cy)) =
    let rec zip lastx lasty changesx changesy =
        [ match changesx, changesy with
          | [],[] -> () // we're done
          | [], _ ->
             // x won't change anymore
             for d,y in changesy do 
                d, f lastx y
          | _, [] -> 
             // y won't change anymore
             for d,x in changesx do 
                d, f x lasty
          | (dx,x) :: tailx , (dy,y) :: taily ->
            if dx < dy then
                // x changes before y
                dx, f x lasty
                yield! zip x lasty tailx changesy
            elif dy < dx then
                // y changes before x
                dy, f lastx y
                yield! zip lastx y changesx taily
            else
                // x and y change at the same time
                // dx is equal to dy
                dx, f x y
                yield! zip x y tailx taily
        ]
    Series(f ix iy, zip ix iy cx cy)

using map2 we can add two series:

 let add x y = x + y
 map2 add
        (Series(0, [DateTime(2020,10,03), 1
                    DateTime(2020,10,05), 5 ]))
        (Series(2, [DateTime(2020,10,03), 2 
                    DateTime(2020,10,04), 3]))

Series
  (2,
   [(10/03/2020 00:00:00, 3); (10/04/2020 00:00:00, 4); (10/05/2020 00:00:00, 8)])

Here is a graphical representation:

         Initial   2020-10-3    4   5
x:          0              1    -   5
y:          2              2    3   -
result:     2              3    4   8

We define apply and the two operators as we did for option:

 let apply f x = map2 basicApply f x
 let (<!>) = map
 let (<*>) = apply

And we can use it with a user

 type User =
     { FirstName: string
       LastName: string
       Age: int
       FavoriteLanguage: string }
 let user firstname lastname age favoriteLang =
     { FirstName = firstname
       LastName = lastname
       Age = age
       FavoriteLanguage = favoriteLang } 

 let birthDate = DateTime(1978,10,01) 
 user
    <!> always "John"
    <*> Series("Dow", [ DateTime(2010,08,17), "Snow"]) // married
    <*> Series(0, [for y in 1 .. 42 -> birthDate.AddYears(y), y ])
    <*> Series("C#", [DateTime(2005,05,01), "F#"])

The result is a Series of User with the new values on each change.

We can now take any function that works on non-Series values, and apply it to Series of values. This is especially useful with hotels data. Hotels define prices, availability, closures and all other properties for their rooms for each night in a calendar. Each property can be modeled as a Series.

Let's compute the potential sells for a room:

 let potentialSells availability price closed =
     if closed then
         0m
     else
         decimal availability * price

This function has no notion of time and Series.

Now we want to apply it for every nights:

 let availability = 
    Series(0, [ DateTime(2020,10,03), 5
                DateTime(2020,10,07), 3
                DateTime(2020,10,09), 0])
 let price =
    Series(100m, [ DateTime(2020,10,04), 110m
                   DateTime(2020,10,06), 100m ])
 let closed =
    Series(false, [DateTime(2020,10,5), true
                   DateTime(2020,10,6), false])
 potentialSells
 <!> availability
 <*> price
 <*> closed

Series
  (0M,
   [(10/03/2020 00:00:00, 500M); (10/04/2020 00:00:00, 550M);
    (10/05/2020 00:00:00, 0M); (10/06/2020 00:00:00, 500M);
    (10/07/2020 00:00:00, 300M); (10/09/2020 00:00:00, 0M)])

Just imagine the headache if we did not have this applicative..

Queries

The first two examples were structures that "contain" data. For this third case, we'll consider a different problem.

We have a document store - like elastic search - where we can query documents and request specific properties for the returned document. For instance in the query for a user we ask for the "firstname", "lastname" and "age" properties and we get these properties in the result.

For the demo we'll use a simple function:

 let queryService (properties: string Set) : Map<string,string> =
    Map.ofList [
        if Set.contains "firstname" properties then
            "firstname", "John"
        if Set.contains "lastname" properties then
            "lastname", "Doe"
        if Set.contains "age" properties then
            "age", "42"
        if Set.contains "favoritelanguage" properties then
            "favoritelanguage", "F#"
    ]

The real one would take a document id and actually call the document database.

Despite being very useful (we get only the properties we're interested in), this kind of interface often leads to irritating bugs. When accessing the result, we must be sure that all the properties we use have been correctly requested. And when we stop using a property, we should not forget to remove it from the query.

That would be awesome if we could just use the properties and the query would magically know which one to fetch.

Let's introduce the Query type:

 type Query<'t> =
    { Properties: string Set
      Get: Map<string,string> -> 't }

This type is exactly here to do what we want. It contains a list of properties to query and a function that uses the result to extract a value from it. We have to create simple ways to build it safely.

The first thing is to be able to query a single property

 let prop name : Query<string> =
      { Properties = set [ name ]
        Get = fun response -> response.[name] }

This function takes a property name and builds a Query that:

has the expected property name in Properties
can extract this property from the result

We can define stock properties like using the prop function:

 let firstname = prop "firstname"
 let lastname = prop "lastname"
 let favoriteLanguage = prop "favoritelanguage"

We can fetch them with the following function:

 let callService (query: Query<'t>) : 't =
    let response = queryService query.Properties
    query.Get response

For age, we'd like to convert it to an int. This is easily done with a map function that will change the result using a given function

 let map (f: 'a -> 'b) (q: Query<'a>) : Query<'b> =
     { Properties = q.Properties
       Get = fun response ->
               let v = q.Get response
               f v }

 let (<!>) = map

 let age = int <!> prop "age"

Building a full name could be done like that (it can be more complicated):

 let fullname firstname lastname =
     firstname + " " + lastname

We need to retrieve both first name and last name and pass them to the function. But we can also make a map2:

 let map2 (f: 'a -> 'b -> 'c) (x: Query<'a>) (y: Query<'b>) : Query<'c> =
    { Properties = x.Properties + y.Properties
      Get = fun response ->
               let xvalue = x.Get response
               let yvalue = y.Get response
               f xvalue yvalue 
    }

The result is a Query that:

has the union of the properties of both queries
gets values from both and passes them to the given function

With a map2, we can define apply and the operator:

 let apply f x = map2 basicApply f x
 let (<*>) = apply

With this we can query a user:

 type User =
     { FirstName: string
       LastName: string
       Age: int
       FavoriteLanguage: string }
 let user firstname lastname age favoriteLang =
     { FirstName = firstname
       LastName = lastname
       Age = age
       FavoriteLanguage = favoriteLang } 
 
 let userQuery =
     user
     <!> firstname
     <*> lastname
     <*> age
     <*> favoriteLanguage

 callService userQuery

using userQuery, we just composed basic properties to form a query for a larger structure, so we know that we cannot use a property without requesting it in the query.

Other applicatives

Applicatives can be found in a lot of places. To zip lists, execute async computations in parallel.

It can also be used to create formlets. A Formlet<'t> is a UX form to fill a 't structure. The simples formlet are input fields. A text input is a Formlet<string>, a checkbox a Formlet<bool>. A label function is a (string -> Formlet<'a> -> Formlet<'a>) function that adds a label to an existing formlet. A map function can change Formlet<string> to Formlet<Address> given a (string -> Address) function. And we use map2 and apply to take several formlets and compose them in a Formlet<User> for instance.

Once you start to see it, you'll spot them everywhere.

Be careful to not abuse it. For a single use, it's often better to compute the result directly.

But when you have many places that are impacted, especially if the code changes often, it can reduce code complexity by a fair amount.

Don't hesitate to ping me on twitter if you find nice uses of applicatives!

As suggested by Chet Husk, I'll soon post about the new Applicatives support in Computation Expressions.

val basicApply: f: ('a -> 'b) -> x: 'a -> 'b

val f: ('a -> 'b)

val x: 'a

Multiple items
module Option from Microsoft.FSharp.Core

--------------------
type Option<'t> = | Some of 't | None

union case Option.Some: Value: 'T -> Option<'T>

union case Option.None: Option<'T>

val map: f: ('a -> 'b) -> x: Option<'a> -> Option<'b>

val x: Option<'a>

union case Option.Some: 't -> Option<'t>

val value: 'a

union case Option.None: Option<'t>

module Option from Microsoft.FSharp.Core

val map2: f: ('a -> 'b -> 'c) -> x: Option<'a> -> y: Option<'b> -> Option<'c>

val f: ('a -> 'b -> 'c)

val y: Option<'b>

val xvalue: 'a

val yvalue: 'b

val add: x: int -> y: int -> int

val x: int

val y: int

val mappedAdd: (Option<int> -> Option<(int -> int)>)

Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int

val apply: f: Option<('a -> 'b)> -> x: Option<'a> -> Option<'b>

val f: Option<('a -> 'b)>

val partialAdd: Option<(int -> int)>

type User = { FirstName: string LastName: string Age: int FavoriteLanguage: string }

Multiple items
val string: value: 'T -> string

--------------------
type string = System.String

val user: firstname: string -> lastname: string -> age: int -> favoriteLang: string -> User

val firstname: string

val lastname: string

val age: int

val favoriteLang: string

val user': Option<(string -> int -> string -> User)>

val user'': Option<(int -> string -> User)>

val user''': Option<(string -> User)>

val map2: f: ('a -> 'b -> 'c) -> xresult: Result<'a,string> -> yresult: Result<'b,string> -> Result<'c,string>

val xresult: Result<'a,string>

val yresult: Result<'b,string>

union case Result.Ok: ResultValue: 'T -> Result<'T,'TError>

val y: 'b

union case Result.Error: ErrorValue: 'TError -> Result<'T,'TError>

val fe: string

val xe: string

val apply: f: Result<('a -> 'b),string> -> x: Result<'a,string> -> Result<'b,string>

val f: Result<('a -> 'b),string>

val x: Result<'a,string>

val map: mapping: ('T -> 'U) -> result: Result<'T,'TError> -> Result<'U,'TError>

namespace System

val notEmpty: prop: string -> value: string -> Result<string,string>

val prop: string

val value: string

String.IsNullOrEmpty(value: string) : bool

val sprintf: format: Printf.StringFormat<'T> -> 'T

val tryParse: prop: string -> input: string -> Result<int,string>

val input: string

[<Struct>] type Int32 = member CompareTo: value: int -> int + 1 overload member Equals: obj: int -> bool + 1 overload member GetHashCode: unit -> int member GetTypeCode: unit -> TypeCode member ToString: unit -> string + 3 overloads member TryFormat: utf8Destination: Span<byte> * bytesWritten: byref<int> * ?format: ReadOnlySpan<char> * ?provider: IFormatProvider -> bool + 1 overload static member Abs: value: int -> int static member BigMul: left: int * right: int -> int64 static member Clamp: value: int * min: int * max: int -> int static member CopySign: value: int * sign: int -> int ...
<summary>Represents a 32-bit signed integer.</summary>

Int32.TryParse(s: string, result: byref<int>) : bool
Int32.TryParse(s: ReadOnlySpan<char>, result: byref<int>) : bool
Int32.TryParse(utf8Text: ReadOnlySpan<byte>, result: byref<int>) : bool
Int32.TryParse(s: string, provider: IFormatProvider, result: byref<int>) : bool
Int32.TryParse(s: ReadOnlySpan<char>, provider: IFormatProvider, result: byref<int>) : bool
Int32.TryParse(utf8Text: ReadOnlySpan<byte>, provider: IFormatProvider, result: byref<int>) : bool
Int32.TryParse(s: string, style: Globalization.NumberStyles, provider: IFormatProvider, result: byref<int>) : bool
Int32.TryParse(s: ReadOnlySpan<char>, style: Globalization.NumberStyles, provider: IFormatProvider, result: byref<int>) : bool
Int32.TryParse(utf8Text: ReadOnlySpan<byte>, style: Globalization.NumberStyles, provider: IFormatProvider, result: byref<int>) : bool

Multiple items
val string: value: 'T -> string

--------------------
type string = String

val value: int

Multiple items
union case Series.Series: 'a * (DateTime * 'a) list -> Series<'a>

--------------------
type Series<'a> = | Series of 'a * (DateTime * 'a) list

type Series<'a> = | Series of 'a * (DateTime * 'a) list

Multiple items
[<Struct>] type DateTime = new: date: DateOnly * time: TimeOnly -> unit + 16 overloads member Add: value: TimeSpan -> DateTime member AddDays: value: float -> DateTime member AddHours: value: float -> DateTime member AddMicroseconds: value: float -> DateTime member AddMilliseconds: value: float -> DateTime member AddMinutes: value: float -> DateTime member AddMonths: months: int -> DateTime member AddSeconds: value: float -> DateTime member AddTicks: value: int64 -> DateTime ...
<summary>Represents an instant in time, typically expressed as a date and time of day.</summary>

--------------------
DateTime ()
   (+0 other overloads)
DateTime(ticks: int64) : DateTime
   (+0 other overloads)
DateTime(date: DateOnly, time: TimeOnly) : DateTime
   (+0 other overloads)
DateTime(ticks: int64, kind: DateTimeKind) : DateTime
   (+0 other overloads)
DateTime(date: DateOnly, time: TimeOnly, kind: DateTimeKind) : DateTime
   (+0 other overloads)
DateTime(year: int, month: int, day: int) : DateTime
   (+0 other overloads)
DateTime(year: int, month: int, day: int, calendar: Globalization.Calendar) : DateTime
   (+0 other overloads)
DateTime(year: int, month: int, day: int, hour: int, minute: int, second: int) : DateTime
   (+0 other overloads)
DateTime(year: int, month: int, day: int, hour: int, minute: int, second: int, kind: DateTimeKind) : DateTime
   (+0 other overloads)
DateTime(year: int, month: int, day: int, hour: int, minute: int, second: int, calendar: Globalization.Calendar) : DateTime
   (+0 other overloads)

type 'T list = List<'T>

val always: x: 'a -> Series<'a>

val map: f: ('a -> 'b) -> Series<'a> -> Series<'b>

val initial: 'a

val changes: (DateTime * 'a) list

val map: mapping: ('T -> 'U) -> list: 'T list -> 'U list

val d: DateTime

val v: 'a

val map2: f: ('a -> 'b -> 'c) -> Series<'a> -> Series<'b> -> Series<'c>

val ix: 'a

val cx: (DateTime * 'a) list

val iy: 'b

val cy: (DateTime * 'b) list

val zip: lastx: 'a -> lasty: 'b -> changesx: ('d * 'a) list -> changesy: ('d * 'b) list -> ('d * 'c) list (requires comparison)

val lastx: 'a

val lasty: 'b

val changesx: ('d * 'a) list (requires comparison)

val changesy: ('d * 'b) list (requires comparison)

val d: 'd (requires comparison)

val dx: 'd (requires comparison)

val tailx: ('d * 'a) list (requires comparison)

val dy: 'd (requires comparison)

val taily: ('d * 'b) list (requires comparison)

val apply: f: Series<('a -> 'b)> -> x: Series<'a> -> Series<'b>

val f: Series<('a -> 'b)>

val x: Series<'a>

val birthDate: DateTime

DateTime.AddYears(value: int) : DateTime

val potentialSells: availability: int -> price: decimal -> closed: bool -> decimal

val availability: int

val price: decimal

val closed: bool

Multiple items
val decimal: value: 'T -> decimal (requires member op_Explicit)

--------------------
type decimal = Decimal

--------------------
type decimal<'Measure> = decimal

val availability: Series<int>

val price: Series<decimal>

val closed: Series<bool>

module Queries from 2020-10-03-applicatives-irl

val queryService: properties: Set<string> -> Map<string,string>

val properties: Set<string>

val ofList: elements: ('Key * 'T) list -> Map<'Key,'T> (requires comparison)

val contains: element: 'T -> set: Set<'T> -> bool (requires comparison)

type Query<'t> = { Properties: Set<string> Get: (Map<string,string> -> 't) }

val prop: name: string -> Query<string>

val name: string

val set: elements: 'T seq -> Set<'T> (requires comparison)

val response: Map<string,string>

val firstname: Query<string>

val lastname: Query<string>

val favoriteLanguage: Query<string>

val callService: query: Query<'t> -> 't

val query: Query<'t>

Query.Properties: Set<string>

Query.Get: Map<string,string> -> 't

val map: f: ('a -> 'b) -> q: Query<'a> -> Query<'b>

val q: Query<'a>

Query.Get: Map<string,string> -> 'a

val age: Query<int>

val fullname: firstname: string -> lastname: string -> string

val map2: f: ('a -> 'b -> 'c) -> x: Query<'a> -> y: Query<'b> -> Query<'c>

val x: Query<'a>

val y: Query<'b>

Query.Get: Map<string,string> -> 'b

val apply: f: Query<('a -> 'b)> -> x: Query<'a> -> Query<'b>

val f: Query<('a -> 'b)>

val userQuery: Query<User>