includes-count 0.1 → 0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 01664881d5b615683b68c72b023bf901e492fb35
+  data.tar.gz: 15a6cba04f0c7a280de2eb6825532665cee4e15c
+SHA512:
+  metadata.gz: 1b60c9999656159d056e45ca3a457e597079d3891bc734aa4f7be65caa9515aec046156c79de7c01f5356a4547e9f02bfb2524172fc9d186fb09e6e677dc71a5
+  data.tar.gz: 8312170635c24bad30c4ae06c5f5bd290bbb8be175ec112c27ac51e7b8848d76f39071aae08dea7c2940418df8ee8150c2efe8d40470c62c66ca36baa7931d4a

data/README.md

@@ -1,4 +1,138 @@
-Includes Count Gem
-==================
+Includes Count
+==============
 
-Tested with ActiveRecord version 3.1.3
+This gem adds an `includes_count` method to active record queries, which adds the count of an association to a relation using a simple `SELECT` SQL query in a similar way as the `includes` method does, only that retrieving counts instead of the full records collection. 
+
+This gem has been tested with ActiveRecord version 3.1.3.
+
+Usage
+=====
+
+For example, in the following model:
+
+```ruby
+class Blog
+  has_many :posts
+  has_many :comments, :through => :posts
+end
+
+class Post
+  belongs_to :blog
+  has_many :comments
+end
+
+class Comment
+  belongs_to :post
+end
+```
+
+It is possible to retrieve the number of posts in every blog with the command:
+
+```ruby
+blogs_with_posts_count = Blog.scoped.includes_count(:posts)
+```
+
+This will issue a simple `SELECT` query retrieving all counts and assigning them in memory, thus not requiring an `INNER JOIN` that could be expensive to handle in the database:
+
+```sql
+SELECT SQL_NO_CACHE posts.blog_id, COUNT(id) AS posts_count
+FROM `posts`
+WHERE `posts`.`blog_id` IN (1, 2, 3, 4, 5, 6, 7, 8)
+GROUP BY `posts`.`blog_id`
+```
+    
+The count is projected to a field named by default `association_name_count`:
+
+```ruby
+blogs_with_posts_count.map(&:posts_count)
+```
+    
+The name of the method can be changed by supplying the `count_name` option:
+
+```ruby
+blogs_with_posts_count = Blog.scoped.includes_count(:posts, :count_name => 'number_of_posts')
+blogs_with_posts_count.map(&:posts_count)
+```
+    
+The execution of the count is delayed until execution of the query, as happens with the `includes` clause, so further clauses, such as `where`, can be set to the relation:
+
+```ruby
+latest_blogs_with_posts_count = Blog.scoped.includes_count(:posts).where('updated_at > ?', 1.week.ago)
+```
+
+This will retrieve only the blogs that have been updated since 1 week ago, along with their counts. Supposing there are only two blogs that match that condition (ids 3 and 5), the `SELECT` query issued will be the following:
+
+```sql
+SELECT SQL_NO_CACHE posts.blog_id, COUNT(id) AS posts_count
+FROM `posts`
+WHERE `posts`.`blog_id` IN (3, 5)
+GROUP BY `posts`.`blog_id`
+```
+
+Conditions can be specified on the included association (using a string, a hash or a proc), in order to filter which records are to be counted:
+
+```ruby
+blogs_with_rails_posts_count = Blog.scoped.includes_count(:posts, :count_name => 'rails_posts_count', :conditions => "category = 'rails'")
+```
+
+```sql
+SELECT SQL_NO_CACHE posts.blog_id, COUNT(id) AS posts_count
+FROM `posts`
+WHERE `posts`.`blog_id` IN (3, 5)
+  AND `posts`.`category` = 'rails'
+GROUP BY `posts`.`blog_id`
+```
+    
+Through Associations
+--------------------
+
+The `includes_count` method also supports through associations, and issues as many `SELECT` queries as needed to navigate the hierarchy and obtain the specified counts.
+
+```ruby
+blogs_with_comments_count = Blog.scoped.includes_count(:comments)
+```
+    
+```sql
+SELECT SQL_NO_CACHE `posts`.*
+FROM `posts`
+WHERE `posts`.`blog_id` IN (1, 2, 3, 4, 5, 6, 7, 8)
+```
+
+```sql
+SELECT SQL_NO_CACHE `comments`.post_id, COUNT(id) AS comments_count
+FROM `comments`
+WHERE `comments`.`post_id` IN (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
+GROUP BY `comments`.`post_id`
+```
+
+As usual, the value can be accessed via the method named after the association, and overridden via `count_name`:
+
+```ruby
+blogs_with_posts_count.map(&:comments_count)
+```
+    
+It is also possible to specify conditions at any of the intermediate associations in the `through` association:
+
+```ruby
+blogs_with_comments_count_from_rails_posts = Blog.scoped.includes_count(:comments, :through_options => { :posts => { :conditions => "category = 'rails'"} })
+```
+    
+```sql
+SELECT SQL_NO_CACHE `posts`.*
+FROM `posts`
+WHERE `posts`.`blog_id` IN (1, 2, 3, 4, 5, 6, 7, 8)
+  AND `posts`.`category` = 'rails'
+```
+    
+```sql
+SELECT SQL_NO_CACHE `comments`.post_id, COUNT(id) AS comments_count
+FROM `comments`
+WHERE `comments`.`post_id` IN (5, 6, 10, 11, 12)
+GROUP BY `comments`.`post_id`
+```
+
+
+Known Issues
+------------
+
+* The `includes_count` method is included only in `ActiveRecord::Relation` objects, which means you cannot execute it straight on a model. As a workaround, supply the method `scoped` before executing `includes_count`: `Blog.scoped.includes_count(:posts)`

data/lib/includes-count.rb

@@ -19,8 +19,13 @@ module ActiveRecord
 
         def preload
           associated_records_by_owner.each do |owner, associated_records|
-            owner[count_name] ||= 0
-            owner[count_name] += associated_records.map{|r| r[count_name] || 0}.sum
+            sum = associated_records.map{|r| r[count_name] || 0}.sum
+            owner.instance_eval "
+              def #{count_name}
+                @#{count_name} ||= 0
+                @#{count_name} += #{sum}
+              end  
+            "
           end
         end
 

data/lib/includes-count/version.rb

@@ -1,3 +1,3 @@
 module IncludesCount
-  VERSION = "0.1"
+  VERSION = "0.2"
 end

metadata

@@ -1,27 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: includes-count
 version: !ruby/object:Gem::Version
-  version: '0.1'
-  prerelease: 
+  version: '0.2'
 platform: ruby
 authors:
 - Santiago Palladino
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-10 00:00:00.000000000 Z
+date: 2014-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &70110664755620 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70110664755620
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: The includes_count method executes a SQL count on an association to retrieve
   its number of records, optionally filtered by a set of conditions.
 email:
@@ -39,26 +41,25 @@ files:
 - lib/includes-count/version.rb
 homepage: ''
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: includes-count
-rubygems_version: 1.8.10
+rubygems_version: 2.0.14
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Adds includes_count method to active record queries
 test_files: []