Somum.Results 10.1.6

Somum.Results

Somum.Results is a .NET Standard 2.0 class library that provides a consistent result model for operations that may succeed or fail.

It separates an operation's success state, returned value, HTTP status code, optional application error code, and structured errors. Use it across handlers, services, and API boundaries to return expected failures without relying on exceptions for normal control flow.

Target Framework

• .NET Standard 2.0

The library can be referenced from .NET Standard-compatible libraries and modern .NET applications.

Core Types

Success and Failure Semantics

A Result or Result<T> is successful when its ResultErrors collection contains no ResultError entries:

if (result.IsSuccess)
{
    // Process result.Value for Result<T>.
}

if (result.IsFailure)
{
    // Inspect result.Errors.
}

ResultErrors.IsSuccess is determined by the number of errors, not by the HTTP status code. This allows callers to associate a status code with a result independently of whether the error collection is empty.

Creating Results

Successful operations

Use the static factory methods for explicit success results:

using System.Net;
using Somum.Results;

Result completed = Result.Success();
Result created = Result.Success(HttpStatusCode.Created);

Result<long> identifier = Result.Success(42L, HttpStatusCode.Created);
Result<string> name = Result<string>.Success("Campaign managers");

A value can also be implicitly converted to Result<T>:

Result<string> result = "Campaign managers";

Failed operations

Create structured errors with ResultError or ResultErrors:

using System.Net;
using Somum.Results;

var errors = new ResultErrors(HttpStatusCode.BadRequest, "validation_failed")
    .AddError("name", "Name is required.")
    .AddError("roles", "At least one role is required.");

Result failure = Result.Failure(errors);
Result<long> typedFailure = errors;

A single ResultError can be combined with an HTTP status code:

ResultErrors errors = new ResultError("name", "Name is required.")
    + HttpStatusCode.BadRequest;

Error Details

A ResultError contains:

• Prop — the affected property name or an operation-level identifier.
• Message — the error message or message-template key.
• Args — optional values used to format the message.

ResultErrors exposes errors as IReadOnlyList<ResultError>. Add errors through AddError; do not mutate the returned collection.

Status Codes and Composition

Use the + operator to return a copy of a result or error collection with a different HTTP status code:

using System.Net;
using Somum.Results;

Result<string> result = "Created";
result += HttpStatusCode.Created;

ResultErrors errors = new();
errors = errors + HttpStatusCode.UnprocessableEntity;

For Result<T>, adding a ResultError appends that error to the existing result and causes IsFailure to become true:

Result<string> result = "value";
result += new ResultError("value", "The value is invalid.");

Asynchronous Interoperability

Result, Result<T>, and ResultErrors provide implicit conversions to completed Task<Result> or Task<Result<T>> instances. This is useful when a method returns a task but its outcome is already available:

Task<Result> ValidateAsync(bool isValid)
{
    if (isValid)
        return Result.Success();

    return new ResultError("request", "Request is invalid.")
        + HttpStatusCode.BadRequest;
}

Prefer async/await when actual asynchronous work is required.

Usage

Reference the project from another project in the solution:

<ItemGroup>
  <ProjectReference Include="..\Somum.Results\Somum.Results.csproj" />
</ItemGroup>

Guidelines

• Use results for expected validation, authorization, and business-rule failures.
• Use exceptions for unexpected or unrecoverable failures.
• Check IsSuccess before reading Result<T>.Value; failed results can contain the default value of T.
• Preserve the HTTP status code and application error code when propagating failures.
• Use stable property identifiers and message keys when errors are consumed by clients or localization layers.