sortsmith 0.2.0 → 1.0.0

data/lib/sortsmith/sorter.rb

@@ -1,178 +1,771 @@
 # frozen_string_literal: true
 
 module Sortsmith
+  ##
+  # A chainable sorting interface that provides a fluent API for complex sorting operations.
+  #
+  # The Sorter class allows you to build sorting pipelines by chaining extractors,
+  # modifiers, and ordering methods before executing the sort with a terminator method.
+  # This creates readable, expressive sorting code that handles edge cases gracefully.
+  #
+  # @example Basic usage
+  #   users.sort_by.dig(:name).sort
+  #   # => sorted array by name
+  #
+  # @example Complex chaining
+  #   users.sort_by.dig(:name, indifferent: true).downcase.desc.sort
+  #   # => sorted by name (case-insensitive, descending, with indifferent key access)
+  #
+  # @example Method extraction
+  #   users.sort_by.method(:full_name).insensitive.sort
+  #   # => sorted by calling full_name method on each user
+  #
+  # @example Mixed key types
+  #   mixed_data = [
+  #     {name: "Bob"},      # symbol key
+  #     {"name" => "Alice"} # string key
+  #   ]
+  #   mixed_data.sort_by.dig(:name, indifferent: true).sort
+  #   # => handles both key types gracefully
+  #
+  # @example Handling missing methods gracefully
+  #   users.sort_by.method(:missing_email).sort
+  #   # => preserves original order when method doesn't exist
+  #
+  # @see Enumerable#sort_by The enhanced sort_by method
+  # @since 0.9.0
+  #
   class Sorter
+    ##
+    # Transformation proc for converting hash keys to symbols for indifferent access.
     #
-    # Creates a Sorter builder instance
+    # Used internally when the `indifferent: true` option is specified in {#dig}.
+    # This enables consistent key lookup across hashes with mixed symbol/string keys.
     #
-    # @param enumerable [Enumerable] The enumerable (Array, Hash) to sort
+    # @example Usage in indifferent access
+    #   mixed_hashes = [
+    #     {name: "Bob"},        # symbol key
+    #     {"name" => "Alice"}   # string key
+    #   ]
+    #   # Both will be accessed via :name after transformation
     #
-    def initialize(enumerable)
-      @enumerable = enumerable
-      @pipeline = []
-      @direction = :asc
-    end
+    # @return [Proc] A proc that transforms hash keys to symbols
+    # @api private
+    #
+    INDIFFERENT_KEYS_TRANSFORM = ->(item) { item.transform_keys(&:to_sym) }
 
+    ##
+    # List of enumerable methods that are delegated to the sorted result.
     #
-    # Finalizes the Sorter instance and sorts the enumerable
+    # These methods allow seamless chaining from sorting operations to common
+    # array operations without breaking the fluent interface. Each delegated
+    # method executes the sort pipeline first, then applies the requested
+    # operation to the sorted result.
     #
-    # @return [Enumerable] The sorted enumerable
+    # @example Delegated method usage
+    #   users.sort_by.dig(:score).desc.first(3)    # Get top 3 scores
+    #   users.sort_by.dig(:name).each { |u| puts u } # Iterate in sorted order
+    #   users.sort_by.dig(:age)[0..2]               # Array slice of sorted results
     #
-    def sort
-      filter_steps = select_filter_steps
-      transformation_steps = select_transformation_steps
-
-      result =
-        @enumerable.sort do |left, right|
-          filter_steps.each do |step|
-            left = step.perform(left)
-            right = step.perform(right)
-          end
+    # @since 1.0.0
+    # @api private
+    #
+    DELEGATED_METHODS = %i[first last take drop each map select [] size count length].freeze
 
-          left_priority = type_priority(left)
-          right_priority = type_priority(right)
+    ##
+    # Initialize a new Sorter instance.
+    #
+    # Creates a new chainable sorter for the given collection. Typically called
+    # automatically when using `collection.sort_by` without a block.
+    #
+    # @param input [Array, Enumerable] The collection to be sorted
+    #
+    # @example Direct instantiation (rarely needed)
+    #   sorter = Sortsmith::Sorter.new(users)
+    #   sorter.dig(:name).sort
+    #
+    # @example Typical usage (via sort_by)
+    #   users.sort_by.dig(:name).sort
+    #
+    def initialize(input)
+      @input = input
+      @extractors = []
+      @modifiers = []
+      @ordering = []
+    end
 
-          # Apply the transformation pipeline only for same-type comparisons
-          if left_priority == right_priority
-            left = apply_transformations(transformation_steps, left)
-            right = apply_transformations(transformation_steps, right)
+    ############################################################################
+    # Extractors
+    ############################################################################
 
-            left <=> right
-          else
-            left_priority <=> right_priority
-          end
-        end
+    ##
+    # Extract values from objects using hash keys or object methods.
+    #
+    # The workhorse method for value extraction. Works with hashes, structs,
+    # and any object that responds to the given identifiers. Supports nested
+    # digging with multiple arguments and handles mixed key types gracefully.
+    #
+    # When extracting from objects that don't respond to the specified keys/methods,
+    # returns an empty string to preserve the original ordering rather than causing
+    # comparison errors.
+    #
+    # @param identifiers [Array<Symbol, String, Integer>] Keys, method names, or indices to extract
+    # @param indifferent [Boolean] When true, normalizes hash keys to symbols for consistent lookup
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Hash key extraction
+    #   users.sort_by.dig(:name).sort
+    #
+    # @example Nested hash extraction
+    #   users.sort_by.dig(:profile, :email).sort
+    #
+    # @example Array index extraction
+    #   coordinates.sort_by.dig(0).sort  # sort by x-coordinate
+    #
+    # @example Mixed key types with indifferent access
+    #   mixed_data = [
+    #     {name: "Bob"},        # symbol key
+    #     {"name" => "Alice"}   # string key
+    #   ]
+    #   mixed_data.sort_by.dig(:name, indifferent: true).sort
+    #   # => Both key types work seamlessly
+    #
+    # @example Object method calls
+    #   users.sort_by.dig(:calculate_score).sort
+    #
+    # @example Graceful handling of missing keys
+    #   users.sort_by.dig(:missing_field).sort
+    #   # => Preserves original order instead of erroring
+    #
+    def dig(*identifiers, indifferent: false)
+      if indifferent
+        identifiers = identifiers.map(&:to_sym)
+        before_extract = INDIFFERENT_KEYS_TRANSFORM
+      end
 
-      (@direction == :asc) ? result : result.reverse
+      @extractors << {method: :dig, positional: identifiers, before_extract:}
+      self
     end
 
+    ##
+    # Alias for {#dig} - extracts values from objects using hash keys or object methods.
+    #
+    # Provides semantic clarity when working primarily with hash keys rather than
+    # nested structures or method calls.
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Key extraction
+    #   users.sort_by.key(:name).sort
+    #
+    # @see #dig The main extraction method
+    #
+    alias_method :key, :dig
+
+    ##
+    # Alias for {#dig} - extracts values from objects using hash keys or object methods.
+    #
+    # Provides semantic clarity when working with object fields or properties,
+    # making the sorting intent more explicit in business domain contexts.
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Field extraction
+    #   products.sort_by.field(:price).desc.sort
+    #
+    # @example Nested field extraction
+    #   users.sort_by.field(:profile, :email).sort
+    #
+    # @see #dig The main extraction method
+    #
+    alias_method :field, :dig
+
+    ##
+    # Extract values by calling methods on objects with optional arguments.
+    #
+    # Enables chainable sorting by calling methods on each object in the collection.
+    # Supports method calls with both positional and keyword arguments. When objects
+    # don't respond to the specified method, returns an empty string to preserve
+    # original ordering.
+    #
+    # This is particularly useful for custom objects, calculated values, or methods
+    # that require parameters.
+    #
+    # @param method_name [Symbol, String] The method name to call on each object
+    # @param positional [Array] Positional arguments to pass to the method
+    # @param keyword [Hash] Keyword arguments to pass to the method
     #
-    # Adds a "filter" step to the sort pipeline.
-    # Filter steps are used to get data from the current item being sorted
-    # These are performed before transformation steps
+    # @return [Sorter] Returns self for method chaining
     #
-    # @param & [Proc] The block to execute
+    # @example Basic method sorting
+    #   users.sort_by.method(:name).sort
     #
-    # @return [Self] The sorter instance
+    # @example Method with chainable modifiers
+    #   users.sort_by.method(:full_name).insensitive.desc.sort
     #
-    def add_filter(&)
-      add_step(type: Step::FILTER, &)
+    # @example Method with positional arguments
+    #   products.sort_by.method(:price_in, "USD").sort
+    #
+    # @example Method with keyword arguments
+    #   items.sort_by.method(:calculate_score, boost: 1.5).sort
+    #
+    # @example Complex method calls
+    #   reports.sort_by.method(:metric_for, :revenue, period: "Q1").desc.sort
+    #
+    # @example Graceful handling of missing methods
+    #   mixed_objects.sort_by.method(:priority).sort
+    #   # => Objects without :priority method maintain original order
+    #
+    def method(method_name, *positional, **keyword)
+      @extractors << {method: method_name, positional:, keyword:}
+      self
     end
 
+    ##
+    # Alias for {#method} - extracts values by calling methods on objects.
     #
-    # Adds a "transformation" step to the sort pipeline
-    # Transformation steps are used to transform data.
-    # These are performed after filter steps
+    # Provides semantic clarity when working with object attributes or properties,
+    # emphasizing that you're accessing object state rather than calling behavior.
     #
-    # @param & [Proc] The block to execute
+    # @return [Sorter] Returns self for method chaining
     #
-    # @return [Self] The sorter instance
+    # @example Attribute extraction
+    #   users.sort_by.attribute(:full_name).sort
     #
-    def add_transformation(&)
-      add_step(type: Step::TRANSFORMATION, &)
+    # @example With arguments
+    #   reports.sort_by.attribute(:score_for, "Q1").desc.sort
+    #
+    # @see #method The main method extraction feature
+    #
+    alias_method :attribute, :method
+
+    ##
+    # Universal extraction method that intelligently chooses the appropriate extraction strategy.
+    #
+    # This method serves as the smart dispatcher for value extraction, automatically detecting
+    # whether the input collection contains hash-like objects (that respond to `dig`) or
+    # regular objects (that need method calls). It provides a unified interface regardless
+    # of the underlying data structure.
+    #
+    # When `field` is nil, returns self without adding any extractors to the pipeline,
+    # allowing for graceful handling of dynamic field selection scenarios.
+    #
+    # @param field [Symbol, String, nil] The field name, hash key, or method name to extract
+    # @param positional [Array] Additional positional arguments passed to extraction
+    # @param keyword [Hash] Additional keyword arguments passed to extraction
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Hash extraction (uses dig internally)
+    #   users = [{ name: "Alice" }, { name: "Bob" }]
+    #   users.sort_by.extract(:name).sort
+    #
+    # @example Object method extraction (uses method internally)
+    #   User = Struct.new(:name, :score)
+    #   users = [User.new("Alice", 92), User.new("Bob", 78)]
+    #   users.sort_by.extract(:score).sort
+    #
+    # @example Indifferent key access
+    #   mixed_data = [{ name: "Alice" }, { "name" => "Bob" }]
+    #   mixed_data.sort_by.extract(:name, indifferent: true).sort
+    #
+    # @example Graceful nil handling
+    #   field_name = might_return_nil_from_api()
+    #   users.sort_by.extract(field_name).sort  # No extraction if field_name is nil
+    #
+    # @example Chaining with modifiers
+    #   users.sort_by.extract(:name).insensitive.desc.sort
+    #
+    # @see #dig Hash and nested structure extraction
+    # @see #method Object method extraction with arguments
+    # @since 1.0.0
+    #
+    def extract(field, *positional, **keyword)
+      return self if field.nil?
+
+      if @input.first.respond_to?(:dig)
+        dig(field, **keyword)
+      else
+        method(field, *positional, **keyword)
+      end
     end
 
+    ############################################################################
+    # Modifiers
+    ############################################################################
+
+    ##
+    # Transform extracted values to lowercase for comparison.
+    #
+    # Only affects values that respond to #downcase (typically strings).
+    # Non-string values are converted to strings first, ensuring consistent
+    # behavior across mixed data types.
+    #
+    # @return [Sorter] Returns self for method chaining
     #
-    # Instructs the sorter to perform a fetch by key on the Hash being sorted
+    # @example Case-insensitive string sorting
+    #   names = ["charlie", "Alice", "BOB"]
+    #   names.sort_by.downcase.sort
+    #   # => ["Alice", "BOB", "charlie"]
     #
-    # @param key [String, Symbol, Any] The hash key to fetch
+    # @example With hash extraction
+    #   users.sort_by.dig(:name).downcase.sort
     #
-    # @return [Self] The sorter instance
+    # @example Mixed data types
+    #   mixed = ["Apple", 42, "banana"]
+    #   mixed.sort_by.downcase.sort
+    #   # => [42, "Apple", "banana"] (42 becomes "42")
     #
-    def by_key(key)
-      add_filter { |i| i&.fetch(key) }
+    def downcase
+      @modifiers << {method: :downcase}
       self
     end
 
+    ##
+    # Alias for {#downcase} - provides case-insensitive sorting.
     #
-    # Instructs the sorter to perform a method call on the object being sorted
+    # Offers semantic clarity when the intent is case-insensitive comparison
+    # rather than specifically forcing lowercase.
     #
-    # @param method [String, Symbol] The method name to call
+    # @return [Sorter] Returns self for method chaining
     #
-    # @return [Self] The sorter instance
+    # @example Semantic case-insensitive sorting
+    #   users.sort_by.dig(:name).insensitive.sort
     #
-    def by_method(method)
-      add_filter { |i| i&.public_send(method) }
-    end
+    # @see #downcase The underlying transformation method
+    #
+    alias_method :insensitive, :downcase
 
-    alias_method :by_attribute, :by_method
+    ##
+    # Alias for {#downcase} - provides case-insensitive sorting.
+    #
+    # Offers explicit semantic clarity when the intent is case-insensitive comparison.
+    # More verbose than {#insensitive} but crystal clear about the behavior.
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    # @example Explicit case-insensitive sorting
+    #   users.sort_by.dig(:name).case_insensitive.sort
+    #
+    # @see #downcase The underlying transformation method
+    # @see #insensitive The shorter alias
+    #
+    alias_method :case_insensitive, :downcase
 
+    ##
+    # Transform extracted values to uppercase for comparison.
     #
-    # Instructs the sorter to sort by a case insensitive value
-    # This will prioritize capital letters first, followed by their lowercase counterparts
+    # Only affects values that respond to #upcase (typically strings).
+    # Non-string values are converted to strings first, ensuring consistent
+    # behavior across mixed data types.
     #
-    # @return [Self] The sorter instance
+    # @return [Sorter] Returns self for method chaining
     #
-    def case_insensitive
-      add_transformation do |item|
-        case item
-        when String
-          item.chars.flat_map { |c| [c.downcase, c] }
-        else
-          item
-        end
-      end
+    # @example Uppercase sorting
+    #   names.sort_by.upcase.sort
+    #
+    # @example With extraction
+    #   users.sort_by.dig(:department).upcase.desc.sort
+    #
+    def upcase
+      @modifiers << {method: :upcase}
+      self
     end
 
+    ############################################################################
+    # Ordering
+    ############################################################################
+
+    ##
+    # Sort in ascending order (default behavior).
+    #
+    # This is typically unnecessary as ascending is the default sort direction,
+    # but can be useful for explicit clarity or resetting direction after
+    # previous desc calls in a chain.
     #
-    # Controls which direction the array will be sorted
+    # @return [Sorter] Returns self for method chaining
     #
-    # @return [Self] The sorter instance
+    # @example Explicit ascending sort
+    #   users.sort_by.dig(:name).asc.sort
+    #
+    # @example Resetting after desc
+    #   users.sort_by.dig(:name).desc.asc.sort  # ends up ascending
     #
     def asc
-      @direction = :asc
+      @ordering << {method: :sort!}
       self
     end
 
-    alias_method :forward, :asc
-
+    ##
+    # Sort in descending order.
+    #
+    # Reverses the final sort order after all comparisons are complete.
+    # Can be chained with other modifiers and will apply to the final result.
     #
-    # Controls which direction the array will be sorted
+    # @return [Sorter] Returns self for method chaining
     #
-    # @return [Self] The sorter instance
+    # @example Descending sort
+    #   users.sort_by.dig(:age).desc.sort
+    #   # => Oldest users first
+    #
+    # @example With case modification
+    #   users.sort_by.dig(:name).insensitive.desc.sort
+    #   # => Case-insensitive, reverse alphabetical
     #
     def desc
-      @direction = :desc
+      @ordering << {method: :reverse!}
       self
     end
 
-    alias_method :reverse, :desc
+    ############################################################################
+    # Terminators
+    ############################################################################
 
-    private
+    ##
+    # Execute the sort pipeline and return a new sorted array.
+    #
+    # Applies all chained extraction, transformation, and ordering steps
+    # to produce the final sorted result. The original collection remains
+    # unchanged.
+    #
+    # @return [Array] A new array containing the sorted elements
+    #
+    # @example Basic termination
+    #   sorted_users = users.sort_by.dig(:name).sort
+    #   # original users array unchanged
+    #
+    # @example Complex pipeline
+    #   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) }
 
-    def add_step(type:, &block)
-      @pipeline << Step.new(type:, block:)
-      self
+      # Apply any ordering transformations (like desc)
+      apply_ordering(sorted)
+    end
+
+    ##
+    # Alias for {#sort} - returns a new sorted array.
+    #
+    # Provides semantic clarity when the intent is to convert the sorter
+    # pipeline to an array result.
+    #
+    # @return [Array] A new array containing the sorted elements
+    #
+    # @example Array conversion
+    #   result = users.sort_by.dig(:name).to_a
+    #
+    # @see #sort The main termination method
+    #
+    alias_method :to_a, :sort
+
+    ##
+    # Execute the sort pipeline and mutate the original array in place.
+    #
+    # Same as {#sort} but modifies the original array instead of creating a new one.
+    # Returns the mutated array for chaining. Use when memory efficiency is
+    # important and you don't need to preserve the original order.
+    #
+    # @return [Array] The original array, now sorted
+    #
+    # @example In-place sorting
+    #   users.sort_by.dig(:name).sort!
+    #   # users array is now modified
+    #
+    # @example Chaining after mutation
+    #   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)
     end
 
-    def select_filter_steps
-      @pipeline.select { |s| s.type == Step::FILTER }
+    ##
+    # Alias for {#sort!} - execute sort pipeline and mutate original array.
+    #
+    # Provides semantic clarity when the intent is to convert the sorter
+    # pipeline to an array while modifying the original collection in place.
+    #
+    # @return [Array] The original array, now sorted
+    #
+    # @example In-place array conversion
+    #   users.sort_by.dig(:name).to_a!
+    #   # users array is now sorted by name
+    #
+    # @see #sort! The main in-place sorting method
+    #
+    alias_method :to_a!, :sort!
+
+    ##
+    # Shorthand for adding desc and executing sort.
+    #
+    # Equivalent to calling `.desc.sort` but more concise and expressive.
+    # Useful when you know you want descending order and don't need other
+    # modifiers.
+    #
+    # @return [Array] A new array sorted in descending order
+    #
+    # @example Reverse sorting
+    #   users.sort_by.dig(:created_at).reverse
+    #   # => Newest users first
+    #
+    # @example Equivalent to
+    #   users.sort_by.dig(:created_at).desc.sort
+    #
+    def reverse
+      desc.sort
     end
 
-    def select_transformation_steps
-      @pipeline.select { |s| s.type == Step::TRANSFORMATION }
+    ##
+    # Shorthand for adding desc and executing sort!.
+    #
+    # Equivalent to calling `.desc.sort!` but more concise. Mutates the
+    # original array and returns it in descending order.
+    #
+    # @return [Array] The original array, sorted in descending order
+    #
+    # @example In-place reverse sorting
+    #   users.sort_by.dig(:score).reverse!
+    #
+    def reverse!
+      desc.sort!
     end
 
-    def type_priority(value)
-      case value
-      when NilClass then 0
-      when Numeric then 1
-      when String then 2
-      when Array then 3
-      when Hash then 4
-      else
-        5
+    ## The following methods are automatically generated and delegate to the sorted array:
+    #
+    # @!method first(n = 1)
+    #   Get the first n elements from the sorted result
+    #   @param n [Integer] Number of elements to return
+    #   @return [Object, Array] Single element if n=1, array otherwise
+    #   @example
+    #     users.sort_by.dig(:score).desc.first    # Highest scoring user
+    #     users.sort_by.dig(:name).first(3)       # First 3 alphabetically
+    #
+    # @!method last(n = 1)
+    #   Get the last n elements from the sorted result
+    #   @param n [Integer] Number of elements to return
+    #   @return [Object, Array] Single element if n=1, array otherwise
+    #   @example
+    #     users.sort_by.dig(:age).last            # Oldest user
+    #     users.sort_by.dig(:score).last(2)       # Bottom 2 scores
+    #
+    # @!method take(n)
+    #   Take the first n elements from the sorted result
+    #   @param n [Integer] Number of elements to take
+    #   @return [Array] Array with up to n elements
+    #   @example
+    #     users.sort_by.dig(:score).desc.take(5)  # Top 5 users
+    #
+    # @!method drop(n)
+    #   Drop the first n elements from the sorted result
+    #   @param n [Integer] Number of elements to drop
+    #   @return [Array] Array with remaining elements
+    #   @example
+    #     users.sort_by.dig(:score).drop(3)       # All except top 3
+    #
+    # @!method each(&block)
+    #   Iterate over the sorted result
+    #   @yield [Object] Each element in sorted order
+    #   @return [Array, Enumerator] Sorted array if block given, enumerator otherwise
+    #   @example
+    #     users.sort_by.dig(:name).each { |user| puts user[:email] }
+    #
+    # @!method map(&block)
+    #   Transform each element of the sorted result
+    #   @yield [Object] Each element in sorted order
+    #   @return [Array, Enumerator] Transformed array if block given, enumerator otherwise
+    #   @example
+    #     users.sort_by.dig(:name).map(&:upcase)
+    #
+    # @!method select(&block)
+    #   Filter the sorted result
+    #   @yield [Object] Each element in sorted order
+    #   @return [Array, Enumerator] Filtered array if block given, enumerator otherwise
+    #   @example
+    #     users.sort_by.dig(:score).select { |u| u[:active] }
+    #
+    # @!method [](index)
+    #   Access elements by index in the sorted result
+    #   @param index [Integer, Range] Index or range to access
+    #   @return [Object, Array] Element(s) at the specified index/range
+    #   @example
+    #     users.sort_by.dig(:score).desc[0]      # Highest scoring user
+    #     users.sort_by.dig(:name)[1..3]         # Users 2-4 alphabetically
+    #
+    # @!method size
+    #   Get the number of elements in the sorted result
+    #   @return [Integer] Number of elements
+    #   @example
+    #     users.sort_by.dig(:name).size
+    #
+    # @!method count(&block)
+    #   Count elements in the sorted result, optionally with a condition
+    #   @yield [Object] Each element for conditional counting
+    #   @return [Integer] Count of elements
+    #   @example
+    #     users.sort_by.dig(:name).count                    # Total count
+    #     users.sort_by.dig(:score).count { |u| u[:active] } # Count active users
+    #
+    # @!method length
+    #   Get the number of elements in the sorted result (alias for size)
+    #   @return [Integer] Number of elements
+    #   @example
+    #     users.sort_by.dig(:name).length
+    #
+    DELEGATED_METHODS.each do |method_name|
+      define_method(method_name) do |*args, &block|
+        to_a.public_send(method_name, *args, &block)
       end
     end
 
-    def apply_transformations(steps, value)
-      result = value
+    private
+
+    ##
+    # Apply the complete pipeline of steps to two items for comparison.
+    #
+    # 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.
+    #
+    # @param item_a [Object] First item to compare
+    # @param item_b [Object] Second item to compare
+    # @return [Integer] Comparison result (-1, 0, 1)
+    #
+    # @api private
+    #
+    def apply_sorting(item_a, item_b)
+      @extractors.each do |extractor|
+        item_a, item_b = apply_extractor(extractor, item_a, item_b)
+      end
 
-      steps.each do |step|
-        result = step.perform(result)
+      @modifiers.each do |modifier|
+        item_a, item_b = apply_modifier(modifier, item_a, item_b)
+      end
+
+      # Final comparison using Ruby's spaceship operator
+      result = item_a <=> item_b
+
+      if result.nil?
+        raise ArgumentError,
+          <<~ERROR
+            Cannot compare values during sort - this usually means your extraction returned incomparable types or you're missing an extraction method.
+            Comparing:
+              #{item_a.inspect} (#{item_a.class})
+              <=>
+              #{item_b.inspect} (#{item_b.class})
+          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]
+    end
+
+    ##
+    # Extract a value from an object by invoking a specified method.
+    #
+    # Handles extraction with optional arguments and preprocessing. When the
+    # object doesn't respond to the method, returns an empty string to maintain
+    # original ordering rather than causing comparison failures.
+    #
+    # @param item [Object] The object from which to extract the value
+    # @param method [Symbol, String] The method to call on the object
+    # @param positional [Array] Optional positional arguments to pass to the method
+    # @param keyword [Hash] Optional keyword arguments to pass to the method
+    # @param before_extract [Proc, nil] Optional proc to preprocess the item before extraction
+    # @return [Object, String] The result of the method call, or empty string if method unavailable
+    #
+    # @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]
+    end
+
+    ##
+    # Modify a value using a specified transformation method.
+    #
+    # Applies transformations like case changes to values. When the value
+    # doesn't respond to the transformation method, converts it to a string
+    # first to enable string operations on non-string types.
+    #
+    # @param item [Object] The value to modify
+    # @param method [Symbol, String] The transformation method to apply
+    # @param positional [Array] Optional positional arguments
+    # @param keyword [Hash] Optional keyword arguments
+    # @return [Object] The transformed value
+    #
+    # @api private
+    #
+    def modify_value(item, method:, positional: [], keyword: {})
+      return item.to_s unless item.respond_to?(method)
+
+      item.public_send(method, *positional, **keyword)
+    end
   end
 end