🚀 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! ⭐