filterameter 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b14f3434137044896e6273279573a9ec00bbb9ef6b1fbe03c99a01851df5a4d3
-  data.tar.gz: d2afe0937ee82dea9c8ec4933c39bb13a083c6183772ecb847ef7a28d582afbd
+  metadata.gz: 9666ad7ecd3f4cb352a26a7b8522fdff5a4ed94f9fa26199111659944982d8b1
+  data.tar.gz: 93b5c66bfac1d89d8e77b6e967da5cce8531633029718f8c5484b8688bcef428
 SHA512:
-  metadata.gz: 2ebdc7ca579a967fc95e3843df78e6137291a1136e60fe9636306d5899327f4a456e581e70251c4ad1203e253d82f24090f85cefe699476c8d928c2f22f2796e
-  data.tar.gz: d5bb0bf69b24912dcd22b21f41abb5655bb225cf77316c20e7c753ca2dd060a47815cd6af66b4cc229ca33bfcf94010bbcfc84f5abcdfbf1fd6faee1dda6d8a1
+  metadata.gz: 4daba3e1643f9b6cb5a1c00f81b734bba3e8d10e55038a8bad8ae2e1b74f9172b74870836d8c27d6afb506bb19092c5631ccea70e0feccc44dbe15758d0ca583
+  data.tar.gz: 879d2e0e5bc26f3bd4341bad4c5974f4ef17696418e05e6da8bb1cd5f6c7b8e16bfe835ae78ad08e954c487e3f8164b5b1bf1006a59b7e99cab5e775b0b79026

data/README.md

@@ -247,10 +247,10 @@ end
 
 #### Default Sort
 
-A default sort can be declared using `default_sort`. The argument(s) should specify one or more of the declared sorts or sortable filters by name. By default, the order is ascending. If you want descending order, you can map the column name symbol to :desc.
+A default sort can be declared using `default_sort`. The argument(s) should specify one or more of the declared sorts or sortable filters by name. The sorts should be defined as key-value pairs, with the name as the key and the direction as the value.
 
 ```ruby
-default_sort updated_at: :desc, :description
+default_sort updated_at: :desc, description: :asc
 ```
 
 In order to provide consistent results, a sort is always applied. If no default is specified, it will use primary key descending.

data/lib/filterameter/declarative_filters.rb

@@ -6,17 +6,130 @@ module Filterameter
   # 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
+
+      # Declares a default sort order for the query. Specify a list of sort names and directions as pairs.
+      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

data/lib/filterameter/query_builder.rb

@@ -30,7 +30,9 @@ module Filterameter
 
     def parse_filter_params(filter_params)
       sort = parse_sorts(filter_params.delete('sort'))
-      [sort, remove_invalid_values(filter_params)]
+      params = filter_params.reject { |_k, v| v.is_a?(String) && v.empty? }
+                            .then { |p| remove_invalid_values(p) }
+      [sort, params]
     end
 
     def parse_sorts(sorts)

data/lib/filterameter/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: filterameter
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Todd Kummer
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-19 00:00:00.000000000 Z
+date: 2025-03-15 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.17
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Declarative Filter Parameters
 test_files: []

data/lib/filterameter/filterable.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # # Filterable
-  #
-  # Mixin Filterable provides class methods `filter` and `filters`.
-  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 `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
-      #
-      # :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 `_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`
-      #
-      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 `filter` if more options are required.
-      def filters(*names)
-        names.each { |name| filter(name) }
-      end
-    end
-  end
-end

data/lib/filterameter/sortable.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Filterameter
-  # # Sortable
-  #
-  # Mixin Sortable provides class methods `sort` and `sorts`.
-  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 `parameter_name` 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 `filter` 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