This wiki serves as the comprehensive documentation hub for Zentient.Results, a modern, lightweight, and extensible .NET library for structured result handling. Whether you're a developer evaluating the framework, an architect designing robust systems, or a contributor looking to dive deeper, you'll find the information you need here.

Zentient.Results empowers .NET developers to build more reliable, maintainable, and observable applications by providing a standardized, explicit, and immutable way to represent the outcome of any operation. It helps you move beyond traditional exception-based control flow for expected outcomes, offering a clear and consistent pattern for success, failure, and rich error propagation.

• Clarity & Predictability: Explicitly communicate success or failure and associated data in your method signatures.
• Structured Errors: Get rich, categorized error information (codes, messages, data, nested errors) instead of just generic exceptions.
• Functional Composability: Chain operations fluently with Map, Bind, OnSuccess, and OnFailure for clean, readable code.
• Clean Architecture Alignment: Seamlessly integrate with Clean Architecture, CQRS, and Domain-Driven Design principles by separating business logic from error handling mechanics.
• Enhanced Observability: Facilitate better logging, tracing, and diagnostics with standardized error contexts.
• Testability: Write more robust unit and integration tests by explicitly asserting expected result states and error details.

To begin using Zentient.Results in your project, install it via NuGet:

dotnet add package Zentient.Results

Basic Usage Example:

using Zentient.Results;
using System;

public class DataService
{
    public IResult<string> FetchData(int id)
    {
        if (id <= 0)
        {
            return Result<string>.Failure(
                default, // Value is default for failure
                new ErrorInfo(ErrorCategory.Validation, "InvalidId", "ID must be positive."),
                ResultStatuses.BadRequest
            );
        }

        if (id == 404)
        {
            return Result<string>.NotFound(
                new ErrorInfo(ErrorCategory.NotFound, "DataNotFound", $"Data with ID {id} not found.")
            );
        }

        return Result<string>.Success($"Data for ID: {id}");
    }
}

// In your application logic:
var service = new DataService();

// Handle success
IResult<string> successResult = service.FetchData(123);
if (successResult.IsSuccess)
{
    Console.WriteLine($"Success: {successResult.Value}"); // Output: Success: Data for ID: 123
}

// Handle failure
IResult<string> failureResult = service.FetchData(-5);
if (failureResult.IsFailure)
{
    Console.WriteLine($"Failure ({failureResult.Status.Code}): {failureResult.Error}"); // Output: Failure (400): ID must be positive.
    // Access full error details: failureResult.Errors
}

// Chaining operations
IResult<int> parsedIdResult = service.FetchData(500)
    .Map(data => int.Parse(data.Replace("Data for ID: ", ""))); // Map string to int if successful
    
if (parsedIdResult.IsSuccess)
{
    Console.WriteLine($"Parsed ID: {parsedIdResult.Value}"); // Output: Parsed ID: 500
}

For more examples and detailed usage instructions, visit:

• Quick Start Guide
• Basic Usage Patterns

Explore the wiki to deepen your understanding of Zentient.Results:

• Understanding IResult and IResult<T>
• Structured Error Handling with ErrorInfo and ErrorCategory
• Managing Operation Status with IResultStatus and ResultStatuses

• Chaining and Composing Operations (Map, Bind, Then)
• Integrating with ASP.NET Core Controllers and Minimal APIs
• Customizing Result Statuses and Error Information
• Serialization and Deserialization with System.Text.Json

• Architecture Overview
• Key Design Decisions

We welcome contributions from the community! If you're interested in helping us improve Zentient.Results, please refer to:

• Contributing Guidelines
• Code of Conduct

• Report an Issue: If you find a bug or have a feature request, please open an issue on our [GitHub Issues page].
• Discussions: Join our [Discussions] to ask questions or share ideas.

Thank you for your interest in Zentient.Results! We hope it helps you build more robust and maintainable .NET applications.