🚀 SmartOrderBy - Intelligent .NET Sorting Library

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

✨ Key Highlights

• 🎯 Intelligent Sorting: Automatically generates ORDER BY clauses from request objects
• 🔍 Deep Property Navigation: Support for nested property sorting (e.g., Books.Author.Name)
• 🏷️ Attribute-Based Configuration: Simple attribute decoration for sort 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 SmartOrderBy NuGet package:

# Package Manager Console
PM> Install-Package SmartOrderBy

# .NET CLI
dotnet add package SmartOrderBy

# NuGet Package Manager
Install-Package SmartOrderBy

Basic Usage

1. Define your sorting request with the Sorting object:

public class PublisherRequest
{
    public Sorting OrderBy { get; set; }
}

public class Sorting
{
    public string Name { get; set; }
    public string OrderType { get; set; }
}

2. Use SmartOrderBy in your queries:

[HttpPost("/publishers")]
public IActionResult GetPublishers(PublisherRequest request)
{
    var result = _context.Publishers
        .Include(x => x.Books)
        .ThenInclude(x => x.Author)
        .OrderBy(request.OrderBy)  // 🎯 SmartOrderBy magic happens here!
        .ToList();

    return Ok(result);
}

That's it! SmartOrderBy automatically generates the appropriate ORDER BY clauses based on your request object.

🏗️ Architecture & Components

┌─────────────────────────────────────────────────────────────┐
│                    SmartOrderBy Library                     │
├─────────────────────────────────────────────────────────────┤
│  📋 Core Components                                        │
│  • Sorting Class           • OrderType Enum               │
│  • Extensions              • OrderByMapper                │
│  • Property Resolution     • Expression Generation        │
├─────────────────────────────────────────────────────────────┤
│  🔧 Extension Methods                                      │
│  • OrderBy(sorting)        • OrderByDescending(sorting)   │
│  • ThenBy(sorting)         • ThenByDescending(sorting)    │
├─────────────────────────────────────────────────────────────┤
│  🎯 Mapping System                                         │
│  • Property Mapping        • Nested Entity Support        │
│  • Type Safety            • Performance Optimization      │
└─────────────────────────────────────────────────────────────┘

Key Components

• 📋 Sorting Class: Simple structure for sort criteria
• 🔍 OrderType Enum: Supports "asc", "ascending", "a" or "desc", "descending", "d"
• ⚡ Extensions: Fluent API for sorting operations
• 🔧 OrderByMapper: Advanced property mapping system

🎨 Advanced Usage Examples

Simple Property Sorting

public class BookSearchRequest
{
    public Sorting OrderBy { get; set; }
}

// Usage
var result = _context.Books
    .OrderBy(request.OrderBy)
    .ToList();

Nested Property Sorting

public class AdvancedSearchRequest
{
    [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; }
}

Custom Property Mapping

If you want to specify the name of the field you want to sort differently from the field in the entity, you need to map it.

👉 You can access the sample domain structure here. 👈

For example, if you want to make a sorting with the name bookId according to the Id field of the Book entity in Publisher, you will need to make a mapping as follows:

OrderByMapper.Map<Publisher, Book>("bookId", x => x.Id);

Or if you want to make a sort with the authorAge name according to the Age field of the Author entity in the Book entity in Publisher:

OrderByMapper.Map<Publisher, Book, Author>("authorAge", x => x.Age);

⭐ The important thing here is to specify the relevant entities in Map<TSource,T1,T2,...> respectively until you reach the sort field.

Multiple Sorting Criteria

// Combine multiple sorts with ThenBy
var result = _context.Publishers
    .OrderBy(request.OrderBy)
    .ThenBy(request.ThenBy)
    .ThenByDescending(request.ThenByDesc)
    .ToList();

📊 Performance & Benchmarks

Performance Metrics

• Simple Sort: ~0.1ms overhead per sort
• Complex Nested Sort: ~0.5ms overhead per sort
• 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 sorts
• Consider database indexing for sorted properties
• Use pagination for large datasets

🛠️ Development & Testing

Building from Source

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

Running Tests

# Run all tests
dotnet test

# Run specific test project
dotnet test test/SmartOrderBy.Test/

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

Sample API

cd sample/Sample.Api
dotnet run

Browse to the API endpoints to see SmartOrderBy in action.

🔧 Configuration & Customization

Global Configuration

// In Program.cs or Startup.cs
services.Configure<SmartOrderByOptions>(options =>
{
    options.DefaultOrderType = OrderType.Ascending;
    options.CaseSensitive = false;
    options.MaxNestingLevel = 10;
});

Custom Mapping Usage

// Configure mappings in your startup
OrderByMapper.Map<Publisher, Book>("bookId", x => x.Id);
OrderByMapper.Map<Publisher, Book, Author>("authorAge", x => x.Age);

📚 API Reference

Core Classes

Class	Description	Example
Sorting	Basic sorting criteria	new Sorting { Name = "Title", OrderType = "asc" }
OrderType	Sort direction enum	OrderType.Ascending, OrderType.Descending
OrderByMapper	Property mapping system	OrderByMapper.Map<T, T1>()

Order Types

Type	Description	SQL Equivalent
asc, ascending, a	Ascending order	ORDER BY ASC
desc, descending, d	Descending order	ORDER BY DESC

Extension Methods

Method	Description	Example
OrderBy(sorting)	Primary sort	.OrderBy(request.OrderBy)
OrderByDescending(sorting)	Primary sort descending	.OrderByDescending(request.OrderBy)
ThenBy(sorting)	Secondary sort	.ThenBy(request.ThenBy)
ThenByDescending(sorting)	Secondary sort descending	.ThenByDescending(request.ThenBy)

🤝 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 (v1.2.0.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 sorting operations
• 📊 Query Analytics: Performance monitoring and insights
• 🎨 Custom Comparers: User-defined comparison logic
• 🌐 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 SmartOrderBy

---

Built with ❤️ by Barış Yerlikaya

Made in Turkey 🇹🇷 | Contact | LinkedIn

---

⭐ Star this repository if you find SmartOrderBy helpful! ⭐