filterameter 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9240312d328da15d2d007226b2c19f29cb9de9ec0a19ebd7cc6551cad64cabf2
-  data.tar.gz: fa0044f0983f298258451fda21c68388af52a45d9dc62e631d18ee910334eef3
+  metadata.gz: c02c45f5366abfe01e6858a4d70d932e585b219a27680f799f5b53056202322f
+  data.tar.gz: acff8ae1523f525d3f7d9415c32dd5d3fd9b707118498b38d78eff4ca05ccc97
 SHA512:
-  metadata.gz: 29a0f5344ea78d56cf4984ea9de64d587b541ffe3b3e94eca85234f3c004d6c9eaa4c055d15351f180fd2791172075b8a5fdef21a3a139cb4d909da385f638ac
-  data.tar.gz: 277e0d817280074f8e4725d321e09a5b819be0031fccbd7382b2700928919151e3f5a4ad72618a5155d6cb1a57cafb22b507983382ae1db9bdb452ad439809cc
+  metadata.gz: 2923df8284998b1129cb3b66bb7166cd08ef8708b21a8a6af666c393c219178f38111802294bc051434cd5a33cf6e6853f593abd6415fa031329bc09fbab8a92
+  data.tar.gz: 7fc9483785d7226ce14d9d3eae2f04b6d99c9f3bbfecdcd886b10cb9302e2ad119958e8ee1092e566e64eacc7d218b0bf754a0eeabb8463525858dc9cfaf5ed2

data/README.md

@@ -9,6 +9,9 @@ Declarative filter parameters provide clean and clear filters for Rails controll
 ## Usage
 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.
 
+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
   filter :color
   filter :size, validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
@@ -17,6 +20,14 @@ Declare filters in controllers to increase readability and reduce boilerplate co
                                                     { numericality: { less_than: 100 } }]
 ```
 
+Filters without options can be declared all at once with `filters`:
+
+```ruby
+filters :color,
+        :size,
+        :name
+```
+
 ### Filtering Options
 
 The following options can be specified for each filter.
@@ -97,32 +108,61 @@ 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>.
 
-### Controllers
+### Scope Filters
 
-Include module `Filterameter::DeclarativeFilters` in the controller. Add before action callback `build_filtered_query` for controller actions that should build the query.
+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`.
 
-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:
+Passing `high_priority=false` will not invoke the scope. This makes it easy to include a filter with a check box UI.
 
-#### filter_model
-Provide the name of the model. This method also allows the variable name to be optionally provided as the second parameter.
+Scopes that do take arguments [must be written as class methods, not inline scopes.](https://guides.rubyonrails.org/active_record_querying.html#passing-in-arguments) For example, imagine a scope called `recent` that takes an as of date as an argument. Here is what that might look like:
+
+```ruby
+def self.recent(as_of_date)
+  where('created_at > ?', as_of_date)
+end
+```
+
+### 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. 
+
+**If the conventions do not provide the correct model**, the model can be named explicitly with the following:
 
 ```ruby
 filter_model 'Picture'
 ```
 
-#### filter_query_var_name
-Provide the name of the instance variable. For example, if the query is stored as `@data`, use the following:
+
+### Building the Query
+
+There are two ways to apply the filters and build the query, depending on how much control and/or visibility is desired:
+
+- 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.
+
+When using the callback, the variable name is the pluralized model name. For example, the Photo model will use the variable `@photos` to store the query. The variable name can be explicitly specified with with `filter_query_var_name`. For example, if the query is stored as `@data`, use the following:
 
 ```ruby
 filter_query_var_name :data
 ```
 
-#### Example
+Additionally, the `filter_model` command takes an optional second parameter to specify the variable name. Both the model and the variable name can be specified with this short-cut. For example, to use the Picture model and store the results as `@data`, use the following:
+
+```ruby
+filter_model 'Picture', :data
+```
+
+##### Example
 
 In the happy path, the WidgetsController serves Widgets and can filter on size and color. Here's what the controller might look like:
 
 ```ruby
-class WidgetController < ApplicationController
+class WidgetsController < ApplicationController
   include Filterameter::DeclarativeFilters
   before_action :build_filtered_query, only: :index
 
@@ -135,6 +175,61 @@ class WidgetController < ApplicationController
 end
 ```
 
+#### Manually call `build_query_from_filters`
+
+To generate the query manually, you can call `build_query_from_filters` directly _instead of using the callback_.
+
+###### Example
+
+Here's the Widgets controller again, this time building the query manually:
+
+```ruby
+class WidgetsController < ApplicationController
+  include Filterameter::DeclarativeFilters
+
+  filter :size
+  filter :color
+
+  def index
+    @widgets = build_query_from_filters
+    render json: @widgets
+  end
+end
+```
+
+This method optionally takes a starting query. If there was a controller for Active Widgets that should only return active widgets, the following could be passed into the method as the starting point:
+
+```ruby
+  def index
+    @widgets = build_query_from_filters(Widget.where(active: true))
+  end
+```
+
+Note that the starting query provides the model, so the model is not looked up and any `model_name` declaration is ignored.
+
+### Query Parameters
+
+The query parameters are pulled from the controller parameters, nested under the key `filter`. For example a request for large, blue widgets might have the following url:
+
+`/widgets?filter[size]=large&filter[color]=blue`
+
+To change the source of the query parameters, override the `filter_parameters` method. Here is another way to provide a default filter:
+
+```ruby
+def filter_parameters
+  super.with_defaults(active: true)
+end
+```
+
+This also provides an easy way to nest the criteria under a key other than `filter`:
+
+```ruby
+def filter_parameters
+  params.to_unsafe_h.fetch(:criteria, {})
+end
+```
+
+
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -172,8 +267,21 @@ On [a generic search form](https://guides.rubyonrails.org/form_helpers.html#a-ge
 <% end %>
 ```
 
+## Contributions
+
+Feedback, feature requests, and proposed changes are welcomed. Please use the [issue tracker](https://github.com/RockSolt/filterameter/issues) 
+for feedback and feature requests. To propose a change directly, please fork the repo and open a pull request. Keep an eye on the actions to make
+sure the tests and Rubocop are passing. [Code Climate](https://codeclimate.com/github/RockSolt/filterameter) is also used manually to assess the codeline.
+
+To report a bug, please use the [issue tracker](https://github.com/RockSolt/filterameter/issues) and provide the following information:
+
+- the version in use
+- the filter declarations
+- the SQL generated (for invalid / incorrect queries)
+
+Gold stars will be awarded if you are able to [replicate the issue with a test](spec/README.md).
 
-## Running Tests
+### Running Tests
 
 Tests are written in RSpec and the dummy app uses a docker database. The script `bin/start_db.sh` starts and prepares the test
 database. It is a one-time step before running the tests.

data/lib/filterameter/declarative_filters.rb

@@ -3,7 +3,7 @@
 module Filterameter
   # = Declarative Controller Filters
   #
-  # Mixin DeclarativeFilters can included in controllers to enable the filter DSL.
+  # Mixin DeclarativeFilters should be included in controllers to enable the filter DSL.
   module DeclarativeFilters
     extend ActiveSupport::Concern
     include Filterameter::Filterable
@@ -23,15 +23,20 @@ module Filterameter
       end
     end
 
+    def build_query_from_filters(starting_query = nil)
+      self.class.filter_coordinator.build_query(filter_parameters, starting_query)
+    end
+
+    def filter_parameters
+      params.to_unsafe_h.fetch(:filter, {})
+    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))
-      )
+      starting_query = instance_variable_get(var_name)
+      instance_variable_set(var_name, build_query_from_filters(starting_query))
     end
   end
 end

data/lib/filterameter/filter_declaration.rb

@@ -6,12 +6,19 @@ module Filterameter
   # = Filter Declaration
   #
   # Class FilterDeclaration captures the filter declaration within the controller.
+  #
+  # When the min_only or max_only range option is specified, in addition to the attribute filter which carries that
+  # option, the registry builds a duplicate declaration that also carries the range_type flag (as either :minimum
+  # or :maximum).
+  #
+  # The predicate methods `min_only?` and `max_only?` answer what was declared; the predicate methods `minimum_range?`
+  # and `maximum_range?` answer what type of filter should be built.
   class FilterDeclaration
     VALID_RANGE_OPTIONS = [true, :min_only, :max_only].freeze
 
     attr_reader :name, :parameter_name, :association, :validations
 
-    def initialize(parameter_name, options)
+    def initialize(parameter_name, options, range_type: nil)
       @parameter_name = parameter_name.to_s
 
       validate_options(options)
@@ -21,6 +28,7 @@ module Filterameter
       @validations = Array.wrap(options[:validates])
       @raw_partial_options = options.fetch(:partial, false)
       @raw_range = options[:range]
+      @range_type = range_type
     end
 
     def nested?
@@ -51,14 +59,22 @@ module Filterameter
       @raw_range == true
     end
 
-    def minimum?
+    def min_only?
       @raw_range == :min_only
     end
 
-    def maximum?
+    def max_only?
       @raw_range == :max_only
     end
 
+    def minimum_range?
+      @range_type == :minimum
+    end
+
+    def maximum_range?
+      @range_type == :maximum
+    end
+
     private
 
     def validate_options(options)

data/lib/filterameter/filter_factory.rb

@@ -30,18 +30,28 @@ module Filterameter
     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)
-        Filterameter::Filters::ScopeFilter.new(declaration.name)
+        build_scope_filter(model, declaration)
       elsif declaration.partial_search?
         Filterameter::Filters::MatchesFilter.new(declaration.name, declaration.partial_options)
-      elsif declaration.minimum?
+      elsif declaration.minimum_range?
         Filterameter::Filters::MinimumFilter.new(model, declaration.name)
-      elsif declaration.maximum?
+      elsif declaration.maximum_range?
         Filterameter::Filters::MaximumFilter.new(model, declaration.name)
       else
         Filterameter::Filters::AttributeFilter.new(declaration.name)
       end
     end
 
+    # Inline scopes return an arity of -1 regardless of arguments, so those will always be assumed to be
+    # conditional scopes. To have a filter that passes a value to a scope, it must be a class method.
+    def build_scope_filter(model, declaration)
+      if model.method(declaration.name).arity == 1
+        Filterameter::Filters::ScopeFilter.new(declaration.name)
+      else
+        Filterameter::Filters::ConditionalScopeFilter.new(declaration.name)
+      end
+    end
+
     def filter_class(association_names)
       if any_collections?(association_names)
         Filters::NestedCollectionFilter

data/lib/filterameter/filter_registry.rb

@@ -39,23 +39,25 @@ module Filterameter
 
     # 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.minimum?
-      add_range_maximum(parameter_name, options) if attribute_declaration.range? || attribute_declaration.maximum?
+      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_range = options.with_defaults(name: parameter_name)
-                                  .merge(range: :min_only)
-      @declarations[parameter_name_min] = Filterameter::FilterDeclaration.new(parameter_name_min, options_with_range)
+      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_range = options.with_defaults(name: parameter_name)
-                                  .merge(range: :max_only)
-      @declarations[parameter_name_max] = Filterameter::FilterDeclaration.new(parameter_name_max, options_with_range)
+      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)

data/lib/filterameter/filters/nested_filter.rb

@@ -6,29 +6,38 @@ 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 = build_joins_values_argument(association_names)
+        @joins_values = JoinsValuesBuilder.build(association_names)
         @association_model = association_model
         @attribute_filter = attribute_filter
       end
 
       def apply(query, value)
         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
+             .merge(@attribute_filter.apply(@association_model.all, value))
       end
     end
   end

data/lib/filterameter/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Todd Kummer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-30 00:00:00.000000000 Z
+date: 2024-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -220,7 +220,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Declarative Filter Parameters