filterameter 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8110e021be072bc1f37dd324c42e590e3c91a94fbadd934fdc0758f1f85d700
-  data.tar.gz: 7ee31589a1fb66717647a1085658ab4dd5b9ba7deb58d847102fc72be1d9dffe
+  metadata.gz: 0baada12bc6ad382e146635629a89c47f935e92f1e4c72597889440305c46ebf
+  data.tar.gz: 427ecf17bd6458fbe76af104ab5b1eb32a4edb2adc3c0b73ac4fb329f1eba0f9
 SHA512:
-  metadata.gz: 83117da59a74ba92bf255cdb8ccd025f071f5549dfeb315af5894c12dc8829928fef6aae0eb6d94eaec7abfd5f2a85aa1d085bd7b3ec26d0b476d0506febd7a4
-  data.tar.gz: 3f777e21518ce18d2f62f36912ba3b532839a9f5d03bc73dd7796648d1fcec81992701b07ad639dbe021f7765ab5d5baa66d4d82bf92edc7264a2463df4044ff
+  metadata.gz: 24ce1e8ca752befea919c57f5e79af75d80f77569d0171a052b1b1a14c65af5d0e6ad234127767e3f42bddb4d058feafdee58130cf38102cd4b10eef2bdc3ca9
+  data.tar.gz: 5e0ad2d3348d84df2d7198bc38611f0a3bb8ea52ce4882c61ca0289f48239afc11ec49f4b293fc79810cda25a92f8e236ad00b73bb3d4769e4d4912b99939651

data/README.md

@@ -1,3 +1,6 @@
+[![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)
+
 # Filterameter
 Declarative Filter Parameters for Rails Controllers.
 
@@ -57,6 +60,24 @@ The `match` options defines where you are searching (which then controls where t
 - 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>.
+
 ### Configuring Controllers
 
 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:

data/lib/filterameter/controller_filters.rb

@@ -25,6 +25,7 @@ module Filterameter
       @controller_name = controller_name
       @controller_path = controller_path
       @declarations = {}
+      @ranges = {}
       @filters = Hash.new { |hash, key| hash[key] = filter_factory.build(@declarations[key]) }
     end
 
@@ -33,7 +34,10 @@ module Filterameter
     end
 
     def add_filter(parameter_name, options)
-      @declarations[parameter_name.to_s] = Filterameter::FilterDeclaration.new(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 query_variable_name
@@ -41,7 +45,9 @@ module Filterameter
     end
 
     def build_query(filter_params, starting_query)
-      valid_filters(filter_params).reduce(starting_query || model_class.all) do |query, (name, value)|
+      valid_filters(filter_params)
+        .tap { |parameters| convert_min_and_max_to_range(parameters) }
+        .reduce(starting_query || model_class.all) do |query, (name, value)|
         @filters[name].apply(query, value)
       end
     end
@@ -66,6 +72,16 @@ module Filterameter
       )
     end
 
+    # if both min and max are present in the query parameters, replace with range
+    def convert_min_and_max_to_range(parameters)
+      @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 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
@@ -106,5 +122,27 @@ module Filterameter
     def validator_class
       @validator_class ||= Filterameter::ParametersBase.build_sub_class(@declarations.values)
     end
+
+    # 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)
+      @declarations["#{parameter_name}_min"] = Filterameter::FilterDeclaration.new(parameter_name,
+                                                                                   options.merge(range: :min_only))
+    end
+
+    def add_range_maximum(parameter_name, options)
+      @declarations["#{parameter_name}_max"] = Filterameter::FilterDeclaration.new(parameter_name,
+                                                                                   options.merge(range: :max_only))
+    end
+
+    # memoizing these makes it easier to spot and replace ranges in query parameters; see convert_min_and_max_to_range
+    def capture_range_declaration(name)
+      @ranges[name] = { min: "#{name}_min", max: "#{name}_max" }
+    end
   end
 end

data/lib/filterameter/declarative_filters.rb

@@ -19,6 +19,39 @@ module Filterameter
         controller_filters.query_variable_name = query_variable_name
       end
 
+      # 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 = {})
         controller_filters.add_filter(name, options)
       end

data/lib/filterameter/filter_declaration.rb

@@ -8,6 +8,8 @@ module Filterameter
   #
   # 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)
@@ -19,6 +21,7 @@ module Filterameter
       @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?
@@ -41,10 +44,33 @@ module Filterameter
       @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, :partial)
+      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,8 +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'
 
@@ -24,12 +27,16 @@ module Filterameter
 
     private
 
-    def build_filter(model, declaration)
+    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)
       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(declaration.name)
       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/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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Todd Kummer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-09 00:00:00.000000000 Z
+date: 2020-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -142,21 +142,23 @@ files:
 - lib/filterameter/exceptions/validation_error.rb
 - lib/filterameter/filter_declaration.rb
 - lib/filterameter/filter_factory.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/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
@@ -172,7 +174,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/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