CS.Results 1.1.0

Result Object Pattern Library

This library provides a flexible and easy-to-use implementation of the Result Object Pattern in C#. It helps in handling success and error cases in a standardized way, improving code readability and reducing error-prone conditional logic.

Features

1. Result Types

The library provides two main result types: Result and Result<TValue>. Result represents an operation that can succeed or fail without returning a value, while Result<TValue> represents an operation that can succeed with a value of type TValue or fail.

2. Error Handling

Errors are handled using the IError interface, allowing for flexible and customizable error definitions. The library includes a basic Error implementation and allows for custom error types.

3. Error Factory

An ErrorFactory class is provided to create common error types, such as validation errors, not found errors, and conflict errors. This makes it easy to generate standardized errors throughout your application.

4. Handling Success and Failure in a fluent manner

The library provides synchronous Handle and asynchronous HandleAsync methods for handling the success and failure of operations. These methods take handlers for success and failure scenarios, making it easy to define what should happen in each case.

5. Implicit Conversions

Implicit conversions are supported from IError to Result and from a value of type TValue to Result<TValue>. This feature simplifies the creation of result objects from errors and values.

6. Error Matching

The library includes methods for matching errors by code, making it easy to identify specific errors and respond accordingly.

7. Custom Errors

Users can define custom errors by implementing the IError interface. This allows for more detailed and application specific error handling.

8. Immutable Results

Results are immutable, ensuring that once a result is created, its state (success or failure) and any associated errors cannot be changed. This immutability ensures consistency and predictability in error handling.

9. Composable Error Collections

The library supports creating results with multiple errors, enabling comprehensive error reporting for operations that may encounter multiple issues.

10. Extensibility

The design of the library allows for extensibility. Developers can create custom error types by implementing the IError interface.

Installation

dotnet add package CS.Results --version 1.1.0

Usage

Creating Results

Successful

var result = Result.Success();
var resultWithValue = Result<TestEntity>.Success(new TestEntity { Id = Guid.NewGuid(), Name = "Test Entity" });

Failure

var error = new CustomError("ERR01", "An error occurred");
var errorResult = Result.FromError(error);

var errors = new List<IError>
{
    new Error("ERR01", "First error"),
    new Error("ERR02", "Second error")
};
var multiErrorResult = Result.FromErrors(errors);

Checking Result Status

if (result.IsSuccess)
{
    Console.WriteLine("Operation was successful");
}
else
{
    Console.WriteLine("Operation failed");
}

Handling Results

Synchronous Handling

result.Handle(
    successHandler: () => Console.WriteLine("Success"),
    failureHandler: errors => Console.WriteLine($"Failure: {string.Join(", ", errors.Select(e => e.Message))}")
);

resultWithValue.Handle(
    successHandler: value => Console.WriteLine($"Success: {value.Name}"),
    failureHandler: errors => Console.WriteLine($"Failure: {string.Join(", ", errors.Select(e => e.Message))}")
);

Asynchronous Handling

await result.HandleAsync(
    successHandler: async () => Console.WriteLine("Success"),
    failureHandler: async errors => Console.WriteLine($"Failure: {string.Join(", ", errors.Select(e => e.Message))}")
);

await resultWithValue.HandleAsync(
    successHandler: async value => Console.WriteLine($"Success: {value.Name}"),
    failureHandler: async errors => Console.WriteLine($"Failure: {string.Join(", ", errors.Select(e => e.Message))}")
);

);

Error Matching

By Error Code as string:

if (result.MatchErrorByCode("ERR01"))
{
    Console.WriteLine("Error code ERR01 matched");
}

By Error as reference:

var customError = new CustomError("ER01", "Custom error");
result.MatchErrorByCode(customError);

Implicit Conversions

Result result = new CustomError("ERR01", "An error occurred");
Result<TestEntity> resultWithValue = new TestEntity { Id = Guid.NewGuid(), Name = "Test Product" };

Error Factory

The ErrorFactory class provides convenient methods to create common errors:

var notFoundError = ErrorFactory.NotFound("Item not found");
var validationError = ErrorFactory.ValidationFailure("Validation failed");

Unit Tests

This library includes extensive unit tests to verify its functionality. The tests are written using the XUnit framework and cover various scenarios for both Result and Result<TValue> classes.