FractalDataWorks.Results 0.4.0-preview.6

FractalDataWorks.Results

A result pattern library that provides a standardized way to handle operation outcomes with message support. This library implements the Result pattern to replace exceptions for expected failures.

Overview

The FractalDataWorks.Results library provides:

• IGenericResult and IGenericResult<T> interfaces for result handling
• GenericResult and GenericResult<T> concrete implementations
• NonResult unit type for operations that do not return values
• Integration with FractalDataWorks.Messages for structured message handling
• Functional programming methods (Map, Match) for result composition

Target Framework: .NET Standard 2.0 Dependencies: FractalDataWorks.Messages (via FractalDataWorks.Abstractions)

API Reference

IGenericResult Interface

From IGenericResult.cs:9-40:

public interface IGenericResult
{
    bool IsSuccess { get; }
    bool IsFailure { get; }
    bool IsEmpty { get; }
    bool Error { get; }
    string? CurrentMessage { get; }
    IReadOnlyList<IGenericMessage> Messages { get; }
}

IGenericResult<T> Generic Interface

From IGenericResult.cs:42-52:

public interface IGenericResult<out T> : IGenericResult
{
    T? Value { get; }
}

Note: The Map and Match methods are defined on the concrete GenericResult<T> class, not the interface.

GenericResult Implementation

From GenericResult.cs:12-184:

Message Handling:

• Stores messages as List<IGenericMessage> internally
• Supports construction with string, IGenericMessage, or collections of IGenericMessage
• IsEmpty returns true when message collection is empty
• CurrentMessage returns the last message (LIFO) or null
• Messages property provides read-only access to all messages

Factory Methods (from GenericResult.cs:106-183):

// Success results
public static IGenericResult Success() => new GenericResult(true);
public static IGenericResult Success(string message) => new GenericResult(true, message);
public static IGenericResult Success(IGenericMessage message) => new GenericResult(true, message);
public static IGenericResult Success<TMessage>(TMessage message) where TMessage : IGenericMessage
    => new GenericResult(true, message);
public static IGenericResult Success(IEnumerable<IGenericMessage> messages)
    => new GenericResult(true, messages);
public static IGenericResult Success(params IGenericMessage[] messages)
    => new GenericResult(true, messages);

// Failure results
public static IGenericResult Failure(string message) => new GenericResult(false, message);
public static IGenericResult Failure(IGenericMessage message) => new GenericResult(false, message);
public static IGenericResult Failure<TMessage>(TMessage message) where TMessage : IGenericMessage
    => new GenericResult(false, message);
public static IGenericResult Failure(IEnumerable<IGenericMessage> messages)
    => new GenericResult(false, messages);
public static IGenericResult Failure(params IGenericMessage[] messages)
    => new GenericResult(false, messages);

GenericResult<T> Generic Implementation

From GenericResult.cs:186-348:

Value Handling:

• _hasValue field tracks whether value is accessible (set to IsSuccess in constructors)
• IsEmpty returns !_hasValue (overrides base implementation)
• Value property throws InvalidOperationException when !_hasValue

Value Property (from GenericResult.cs:224-232):

public TResult Value
{
    get
    {
        if (!_hasValue)
            throw new InvalidOperationException("Cannot access value of a failed result.");
        return _value;
    }
}

Functional Methods (from GenericResult.cs:328-347):

public IGenericResult<TNew> Map<TNew>(Func<TResult, TNew> mapper)
{
    if (mapper == null)
        throw new ArgumentNullException(nameof(mapper));

    return IsSuccess
        ? GenericResult<TNew>.Success(mapper(Value))
        : GenericResult<TNew>.Failure(CurrentMessage ?? "Operation failed");
}

public T Match<T>(Func<TResult, T> success, Func<string, T> failure)
{
    if (success == null)
        throw new ArgumentNullException(nameof(success));
    if (failure == null)
        throw new ArgumentNullException(nameof(failure));

    return IsSuccess ? success(Value) : failure(CurrentMessage ?? string.Empty);
}

NonResult Unit Type

From NonResult.cs:12-60:

[ExcludeFromCodeCoverage]
public struct NonResult : IEquatable<NonResult>
{
    public static readonly NonResult Value;

    public bool Equals(NonResult other) => true;
    public override bool Equals(object? obj) => obj is NonResult;
    public override int GetHashCode() => 0;
    public override string ToString() => nameof(NonResult);

    public static bool operator ==(NonResult left, NonResult right) => true;
    public static bool operator !=(NonResult left, NonResult right) => false;
}

Usage Examples

The following examples are based on patterns demonstrated in the test suite.

Basic Result Creation and Checking

From GenericResultTests.cs:14-26:

var result = GenericResult.Success();

result.IsSuccess.ShouldBeTrue();
result.IsFailure.ShouldBeFalse();
result.Error.ShouldBeFalse();
result.IsEmpty.ShouldBeTrue();
result.CurrentMessage.ShouldBeNull();
result.Messages.ShouldBeEmpty();

From GenericResultTests.cs:29-44:

const string message = "Operation completed successfully";
var result = GenericResult.Success(message);

result.IsSuccess.ShouldBeTrue();
result.IsFailure.ShouldBeFalse();
result.IsEmpty.ShouldBeFalse();
result.CurrentMessage.ShouldBe(message);
result.Messages.Count.ShouldBe(1);
result.Messages[0].Message.ShouldBe(message);

Result with Value

From GenericResultTests.cs:361-375:

const int value = 42;
var result = GenericResult<int>.Success(value);

result.IsSuccess.ShouldBeTrue();
result.IsFailure.ShouldBeFalse();
result.IsEmpty.ShouldBeFalse();
result.Value.ShouldBe(value);
result.Messages.ShouldBeEmpty();

Failure Handling

From GenericResultTests.cs:595-603:

var result = GenericResult<int>.Failure("Error");

var exception = Should.Throw<InvalidOperationException>(() => result.Value);
exception.Message.ShouldBe("Cannot access value of a failed result.");

Working with Multiple Messages

From GenericResultTests.cs:79-100:

var messages = new List<IGenericMessage>
{
    new GenericMessage("Message 1"),
    new GenericMessage("Message 2"),
    new GenericMessage("Message 3")
};
var result = GenericResult.Success(messages);

result.IsSuccess.ShouldBeTrue();
result.IsEmpty.ShouldBeFalse();
result.Messages.Count.ShouldBe(3);
result.CurrentMessage.ShouldBe("Message 3"); // LIFO - last message

Map Transformation

From GenericResultTests.cs:629-655:

// Map transforms successful results
var result = (GenericResult<int>)GenericResult<int>.Success(5);
var mapped = result.Map(x => x * 2);

mapped.IsSuccess.ShouldBeTrue();
mapped.Value.ShouldBe(10);

// Map can change type
var intResult = (GenericResult<int>)GenericResult<int>.Success(42);
var stringResult = intResult.Map(x => x.ToString());

stringResult.IsSuccess.ShouldBeTrue();
stringResult.Value.ShouldBe("42");

Match for Branching Logic

From GenericResultTests.cs:716-733:

var result = (GenericResult<int>)GenericResult<int>.Success(42);
var successCalled = false;
var failureCalled = false;

var matchResult = result.Match(
    value => { successCalled = true; return value * 2; },
    error => { failureCalled = true; return 0; }
);

successCalled.ShouldBeTrue();
failureCalled.ShouldBeFalse();
matchResult.ShouldBe(84);

Key Behaviors

CurrentMessage Property (LIFO)

The CurrentMessage property returns the most recently added message (Last In, First Out):

From GenericResultTests.cs:319-334:

var messages = new[]
{
    new GenericMessage("First"),
    new GenericMessage("Second"),
    new GenericMessage("Third")
};
var result = GenericResult.Success(messages);

result.CurrentMessage.ShouldBe("Third"); // Returns last message

IsEmpty Behavior Differences

• GenericResult: IsEmpty returns true when message collection is empty
• GenericResult<T>: IsEmpty returns true when !_hasValue (i.e., when failed)

From GenericResultTests.cs:605-623:

var successResult = GenericResult<int>.Success(42);
successResult.IsEmpty.ShouldBeFalse(); // Has value

var failureResult = GenericResult<int>.Failure("Error");
failureResult.IsEmpty.ShouldBeTrue(); // No value

Map Failure Propagation

Map preserves failures and uses a default message if none exists:

From GenericResultTests.cs:697-709:

var result = (GenericResult<int>)GenericResult<int>.Failure(new GenericMessage(null!));
var mapped = result.Map(x => x * 2);

mapped.IsSuccess.ShouldBeFalse();
mapped.CurrentMessage.ShouldBe("Operation failed"); // Default message

Dependencies

• FractalDataWorks.Abstractions: Provides IGenericResult and IGenericResult<T> interfaces
• FractalDataWorks.Messages: Provides IGenericMessage and GenericMessage types

Related Packages

• FractalDataWorks.Messages - Message types used with results
• FractalDataWorks.Abstractions - Core interfaces