Resulz 2.0.0

Resulz

Resulz is a small "operation result" library with a fluent validation framework for .NET. Instead of throwing exceptions for expected failures, return an OperationResult (or OperationResult<T>) that carries success state, contextual error messages, and optional additional information.

Packages

All packages target .NET 10. Version 1.x targeted .NET 8; 2.x is a breaking change because of the target framework bump.

dotnet add package Resulz
dotnet add package Resulz.Web
dotnet add package Resulz.Validation.Countries

Operation results

OperationResult represents an operation without a return value; OperationResult<T> carries a value. A result is successful when it has no errors.

using Resulz;

OperationResult success = OperationResult.MakeSuccess();

OperationResult failure = OperationResult.MakeFailure(
    ErrorMessage.Create("Email", "EMAIL_REQUIRED"));

if (!failure.Success)
{
    foreach (ErrorMessage error in failure.Errors)
    {
        Console.WriteLine($"{error.Context}: {error.Description}");
    }
}

Errors can be appended, prefixed, and translated after creation:

var result = OperationResult
    .MakeSuccess()
    .AppendError("Email", "EMAIL_NOT_VALID")
    .AppendContextPrefix("Customer.")
    .SetAdditionalInfo(OperationResultStandardInfoCodes.BAD_REQUEST);

// Error context is now "Customer.Email"

AdditionalInfo is a free-form string used to carry a status code or description. Multiple values passed to SetAdditionalInfo are joined with |; each call replaces the previous value. Use the OperationResultStandardInfoCodes helpers instead of raw strings:

result.SetNotFoundCode();        // "NOT_FOUND"
result.SetNotAuthorizedCode();   // "NOT_AUTHORIZED"
result.SetNotValidCode();        // "NOT_VALID"
result.SetBadRequestCode();      // "BAD_REQUEST"
result.SetGenericErrorCode();    // "GENERIC_ERROR"

Results with a value

OperationResult<Customer> created = OperationResult<Customer>.MakeSuccess(customer);

if (created.Success)
{
    Customer value = created.Value;
}

Implicit conversions keep fluent code concise:

OperationResult<int> ok = 42;                       // wraps the value as a success
OperationResult plain = ok;                         // drops the value
OperationResult<int> failed = failure;              // carries the errors, no value

Converting a successful non-generic result to OperationResult<T> throws ArgumentException, because there is no value to carry. This conversion exists for failure propagation inside fluent chains.

Fluent helpers

All helpers return the original result (when successful) so they can be chained:

OperationResult result = OperationResult
    .MakeSuccess()
    .IfSuccess(r => Console.WriteLine("ok"))
    .IfFailed(r => Console.WriteLine($"{r.Errors.Count()} error(s)"));

OperationResult saved = result.Then(() => SaveChanges());

OperationResult also defines true/false and & operators, so if (result) checks Success and result1 & result2 merges the errors of both.

Validation

Validation rules are extension methods on ValueChecker<T>. Start a chain from a successful result with With(value, context) and read the final result from .Result:

using Resulz.Validation;

var result = OperationResult
    .MakeSuccess()
    .With(name, nameof(name)).Required().StringLength(250)
    .With(email, nameof(email)).Required().Email()
    .With(age, nameof(age)).Between(18, 100)
    .Result;

Each rule has two forms: a default-message overload and one that accepts a custom message. Default descriptions follow the {CONTEXT}_{CODE} convention (uppercased), for example NAME_REQUIRED or EMAIL_NOT_EMAIL.

Custom messages are passed as the last argument:

.With(loanAmount, nameof(loanAmount))
    .GreaterThen(0, "LOAN_AMOUNT_MUST_BE_POSITIVE")

By default every rule in the chain runs and can add an error. Call StopOnError() on the checker to skip the remaining rules once the result has at least one error:

.With(name, nameof(name)).StopOnError().Required().StringLength(250)

ASP.NET Core integration

Resulz.Web converts results to action results. Add the package and use ToActionResult():

using Resulz.Web;

[ApiController]
public class CustomersController : ControllerBase
{
    [HttpPost]
    public IActionResult Create(CustomerRequest request)
    {
        var result = Customer.Create(request.Name, request.Email);
        return result.ToActionResult();
    }
}

ToActionResult maps AdditionalInfo to HTTP responses:

Country VAT validation

Resulz.Validation.Countries validates EU VAT numbers and VAT recipient codes:

using Resulz.Validation;
using Resulz.Validation.Countries;

var result = OperationResult
    .MakeSuccess()
    .With(vatNumber, nameof(vatNumber)).ValidateVatNumber("IT")
    .With(recipientCode, nameof(recipientCode)).ValidateVatRecipientCode("IT")
    .Result;

VAT numbers may be supplied with or without the country prefix; CountrySafeVatNumber normalizes them before validation (for example "40474690803" becomes "IT40474690803"). Supported country codes: AT, BE, BG, CY, CZ, DE, DK, EE, EL (Greece), ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK. Any other code falls back to UnknownCountryContextValidator, which rejects every VAT number and recipient code.

Default descriptions are {CONTEXT}_NOT_VATNUMBER and {CONTEXT}_NOT_VATRECIPIENTCODE.

Building and testing

Prerequisites: .NET 10 SDK.

dotnet restore
dotnet build Resulz.sln -c Release
dotnet test Resulz.sln -c Release

# run a single test
dotnet test src/Resultz.UnitTest/Resulz.UnitTest.csproj -c Release \
  --filter "FullyQualifiedName~RequiredTestFailWithString"

# run the sample application
dotnet run --project src/Resulz.Samples

The sample application is interactive and waits for Enter before exiting.

The src/Resultz.UnitTest directory contains the Resulz.UnitTest.csproj project; the folder name is a historical typo.

Versioning and release

• The version for all three packages is defined once in src/Directory.Build.props (PackageVersion). Bump it there, never in individual project files.
• The three library projects have GeneratePackageOnBuild enabled, so a Release build produces .nupkg and .snupkg files in each bin/Release directory.
• The CI workflow (.github/workflows/resultz_build.yml) builds and tests on master. Publishing a GitHub release packs the three packages and publishes them to nuget.org.

Publishing uses NuGet Trusted Publishing over GitHub Actions OIDC, so no long-lived NuGet API key is stored in the repository. To configure it:

1. On nuget.org, create a trusted publishing policy for this repository: owner dogcane, repository Resulz, workflow file resultz_build.yml.
2. Add a repository secret NUGET_USER containing the nuget.org username (profile name), not the e-mail address.
3. Publish a GitHub release; the deploy job requests a short-lived API key via NuGet/login@v1 and pushes the packages with it.

License

GPL-3.0-only. See LICENSE.