Tutorials on FsFlow

Tutorial: Explicit Dependencies First

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial starts one step before Flow<'env, 'error, 'value>. The point is to keep the domain shape obvious: define small interfaces, pass them explicitly, and compose a few operations before introducing an environment record.

Use this approach first when:

the workflow is still local to one feature
you want to prove the dependency boundaries before choosing an environment shape
you want the easiest possible tests

1. Define The Contract

open System
open System.Threading.Tasks
open FsFlow

type OrderId = OrderId of Guid

type Order =
    { Id: OrderId
      Email: string
      Total: decimal }

type PlaceOrderError =
    | InvalidEmail
    | OrderRejected of string
    | TimedOut
    | Cancelled

type IOrderRepository =
    abstract Save : Order -> Task<Result<unit, string>>

type IEmailSender =
    abstract SendConfirmation : Order -> Task

These interfaces are intentionally narrow. They represent what the workflow needs, not the full database or mail client API.

Tutorial: App Record

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial starts where Explicit Dependencies First leaves off.

The problem is not that explicit parameters are wrong. The problem is repetition:

every helper has to thread the same dependencies
adding one more dependency means touching many signatures
the execution boundary gets noisier as the feature grows

An app record solves that by bundling dependencies once at the boundary while keeping the workflow code explicit.

1. Start With The Same Interfaces

open System
open System.Threading.Tasks
open FsFlow

type OrderId = OrderId of Guid

type Order =
    { Id: OrderId
      Email: string
      Total: decimal }

type PlaceOrderError =
    | InvalidEmail
    | OrderRejected of string
    | AuditWriteFailed

type IOrderRepository =
    abstract Save : Order -> Task<Result<unit, string>>

type IEmailSender =
    abstract SendConfirmation : Order -> Task

type IAuditLog =
    abstract Write : string -> Task<Result<unit, unit>>

2. Bundle Them Once

type AppEnv =
    { Orders: IOrderRepository
      Email: IEmailSender
      Audit: IAuditLog }

Adding a third dependency is now an additive change to the environment record rather than a rewrite of every helper signature.

Tutorial: Runtime Operations

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial focuses on the operational helpers that sit around a workflow: timeout, retry, cancellation, annotations, and exception translation.

Use these helpers at the application boundary. They are not substitutes for domain rules.

A Small Workflow To Wrap

open System
open System.Threading
open FsFlow

type CheckoutError =
    | GatewayUnavailable
    | CheckoutTimedOut
    | CheckoutCancelled
    | ReceiptStoreFailed
    | UnexpectedGatewayFailure of string

let authorizeCard : Flow<unit, CheckoutError, string> =
    flow {
        do! Flow.Runtime.sleep (TimeSpan.FromMilliseconds 50)
        return "receipt-123"
    }

let storeReceipt (receiptId: string) : Flow<unit, CheckoutError, unit> =
    flow {
        do! Flow.Runtime.sleep (TimeSpan.FromMilliseconds 20)
        return ()
    }

let notifyCustomer (receiptId: string) : Flow<unit, CheckoutError, unit> =
    flow {
        do! Flow.Runtime.sleep (TimeSpan.FromMilliseconds 20)
        return ()
    }

let checkout : Flow<unit, CheckoutError, string> =
    flow {
        let! receiptId = authorizeCard
        do! storeReceipt receiptId
        do! notifyCustomer receiptId
        return receiptId
    }

Even in this tiny example there are already several composed steps. Runtime helpers answer how this execution should behave when one of those steps is slow, flaky, canceled, or throws.

Tutorial: Using Existing Services

Mon, 01 Jan 0001 00:00:00 +0000

FsFlow ships with a few reusable service packages such as clock, logging, environment variables, console, filesystem, HTTP, and process execution.

These are still explicit dependencies. The workflow only sees them when your environment provides them.

Build An Environment

open FsFlow
open FsFlow.Services.Core

type AppEnv =
    { Runtime: BaseRuntime }

    interface IHas<IClock> with
        member this.Service = this.Runtime.Clock

    interface IHas<ILog> with
        member this.Service = this.Runtime.Log

    interface IHas<IEnvironmentVariables> with
        member this.Service = this.Runtime.EnvironmentVariables

Use The Services

let loadMode : Flow<AppEnv, EnvironmentVariableError, string> =
    flow {
        let! now = Clock.utcDateTime
        let! mode = EnvironmentVariable.get "APP_MODE"
        do! Log.info $"[{now:O}] starting in mode {mode}"
        return mode
    }

The workflow does not know where the clock, logger, or environment variables came from. It only knows the service contracts.

Tutorial: Creating Reusable Services

Mon, 01 Jan 0001 00:00:00 +0000

Use a custom service when several workflows should depend on the same named contract without being tied to one concrete app record field name.

Define The Contract

open System.Threading.Tasks
open FsFlow

type IExchangeRates =
    abstract GetUsdToAud : unit -> Task<decimal>

Write A Reusable Helper

let priceInAud<'env, 'error when 'env :> IHas<IExchangeRates>>
    (usdAmount: decimal)
    : Flow<'env, 'error, decimal> =
    flow {
        let! rates = Service<IExchangeRates>.get()
        let! rate = rates.GetUsdToAud()
        return usdAmount * rate
    }

This helper no longer cares whether the caller stores the service in Rates, Runtime.ExchangeRates, or any other field. It only needs IHas<IExchangeRates>.

Provide An App Environment

type AppEnv =
    { Rates: IExchangeRates
      Region: string }

    interface IHas<IExchangeRates> with
        member this.Service = this.Rates

Use A Test Double

type FixedRates(rate: decimal) =
    interface IExchangeRates with
        member _.GetUsdToAud() = Task.FromResult rate

Now every workflow that depends on IExchangeRates can run against the same deterministic test implementation.

Tutorial: Layers

Mon, 01 Jan 0001 00:00:00 +0000

Layers are for construction time, not business logic time.

Use a layer when you need to:

build an environment from other services or config
fail during provisioning before the workflow starts
own resources that must be cleaned up exactly once
compose several independent startup steps in parallel

1. The Workflow Still Targets An Environment

open System
open System.Threading
open System.Threading.Tasks
open FsFlow

type IOrders =
    abstract Save : string -> Task<unit>

type IClock =
    abstract UtcNow : unit -> DateTimeOffset

type AppEnv =
    { Orders: IOrders
      Clock: IClock }

let saveOrder (orderId: string) : Flow<AppEnv, string, unit> =
    flow {
        let! env = Flow.env
        do! env.Orders.Save orderId
        let now = env.Clock.UtcNow()
        printfn "[%O] saved %s" now orderId
    }

The workflow still depends on AppEnv. Layers only change how AppEnv gets built.