mirror of
https://github.com/IBM/fp-go.git
synced 2025-11-23 22:14:53 +02:00
148 lines
6.0 KiB
Go
148 lines
6.0 KiB
Go
// Copyright (c) 2024 - 2025 IBM Corp.
|
|
// All rights reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
// Package statereaderioresult provides a functional programming abstraction that combines
|
|
// four powerful concepts: State, Reader, IO, and Result monads, specialized for Go's context.Context.
|
|
//
|
|
// # StateReaderIOResult
|
|
//
|
|
// StateReaderIOResult[S, A] represents a computation that:
|
|
// - Manages state of type S (State)
|
|
// - Depends on a [context.Context] (Reader)
|
|
// - Performs side effects (IO)
|
|
// - Can fail with an [error] or succeed with a value of type A (Result)
|
|
//
|
|
// This is a specialization of StateReaderIOEither with:
|
|
// - Context type fixed to [context.Context]
|
|
// - Error type fixed to [error]
|
|
//
|
|
// This is particularly useful for:
|
|
// - Stateful computations with dependency injection using Go contexts
|
|
// - Error handling in effectful computations with state
|
|
// - Composing operations that need access to context, manage state, and can fail
|
|
// - Working with Go's standard context patterns (cancellation, deadlines, values)
|
|
//
|
|
// # Core Operations
|
|
//
|
|
// Construction:
|
|
// - Of/Right: Create a successful computation with a value
|
|
// - Left: Create a failed computation with an error
|
|
// - FromState: Lift a State into StateReaderIOResult
|
|
// - FromIO: Lift an IO into StateReaderIOResult
|
|
// - FromResult: Lift a Result into StateReaderIOResult
|
|
// - FromIOResult: Lift an IOResult into StateReaderIOResult
|
|
// - FromReaderIOResult: Lift a ReaderIOResult into StateReaderIOResult
|
|
//
|
|
// Transformation:
|
|
// - Map: Transform the success value
|
|
// - Chain: Sequence dependent computations (monadic bind)
|
|
// - Flatten: Flatten nested StateReaderIOResult
|
|
//
|
|
// Combination:
|
|
// - Ap: Apply a function in a context to a value in a context
|
|
//
|
|
// Context Access:
|
|
// - Asks: Get a value derived from the context
|
|
// - Local: Run a computation with a modified context
|
|
//
|
|
// Kleisli Arrows:
|
|
// - FromResultK: Lift a Result-returning function to a Kleisli arrow
|
|
// - FromIOK: Lift an IO-returning function to a Kleisli arrow
|
|
// - FromIOResultK: Lift an IOResult-returning function to a Kleisli arrow
|
|
// - FromReaderIOResultK: Lift a ReaderIOResult-returning function to a Kleisli arrow
|
|
// - ChainResultK: Chain with a Result-returning function
|
|
// - ChainIOResultK: Chain with an IOResult-returning function
|
|
// - ChainReaderIOResultK: Chain with a ReaderIOResult-returning function
|
|
//
|
|
// Do Notation (Monadic Composition):
|
|
// - Do: Start a do-notation chain
|
|
// - Bind: Bind a value from a computation
|
|
// - BindTo: Bind a value to a simple constructor
|
|
// - Let: Compute a derived value
|
|
// - LetTo: Set a constant value
|
|
// - ApS: Apply in sequence (for applicative composition)
|
|
// - BindL/ApSL/LetL/LetToL: Lens-based variants for working with nested structures
|
|
//
|
|
// # Example Usage
|
|
//
|
|
// type AppState struct {
|
|
// RequestCount int
|
|
// LastError error
|
|
// }
|
|
//
|
|
// // A computation that manages state, depends on context, performs IO, and can fail
|
|
// func processRequest(data string) statereaderioresult.StateReaderIOResult[AppState, string] {
|
|
// return func(state AppState) readerioresult.ReaderIOResult[pair.Pair[AppState, string]] {
|
|
// return func(ctx context.Context) ioresult.IOResult[pair.Pair[AppState, string]] {
|
|
// return func() result.Result[pair.Pair[AppState, string]] {
|
|
// // Check context for cancellation
|
|
// if ctx.Err() != nil {
|
|
// return result.Error[pair.Pair[AppState, string]](ctx.Err())
|
|
// }
|
|
// // Update state
|
|
// newState := AppState{RequestCount: state.RequestCount + 1}
|
|
// // Perform IO operations
|
|
// return result.Of(pair.MakePair(newState, "processed: " + data))
|
|
// }
|
|
// }
|
|
// }
|
|
// }
|
|
//
|
|
// // Compose operations using do-notation
|
|
// result := function.Pipe3(
|
|
// statereaderioresult.Do[AppState](State{}),
|
|
// statereaderioresult.Bind(
|
|
// func(result string) func(State) State { return func(s State) State { return State{result: result} } },
|
|
// func(s State) statereaderioresult.StateReaderIOResult[AppState, string] {
|
|
// return processRequest(s.input)
|
|
// },
|
|
// ),
|
|
// statereaderioresult.Map[AppState](func(s State) string { return s.result }),
|
|
// )
|
|
//
|
|
// // Execute with initial state and context
|
|
// initialState := AppState{RequestCount: 0}
|
|
// ctx := context.Background()
|
|
// outcome := result(initialState)(ctx)() // Returns result.Result[pair.Pair[AppState, string]]
|
|
//
|
|
// # Context Integration
|
|
//
|
|
// This package is designed to work seamlessly with Go's context.Context:
|
|
//
|
|
// // Using context values
|
|
// getUserID := statereaderioresult.Asks[AppState, string](func(ctx context.Context) statereaderioresult.StateReaderIOResult[AppState, string] {
|
|
// userID, ok := ctx.Value("userID").(string)
|
|
// if !ok {
|
|
// return statereaderioresult.Left[AppState, string](errors.New("missing userID"))
|
|
// }
|
|
// return statereaderioresult.Of[AppState](userID)
|
|
// })
|
|
//
|
|
// // Using context cancellation
|
|
// withTimeout := statereaderioresult.Local[AppState, string](func(ctx context.Context) context.Context {
|
|
// ctx, _ = context.WithTimeout(ctx, 5*time.Second)
|
|
// return ctx
|
|
// })
|
|
//
|
|
// # Monad Laws
|
|
//
|
|
// StateReaderIOResult satisfies the monad laws:
|
|
// - Left Identity: Of(a) >>= f ≡ f(a)
|
|
// - Right Identity: m >>= Of ≡ m
|
|
// - Associativity: (m >>= f) >>= g ≡ m >>= (x => f(x) >>= g)
|
|
//
|
|
// These laws are verified in the testing subpackage.
|
|
package statereaderioresult
|