fix: document statereaderioeither

Signed-off-by: Dr. Carsten Leue <carsten.leue@de.ibm.com>
2025-11-23 22:14:53 +02:00 · 2025-11-18 16:06:56 +01:00
parent 77dde302ef
commit 6d94697128
6 changed files with 1084 additions and 13 deletions
--- a/v2/statereaderioeither/state.go
+++ b/v2/statereaderioeither/state.go
@@ -23,18 +23,51 @@ import (
 	"github.com/IBM/fp-go/v2/readerioeither"
 )

+// Left creates a StateReaderIOEither that represents a failed computation with the given error.
+// The error value is immediately available and does not depend on state or context.
+//
+// Example:
+//
+//	result := statereaderioeither.Left[AppState, Config, string](errors.New("validation failed"))
+//	// Returns a failed computation that ignores state and context
 func Left[S, R, A, E any](e E) StateReaderIOEither[S, R, E, A] {
 	return function.Constant1[S](readerioeither.Left[R, Pair[S, A]](e))
 }

+// Right creates a StateReaderIOEither that represents a successful computation with the given value.
+// The value is wrapped and the state is passed through unchanged.
+//
+// Example:
+//
+//	result := statereaderioeither.Right[AppState, Config, error](42)
+//	// Returns a successful computation containing 42
 func Right[S, R, E, A any](a A) StateReaderIOEither[S, R, E, A] {
 	return statet.Of[StateReaderIOEither[S, R, E, A]](readerioeither.Of[R, E, Pair[S, A]], a)
 }

+// Of creates a StateReaderIOEither that represents a successful computation with the given value.
+// This is the monadic return/pure operation for StateReaderIOEither.
+// Equivalent to [Right].
+//
+// Example:
+//
+//	result := statereaderioeither.Of[AppState, Config, error](42)
+//	// Returns a successful computation containing 42
 func Of[S, R, E, A any](a A) StateReaderIOEither[S, R, E, A] {
 	return Right[S, R, E](a)
 }

+// MonadMap transforms the success value of a StateReaderIOEither using the provided function.
+// If the computation fails, the error is propagated unchanged.
+// The state is threaded through the computation.
+// This is the functor map operation.
+//
+// Example:
+//
+//	result := statereaderioeither.MonadMap(
+//	    statereaderioeither.Of[AppState, Config, error](21),
+//	    func(x int) int { return x * 2 },
+//	) // Result contains 42
 func MonadMap[S, R, E, A, B any](fa StateReaderIOEither[S, R, E, A], f func(A) B) StateReaderIOEither[S, R, E, B] {
 	return statet.MonadMap[StateReaderIOEither[S, R, E, A], StateReaderIOEither[S, R, E, B]](
 		readerioeither.MonadMap[R, E, Pair[S, A], Pair[S, B]],
@@ -43,6 +76,13 @@ func MonadMap[S, R, E, A, B any](fa StateReaderIOEither[S, R, E, A], f func(A) B
 	)
 }

+// Map is the curried version of [MonadMap].
+// Returns a function that transforms a StateReaderIOEither.
+//
+// Example:
+//
+//	double := statereaderioeither.Map[AppState, Config, error](func(x int) int { return x * 2 })
+//	result := function.Pipe1(statereaderioeither.Of[AppState, Config, error](21), double)
 func Map[S, R, E, A, B any](f func(A) B) Operator[S, R, E, A, B] {
 	return statet.Map[StateReaderIOEither[S, R, E, A], StateReaderIOEither[S, R, E, B]](
 		readerioeither.Map[R, E, Pair[S, A], Pair[S, B]],
@@ -50,6 +90,18 @@ func Map[S, R, E, A, B any](f func(A) B) Operator[S, R, E, A, B] {
 	)
 }

+// MonadChain sequences two computations, passing the result of the first to a function
+// that produces the second computation. This is the monadic bind operation.
+// The state is threaded through both computations.
+//
+// Example:
+//
+//	result := statereaderioeither.MonadChain(
+//	    statereaderioeither.Of[AppState, Config, error](5),
+//	    func(x int) statereaderioeither.StateReaderIOEither[AppState, Config, error, string] {
+//	        return statereaderioeither.Of[AppState, Config, error](fmt.Sprintf("value: %d", x))
+//	    },
+//	)
 func MonadChain[S, R, E, A, B any](fa StateReaderIOEither[S, R, E, A], f Kleisli[S, R, E, A, B]) StateReaderIOEither[S, R, E, B] {
 	return statet.MonadChain(
 		readerioeither.MonadChain[R, E, Pair[S, A], Pair[S, B]],
@@ -58,6 +110,15 @@ func MonadChain[S, R, E, A, B any](fa StateReaderIOEither[S, R, E, A], f Kleisli
 	)
 }

+// Chain is the curried version of [MonadChain].
+// Returns a function that sequences computations.
+//
+// Example:
+//
+//	stringify := statereaderioeither.Chain(func(x int) statereaderioeither.StateReaderIOEither[AppState, Config, error, string] {
+//	    return statereaderioeither.Of[AppState, Config, error](fmt.Sprintf("%d", x))
+//	})
+//	result := function.Pipe1(statereaderioeither.Of[AppState, Config, error](42), stringify)
 func Chain[S, R, E, A, B any](f Kleisli[S, R, E, A, B]) Operator[S, R, E, A, B] {
 	return statet.Chain[StateReaderIOEither[S, R, E, A]](
 		readerioeither.Chain[R, E, Pair[S, A], Pair[S, B]],
@@ -65,6 +126,16 @@ func Chain[S, R, E, A, B any](f Kleisli[S, R, E, A, B]) Operator[S, R, E, A, B]
 	)
 }

+// MonadAp applies a function wrapped in a StateReaderIOEither to a value wrapped in a StateReaderIOEither.
+// If either the function or the value fails, the error is propagated.
+// The state is threaded through both computations sequentially.
+// This is the applicative apply operation.
+//
+// Example:
+//
+//	fab := statereaderioeither.Of[AppState, Config, error](func(x int) int { return x * 2 })
+//	fa := statereaderioeither.Of[AppState, Config, error](21)
+//	result := statereaderioeither.MonadAp(fab, fa) // Result contains 42
 func MonadAp[B, S, R, E, A any](fab StateReaderIOEither[S, R, E, func(A) B], fa StateReaderIOEither[S, R, E, A]) StateReaderIOEither[S, R, E, B] {
 	return statet.MonadAp[StateReaderIOEither[S, R, E, A], StateReaderIOEither[S, R, E, B]](
 		readerioeither.MonadMap[R, E, Pair[S, A], Pair[S, B]],
@@ -74,6 +145,8 @@ func MonadAp[B, S, R, E, A any](fab StateReaderIOEither[S, R, E, func(A) B], fa
 	)
 }

+// Ap is the curried version of [MonadAp].
+// Returns a function that applies a wrapped function to the given wrapped value.
 func Ap[B, S, R, E, A any](fa StateReaderIOEither[S, R, E, A]) Operator[S, R, E, func(A) B, B] {
 	return statet.Ap[StateReaderIOEither[S, R, E, A], StateReaderIOEither[S, R, E, B], StateReaderIOEither[S, R, E, func(A) B]](
 		readerioeither.Map[R, E, Pair[S, A], Pair[S, B]],
@@ -82,6 +155,13 @@ func Ap[B, S, R, E, A any](fa StateReaderIOEither[S, R, E, A]) Operator[S, R, E,
 	)
 }

+// FromReaderIOEither lifts a ReaderIOEither into a StateReaderIOEither.
+// The state is passed through unchanged.
+//
+// Example:
+//
+//	rioe := readerioeither.Of[Config, error](42)
+//	result := statereaderioeither.FromReaderIOEither[AppState](rioe)
 func FromReaderIOEither[S, R, E, A any](fa ReaderIOEither[R, E, A]) StateReaderIOEither[S, R, E, A] {
 	return statet.FromF[StateReaderIOEither[S, R, E, A]](
 		readerioeither.MonadMap[R, E, A],
@@ -89,38 +169,74 @@ func FromReaderIOEither[S, R, E, A any](fa ReaderIOEither[R, E, A]) StateReaderI
 	)
 }

+// FromReaderEither lifts a ReaderEither into a StateReaderIOEither.
+// The state is passed through unchanged.
 func FromReaderEither[S, R, E, A any](fa ReaderEither[R, E, A]) StateReaderIOEither[S, R, E, A] {
 	return FromReaderIOEither[S](readerioeither.FromReaderEither(fa))
 }

+// FromIOEither lifts an IOEither into a StateReaderIOEither.
+// The state is passed through unchanged and the context is ignored.
 func FromIOEither[S, R, E, A any](fa IOEither[E, A]) StateReaderIOEither[S, R, E, A] {
 	return FromReaderIOEither[S](readerioeither.FromIOEither[R](fa))
 }

+// FromState lifts a State computation into a StateReaderIOEither.
+// The computation cannot fail (uses the error type parameter).
 func FromState[R, E, S, A any](sa State[S, A]) StateReaderIOEither[S, R, E, A] {
 	return statet.FromState[StateReaderIOEither[S, R, E, A]](readerioeither.Of[R, E, Pair[S, A]], sa)
 }

+// FromIO lifts an IO computation into a StateReaderIOEither.
+// The state is passed through unchanged and the context is ignored.
 func FromIO[S, R, E, A any](fa IO[A]) StateReaderIOEither[S, R, E, A] {
 	return FromReaderIOEither[S](readerioeither.FromIO[R, E](fa))
 }

+// FromReader lifts a Reader into a StateReaderIOEither.
+// The state is passed through unchanged.
 func FromReader[S, E, R, A any](fa Reader[R, A]) StateReaderIOEither[S, R, E, A] {
 	return FromReaderIOEither[S](readerioeither.FromReader[E](fa))
 }

+// FromEither lifts an Either into a StateReaderIOEither.
+// The state is passed through unchanged and the context is ignored.
+//
+// Example:
+//
+//	result := statereaderioeither.FromEither[AppState, Config](either.Right[error](42))
 func FromEither[S, R, E, A any](ma Either[E, A]) StateReaderIOEither[S, R, E, A] {
 	return either.MonadFold(ma, Left[S, R, A, E], Right[S, R, E, A])
 }

 // Combinators

+// Local runs a computation with a modified context.
+// The function f transforms the context before passing it to the computation.
+//
+// Example:
+//
+//	// Modify config before running computation
+//	withTimeout := statereaderioeither.Local[AppState, error, int](
+//	    func(cfg Config) Config { return Config{...cfg, Timeout: 60} }
+//	)
+//	result := withTimeout(computation)
 func Local[S, E, A, B, R1, R2 any](f func(R2) R1) func(StateReaderIOEither[S, R1, E, A]) StateReaderIOEither[S, R2, E, A] {
 	return func(ma StateReaderIOEither[S, R1, E, A]) StateReaderIOEither[S, R2, E, A] {
 		return function.Flow2(ma, readerioeither.Local[E, Pair[S, A]](f))
 	}
 }

+// Asks creates a computation that derives a value from the context.
+// The function receives the context and returns a StateReaderIOEither.
+//
+// Example:
+//
+//	getTimeout := statereaderioeither.Asks[AppState, Config, error, int](
+//	    func(cfg Config) statereaderioeither.StateReaderIOEither[AppState, Config, error, int] {
+//	        return statereaderioeither.Of[AppState, Config, error](cfg.Timeout)
+//	    },
+//	)
 func Asks[
 	S, R, E, A any,
 ](f func(R) StateReaderIOEither[S, R, E, A]) StateReaderIOEither[S, R, E, A] {
@@ -131,6 +247,15 @@ func Asks[
 	}
 }

+// FromEitherK lifts an Either-returning function into a Kleisli arrow for StateReaderIOEither.
+//
+// Example:
+//
+//	validate := func(x int) either.Either[error, int] {
+//	    if x > 0 { return either.Right[error](x) }
+//	    return either.Left[int](errors.New("negative"))
+//	}
+//	kleisli := statereaderioeither.FromEitherK[AppState, Config](validate)
 func FromEitherK[S, R, E, A, B any](f either.Kleisli[E, A, B]) Kleisli[S, R, E, A, B] {
 	return function.Flow2(
 		f,
@@ -138,6 +263,7 @@ func FromEitherK[S, R, E, A, B any](f either.Kleisli[E, A, B]) Kleisli[S, R, E,
 	)
 }

+// FromIOK lifts an IO-returning function into a Kleisli arrow for StateReaderIOEither.
 func FromIOK[S, R, E, A, B any](f func(A) IO[B]) Kleisli[S, R, E, A, B] {
 	return function.Flow2(
 		f,
@@ -145,6 +271,7 @@ func FromIOK[S, R, E, A, B any](f func(A) IO[B]) Kleisli[S, R, E, A, B] {
 	)
 }

+// FromIOEitherK lifts an IOEither-returning function into a Kleisli arrow for StateReaderIOEither.
 func FromIOEitherK[
 	S, R, E, A, B any,
 ](f ioeither.Kleisli[E, A, B]) Kleisli[S, R, E, A, B] {
@@ -154,6 +281,7 @@ func FromIOEitherK[
 	)
 }

+// FromReaderIOEitherK lifts a ReaderIOEither-returning function into a Kleisli arrow for StateReaderIOEither.
 func FromReaderIOEitherK[S, R, E, A, B any](f readerioeither.Kleisli[R, E, A, B]) Kleisli[S, R, E, A, B] {
 	return function.Flow2(
 		f,
@@ -161,26 +289,32 @@ func FromReaderIOEitherK[S, R, E, A, B any](f readerioeither.Kleisli[R, E, A, B]
 	)
 }

+// MonadChainReaderIOEitherK chains a StateReaderIOEither with a ReaderIOEither-returning function.
 func MonadChainReaderIOEitherK[S, R, E, A, B any](ma StateReaderIOEither[S, R, E, A], f readerioeither.Kleisli[R, E, A, B]) StateReaderIOEither[S, R, E, B] {
 	return MonadChain(ma, FromReaderIOEitherK[S](f))
 }

+// ChainReaderIOEitherK is the curried version of [MonadChainReaderIOEitherK].
 func ChainReaderIOEitherK[S, R, E, A, B any](f readerioeither.Kleisli[R, E, A, B]) Operator[S, R, E, A, B] {
 	return Chain(FromReaderIOEitherK[S](f))
 }

+// MonadChainIOEitherK chains a StateReaderIOEither with an IOEither-returning function.
 func MonadChainIOEitherK[S, R, E, A, B any](ma StateReaderIOEither[S, R, E, A], f ioeither.Kleisli[E, A, B]) StateReaderIOEither[S, R, E, B] {
 	return MonadChain(ma, FromIOEitherK[S, R](f))
 }

+// ChainIOEitherK is the curried version of [MonadChainIOEitherK].
 func ChainIOEitherK[S, R, E, A, B any](f ioeither.Kleisli[E, A, B]) Operator[S, R, E, A, B] {
 	return Chain(FromIOEitherK[S, R](f))
 }

+// MonadChainEitherK chains a StateReaderIOEither with an Either-returning function.
 func MonadChainEitherK[S, R, E, A, B any](ma StateReaderIOEither[S, R, E, A], f either.Kleisli[E, A, B]) StateReaderIOEither[S, R, E, B] {
 	return MonadChain(ma, FromEitherK[S, R](f))
 }

+// ChainEitherK is the curried version of [MonadChainEitherK].
 func ChainEitherK[S, R, E, A, B any](f either.Kleisli[E, A, B]) Operator[S, R, E, A, B] {
 	return Chain(FromEitherK[S, R](f))
 }