Home on FsFlow

FsToolkit.ErrorHandling

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

FsToolkit.ErrorHandling

If you are coming from FsToolkit.ErrorHandling, you will find that FsFlow is orthogonal rather than a direct replacement. While both libraries help with result-based programming, FsFlow focuses on a unified execution model that carries environments and runtime policies.

The Model Difference

FsToolkit.ErrorHandling provides a broad toolbox of helpers for working with Result, AsyncResult, and TaskResult as separate, wrapped types.

FsFlow provides a single, scalable progression:

[Check](/reference/check/) -> [Result](/reference/result/) -> [Validation](/reference/validation/) -> [Flow](/reference/flow/)

In FsFlow, the environment and runtime concerns are baked into the computation, allowing you to write orchestration logic that remains agnostic of whether the underlying work is sync or async until it hits the application boundary.

Getting Started

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

Getting Started

FsFlow is a toolkit for building robust, Result-based programs in F#. It allows you to scale from simple validation logic to complex, effectful application boundaries using a single, unified mental model.

1. The Continuum of Logic

FsFlow is designed around a continuum. You should always use the simplest tool that satisfies your current requirement:

Pure Checks -> Result & Validation -> Flow

Pure Checks: Reusable predicates for basic validation.
Result & Validation: Domain logic that handles success or failure (either fail-fast or error-accumulating).
Flow: The application boundary where you need dependencies, async/task interop, logging, or cancellation.

2. Start with Checks and Results

Most logic starts pure. Use Check for reusable predicates and Result for domain logic.

Pure Checks

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

Pure Checks

Check<'value> is the foundation of FsFlow validation. It is a reusable predicate layer that returns Result<'value, unit>.

If the predicate is true, it returns Ok value.
If the predicate is false, it returns Error ().

By returning unit on failure, Check stays agnostic about your application’s error types. You decide what the error means at the boundary where you use it.

The Two Shapes of Check

Value-Preserving: Check<'value> - returns the input value on success.
```
let check = Check.notBlank // string -> Result<string, unit>
```

Gate: Check<unit> - returns unit on success (useful for yes/no questions).

let check = Check.okIf (age > 18) // unit -> Result<unit, unit>

Attaching Errors with `Check.orError`

Use Check.orError to turn a unit failure into a meaningful application error.

Ref (Atomic References)

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

Ref (Atomic References)

Ref<'T> is a handle to a mutable reference that can be updated atomically. It is the simplest way to manage shared state between multiple concurrent parts of your application.

Note: Ref is currently available on .NET only.

Why Use Ref?

In a functional program, state is usually passed as parameters or through the environment. However, some scenarios—like a shared counter, a cache, or a status flag—require multiple concurrent workflows to observe and update the same value.

Environment Slicing

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

Environment Slicing (The Record Pattern)

The Record Pattern is the most common way to manage dependencies in FsFlow. It uses standard F# records to define the “world” a workflow lives in.

Projecting from the Environment

When a workflow needs a dependency, it “reads” it from the environment record.

type AppEnv = 
    { Gateway: IPingGateway
      Logger: ILogger }

let ping =
    flow {
        // 'env' is the full AppEnv record
        let! gateway = Flow.read (fun env -> env.Gateway)
        return! gateway.Ping()
    }

The Shorthand: `_.Field`

F# provides a nice shorthand for these simple projections. Instead of (fun env -> env.Gateway), you can write _.Gateway. This makes the code much cleaner and easier to read.

Execution Semantics

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

Execution Semantics

This page shows the exact execution rules for Flow, including how a cold program becomes an Effect and resolves to an Exit.

FsFlow uses a unified Flow<'env, 'error, 'value> model that handles synchronous code, F# Async, and .NET Task interop natively.

Execution Shape

Conceptually, execution is:

Flow -> Effect -> Exit

More precisely:

Flow is the cold program you define.
Effect is the deferred runnable carrier.
Exit is the terminal outcome after execution.

Success and Typed Failure

Every Flow execution results in an Exit<'value, 'error>:

Result CE

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

Result CE

Use the result {} computation expression when you have a sequence of steps where each step depends on the previous one, and you want to stop at the first failure.

This is “fail-fast” semantics.

Basic Usage

The result {} builder binds standard F# Result<'value, 'error> types.

type UserError = | MissingName | MissingEmail

let validateUser name email =
    result {
        // If name is blank, it returns Error MissingName and stops.
        let! validName = name |> Check.notBlank |> Check.orError MissingName
        
        // This line only runs if the name was valid.
        let! validEmail = email |> Check.notBlank |> Check.orError MissingEmail
        
        return { Name = validName; Email = validEmail }
    }

Guarded Bindings

Guard is a powerful companion to result {}. It allows you to bind boolean or check-shaped sources directly while attaching an error value at the binding site.

Schedule (Retry & Repeat)

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

Schedule (Retry & Repeat)

The Schedule module provides a powerful DSL for describing policies that govern how and when a workflow should be executed again. You can use schedules to implement sophisticated retry strategies (like exponential backoff with jitter) or recurring tasks.

Note: Schedule is currently available on .NET only.

Basic Schedules

A schedule decides two things:

Whether to continue (recur).
How long to wait before the next attempt.

Fixed Number of Recursions

// Recur 5 times (6 attempts total)
let fiveTimes = Schedule.recurs 5

Fixed Spacing

// Recur indefinitely with 1 second between attempts
let everySecond = Schedule.spaced (TimeSpan.FromSeconds 1.0)

Exponential Backoff

// Delays: 100ms, 200ms, 400ms, 800ms...
let backoff = Schedule.exponential (TimeSpan.FromMilliseconds 100.0)

Adding Jitter

Jitter adds randomness to delays to prevent “thundering herd” problems in distributed systems. Schedule.jittered adds a random factor between 0.5x and 1.5x to the current delay.

Troubleshooting Types

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

Troubleshooting Types

This page shows the compiler errors that usually mean you crossed a wrapper boundary in the wrong place.

Most FsFlow type errors are not exotic. The compiler usually sees one wrapper shape and you intended another.

Error: A Unique Overload For Method `Bind` Could Not Be Determined

This usually happens when the compiler cannot tell which wrapper shape a let! value should use.

Example:

let nested : Async<Async<Result<int, string>>> =
    async {
        return async { return Ok 42 }
    }

let workflow : Flow<unit, string, int> =
    flow {
        let! next = nested
        let! value = next
        return value
    }

The second let! is ambiguous.

Validus Integration

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

Validus Integration

This page shows how FsFlow can fit beside Validus validation pipelines.

Validus is a strong choice when the problem is still validation, especially when you want a richer DSL, composition, accumulation, or value-object style checks.

FsFlow can usually begin after that work is done.

Validus and FsFlow.Check fit especially well together: Validus can handle richer validation rules, while FsFlow.Check stays available for smaller pure guards that feed directly into Result, Validation, or Flow.

The Guard

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

The Guard

The Guard is a bridge. It allows pure predicate checks and simple error-bearing sources (like Option or Result) to fail a computation with a specific domain error.

While builders like flow {} and result {} can bind many types directly, Guard is the primary tool for assigning a domain-specific error to a source or “unwrapping” an effectful source before validation.

Why do I need Guard?

Consider a simple user lookup. When it is a pure function, it works seamlessly with Check:

Benchmarks

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

Benchmarks

This page shows the performance tradeoffs of using FsFlow compared to manual result/async/task composition.

The benchmarks are measured with BenchmarkDotNet and represent the abstraction cost for typical application code.

Summary

abstraction cost is negligible for effectful code
cold execution for task-oriented computations adds small allocation overhead compared to hot ValueTask
performance is competitive with manual Async<Result<'T, 'E>> composition

Setup

All measurements were taken on:

.NET 8.0
Ubuntu 22.04
AMD Ryzen 9 5950X

Abstraction Cost

Measures a 20-step bind sequence where each step is pure. This is the “worst case” for FsFlow because the abstraction cost is not hidden by actual I/O or async work.

Capabilities (CAPS)

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

Capabilities (CAPS)

The CAPS pattern lets you decouple your workflows from specific record types. Instead of saying “I need the AppEnv record,” a workflow says “I need any environment that provides an IClock.”

This is achieved using the Needs<'dep> interface and the Env<'dep> request token.

Requesting a Dependency with `Env<'dep>`

In a CAPS workflow, you use the Env<'dep> token to request a dependency by its type. FsFlow handles finding that dependency in the environment for you.

IcedTasks Integration

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

IcedTasks Integration

This page shows how FsFlow can fit beside IcedTasks.

IcedTasks is a natural neighbor when the codebase already uses task computation expressions and cold or cancellable task helpers.

FsFlow does not need to replace that layer. It can add typed failure, environment threading, and boundary management where those concerns matter.

IcedTasks is especially interesting when you want task-native ergonomics and performance-sensitive helpers. FsFlow stays in the picture when you want to carry a typed result and an explicit environment together with the runtime shape.

STM (Software Transactional Memory)

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

STM (Software Transactional Memory)

Software Transactional Memory (STM) is a powerful concurrency primitive that allows you to combine multiple atomic operations into a single transaction.

While Ref is perfect for updating a single variable, STM is designed for scenarios where you need to update multiple variables consistently. FsFlow ensures that the entire transaction is executed atomically—either all changes are committed, or none are.

Note: STM is currently available on .NET only.

Straightforward Examples

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

Straightforward Examples

These examples show how to use FsFlow for common tasks without the overhead of a full application setup.

1. Simple Environment Access

Use Flow.read to project a single field from your environment record.

type Config = { ApiUrl: string }

let getUrl =
    flow {
        let! url = Flow.read _.ApiUrl
        return url
    }

let outcome = getUrl |> Flow.run { ApiUrl = "https://api.example.com" }
// outcome = Exit.Success "https://api.example.com"

2. Combining Pure Logic and Async Work

Use flow {} to mix pure Check logic, Async blocks, and other flows.

let validateId id =
    id |> okIf (id > 0) |> orError "Invalid ID"

let fetchUser id =
    async { return { Id = id; Name = "Ada" } }

let workflow id =
    flow {
        let! validId = validateId id
        let! user = fetchUser validId // Binds Async<'T> directly
        return user.Name
    }

let effect = workflow 42 |> Flow.run ()
// effect = Effect<string, string> (ValueTask or Async)

3. Retrying a Flow

Use the Schedule module to add operational policies like retries.

Task and Async Interop

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

Task and Async Interop

FsFlow provides a single, unified computation expression—flow {}—that handles synchronous code, F# Async, and .NET Task interop natively. You don’t have to choose between different builders; the same flow can orchestrate all these effect types.

Direct Binds

Inside a flow {} block, you can use let! to bind many common F# and .NET types directly. FsFlow handles the conversion to its internal execution model automatically.

Type	Outcome
`Flow<'env, 'error, 'value>`	Continues with the flow’s value.
`Result<'value, 'error>`	Continues on `Ok`, short-circuits on `Error`.
`Async<'value>`	Awaits the async and continues with the value.
`Async<Result<'value, 'error>>`	Awaits the async and handles the Result outcome.
`Task<'value>`	Awaits the task and continues with the value.
`Task<Result<'value, 'error>>`	Awaits the task and handles the Result outcome.
`ValueTask<'value>`	Awaits the value task and continues with the value.
`ValueTask<Result<'value, 'error>>`	Awaits and handles the Result outcome.

Example: Mixed Orchestration

let fetchUser (id: int) : Task<User> = ...
let validate (user: User) : Result<User, string> = ...
let saveUser (user: User) : Async<unit> = ...

let processUser id =
    flow {
        // Bind a .NET Task
        let! user = fetchUser id
        
        // Bind a Result
        let! validUser = validate user
        
        // Bind an F# Async
        do! saveUser validUser
        
        return "Done"
    }

Option and ValueOption

Option<'value> and ValueOption<'value> can also be bound directly, but only if the flow’s error type is unit.

Validate CE

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

Validate CE

Use the validate {} computation expression when you have multiple independent checks and you want to collect every failure into a single report.

While the standard result {} or flow {} blocks “fail fast” (stopping at the first error), validate {} continues checking even after a failure occurs. This is often called “accumulating” semantics.

Accumulating with `and!`

The key to accumulation is the and! keyword. Steps joined by and! are evaluated independently, and their errors are merged into a Diagnostics graph.

Architectural Styles

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

Architectural Styles

This page shows how the FsFlow workflow family should fit into your application architecture without forcing one app shape on every codebase.

FsFlow supports three valid architectural styles.

Three related workflow families. Three valid architectural styles. Choose based on app shape and team preferences.

1. Booted App Environment

Use this when your application already has a conventional booted runtime and passing one explicit application environment keeps composition simple.

Diagnostics Graph

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

Diagnostics Graph

Unlike many validation libraries that return a flat list of error strings, FsFlow returns a structured Diagnostics Graph. This allows you to represent exactly where in a complex data structure a failure occurred.

The Structure

The graph is a tree where each node can contain local errors and child branches.

type PathSegment =
    | Key of string    // A record field or property
    | Index of int     // A position in a list or sequence
    | Name of string   // A custom label for a validation branch

type Diagnostic<'error> =
    { Path: PathSegment list
      Error: 'error }

type Diagnostics<'error> =
    { Errors: 'error list
      Children: Map<PathSegment, Diagnostics<'error>> }

Creating Scoped Diagnostics

Inside a validate {} block, you use helpers to push diagnostics into the tree:

FSharpPlus Integration

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

FSharpPlus Integration

This page shows how FsFlow can fit beside codebases that already use FSharpPlus.

FSharpPlus is a broad functional base library. That makes it different from the more targeted integration stories like FsToolkit.ErrorHandling, Validus, and IcedTasks.

FsFlow can sit on top of that style where orchestration begins.

FSharpPlus is strongest when the codebase already relies on broad generic operations and monad transformer stacks. That strength comes with a cost: more compiler work, more abstraction to keep in your head, and error surfaces that can be harder to read when you are trying to understand a FsFlow boundary.

Stream (FlowStream)

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

Stream (FlowStream)

FlowStream<'env, 'error, 'value> represents a cold, pull-based asynchronous stream. Like Flow, a FlowStream requires an environment to run and can fail with a typed error. It is built on top of .NET’s IAsyncEnumerable, providing native support for backpressure and asynchronous iteration.

Note: FlowStream is currently available on .NET only.

Creating a Stream

From a Sequence

The simplest way to create a stream is from an existing seq.

let numbers = FlowStream.fromSeq [ 1 .. 10 ]

Transforming Streams

Mapping Values

You can transform the successful values in a stream using FlowStream.map.

Effect-TS Comparison

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

Effect-TS Comparison

This page shows FsFlow in relation to Effect-TS without pretending they solve the same problem at the same scale.

What Carries Over

These ideas are shared:

typed success and error channels
explicit dependency access
compositional workflow values
runtime helpers for retry, timeout, and cancellation-aware execution

What Is Different

FsFlow is aimed at ordinary F# application code:

flow {} instead of generator-based syntax, with direct binding for Async, Task, ValueTask, and ColdTask
first-class interop with Result, Async, and .NET Task
explicit environment reads such as Flow.read _.Gateway or Flow.read _.Gateway
a much smaller surface focused on application flows rather than a broader runtime platform

What Effect-TS Still Has That FsFlow Does Not

Effect-TS is much broader and more mature. FsFlow does not try to match:

FsFlow.CheckModule.all

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

Returns success when every check in the sequence succeeds.

Remarks

Sequentially evaluates each check in the checks sequence. Stops at the first failure.

Parameters

checks: A sequence of checks.

Returns

A Check that succeeds only if all inputs succeed.

FsFlow.CheckModule.and

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

Returns success when both checks succeed.

Remarks

This is a logical “and” operation. It short-circuits: if left fails, right is not evaluated.

Parameters

left: The first check.
right: The second check.

Returns

A Check that succeeds only if both inputs succeed.

FsFlow.CheckModule.any

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

Returns success when at least one check in the sequence succeeds.

Remarks

Sequentially evaluates each check in the checks sequence. Stops at the first success.

Parameters

checks: A sequence of checks.

Returns

A Check that succeeds if any input succeeds.

FsFlow.Flow.apply

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

Applies a flow-wrapped function to a flow-wrapped value.

FsFlow.ValidationModule.apply

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

Applies a validation-wrapped function to a validation-wrapped value.

Parameters

validation: The validation containing the function.
value: The validation containing the value.

Returns

The result of applying the function to the value, with accumulated errors.

FsFlow.ValidationModule.at

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

Scopes a validation under the supplied path segments.

Parameters

path: The path segments to apply to the validation.
validation: The validation to scope.

Returns

A validation nested under the given path.

FsFlow.STM.atomically

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

Executes an STM transaction atomically within a flow.

Parameters

transaction: The STM transaction to execute.

Returns

A flow that performs the transaction and returns its result.

FsFlow.Flow.bind

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

Sequences a synchronous continuation after a successful value.

Remarks

This is the “flatmap” operation for Flow. It allows for dependent steps where the second flow depends on the value produced by the first.

Parameters

binder: A function that takes the successful value and returns a new flow.
flow: The source flow to sequence.

Returns

A Flow representing the combined workflow.

FsFlow.ValidationModule.bind

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

Sequences a validation-producing continuation.

Remarks

This is the monadic “bind” for validation. Note that this operation short-circuits and does not accumulate errors from the binder if the source has already failed. For accumulation, use map2 or the applicative and! syntax.

Parameters

binder: A function of type 'value -> Validation<'next, 'error>.
validation: The source validation.

Returns

The result of the binder or the original diagnostics.

FsFlow.CheckModule.blank

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

Returns success when the string is blank.

Parameters

str: The string to check.

Returns

A Check that succeeds if the string is blank.

FsFlow.Flow.catch

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

Catches exceptions raised during execution and maps them to a typed error.

Remarks

Exceptions that are not caught by this helper will bubble up to the caller of run. This ensures that known exceptions can be handled within the flow context.

Parameters

handler: A function of type exn -> 'error to map the exception.
flow: The source flow of type Flow to monitor.

Returns

A Flow that converts exceptions into success-path errors.

FsFlow.Check

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

A reusable predicate result that either preserves a value on success or acts as a gate with unit on success, while carrying a unit failure placeholder until the caller maps it into a domain-specific error.

Remarks

Use the Check module helpers to create and compose checks.

FsFlow.ValidationModule.collect

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

Collects a sequence of validations into a single validation of a list.

Remarks

This operation is applicative: it will collect errors from ALL items in the sequence.

Parameters

validations: A sequence of type seq<Validation<'value, 'error>>.

Returns

A validation containing the list of values or accumulated diagnostics.

FsFlow.Flow.delay

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

Defers flow construction until execution time.

FsFlow.Caps.Core.EnvironmentVariableErrors.describe

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

Formats a human-readable description for an error.

FsFlow.Diagnostic

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

A single failure item attached to a path in a validation graph.

FsFlow.Diagnostics

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

A mergeable validation graph that carries local errors and nested child branches.

Remarks

`Errors` holds the application errors attached exactly to the current node, while `Children` holds nested branches keyed by `PathSegment`. This structure allows hierarchical validation to stay navigable before flattening. Use `flatten` to convert it into a linear list.

FsFlow.DiagnosticsModule.empty

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

Creates an empty diagnostics graph with no errors.

Returns

An empty Diagnostics.

FsFlow.Env

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

Request token for projecting a value from a dependency.

Remarks

Builders read the dependency from the environment, apply the projection, and then reuse the existing lift/bind behavior for the projected value. If the projection returns a Result, Async, Task, ValueTask, ColdTask, option, or voption, the existing workflow rules still apply.

Examples

type IClock =
     abstract UtcNow : unit -&gt; DateTimeOffset

 type ClockCaps =
     inherit Needs&lt;IClock&gt;
     abstract Clock : IClock

 let readClockNow : Flow&lt;#ClockCaps, unit, DateTimeOffset&gt; =
     flow {
         let! now = Env&lt;IClock&gt; _.UtcNow
         return now
     }

FsFlow.Flow.env

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

Reads the current environment as the flow value.

Remarks

Use this when the entire environment object is needed for the next step of the workflow. For projecting specific properties, read is generally more ergonomic.

Returns

A Flow whose successful value is the current environment.

FsFlow.CapabilityModule.environment

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

Reads the application environment from the environment.

FsFlow.Caps.Core.EnvironmentVariableError

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

Describes a meaningful environment-variable failure.

FsFlow.CheckModule.equal

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

Returns success when the values are equal.

Parameters

expected: The expected value.
actual: The actual value.

Returns

A Check that succeeds if the values are equal.

FsFlow.Flow.error

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

Creates a failing synchronous flow.

FsFlow.ValidationModule.error

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

Creates a failing validation result with the provided diagnostics.

Parameters

diagnostics: The Diagnostics graph.

Returns

A failing Validation.

FsFlow.Caps.Process.ProcessModule.execute

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

Executes a process using the process environment and returns the result.

FsFlow.Caps.FileSystem.FileSystemModule.exists

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

Checks if a file exists using the file system environment.

FsFlow.ScheduleModule.exponential

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

Creates a schedule that recurs with exponential backoff.

FsFlow.Flow.fail

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

Alias for error that reads well in some call sites.

Examples

let flow = Flow.fail "error"
 let result = Flow.run () flow
 // result = Failure (Cause.Fail "error")

FsFlow.ValidationModule.fail

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

Alias for error.

Parameters

diagnostics: The Diagnostics graph.

Returns

A failing Validation.

FsFlow.CheckModule.failIf

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

Returns success when the condition is false.

Parameters

cond: The boolean condition to check.

Returns

A Check that succeeds if cond is false.

FsFlow.CheckModule.failIfBlank

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

Returns the string when it is blank.

Parameters

str: The string to check.

Returns

A Check containing the blank string.

FsFlow.CheckModule.failIfEmpty

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

Returns the sequence when it is not empty.

Parameters

coll: The sequence to check.

Returns

A Check containing the non-empty sequence.

FsFlow.CheckModule.failIfEmptyStr

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

Returns the string when it is null or empty.

Parameters

str: The string to check.

Returns

A Check containing the empty or null string.

FsFlow.CheckModule.failIfEqual

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

Returns success when the values are equal.

Parameters

expected: The expected value.
actual: The actual value.

Returns

A Check that succeeds if the values are equal.

FsFlow.CheckModule.failIfNone

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

Returns the value when the option is Some.

Parameters

opt: The option to check.

Returns

A Check containing the value if present.

FsFlow.CheckModule.failIfNonEmptyStr

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

Returns success when the string is null or empty.

Parameters

str: The string to check.

Returns

A Check that succeeds if the string is null or empty.

FsFlow.CheckModule.failIfNotBlank

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

Returns success when the string is blank.

Parameters

str: The string to check.

Returns

A Check that succeeds if the string is blank.

FsFlow.CheckModule.failIfNotEmpty

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

Returns success when the sequence is empty.

Parameters

coll: The sequence to check.

Returns

A Check that succeeds if the sequence is empty.

FsFlow.CheckModule.failIfNotEqual

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

Returns success when the values are not equal.

Parameters

expected: The expected value.
actual: The actual value.

Returns

A Check that succeeds if the values differ.

FsFlow.CheckModule.failIfNotNull

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

Returns success when the value is null.

Parameters

value: The value to check.

Returns

A Check that succeeds if the value is null.

FsFlow.CheckModule.failIfNull

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

Returns the value when it is null.

Parameters

value: The value to check.

Returns

A Check containing the null value.

FsFlow.CheckModule.failIfSome

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

Returns success when the option is None.

Parameters

opt: The option to check.

Returns

A Check that succeeds if the option is None.

FsFlow.CheckModule.failIfValueNone

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

Returns the value when the value option is ValueSome.

Parameters

opt: The value option to check.

Returns

A Check containing the value if present.

FsFlow.CheckModule.failIfValueSome

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

Returns success when the value option is ValueNone.

Parameters

opt: The value option to check.

Returns

A Check that succeeds if the value option is ValueNone.

FsFlow.Fiber

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

Represents a handle to a running workflow.

FsFlow.DiagnosticsModule.flatten

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

Flattens the structured diagnostics graph into a linear list of diagnostics.

Remarks

During flattening, child paths are accumulated from the root down into each emitted diagnostic. The tree itself stores only local errors and child branches, while Diagnostic is reserved for reporting output.

Parameters

graph: The Diagnostics to flatten.

Returns

A list of type Diagnostic list.

FsFlow.Builders.flow

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

The universal flow { } computation expression.

Remarks

Use this builder when the boundary can mix synchronous values, `Async`, `Task`, `Result`, and environment requests while keeping typed failures and explicit dependency access. It preserves the current environment model while allowing the workflow to compose task-oriented inputs directly, so callers do not need to switch builders just to cross an async boundary.

Examples

 let greeting =
     flow {
         let! name = Flow.env
         let! suffix = async { return "!" }
         return $"Hello, {name}{suffix}"
     }

FsFlow.Flow

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

Represents a cold workflow that reads an environment, returns a typed result, and is executed explicitly through Flow.run.

flow { }

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

The flow { } builder is the primary entry point for orchestrating synchronous, async, and task-based work.

Builder

FsFlow.Builders.flow: The universal flow { } computation expression.

FsFlow.FlowStream

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

Represents a cold stream of values that requires an environment, can fail with a typed error, and supports backpressure.

FsFlow.Flow.fork

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

Starts a flow in a new fiber without waiting for it to complete.

Parameters

flow: The flow to fork.

Returns

A flow that produces a Fiber handle.

FsFlow.Flow.fromOption

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

Lifts an option into a synchronous flow with the supplied error.

Examples

let opt = Some "value"
 let flow = Flow.fromOption "missing" opt

FsFlow.Caps.Core.EnvironmentVariables.fromPairs

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

Creates a deterministic provider from a fixed set of name/value pairs.

FsFlow.CheckModule.fromPredicate

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

Builds a check from a predicate while preserving the successful value.

Parameters

predicate: A function of type 'value -> bool to test the value.
value: The value of type 'value to check.

Returns

A Check containing the value if the predicate succeeds.

FsFlow.Flow.fromResult

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

Lifts a Result into a synchronous flow.

Examples

let res = Ok "success"
 let flow = Flow.fromResult res

FsFlow.ValidationModule.fromResult

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

Lifts a standard Result into the Validation context.

Remarks

If the result is an error, it is wrapped in a root-level Diagnostics graph.

Parameters

result: The result to lift.

Returns

A Validation mirroring the result.

FsFlow.FlowStreamModule.fromSeq

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

Creates a stream from a sequence of values.

FsFlow.Caps.Core.Clock.fromValue

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

Creates a deterministic clock that always returns the supplied instant.

FsFlow.Caps.Core.Guid.fromValue

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

Creates a deterministic GUID generator that always returns the supplied value.

FsFlow.Caps.Core.Random.fromValue

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

Creates a deterministic random generator that always returns the supplied value.

FsFlow.Flow.fromValueOption

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

Lifts a value option into a synchronous flow with the supplied error.

Parameters

error: The error to return if the value option is ValueNone.
value: The value option to lift.

Returns

A Flow that succeeds with the option’s value or fails with the provided error.

FsFlow.Caps.Core.EnvironmentVariable.get

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

Reads a raw string environment variable from the environment.

FsFlow.RefModule.get

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

Reads the current value of the reference.

FsFlow.TRefModule.get

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

Reads the current value of the transactional reference within a transaction.

FsFlow.Caps.Core.EnvironmentVariable.getBool

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

Reads a boolean environment variable from the environment.

FsFlow.Caps.Core.EnvironmentVariable.getGuid

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

Reads a GUID environment variable from the environment.

FsFlow.Caps.Core.EnvironmentVariable.getInt

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

Reads an integer environment variable from the environment.

FsFlow.Caps.Http.HttpModule.getString

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

Sends a GET request using the HTTP environment and returns the response body.

FsFlow.Caps.Core.IClock

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

Provides synchronous access to the current UTC clock.

FsFlow.Caps.Console.IConsole

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

Provides synchronous access to standard console I/O.

FsFlow.Caps.Core.IEnvironmentVariables

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

Provides synchronous environment-variable lookup.

FsFlow.Caps.FileSystem.IFileSystem

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

Provides synchronous access to file system operations.

FsFlow.Flow.ignore

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

Maps the successful value of a synchronous flow to unit.

FsFlow.ValidationModule.ignore

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

Maps a successful validation value to unit while preserving the diagnostics.

Parameters

validation: The source validation.

Returns

A validation that keeps the original diagnostics and discards the success value.

FsFlow.Caps.Core.IGuid

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

Provides synchronous GUID generation.

FsFlow.Caps.Http.IHttp

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

Provides asynchronous access to HTTP client operations.

FsFlow.ValidationModule.index

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

Prefixes a validation with an indexed branch.

Parameters

index: The branch index.
validation: The validation to scope.

Returns

A validation whose diagnostics are prefixed with Index index.

FsFlow.Flow.interrupt

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

Signals a fiber to stop and waits for it to finish its cleanup.

Parameters

fiber: The fiber to interrupt.

Returns

A flow that completes with the fiber’s final outcome after interruption.

FsFlow.Caps.Process.IProcess

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

Provides asynchronous access to external process execution.

FsFlow.Caps.Core.IRandom

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

Provides synchronous random-number generation.

FsFlow.ScheduleModule.jittered

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

Adds random jitter to a schedule’s delay.

FsFlow.Flow.join

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

Waits for a fiber to complete and returns its final outcome.

Parameters

fiber: The fiber to join.

Returns

A flow that completes with the fiber’s outcome.

FsFlow.ValidationModule.key

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

Prefixes a validation with a keyed branch.

Parameters

key: The branch key.
validation: The validation to scope.

Returns

A validation whose diagnostics are prefixed with Key key.

FsFlow.Caps.Console.ConsoleModule.live

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

Creates a live console backed by Console.

FsFlow.Caps.Core.Clock.live

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

Creates a live clock backed by UtcNow.

FsFlow.Caps.Core.EnvironmentVariables.live

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

Creates a live provider backed by the current process environment.

FsFlow.Caps.Core.Guid.live

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

Creates a live GUID generator backed by NewGuid.

FsFlow.Caps.Core.Random.live

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

Creates a live random-number generator backed by Random.

FsFlow.Caps.FileSystem.FileSystemModule.live

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

Creates a live file system backed by File.

FsFlow.Caps.Http.HttpModule.live

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

Creates a live HTTP client backed by HttpClient.

FsFlow.Caps.Process.ProcessModule.live

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

Creates a live process runner backed by Process.

FsFlow.Flow.localEnv

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

Transforms the environment before running the flow.

FsFlow.RefModule.make

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

Creates a new Ref with the initial value.

FsFlow.TRefModule.make

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

Creates a new TRef with the initial value.

FsFlow.Flow.map

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

Maps the successful value of a synchronous flow.

Remarks

If the source flow fails, the mapper is not executed, and the error is preserved. This allows for safe transformation of data within the flow.

Parameters

mapper: A function of type 'value -> 'next to transform the successful value.
flow: The source flow of type Flow to transform.

Returns

A new Flow with the transformed success value of type 'next.

FsFlow.FlowStreamModule.map

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

Maps the successful values of a stream.

FsFlow.ValidationModule.map

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

Maps the successful value of a validation.

Parameters

mapper: A function of type 'value -> 'next.
validation: The source Validation.

Returns

A validation with the transformed success value.

FsFlow.Flow.map2

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

Combines two flows with a mapping function.

FsFlow.ValidationModule.map2

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

Combines two validations, accumulating errors if both fail.

Remarks

This is the core applicative operation. If both left and right fail, their diagnostics graphs are merged.

Parameters

mapper: A function of type 'left -> 'right -> 'value.
left: The first validation.
right: The second validation.

Returns

A validation with the combined result.

FsFlow.Flow.map3

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

Combines three flows with a mapping function.

FsFlow.ValidationModule.map3

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

Combines three validations, accumulating errors when any input fails.

Parameters

mapper: A function of type 'left -> 'middle -> 'right -> 'value.
left: The first validation.
middle: The second validation.
right: The third validation.

Returns

A validation with the combined result.

FsFlow.Flow.mapError

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

Maps the error value of a synchronous flow.

Remarks

Transforms the error type of the flow while leaving successful values untouched. Useful for mapping internal errors into public-facing domain errors.

Parameters

mapper: The function to transform the error value.
flow: The source flow.

Returns

A Flow with the transformed error type.

FsFlow.ValidationModule.mapError

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

Maps the error type of a validation graph.

Parameters

mapper: A function of type 'error -> 'nextError.
validation: The source Validation.

Returns

A validation with transformed error values.

FsFlow.DiagnosticsModule.merge

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

Recursively merges two diagnostics graphs, combining shared branches and local errors.

Remarks

This is the core operation for applicative validation. It ensures that errors from sibling fields are collected together into a single structured graph.

Parameters

left: The first graph of type Diagnostics.
right: The second graph of type Diagnostics.

Returns

A new Diagnostics containing the union of both inputs.

FsFlow.ValidationModule.merge

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

Merges two validations into a validation of a tuple.

Parameters

left: The first validation.
right: The second validation.

Returns

A validation containing a tuple of the results.

FsFlow.MissingCapability

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

Describes a missing service-provider capability.

FsFlow.RefModule.modify

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

Updates the value of the reference using the supplied function and returns a derived value.

FsFlow.ValidationModule.name

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

Prefixes a validation with a named branch.

Parameters

name: The branch name.
validation: The validation to scope.

Returns

A validation whose diagnostics are prefixed with Name name.

FsFlow.Needs

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

Describes the capability contract for a single dependency.

Remarks

Named cap-set interfaces inherit this contract once and then expose the dependency through a member such as Clock or Logger. Workflow builders can accept any environment that implements Needs<'dep>, which lets larger runtimes satisfy smaller boundaries.

Examples

type IClock =
     abstract UtcNow : unit -&gt; DateTimeOffset

 type ClockCaps =
     inherit Needs&lt;IClock&gt;
     abstract Clock : IClock

FsFlow.Caps.Core.Guid.newGuid

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

Reads a GUID from the environment.

FsFlow.Caps.Core.Random.nextInt

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

Reads a random integer from the environment.

FsFlow.CheckModule.not

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

Returns success when the supplied check fails.

Remarks

This is a logical “not” operation for checks. Note that it discards the success value and returns Unit on success.

Parameters

check: The source Check to invert.

Returns

A Check that succeeds if the input fails.

FsFlow.CheckModule.notBlank

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

Returns the string when it is not blank.

Parameters

str: The string to check.

Returns

A Check containing the non-blank string.

FsFlow.CheckModule.notEmpty

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

Returns the sequence when it is not empty.

Parameters

coll: The sequence to check.

Returns

A Check containing the non-empty sequence.

FsFlow.CheckModule.notEqual

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

Returns success when the values are not equal.

Parameters

expected: The expected value.
actual: The actual value.

Returns

A Check that succeeds if the values differ.

FsFlow.CheckModule.notNull

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

Returns the value when it is not null.

Parameters

value: The value to check.

Returns

A Check containing the non-null value.

FsFlow.Caps.Core.Clock.now

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

Reads the current UTC timestamp from the environment.

FsFlow.Flow.ok

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

Creates a successful synchronous flow.

FsFlow.ValidationModule.ok

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

Creates a successful validation result.

Parameters

value: The success value of type 'value.

Returns

A successful Validation.

FsFlow.CheckModule.okIf

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

Returns success when the condition is true.

Parameters

cond: The boolean condition to check.

Returns

A Check that succeeds if cond is true.

FsFlow.CheckModule.okIfBlank

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

Returns success when the string is blank.

Parameters

str: The string to check.

Returns

A Check that succeeds if the string is null, empty, or whitespace.

FsFlow.CheckModule.okIfEmpty

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

Returns success when the sequence is empty.

Parameters

coll: The sequence to check.

Returns

A Check that succeeds if the sequence is empty.

FsFlow.CheckModule.okIfEmptyStr

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

Returns success when the string is null or empty.

Parameters

str: The string to check.

Returns

A Check that succeeds if the string is null or empty.

FsFlow.CheckModule.okIfEqual

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

Returns success when the values are equal.

Parameters

expected: The expected value.
actual: The actual value.

Returns

A Check that succeeds if the values are equal.

FsFlow.CheckModule.okIfNone

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

Returns success when the option is None.

Parameters

opt: The option to check.

Returns

A Check that succeeds if the option is None.

FsFlow.CheckModule.okIfNonEmptyStr

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

Returns the string when it is not null or empty.

Parameters

str: The string to check.

Returns

A Check containing the non-empty string.

FsFlow.CheckModule.okIfNotBlank

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

Returns the string when it is not blank.

Parameters

str: The string to check.

Returns

A Check containing the non-blank string.

FsFlow.CheckModule.okIfNotEmpty

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

Returns the sequence when it is not empty.

Parameters

coll: The sequence of type seq<'a> to check.

Returns

A Check containing the non-empty sequence.

FsFlow.CheckModule.okIfNotEqual

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

Returns success when the values are not equal.

Parameters

expected: The expected value.
actual: The actual value.

Returns

A Check that succeeds if the values differ.

FsFlow.CheckModule.okIfNotNull

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

Returns the value when it is not null.

Parameters

value: The value of type 'a to check for null.

Returns

A Check containing the non-null value.

FsFlow.CheckModule.okIfNull

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

Returns success when the value is null.

Parameters

value: The value to check.

Returns

A Check that succeeds if the value is null.

FsFlow.CheckModule.okIfSome

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

Returns the value when the option is Some.

Parameters

opt: The FSharpOption to check.

Returns

A Check containing the value if present.

FsFlow.CheckModule.okIfValueNone

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

Returns success when the value option is ValueNone.

Parameters

opt: The value option to check.

Returns

A Check that succeeds if the value option is ValueNone.

FsFlow.CheckModule.okIfValueSome

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

Returns the value when the value option is ValueSome.

Parameters

opt: The FSharpValueOption to check.

Returns

A Check containing the value if present.

FsFlow.CheckModule.or

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

Returns success when either check succeeds.

Remarks

This is a logical “or” operation. It short-circuits: if left succeeds, right is not evaluated.

Parameters

left: The first check.
right: The second check.

Returns

A Check that succeeds if either input succeeds.

FsFlow.Flow.orElse

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

Falls back to another flow when the source flow fails.

FsFlow.ValidationModule.orElse

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

Falls back to another validation when the source validation fails.

Remarks

This is a left-biased choice operator. If the source succeeds, the fallback is not used. If the source fails, the fallback validation is returned as-is.

Parameters

fallback: The validation to use when the source fails.
validation: The source validation.

Returns

The source validation when it succeeds, otherwise the fallback validation.

FsFlow.Flow.orElseFlow

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

Turns a pure validation result into a synchronous flow with environment-provided failure.

Remarks

This helper bridges the gap between pure validation (which often uses Result or Check) and the Flow environment model. If the result is an error, the provided errorFlow is executed to produce the final application error.

Parameters

errorFlow: A flow that reads the environment to produce an error value.
result: The pure result to bridge.

Returns

A Flow that mirrors the success of the result or fails with the outcome of the error flow.

FsFlow.Flow.orElseWith

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

Falls back to another flow when the source flow fails.

FsFlow.ValidationModule.orElseWith

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

Computes a fallback validation from the source diagnostics when validation fails.

Remarks

This is the lazy counterpart to orElse and is useful when the alternate branch depends on the accumulated diagnostics.

Parameters

fallback: A function that turns the diagnostics into an alternate validation.
validation: The source validation.

Returns

The source validation when it succeeds, otherwise the computed fallback validation.

FsFlow.CheckModule.orError

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

Maps a unit error into the supplied application error value.

Remarks

This is the primary bridge from checks to domain-specific results.

Parameters

error: The domain error of type 'error to return on failure.
result: The source Check.

Returns

A Result with the provided error value.

FsFlow.CheckModule.orErrorWith

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

Maps a unit error into an application error produced on demand.

Parameters

errorFn: A function of type unit -> 'error to produce the error.
result: The source Check.

Returns

A Result with the produced error value.

FsFlow.Path

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

A path through a validation graph, represented as a list of PathSegment.

FsFlow.PathSegment

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

Location markers used to describe where a diagnostic belongs in a validation graph.

FsFlow.Caps.Process.ProcessResult

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

Represents the outcome of an external process execution.

FsFlow.LayerModule.provideLayer

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

Provides a derived environment from a layer flow to a downstream flow.

FsFlow.Flow.provideLayer

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

Provides a derived environment from a layer flow to a downstream flow.

FsFlow.Flow.race

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

Runs two flows concurrently and returns the result of the first one to complete.

Remarks

The “loser” flow is interrupted immediately.

FsFlow.Flow.read

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

Projects a value from the current environment.

Remarks

This is the primary way to access dependencies or configuration stored in the environment. The projection function is applied to the environment at execution time.

Parameters

projection: A function that extracts a value from the environment.

Returns

A Flow containing the projected value.

FsFlow.Caps.FileSystem.FileSystemModule.readAllText

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

Reads all text from a file using the file system environment.

FsFlow.Caps.Console.ConsoleModule.readLine

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

Reads a line from the console environment.

FsFlow.ScheduleModule.recurs

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

Creates a schedule that recurs a fixed number of times.

FsFlow.Ref

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

Represents a handle to a mutable reference that can be updated atomically.

FsFlow.Builders.result

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

The fail-fast result { } computation expression.

Remarks

Use this builder when the happy path should short-circuit on the first error and you want to keep the workflow in `Result` shape all the way through. It works well for parsing, validation, and other boundaries where failure is expected to stop the flow immediately instead of accumulating diagnostics. Use `Check.orError` when a pure check needs a domain error, and `Guard.MapError` when you need to remap an existing error before entering the CE.

Examples

 let parsedUser =
     result {
         let! age = parseAge input
         let! name = parseName input
         return { Age = age; Name = name }
     }

Result Builder

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

The result { } builder provides a fail-fast computation expression for standard F# Result values.

Builder

FsFlow.Builders.result: The fail-fast result { } computation expression.

FsFlow.Flow.run

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

Executes a flow with the provided environment and the default cancellation token.

Examples

let flow = Flow.read (fun env -> $"Hello, {env}!")
 let result = Flow.run "World" flow
 // result = Effect that resolves to Success "Hello, World!" on both .NET and Fable

FsFlow.FlowStreamModule.runForEach

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

Executes the stream and performs an action for each value.

FsFlow.CapabilityModule.runtime

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

Reads the current runtime from the environment.

FsFlow.Schedule

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

Represents a stateful schedule that can decide whether to continue and how long to delay.

FsFlow.Flow.sequence

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

Transforms a sequence of flows into a flow of a sequence and stops at the first failure.

FsFlow.ValidationModule.sequence

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

Transforms a sequence of validations into a validation of a list.

Parameters

validations: The input sequence.

Returns

A validation containing the list of values.

FsFlow.CapabilityModule.service

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

Reads a service from the environment using the provided projection.

FsFlow.CapabilityModule.serviceFromProvider

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

Reads a service from IServiceProvider and fails when it is not registered.

FsFlow.RefModule.set

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

Sets the value of the reference to the specified value.

FsFlow.TRefModule.set

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

Sets the value of the transactional reference within a transaction.

FsFlow.DiagnosticsModule.singleton

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

Creates a diagnostics graph containing exactly one error at the root.

Parameters

error: The application error to store at the root.

Returns

A Diagnostics with a single error.

FsFlow.ScheduleModule.spaced

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

Creates a schedule that recurs with a fixed delay between attempts.

FsFlow.FlowScheduleExtensions.Flow.Repeat.Static

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

Repeats a successful flow according to the supplied schedule.

FsFlow.FlowScheduleExtensions.Flow.Retry.Static

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

Retries a failing flow according to the supplied schedule.

FsFlow.StmBuilders.stm

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

The stm { } computation expression for building atomic transactions.

FsFlow.STM

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

Represents a transactional operation that can be composed and executed atomically.

FsFlow.Flow.succeed

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

Alias for ok that reads well in some call sites.

Examples

let flow = Flow.succeed 42
 let result = Flow.run () flow
 // result = Success 42

FsFlow.ValidationModule.succeed

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

Alias for ok.

Parameters

value: The success value of type 'value.

Returns

A successful Validation.

FsFlow.Flow.tap

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

Runs a synchronous side effect on success and preserves the original value.

Remarks

Use this for logging, telemetry, or other “fire and forget” operations that should not alter the primary value path. If the binder flow fails, the entire flow fails with that error.

Parameters

binder: A function that produces a side-effect flow from the successful value.
flow: The source flow.

Returns

A Flow that preserves the original success value after the side effect.

FsFlow.Flow.tapError

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

Runs a synchronous side effect on failure and preserves the original error.

Remarks

Use this for error logging or cleanup actions that depend on the environment. If the binder side-effect flow itself fails, its error will overwrite the original error.

Parameters

binder: A function that produces a side-effect flow from the error value.
flow: The source flow.

Returns

A Flow that preserves the original error after the side effect.

FsFlow.ValidationModule.toResult

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

Converts a Validation into a standard Result.

Parameters

validation: The validation to convert.

Returns

A result containing either the success value or the full diagnostics graph.

FsFlow.DiagnosticsModule.toString

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

Renders a diagnostics graph in a YAML-like layout for display.

Remarks

This is intended for human-readable output. Empty sections are omitted, and children are shown directly under their branch labels at the same indentation level as errors. Errors render as YAML-style bullet items without an Errors: key. Use flatten when you need path-bearing diagnostics for reporting or assertions.

Parameters

graph: The diagnostics graph to render.

Returns

A formatted string representation of the graph.

FsFlow.Runtime.Telemetry.Activity.trace

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

Wraps a flow in a new activity and automatically maps metadata traits from the environment to tags.

Parameters

name: The name of the activity.
flow: The flow to trace.

Returns

A flow that executes within the activity span.

FsFlow.Flow.traverse

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

Transforms a sequence of values into a flow and stops at the first failure.

FsFlow.ValidationModule.traverseIndexed

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

Maps a sequence into validations while prefixing each item with its index.

Remarks

This is the indexed version of sequence. It is useful for list and array validation because each item can keep its own Index branch without the caller manually wrapping every item.

Parameters

binder: A function of type int -> 'source -> Validation<'value, 'error>.
values: The input sequence.

Returns

A validation containing the list of values or accumulated diagnostics.

FsFlow.TRef

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

Represents a transactional reference that can be updated atomically within an STM transaction.

FsFlow.Caps.Core.EnvironmentVariable.tryGet

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

Reads a raw string environment variable without wrapping it in a result.

FsFlow.Caps.Core.EnvironmentVariables.tryGet

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

Reads a raw environment-variable value from the environment.

FsFlow.RefModule.update

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

Updates the value of the reference using the supplied function.

FsFlow.TRefModule.update

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

Updates the value of the transactional reference within a transaction using the supplied function.

FsFlow.Builders.validate

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

The accumulating validate { } computation expression.

Remarks

Use this builder when you want to collect all validation failures instead of stopping at the first one. Use `and!` when sibling validations should accumulate into the same diagnostics graph. Plain `let!` and `do!` are sequential: if the left side fails, the later step is not evaluated. `Check<'value>` covers both value-preserving checks and gate checks. Use `Check.orError` to attach an application error, and `Guard.Of` / `Guard.MapError` when you want the same error-bound source shape to participate directly in validation. When nested API response fields need to keep their place in the diagnostics graph, use the scoped helpers `validate.key`, `validate.index`, and `validate.name` inside the computation expression. If you already have a `Validation` value, use `Validation.key`, `Validation.index`, or `Validation.name` to prefix it after the fact. It is intended for forms, configuration checks, and other input-heavy boundaries where the user benefits from seeing every problem at once.

Examples

 let validatedUser =
     validate {
         let! name = Check.notBlank input.Name
         let! age = Check.okIf (input.Age > 0) "Age must be positive"
         return { Name = name; Age = age }
     }

let validatedCustomer =
    validate.key "customer" {
        let! name =
            validate.name "Name" {
                return! input.Name |> Check.notBlank |> Check.orError "Name required"
            }

        return name
    }

validate { }

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

The validate { } builder is used for accumulating sibling failures into a structured diagnostics graph.

Builder

FsFlow.Builders.validate: The accumulating validate { } computation expression.

FsFlow.Hosting.Startup.validateEnvironment

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

Validates that all required environment variables are present and valid using the process environment.

FsFlow.Validation

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

An accumulating validation result that keeps the structured diagnostics graph visible.

Remarks

Unlike FSharpResult, this type is designed for applicative composition using and! in the validate { } builder, which merges errors instead of short-circuiting.

FsFlow.Flow.value

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

Alias for ok that reads well in some call sites.

Examples

let flow = Flow.value "constant"

FsFlow.Caps.FileSystem.FileSystemModule.writeAllText

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

Writes all text to a file using the file system environment.

FsFlow.Caps.Console.ConsoleModule.writeLine

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

Writes a line to the console environment.

FsFlow.Flow.zip

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

Combines two flows into a tuple of their values.

FsFlow.Flow.zipPar

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

Combines two flows into a tuple of their values, running them concurrently.

Remarks

If either flow fails, the other is interrupted immediately.

Home on FsFlow

FsToolkit.ErrorHandling

FsToolkit.ErrorHandling

The Model Difference

Getting Started

Getting Started

1. The Continuum of Logic

2. Start with Checks and Results

Pure Checks

Pure Checks

The Two Shapes of Check

Attaching Errors with Check.orError

Ref (Atomic References)

Ref (Atomic References)

Why Use Ref?

Environment Slicing

Environment Slicing (The Record Pattern)

Projecting from the Environment

The Shorthand: _.Field

Execution Semantics

Execution Semantics

Execution Shape

Success and Typed Failure

Result CE

Result CE

Basic Usage

Guarded Bindings

Schedule (Retry & Repeat)

Schedule (Retry & Repeat)

Basic Schedules

Fixed Number of Recursions

Fixed Spacing

Exponential Backoff

Adding Jitter

Troubleshooting Types

Troubleshooting Types

Error: A Unique Overload For Method Bind Could Not Be Determined

Validus Integration

Validus Integration

The Guard

The Guard

Why do I need Guard?

Benchmarks

Benchmarks

Summary

Setup

Abstraction Cost

Capabilities (CAPS)

Capabilities (CAPS)

Requesting a Dependency with Env<'dep>

IcedTasks Integration

IcedTasks Integration

STM (Software Transactional Memory)

STM (Software Transactional Memory)

Straightforward Examples

Straightforward Examples

1. Simple Environment Access

2. Combining Pure Logic and Async Work

3. Retrying a Flow

Task and Async Interop

Task and Async Interop

Direct Binds

Example: Mixed Orchestration

Option and ValueOption

Validate CE

Validate CE

Accumulating with and!

Architectural Styles

Architectural Styles

1. Booted App Environment

Diagnostics Graph

Diagnostics Graph

The Structure

Creating Scoped Diagnostics

FSharpPlus Integration

FSharpPlus Integration

Stream (FlowStream)

Stream (FlowStream)

Creating a Stream

From a Sequence

Attaching Errors with `Check.orError`

The Shorthand: `_.Field`

Error: A Unique Overload For Method `Bind` Could Not Be Determined

Requesting a Dependency with `Env<'dep>`

Accumulating with `and!`