MonadicTypes.NET.Errors 0.3.0-preview.2

MonadicTypes.NET.Errors

Structured, immutable errors and validation values for MonadicTypes.NET. This package includes MonadicTypes.NET transitively.

Requirements

• .NET 10 or later
• Compatible with trimming and NativeAOT
• No dependency on FluentValidation or another validation framework

Install

dotnet add package MonadicTypes.NET.Errors --prerelease

Quick Start

using MonadicTypes;

public sealed record Customer(int Id);

static Result<Customer, Error> FindCustomer(int id) => id switch
{
    <= 0 => Result<Customer, Error>.Fail(
        Error.Validation("CUSTOMER_ID_INVALID", "Customer ID must be positive.")),
    _ => Result<Customer, Error>.Fail(
        Error.NotFound("CUSTOMER_NOT_FOUND", "The customer does not exist."))
};

ValidationErrors validation = new(
    new ValidationIssue("email", "EMAIL_INVALID", "Email is invalid."));

Error Contract

Error carries a bounded category, stable machine code, message, public-message policy, and optional exception cause. Its focused built-in categories cover validation, authentication, authorization, resource state, request preconditions and content, rate limits, cancellation, upstream failures, and unexpected failures. Construct any built-in category with new Error(type, code, message, ...); the named factories retain the common short forms. Error.Custom supports positive application-defined numeric categories without making the core type itself an HTTP-status catalog.

Error.IO and Error.System provide standard-code convenience forms and custom-code overloads that can retain an exception and explicit disclosure policy without changing their Failure or Unexpected category.

Cause is retained for diagnostics and stack-preserving rethrow; default HTTP conversion never serializes it. Compact domain errors can implement IErrorConvertible<Error> and widen only at an application boundary.

Equality compares category, numeric category, ordinal code, ordinal message, disclosure policy, and retained-cause identity. Hashing uses the same fields. ToString returns [CODE] message; TryFormat writes that representation to a caller-owned span without allocating a string. These contracts do not expose the compact internal message/cause representation.

ValidationErrors.Create maps third-party validation objects through caller supplied functions, so compatibility does not require a runtime dependency on the originating validation library. ValidationErrors is an immutable owner with reference identity; use AsSpan for explicit allocation-free sequence inspection or comparison.

Successful Result<T,Error> paths allocate 0 B. Rich errors allocate only when an error is constructed; use compact readonly domain errors on measured failure hot paths when that allocation matters.

Related Packages

Documentation

See structured errors and validation and the compatibility contract.

Apache-2.0. Developed with AI assistance.

Complete API reference

Documented public members: 84