sortsmith 0.2.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5b3aee0492a9a38de3999f07444c05e0e7ad00c86c3c3f6a87be19151e5b23
-  data.tar.gz: e3a1f4497ffc436f56ee881e58086e23dc0009357e1bfe3cd9393dc4642162de
+  metadata.gz: a2145a4f96e357b7c580dd3bbd5c672120788c422d76737fcf7015539ace75c7
+  data.tar.gz: 80376b95b0cb7cee7a0b741a69d90a91307384623007b63384a1551871fdb2d5
 SHA512:
-  metadata.gz: 64d378b0764c272de8ba01a1230ef7457ea36627712c5c38f1531b9d57e1ca44e2627bb880aeede760f0bfc168cfdffccea8d1b3577e07daa8fe64181e3cb8cd
-  data.tar.gz: 373dea1996fbe61a6c2e0cf3095c761b4b388f52932e78e8e43f1d3e7cac696d949ecf2233cd4f8d89c77cd1133c9aa6b2e84d40fc0e9c70d7e5795b5e65b84a
+  metadata.gz: 5de79e4da81b5dbf9096a9c0cbf21dd6c00500a89b8fcec679b3116b324864b3b70bf8d8e4759069412dc0979eeadbe5e3a05e8da28016ea2638de7ab8fbc54a
+  data.tar.gz: 1e7270386a18f165954b41810143d89920f66195f311826a19f4465a60c8865cbf3dd9e0de29cc7408d9bd41cbac43f8803030aa5724bc64e0e63f96e077f456

data/CHANGELOG.md

@@ -13,6 +13,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.9.0] - 12025-07-06
+
+### 🎉 MAJOR REWRITE: Fluent Chainable API
+
+**BREAKING CHANGES**: Complete API redesign introducing a fluent, chainable interface. See migration guide below.
+
+**Pre-1.0 Notice**: This release represents our new stable API design, but we're seeking community feedback before locking in 1.0.0 compatibility guarantees.
+
+### 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`
+- `reverse!` - Shorthand for `desc.sort!`
+- `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
+
+### 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
+
+### 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`)
+- `Sortsmith::Step` class (internal restructure)
+- Manual `Sorter.new()` instantiation requirement
+- `rbs` and `steep` type checking
+
+### Migration Guide
+
+The new API is more concise and intuitive, but requires updating existing code:
+
+```ruby
+# v0.2.x (OLD)
+Sortsmith::Sorter.new(users).by_key(:name).case_insensitive.desc.sort
+
+# v0.9.x (NEW)
+users.sort_by.dig(:name).insensitive.desc.sort
+
+# v0.2.x (OLD)
+Sortsmith::Sorter.new(objects).by_method(:calculate_score).sort
+
+# v0.9.x (NEW)
+objects.sort_by.dig(:calculate_score).sort
+```
+
+### Technical Improvements
+
+- Complete test suite rewrite with comprehensive edge case coverage
+- Enhanced error handling for mixed data types
+- Improved performance through reduced object allocations
+- Cleaner internal architecture with separation of concerns
+- Better documentation with extensive API examples
+
 ## [0.2.0] - 12025-02-17
 
 ### Added
@@ -42,7 +134,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Type checking with Steep/RBS
 - GitHub Actions workflow for automated testing and type checking
 
-[unreleased]: https://github.com/itsthedevman/sortsmith/compare/v0.2.0...HEAD
+[unreleased]: https://github.com/itsthedevman/sortsmith/compare/v0.9.0...HEAD
+[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
 [0.1.0]: https://github.com/itsthedevman/sortsmith/compare/ac357965a1bc641d187333a5b032c5a423020ae9...v0.1.0

data/README.md

@@ -1,17 +1,66 @@
 # 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)
 [![Tests](https://github.com/itsthedevman/sortsmith/actions/workflows/main.yml/badge.svg)](https://github.com/itsthedevman/sortsmith/actions/workflows/main.yml)
-![Ruby Version](https://img.shields.io/badge/ruby-3.3.6-ruby)
 
-Sortsmith is a flexible sorting library for Ruby that makes complex sorting operations simple and composable. It makes handling common sorting patterns like case-insensitive sorting of hashes and objects easy, while remaining extensible for custom sorting needs.
+**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.
 
-## Features
+```ruby
+# Instead of this...
+users.sort_by { |user| user[:name].downcase }.reverse
+
+# Write this!
+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.
+
+## Table of Contents
+
+- [Why Sortsmith?](#why-sortsmith)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Usage Examples](#usage-examples)
+  - [Array Sorting](#array-sorting)
+  - [Hash Collections](#hash-collections)
+  - [Object Collections](#object-collections)
+  - [Mixed Key Types](#mixed-key-types)
+- [API Reference](#api-reference)
+- [Migration from v0.2.x](#migration-from-v02x)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why Sortsmith?
+
+Ruby's `sort_by` is powerful, but real-world sorting often gets messy:
+
+```ruby
+# Sorting users by name, case-insensitive, descending
+users.sort_by { |u| u[:name].to_s.downcase }.reverse
 
-- Builder pattern for chainable sorting configuration
-- Built-in support for case-insensitive sorting
-- Hash key and method/attribute sorting
-- Flexible transformation pipeline
+# What if some names are nil?
+users.sort_by { |u| (u[:name] || "").downcase }.reverse
+
+# What about mixed string/symbol keys?
+users.sort_by { |u| (u[:name] || u["name"] || "").downcase }.reverse
+```
+
+Sortsmith handles all the edge cases and gives you a clean, readable API:
+
+```ruby
+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
 
@@ -33,89 +82,229 @@ Or install it yourself as:
 $ gem install sortsmith
 ```
 
-## Usage
+## Quick Start
 
-### Basic Sorting
+Sortsmith extends Ruby's `sort_by` method. When called without a block, it returns a chainable sorter:
 
 ```ruby
-# Sort an array of Strings
-users = ["Bob", "Alice", "Carol"]
+require "sortsmith"
 
-sorted_users = Sortsmith::Sorter.new(users).sort
+# Basic string sorting
+names = ["charlie", "Alice", "bob"]
+names.sort_by.insensitive.sort
+# => ["Alice", "bob", "charlie"]
 
-# Result: ["Alice", "Bob", "Carol"]
+# Hash sorting
+users = [
+  { name: "Charlie", age: 25 },
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 20 }
+]
+
+users.sort_by.dig(:name).sort
+# => [{ name: "Alice", age: 30 }, { name: "Bob", age: 20 }, { 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 }]
+```
+
+## Core Concepts
+
+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**
+
+```ruby
+collection.sort_by.dig(:field).downcase.desc.sort
+#          ↑       ↑           ↑        ↑    ↑
+#          |    extract   transform  order execute
+#       chainable  (opt)      (opt)   (opt) (required)
+```
+
+**Minimal example:**
+```ruby
+# This works! (though not particularly useful)
+users.sort_by.sort  # Same as users.sort
+
+# More practical examples
+users.sort_by.dig(:name).sort           # Extract only
+users.sort_by.downcase.sort             # Transform only
+users.sort_by.desc.sort                 # Order only
+users.sort_by.dig(:name).desc.sort      # Extract + order
 ```
 
-### Hash Sorting
+Each step builds on the previous ones, so you can mix and match based on what your data needs. The only requirement is ending with a terminator to actually execute the sort.
+
+## Usage Examples
+
+### Array Sorting
+
+```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
 
 ```ruby
-# Sort an array of hashes by a key
 users = [
-  { name: "Carol", age: 35 },
-  { name: "Bob", age: 25 },
-  { name: "Alice", age: 30 }
+  { name: "Charlie", score: 85, team: "red" },
+  { name: "Alice", score: 92, team: "blue" },
+  { name: "bob", score: 78, team: "red" }
 ]
 
-sorted_users = Sortsmith::Sorter.new(users)
-  .by_key(:name)
-  .sort
+# 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" }]
 
-# Result: [{ name: "Alice" }, { name: "Bob" }, { name: "Carol" }]
+# 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" } } }, ...]
 ```
 
-### Object Sorting
+### Object Collections
 
 ```ruby
-# Sort objects by method/attribute
-class User < Data.define(:name)
-end
+User = Struct.new(:name, :age, :city)
+
+users = [
+  User.new("Charlie", 25, "NYC"),
+  User.new("Alice", 30, "LA"),
+  User.new("bob", 20, "Chicago")
+]
 
-users = [User.new(name: "Bob"), User.new(name: "Carol"), User.new(name: "Alice")]
+# Sort by any method/attribute
+users.sort_by.dig(:name).insensitive.sort
+# => [User.new("Alice"), User.new("bob"), User.new("Charlie")]
 
-sorted_users = Sortsmith::Sorter.new(users)
-  .by_method(:name)
-  .sort
+users.sort_by.dig(:age).reverse
+# => [User.new("Alice", 30), User.new("Charlie", 25), User.new("bob", 20)]
 
-# Result: [#<data User name="Alice">, #<data User name="Bob">, #<data User name="Carol">]
+# Works with any object that responds to the method
+class Score
+  def calculate; rand(100); end
+end
+
+scores = [Score.new, Score.new, Score.new]
+scores.sort_by.dig(:calculate).desc.sort
 ```
 
-### Case Insensitive Sorting
+### Mixed Key Types
+
+Real-world data often has inconsistent key types. Sortsmith handles this gracefully:
 
 ```ruby
-users = [
-  {"name" => "bob"},
-  {"name" => "Billy"},
-  {"name" => "Alice"},
-  {"name" => "carol"},
-  {"name" => "Cassidy"},
-  {"name" => "alex"}
+mixed_users = [
+  { name: "Charlie" },        # symbol key
+  { "name" => "Alice" },      # string key
+  { :name => "Bob" },         # symbol key again
+  { "name" => "Diana" }       # string key again
 ]
 
-# Order of methods does not matter
-# However, the hash's key type does
-sorted_users = Sortsmith::Sorter.new(users)
-    .case_insensitive
-    .by_key("name")
-    .sort
+# The indifferent option handles both key types
+mixed_users.sort_by.dig(:name, indifferent: true).sort
+# => [{ "name" => "Alice" }, { :name => "Bob" }, { name: "Charlie" }, { "name" => "Diana" }]
 
-# Result: [{"name"=>"Alice"}, {"name"=>"alex"}, {"name"=>"Billy"}, {"name"=>"bob"}, {"name"=>"Cassidy"}, {"name"=>"carol"}]
+# Without indifferent access, you'd get sorting failures or unexpected results
 ```
 
-### Reverse Sorting
+**Performance Note**: Indifferent key access adds modest overhead (~2x slower depending on the machine) but operates in microseconds and is typically worth the convenience for mixed-key scenarios.
 
 ```ruby
-# Sort in descending order
-sorted_desc = Sortsmith::Sorter.new(array)
-  .by_attribute(:name)
-  .desc
-  .sort
+# Rails users can also normalize keys upfront for better performance
+mixed_users.map(&:symbolize_keys).sort_by.dig(:name).sort
+
+# But indifferent access is handy when you can't control the data source
+api_response.sort_by.dig(:name, indifferent: true).sort
 ```
 
+## API Reference
+
+### 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
+
+### Modifiers
+
+- **`downcase`** - Convert extracted strings to lowercase for comparison
+- **`upcase`** - Convert extracted strings to uppercase for comparison
+- **`insensitive`** - Alias for `downcase` (semantic clarity)
+
+### Ordering
+
+- **`asc`** - Sort in ascending order (default)
+- **`desc`** - Sort in descending order
+
+### Terminators
+
+- **`sort`** - Execute sort and return new array
+- **`sort!`** - Execute sort and mutate original array
+- **`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:
+
+```ruby
+# v0.2.x (OLD - no longer works)
+Sortsmith::Sorter.new(users).by_key(:name).case_insensitive.desc.sort
+
+# v0.3.x (NEW)
+users.sort_by.dig(:name).insensitive.desc.sort
+
+# v0.2.x (OLD)
+Sortsmith::Sorter.new(objects).by_method(:calculate_score).sort
+
+# v0.3.x (NEW)
+objects.sort_by.dig(:calculate_score).sort
+```
+
+**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
 
-- Ruby 3.3.6
+- Ruby 3.0+
 - Nix with Direnv (optional, but recommended)
 
 ### Setting Up the Development Environment
@@ -136,12 +325,6 @@ bundle install
 bundle exec rake test
 ```
 
-### Type Checking
-
-```bash
-bundle exec steep check
-```
-
 ### Code Style
 
 This project uses StandardRB. To check your code:
@@ -168,7 +351,7 @@ Please note that this project is released with a [Contributor Code of Conduct](C
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.md).
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
 
 ## Changelog
 
@@ -177,3 +360,9 @@ See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
 ## Credits
 
 - Author: Bryan "itsthedevman"
+
+## Looking for a Software Engineer?
+
+I'm currently looking for opportunities where I can tackle meaningful problems and help build reliable software while mentoring the next generation of developers. If you're looking for a senior engineer with full-stack Rails expertise and a passion for clean, maintainable code, let's talk!
+
+[bryan@itsthedevman.com](mailto:bryan@itsthedevman.com)

data/flake.nix

@@ -1,21 +1,27 @@
 {
-  description = "Ruby 3.4 development environment";
+  description = "Ruby 3.2 development environment";
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
       in
       {
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
-            (ruby_3_4.override {
-              jemallocSupport = true;
+            (ruby_3_2.override {
+              jemallocSupport = false;
               docSupport = false;
             })
 

data/lib/sortsmith/core_ext/enumerable.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+##
+# Extensions to Ruby's built-in Enumerable module.
+#
+# Sortsmith extends {Enumerable} to provide enhanced sorting capabilities
+# while preserving the original behavior when used with blocks.
+#
+# The key enhancement is allowing `sort_by` to be called without a block,
+# which returns a {Sortsmith::Sorter} instance for method chaining.
+#
+# @example Original behavior (unchanged)
+#   [1, 2, 3].sort_by { |n| -n }
+#   # => [3, 2, 1]
+#
+# @example New chainable behavior
+#   users.sort_by.dig(:name).downcase.sort
+#   # => Returns Sorter instance for chaining
+#
+# @see Sortsmith::Sorter The chainable sorting interface
+#
+module Enumerable
+  ##
+  # Stores the original sort_by method before extension.
+  #
+  # This alias preserves Ruby's original `sort_by` behavior, allowing
+  # Sortsmith to enhance the method while maintaining full backward
+  # compatibility when blocks are provided.
+  #
+  # @see #sort_by The enhanced version
+  # @api private
+  #
+  alias_method :og_sort_by, :sort_by
+
+  ##
+  # Enhanced sort_by that supports both traditional block usage and chainable API.
+  #
+  # 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 dual behavior ensures complete backward compatibility while unlocking
+  # powerful new sorting capabilities.
+  #
+  # @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)
+  #   users.sort_by { |user| user.name.downcase }
+  #   # => sorted array
+  #
+  # @example Chainable usage (new)
+  #   users.sort_by.dig(:name).downcase.desc.sort
+  #   # => sorted array via method chaining
+  #
+  # @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
+  #   # => handles both key types gracefully
+  #
+  # @see Sortsmith::Sorter#dig
+  # @see Sortsmith::Sorter#sort
+  # @see #og_sort_by Original sort_by behavior
+  #
+  # @since 0.1.0
+  #
+  def sort_by(&block)
+    return Sortsmith::Sorter.new(self) if block.nil?
+
+    og_sort_by(&block)
+  end
+end

data/lib/sortsmith/sorter.rb

@@ -1,178 +1,317 @@
 # 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.
+  #
+  # @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 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
+  #
   class Sorter
+    ##
+    # Initialize a new Sorter instance
     #
-    # Creates a Sorter builder instance
+    # @param input [Array, Enumerable] The collection to be sorted
+    def initialize(input)
+      @input = input
+      @extractors = []
+      @modifiers = []
+      @ordering = []
+    end
+
+    ############################################################################
+    # Extractors
+    ############################################################################
+
+    ##
+    # Extract values from objects using hash keys or object methods
+    #
+    # Works with hashes, structs, and any object that responds to the given identifiers.
+    # Supports nested digging with multiple arguments.
+    #
+    # @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 extraction
+    #   users.sort_by.dig(:name).sort
+    #
+    # @example Nested extraction
+    #   users.sort_by.dig(:profile, :email).sort
     #
-    # @param enumerable [Enumerable] The enumerable (Array, Hash) to sort
+    # @example Mixed key types
+    #   users.sort_by.dig(:name, indifferent: true).sort
     #
-    def initialize(enumerable)
-      @enumerable = enumerable
-      @pipeline = []
-      @direction = :asc
+    # @example Object method calls
+    #   objects.sort_by.dig(:calculate_score).sort
+    #
+    def dig(*identifiers, indifferent: false)
+      @extractors << {method: :dig, positional: identifiers, indifferent: indifferent}
+      self
     end
 
+    ############################################################################
+    # Modifiers
+    ############################################################################
+
+    ##
+    # Transform extracted values to lowercase for comparison
     #
-    # Finalizes the Sorter instance and sorts the enumerable
+    # Only affects values that respond to #downcase (typically strings).
+    # Non-string values pass through unchanged.
     #
-    # @return [Enumerable] The sorted enumerable
+    # @return [Sorter] Returns self for method chaining
     #
-    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
-
-          left_priority = type_priority(left)
-          right_priority = type_priority(right)
-
-          # 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)
-
-            left <=> right
-          else
-            left_priority <=> right_priority
-          end
-        end
-
-      (@direction == :asc) ? result : result.reverse
+    # @example Case-insensitive string sorting
+    #   names.sort_by.downcase.sort
+    #
+    # @example With hash extraction
+    #   users.sort_by.dig(:name).downcase.sort
+    #
+    def downcase
+      @modifiers << {method: :downcase}
+      self
     end
 
+    ##
+    # Alias for #downcase - provides case-insensitive sorting
+    #
+    # @return [Sorter] Returns self for method chaining
+    #
+    alias_method :insensitive, :downcase
+
+    ##
+    # Transform extracted values to uppercase for comparison
     #
-    # 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
+    # Only affects values that respond to #upcase (typically strings).
+    # Non-string values pass through unchanged.
     #
-    # @param & [Proc] The block to execute
+    # @return [Sorter] Returns self for method chaining
     #
-    # @return [Self] The sorter instance
+    # @example Uppercase sorting
+    #   names.sort_by.upcase.sort
     #
-    def add_filter(&)
-      add_step(type: Step::FILTER, &)
+    def upcase
+      @modifiers << {method: :upcase}
+      self
     end
 
+    ############################################################################
+    # Ordering
+    ############################################################################
+
+    ##
+    # Sort in ascending order (default behavior)
     #
-    # Adds a "transformation" step to the sort pipeline
-    # Transformation steps are used to transform data.
-    # These are performed after filter steps
-    #
-    # @param & [Proc] The block to execute
+    # This is typically unnecessary as ascending is the default,
+    # but can be useful for explicit clarity or resetting after desc.
     #
-    # @return [Self] The sorter instance
+    # @return [Sorter] Returns self for method chaining
     #
-    def add_transformation(&)
-      add_step(type: Step::TRANSFORMATION, &)
+    def asc
+      @ordering << {method: :sort!}
+      self
     end
 
+    ##
+    # Sort in descending order
     #
-    # Instructs the sorter to perform a fetch by key on the Hash being sorted
+    # Reverses the final sort order after all comparisons are complete.
     #
-    # @param key [String, Symbol, Any] The hash key to fetch
+    # @return [Sorter] Returns self for method chaining
     #
-    # @return [Self] The sorter instance
+    # @example Descending sort
+    #   users.sort_by.dig(:age).desc.sort
     #
-    def by_key(key)
-      add_filter { |i| i&.fetch(key) }
+    def desc
+      @ordering << {method: :reverse!}
       self
     end
 
+    ############################################################################
+    # Terminators
+    ############################################################################
+
+    ##
+    # Execute the sort pipeline and return a new sorted array
     #
-    # Instructs the sorter to perform a method call on the object being sorted
+    # Applies all chained extraction, transformation, and ordering steps
+    # to produce the final sorted result. The original collection is unchanged.
     #
-    # @param method [String, Symbol] The method name to call
+    # @return [Array] A new array containing the sorted elements
     #
-    # @return [Self] The sorter instance
+    # @example Basic termination
+    #   sorted_users = users.sort_by.dig(:name).sort
     #
-    def by_method(method)
-      add_filter { |i| i&.public_send(method) }
+    def sort
+      # Apply all extraction and transformation steps during comparison
+      sorted = @input.sort do |item_a, item_b|
+        apply_steps(item_a, item_b)
+      end
+
+      # Apply any ordering transformations (like desc)
+      apply_ordering_steps(sorted)
     end
 
-    alias_method :by_attribute, :by_method
+    ##
+    # Alias for #sort - returns a new sorted array
+    #
+    # @return [Array] A new array containing the sorted elements
+    #
+    # @see #sort
+    #
+    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.
     #
-    # Instructs the sorter to sort by a case insensitive value
-    # This will prioritize capital letters first, followed by their lowercase counterparts
+    # @return [Array] The original array, now sorted
     #
-    # @return [Self] The sorter instance
+    # @example In-place sorting
+    #   users.sort_by.dig(:name).sort!
+    #   # users array is now modified
     #
-    def case_insensitive
-      add_transformation do |item|
-        case item
-        when String
-          item.chars.flat_map { |c| [c.downcase, c] }
-        else
-          item
-        end
+    def sort!
+      # Sort the original array in place
+      @input.sort! do |item_a, item_b|
+        apply_steps(item_a, item_b)
       end
+
+      # Apply any ordering transformations
+      apply_ordering_steps(@input)
     end
 
+    ##
+    # Shorthand for adding desc and executing sort
     #
-    # Controls which direction the array will be sorted
+    # Equivalent to calling .desc.sort but more concise.
     #
-    # @return [Self] The sorter instance
+    # @return [Array] A new array sorted in descending order
     #
-    def asc
-      @direction = :asc
-      self
+    # @example Reverse sorting
+    #   users.sort_by.dig(:name).reverse
+    #
+    def reverse
+      desc.sort
     end
 
-    alias_method :forward, :asc
-
+    ##
+    # Shorthand for adding desc and executing sort!
     #
-    # Controls which direction the array will be sorted
+    # Equivalent to calling .desc.sort! but more concise.
     #
-    # @return [Self] The sorter instance
+    # @return [Array] The original array, sorted in descending order
     #
-    def desc
-      @direction = :desc
-      self
+    def reverse!
+      desc.sort!
     end
 
-    alias_method :reverse, :desc
-
     private
 
-    def add_step(type:, &block)
-      @pipeline << Step.new(type:, block:)
-      self
-    end
+    ##
+    # Apply the complete pipeline of steps to two items for comparison
+    #
+    # Iterates through all extraction and transformation steps,
+    # applying each one to both items in sequence.
+    #
+    # @param item_a [Object] First item to compare
+    # @param item_b [Object] Second item to compare
+    # @return [Integer] Comparison result (-1, 0, 1)
+    #
+    def apply_steps(item_a, item_b)
+      @extractors.each do |step|
+        item_a, item_b = apply_step(step, item_a, item_b)
+      end
 
-    def select_filter_steps
-      @pipeline.select { |s| s.type == Step::FILTER }
-    end
+      @modifiers.each do |step|
+        item_a, item_b = apply_step(step, item_a, item_b)
+      end
 
-    def select_transformation_steps
-      @pipeline.select { |s| s.type == Step::TRANSFORMATION }
+      # Final comparison using Ruby's spaceship operator
+      item_a <=> item_b
     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
+    ##
+    # Apply ordering transformations to the sorted array
+    #
+    # Executes any ordering steps (like desc) that affect the final
+    # arrangement of the sorted results.
+    #
+    # @param sorted [Array] The array to apply ordering to
+    # @return [Array] The array with ordering applied
+    #
+    def apply_ordering_steps(sorted)
+      @ordering.each do |step|
+        sorted.public_send(step[:method])
       end
+
+      sorted
     end
 
-    def apply_transformations(steps, value)
-      result = value
+    ##
+    # Apply a single step to both items in the comparison
+    #
+    # Handles different step types and safely manages method calls,
+    # falling back to string conversion for non-responsive objects.
+    #
+    # @param step [Hash] Step configuration containing method and arguments
+    # @param item_a [Object] First item to transform
+    # @param item_b [Object] Second item to transform
+    # @return [Array<Object, Object>] Transformed items
+    #
+    def apply_step(step, item_a, item_b)
+      method = step[:method]
+      positional = step[:positional] || []
+      indifferent = step[:indifferent] || false
 
-      steps.each do |step|
-        result = step.perform(result)
+      # For indifferent key access, normalize all positional args to symbols
+      if indifferent
+        positional = positional.map { |i| i.respond_to?(:to_sym) ? i.to_sym : i }
       end
 
-      result
+      item_a = extract_value_from(item_a, method, positional, indifferent)
+      item_b = extract_value_from(item_b, method, positional, indifferent)
+
+      [item_a, item_b]
+    end
+
+    ##
+    # Extracts a value from an object using the specified method and parameters.
+    #
+    # @param item [Object] the object to extract a value from
+    # @param method [Symbol, String] the method name to call on the object
+    # @param positional [Array] positional arguments to pass to the method
+    # @param indifferent [Boolean] whether to normalize hash keys to symbols for indifferent access
+    #
+    # @return [Object] the extracted value, or the string representation of the item
+    #
+    def extract_value_from(item, method, positional, indifferent)
+      return item.to_s unless item.respond_to?(method)
+
+      # For hash objects with indifferent access, normalize keys to symbols
+      item = item.transform_keys(&:to_sym) if indifferent
+
+      item.public_send(method, *positional)
     end
   end
 end

data/lib/sortsmith/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module Sortsmith
-  VERSION = "0.2.0"
+  #
+  # The current version of the Sortsmith gem
+  #
+  VERSION = "0.9.0"
 end

data/lib/sortsmith.rb

@@ -1,9 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "sortsmith/sorter"
-require_relative "sortsmith/step"
 require_relative "sortsmith/version"
+require_relative "sortsmith/core_ext/enumerable"
+require_relative "sortsmith/sorter"
 
+##
+# Sortsmith provides a flexible, chainable API for sorting Ruby collections.
+#
+# The gem extends Ruby's built-in {Enumerable} module to provide an intuitive
+# sorting interface that reads like natural language and supports complex
+# sorting operations through method chaining.
+#
+# @example Basic usage
+#   users = ["Charlie", "alice", "Bob"]
+#   users.sort_by.downcase.sort
+#   # => ["alice", "Bob", "Charlie"]
+#
+# @example Hash sorting
+#   users = [
+#     { name: "Charlie", age: 25 },
+#     { name: "alice", age: 30 },
+#     { name: "Bob", age: 20 }
+#   ]
+#   users.sort_by.dig(:name).insensitive.sort
+#   # => sorted by name, case-insensitive
+#
+# @example Complex chaining
+#   users.sort_by.dig(:name, indifferent: true).downcase.desc.sort
+#   # => Extract name (works with both string/symbol keys), downcase, descending
+#
+# @see Sortsmith::Sorter The main sorting interface
+# @see Enumerable#sort_by The extended sort_by method
+#
+# @author Bryan "itsthedevman"
+# @since 0.1.0
+#
 module Sortsmith
+  ##
+  # Base error class for all Sortsmith-related exceptions.
+  #
+  # This provides a namespace for any custom errors that may be raised
+  # during sorting operations, making it easier to rescue Sortsmith-specific
+  # issues without catching unrelated StandardError instances.
+  #
+  # @example Rescuing Sortsmith errors
+  #   begin
+  #     complex_sort_operation
+  #   rescue Sortsmith::Error => e
+  #     handle_sorting_error(e)
+  #   end
+  #
+  # @since 0.1.0
+  #
   class Error < StandardError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sortsmith
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-17 00:00:00.000000000 Z
+date: 2025-07-07 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,17 +25,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- Steepfile
 - flake.lock
 - flake.nix
 - lib/sortsmith.rb
+- lib/sortsmith/core_ext/enumerable.rb
 - lib/sortsmith/sorter.rb
-- lib/sortsmith/step.rb
 - lib/sortsmith/version.rb
-- sig/sortsmith.rbs
-- sig/sortsmith/sorter.rbs
-- sig/sortsmith/step.rbs
-- sig/sortsmith/version.rbs
 homepage: https://github.com/itsthedevman/sortsmith
 licenses:
 - MIT
@@ -53,7 +48,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Steepfile

@@ -1,8 +0,0 @@
-# D = Steep::Diagnostic
-
-target :lib do
-  signature "sig"
-  ignore_signature "sig/test"
-
-  check "lib"
-end

data/lib/sortsmith/step.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Sortsmith
-  #
-  # Represents a step in the sorting process
-  #
-  class Step < Data.define(:type, :block)
-    TYPES = [
-      TRANSFORMATION = :transformation,
-      FILTER = :filter
-    ].freeze
-
-    def perform(item)
-      block.call(item)
-    end
-  end
-end

data/sig/sortsmith/sorter.rbs

@@ -1,107 +0,0 @@
-module Sortsmith
-    interface _Sortable
-    def to_s: () -> String
-    def <=>: (self) -> Integer
-  end
-
-  class Sorter[Elem < _Sortable]
-    @enumerable: Enumerable[Elem]
-
-    @pipeline: Array[Step]
-
-    @direction: Symbol
-
-    #
-    # Creates a Sorter builder instance
-    #
-    # @param enumerable [Enumerable] The enumerable (Array, Hash) to sort
-    #
-    def initialize: (Enumerable[Elem] enumerable) -> void
-
-    #
-    # Finalizes the Sorter instance and sorts the enumerable
-    #
-    # @return [Enumerable] The sorted enumerable
-    #
-    def sort: () -> Enumerable[Elem]
-
-    #
-    # 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
-    #
-    # @param & [Proc] The block to execute
-    #
-    # @return [Self] The sorter instance
-    #
-    def add_filter: () { (untyped) -> untyped } -> self
-
-    #
-    # Adds a "transformation" step to the sort pipeline
-    # Transformation steps are used to transform data.
-    # These are performed after filter steps
-    #
-    # @param & [Proc] The block to execute
-    #
-    # @return [Self] The sorter instance
-    #
-    def add_transformation: () { (untyped) -> untyped } -> self
-
-    #
-    # Instructs the sorter to perform a fetch by key on the Hash being sorted
-    #
-    # @param key [String, Symbol, Any] The hash key to fetch
-    #
-    # @return [Self] The sorter instance
-    #
-    def by_key: ((String | Symbol | untyped) key) -> self
-
-    #
-    # Instructs the sorter to perform a method call on the object being sorted
-    #
-    # @param method [String, Symbol] The method name to call
-    #
-    # @return [Self] The sorter instance
-    #
-    def by_method: ((String | Symbol) method) -> self
-
-    alias by_attribute by_method
-
-    #
-    # Instructs the sorter to sort by a case insensitive value
-    #
-    # @return [Self] The sorter instance
-    #
-    def case_insensitive: () -> self
-
-    #
-    # Controls which direction the array will be sorted
-    #
-    # @return [Self] The sorter instance
-    #
-    def asc: () -> self
-
-    alias forward asc
-
-    #
-    # Controls which direction the array will be sorted
-    #
-    # @return [Self] The sorter instance
-    #
-    def desc: () -> self
-
-    alias reverse desc
-
-    private
-
-    def add_step: (type: Symbol) { (untyped) -> untyped } -> self
-
-    def select_filter_steps: () -> Array[Step]
-
-    def select_transformation_steps: () -> Array[Step]
-
-    def type_priority: (untyped value) -> Integer
-
-    def apply_transformations: (Array[Step] steps, untyped value) -> untyped
-  end
-end

data/sig/sortsmith/step.rbs

@@ -1,28 +0,0 @@
-module Sortsmith
-  #
-  # Represents a step in the sorting process
-  #
-  class Step < ::Data
-    TYPES: ::Array[Symbol]
-
-    FILTER: Symbol
-
-    TRANSFORMATION: Symbol
-
-    attr_reader type: Symbol
-
-    attr_reader block: ^(untyped) -> untyped
-
-    def self.new: (Symbol type, untyped block) -> instance
-                | (type: Symbol, block: untyped) -> instance
-
-    def self.[]: (Symbol type, untyped block) -> instance
-              | (type: Symbol, block: untyped) -> instance
-
-    def self.members: () -> [ :type, :block ]
-
-    def members: () -> [ :type, :block ]
-
-    def perform: (untyped item) -> untyped
-  end
-end

data/sig/sortsmith/version.rbs

@@ -1,3 +0,0 @@
-module Sortsmith
-  VERSION: String
-end

data/sig/sortsmith.rbs

@@ -1,4 +0,0 @@
-module Sortsmith
-  class Error < StandardError
-  end
-end