where_exists 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fe61ef5f7b676e2d9b3704b34f8101e7e84157060f2b11d56db8e99027765a9
-  data.tar.gz: e8de623c18fe2df6c50c809b6bf0b551eb66bf7ae2a36e0ca65cc18a44470b79
+  metadata.gz: 5f3ba0936a289c595a6efec3b73bcc9f46f445981150a43fa72af419eb13dec8
+  data.tar.gz: 022c543b783c601be1076b4de866e9052d1c6b352b727b52a793585a571aed61
 SHA512:
-  metadata.gz: 9f4b7fe34573309d53e2e81255782a2d4f3dbfa190c9e975d5cc9eb6750f0b118d448401002786862932ed1fcda19cda6ee3387d5a7a036b7594d841872c907e
-  data.tar.gz: 389a33011c215ad3373388d20f5b49f186b80458dc18afee829c9ddf370d84b517e8ad16df300e041198b192f2884f9a4217cd6677179f7999591f5d74580f16
+  metadata.gz: 265df32741d7633eaaac17b5dfa27a33e813ba4680a98ca4c8fd05d58d839adf4439944dd5e0942b1b44af850a14fb2bf5b48848d73fb8c4beb6fb2b94766749
+  data.tar.gz: 7dd2b69d952f63f4bb96999b0e4c86672fe08cdd77f37755a48a7d6d2aab0072bf0a65b5f6aed8183a6688dcbdff453fd00d41a035e29009762cfc69fcc8a261

data/README.markdown

@@ -0,0 +1,172 @@
+# Where Exists
+**Rails way to harness the power of SQL EXISTS condition**<br>
+[![Gem Version](https://badge.fury.io/rb/where_exists.svg)](http://badge.fury.io/rb/where_exists)
+
+## Description
+
+<img src="http://i.imgur.com/psLfPoW.gif" alt="Exists" align="right" width="100" height="200">
+
+This gem does exactly two things:
+
+* Selects each model object for which there is a certain associated object
+* Selects each model object for which there aren't any certain associated objects
+
+It uses SQL [EXISTS condition](http://www.techonthenet.com/sql/exists.php) to do it fast, and extends ActiveRecord with `where_exists` and `where_not_exists` methods to make its usage simple and straightforward.
+
+## Quick start
+
+Add gem to Gemfile:
+
+    gem 'where_exists'
+
+and run `bundle install` as usual.
+
+And now you have `where_exists` and `where_not_exists` methods available for your ActiveRecord models and relations.
+
+Syntax:
+
+```ruby
+Model.where_exists(association, additional_finder_parameters)
+```
+
+Supported Rails versions: >= 5.2.
+
+## Example of usage
+
+Given there is User model:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :connections
+  has_many :groups, through: :connections
+end
+```
+
+And Group:
+
+```ruby
+class Group < ActiveRecord::Base
+  has_many :connections
+  has_many :users, through: :connections
+end
+```
+
+And standard many-to-many Connection:
+
+```ruby
+class Connection
+  belongs_to :user
+  belongs_to :group
+end
+```
+
+What I want to do is to:
+
+* Select users who don't belong to given set of Groups (groups with ids `[4,5,6]`)
+* Select users who belong to one set of Groups (`[1,2,3]`) and don't belong to another (`[4,5,6]`)
+* Select users who don't belong to a Group
+
+Also, I don't want to:
+
+* Fetch a lot of data from database to manipulate it with Ruby code. I know that will be inefficient in terms of CPU and memory (Ruby is much slower than any commonly used DB engine, and typically I want to rely on DB engine to do the heavy lifting)
+* I tried queries like `User.joins(:group).where(group_id: [1,2,3]).where.not(group_id: [4,5,6])` and they return wrong results (some users from the result set belong to groups 4,5,6 *as well as* 1,2,3)
+* I don't want to do `join` merely for the sake of only checking for existence, because I know that that is a pretty complex (i.e. CPU/memory-intensive) operation for DB
+
+<sub><sup>If you wonder how to do that without the gem (i.e. essentially by writing SQL EXISTS statement manually) see that [StackOverflow answer](http://stackoverflow.com/a/32016347/5029266) (disclosure: it's self-answered question of a contributor of this gem).</sup></sub>
+
+And now you are able to do all these things (and more) as simple as:
+
+> Select only users who don't belong to given set of Groups (groups with ids `[4,5,6]`)
+
+```ruby
+# It's really neat, isn't it?
+User.where_exists(:groups, id: [4,5,6])
+```
+
+<sub><sup>Notice that the second argument is `where` parameters for Group model</sup></sub>
+
+> Select only users who belong to one set of Groups (`[1,2,3]`) and don't belong to another (`[4,5,6]`)
+
+```ruby
+# Chain-able like you expect them to be.
+#
+# Additional finder parameters is anything that
+# could be fed to 'where' method.
+#
+# Let's use 'name' instead of 'id' here, for example.
+
+User.where_exists(:groups, name: ['first','second','third']).
+  where_not_exists(:groups, name: ['fourth','fifth','sixth'])
+```
+
+<sub><sup>It is possible to add as much attributes to the criteria as it is necessary, just as with regular `where(...)`</sub></sup>
+
+> Select only users who don't belong to a Group
+
+```ruby
+# And that's just its basic capabilities
+User.where_not_exists(:groups)
+```
+
+<sub><sup>Adding parameters (the second argument) to `where_not_exists` method is feasible as well, if you have such requirements.</sup></sub>
+
+
+> Re-use existing scopes
+
+```ruby
+User.where_exists(:groups) do |groups_scope|
+  groups_scope.activated_since(Time.now)
+end
+
+User.where_exists(:groups, &:approved)
+```
+<sub><sup>If you pass a block to `where_exists`, the scope of the relation will be yielded to your block so you can re-use existing scopes.</sup></sub>
+
+
+
+## Additional capabilities
+
+**Q**: Does it support both `has_many` and `belongs_to` association type?<br>
+**A**: Yes.
+
+
+**Q**: Does it support polymorphic associations?<br>
+**A**: Yes, both ways.
+
+
+**Q**: Does it support multi-level (recursive) `:through` associations?<br>
+**A**: You bet. (Now you can forget complex EXISTS or JOIN statetements in a pretty wide variety of similar cases.)
+
+
+**Q**: Does it support `where` parameters with interpolation, e.g. `parent.where_exists(:child, 'fieldA > ?', 1)`?<br>
+**A**: Yes.
+
+
+**Q**: Does it take into account default association condition, e.g. `has_many :drafts, -> { where published: nil }`?<br>
+**A**: Yes.
+
+## Contributing
+
+If you find that this gem lacks certain possibilities that you would have found useful, don't hesitate to create a [feature request](https://github.com/EugZol/where_exists/issues).
+
+Also,
+
+* Report bugs
+* Submit pull request with new features or bug fixes
+* Enhance or clarify the documentation that you are reading
+
+To run tests:
+```
+> bundle exec appraisal install
+> bundle exec appraisal rake test
+```
+
+## License
+
+This project uses MIT license. See [`MIT-LICENSE`](https://github.com/EugZol/where_exists/blob/master/MIT-LICENSE) file for full text.
+
+## Alternatives
+
+One known alternative is https://github.com/MaxLap/activerecord_where_assoc
+
+A comprehensive comparison is made by MaxLap here: https://github.com/MaxLap/activerecord_where_assoc/blob/master/ALTERNATIVES_PROBLEMS.md

data/lib/where_exists/version.rb

@@ -1,3 +1,3 @@
 module WhereExists
-  VERSION = "1.2.0"
+  VERSION = "2.0.0"
 end

data/lib/where_exists.rb

@@ -20,7 +20,11 @@ module WhereExists
       not_string = "NOT "
     end
 
-    self.where("#{not_string}(#{queries_sql})")
+    if queries_sql.empty?
+      does_exist ? self.none : self.all
+    else
+      self.where("#{not_string}(#{queries_sql})")
+    end
   end
 
   def build_exists_string(association_name, *where_parameters, &block)

data/test/belongs_to_polymorphic_test.rb

@@ -61,6 +61,18 @@ class BelongsToPolymorphicTest < Minitest::Test
     assert_equal orphaned_child.id, result.first.id
   end
 
+  def test_no_entities_or_empty_child_relation
+    result = BelongsToPolymorphicChild.where_not_exists(:polymorphic_entity)
+    assert_equal 0, result.length
+
+    _first_child = BelongsToPolymorphicChild.create!
+    result = BelongsToPolymorphicChild.where_not_exists(:polymorphic_entity)
+    assert_equal 1, result.length
+
+    result = BelongsToPolymorphicChild.where_exists(:polymorphic_entity)
+    assert_equal 0, result.length
+  end
+
   def test_table_name_based_lookup
     first_entity = FirstPolymorphicEntity.create!
     second_entity = SecondPolymorphicEntity.create! id: first_entity.id + 1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: where_exists
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Eugene Zolotarev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-19 00:00:00.000000000 Z
+date: 2021-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,34 +16,34 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '5.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Rails way to harness the power of SQL "EXISTS" statement
 email:
 - eugzol@gmail.com
@@ -94,6 +108,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
+- README.markdown
 - Rakefile
 - lib/where_exists.rb
 - lib/where_exists/version.rb
@@ -125,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: "#where_exists extension of ActiveRecord"