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

Creating Flows

Flow.succeed creates a description that succeeds with a value, and Flow.fail one that fails with an expected, typed error. Neither runs until Flow.run starts it:

> let greeting () : Flow<string> = Flow.succeed "Hello";;
> Flow.run () (greeting ());;
> type LoadError = UserNotFound;;
> let missing () : Flow<LoadError, string> = Flow.fail UserNotFound;;
> Flow.run () (missing ());;
val it: Exit<string,Never> = Success "Hello"
val it: Exit<string,LoadError> = Failure (Fail UserNotFound)

Use Flow.fromTask or Flow.fromAsync when the operation comes from a Task- or Async-returning API and thrown exceptions are defects. Use an attempt constructor when thrown exceptions are expected interop failures that callers should handle:

> let path () = System.IO.Path.Combine(System.IO.Path.GetTempPath(), "axial-docs-message.txt");;
> System.IO.File.WriteAllText(path (), "Hello from a file");;
> let readText (file: string) : Flow<string> = Flow.fromTask (fun token -> System.IO.File.ReadAllTextAsync(file, token));;
> Flow.run () (readText (path ()));;
> match Flow.run () (readText (path () + ".missing")) with Exit.Failure (Cause.Die error) -> error.GetType().Name | _ -> "";;
> let attemptRead (file: string) : ExnFlow<string> = Flow.attemptTask (fun token -> System.IO.File.ReadAllTextAsync(file, token));;
> match Flow.run () (attemptRead (path () + ".missing")) with Exit.Failure (Cause.Fail error) -> error.GetType().Name | _ -> "";;
val it: unit = ()
val it: Exit<string,Never> = Success "Hello from a file"
val it: string = "FileNotFoundException"
val it: string = "FileNotFoundException"

The missing file shows the difference. fromTask reports the exception as a defect (Cause.Die); attemptTask places it in the typed error channel (Cause.Fail), where the caller is expected to handle it.

The Task and Async interop guide covers cancellation and all supported carriers.

Go Further

  • Flow construction reference lists every constructor and conversion.
  • Defects explains when an exception should remain a defect and when an attempt constructor is appropriate.