SharpUtils.Results 1.0.2

Results

A comprehensive functional results library for .NET 9 and C# 13, providing robust error handling patterns and composition primitives. This library helps eliminate exception-based error handling in favor of a more functional approach that's type-safe, composable, and easier to reason about.

Russian version (������� ������)

Overview

Results is a lightweight library implementing the Result pattern (also known as the Either monad in functional programming). It encapsulates the outcome of an operation that can either succeed with a value or fail with an error message, making error handling more explicit and predictable.

Installation

Install the package from NuGet:

dotnet add package SharpUtils.Results

Or via the NuGet Package Manager:

Install-Package SharpUtils.Results

Key Components

Result<T>

The core generic class representing an operation result:

• Properties:

  • Value: The result value (when successful)
  • ErrorMessage: The error details (when failed)
  • IsSuccess: Boolean indicating success
  • IsFailure: Boolean indicating failure

• Factory Methods:

  • Success(T value): Creates a successful result with a value
  • Failure(string errorMessage): Creates a failed result with an error message

• Pattern Matching:

  • Match<TResult>(Func<T, TResult> onSuccess, Func<string, TResult> onFailure): Handles both success and failure cases
  • MatchAsync<TResult>(...): Asynchronous version of Match

• Transformation:

  • Map<U>(Func<T, U> mapper): Transforms the value if successful
  • MapAsync<U>(Func<T, Task<U>> mapper): Asynchronously transforms the value
  • Bind<U>(Func<T, Result<U>> binder): Chains results together
  • BindAsync<U>(Func<T, Task<Result<U>>> binder): Asynchronously chains results

• Callbacks:

  • OnSuccess(Action<T> action): Executes an action if successful
  • OnFailure(Action<string> action): Executes an action if failed

• Value Extraction:

  • ValueOrDefault(T defaultValue): Safely extracts the value or returns a default

• Operator Overloads:

  • Implicit conversion from T to Result<T>
  • Implicit conversion from Result<T> to bool (true if successful)
  • Implicit conversion from Result<T> to T (throws if failed)

Result (Non-generic)

A specialization for operations that don't return a value:

• Success(): Creates a successful result with no value
• Failure(string errorMessage): Creates a failed result with an error message

PaginatedResult<T>

Extends Result<IEnumerable<T>> with pagination metadata:

• Properties:

  • Page: Current page number
  • PageSize: Number of items per page
  • TotalItems: Total number of items across all pages
  • TotalPages: Calculated total number of pages

• Factory Methods:

  • Success(IEnumerable<T> value, uint page, uint pageSize, uint totalItems)
  • Failure(string errorMessage)
  • Empty(uint page, uint pageSize)

• Specialized Methods:

  • MapItems<U>(Func<T, U> mapper): Maps each item in the collection
  • MapItemsAsync<U>(...): Asynchronously maps items
  • BindItems<U>(...): Binds each item to a new result
  • BindItemsAsync<U>(...): Asynchronously binds items

Unit

Represents a void value, used in the non-generic Result implementation.

Usage Examples

Basic Result Usage

using Results;

// Creating successful and failed results
var success = Result<int>.Success(42);
var failure = Result<int>.Failure("Something went wrong");

// Checking result status
if (success.IsSuccess)
{
    Console.WriteLine($"Value: {success.Value}");
}

// Using pattern matching
var message = success.Match(
    value => $"The answer is {value}",
    error => $"Error occurred: {error}"
);

// Using callbacks
success
    .OnSuccess(value => Console.WriteLine($"Success: {value}"))
    .OnFailure(error => Console.WriteLine($"Error: {error}"));

// Transforming results
var transformed = success
    .Map(x => x * 2)
    .Map(x => x.ToString());

// Chaining operations
var chained = success
    .Bind(x => TryDivide(100, x))
    .Bind(x => TryParse(x.ToString()));

// Using operator overloads
Result<int> implicitSuccess = 42; // Implicit conversion from value
bool isSuccessful = success;      // Implicit conversion to bool

Using PaginatedResult

// Creating a paginated result
var pagedData = PaginatedResult<string>.Success(
    new[] { "Item1", "Item2", "Item3" },
    page: 1,
    pageSize: 10,
    totalItems: 25
);

// Accessing pagination information
Console.WriteLine($"Page {pagedData.Page} of {pagedData.TotalPages}");
Console.WriteLine($"Items: {pagedData.Value!.Count()} of {pagedData.TotalItems}");

// Transforming all items in the collection
var upperCaseItems = pagedData.MapItems(item => item.ToUpper());

// Binding items to other results
var boundItems = pagedData.BindItems(item => 
    item.Length > 5 
        ? Result<int>.Success(item.Length) 
        : Result<int>.Failure("Item too short")
);

Async Operations

// Async transformations
var asyncResult = await Result<int>.Success(42)
    .MapAsync(async x => {
        await Task.Delay(100);
        return x * 2;
    });

// Async binding
var asyncBound = await Result<string>.Success("42")
    .BindAsync(async s => {
        await Task.Delay(100);
        if (int.TryParse(s, out var n))
            return Result<int>.Success(n);
        return Result<int>.Failure("Not a number");
    });

Error Handling Patterns

Railway-Oriented Programming

This library supports the railway-oriented programming pattern, where functions can be composed together while handling errors gracefully:

// Define operations that return Results
Result<User> GetUser(string id) => /* ... */;
Result<Order> GetLatestOrder(User user) => /* ... */;
Result<Receipt> GenerateReceipt(Order order) => /* ... */;
Result<Unit> SendEmail(Receipt receipt, User user) => /* ... */;

// Chain operations, automatically handling failures
var result = GetUser("user123")
    .Bind(GetLatestOrder)
    .Bind(GenerateReceipt)
    .Bind(receipt => SendEmail(receipt, user));

// Handle the final result
result.Match(
    _ => Console.WriteLine("Email sent successfully"),
    error => Console.WriteLine($"Failed: {error}")
);

Target Frameworks

• .NET 9.0
• .NET 8.0
• .NET 7.0
• .NET 6.0
• .NET Standard 2.1
• .NET Standard 2.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.