eQuantic LINQ Extensions

// Instalar vía Package Manager Console
Install-Package eQuantic.Linq

// O vía .NET CLI
dotnet add package eQuantic.Linq

// Declaraciones using básicas
using eQuantic.Linq.Specification;
using eQuantic.Linq.Filter;
using eQuantic.Linq.Sorter;
using eQuantic.Linq.Extensions;

// Implementación de especificación personalizada
public class ActiveUserSpecification : Specification<User>
{
    public override Expression<Func<User, bool>> SatisfiedBy()
    {
        return user => user.IsActive && user.EmailVerified;
    }
}

// Usando especificaciones con operadores lógicos
var activeAdminSpec = new ActiveUserSpecification() && 
                     new AdminUserSpecification();

// Aplicando especificaciones a consultas
var activeAdminUsers = users.Where(activeAdminSpec.SatisfiedBy());

// Uso directo de especificaciones
var isActiveAdmin = activeAdminSpec.IsSatisfiedBy(user);

// Método de capa de servicio con filtro de entidad
public async Task<List<Product>> GetProductsAsync(IEntityFilter<Product> filter)
{
    var query = dbContext.Products.AsQueryable();
    
    if (filter != null)
    {
        query = filter.Filter(query);
    }
    
    return await query.ToListAsync();
}

// Uso en controlador con API fluida
var filter = EntityFilter<Product>
    .Where(p => p.Category == "Electrónicos")
    .And(p => p.Price > 100)
    .And(p => p.InStock);

var products = await productService.GetProductsAsync(filter);

// Filtrado complejo con condiciones anidadas
var complexFilter = EntityFilter<Product>
    .Where(p => p.Category == "Electrónicos" || p.Category == "Computadoras")
    .And(p => p.Price >= minPrice && p.Price <= maxPrice)
    .And(p => p.Reviews.Any(r => r.Rating >= 4));

// Método de capa de servicio con ordenador de entidad
public async Task<List<Product>> GetSortedProductsAsync(IEntitySorter<Product> sorter)
{
    var query = dbContext.Products.AsQueryable();
    
    if (sorter != null)
    {
        query = sorter.Sort(query);
    }
    
    return await query.ToListAsync();
}

// Creando ordenamiento multi-nivel
var sorter = EntitySorter<Product>
    .OrderByDescending(p => p.Featured)
    .ThenBy(p => p.Price)
    .ThenByDescending(p => p.CreatedDate);

var sortedProducts = await productService.GetSortedProductsAsync(sorter);

// Ordenamiento dinámico basado en entrada del usuario
var dynamicSorter = EntitySorter<Product>.OrderBy(p => p.Name);
if (sortByPrice)
{
    dynamicSorter = dynamicSorter.ThenBy(p => p.Price);
}
if (sortByRating)
{
    dynamicSorter = dynamicSorter.ThenByDescending(p => p.AverageRating);
}

// Casting básico con mapeo automático de propiedades
var productDto = product.Cast<ProductDto>();

// Configuración de mapeo personalizada
var productDto = product.Cast<ProductDto>(options =>
{
    options.Map(src => src.ProductName, dest => dest.Name);
    options.Map(src => src.UnitPrice, dest => dest.Price);
    options.CustomMap(src => src.Category.Name, dest => dest.CategoryName);
    options.ExcludeUnmapped();
});

// Casting de colecciones
var productDtos = products.Cast<ProductDto>(options =>
{
    options.Map(src => src.ProductName, dest => dest.Name);
    options.Map(src => src.CreatedDate, dest => dest.CreatedAt);
});

// Mapeo complejo con objetos anidados
var orderDto = order.Cast<OrderDto>(options =>
{
    options.Map(src => src.Customer.FullName, dest => dest.CustomerName);
    options.Map(src => src.OrderItems.Sum(oi => oi.Total), dest => dest.TotalAmount);
    options.CustomMap(src => src.OrderDate.ToString("yyyy-MM-dd"), dest => dest.FormattedDate);
});

// Modelo con atributos de generador de código fuente
[GenerateSpecifications]
public class Product
{
    public int Id { get; set; }
    
    [SpecProperty(FilterOperator.Equal | FilterOperator.Contains)]
    public string Name { get; set; }
    
    [SpecProperty(FilterOperator.Equal | FilterOperator.GreaterThan | FilterOperator.LessThan)]
    public decimal Price { get; set; }
    
    [SpecProperty(FilterOperator.Equal)]
    public bool InStock { get; set; }
    
    [SpecProperty(FilterOperator.Equal | FilterOperator.Contains)]
    public string Category { get; set; }
}

// Uso de código generado (creado automáticamente por el generador de código fuente)
var nameSpec = ProductSpecifications.NameContains("laptop");
var priceSpec = ProductSpecifications.PriceGreaterThan(500m);
var categorySpec = ProductSpecifications.CategoryEqual("Electrónicos");

// Combinar especificaciones generadas
var combinedSpec = nameSpec && priceSpec && categorySpec;
var filteredProducts = products.Where(combinedSpec.SatisfiedBy());

// Uso de filtro de entidad asíncrono
public class ProductService
{
    public async Task<PagedResult<Product>> GetProductsAsync(
        IAsyncEntityFilter<Product> filter,
        int page = 1,
        int pageSize = 10)
    {
        var query = dbContext.Products.AsQueryable();
        
        if (filter != null)
        {
            query = await filter.FilterAsync(query);
        }
        
        var totalCount = await query.CountAsync();
        var items = await query
            .Skip((page - 1) * pageSize)
            .Take(pageSize)
            .ToListAsync();
            
        return new PagedResult<Product>
        {
            Items = items,
            TotalCount = totalCount,
            CurrentPage = page,
            PageSize = pageSize
        };
    }
}

// Evaluación asíncrona de especificaciones
var activeUserSpec = new ActiveUserSpecification();
var user = await dbContext.Users.FirstOrDefaultAsync(activeUserSpec.SatisfiedBy());

// ===== MODELOS DE EJEMPLO =====
// Estructuras típicas de aplicaciones del mundo real con relaciones
public class User
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public List<Role> Roles { get; set; } = new();
    public List<Project> Projects { get; set; } = new();
}

public class Role
{
    public string Name { get; set; } = string.Empty;
    public bool IsActive { get; set; }
    public List<string> Permissions { get; set; } = new();
}

public class Project
{
    public string Name { get; set; } = string.Empty;
    public string Status { get; set; } = string.Empty;
    public int Priority { get; set; }
    public bool IsCompleted { get; set; }
    public DateTime AssignedAt { get; set; }
}

// ===== ANY - CUALQUIER ELEMENTO SATISFACE LA CONDICIÓN =====

// Escenario 1: Usuarios con CUALQUIER rol administrativo
// Útil para sistemas de autorización
var adminOrManagerUsers = new CompositeFiltering<User>(
    CompositeOperator.Any,
    u => u.Roles,
    "Name:eq(Admin)",
    "Name:eq(Manager)",
    "Name:eq(SuperAdmin)"
);

// Escenario 2: Usuarios con CUALQUIER proyecto de alta prioridad
// Ideal para paneles de gestión
var highPriorityUsers = new CompositeFiltering<User>(
    CompositeOperator.Any,
    u => u.Projects,
    "Priority:gte(8)",
    "Status:eq(Critical)"
);

// ===== ALL - TODOS LOS ELEMENTOS DEBEN SATISFACER =====

// Escenario 3: Usuarios donde TODOS los proyectos están completos
// Perfecto para informes de productividad
var usersWithCompletedProjects = new CompositeFiltering<User>(
    CompositeOperator.All,
    u => u.Projects,
    "Status:eq(Completed)",
    "IsCompleted:eq(true)"
);

// Escenario 4: Usuarios donde TODOS los roles están activos
// Importante para auditoría de seguridad
var usersWithActiveRoles = new CompositeFiltering<User>(
    CompositeOperator.All,
    u => u.Roles,
    "IsActive:eq(true)"
);

// ===== CONSULTAS COMPLEJAS CON CONDICIONES ANIDADAS =====

// Escenario 5: Usuarios con cualquier rol que tenga permisos de escritura
var writePermissionUsers = new CompositeFiltering<User>(
    CompositeOperator.Any,
    u => u.Roles,
    "Permissions:ct(write)",
    "Permissions:ct(admin)",
    "and(Name:eq(Editor),IsActive:eq(true))"
);

// Escenario 6: Usuarios con todos los proyectos activos y de alta prioridad
var qualityFocusedUsers = new CompositeFiltering<User>(
    CompositeOperator.All,
    u => u.Projects,
    "Status:neq(Cancelled)",
    "Priority:gte(5)",
    "AssignedAt:gte(2024-01-01)"
);

// ===== APLICACIÓN PRÁCTICA EN SERVICIOS =====

public class UserManagementService
{
    private readonly IRepository<User> _userRepository;
    
    /// <summary>
    /// Busca administradores activos del sistema
    /// </summary>
    public async Task<List<User>> GetActiveAdministratorsAsync()
    {
        var adminFilter = new CompositeFiltering<User>(
            CompositeOperator.Any,
            u => u.Roles,
            "Name:eq(Admin)",
            "Name:eq(SuperAdmin)",
            "and(Name:eq(Manager),IsActive:eq(true))"
        );
        
        return await adminFilter.Filter(_userRepository.Query())
            .Where(u => u.IsActive)
            .ToListAsync();
    }
    
    /// <summary>
    /// Busca usuarios que completaron todos sus proyectos (para bonos)
    /// </summary>
    public async Task<List<User>> GetTopPerformersAsync()
    {
        var completedProjectsFilter = new CompositeFiltering<User>(
            CompositeOperator.All,
            u => u.Projects,
            "Status:eq(Completed)",
            "IsCompleted:eq(true)"
        );
        
        return await completedProjectsFilter.Filter(_userRepository.Query())
            .Where(u => u.Projects.Count > 0) // Solo usuarios con proyectos
            .Include(u => u.Projects)
            .ToListAsync();
    }
}

// ===== FORMATO DE CONSULTA STRING - ANÁLISIS DINÁMICO =====

// La funcionalidad soporta análisis de consultas en string para APIs dinámicas
// Formato: "Propiedad:operador(condiciones)"

// Análisis de consulta Any
var anyRoleFilter = CompositeFiltering.ParseComposite(
    "Roles:any(Name:eq(Admin),IsActive:eq(true),Permissions:ct(write))"
);

// Análisis de consulta All
var allProjectFilter = CompositeFiltering.ParseComposite(
    "Projects:all(Status:neq(Cancelled),Priority:gte(5),IsCompleted:eq(false))"
);

// ===== INTEGRACIÓN CON OPERACIONES ASÍNCRONAS =====

// Funciona perfectamente con operaciones asíncronas
var users = await Query.For<User>()
    .Where(u => u.IsActive)
    .Where(adminOrManagerUsers) // Aplica filtro de colección
    .OrderByDescending(u => u.LastLoginAt)
    .ApplyToAsync(dbContext.Users, cancellationToken);

// Procesamiento de streams para grandes volúmenes
await foreach (var user in Query.For<User>()
    .Where(u => u.CreatedAt > DateTime.Now.AddYears(-1))
    .Where(usersWithCompletedProjects)
    .ApplyToAsyncEnumerable(dbContext.Users, cancellationToken))
{
    await ProcessUserAsync(user);
}

// ===== CASTING DE FILTROS =====
// Transformar filtros genéricos (de APIs externas, frontend, etc.)
// en filtros type-safe para tus entidades
var dtoFilters = new IFiltering[]
{
    new Filtering("productName", "Laptop", FilterOperator.Contains),
    new Filtering("minPrice", "500", FilterOperator.GreaterThan),
    new Filtering("category", "Electrónicos", FilterOperator.Equals),
    new Filtering("isAvailable", "true", FilterOperator.Equals)
};

// CastWith() realiza transformación type-safe con FluentCastBuilder
var entityFilters = dtoFilters.CastWith<Product>(builder => builder
    .MapFilter("productName", p => p.Name) // Mapea "productName" -> Product.Name
    .MapFilter("minPrice", p => p.Price, value => decimal.Parse(value)) // + conversión
    .MapFilter("category", p => p.Category)
    .MapFilter("isAvailable", p => p.IsActive, value => bool.Parse(value))
    .ExcludeUnmapped()); // Ignora filtros no mapeados (seguridad)

// Aplica los filtros transformados
var products = await repository.GetAsync(entityFilters.ToSpecification());

// ===== CASTING DE SORTING =====
// Mismo concepto para ordenamiento
var dtoSortings = new ISorting[]
{
    new Sorting("displayName", SortDirection.Ascending),
    new Sorting("createdDate", SortDirection.Descending)
};

var entitySortings = dtoSortings.CastWith<Product>(builder => builder
    .MapSorting("displayName", p => p.Name)
    .MapSorting("createdDate", p => p.CreatedAt));

// ===== CASTING DE OBJETOS SIMPLES =====
// Transformar DTOs a entidades o viceversa
var productDto = new ProductDto
{
    ProductName = "Gaming Laptop",
    UnitPrice = 1299.99m,
    CategoryName = "Electrónicos",
    Available = true
};

// CastWith() para objetos simples también
var product = productDto.CastWith<Product>(builder => builder
    .Map(dto => dto.ProductName, entity => entity.Name)
    .Map(dto => dto.UnitPrice, entity => entity.Price)
    .Map(dto => dto.Available, entity => entity.IsActive)
    .CustomMap(dto => dto.CategoryName, entity => entity.Category, 
               categoryName => new Category { Name = categoryName })
    .ExcludeUnmapped());

// ===== BENEFICIOS DE CASTWITH() =====
// 1. RENDIMIENTO: Expresiones se almacenan automáticamente en caché
// 2. SEGURIDAD DE TIPOS: Errores detectados en tiempo de compilación
// 3. EFICIENCIA DE MEMORIA: Menor asignación de memoria
// 4. API INTUITIVA: Interfaz fluida y descubrible

// ===== COMPARANDO CON MÉTODO TRADICIONAL =====
// El método Cast() tradicional aún funciona (retrocompatibilidad)
var productLegacy = productDto.Cast<Product>(options =>
{
    options.Map(dto => dto.ProductName, entity => entity.Name);
    options.Map(dto => dto.UnitPrice, entity => entity.Price);
    options.ExcludeUnmapped();
});

// Pero CastWith() ofrece mejor rendimiento y API más limpia