Free programs: logic that names its operations
A free program describes what to do as a list of instructions and leaves how to do it to an
interpreter. The same program can run against real services, against fixed answers in a test, or
as a durable workflow. The types are in the FCQRS.Model.FreeMonad module of the FCQRS.Model
package, which also compiles with Fable.
Start with the instructions
An order reserves stock and charges the customer. Each operation it needs is a case of an instruction type:
Shared setup
open System
open System.Threading.Tasks
open FCQRS.Model.FreeMonad
SystemThreadingTasksFCQRSModelFCQRS.Model.FreeMonadtype OrderInstruction =
| Reserve of order: string
| Charge of amount: decimal
let reserve order : Free<OrderInstruction, Result<string, string>> =
Eff.perform (Reserve order)
let charge amount : Free<OrderInstruction, Result<string, string>> =
Eff.perform (Charge amount)
Fcqrs_450-concepts_014-free-programs.md_page.OrderInstructionReserveorder: stringstringAn abbreviation for the CLI type . Basic Types
Chargeamount: decimaldecimalAn abbreviation for the CLI type . Basic Types
reserve: string -> Free<OrderInstruction,Result<string,string>>FCQRS.Model.FreeMonad.Free`2Microsoft.FSharp.Core.FSharpResult`2Helper type for error handling without exceptions. Choices and Results
FCQRS.Model.FreeMonad.Effperform: 'I -> Free<'I,'X>charge: decimal -> Free<OrderInstruction,Result<string,string>>Eff.perform makes a program of one instruction. Its result is the interpreter's answer, read as
the type the function declares: reserve expects a Result<string, string>. Writing one typed
function per instruction keeps that type in one place.
Write the program
freeResult builds a program that gives a Result. A let! on an Error ends it:
let order (id: string) =
freeResult {
let! shelf = reserve id
let! receipt = charge 30m
return $"{shelf} {receipt}"
}
order: string -> Free<OrderInstruction,Result<string,string>>id: stringstringAn abbreviation for the CLI type . Basic Types
freeResult: FreeResultBuildershelf: stringreserve: string -> Free<OrderInstruction,Result<string,string>>receipt: stringcharge: decimal -> Free<OrderInstruction,Result<string,string>>order "A-1" calls no service. It gives a value of type
Free<OrderInstruction, Result<string, string>>: either Pure with a result, or Impure with the
next instruction and a function that takes the answer and gives the rest of the program. free
builds a program whose result is not a Result. Both builders take if, while, for,
try ... with, and try ... finally.
Run it with an interpreter
An interpreter answers each instruction and passes the answer, boxed, to the rest of the program. It is a loop over the two cases:
let rec run (answer: OrderInstruction -> obj) program =
match program with
| Pure result -> result
| Impure(instruction, next) -> run answer (next (answer instruction))
let fixedAnswers instruction =
match instruction with
| Reserve _ -> box (Ok "shelf-4": Result<string, string>)
| Charge _ -> box (Ok "receipt-9": Result<string, string>)
let result = run fixedAnswers (order "A-1")
// Ok "shelf-4 receipt-9"
run: (OrderInstruction -> obj) -> Free<OrderInstruction,'a> -> 'aanswer: OrderInstruction -> objFcqrs_450-concepts_014-free-programs.md_page.OrderInstructionobjAn abbreviation for the CLI type . Basic Types
program: Free<OrderInstruction,'a>Pureresult: 'aImpureinstruction: OrderInstructionnext: obj -> Free<OrderInstruction,'a>fixedAnswers: OrderInstruction -> objnullReservebox: 'T -> objnullBoxes a strongly typed value. The value to box. The boxed object. let x: int = 123 let obj1 = box x // obj1 is a generic object type unbox<int> obj1 // Evaluates to 123 (int) unbox<double> obj1 // Throws System.InvalidCastException
OkRepresents an OK or a Successful result. The code succeeded with a value of 'T.
Microsoft.FSharp.Core.FSharpResult`2Helper type for error handling without exceptions. Choices and Results
stringAn abbreviation for the CLI type . Basic Types
Chargeresult: Result<string,string>order: string -> Free<OrderInstruction,Result<string,string>>FCQRS.Model 6.2.0 and later ship this loop as Free.run, so a test writes
Free.run fixedAnswers (order "A-1"). An answer may be null there, which is how () and None
are boxed.
An interpreter for real services answers with a Task:
type IWarehouse =
abstract Reserve: order: string -> Task<Result<string, string>>
type IPayments =
abstract Charge: amount: decimal -> Task<Result<string, string>>
let live (warehouse: IWarehouse) (payments: IPayments) instruction =
task {
match instruction with
| Reserve id ->
let! reserved = warehouse.Reserve id
return box reserved
| Charge amount ->
let! charged = payments.Charge amount
return box charged
}
Fcqrs_450-concepts_014-free-programs.md_page.IWarehouseReserve: IWarehouse -> string -> Task<Result<string,string>>orderstringAn abbreviation for the CLI type . Basic Types
System.Threading.Tasks.Task`1Represents an asynchronous operation that can return a value. The type of the result produced by this .
Microsoft.FSharp.Core.FSharpResult`2Helper type for error handling without exceptions. Choices and Results
Fcqrs_450-concepts_014-free-programs.md_page.IPaymentsCharge: IPayments -> decimal -> Task<Result<string,string>>amountdecimalAn abbreviation for the CLI type . Basic Types
live: IWarehouse -> IPayments -> OrderInstruction -> Task<objnull>warehouse: IWarehousepayments: IPaymentsinstruction: OrderInstructiontask: TaskBuilderBuilds a task using computation expression syntax.
Reserveid: stringreserved: Result<string,string>Reserve: string -> Task<Result<string,string>>box: 'T -> objnullBoxes a strongly typed value. The value to box. The boxed object. let x: int = 123 let obj1 = box x // obj1 is a generic object type unbox<int> obj1 // Evaluates to 123 (int) unbox<double> obj1 // Throws System.InvalidCastException
Chargeamount: decimalcharged: Result<string,string>Charge: decimal -> Task<Result<string,string>>Free.runTask (live warehouse payments) (order id) runs the program with it and gives a
Task<Result<string, string>>. Free.runAsync does the same for an interpreter that answers with
an Async.
The program's code is the same in both cases. The services are arguments of the interpreter; the program never sees them.
What the types do not check
- An answer's type is checked when the program runs. On .NET, an answer of another type than the instruction's function declares raises an exception that names both types. Under Fable the answer is not checked, because JavaScript keeps no generic type to test.
- A program value shares its first block's state. A block's code up to its first instruction
runs when the block is built. A
let mutableor aforloop placed there belongs to the value, so a second run of the same value continues from the first run's state.orderis a function, so each call builds a fresh program; write programs that keep state the same way. - A program is sequential. One instruction follows another, and nothing runs in parallel unless an interpreter does it inside one instruction. An instruction can carry programs for the interpreter to run together, as Run instructions together shows.
Binds nested to any depth run in a loop on .NET, so a program that recurses below a let! neither
grows the stack nor slows down with depth. Under Fable, bind keeps a closure per level.
Next: Run a free-monad program as a workflow gives each instruction a durable workflow step.