SmartOrderBy 1.2.1

dotnet add package SmartOrderBy --version 1.2.1
                    
NuGet\Install-Package SmartOrderBy -Version 1.2.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SmartOrderBy" Version="1.2.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SmartOrderBy" Version="1.2.1" />
                    
Directory.Packages.props
<PackageReference Include="SmartOrderBy" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SmartOrderBy --version 1.2.1
                    
#r "nuget: SmartOrderBy, 1.2.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package SmartOrderBy@1.2.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SmartOrderBy&version=1.2.1
                    
Install as a Cake Addin
#tool nuget:?package=SmartOrderBy&version=1.2.1
                    
Install as a Cake Tool

πŸš€ SmartOrderBy - Intelligent .NET Sorting Library

GitHub Workflow Status (with event) SmartOrderBy Nuget SmartOrderBy Nuget .NET License Code Quality

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; }
}
  1. 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

πŸ“„ 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! ⭐

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.
  • .NETStandard 2.1

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on SmartOrderBy:

Package Downloads
EntityGuardian

In your projects developed with EntityFramework, it keeps track of all the changes that take place in your database and records them wherever you want.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.1 99 8/22/2025
1.2.0.1 330 4/8/2025
1.2.0 911 8/2/2024
1.1.0.3 475 4/14/2024
1.1.0.2 401 2/27/2024
1.1.0.1 635 1/22/2024
1.1.0 439 12/2/2023
1.0.0.1 514 10/23/2023
1.0.0 298 10/5/2023

Enhanced performance with optimized expression tree generation, improved nested property support, and comprehensive documentation.