validation

func ApplicativeMonoid ¶

func ApplicativeMonoid[A any](m Monoid[A]) Monoid[Validation[A]]

ApplicativeMonoid creates a Monoid instance for Validation[A] given a Monoid for A. This allows combining validation results where the success values are also combined using the provided monoid. If any validation fails, all errors are accumulated.

The resulting monoid:

• Empty: Returns a successful validation with the empty value from the inner monoid
• Concat: Combines two validations:
• Both success: Combines values using the inner monoid
• Any failure: Accumulates all errors

Example:

import "github.com/IBM/fp-go/v2/string"

// Create a monoid for validations of strings
m := ApplicativeMonoid(string.Monoid)

v1 := Success("Hello")
v2 := Success(" World")
combined := m.Concat(v1, v2) // Success("Hello World")

v3 := Failures[string](someErrors)
failed := m.Concat(v1, v3) // Failures with accumulated errors

func ErrorsMonoid ¶

func ErrorsMonoid() Monoid[Errors]

ErrorsMonoid returns a Monoid instance for Errors (array of ValidationError pointers). The monoid concatenates error arrays, with an empty array as the identity element. This is used internally by the applicative operations to accumulate validation errors.

Example:

m := ErrorsMonoid()
combined := m.Concat(errors1, errors2) // Concatenates both error arrays
empty := m.Empty()                      // Returns empty error array

func Ap ¶

func Ap[B, A any](fa Validation[A]) Operator[func(A) B, B]

Ap applies a validation containing a function to a validation containing a value. This is the applicative apply operation that accumulates errors from both validations. If either validation fails, all errors are collected. If both succeed, the function is applied.

This enables combining multiple validations while collecting all errors:

Example:

// Validate multiple fields and collect all errors
validateUser := Ap(Ap(Of(func(name string) func(age int) User {
	return func(age int) User { return User{name, age} }
}))(validateName))(validateAge)

func ApS ¶ added in v2.2.6

func ApS[S1, S2, T any](
	setter func(T) func(S1) S2,
	fa Validation[T],
) Operator[S1, S2]

ApS attaches a value to a context S1 to produce a context S2 by considering the context and the value concurrently. This uses the applicative functor pattern, allowing parallel composition.

IMPORTANT: Unlike Bind which fails fast, ApS aggregates ALL validation errors from both the context and the value. If both validations fail, all errors are collected and returned together. This is useful for validating multiple independent fields and reporting all errors at once.

Example:

type State struct { x int; y int }
result := F.Pipe2(
    Do(State{}),
    ApS(func(x int) func(State) State {
        return func(s State) State { s.x = x; return s }
    }, Success(42)),
)

Error aggregation example:

stateFailure := Failures[State](Errors{&ValidationError{Messsage: "state error"}})
valueFailure := Failures[int](Errors{&ValidationError{Messsage: "value error"}})
result := ApS(setter, valueFailure)(stateFailure)
// Result contains BOTH errors: ["state error", "value error"]

func ApSL ¶ added in v2.2.6

func ApSL[S, T any](
	lens L.Lens[S, T],
	fa Validation[T],
) Operator[S, S]

ApSL attaches a value to a context using a lens-based setter. This is a convenience function that combines ApS with a lens, allowing you to use optics to update nested structures in a more composable way.

IMPORTANT: Like ApS, this function aggregates ALL validation errors. If both the context and the value fail validation, all errors are collected and returned together. This enables comprehensive error reporting for complex nested structures.

The lens parameter provides both the getter and setter for a field within the structure S. This eliminates the need to manually write setter functions.

Example:

type Address struct {
    Street string
    City   string
}

type Person struct {
    Name    string
    Address Address
}

// Create a lens for the Address field
addressLens := lens.MakeLens(
    func(p Person) Address { return p.Address },
    func(p Person, a Address) Person { p.Address = a; return p },
)

// Use ApSL to update the address
result := F.Pipe2(
    Success(Person{Name: "Alice"}),
    ApSL(
        addressLens,
        Success(Address{Street: "Main St", City: "NYC"}),
    ),
)

func Bind ¶ added in v2.2.6

func Bind[S1, S2, A any](
	setter func(A) func(S1) S2,
	f Kleisli[S1, A],
) Operator[S1, S2]

Bind attaches the result of a computation to a context S1 to produce a context S2. This is used in do-notation style to sequentially build up a context.

Example:

type State struct { x int; y int }
result := F.Pipe2(
    Do(State{}),
    Bind(func(x int) func(State) State {
        return func(s State) State { s.x = x; return s }
    }, func(s State) Validation[int] { return Success(42) }),
)

func BindL ¶ added in v2.2.6

func BindL[S, T any](
	lens L.Lens[S, T],
	f Kleisli[T, T],
) Operator[S, S]

BindL attaches the result of a computation to a context using a lens-based setter. This is a convenience function that combines Bind with a lens, allowing you to use optics to update nested structures based on their current values.

The lens parameter provides both the getter and setter for a field within the structure S. The computation function f receives the current value of the focused field and returns a Validation that produces the new value.

Unlike ApSL, BindL uses monadic sequencing, meaning the computation f can depend on the current value of the focused field.

Example:

type Counter struct {
    Value int
}

valueLens := lens.MakeLens(
    func(c Counter) int { return c.Value },
    func(c Counter, v int) Counter { c.Value = v; return c },
)

// Increment the counter, but fail if it would exceed 100
increment := func(v int) Validation[int] {
    if v >= 100 {
        return Failures[int](Errors{&ValidationError{Messsage: "exceeds limit"}})
    }
    return Success(v + 1)
}

result := F.Pipe1(
    Success(Counter{Value: 42}),
    BindL(valueLens, increment),
) // Success(Counter{Value: 43})

func BindTo ¶ added in v2.2.6

func BindTo[S1, T any](
	setter func(T) S1,
) Operator[T, S1]

BindTo initializes a new state S1 from a value T. This is typically used as the first operation after creating a Validation value.

Example:

type State struct { value int }
result := F.Pipe1(
    Success(42),
    BindTo(func(x int) State { return State{value: x} }),
)

func Chain ¶ added in v2.1.21

func Chain[A, B any](f Kleisli[A, B]) Operator[A, B]

Chain is the curried version of MonadChain. Sequences two validation computations where the second depends on the first.

Example:

validatePositive := func(x int) Validation[int] {
    if x > 0 { return Success(x) }
    return Failure("must be positive")
}
result := Chain(validatePositive)(Success(42)) // Success(42)

func ChainLeft ¶ added in v2.2.8

func ChainLeft[A any](f Kleisli[Errors, A]) Operator[A, A]

ChainLeft is the curried version of MonadChainLeft. Returns a function that transforms validation failures while preserving successes.

Unlike the standard Either ChainLeft which replaces errors, this validation-specific implementation **aggregates errors** using the Errors monoid. When the transformation function returns a failure, both the original errors and the new errors are combined, ensuring no validation errors are lost.

This is particularly useful for:

• Error recovery with fallback validation
• Adding contextual information to existing errors
• Transforming error types while preserving all error details
• Building error handling pipelines that accumulate failures

Key behavior:

• Success values pass through unchanged
• When transforming failures, if the transformation also fails, **all errors are aggregated**
• If the transformation succeeds, it recovers from the original failure

Example - Error recovery with aggregation:

recoverFromNotFound := ChainLeft(func(errs Errors) Validation[int] {
    // Check if this is a "not found" error
    for _, err := range errs {
        if err.Messsage == "not found" {
            return Success(0) // recover with default
        }
    }
    // Add context to existing errors
    return Failures[int](Errors{
        &ValidationError{Messsage: "recovery failed"},
    })
    // Result will contain BOTH original errors AND "recovery failed"
})

result := recoverFromNotFound(Failures[int](Errors{
    &ValidationError{Messsage: "database error"},
}))
// Result contains: ["database error", "recovery failed"]

Example - Adding context to errors:

addContext := ChainLeft(func(errs Errors) Validation[string] {
    // Add contextual information
    return Failures[string](Errors{
        &ValidationError{
            Messsage: "validation failed in user.email field",
        },
    })
    // Original errors are preserved and new context is added
})

result := F.Pipe1(
    Failures[string](Errors{
        &ValidationError{Messsage: "invalid format"},
    }),
    addContext,
)
// Result contains: ["invalid format", "validation failed in user.email field"]

Example - Success values pass through:

handler := ChainLeft(func(errs Errors) Validation[int] {
    return Failures[int](Errors{
        &ValidationError{Messsage: "never called"},
    })
})
result := handler(Success(42)) // Success(42) - unchanged

func Let ¶ added in v2.2.6

func Let[S1, S2, B any](
	key func(B) func(S1) S2,
	f func(S1) B,
) Operator[S1, S2]

Let attaches the result of a pure computation to a context S1 to produce a context S2. Unlike Bind, the computation function returns a plain value, not an Option.

Example:

type State struct { x int; computed int }
result := F.Pipe2(
    Do(State{x: 5}),
    Let(func(c int) func(State) State {
        return func(s State) State { s.computed = c; return s }
    }, func(s State) int { return s.x * 2 }),
)

func LetL ¶ added in v2.2.6

func LetL[S, T any](
	lens L.Lens[S, T],
	f Endomorphism[T],
) Operator[S, S]

LetL attaches the result of a pure computation to a context using a lens-based setter. This is a convenience function that combines Let with a lens, allowing you to use optics to update nested structures with pure transformations.

The lens parameter provides both the getter and setter for a field within the structure S. The transformation function f receives the current value of the focused field and returns the new value directly (not wrapped in Validation).

This is useful for pure transformations that cannot fail, such as mathematical operations, string manipulations, or other deterministic updates.

Example:

type Counter struct {
    Value int
}

valueLens := lens.MakeLens(
    func(c Counter) int { return c.Value },
    func(c Counter, v int) Counter { c.Value = v; return c },
)

// Double the counter value
double := func(v int) int { return v * 2 }

result := F.Pipe1(
    Success(Counter{Value: 21}),
    LetL(valueLens, double),
) // Success(Counter{Value: 42})

func LetTo ¶ added in v2.2.6

func LetTo[S1, S2, B any](
	key func(B) func(S1) S2,
	b B,
) Operator[S1, S2]

LetTo attaches a constant value to a context S1 to produce a context S2.

Example:

type State struct { x int; name string }
result := F.Pipe2(
    Do(State{x: 5}),
    LetTo(func(n string) func(State) State {
        return func(s State) State { s.name = n; return s }
    }, "example"),
)

func LetToL ¶ added in v2.2.6

func LetToL[S, T any](
	lens L.Lens[S, T],
	b T,
) Operator[S, S]

LetToL attaches a constant value to a context using a lens-based setter. This is a convenience function that combines LetTo with a lens, allowing you to use optics to set nested fields to specific values.

The lens parameter provides the setter for a field within the structure S. Unlike LetL which transforms the current value, LetToL simply replaces it with the provided constant value b.

This is useful for resetting fields, initializing values, or setting fields to predetermined constants.

Example:

type Config struct {
    Debug   bool
    Timeout int
}

debugLens := lens.MakeLens(
    func(c Config) bool { return c.Debug },
    func(c Config, d bool) Config { c.Debug = d; return c },
)

result := F.Pipe1(
    Success(Config{Debug: true, Timeout: 30}),
    LetToL(debugLens, false),
) // Success(Config{Debug: false, Timeout: 30})

func Map ¶

func Map[A, B any](f func(A) B) Operator[A, B]

Map transforms the value inside a successful validation using the provided function. If the validation is a failure, the errors are preserved unchanged. This is the functor map operation for Validation.

Map is used for transforming successful values without changing the validation context. It's the most basic operation for working with validated values and forms the foundation for more complex validation pipelines.

Behavior:

• Success: applies function to value → Success(f(value))
• Failure: preserves errors unchanged → Failure(same errors)

This is useful for:

• Type transformations: converting validated values to different types
• Value transformations: normalizing, formatting, or computing derived values
• Pipeline composition: chaining multiple transformations
• Preserving validation context: errors pass through unchanged

Example - Transform successful value:

doubled := Map(func(x int) int { return x * 2 })(Of(21))
// Result: Success(42)

Example - Failure preserved:

result := Map(func(x int) int { return x * 2 })(
    Failures[int](Errors{&ValidationError{Messsage: "invalid"}}),
)
// Result: Failure with same error: ["invalid"]

Example - Type transformation:

toString := Map(func(x int) string { return fmt.Sprintf("%d", x) })
result := toString(Of(42))
// Result: Success("42")

Example - Chaining transformations:

result := F.Pipe3(
    Of(5),
    Map(func(x int) int { return x + 10 }),  // 15
    Map(func(x int) int { return x * 2 }),   // 30
    Map(func(x int) string { return fmt.Sprintf("%d", x) }),  // "30"
)
// Result: Success("30")

func FailureWithError ¶

func FailureWithError[T any](value any, message string) Reader[error, Reader[Context, Validation[T]]]

FailureWithError creates a validation failure with a custom message and underlying cause. Returns a Reader that takes an error, then a Context, and produces a Validation[T] failure. This is useful for wrapping errors from other operations while maintaining validation context.

Example:

fail := FailureWithError[int]("abc", "parse failed")
result := fail(parseErr)([]ContextEntry{{Key: "count", Type: "int"}})

func FailureWithMessage ¶

func FailureWithMessage[T any](value any, message string) Reader[Context, Validation[T]]

FailureWithMessage creates a validation failure with a custom message. Returns a Reader that takes a Context and produces a Validation[T] failure. This is useful for creating context-aware validation errors.

Example:

fail := FailureWithMessage[int]("abc", "expected integer")
result := fail([]ContextEntry{{Key: "age", Type: "int"}})

func ToResult ¶ added in v2.1.19

func ToResult[T any](val Validation[T]) Result[T]

ToResult converts a Validation[T] to a Result[T]. It transforms the Left side (validation errors) into a standard error using MakeValidationErrors, while preserving the Right side (successful value) unchanged. This is useful for integrating validation results with code that expects Result types.

Type Parameters:

• T: The type of the successfully validated value

Parameters:

• val: A Validation[T] which is Either[Errors, T]

Returns:

• A Result[T] which is Either[error, T], with validation errors converted to a single error

Example:

validation := Success[int](42)
result := ToResult(validation) // Result containing 42

validation := Failures[int](Errors{&ValidationError{Messsage: "invalid"}})
result := ToResult(validation) // Result containing ValidationErrors error

func Do ¶ added in v2.2.6

func Do[S any](
	empty S,
) Validation[S]

Do creates an empty context of type S to be used with the Bind operation. This is the starting point for building up a context using do-notation style.

Example:

type Result struct {
    x int
    y string
}
result := Do(Result{})

func Failures ¶

func Failures[T any](err Errors) Validation[T]

Failures creates a validation failure from a collection of errors. Returns a Left Either containing the errors.

func MonadAp ¶ added in v2.1.21

func MonadAp[B, A any](fab Validation[func(A) B], fa Validation[A]) Validation[B]

MonadAp applies a validation containing a function to a validation containing a value. This is the applicative apply operation that **accumulates errors** from both validations.

**Key behavior**: Unlike Either's MonadAp which fails fast (returns first error), this validation-specific implementation **accumulates all errors** using the Errors monoid. When both the function validation and value validation fail, all errors from both are combined.

This error accumulation is the defining characteristic of the Validation applicative, making it ideal for scenarios where you want to collect all validation failures at once rather than stopping at the first error.

Behavior:

• Both succeed: applies the function to the value → Success(result)
• Function fails, value succeeds: returns function's errors → Failure(func errors)
• Function succeeds, value fails: returns value's errors → Failure(value errors)
• Both fail: **combines all errors** → Failure(func errors + value errors)

This is particularly useful for:

• Form validation: collect all field errors at once
• Configuration validation: report all invalid settings together
• Data validation: accumulate all constraint violations
• Multi-field validation: validate independent fields in parallel

Example - Both succeed:

double := func(x int) int { return x * 2 }
result := MonadAp(Of(double), Of(21))
// Result: Success(42)

Example - Error accumulation (key feature):

funcValidation := Failures[func(int) int](Errors{
    &ValidationError{Messsage: "function error"},
})
valueValidation := Failures[int](Errors{
    &ValidationError{Messsage: "value error"},
})
result := MonadAp(funcValidation, valueValidation)
// Result: Failure with BOTH errors: ["function error", "value error"]

Example - Validating multiple fields:

type User struct {
    Name string
    Age  int
}

makeUser := func(name string) func(int) User {
    return func(age int) User { return User{name, age} }
}

nameValidation := validateName("ab")  // Fails: too short
ageValidation := validateAge(16)      // Fails: too young

// First apply name
step1 := MonadAp(Of(makeUser), nameValidation)
// Then apply age
result := MonadAp(step1, ageValidation)
// Result contains ALL validation errors from both fields

func MonadChain ¶ added in v2.1.21

func MonadChain[A, B any](fa Validation[A], f Kleisli[A, B]) Validation[B]

MonadChain sequences two validation computations where the second depends on the first. If the first validation fails, returns the failure without executing the second. This is the monadic bind operation for Validation.

Example:

result := MonadChain(
    Success(42),
    func(x int) Validation[string] {
        return Success(fmt.Sprintf("Value: %d", x))
    },
) // Success("Value: 42")

func MonadChainLeft ¶ added in v2.2.8

func MonadChainLeft[A any](fa Validation[A], f Kleisli[Errors, A]) Validation[A]

MonadChainLeft sequences a computation on the failure (Left) channel of a Validation. If the Validation is a failure, applies the function to transform or recover from the errors. If the Validation is a success, returns the success value unchanged.

**Critical difference from Either.MonadChainLeft**: This validation-specific implementation **aggregates errors** using the Errors monoid. When the transformation function returns a failure, both the original errors and the new errors are combined, ensuring comprehensive error reporting.

This is the dual of MonadChain - while Chain operates on success values, ChainLeft operates on failure values. It's particularly useful for:

• Error recovery: converting specific errors into successful values
• Error enrichment: adding context or transforming error messages
• Fallback logic: providing alternative validations when the first fails
• Error aggregation: combining multiple validation failures

The function parameter receives the collection of validation errors and must return a new Validation[A]. This allows you to:

• Recover by returning Success(value)
• Transform errors by returning Failures(newErrors) - **original errors are preserved**
• Implement conditional error handling based on error content

Example - Error recovery:

result := MonadChainLeft(
    Failures[int](Errors{
        &ValidationError{Messsage: "not found"},
    }),
    func(errs Errors) Validation[int] {
        // Check if we can recover
        for _, err := range errs {
            if err.Messsage == "not found" {
                return Success(0) // recover with default value
            }
        }
        return Failures[int](errs) // propagate errors
    },
) // Success(0)

Example - Error aggregation (key feature):

result := MonadChainLeft(
    Failures[string](Errors{
        &ValidationError{Messsage: "error 1"},
        &ValidationError{Messsage: "error 2"},
    }),
    func(errs Errors) Validation[string] {
        // Transformation also fails
        return Failures[string](Errors{
            &ValidationError{Messsage: "error 3"},
        })
    },
)
// Result contains ALL errors: ["error 1", "error 2", "error 3"]
// This is different from Either.MonadChainLeft which would only keep "error 3"

Example - Adding context to errors:

result := MonadChainLeft(
    Failures[int](Errors{
        &ValidationError{Value: "abc", Messsage: "invalid number"},
    }),
    func(errs Errors) Validation[int] {
        // Add contextual information
        contextErrors := Errors{
            &ValidationError{
                Context:  []ContextEntry{{Key: "user", Type: "User"}, {Key: "age", Type: "int"}},
                Messsage: "failed to parse user age",
            },
        }
        return Failures[int](contextErrors)
    },
)
// Result contains both original error and context:
// ["invalid number", "failed to parse user age"]

Example - Success values pass through:

result := MonadChainLeft(
    Success(42),
    func(errs Errors) Validation[int] {
        return Failures[int](Errors{
            &ValidationError{Messsage: "never called"},
        })
    },
) // Success(42) - unchanged

func MonadMap ¶ added in v2.1.21

func MonadMap[A, B any](fa Validation[A], f func(A) B) Validation[B]

MonadMap transforms the value inside a successful validation using the provided function. If the validation is a failure, the errors are preserved unchanged. This is the non-curried version of Map.

MonadMap is useful when you have both the validation and the transformation function available at the same time, rather than needing to create a reusable operator.

Behavior:

• Success: applies function to value → Success(f(value))
• Failure: preserves errors unchanged → Failure(same errors)

Example - Transform successful value:

result := MonadMap(Of(21), func(x int) int { return x * 2 })
// Result: Success(42)

Example - Failure preserved:

result := MonadMap(
    Failures[int](Errors{&ValidationError{Messsage: "invalid"}}),
    func(x int) int { return x * 2 },
)
// Result: Failure with same error: ["invalid"]

Example - Type transformation:

result := MonadMap(Of(42), func(x int) string {
    return fmt.Sprintf("Value: %d", x)
})
// Result: Success("Value: 42")

Example - Computing derived values:

type User struct { FirstName, LastName string }
result := MonadMap(
    Of(User{"John", "Doe"}),
    func(u User) string { return u.FirstName + " " + u.LastName },
)
// Result: Success("John Doe")

func Of ¶

func Of[A any](a A) Validation[A]

Of creates a successful validation result containing the given value. This is the pure/return operation for the Validation monad.

Example:

valid := Of(42) // Validation[int] containing 42

func Success ¶

func Success[T any](value T) Validation[T]

Success creates a successful validation result. Returns a Right Either containing the validated value.