filterameter 1.0.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50c824121830196b05ccb71f43495ad4d5197f85fe9d31456edc549fd2462a59
-  data.tar.gz: 4bb268b89c285e6542b0347bb3c52ca903f4d9be517f33b6303a76200b36f6c6
+  metadata.gz: 4184e23f30b4d9771a19a4a5c48bff17fb32b8dabc7d9ed3895beadcfb859d14
+  data.tar.gz: b62d21e81555a74e9f7e151355093ac9f77f44b774a880a5061832b2c1411fee
 SHA512:
-  metadata.gz: 21e92b0610890ed0ccbd8e3bdba68864de0c28d1c1ea42af40e51e696b0950c0ed6dd2d085673e493f400ca875d0307eeaaf9b844d021f1ae0d2fe11d53420c7
-  data.tar.gz: 77edd1277a98e49ab6c6425fe387404176477afc9050bafbb4d3d0eb34268d0e0e4a1f2983fb3b4951a0c9e7c88a0309464ab11112d67ae401ebcb75f7a74617
+  metadata.gz: da210337a494a23ff4779a935e1ff1c281894b9e021c395658e9204ca71c5358f77ccbe6e7623e8afea03c82e6077d8a7df0b3b49df9ae47addb271795fd17f8
+  data.tar.gz: 3264ea77862d726d0b31ec2802089f627be2187290dce49704995684549dc1afdaa956f1775369bca2872a02cdc33184278c27f198b0edb8fdd5d7d7ebabc698

data/README.md

@@ -1,8 +1,10 @@
 [![Gem Version](https://badge.fury.io/rb/filterameter.svg)](https://badge.fury.io/rb/filterameter)
 [![RuboCop](https://github.com/RockSolt/filterameter/workflows/RuboCop/badge.svg)](https://github.com/RockSolt/filterameter/actions?query=workflow%3ARuboCop)
 [![RSpec](https://github.com/RockSolt/filterameter/workflows/RSpec/badge.svg)](https://github.com/RockSolt/filterameter/actions?query=workflow%3ARSpec)
+[![Ruby Users Forum](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fwww.rubyforum.org&style=flat&logo=discourse&label=Ruby%20Users%20Forum)](https://www.rubyforum.org/tag/filterameter)
 
 # Filterameter
+
 Filterameter provides declarative filters for Rails controllers to reduce boilerplate code and increase readability. How many times have you seen (or written) this controller action?
 
 ```ruby
@@ -33,6 +35,7 @@ It's redundant code and a bit of a pain to write and maintain. Not to mention wh
 Simplify and speed development of Rails controllers by making filter parameters declarative with Filterameter.
 
 ## Table of Contents
+
 - [Getting Started](#getting-started)
 - [Usage](#usage)
   - [Filtering Options](#filtering-options)
@@ -42,13 +45,16 @@ Simplify and speed development of Rails controllers by making filter parameters
     - [Partial](#partial)
     - [Range](#range)
     - [Sortable](#sortable)
+    - [Converters](#converters)
   - [Scope Filters](#scope-filters)
   - [Sorting](#sorting)
   - [Building the Query](#building-the-query)
+  - [Building Links](#building-links)
   - [Specifying the Model](#specifying-the-model)
 - [Configuration](#configuration)
 - [Testing Declarations](#testing-declarations)
 - [Forms and Query Parameters](#forms-and-query-parameters)
+- [Community](#community)
 - [Contribute](#contribute)
 - [License](#license)
 
@@ -57,6 +63,7 @@ Simplify and speed development of Rails controllers by making filter parameters
 This gem requires Rails 6.1+, and works with ActiveRecord.
 
 ### Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -64,16 +71,19 @@ gem 'filterameter'
 ```
 
 And then execute:
+
 ```bash
 $ bundle install
 ```
 
 Or install it yourself as:
+
 ```bash
 $ gem install filterameter
 ```
 
 ## Usage
+
 Include module `Filterameter::DeclarativeFilters` in the controller to provide the filter DSL. It can be included in the `ApplicationController` to make the functionality available to all controllers or it can be mixed in on a case-by-case basis.
 
 ```ruby
@@ -82,6 +92,9 @@ Include module `Filterameter::DeclarativeFilters` in the controller to provide t
   filter :brand_name, association: :brand, name: :name
   filter :on_sale, association: :price, validates: [{ numericality: { greater_than: 0 } },
                                                     { numericality: { less_than: 100 } }]
+  filter :amount do |value|
+    value.is_a?(String) ? value.delete(",") : value
+  end
 ```
 
 Filters without options can be declared all at once with `filters`:
@@ -97,6 +110,7 @@ filters :color,
 The following options can be specified for each filter.
 
 #### name
+
 If the name of the parameter is different than the name of the attribute or scope, then use the name parameter to specify the name of the attribute or scope. For example, if the attribute name is `current_status` but the filter is exposed simply as `status` use the following:
 
 ```ruby
@@ -106,6 +120,7 @@ filter :status, name: :current_status
 This option can also be helpful with nested filters so that the query parameter can be prefixed with the model name. See the `association` option for an example.
 
 #### association
+
 If the attribute or scope is nested, it can be referenced by naming the association. For example, if the manager_id attribute lives on an employee's department record, use the following:
 
 ```ruby
@@ -123,6 +138,7 @@ If an association is a `has_many` [the distinct method](https://api.rubyonrails.
 _Limitation:_ If there is more than one association to the same table _and_ both associations can be part of the query, then you cannot use a nested filter directly. Instead, build a scope that disambiguates the associations then build a filter against that scope.
 
 #### validates
+
 If the filter value should be validated, use the `validates` option along with [ActiveModel validations](https://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates). Here's an example of the inclusion validator being used to restrict sizes:
 
 ```ruby
@@ -135,9 +151,10 @@ The `inclusion` validator has been overridden to provide the additional option `
 filter :size, validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
 ```
 
-
 #### partial
+
 Specify the partial option if the filter should do a partial search (SQL's `LIKE`). The partial option accepts a hash to specify the search behavior. Here are the available options:
+
 - match: anywhere (default), from_start, dynamic
 - case_sensitive: true, false (default)
 
@@ -150,14 +167,17 @@ filter :reason, partial: { match: :dynamic, case_sensitive: true }
 ```
 
 The `match` options defines where you are searching (which then controls where the wildcard(s) appear):
+
 - anywhere: adds wildcards at the start and end, for example '%blue%'
 - from_start: adds a wildcard at the end, for example 'blue%'
 - dynamic: adds no wildcards; this enables the client to fully control the search string
 
 #### range
+
 Specify the range option to enable searches by ranges, minimum values, or maximum values. (All of these are inclusive. A search for a minimum value of $10.00 would include all items priced at $10.00.)
 
 Here are the available options:
+
 - true: enable ranges, minimum values, and/or maximum values
 - min_only: enables minimum values
 - max_only: enables maximum values
@@ -185,6 +205,17 @@ The following filters are not sortable:
 - scope filters (see [_Sorting with a Scope_](#sorting-with-a-scope))
 - filters with collection associations
 
+#### Converters
+
+If the filter value needs to be converted before being applied to the query, a converter block can be provided. The block should take the parameter value as an argument and return the converted value.
+
+For example, if the amount filter should remove commas from the value before applying it to the query, the declaration would look like this:
+
+```ruby
+filter :amount do |value|
+  value.is_a?(String) ? value.delete(",") : value
+end
+```
 
 ### Scope Filters
 
@@ -261,7 +292,6 @@ There are two ways to apply the filters and build the query, depending on how mu
 - Use the `build_filtered_query` before action callback
 - Manually call `build_query_from_filters`
 
-
 #### Use the `build_filtered_query` before action callback
 
 Add before action callback `build_filtered_query` for controller actions that should build the query. This can be done either in the `ApplicationController` or on a case-by-case basis.
@@ -335,6 +365,35 @@ The starting query is also a good place to provide any includes to enable eager
 
 Note that the starting query provides the model, so the model is not looked up and the `model_name` declaration in not needed.
 
+### Building Links
+
+Because Filterameter knows all about the filter and sort parameters in the query string, it is also able to build similar links. For example, sorting by a different column or direction should still carry all the same filters and page parameters; or pagination might require links with the same filtering and sorting but a different page number or page size.
+
+The `DeclarativeFilters` mixin exposes method `query_parameters`, which returns an instance of QueryParameters. The object can be passed to views to build pagination and sort links.
+
+The following methods are available:
+
+| Method     | Updates   | Preserves                    | Resets |
+| ---------- | --------- | ---------------------------- | ------ |
+| `for_page` | Page      | Filters, sort, and page size | —      |
+| `for_size` | Page size | Filters and sort             | Page   |
+| `for_sort` | Sort      | Filters and page size        | Page   |
+
+```ruby
+products_path(query_parameters.for_page(2))
+products_path(query_parameters.for_size(100))
+products_path(query_parameters.for_sort(:name, initial_direction: :asc))
+```
+
+`for_sort` cycles a field from its initial direction to the opposite direction and then removes the explicit sort. When a controller default sort is active, it removes the explicit sort only when doing so changes the effective ordering; otherwise it returns the field to the initial direction so the link is not a no-op.
+
+#### Sort Helpers
+
+The `query_parameters` object also provides helpers to provide info on the current sort for each field name. The following methods are available:
+
+- `sorted_by?(name)` - returns true if the current sort includes the specified name
+- `sort_direction(name)` - returns the current sort direction for the given name, or nil if the name is not part of the current sort
+
 ### Specifying the Model
 
 Rails conventions are used to determine the controller's model. For example, the PhotosController builds a query against the Photo model. If a controller is namespaced, the model will first be looked up without the namespace, then with the namespace.
@@ -349,11 +408,13 @@ _Important:_ If the `filter_model` declaration is used, it must be before any fi
 
 ## Configuration
 
-There are three configuration options:
+The following configuration options are available:
 
 - action_on_undeclared_parameters
 - action_on_validation_failure
 - filter_key
+- pagination_page_param
+- pagination_size_param
 
 The configuration options can be set in an initializer, an environment file, or in `application.rb`.
 
@@ -368,6 +429,8 @@ Filterameter.configure do |config|
   config.action_on_undeclared_parameters = :log
   config.action_on_validation_failure = :log
   config.filter_key = :f
+  config.pagination_page_param = %i[page number]
+  config.pagination_size_param = %i[page size]
 end
 ```
 
@@ -387,6 +450,23 @@ If the filter parameters are NOT nested, set this to false. Doing so will restri
 those that have been declared, meaning undeclared parameters are ignored (and the action_on_undeclared_parameters
 configuration option does not come into play).
 
+#### Pagination Parameters
+
+`pagination_page_param` and `pagination_size_param` are arrays describing the parameter paths used for the page
+number and page size. They default to `%i[page number]` and `%i[page size]`, which produce `page[number]` and
+`page[size]`. Page-size values are preserved when generating page and sort links.
+
+For top-level parameters, such as the common Pagy or Kaminari convention, configure single-key paths (which do not need to be arrays):
+
+```ruby
+Filterameter.configure do |config|
+  config.pagination_page_param = :page
+  config.pagination_size_param = :per_page
+end
+```
+
+This produces `page=2&per_page=50`. Parameter paths may use any nesting or key names, except that they cannot be rooted at the configured `filter_key`. The filter namespace is reserved for filter and sort parameters.
+
 ## Testing Declarations
 
 The declarations can be tested for each controller, catching typos, incorrectly defined scopes, or any other issues. Method `declarations_validator` is added to each controller, and a single controller test can be added to validate all the declarations for that controller.
@@ -443,6 +523,10 @@ For example, the following sorts by size descending:
 
 `/widgets?filter[sort]=-size`
 
+## Community
+
+Join us in the `filterameter` category on the [Ruby Users Forum](https://www.rubyforum.org/tag/filterameter).
+
 ## Contribute
 
 Feedback, feature requests, and proposed changes are welcomed. Please use the [issue tracker](https://github.com/RockSolt/filterameter/issues)
@@ -474,4 +558,5 @@ bundle exec appraisal rspec
 ```
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/filterameter/configuration.rb

@@ -7,6 +7,8 @@ module Filterameter
   # *   action_on_undeclared_parameters
   # *   action_on_validation_failure
   # *   filter_key
+  # *   pagination_page_param
+  # *   pagination_size_param
   #
   # ## Action on Undeclared Parameters
   #
@@ -29,21 +31,77 @@ module Filterameter
   # restrict the filter parameters to only those that have been declared, meaning
   # undeclared parameters are ignored (and the action_on_undeclared_parameters
   # configuration option does not come into play).
+  #
+  # ## Pagination Parameters
+  #
+  # Pagination parameter paths are arrays of keys. They default to
+  # `[:page, :number]` and `[:page, :size]`, producing the nested parameters
+  # `page[number]` and `page[size]`. Use a single-key path, such as `[:page]`
+  # and `[:per_page]`, for top-level pagination parameters. Pagination paths
+  # cannot be rooted at the configured filter key.
   class Configuration
-    attr_accessor :action_on_undeclared_parameters, :action_on_validation_failure, :filter_key
+    attr_accessor :action_on_undeclared_parameters, :action_on_validation_failure
+    attr_reader :pagination_page_param, :pagination_size_param, :filter_key
 
     def initialize
-      @action_on_undeclared_parameters =
-        @action_on_validation_failure =
-          if Rails.env.development?
-            :log
-          elsif Rails.env.test?
-            :raise
-          else
-            false
-          end
+      @action_on_undeclared_parameters = @action_on_validation_failure = default_action
 
       @filter_key = :filter
+      configure_pagination
+    end
+
+    def filter_key=(key)
+      validate_pagination_paths(key)
+      @filter_key = key
+    end
+
+    def pagination_page_param=(param)
+      path = pagination_param(param)
+      validate_pagination_path(path, :pagination_page_param)
+      @pagination_page_param = path
+    end
+
+    def pagination_size_param=(param)
+      path = pagination_param(param)
+      validate_pagination_path(path, :pagination_size_param)
+      @pagination_size_param = path
+    end
+
+    private
+
+    def default_action
+      if Rails.env.development?
+        :log
+      elsif Rails.env.test?
+        :raise
+      else
+        false
+      end
+    end
+
+    def configure_pagination
+      self.pagination_page_param = %i[page number]
+      self.pagination_size_param = %i[page size]
+    end
+
+    def pagination_param(param)
+      path = Array(param).map(&:to_sym)
+      raise ArgumentError, 'pagination parameter path cannot be empty' if path.empty?
+
+      path
+    end
+
+    def validate_pagination_paths(filter_key)
+      return unless filter_key
+
+      validate_pagination_path(@pagination_page_param, :pagination_page_param, filter_key)
+      validate_pagination_path(@pagination_size_param, :pagination_size_param, filter_key)
+    end
+
+    def validate_pagination_path(path, name, filter_key = @filter_key)
+      return unless filter_key && path&.first == filter_key.to_sym
+
+      raise ArgumentError, "#{name} cannot be nested under filter_key (#{filter_key.inspect})"
     end
   end
 end

data/lib/filterameter/declarative_filters.rb

@@ -61,8 +61,8 @@ module Filterameter
       #     filter :department_name, partial: :from_start
       #     filter :reason, partial: { match: :dynamic, case_sensitive: true }
       #     filter :price, range: true
-      def filter(name, options = {})
-        filter_coordinator.add_filter(name, options)
+      def filter(name, options = {}, &converter)
+        filter_coordinator.add_filter(name, options.merge(converter:))
       end
 
       # Declares a list of filters without options. Filters that require options must be declared with `filter`.
@@ -161,18 +161,28 @@ module Filterameter
       self.class.filter_coordinator.build_query(filter_parameters, starting_query)
     end
 
-    def filter_parameters
-      filter_key = Filterameter.configuration.filter_key
+    # Returns the current Filterameter query state for pagination and sortable links.
+    # Its sort is the requested sort, or this controller's declared default when none was requested.
+    def query_parameters
+      Filterameter::QueryParameters.new(
+        filterameter_request_parameters,
+        default_sort: self.class.filter_coordinator.default_sort_parameters
+      )
+    end
 
-      if filter_key
-        params.to_unsafe_h.fetch(filter_key, {})
-      else
-        params.to_unsafe_h.slice(*self.class.filter_coordinator.filter_parameter_names, :sort)
-      end
+    def filter_parameters
+      filterameter_request_parameters.filter_and_sort_params
     end
 
     private
 
+    def filterameter_request_parameters
+      @filterameter_request_parameters ||= Filterameter::RequestParameters.new(
+        params,
+        declared_filter_parameter_names: self.class.filter_coordinator.filter_parameter_names
+      )
+    end
+
     def build_filtered_query
       var_name = "@#{self.class.filter_coordinator.query_variable_name}"
       starting_query = instance_variable_get(var_name)

data/lib/filterameter/filter_coordinator.rb

@@ -17,6 +17,7 @@ module Filterameter
   # The coordinators encapsulate references to the Query Builder and Filter Registry to keep the namespace clean for
   # controllers that implement filter parameters.
   class FilterCoordinator
+    attr_reader :default_sort_parameters
     attr_writer :query_variable_name
 
     delegate :add_filter, :add_sort, :filter_parameter_names, to: :registry
@@ -40,9 +41,12 @@ module Filterameter
     end
 
     def default_sort=(sort_and_direction_pairs)
-      @default_sort = sort_and_direction_pairs.map do |name, direction|
-        Filterameter::Helpers::RequestedSort.new(name, direction)
-      end
+      normalized = Helpers::SortNormalizer.normalize(sort_and_direction_pairs).freeze
+
+      @default_sort_parameters = normalized
+      @default_sort = normalized.map do |name, direction|
+        RequestedSort.new(name, direction)
+      end.freeze
     end
 
     def declarations_validator

data/lib/filterameter/filter_declaration.rb

@@ -16,7 +16,7 @@ module Filterameter
   class FilterDeclaration
     VALID_RANGE_OPTIONS = [true, :min_only, :max_only].freeze
 
-    attr_reader :name, :parameter_name, :association, :validations
+    attr_reader :name, :parameter_name, :association, :validations, :converter
 
     def initialize(parameter_name, options, range_type: nil)
       @parameter_name = parameter_name.to_s
@@ -29,6 +29,7 @@ module Filterameter
       @raw_range = options[:range]
       @range_type = range_type
       @sortable = options.fetch(:sortable, true)
+      @converter = options[:converter]
     end
 
     def nested?
@@ -88,7 +89,7 @@ module Filterameter
     private
 
     def validate_options(options)
-      options.assert_valid_keys(:name, :association, :validates, :partial, :range, :sortable)
+      options.assert_valid_keys(:name, :association, :validates, :partial, :range, :sortable, :converter)
       validate_range(options[:range]) if options.key?(:range)
     end
 

data/lib/filterameter/filter_factory.rb

@@ -15,7 +15,7 @@ module Filterameter
       if declaration.nested?
         build_nested_filter(declaration, context)
       else
-        build_filter(@model_class, declaration, context.scope?)
+        build_filter_or_scope_filter(@model_class, declaration, context.scope?)
       end
     end
 
@@ -23,23 +23,29 @@ module Filterameter
 
     def build_nested_filter(declaration, context)
       model = context.model_from_association
-      filter = build_filter(model, declaration, context.scope?)
+      filter = build_filter_or_scope_filter(model, declaration, context.scope?)
       nested_filter_class = context.any_collections? ? Filters::NestedCollectionFilter : Filters::NestedFilter
 
       nested_filter_class.new(declaration.association, model, filter)
     end
 
-    def build_filter(model, declaration, declaration_is_a_scope) # rubocop:disable Metrics/MethodLength
+    def build_filter_or_scope_filter(model, declaration, declaration_is_a_scope)
       if declaration_is_a_scope
         build_scope_filter(model, declaration)
-      elsif declaration.partial_search?
-        Filterameter::Filters::MatchesFilter.new(declaration.name, declaration.partial_options)
+      else
+        build_filter(model, declaration)
+      end
+    end
+
+    def build_filter(model, declaration)
+      if declaration.partial_search?
+        Filterameter::Filters::MatchesFilter.new(declaration.name, declaration.partial_options, &declaration.converter)
       elsif declaration.minimum_range?
-        Filterameter::Filters::MinimumFilter.new(model, declaration.name)
+        Filterameter::Filters::MinimumFilter.new(model, declaration.name, &declaration.converter)
       elsif declaration.maximum_range?
-        Filterameter::Filters::MaximumFilter.new(model, declaration.name)
+        Filterameter::Filters::MaximumFilter.new(model, declaration.name, &declaration.converter)
       else
-        Filterameter::Filters::AttributeFilter.new(declaration.name)
+        Filterameter::Filters::AttributeFilter.new(declaration.name, &declaration.converter)
       end
     end
 
@@ -48,9 +54,9 @@ module Filterameter
     def build_scope_filter(model, declaration)
       number_of_arguments = model.method(declaration.name).arity
       if number_of_arguments < 1
-        Filterameter::Filters::ConditionalScopeFilter.new(declaration.name)
+        Filterameter::Filters::ConditionalScopeFilter.new(declaration.name, &declaration.converter)
       elsif number_of_arguments == 1
-        Filterameter::Filters::ScopeFilter.new(declaration.name)
+        Filterameter::Filters::ScopeFilter.new(declaration.name, &declaration.converter)
       else
         raise Filterameter::DeclarationErrors::FilterScopeArgumentError.new(model.name, declaration.name)
       end

data/lib/filterameter/filters/arel_filter.rb

@@ -10,9 +10,10 @@ module Filterameter
       include Filterameter::Errors
       include Filterameter::Filters::AttributeValidator
 
-      def initialize(model, attribute_name)
+      def initialize(model, attribute_name, &converter)
         @attribute_name = attribute_name
         @arel_attribute = model.arel_table[attribute_name]
+        @converter = converter
       end
     end
   end

data/lib/filterameter/filters/attribute_filter.rb

@@ -9,11 +9,13 @@ module Filterameter
       include Filterameter::Errors
       include AttributeValidator
 
-      def initialize(attribute_name)
+      def initialize(attribute_name, &converter)
         @attribute_name = attribute_name
+        @converter = converter
       end
 
       def apply(query, value)
+        value = @converter.call(value) if @converter
         query.where(@attribute_name => value)
       end
     end

data/lib/filterameter/filters/conditional_scope_filter.rb

@@ -8,11 +8,13 @@ module Filterameter
     class ConditionalScopeFilter
       include Filterameter::Errors
 
-      def initialize(scope_name)
+      def initialize(scope_name, &converter)
         @scope_name = scope_name
+        @converter = converter
       end
 
       def apply(query, value)
+        value = @converter.call(value) if @converter
         return query unless ActiveModel::Type::Boolean.new.cast(value)
 
         query.public_send(@scope_name)

data/lib/filterameter/filters/matches_filter.rb

@@ -9,14 +9,16 @@ module Filterameter
       include Filterameter::Errors
       include Filterameter::Filters::AttributeValidator
 
-      def initialize(attribute_name, options)
+      def initialize(attribute_name, options, &converter)
         @attribute_name = attribute_name
         @prefix = options.match_anywhere? ? '%' : nil
         @suffix = options.match_anywhere? || options.match_from_start? ? '%' : nil
         @case_sensitive = options.case_sensitive?
+        @converter = converter
       end
 
       def apply(query, value)
+        value = @converter.call(value) if @converter
         arel = query.arel_table[@attribute_name].matches("#{@prefix}#{value}#{@suffix}", false, @case_sensitive)
         query.where(arel)
       end

data/lib/filterameter/filters/maximum_filter.rb

@@ -7,6 +7,7 @@ module Filterameter
     # Class MaximumFilter adds criteria for all values greater than or equal to a maximum.
     class MaximumFilter < ArelFilter
       def apply(query, value)
+        value = @converter.call(value) if @converter
         query.where(@arel_attribute.lteq(value))
       end
     end

data/lib/filterameter/filters/minimum_filter.rb

@@ -7,6 +7,7 @@ module Filterameter
     # Class MinimumFilter adds criteria for all values greater than or equal to a minimum.
     class MinimumFilter < ArelFilter
       def apply(query, value)
+        value = @converter.call(value) if @converter
         query.where(@arel_attribute.gteq(value))
       end
     end

data/lib/filterameter/filters/scope_filter.rb

@@ -8,11 +8,13 @@ module Filterameter
     class ScopeFilter
       include Filterameter::Errors
 
-      def initialize(scope_name)
+      def initialize(scope_name, &converter)
         @scope_name = scope_name
+        @converter = converter
       end
 
       def apply(query, value)
+        value = @converter.call(value) if @converter
         query.public_send(@scope_name, value)
       end
 

data/lib/filterameter/helpers/sort_normalizer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Helpers
+    # Normalizes the hash representation used for declared and current sorts.
+    module SortNormalizer
+      module_function
+
+      def normalize(sort)
+        return if sort.nil?
+        raise ArgumentError, 'default_sort must be a hash of sort names and directions' unless sort.is_a?(Hash)
+
+        sort.each_with_object({}) do |(name, direction), result|
+          result[name.to_sym] = SortSerializer.normalize_direction(direction)
+        end
+      end
+    end
+  end
+end

data/lib/filterameter/helpers/sort_serializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Helpers
+    # # Sort Serializer
+    #
+    # Handles conversion between sort string representation and hash representation.
+    #
+    # String format follows standard conventions:
+    # - "name" or "+name" for ascending
+    # - "-name" for descending
+    #
+    # Hash format:
+    # - { name: :asc } for ascending
+    # - { name: :desc } for descending
+    module SortSerializer
+      module_function
+
+      # Converts a sort string to a hash with name and direction
+      #
+      # @param sort_string [String] the sort string (e.g., "name", "-name")
+      # @return [Hash] hash with :name and :direction keys
+      #
+      # @example
+      #   deserialize("name")     #=> { name: "name", direction: :asc }
+      #   deserialize("-name")    #=> { name: "name", direction: :desc }
+      def deserialize(sort_string)
+        parsed = sort_string.to_s.match(/(?<sign>[+|-]?)(?<name>\w+)/)
+        {
+          name: parsed['name'],
+          direction: parsed['sign'] == '-' ? :desc : :asc
+        }
+      end
+
+      # Converts a name and direction to a sort string
+      #
+      # @param name [String, Symbol] the sort field name
+      # @param direction [Symbol, String] the sort direction (:asc or :desc)
+      # @return [String] the serialized sort string
+      # @raise [ArgumentError] if direction is not :asc or :desc
+      #
+      # @example
+      #   serialize("name", :asc)   #=> "name"
+      #   serialize("name", :desc)  #=> "-name"
+      def serialize(name, direction)
+        case normalize_direction(direction)
+        when :asc then name.to_s
+        when :desc then "-#{name}"
+        end
+      end
+
+      def normalize_direction(direction)
+        normalized = direction.to_sym if direction.respond_to?(:to_sym)
+        return normalized if %i[asc desc].include?(normalized)
+
+        raise ArgumentError, 'direction must be :asc or :desc'
+      end
+    end
+  end
+end

data/lib/filterameter/query_builder.rb

@@ -36,7 +36,7 @@ module Filterameter
     end
 
     def parse_sorts(sorts)
-      Array.wrap(sorts).map { |sort| Helpers::RequestedSort.parse(sort) }
+      Array.wrap(sorts).map { |sort| RequestedSort.parse(sort) }
     end
 
     def apply_filters(query, filters)

data/lib/filterameter/query_parameters.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # # Query Parameters
+  #
+  # Because Filterameter knows all about the filter and sort parameters in the query string, it is also able to
+  # generate query parameters for similar links. For example, sorting by a different column or direction should still
+  # carry all the same filters and page parameters; or pagination might require links with the same filtering and
+  # sorting but a different page number or page size.
+  #
+  # QueryParameters is a value object containing the current query parameters. It provides helpers for generating
+  # updated parameters:
+  #
+  # - `for_sort`: updates sorting, preserves filters and page size, and resets the page
+  # - `for_page`: updates the page, preserves filters, sorting, and page size
+  # - `for_size`: updates page size, preserves filters and sorting, and resets the page
+  #
+  # The return of each method are the arguments that can be passed to Rails path builders.
+  class QueryParameters
+    attr_reader :filter_params, :sort_order, :requested_sort_order
+
+    def initialize(request_parameters, default_sort: nil,
+                   sort_strategy: SortStrategies::ReplacementSortStrategy.new)
+      @request_params = request_parameters
+      @sort_strategy = sort_strategy
+      @default_sort = Helpers::SortNormalizer.normalize(default_sort) || {}
+      @filter_params = @request_params.filter_params
+      raw_sort = @request_params.sort_params
+      @sort_requested = raw_sort.present?
+      @requested_sort_order = @sort_requested ? parse_sort(raw_sort) : {}
+      @sort_order = @sort_requested ? @requested_sort_order : @default_sort
+    end
+
+    # Returns the current filter and sort state with the page number replaced.
+    def for_page(page_number)
+      write_at_path(@request_params.filter_sort_and_pagination_params, @request_params.pagination_page_path,
+                    page_number)
+    end
+
+    def for_size(page_size)
+      write_at_path(current_query_params_without_page, @request_params.pagination_size_path, page_size)
+    end
+
+    # Returns the current filter state with the sort updated according to the sort strategy. The page number is
+    # omitted, allowing the pagination library to use its configured first page.
+    def for_sort(name, initial_direction: :asc)
+      normalized_direction = Helpers::SortSerializer.normalize_direction(initial_direction)
+      result = @sort_strategy.call(self, name, normalized_direction)
+      override_sort(current_query_params_without_page, result)
+    end
+
+    def sorted_by?(name)
+      @sort_order.key?(name.to_sym)
+    end
+
+    def sort_requested?
+      @sort_requested
+    end
+
+    def default_sort_order
+      @default_sort
+    end
+
+    def sort_direction(name)
+      @sort_order[name.to_sym]
+    end
+
+    private
+
+    def current_query_params_without_page
+      delete_at_path(@request_params.filter_sort_and_pagination_params, @request_params.pagination_page_path)
+    end
+
+    # Methods `write_at_path` and `delete_at_path` introduce a fair amount of the complexity here. If this could assume
+    # how the pagination parameters are stored, it could be much simpler. But the configuration allows for params at the
+    # root (such as `page` and `per_page`) or nested under a key (such as `page[number]` and `page[size]`).
+    #
+    # All of which is to say, you can ignore these methods for the most part. The write method is also used to override
+    # the sort, since that can also optionally be nested.
+
+    def write_at_path(params, path, value)
+      container = path[0...-1].reduce(params) do |hash, key|
+        hash[key] = {} unless hash[key].is_a?(Hash)
+        hash[key]
+      end
+      container[path.last] = value
+      params
+    end
+
+    def delete_at_path(params, path)
+      return params unless params.is_a?(Hash)
+
+      key = path.first
+      if path.one?
+        params.delete(key)
+      elsif (nested_params = params[key]).is_a?(Hash)
+        delete_at_path(nested_params, path.drop(1))
+        params.delete(key) if nested_params.empty?
+      end
+      params
+    end
+
+    def override_sort(params, sort)
+      path = @request_params.sort_path
+      if sort.empty?
+        delete_at_path(params, path)
+      else
+        serialized = sort.map { |name, dir| Helpers::SortSerializer.serialize(name, dir) }
+        write_at_path(params, path, serialized.one? ? serialized.first : serialized)
+      end
+    end
+
+    def parse_sort(sort)
+      Array.wrap(sort).each_with_object({}) do |s, hash|
+        parsed = RequestedSort.parse(s.to_s)
+        hash[parsed.name.to_sym] = parsed.direction
+      end
+    end
+  end
+end

data/lib/filterameter/request_parameters.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # # Request Parameters
+  #
+  # Value object that normalizes incoming request params and provides structured access to
+  # Filterameter filters, sorting, and pagination.
+  #
+  # By default, filter and sort params are read from the configured filter-key namespace, while
+  # pagination params remain at the top level. When that namespace is disabled, all parameter types
+  # are read from the top level.
+  #
+  # Exposes the configured pagination and sort parameter paths for link generation.
+  class RequestParameters
+    attr_reader :pagination_page_path, :pagination_size_path, :sort_path
+
+    def initialize(params, declared_filter_parameter_names: nil)
+      @params = normalize(params)
+      @declared_filter_parameter_names = normalize_declared_names(declared_filter_parameter_names)
+      config = Filterameter.configuration
+      @filter_key = config.filter_key
+      @sort_path = sort_parameter_path.freeze
+      @pagination_page_path = config.pagination_page_param.dup.freeze
+      @pagination_size_path = config.pagination_size_param.dup.freeze
+      @pagination_roots = pagination_roots.freeze
+    end
+
+    # Returns the filter params, excluding sort and pagination.
+    def filter_params
+      filter_and_sort_params.except(:sort)
+    end
+
+    # Returns the raw sort value from the request (a string, array of strings, or nil).
+    def sort_params
+      filter_and_sort_params[:sort]
+    end
+
+    # Returns the filter and sort params, excluding pagination.
+    def filter_and_sort_params
+      params = if @filter_key
+                 @params.fetch(filter_key) { @params.fetch(filter_key.to_s, {}) }
+               else
+                 flat_filter_and_sort_params
+               end
+
+      params.deep_dup
+    end
+
+    # Returns the filter, sort, and pagination params — the full set needed for link generation.
+    def filter_sort_and_pagination_params
+      return flat_query_params.deep_dup unless @filter_key
+
+      @params.slice(filter_key, *@pagination_roots).deep_dup
+    end
+
+    private
+
+    def normalize(params)
+      hash = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+      hash.deep_symbolize_keys
+    end
+
+    def filter_key
+      @filter_key.to_sym
+    end
+
+    def normalize_declared_names(names)
+      names&.map(&:to_sym)
+    end
+
+    def sort_parameter_path
+      @filter_key ? [@filter_key.to_sym, :sort] : [:sort]
+    end
+
+    def pagination_roots
+      [@pagination_page_path.first, @pagination_size_path.first].uniq
+    end
+
+    def flat_filter_and_sort_params
+      params = @params.except(*@pagination_roots)
+      return params unless @declared_filter_parameter_names
+
+      params.slice(*@declared_filter_parameter_names, :sort)
+    end
+
+    def flat_query_params
+      return @params unless @declared_filter_parameter_names
+
+      result = @params.slice(*@declared_filter_parameter_names, :sort)
+      [@pagination_page_path, @pagination_size_path].each do |path|
+        value = value_at_path(@params, path)
+        write_at_path(result, path, value) unless value.nil?
+      end
+      result
+    end
+
+    def value_at_path(params, path)
+      path.reduce(params) { |value, key| value.is_a?(Hash) ? value[key] : nil }
+    end
+
+    def write_at_path(params, path, value)
+      container = path[0...-1].reduce(params) { |hash, key| hash[key] ||= {} }
+      container[path.last] = value
+    end
+  end
+end

data/lib/filterameter/requested_sort.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # A parsed sort request containing a field name and direction.
+  class RequestedSort
+    attr_reader :name, :direction
+
+    def self.parse(sort)
+      result = Helpers::SortSerializer.deserialize(sort)
+      new(result[:name], result[:direction])
+    end
+
+    def initialize(name, direction)
+      @name = name
+      @direction = direction
+      freeze
+    end
+  end
+end

data/lib/filterameter/sort_strategies/replacement_sort_strategy.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module SortStrategies
+    # # Replacement Sort Strategy
+    #
+    # The ReplacementSortStrategy replaces the current sort with the requested sort. If the field is not currently being
+    # sorted, it will be added in the initial direction.If the field is currently being sorted in the initial
+    # sorted in the initial direction, the direction will be toggled; if the field is currently being sorted in the
+    #  opposite direction, the sort will be removed unless doing so would immediately restore the same default sort, in
+    #  which case it returns to the initial direction instead.
+    class ReplacementSortStrategy
+      def call(query_params, sort_field, initial_direction)
+        return { sort_field => initial_direction } unless query_params.sorted_by?(sort_field)
+
+        if query_params.sort_direction(sort_field) == initial_direction
+          { sort_field => opposite_direction(initial_direction) }
+        else
+          return { sort_field => initial_direction } unless query_params.sort_requested?
+          if query_params.requested_sort_order == query_params.default_sort_order
+            return { sort_field => initial_direction }
+          end
+
+          {}
+        end
+      end
+
+      private
+
+      def opposite_direction(direction)
+        direction == :asc ? :desc : :asc
+      end
+    end
+  end
+end

data/lib/filterameter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Filterameter
-  VERSION = '1.0.3'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.2.0
 platform: ruby
 authors:
 - Todd Kummer
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -178,17 +178,22 @@ files:
 - lib/filterameter/filters/scope_filter.rb
 - lib/filterameter/helpers/declaration_with_model.rb
 - lib/filterameter/helpers/joins_values_builder.rb
-- lib/filterameter/helpers/requested_sort.rb
+- lib/filterameter/helpers/sort_normalizer.rb
+- lib/filterameter/helpers/sort_serializer.rb
 - lib/filterameter/log_subscriber.rb
 - lib/filterameter/options/partial_options.rb
 - lib/filterameter/parameters_base.rb
 - lib/filterameter/query_builder.rb
+- lib/filterameter/query_parameters.rb
 - lib/filterameter/registries/filter_registry.rb
 - lib/filterameter/registries/registry.rb
 - lib/filterameter/registries/sort_registry.rb
 - lib/filterameter/registries/sub_registry.rb
+- lib/filterameter/request_parameters.rb
+- lib/filterameter/requested_sort.rb
 - lib/filterameter/sort_declaration.rb
 - lib/filterameter/sort_factory.rb
+- lib/filterameter/sort_strategies/replacement_sort_strategy.rb
 - lib/filterameter/sorts/attribute_sort.rb
 - lib/filterameter/sorts/scope_sort.rb
 - lib/filterameter/validators/inclusion_validator.rb
@@ -196,7 +201,9 @@ files:
 homepage: https://github.com/RockSolt/filterameter
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
+  mailing_list_uri: https://www.rubyforum.org/tag/filterameter
 rdoc_options: []
 require_paths:
 - lib

data/lib/filterameter/helpers/requested_sort.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  module Helpers
-    # # Reqested Sort
-    #
-    # Class RequestedSort parses the name and direction from a sort segment.
-    class RequestedSort
-      SIGN_AND_NAME = /(?<sign>[+|-]?)(?<name>\w+)/
-      attr_reader :name, :direction
-
-      def self.parse(sort)
-        parsed = sort.match SIGN_AND_NAME
-
-        new(parsed['name'],
-            parsed['sign'] == '-' ? :desc : :asc)
-      end
-
-      def initialize(name, direction)
-        @name = name
-        @direction = direction
-      end
-    end
-  end
-end