toller 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b4793bf7b83960e6161abed53be6955abdad7ecc5678a0886277639e89bf838
-  data.tar.gz: b20310d7b23eb741a4d60a8a67129a9bc51276e003d1b875add801292f12c05c
+  metadata.gz: 565b78efab21039ddd7025adad94e0ac2e045943acef17e97374aac58b0b3b10
+  data.tar.gz: a73035fb270e002dfd8cfe8ed38dff7317dbbf033e4aac922e5b409fc9aad92b
 SHA512:
-  metadata.gz: 9a03af42f39cb441c4765376d1f172cddbe2ef471bfa9a757b6d9f99681e5b11e4e6bc332b207aeda90aa690f68d20e095c7e93270090bedf96b40f3ad608544
-  data.tar.gz: 8359c6389c7c020520b1f816481a848ef67c4fad52d8ca570c93c491df6b5b0e437b12763af8dc2c1c5a05dcb65dd0102a62127a8ca74b244cb843f10f06de4a
+  metadata.gz: b6a9f24aeec9383b065c39c3430c63ab90bd75cd963b414418e552d3fdd22a151e0c1da7ece697c92116958d294781c83330145889266d6be739e7ba2698b78a
+  data.tar.gz: b816afc011e2070a7adfeee999702ecdf2ca04af45e50a4ec7966d98ef1fd5486aaa1bcffd4c48a443db9aafdc43a60c5679c7b4dd20e5ff918304b6b38232bd

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.0'
 ```
 
 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,6 +31,13 @@ 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)
@@ -25,6 +46,8 @@ module Toller
       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/mutators/boolean.rb

@@ -1,14 +1,20 @@
 # 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)
         end

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

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Date filter mutator
-      #
       module Date
         module_function
 
+        ##
+        # Coerces a raw filter param into a date value or 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)
 
@@ -17,13 +23,25 @@ module Toller
           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. "2024-01-01..2024-12-31"
+        # @param dots [String] the range separator, either ".." or "..."
+        # @return [Range] the resulting range
         def range(value, dots)
           Range.new(*value.split(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?('..')
+          return "..." if value.include?("...")
+          return ".." if value.include?("..")
 
           nil
         end

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

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Datetime filter mutator
-      #
       module Datetime
         module_function
 
+        ##
+        # Coerces a raw filter param into a datetime value or 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)
 
@@ -17,13 +23,25 @@ module Toller
           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. "2024-01-01..2024-12-31"
+        # @param dots [String] the range separator, either ".." or "..."
+        # @return [Range] the resulting range
         def range(value, dots)
           Range.new(*value.split(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?('..')
+          return "..." if value.include?("...")
+          return ".." if value.include?("..")
 
           nil
         end

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

@@ -1,33 +1,55 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Integer filter mutator
-      #
       module Integer
         module_function
 
+        ##
+        # Coerces a raw filter param into an integer value or 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)
           return value unless range?(value)
 
           range(value)
         end
 
+        ##
+        # Checks whether +value+ contains range syntax.
+        #
+        # @param value [String] the raw filter param value
+        # @return [Boolean] true if +value+ contains `..` or `...`
         def range?(value)
           range_dots = inclusive_or_exclusive_range(value)
 
           range_dots.present?
         end
 
+        ##
+        # Builds a Range by splitting +value+ on its range dots.
+        #
+        # @param value [String] the raw range string, e.g. "1..10"
+        # @return [Range] the resulting range
         def range(value)
           Range.new(*value.split(inclusive_or_exclusive_range(value)))
         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?('..')
+          return "..." if value.include?("...")
+          return ".." if value.include?("..")
 
           nil
         end

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

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
+    # :nodoc:
     module Mutators
       ##
       # Time filter mutator
-      #
       module Time
         module_function
 
+        ##
+        # Coerces a raw filter param into a time value or 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)
 
@@ -17,13 +23,25 @@ module Toller
           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. "09:00..17:00"
+        # @param dots [String] the range separator, either ".." or "..."
+        # @return [Range] the resulting range
         def range(value, dots)
           Range.new(*value.split(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?('..')
+          return "..." if value.include?("...")
+          return ".." if value.include?("..")
 
           nil
         end

data/lib/toller/filters/scope_handler.rb

@@ -1,11 +1,18 @@
 # 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.
+      #
+      # @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
       def call(collection, value, properties)
         scoped_name = properties[:scope_name] || properties[:field]
 

data/lib/toller/filters/where_handler.rb

@@ -1,11 +1,19 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Filters
     ##
     # Where handler for filter
-    #
     class WhereHandler
+      ##
+      # Applies a plain `where` clause to +collection+ for a non-scope filter.
+      #
+      # @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
       def call(collection, type, value, properties)
         field_name = properties[:field]
 
@@ -16,28 +24,61 @@ module Toller
 
       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

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,6 +31,13 @@ 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)
@@ -25,6 +46,8 @@ module Toller
       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/order_handler.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
 
 module Toller
+  # :nodoc:
   module Sorts
     ##
     # Order handler for filter
-    #
     class OrderHandler
+      ##
+      # Applies a plain `order` clause to +collection+ for a non-scope sort.
+      #
+      # @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
       def call(collection, direction, properties)
         field_name = properties[:field]
 

data/lib/toller/sorts/scope_handler.rb

@@ -1,11 +1,18 @@
 # 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.
+      #
+      # @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
       def call(collection, direction, properties)
         scoped_name = properties[:scope_name] || properties[:field]
 

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.0.0"
 end

data/lib/toller.rb

@@ -1,26 +1,30 @@
 # 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/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"
 
 ##
 # Toller
 #
 # Query param based filtering and sorting
-#
 module Toller
   extend ActiveSupport::Concern
 
+  ##
+  # 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 +34,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.0.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: []
@@ -65,8 +52,13 @@ files:
 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 +66,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: []