Axial
Repository F# setup
open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Layers
open Axial.Console
open Axial.FileSystem
open Axial.Hosting
open Axial.Hosting.Browser
open Axial.Hosting.Node
open Axial.PlatformService
open Axial.State
open Axial.Telemetry
open Axial.Telemetry.JavaScript

Choosing an Approach

Axial has one dependency model: workflows read an explicit environment, reusable helpers name service contracts, and layers build the environment at the boundary.

Use this order:

  1. Use records plus Flow.envWith for most application code.
  2. Declare a per-service contract for reusable named services.
  3. Use Layer and Layer.provide to build environments and own resource cleanup.
  4. Use ServiceProvider.get only at .NET host edges where direct IServiceProvider lookup is intentional.

Default Shape

Plain F# records make dependencies visible and let tests supply fakes.

Show page setup
// Setup for the checked examples on this page.
open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Layers
open Axial.Console
open Axial.FileSystem
open Axial.Hosting
open Axial.Hosting.Browser
open Axial.Hosting.Node
open Axial.PlatformService
open Axial.State
open Axial.Telemetry
open Axial.Telemetry.JavaScript
/// Fails the docs test when an example's result differs from the value shown.
let shouldEqual expected actual =
    if actual <> expected then failwithf "Expected %A but got %A" expected actual
Verified
type Order = { Id: int }
type OrderError = DuplicateOrder of int

type IOrderRepo =
    abstract Save: Order -> Result<unit, OrderError>

type IEmailSender =
    abstract SendConfirmation: Order -> unit

type ApiDeps = { Orders: IOrderRepo; Email: IEmailSender }

let placeOrder (order: Order) : Flow<ApiDeps, OrderError, unit> =
    flow {
        let! orders = Flow.envWith _.Orders
        let! email = Flow.envWith _.Email
        do! orders.Save order
        email.SendConfirmation order
    }

A test supplies the same record with fakes:

Verified
type MemoryOrders() =
    let gate = obj()
    let mutable saved = []
    member _.Saved = lock gate (fun () -> List.rev saved)

    interface IOrderRepo with
        member _.Save order =
            lock gate (fun () ->
                if List.contains order.Id saved then
                    Error(DuplicateOrder order.Id)
                else
                    saved <- order.Id :: saved
                    Ok())

type MemoryEmail() =
    let gate = obj()
    let mutable sent = []
    member _.Sent = lock gate (fun () -> List.rev sent)

    interface IEmailSender with
        member _.SendConfirmation order = lock gate (fun () -> sent <- order.Id :: sent)
Verified
let orders = MemoryOrders()
let email = MemoryEmail()
let deps = { Orders = orders; Email = email }

placeOrder { Id = 1 } |> Flow.run deps |> shouldEqual (Exit.Success())
placeOrder { Id = 1 } |> Flow.run deps |> shouldEqual (Exit.Failure(Cause.Fail(DuplicateOrder 1)))
email.Sent |> shouldEqual [ 1 ]

Use a concrete record for the boundary. Add a named abstraction only when more than one implementation or caller needs it.

Service Contracts

Reusable helpers can ask for a named service without forcing every application to use the same record shape:

Verified
type IHasOrders =
    abstract OrderRepo: IOrderRepo

let orderRepo<'env, 'error when 'env :> IHasOrders> : Flow<'env, 'error, IOrderRepo> =
    Flow.envWith _.OrderRepo

let save (order: Order) : Flow<#IHasOrders, OrderError, unit> =
    flow {
        let! orders = orderRepo
        do! orders.Save order
    }

Any environment that implements IHasOrders can run save:

Verified
type CheckoutEnv =
    { Orders: IOrderRepo }
    interface IHasOrders with
        member this.OrderRepo = this.Orders
Verified
save { Id = 7 } |> Flow.run { Orders = MemoryOrders() } |> shouldEqual (Exit.Success())

Layers

Layers build explicit environments and own cleanup through Scope. Use layer { } when application startup needs to combine several services into one environment.

Verified
type AppEnv = { Runtime: BaseRuntime; Orders: IOrderRepo }

let ordersLayer : Layer<unit, OrderError, IOrderRepo> = Layer.succeed (MemoryOrders())

let appLayer : Layer<unit, OrderError, AppEnv> =
    layer {
        let! runtime = BaseRuntime.live |> Layer.widenError
        and! orders = ordersLayer

        return { Runtime = runtime; Orders = orders }
    }

Layer.provide builds the environment, runs the workflow in it, and releases whatever the layers acquired:

Verified
let saveInApp : Flow<AppEnv, OrderError, unit> = save { Id = 3 } |> Flow.localEnv (fun app -> { Orders = app.Orders })

saveInApp |> Layer.provide appLayer |> Flow.run () |> shouldEqual (Exit.Success())

Use layers when construction can fail, when resources need cleanup, or when a host container should be validated once at startup. Plain let! is sequential and dependent; sibling and! bindings are independent and use Layer.merge.

Tutorials

Start with App Record and Layers.

More Detail