sortsmith 0.9.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2145a4f96e357b7c580dd3bbd5c672120788c422d76737fcf7015539ace75c7
-  data.tar.gz: 80376b95b0cb7cee7a0b741a69d90a91307384623007b63384a1551871fdb2d5
+  metadata.gz: 594500201df14a274a22465d71f25e9471d67a9f6154047d73826974bdec2d62
+  data.tar.gz: cbf4a37cfeb106380825ea34aa9963c9342b2c2c8776149df7e1a1f2c9b60582
 SHA512:
-  metadata.gz: 5de79e4da81b5dbf9096a9c0cbf21dd6c00500a89b8fcec679b3116b324864b3b70bf8d8e4759069412dc0979eeadbe5e3a05e8da28016ea2638de7ab8fbc54a
-  data.tar.gz: 1e7270386a18f165954b41810143d89920f66195f311826a19f4465a60c8865cbf3dd9e0de29cc7408d9bd41cbac43f8803030aa5724bc64e0e63f96e077f456
+  metadata.gz: 1dba596a763ca288fa3bd45bc5d5f8f4dd7cbd5683e886bd4e765957d1ae4225605454af524825073a006cd63fe5c183063b613aa4317abb6ad3b2ffcf00739b
+  data.tar.gz: aa1d3317d8486227a8e33da7633101afa356fdf2a640ff678d1f8d1b140bd734abce58fc3767899f352609574c00400e02106e47fd1e404540ef9087490da9c6

data/CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+<!--
 ## [Unreleased]
 
 ### Added
@@ -12,6 +13,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 ### Removed
+-->
+
+## [1.0.1] - 12026-02-15
+
+### Added
+
+#### Nil Handling Control
+
+- **`nil_first`** - Position nil values at the beginning of sort results
+- **`nil_last`** - Explicitly position nil values at the end (default behavior)
+- Nil positioning is independent of `asc`/`desc` modifiers for predictable behavior
+- Graceful handling of nil values during comparison (should be no more comparison errors)
+
+### Changed
+
+#### Internal Implementation
+
+- **Major performance improvement**: Refactored sorting to use Schwartzian Transform (extract once, sort, map back) instead of comparison sort
+  - Reduced overhead from ~65x slower to ~5.9x slower compared to native Ruby sort (measured on Ruby 3.2.9, AMD Ryzen 7 3700X, 32GB RAM)
+  - ~11x speedup for typical use cases
+  - Tests now run 4.4x faster
+- Refactored `asc`/`desc` from array ordering to comparison-time flag for better performance and consistency
+- Improved nil comparison logic to handle edge cases consistently
+
+### Fixed
+
+- Fixed comparison errors when sorting collections with nil values
+- Fixed `NoMethodError` when trying to negate nil result in descending sorts
+
+
+## [1.0.0] - 12025-08-03
+
+### 🎉 API Stability Milestone
+
+Sortsmith has reached 1.0.0! After evolving through several major API redesigns and proving itself in real projects, the core interface is now stable and ready for broader adoption.
+
+**What 1.0.0 means:**
+- **Stable API**: Method signatures and behavior are locked for semver compatibility
+- **Complete Vision**: From the verbose early days to today's clean `collection.sort_by(:name).insensitive.desc.sort`, the API finally feels right
+- **Battle Tested**: Handles the weird edge cases and mixed data types you actually encounter in real Ruby apps
+
+This represents the sorting library I always wished Ruby had built-in. Simple things are simple, complex things are possible, and it all reads like English.
+
+### Added
+
+#### Universal Field Extraction
+
+- **Direct syntax**: `sort_by(field, **opts)` - Sort by any field/method without explicit chaining
+- **Object method extraction**: `method(*args, **kwargs)` - Call methods on objects with full argument support
+- **Mixed key handling**: Enhanced `indifferent: true` support across all extractors
+
+#### Semantic Aliases for Better Readability
+
+- `key` - Alias for `dig` (emphasizes hash key extraction)
+- `field` - Alias for `dig` (emphasizes object field access)
+- `attribute` - Alias for `method` (emphasizes object attribute access)
+- `case_insensitive` - Alias for `insensitive`/`downcase` (explicit case handling)
+
+#### Seamless Enumerable Integration
+
+- **Delegated methods**: `first`, `last`, `take`, `drop`, `each`, `map`, `select`, `[]`, `size`, `count`, `length`
+- **Fluent chaining**: Sort operations flow directly into array operations without breaking
+- **Full argument support**: All delegated methods support blocks, arguments, and return appropriate types
+
+#### Enhanced Terminators
+
+- `to_a!` - Mutating version of `to_a` for consistency with `sort!`
 
 ## [0.9.0] - 12025-07-06
 
@@ -24,23 +92,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 #### Core API Transformation
+
 - **Fluent API**: Direct extension of `Enumerable#sort_by` for natural Ruby integration
 - **Chainable Interface**: Method chaining that reads like English: `users.sort_by.dig(:name).downcase.desc.sort`
 - **Universal `dig` Method**: Single extraction method that works with hashes, objects, and nested structures
 - **Indifferent Key Access**: Handle mixed symbol/string hash keys with `dig(:name, indifferent: true)`
 
 #### New Extraction Methods
+
 - `dig(*identifiers, indifferent: false)` - Extract values from hashes, objects, or nested structures
 - Support for nested extraction: `dig(:user, :profile, :email)`
 - Automatic fallback to method calls for non-hash objects
 
 #### Enhanced Modifiers
+
 - `downcase` / `upcase` - Case transformations with automatic type checking
 - `insensitive` - Alias for `downcase` for semantic clarity
 - `asc` / `desc` - Explicit sort direction control
 - Smart modifier chaining that only affects compatible data types
 
 #### Multiple Terminators
+
 - `sort` - Returns new sorted array (non-mutating)
 - `sort!` - Mutates original array in place
 - `reverse` - Shorthand for `desc.sort`
@@ -48,6 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `to_a` - Alias for `sort` for semantic clarity
 
 #### Backward Compatibility
+
 - `sort_by` with block maintains original Ruby behavior
 - `sort_by` without block returns Sortsmith::Sorter instance
 - Zero breaking changes for existing Ruby code
@@ -55,16 +128,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 #### API Design Philosophy
+
 - **Before**: `Sortsmith::Sorter.new(collection).by_key(:name).case_insensitive.desc.sort`
 - **After**: `collection.sort_by.dig(:name).insensitive.desc.sort`
 
 #### Improved Ergonomics
+
 - No more explicit `Sorter.new()` instantiation required
 - Tab-completable method discovery
 - Natural language flow in method chains
 - Unified `dig` method replaces separate `by_key`/`by_method` methods
 
 #### Enhanced Ruby Version Support
+
 - **Restored Ruby 3.0 and 3.1 compatibility** - Previously removed in v0.2.0, now supported again
 - Full compatibility matrix: Ruby 3.0.7, 3.1.7, 3.2.8, 3.3.8, 3.4.4
 - Expanded from Ruby 3.2+ requirement back to Ruby 3.0+ for broader accessibility
@@ -72,6 +148,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 
 #### Legacy API (Breaking Changes)
+
 - `by_key` method (replaced by `dig`)
 - `by_method`/`by_attribute` methods (replaced by `dig`)
 - `case_insensitive` method (replaced by `insensitive`/`downcase`)
@@ -122,11 +199,13 @@ objects.sort_by.dig(:calculate_score).sort
 ## [0.1.1] - 12025-01-15
 
 ### Changed
+
 - Improved handling of non-string objects when sorting
 
 ## [0.1.0] - 12025-01-14
 
 ### Added
+
 - Initial implementation of `Sortsmith::Sorter`
 - Support for case-insensitive sorting
 - Support for sorting by hash keys and object methods
@@ -134,7 +213,9 @@ objects.sort_by.dig(:calculate_score).sort
 - Type checking with Steep/RBS
 - GitHub Actions workflow for automated testing and type checking
 
-[unreleased]: https://github.com/itsthedevman/sortsmith/compare/v0.9.0...HEAD
+[unreleased]: https://github.com/itsthedevman/sortsmith/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/itsthedevman/sortsmith/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/itsthedevman/sortsmith/compare/v0.9.0...v1.0.0
 [0.9.0]: https://github.com/itsthedevman/sortsmith/compare/v0.2.0...v0.9.0
 [0.2.0]: https://github.com/itsthedevman/sortsmith/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/itsthedevman/sortsmith/compare/v0.1.0...v0.1.1

data/README.md

@@ -1,7 +1,7 @@
 # Sortsmith
 
 [![Gem Version](https://badge.fury.io/rb/sortsmith.svg)](https://badge.fury.io/rb/sortsmith)
-![Ruby Version](https://img.shields.io/badge/ruby-3.0+-ruby)
+![Ruby Version](https://img.shields.io/badge/ruby-3.1+-ruby)
 [![Tests](https://github.com/itsthedevman/sortsmith/actions/workflows/main.yml/badge.svg)](https://github.com/itsthedevman/sortsmith/actions/workflows/main.yml)
 
 **Sortsmith** makes sorting Ruby collections feel natural and fun. Instead of wrestling with verbose blocks or complex comparisons, just chain together what you want in plain English.
@@ -11,10 +11,10 @@
 users.sort_by { |user| user[:name].downcase }.reverse
 
 # Write this!
-users.sort_by.dig(:name).downcase.reverse
+users.sort_by(:name).downcase.reverse
 ```
 
-Sortsmith extends Ruby's built-in `sort_by` method with a fluent, chainable API that handles the messy details so you can focus on expressing *what* you want sorted, not *how* to sort it.
+Sortsmith extends Ruby's built-in `sort_by` method with a fluent, chainable API that handles the messy details so you can focus on expressing _what_ you want sorted, not _how_ to sort it.
 
 ## Table of Contents
 
@@ -46,21 +46,28 @@ users.sort_by { |u| (u[:name] || "").downcase }.reverse
 
 # What about mixed string/symbol keys?
 users.sort_by { |u| (u[:name] || u["name"] || "").downcase }.reverse
+
+# Need nils first instead of last?
+nils, non_nils = users.partition { |u| u[:name].nil? }
+nils + non_nils.sort_by { |u| u[:name].downcase }
 ```
 
 Sortsmith handles all the edge cases and gives you a clean, readable API:
 
 ```ruby
-users.sort_by.dig(:name, indifferent: true).insensitive.desc.sort
+users.sort_by.dig(:name).insensitive.desc.sort
+
+# With nils first
+users.sort_by.dig(:name).insensitive.nil_first.sort
 ```
 
 **Features:**
+
 - **Fluent chaining** - Reads like English
 - **Universal extraction** - Works with hashes, objects, and nested data
 - **Indifferent key access** - Handles mixed symbol/string keys automatically
-- **Nil-safe** - Graceful handling of missing data
+- **Nil-safe** - Graceful handling of missing data with control over nil positioning
 - **Minimal overhead** - Extends existing Ruby methods without breaking compatibility
-- **Tab-completable** - Discoverable API through your editor
 
 ## Installation
 
@@ -84,17 +91,17 @@ $ gem install sortsmith
 
 ## Quick Start
 
-Sortsmith extends Ruby's `sort_by` method. When called without a block, it returns a chainable sorter:
+Sortsmith extends Ruby's `sort_by` method with a fluent, chainable API. Use it with or without a block for maximum flexibility:
 
 ```ruby
 require "sortsmith"
 
-# Basic string sorting
+# Direct syntax for simple cases
 names = ["charlie", "Alice", "bob"]
-names.sort_by.insensitive.sort
+names.sort_by(:name).insensitive.sort
 # => ["Alice", "bob", "charlie"]
 
-# Hash sorting
+# Or use the chainable API for complex scenarios
 users = [
   { name: "Charlie", age: 25 },
   { name: "Alice", age: 30 },
@@ -104,6 +111,10 @@ users = [
 users.sort_by.dig(:name).sort
 # => [{ name: "Alice", age: 30 }, { name: "Bob", age: 20 }, { name: "Charlie", age: 25 }]
 
+# Seamless integration with enumerable methods
+users.sort_by(:age).desc.first(2)
+# => [{ name: "Alice", age: 30 }, { name: "Charlie", age: 25 }]
+
 # The original sort_by with blocks still works exactly the same!
 users.sort_by { |u| u[:age] }
 # => [{ name: "Bob", age: 20 }, { name: "Charlie", age: 25 }, { name: "Alice", age: 30 }]
@@ -113,10 +124,10 @@ users.sort_by { |u| u[:age] }
 
 Sortsmith uses a simple pipeline concept where each step is **optional** except for the terminator:
 
-1. **Extract** - Get the value to sort by (`dig`) - *optional*
-2. **Transform** - Modify the value for comparison (`downcase`, `upcase`) - *optional*
-3. **Order** - Choose sort direction (`asc`, `desc`) - *optional*
-4. **Execute** - Run the sort (`sort`, `sort!`, `reverse`) - **required**
+1. **Extract** - Get the value to sort by (`dig`, `method`, etc.) - _optional_
+2. **Transform** - Modify the value for comparison (`downcase`, `upcase`, etc.) - _optional_
+3. **Order** - Choose sort direction (`asc`, `desc`) - _optional_
+4. **Execute** - Run the sort (`sort`, `sort!`, `reverse`, `to_a`, etc.) - **required**
 
 ```ruby
 collection.sort_by.dig(:field).downcase.desc.sort
@@ -126,6 +137,7 @@ collection.sort_by.dig(:field).downcase.desc.sort
 ```
 
 **Minimal example:**
+
 ```ruby
 # This works! (though not particularly useful)
 users.sort_by.sort  # Same as users.sort
@@ -141,59 +153,29 @@ Each step builds on the previous ones, so you can mix and match based on what yo
 
 ## Usage Examples
 
-### Array Sorting
+### Simple Direct Syntax
 
 ```ruby
-# Basic sorting
-words = ["banana", "Apple", "cherry"]
-words.sort_by.sort
-# => ["Apple", "banana", "cherry"]
-
-# Case-insensitive
-words.sort_by.insensitive.sort
-# => ["Apple", "banana", "cherry"]
-
-# Descending order
-words.sort_by.downcase.desc.sort
-# => ["cherry", "banana", "Apple"]
-
-# In-place mutation
-words.sort_by.insensitive.sort!
-# Modifies the original array
-```
+# Clean and direct for common operations
+words = ["elephant", "cat", "butterfly"]
+words.sort_by(:length).desc.sort
+# => ["butterfly", "elephant", "cat"]
 
-### Hash Collections
-
-```ruby
+# Works great with hashes
 users = [
-  { name: "Charlie", score: 85, team: "red" },
-  { name: "Alice", score: 92, team: "blue" },
-  { name: "bob", score: 78, team: "red" }
+  { name: "Cat", score: 99 },
+  { name: "Charlie", score: 85 },
+  { name: "karen", score: 50 },
+  { name: "Alice", score: 92 },
+  { name: "bob", score: 78 },
 ]
 
-# Sort by name (case-sensitive)
-users.sort_by.dig(:name).sort
-# => [{ name: "Alice" }, { name: "Charlie" }, { name: "bob" }]
-
-# Sort by name (case-insensitive)
-users.sort_by.dig(:name).insensitive.sort
-# => [{ name: "Alice" }, { name: "bob" }, { name: "Charlie" }]
-
-# Sort by score (descending)
-users.sort_by.dig(:score).desc.sort
-# => [{ score: 92 }, { score: 85 }, { score: 78 }]
-
-# Multiple field extraction (nested digging)
-data = [
-  { user: { profile: { name: "Charlie" } } },
-  { user: { profile: { name: "Alice" } } }
-]
-
-data.sort_by.dig(:user, :profile, :name).sort
-# => [{ user: { profile: { name: "Alice" } } }, ...]
+# Get top 3 by score
+users.sort_by(:score).desc.first(3)
+# => [{ name: "Cat", score: 99 }, { name: "Alice", score: 92 }, { name: "Charlie", score: 85 }]
 ```
 
-### Object Collections
+### Object Method Sorting
 
 ```ruby
 User = Struct.new(:name, :age, :city)
@@ -204,20 +186,59 @@ users = [
   User.new("bob", 20, "Chicago")
 ]
 
-# Sort by any method/attribute
-users.sort_by.dig(:name).insensitive.sort
+# Sort by any method or attribute
+users.sort_by.method(:name).insensitive.sort
 # => [User.new("Alice"), User.new("bob"), User.new("Charlie")]
 
-users.sort_by.dig(:age).reverse
-# => [User.new("Alice", 30), User.new("Charlie", 25), User.new("bob", 20)]
+# Or use the semantic alias
+users.sort_by.attribute(:age).desc.first
+# => User.new("Alice", 30, "LA")
 
-# Works with any object that responds to the method
-class Score
-  def calculate; rand(100); end
+# Methods with arguments work too
+class Product
+  def price_in(currency)
+    # calculation logic
+  end
 end
 
-scores = [Score.new, Score.new, Score.new]
-scores.sort_by.dig(:calculate).desc.sort
+products.sort_by.method(:price_in, "USD").sort
+```
+
+### Hash Collections with Multiple Access Patterns
+
+```ruby
+users = [
+  { name: "Charlie", score: 85, team: "red" },
+  { name: "Alice", score: 92, team: "blue" },
+  { name: "bob", score: 78, team: "red" }
+]
+
+# Multiple semantic ways to express extraction
+users.sort_by.key(:name).insensitive.sort      # Emphasizes hash keys
+users.sort_by.field(:score).desc.sort          # Emphasizes data fields
+users.sort_by.dig(:team, :name).sort           # Nested access
+
+# Case handling with explicit naming
+users.sort_by(:name).case_insensitive.reverse
+# => [{ name: "bob" }, { name: "Charlie" }, { name: "Alice" }]
+```
+
+### Seamless Enumerable Integration
+
+```ruby
+# Chain directly into enumerable methods - no .to_a needed!
+users.sort_by(:score).desc.first(2)           # Top 2 performers
+users.sort_by(:name).each { |u| puts u }      # Iterate in order
+users.sort_by(:team).map(&:name)              # Transform sorted results
+users.sort_by(:score).select { |u| u[:active] } # Filter sorted results
+
+# Array access works too
+users.sort_by(:score).desc[0]                 # Best performer
+users.sort_by(:name)[1..3]                    # Users 2-4 alphabetically
+
+# Quick stats
+users.sort_by(:score).count                   # Total count
+users.sort_by(:team).count { |u| u[:active] } # Conditional count
 ```
 
 ### Mixed Key Types
@@ -251,17 +272,53 @@ api_response.sort_by.dig(:name, indifferent: true).sort
 
 ## API Reference
 
+### Universal Extraction
+
+- **`sort_by(field, **opts)`** - Direct field extraction
+  - Works with hashes, objects, and any method name
+  - Supports all the same options as `dig` and `method`
+
 ### Extractors
 
 - **`dig(*identifiers, indifferent: false)`** - Extract values from hashes, objects, or nested structures
-  - Works with hash keys, object methods, and nested paths
-  - `indifferent: true` normalizes hash keys for consistent lookup across string/symbol keys
+- **`method(method_name, *args, **kwargs)`** - Call methods on objects with arguments
+- **`key(*identifiers, **opts)`** - Alias for `dig` (semantic clarity for hash keys)
+- **`field(*identifiers, **opts)`** - Alias for `dig` (semantic clarity for object fields)
+- **`attribute(method_name, *args, **kwargs)`** - Alias for `method` (semantic clarity)
 
 ### Modifiers
 
 - **`downcase`** - Convert extracted strings to lowercase for comparison
 - **`upcase`** - Convert extracted strings to uppercase for comparison
 - **`insensitive`** - Alias for `downcase` (semantic clarity)
+- **`case_insensitive`** - Alias for `downcase` (explicit case handling)
+
+### Nil Handling (NEW!)
+
+- **`nil_first`** - Position nil values at the beginning of results
+- **`nil_last`** - Position nil values at the end of results (default)
+
+```ruby
+users = [
+  { name: "Bob" },
+  { name: nil },
+  { name: "Alice" }
+]
+
+# Default: nils last
+users.sort_by.dig(:name).sort
+# => [{ name: "Alice" }, { name: "Bob" }, { name: nil }]
+
+# Nils first
+users.sort_by.dig(:name).nil_first.sort
+# => [{ name: nil }, { name: "Alice" }, { name: "Bob" }]
+
+# Nil positioning is independent of sort direction
+users.sort_by.dig(:name).nil_first.desc.sort
+# => [{ name: nil }, { name: "Bob" }, { name: "Alice" }]
+```
+
+**Note**: Nil positioning is independent of `asc`/`desc` modifiers. `nil_first` always places nils at the beginning, and `nil_last` always places them at the end, regardless of whether the non-nil values are sorted ascending or descending.
 
 ### Ordering
 
@@ -273,33 +330,28 @@ api_response.sort_by.dig(:name, indifferent: true).sort
 - **`sort`** - Execute sort and return new array
 - **`sort!`** - Execute sort and mutate original array
 - **`to_a`** - Alias for `sort`
+- **`to_a!`** - Alias for `sort!`
 - **`reverse`** - Shorthand for `desc.sort`
 - **`reverse!`** - Shorthand for `desc.sort!`
 
-## Migration from v0.2.x
-
-The v0.3.x API is more concise and intuitive:
+### Delegated Enumerable Methods
 
-```ruby
-# v0.2.x (OLD - no longer works)
-Sortsmith::Sorter.new(users).by_key(:name).case_insensitive.desc.sort
+The following methods execute the sort and delegate to the resulting array:
 
-# v0.3.x (NEW)
-users.sort_by.dig(:name).insensitive.desc.sort
+- **`first(n=1)`**, **`last(n=1)`** - Get first/last n elements
+- **`take(n)`**, **`drop(n)`** - Take/drop n elements
+- **`each`**, **`map`**, **`select`** - Standard enumerable operations
+- **`[](index)`** - Array access by index or range
+- **`size`**, **`count`**, **`length`** - Size information
 
-# v0.2.x (OLD)
-Sortsmith::Sorter.new(objects).by_method(:calculate_score).sort
-
-# v0.3.x (NEW)
-objects.sort_by.dig(:calculate_score).sort
+```ruby
+# All of these execute the sort first, then apply the operation
+users.sort_by(:score).desc.first(3)    # Get top 3
+users.sort_by(:name).take(5)           # Take first 5 alphabetically
+users.sort_by(:team)[0]                # First by team name
+users.sort_by(:score).size             # Total size after sorting
 ```
 
-**Key Changes:**
-- `by_key` → `dig`
-- `by_method`/`by_attribute` → `dig`
-- `case_insensitive` → `insensitive` or `downcase`
-- No more manual `Sorter.new()` - just call `sort_by` without a block
-
 ## Development
 
 ### Prerequisites
@@ -310,11 +362,13 @@ objects.sort_by.dig(:calculate_score).sort
 ### Setting Up the Development Environment
 
 With Nix:
+
 ```bash
 direnv allow
 ```
 
 Without Nix:
+
 ```bash
 bundle install
 ```
@@ -325,6 +379,31 @@ bundle install
 bundle exec rake test
 ```
 
+### Benchmarks
+
+Run performance benchmarks to compare Sortsmith with native Ruby:
+
+```bash
+# Quick benchmark
+bundle exec rake benchmark
+
+# Full benchmark suite
+bundle exec rake benchmark:full
+```
+
+#### Performance
+
+Sortsmith prioritizes developer ergonomics and code readability over raw performance. Benchmarks show approximately **5.7x-6.5x slower** than native Ruby `sort_by` for typical use cases:
+
+- Basic sorting: **5.75x slower**
+- Case-insensitive + descending: **5.65x slower**
+- With nil values: **6.06x slower**
+- Top N selection: **6.50x slower**
+
+*Benchmarked on Ruby 3.2.9, AMD Ryzen 7 3700X 8-Core Processor, 32GB RAM*
+
+The performance overhead is typically measured in microseconds for small to medium datasets, making it negligible for most real-world applications where code clarity and maintainability are more important than micro-optimizations.
+
 ### Code Style
 
 This project uses StandardRB. To check your code:

data/Rakefile

@@ -8,3 +8,18 @@ Minitest::TestTask.create
 require "standard/rake"
 
 task default: %i[test standard]
+
+namespace :benchmark do
+  desc "Run quick benchmark"
+  task :quick do
+    ruby "benchmark/quick_benchmark.rb"
+  end
+
+  desc "Run full benchmark suite"
+  task :full do
+    ruby "benchmark/sorting_benchmark.rb"
+  end
+end
+
+desc "Run quick benchmark"
+task benchmark: "benchmark:quick"

data/benchmark/quick_benchmark.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "sortsmith"
+require "benchmark/ips"
+
+# Quick comparison of common scenarios
+puts "Quick Performance Comparison"
+puts "=" * 60
+
+users = Array.new(1000) do |i|
+  {
+    name: ["Alice", "bob", "Charlie", "DIANA"].sample,
+    score: rand(0..100),
+    age: i.even? ? rand(18..65) : nil
+  }
+end
+
+puts "\n1. Basic sorting"
+Benchmark.ips do |x|
+  x.report("native") { users.sort_by { |u| u[:name] } }
+  x.report("sortsmith") { users.sort_by.dig(:name).sort }
+  x.compare!
+end
+
+puts "\n2. Case-insensitive + descending"
+Benchmark.ips do |x|
+  x.report("native") { users.sort_by { |u| u[:name].to_s.downcase }.reverse }
+  x.report("sortsmith") { users.sort_by.dig(:name).insensitive.desc.sort }
+  x.compare!
+end
+
+puts "\n3. With nil values"
+Benchmark.ips do |x|
+  x.report("native") { users.sort_by { |u| u[:age] || 0 } }
+  x.report("sortsmith") { users.sort_by.dig(:age).sort }
+  x.compare!
+end
+
+puts "\n4. Top 5 by score"
+Benchmark.ips do |x|
+  x.report("native") { users.sort_by { |u| u[:score] }.last(5).reverse }
+  x.report("sortsmith") { users.sort_by.dig(:score).desc.first(5) }
+  x.compare!
+end
+
+puts "\n" + "=" * 60