activerecord_where_assoc 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c5feb6230bf9dd2b1e1b8d74443da251e7ae7fbf
-  data.tar.gz: 1917b5b495c2808adf89737ab31676ca99fa5923
+SHA256:
+  metadata.gz: 455c7e8523f81f043fe2933c78e54e3799f66f01bff81dd34d21185c3b268aaf
+  data.tar.gz: 1895e78079d3f9f06f532e01dcd7313a9c7fa27e3f38ec411359a1352fd755db
 SHA512:
-  metadata.gz: 858c201216236ced5dbc8580874153319f11526849edb21b900302f59aabc7d99d4bd56e35a74c49ef5cd4fe07e8d0b0c4ee092d8fc8cefdcd40f0024dc371ef
-  data.tar.gz: c2ae301a6ad1f8920d33608527db33241c6e6f2bb1f14151cfa8db100af0ad5b24a01debdc46efbbde1268fd4fa7f687b89dce09a147bc8c4f7a174743e8d75a
+  metadata.gz: fecba216f37489edaaf31945436228781fae1a102a336e93e3958b47305ca04493981b6c8291743cdfd54db236560a2c3027cae61c4988997f573368b3ad7770
+  data.tar.gz: d2011c3dbee23ab3244df38e2069a5bbac4ac8c062ed4028af3090bb91222f31f98132bc62e5db0804af34736310b9d1e763dc82b5cc99b1d231fb24c1553e9e

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+# 1.0.1
+
+* Fix broken urls in error messages 
 
 # 1.0.0
 

data/README.md

@@ -20,6 +20,8 @@ my_user.posts.where_assoc_count(5, :>=, :comments) { |comments| comments.not_spa
 
 These allow for powerful, chainable, clear and easy to reuse queries. (Great for scopes)
 
+Here is an [introduction to this gem](INTRODUCTION.md).
+
 You avoid many [problems with the alternative options](ALTERNATIVES_PROBLEMS.md).
 
 Here are [many examples](EXAMPLES.md), including the generated SQL queries.
@@ -54,6 +56,12 @@ Or install it yourself as:
 
     $ gem install activerecord_where_assoc
 
+## Documentation
+
+The [documentation is nicely structured](https://maxlap.github.io/activerecord_where_assoc/ActiveRecordWhereAssoc/QueryMethods.html)
+
+If you prefer to see it in the code, [everything is in this file](https://github.com/MaxLap/activerecord_where_assoc/blob/master/lib/active_record_where_assoc/query_methods.rb) 
+
 ## Usage
 
 The [documentation is nicely structured](https://maxlap.github.io/activerecord_where_assoc/ActiveRecordWhereAssoc/QueryMethods.html)  
@@ -95,7 +103,7 @@ where_assoc_count(left_operand, operator, association_name, conditions, options,
     Post.where_assoc_count(5, :<=, :comments, is_spam: true)
     ```
 * `where_assoc_count`'s additional arguments  
-  The order of the parameters of `#where_assoc_count` can be confusingof may seem confusing, but you will get used to it. To help remember: the goal is to do: `5 < (SELECT COUNT(*) FROM ...)`, the number is first, then operator, then the association and its conditions.
+  The order of the parameters of `#where_assoc_count` may seem confusing, but you will get used to it. It helps to remember: the goal is to do: `5 < (SELECT COUNT(*) FROM ...)`, the number is first, then operator, then the association and its conditions.
   * left_operand:  
       * a number  
       * a string of SQL to embed in the query  
@@ -171,7 +179,7 @@ All the methods always chain nested associations using an `EXISTS` when they hav
 
 ### Using `#from` in scope
 
-If you want to use a scope / condition which uses `#from`, then you need to use the [:never_alias_limit](#never_alias_limit) option to avoid `#where_assoc_*` being overwritten by your scope and getting a weird exception / wrong result.
+If you want to use a scope / condition which uses `#from`, then you need to use the [:never_alias_limit](https://maxlap.github.io/activerecord_where_assoc/ActiveRecordWhereAssoc/QueryMethods.html#module-ActiveRecordWhereAssoc::QueryMethods-label-3Anever_alias_limit+option) option to avoid `#where_assoc_*` being overwritten by your scope and getting a weird exception / wrong result.
 
 ## Known issues/limitations
 
@@ -180,7 +188,7 @@ On MySQL databases, it is not possible to use `has_one` associations and associa
 
 I do not know of a way to do a SQL query that can deal with all the specifics of `has_one` for MySQL. If you have one, then please suggest it in an issue/pull request.
 
-In order to work around this, you must use the [ignore_limit](#ignore_limit) option. The behavior is less correct, but better than being unable to use the gem. 
+In order to work around this, you must use the [ignore_limit](https://maxlap.github.io/activerecord_where_assoc/ActiveRecordWhereAssoc/QueryMethods.html#module-ActiveRecordWhereAssoc::QueryMethods-label-3Aignore_limit+option) option. The behavior is less correct, but better than being unable to use the gem. 
 
 ### has_* :through vs limit/offset
 For `has_many` and `has_one` with the `:through` option, `#limit` and `#offset` are ignored. Note that `#limit` and `#offset` of the `:source` and of the `:through` side are applied correctly.

data/lib/active_record_where_assoc.rb

@@ -29,7 +29,6 @@ require_relative "active_record_where_assoc/querying"
 ActiveSupport.on_load(:active_record) do
   ActiveRecord.eager_load!
 
-  # Need to use #send for the include to support Ruby 2.0
-  ActiveRecord::Relation.send(:include, ActiveRecordWhereAssoc::QueryMethods)
+  ActiveRecord::Relation.include(ActiveRecordWhereAssoc::QueryMethods)
   ActiveRecord::Base.extend(ActiveRecordWhereAssoc::Querying)
 end

data/lib/active_record_where_assoc/core_logic.rb

@@ -284,7 +284,7 @@ module ActiveRecordWhereAssoc
             end
             msg << "This is not supported by ActiveRecord when doing joins, but it is by WhereAssoc. However, "
             msg << "you must pass the :poly_belongs_to option to specify what to do in this case.\n"
-            msg << "See https://github.com/MaxLap/activerecord_where_assoc#poly_belongs_to"
+            msg << "See https://maxlap.github.io/activerecord_where_assoc/ActiveRecordWhereAssoc/QueryMethods.html#module-ActiveRecordWhereAssoc::QueryMethods-label-3Apoly_belongs_to+option"
             raise ActiveRecordWhereAssoc::PolymorphicBelongsToWithoutClasses, msg
           else
             if on_poly_belongs_to.is_a?(Class) && on_poly_belongs_to < ActiveRecord::Base
@@ -315,7 +315,7 @@ module ActiveRecordWhereAssoc
         msg = String.new
         msg << "Associations and default_scopes with a limit or offset are not supported for MySQL (this includes has_many). "
         msg << "Use ignore_limit: true to ignore both limit and offset, and treat has_one like has_many. "
-        msg << "See https://github.com/MaxLap/activerecord_where_assoc/tree/ignore_limits#mysql-doesnt-support-sub-limit for details."
+        msg << "See https://github.com/MaxLap/activerecord_where_assoc#mysql-doesnt-support-sub-limit for details."
         raise MySQLDoesntSupportSubLimitError, msg
       end
 

data/lib/active_record_where_assoc/query_methods.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "active_record_compat"
-require_relative "exceptions"
-
 # See ActiveRecordWhereAssoc::QueryMethods
 module ActiveRecordWhereAssoc
   # This module adds new variations of +#where+ to your Models/relations/associations/scopes.
@@ -134,6 +131,8 @@ module ActiveRecordWhereAssoc
   #   Post.where_assoc_exists(:comments) { where(author_id: self.foo(:bar)) }
   #   # THESE ARE WRONG!
   #
+  # If both +condition+ and +block+ are given, the conditions are applied first, and then the block.
+  #
   # === Options
   # Some options are available to tweak how queries are generated. The default values of the options
   # can be changed globally:
@@ -150,53 +149,53 @@ module ActiveRecordWhereAssoc
   # Note, if you don't need a condition, you must pass nil as condition to provide options:
   #   Post.where_assoc_exists(:comments, nil, ignore_limit: true)
   #
-  # [ignore_limit]
-  #   When true, +#limit+ and +#offset+ that are set from default_scope, on associations, and from
-  #   +#has_one+ are ignored. <br>
-  #   Removing the limit from +#has_one+ makes them be treated like a +#has_many+.
-  #
-  #   Main reasons to use ignore_limit: true
-  #   * Needed for MySQL to be able to do anything with +#has_one+ associations because MySQL
-  #     doesn't support sub-limit. <br>
-  #     See {MySQL doesn't support limit}[https://github.com/MaxLap/activerecord_where_assoc#mysql-doesnt-support-sub-limit] <br>
-  #     Note, this does mean the +#has_one+ will be treated as if it was a +#has_many+ for MySQL too.
-  #   * You have a +#has_one+ association which you know can never have more than one record and are
-  #     dealing with a heavy/slow query. The query used to deal with +#has_many+ is less complex, and
-  #     may prove faster.
-  #   * For this one special case, you want to check the other records that match your has_one
-  #
-  # [never_alias_limit]
-  #   When true, +#where_assoc_*+ will not use +#from+ to build relations that have +#limit+ or +#offset+ set
-  #   on default_scope or on associations or for +#has_one+. <br>
-  #   This allows changing the from as part of the conditions (such as for a scope)
-  #
-  #   Main reasons to use this: you have to use +#from+ in the block of +#where_assoc_*+ method
-  #   (ex: because a scope needs +#from+).
-  #
-  #   Why this isn't the default:
-  #   * From very few tests, the aliasing way seems to produce better plans.
-  #   * Using aliasing produces a shorter query.
-  #
-  # [poly_belongs_to]
-  #   Specify what to do when a polymorphic belongs_to is encountered. Things are tricky because the query can
-  #   end up searching in multiple Models, and just knowing which ones to look into can require an expensive query.
-  #   It's also possible that you only want to search for those that match some specific Models, ignoring the other ones.
-  #   [:pluck]
-  #     Do a +#pluck+ in the column to detect to possible choices. This option can have a performance cost for big tables
-  #     or when the query if done often, as the +#pluck+ will be executed each time
-  #   [model or array of models]
-  #     Specify which models to search for. This avoids the performance cost of +#pluck+ and can allow to filter some
-  #     of the choices out that don't interest you. <br>
-  #     Note, these are not instances, it's actual models, ex: <code>[Post, Comment]</code>
-  #   [a hash]
-  #     The keys must be models (same behavior as an array of models). <br>
-  #     The values are conditions to apply only for key's model.
-  #     The conditions are either a proc (behaves like the block, but only for that model) or the same things +#where+
-  #     can receive. (String, Hash, Array, nil). Ex:
-  #       List.where_assoc_exists(:items, nil, poly_belongs_to: {Car => "color = 'blue'",
-  #                                                              Computer => proc { brand_new.where(core: 4) } })
-  #   [:raise]
-  #     (default) raise an exception when a polymorphic belongs_to is encountered.
+  # ===== :ignore_limit option
+  # When true, +#limit+ and +#offset+ that are set from default_scope, on associations, and from
+  # +#has_one+ are ignored. <br>
+  # Removing the limit from +#has_one+ makes them be treated like a +#has_many+.
+  #
+  # Main reasons to use ignore_limit: true
+  # * Needed for MySQL to be able to do anything with +#has_one+ associations because MySQL
+  #   doesn't support sub-limit. <br>
+  #   See {MySQL doesn't support limit}[https://github.com/MaxLap/activerecord_where_assoc#mysql-doesnt-support-sub-limit] <br>
+  #   Note, this does mean the +#has_one+ will be treated as if it was a +#has_many+ for MySQL too.
+  # * You have a +#has_one+ association which you know can never have more than one record and are
+  #   dealing with a heavy/slow query. The query used to deal with +#has_many+ is less complex, and
+  #   may prove faster.
+  # * For this one special case, you want to check the other records that match your has_one
+  #
+  # ===== :never_alias_limit option
+  # When true, +#where_assoc_*+ will not use +#from+ to build relations that have +#limit+ or +#offset+ set
+  # on default_scope or on associations or for +#has_one+. <br>
+  # This allows changing the from as part of the conditions (such as for a scope)
+  #
+  # Main reasons to use this: you have to use +#from+ in the block of +#where_assoc_*+ method
+  # (ex: because a scope needs +#from+).
+  #
+  # Why this isn't the default:
+  # * From very few tests, the aliasing way seems to produce better plans.
+  # * Using aliasing produces a shorter query.
+  #
+  # ===== :poly_belongs_to option
+  # Specify what to do when a polymorphic belongs_to is encountered. Things are tricky because the query can
+  # end up searching in multiple Models, and just knowing which ones to look into can require an expensive query.
+  # It's also possible that you only want to search for those that match some specific Models, ignoring the other ones.
+  # [:pluck]
+  #   Do a +#pluck+ in the column to detect to possible choices. This option can have a performance cost for big tables
+  #   or when the query if done often, as the +#pluck+ will be executed each time
+  # [model or array of models]
+  #   Specify which models to search for. This avoids the performance cost of +#pluck+ and can allow to filter some
+  #   of the choices out that don't interest you. <br>
+  #   Note, these are not instances, it's actual models, ex: <code>[Post, Comment]</code>
+  # [a hash]
+  #   The keys must be models (same behavior as an array of models). <br>
+  #   The values are conditions to apply only for key's model.
+  #   The conditions are either a proc (behaves like the block, but only for that model) or the same things +#where+
+  #   can receive. (String, Hash, Array, nil). Ex:
+  #     List.where_assoc_exists(:items, nil, poly_belongs_to: {Car => "color = 'blue'",
+  #                                                            Computer => proc { brand_new.where(core: 4) } })
+  # [:raise]
+  #   (default) raise an exception when a polymorphic belongs_to is encountered.
   module QueryMethods
     # :section: Basic methods
 
@@ -342,7 +341,13 @@ module ActiveRecordWhereAssoc
     #   The operator to use, one of these symbols: <code>  :<  :<=  :==  :!=  :>=  :>  </code>
     #
     # [association_name]
-    #   The association that must exist <br>
+    #   The association that must have a certain number of occurrences <br>
+    #   Note that if you use an array of association names, the number of the last association
+    #   is what is counted.
+    #
+    #     # Users which have received at least 5 comments total (can be spread on all of their posts)
+    #     User.where_assoc_count(5, :<=, [:posts, :comments])
+    #
     #   See ActiveRecordWhereAssoc::QueryMethods@Association
     #
     # [condition]
@@ -357,8 +362,8 @@ module ActiveRecordWhereAssoc
     #   More complex conditions the associated record must match (can also use scopes of the association's model) <br>
     #   See ActiveRecordWhereAssoc::QueryMethods@Block
     #
-    # The order of the parameters may seem confusing. But you will get used to it. To help
-    # remember the order of the parameters, remember that the goal is to do:
+    # The order of the parameters may seem confusing. But you will get used to it. It helps
+    # to remember that the goal is to do:
     #    5 < (SELECT COUNT(*) FROM ...)
     # So the parameters are in the same order as in that query: number, operator, association.
     #

data/lib/active_record_where_assoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordWhereAssoc
-  VERSION = "1.0.0".freeze
+  VERSION = "1.0.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord_where_assoc
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Maxime Handfield Lapointe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-10 00:00:00.000000000 Z
+date: 2019-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -172,7 +172,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ALTERNATIVES_PROBLEMS.md
 - CHANGELOG.md
 - EXAMPLES.md
 - LICENSE.txt
@@ -204,8 +203,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Make ActiveRecord do conditions on your associations

data/ALTERNATIVES_PROBLEMS.md

@@ -1,231 +0,0 @@
-There are multiple ways of achieving results similar to what this gems does using either only built-in ActiveRecord functionalities or other gems.
-
-This is a list of some of those alternatives, explaining what issues they have or reasons to prefer this gem over them.
-
-
-## Too long; didn't read
-
-**Use this gem, you will avoid problems and save time**
-
-* No more having to choose, case by case, which way has the less problems.  
-  Just use `#where_assoc_*` each time and avoid every problems.
-* Need less raw SQL, which means less code, more clarity and less maintenance.
-* Generates a single `#where`. No weird side-effects things like `#eager_load` or `#join`
-  This makes well-behaved scopes, you can even have multiple conditions on the same association
-* Handles recursive associations correctly.
-* Handles has_one correctly (Except [MySQL has a limitation](README.md#mysql-doesnt-support-sub-limit)).
-* Handles polymorphic belongs_to
-
-## Short version
-
-Summary of the problems of the alternatives that `activerecord_where_assoc` solves. The following sections go in more details.
-
-* every alternatives (except raw SQL):
-  * treat `has_one` like a `has_many`.
-  * can't handle recursive associations. (ex: parent/children)
-  * no simple way of checking for more complex counts. (such as `less than 5`)
-* `joins` / `includes`:
-  * doing `not exists` with conditions requires a `LEFT JOIN` with the conditions as part of the `ON`, which requires raw SQL.
-  * checking for 2 sets of conditions on different records of the same association won't work. (so your scopes can be incompatible)
-  * can't be used with Rails 5's `or` unless both sides do the same `joins` / `includes` / `eager_load`.
-  * Doesn't work for polymorphic belongs_to.
-* `joins`:
-  * `has_many` may return duplicate records.
-  * using `uniq` / `distinct` to solve duplicate rows is an unexpected side-effect when this is in a scope.
-* `includes`:
-  * triggers eagerloading, which makes your `scope` have unexpected bad performances if it's not necessary.
-  * when using a condition, the eagerloaded records are also filtered, which is very bug-prone when in a scope.
-* raw SQL:
-  * verbose, less clear on the goal of the queries (you don't even name the association the query is about).
-  * need to repeat conditions from the association / default_scope.
-* `where_exists` gem:
-  * can't use scopes of the association's model.
-  * can't go deeper than one level of association.
-
-## Common problems to most alternatives
-
-These are problems that affect most alternatives. Details are written in this section and just referred to by a one liner when they apply to an alternative.
-
-### Treating has_one like has_many
-
-Every alternative treats a has_one just like a has_many. So if any of the records (instead of only the first) matches your condition, you will get a match.
-
-And example to clarify:
-
-```ruby
-class Person < ActiveRecord::Base
-  has_many :addresses
-  has_one :current_address, -> { order("effective_date DESC") }, class_name: 'Address'
-end
-
-# This correctly matches only those whose current_address is in Montreal
-Person.where_assoc_exists(:current_address, city: 'Montreal')
-
-# Every alternatives (except raw SQL):
-# Matches those that have had an address in Montreal, no matter when
-Person.where_assoc_exists(:addresses, city: 'Montreal')
-```
-
-The general version of this problem is the handling of `limit` and `offset` on associations and in default_scopes. where_assoc_exists handle those correctly and only checks the records that match the limit and the offset.
-
-Note: [MySQL has a limitation](README.md#mysql-doesnt-support-sub-limit), this makes handling has_one correctly not possible with MySQL.
-
-### Raw SQL joins or sub-selects
-
-Having to write the joins and conditions in raw SQL is more painful and more error prone than having a method do it for you. It hides the important details of what you are doing in a lot of verbosity.
-
-If there are conditions set on either the association or a default_scope of the model, then you must rewrite those conditions in your manual joins and your manual sub-selects. Worst, if you add/change those conditions on the association / default_scope, then you must find every raw SQL that apply and do the same operation.
-
-```ruby
-class Post < ActiveRecord::Base
-  # Any raw SQL doing a join or sub-select on public_comments, if it want to be representative,
-  # must repeat "public = true".
-  has_many :public_comments, -> { where(public: true) }, class_name: 'Comment'
-end
-
-class Comment < ActiveRecord::Base
-  # Any raw SQL doing a join or sub-select to this model, if it want to be representative,
-  # must repeat "deleted_at IS NULL".
-  default_scope -> { where(deleted_at: nil) }
-end
-```
-
-All of this is avoided by where_assoc_* methods.
-
-### Unable to handle recursive associations
-
-When you have recursive associations such as parent/children, you must compare multiple rows of the same table. To do this, you have no choice but to write your own raw SQL to, at the very least, do a SQL join with an alias.
-
-This brings us back to the [raw SQL joins](#raw-sql-joins-or-sub-selects) problem.
-
-`where_assoc_*` methods handle this seemlessly.
-
-### Unable to handle polymorphic belongs_to
-
-When you have a polymorphic belongs_to, you can't use `joins` or `includes` in order to do queries on it. You have to use manual SQL ([raw SQL joins](#raw-sql-joins-or-sub-selects)) or a gem that provides the feature, such as `activerecord_where_assoc`.
-
-## ActiveRecord only
-
-Those are the common ways given in stack overflow answers.
-
-### Using `joins` and `where`
-
-```ruby
-Post.where_assoc_exists(:comments, is_spam: true)
-Post.joins(:comments).where(comments: {is_spam: true})
-```
-
-* If the association maps to multiple records (such as with a has_many), then the the relation will return one record for each matching association record. In this example, you would get the same post twice if it has 2 comments that are marked as spam.  
-  Using `uniq` can solve this issue, but if you do that in a scope, then that scope unexpectedly adds a DISTINCT to your query, which can lead to unexpected results if you actually wanted duplicates for a different reason.
-
-* Doing the opposite is a lot more complicated, as seen below. You have to include your conditions directly in the join and use a LEFT JOIN, this means writing the whole thing in raw SQL, and then you must check for the id of the association to be empty.
-
-```ruby
-Post.where_assoc_not_exists(:comments, is_spam: true)
-Post.joins("LEFT JOIN comments ON posts.id = comments.post_id AND comments.is_spam = true").where(comments: {id: nil})
-```
-
-Writing a raw join like that has yet more problems: [raw SQL joins](#raw-sql-joins-or-sub-selects)
-
-* If you want to have another condition referring to the same association (or just the same table), then you need to write out the SQL for the second join using an alias. Therefore, your scopes are not even compatible unless each of them has a join with a unique alias.
-
-```ruby
-# We want to be able to match either different or the same records
-Post.where_assoc_exists(:comments, is_spam: true)
-    .where_assoc_exists(:comments, is_reported: true)
-
-# Please don't ever do this, this just shows how painful it would be
-# If you reach the need to do this but won't use where_assoc_exists,
-# go for a regular #where("EXISTS( SELECT ...)")
-Post.joins(:comments).where(comments: {is_spam: true})
-    .joins("JOIN comments comments_for_reported ON posts.id = comments_for_reported.post_id")
-    .where(comments_for_reported: {is_reported: true})
-```
-
-* Cannot be used with Rails 5's `or` unless both side do the same `joins`.
-* [Treats has_one like a has_many](#treating-has_one-like-has_many)
-* [Can't handle recursive associations](#unable-to-handle-recursive-associations)
-* [Can't handle polymorphic belongs_to](#unable-to-handle-polymorphic-belongs_to)
-
-### Using `includes` (or `eager_load`) and `where`
-
-This solution is similar to the `joins` one above, but avoids the need for `uniq`. Every other problems of the `joins` remain. You also add other potential issues.
-
-```ruby
-Post.where_assoc_exists(:comments, is_spam: true)
-Post.eager_load(:comments).where(comments: {is_spam: true})
-```
-
-* You are triggering the loading of potentially lots of records that you might not need. You don't expect a scope like `have_reported_comments` to trigger eager loading. This is a performance degradation.
-
-* The eager loaded records of the association are actually also filtered by the conditions. All of the posts returned will only have the comments that are spam.  
-  This means if you iterate on `Post.have_reported_comments` to display each of the comments of the posts that have at least one reported comment, you are actually only going to display the reported comments. This may be what you wanted to do, but it clearly isn't intuitive.
-
-* Cannot be used with Rails 5's `or` unless both side do the same `includes` or `eager_load`.
-
-* [Treats has_one like a has_many](#treating-has_one-like-has_many)
-* [Can't handle recursive associations](#unable-to-handle-recursive-associations)
-* [Can't handle polymorphic belongs_to](#unable-to-handle-polymorphic-belongs_to)
-
-* Simply cannot be used for complex cases.
-
-Note: using `includes` (or `eager_load`) already does a LEFT JOIN, so it is pretty easy to do a "not exists", but only if you don't need any condition on the association (which would normally need to be in the JOIN clause):
-
-```ruby
-Post.where_assoc_exists(:comments)
-Post.eager_load(:comments).where(comments: {id: nil})
-```
-
-### Using `where("EXISTS( SELECT... )")`
-
-This is what is gem does behind the scene, but doing it manually can lead to troubles:
-
-* Problems with writing [raw SQL sub-selects](#raw-sql-joins-or-sub-selects)
-
-* Unless you do a quite complex nested sub-selects, you will [treat has_one like a has_many](#treating-has_one-like-has_many)
-
-
-## Gems
-
-### where_exists
-
-https://github.com/EugZol/where_exists
-
-An interesting gem that also does `EXISTS (SELECT ... )` behind the scene. Solves most issues from ActiveRecord only alternatives, but appears less powerful than where_assoc_exists.
-
-* where_exists supports polymorphic belongs_to only by always doing a `pluck` everytime. In some situation could be a slow query if there is a lots of rows to scan. where_assoc also allows directly specifying the classes manually, avoiding the pluck and possibly filtering the choices.
-  
-* Unable to use scopes of the association's model.
-```ruby
-# There is no equivalent for this (admins is a scope on User)
-Comment.where_assoc_exists(:author, &:admins)
-```
-
-* Cannot use a block for more complex conditions
-```ruby
-# There is no equivalent for this
-Comment.where_assoc_exists(:author) { admins.where("created_at <= ?", 1.month.ago) }
-```
-
-* Unable to dig deeper in the associations  
-  Note: it does follow :through associations so doing a custom associations for your need can be a workaround.
-
-```ruby
-# There is no equivalent for this (Users that have posts with at least a comments)
-User.where_assoc_exists([:posts, :comments])
-```
-
-* Has no equivalent to `where_assoc_count`
-```ruby
-# There is no equivalent for this (posts with more than 5 comments)
-Post.where_assoc_count(:comments, :>, 5)
-```
-
-* [Treats has_one like a has_many](#treating-has_one-like-has_many)
-
-* [Can't handle recursive associations](#unable-to-handle-recursive-associations)
-
-* `where_exists` is shorter than `where_assoc_exists`, but it is also less obvious about what it does.  
-  In any case, it is trivial to alias one name to the other one.
-
-* where_exists supports Rails 4.2 and up, while where_assoc supports Rails 4.1 and up.