toller 0.5.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b4793bf7b83960e6161abed53be6955abdad7ecc5678a0886277639e89bf838
-  data.tar.gz: b20310d7b23eb741a4d60a8a67129a9bc51276e003d1b875add801292f12c05c
+  metadata.gz: bb4ebc1d6c6e8f4eaae0c68c740ae3b35693cd678c6e14e245295a40ad48f2d0
+  data.tar.gz: f380d915cb7f85ed2f3cd6873db803c71d01b9a28e96b9ba8375bb241a02432f
 SHA512:
-  metadata.gz: 9a03af42f39cb441c4765376d1f172cddbe2ef471bfa9a757b6d9f99681e5b11e4e6bc332b207aeda90aa690f68d20e095c7e93270090bedf96b40f3ad608544
-  data.tar.gz: 8359c6389c7c020520b1f816481a848ef67c4fad52d8ca570c93c491df6b5b0e437b12763af8dc2c1c5a05dcb65dd0102a62127a8ca74b244cb843f10f06de4a
+  metadata.gz: b84c1d90d5d1ebddb6ac81713874ce935d141664a3cb9b4601e08bd4394e844e26aa495d77d88b6381f39587093b3794411cefcc1fe082951239033ba2da070d
+  data.tar.gz: 2a1f0894da895687f8b8699073bd84932c41b1a1af591c95269f6e596e8555111af92dea2b065b598a1e3e18ee3f0869033385c46a44c04696d2fd1b74f37940

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020 David Freerksen
+Copyright 2026 David Freerksen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,13 +1,22 @@
 # Toller
 
-URL based filtering and sorting. See the wiki for usage information.
+URL-query-param-based filtering and sorting for Rails controllers.
+
+Toller is a Rails engine that lets controllers declare filter_on/sort_on directives, then applies whichever filters and sorts are active for the current request to an ActiveRecord relation based on URL query parameters.
+
+See the [wiki](https://github.com/dfreerksen/toller/wiki) for usage information.
+
+## Requirements
+
+* Ruby >= 3.3.0
+* Rails >= 6.0
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'toller'
+gem 'toller', '~> 1.1'
 ```
 
 And then execute:
@@ -40,40 +49,77 @@ $ bin/test
 
 ### Appraisal
 
+Uses [Appraisal2](https://github.com/appraisal-rb/appraisal2) (a maintained fork of [Appraisal](https://github.com/thoughtbot/appraisal), still exposing the `appraisal` executable) to ensure various dependency versions work as expected
+
+When dependencies change, run
+
 ```bash
 $ bundle exec appraisal install
-$ bundle exec appraisal rails-5 bin/test
-$ bundle exec appraisal rails-6 bin/test
+$ bundle exec appraisal generate-install
 ```
 
-### WWTD
+To run tests with Appraisal, run
+
+```bash
+$ bundle exec appraisal rspec
+```
 
-Test against the Travis simulator. Note that [WWTD](https://github.com/grosser/wwtd) needs to be installed (install with `gem install wwtd`)
+`-n 1` forces Appraisal2 to run one Rails version at a time. Without it, Appraisal2 defaults to running 2 appraisals in parallel, and since every appraisal shares the same `test/dummy/db/test.sqlite3` file, concurrent runs can intermittently fail with `SQLite3::BusyException: database is locked`.
 
 ```bash
-$ wwtd
+$ bundle exec appraisal rails-6-0 rspec
+$ bundle exec appraisal rails-6-1 rspec
+$ bundle exec appraisal rails-7-0 rspec
+$ bundle exec appraisal rails-7-1 rspec
+$ bundle exec appraisal rails-7-2 rspec
+$ bundle exec appraisal rails-8-0 rspec
+$ bundle exec appraisal rails-8-1 rspec
 ```
 
 ## Release
 
-1. Bump the gem version in `lib/toller/version.rb`
-2. Build the gem with
+See [Release.md](docs/Release.md)
+
+## Code Analysis
+
+Various tools are used to ensure code is linted and formatted correctly.
+
+### RuboCop
+
+[RuboCop](https://github.com/bbatsov/rubocop) is a Ruby static code analyzer.
+
+```bash
+$ rubocop
+```
+
+### YARD-Lint
+
+[YARD-Lint](https://github.com/mensfeld/yard-lint) is a linter for YARD documentation.
+
+```bash
+$ bundle exec yard-lint
+```
 
-   ```
-   $ bundle exec rake build
-   ```
+## Documentation
 
-   This will create a new .gem file in `pkg/`. Fix any errors or warnings that come up.
-3. Commit the version change to git with a commit message similar to "Release [X.Y.Z]"
-4. Create the gem, tag it in Github and release to Rubygems
+[Yard](https://github.com/lsegal/yard) is used to generate documentation. [Online documentation is available](http://www.rubydoc.info/github/dfreerksen/toller/master)
 
-   ```
-   $ bundle exec rake release
-   ```
+Build the documentation with one of the following
+
+```bash
+$ yard
+$ yard doc
+```
+
+Build the documentation and list all undocumented objects
+
+```bash
+$ yard stats --list-undoc
+```
 
 ## Contributing
 
-1. Fork it ([https://github.com/dfrerksen/recieve/fork](https://github.com/dfrerksen/recieve/fork))
+1. Fork it ([https://github.com/dfrerksen/toller/fork](https://github.com/dfrerksen/toller/fork))
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/Rakefile

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 begin
-  require 'bundler/setup'
+  require "bundler/setup"
 rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
 end
 
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
 
-APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
-load 'rails/tasks/engine.rake'
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"

data/lib/toller/filter.rb

@@ -3,10 +3,24 @@
 module Toller
   ##
   # Filter
-  #
   class Filter
-    attr_reader :parameter, :properties, :type
+    # @return [Symbol] the public filter param name
+    attr_reader :parameter
 
+    # @return [Hash] the filter's resolved options (:field, :default, :scope_name, etc.)
+    attr_reader :properties
+
+    # @return [Symbol] the filter type, e.g. :string, :integer, :scope
+    attr_reader :type
+
+    ##
+    # @param parameter [Symbol] the public filter param name
+    # @param type [Symbol] the filter type, e.g. :string, :integer, :scope
+    # @param options [Hash] filter options; merged over defaults for :field, :default, and :scope_name
+    # @option options [Symbol] :field the column/attribute to query; defaults to +parameter+
+    # @option options [Boolean] :default whether this filter applies automatically when no filter params were sent
+    # @option options [Symbol] :scope_name for type: :scope, the model scope to call; defaults to +parameter+
+    # @return [Toller::Filter] a new instance of Filter
     def initialize(parameter, type, options)
       @parameter = parameter
       @type = type
@@ -17,14 +31,23 @@ module Toller
       )
     end
 
+    ##
+    # Applies this filter to +collection+, dispatching to the scope or
+    # where handler based on +type+.
+    #
+    # @param collection [ActiveRecord::Relation] the collection to filter
+    # @param value [Object] the active filter param value
+    # @return [ActiveRecord::Relation] the filtered collection
     def apply!(collection, value)
       if type == :scope
         Filters::ScopeHandler.new.call(collection, value, properties)
       else
-        Filters::WhereHandler.new.call(collection, type, value, properties)
+        Filters::ColumnHandler.new.call(collection, type, value, properties)
       end
     end
 
+    ##
+    # @return [Boolean] whether this filter applies automatically when no filter params were sent at all
     def default
       properties[:default]
     end

data/lib/toller/filters/column_handler.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Toller
+  # :nodoc:
+  module Filters
+    ##
+    # Column handler for filter
+    class ColumnHandler
+      ##
+      # Applies a plain `where` clause to +collection+ for a non-scope filter.
+      #
+      # If +field+ isn't a real column on the collection's model, the filter is
+      # logged and skipped instead of raising once the relation is evaluated.
+      #
+      # @param collection [ActiveRecord::Relation] the collection to filter
+      # @param type [Symbol] the filter type (e.g. :string, :integer, :boolean)
+      # @param value [Object] the raw filter param value
+      # @param properties [Hash] the filter's properties, used to resolve `:field`
+      # @return [ActiveRecord::Relation] the filtered collection, or +collection+ unchanged if `:field` is unknown
+      def call(collection, type, value, properties)
+        field_name = properties[:field]
+
+        unless collection.klass.column_names.include?(field_name.to_s)
+          Rails.logger.warn("[Toller] Skipping filter: #{collection.klass} has no column `#{field_name}`")
+          return collection
+        end
+
+        mutated_value = value_mutator(type, value)
+
+        collection.where(field_name => mutated_value)
+      end
+
+      private
+
+      ##
+      # Value mutator
+      #
+      # Runs +value+ through the type-specific mutator, if one exists for +type+.
+      #
+      # @param type [Symbol] the filter type
+      # @param value [Object] the raw filter param value
+      # @return [Object] the mutated value, or the original +value+ if +type+ has no mutator
+      def value_mutator(type, value)
+        return value unless %i[boolean date datetime integer time].include?(type)
+
+        send("#{type}_mutator", value)
+      end
+
+      ##
+      # Boolean mutator
+      #
+      # @param value [String] the raw filter param value
+      # @return [Boolean] the mutated boolean value
+      def boolean_mutator(value)
+        Mutators::Boolean.call(value)
+      end
+
+      ##
+      # Integer mutator
+      #
+      # @param value [String] the raw filter param value
+      # @return [String, Range] the mutated integer value or range
+      def integer_mutator(value)
+        Mutators::Integer.call(value)
+      end
+
+      ##
+      # Date mutator
+      #
+      # @param value [String] the raw filter param value
+      # @return [String, Range] the mutated date value or range
+      def date_mutator(value)
+        Mutators::Date.call(value)
+      end
+
+      ##
+      # Time mutator
+      #
+      # @param value [String] the raw filter param value
+      # @return [String, Range] the mutated time value or range
+      def time_mutator(value)
+        Mutators::Time.call(value)
+      end
+
+      ##
+      # DateTime mutator
+      #
+      # @param value [String] the raw filter param value
+      # @return [String, Range] the mutated datetime value or range
+      def datetime_mutator(value)
+        Mutators::Datetime.call(value)
+      end
+    end
+  end
+end

data/lib/toller/filters/mutators/boolean.rb

@@ -1,16 +1,22 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Boolean filter mutator
-      #
       module Boolean
         module_function
 
+        ##
+        # Coerces a raw filter param into a boolean.
+        #
+        # @param value [String] the raw filter param value
+        # @return [Boolean] true if +value+ is one of "1", "t", "true", "y", "yes"; false otherwise
         def call(value)
-          %w[1 t true y yes].include?(value)
+          %w[1 t true y yes].include?(value.to_s.downcase)
         end
       end
     end

data/lib/toller/filters/mutators/common/range.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Toller
+  # :nodoc:
+  module Filters
+    # :nodoc:
+    module Mutators
+      # :nodoc:
+      module Common
+        ##
+        # Shared range-parsing behavior for filter mutators. Extend this module to get a
+        # `call(value)` that returns +value+ unchanged, or a Range when +value+ contains
+        # Ruby range syntax (`..` for inclusive, `...` for exclusive).
+        #
+        # Note: methods here must refer to Ruby's core Range class as `::Range` — a bare
+        # `Range` would resolve to this module (Mutators::Common::Range) instead, since
+        # Ruby's constant lookup checks the lexical scope before the top level.
+        module Range
+          ##
+          # Coerces a raw filter param into its original value or a Range.
+          #
+          # @param value [String] the raw filter param value
+          # @return [String,::Range] the original value, or a Range when the value contains range syntax
+          #                          (`..` or `...`)
+          def call(value)
+            range_dots = inclusive_or_exclusive_range(value)
+
+            return value if range_dots.blank?
+
+            range(value, range_dots)
+          end
+
+          ##
+          # Builds a Range by splitting +value+ on the given range dots.
+          #
+          # @param value [String] the raw range string, e.g. "1..10"
+          # @param dots [String] the range separator, either ".." or "..."
+          # @return [::Range] the resulting range, exclusive when +dots+ is "..."
+          def range(value, dots)
+            ::Range.new(*value.split(dots), dots == "...")
+          end
+
+          ##
+          # Detects whether +value+ contains inclusive or exclusive range syntax.
+          #
+          # @param value [String] the raw filter param value
+          # @return [String,nil] "..." for an exclusive range, ".." for an inclusive range, or nil if +value+ is not
+          #                      a range
+          def inclusive_or_exclusive_range(value)
+            return "..." if value.include?("...")
+            return ".." if value.include?("..")
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toller/filters/mutators/date.rb

@@ -1,32 +1,14 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Date filter mutator
-      #
       module Date
-        module_function
-
-        def call(value)
-          range_dots = inclusive_or_exclusive_range(value)
-
-          return value if range_dots.blank?
-
-          range(value, range_dots)
-        end
-
-        def range(value, dots)
-          Range.new(*value.split(dots))
-        end
-
-        def inclusive_or_exclusive_range(value)
-          return '...' if value.include?('...')
-          return '..' if value.include?('..')
-
-          nil
-        end
+        extend Common::Range
       end
     end
   end

data/lib/toller/filters/mutators/datetime.rb

@@ -1,32 +1,14 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Datetime filter mutator
-      #
       module Datetime
-        module_function
-
-        def call(value)
-          range_dots = inclusive_or_exclusive_range(value)
-
-          return value if range_dots.blank?
-
-          range(value, range_dots)
-        end
-
-        def range(value, dots)
-          Range.new(*value.split(dots))
-        end
-
-        def inclusive_or_exclusive_range(value)
-          return '...' if value.include?('...')
-          return '..' if value.include?('..')
-
-          nil
-        end
+        extend Common::Range
       end
     end
   end

data/lib/toller/filters/mutators/integer.rb

@@ -1,36 +1,14 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Integer filter mutator
-      #
       module Integer
-        module_function
-
-        def call(value)
-          return value unless range?(value)
-
-          range(value)
-        end
-
-        def range?(value)
-          range_dots = inclusive_or_exclusive_range(value)
-
-          range_dots.present?
-        end
-
-        def range(value)
-          Range.new(*value.split(inclusive_or_exclusive_range(value)))
-        end
-
-        def inclusive_or_exclusive_range(value)
-          return '...' if value.include?('...')
-          return '..' if value.include?('..')
-
-          nil
-        end
+        extend Common::Range
       end
     end
   end

data/lib/toller/filters/mutators/time.rb

@@ -1,32 +1,14 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Time filter mutator
-      #
       module Time
-        module_function
-
-        def call(value)
-          range_dots = inclusive_or_exclusive_range(value)
-
-          return value if range_dots.blank?
-
-          range(value, range_dots)
-        end
-
-        def range(value, dots)
-          Range.new(*value.split(dots))
-        end
-
-        def inclusive_or_exclusive_range(value)
-          return '...' if value.include?('...')
-          return '..' if value.include?('..')
-
-          nil
-        end
+        extend Common::Range
       end
     end
   end

data/lib/toller/filters/scope_handler.rb

@@ -1,14 +1,29 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
     ##
     # Scope handler for filter
-    #
     class ScopeHandler
+      ##
+      # Applies a named scope to +collection+ for a `type: :scope` filter.
+      #
+      # If the resolved scope doesn't exist on the collection's model, the
+      # filter is logged and skipped instead of raising a NoMethodError.
+      #
+      # @param collection [ActiveRecord::Relation] the collection to filter
+      # @param value [Object] the filter param value to pass to the scope
+      # @param properties [Hash] the filter's properties, used to resolve `:scope_name` (falling back to `:field`)
+      # @return [ActiveRecord::Relation] the scoped collection, or +collection+ unchanged if the scope is unknown
       def call(collection, value, properties)
         scoped_name = properties[:scope_name] || properties[:field]
 
+        unless collection.klass.respond_to?(scoped_name)
+          Rails.logger.warn("[Toller] Skipping filter: #{collection.klass} has no scope `#{scoped_name}`")
+          return collection
+        end
+
         collection.public_send(scoped_name, value)
       end
     end

data/lib/toller/retriever.rb

@@ -3,14 +3,38 @@
 module Toller
   ##
   # Retriever
-  #
   class Retriever
-    attr_reader :collection, :filter_params, :retrievals, :sort_params
+    # @return [ActiveRecord::Relation] the collection being filtered/sorted
+    attr_reader :collection
 
+    # @return [Hash] the request's filter params, keyed by filter parameter name
+    attr_reader :filter_params
+
+    # @return [Array<Toller::Filter,Toller::Sort>] every Filter and Sort registered on the
+    #   including class's ancestor chain
+    attr_reader :retrievals
+
+    # @return [Array<String>] the request's sort params, e.g. ['-published_at', 'title']
+    attr_reader :sort_params
+
+    ##
+    # Builds a Retriever and applies all active filters/sorts to +collection+.
+    #
+    # @param collection [ActiveRecord::Relation] the collection to filter/sort
+    # @param filter_params [Hash] the request's filter params
+    # @param sort_params [Array<String>] the request's sort params
+    # @param retrievals [Array<Toller::Filter,Toller::Sort>] every registered Filter and Sort
+    # @return [ActiveRecord::Relation] the filtered and sorted collection
     def self.filter(collection, filter_params, sort_params, retrievals)
       new(collection, filter_params, sort_params, retrievals).filter
     end
 
+    ##
+    # @param collection [ActiveRecord::Relation] the collection to filter/sort
+    # @param filter_params [Hash] the request's filter params
+    # @param sort_params [Array<String>] the request's sort params
+    # @param retrievals [Array<Toller::Filter,Toller::Sort>] every registered Filter and Sort
+    # @return [Toller::Retriever] a new instance of Retriever
     def initialize(collection, filter_params, sort_params, retrievals)
       @collection = collection
       @filter_params = filter_params
@@ -18,6 +42,11 @@ module Toller
       @retrievals = retrievals
     end
 
+    ##
+    # Reduces over the active filters/sorts, chaining each one's `apply!`
+    # onto the collection returned by the previous one.
+    #
+    # @return [ActiveRecord::Relation] the filtered and sorted collection
     def filter
       active_retrievals.reduce(collection) do |items, retrieval|
         param_value = if retrieval.is_a?(Filter)
@@ -32,18 +61,26 @@ module Toller
 
     private
 
+    ##
+    # @return [Array<Toller::Filter,Toller::Sort>] the subset of +retrievals+ that are active for the current request
     def active_retrievals
       retrievals.select do |retrieval|
         retrieval.is_a?(Filter) ? filtering_activated?(retrieval) : sorting_activated?(retrieval)
       end
     end
 
+    ##
+    # @param retrieval [Toller::Filter] the filter to check
+    # @return [Boolean] whether +retrieval+ is active for the current request
     def filtering_activated?(retrieval)
       return true if filter_params.blank? && retrieval.default
 
       filter_params.fetch(retrieval.parameter, nil).present?
     end
 
+    ##
+    # @param retrieval [Toller::Sort] the sort to check
+    # @return [Boolean] whether +retrieval+ is active for the current request
     def sorting_activated?(retrieval)
       return true if sort_params.blank? && retrieval.default
 

data/lib/toller/sort.rb

@@ -3,10 +3,24 @@
 module Toller
   ##
   # Sort
-  #
   class Sort
-    attr_reader :parameter, :properties, :type
+    # @return [Symbol] the public sort param name
+    attr_reader :parameter
 
+    # @return [Hash] the sort's resolved options (:field, :default, :scope_name, etc.)
+    attr_reader :properties
+
+    # @return [Symbol] the sort type, e.g. :string, :integer, :scope
+    attr_reader :type
+
+    ##
+    # @param parameter [Symbol] the public sort param name
+    # @param type [Symbol] the sort type, e.g. :string, :integer, :scope
+    # @param options [Hash] sort options; merged over defaults for :field, :default, and :scope_name
+    # @option options [Symbol] :field the column/attribute to sort on; defaults to +parameter+
+    # @option options [Boolean] :default whether this sort applies automatically when no sort params were sent
+    # @option options [Symbol] :scope_name for type: :scope, the model scope to call; defaults to +parameter+
+    # @return [Toller::Sort] a new instance of Sort
     def initialize(parameter, type, options)
       @parameter = parameter
       @type = type
@@ -17,14 +31,23 @@ module Toller
       )
     end
 
+    ##
+    # Applies this sort to +collection+, dispatching to the scope or
+    # order handler based on +type+.
+    #
+    # @param collection [ActiveRecord::Relation] the collection to sort
+    # @param direction [Symbol] the sort direction, :asc or :desc
+    # @return [ActiveRecord::Relation] the sorted collection
     def apply!(collection, direction = :asc)
       if type == :scope
         Sorts::ScopeHandler.new.call(collection, direction, properties)
       else
-        Sorts::OrderHandler.new.call(collection, direction, properties)
+        Sorts::ColumnHandler.new.call(collection, direction, properties)
       end
     end
 
+    ##
+    # @return [Boolean] whether this sort applies automatically when no sort params were sent at all
     def default
       properties[:default]
     end

data/lib/toller/sorts/column_handler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Toller
+  # :nodoc:
+  module Sorts
+    ##
+    # Column handler for filter
+    class ColumnHandler
+      ##
+      # Applies a plain `order` clause to +collection+ for a non-scope sort.
+      #
+      # If +field+ isn't a real column on the collection's model, the sort is
+      # logged and skipped instead of raising once the relation is evaluated.
+      #
+      # @param collection [ActiveRecord::Relation] the collection to sort
+      # @param direction [Symbol] the sort direction, :asc or :desc
+      # @param properties [Hash] the sort's properties, used to resolve `:field`
+      # @return [ActiveRecord::Relation] the sorted collection, or +collection+ unchanged if `:field` is unknown
+      def call(collection, direction, properties)
+        field_name = properties[:field]
+
+        unless collection.klass.column_names.include?(field_name.to_s)
+          Rails.logger.warn("[Toller] Skipping sort: #{collection.klass} has no column `#{field_name}`")
+          return collection
+        end
+
+        collection.order(field_name => direction)
+      end
+    end
+  end
+end

data/lib/toller/sorts/scope_handler.rb

@@ -1,14 +1,29 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Sorts
     ##
     # Scope handler for sort
-    #
     class ScopeHandler
+      ##
+      # Applies a named scope to +collection+ for a `type: :scope` sort.
+      #
+      # If the resolved scope doesn't exist on the collection's model, the
+      # sort is logged and skipped instead of raising a NoMethodError.
+      #
+      # @param collection [ActiveRecord::Relation] the collection to sort
+      # @param direction [Symbol] the sort direction, :asc or :desc, passed to the scope
+      # @param properties [Hash] the sort's properties, used to resolve `:scope_name` (falling back to `:field`)
+      # @return [ActiveRecord::Relation] the scoped collection, or +collection+ unchanged if the scope is unknown
       def call(collection, direction, properties)
         scoped_name = properties[:scope_name] || properties[:field]
 
+        unless collection.klass.respond_to?(scoped_name)
+          Rails.logger.warn("[Toller] Skipping sort: #{collection.klass} has no scope `#{scoped_name}`")
+          return collection
+        end
+
         collection.public_send(scoped_name, direction)
       end
     end

data/lib/toller/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Toller
-  VERSION = '0.5.0'
+  # @return [String] the current gem version
+  VERSION = "1.1.0"
 end

data/lib/toller.rb

@@ -1,26 +1,43 @@
 # frozen_string_literal: true
 
-require 'toller/filter'
-require 'toller/filters/mutators/boolean'
-require 'toller/filters/mutators/date'
-require 'toller/filters/mutators/datetime'
-require 'toller/filters/mutators/integer'
-require 'toller/filters/mutators/time'
-require 'toller/filters/scope_handler'
-require 'toller/filters/where_handler'
-require 'toller/retriever'
-require 'toller/sort'
-require 'toller/sorts/order_handler'
-require 'toller/sorts/scope_handler'
+require "toller/filter"
+require "toller/filters/column_handler"
+require "toller/filters/mutators/boolean"
+require "toller/filters/mutators/common/range"
+require "toller/filters/mutators/date"
+require "toller/filters/mutators/datetime"
+require "toller/filters/mutators/integer"
+require "toller/filters/mutators/time"
+require "toller/filters/scope_handler"
+require "toller/retriever"
+require "toller/sort"
+require "toller/sorts/column_handler"
+require "toller/sorts/scope_handler"
 
 ##
 # Toller
 #
 # Query param based filtering and sorting
-#
 module Toller
   extend ActiveSupport::Concern
 
+  ##
+  # Coerces a raw string value into a boolean, using the same rule Toller's
+  # own `type: :boolean` filters use internally. Handy inside a model scope
+  # backing a `type: :scope` filter, which receives the raw param value
+  # unmutated.
+  #
+  # @param value [String] the raw value
+  # @return [Boolean] true if +value+ is one of "1", "t", "true", "y", "yes"; false otherwise
+  def self.truthy(value)
+    Filters::Mutators::Boolean.call(value)
+  end
+
+  ##
+  # Applies every active filter/sort for the current request to +collection+.
+  #
+  # @param collection [ActiveRecord::Relation] the collection to filter/sort
+  # @return [ActiveRecord::Relation] the filtered and sorted collection
   def retrieve(collection)
     Retriever.filter(collection, filter_params, sort_params, retrievals)
   end
@@ -30,37 +47,73 @@ module Toller
   end
 
   class_methods do
+    ##
+    # Declares a filter on the including controller.
+    #
+    # @param parameter [Symbol] the public filter param name
+    # @param type [Symbol] the filter type, e.g. :string, :integer, :scope
+    # @param options [Hash] filter options, e.g. :field, :scope_name, :default
+    # @return [Array<Toller::Filter,Toller::Sort>] the class's updated `_filters` list
     def filter_on(parameter, type:, **options)
       _filters << Filter.new(parameter, type, options)
     end
 
+    ##
+    # Declares a sort on the including controller.
+    #
+    # @param parameter [Symbol] the public sort param name
+    # @param type [Symbol] the sort type, e.g. :string, :integer, :scope
+    # @param options [Hash] sort options, e.g. :field, :scope_name, :default
+    # @return [Array<Toller::Filter,Toller::Sort>] the class's updated `_filters` list
     def sort_on(parameter, type:, **options)
       _filters << Sort.new(parameter, type, options)
     end
 
+    ##
+    # @return [Array<Toller::Filter,Toller::Sort>] the filters/sorts declared directly on this class
+    #                                              via `filter_on`/`sort_on`
     def _filters
       @_filters ||= []
     end
   end
 
+  ##
+  # @return [Hash] the current request's filter params, keyed by filter parameter name
   def filter_params
     params.fetch(filter_param_key.to_sym, {})
   end
 
+  ##
+  # @return [Array<String>] the current request's sort params, e.g. ['-published_at', 'title']
   def sort_params
-    params.fetch(sort_param_key.to_sym, '').split(',')
+    params.fetch(sort_param_key.to_sym, "").split(",")
   end
 
+  ##
+  # Override in an including controller to change the query param Toller
+  # reads filters from.
+  #
+  # @return [Symbol] the query param key holding filter params
   def filter_param_key
     :filters
   end
 
+  ##
+  # Override in an including controller to change the query param Toller
+  # reads sorts from.
+  #
+  # @return [Symbol] the query param key holding sort params
   def sort_param_key
     :sort
   end
 
   private
 
+  ##
+  # Retrievals
+  #
+  # @return [Array<Toller::Filter,Toller::Sort>] every Filter and Sort registered via `filter_on`/`sort_on` across the
+  #                                              including class's ancestor chain
   def retrievals
     self.class.ancestors.flat_map { |klass| klass.try(:_filters) }.compact
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: toller
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.1.0
 platform: ruby
 authors:
 - David Freerksen
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,29 +15,17 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: appraisal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.3.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.3.0
-description: Description of Toller.
+        version: '6.0'
+description: Toller is a Rails engine that lets controllers declare filter_on/sort_on
+  directives, then applies whichever filters and sorts are active for the current
+  request to an ActiveRecord relation based on URL query parameters.
 email:
 - dfreerksen@gmail.com
 executables: []
@@ -50,23 +37,29 @@ files:
 - Rakefile
 - lib/toller.rb
 - lib/toller/filter.rb
+- lib/toller/filters/column_handler.rb
 - lib/toller/filters/mutators/boolean.rb
+- lib/toller/filters/mutators/common/range.rb
 - lib/toller/filters/mutators/date.rb
 - lib/toller/filters/mutators/datetime.rb
 - lib/toller/filters/mutators/integer.rb
 - lib/toller/filters/mutators/time.rb
 - lib/toller/filters/scope_handler.rb
-- lib/toller/filters/where_handler.rb
 - lib/toller/retriever.rb
 - lib/toller/sort.rb
-- lib/toller/sorts/order_handler.rb
+- lib/toller/sorts/column_handler.rb
 - lib/toller/sorts/scope_handler.rb
 - lib/toller/version.rb
 homepage: https://github.com/dfreerksen/toller
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  rubygems_mfa_required: 'true'
+  bug_tracker_uri: https://github.com/dfreerksen/toller/issues
+  documentation_uri: https://www.rubydoc.info/github/dfreerksen/toller/master
+  homepage_uri: https://github.com/dfreerksen/toller
+  source_code_uri: https://github.com/dfreerksen/toller
+  wiki_uri: https://github.com/dfreerksen/toller/wiki
 rdoc_options: []
 require_paths:
 - lib
@@ -74,15 +67,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.8
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Summary of Toller.
+summary: URL-query-param-based filtering and sorting for Rails controllers.
 test_files: []

data/lib/toller/filters/where_handler.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Toller
-  module Filters
-    ##
-    # Where handler for filter
-    #
-    class WhereHandler
-      def call(collection, type, value, properties)
-        field_name = properties[:field]
-
-        mutated_value = value_mutator(type, value)
-
-        collection.where(field_name => mutated_value)
-      end
-
-      private
-
-      def value_mutator(type, value)
-        return value unless %i[boolean date datetime integer time].include?(type)
-
-        send("#{type}_mutator", value)
-      end
-
-      def boolean_mutator(value)
-        Mutators::Boolean.call(value)
-      end
-
-      def integer_mutator(value)
-        Mutators::Integer.call(value)
-      end
-
-      def date_mutator(value)
-        Mutators::Date.call(value)
-      end
-
-      def time_mutator(value)
-        Mutators::Time.call(value)
-      end
-
-      def datetime_mutator(value)
-        Mutators::Datetime.call(value)
-      end
-    end
-  end
-end

data/lib/toller/sorts/order_handler.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Toller
-  module Sorts
-    ##
-    # Order handler for filter
-    #
-    class OrderHandler
-      def call(collection, direction, properties)
-        field_name = properties[:field]
-
-        collection.order(field_name => direction)
-      end
-    end
-  end
-end