activerecord_where_assoc 0.1.3 → 1.1.2

data/lib/active_record_where_assoc/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord_where_assoc
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 1.1.2
 platform: ruby
 authors:
 - Maxime Handfield Lapointe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-20 00:00:00.000000000 Z
+date: 2020-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -28,14 +28,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
 - !ruby/object:Gem::Dependency
@@ -68,32 +68,18 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.0'
 - !ruby/object:Gem::Dependency
   name: deep-cover
   requirement: !ruby/object:Gem::Requirement
@@ -172,7 +158,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ALTERNATIVES_PROBLEMS.md
 - CHANGELOG.md
 - EXAMPLES.md
 - LICENSE.txt
@@ -181,8 +166,9 @@ files:
 - lib/active_record_where_assoc/active_record_compat.rb
 - lib/active_record_where_assoc/core_logic.rb
 - lib/active_record_where_assoc/exceptions.rb
-- lib/active_record_where_assoc/query_methods.rb
-- lib/active_record_where_assoc/querying.rb
+- lib/active_record_where_assoc/relation_returning_delegates.rb
+- lib/active_record_where_assoc/relation_returning_methods.rb
+- lib/active_record_where_assoc/sql_returning_methods.rb
 - lib/active_record_where_assoc/version.rb
 - lib/activerecord_where_assoc.rb
 homepage: https://github.com/MaxLap/activerecord_where_assoc
@@ -204,8 +190,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Make ActiveRecord do conditions on your associations

data/ALTERNATIVES_PROBLEMS.md

@@ -1,221 +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.
-* Allows powerful scopes without traps.
-* Handles recursive associations correctly.
-* Handles has_one correctly.
-
-## 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`.
-* `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.
-
-### 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.
-
-## 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)
-
-### 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)
-
-* 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. This is something that where_assoc doesn't do at the moment.  
-  However, the way it does this is by doing a pluck on the type column, which in some situation could be a slow query if there is a lots of rows to scan.
-  
-* 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.

data/lib/active_record_where_assoc/query_methods.rb

@@ -1,180 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "active_record_compat"
-require_relative "exceptions"
-
-module ActiveRecordWhereAssoc
-  module QueryMethods
-    # Returns a new relation, which is the result of filtering the current relation
-    # based on if a record for the specified association of the model exists. Conditions
-    # the associated model must match to count as existing can also be specified.
-    #
-    # Here is a quick overview of the arguments received followed by a detailed explanation
-    # along with more examples. You may also consider viewing the gem's README. It contains
-    # known issues and some tips. The readme is packaged with the gem and viewable on github:
-    # https://github.com/MaxLap/activerecord_where_assoc
-    #
-    #
-    # As 1st argument, you must specify the association to check against. This can be
-    # any of the associations on the current relation's model.
-    #
-    #    # Posts that have at least one comment
-    #    Post.where_assoc_exists(:comments)
-    #
-    # As 2nd argument, you can add conditions that the records in the association must match
-    # to be considered as existing.
-    #
-    # The 3rd argument is for options that alter how the query is generated.
-    #
-    # If your conditions are too complex or too long to be placed in the 2nd argument,
-    # #where_assoc_* accepts a block in which you can do anything you want on the relation
-    # (any scoping method such as #where, #joins, nested #where_assoc_*, scopes of the model).
-    #
-    # === the association argument (1st argument)
-    #
-    # This is the association you want to check if records exists. If you want, you can pass
-    # an array of associations. They will be followed in order, just like a has_many :through
-    # would.
-    #
-    #    # Posts with at least one comment
-    #    Post.where_assoc_exists(:comments)
-    #
-    #    # Posts for which there is at least one reply to a comment.
-    #    Post.where_assoc_exists([:comments, :replies])
-    #
-    # Note that if you use conditions / blocks, they will only be applied to the last
-    # association of the array. If you want something else, you will need to use
-    # the block argument to nest multiple calls to #where_assoc_exists
-    #
-    #    # Post.where_assoc_exists(:comments) { where_assoc_exists(:replies) }
-    #
-    # === the condition argument (2nd argument)
-    #
-    # This argument is additional conditions the association's records must fulfill to be
-    # considered as "existing". The argument is passed directly to #where.
-    #
-    #    # Posts that have at least one comment considered as spam
-    #    # Using a Hash
-    #    Post.where_assoc_exists(:comments, is_spam: true)
-    #
-    #    # Using a String
-    #    Post.where_assoc_exists(:comments, "is_spam = true")
-    #
-    #    # Using an Array (a string and its binds)
-    #    Post.where_assoc_exists(:comments, ["is_spam = ?", true])
-    #
-    # If the condition argument is blank, it is ignored (just like #where does).
-    #
-    # === the options argument (3rd argument)
-    #
-    # Some options are available to tweak how things queries are generated. In some case, this
-    # also changes the results of the query.
-    #
-    # ignore_limit: when true, #limit and #offset that are set either from default_scope or
-    #               on associations are ignored. #has_one means #limit(1), so this makes
-    #               #has_one be treated like #has_many.
-    #
-    # 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.
-    #                    Note, #has_one means #limit(1), so it will also use #from unless this
-    #                    option is activated.
-    #
-    # === the block
-    #
-    # The block is used to add more complex conditions. The result behaves the same way
-    # as the 2nd argument's conditions, but lets you use any scoping methods, such as
-    # #where, #joins, # nested #where_assoc_* and scopes of the model. Note that using
-    # #joins might lead to unexpected results when using #where_assoc_count, since if
-    # the joins adds rows, it will change the resulting count.
-    #
-    # There are 2 ways of using the block for adding conditions to the association.
-    #
-    # * A block that receives one argument
-    # The block receives a relation on the target association and return a relation with added
-    # filters or may return nil to do nothing.
-    #
-    #    # Using a where for the added condition
-    #    Post.where_assoc_exists(:comments) { |comments| comments.where(is_spam: true) }
-    #
-    #    # Applying a scope of the relation
-    #    Post.where_assoc_exists(:comments) { |comments| comments.spam_flagged }
-    #
-    #    # Applying a scope of the relation, using the &:shortcut for procs
-    #    Post.where_assoc_exists(:comments, &:spam_flagged)
-    #
-    #
-    # * A block that receives no argument
-    # Instead of receiving the relation as argument, the relation is used as the "self" of
-    # the block. Everything else is identical to the block with one argument.
-    #
-    #    # Using a where for the added condition
-    #    Post.where_assoc_exists(:comments) { where(is_spam: true) }
-    #
-    #    # Applying a scope of the relation
-    #    Post.where_assoc_exists(:comments) { spam_flagged }
-    #
-    # The main reason to use a block with an argument instead of without is when you need
-    # to call methods on the self outside of the block, such as:
-    #
-    #    Post.where_assoc_exists(:comments) { |comments| comments.where(id: self.something) }
-    #
-    def where_assoc_exists(association_name, given_scope = nil, options = {}, &block)
-      ActiveRecordWhereAssoc::CoreLogic.do_where_assoc_exists(self, association_name, given_scope, options, &block)
-    end
-
-    # Returns a new relation, which is the result of filtering the current relation
-    # based on if a record for the specified association of the model doesn't exist.
-    # Conditions the associated model must match to count as existing can also be specified.
-    #
-    # The parameters and everything is identical to #where_assoc_exists. The only
-    # difference is that a record is matched if no matching association record that
-    # fulfill the conditions are found.
-    def where_assoc_not_exists(association_name, given_scope = nil, options = {}, &block)
-      ActiveRecordWhereAssoc::CoreLogic.do_where_assoc_not_exists(self, association_name, given_scope, options, &block)
-    end
-
-    # Returns a new relation, which is the result of filtering the current relation
-    # based on how many records for the specified association of the model exists. Conditions
-    # the associated model must match can also be specified.
-    #
-    # #where_assoc_count is a generalization of #where_assoc_exists and #where_assoc_not_exists.
-    # It behave behaves the same way as them, but is more flexible as it allows you to be
-    # specific about how many matches there should be. To clarify, here are equivalent examples:
-    #
-    #    Post.where_assoc_exists(:comments)
-    #    Post.where_assoc_count(1, :<=, :comments)
-    #
-    #    Post.where_assoc_not_exists(:comments)
-    #    Post.where_assoc_count(0, :==, :comments)
-    #
-    # The usage is the same as with #where_assoc_exists, however, 2 arguments are inserted
-    # at the beginning.
-    #
-    # 1st argument: the left side of the comparison. One of:
-    #               a number
-    #               a string of SQL to embed in the query
-    #               a range (operator must be :== or :!=), will use BETWEEN or NOT BETWEEN
-    #                                                      supports infinite ranges and exclusive end
-    # 2nd argument: the operator to use: :<, :<=, :==, :!=, :>=, :>
-    # 3rd, 4th and 5th arguments: same as #where_assoc_exists' 1st, 2nd and 3rd arguments
-    # block: same as #where_assoc_exists' 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:
-    #    5 < (SELECT COUNT(*) FROM ...)
-    # So the parameters are in the same order as in that query: number, operator, association.
-    #
-    # To be clear, when you use multiple associations in an array, the count you will be
-    # comparing against is the total number of records of that last association.
-    #
-    #   # The users that have received at least 5 comments total on all of their posts
-    #   # So this can be one post that has 5 comments of 5 posts with 1 comments
-    #   User.where_assoc_count(5, :<=, [:posts, :comments])
-    #
-    #   # The users that have at least 5 posts with at least one comments
-    #   User.where_assoc_count(5, :<=, :posts) { where_assoc_exists(:comments) }
-    def where_assoc_count(left_operand, operator, association_name, given_scope = nil, options = {}, &block)
-      ActiveRecordWhereAssoc::CoreLogic.do_where_assoc_count(self, left_operand, operator, association_name, given_scope, options, &block)
-    end
-  end
-end