eager_record 0.0.1

data/History.txt

@@ -0,0 +1,2 @@
+== 0.0.1 2010-05-03
+* Initial release

data/README.rdoc

@@ -0,0 +1,71 @@
+= EagerRecord
+
+Never pass the `:include` option to `find` again.
+
+EagerRecord is a simple extension to ActiveRecord that automates the process
+of preloading associations in a result set. Each time ActiveRecord loads a
+collection of more than one record out of the database, a reference to the
+collection is stored in each record. Then, when you first access an association
+on one of those records; EagerRecord automatically preloads that association for
+all of the records in the collection.
+
+== Basic Usage
+
+There isn't really any usage; just install the gem and add it as a dependency.
+Whereas before you might write:
+
+  Comment.all(:include => :user).each { |comment| puts comment.user }
+
+Now you get the same effect with:
+
+  Comment.all.each { |comment| puts comment.user }
+
+In the first iteration of that loop, all the comments' users are loaded in a
+single SQL query.
+
+== Scoped Preloading
+
+It isn't enabled by default, but EagerRecord has experimental support for
+"scoped preloading". If you turn it on, EagerRecord will perform preloading
+on scoped associations in the same way that it does so for normal ones. For
+instance, let's say you've got a `:ham` named scope for your `Comment` class:
+
+  Post.all.each { |post| puts post.comments.ham.inspect }
+
+In the first iteration of this loop, EagerRecord will preload all of the ham
+comments for all of the posts in the collection; the above code will only
+generate two SQL queries. A couple of caveats:
+
+* This only works for normal `has_many` associations right now. I could add
+  support for other collection types in the future.
+* The code that does this is considerably more invasive in ActiveRecord's
+  internals than the regular eager preloading code. It basically has to trick
+  ActiveRecord into thinking that there is an association collection defined
+  on your model that doesn't actually exist, and then tell it to preload that
+  association. There are a couple of tests; so I know it basically works, but
+  beware that your mileage may vary. Because of this, you have to explicitly
+  tell eager record you want to use this feature (put this line in a file in
+  `config/initializers`:
+
+  EagerRecord.use_scoped_preload = true
+
+=== Does it work with all association types?
+
+The test suite covers just about all of them; if you find one that doesn't work,
+please file an issue.
+
+=== Do I need to make any changes to my code?
+
+EagerRecord doesn't add any new methods to ActiveRecord, so you don't need to
+interact with it directly. However, you might want to make adjustments to your
+code to encourage preloading to happen at the earliest possible point. In
+particular, if you're using `size` or `first` or `last`, on a collection,
+but then later on also working with all the members of that collection, you're
+better off calling `to_a` at the beginning so that preloading happens and
+ActiveRecord doesn't make extra SQL queries.
+
+== This is free software.
+
+The author(s) of this software relinqiush all copyright on it to the maximum
+extent permitted by law. Anyone is free to copy, distribute, mangle, sell,
+improve, destroy, heckle, hate, or love this software with no restrictions.

data/lib/eager_record/version.rb

@@ -0,0 +1,3 @@
+module EagerRecord
+  VERSION = '0.0.1'
+end

data/lib/eager_record.rb

@@ -0,0 +1,180 @@
+require 'rubygems'
+require 'active_record'
+require 'digest'
+
+module EagerRecord
+  autoload :VERSION, File.join(File.dirname(__FILE__), 'eager_record', 'version')
+
+  TEMPORARY_SCOPED_PRELOAD_ASSOCIATION = :"_temporary_association_for_scoped_preloading"
+
+  class <<self
+    def install
+      ActiveRecord::Base.module_eval do
+        extend(EagerRecord::BaseExtensions::ClassMethods)
+        include(EagerRecord::BaseExtensions::InstanceMethods)
+      end
+      ActiveRecord::Associations::AssociationProxy.module_eval { include(EagerRecord::AssociationProxyExtensions) }
+      ActiveRecord::Associations::AssociationCollection.module_eval { include(EagerRecord::AssociationCollectionExtensions) }
+      ActiveRecord::Associations::HasManyAssociation.module_eval { include(EagerRecord::HasManyAssociationExtensions) }
+    end
+
+    def use_scoped_preload=(flag)
+      @use_scoped_preload = flag
+    end
+
+    def use_scoped_preload?
+      !!@use_scoped_preload
+    end
+  end
+
+  module BaseExtensions
+    module ClassMethods
+      def self.extended(base)
+        (class <<base; self; end).module_eval do
+          alias_method_chain :find_by_sql, :eager_preloading
+        end
+      end
+
+      def find_by_sql_with_eager_preloading(*args)
+        collection = find_by_sql_without_eager_preloading(*args)
+        grouped_collections = collection.group_by { |record| record.class }
+        grouped_collections.values.each do |grouped_collection|
+          if grouped_collection.length > 1
+            grouped_collection.each do |record|
+              record.instance_variable_set(:@originating_collection, grouped_collection)
+            end
+          end
+        end
+        collection
+      end
+    end
+
+    module InstanceMethods
+      def self.included(base)
+        base.has_many TEMPORARY_SCOPED_PRELOAD_ASSOCIATION, :readonly => true
+      end
+
+      private
+
+      def scoped_preloaded_associations
+        @scoped_preloaded_associations ||= Hash.new { |h, k| h[k] = {}}
+      end
+
+      def scoped_preloaded_associations_for(association_name)
+        scoped_preloaded_associations[association_name.to_sym]
+      end
+    end
+  end
+
+  module AssociationProxyExtensions
+
+    def self.included(base)
+      base.module_eval do
+        alias_method_chain :load_target, :eager_preloading
+      end
+    end
+
+    def load_target_with_eager_preloading
+      return nil unless defined?(@loaded)
+
+      if !loaded? and (!@owner.new_record? || foreign_key_present)
+        if originating_collection = @owner.instance_variable_get(:@originating_collection)
+          association_name = @reflection.name
+          @owner.class.__send__(:preload_associations, originating_collection, association_name)
+          return @target if loaded?
+        end
+      end
+      load_target_without_eager_preloading
+    end
+  end
+
+  module AssociationCollectionExtensions
+    def self.included(base)
+      base.module_eval do
+        alias_method_chain :load_target, :eager_preloading
+        alias_method_chain :find, :eager_preloading
+      end
+    end
+
+    def load_target_with_eager_preloading
+      if !@owner.new_record? || foreign_key_present
+        if !loaded?
+          if originating_collection = @owner.instance_variable_get(:@originating_collection)
+            @owner.class.__send__(:preload_associations, originating_collection, @reflection.name)
+            return target if loaded?
+          end
+        end
+      end
+      load_target_without_eager_preloading
+    end
+
+    # 
+    # Because of some likely unintentional plumbing in the scoping/association
+    # delegation chain, current_scoped_methods returns an association proxy's
+    # scope when called on the association collection. This means that, among
+    # other things, a named scope called on an association collection will
+    # duplicate the association collection's SQL restriction.
+    #
+    def current_scoped_methods
+      @reflection.klass.__send__(:current_scoped_methods)
+    end
+
+    def find_with_eager_preloading(*args)
+      if EagerRecord.use_scoped_preload? && originating_collection = @owner.instance_variable_get(:@originating_collection)
+        find_using_scoped_preload(originating_collection, *args)
+      else
+        find_without_eager_preloading(*args)
+      end
+    end
+
+    private
+
+    # 
+    # Subclasses can override this
+    #
+    def find_using_scoped_preload(originating_collection, *args)
+      find_without_eager_preloading(*args)
+    end
+  end
+
+  module HasManyAssociationExtensions
+    def find_using_scoped_preload(originating_collection, *args)
+      options = args.extract_options!
+      reflection_name = @reflection.name
+      current_scope = 
+        if current_scoped_methods && current_scoped_methods[:find] #XXX regression test
+          @reflection.options.merge(current_scoped_methods[:find])
+        else
+          @reflection.options
+        end
+      owner_class = @owner.class
+      reflection_class = @reflection.klass
+      scope_key = current_scope.inspect
+      if preloaded_association = @owner.__send__(:scoped_preloaded_associations_for, reflection_name)[scope_key]
+        return preloaded_association
+      end
+      reflection = owner_class.__send__(
+        :create_has_many_reflection,
+        TEMPORARY_SCOPED_PRELOAD_ASSOCIATION,
+        current_scope.merge(
+          :class_name => reflection_class.name,
+          :readonly => true
+      )
+      )
+      originating_collection.each do |record|
+        association = ActiveRecord::Associations::HasManyAssociation.new(record, reflection)
+        record.__send__(:association_instance_set, TEMPORARY_SCOPED_PRELOAD_ASSOCIATION, association)
+      end
+      owner_class.__send__(:preload_has_many_association, originating_collection, reflection)
+      originating_collection.each do |record|
+        record.instance_eval do
+          @scoped_preloaded_associations ||= Hash.new { |h, k| h[k] = {} }
+          @scoped_preloaded_associations[reflection_name][scope_key] =
+            association_instance_get(TEMPORARY_SCOPED_PRELOAD_ASSOCIATION)
+          association_instance_set(TEMPORARY_SCOPED_PRELOAD_ASSOCIATION, nil)
+        end
+      end
+      @owner.__send__(:scoped_preloaded_associations_for, reflection_name)[scope_key]
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: eager_record
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Mat Brown
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-03 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: EagerRecord extends ActiveRecord to automate association preloading. Each time a collection of more than one record is loaded from the database, each record remembers the collection that it is part of; then when one of those records has an association accessed, EagerRecord triggers a preload_associations for all the records in the originating collection. Never worry about that :include option again!
+email: mat@patch.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/eager_record.rb
+- lib/eager_record/version.rb
+- README.rdoc
+- History.txt
+has_rdoc: true
+homepage: http://github.com/outoftime/eager_record
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: eager_record
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Automatic association preloading for ActiveRecord collections.
+test_files: []
+