Vali-Flow 1.1.0

Vali-Flow - Documentation

This document provides a comprehensive overview of the Vali-Flow library, a .NET library designed to simplify data access and validation in Entity Framework Core (EF Core) applications. The library offers a fluent API for building specifications (ValiFlow<T>), a robust evaluator (ValiFlowEvaluator<T>) for querying and modifying data, specification classes (QuerySpecification<T>, BasicSpecification<T>) for defining query criteria, and a generic repository (DbRepositoryAsync<T>) for clean data access patterns. The documentation includes detailed descriptions, code examples, tables, and usage instructions.

Table of Contents

1. Overview
2. Core Components
   • ValiFlow<T>
   • IEvaluatorRead<T>
   • IEvaluatorWrite<T>
   • ValiFlowEvaluator<T>
3. Specification Components
   • BasicSpecification<T>
   • QuerySpecification<T>
4. Repository Components
   • ApplicationDbContext
   • IReadRepositoryAsync<T>
   • IWriteRepositoryAsync<T>
   • DbRepositoryAsync<T>
   • Dependency Injection
5. Component Summary
6. Usage
7. Implementation Details
8. Dependencies
9. Extensibility
10. Features and Enhancements 🌟
11. Code Structure

Overview

Vali-Flow is a .NET library that streamlines data access and validation in EF Core applications. It provides a fluent API for constructing complex query and validation specifications, a powerful evaluator for executing these specifications, and a generic repository for clean data access. The library is designed for clean architecture, separating concerns and promoting reusability.

Key features:

• Fluent Specification API: Build complex queries and validations using ValiFlow<T> and specification classes.
• Asynchronous Data Access: All operations are asynchronous, supporting scalable applications.
• Generic Design: Works with any entity type T, reducing code duplication.
• Extensible Repository: DbRepositoryAsync<T> integrates with the evaluator for clean data access.
• Robust Error Handling: Includes validation and exception handling for reliable operations.
• Dependency Injection: Seamlessly integrates with ASP.NET Core.

The library is organized into core components (specifications and evaluation), specification components (query criteria), and repository components (data access).

Core Components

ValiFlow<T>

ValiFlow<T> is a fluent API for building specifications that define query filters, validations, or conditions for entities of type T. It resides in the Vali-Flow.Core namespace and supports chaining methods to construct complex logic.

Key Features:

• Supports building filters, validations, and query conditions.
• Provides methods like Build() and BuildNegated() to generate Expression<Func<T, bool>>.
• Used by ValiFlowEvaluator<T> and specification classes to define criteria.

Code Example:

using Vali_Flow.Core;

var spec = new ValiFlow<Product>()
    .Add(p => p.Price > 100)
    .Add(p => p.Category == "Electronics");
Expression<Func<Product, bool>> filter = spec.Build();

IEvaluatorRead<T>

IEvaluatorRead<T> defines methods for querying data asynchronously, supporting filtering, grouping, aggregation, and pagination.

Method Summary:

IEvaluatorWrite<T>

IEvaluatorWrite<T> defines methods for modifying data asynchronously, including adding, updating, deleting, and bulk operations.

Method Summary:

ValiFlowEvaluator<T>

ValiFlowEvaluator<T> is the core class that implements IEvaluatorRead<T> and IEvaluatorWrite<T>. It provides the logic for querying and modifying data using EF Core, leveraging ValiFlow<T> and specification classes.

Key Features:

• Accepts a DbContext for database operations.
• Implements all methods from IEvaluatorRead<T> and IEvaluatorWrite<T>.
• Supports advanced querying (e.g., grouping, aggregation) and bulk operations.
• Uses QuerySpecification<T> and BasicSpecification<T> for query composition.

Code Example:

using Vali_Flow.Classes.Evaluators;

public class ValiFlowEvaluator<T> : IEvaluatorRead<T>, IEvaluatorWrite<T> where T : class
{
    private readonly DbContext _dbContext;

    public ValiFlowEvaluator(DbContext dbContext)
    {
        _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext), "The provided DbContext is null.");
    }

    // Implementation details omitted for brevity
}

Specification Components

BasicSpecification<T>

BasicSpecification<T> is a base class for defining simple query specifications, including filters, inclusions, and EF Core configurations (e.g., change tracking, split queries). It implements IBasicSpecification<T> and resides in the Vali_Flow.Classes.Specification namespace.

Key Features:

• Defines a ValiFlow<T> filter for query criteria.
• Supports including related entities via AddInclude.
• Configures EF Core options like AsNoTracking, AsSplitQuery, and IgnoreQueryFilters.
• Provides chainable methods for fluent configuration.

Method Summary:

Code Example:

using System.Linq.Expressions;
using Vali_Flow.Classes.Specification;
using Vali_Flow.Core;

var spec = new BasicSpecification<Product>(new ValiFlow<Product>().Add(p => p.Price > 100))
    .AddInclude(p => p.Category)
    .WithAsNoTracking(true)
    .WithIgnoreQueryFilters(true);

QuerySpecification<T>

QuerySpecification<T> extends BasicSpecification<T> and implements IQuerySpecification<T>. It adds support for ordering, pagination, and limiting the number of results, making it ideal for complex queries.

Key Features:

• Supports primary ordering (WithOrderBy) and secondary ordering (AddThenBy, AddThenBys).
• Configures pagination (WithPagination, WithPage, WithPageSize) and maximum items (WithTop).
• Inherits filter and inclusion capabilities from BasicSpecification<T>.

Method Summary:

Code Example:

using System.Linq.Expressions;
using Vali_Flow.Classes.Specification;
using Vali_Flow.Core;

var spec = new QuerySpecification<Product>(new ValiFlow<Product>().Add(p => p.Price > 100))
    .WithOrderBy(p => p.Price, false)
    .AddThenBy(p => p.Name)
    .WithPagination(2, 10)
    .WithTop(50);

Repository Components

ApplicationDbContext

ApplicationDbContext is the EF Core DbContext used for database interactions in the repository layer. It defines the database schema and configures the connection to a SQL Server database.

Key Features:

• Inherits from Microsoft.EntityFrameworkCore.DbContext.
• Configured via DbContextOptions<ApplicationDbContext>.
• Used by DbRepositoryAsync<T> and passed to ValiFlowEvaluator<T>.

Code Example:

namespace Infrastructure.Data;

public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options)
    {
    }

    // Example DbSet properties
    // public DbSet<Product> Products { get; set; }
}

IReadRepositoryAsync<T>

IReadRepositoryAsync<T> is an interface for read-only data operations, inheriting from IEvaluatorRead<T>.

Key Features:

• Provides access to all query methods defined in IEvaluatorRead<T>.
• Generic constraint ensures T is a class.
• Can be extended with additional methods.

Code Example:

namespace Application.Interfaces.ValiFlow;

public interface IReadRepositoryAsync<T> : IEvaluatorRead<T> where T : class
{
    // Inherits methods from IEvaluatorRead<T>
}

IWriteRepositoryAsync<T>

IWriteRepositoryAsync<T> is an interface for write operations, inheriting from IEvaluatorWrite<T>.

Key Features:

• Provides access to all write methods defined in IEvaluatorWrite<T>.
• Generic constraint ensures T is a class.
• Supports bulk operations.

Code Example:

namespace Application.Interfaces.ValiFlow;

public interface IWriteRepositoryAsync<T> : IEvaluatorWrite<T> where T : class
{
    // Inherits methods from IEvaluatorWrite<T>
}

DbRepositoryAsync<T>

DbRepositoryAsync<T> is a generic repository class that extends ValiFlowEvaluator<T> and implements IReadRepositoryAsync<T> and IWriteRepositoryAsync<T>. It provides a clean interface for data access.

Key Features:

• Inherits all method implementations from ValiFlowEvaluator<T>.
• Uses ApplicationDbContext for database interactions.
• Validates ApplicationDbContext to ensure it is not null.
• Extensible for custom methods or overrides.

Code Example:

namespace Infrastructure.Repositories;

public class DbRepositoryAsync<T> : ValiFlowEvaluator<T>, IReadRepositoryAsync<T>, IWriteRepositoryAsync<T> where T : class
{
    private readonly ApplicationDbContext _dbContext;

    public DbRepositoryAsync(ApplicationDbContext dbContext) : base(dbContext)
    {
        _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext), "The provided DbContext is null.");
    }
}

Dependency Injection

The dependency injection setup registers ApplicationDbContext and DbRepositoryAsync<T> with the ASP.NET Core dependency injection container.

Key Features:

• Configures ApplicationDbContext with a SQL Server connection string.
• Registers DbRepositoryAsync<T> for both IReadRepositoryAsync<T> and IWriteRepositoryAsync<T>.

Dependency Injection Summary:

Code Example:

namespace Infrastructure;

public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(this IServiceCollection services, string connectionString)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(connectionString));

        services.AddScoped(typeof(IReadRepositoryAsync<>), typeof(DbRepositoryAsync<>));
        services.AddScoped(typeof(IWriteRepositoryAsync<>), typeof(DbRepositoryAsync<>));

        return services;
    }
}

Component Summary :

Usage

The Vali-Flow library can be used in three primary ways:

1. Core Usage: Use ValiFlow<T> and ValiFlowEvaluator<T> for specification-based data access.
2. Specification Usage: Use BasicSpecification<T> or QuerySpecification<T> for complex query composition.
3. Repository Usage: Use DbRepositoryAsync<T> for clean data access patterns.

Core Usage Example:

var evaluator = new ValiFlowEvaluator<Product>(dbContext);
var spec = new QuerySpecification<Product>(new ValiFlow<Product>().Add(p => p.Price > 100));
var products = await evaluator.EvaluateQueryAsync(spec);
var count = await evaluator.EvaluateCountAsync(spec);

Specification Usage Example:

var spec = new QuerySpecification<Product>()
    .WithFilter(new ValiFlow<Product>().Add(p => p.Price > 100))
    .WithOrderBy(p => p.Price, false)
    .AddInclude(p => p.Category)
    .WithPagination(1, 20);
var evaluator = new ValiFlowEvaluator<Product>(dbContext);
var products = await evaluator.EvaluateQueryAsync(spec);

Repository Usage Example:

public class ProductService
{
    private readonly IReadRepositoryAsync<Product> _readRepository;
    private readonly IWriteRepositoryAsync<Product> _writeRepository;

    public ProductService(
        IReadRepositoryAsync<Product> readRepository,
        IWriteRepositoryAsync<Product> writeRepository)
    {
        _readRepository = readRepository;
        _writeRepository = writeRepository;
    }

    public async Task<Product> AddProductAsync(Product product)
    {
        return await _writeRepository.AddAsync(product);
    }

    public async Task<Product?> GetProductByIdAsync(int id)
    {
        var spec = new QuerySpecification<Product>(new ValiFlow<Product>().Add(p => p.Id == id));
        return await _readRepository.EvaluateGetFirstAsync(spec);
    }
}

Service Configuration:

using Infrastructure;

var builder = WebApplication.CreateBuilder(args);

// Configure services
var connectionString = "Server=.;Database=MyDb;Trusted_Connection=True;";
builder.Services.AddInfrastructure(connectionString);
builder.Services.AddScoped<ProductService>();

var app = builder.Build();

// Configure the HTTP request pipeline (example)
app.MapGet("/", () => "Hello, World!");

app.Run();

Implementation Details

• ValiFlow<T>: Provides a fluent API for constructing Expression<Func<T, bool>> expressions, used by specifications and evaluators.
• BasicSpecification<T>: Defines basic query criteria, including filters and inclusions, with EF Core-specific configurations.
• QuerySpecification<T>: Extends BasicSpecification<T> to support ordering, pagination, and limiting results.
• ValiFlowEvaluator<T>: Implements the core logic for querying and modifying data, using EF Core and specifications.
• DbRepositoryAsync<T>: Extends ValiFlowEvaluator<T> to provide a repository pattern, inheriting all data access methods.
• Error Handling: Includes validation (e.g., null checks, pagination constraints) and exception handling across components.
• Asynchronous Design: All methods are asynchronous, ensuring scalability.

Dependencies

The Vali-Flow library relies on the following NuGet packages:

• Vali_Flow.Core:
  • Description: Vali_Flow.Core is a component of the Vali-Flow library for managing validations in .NET in a fluent and expressive way. It allows developers to define data validations and query specifications using chained expressions, making code writing and maintenance easier. Compatible with multiple data types, it provides intuitive methods for validating strings, dates, collections, and general comparisons.
  • Release Notes:
    • New integration of the specification pattern into the methods.
    • Improved stability and compatibility with Vali-Flow library components.
    • New methods for reading (batch read data) and writing with Entity Framework Core.
  • Compatible with: .NET 7, .NET 8, .NET 9
  • Available at https://www.nuget.org/packages/Vali-Flow.Core/.
• Microsoft.EntityFrameworkCore: Core EF Core functionality for database operations.
• EFCore.BulkExtensions: Support for bulk operations to enhance performance.

NuGet Packages:

<PackageReference Include="Vali_Flow.Core" Version="1.0.4" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
<PackageReference Include="EFCore.BulkExtensions" Version="8.0.0" />

Extensibility

The library is highly extensible:

• Custom Specifications: Extend ValiFlow<T>, BasicSpecification<T>, or QuerySpecification<T> with new methods.
• Evaluator Overrides: Derive from ValiFlowEvaluator<T> to customize query or write logic.
• Repository Methods: Add custom methods to DbRepositoryAsync<T> for application-specific needs.
• Interface Extensions: Add methods to IReadRepositoryAsync<T> or IWriteRepositoryAsync<T>.

Example: Adding a Custom Repository Method:

public class DbRepositoryAsync<T> : ValiFlowEvaluator<T>, IReadRepositoryAsync<T>, IWriteRepositoryAsync<T> where T : class
{
    private readonly ApplicationDbContext _dbContext;

    public DbRepositoryAsync(ApplicationDbContext dbContext) : base(dbContext)
    {
        _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext), "The provided DbContext is null.");
    }

    public async Task<IEnumerable<T>> GetByCustomFilterAsync(Expression<Func<T, bool>> filter)
    {
        var spec = new QuerySpecification<T>(new ValiFlow<T>().Add(filter));
        var query = await EvaluateQueryAsync(spec);
        return await query.ToListAsync();
    }
}

Features and Enhancements 🌟

The Vali-Flow library is actively developed with new features and improvements to enhance its functionality and usability.

Recent Updates

• Enhanced Expression Building: Improved Vali-Flow.Core to support more complex and reusable expression composition, enabling developers to create dynamic and scalable query filters with ease.
• Optimized Specification Evaluation: Enhanced ValiFlowEvaluator<T> to improve performance for complex specifications, including better handling of includes, pagination, and grouping operations.
• Bulk Operation Improvements: Optimized bulk operations (e.g., BulkInsertAsync, BulkUpdateAsync) in Vali-Flow for faster data manipulation, with improved integration with EF Core and Vali-Flow.Core specifications.
• Multi-targeting Support: Added support for .NET 7, 8, and 9, ensuring Vali-Flow’s compatibility with modern .NET ecosystems.

Planned Features

• Request Pre-processing and Post-processing Hooks: Support for hooks to execute custom logic before and after request processing in Vali-Flow, enhancing flexibility for specification and query execution.
• Enhanced Debugging Tools: Improved tools for debugging pipeline execution in Vali-Flow, providing better insights into operation flows for specification evaluation and data access.

Follow the project on GitHub for updates on new features and improvements!

Donations 💖

If you find Vali-Flow useful and would like to support its development, consider making a donation:

• For Latin America: Donate via MercadoPago
• For International Donations: Donate via PayPal

Your contributions help keep this project alive and improve its development! 🚀

License 📜

This project is licensed under the Apache License 2.0.

Contributions 🤝

Feel free to open issues and submit pull requests to improve this library!