Atya.Errors.Validation 1.0.0

Validation

Transport-agnostic validation abstractions, models, helpers, and composite validators for the Atya Errors group.

This package provides small validation building blocks for domain, application, worker, and API layers without any transport-specific concepts. It intentionally does not include a rules DSL, reflection-based validation, ASP.NET integration, or localization.

Install

dotnet add package Atya.Errors.Validation

Supported framework

Atya.Errors.Validation targets net10.0.

Quick start

using Atya.Errors.Validation.Abstractions;
using Atya.Errors.Validation.Extensions;
using Atya.Errors.Validation.Models;
using Atya.Errors.Validation.Validators;

var validator = new CompositeValidator<CreateCustomerCommand>(
[
    new NameRequiredValidator(),
    new EmailFormatValidator(),
]);

var command = new CreateCustomerCommand("", "not-an-email");
var result = await validator.ValidateAsync(command);

if (!result.IsValid)
{
    foreach (var error in result.Errors)
    {
        Console.WriteLine($"{error.PropertyName}: {error.Message}");
    }
}

sealed record CreateCustomerCommand(string Name, string Email);

sealed class NameRequiredValidator : IValidator<CreateCustomerCommand>
{
    public ValueTask<ValidationResult> ValidateAsync(
        CreateCustomerCommand instance,
        CancellationToken cancellationToken = default)
    {
        _ = cancellationToken;

        return string.IsNullOrWhiteSpace(instance.Name)
            ? ValueTask.FromResult(ValidationResult.FromFailure(
                ValidationFailureFactory.Required(nameof(instance.Name), instance.Name)))
            : ValueTask.FromResult(ValidationResult.Success);
    }
}

sealed class EmailFormatValidator : IValidator<CreateCustomerCommand>
{
    public ValueTask<ValidationResult> ValidateAsync(
        CreateCustomerCommand instance,
        CancellationToken cancellationToken = default)
    {
        _ = cancellationToken;

        return instance.Email.Contains('@', StringComparison.Ordinal)
            ? ValueTask.FromResult(ValidationResult.Success)
            : ValueTask.FromResult(ValidationResult.FromFailure(
                ValidationFailureFactory.Invalid(
                    nameof(instance.Email),
                    "Email must contain '@'.",
                    instance.Email)));
    }
}

Core APIs

• IValidator<T> defines the async validation contract.
• ValidationFailure is an immutable value object for one property or logical field failure.
• ValidationResult represents success or one or more failures.
• ValidationFailureFactory creates standard Atya validation failures.
• ValidatorExtensions.ValidateAllAsync executes validators in order and combines failures.
• ValidatorExtensions.ValidateAndThrowAsync validates with one validator and throws on failure.
• CompositeValidator<T> composes several validators behind one IValidator<T>.
• ValidationExtensions.ThrowIfInvalid and ToValidationException convert failures into Atya.Errors.Exceptions.ValidationException.

Behavior

• ValidationFailure trims PropertyName, Message, and non-empty ErrorCode values.
• Empty or whitespace PropertyName and Message values throw ArgumentException.
• Empty failure collections produce ValidationResult.Success.
• Result and failure collections are copied before storage, so callers cannot mutate a result through the original input collection.
• Composite and extension-based validation runs validators sequentially in the order provided.
• Cancellation is checked before each validator and the same token is passed to validators.
• Validators must return a non-null ValidationResult; a null result throws ArgumentNullException.

Exceptions

Use ThrowIfInvalid when validation errors should become an Atya validation exception:

await validator.ValidateAndThrowAsync(command);

The default exception message is Validation failed. and the default error code is validation.failed. Provide explicit values when those should be part of a public API contract.

Versioning and support

Stable releases use SemVer and are produced from vMAJOR.MINOR.PATCH tags. Breaking API changes should wait for the next major version. Bug fixes and new non-breaking helpers can be released in patch or minor versions as appropriate.