activerecord 4.2.0 → 6.0.0

data/lib/active_record/associations/collection_proxy.rb

@@ -1,10 +1,9 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   module Associations
-    # Association proxies in Active Record are middlemen between the object that
-    # holds the association, known as the <tt>@owner</tt>, and the actual associated
-    # object, known as the <tt>@target</tt>. The kind of association any proxy is
-    # about is available in <tt>@reflection</tt>. That's an instance of the class
-    # ActiveRecord::Reflection::AssociationReflection.
+    # Collection proxies in Active Record are middlemen between an
+    # <tt>association</tt>, and its <tt>target</tt> result set.
     #
     # For example, given
     #
@@ -14,26 +13,26 @@ module ActiveRecord
     #
     #   blog = Blog.first
     #
-    # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
-    # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
-    # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
+    # The collection proxy returned by <tt>blog.posts</tt> is built from a
+    # <tt>:has_many</tt> <tt>association</tt>, and delegates to a collection
+    # of posts as the <tt>target</tt>.
     #
-    # This class delegates unknown methods to <tt>@target</tt> via
-    # <tt>method_missing</tt>.
+    # This class delegates unknown methods to the <tt>association</tt>'s
+    # relation class via a delegate cache.
     #
-    # The <tt>@target</tt> object is not \loaded until needed. For example,
+    # The <tt>target</tt> result set is not loaded until needed. For example,
     #
     #   blog.posts.count
     #
     # is computed directly through SQL and does not trigger by itself the
     # instantiation of the actual post records.
     class CollectionProxy < Relation
-      delegate(*(ActiveRecord::Calculations.public_instance_methods - [:count]), to: :scope)
-
       def initialize(klass, association) #:nodoc:
         @association = association
-        super klass, klass.arel_table
-        merge! association.scope(nullify: false)
+        super klass
+
+        extensions = association.extensions
+        extend(*extensions) if extensions.any?
       end
 
       def target
@@ -53,6 +52,12 @@ module ActiveRecord
         @association.loaded?
       end
 
+      ##
+      # :method: select
+      #
+      # :call-seq:
+      #   select(*fields, &block)
+      #
       # Works in two ways.
       #
       # *First:* Specify a subset of fields to be selected from the result set.
@@ -75,7 +80,7 @@ module ActiveRecord
       #   #      #<Pet id: nil, name: "Choo-Choo">
       #   #    ]
       #
-      #   person.pets.select(:id, :name )
+      #   person.pets.select(:id, :name)
       #   # => [
       #   #      #<Pet id: 1, name: "Fancy-Fancy">,
       #   #      #<Pet id: 2, name: "Spook">,
@@ -100,18 +105,9 @@ module ActiveRecord
       #   #      #<Pet id: 2, name: "Spook", person_id: 1>,
       #   #      #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
-      #
-      #   person.pets.select(:name) { |pet| pet.name =~ /oo/ }
-      #   # => [
-      #   #      #<Pet id: 2, name: "Spook">,
-      #   #      #<Pet id: 3, name: "Choo-Choo">
-      #   #    ]
-      def select(*fields, &block)
-        @association.select(*fields, &block)
-      end
 
       # Finds an object in the collection responding to the +id+. Uses the same
-      # rules as <tt>ActiveRecord::Base.find</tt>. Returns <tt>ActiveRecord::RecordNotFound</tt>
+      # rules as ActiveRecord::Base.find. Returns ActiveRecord::RecordNotFound
       # error if the object cannot be found.
       #
       #   class Person < ActiveRecord::Base
@@ -126,7 +122,7 @@ module ActiveRecord
       #   #    ]
       #
       #   person.pets.find(1) # => #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>
-      #   person.pets.find(4) # => ActiveRecord::RecordNotFound: Couldn't find Pet with id=4
+      #   person.pets.find(4) # => ActiveRecord::RecordNotFound: Couldn't find Pet with 'id'=4
       #
       #   person.pets.find(2) { |pet| pet.name.downcase! }
       #   # => #<Pet id: 2, name: "fancy-fancy", person_id: 1>
@@ -136,10 +132,17 @@ module ActiveRecord
       #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
-      def find(*args, &block)
-        @association.find(*args, &block)
+      def find(*args)
+        return super if block_given?
+        @association.find(*args)
       end
 
+      ##
+      # :method: first
+      #
+      # :call-seq:
+      #   first(limit = nil)
+      #
       # Returns the first record, or the first +n+ records, from the collection.
       # If the collection is empty, the first form returns +nil+, and the second
       # form returns an empty array.
@@ -166,35 +169,63 @@ module ActiveRecord
       #   another_person_without.pets          # => []
       #   another_person_without.pets.first    # => nil
       #   another_person_without.pets.first(3) # => []
-      def first(*args)
-        @association.first(*args)
-      end
 
-      # Same as +first+ except returns only the second record.
-      def second(*args)
-        @association.second(*args)
-      end
+      ##
+      # :method: second
+      #
+      # :call-seq:
+      #   second()
+      #
+      # Same as #first except returns only the second record.
 
-      # Same as +first+ except returns only the third record.
-      def third(*args)
-        @association.third(*args)
-      end
+      ##
+      # :method: third
+      #
+      # :call-seq:
+      #   third()
+      #
+      # Same as #first except returns only the third record.
 
-      # Same as +first+ except returns only the fourth record.
-      def fourth(*args)
-        @association.fourth(*args)
-      end
+      ##
+      # :method: fourth
+      #
+      # :call-seq:
+      #   fourth()
+      #
+      # Same as #first except returns only the fourth record.
 
-      # Same as +first+ except returns only the fifth record.
-      def fifth(*args)
-        @association.fifth(*args)
-      end
+      ##
+      # :method: fifth
+      #
+      # :call-seq:
+      #   fifth()
+      #
+      # Same as #first except returns only the fifth record.
 
-      # Same as +first+ except returns only the forty second record.
+      ##
+      # :method: forty_two
+      #
+      # :call-seq:
+      #   forty_two()
+      #
+      # Same as #first except returns only the forty second record.
       # Also known as accessing "the reddit".
-      def forty_two(*args)
-        @association.forty_two(*args)
-      end
+
+      ##
+      # :method: third_to_last
+      #
+      # :call-seq:
+      #   third_to_last()
+      #
+      # Same as #first except returns only the third-to-last record.
+
+      ##
+      # :method: second_to_last
+      #
+      # :call-seq:
+      #   second_to_last()
+      #
+      # Same as #first except returns only the second-to-last record.
 
       # Returns the last record, or the last +n+ records, from the collection.
       # If the collection is empty, the first form returns +nil+, and the second
@@ -222,8 +253,39 @@ module ActiveRecord
       #   another_person_without.pets         # => []
       #   another_person_without.pets.last    # => nil
       #   another_person_without.pets.last(3) # => []
-      def last(*args)
-        @association.last(*args)
+      def last(limit = nil)
+        load_target if find_from_target?
+        super
+      end
+
+      # Gives a record (or N records if a parameter is supplied) from the collection
+      # using the same rules as <tt>ActiveRecord::Base.take</tt>.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.take # => #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>
+      #
+      #   person.pets.take(2)
+      #   # => [
+      #   #      #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>
+      #   #    ]
+      #
+      #   another_person_without.pets         # => []
+      #   another_person_without.pets.take    # => nil
+      #   another_person_without.pets.take(2) # => []
+      def take(limit = nil)
+        load_target if find_from_target?
+        super
       end
 
       # Returns a new object of the collection type that has been instantiated
@@ -285,7 +347,7 @@ module ActiveRecord
         @association.create(attributes, &block)
       end
 
-      # Like +create+, except that if the record is invalid, raises an exception.
+      # Like #create, except that if the record is invalid, raises an exception.
       #
       #   class Person
       #     has_many :pets
@@ -301,34 +363,6 @@ module ActiveRecord
         @association.create!(attributes, &block)
       end
 
-      # Add one or more records to the collection by setting their foreign keys
-      # to the association's primary key. Since << flattens its argument list and
-      # inserts each record, +push+ and +concat+ behave identically. Returns +self+
-      # so method calls may be chained.
-      #
-      #   class Person < ActiveRecord::Base
-      #     has_many :pets
-      #   end
-      #
-      #   person.pets.size # => 0
-      #   person.pets.concat(Pet.new(name: 'Fancy-Fancy'))
-      #   person.pets.concat(Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo'))
-      #   person.pets.size # => 3
-      #
-      #   person.id # => 1
-      #   person.pets
-      #   # => [
-      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
-      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
-      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
-      #   #    ]
-      #
-      #   person.pets.concat([Pet.new(name: 'Brain'), Pet.new(name: 'Benny')])
-      #   person.pets.size # => 5
-      def concat(*records)
-        @association.concat(*records)
-      end
-
       # Replaces this collection with +other_array+. This will perform a diff
       # and delete/add only records that have changed.
       #
@@ -359,7 +393,7 @@ module ActiveRecord
       # specified by the +:dependent+ option. If no +:dependent+ option is given,
       # then it will follow the default strategy.
       #
-      # For +has_many :through+ associations, the default deletion strategy is
+      # For <tt>has_many :through</tt> associations, the default deletion strategy is
       # +:delete_all+.
       #
       # For +has_many+ associations, the default deletion strategy is +:nullify+.
@@ -394,7 +428,7 @@ module ActiveRecord
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: nil>
       #   #    ]
       #
-      # Both +has_many+ and +has_many :through+ dependencies default to the
+      # Both +has_many+ and <tt>has_many :through</tt> dependencies default to the
       # +:delete_all+ strategy if the +:dependent+ option is set to +:destroy+.
       # Records are not instantiated and callbacks will not be fired.
       #
@@ -413,7 +447,7 @@ module ActiveRecord
       #   person.pets.delete_all
       #
       #   Pet.find(1, 2, 3)
-      #   # => ActiveRecord::RecordNotFound
+      #   # => ActiveRecord::RecordNotFound: Couldn't find all Pets with 'id': (1, 2, 3)
       #
       # If it is set to <tt>:delete_all</tt>, all the objects are deleted
       # *without* calling their +destroy+ method.
@@ -433,9 +467,9 @@ module ActiveRecord
       #   person.pets.delete_all
       #
       #   Pet.find(1, 2, 3)
-      #   # => ActiveRecord::RecordNotFound
+      #   # => ActiveRecord::RecordNotFound: Couldn't find all Pets with 'id': (1, 2, 3)
       def delete_all(dependent = nil)
-        @association.delete_all(dependent)
+        @association.delete_all(dependent).tap { reset_scope }
       end
 
       # Deletes the records of the collection directly from the database
@@ -462,18 +496,19 @@ module ActiveRecord
       #
       #   Pet.find(1) # => Couldn't find Pet with id=1
       def destroy_all
-        @association.destroy_all
+        @association.destroy_all.tap { reset_scope }
       end
 
-      # Deletes the +records+ supplied and removes them from the collection. For
-      # +has_many+ associations, the deletion is done according to the strategy
-      # specified by the <tt>:dependent</tt> option. Returns an array with the
+      # Deletes the +records+ supplied from the collection according to the strategy
+      # specified by the +:dependent+ option. If no +:dependent+ option is given,
+      # then it will follow the default strategy. Returns an array with the
       # deleted records.
       #
-      # If no <tt>:dependent</tt> option is given, then it will follow the default
-      # strategy. The default strategy is <tt>:nullify</tt>. This sets the foreign
-      # keys to <tt>NULL</tt>. For, +has_many+ <tt>:through</tt>, the default
-      # strategy is +delete_all+.
+      # For <tt>has_many :through</tt> associations, the default deletion strategy is
+      # +:delete_all+.
+      #
+      # For +has_many+ associations, the default deletion strategy is +:nullify+.
+      # This sets the foreign keys to +NULL+.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets # dependent: :nullify option by default
@@ -526,7 +561,7 @@ module ActiveRecord
       #   # => [#<Pet id: 2, name: "Spook", person_id: 1>]
       #
       #   Pet.find(1, 3)
-      #   # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (1, 3)
+      #   # => ActiveRecord::RecordNotFound: Couldn't find all Pets with 'id': (1, 3)
       #
       # If it is set to <tt>:delete_all</tt>, all the +records+ are deleted
       # *without* calling their +destroy+ method.
@@ -554,9 +589,9 @@ module ActiveRecord
       #   #    ]
       #
       #   Pet.find(1)
-      #   # => ActiveRecord::RecordNotFound: Couldn't find Pet with id=1
+      #   # => ActiveRecord::RecordNotFound: Couldn't find Pet with 'id'=1
       #
-      # You can pass +Fixnum+ or +String+ values, it finds the records
+      # You can pass +Integer+ or +String+ values, it finds the records
       # responding to the +id+ and executes delete on them.
       #
       #   class Person < ActiveRecord::Base
@@ -580,7 +615,7 @@ module ActiveRecord
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
       def delete(*records)
-        @association.delete(*records)
+        @association.delete(*records).tap { reset_scope }
       end
 
       # Destroys the +records+ supplied and removes them from the collection.
@@ -618,9 +653,9 @@ module ActiveRecord
       #   person.pets.size  # => 0
       #   person.pets       # => []
       #
-      #   Pet.find(1, 2, 3) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (1, 2, 3)
+      #   Pet.find(1, 2, 3) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with 'id': (1, 2, 3)
       #
-      # You can pass +Fixnum+ or +String+ values, it finds the records
+      # You can pass +Integer+ or +String+ values, it finds the records
       # responding to the +id+ and then deletes them from the database.
       #
       #   person.pets.size # => 3
@@ -650,11 +685,17 @@ module ActiveRecord
       #   person.pets.size  # => 0
       #   person.pets       # => []
       #
-      #   Pet.find(4, 5, 6) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (4, 5, 6)
+      #   Pet.find(4, 5, 6) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with 'id': (4, 5, 6)
       def destroy(*records)
-        @association.destroy(*records)
+        @association.destroy(*records).tap { reset_scope }
       end
 
+      ##
+      # :method: distinct
+      #
+      # :call-seq:
+      #   distinct(value = true)
+      #
       # Specifies whether the records should be unique or not.
       #
       #   class Person < ActiveRecord::Base
@@ -669,17 +710,35 @@ module ActiveRecord
       #
       #   person.pets.select(:name).distinct
       #   # => [#<Pet name: "Fancy-Fancy">]
-      def distinct
-        @association.distinct
+      #
+      #   person.pets.select(:name).distinct.distinct(false)
+      #   # => [
+      #   #      #<Pet name: "Fancy-Fancy">,
+      #   #      #<Pet name: "Fancy-Fancy">
+      #   #    ]
+
+      #--
+      def calculate(operation, column_name)
+        null_scope? ? scope.calculate(operation, column_name) : super
       end
-      alias uniq distinct
 
-      # Count all records using SQL.
+      def pluck(*column_names)
+        null_scope? ? scope.pluck(*column_names) : super
+      end
+
+      ##
+      # :method: count
+      #
+      # :call-seq:
+      #   count(column_name = nil, &block)
+      #
+      # Count all records.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets
       #   end
       #
+      #   # This will perform the count using SQL.
       #   person.pets.count # => 3
       #   person.pets
       #   # => [
@@ -687,11 +746,11 @@ module ActiveRecord
       #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
-      def count(column_name = nil, options = {})
-        # TODO: Remove options argument as soon we remove support to
-        # activerecord-deprecated_finders.
-        @association.count(column_name, options)
-      end
+      #
+      # Passing a block will select all of a person's pets in SQL and then
+      # perform the count using Ruby.
+      #
+      #   person.pets.count { |pet| pet.name.include?('-') } # => 2
 
       # Returns the size of the collection. If the collection hasn't been loaded,
       # it executes a <tt>SELECT COUNT(*)</tt> query. Else it calls <tt>collection.size</tt>.
@@ -721,6 +780,12 @@ module ActiveRecord
         @association.size
       end
 
+      ##
+      # :method: length
+      #
+      # :call-seq:
+      #   length()
+      #
       # Returns the size of the collection calling +size+ on the target.
       # If the collection has been already loaded, +length+ and +size+ are
       # equivalent. If not and you are going to need the records anyway this
@@ -741,14 +806,11 @@ module ActiveRecord
       #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
-      def length
-        @association.length
-      end
 
       # Returns +true+ if the collection is empty. If the collection has been
       # loaded it is equivalent
       # to <tt>collection.size.zero?</tt>. If the collection has not been loaded,
-      # it is equivalent to <tt>collection.exists?</tt>. If the collection has
+      # it is equivalent to <tt>!collection.exists?</tt>. If the collection has
       # not already been loaded and you are going to fetch the records anyway it
       # is better to check <tt>collection.length.zero?</tt>.
       #
@@ -767,6 +829,12 @@ module ActiveRecord
         @association.empty?
       end
 
+      ##
+      # :method: any?
+      #
+      # :call-seq:
+      #   any?()
+      #
       # Returns +true+ if the collection is not empty.
       #
       #   class Person < ActiveRecord::Base
@@ -777,7 +845,7 @@ module ActiveRecord
       #   person.pets.any?  # => false
       #
       #   person.pets << Pet.new(name: 'Snoop')
-      #   person.pets.count # => 0
+      #   person.pets.count # => 1
       #   person.pets.any?  # => true
       #
       # You can also pass a +block+ to define criteria. The behavior
@@ -796,10 +864,13 @@ module ActiveRecord
       #     pet.group == 'dogs'
       #   end
       #   # => true
-      def any?(&block)
-        @association.any?(&block)
-      end
 
+      ##
+      # :method: many?
+      #
+      # :call-seq:
+      #   many?()
+      #
       # Returns true if the collection has more than one record.
       # Equivalent to <tt>collection.size > 1</tt>.
       #
@@ -834,9 +905,6 @@ module ActiveRecord
       #     pet.group == 'cats'
       #   end
       #   # => true
-      def many?(&block)
-        @association.many?(&block)
-      end
 
       # Returns +true+ if the given +record+ is present in the collection.
       #
@@ -852,27 +920,14 @@ module ActiveRecord
         !!@association.include?(record)
       end
 
-      def arel
-        scope.arel
-      end
-
       def proxy_association
         @association
       end
 
-      # We don't want this object to be put on the scoping stack, because
-      # that could create an infinite loop where we call an @association
-      # method, which gets the current scope, which is this object, which
-      # delegates to @association, and so on.
-      def scoping
-        @association.scope.scoping { yield }
-      end
-
       # Returns a <tt>Relation</tt> object for the records in this association
       def scope
-        @association.scope
+        @scope ||= @association.scope
       end
-      alias spawn scope
 
       # Equivalent to <tt>Array#==</tt>. Returns +true+ if the two arrays
       # contain the same number of elements and if each element is equal
@@ -902,6 +957,12 @@ module ActiveRecord
         load_target == other
       end
 
+      ##
+      # :method: to_ary
+      #
+      # :call-seq:
+      #   to_ary()
+      #
       # Returns a new array of objects from the collection. If the collection
       # hasn't been loaded, it fetches the records from the database.
       #
@@ -935,14 +996,15 @@ module ActiveRecord
       #   #       #<Pet id: 5, name: "Brain", person_id: 1>,
       #   #       #<Pet id: 6, name: "Boss",  person_id: 1>
       #   #    ]
-      def to_ary
-        load_target.dup
+
+      def records # :nodoc:
+        load_target
       end
-      alias_method :to_a, :to_ary
 
       # Adds one or more +records+ to the collection by setting their foreign keys
-      # to the association's primary key. Returns +self+, so several appends may be
-      # chained together.
+      # to the association's primary key. Since <tt><<</tt> flattens its argument list and
+      # inserts each record, +push+ and +concat+ behave identically. Returns +self+
+      # so several appends may be chained together.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets
@@ -965,21 +1027,24 @@ module ActiveRecord
       end
       alias_method :push, :<<
       alias_method :append, :<<
+      alias_method :concat, :<<
 
-      def prepend(*args)
-        raise NoMethodError, "prepend on association is not defined. Please use << or append"
+      def prepend(*args) # :nodoc:
+        raise NoMethodError, "prepend on association is not defined. Please use <<, push or append"
       end
 
       # Equivalent to +delete_all+. The difference is that returns +self+, instead
       # of an array with the deleted objects, so methods can be chained. See
       # +delete_all+ for more information.
+      # Note that because +delete_all+ removes records by directly
+      # running an SQL query into the database, the +updated_at+ column of
+      # the object is not changed.
       def clear
         delete_all
         self
       end
 
       # Reloads the collection from the database. Returns +self+.
-      # Equivalent to <tt>collection(true)</tt>.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets
@@ -993,12 +1058,9 @@ module ActiveRecord
       #
       #   person.pets.reload # fetches pets from the database
       #   # => [#<Pet id: 1, name: "Snoop", group: "dogs", person_id: 1>]
-      #
-      #   person.pets(true)  # fetches pets from the database
-      #   # => [#<Pet id: 1, name: "Snoop", group: "dogs", person_id: 1>]
       def reload
-        proxy_association.reload
-        self
+        proxy_association.reload(true)
+        reset_scope
       end
 
       # Unloads the association. Returns +self+.
@@ -1020,8 +1082,47 @@ module ActiveRecord
       def reset
         proxy_association.reset
         proxy_association.reset_scope
+        reset_scope
+      end
+
+      def reset_scope # :nodoc:
+        @offsets = {}
+        @scope = nil
         self
       end
+
+      delegate_methods = [
+        QueryMethods,
+        SpawnMethods,
+      ].flat_map { |klass|
+        klass.public_instance_methods(false)
+      } - self.public_instance_methods(false) - [:select] + [:scoping, :values]
+
+      delegate(*delegate_methods, to: :scope)
+
+      private
+
+        def find_nth_with_limit(index, limit)
+          load_target if find_from_target?
+          super
+        end
+
+        def find_nth_from_last(index)
+          load_target if find_from_target?
+          super
+        end
+
+        def null_scope?
+          @association.null_scope?
+        end
+
+        def find_from_target?
+          @association.find_from_target?
+        end
+
+        def exec_queries
+          load_target
+        end
     end
   end
 end