filterameter 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a523b898a73ce9f67d723e9dcbf1131748bf7d431c8cab11dc6faa00ac9409a
-  data.tar.gz: 428a21db90c7823118037fe7fd698dda522644a3cf47bcb1b5c3e0b0d8a7418e
+  metadata.gz: e753f63174bbf6eb6a0ad352fc518782bc092f5e9075bcd596d540c76ceb6ab1
+  data.tar.gz: 14f544522f30cbf4d2d6fe54fb5e8a5e0310172fcc75007c087e9402359d6ae3
 SHA512:
-  metadata.gz: 82db4c9d6db4b7bf27815e97ff3479fe2e0afc85ec66ea69db6807ba2ff0a98b2b61fe82975b61164c22eed53b07e59678dcd0098912d89f02909a4276ba44f9
-  data.tar.gz: 53401b585ec11bc664c8268425720e890bbce6197606366059d46c9eb78fd72350217860fb2cf54f1c16fd055a2c88b3fe81789e4a45cf97c0d618b89be400ef
+  metadata.gz: 13b2457bf17e0cdd1d9b11075d4a5df015179b46000a2b3418d10ab5885bb5d2fc0435c59bfdae7668c2cf165973084ccd2a1403e95f32e1e40cef1a67849dfb
+  data.tar.gz: 26b14da4bdc7e786dbd025af086dc9aadac131306c3ef82ea7ef8f73e72e7518e4de825d34ab80b51ed2b3052705060ebf87b6ae5dce56a8adc697f051928258

data/README.md

@@ -1,12 +1,17 @@
+[![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)
+[![Maintainability](https://api.codeclimate.com/v1/badges/d9d87f9ce8020eb6e656/maintainability)](https://codeclimate.com/github/RockSolt/filterameter/maintainability)
+
 # Filterameter
-Declarative Filter Parameters for Rails Controllers.
+Declarative filter parameters provide provide clean and clear filters for queries.
 
 ## Usage
-Declare filters at the top of 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 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.
 
 ```ruby
   filter :color
-  filter :size, validates: { inclusion: { in: %w[Small Medium Large] }, unless: -> { size.is_a? Array } }
+  filter :size, validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
   filter :brand_name, association: :brand, name: :name
   filter :on_sale, association: :price, validates: [{ numericality: { greater_than: 0 } },
                                                     { numericality: { less_than: 100 } }]
@@ -34,14 +39,87 @@ filter :manager_id, association: :department
 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
-filter :size, validates: { inclusion: { in: %w[Small Medium Large] }, unless: -> { size.is_a? Array } }
+filter :size, validates: { inclusion: { in: %w[Small Medium Large] } }
+```
+
+The `inclusion` validator has been overridden to provide the additional option `allow_multiple_values`. When true, the value can be an array and each entry in the array will be validated. Use this when the filter can specify one or more values.
+
+```ruby
+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)
+
+There are two shortcuts: : the partial option can be declared with `true`, which just uses the defaults; or the partial option can be declared with the match option directly, such as `partial: :from_start`.
+
+```ruby
+filter :description, partial: true
+filter :department_name, partial: :from_start
+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
+
+Using the range option means that _in addition to the attribute filter_ minimum and maximum query parameters may also be specified. The parameter names are the attribute name plus the suffix <tt>_min</tt> or <tt>_max</tt>.
+
+```ruby
+filter :price, range: true
+filter :approved_at, range: :min_only
+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
 ```
 
-Note that the `inclusion` validator does not allow arrays to be specified. If the filter should allow multiple values to be specified, then the validation needs to be disabled when the value an array.
+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:
 
-### Configuring Controllers
+```ruby
+filters = { size: 'large', color: 'blue' }
+widgets = WidgetQuery.build_query(filters, Widget.limit(10))
+```
 
-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:
+### Controllers
+
+Include module `Filterameter::DeclarativeControllerFilters` 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:
 
 #### filter_model
 Provide the name of the model. This method also allows the variable name to be optionally provided as the second parameter.
@@ -57,6 +135,24 @@ Provide the name of the instance variable. For example, if the query is stored a
 filter_query_var_name :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
+  include Filterameter::DeclarativeControllerFilters
+  before_action :build_filtered_query, only: :index
+
+  filter :size
+  filter :color
+
+  def index
+    render json: @widgets
+  end
+end
+```
+
 ## Installation
 Add this line to your application's Gemfile:
 

data/lib/filterameter/coordinators/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'filterameter/filter_declaration'
+require 'filterameter/filter_factory'
+require 'filterameter/filter_registry'
+require 'filterameter/log_subscriber'
+require 'filterameter/parameters_base'
+require 'filterameter/query_builder'
+
+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

@@ -0,0 +1,42 @@
+# 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'
+
+require 'filterameter/coordinators/base'
+
+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

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'filterameter/filterable'
+require 'filterameter/coordinators/controller_coordinator'
+
+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

data/lib/filterameter/declarative_filters.rb

@@ -1,50 +1,31 @@
 # frozen_string_literal: true
 
-require 'filterameter/controller_filters'
+require 'filterameter/coordinators/query_coordinator'
+require 'filterameter/filterable'
+require 'filterameter/query_builder'
 
 module Filterameter
   # = Declarative Filters
   #
-  # module DeclarativeFilters provides a controller DSL to declare filters along with any validations.
+  # Mixin DeclarativeFilters is included to build query classes using the filter DSL.
   module DeclarativeFilters
     extend ActiveSupport::Concern
-
-    included do
-      before_action :build_filtered_query, only: :index
-    end
+    include Filterameter::Filterable
 
     class_methods do
-      def filter_model(model_class, query_var_name = nil)
-        controller_filters.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)
-        controller_filters.query_variable_name = query_variable_name
-      end
+      delegate :build_query, to: :filter_coordinator
 
-      def filter(name, options = {})
-        controller_filters.add_filter(name, options)
+      def model(model_class)
+        filter_coordinator.model_class = model_class
       end
 
-      def filters(*names)
-        names.each { |name| filter(name) }
+      def default_query(query)
+        filter_coordinator.default_query = query
       end
 
-      def controller_filters
-        @controller_filters ||= Filterameter::ControllerFilters.new(controller_name, controller_path)
+      def filter_coordinator
+        @filter_coordinator ||= Filterameter::Coordinators::QueryCoordinator.new
       end
     end
-
-    private
-
-    def build_filtered_query
-      var_name = "@#{self.class.controller_filters.query_variable_name}"
-      instance_variable_set(
-        var_name,
-        self.class.controller_filters.build_query(params.to_unsafe_h.fetch(:filter, {}),
-                                                  instance_variable_get(var_name))
-      )
-    end
   end
 end

data/lib/filterameter/exceptions/cannot_determine_model_error.rb

@@ -10,7 +10,7 @@ module Filterameter
     class CannotDetermineModelError < FilterameterError
       def initialize(name, path)
         super "Cannot determine model name from controller name #{value_and_classify(name)} " \
-          "or path #{value_and_classify(path)}. Declare the model explicitly with filter_model."
+              "or path #{value_and_classify(path)}. Declare the model explicitly with filter_model."
       end
 
       private

data/lib/filterameter/exceptions/undeclared_parameter_error.rb

@@ -7,14 +7,15 @@ module Filterameter
     # Class UndeclaredParameterError is raised when a request contains filter parameters that have not been declared.
     # Configuration setting `action_on_undeclared_parameters` determines whether or not the exception is raised.
     class UndeclaredParameterError < FilterameterError
-      attr_reader :keys
+      attr_reader :key
 
-      def initialize(keys)
-        @keys = keys
+      def initialize(key)
+        super
+        @key = key
       end
 
       def message
-        "The following filter parameter(s) have not been declared: #{keys}"
+        "The following filter parameter has not been declared: #{key}"
       end
     end
   end

data/lib/filterameter/exceptions/validation_error.rb

@@ -10,6 +10,7 @@ module Filterameter
       attr_reader :errors
 
       def initialize(errors)
+        super
         @errors = errors
       end
 

data/lib/filterameter/filter_declaration.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require 'active_support/core_ext/array/wrap'
+require 'filterameter/options/partial_options'
 
 module Filterameter
   # = Filter Declaration
   #
   # Class FilterDeclaration captures the filter declaration within the controller.
   class FilterDeclaration
+    VALID_RANGE_OPTIONS = [true, :min_only, :max_only].freeze
+
     attr_reader :name, :parameter_name, :association, :validations
 
     def initialize(parameter_name, options)
@@ -17,6 +20,8 @@ module Filterameter
       @association = options[:association]
       @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]
     end
 
     def nested?
@@ -31,10 +36,41 @@ module Filterameter
       @filter_on_empty
     end
 
+    def partial_search?
+      partial_options.present?
+    end
+
+    def partial_options
+      @partial_options ||= @raw_partial_options ? Options::PartialOptions.new(@raw_partial_options) : nil
+    end
+
+    def range_enabled?
+      @raw_range.present?
+    end
+
+    def range?
+      @raw_range == true
+    end
+
+    def minimum?
+      @raw_range == :min_only
+    end
+
+    def maximum?
+      @raw_range == :max_only
+    end
+
     private
 
     def validate_options(options)
-      options.assert_valid_keys(:name, :association, :filter_on_empty, :validates)
+      options.assert_valid_keys(:name, :association, :filter_on_empty, :validates, :partial, :range)
+      validate_range(options[:range]) if options.key?(:range)
+    end
+
+    def validate_range(range)
+      return if VALID_RANGE_OPTIONS.include?(range)
+
+      raise ArgumentError, "Invalid range option: #{range}"
     end
   end
 end

data/lib/filterameter/filter_factory.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require 'filterameter/filters/arel_filter'
 require 'filterameter/filters/attribute_filter'
 require 'filterameter/filters/conditional_scope_filter'
+require 'filterameter/filters/matches_filter'
+require 'filterameter/filters/maximum_filter'
+require 'filterameter/filters/minimum_filter'
 require 'filterameter/filters/nested_filter'
 require 'filterameter/filters/scope_filter'
 
@@ -16,19 +20,25 @@ module Filterameter
 
     def build(declaration)
       model = declaration.nested? ? model_from_association(declaration.association) : @model_class
-      filter = build_filter(model, declaration.name)
+      filter = build_filter(model, declaration)
 
       declaration.nested? ? Filterameter::Filters::NestedFilter.new(declaration.association, model, filter) : filter
     end
 
     private
 
-    def build_filter(model, name)
+    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?(name) && !model.dangerous_class_method?(name)
-        Filterameter::Filters::ScopeFilter.new(name)
+      if model.respond_to?(declaration.name) && !model.dangerous_class_method?(declaration.name)
+        Filterameter::Filters::ScopeFilter.new(declaration.name)
+      elsif declaration.partial_search?
+        Filterameter::Filters::MatchesFilter.new(declaration.name, declaration.partial_options)
+      elsif declaration.minimum?
+        Filterameter::Filters::MinimumFilter.new(model, declaration.name)
+      elsif declaration.maximum?
+        Filterameter::Filters::MaximumFilter.new(model, declaration.name)
       else
-        Filterameter::Filters::AttributeFilter.new(name)
+        Filterameter::Filters::AttributeFilter.new(declaration.name)
       end
     end
 

data/lib/filterameter/filter_registry.rb

@@ -0,0 +1,62 @@
+# 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)
+      @declarations[parameter_name.to_s] = Filterameter::FilterDeclaration.new(parameter_name, options).tap do |fd|
+        add_declarations_for_range(fd, options, parameter_name) if fd.range_enabled?
+      end
+    end
+
+    def fetch(name)
+      name = 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.minimum?
+      add_range_maximum(parameter_name, options) if attribute_declaration.range? || attribute_declaration.maximum?
+      capture_range_declaration(parameter_name) if attribute_declaration.range?
+    end
+
+    def add_range_minimum(parameter_name, options)
+      parameter_name_min = "#{parameter_name}_min"
+      @declarations[parameter_name_min] = Filterameter::FilterDeclaration.new(parameter_name_min,
+                                                                              options.merge(range: :min_only))
+    end
+
+    def add_range_maximum(parameter_name, options)
+      parameter_name_min = "#{parameter_name}_max"
+      @declarations[parameter_name_min] = Filterameter::FilterDeclaration.new(parameter_name_min,
+                                                                              options.merge(range: :max_only))
+    end
+
+    def capture_range_declaration(name)
+      @ranges[name] = { min: "#{name}_min", max: "#{name}_max" }
+    end
+  end
+end

data/lib/filterameter/filterable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Declarative Filters
+  #
+  # Mixin Filterable provides class methods <tt>filter</tt> and <tt>filters</tt>.
+  module Filterable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declares a filter that can be read from the parameters and applied to the ActiveRecord query. The <tt>name</tt>
+      # identifies the name of the parameter and is the default value to determine the criteria to be applied. The name
+      # can be either an attribute or a scope.
+      #
+      # === 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.
+      #
+      # [:validates]
+      #   Specify a validation if the parameter value should be validated. This uses ActiveModel validations;
+      #   please review those for types of validations and usage.
+      #
+      # [: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)
+      #
+      #   There are two shortcuts: : the partial option can be declared with `true`, which just uses the
+      #   defaults; or the partial option can be declared with the match option directly,
+      #   such as `partial: :from_start`.
+      #
+      # [:range]
+      #   Specify a range option if the filter also allows ranges to be searched. The range option accepts
+      #   the following options:
+      #   - true: enables two additional parameters with attribute name plus suffixes <tt>_min</tt> and <tt>_max</tt>
+      #   - :min_only: enables additional parameter with attribute name plus suffix <tt>_min</tt>
+      #   - :max_only: enables additional parameter with attribute name plus suffix <tt>_max</tt>
+      def filter(name, options = {})
+        filter_coordinator.add_filter(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 filters(*names)
+        names.each { |name| filter(name) }
+      end
+    end
+  end
+end

data/lib/filterameter/filters/arel_filter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Filters
+    # = Arel Filter
+    #
+    # Class ArelFilter is a base class for arel queries. It does not implement <tt>apply</tt>.
+    class ArelFilter
+      def initialize(model, attribute_name)
+        @arel_attribute = model.arel_table[attribute_name]
+      end
+    end
+  end
+end

data/lib/filterameter/filters/matches_filter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Filters
+    # = Matches Filter
+    #
+    # Class MatchesFilter uses arel's `matches` to generate a LIKE query.
+    class MatchesFilter
+      def initialize(attribute_name, options)
+        @attribute_name = attribute_name
+        @prefix = options.match_anywhere? ? '%' : nil
+        @suffix = options.match_anywhere? || options.match_from_start? ? '%' : nil
+        @case_sensitive = options.case_sensitive?
+      end
+
+      def apply(query, value)
+        arel = query.arel_table[@attribute_name].matches("#{@prefix}#{value}#{@suffix}", false, @case_sensitive)
+        query.where(arel)
+      end
+    end
+  end
+end

data/lib/filterameter/filters/maximum_filter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Filters
+    # = Maximum Filter
+    #
+    # Class MaximumFilter adds criteria for all values greater than or equal to a maximum.
+    class MaximumFilter < ArelFilter
+      def apply(query, value)
+        query.where(@arel_attribute.lteq(value))
+      end
+    end
+  end
+end

data/lib/filterameter/filters/minimum_filter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Filters
+    # = Minimum Filter
+    #
+    # Class MinimumFilter adds criteria for all values greater than or equal to a minimum.
+    class MinimumFilter < ArelFilter
+      def apply(query, value)
+        query.where(@arel_attribute.gteq(value))
+      end
+    end
+  end
+end

data/lib/filterameter/options/partial_options.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Options
+  # = Partial Options
+  #
+  # Class PartialOptions parses the options passed in as partial, then exposes those. Here are the options along with
+  # their valid values:
+  # - match: anywhere (default), from_start, dynamic
+  # - case_sensitive: true, false (default)
+  #
+  # Options may be specified by passing a hash with the option keys:
+  #
+  #   partial: { match: :from_start, case_sensitive: true }
+  #
+  # There are two shortcuts: the partial option can be declared with `true`, which just uses the defaults; or the
+  # partial option can be declared with the match option directly, such as partial: :from_start.
+  class PartialOptions
+    VALID_OPTIONS = %i[match case_sensitive].freeze
+    VALID_MATCH_OPTIONS = %w[anywhere from_start dynamic].freeze
+
+    def initialize(options)
+      @match = 'anywhere'
+      @case_sensitive = false
+
+      case options
+      when TrueClass
+        nil
+      when Hash
+        evaluate_hash(options)
+      when String, Symbol
+        assign_match(options)
+      end
+    end
+
+    def case_sensitive?
+      @case_sensitive
+    end
+
+    def match_anywhere?
+      @match == 'anywhere'
+    end
+
+    def match_from_start?
+      @match == 'from_start'
+    end
+
+    def match_dynamically?
+      @match == 'dynamic'
+    end
+
+    private
+
+    def evaluate_hash(options)
+      options.assert_valid_keys(:match, :case_sensitive)
+      assign_match(options[:match]) if options.key?(:match)
+      assign_case_sensitive(options[:case_sensitive]) if options.key?(:case_sensitive)
+    end
+
+    def assign_match(value)
+      validate_match(value)
+      @match = value.to_s
+    end
+
+    def validate_match(value)
+      return if VALID_MATCH_OPTIONS.include? value.to_s
+
+      raise ArgumentError,
+            "Invalid match option for partial: #{value}. Valid options are #{VALID_MATCH_OPTIONS.to_sentence}"
+    end
+
+    def assign_case_sensitive(value)
+      validate_case_sensitive(value)
+      @case_sensitive = value
+    end
+
+    def validate_case_sensitive(value)
+      return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      raise ArgumentError, "Invalid case_sensitive option for partial: #{value}. Valid options are true and false."
+    end
+  end
+end

data/lib/filterameter/parameters_base.rb

@@ -2,6 +2,7 @@
 
 require 'active_model/attribute_assignment'
 require 'active_model/validations'
+require 'filterameter/validators/inclusion_validator'
 
 module Filterameter
   # = Parameters
@@ -9,6 +10,7 @@ module Filterameter
   # Class Parameters is sub-classed to provide controller-specific validations.
   class ParametersBase
     include ActiveModel::Validations
+    include Filterameter::Validators
 
     def self.build_sub_class(declarations)
       Class.new(self).tap do |sub_class|

data/lib/filterameter/query_builder.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Query Builder
+  #
+  # Class Query Builder turns filter parameters into a query.
+  class QueryBuilder
+    def initialize(default_query, filter_registry)
+      @default_query = default_query
+      @registry = filter_registry
+    end
+
+    def build_query(filter_params, starting_query = nil)
+      valid_filters(filter_params)
+        .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
+    end
+
+    private
+
+    def add_filter_parameter_to_query(query, filter_name, parameter_value)
+      @registry.fetch(filter_name).apply(query, parameter_value)
+    rescue Filterameter::Exceptions::UndeclaredParameterError => e
+      handle_undeclared_parameter(e)
+      query
+    end
+
+    def valid_filters(filter_params)
+      remove_invalid_values(filter_params)
+    end
+
+    # if both min and max are present in the query parameters, replace with range
+    def convert_min_and_max_to_range(parameters)
+      @registry.ranges.each do |attribute_name, min_max_names|
+        next unless min_max_names.values.all? { |min_max_name| parameters[min_max_name].present? }
+
+        parameters[attribute_name] = Range.new(parameters.delete(min_max_names[:min]),
+                                               parameters.delete(min_max_names[:max]))
+      end
+    end
+
+    def handle_undeclared_parameter(exception)
+      action = Filterameter.configuration.action_on_undeclared_parameters
+      return unless action
+
+      case action
+      when :log
+        ActiveSupport::Notifications.instrument('undeclared_parameters.filterameter', key: exception.key)
+      when :raise
+        raise exception
+      end
+    end
+
+    def remove_invalid_values(filter_params)
+      validator = validator_class.new(filter_params)
+      return filter_params if validator.valid?
+
+      case Filterameter.configuration.action_on_validation_failure
+      when :log
+        ActiveSupport::Notifications.instrument('validation_failure.filterameter', errors: validator.errors)
+      when :raise
+        raise Filterameter::Exceptions::ValidationError, validator.errors
+      end
+
+      filter_params.except(*validator.errors.attribute_names.map(&:to_s))
+    end
+
+    def validator_class
+      @validator_class ||= Filterameter::ParametersBase.build_sub_class(@registry.filter_declarations)
+    end
+  end
+end

data/lib/filterameter/validators/inclusion_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Validators
+    # = Inclusion Validator
+    #
+    # Class InclusionValidator extends ActiveModel::Validations::InclusionValidator to enable validations of multiple
+    # values.
+    #
+    # == Example
+    #
+    #   validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
+    #
+    class InclusionValidator < ActiveModel::Validations::InclusionValidator
+      def validate_each(record, attribute, value)
+        return super unless allow_multiple_values?
+
+        # any? just provides a mechanism to stop after first error
+        Array.wrap(value).any? { |v| super(record, attribute, v) }
+      end
+
+      private
+
+      def allow_multiple_values?
+        @options.fetch(:allow_multiple_values, false)
+      end
+    end
+  end
+end

data/lib/filterameter/version.rb

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

data/lib/filterameter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'filterameter/configuration'
+require 'filterameter/declarative_controller_filters'
 require 'filterameter/declarative_filters'
 require 'filterameter/exceptions'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Todd Kummer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-13 00:00:00.000000000 Z
+date: 2021-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,20 +24,62 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 5.2.2
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: guard-rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.4
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -58,28 +100,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.77'
+        version: 1.22.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.22.3
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.77'
+        version: 2.8.1
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.18'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.18'
 description: Enable filter parameters to be declared in controllers.
 email:
 - todd@rockridgesolutions.com
@@ -92,7 +148,10 @@ files:
 - Rakefile
 - lib/filterameter.rb
 - lib/filterameter/configuration.rb
-- lib/filterameter/controller_filters.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
@@ -100,19 +159,27 @@ files:
 - lib/filterameter/exceptions/validation_error.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
 - lib/filterameter/filters/conditional_scope_filter.rb
+- lib/filterameter/filters/matches_filter.rb
+- lib/filterameter/filters/maximum_filter.rb
+- lib/filterameter/filters/minimum_filter.rb
 - lib/filterameter/filters/nested_filter.rb
 - lib/filterameter/filters/scope_filter.rb
 - lib/filterameter/log_subscriber.rb
+- lib/filterameter/options/partial_options.rb
 - lib/filterameter/parameters_base.rb
+- lib/filterameter/query_builder.rb
+- lib/filterameter/validators/inclusion_validator.rb
 - lib/filterameter/version.rb
-- lib/tasks/filterameter_tasks.rake
 homepage: https://github.com/RockSolt/filterameter
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -128,7 +195,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.0.8
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Declarative Filter Parameters for Rails Controllers
 test_files: []

data/lib/filterameter/controller_filters.rb

@@ -1,110 +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'
-
-require 'filterameter/filter_factory'
-require 'filterameter/filter_declaration'
-require 'filterameter/log_subscriber'
-require 'filterameter/parameters_base'
-
-module Filterameter
-  # = 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 ControllerFilters
-    attr_writer :query_variable_name
-
-    def initialize(controller_name, controller_path)
-      @controller_name = controller_name
-      @controller_path = controller_path
-      @declarations = {}
-      @filters = Hash.new { |hash, key| hash[key] = filter_factory.build(@declarations[key]) }
-    end
-
-    def model_class=(model_class)
-      @model_class = model_class.is_a?(String) ? model_class.constantize : model_class
-    end
-
-    def add_filter(parameter_name, options)
-      @declarations[parameter_name.to_s] = Filterameter::FilterDeclaration.new(parameter_name, options)
-    end
-
-    def query_variable_name
-      @query_variable_name ||= model_class.model_name.plural
-    end
-
-    def build_query(filter_params, starting_query)
-      valid_filters(filter_params).reduce(starting_query || model_class.all) do |query, (name, value)|
-        @filters[name].apply(query, value)
-      end
-    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
-
-    # lazy so that model_class can be optionally set
-    def filter_factory
-      @filter_factory ||= Filterameter::FilterFactory.new(model_class)
-    end
-
-    def valid_filters(filter_params)
-      remove_invalid_values(
-        remove_undeclared_filters(filter_params)
-      )
-    end
-
-    def remove_undeclared_filters(filter_params)
-      filter_params.slice(*declared_parameter_names).tap do |declared_parameters|
-        handle_undeclared_parameters(filter_params) if declared_parameters.size != filter_params.size
-      end
-    end
-
-    def handle_undeclared_parameters(filter_params)
-      action = Filterameter.configuration.action_on_undeclared_parameters
-      return unless action
-
-      undeclared_parameter_names = filter_params.keys - declared_parameter_names
-      case action
-      when :log
-        ActiveSupport::Notifications.instrument('undeclared_parameters.filterameter', keys: undeclared_parameter_names)
-      when :raise
-        raise Filterameter::Exceptions::UndeclaredParameterError, undeclared_parameter_names
-      end
-    end
-
-    def remove_invalid_values(filter_params)
-      validator = validator_class.new(filter_params)
-      return filter_params if validator.valid?
-
-      case Filterameter.configuration.action_on_validation_failure
-      when :log
-        ActiveSupport::Notifications.instrument('validation_failure.filterameter', errors: validator.errors)
-      when :raise
-        raise Filterameter::Exceptions::ValidationError, validator.errors
-      end
-
-      filter_params.except(*validator.errors.keys.map(&:to_s))
-    end
-
-    def declared_parameter_names
-      @declared_parameter_names ||= @declarations.keys
-    end
-
-    def validator_class
-      @validator_class ||= Filterameter::ParametersBase.build_sub_class(@declarations.values)
-    end
-  end
-end

data/lib/tasks/filterameter_tasks.rake

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-# desc "Explaining what the task does"
-# task :filterameter do
-#   # Task goes here
-# end