filterameter 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fab4750d809945619906678860278bb1266e20f3167a7e1cf15ca2cfcdb2404d
-  data.tar.gz: da0d8f1d87b5aa8393f0283ce92442b968a4f388f6aa86eaf65c0740f3da8a7f
+  metadata.gz: 8b2ac8a6c211408669122ab5bf2a131ade58736fa145508305f5ebe3dc9c0bdb
+  data.tar.gz: 9216ddecfedab830f9a3a82cf9c1936f040e64664b23b2d16a4ccd71f1f4923e
 SHA512:
-  metadata.gz: 6c4c735e792c7da17e8753e760e2e75143e1e959f0000fb2367246dc280a57fc3709d47ac063a8261a3429727ac178d41c18fc4a0fc2abcec8417e2ec0c28240
-  data.tar.gz: 2a92f39bcd0af14ff33f3efc35f65def9d882a3caf01b18a04ec0c31ece6977966962ce88d893d0efb62c2b4492babe2d90b02fde8f730a76121c869d2ca3c3c
+  metadata.gz: ad640c098660b98a33f54378f16dced7d3c2dd278c6d6b6db120d2026cb7f03bda5f0d5033653e697af153eff4bdb3c9c84e39d263a18eedba5075098b7354ef
+  data.tar.gz: 3e775bbe1d6ed769bdfb1a83ac3f4a74c69128517a5bf6ea3fc140e50a8b025214d87d544c9263ad4bf0495f34d477f7a2128836f81e7b6a82d4ec037b9df938

data/README.md

@@ -4,10 +4,10 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/d9d87f9ce8020eb6e656/maintainability)](https://codeclimate.com/github/RockSolt/filterameter/maintainability)
 
 # Filterameter
-Declarative filter parameters provide clean and clear filters for queries.
+Declarative filter parameters provide clean and clear filters for Rails controllers.
 
 ## Usage
-Declare filters in query classes or controllers to increase readability and reduce boilerplate code. Filters can be declared for attributes, scopes, or attributes from singular associations (`belongs_to` or `has_one`). Validations can also be assigned.
+Declare filters in controllers to increase readability and reduce boilerplate code. Filters can be declared for attributes or scopes, either directly on the model or on an associated model. Validations can also be assigned.
 
 ```ruby
   filter :color
@@ -28,13 +28,25 @@ If the name of the parameter is different than the name of the attribute or scop
 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. Only singular associations are valid. For example, if the manager_id attribute lives on an employee's department record, use the following:
+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
 filter :manager_id, association: :department
 ```
 
+The attribute or scope can be nested more than one level. Declare the filter with an array specifying the associations in order. For example, if an employee belongs to a department and a department belongs to a business unit, use the following to query on the business unit name:
+
+```ruby
+filter :business_unit_name, name: :name, association: [:department, :business_unit]
+```
+
+If an association is a `has_many` [the distinct method](https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-distinct) is called on the query.
+
+_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:
 
@@ -85,39 +97,9 @@ 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>.
 
-### Query Classes
-
-Include module `Filterameter::DeclarativeFilters` in the query class. The model must be declared using `model`, and a default query can optionally be declared using `default_query`. If no default query is provided, then the default is `.all`.
-
-#### Example
-
-Here's what a query class for the Widgets model with filters on size and color might look like:
-
-```ruby
-class WidgetQuery
-  include Filterameter::DeclarativeFilters
-
-  model Widget
-  filter :size
-  filter :color
-end
-```
-
-Build the query using class method `build_query`. The method takes two parameters:
-
-- filter: the hash of filter parameters
-- starting_query: any scope to build on (if not provided, the default query is the starting point)
-
-Here's how the query might be invoked:
-
-```ruby
-filters = { size: 'large', color: 'blue' }
-widgets = WidgetQuery.build_query(filters, Widget.limit(10))
-```
-
 ### Controllers
 
-Include module `Filterameter::DeclarativeControllerFilters` in the controller. Add before action callback `build_filtered_query` for controller actions that should build the query.
+Include module `Filterameter::DeclarativeFilters` in the controller. Add before action callback `build_filtered_query` for controller actions that should build the query.
 
 Rails conventions are used to determine the controller's model as well as the name of the instance variable to apply the filters to. For example, the PhotosController will use the variable `@photos` to store a query against the Photo model. **If the conventions do not provide the correct info**, they can be overridden with the following two methods:
 
@@ -141,7 +123,7 @@ In the happy path, the WidgetsController serves Widgets and can filter on size a
 
 ```ruby
 class WidgetController < ApplicationController
-  include Filterameter::DeclarativeControllerFilters
+  include Filterameter::DeclarativeFilters
   before_action :build_filtered_query, only: :index
 
   filter :size

data/lib/filterameter/declarative_filters.rb

@@ -1,27 +1,37 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Declarative Filters
+  # = Declarative Controller Filters
   #
-  # Mixin DeclarativeFilters is included to build query classes using the filter DSL.
+  # Mixin DeclarativeFilters can included in controllers to enable the filter DSL.
   module DeclarativeFilters
     extend ActiveSupport::Concern
     include Filterameter::Filterable
 
     class_methods do
-      delegate :build_query, to: :filter_coordinator
-
-      def model(model_class)
+      def filter_model(model_class, query_var_name = nil)
         filter_coordinator.model_class = model_class
+        filter_query_var_name(query_var_name) if query_var_name.present?
       end
 
-      def default_query(query)
-        filter_coordinator.default_query = query
+      def filter_query_var_name(query_variable_name)
+        filter_coordinator.query_variable_name = query_variable_name
       end
 
       def filter_coordinator
-        @filter_coordinator ||= Filterameter::Coordinators::QueryCoordinator.new
+        @filter_coordinator ||= Filterameter::FilterCoordinator.new(controller_name, controller_path)
       end
     end
+
+    private
+
+    def build_filtered_query
+      var_name = "@#{self.class.filter_coordinator.query_variable_name}"
+      instance_variable_set(
+        var_name,
+        self.class.filter_coordinator.build_query(params.to_unsafe_h.fetch(:filter, {}),
+                                                  instance_variable_get(var_name))
+      )
+    end
   end
 end

data/lib/filterameter/filter_coordinator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+
+require 'active_support/rails'
+require 'action_dispatch'
+require 'action_controller/metal/live'
+require 'action_controller/metal/strong_parameters'
+
+module Filterameter
+  # = Filter Coordinator
+  #
+  # Class FilterCoordinator stores the configuration declared via class-level method calls such as the list of
+  # filters and the optionally declared model class. Each controller will have one instance of the coordinator
+  # stored as a class variable.
+  #
+  # 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_writer :query_variable_name
+
+    delegate :add_filter, to: :registry
+    delegate :build_query, to: :query_builder
+
+    def initialize(controller_name, controller_path)
+      @controller_name = controller_name
+      @controller_path = controller_path
+    end
+
+    def model_class=(model_class)
+      @model_class = model_class.is_a?(String) ? model_class.constantize : model_class
+    end
+
+    def query_builder
+      @query_builder ||= Filterameter::QueryBuilder.new(default_query, registry)
+    end
+
+    def query_variable_name
+      @query_variable_name ||= model_class.model_name.plural
+    end
+
+    private
+
+    def model_class
+      @model_class ||= @controller_name.classify.safe_constantize ||
+                       @controller_path.classify.safe_constantize ||
+                       raise(Filterameter::Exceptions::CannotDetermineModelError.new(@controller_name,
+                                                                                     @controller_path))
+    end
+
+    def default_query
+      model_class.all
+    end
+
+    # lazy so that model_class can be optionally set
+    def registry
+      @registry ||= Filterameter::FilterRegistry.new(Filterameter::FilterFactory.new(model_class))
+    end
+  end
+end

data/lib/filterameter/filter_declaration.rb

@@ -16,7 +16,7 @@ module Filterameter
 
       validate_options(options)
       @name = options.fetch(:name, parameter_name).to_s
-      @association = options[:association]
+      @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)
@@ -24,7 +24,7 @@ module Filterameter
     end
 
     def nested?
-      @association.present?
+      !@association.nil?
     end
 
     def validations?

data/lib/filterameter/filter_factory.rb

@@ -10,14 +10,23 @@ module Filterameter
     end
 
     def build(declaration)
-      model = declaration.nested? ? model_from_association(declaration.association) : @model_class
-      filter = build_filter(model, declaration)
-
-      declaration.nested? ? Filterameter::Filters::NestedFilter.new(declaration.association, model, filter) : filter
+      if declaration.nested?
+        build_nested_filter(declaration)
+      else
+        build_filter(@model_class, declaration)
+      end
     end
 
     private
 
+    def build_nested_filter(declaration)
+      model = model_from_association(declaration.association)
+      filter = build_filter(model, declaration)
+      clazz = filter_class(declaration.association)
+
+      clazz.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)
@@ -33,9 +42,28 @@ module Filterameter
       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 }
+      association.flatten.reduce(@model_class) { |memo, name| memo.reflect_on_association(name).klass }
       # rescue StandardError => e
     end
   end

data/lib/filterameter/filter_registry.rb

@@ -51,8 +51,8 @@ module Filterameter
     end
 
     def add_range_maximum(parameter_name, options)
-      parameter_name_min = "#{parameter_name}_max"
-      @declarations[parameter_name_min] = Filterameter::FilterDeclaration.new(parameter_name_min,
+      parameter_name_max = "#{parameter_name}_max"
+      @declarations[parameter_name_max] = Filterameter::FilterDeclaration.new(parameter_name_max,
                                                                               options.merge(range: :max_only))
     end
 

data/lib/filterameter/filters/nested_collection_filter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Filters
+    # = Nested Collection Filter
+    #
+    # Class NestedCollectionFilter joins the nested table(s), merges the filter to the association's model, then makes
+    # the results distinct.
+    class NestedCollectionFilter < NestedFilter
+      def apply(*)
+        super.distinct
+      end
+    end
+  end
+end

data/lib/filterameter/filters/nested_filter.rb

@@ -6,8 +6,8 @@ module Filterameter
     #
     # Class NestedFilter joins the nested table(s) then merges the filter to the association's model.
     class NestedFilter
-      def initialize(joins_values, association_model, attribute_filter)
-        @joins_values = joins_values
+      def initialize(association_names, association_model, attribute_filter)
+        @joins_values = build_joins_values_argument(association_names)
         @association_model = association_model
         @attribute_filter = attribute_filter
       end
@@ -16,6 +16,20 @@ module Filterameter
         query.joins(@joins_values)
              .merge(@attribute_filter.apply(@association_model, value))
       end
+
+      private
+
+      def build_joins_values_argument(association_names)
+        return association_names.first if association_names.size == 1
+
+        convert_to_nested_hash(association_names)
+      end
+
+      def convert_to_nested_hash(association_names)
+        {}.tap do |nested_hash|
+          association_names.reduce(nested_hash) { |memo, name| memo.store(name, {}) }
+        end
+      end
     end
   end
 end

data/lib/filterameter/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Todd Kummer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-13 00:00:00.000000000 Z
+date: 2024-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -114,14 +114,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.60.2
+        version: '1.64'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.60.2
+        version: '1.64'
 - !ruby/object:Gem::Dependency
   name: rubocop-packaging
   requirement: !ruby/object:Gem::Requirement
@@ -142,14 +142,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.23.1
+        version: '2.25'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.23.1
+        version: '2.25'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -164,7 +164,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
-description: Enable filter parameters to be declared in query classes or controllers.
+description: Declare filters in Rails controllers to increase readability and reduce
+  boilerplate code.
 email:
 - todd@rockridgesolutions.com
 executables: []
@@ -175,15 +176,12 @@ files:
 - Rakefile
 - lib/filterameter.rb
 - lib/filterameter/configuration.rb
-- lib/filterameter/coordinators/base.rb
-- lib/filterameter/coordinators/controller_coordinator.rb
-- lib/filterameter/coordinators/query_coordinator.rb
-- lib/filterameter/declarative_controller_filters.rb
 - lib/filterameter/declarative_filters.rb
 - lib/filterameter/exceptions.rb
 - lib/filterameter/exceptions/cannot_determine_model_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
@@ -194,6 +192,7 @@ files:
 - lib/filterameter/filters/matches_filter.rb
 - lib/filterameter/filters/maximum_filter.rb
 - lib/filterameter/filters/minimum_filter.rb
+- lib/filterameter/filters/nested_collection_filter.rb
 - lib/filterameter/filters/nested_filter.rb
 - lib/filterameter/filters/scope_filter.rb
 - lib/filterameter/log_subscriber.rb

data/lib/filterameter/coordinators/base.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  module Coordinators
-    # = Coordinators Base
-    #
-    # The main responsibility of the Coordinators classes is to keep the namespace clean for controllers and query
-    # objects that implement filter parameters. The coordinators encapsulate references to the Query Builder and
-    # Filter Registry.
-    class Base
-      attr_reader :model_class
-
-      delegate :add_filter, to: :registry
-      delegate :build_query, to: :query_builder
-
-      def model_class=(model_class)
-        @model_class = model_class.is_a?(String) ? model_class.constantize : model_class
-      end
-
-      def query_builder
-        @query_builder ||= Filterameter::QueryBuilder.new(default_query, registry)
-      end
-
-      private
-
-      def default_query
-        model_class.all
-      end
-
-      # lazy so that model_class can be optionally set
-      def registry
-        @registry ||= Filterameter::FilterRegistry.new(Filterameter::FilterFactory.new(model_class))
-      end
-    end
-  end
-end

data/lib/filterameter/coordinators/controller_coordinator.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-require 'active_support/inflector'
-
-require 'active_support/rails'
-require 'action_dispatch'
-require 'action_controller/metal/live'
-require 'action_controller/metal/strong_parameters'
-
-module Filterameter
-  module Coordinators
-    # = Controller Filters
-    #
-    # Class ControllerFilters stores the configuration declared via class-level method calls such as the list of
-    # filters and the optionally declared model class. Each controller will have one instance of the controller
-    # declarations stored as a class variable.
-    class ControllerCoordinator < Filterameter::Coordinators::Base
-      attr_writer :query_variable_name
-
-      def initialize(controller_name, controller_path)
-        @controller_name = controller_name
-        @controller_path = controller_path
-        super()
-      end
-
-      def query_variable_name
-        @query_variable_name ||= model_class.model_name.plural
-      end
-
-      private
-
-      def model_class
-        @model_class ||= @controller_name.classify.safe_constantize ||
-                         @controller_path.classify.safe_constantize ||
-                         raise(Filterameter::Exceptions::CannotDetermineModelError.new(@controller_name,
-                                                                                       @controller_path))
-      end
-    end
-  end
-end

data/lib/filterameter/coordinators/query_coordinator.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  module Coordinators
-    # = Query Coordinator
-    #
-    # Class QueryCoordinator coordinates the filter logic for query classes.
-    class QueryCoordinator < Filterameter::Coordinators::Base
-      attr_writer :default_query
-
-      private
-
-      def default_query
-        @default_query || super
-      end
-    end
-  end
-end

data/lib/filterameter/declarative_controller_filters.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # = Declarative Controller Filters
-  #
-  # Mixin DeclarativeControllerFilters can included in controllers to enable the filter DSL.
-  module DeclarativeControllerFilters
-    extend ActiveSupport::Concern
-    include Filterameter::Filterable
-
-    class_methods do
-      def filter_model(model_class, query_var_name = nil)
-        filter_coordinator.model_class = model_class
-        filter_query_var_name(query_var_name) if query_var_name.present?
-      end
-
-      def filter_query_var_name(query_variable_name)
-        filter_coordinator.query_variable_name = query_variable_name
-      end
-
-      def filter_coordinator
-        @filter_coordinator ||= Filterameter::Coordinators::ControllerCoordinator.new(controller_name, controller_path)
-      end
-    end
-
-    private
-
-    def build_filtered_query
-      var_name = "@#{self.class.filter_coordinator.query_variable_name}"
-      instance_variable_set(
-        var_name,
-        self.class.filter_coordinator.build_query(params.to_unsafe_h.fetch(:filter, {}),
-                                                  instance_variable_get(var_name))
-      )
-    end
-  end
-end