where_exists 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10aa100274a4f1cbc5ffd1efddaf255242a4ffa99bb4aa857ec807e4060a2198
-  data.tar.gz: 7572426b34fd9056a781006dce704de782bc94f48899ec66d6cdb2ce7fd00aab
+  metadata.gz: 28bde73cd6a1857a0762a1fd489258ad40b44cea344afba4357cbe7fa83cdf41
+  data.tar.gz: ed7a98cb6a7391cb955c911f0063f9eb901e86305b0b7ddb3e01b9a209371476
 SHA512:
-  metadata.gz: d17add3cb16b2edeca33761dd8097b4da1f1203af9ffe891b0c2756d6e606b08b12ac7ce67bd8e5869cfee6389fbfc8fcb26da2d00941d00ab9c00d6691c8af9
-  data.tar.gz: 33f4b910af735aedb797329d99c876a5978fdaac103f704044ad9095e4856e4cffc17359f5f2ad0c4f21379483622f25fecd842a4928327e2641d21078cee77c
+  metadata.gz: 943e345289ac9f2a2d44a5428a559c8a22adb11713b26ac0e7893fd28ccbb9577a092bbae50fa9eec960c72497ca5d902892209ce7c83d9c2b291fc017e0d5ab
+  data.tar.gz: 509c56167e4998c662bf21efa637de8495cc5d2974421041d8264f66de16f99a2c223463cfd494b35f64bffb39b8511696822405e2609b649ff876f685ffd4cc

data/README.markdown

@@ -0,0 +1,168 @@
+# 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: >= 4.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 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.1"
+  VERSION = "1.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: where_exists
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Eugene Zolotarev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-19 00:00:00.000000000 Z
+date: 2020-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -19,7 +19,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,21 +29,21 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.2'
 - !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
@@ -94,6 +94,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
+- README.markdown
 - Rakefile
 - lib/where_exists.rb
 - lib/where_exists/version.rb
@@ -125,17 +126,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: "#where_exists extension of ActiveRecord"
 test_files:
+- test/has_and_belongs_to_many.rb
 - test/belongs_to_polymorphic_test.rb
-- test/belongs_to_test.rb
+- test/has_many_through_test.rb
 - test/db/test.db
-- test/documentation_test.rb
-- test/has_and_belongs_to_many.rb
+- test/test_helper.rb
 - test/has_many_polymorphic_test.rb
 - test/has_many_test.rb
-- test/has_many_through_test.rb
-- test/test_helper.rb
+- test/documentation_test.rb
+- test/belongs_to_test.rb