edge_rider 0.1.1 → 0.2.0

data/README.md

@@ -1,10 +1,184 @@
 Edge Rider [![Build Status](https://secure.travis-ci.org/makandra/edge_rider.png?branch=master)](https://travis-ci.org/makandra/edge_rider)
 ====================================
 
-Power tools for Active Record relations (scopes)
+Power tools for ActiveRecord relations (scopes)
 -------------------------------------------------
 
-TODO: Write README
+In ActiveRecord, relations (or scopes) allow you to construct complex queries piece-by-piece
+and then trigger a query or update at a precisely defined moment. If you write any kind
+of scalable code with ActiveRecord, you are probably using relations (or scopes) to do it.
+
+Edge Rider was created with two intents:
+
+1. Provides a number of utility methods to facilitate hardcore work with relations.
+2. Provide a stable API for working with relations across multiple versions of Rails (since
+Rails has a tradition of breaking details of its relation API every other release).
+
+It has been tested with Rails 2.3, 3.0 and 3.2.
+
+
+Usage
+-----
+
+### Traversing a relation along an association
+
+Edge Rider gives your relations a method `#traverse_association` which
+returns a new relation by "pivoting" around a named association.
+
+Say we have a `Post` model and each `Post` belongs to an author:
+
+    class Post < ActiveRecord::Base
+      belongs_to :author
+    end
+  
+To turn a relation of posts into a relation of its authors:
+
+    posts = Post.where(:archived => false)
+    authors = posts.traverse_association(:author)
+    
+You can traverse multiple associations in a single call.
+E.g. to turn a relation of posts into a relation of all posts of their authors:
+
+    posts = Post.where(:archived => false)
+    posts_by_same_authors = posts.traverse_association(:author, :posts)
+
+*Implementation note:* The traversal is achieved internally by collecting all foreign keys in the current relation
+and return a new relation with an `IN(...)` query (which is very efficient even for many thousand keys).
+This means every association that you pivot around will trigger one SQL query.
+
+
+### Efficiently collect all record IDs in a relation
+
+You often want to retrieve an array of all record IDs in a relation.
+
+You should **not** use `relation.collect(&:id)` for this because a call like that
+will instantiate a potentially large number of ActiveRecord objects only to collect
+its ID.
+
+Edge Rider has a better way. Your relations gain a method `#collect_ids` that will
+fetch all IDs in a single query without instantiating a single ActiveRecord object:
+
+    posts = Post.where(:archived => false)
+    post_ids = posts.collect_ids
+
+*Implemenation note:* In Rails 3.2+, `#collect_ids` delegates to [`#pluck`](http://apidock.com/rails/ActiveRecord/Calculations/pluck),
+which can be used for the same purpose.
+
+
+### Collect record IDs from any kind of object
+
+When writing a method that filters by record IDs, you can make it more useful by accepting
+any kind of argument that can be turned into a list of IDs:
+
+    Post.by_author(1)
+    Post.by_author([1, 2, 3])
+    Post.by_author(Author.find(1))
+    Post.by_author([Author.find(1), Author.find(2)])
+    Post.by_author(Author.active)
+
+For this use case Edge Rider defines `#collect_ids` on many different types:
+
+    Post.where(:id => [1, 2]).collect_ids    # => [1, 2, 3]
+    [Post.find(1), Post.find(2)].collect_ids # => [1, 2]
+    Post.find(1).collect_ids                 # => [1]
+    [1, 2, 3].collect_ids                    # => [1, 2, 3]
+    1.collect_ids                            # => [1]
+
+You can now write `Post.by_author` from the example above without a single `if` or `case`:
+
+    class Post < ActiveRecord::Base
+    
+      belongs_to :author
+
+      def self.for_author(author_or_authors)
+        where(:author_id => author_or_authors.collect_ids)
+      end
+
+    end
+    
+    
+### Efficiently collect all values in a relation's column
+
+You often want to ask a relation for an array of all values ofin a given column.
+
+You should **not** use `relation.collect(&:column)` for this because a call like that
+will instantiate a potentially large number of ActiveRecord objects only to collect
+its column value.
+
+Edge Rider has a better way. Your relations gain a method `#collect_column` that will
+fetch all column values in a single query without instantiating a single ActiveRecord object:
+
+    posts = Post.where(:archived => false)
+    subjects = posts.collect_column(:subject)
+
+*Implementation note:* In Rails 3.2+, `#collect_column` delegates to [`#pluck`](http://apidock.com/rails/ActiveRecord/Calculations/pluck),
+which can be used for the same effect.
+
+#### Collect unique values in a relation's column
+
+If you only care about *unique* values, use the `:distinct => true` option:
+
+    posts = Post.where(:archived => false)
+    distinct_subjects = posts.collect_column(:subject, :distinct => true)
+
+With this options duplicates are discarded by the database before making their way into Ruby.
+
+*Implementation note:* In Rails 3.2+, the `:distinct` option is implemented with [`#uniq`](http://apidock.com/rails/ActiveRecord/QueryMethods/uniq)
+ which can be used for the same effect.
+
+
+### Retrieve the SQL a relation would produce
+
+Sometimes it is useful to ask a relation which SQL query it would trigger,
+if it was evaluated right now. For this, Edge Rider gives your relations a method
+`#to_sql`:
+
+    # Rails 2 scope
+    Post.scoped(:conditions => { :id => [1, 2] }).to_sql 
+    # => SELECT `posts`.* FROM `posts` WHERE `posts.id` IN (1, 2)
+
+    # Rails 3 relation
+    Post.where(:id => [1, 2]).to_sql 
+    # => SELECT `posts`.* FROM `posts` WHERE `posts.id` IN (1, 2)
+
+*Implementation note*: Rails 3+ implements `#to_sql`. Edge Rider backports this method to Rails 2 so you can use it
+regardless of your Rails version.
+
+
+### Simplify a complex relation for better chainability
+
+In theory you can take any relation and extend it with additional joins or conditions.
+We call this *chaining** relations.
+
+In practice chaining becomes problematic as relation chains grow more complex.
+In particular having JOINs in your relation will reduce the relations's ability to be chained with additional JOINs
+without crashes or side effects. This is because ActiveRecord doesn't really "understand" your relation chain, it only
+mashes together strings that mostly happen to look like a MySQL query in the end.
+
+Edge Rider gives your relations a new method `#to_id_query`:
+
+    Site.joins(:user).where(:users => { :name => 'Bruce' }).to_id_query
+
+`#to_id_query` will immediately run an SQL query where it collects all the IDs that match your relation:
+
+    SELECT sites.id FROM sites INNER JOIN users WHERE sites.user_id = sites.id AND users.name = 'Bruce'
+
+It now uses these IDs to return a new relation that has **no joins** and a single condition on the `id` column:
+
+    SELECT * FROM sites WHERE sites.user_id IN (3, 17, 103)
+
+
+### Preload associations for loaded ActiveRecords
+
+Sometimes you want to fetch associations for records that you already instantiated, e.g. when it has deeply nested associations.
+
+Edge Rider gives your model classes a method `.preload_associations`. The method can be used to preload associations for loaded objects like this:
+
+    @user = User.find(params[:id])
+    User.preload_associations [@user], { :threads => { :posts => :author }, :messages => :sender }
+
+*Implementation note*: Rails 2.3 and Rails 3.0 already has a method [`.preload_associations`](http://apidock.com/rails/ActiveRecord/AssociationPreload/ClassMethods/preload_associations)
+which Edge Rider merely makes public. Edge Rider ports this method forward to Rails 3.1+.
 
 
 Installation
@@ -17,7 +191,6 @@ In your `Gemfile` say:
 Now run `bundle install` and restart your server.
 
 
-
 Development
 -----------
 

data/lib/edge_rider/preload_associations.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+module EdgeRider
+  module PreloadAssociations
+
+    def preload_associations(*args)
+      ActiveRecord::Associations::Preloader.new(*args).run
+    end
+
+    if ActiveRecord::Base.respond_to?(:preload_associations, true) # Rails 2.3, Rails 3.0
+      ActiveRecord::Base.class_eval do
+        class << self
+          public :preload_associations
+        end
+      end
+    else # Rails 3.2+
+      ActiveRecord::Base.send(:extend, self)
+    end
+
+  end
+end

data/lib/edge_rider/traverse_association.rb

@@ -15,13 +15,13 @@ module EdgeRider
 
         raise NotImplementedError if reflection.options[:conditions].present?
 
-        if reflection.macro == :belongs_to
+        if reflection.macro == :belongs_to # belongs_to
           ids = scope.collect_column(foreign_key, :distinct => true)
           scope = EdgeRider::Util.exclusive_query(reflection.klass, :id => ids)
         elsif reflection.macro == :has_many || reflection.macro == :has_one
-          if reflection.through_reflection
+          if reflection.through_reflection # has_many :through
             scope = scope.traverse_association(reflection.through_reflection.name, reflection.source_reflection.name)
-          else
+          else # has_many or has_one
             ids = scope.collect_ids
             scope = EdgeRider::Util.exclusive_query(reflection.klass, foreign_key => ids)
           end

data/lib/edge_rider/version.rb

@@ -1,3 +1,3 @@
 module EdgeRider
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/edge_rider.rb

@@ -5,6 +5,7 @@ require 'edge_rider/util'
 
 require 'edge_rider/collect_column'
 require 'edge_rider/collect_ids'
+require 'edge_rider/preload_associations'
 require 'edge_rider/traverse_association'
 require 'edge_rider/to_id_query'
 require 'edge_rider/to_sql'

data/spec/shared/spec/edge_rider/preload_associations_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe EdgeRider::PreloadAssociations do
+
+  it 'should preload the given named associations so they are no longer fetched lazily' do
+    forum = Forum.create!
+    topic = Topic.create!(:forum => forum)
+    post = Post.create!(:topic => topic)
+    Forum.preload_associations([forum], :topics => :posts)
+    Topic.should_not_receive(:new)
+    Post.should_not_receive(:new)
+    forum.topics.collect(&:posts)
+  end
+
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: edge_rider
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Henning Koch
@@ -15,7 +15,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-02-11 00:00:00 Z
+date: 2013-02-14 00:00:00 +01:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rails
@@ -50,6 +51,7 @@ files:
 - lib/edge_rider/collect_column.rb
 - lib/edge_rider/collect_ids.rb
 - lib/edge_rider/development.rb
+- lib/edge_rider/preload_associations.rb
 - lib/edge_rider/to_id_query.rb
 - lib/edge_rider/to_sql.rb
 - lib/edge_rider/traverse_association.rb
@@ -118,10 +120,12 @@ files:
 - spec/shared/app_root/db/migrate/001_create_test_tables.rb
 - spec/shared/spec/edge_rider/collect_column_spec.rb
 - spec/shared/spec/edge_rider/collect_ids_spec.rb
+- spec/shared/spec/edge_rider/preload_associations_spec.rb
 - spec/shared/spec/edge_rider/to_id_query_spec.rb
 - spec/shared/spec/edge_rider/to_sql_spec.rb
 - spec/shared/spec/edge_rider/traverse_association_spec.rb
 - spec/shared/spec/edge_rider/util_spec.rb
+has_rdoc: true
 homepage: https://github.com/makandra/edge_rider
 licenses: []
 
@@ -151,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.3.9.5
 signing_key: 
 specification_version: 3
 summary: Power tools for ActiveRecord relations (scopes)