eQuantic LINQ Extensions

// Install via Package Manager Console
Install-Package eQuantic.Linq

// Or via .NET CLI
dotnet add package eQuantic.Linq

// Basic using statements
using eQuantic.Linq.Specification;
using eQuantic.Linq.Filter;
using eQuantic.Linq.Sorter;
using eQuantic.Linq.Extensions;

// Custom specification implementation
public class ActiveUserSpecification : Specification<User>
{
    public override Expression<Func<User, bool>> SatisfiedBy()
    {
        return user => user.IsActive && user.EmailVerified;
    }
}

// Using specifications with logical operators
var activeAdminSpec = new ActiveUserSpecification() && 
                     new AdminUserSpecification();

// Applying specifications to queries
var activeAdminUsers = users.Where(activeAdminSpec.SatisfiedBy());

// Direct specification usage
var isActiveAdmin = activeAdminSpec.IsSatisfiedBy(user);

// Service layer method with entity filter
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();
}

// Controller usage with fluent API
var filter = EntityFilter<Product>
    .Where(p => p.Category == "Electronics")
    .And(p => p.Price > 100)
    .And(p => p.InStock);

var products = await productService.GetProductsAsync(filter);

// Complex filtering with nested conditions
var complexFilter = EntityFilter<Product>
    .Where(p => p.Category == "Electronics" || p.Category == "Computers")
    .And(p => p.Price >= minPrice && p.Price <= maxPrice)
    .And(p => p.Reviews.Any(r => r.Rating >= 4));

// Service layer method with entity sorter
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();
}

// Creating multi-level sorting
var sorter = EntitySorter<Product>
    .OrderByDescending(p => p.Featured)
    .ThenBy(p => p.Price)
    .ThenByDescending(p => p.CreatedDate);

var sortedProducts = await productService.GetSortedProductsAsync(sorter);

// Dynamic sorting based on user input
var dynamicSorter = EntitySorter<Product>.OrderBy(p => p.Name);
if (sortByPrice)
{
    dynamicSorter = dynamicSorter.ThenBy(p => p.Price);
}
if (sortByRating)
{
    dynamicSorter = dynamicSorter.ThenByDescending(p => p.AverageRating);
}

// Basic casting with automatic property mapping
var productDto = product.Cast<ProductDto>();

// Custom mapping configuration
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();
});

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

// Complex mapping with nested objects
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);
});

// Model with source generator attributes
[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; }
}

// Generated code usage (automatically created by source generator)
var nameSpec = ProductSpecifications.NameContains("laptop");
var priceSpec = ProductSpecifications.PriceGreaterThan(500m);
var categorySpec = ProductSpecifications.CategoryEqual("Electronics");

// Combine generated specifications
var combinedSpec = nameSpec && priceSpec && categorySpec;
var filteredProducts = products.Where(combinedSpec.SatisfiedBy());

// Async entity filter usage
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
        };
    }
}

// Async specification evaluation
var activeUserSpec = new ActiveUserSpecification();
var user = await dbContext.Users.FirstOrDefaultAsync(activeUserSpec.SatisfiedBy());

// ===== EXAMPLE MODELS =====
// Typical real-world application structures with relationships
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 - ANY ITEM SATISFIES THE CONDITION =====

// Scenario 1: Users with ANY administrative role
// Useful for authorization systems
var adminOrManagerUsers = new CompositeFiltering<User>(
    CompositeOperator.Any,
    u => u.Roles,
    "Name:eq(Admin)",
    "Name:eq(Manager)",
    "Name:eq(SuperAdmin)"
);

// Scenario 2: Users with ANY high-priority project
// Ideal for management dashboards
var highPriorityUsers = new CompositeFiltering<User>(
    CompositeOperator.Any,
    u => u.Projects,
    "Priority:gte(8)",
    "Status:eq(Critical)"
);

// ===== ALL - ALL ITEMS MUST SATISFY =====

// Scenario 3: Users where ALL projects are completed
// Perfect for productivity reports
var usersWithCompletedProjects = new CompositeFiltering<User>(
    CompositeOperator.All,
    u => u.Projects,
    "Status:eq(Completed)",
    "IsCompleted:eq(true)"
);

// Scenario 4: Users where ALL roles are active
// Important for security auditing
var usersWithActiveRoles = new CompositeFiltering<User>(
    CompositeOperator.All,
    u => u.Roles,
    "IsActive:eq(true)"
);

// ===== COMPLEX QUERIES WITH NESTED CONDITIONS =====

// Scenario 5: Users with any role that has write permissions
var writePermissionUsers = new CompositeFiltering<User>(
    CompositeOperator.Any,
    u => u.Roles,
    "Permissions:ct(write)",
    "Permissions:ct(admin)",
    "and(Name:eq(Editor),IsActive:eq(true))"
);

// Scenario 6: Users with all active and high-priority projects
var qualityFocusedUsers = new CompositeFiltering<User>(
    CompositeOperator.All,
    u => u.Projects,
    "Status:neq(Cancelled)",
    "Priority:gte(5)",
    "AssignedAt:gte(2024-01-01)"
);

// ===== PRACTICAL APPLICATION IN SERVICES =====

public class UserManagementService
{
    private readonly IRepository<User> _userRepository;
    
    /// <summary>
    /// Find active system administrators
    /// </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>
    /// Find users who completed all their projects (for bonuses)
    /// </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) // Only users with projects
            .Include(u => u.Projects)
            .ToListAsync();
    }
}

// ===== STRING QUERY FORMAT - DYNAMIC PARSING =====

// The functionality supports parsing string queries for dynamic APIs
// Format: "Property:operator(conditions)"

// Parse Any query
var anyRoleFilter = CompositeFiltering.ParseComposite(
    "Roles:any(Name:eq(Admin),IsActive:eq(true),Permissions:ct(write))"
);

// Parse All query
var allProjectFilter = CompositeFiltering.ParseComposite(
    "Projects:all(Status:neq(Cancelled),Priority:gte(5),IsCompleted:eq(false))"
);

// ===== INTEGRATION WITH ASYNC OPERATIONS =====

// Works perfectly with asynchronous operations
var users = await Query.For<User>()
    .Where(u => u.IsActive)
    .Where(adminOrManagerUsers) // Apply collection filter
    .OrderByDescending(u => u.LastLoginAt)
    .ApplyToAsync(dbContext.Users, cancellationToken);

// Stream processing for large volumes
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);
}

// ===== FILTER CASTING =====
// Transform generic filters (from external APIs, frontend, etc.)
// into type-safe filters for your entities
var dtoFilters = new IFiltering[]
{
    new Filtering("productName", "Laptop", FilterOperator.Contains),
    new Filtering("minPrice", "500", FilterOperator.GreaterThan),
    new Filtering("category", "Electronics", FilterOperator.Equals),
    new Filtering("isAvailable", "true", FilterOperator.Equals)
};

// CastWith() performs type-safe transformation with FluentCastBuilder
var entityFilters = dtoFilters.CastWith<Product>(builder => builder
    .MapFilter("productName", p => p.Name) // Maps "productName" -> Product.Name
    .MapFilter("minPrice", p => p.Price, value => decimal.Parse(value)) // + conversion
    .MapFilter("category", p => p.Category)
    .MapFilter("isAvailable", p => p.IsActive, value => bool.Parse(value))
    .ExcludeUnmapped()); // Ignores unmapped filters (safety)

// Apply the transformed filters
var products = await repository.GetAsync(entityFilters.ToSpecification());

// ===== SORTING CASTING =====
// Same concept for sorting
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));

// ===== SIMPLE OBJECT CASTING =====
// Transform DTOs to entities or vice versa
var productDto = new ProductDto
{
    ProductName = "Gaming Laptop",
    UnitPrice = 1299.99m,
    CategoryName = "Electronics",
    Available = true
};

// CastWith() for simple objects too
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());

// ===== CASTWITH() BENEFITS =====
// 1. PERFORMANCE: Expressions are automatically cached
// 2. TYPE SAFETY: Errors detected at compile time
// 3. MEMORY EFFICIENT: Lower memory allocation
// 4. INTUITIVE API: Fluent and discoverable interface

// ===== COMPARING WITH TRADITIONAL METHOD =====
// Traditional Cast() method still works (backward compatibility)
var productLegacy = productDto.Cast<Product>(options =>
{
    options.Map(dto => dto.ProductName, entity => entity.Name);
    options.Map(dto => dto.UnitPrice, entity => entity.Price);
    options.ExcludeUnmapped();
});

// But CastWith() offers better performance and cleaner API