filterameter 0.10.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 929699bdcf63b640acc335ab2b6690e4d57822541e354f93aa9faf71ef0faf3c
-  data.tar.gz: 205958bfb5a55418e740382146934b8aa7f3ef122686f903621b6de1f14a2788
+  metadata.gz: a250b39d9c80245166bcfe14a7133cd5ec83f9746989d7e461fa0c121358f57a
+  data.tar.gz: 5d7c64cb79fd73ee94e4e94316b0b5964fac440b14fb0bc58c0c1d805d0f9d60
 SHA512:
-  metadata.gz: dd04092048f8c2d00d4df6f77136e4714e21385b08ca21f0fe1608ba0ff7b12d97d1ca27fc26024f7d52180cb1013546c520131cfe35e90fa688d5c36a185071
-  data.tar.gz: 1a065d5dcd20ac179e80b1d507ed52de4be84704651cbba2b7fa68c65c0793db06577eec83c68949e880173bfa8ffae930eca2d0ceec68952d26901be7649c93
+  metadata.gz: d170eb98f80c24173fa92d0251aa68af7d5f3d002d4c3ff473e086aba8d16f07fd05422af6dced018331e883431c93292b4d0b7e5bf3476587b40df8dbeab8d3
+  data.tar.gz: e2342236255b79da8ee96aa7eec0e33c6e9f0131473eaadffd31f833c7212d01d2123eeb6a70cdff8d619ff8678f4d6aafc8d9b52151de9dc6583983f3accd92

data/README.md

@@ -4,13 +4,78 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/d9d87f9ce8020eb6e656/maintainability)](https://codeclimate.com/github/RockSolt/filterameter/maintainability)
 
 # Filterameter
-Declarative filter parameters provide clean and clear filters for Rails controllers.
+Filterameter provides declarative filters for Rails controllers to reduce boilerplate code and increase readability. How many times have you seen (or written) this controller action?
 
-## 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.
+```ruby
+def index
+  @films = Films.all
+  @films = @films.where(name: params[:name]) if params[:name]
+  @films = @films.joins(:film_locations).merge(FilmLocations.where(location_id: params[:location_id])) if params[:location_id]
+  @films = @films.directed_by(params[:director_id]) if params[:director_id]
+  @films = @films.written_by(params[:writer_id]) if params[:writer_id]
+  @films = @films.acted_by(params[:actor_id]) if params[:actor_id]
+end
+```
 
-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.
+It's redundant code and a bit of a pain to write and maintain. Not to mention what RuboCop is going to say about it. Wouldn't it be nice if you could just declare the filters that the controller accepts?
 
+```ruby
+  filter :name, partial: true
+  filter :location_id, association: :film_locations
+  filter :director_id, name: :directed_by
+  filter :writer_id, name: :written_by
+  filter :actor_id, name: :acted_by
+
+  def index
+    @films = build_query_from_filters
+  end
+```
+
+Simplify and speed development of Rails controllers by making filter parameters declarative with Filterameter.
+
+## Table of Contents
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+  - [Filtering Options](#filtering-options)
+    - [Name](#name)
+    - [Association](#association)
+    - [Validates](#validates)
+    - [Partial](#partial)
+    - [Range](#range)
+    - [Sortable](#sortable)
+  - [Scope Filters](#scope-filters)
+  - [Sorting](#sorting)
+  - [Building the Query](#building-the-query)
+  - [Specifying the Model](#specifying-the-model)
+- [Configuration](#configuration)
+- [Testing Declarations](#testing-declarations)
+- [Forms and Query Parameters](#forms-and-query-parameters)
+- [Contribute](#contribute)
+- [License](#license)
+
+## Getting Started
+
+This gem requires Rails 6.1+, and works with ActiveRecord.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'filterameter'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+```bash
+$ gem install filterameter
+```
+
+## Usage
+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
@@ -190,18 +255,6 @@ default_sort updated_at: :desc, :description
 
 In order to provide consistent results, a sort is always applied. If no default is specified, it will use primary key descending.
 
-### 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'
-```
-
-_Important:_ If the `filter_model` declaration is used, it must be before any filter or sort declarations.
-
 ### 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:
@@ -273,34 +326,29 @@ This method optionally takes a starting query. If there was a controller for Act
   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`
+The starting query is also a good place to provide any includes to enable eager loading:
 
-#### Sort Parameters
-
-The sort is also nested underneath the key `filter`. 
-
-`/widgets?filter[sort]=size`
+```ruby
+  def index
+    @widgets = build_query_from_filters(Widgets.includes(:manufacturer))
+  end
+```
 
-Use an array to pass multiple sorts. The order of the parameters is the order the sorts will be applied. For example, the following sorts first by size then by color:
+Note that the starting query provides the model, so the model is not looked up and the `model_name` declaration in not needed.
 
-`/widgets?filter[sort]=size&filter[sort]=color`
+### Specifying the Model
 
-Sorts are ascending by default, but can use a prefix can be added to control the sort:
+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. 
 
-- `+` ascending (the default)
-- `-` descending
+**If the conventions do not provide the correct model**, the model can be named explicitly with the following:
 
-For example, the following sorts by size descending:
+```ruby
+filter_model 'Picture'
+```
 
-`/widgets?filter[sort]=-size`
+_Important:_ If the `filter_model` declaration is used, it must be before any filter or sort declarations.
 
-### Configuration
+## Configuration
 
 There are three configuration options:
 
@@ -340,7 +388,7 @@ 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
+## 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.
 
@@ -357,26 +405,9 @@ validator = WidgetsController.declarations_validator
 assert_predicate validator, :valid?, -> { validator.errors }
 ```
 
-## Installation
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'filterameter'
-```
-
-And then execute:
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-```bash
-$ gem install filterameter
-```
-
 ## Forms and Query Parameters
 
-The controller mixin will look for filter parameters nested under the `filter` key. For example, here's what the query parameters might look like for size and color:
+The filter parameters are pulled from the controller parameters, nested under the key `filter` (by default; see [Configuration](#configuration) to change the filter key). For example a request for large, blue widgets might have the following query parameters on the url:
 
 ```
 ?filter[size]=large&filter[color]=blue
@@ -394,7 +425,26 @@ On [a generic search form](https://guides.rubyonrails.org/form_helpers.html#a-ge
 <% end %>
 ```
 
-## Contributions
+#### Sort Parameters
+
+The sort is also nested underneath the filter key:
+
+`/widgets?filter[sort]=size`
+
+Use an array to pass multiple sorts. The order of the parameters is the order the sorts will be applied. For example, the following sorts first by size then by color:
+
+`/widgets?filter[sort]=size&filter[sort]=color`
+
+Sorts are ascending by default, but can use a prefix can be added to control the sort:
+
+- `+` ascending (the default)
+- `-` descending
+
+For example, the following sorts by size descending:
+
+`/widgets?filter[sort]=-size`
+
+## Contribute
 
 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

data/lib/filterameter/configuration.rb

@@ -1,29 +1,33 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Configuration
+  # # Configuration
   #
   # Class Configuration stores the following settings:
-  # - action_on_undeclared_parameters
-  # - action_on_validation_failure
-  # - filter_key
+  # *   action_on_undeclared_parameters
+  # *   action_on_validation_failure
+  # *   filter_key
   #
-  # == Action on Undeclared Parameters
+  # ## Action on Undeclared Parameters
   #
-  # Occurs when the filter parameter contains any keys that are not defined. Valid actions are :log, :raise, and
-  # false (do not take action). By default, development will log, test will raise, and production will do nothing.
+  # Occurs when the filter parameter contains any keys that are not defined. Valid
+  # actions are :log, :raise, and false (do not take action). By default,
+  # development will log, test will raise, and production will do nothing.
   #
-  # == Action on Validation Failure
+  # ## Action on Validation Failure
   #
-  # Occurs when a filter parameter fails a validation. Valid actions are :log, :raise, and false (do not take action).
-  # By default, development will log, test will raise, and production will do nothing.
+  # Occurs when a filter parameter fails a validation. Valid actions are :log,
+  # :raise, and false (do not take action). By default, development will log, test
+  # will raise, and production will do nothing.
   #
-  # == Filter Key
+  # ## Filter Key
   #
-  # By default, the filter parameters are nested under the key :filter. Use this setting to override the key.
+  # By default, the filter parameters are nested under the key :filter. Use this
+  # setting to override the key.
   #
-  # If the filter parameters are NOT nested, set this to false. Doing so will restrict the filter parameters to only
-  # those that have been declared, meaning undeclared parameters are ignored (and the action_on_undeclared_parameters
+  # If the filter parameters are NOT nested, set this to false. Doing so will
+  # restrict the filter parameters to only those that have been declared, meaning
+  # undeclared parameters are ignored (and the action_on_undeclared_parameters
   # configuration option does not come into play).
   class Configuration
     attr_accessor :action_on_undeclared_parameters, :action_on_validation_failure, :filter_key

data/lib/filterameter/declaration_errors/cannot_be_inline_scope_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = CannotBeInlineScopeError
+    # # Cannot Be Inline Scope Error
     #
     # 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

data/lib/filterameter/declaration_errors/filter_scope_argument_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = Filter Scope Argument Error
+    # # 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.

data/lib/filterameter/declaration_errors/no_such_attribute_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = No Such Attribute Error
+    # # 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

data/lib/filterameter/declaration_errors/not_a_scope_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = Not A Scope Error
+    # # 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

data/lib/filterameter/declaration_errors/sort_scope_requires_one_argument_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = Sort Scope Requires One Argument Error
+    # # 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

data/lib/filterameter/declaration_errors/unexpected_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = Unexpected Error
+    # # Unexpected Error
     #
     # Error UnexpectedError occurs when the filter or scope factory raises an exception that the validator did not
     # expect.

data/lib/filterameter/declaration_errors.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module DeclarationErrors
-    # = Declaration Error
+    # # Declaration Error
     #
     # Error DeclarationError provides a base class for errors from filter or sort declarations.
     class DeclarationError < StandardError

data/lib/filterameter/declarations_validator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Declarations Validator
+  # # 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.
@@ -10,11 +10,12 @@ module Filterameter
   #
   # A test in RSpec might look like this:
   #
-  #   expect(WidgetsController.declarations_validator).to be_valid
+  #     expect(WidgetsController.declarations_validator).to be_valid
   #
   # In Minitest it might look like this:
   #
-  #   assert WidgetsController.declarations_validator.valid?, WidgetsController.declarations_validator.errors
+  #     validator = WidgetsController.declarations_validator
+  #     assert_predicate validator, :valid?, -> { validator.errors }
   class DeclarationsValidator
     include Filterameter::Errors
 
@@ -69,7 +70,7 @@ module Filterameter
       "\nInvalid #{type} for '#{name}':\n  #{errors.join("\n  ")}"
     end
 
-    # = Factory Errors
+    # # Factory Errors
     #
     # Class FactoryErrors is swapped in if the fetch from a factory fails. It is always invalid and provides the reason.
     class FactoryErrors

data/lib/filterameter/declarative_filters.rb

@@ -1,22 +1,134 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Declarative Controller Filters
+  # # Declarative Controller Filters
   #
   # Mixin DeclarativeFilters should be included in controllers to enable the filter DSL.
   module DeclarativeFilters
     extend ActiveSupport::Concern
-    include Filterameter::Filterable
-    include Filterameter::Sortable
 
     class_methods do
       delegate :declarations_validator, to: :filter_coordinator
 
+      # Declares a filter that can be read from the parameters and applied to the
+      # ActiveRecord query. The `name` 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
+      #
+      # The declaration can also include an `options` hash to specialize the behavior of the filter.
+      #
+      # * **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. Use an array if the
+      #   asociation is more than one level.
+      #
+      # * **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 `_min` and `_max`
+      #     *   min_only: enables additional parameter with attribute name plus
+      #         suffix `_min`
+      #     *   max_only: enables additional parameter with attribute name plus
+      #         suffix `_max`
+      #
+      # * **sortable**: By default most filters are sortable. To prevent an attribute filter from being sortable, set
+      #   the option to `false`.
+      #
+      # Options examples:
+      #
+      #     filter :status, name: :current_status
+      #     filter :manager_id, association: :department
+      #     filter :business_unit_name, name: :name, association: [:department, :business_unit]
+      #     filter :size, validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
+      #     filter :description, partial: true
+      #     filter :department_name, partial: :from_start
+      #     filter :reason, partial: { match: :dynamic, case_sensitive: true }
+      #     filter :price, range: true
+      def filter(name, options = {})
+        filter_coordinator.add_filter(name, options)
+      end
+
+      # Declares a list of filters without options. Filters that require options must be declared with `filter`.
+      def filters(*names)
+        names.each { |name| filter(name) }
+      end
+
+      # Declares a sort that can be read from the parameters and applied to the
+      # ActiveRecord query. The `parameter_name` identifies the name of the parameter
+      # and is the default value for the attribute name when none is specified in the
+      # options.
+      #
+      # ## Options
+      #
+      # The declaration can also include an `options` hash to specialize the behavior of the sort.
+      #
+      # * **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.
+      #
+      # Options example:
+      #
+      #     sort :project_created_at, name: :created_at, association: :project
+      def sort(parameter_name, options = {})
+        filter_coordinator.add_sort(parameter_name, options)
+      end
+
+      # Declares a list of sorts without options. Sorts that require options must be declared with `sort`.
+      def sorts(*parameter_names)
+        parameter_names.each { |parameter_name| filter(parameter_name) }
+      end
+
+      def default_sort(sort_and_direction_pairs)
+        filter_coordinator.default_sort = sort_and_direction_pairs
+      end
+
+      # 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'
+      # ```
+      #
+      # An optional second parameter can be used 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:
+      #
+      #     filter_model 'Picture', :data
+      #
+      # **Important:** If the `filter_model` declaration is used, it must be before any filter or sort declarations.
       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
 
+      # When using the before action callback `build_filtered_query`, the query is assigned to an instance variable with
+      # the name of the model pluralized. For example, the Photo model will use the variable `@photos`.
+      #
+      # To use a different variable name with the callback, assign it with `filter_query_var_name`. For example, if the
+      # query is stored as `@data`, use the following:
+      #
+      #     filter_query_var_name :data
       def filter_query_var_name(query_variable_name)
         filter_coordinator.query_variable_name = query_variable_name
       end
@@ -26,6 +138,24 @@ module Filterameter
       end
     end
 
+    # Returns an ActiveRecord query from the filter parameters.
+    #
+    #     def index
+    #       @widgets = build_query_from_filters
+    #     end
+    #
+    # The method optionally takes a starting query. For example, this restricts the results
+    # to only active widgets:
+    #
+    #     def index
+    #       @widgets = build_query_from_filters(Widgets.where(active: true))
+    #     end
+    #
+    # The starting query can also be used to provide eager loading:
+    #
+    #     def index
+    #       @widgets = build_query_from_filters(Widgets.includes(:manufacturer))
+    #     end
     def build_query_from_filters(starting_query = nil)
       self.class.filter_coordinator.build_query(filter_parameters, starting_query)
     end

data/lib/filterameter/errors.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Errors
+  # # Errors
   #
   # Module Errors provides `valid?` and `errors` to implementing classes. If the `valid?` method is not overridden,
   # then it returns true.

data/lib/filterameter/exceptions/cannot_determine_model_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Exceptions
-    # = Cannot Determine Model Error
+    # # Cannot Determine Model Error
     #
     # Class CannotDetermineModelError is raised when the model class cannot be determined from either the controller
     # name or controller path. This is a setup issue; the resolution is for the controller to specify the model class

data/lib/filterameter/exceptions/collection_association_sort_error.rb

@@ -2,10 +2,10 @@
 
 module Filterameter
   module Exceptions
-    # = Collection Association Sort Error
+    # # Collection Association Sort Error
     #
-    # Class CollectionAssociationSortError is raised when a sort is attempted on a collection association. (Sorting is
-    # only valid on _singular_ associations.)
+    # Class CollectionAssociationSortError is raised when a sort is attempted on a
+    # collection association. (Sorting is only valid on *singular* associations.)
     class CollectionAssociationSortError < FilterameterError
       def initialize(declaration)
         super("Sorting is not allowed on collection associations: \n\t\t#{declaration}")

data/lib/filterameter/exceptions/invalid_association_declaration_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Exceptions
-    # = Invalid Association Declaration Error
+    # # Invalid Association Declaration Error
     #
     # Class InvalidAssociationDeclarationError is raised when the declared association(s) are not valid.
     class InvalidAssociationDeclarationError < FilterameterError

data/lib/filterameter/exceptions/undeclared_parameter_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Exceptions
-    # = Undeclared Parameter Error
+    # # Undeclared Parameter Error
     #
     # 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.

data/lib/filterameter/exceptions/validation_error.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Exceptions
-    # = Validation Error
+    # # Validation Error
     #
     # Class ValidationError is raised when a specified parameter fails a validation. Configuration setting
     # `action_on_validation_failure` determines whether or not the exception is raised.

data/lib/filterameter/filter_coordinator.rb

@@ -8,7 +8,7 @@ require 'action_controller/metal/live'
 require 'action_controller/metal/strong_parameters'
 
 module Filterameter
-  # = Filter Coordinator
+  # # Filter Coordinator
   #
   # Class FilterCoordinator stores the configuration declared via class-level method calls such as the list of
   # filters and the optionally declared model class. Each controller will have one instance of the coordinator

data/lib/filterameter/filter_declaration.rb

@@ -3,7 +3,7 @@
 require 'active_support/core_ext/array/wrap'
 
 module Filterameter
-  # = Filter Declaration
+  # # Filter Declaration
   #
   # Class FilterDeclaration captures the filter declaration within the controller.
   #

data/lib/filterameter/filter_factory.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Filter Factory
+  # # Filter Factory
   #
   # Class FilterFactory builds a filter from a FilterDeclaration.
   class FilterFactory

data/lib/filterameter/filters/arel_filter.rb

@@ -2,9 +2,10 @@
 
 module Filterameter
   module Filters
-    # = Arel Filter
+    # # Arel Filter
     #
-    # Class ArelFilter is a base class for arel queries. It does not implement <tt>apply</tt>.
+    # Class ArelFilter is a base class for arel queries. It does not implement
+    # `apply`.
     class ArelFilter
       include Filterameter::Errors
       include Filterameter::Filters::AttributeValidator

data/lib/filterameter/filters/attribute_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Attribute Filter
+    # # Attribute Filter
     #
     # Class AttributeFilter leverages ActiveRecord's where query method to add criteria for an attribute.
     class AttributeFilter

data/lib/filterameter/filters/attribute_validator.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Attribute Validator
+    # # Attribute Validator
     #
     # Module AttributeValidator validates that the attribute exists on the model.
     module AttributeValidator

data/lib/filterameter/filters/conditional_scope_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Conditional Scope Filter
+    # # Conditional Scope Filter
     #
     # Class ConditionalScopeFilter applies the scope if the parameter is not false.
     class ConditionalScopeFilter

data/lib/filterameter/filters/matches_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Matches Filter
+    # # Matches Filter
     #
     # Class MatchesFilter uses arel's `matches` to generate a LIKE query.
     class MatchesFilter

data/lib/filterameter/filters/maximum_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Maximum Filter
+    # # Maximum Filter
     #
     # Class MaximumFilter adds criteria for all values greater than or equal to a maximum.
     class MaximumFilter < ArelFilter

data/lib/filterameter/filters/minimum_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Minimum Filter
+    # # Minimum Filter
     #
     # Class MinimumFilter adds criteria for all values greater than or equal to a minimum.
     class MinimumFilter < ArelFilter

data/lib/filterameter/filters/nested_collection_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Nested Collection Filter
+    # # Nested Collection Filter
     #
     # Class NestedCollectionFilter joins the nested table(s), merges the filter to the association's model, then makes
     # the results distinct.

data/lib/filterameter/filters/nested_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Nested Attribute Filter
+    # # Nested Attribute Filter
     #
     # Class NestedFilter joins the nested table(s) then merges the filter to the association's model.
     class NestedFilter

data/lib/filterameter/filters/scope_filter.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Filters
-    # = Scope Filter
+    # # Scope Filter
     #
     # Class ScopeFilter applies the named scope passing in the parameter value.
     class ScopeFilter

data/lib/filterameter/helpers/declaration_with_model.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Helpers
-    # = Declaration with Model
+    # # Declaration with Model
     #
     # Class DeclarationWithModel inspects the declaration under the context of the model. This enables
     # predicate methods as well as drilling through associations.

data/lib/filterameter/helpers/joins_values_builder.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Helpers
-    # = Joins Values Builder
+    # # 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

data/lib/filterameter/helpers/requested_sort.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Helpers
-    # = Reqested Sort
+    # # Reqested Sort
     #
     # Class RequestedSort parses the name and direction from a sort segment.
     class RequestedSort

data/lib/filterameter/log_subscriber.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Log Subscriber
+  # # Log Subscriber
   #
   # Class LogSubscriber provides instrumentation for events.
   class LogSubscriber < ActiveSupport::LogSubscriber

data/lib/filterameter/options/partial_options.rb

@@ -2,19 +2,20 @@
 
 module Filterameter
   module Options
-    # = Partial 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)
+    # 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 }
+    #     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.
+    # 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

data/lib/filterameter/parameters_base.rb

@@ -4,7 +4,7 @@ require 'active_model/attribute_assignment'
 require 'active_model/validations'
 
 module Filterameter
-  # = Parameters
+  # # Parameters
   #
   # Class Parameters is sub-classed to provide controller-specific validations.
   class ParametersBase

data/lib/filterameter/query_builder.rb

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Query Builder
+  # # Query Builder
   #
   # Class Query Builder turns filter parameters into a query.
   #
   # The query builder is instantiated by the filter coordinator. The default query currently is simple `all`. The
   # default sort comes for the controller declaration of the same name; it is optional and the value may be nil.
   #
-  # If the request includes a sort, it is always applied. If not, the following logic kicks in to provide a sort:
-  # - if the starting query includes a sort, no additional sort is applied
-  # - if a default sort has been declared, it is applied
-  # - if neither of those provides a sort, then the fallback is primary key desc
+  # If the request includes a sort, it is always applied. If not, the following
+  # logic kicks in to provide a sort:
+  # *   if the starting query includes a sort, no additional sort is applied
+  # *   if a default sort has been declared, it is applied
+  # *   if neither of those provides a sort, then the fallback is primary key desc
   class QueryBuilder
     def initialize(default_query, default_sort, filter_registry)
       @default_query = default_query
@@ -87,9 +88,10 @@ module Filterameter
       end
     end
 
-    # TODO: this handles any runtime exceptions, not just undeclared parameter errors:
-    # - should the config option be more generalized?
-    # - or should there be a config option for each type of error?
+    # TODO: this handles any runtime exceptions, not just undeclared parameter
+    # errors:
+    # *   should the config option be more generalized?
+    # *   or should there be a config option for each type of error?
     def handle_undeclared_parameter(exception)
       action = Filterameter.configuration.action_on_undeclared_parameters
       return unless action

data/lib/filterameter/registries/filter_registry.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Registries
-    # Filters
+    # # Filter Registry
     #
     # 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.

data/lib/filterameter/registries/registry.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Registries
-    # = Registry
+    # # Registry
     #
     # Class Registry records declarations and allows resulting filters and sorts to be fetched from sub-registries.
     class Registry

data/lib/filterameter/registries/sort_registry.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Registries
-    # Sort Registry
+    # # Sort Registry
     #
     # 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.

data/lib/filterameter/registries/sub_registry.rb

@@ -2,12 +2,11 @@
 
 module Filterameter
   module Registries
-    # SubRegistry
+    # # SubRegistry
     #
     # Class SubRegistry provides add and fetch methods as well as the initialization for sub-registries.
     #
     # Subclasses must implement build_declaration.
-    #
     class SubRegistry
       def initialize(factory)
         @factory = factory

data/lib/filterameter/sort_declaration.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Sort Declaration
+  # # Sort Declaration
   #
   # Class SortDeclaration captures the sort declaration within the controller. A sort declaration is also generated
   # from a FilterDeclaration when it is `sortable?`.

data/lib/filterameter/sort_factory.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Filterameter
-  # = Sort Factory
+  # # Sort Factory
   #
   # Class SortFactory builds a sort from a model and a declaration.
   class SortFactory

data/lib/filterameter/sorts/attribute_sort.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Sorts
-    # = Attribute Sort
+    # # Attribute Sort
     #
     # Class AttributeSort leverages ActiveRecord's `order` query method to add sorting for an attribute.
     class AttributeSort

data/lib/filterameter/sorts/scope_sort.rb

@@ -2,7 +2,7 @@
 
 module Filterameter
   module Sorts
-    # = Scope Sort
+    # # 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.

data/lib/filterameter/validators/inclusion_validator.rb

@@ -2,14 +2,14 @@
 
 module Filterameter
   module Validators
-    # = Inclusion Validator
+    # # Inclusion Validator
     #
     # Class InclusionValidator extends ActiveModel::Validations::InclusionValidator to enable validations of multiple
     # values.
     #
-    # == Example
+    # ## Example
     #
-    #   validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
+    #     validates: { inclusion: { in: %w[Small Medium Large], allow_multiple_values: true } }
     #
     class InclusionValidator < ActiveModel::Validations::InclusionValidator
       def validate_each(record, attribute, value)

data/lib/filterameter/version.rb

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

data/lib/filterameter.rb

@@ -5,7 +5,7 @@ require 'zeitwerk'
 loader = Zeitwerk::Loader.for_gem
 loader.setup # ready!
 
-# = Filterameter
+# # Filterameter
 module Filterameter
   class << self
     attr_writer :configuration

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Todd Kummer
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-29 00:00:00.000000000 Z
+date: 2025-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -100,14 +99,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -156,14 +155,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.3
+        version: 3.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.3
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec_rails
   requirement: !ruby/object:Gem::Requirement
@@ -223,7 +222,6 @@ files:
 - lib/filterameter/filter_coordinator.rb
 - lib/filterameter/filter_declaration.rb
 - lib/filterameter/filter_factory.rb
-- lib/filterameter/filterable.rb
 - lib/filterameter/filters/arel_filter.rb
 - lib/filterameter/filters/attribute_filter.rb
 - lib/filterameter/filters/attribute_validator.rb
@@ -247,7 +245,6 @@ files:
 - lib/filterameter/registries/sub_registry.rb
 - lib/filterameter/sort_declaration.rb
 - 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
@@ -256,7 +253,6 @@ homepage: https://github.com/RockSolt/filterameter
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -271,8 +267,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Declarative Filter Parameters
 test_files: []

data/lib/filterameter/filterable.rb

@@ -1,55 +0,0 @@
-# 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/sortable.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # = Sortable
-  #
-  # Mixin Sortable provides class methods <tt>sort</tt> and <tt>sorts</tt>.
-  module Sortable
-    extend ActiveSupport::Concern
-
-    class_methods do
-      # Declares a sort that can be read from the parameters and applied to the ActiveRecord query. The
-      # <tt>parameter_name</tt> identifies the name of the parameter and is the default value for the attribute
-      # name when none is specified in the options.
-      #
-      # The including class must implement `filter_coordinator`
-      #
-      # === 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.
-      def sort(parameter_name, options = {})
-        filter_coordinator.add_sort(parameter_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 sorts(*parameter_names)
-        parameter_names.each { |parameter_name| filter(parameter_name) }
-      end
-
-      def default_sort(sort_and_direction_pairs)
-        filter_coordinator.default_sort = sort_and_direction_pairs
-      end
-    end
-  end
-end