filterameter 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c02c45f5366abfe01e6858a4d70d932e585b219a27680f799f5b53056202322f
-  data.tar.gz: acff8ae1523f525d3f7d9415c32dd5d3fd9b707118498b38d78eff4ca05ccc97
+  metadata.gz: abb0f5a22c735d69e3e44625f0fd4a0cd451f35499677f4f0d51d5a7aff8ea3a
+  data.tar.gz: 359eefe9c128bd46651e475e6fc1620d145c68478429e8d49ab3d601fa95f2bb
 SHA512:
-  metadata.gz: 2923df8284998b1129cb3b66bb7166cd08ef8708b21a8a6af666c393c219178f38111802294bc051434cd5a33cf6e6853f593abd6415fa031329bc09fbab8a92
-  data.tar.gz: 7fc9483785d7226ce14d9d3eae2f04b6d99c9f3bbfecdcd886b10cb9302e2ad119958e8ee1092e566e64eacc7d218b0bf754a0eeabb8463525858dc9cfaf5ed2
+  metadata.gz: 3b11d1b2281e340ecc32ea75e37c857f888cce526fda98b4c2d96a5bbfd8a7ba0f2cbd901480c10eb8b6fc4ca4d48080e43f79f66e7bdb879819d407c896b237
+  data.tar.gz: 285384ed0b9506937406aa0d83744b99239666a4d84b7b0d6893bc1351ac26e227eb37cd1d9baa2c3e7be720fea36a9acc1a7b7d3979006fd8be0eaaa72dd21b

data/README.md

@@ -108,6 +108,20 @@ filter :sale_price, range: :max_only
 
 In the first example, query parameters could include <tt>price</tt>, <tt>price_min</tt>, and <tt>price_max</tt>.
 
+#### sortable
+
+By default most filters are sortable. To prevent an attribute filter from being sortable, set the option to false.
+
+```ruby
+filter :price, sortable: false
+```
+
+The following filters are not sortable:
+
+- scope filters (see [_Sorting with a Scope_](#sorting-with-a-scope))
+- filters with collection associations
+
+
 ### Scope Filters
 
 For scopes that do not take arguments, the filter should provide a boolean that indicates whether or not the scope should be invoked. For example, imagine a scope called `high_priority` with criteria that identifies high priority records. The scope would be invoked by the query parameters `high_priority=true`.
@@ -122,6 +136,60 @@ def self.recent(as_of_date)
 end
 ```
 
+### Sorting
+
+As noted above, most attribute filters are sortable by default. If no filter has been declared for an attribute, the `sort` declaration can be used. Use the same `name` and `association` options as needed.
+
+For example, the following declaration could be used on an activity controller to allow activities to be sorted by project created at.
+
+```ruby
+sort :project_created_at, name: :created_at, association: :project
+```
+
+Sorts without options can be declared all at once with `sorts`:
+
+```ruby
+sorts :created_at,
+      :updated_at,
+      :description
+```
+
+#### Sorting with a Scope
+
+Scopes can be used for sorting, but must be declared with `sort` (or `sorts`). For example, if a model included a scope called `by_created_at` you could add the following to the controller to expose it.
+
+```ruby
+sort :by_created_at
+```
+
+The `name` and `association` options can also be used. For example, if the scope was on the Project model it could also be used on a child Activity controller using the `association` option:
+
+```ruby
+sort :by_created_at, association: :project
+```
+
+Only singular associations are valid for sorting. A collection association could return multiple values, making the sort indeterminate.
+
+A scope that is used for sorting must accept a single argument. It will be passed either `:asc` or `:desc` depending on the parameter.
+
+The example scope above might be defined as follows:
+
+```ruby
+def self.by_created_at(dir)
+  order(created_at: dir)
+end
+```
+
+#### Default Sort
+
+A default sort can be declared using `default_sort`. The argument(s) should specify one or more of the declared sorts or sortable filters by name. By default, the order is ascending. If you want descending order, you can map the column name symbol to :desc.
+
+```ruby
+default_sort updated_at: :desc, :description
+```
+
+In order to provide consistent results, a sort is always applied. If no default is specified, it will use primary key descending.
+
 ### 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. 
@@ -192,7 +260,6 @@ class WidgetsController < ApplicationController
 
   def index
     @widgets = build_query_from_filters
-    render json: @widgets
   end
 end
 ```
@@ -213,6 +280,28 @@ The query parameters are pulled from the controller parameters, nested under the
 
 `/widgets?filter[size]=large&filter[color]=blue`
 
+#### Sort Parameters
+
+The sort is also nested underneath the key `filter`. 
+
+`/widgets?filter[sort]=size`
+
+Use an array to pass multiple sorts. The order of the parameters is the order the sorts will be applied. For example, the following sorts first by size then by color:
+
+`/widgets?filter[sort]=size&filter[sort]=color`
+
+Sorts are ascending by default, but can use a prefix can be added to control the sort:
+
+- `+` ascending (the default)
+- `-` descending
+
+For example, the following sorts by size descending:
+
+`/widgets?filter[sort]=-size`
+
+
+#### Override the Filter Key
+
 To change the source of the query parameters, override the `filter_parameters` method. Here is another way to provide a default filter:
 
 ```ruby

data/lib/filterameter/declarative_filters.rb

@@ -7,6 +7,7 @@ module Filterameter
   module DeclarativeFilters
     extend ActiveSupport::Concern
     include Filterameter::Filterable
+    include Filterameter::Sortable
 
     class_methods do
       def filter_model(model_class, query_var_name = nil)

data/lib/filterameter/exceptions/collection_association_sort_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Exceptions
+    # = Collection Association Sort Error
+    #
+    # Class CollectionAssociationSortError is raised when a sort is attempted on a collection association. (Sorting is
+    # only valid on _singular_ associations.)
+    class CollectionAssociationSortError < FilterameterError
+      def initialize(declaration)
+        super("Sorting is not allowed on collection associations: \n\t\t#{declaration}")
+      end
+    end
+  end
+end

data/lib/filterameter/exceptions/invalid_association_declaration_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Exceptions
+    # = Invalid Association Declaration Error
+    #
+    # Class InvalidAssociationDeclarationError is raised when the declared association(s) are not valid.
+    class InvalidAssociationDeclarationError < FilterameterError
+      def initialize(name, model_name, associations)
+        super("The association(s) declared on filter #{name} are not valid for model #{model_name}: #{associations}")
+      end
+    end
+  end
+end

data/lib/filterameter/filter_coordinator.rb

@@ -19,7 +19,7 @@ module Filterameter
   class FilterCoordinator
     attr_writer :query_variable_name
 
-    delegate :add_filter, to: :registry
+    delegate :add_filter, :add_sort, to: :registry
     delegate :build_query, to: :query_builder
 
     def initialize(controller_name, controller_path)
@@ -32,13 +32,19 @@ module Filterameter
     end
 
     def query_builder
-      @query_builder ||= Filterameter::QueryBuilder.new(default_query, registry)
+      @query_builder ||= Filterameter::QueryBuilder.new(default_query, @default_sort, registry)
     end
 
     def query_variable_name
       @query_variable_name ||= model_class.model_name.plural
     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
+    end
+
     private
 
     def model_class
@@ -54,7 +60,7 @@ module Filterameter
 
     # lazy so that model_class can be optionally set
     def registry
-      @registry ||= Filterameter::FilterRegistry.new(Filterameter::FilterFactory.new(model_class))
+      @registry ||= Filterameter::Registries::Registry.new(model_class)
     end
   end
 end

data/lib/filterameter/filter_declaration.rb

@@ -24,11 +24,11 @@ module Filterameter
       validate_options(options)
       @name = options.fetch(:name, parameter_name).to_s
       @association = Array.wrap(options[:association]).presence
-      @filter_on_empty = options.fetch(:filter_on_empty, false)
       @validations = Array.wrap(options[:validates])
       @raw_partial_options = options.fetch(:partial, false)
       @raw_range = options[:range]
       @range_type = range_type
+      @sortable = options.fetch(:sortable, true)
     end
 
     def nested?
@@ -39,10 +39,6 @@ module Filterameter
       !@validations.empty?
     end
 
-    def filter_on_empty?
-      @filter_on_empty
-    end
-
     def partial_search?
       partial_options.present?
     end
@@ -75,10 +71,24 @@ module Filterameter
       @range_type == :maximum
     end
 
+    def sortable?
+      @sortable
+    end
+
+    def to_s
+      options = {}
+      options[:name] = ":#{@name}" if @parameter_name != @name
+      options[:association] = @association if nested?
+      options[:partial] = partial_options if partial_options
+
+      (["filter :#{@parameter_name}"] + options.map { |k, v| "#{k}: #{v}" })
+        .join(', ')
+    end
+
     private
 
     def validate_options(options)
-      options.assert_valid_keys(:name, :association, :filter_on_empty, :validates, :partial, :range)
+      options.assert_valid_keys(:name, :association, :validates, :partial, :range, :sortable)
       validate_range(options[:range]) if options.key?(:range)
     end
 

data/lib/filterameter/filter_factory.rb

@@ -10,26 +10,27 @@ module Filterameter
     end
 
     def build(declaration)
+      context = Helpers::DeclarationWithModel.new(@model_class, declaration)
+
       if declaration.nested?
-        build_nested_filter(declaration)
+        build_nested_filter(declaration, context)
       else
-        build_filter(@model_class, declaration)
+        build_filter(@model_class, declaration, context.scope?)
       end
     end
 
     private
 
-    def build_nested_filter(declaration)
-      model = model_from_association(declaration.association)
-      filter = build_filter(model, declaration)
-      clazz = filter_class(declaration.association)
+    def build_nested_filter(declaration, context)
+      model = context.model_from_association
+      filter = build_filter(model, declaration, context.scope?)
+      nested_filter_class = context.any_collections? ? Filters::NestedCollectionFilter : Filters::NestedFilter
 
-      clazz.new(declaration.association, model, filter)
+      nested_filter_class.new(declaration.association, model, filter)
     end
 
-    def build_filter(model, declaration) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-      # checking dangerous_class_method? excludes any names that cannot be scope names, such as "name"
-      if model.respond_to?(declaration.name) && !model.dangerous_class_method?(declaration.name)
+    def build_filter(model, declaration, declaration_is_a_scope) # rubocop:disable Metrics/MethodLength
+      if declaration_is_a_scope
         build_scope_filter(model, declaration)
       elsif declaration.partial_search?
         Filterameter::Filters::MatchesFilter.new(declaration.name, declaration.partial_options)
@@ -51,30 +52,5 @@ module Filterameter
         Filterameter::Filters::ConditionalScopeFilter.new(declaration.name)
       end
     end
-
-    def filter_class(association_names)
-      if any_collections?(association_names)
-        Filters::NestedCollectionFilter
-      else
-        Filters::NestedFilter
-      end
-    end
-
-    def any_collections?(association_names)
-      association_names.reduce(@model_class) do |model, name|
-        association = model.reflect_on_association(name)
-        return true if association.collection?
-
-        association.klass
-      end
-
-      false
-    end
-
-    # TODO: rescue then raise custom error with cause
-    def model_from_association(association)
-      association.flatten.reduce(@model_class) { |memo, name| memo.reflect_on_association(name).klass }
-      # rescue StandardError => e
-    end
   end
 end

data/lib/filterameter/filters/nested_filter.rb

@@ -6,31 +6,8 @@ module Filterameter
     #
     # Class NestedFilter joins the nested table(s) then merges the filter to the association's model.
     class NestedFilter
-      # = Joins Values Builder
-      #
-      # Class JoinsValuesBuilder evaluates an array of names to return either the single entry when there is only
-      # one element in the array or a nested hash when there is more than one element. This is the argument that is
-      # passed into the ActiveRecord query method `joins`.
-      class JoinsValuesBuilder
-        def self.build(association_names)
-          return association_names.first if association_names.size == 1
-
-          new(association_names).to_h
-        end
-
-        def initialize(association_names)
-          @association_names = association_names
-        end
-
-        def to_h
-          {}.tap do |nested_hash|
-            @association_names.reduce(nested_hash) { |memo, name| memo.store(name, {}) }
-          end
-        end
-      end
-
       def initialize(association_names, association_model, attribute_filter)
-        @joins_values = JoinsValuesBuilder.build(association_names)
+        @joins_values = Filterameter::Helpers::JoinsValuesBuilder.build(association_names)
         @association_model = association_model
         @attribute_filter = attribute_filter
       end

data/lib/filterameter/helpers/declaration_with_model.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Helpers
+    # = Declaration with Model
+    #
+    # Class DeclarationWithModel inspects the declaration under the context of the model. This enables
+    # predicate methods as well as drilling through associations.
+    class DeclarationWithModel
+      def initialize(model, declaration)
+        @model = model
+        @declaration = declaration
+      end
+
+      def scope?
+        model = @declaration.nested? ? model_from_association : @model
+
+        model.respond_to?(@declaration.name) &&
+          # checking dangerous_class_method? excludes any names that cannot be scope names, such as "name"
+          !model.dangerous_class_method?(@declaration.name)
+      end
+
+      def any_collections?
+        @declaration.association.reduce(@model) do |related_model, name|
+          association = related_model.reflect_on_association(name)
+          return true if association.collection?
+
+          association.klass
+        end
+
+        false
+      end
+
+      def model_from_association
+        @declaration.association.flatten.reduce(@model) do |memo, name|
+          association = memo.reflect_on_association(name)
+          raise_invalid_association if association.nil?
+
+          association.klass
+        end
+      end
+
+      private
+
+      def raise_invalid_association
+        raise Filterameter::Exceptions::InvalidAssociationDeclarationError.new(@declaration.name,
+                                                                               @model.name,
+                                                                               @declaration.association)
+      end
+    end
+  end
+end

data/lib/filterameter/helpers/joins_values_builder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Helpers
+    # = Joins Values Builder
+    #
+    # Class JoinsValuesBuilder evaluates an array of names to return either the single entry when there is only
+    # one element in the array or a nested hash when there is more than one element. This is the argument that is
+    # passed into the ActiveRecord query method `joins`.
+    class JoinsValuesBuilder
+      def self.build(association_names)
+        return association_names.first if association_names.size == 1
+
+        new(association_names).to_h
+      end
+
+      def initialize(association_names)
+        @association_names = association_names
+      end
+
+      def to_h
+        {}.tap do |nested_hash|
+          @association_names.reduce(nested_hash) { |memo, name| memo.store(name, {}) }
+        end
+      end
+    end
+  end
+end

data/lib/filterameter/helpers/requested_sort.rb

@@ -0,0 +1,25 @@
+# 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

data/lib/filterameter/options/partial_options.rb

@@ -49,6 +49,16 @@ module Filterameter
         @match == 'dynamic'
       end
 
+      def to_s
+        if case_sensitive?
+          case_sensitive_to_s
+        elsif match_anywhere?
+          'true'
+        else
+          ":#{@match}"
+        end
+      end
+
       private
 
       def evaluate_hash(options)
@@ -79,6 +89,10 @@ module Filterameter
 
         raise ArgumentError, "Invalid case_sensitive option for partial: #{value}. Valid options are true and false."
       end
+
+      def case_sensitive_to_s
+        match_anywhere? ? '{ case_sensitive: true }' : "{ match: :#{@match}, case_sensitive: true }"
+      end
     end
   end
 end

data/lib/filterameter/query_builder.rb

@@ -4,31 +4,77 @@ module Filterameter
   # = Query Builder
   #
   # Class Query Builder turns filter parameters into a query.
+  #
+  # The query builder is instantiated by the filter coordinator. The default query currently is simple `all`. The
+  # default sort comes for the controller declaration of the same name; it is optional and the value may be nil.
+  #
+  # If the request includes a sort, it is always applied. If not, the following logic kicks in to provide a sort:
+  # - if the starting query includes a sort, no additional sort is applied
+  # - if a default sort has been declared, it is applied
+  # - if neither of those provides a sort, then the fallback is primary key desc
   class QueryBuilder
-    def initialize(default_query, filter_registry)
+    def initialize(default_query, default_sort, filter_registry)
       @default_query = default_query
+      @default_sort = default_sort
       @registry = filter_registry
     end
 
     def build_query(filter_params, starting_query = nil)
-      valid_filters(filter_params.stringify_keys)
-        .tap { |parameters| convert_min_and_max_to_range(parameters) }
-        .reduce(starting_query || @default_query) do |query, (name, value)|
-        add_filter_parameter_to_query(query, name, value)
-      end
+      sorts, filters = parse_filter_params(filter_params.stringify_keys)
+      query = apply_filters(starting_query || @default_query, filters)
+      apply_sorts(query, sorts)
     end
 
     private
 
+    def parse_filter_params(filter_params)
+      sort = parse_sorts(filter_params.delete('sort'))
+      [sort, remove_invalid_values(filter_params)]
+    end
+
+    def parse_sorts(sorts)
+      Array.wrap(sorts).map { |sort| Helpers::RequestedSort.parse(sort) }
+    end
+
+    def apply_filters(query, filters)
+      filters.tap { |parameters| convert_min_and_max_to_range(parameters) }
+             .reduce(query) do |memo, (name, value)|
+        add_filter_parameter_to_query(memo, name, value)
+      end
+    end
+
     def add_filter_parameter_to_query(query, filter_name, parameter_value)
-      @registry.fetch(filter_name).apply(query, parameter_value)
-    rescue Filterameter::Exceptions::UndeclaredParameterError => e
+      @registry.fetch_filter(filter_name).apply(query, parameter_value)
+    rescue Filterameter::Exceptions::FilterameterError => e
+      handle_undeclared_parameter(e)
+      query
+    end
+
+    def apply_sorts(query, requested_sorts)
+      return query if no_sort_requested_but_starting_query_includes_sort?(query, requested_sorts)
+
+      sorts = requested_sorts.presence || @default_sort
+      if sorts.present?
+        sorts.reduce(query) { |memo, sort| add_sort_to_query(memo, sort.name, sort.direction) }
+      else
+        sort_by_primary_key_desc(query)
+      end
+    end
+
+    def no_sort_requested_but_starting_query_includes_sort?(query, requested_sorts)
+      requested_sorts.empty? && query.order_values.present?
+    end
+
+    def add_sort_to_query(query, name, direction)
+      @registry.fetch_sort(name).apply(query, direction)
+    rescue Filterameter::Exceptions::FilterameterError => e
       handle_undeclared_parameter(e)
       query
     end
 
-    def valid_filters(filter_params)
-      remove_invalid_values(filter_params)
+    def sort_by_primary_key_desc(query)
+      primary_key = query.model.primary_key
+      query.order(primary_key => :desc)
     end
 
     # if both min and max are present in the query parameters, replace with range
@@ -41,6 +87,9 @@ module Filterameter
       end
     end
 
+    # TODO: this handles any runtime exceptions, not just undeclared parameter errors:
+    # - should the config option be more generalized?
+    # - or should there be a config option for each type of error?
     def handle_undeclared_parameter(exception)
       action = Filterameter.configuration.action_on_undeclared_parameters
       return unless action

data/lib/filterameter/registries/filter_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Registries
+    # Filters
+    #
+    # Class FilterRegistry is a collection of the filters. It captures the filter declarations when classes are loaded,
+    # then uses the injected FilterFactory to build the filters on demand as they are needed.
+    class FilterRegistry < SubRegistry
+      attr_reader :ranges
+
+      def initialize(factory)
+        super
+        @ranges = {}
+      end
+
+      def build_declaration(name, options)
+        Filterameter::FilterDeclaration.new(name, options).tap do |fd|
+          add_declarations_for_range(fd, options, name) if fd.range_enabled?
+        end
+      end
+
+      def filter_declarations
+        @declarations.values
+      end
+
+      private
+
+      # if range is enabled, then in addition to the attribute filter this also adds min and/or max filters
+      def add_declarations_for_range(attribute_declaration, options, parameter_name)
+        add_range_minimum(parameter_name, options) if attribute_declaration.range? || attribute_declaration.min_only?
+        add_range_maximum(parameter_name, options) if attribute_declaration.range? || attribute_declaration.max_only?
+        capture_range_declaration(parameter_name) if attribute_declaration.range?
+      end
+
+      def add_range_minimum(parameter_name, options)
+        parameter_name_min = "#{parameter_name}_min"
+        options_with_name = options.with_defaults(name: parameter_name)
+        @declarations[parameter_name_min] = Filterameter::FilterDeclaration.new(parameter_name_min,
+                                                                                options_with_name,
+                                                                                range_type: :minimum)
+      end
+
+      def add_range_maximum(parameter_name, options)
+        parameter_name_max = "#{parameter_name}_max"
+        options_with_name = options.with_defaults(name: parameter_name)
+        @declarations[parameter_name_max] = Filterameter::FilterDeclaration.new(parameter_name_max,
+                                                                                options_with_name,
+                                                                                range_type: :maximum)
+      end
+
+      def capture_range_declaration(name)
+        @ranges[name] = { min: "#{name}_min", max: "#{name}_max" }
+      end
+    end
+  end
+end

data/lib/filterameter/registries/registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Registries
+    # = Registry
+    #
+    # Class Registry records declarations and allows resulting filters and sorts to be fetched from sub-registries.
+    class Registry
+      delegate :filter_declarations, :ranges, to: :@filter_registry
+
+      def initialize(model_class)
+        @filter_registry = Filterameter::Registries::FilterRegistry.new(Filterameter::FilterFactory.new(model_class))
+        @sort_registry = Filterameter::Registries::SortRegistry.new(Filterameter::SortFactory.new(model_class))
+      end
+
+      def add_filter(parameter_name, options)
+        declaration = @filter_registry.add(parameter_name, options)
+        add_sort(parameter_name, options.slice(:name, :association)) if declaration.sortable?
+      end
+
+      def fetch_filter(parameter_name)
+        @filter_registry.fetch(parameter_name)
+      end
+
+      def add_sort(parameter_name, options)
+        @sort_registry.add(parameter_name, options)
+      end
+
+      def fetch_sort(parameter_name)
+        @sort_registry.fetch(parameter_name)
+      end
+    end
+  end
+end

data/lib/filterameter/registries/sort_registry.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Registries
+    # Sort Registry
+    #
+    # Class SortRegistry is a collection of the sorts. It captures the declarations when classes are loaded,
+    # then uses the injected SortFactory to build the sorts on demand as they are needed.
+    class SortRegistry < SubRegistry
+      private
+
+      def build_declaration(name, options)
+        Filterameter::SortDeclaration.new(name, options)
+      end
+    end
+  end
+end

data/lib/filterameter/registries/sub_registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Registries
+    # SubRegistry
+    #
+    # Class SubRegistry provides add and fetch methods as well as the initialization for sub-registries.
+    #
+    # Subclasses must implement build_declaration.
+    #
+    class SubRegistry
+      def initialize(factory)
+        @factory = factory
+        @declarations = {}
+        @registry = {}
+      end
+
+      def add(parameter_name, options)
+        name = parameter_name.to_s
+        @declarations[name] = build_declaration(name, options)
+      end
+
+      def fetch(parameter_name)
+        name = parameter_name.to_s
+        @registry.fetch(name) do
+          raise Filterameter::Exceptions::UndeclaredParameterError, name unless @declarations.keys.include?(name)
+
+          @registry[name] = @factory.build(@declarations[name])
+        end
+      end
+    end
+  end
+end

data/lib/filterameter/sort_declaration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Sort Declaration
+  #
+  # Class SortDeclaration captures the sort declaration within the controller. A sort declaration is also generated
+  # from a FilterDeclaration when it is `sortable?`.
+  class SortDeclaration
+    attr_reader :name, :parameter_name, :association
+
+    def initialize(parameter_name, options)
+      @parameter_name = parameter_name.to_s
+
+      validate_options(options)
+      @name = options.fetch(:name, parameter_name).to_s
+      @association = Array.wrap(options[:association]).presence
+    end
+
+    def nested?
+      !@association.nil?
+    end
+
+    def to_s
+      options = {}
+      options[:name] = ":#{@name}" if @parameter_name != @name
+      options[:association] = @association if nested?
+
+      (["sort :#{@parameter_name}"] + options.map { |k, v| "#{k}: #{v}" })
+        .join(', ')
+    end
+
+    private
+
+    def validate_options(options)
+      options.assert_valid_keys(:name, :association)
+    end
+  end
+end

data/lib/filterameter/sort_factory.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Sort Factory
+  #
+  # Class SortFactory builds a sort from a model and a declaration.
+  class SortFactory
+    def initialize(model_class)
+      @model_class = model_class
+    end
+
+    def build(declaration)
+      context = Helpers::DeclarationWithModel.new(@model_class, declaration)
+
+      if declaration.nested?
+        build_nested_sort(declaration, context)
+      else
+        build_sort(declaration.name, context.scope?)
+      end
+    end
+
+    private
+
+    def build_nested_sort(declaration, context)
+      validate!(declaration, context)
+
+      model = context.model_from_association
+      sort = build_sort(declaration.name, context.scope?)
+      nested_sort_class = context.any_collections? ? Filters::NestedCollectionFilter : Filters::NestedFilter
+
+      nested_sort_class.new(declaration.association, model, sort)
+    end
+
+    def build_sort(name, declaration_is_a_scope)
+      if declaration_is_a_scope
+        Filterameter::Filters::ScopeFilter.new(name)
+      else
+        Filterameter::Sorts::AttributeSort.new(name)
+      end
+    end
+
+    def validate!(declaration, context)
+      return unless context.any_collections?
+
+      raise Exceptions::CollectionAssociationSortError, declaration
+    end
+  end
+end

data/lib/filterameter/sortable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Sortable
+  #
+  # Mixin Sortable provides class methods <tt>sort</tt> and <tt>sorts</tt>.
+  module Sortable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declares a sort that can be read from the parameters and applied to the ActiveRecord query. The
+      # <tt>parameter_name</tt> identifies the name of the parameter and is the default value for the attribute
+      # name when none is specified in the options.
+      #
+      # The including class must implement `filter_coordinator`
+      #
+      # === Options
+      #
+      # [:name]
+      #   Specify the attribute or scope name if the parameter name is not the same. The default value
+      #   is the parameter name, so if the two match this can be left out.
+      #
+      # [:association]
+      #   Specify the name of the association if the attribute or scope is nested.
+      def sort(parameter_name, options = {})
+        filter_coordinator.add_sort(parameter_name, options)
+      end
+
+      # Declares a list of filters that can be read from the parameters and applied to the query. The name can be either
+      # an attribute or a scope. Declare filters individually with <tt>filter</tt> if more options are required.
+      def sorts(*parameter_names)
+        parameter_names.each { |parameter_name| filter(parameter_name) }
+      end
+
+      def default_sort(sort_and_direction_pairs)
+        filter_coordinator.default_sort = sort_and_direction_pairs
+      end
+    end
+  end
+end

data/lib/filterameter/sorts/attribute_sort.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Sorts
+    # = Attribute Sort
+    #
+    # Class AttributeSort leverages ActiveRecord's `order` query method to add sorting for an attribute.
+    class AttributeSort
+      def initialize(attribute_name)
+        @attribute_name = attribute_name
+      end
+
+      def apply(query, direction)
+        query.order(@attribute_name => direction)
+      end
+    end
+  end
+end

data/lib/filterameter/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Todd Kummer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-14 00:00:00.000000000 Z
+date: 2024-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -179,12 +179,13 @@ files:
 - lib/filterameter/declarative_filters.rb
 - lib/filterameter/exceptions.rb
 - lib/filterameter/exceptions/cannot_determine_model_error.rb
+- lib/filterameter/exceptions/collection_association_sort_error.rb
+- lib/filterameter/exceptions/invalid_association_declaration_error.rb
 - lib/filterameter/exceptions/undeclared_parameter_error.rb
 - lib/filterameter/exceptions/validation_error.rb
 - lib/filterameter/filter_coordinator.rb
 - lib/filterameter/filter_declaration.rb
 - lib/filterameter/filter_factory.rb
-- lib/filterameter/filter_registry.rb
 - lib/filterameter/filterable.rb
 - lib/filterameter/filters/arel_filter.rb
 - lib/filterameter/filters/attribute_filter.rb
@@ -195,10 +196,21 @@ files:
 - lib/filterameter/filters/nested_collection_filter.rb
 - lib/filterameter/filters/nested_filter.rb
 - 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/log_subscriber.rb
 - lib/filterameter/options/partial_options.rb
 - lib/filterameter/parameters_base.rb
 - lib/filterameter/query_builder.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/sort_declaration.rb
+- lib/filterameter/sort_factory.rb
+- lib/filterameter/sortable.rb
+- lib/filterameter/sorts/attribute_sort.rb
 - lib/filterameter/validators/inclusion_validator.rb
 - lib/filterameter/version.rb
 homepage: https://github.com/RockSolt/filterameter

data/lib/filterameter/filter_registry.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # Filters
-  #
-  # Class FilterRegistry is a collection of the filters. It captures the filter declarations when classes are loaded,
-  # then uses the injected FilterFactory to build the filters on demand as they are needed.
-  class FilterRegistry
-    attr_reader :ranges
-
-    def initialize(filter_factory)
-      @filter_factory = filter_factory
-      @declarations = {}
-      @ranges = {}
-      @filters = {}
-    end
-
-    def add_filter(parameter_name, options)
-      name = parameter_name.to_s
-      @declarations[name] = Filterameter::FilterDeclaration.new(name, options).tap do |fd|
-        add_declarations_for_range(fd, options, name) if fd.range_enabled?
-      end
-    end
-
-    def fetch(parameter_name)
-      name = parameter_name.to_s
-      @filters.fetch(name) do
-        raise Filterameter::Exceptions::UndeclaredParameterError, name unless @declarations.keys.include?(name)
-
-        @filters[name] = @filter_factory.build(@declarations[name])
-      end
-    end
-
-    def filter_declarations
-      @declarations.values
-    end
-
-    private
-
-    # if range is enabled, then in addition to the attribute filter this also adds min and/or max filters
-    def add_declarations_for_range(attribute_declaration, options, parameter_name)
-      add_range_minimum(parameter_name, options) if attribute_declaration.range? || attribute_declaration.min_only?
-      add_range_maximum(parameter_name, options) if attribute_declaration.range? || attribute_declaration.max_only?
-      capture_range_declaration(parameter_name) if attribute_declaration.range?
-    end
-
-    def add_range_minimum(parameter_name, options)
-      parameter_name_min = "#{parameter_name}_min"
-      options_with_name = options.with_defaults(name: parameter_name)
-      @declarations[parameter_name_min] = Filterameter::FilterDeclaration.new(parameter_name_min,
-                                                                              options_with_name,
-                                                                              range_type: :minimum)
-    end
-
-    def add_range_maximum(parameter_name, options)
-      parameter_name_max = "#{parameter_name}_max"
-      options_with_name = options.with_defaults(name: parameter_name)
-      @declarations[parameter_name_max] = Filterameter::FilterDeclaration.new(parameter_name_max,
-                                                                              options_with_name,
-                                                                              range_type: :maximum)
-    end
-
-    def capture_range_declaration(name)
-      @ranges[name] = { min: "#{name}_min", max: "#{name}_max" }
-    end
-  end
-end