ransack 2.3.2 → 2.5.0

data/README.md

@@ -1,6 +1,6 @@
 # ![Ransack](./logo/ransack-h.png "Ransack")
 
-[![Build Status](https://travis-ci.org/activerecord-hackery/ransack.svg)](https://travis-ci.org/activerecord-hackery/ransack)
+[![Build Status](https://github.com/activerecord-hackery/ransack/workflows/test/badge.svg)](https://github.com/activerecord-hackery/ransack/actions)
 [![Gem Version](https://badge.fury.io/rb/ransack.svg)](http://badge.fury.io/rb/ransack)
 [![Code Climate](https://codeclimate.com/github/activerecord-hackery/ransack/badges/gpa.svg)](https://codeclimate.com/github/activerecord-hackery/ransack)
 [![Backers on Open Collective](https://opencollective.com/ransack/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/ransack/sponsors/badge.svg)](#sponsors)
@@ -11,13 +11,11 @@ Ransack enables the creation of both
 for your Ruby on Rails application
 ([demo source code here](https://github.com/activerecord-hackery/ransack_demo)).
 If you're looking for something that simplifies query generation at the model
-or controller layer, you're probably not looking for Ransack (or MetaSearch,
-for that matter). Try [Squeel](https://github.com/activerecord-hackery/squeel)
-instead.
+or controller layer, you're probably not looking for Ransack.
 
 ## Getting started
 
-Ransack is compatible with Rails 6.0, 5.0, 5.1 and 5.2 on Ruby 2.3 and later.
+Ransack is supported for Rails 6.1, 6.0, 5.2 on Ruby 2.6.6 and later.
 
 In your Gemfile, for the last officially released gem:
 
@@ -41,27 +39,14 @@ gem 'ransack', github: 'activerecord-hackery/ransack'
 
 ## Usage
 
-Ransack can be used in one of two modes, simple or advanced.
+Ransack can be used in one of two modes, simple or advanced. For
+searching/filtering not requiring complex boolean logic, Ransack's simple
+mode should meet your needs.
 
-### Simple Mode
-
-This mode works much like MetaSearch, for those of you who are familiar with
-it, and requires very little setup effort.
-
-If you're coming from MetaSearch, things to note:
-
-  1. The default param key for search params is now `:q`, instead of `:search`.
-  This is primarily to shorten query strings, though advanced queries (below)
-  will still run afoul of URL length limits in most browsers and require a
-  switch to HTTP POST requests. This key is [configurable](https://github.com/activerecord-hackery/ransack/wiki/Configuration).
+If you're coming from MetaSearch (Ransack's predecessor), refer to the
+[Updating From MetaSearch](#updating-from-metasearch) section
 
-  2. `form_for` is now `search_form_for`, and validates that a Ransack::Search
-  object is passed to it.
-
-  3. Common ActiveRecord::Relation methods are no longer delegated by the
-  search object. Instead, you will get your search results (an
-  ActiveRecord::Relation in the case of the ActiveRecord adapter) via a call to
-  `Ransack#result`.
+### Simple Mode
 
 #### In your controller
 
@@ -78,9 +63,35 @@ this example, with preloading each Person's Articles and pagination):
 def index
   @q = Person.ransack(params[:q])
   @people = @q.result.includes(:articles).page(params[:page])
+end
+```
 
-  # or use `to_a.uniq` to remove duplicates (can also be done in the view):
-  @people = @q.result.includes(:articles).page(params[:page]).to_a.uniq
+##### Default search options
+
+**Search parameter**
+
+Ransack uses a default `:q` param key for search params. This may be changed by
+setting the `search_key` option in a Ransack initializer file (typically
+`config/initializers/ransack.rb`):
+
+```ruby
+Ransack.configure do |c|
+  # Change default search parameter key name.
+  # Default key name is :q
+  c.search_key = :query
+end
+```
+
+**String search**
+
+After version 2.4.0 when searching a string query Ransack by default strips all whitespace around the query string.
+This may be disabled by setting the `strip_whitespace` option in a Ransack initializer file:
+
+```ruby
+Ransack.configure do |c|
+  # Change whitespace stripping behaviour.
+  # Default is true
+  c.strip_whitespace = false
 end
 ```
 
@@ -250,6 +261,57 @@ the order indicator arrow by passing `hide_indicator: true` in the sort link:
   default_order: { last_name: 'asc', first_name: 'desc' }) %>
 ```
 
+#### PostgreSQL's sort option
+
+The `NULLS FIRST` and `NULLS LAST` options can be used to determine whether nulls appear before or after non-null values in the sort ordering.
+
+You may want to configure it like this:
+
+```rb
+Ransack.configure do |c|
+  c.postgres_fields_sort_option = :nulls_first # or :nulls_last
+end
+```
+
+To treat nulls as having the lowest or highest value respectively. To force nulls to always be first or last, use
+
+```rb
+Ransack.configure do |c|
+  c.postgres_fields_sort_option = :nulls_always_first # or :nulls_always_last
+end
+```
+
+See this feature: https://www.postgresql.org/docs/13/queries-order.html
+
+#### Case Insensitive Sorting in PostgreSQL
+
+In order to request PostgreSQL to do a case insensitive sort for all string columns of a model at once, Ransack can be extended by using this approach:
+
+```ruby
+module RansackObject
+
+  def self.included(base)
+    base.columns.each do |column|
+      if column.type == :string
+        base.ransacker column.name.to_sym, type: :string do
+          Arel.sql("lower(#{base.table_name}.#{column.name})")
+        end
+      end
+    end
+  end
+end
+```
+
+```ruby
+class UserWithManyAttributes < ActiveRecord::Base
+  include RansackObject
+end
+```
+
+If this approach is taken, it is advisable to [add a functional index](https://www.postgresql.org/docs/13/citext.html).
+
+This was originally asked in [a Ransack issue](https://github.com/activerecord-hackery/ransack/issues/1201) and a solution was found on [Stack Overflow](https://stackoverflow.com/a/34677378). 
+
 ### Advanced Mode
 
 "Advanced" searches (ab)use Rails' nested attributes functionality in order to
@@ -408,6 +470,25 @@ query parameters in your URLs.
 <% end %>
 ```
 
+You can also use `ransack_alias` for sorting.
+
+```ruby
+class Post < ActiveRecord::Base
+  belongs_to :author
+
+  # Abbreviate :author_first_name to :author
+  ransack_alias :author, :author_first_name
+end
+```
+
+Now, you can use `:author` instead of `:author_first_name` in a `sort_link`.
+
+```erb
+<%= sort_link(@q, :author) %>
+```
+
+Note that using `:author_first_name_or_author_last_name_cont` would produce an invalid sql query. In those cases, Ransack ignores the sorting clause.
+
 ### Search Matchers
 
 List of all possible predicates
@@ -437,13 +518,10 @@ List of all possible predicates
 | `*_lteq_any` | Less than or equal to any | |
 | `*_gt_any` | Greater than any | |
 | `*_gteq_any` | Greater than or equal to any | |
-| `*_matches_any` | `*_does_not_match_any` | same as above but with `LIKE` |
 | `*_lt_all` | Less than all | SQL: `col < value1 AND col < value2` |
 | `*_lteq_all` | Less than or equal to all | |
 | `*_gt_all` | Greater than all | |
 | `*_gteq_all` | Greater than or equal to all | |
-| `*_matches_all` | Matches all | same as above but with `LIKE` |
-| `*_does_not_match_all` | Does not match all | |
 | `*_not_eq_all` | none of values in a set | |
 | `*_start` | Starts with | SQL: `col LIKE 'value%'` |
 | `*_not_start` | Does not start with | |
@@ -463,7 +541,7 @@ List of all possible predicates
 | `*_not_cont` | Does not contain |
 | `*_not_cont_any` | Does not contain any of | |
 | `*_not_cont_all` | Does not contain all of | |
-| `*_i_cont` | Contains value with case insensitive | uses `LIKE` |
+| `*_i_cont` | Contains value with case insensitive | uses `ILIKE` |
 | `*_i_cont_any` | Contains any of values with case insensitive | |
 | `*_i_cont_all` | Contains all of values with case insensitive | |
 | `*_not_i_cont` | Does not contain with case insensitive |
@@ -673,6 +751,43 @@ Trying it out in `rails console`:
 
 That's it! Now you know how to whitelist/blacklist various elements in Ransack.
 
+### Handling unknown predicates or attributes
+
+By default, Ransack will ignore any unknown predicates or attributes:
+
+```ruby
+Article.ransack(unknown_attr_eq: 'Ernie').result.to_sql
+=> SELECT "articles".* FROM "articles"
+```
+
+Ransack may be configured to raise an error if passed an unknown predicate or
+attributes, by setting the `ignore_unknown_conditions` option to `false` in your
+Ransack initializer file at `config/initializers/ransack.rb`:
+
+```ruby
+Ransack.configure do |c|
+  # Raise errors if a query contains an unknown predicate or attribute.
+  # Default is true (do not raise error on unknown conditions).
+  c.ignore_unknown_conditions = false
+end
+```
+
+```ruby
+Article.ransack(unknown_attr_eq: 'Ernie')
+# ArgumentError (Invalid search term unknown_attr_eq)
+```
+
+As an alternative to setting a global configuration option, the `.ransack!`
+class method also raises an error if passed an unknown condition:
+
+```ruby
+Article.ransack!(unknown_attr_eq: 'Ernie')
+# ArgumentError: Invalid search term unknown_attr_eq
+```
+
+This is equivalent to the `ignore_unknown_conditions` configuration option,
+except it may be applied on a case-by-case basis.
+
 ### Using Scopes/Class Methods
 
 Continuing on from the preceding section, searching by scopes requires defining
@@ -869,6 +984,28 @@ en:
         title: Old Ransack Namespaced Title
 ```
 
+### Updating From MetaSearch
+
+Ransack works much like MetaSearch, for those of you who are familiar with
+it, and requires very little setup effort.
+
+If you're coming from MetaSearch, things to note:
+
+  1. The default param key for search params is now `:q`, instead of `:search`.
+  This is primarily to shorten query strings, though advanced queries (below)
+  will still run afoul of URL length limits in most browsers and require a
+  switch to HTTP POST requests. This key is
+  [configurable](default-search-parameter) via setting the `search_key` option
+  in your Ransack intitializer file.
+
+  2. `form_for` is now `search_form_for`, and validates that a Ransack::Search
+  object is passed to it.
+
+  3. Common ActiveRecord::Relation methods are no longer delegated by the
+  search object. Instead, you will get your search results (an
+  ActiveRecord::Relation in the case of the ActiveRecord adapter) via a call to
+  `Ransack#result`.
+
 ## Mongoid
 
 Mongoid support has been moved to its own gem at [ransack-mongoid](https://github.com/activerecord-hackery/ransack-mongoid).

data/bug_report_templates/test-ransack-scope-and-column-same-name.rb

@@ -0,0 +1,78 @@
+# test-ransack-scope-and-column-same-name.rb
+
+# This is a stand-alone test case.
+
+# Run it in your console with: `ruby test-ransack-scope-and-column-same-name.rb`
+
+# If you change the gem dependencies, run it with:
+# `rm gemfile* && ruby test-ransack-scope-and-column-same-name.rb`
+
+unless File.exist?('Gemfile')
+  File.write('Gemfile', <<-GEMFILE)
+    source 'https://rubygems.org'
+
+    # Rails master
+    gem 'rails', github: 'rails/rails', branch: '6-1-stable'
+
+    # Rails last release
+    # gem 'rails'
+
+    gem 'sqlite3'
+    gem 'ransack', github: 'activerecord-hackery/ransack'
+  GEMFILE
+
+  system 'bundle install'
+end
+
+require 'bundler'
+Bundler.setup(:default)
+
+require 'active_record'
+require 'minitest/autorun'
+require 'logger'
+require 'ransack'
+
+# This connection will do for database-independent bug reports.
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+# Display versions.
+message = "Running test case with Ruby #{RUBY_VERSION}, Active Record #{
+  ::ActiveRecord::VERSION::STRING}, Arel #{Arel::VERSION} and #{
+  ::ActiveRecord::Base.connection.adapter_name}"
+line = '=' * message.length
+puts line, message, line
+
+ActiveRecord::Schema.define do
+  create_table :users, force: true do |t|
+    t.boolean :active, null: false, default: true
+  end
+end
+
+class User < ActiveRecord::Base
+  scope :activated, -> (boolean = true) { where(active: boolean) }
+
+  private
+
+  def self.ransackable_scopes(auth_object = nil)
+    %i(activated)
+  end
+end
+
+class BugTest < Minitest::Test
+  def test_activated_scope_equals_true
+    sql = User.ransack({ activated: true }).result.to_sql
+    puts sql
+    assert_equal(
+      "SELECT \"users\".* FROM \"users\" WHERE \"users\".\"active\" = 1", sql
+      )
+  end
+
+  def test_activated_scope_equals_false
+    sql = User.ransack({ activated: false }).result.to_sql
+    puts sql
+    assert_equal(
+      "SELECT \"users\".* FROM \"users\"", sql
+      )
+  end
+end

data/bug_report_templates/test-ransacker-arel-present-predicate.rb

@@ -0,0 +1,71 @@
+# test-ransacker-arel-present-predicate.rb
+
+# Run it in your console with: `ruby test-ransacker-arel-present-predicate.rb`
+
+# If you change the gem dependencies, run it with:
+# `rm gemfile* && ruby test-ransacker-arel-present-predicate.rb`
+
+unless File.exist?('Gemfile')
+  File.write('Gemfile', <<-GEMFILE)
+    source 'https://rubygems.org'
+
+    # Rails master
+    gem 'rails', github: 'rails/rails', branch: '6-1-stable'
+
+    # Rails last release
+    # gem 'rails'
+
+    gem 'sqlite3'
+    gem 'ransack', github: 'activerecord-hackery/ransack'
+  GEMFILE
+
+  system 'bundle install'
+end
+
+require 'bundler'
+Bundler.setup(:default)
+
+require 'active_record'
+require 'minitest/autorun'
+require 'logger'
+require 'ransack'
+
+# This connection will do for database-independent bug reports.
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+# Display versions.
+message = "Running test case with Ruby #{RUBY_VERSION}, Active Record #{
+  ::ActiveRecord::VERSION::STRING}, Arel #{Arel::VERSION} and #{
+  ::ActiveRecord::Base.connection.adapter_name}"
+line = '=' * message.length
+puts line, message, line
+
+ActiveRecord::Schema.define do
+  create_table :projects, force: true do |t|
+    t.string :name
+    t.string :number
+  end
+end
+
+class Project < ActiveRecord::Base
+  ransacker :name do
+    Arel.sql('projects.name')
+  end
+
+  ransacker :number do |parent|
+    parent.table[:number]
+  end
+end
+
+class BugTest < Minitest::Test
+  def test_ransackers
+    sql = Project.ransack({ number_present: 1 }).result.to_sql
+    puts sql
+    assert_equal "SELECT \"projects\".* FROM \"projects\" WHERE (\"projects\".\"number\" IS NOT NULL AND \"projects\".\"number\" != '')", sql
+
+    sql = Project.ransack({ name_present: 1 }).result.to_sql
+    puts sql
+    assert_equal "SELECT \"projects\".* FROM \"projects\" WHERE (projects.name IS NOT NULL AND projects.name != '')", sql
+  end
+end

data/docs/release_process.md

@@ -0,0 +1,17 @@
+## Release Process
+
+*For maintainers of Ransack.*
+
+To release a new version of Ransack and publish it to RubyGems, take the following steps:
+
+- Create a new release, marked `Prerelease`.
+- Update the versions file to the new release, commit and push to `master`.
+- Update the [`version.rb`](../lib/ransack/version.rb) file to the new release, commit and push to `master`.
+- From the terminal, run the following commands:
+
+```bash
+rake build
+rake release
+```
+
+![Create a Release](img/create_release.png)

data/{polyamorous/lib → lib}/polyamorous/activerecord_5.2_ruby_2/join_association.rb

@@ -16,5 +16,9 @@ module Polyamorous
         super(reflection, children)
       end
     end
+
+    def ==(other)
+      base_klass == other.base_klass
+    end
   end
 end

data/lib/polyamorous/activerecord_5.2_ruby_2/reflection.rb

@@ -0,0 +1,11 @@
+module Polyamorous
+  module ReflectionExtensions
+    def join_scope(table, foreign_table, foreign_klass)
+      if respond_to?(:polymorphic?) && polymorphic?
+        super.where!(foreign_table[foreign_type].eq(klass.name))
+      else
+        super
+      end
+    end
+  end
+end

data/{polyamorous/lib → lib}/polyamorous/activerecord_6.0_ruby_2/join_association.rb

@@ -1,2 +1 @@
-# active_record_6.0_ruby_2/join_association
 require 'polyamorous/activerecord_5.2_ruby_2/join_association'

data/{polyamorous/lib → lib}/polyamorous/activerecord_6.0_ruby_2/join_dependency.rb

@@ -1,5 +1,4 @@
 # active_record_6.0_ruby_2/join_dependency.rb
-
 module Polyamorous
   module JoinDependencyExtensions
     # Replaces ActiveRecord::Associations::JoinDependency#build

data/{polyamorous/lib → lib}/polyamorous/activerecord_6.0_ruby_2/reflection.rb

@@ -1,2 +1 @@
-# active_record_6.0_ruby_2/reflection.rb
 require 'polyamorous/activerecord_5.2_ruby_2/reflection'

data/lib/polyamorous/activerecord_6.1_ruby_2/join_association.rb

@@ -0,0 +1,74 @@
+module Polyamorous
+  module JoinAssociationExtensions
+    include SwappingReflectionClass
+    def self.prepended(base)
+      base.class_eval { attr_reader :join_type }
+    end
+
+    def initialize(reflection, children, polymorphic_class = nil, join_type = Arel::Nodes::InnerJoin)
+      @join_type = join_type
+      if polymorphic_class && ::ActiveRecord::Base > polymorphic_class
+        swapping_reflection_klass(reflection, polymorphic_class) do |reflection|
+          super(reflection, children)
+          self.reflection.options[:polymorphic] = true
+        end
+      else
+        super(reflection, children)
+      end
+    end
+
+    # Same as #join_constraints, but instead of constructing tables from the
+    # given block, uses the ones passed
+    def join_constraints_with_tables(foreign_table, foreign_klass, join_type, alias_tracker, tables)
+      joins = []
+      chain = []
+
+      reflection.chain.each.with_index do |reflection, i|
+        table = tables[i]
+
+        @table ||= table
+        chain << [reflection, table]
+      end
+
+      # The chain starts with the target table, but we want to end with it here (makes
+      # more sense in this context), so we reverse
+      chain.reverse_each do |reflection, table|
+        klass = reflection.klass
+
+        join_scope = reflection.join_scope(table, foreign_table, foreign_klass)
+
+        unless join_scope.references_values.empty?
+          join_dependency = join_scope.construct_join_dependency(
+            join_scope.eager_load_values | join_scope.includes_values, Arel::Nodes::OuterJoin
+          )
+          join_scope.joins!(join_dependency)
+        end
+
+        arel = join_scope.arel(alias_tracker.aliases)
+        nodes = arel.constraints.first
+
+        if nodes.is_a?(Arel::Nodes::And)
+          others = nodes.children.extract! do |node|
+            !Arel.fetch_attribute(node) { |attr| attr.relation.name == table.name }
+          end
+        end
+
+        joins << table.create_join(table, table.create_on(nodes), join_type)
+
+        if others && !others.empty?
+          joins.concat arel.join_sources
+          append_constraints(joins.last, others)
+        end
+
+        # The current table in this iteration becomes the foreign table in the next
+        foreign_table, foreign_klass = table, klass
+      end
+
+      joins
+    end
+
+    def ==(other)
+      base_klass == other.base_klass
+    end
+  end
+end

data/lib/polyamorous/activerecord_6.1_ruby_2/join_dependency.rb

@@ -0,0 +1,93 @@
+# active_record_6.1_ruby_2/join_dependency.rb
+module Polyamorous
+  module JoinDependencyExtensions
+    # Replaces ActiveRecord::Associations::JoinDependency#build
+    def build(associations, base_klass)
+      associations.map do |name, right|
+        if name.is_a? Join
+          reflection = find_reflection base_klass, name.name
+          reflection.check_validity!
+          reflection.check_eager_loadable!
+
+          klass = if reflection.polymorphic?
+            name.klass || base_klass
+          else
+            reflection.klass
+          end
+          JoinAssociation.new(reflection, build(right, klass), name.klass, name.type)
+        else
+          reflection = find_reflection base_klass, name
+          reflection.check_validity!
+          reflection.check_eager_loadable!
+
+          if reflection.polymorphic?
+            raise ActiveRecord::EagerLoadPolymorphicError.new(reflection)
+          end
+          JoinAssociation.new(reflection, build(right, reflection.klass))
+        end
+      end
+    end
+
+    def join_constraints(joins_to_add, alias_tracker, references)
+      @alias_tracker = alias_tracker
+      @joined_tables = {}
+      @references = {}
+
+      references.each do |table_name|
+        @references[table_name.to_sym] = table_name if table_name.is_a?(String)
+      end
+
+      joins = make_join_constraints(join_root, join_type)
+
+      joins.concat joins_to_add.flat_map { |oj|
+        if join_root.match?(oj.join_root) && join_root.table.name == oj.join_root.table.name
+          walk join_root, oj.join_root, oj.join_type
+        else
+          make_join_constraints(oj.join_root, oj.join_type)
+        end
+      }
+    end
+
+    def construct_tables_for_association!(join_root, association)
+      tables = table_aliases_for(join_root, association)
+      association.table = tables.first
+      tables
+    end
+
+    private
+
+    def table_aliases_for(parent, node)
+      node.reflection.chain.map { |reflection|
+        alias_tracker.aliased_table_for(reflection.klass.arel_table) do
+          root = reflection == node.reflection
+          name = reflection.alias_candidate(parent.table_name)
+          root ? name : "#{name}_join"
+        end
+      }
+    end
+
+    module ClassMethods
+      # Prepended before ActiveRecord::Associations::JoinDependency#walk_tree
+      #
+      def walk_tree(associations, hash)
+        case associations
+        when TreeNode
+          associations.add_to_tree(hash)
+        when Hash
+          associations.each do |k, v|
+            cache =
+              if TreeNode === k
+                k.add_to_tree(hash)
+              else
+                hash[k] ||= {}
+              end
+            walk_tree(v, cache)
+          end
+        else
+          super(associations, hash)
+        end
+      end
+    end
+
+  end
+end

data/{polyamorous/lib → lib}/polyamorous/activerecord_6.1_ruby_2/reflection.rb

@@ -1,2 +1 @@
-# active_record_6.1_ruby_2/reflection.rb
 require 'polyamorous/activerecord_6.0_ruby_2/reflection'

data/lib/polyamorous/activerecord_7.0_ruby_2/join_association.rb

@@ -0,0 +1 @@
+require 'polyamorous/activerecord_6.1_ruby_2/join_association'

data/lib/polyamorous/activerecord_7.0_ruby_2/join_dependency.rb

@@ -0,0 +1 @@
+require 'polyamorous/activerecord_6.1_ruby_2/join_dependency'

data/lib/polyamorous/activerecord_7.0_ruby_2/reflection.rb

@@ -0,0 +1 @@
+require 'polyamorous/activerecord_6.1_ruby_2/reflection'

data/{polyamorous/lib → lib/polyamorous}/polyamorous.rb

@@ -11,7 +11,7 @@ if defined?(::ActiveRecord)
   require 'polyamorous/join'
   require 'polyamorous/swapping_reflection_class'
 
-  ar_version = ::ActiveRecord::VERSION::STRING[0,3]
+  ar_version = ::ActiveRecord::VERSION::STRING[0, 3]
   %w(join_association join_dependency reflection).each do |file|
     require "polyamorous/activerecord_#{ar_version}_ruby_2/#{file}"
   end

data/lib/polyamorous.rb

@@ -0,0 +1 @@
+require 'polyamorous/polyamorous'