Add `match` Function to Result Utility

[AliiiBenn]

Summary

Add a standalone match function to the Result utility that provides functional pattern matching for Result objects. This function will allow developers to handle both success and error cases in a clean, declarative way.

Description

The match function will be a standalone utility function that takes a Result object and two callback functions - one for handling success cases and one for handling error cases. It will inspect the Result and call the appropriate callback based on whether the Result contains a success value or an error.

Technical Implementation

Function Signature

def match(result: Result[T, E], *, on_success: Callable[[T], R], on_error: Callable[[E], R]) -> R:

Implementation Details

• Function Location: src/utils/result.py
• Type Parameters:
  • T: The success type parameter of the Result
  • E: The error type parameter of the Result
  • R: The return type of both callback functions
• Parameters:
  • result: The Result object to match against
  • on_success: Keyword-only function that takes a success value (T) and returns R
  • on_error: Keyword-only function that takes an error value (E) and returns R
• Return Type: R (the return type of both callback functions)
• Behavior:
  • If result.is_ok() returns True, call on_success(result.unwrap())
  • If result.is_err() returns True, call on_error(result.unwrap())
  • Use * to force keyword-only arguments for on_success and on_error

Files to Modify

• src/utils/result.py: Add the new match function to this file

Expected Usage Examples

Basic Usage

from utils.result import Ok, Err, match

# Success case
result = Ok(42)
value = match(
    result,
    on_success=lambda x: x * 2,
    on_error=lambda e: 0
)
# value == 84

# Error case
result = Err("Not found")
value = match(
    result,
    on_success=lambda x: x * 2,
    on_error=lambda e: 0
)
# value == 0

With Exception Handling

from utils.result import Ok, Err, match

result = Ok("data")
response = match(
    result,
    on_success=lambda r: LogResponse.from_orm(r),
    on_error=lambda r: raise r
)

Type-Specific Handling

from utils.result import Ok, Err, match

result = Ok(42)
result = Err("error message")

def handle_success(value: int) -> str:
    return f"Success: {value}"

def handle_error(error: str) -> str:
    return f"Error: {error}"

result_str = match(
    result,
    on_success=handle_success,
    on_error=handle_error
)

Acceptance Criteria

1. The match function is added to src/utils/result.py
2. Function signature uses * for keyword-only arguments
3. Function properly checks result.is_ok() and result.is_err()
4. Function calls the appropriate callback based on result type
5. Function includes proper type hints following existing code style
6. Function is a standalone function, not a method of the Result class
7. Function works with both Ok and Err instances
8. Function signature matches the required implementation

Code Style Requirements

• Follow the existing type hint style in the file
• Use the same import patterns (Generic, TypeVar, Callable, Protocol)
• Maintain consistent formatting and indentation
• Add appropriate docstring following the style of existing code
• Use the same naming conventions as the rest of the codebase

Testing

The function should be tested with various scenarios:

• Success values of different types
• Error values of different types
• Functions that return different types
• Functions that may throw exceptions
• Edge cases (None values if applicable)