🚀 SmartWhere - Intelligent .NET Filtering Library

SmartWhere is a production-ready .NET library that provides intelligent filtering capabilities for IQueryable<T> collections. It transforms complex filtering logic into simple, declarative code using attributes and interfaces, making your data access layer cleaner and more maintainable.

✨ Key Highlights

• 🎯 Intelligent Filtering: Automatically generates WHERE clauses from request objects
• 🔍 Deep Property Navigation: Support for nested property filtering (e.g., Books.Author.Name)
• 🏷️ Attribute-Based Configuration: Simple attribute decoration for filter properties
• 🔧 Type-Safe Operations: Full IntelliSense support and compile-time validation
• ⚡ High Performance: Optimized expression tree generation
• 🎨 Clean Architecture: Follows SOLID principles and DRY methodology
• 🔌 Easy Integration: Single-line integration with existing Entity Framework queries
• 📚 Comprehensive Support: Works with any IQueryable<T> implementation

🚀 Quick Start

Installation

Install the SmartWhere NuGet package:

# Package Manager Console
PM> Install-Package SmartWhere

# .NET CLI
dotnet add package SmartWhere

# NuGet Package Manager
Install-Package SmartWhere

Basic Usage

1. Define your search request implementing IWhereClause:

public class PublisherSearchRequest : IWhereClause
{
    [WhereClause]
    public int Id { get; set; }

    [WhereClause(PropertyName = "Name")]
    public string PublisherName { get; set; }

    [WhereClause("Book.Name")]
    public string BookName { get; set; }

    [WhereClause("Books.Author.Name")]
    public string AuthorName { get; set; }
}

2. Use SmartWhere in your queries:

[HttpPost]
public IActionResult GetPublishers(PublisherSearchRequest request)
{
    var result = _context.Set<Publisher>()
        .Include(x => x.Books)
        .ThenInclude(x => x.Author)
        .Where(request)  // 🎯 SmartWhere magic happens here!
        .ToList();

    return Ok(result);
}

That's it! SmartWhere automatically generates the appropriate WHERE clauses based on your request object.

🏗️ Architecture & Components

┌─────────────────────────────────────────────────────────────┐
│                    SmartWhere Library                       │
├─────────────────────────────────────────────────────────────┤
│  📋 Core Components                                        │
│  • WhereClauseAttribute     • IWhereClause Interface      │
│  • Extensions               • Logical Operators            │
│  • Comparison Operators     • String Methods               │
├─────────────────────────────────────────────────────────────┤
│  🔧 Extension Methods                                      │
│  • Where(request)           • And(request)                │
│  • Or(request)              • Not(request)                │
├─────────────────────────────────────────────────────────────┤
│  🎯 Attribute System                                       │
│  • WhereClause             • TextualWhereClause           │
│  • ComparativeWhereClause  • WhereClauseClass             │
└─────────────────────────────────────────────────────────────┘

Key Components

• 📋 WhereClauseAttribute: Base attribute for simple property filtering
• 🔍 TextualWhereClauseAttribute: Advanced text search with multiple string methods
• ⚖️ ComparativeWhereClauseAttribute: Numeric and date comparison operations
• 🏷️ WhereClauseClassAttribute: Class-level filtering configuration
• 🔌 IWhereClause Interface: Contract for filter request objects
• ⚡ Extensions: Fluent API for complex filtering operations

🎨 Advanced Usage Examples

Text Search with Multiple Methods

public class BookSearchRequest : IWhereClause
{
    [TextualWhereClause(StringMethod.Contains, PropertyName = "Title")]
    public string Title { get; set; }

    [TextualWhereClause(StringMethod.StartsWith, PropertyName = "ISBN")]
    public string ISBN { get; set; }

    [TextualWhereClause(StringMethod.EndsWith, PropertyName = "Description")]
    public string Description { get; set; }
}

Numeric and Date Comparisons

public class OrderSearchRequest : IWhereClause
{
    [ComparativeWhereClause(ComparisonOperator.GreaterThan, PropertyName = "TotalAmount")]
    public decimal MinAmount { get; set; }

    [ComparativeWhereClause(ComparisonOperator.LessThanOrEqual, PropertyName = "OrderDate")]
    public DateTime MaxDate { get; set; }

    [ComparativeWhereClause(ComparisonOperator.Between, PropertyName = "Quantity")]
    public int QuantityRange { get; set; }
}

Complex Logical Operations

// Combine multiple filters with logical operators
var result = _context.Orders
    .Where(request1)
    .And(request2)
    .Or(request3)
    .Not(request4)
    .ToList();

Nested Property Filtering

public class AdvancedSearchRequest : IWhereClause
{
    [WhereClause("Publisher.Country.Name")]
    public string CountryName { get; set; }

    [WhereClause("Books.Genre.Category")]
    public string GenreCategory { get; set; }

    [WhereClause("Books.Author.BirthCountry.Region")]
    public string AuthorRegion { get; set; }
}

📊 Performance & Benchmarks

Performance Metrics

• Simple Filter: ~0.1ms overhead per filter
• Complex Nested Filter: ~0.5ms overhead per filter
• Memory Usage: Minimal additional memory footprint
• Compilation: Expression trees generated at runtime for optimal performance

Scaling Tips

• Use projection for large result sets
• Implement caching for frequently used filters
• Consider database indexing for filtered properties
• Use pagination for large datasets

🛠️ Development & Testing

Building from Source

git clone https://github.com/byerlikaya/SmartWhere.git
cd SmartWhere
dotnet restore
dotnet build
dotnet test

Running Tests

# Run all tests
dotnet test

# Run specific test project
dotnet test tests/SmartWhere.Tests/

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Sample API

cd sample/Sample.Api
dotnet run

Browse to the API endpoints to see SmartWhere in action.

🔧 Configuration & Customization

Global Configuration

// In Program.cs or Startup.cs
services.Configure<SmartWhereOptions>(options =>
{
    options.DefaultStringMethod = StringMethod.Contains;
    options.CaseSensitive = false;
    options.MaxNestingLevel = 10;
});

Custom Attribute Usage

[WhereClauseClass(DefaultStringMethod = StringMethod.StartsWith)]
public class CustomSearchRequest : IWhereClause
{
    [WhereClause]
    public string Name { get; set; }
}

📚 API Reference

Core Attributes

Attribute	Description	Example
WhereClause	Basic property filtering	[WhereClause]
TextualWhereClause	Text search with methods	[TextualWhereClause(StringMethod.Contains)]
ComparativeWhereClause	Numeric/date comparisons	[ComparativeWhereClause(ComparisonOperator.GreaterThan)]
WhereClauseClass	Class-level configuration	[WhereClauseClass]

String Methods

Method	Description	SQL Equivalent
Contains	Substring search	LIKE '%value%'
StartsWith	Prefix search	LIKE 'value%'
EndsWith	Suffix search	LIKE '%value'
Equals	Exact match	= 'value'

Comparison Operators

Operator	Description	SQL Equivalent
Equals	Equal to	=
NotEquals	Not equal to	!=
GreaterThan	Greater than	>
LessThan	Less than	<
GreaterThanOrEqual	Greater than or equal	>=
LessThanOrEqual	Less than or equal	<=
Between	Range check	BETWEEN

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following SOLID principles
4. Add comprehensive tests
5. Ensure 0 warnings, 0 errors
6. Submit a pull request

Code Quality Standards

• Follow SOLID principles
• Maintain DRY methodology
• Write comprehensive tests
• Ensure 0 warnings, 0 errors
• Use meaningful commit messages

🆕 What's New

Latest Release (v2.2.2.1)

• 🎯 Enhanced Performance: Optimized expression tree generation
• 🔍 Improved Nested Property Support: Better handling of complex property paths
• 🧹 Code Quality Improvements: SOLID principles implementation
• 📚 Enhanced Documentation: Comprehensive examples and API reference
• ⚡ Better Error Handling: Improved validation and error messages

Upcoming Features

• 🔄 Async Support: Async filtering operations
• 📊 Query Analytics: Performance monitoring and insights
• 🎨 Custom Operators: User-defined comparison operators
• 🌐 Multi-Language Support: Localized error messages

📚 Resources

• 📖 Wiki Documentation
• 🏠 GitHub Repository
• 🐛 Issue Tracker
• 💬 Discussions
• 📦 NuGet Package

📄 License

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

🙏 Acknowledgments

• Entity Framework Team for the excellent IQueryable<T> foundation
• .NET Community for inspiration and feedback
• Contributors who help improve SmartWhere

---

Built with ❤️ by Barış Yerlikaya

Made in Turkey 🇹🇷 | Contact | LinkedIn

---

⭐ Star this repository if you find SmartWhere helpful! ⭐