Namespace: Zentient.Results Assembly: Zentient.Results.dll Available since: v0.1.0

Represents the concrete, immutable implementation of the generic result interface IResult<T>, encapsulating a typed value on success or structured errors on failure, along with diagnostic messages and a semantic result status.

Result<T> is the backbone of typed outcome modeling across Zentient applications—powering command/query results, service outcomes, and transport-agnostic adapters.

The Result<T> class adheres to a functional, declarative, and immutable model. It allows precise, type-safe control over operation results without resorting to exceptions or ambiguous null patterns.

• ✅ Immutability – Once created, a Result<T> cannot change state.
• 🧭 Semantic Clarity – Makes success/failure explicit, promoting reliable control flows.
• 🔀 Structured Metadata – Encodes status, traceability, and errors as first-class citizens.
• 🔧 Adapter Ready – Suitable for seamless protocol mapping (e.g., ProblemDetails, gRPC).
• ♻️ Extensible API Surface – Designed for use with fluent extensions (Map, Bind, Match).

public sealed class Result<T> : IResult<T>

• Signature: public Result(T? value, IReadOnlyList<ErrorInfo> errors, IResultStatus status, IReadOnlyList<string> messages)

• Summary: Constructs a fully-defined result instance with explicit state.

• Parameters:

  • value (T?): The result value (may be null for failure).
  • errors (IReadOnlyList<ErrorInfo>): The error list (empty if successful).
  • status (IResultStatus): Semantic status of the result.
  • messages (IReadOnlyList<string>): Diagnostic or user-facing messages.

• Remarks: Used internally and by factory methods. Prefer Success(...) or Failure(...) for instantiation.

• Signature: public static Result<T> Success(T value)

• Summary: Creates a successful result with a provided value.

• Parameters:

  • value (T): The success result value.

• Return Value: Result<T>: A success result containing the given value.

• Behavior: Initializes an empty Errors list and Status.Success.

var result = Result<string>.Success("OK");

• Signature: public static Result<T> Failure(T? value, IEnumerable<ErrorInfo>, IResultStatus)

• Summary: Creates a failed result instance with structured error information.

• Parameters:

  • value (T?): Optional payload to include.
  • errors (IEnumerable<ErrorInfo>): One or more error descriptors.
  • status (IResultStatus): Failure status.

• Return Value: Result<T>: A failed result instance.

var result = Result<string>.Failure(null, new[] { ErrorInfo.Create(...)} , ResultStatus.FailedValidation);

• Signature: public static Result<T> FromException(T? value, Exception ex)

• Summary: Constructs a failed result from an unhandled exception.

• Parameters:

  • value (T?): Optional value to preserve.
  • ex (Exception): The thrown exception.

• Return Value: Result<T>

• Behavior: Automatically converts exception to ErrorInfo with diagnostic metadata.

• Type: T
• Summary: The success value of the result.
• Behavior: Only populated when IsSuccess == true.

• Type: IReadOnlyList<ErrorInfo>
• Summary: Structured error list associated with this result.
• Behavior: Empty if the result succeeded.

• Type: IReadOnlyList<string>
• Summary: Supplementary trace messages.
• Behavior: May include debug hints or observability logs.

• Type: IResultStatus
• Summary: Protocol-neutral semantic result code.
• Behavior: Used for mapping to gRPC, HTTP, etc.

• Type: string?
• Summary: Shortcut to the first error’s message, if available.

• Type: bool
• Summary: Indicates the binary result state.

Result<int> ParseId(string input)
{
    if (int.TryParse(input, out var id))
        return Result<int>.Success(id);

    return Result<int>.Failure(default, new[] {
        ErrorInfo.Create("InvalidId", "The input is not a valid integer.")
    }, ResultStatus.FailedValidation);
}

var result = ParseId("42");

if (result.IsSuccess)
    Console.WriteLine(result.Value);
else
    Console.WriteLine($"Failed: {result.ErrorMessage}");

• Result<T> is immutable; mutation after construction is unsupported.
• Designed for use with functional pipelines via extension methods.
• Use FromException(...) for fallback handling of unexpected failures.

• CQRS Pipelines: Used for returning values in commands/queries.
• HTTP Adapters: Mapped to ProblemDetails for transport translation.
• gRPC: Exposed via GrpcResult<T>, carrying both value and trailers.
• Serialization: Optimized for System.Text.Json and JSON-RPC contracts.

• IResult<T>
• ErrorInfo
• Result
• ResultStatus
• Map
• Bind

#API #ResultModel #TypedResult #ErrorHandling #Immutability #FunctionalCore #ZentientCore

Last Updated: 2025-06-21 Version: 0.4.0