sortsmith 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2145a4f96e357b7c580dd3bbd5c672120788c422d76737fcf7015539ace75c7
-  data.tar.gz: 80376b95b0cb7cee7a0b741a69d90a91307384623007b63384a1551871fdb2d5
+  metadata.gz: 16b369873631fe1de4c59f32bbbf5fbdb383ee1b3924a864ccd11a2ac6c4f1d5
+  data.tar.gz: cb329eecad62b7cf05e13624258fc09dd4a21e0aab192e50774a8e2a6c6beed3
 SHA512:
-  metadata.gz: 5de79e4da81b5dbf9096a9c0cbf21dd6c00500a89b8fcec679b3116b324864b3b70bf8d8e4759069412dc0979eeadbe5e3a05e8da28016ea2638de7ab8fbc54a
-  data.tar.gz: 1e7270386a18f165954b41810143d89920f66195f311826a19f4465a60c8865cbf3dd9e0de29cc7408d9bd41cbac43f8803030aa5724bc64e0e63f96e077f456
+  metadata.gz: e3ada898d22d88aabe5c314dc67ac35dced713ec5f7bced55ec4ca87d12f10cd62b9fe218d6acb45831d9ec62734917d72c5343dce56b15bace088b23188bc95
+  data.tar.gz: e362605cde0d51b9eb63ef435e69cf13d91651ff2a9ba22dfe07a8cdd1e33c9c8bb0ce695c0914bfb3579226a3306c2d4d03f029752c25f8b17dbff22133fb1d

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,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 ### Removed
+-->
+
+## [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 +64,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 +92,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 +100,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 +120,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 +171,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 +185,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/v0.9.0...HEAD
+[unreleased]: https://github.com/itsthedevman/sortsmith/compare/v1.0.0...HEAD
+[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.
@@ -14,7 +14,7 @@ users.sort_by { |user| user[:name].downcase }.reverse
 users.sort_by.dig(: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
 
@@ -55,12 +55,12 @@ users.sort_by.dig(:name, indifferent: true).insensitive.desc.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
 - **Minimal overhead** - Extends existing Ruby methods without breaking compatibility
-- **Tab-completable** - Discoverable API through your editor
 
 ## Installation
 
@@ -84,17 +84,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 (NEW!)
 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 +104,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 (NEW!)
+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 +117,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 +130,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 +146,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
-```
-
-### Hash Collections
+# Clean and direct for common operations
+words = ["elephant", "cat", "butterfly"]
+words.sort_by(:length).desc.sort
+# => ["butterfly", "elephant", "cat"]
 
-```ruby
+# Works great with hashes
 users = [
-  { name: "Charlie", score: 85, team: "red" },
-  { name: "Alice", score: 92, team: "blue" },
-  { name: "bob", score: 78, team: "red" }
-]
-
-# 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" } } }
+  { name: "Cat", score: 99 },
+  { name: "Charlie", score: 85 },
+  { name: "karen", score: 50 },
+  { name: "Alice", score: 92 },
+  { name: "bob", score: 78 },
 ]
 
-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 +179,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 +265,26 @@ api_response.sort_by.dig(:name, indifferent: true).sort
 
 ## API Reference
 
+### Universal Extraction
+
+- **`sort_by(field, **opts)`\*\* - Direct field extraction (NEW!)
+  - 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 (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!)
 
 ### 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!)
 
 ### Ordering
 
@@ -273,33 +296,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!` (NEW!)
 - **`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:
-
-```ruby
-# v0.2.x (OLD - no longer works)
-Sortsmith::Sorter.new(users).by_key(:name).case_insensitive.desc.sort
+### Delegated Enumerable Methods (NEW!)
 
-# v0.3.x (NEW)
-users.sort_by.dig(:name).insensitive.desc.sort
+The following methods execute the sort and delegate to the resulting array:
 
-# v0.2.x (OLD)
-Sortsmith::Sorter.new(objects).by_method(:calculate_score).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.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 +328,13 @@ objects.sort_by.dig(:calculate_score).sort
 ### Setting Up the Development Environment
 
 With Nix:
+
 ```bash
 direnv allow
 ```
 
 Without Nix:
+
 ```bash
 bundle install
 ```

data/flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1736798957,
-        "narHash": "sha256-qwpCtZhSsSNQtK4xYGzMiyEDhkNzOCz/Vfu4oL2ETsQ=",
+        "lastModified": 1751792365,
+        "narHash": "sha256-J1kI6oAj25IG4EdVlg2hQz8NZTBNYvIS0l4wpr9KcUo=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9abb87b552b7f55ac8916b6fc9e5cb486656a2f3",
+        "rev": "1fd8bada0b6117e6c7eb54aad5813023eed37ccb",
         "type": "github"
       },
       "original": {

data/lib/sortsmith/core_ext/enumerable.rb

@@ -33,43 +33,77 @@ module Enumerable
   alias_method :og_sort_by, :sort_by
 
   ##
-  # Enhanced sort_by that supports both traditional block usage and chainable API.
+  # Enhanced sort_by that supports both traditional block usage and direct field extraction.
   #
-  # When called with a block, behaves exactly like Ruby's original `sort_by`.
-  # When called without a block, returns a {Sortsmith::Sorter} instance that
-  # provides a chainable interface for complex sorting operations.
+  # This method extends Ruby's built-in `sort_by` to provide a fluent, chainable API
+  # for sorting operations. When called with a block, it behaves exactly like the
+  # original `sort_by`. When called without a block, it returns a {Sortsmith::Sorter}
+  # instance for method chaining.
   #
-  # This dual behavior ensures complete backward compatibility while unlocking
-  # powerful new sorting capabilities.
+  # The direct syntax (`sort_by(field)`) provides a concise way to sort by a specific
+  # field or method without verbose chaining, making simple sorting operations more
+  # readable and intuitive.
   #
+  # @param field [Symbol, String, nil] Optional field name for direct extraction
+  # @param positional [Array] Additional positional arguments for extraction
+  # @param keyword [Hash] Additional keyword arguments for extraction
   # @param block [Proc, nil] Optional block for traditional sort_by behavior
-  # @return [Array, Sortsmith::Sorter] Array when block given, Sorter when block nil
   #
-  # @example Traditional usage (unchanged)
+  # @return [Array, Sortsmith::Sorter] Array when block given, Sorter instance otherwise
+  #
+  # @example Traditional block usage (unchanged)
   #   users.sort_by { |user| user.name.downcase }
   #   # => sorted array
   #
-  # @example Chainable usage (new)
-  #   users.sort_by.dig(:name).downcase.desc.sort
+  # @example Direct field syntax (new)
+  #   users.sort_by(:name).insensitive.sort
   #   # => sorted array via method chaining
   #
-  # @example Mixed key types with indifferent access
+  # @example Direct syntax with immediate result
+  #   users.sort_by(:score).desc.first(3)
+  #   # => top 3 users by score
+  #
+  # @example Chainable interface without field
+  #   users.sort_by.dig(:profile, :email).sort
+  #   # => sorted by nested email field
+  #
+  # @example Mixed key types
   #   mixed_data = [
   #     { name: "Bob" },        # symbol key
   #     { "name" => "Alice" }   # string key
   #   ]
-  #   mixed_data.sort_by.dig(:name, indifferent: true).sort
+  #   mixed_data.sort_by(:name, indifferent: true).sort
   #   # => handles both key types gracefully
   #
-  # @see Sortsmith::Sorter#dig
-  # @see Sortsmith::Sorter#sort
-  # @see #og_sort_by Original sort_by behavior
+  # @example Object method sorting
+  #   products.sort_by(:calculate_price).desc.sort
+  #   # => sorted by calculated price method
+  #
+  # @example Dynamic field selection
+  #   sort_field = params[:sort_by]  # might be nil
+  #   users.sort_by(sort_field).sort
+  #   # => gracefully handles nil field
   #
-  # @since 0.1.0
+  # @example Integration with enumerable methods
+  #   users.sort_by(:created_at).desc.take(10)
+  #   # => newest 10 users without breaking the chain
   #
-  def sort_by(&block)
-    return Sortsmith::Sorter.new(self) if block.nil?
+  # @raise [ArgumentError] When extraction results in incomparable types
+  #
+  # @note This method maintains full backward compatibility with Ruby's original sort_by
+  # @note When field is nil, returns a plain Sorter instance for manual chaining
+  #
+  # @see Sortsmith::Sorter The chainable sorting interface
+  # @see #extract Universal extraction method
+  # @see Enumerable#sort_by Original Ruby method (aliased as og_sort_by)
+  # @since 1.0.0
+  #
+  def sort_by(field = nil, *positional, **keyword, &block)
+    return og_sort_by(&block) if block
+
+    sorter = Sortsmith::Sorter.new(self)
+    return sorter if field.nil?
 
-    og_sort_by(&block)
+    sorter.extract(field, *positional, **keyword)
   end
 end