filterameter 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f62d4fc49f10adca7c1fec20fb17e430740035d69b154f973d8f300405f64f9c
-  data.tar.gz: 7369430dbb71a29faf17853a35eaa69f3a35fae52b82d63e85f5c14bd550aa51
+  metadata.gz: 929699bdcf63b640acc335ab2b6690e4d57822541e354f93aa9faf71ef0faf3c
+  data.tar.gz: 205958bfb5a55418e740382146934b8aa7f3ef122686f903621b6de1f14a2788
 SHA512:
-  metadata.gz: e5ee234ae90460282e2618135b96f91882af00361b1c16eda99beb42640cf9c4186d1bb61fa1989235015a1f4dff07f7611ca5dea55ec6277c27dc9239329bc8
-  data.tar.gz: 6f802f89428a06de2f077d5c4b38464bc8ad1ee4327d334856f3421481cba3af84ef789cb2e85863fe933f8b45f90fe2b7640910d16618bb97e35c65d9bda691
+  metadata.gz: dd04092048f8c2d00d4df6f77136e4714e21385b08ca21f0fe1608ba0ff7b12d97d1ca27fc26024f7d52180cb1013546c520131cfe35e90fa688d5c36a185071
+  data.tar.gz: 1a065d5dcd20ac179e80b1d507ed52de4be84704651cbba2b7fa68c65c0793db06577eec83c68949e880173bfa8ffae930eca2d0ceec68952d26901be7649c93

data/README.md

@@ -340,8 +340,22 @@ If the filter parameters are NOT nested, set this to false. Doing so will restri
 those that have been declared, meaning undeclared parameters are ignored (and the action_on_undeclared_parameters
 configuration option does not come into play).
 
+### Testing Declarations
 
+The declarations can be tested for each controller, catching typos, incorrectly defined scopes, or any other issues. Method `declarations_validator` is added to each controller, and a single controller test can be added to validate all the declarations for that controller.
 
+An RSpec test might look like this:
+
+```ruby
+expect(WidgetsController.declarations_validator).to be_valid
+```
+
+In Minitest it might look like this:
+
+```ruby
+validator = WidgetsController.declarations_validator
+assert_predicate validator, :valid?, -> { validator.errors }
+```
 
 ## Installation
 Add this line to your application's Gemfile:

data/lib/filterameter/declaration_errors/cannot_be_inline_scope_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = CannotBeInlineScopeError
+    #
+    # Error CannotBeInlineScopeError occurs when an inline scope has been used to define a filter that takes a
+    # parameter. This is not valid for use as a Filterameter filter because an inline scope always has an arity of -1
+    # meaning the factory cannot tell if it has an argument or not. As such, all inline scopes are assumed to not have
+    # arguments and thus be conditional scopes.
+    #
+    # [The Rails guide](https://guides.rubyonrails.org/active_record_querying.html#passing-in-arguments) provides
+    # guidance suggesting scopes that take arguments be written as class methods. This takes that guidance a step
+    # further and makes it a requirement for a scope that will be used as a filter.
+    class CannotBeInlineScopeError < DeclarationError
+      def initialize(model_name, scope_name)
+        super(<<~ERROR.chomp)
+          #{model_name} scope '#{scope_name}' needs to be written as a class method, not as an inline scope. This is a
+            suggestion from the Rails guide but a requirement in order to use a scope that has an argument as a filter.
+        ERROR
+      end
+    end
+  end
+end

data/lib/filterameter/declaration_errors/filter_scope_argument_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = Filter Scope Argument Error
+    #
+    # Error FilterScopeArgumentError occurs when a scope used as a filter but does not have either zero or one
+    # arument. A conditional scope filter should take zero arguments; other scope filters should take one argument.
+    class FilterScopeArgumentError < DeclarationError
+      def initialize(model_name, scope_name)
+        super("#{model_name} scope '#{scope_name}' takes too many arguments. Scopes for filters can only have either " \
+              'zero (conditional scope) or one argument')
+      end
+    end
+  end
+end

data/lib/filterameter/declaration_errors/no_such_attribute_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = No Such Attribute Error
+    #
+    # Error NoSuchAttributeError occurs when a filter or sort references an attribute that does not exist on the model.
+    # The most likely case of this is a typo. Note that if the typo was supposed to reference a scope, this error is
+    # added as attributes are assumed when no matching scopes are found.
+    class NoSuchAttributeError < DeclarationError
+      def initialize(model_name, attribute_name)
+        super("Attribute '#{attribute_name}' does not exist on #{model_name}")
+      end
+    end
+  end
+end

data/lib/filterameter/declaration_errors/not_a_scope_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = Not A Scope Error
+    #
+    # Error NotAScopeError flags a class method that has been used as a filter but is not a scope. This could occur if
+    # there is a class method of the same name an attribute, in which case the class method is going to block the
+    # creation of an attribute filter. The work around (if the class method cannot be renamed) is to create a scope
+    # that provides a filter on the attribute.
+    class NotAScopeError < DeclarationError
+      def initialize(model_name, scope_name)
+        super("#{model_name} class method '#{scope_name}' is not a scope.")
+      end
+    end
+  end
+end

data/lib/filterameter/declaration_errors/sort_scope_requires_one_argument_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = Sort Scope Requires One Argument Error
+    #
+    # Error SortScopeRequiresOneArgumentError occurs when a sort has been declared for a scope that does not take
+    # exactly one argument. Sort scopes must take a single argument and will receive either :asc or :desc to indicate
+    # the direction.
+    class SortScopeRequiresOneArgumentError < DeclarationError
+      def initialize(model_name, scope_name)
+        super("#{model_name} scope '#{scope_name}' must take exactly one argument to sort by.")
+      end
+    end
+  end
+end

data/lib/filterameter/declaration_errors/unexpected_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = Unexpected Error
+    #
+    # Error UnexpectedError occurs when the filter or scope factory raises an exception that the validator did not
+    # expect.
+    class UnexpectedError < DeclarationError
+      def initialize(error)
+        super(<<~ERROR)
+          The previous error was unexpected. It occurred during while building a filter or sort (see below). Please
+          report this to the library so that the error can be handled and provide clearer feedback about what is wrong
+          with the declaration.
+
+          #{error.message}
+            #{error.backtrace.join("\n\t")}
+        ERROR
+      end
+    end
+  end
+end

data/lib/filterameter/declaration_errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module DeclarationErrors
+    # = Declaration Error
+    #
+    # Error DeclarationError provides a base class for errors from filter or sort declarations.
+    class DeclarationError < StandardError
+    end
+  end
+end

data/lib/filterameter/declarations_validator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Declarations Validator
+  #
+  # Class DeclarationsValidtor fetches each filter and sort from the registry to validate the declaration. This class
+  # can be accessed from the controller as `declarations_validator` (via the FilterCoordinator) and be used in tests.
+  #
+  # Use the `valid?` method to test, then report errors with the `errors` attribute.
+  #
+  # A test in RSpec might look like this:
+  #
+  #   expect(WidgetsController.declarations_validator).to be_valid
+  #
+  # In Minitest it might look like this:
+  #
+  #   assert WidgetsController.declarations_validator.valid?, WidgetsController.declarations_validator.errors
+  class DeclarationsValidator
+    include Filterameter::Errors
+
+    def initialize(controller_name, model, registry)
+      @controller_name = controller_name
+      @model = model
+      @registry = registry
+    end
+
+    def inspect
+      "filter declarations on #{@controller_name.titleize}Controller"
+    end
+
+    def errors
+      @errors&.join("\n")
+    end
+
+    private
+
+    def validate(_)
+      @errors.push(*validation_errors_for('filter', fetch_filters))
+      @errors.push(*validation_errors_for('sort', fetch_sorts))
+    end
+
+    def fetch_filters
+      @registry.filter_parameter_names.index_with { |name| fetch_filter(name) }
+    end
+
+    def fetch_filter(name)
+      @registry.fetch_filter(name)
+    rescue StandardError => e
+      FactoryErrors.new(e)
+    end
+
+    def fetch_sorts
+      (@registry.sort_parameter_names - @registry.filter_parameter_names).index_with { |name| fetch_sort(name) }
+    end
+
+    def fetch_sort(name)
+      @registry.fetch_sort(name)
+    rescue StandardError => e
+      FactoryErrors.new(e)
+    end
+
+    def validation_errors_for(type, items)
+      items.select { |_name, item| item.respond_to? :valid? }
+           .reject { |_name, item| item.valid?(@model) }
+           .map { |name, item| error_message(type, name, item.errors) }
+    end
+
+    def error_message(type, name, errors)
+      "\nInvalid #{type} for '#{name}':\n  #{errors.join("\n  ")}"
+    end
+
+    # = Factory Errors
+    #
+    # Class FactoryErrors is swapped in if the fetch from a factory fails. It is always invalid and provides the reason.
+    class FactoryErrors
+      attr_reader :errors
+
+      def initialize(error)
+        @errors = [wrap_if_unexpected(error)]
+      end
+
+      def valid?(_)
+        false
+      end
+
+      def to_s
+        @errors.join("\n")
+      end
+
+      private
+
+      def wrap_if_unexpected(error)
+        return error if error.is_a?(Filterameter::DeclarationErrors::DeclarationError)
+
+        Filterameter::DeclarationErrors::UnexpectedError.new(error)
+      end
+    end
+  end
+end

data/lib/filterameter/declarative_filters.rb

@@ -10,6 +10,8 @@ module Filterameter
     include Filterameter::Sortable
 
     class_methods do
+      delegate :declarations_validator, to: :filter_coordinator
+
       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?

data/lib/filterameter/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Filterameter
+  # = Errors
+  #
+  # Module Errors provides `valid?` and `errors` to implementing classes. If the `valid?` method is not overridden,
+  # then it returns true.
+  #
+  # To provide validations rules, override `validate`. If any fail, populate the errors attribute with the
+  # reason for the failures.
+  module Errors
+    attr_reader :errors
+
+    def valid?(model = nil)
+      @errors = []
+      validate(model)
+      @errors.empty?
+    end
+
+    private
+
+    def validate(_model); end
+  end
+end

data/lib/filterameter/filter_coordinator.rb

@@ -45,6 +45,10 @@ module Filterameter
       end
     end
 
+    def declarations_validator
+      Filterameter::DeclarationsValidator.new(@controller_name, model_class, registry)
+    end
+
     private
 
     def model_class

data/lib/filterameter/filter_factory.rb

@@ -46,10 +46,13 @@ module Filterameter
     # 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
+      number_of_arguments = model.method(declaration.name).arity
+      if number_of_arguments < 1
+        Filterameter::Filters::ConditionalScopeFilter.new(declaration.name)
+      elsif number_of_arguments == 1
         Filterameter::Filters::ScopeFilter.new(declaration.name)
       else
-        Filterameter::Filters::ConditionalScopeFilter.new(declaration.name)
+        raise Filterameter::DeclarationErrors::FilterScopeArgumentError.new(model.name, declaration.name)
       end
     end
   end

data/lib/filterameter/filters/arel_filter.rb

@@ -6,7 +6,11 @@ module Filterameter
     #
     # Class ArelFilter is a base class for arel queries. It does not implement <tt>apply</tt>.
     class ArelFilter
+      include Filterameter::Errors
+      include Filterameter::Filters::AttributeValidator
+
       def initialize(model, attribute_name)
+        @attribute_name = attribute_name
         @arel_attribute = model.arel_table[attribute_name]
       end
     end

data/lib/filterameter/filters/attribute_filter.rb

@@ -6,6 +6,9 @@ module Filterameter
     #
     # Class AttributeFilter leverages ActiveRecord's where query method to add criteria for an attribute.
     class AttributeFilter
+      include Filterameter::Errors
+      include AttributeValidator
+
       def initialize(attribute_name)
         @attribute_name = attribute_name
       end

data/lib/filterameter/filters/attribute_validator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Filters
+    # = Attribute Validator
+    #
+    # Module AttributeValidator validates that the attribute exists on the model.
+    module AttributeValidator
+      private
+
+      def validate(model)
+        return if model.attribute_method? @attribute_name
+
+        @errors << Filterameter::DeclarationErrors::NoSuchAttributeError.new(model, @attribute_name)
+      end
+    end
+  end
+end

data/lib/filterameter/filters/conditional_scope_filter.rb

@@ -6,6 +6,8 @@ module Filterameter
     #
     # Class ConditionalScopeFilter applies the scope if the parameter is not false.
     class ConditionalScopeFilter
+      include Filterameter::Errors
+
       def initialize(scope_name)
         @scope_name = scope_name
       end
@@ -15,6 +17,20 @@ module Filterameter
 
         query.public_send(@scope_name)
       end
+
+      private
+
+      def validate(model)
+        validate_is_a_scope(model)
+      rescue ArgumentError
+        @errors << Filterameter::DeclarationErrors::CannotBeInlineScopeError.new(model.name, @scope_name)
+      end
+
+      def validate_is_a_scope(model)
+        return if model.public_send(@scope_name).is_a? ActiveRecord::Relation
+
+        @errors << Filterameter::DeclarationErrors::NotAScopeError.new(model.name, @scope_name)
+      end
     end
   end
 end

data/lib/filterameter/filters/matches_filter.rb

@@ -6,6 +6,9 @@ module Filterameter
     #
     # Class MatchesFilter uses arel's `matches` to generate a LIKE query.
     class MatchesFilter
+      include Filterameter::Errors
+      include Filterameter::Filters::AttributeValidator
+
       def initialize(attribute_name, options)
         @attribute_name = attribute_name
         @prefix = options.match_anywhere? ? '%' : nil

data/lib/filterameter/filters/nested_filter.rb

@@ -6,6 +6,8 @@ module Filterameter
     #
     # Class NestedFilter joins the nested table(s) then merges the filter to the association's model.
     class NestedFilter
+      include Filterameter::Errors
+
       def initialize(association_names, association_model, attribute_filter)
         @joins_values = Filterameter::Helpers::JoinsValuesBuilder.build(association_names)
         @association_model = association_model
@@ -16,6 +18,19 @@ module Filterameter
         query.joins(@joins_values)
              .merge(@attribute_filter.apply(@association_model.all, value))
       end
+
+      private
+
+      def validate(model)
+        @errors.push(*@attribute_filter.errors) unless @attribute_filter.valid?(@association_model)
+        validate_associations(model)
+      end
+
+      def validate_associations(model)
+        model.joins(@joins_values).to_sql
+      rescue ActiveRecord::ConfigurationError => e
+        @errors << e.message
+      end
     end
   end
 end

data/lib/filterameter/filters/scope_filter.rb

@@ -6,6 +6,8 @@ module Filterameter
     #
     # Class ScopeFilter applies the named scope passing in the parameter value.
     class ScopeFilter
+      include Filterameter::Errors
+
       def initialize(scope_name)
         @scope_name = scope_name
       end
@@ -13,6 +15,18 @@ module Filterameter
       def apply(query, value)
         query.public_send(@scope_name, value)
       end
+
+      private
+
+      def validate(model)
+        validate_is_a_scope(model)
+      end
+
+      def validate_is_a_scope(model)
+        return if model.public_send(@scope_name, '42').is_a? ActiveRecord::Relation
+
+        @errors << Filterameter::DeclarationErrors::NotAScopeError.new(model.name, @scope_name)
+      end
     end
   end
 end

data/lib/filterameter/registries/filter_registry.rb

@@ -24,10 +24,6 @@ module Filterameter
         @declarations.values
       end
 
-      def filter_parameter_names
-        @declarations.keys
-      end
-
       private
 
       # if range is enabled, then in addition to the attribute filter this also adds min and/or max filters

data/lib/filterameter/registries/registry.rb

@@ -6,7 +6,9 @@ module Filterameter
     #
     # Class Registry records declarations and allows resulting filters and sorts to be fetched from sub-registries.
     class Registry
-      delegate :filter_declarations, :filter_parameter_names, :ranges, to: :@filter_registry
+      delegate :filter_declarations, :ranges, to: :@filter_registry
+      delegate :parameter_names, prefix: :filter, to: :@filter_registry
+      delegate :parameter_names, prefix: :sort, to: :@sort_registry
 
       def initialize(model_class)
         @filter_registry = Filterameter::Registries::FilterRegistry.new(Filterameter::FilterFactory.new(model_class))

data/lib/filterameter/registries/sort_registry.rb

@@ -7,6 +7,10 @@ module Filterameter
     # Class SortRegistry is a collection of the sorts. It captures the declarations when classes are loaded,
     # then uses the injected SortFactory to build the sorts on demand as they are needed.
     class SortRegistry < SubRegistry
+      def sort_parameter_names
+        @declarations.keys
+      end
+
       private
 
       def build_declaration(name, options)

data/lib/filterameter/registries/sub_registry.rb

@@ -28,6 +28,10 @@ module Filterameter
           @registry[name] = @factory.build(@declarations[name])
         end
       end
+
+      def parameter_names
+        @declarations.keys
+      end
     end
   end
 end

data/lib/filterameter/sort_factory.rb

@@ -33,7 +33,7 @@ module Filterameter
 
     def build_sort(name, declaration_is_a_scope)
       if declaration_is_a_scope
-        Filterameter::Filters::ScopeFilter.new(name)
+        Filterameter::Sorts::ScopeSort.new(name)
       else
         Filterameter::Sorts::AttributeSort.new(name)
       end

data/lib/filterameter/sorts/attribute_sort.rb

@@ -6,6 +6,9 @@ module Filterameter
     #
     # Class AttributeSort leverages ActiveRecord's `order` query method to add sorting for an attribute.
     class AttributeSort
+      include Filterameter::Errors
+      include Filterameter::Filters::AttributeValidator
+
       def initialize(attribute_name)
         @attribute_name = attribute_name
       end

data/lib/filterameter/sorts/scope_sort.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Filterameter
+  module Sorts
+    # = Scope Sort
+    #
+    # Class ScopeSort applies the scope with the a param that is either :asc or :desc. A scope that does not take
+    # exactly one argument is not valid for sorting.
+    class ScopeSort < Filterameter::Filters::ScopeFilter
+      private
+
+      def validate(model)
+        validate_is_a_scope(model)
+      rescue ArgumentError
+        @errors << Filterameter::DeclarationErrors::SortScopeRequiresOneArgumentError.new(model.name, @scope_name)
+      end
+
+      def validate_is_a_scope(model)
+        return if model.public_send(@scope_name, :asc).is_a? ActiveRecord::Relation
+
+        @errors << Filterameter::DeclarationErrors::NotAScopeError.new(model.name, @scope_name)
+      end
+    end
+  end
+end

data/lib/filterameter/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Todd Kummer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-18 00:00:00.000000000 Z
+date: 2024-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -150,6 +150,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.25'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.30.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.30.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -176,7 +204,16 @@ files:
 - Rakefile
 - lib/filterameter.rb
 - lib/filterameter/configuration.rb
+- lib/filterameter/declaration_errors.rb
+- lib/filterameter/declaration_errors/cannot_be_inline_scope_error.rb
+- lib/filterameter/declaration_errors/filter_scope_argument_error.rb
+- lib/filterameter/declaration_errors/no_such_attribute_error.rb
+- lib/filterameter/declaration_errors/not_a_scope_error.rb
+- lib/filterameter/declaration_errors/sort_scope_requires_one_argument_error.rb
+- lib/filterameter/declaration_errors/unexpected_error.rb
+- lib/filterameter/declarations_validator.rb
 - lib/filterameter/declarative_filters.rb
+- lib/filterameter/errors.rb
 - lib/filterameter/exceptions.rb
 - lib/filterameter/exceptions/cannot_determine_model_error.rb
 - lib/filterameter/exceptions/collection_association_sort_error.rb
@@ -189,6 +226,7 @@ files:
 - lib/filterameter/filterable.rb
 - lib/filterameter/filters/arel_filter.rb
 - lib/filterameter/filters/attribute_filter.rb
+- lib/filterameter/filters/attribute_validator.rb
 - lib/filterameter/filters/conditional_scope_filter.rb
 - lib/filterameter/filters/matches_filter.rb
 - lib/filterameter/filters/maximum_filter.rb
@@ -211,6 +249,7 @@ files:
 - lib/filterameter/sort_factory.rb
 - lib/filterameter/sortable.rb
 - lib/filterameter/sorts/attribute_sort.rb
+- lib/filterameter/sorts/scope_sort.rb
 - lib/filterameter/validators/inclusion_validator.rb
 - lib/filterameter/version.rb
 homepage: https://github.com/RockSolt/filterameter
@@ -225,7 +264,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="