Validation & Results on FsFlow

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.

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.

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:

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.

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:

Validation & Results on FsFlow

Pure Checks

Pure Checks

The Two Shapes of Check

Attaching Errors with Check.orError

Result CE

Result CE

Basic Usage

Guarded Bindings

The Guard

The Guard

Why do I need Guard?

Validate CE

Validate CE

Accumulating with and!

Diagnostics Graph

Diagnostics Graph

The Structure

Creating Scoped Diagnostics

Attaching Errors with `Check.orError`

Accumulating with `and!`