sortsmith 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b369873631fe1de4c59f32bbbf5fbdb383ee1b3924a864ccd11a2ac6c4f1d5
-  data.tar.gz: cb329eecad62b7cf05e13624258fc09dd4a21e0aab192e50774a8e2a6c6beed3
+  metadata.gz: 594500201df14a274a22465d71f25e9471d67a9f6154047d73826974bdec2d62
+  data.tar.gz: cbf4a37cfeb106380825ea34aa9963c9342b2c2c8776149df7e1a1f2c9b60582
 SHA512:
-  metadata.gz: e3ada898d22d88aabe5c314dc67ac35dced713ec5f7bced55ec4ca87d12f10cd62b9fe218d6acb45831d9ec62734917d72c5343dce56b15bace088b23188bc95
-  data.tar.gz: e362605cde0d51b9eb63ef435e69cf13d91651ff2a9ba22dfe07a8cdd1e33c9c8bb0ce695c0914bfb3579226a3306c2d4d03f029752c25f8b17dbff22133fb1d
+  metadata.gz: 1dba596a763ca288fa3bd45bc5d5f8f4dd7cbd5683e886bd4e765957d1ae4225605454af524825073a006cd63fe5c183063b613aa4317abb6ad3b2ffcf00739b
+  data.tar.gz: aa1d3317d8486227a8e33da7633101afa356fdf2a640ff678d1f8d1b140bd734abce58fc3767899f352609574c00400e02106e47fd1e404540ef9087490da9c6

data/CHANGELOG.md

@@ -15,6 +15,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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
@@ -185,7 +213,8 @@ 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/v1.0.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

data/README.md

@@ -11,7 +11,7 @@
 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.
@@ -46,12 +46,19 @@ 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:**
@@ -59,7 +66,7 @@ users.sort_by.dig(:name, indifferent: true).insensitive.desc.sort
 - **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
 
 ## Installation
@@ -89,7 +96,7 @@ Sortsmith extends Ruby's `sort_by` method with a fluent, chainable API. Use it w
 ```ruby
 require "sortsmith"
 
-# Direct syntax for simple cases (NEW!)
+# Direct syntax for simple cases
 names = ["charlie", "Alice", "bob"]
 names.sort_by(:name).insensitive.sort
 # => ["Alice", "bob", "charlie"]
@@ -104,7 +111,7 @@ users = [
 users.sort_by.dig(:name).sort
 # => [{ name: "Alice", age: 30 }, { name: "Bob", age: 20 }, { name: "Charlie", age: 25 }]
 
-# Seamless integration with enumerable methods (NEW!)
+# Seamless integration with enumerable methods
 users.sort_by(:age).desc.first(2)
 # => [{ name: "Alice", age: 30 }, { name: "Charlie", age: 25 }]
 
@@ -267,24 +274,51 @@ api_response.sort_by.dig(:name, indifferent: true).sort
 
 ### Universal Extraction
 
-- **`sort_by(field, **opts)`\*\* - Direct field extraction (NEW!)
+- **`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
-- **`method(method_name, \*args, **kwargs)`\*\* - Call methods on objects with arguments (NEW!)
-- **`key(\*identifiers, **opts)`** - Alias for `dig` (semantic clarity for hash keys) (NEW!)
-- **`field(\*identifiers, **opts)`** - Alias for `dig` (semantic clarity for object fields) (NEW!)
-- **`attribute(method_name, \*args, **kwargs)`** - Alias for `method` (semantic clarity) (NEW!)
+- **`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) (NEW!)
+- **`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
 
@@ -296,11 +330,11 @@ 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!` (NEW!)
+- **`to_a!`** - Alias for `sort!`
 - **`reverse`** - Shorthand for `desc.sort`
 - **`reverse!`** - Shorthand for `desc.sort!`
 
-### Delegated Enumerable Methods (NEW!)
+### Delegated Enumerable Methods
 
 The following methods execute the sort and delegate to the resulting array:
 
@@ -345,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

data/benchmark/sorting_benchmark.rb

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "sortsmith"
+require "benchmark/ips"
+
+# Sample data generators
+def generate_users(count)
+  Array.new(count) do |i|
+    {
+      name: ["Alice", "Bob", "Charlie", "Diana", "Eve", "Frank"].sample,
+      age: rand(18..65),
+      score: rand(0..100),
+      email: "user#{i}@example.com"
+    }
+  end
+end
+
+def generate_mixed_nil_users(count)
+  Array.new(count) do |i|
+    {
+      name: i.even? ? ["Alice", "Bob", "Charlie"].sample : nil,
+      age: rand(18..65),
+      score: i.odd? ? rand(0..100) : nil
+    }
+  end
+end
+
+def generate_mixed_case_names(count)
+  names = ["alice", "BOB", "Charlie", "DIANA", "eve", "Frank"]
+  Array.new(count) { names.sample }
+end
+
+puts "=" * 80
+puts "Sortsmith Performance Benchmarks"
+puts "=" * 80
+puts
+
+# Benchmark 1: Basic hash key sorting
+puts "Benchmark 1: Basic hash key sorting (1000 items)"
+puts "-" * 80
+users = generate_users(1000)
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("native sort_by") do
+    users.sort_by { |u| u[:name] }
+  end
+
+  x.report("sortsmith .dig") do
+    users.sort_by.dig(:name).sort
+  end
+
+  x.report("sortsmith direct") do
+    users.sort_by(:name).sort
+  end
+
+  x.compare!
+end
+
+puts "\n"
+
+# Benchmark 2: Case-insensitive sorting
+puts "Benchmark 2: Case-insensitive sorting (1000 items)"
+puts "-" * 80
+names = generate_mixed_case_names(1000)
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("native downcase") do
+    names.sort_by { |n| n.downcase }
+  end
+
+  x.report("sortsmith .insensitive") do
+    names.sort_by.insensitive.sort
+  end
+
+  x.compare!
+end
+
+puts "\n"
+
+# Benchmark 3: Descending order
+puts "Benchmark 3: Descending order (1000 items)"
+puts "-" * 80
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("native reverse") do
+    users.sort_by { |u| u[:score] }.reverse
+  end
+
+  x.report("sortsmith .desc") do
+    users.sort_by.dig(:score).desc.sort
+  end
+
+  x.report("sortsmith .reverse") do
+    users.sort_by.dig(:score).reverse
+  end
+
+  x.compare!
+end
+
+puts "\n"
+
+# Benchmark 4: Complex chaining
+puts "Benchmark 4: Complex chaining - case-insensitive descending (1000 items)"
+puts "-" * 80
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("native") do
+    users.sort_by { |u| u[:name].to_s.downcase }.reverse
+  end
+
+  x.report("sortsmith") do
+    users.sort_by.dig(:name).insensitive.desc.sort
+  end
+
+  x.compare!
+end
+
+puts "\n"
+
+# Benchmark 5: Nil handling
+puts "Benchmark 5: Nil handling (1000 items, ~50% nils)"
+puts "-" * 80
+mixed_users = generate_mixed_nil_users(1000)
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("native with || fallback") do
+    mixed_users.sort_by { |u| u[:name] || "" }
+  end
+
+  x.report("sortsmith nil_last (default)") do
+    mixed_users.sort_by.dig(:name).sort
+  end
+
+  x.report("sortsmith nil_first") do
+    mixed_users.sort_by.dig(:name).nil_first.sort
+  end
+
+  x.compare!
+end
+
+puts "\n"
+
+# Benchmark 6: Small vs Large datasets
+puts "Benchmark 6: Scaling - Small vs Large datasets"
+puts "-" * 80
+
+[10, 100, 1_000, 10_000].each do |size|
+  puts "\n#{size} items:"
+  data = generate_users(size)
+
+  Benchmark.ips do |x|
+    x.config(time: 3, warmup: 1)
+
+    x.report("native") do
+      data.sort_by { |u| u[:name] }
+    end
+
+    x.report("sortsmith") do
+      data.sort_by.dig(:name).sort
+    end
+
+    x.compare!
+  end
+end
+
+puts "\n"
+
+# Benchmark 7: Delegated methods
+puts "Benchmark 7: Delegated enumerable methods (1000 items)"
+puts "-" * 80
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("native .first(3)") do
+    users.sort_by { |u| u[:score] }.last(3).reverse
+  end
+
+  x.report("sortsmith .first(3)") do
+    users.sort_by.dig(:score).desc.first(3)
+  end
+
+  x.report("native .each") do
+    users.sort_by { |u| u[:name] }.each { |u| u[:name] }
+  end
+
+  x.report("sortsmith .each") do
+    users.sort_by.dig(:name).each { |u| u[:name] }
+  end
+
+  x.compare!
+end
+
+puts "\n" + "=" * 60

data/flake.lock

@@ -1,5 +1,21 @@
 {
   "nodes": {
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "narHash": "sha256-CIVLLkVgvHYbgI2UpXvIIBJ12HWgX+fjA8Xf8PUmqCY=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -18,13 +34,31 @@
         "type": "github"
       }
     },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1751792365,
-        "narHash": "sha256-J1kI6oAj25IG4EdVlg2hQz8NZTBNYvIS0l4wpr9KcUo=",
+        "lastModified": 1771008912,
+        "narHash": "sha256-gf2AmWVTs8lEq7z/3ZAsgnZDhWIckkb+ZnAo5RzSxJg=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "1fd8bada0b6117e6c7eb54aad5813023eed37ccb",
+        "rev": "a82ccc39b39b621151d6732718e3e250109076fa",
         "type": "github"
       },
       "original": {
@@ -34,10 +68,33 @@
         "type": "github"
       }
     },
+    "nixpkgs-ruby": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1770273217,
+        "narHash": "sha256-biMRh5KRKwtDbyHaBTmdrQxB0Ua2SlMEF+krGH1tPt0=",
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "8b840328105a5d6d5c0aac9d3d12d7e2213aac33",
+        "type": "github"
+      },
+      "original": {
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "flake-utils": "flake-utils",
-        "nixpkgs": "nixpkgs"
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-ruby": "nixpkgs-ruby"
       }
     },
     "systems": {
@@ -54,6 +111,21 @@
         "repo": "default",
         "type": "github"
       }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
     }
   },
   "root": "root",

data/flake.nix

@@ -4,6 +4,8 @@
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
+    nixpkgs-ruby.url = "github:bobvanderlinden/nixpkgs-ruby";
+    nixpkgs-ruby.inputs.nixpkgs.follows = "nixpkgs";
   };
 
   outputs =
@@ -11,19 +13,19 @@
       self,
       nixpkgs,
       flake-utils,
+      nixpkgs-ruby,
     }:
     flake-utils.lib.eachDefaultSystem (
       system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
+        ruby = nixpkgs-ruby.packages.${system}."ruby-3.2.9";
       in
       {
         devShells.default = pkgs.mkShell {
-          buildInputs = with pkgs; [
-            (ruby_3_2.override {
-              jemallocSupport = false;
-              docSupport = false;
-            })
+          buildInputs = [
+            ruby
+          ] ++ (with pkgs; [
 
             # Dependencies for native gems
             pkg-config
@@ -31,7 +33,7 @@
             readline
             zstd
             libyaml
-          ];
+          ]);
 
           shellHook = ''
             export GEM_HOME="$PWD/vendor/bundle"

data/lib/sortsmith/sorter.rb

@@ -32,6 +32,14 @@ module Sortsmith
   #   users.sort_by.method(:missing_email).sort
   #   # => preserves original order when method doesn't exist
   #
+  # @example Nil value handling
+  #   users = [{name: "Bob"}, {name: nil}, {name: "Alice"}]
+  #   users.sort_by.dig(:name).nil_first.sort
+  #   # => [{name: nil}, {name: "Alice"}, {name: "Bob"}]
+  #
+  #   users.sort_by.dig(:name).nil_last.desc.sort
+  #   # => [{name: "Bob"}, {name: "Alice"}, {name: nil}]
+  #
   # @see Enumerable#sort_by The enhanced sort_by method
   # @since 0.9.0
   #
@@ -91,7 +99,8 @@ module Sortsmith
       @input = input
       @extractors = []
       @modifiers = []
-      @ordering = []
+      @descending = false
+      @nil_first = false
     end
 
     ############################################################################
@@ -393,7 +402,7 @@ module Sortsmith
     #   users.sort_by.dig(:name).desc.asc.sort  # ends up ascending
     #
     def asc
-      @ordering << {method: :sort!}
+      @descending = false
       self
     end
 
@@ -414,7 +423,79 @@ module Sortsmith
     #   # => Case-insensitive, reverse alphabetical
     #
     def desc
-      @ordering << {method: :reverse!}
+      @descending = true
+      self
+    end
+
+    ##
+    # Position nil values at the beginning of sort results.
+    #
+    # By default, nil values sort last (matching SQL/database conventions).
+    # This modifier overrides that behavior to place nils first, regardless
+    # of sort direction (asc/desc).
+    #
+    # The nil positioning is independent of asc/desc modifiers, meaning
+    # nil_first with desc will show nils first, then non-nil values in
+    # descending order.
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Basic nil_first usage
+    #   users = [
+    #     {name: "Bob"},
+    #     {name: nil},
+    #     {name: "Alice"}
+    #   ]
+    #   users.sort_by.dig(:name).nil_first.sort
+    #   # => [{name: nil}, {name: "Alice"}, {name: "Bob"}]
+    #
+    # @example Combining with desc
+    #   users.sort_by.dig(:name).nil_first.desc.sort
+    #   # => [{name: nil}, {name: "Bob"}, {name: "Alice"}]
+    #   # Nils first, then descending order
+    #
+    # @example With case modifiers
+    #   users.sort_by.dig(:name).insensitive.nil_first.sort
+    #   # => Case-insensitive sort with nils first
+    #
+    # @see #nil_last To explicitly position nils at the end
+    #
+    def nil_first
+      @nil_first = true
+      self
+    end
+
+    ##
+    # Position nil values at the end of sort results (explicit default).
+    #
+    # This is the default behavior, but can be used for explicitness or to
+    # override a previous nil_first call in a chain. Nil values will appear
+    # last regardless of sort direction (asc/desc).
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Explicit nil_last
+    #   users = [
+    #     {name: "Bob"},
+    #     {name: nil},
+    #     {name: "Alice"}
+    #   ]
+    #   users.sort_by.dig(:name).nil_last.sort
+    #   # => [{name: "Alice"}, {name: "Bob"}, {name: nil}]
+    #
+    # @example Overriding nil_first
+    #   users.sort_by.dig(:name).nil_first.nil_last.sort
+    #   # => Last setting wins: nils appear last
+    #
+    # @example With desc
+    #   users.sort_by.dig(:name).nil_last.desc.sort
+    #   # => [{name: "Bob"}, {name: "Alice"}, {name: nil}]
+    #   # Descending order, then nils last
+    #
+    # @see #nil_first To position nils at the beginning
+    #
+    def nil_last
+      @nil_first = false
       self
     end
 
@@ -439,11 +520,53 @@ module Sortsmith
     #   result = users.sort_by.dig(:name, indifferent: true).insensitive.desc.sort
     #
     def sort
-      # Apply all extraction and transformation steps during comparison
-      sorted = @input.sort { |a, b| apply_sorting(a, b) }
+      # Schwartzian Transform: extract once (O(n)), sort (O(n log n)), map back (O(n))
+
+      # Step 1: Pair each item with its extracted sort value
+      pairs = @input.map { |item| [extract_and_transform(item), item] }
+
+      # Step 2: Partition nils so we can use C-level sort_by on non-nil values
+      nil_pairs, non_nil_pairs = pairs.partition { |v, _| v.nil? }
+
+      # Step 3: Sort non-nil values using Ruby's native sort_by (runs in C)
+      begin
+        non_nil_pairs.sort_by! { |v, _| v }
+      rescue ArgumentError
+        # Re-raise with a more helpful error message
+        # Find the first pair of incomparable values for the message
+        non_nil_pairs.each_cons(2) do |(val_a, _), (val_b, _)|
+          result = val_a <=> val_b
+          next unless result.nil?
+
+          # <=> returned nil - incomparable types
+          raise ArgumentError, <<~ERROR
+            Cannot compare values during sort - the values are incomparable types.
+            This usually means your extraction returned mixed types or you're missing an extraction method.
+            Comparing:
+              #{val_a.inspect} (#{val_a.class})
+              <=>
+              #{val_b.inspect} (#{val_b.class})
+          ERROR
+        rescue ArgumentError
+          # <=> raised instead of returning nil
+          raise ArgumentError, <<~ERROR
+            Cannot compare values during sort - the <=> operator raised an exception.
+            This usually means the class doesn't implement <=>, has a buggy implementation, or you're missing an extraction method.
+            Comparing:
+              #{val_a.inspect} (#{val_a.class})
+              <=>
+              #{val_b.inspect} (#{val_b.class})
+          ERROR
+        end
+      end
+
+      non_nil_pairs.reverse! if @descending
+
+      # Step 4: Combine based on nil positioning
+      result = @nil_first ? nil_pairs.concat(non_nil_pairs) : non_nil_pairs.concat(nil_pairs)
 
-      # Apply any ordering transformations (like desc)
-      apply_ordering(sorted)
+      # Step 5: Strip the sort values, keeping only the original items
+      result.map! { |_, item| item }
     end
 
     ##
@@ -478,11 +601,8 @@ module Sortsmith
     #   result = users.sort_by.dig(:name).sort!.first(10)
     #
     def sort!
-      # Sort the original array in place
-      @input.sort! { |a, b| apply_sorting(a, b) }
-
-      # Apply any ordering transformations
-      apply_ordering(@input)
+      sorted = sort
+      @input.replace(sorted)
     end
 
     ##
@@ -626,27 +746,48 @@ module Sortsmith
     private
 
     ##
-    # Apply the complete pipeline of steps to two items for comparison.
+    # Extract and transform a single item through the full pipeline.
     #
-    # Iterates through all extraction and transformation steps in order,
-    # applying each one to both items in sequence. This creates the values
-    # that will be compared using Ruby's spaceship operator.
+    # Applies all extractors and modifiers to produce the final value
+    # that will be used for sorting comparisons.
     #
-    # @param item_a [Object] First item to compare
-    # @param item_b [Object] Second item to compare
-    # @return [Integer] Comparison result (-1, 0, 1)
+    # @param item [Object] The item to process
+    # @return [Object] The extracted and transformed value
     #
     # @api private
     #
-    def apply_sorting(item_a, item_b)
+    def extract_and_transform(item)
+      value = item
+
       @extractors.each do |extractor|
-        item_a, item_b = apply_extractor(extractor, item_a, item_b)
+        value = extract_value(value, **extractor)
       end
 
       @modifiers.each do |modifier|
-        item_a, item_b = apply_modifier(modifier, item_a, item_b)
+        value = modify_value(value, **modifier)
       end
 
+      value
+    end
+
+    ##
+    # Compare two extracted values according to nil positioning and sort direction.
+    #
+    # Handles nil values specially and applies the @descending flag to non-nil comparisons.
+    #
+    # @param item_a [Object] First value to compare
+    # @param item_b [Object] Second value to compare
+    # @return [Integer] Comparison result (-1, 0, 1)
+    #
+    # @api private
+    #
+    def compare_values(item_a, item_b)
+      # Handle nil values specially before comparison
+      # nil_first/nil_last positioning is absolute and not affected by asc/desc
+      return 0 if item_a.nil? && item_b.nil?
+      return @nil_first ? -1 : 1 if item_a.nil?
+      return @nil_first ? 1 : -1 if item_b.nil?
+
       # Final comparison using Ruby's spaceship operator
       result = item_a <=> item_b
 
@@ -661,46 +802,7 @@ module Sortsmith
           ERROR
       end
 
-      result
-    end
-
-    ##
-    # Apply ordering transformations to the sorted array.
-    #
-    # Executes any ordering steps (like desc) that affect the final
-    # arrangement of the sorted results. This happens after the sort
-    # comparison is complete.
-    #
-    # @param sorted [Array] The array to apply ordering to
-    # @return [Array] The array with ordering applied
-    #
-    # @api private
-    #
-    def apply_ordering(sorted)
-      @ordering.each { |step| sorted.public_send(step[:method]) }
-
-      sorted
-    end
-
-    ##
-    # Apply an extraction step to both comparison items.
-    #
-    # Extraction steps pull values out of objects (like hash keys or method calls)
-    # that will be used for comparison. When extraction fails, returns empty
-    # strings to preserve original ordering.
-    #
-    # @param extractor [Hash] Extraction step configuration
-    # @param item_a [Object] First item to extract from
-    # @param item_b [Object] Second item to extract from
-    # @return [Array<Object, Object>] Extracted values for comparison
-    #
-    # @api private
-    #
-    def apply_extractor(extractor, item_a, item_b)
-      item_a = extract_value(item_a, **extractor)
-      item_b = extract_value(item_b, **extractor)
-
-      [item_a, item_b]
+      @descending ? -result : result
     end
 
     ##
@@ -720,31 +822,10 @@ module Sortsmith
     # @api private
     #
     def extract_value(item, method:, positional: [], keyword: {}, before_extract: nil)
-      return "" unless item.respond_to?(method)
-
       item = before_extract.call(item) if before_extract
       item.public_send(method, *positional, **keyword)
-    end
-
-    ##
-    # Apply a modification step to both comparison items.
-    #
-    # Modification steps transform values for comparison (like case changes).
-    # Both items are processed with the same transformation to ensure
-    # consistent comparison behavior.
-    #
-    # @param modifier [Hash] Modification step configuration
-    # @param item_a [Object] First item to modify
-    # @param item_b [Object] Second item to modify
-    # @return [Array<Object, Object>] Modified values for comparison
-    #
-    # @api private
-    #
-    def apply_modifier(modifier, item_a, item_b)
-      item_a = modify_value(item_a, **modifier)
-      item_b = modify_value(item_b, **modifier)
-
-      [item_a, item_b]
+    rescue NoMethodError
+      ""
     end
 
     ##
@@ -763,9 +844,9 @@ module Sortsmith
     # @api private
     #
     def modify_value(item, method:, positional: [], keyword: {})
-      return item.to_s unless item.respond_to?(method)
-
       item.public_send(method, *positional, **keyword)
+    rescue NoMethodError
+      item.to_s
     end
   end
 end

data/lib/sortsmith/version.rb

@@ -4,5 +4,5 @@ module Sortsmith
   #
   # The current version of the Sortsmith gem
   #
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sortsmith
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-03 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies: []
 description: Sortsmith provides a flexible, chainable API for sorting Ruby collections.
   It supports sorting by object keys, methods, case sensitivity, and custom transformations.
@@ -25,6 +25,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmark/quick_benchmark.rb
+- benchmark/sorting_benchmark.rb
 - flake.lock
 - flake.nix
 - lib/sortsmith.rb