DevSource.Stack.Notifications 3.0.0

<div align="center"> <img src="https://github.com/uitanmaciel/devsource-stack-notifications/blob/main/src/DevSource.Stack.Notifications/devsource-icon.jpeg" width="130" />
</div>

DevSource.Stack.Notifications

This library is an implementation for application-level Notifications, designed to facilitate error handling and validation in a systematic and flexible way, allowing the developer to avoid throwing exceptions throughout the system. It allows errors and messages to be accumulated throughout the process flow, enabling a cohesive response mechanism.

DevSource.Stack.Notifications is an integral part of the DevSource ecosystem.

Features

• Validation Rules: Comprehensive validation rules for strings, numbers, dates, emails, passwords, documents, phones, collections, credit cards, and files
• Notification Pattern: Implement the Notification Pattern to avoid throwing exceptions throughout your application
• Fluent API: Chainable validation methods for clean and readable code
• Custom Messages: Support for custom error messages on all validations
• Brazilian Document Validation: Built-in support for CPF and CNPJ validation
• Phone Validation: Support for Brazilian and international phone formats
• Collection Validation: Validate collections and enumerables with ease
• Credit Card Validation: Luhn algorithm implementation for credit card validation
• File Validation: Validate file sizes, extensions, and MIME types
• Conditional Validation: Execute validations conditionally with When, RequireAtLeastOne, and AllOrNone
• Type-Safe: Generic implementation with strong typing support
• Lightweight: Zero external dependencies, pure .NET implementation
• Well-Tested: Comprehensive test suite with 130+ tests ensuring reliability

Requirements

• .NET 8.0 or higher
• No external dependencies required

Getting Started

Installation

Install the package from NuGet:

dotnet add package DevSource.Stack.Notifications

Basic Setup

Inherit from Notifier class in your domain entities or services:

using DevSource.Stack.Notifications;

public class User : Notifier
{
    public string Name { get; set; } = null!;
    public string Email { get; set; } = null!;
    public string Password { get; set; } = null!;
}

Usage Examples

Basic Validation

using DevSource.Stack.Notifications;
using DevSource.Stack.Notifications.Validations;

public class User : Notifier
{
    public string Name { get; set; } = null!;
    public string Email { get; set; } = null!;
    public string Password { get; set; } = null!;

    public User(string name, string email, string password)
    {
        Name = name;
        Email = email;
        Password = password;
    }

    public Task<bool> Create()
    {
        ValidateFields();

        if (HasNotifications) // Check for validation errors
            return Task.FromResult(false);

        // Business logic to create user
        return Task.FromResult(true);
    }

    private void ValidateFields()
    {
        AddNotifications(new ValidationRules<User>()
            .IsNotNull(nameof(Name), Name)
            .MinLength(nameof(Name), Name, 3)
            .IsEmail(nameof(Email), Email)
            .IsPassword(nameof(Password), Password, 8)
        );
    }
}

Handling Notifications

Check the Notifications property to capture validation errors:

var user = new User("John Doe", "invalid-email", "short");
var result = await user.Create();

if (result)
{
    Console.WriteLine("User created successfully!");
}
else
{
    foreach (var notification in user.Notifications)
    {
        Console.WriteLine($"{notification.Key}: {notification.Message}");
    }
}

Output:

Email: The 'Email' is not a valid email
Password: The value of field 'Password' is invalid

Custom Error Messages

You can provide custom error messages for any validation:

AddNotifications(new ValidationRules<User>()
    .IsNotNull(nameof(Name), Name, "Name is required")
    .MinLength(nameof(Name), Name, 3, "Name must have at least 3 characters")
    .IsEmail(nameof(Email), Email, "Please provide a valid email address")
);

String Validations

AddNotifications(new ValidationRules<Product>()
    .IsNotNull(nameof(Name), Name)
    .MinLength(nameof(Name), Name, 3)
    .MaxLength(nameof(Name), Name, 100)
    .MinLength(nameof(Description), Description, 10)
);

Number Validations

AddNotifications(new ValidationRules<Product>()
    .IsGreaterThan(nameof(Price), Price, 0)
    .IsLowerThan(nameof(Discount), Discount, 100)
    .IsBetween(nameof(Stock), Stock, 0, 1000)
);

DateTime Validations

AddNotifications(new ValidationRules<Event>()
    .IsInTheFuture(nameof(StartDate), StartDate)
    .IsDateBetween(nameof(EndDate), EndDate, DateTime.Now, DateTime.Now.AddYears(1))
    .IsDayOfWeek(nameof(StartDate), StartDate, DayOfWeek.Monday)
);

Brazilian Document Validations

AddNotifications(new ValidationRules<Customer>()
    .IsCpf(nameof(Cpf), Cpf) // Validates CPF format and check digits
    .IsCnpj(nameof(Cnpj), Cnpj) // Validates CNPJ format and check digits
);

Phone Validations

AddNotifications(new ValidationRules<Contact>()
    .IsBrazilianPhone(nameof(Phone), Phone) // (XX) XXXXX-XXXX
    .IsInternationalPhone(nameof(InternationalPhone), InternationalPhone) // +55XXXXXXXXXXX
);

Collection Validations

AddNotifications(new ValidationRules<Order>()
    .IsNotEmpty(nameof(Items), Items)
    .HasMinItems(nameof(Items), Items, 1)
    .HasMaxItems(nameof(Items), Items, 10)
    .HasExactItems(nameof(Items), Items, 5)
    .HasUniqueItems(nameof(Tags), Tags)
    .ContainsItem(nameof(Categories), Categories, "Electronics")
);

Credit Card Validations

AddNotifications(new ValidationRules<Payment>()
    .IsCreditCard(nameof(CardNumber), CardNumber) // Luhn algorithm
    .IsCreditCardNotExpired(nameof(ExpiryDate), ExpiryMonth, ExpiryYear)
);

File Validations

Conditional Validations

Conditional Validations

AddNotifications(new ValidationRules<User>()
    .When(user.IsCompany, rules => rules
        .IsNotNull(nameof(CompanyName), CompanyName)
        .IsCnpj(nameof(Cnpj), Cnpj))
    .When(() => user.Age < 18, rules => rules
        .IsNotNull(nameof(ParentName), ParentName))
    .RequireAtLeastOne(Email, Phone) // At least one must be filled
    .AllOrNone(State, City, ZipCode) // All or none must be filled
);

Combining Multiple Validators

You can combine validations from different notifiers:

var addressValidator = new ValidationRules<Address>()
    .IsNotNull(nameof(Street), address.Street)
    .IsNotNull(nameof(City), address.City);

var userValidator = new ValidationRules<User>()
    .IsNotNull(nameof(Name), Name)
    .IsEmail(nameof(Email), Email)
    .Join(addressValidator); // Combine validations

AddNotifications(userValidator);

API Reference

Available Validations

String Validations

Number Validations

Supports: int, double, decimal

DateTime Validations

Email & Password Validations

Core Classes

Notifier

Base class that provides notification management capabilities:

public class Notifier
{
    public IReadOnlyCollection<Notification> Notifications { get; }
    public bool HasNotifications { get; }
    
    protected void AddNotification(Notification notification)
    protected void AddNotifications(IEnumerable<Notification> notifications)
    protected void AddNotifications(params Notifier[] notifiers)
    protected void ClearNotifications()
}

ValidationRules<T>

Fluent validation builder:

public class ValidationRules<T> : Notifier
{
    public ValidationRules<T> Join(params Notifier[] notifiers)
    // All validation methods return ValidationRules<T> for chaining
}

Notification

Represents a single notification:

public class Notification
{
    public string Key { get; }
    public string Message { get; }
}

Integration with ASP.NET Core

Minimal API Example

app.MapPost("/users", async (CreateUserRequest request) =>
{
    var user = new User(request.Name, request.Email, request.Password);
    var result = await user.Create();
    
    if (!result)
        return Results.BadRequest(new { errors = user.Notifications });
    
    return Results.Created($"/users/{user.Id}", user);
});

Controller Example

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create([FromBody] CreateUserRequest request)
    {
        var user = new User(request.Name, request.Email, request.Password);
        var result = await user.Create();
        
        if (!result)
            return BadRequest(new { errors = user.Notifications });
        
        return CreatedAtAction(nameof(GetById), new { id = user.Id }, user);
    }
}

Custom Validation Middleware

public class NotificationMiddleware
{
    private readonly RequestDelegate _next;

    public NotificationMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (ValidationException ex)
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            await context.Response.WriteAsJsonAsync(new 
            { 
                errors = ex.Notifications 
            });
        }
    }
}

Running the tests

To run the tests, use the following command:

dotnet test

To run with coverage:

dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Uitan Maciel - GitHub Profile

<div align="center"> Made with ❤️ by the DevSource community </div>