mongoid 7.0.12 → 7.3.3

data/lib/mongoid/association/options.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 module Mongoid
   module Association
 
@@ -21,7 +24,7 @@ module Mongoid
         @options[:dependent]
       end
 
-      # The custom sorting options on the relation.
+      # The custom sorting options on the association.
       #
       # @return [ Criteria::Queryable::Key ] The custom sorting options.
       #
@@ -48,16 +51,16 @@ module Mongoid
         !!@options[:autobuild]
       end
 
-      # Is the relation cyclic.
+      # Is the association cyclic.
       #
-      # @return [ true, false ] Whether the relation is cyclic.
+      # @return [ true, false ] Whether the association is cyclic.
       #
       # @since 7.0
       def cyclic?
         !!@options[:cyclic]
       end
 
-      # The name the owning object uses to refer to this relation.
+      # The name the owning object uses to refer to this association.
       #
       # @return [ String ] The inverse_of option.
       #
@@ -103,7 +106,7 @@ module Mongoid
       # @since 7.0
       def polymorphic?; false; end
 
-      # Whether the relation has callbacks cascaded down from the parent.
+      # Whether the association has callbacks cascaded down from the parent.
       #
       # @return [ true, false ] Whether callbacks are cascaded.
       #
@@ -149,4 +152,4 @@ module Mongoid
       end
     end
   end
-end
+end

data/lib/mongoid/association/proxy.rb

@@ -1,29 +1,46 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 require "mongoid/association/marshalable"
 
 module Mongoid
   module Association
 
-    # This class is the superclass for all relation proxy objects, and contains
-    # common behaviour for all of them.
+    # This class is the superclass for all association proxy objects, and contains
+    # common behavior for all of them.
     class Proxy
+      extend Forwardable
+
       alias :extend_proxy :extend
 
       # We undefine most methods to get them sent through to the target.
       instance_methods.each do |method|
         undef_method(method) unless
-          method =~ /\A(__.*|send|object_id|equal\?|respond_to\?|tap|public_send|extend_proxy|extend_proxies)\z/
+          method =~ /\A(?:__.*|send|object_id|equal\?|respond_to\?|respond_to_missing\?|tap|public_send|extend_proxy|extend_proxies)\z/
       end
 
       include Threaded::Lifecycle
       include Marshalable
 
-      attr_accessor :_base, :_association, :_target
+      # Model instance for the base of the association.
+      #
+      # For example, if a Post embeds_many Comments, _base is a particular
+      # instance of the Post model.
+      attr_accessor :_base
+
+      attr_accessor :_association
+
+      # Model instance for one to one associations, or array of model instances
+      # for one to many associations, for the target of the association.
+      #
+      # For example, if a Post embeds_many Comments, _target is an array of
+      # Comment models embedded in a particular Post.
+      attr_accessor :_target
 
       # Backwards compatibility with Mongoid beta releases.
-      delegate :foreign_key, :inverse_foreign_key, to: :_association
-      delegate :bind_one, :unbind_one, to: :binding
-      delegate :collection_name, to: :_base
+      def_delegators :_association, :foreign_key, :inverse_foreign_key
+      def_delegators :binding, :bind_one, :unbind_one
+      def_delegator :_base, :collection_name
 
       # Convenience for setting the target and the association metadata properties since
       # all proxies will need to do this.
@@ -52,17 +69,17 @@ module Mongoid
       # @example Get the class.
       #   proxy.klass
       #
-      # @return [ Class ] The relation class.
+      # @return [ Class ] The association class.
       #
       # @since 3.0.15
       def klass
         _association ? _association.klass : nil
       end
 
-      # Resets the criteria inside the relation proxy. Used by many to many
-      # relations to keep the underlying ids array in sync.
+      # Resets the criteria inside the association proxy. Used by many to many
+      # associations to keep the underlying ids array in sync.
       #
-      # @example Reset the relation criteria.
+      # @example Reset the association criteria.
       #   person.preferences.reset_relation_criteria
       #
       # @since 3.0.14
@@ -70,7 +87,7 @@ module Mongoid
         _target.reset_unloaded(criteria)
       end
 
-      # The default substitutable object for a relation proxy is the clone of
+      # The default substitutable object for an association proxy is the clone of
       # the target.
       #
       # @example Get the substitutable.
@@ -116,10 +133,15 @@ module Mongoid
       # @param [ String, Symbol ] name The name of the method.
       # @param [ Array ] args The arguments passed to the method.
       #
-      def method_missing(name, *args, &block)
+      ruby2_keywords def method_missing(name, *args, &block)
         _target.send(name, *args, &block)
       end
 
+      # @api private
+      ruby2_keywords def respond_to_missing?(name, *args)
+        _target.respond_to?(name, *args)
+      end
+
       # When the base document illegally references an embedded document this
       # error will get raised.
       #
@@ -134,7 +156,7 @@ module Mongoid
       end
 
       # When the base is not yet saved and the user calls create or create!
-      # on the relation, this error will get raised.
+      # on the association, this error will get raised.
       #
       # @example Raise the error.
       #   relation.raise_unsaved(post)
@@ -168,7 +190,7 @@ module Mongoid
 
       class << self
 
-        # Apply ordering to the criteria if it was defined on the relation.
+        # Apply ordering to the criteria if it was defined on the association.
         #
         # @example Apply the ordering.
         #   Proxy.apply_ordering(criteria, association)

data/lib/mongoid/association/referenced/auto_save.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -33,7 +36,7 @@ module Mongoid
         # Check if there is changes for auto-saving
         #
         # @example Return true if there is changes on self or in
-        #           autosaved relations.
+        #           autosaved associations.
         #   document.changed_for_autosave?
         #
         # @since 3.1.3
@@ -60,8 +63,8 @@ module Mongoid
                 self.before_callback_halted = false
               else
                 __autosaving__ do
-                  if relation = ivar(association.name)
-                    Array(relation).each do |doc|
+                  if assoc_value = ivar(association.name)
+                    Array(assoc_value).each do |doc|
                       doc.with(persistence_context) do |d|
                         d.save
                       end

data/lib/mongoid/association/referenced/belongs_to/binding.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -8,7 +10,7 @@ module Mongoid
         class Binding
           include Bindable
 
-          # Binds the base object to the inverse of the relation. This is so we
+          # Binds the base object to the inverse of the association. This is so we
           # are referenced to the actual objects themselves on both sides.
           #
           # This case sets the association on the inverse object as well as the
@@ -74,7 +76,7 @@ module Mongoid
           # @since 3.0.0
           def check_polymorphic_inverses!(doc)
             inverses = _association.inverses(doc)
-            if inverses.count > 1 && _base.send(_association.foreign_key).nil?
+            if inverses.length > 1 && _base.send(_association.foreign_key).nil?
               raise Errors::InvalidSetPolymorphicRelation.new(
                   _association.name, _base.class.name, _target.class.name
               )

data/lib/mongoid/association/referenced/belongs_to/buildable.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -16,11 +18,12 @@ module Mongoid
           #   relation.build(meta, attrs)
           #
           # @param [ Object ] base The base object.
-          # @param [ Object ] object The object to use to build the relation.
-          # @param [ String ] type The type of the relation.
+          # @param [ Object ] object The object to use to build the association.
+          # @param [ String ] type The type of the association.
+          # @param [ nil ] selected_fields Must be nil.
           #
           # @return [ Document ] A single document.
-          def build(base, object, type = nil)
+          def build(base, object, type = nil, selected_fields = nil)
             return object unless query?(object)
             execute_query(object, type)
           end
@@ -28,7 +31,7 @@ module Mongoid
           private
 
           def execute_query(object, type)
-            query_criteria(object, type).limit(-1).first(id_sort: :none)
+            query_criteria(object, type).limit(1).first(id_sort: :none)
           end
 
           def query_criteria(object, type)

data/lib/mongoid/association/referenced/belongs_to/eager.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -10,8 +12,6 @@ module Mongoid
           private
 
           def preload
-            raise Errors::EagerLoad.new(@association.name) if @association.polymorphic?
-
             @docs.each do |d|
               set_relation(d, nil)
             end
@@ -22,6 +22,44 @@ module Mongoid
             end
           end
 
+          # Retrieves the documents referenced by the association, and
+          # yields each one sequentially to the provided block. If the
+          # association is not polymorphic, all documents are retrieved in
+          # a single query. If the association is polymorphic, one query is
+          # issued per association target class.
+          def each_loaded_document(&block)
+            if @association.polymorphic?
+              keys_by_type_from_docs.each do |type, keys|
+                each_loaded_document_of_class(Object.const_get(type), keys, &block)
+              end
+            else
+              super
+            end
+          end
+
+          # Returns a map from association target class name to foreign key
+          # values for the documents of that association target class,
+          # as referenced by this association.
+          def keys_by_type_from_docs
+            inverse_type_field = @association.inverse_type
+
+            @docs.each_with_object({}) do |doc, keys_by_type|
+              next unless doc.respond_to?(inverse_type_field) && doc.respond_to?(group_by_key)
+              inverse_type_name = doc.send(inverse_type_field)
+              # If a particular document does not have a value for this
+              # association, inverse_type_name will be nil.
+              next if inverse_type_name.nil?
+
+              key_value = doc.send(group_by_key)
+              # If a document has the *_type field set but the corresponding
+              # *_id field not set, the key value here will be nil.
+              next unless key_value
+
+              keys_by_type[inverse_type_name] ||= []
+              keys_by_type[inverse_type_name].push(key_value)
+            end
+          end
+
           def group_by_key
             @association.foreign_key
           end

data/lib/mongoid/association/referenced/belongs_to/proxy.rb

@@ -1,12 +1,14 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class BelongsTo
 
-        # This class handles all behaviour for relations that are either
+        # This class handles all behavior for associations that are either
         # one-to-many or one-to-one, where the foreign key is stored on this side
-        # of the relation and the reference is to document(s) in another
+        # of the association and the reference is to document(s) in another
         # collection.
         class Proxy < Association::One
           include Evolvable
@@ -16,9 +18,9 @@ module Mongoid
           # @example Create the new proxy.
           #   Association::BelongsTo::Proxy.new(game, person, association)
           #
-          # @param [ Document ] base The document this relation hangs off of.
+          # @param [ Document ] base The document this association hangs off of.
           # @param [ Document, Array<Document> ] target The target (parent) of the
-          #   relation.
+          #   association.
           # @param [ Association ] association The association object.
           def initialize(base, target, association)
             init(base, target, association) do
@@ -31,7 +33,7 @@ module Mongoid
           # document by deleting the foreign key and the reference, orphaning
           # the target document in the process.
           #
-          # @example Nullify the relation.
+          # @example Nullify the association.
           #   person.game.nullify
           #
           def nullify
@@ -40,14 +42,14 @@ module Mongoid
           end
 
           # Substitutes the supplied target documents for the existing document
-          # in the relation.
+          # in the association.
           #
-          # @example Substitute the relation.
+          # @example Substitute the association.
           #   name.substitute(new_name)
           #
           # @param [ Document, Array<Document> ] replacement The replacement.
           #
-          # @return [ self, nil ] The relation or nil.
+          # @return [ self, nil ] The association or nil.
           #
           # @since 2.0.0.rc.1
           def substitute(replacement)
@@ -61,7 +63,7 @@ module Mongoid
 
           private
 
-          # Instantiate the binding associated with this relation.
+          # Instantiate the binding associated with this association.
           #
           # @example Get the binding object.
           #   binding([ address ])
@@ -90,12 +92,12 @@ module Mongoid
             _association.build(klass, replacement)
           end
 
-          # Are we able to persist this relation?
+          # Are we able to persist this association?
           #
-          # @example Can we persist the relation?
+          # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the relation is persistable.
+          # @return [ true, false ] If the association is persistable.
           #
           # @since 2.1.0
           def persistable?
@@ -116,10 +118,10 @@ module Mongoid
               Eager.new(association, docs)
             end
 
-            # Returns true if the relation is an embedded one. In this case
+            # Returns true if the association is an embedded one. In this case
             # always false.
             #
-            # @example Is this relation embedded?
+            # @example Is this association embedded?
             #   Association::BelongsTo::Proxy.embedded?
             #
             # @return [ false ] Always false.

data/lib/mongoid/association/referenced/belongs_to.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/referenced/belongs_to/binding'
 require 'mongoid/association/referenced/belongs_to/buildable'
 require 'mongoid/association/referenced/belongs_to/proxy'
@@ -107,7 +110,7 @@ module Mongoid
                              default_foreign_key_field
         end
 
-        # Get the relation proxy class for this association type.
+        # Get the association proxy class for this association type.
         #
         # @return [ Association::BelongsTo::Proxy ] The proxy class.
         #
@@ -125,9 +128,9 @@ module Mongoid
           @polymorphic ||= !!@options[:polymorphic]
         end
 
-        # The name of the field used to store the type of polymorphic relation.
+        # The name of the field used to store the type of polymorphic association.
         #
-        # @return [ String ] The field used to store the type of polymorphic relation.
+        # @return [ String ] The field used to store the type of polymorphic association.
         #
         # @since 7.0
         def inverse_type

data/lib/mongoid/association/referenced/counter_cache.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced

data/lib/mongoid/association/referenced/eager.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -15,7 +17,7 @@ module Mongoid
           #   BelongsTo.new(association, parent_docs)
           #
           # @param [ Array<Association> ] associations Associations to eager load
-          # @param [ Array<Document> ] docs Documents to preload the relations
+          # @param [ Array<Document> ] docs Documents to preload the associations
           #
           # @return [ Base ] The eager load preloader
           #
@@ -28,7 +30,7 @@ module Mongoid
 
           # Run the preloader.
           #
-          # @example Preload the relations into the documents.
+          # @example Preload the associations into the documents.
           #   loader.run
           #
           # @return [ Array ] The list of documents given.
@@ -45,11 +47,11 @@ module Mongoid
 
           protected
 
-          # Preload the current relation.
+          # Preload the current association.
           #
           # This method should be implemented in the subclass
           #
-          # @example Preload the current relation into the documents.
+          # @example Preload the current association into the documents.
           #   loader.preload
           #
           # @since 4.0.0
@@ -57,17 +59,29 @@ module Mongoid
             raise NotImplementedError
           end
 
-          # Run the preloader.
-          #
-          # @example Iterate over the documents loaded for the current relation
-          #   loader.each_loaded_document { |doc| }
+          # Retrieves the documents referenced by the association, and
+          # yields each one sequentially to the provided block. If the
+          # association is not polymorphic, all documents are retrieved in
+          # a single query. If the association is polymorphic, one query is
+          # issued per association target class.
           #
           # @since 4.0.0
-          def each_loaded_document
-            doc_keys = keys_from_docs
-            return @association.klass.none if doc_keys.all?(&:nil?)
+          def each_loaded_document(&block)
+            each_loaded_document_of_class(@association.klass, keys_from_docs, &block)
+          end
 
-            criteria = @association.klass.any_in(key => doc_keys)
+          # Retrieves the documents of the specified class, that have the
+          # foreign key included in the specified list of keys.
+          #
+          # When the documents are retrieved, the set of inclusions applied
+          # is the set of inclusions applied to the host document minus the
+          # association that is being eagerly loaded.
+          private def each_loaded_document_of_class(cls, keys)
+            # Note: keys should not include nil elements.
+            # Upstream code is responsible for eliminating nils from keys.
+            return cls.none if keys.empty?
+
+            criteria = cls.any_in(key => keys)
             criteria.inclusions = criteria.inclusions - [@association]
             criteria.each do |doc|
               yield doc
@@ -91,6 +105,9 @@ module Mongoid
 
           # Return a hash with the current documents grouped by key.
           #
+          # Documents that do not have a value for the association being loaded
+          # are not returned.
+          #
           # @example Return a hash with the current documents grouped by key.
           #   loader.grouped_docs
           #
@@ -100,10 +117,15 @@ module Mongoid
           def grouped_docs
             @grouped_docs[@association.name] ||= @docs.group_by do |doc|
               doc.send(group_by_key) if doc.respond_to?(group_by_key)
+            end.reject do |k, v|
+              k.nil?
             end
           end
 
-          # Group the documents and return the keys
+          # Group the documents and return the keys.
+          #
+          # This method omits nil keys (i.e. keys from documents that do not
+          # have a value for the association being loaded).
           #
           # @example
           #   loader.keys_from_docs
@@ -131,10 +153,10 @@ module Mongoid
 
           # Set the pre-loaded document into its parent.
           #
-          # @example Set docs into parent using the current relation name.
+          # @example Set docs into parent using the current association name.
           #   loader.set_relation(doc, docs)
           #
-          # @param [ Document ] doc The object to set the relation on
+          # @param [ Document ] doc The object to set the association on
           # @param [ Document, Array ] element to set into the parent
           #
           # @since 4.0.0

data/lib/mongoid/association/referenced/has_and_belongs_to_many/binding.rb

@@ -1,14 +1,16 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasAndBelongsToMany
 
-        # Binding class for all has_and_belongs_to_many relations.
+        # Binding class for all has_and_belongs_to_many associations.
         class Binding
           include Bindable
 
-          # Binds a single document with the inverse relation. Used
+          # Binds a single document with the inverse association. Used
           # specifically when appending to the proxy.
           #
           # @example Bind one document.
@@ -53,11 +55,15 @@ module Mongoid
 
           # Find the inverse id referenced by inverse_keys
           def inverse_record_id(doc)
-            inverse_association = determine_inverse_association(doc)
-            if inverse_association
-              _base.__send__(inverse_association.primary_key)
+            if pk = _association.options[:inverse_primary_key]
+              _base.send(pk)
             else
-              _base._id
+              inverse_association = determine_inverse_association(doc)
+              if inverse_association
+                _base.__send__(inverse_association.primary_key)
+              else
+                _base._id
+              end
             end
           end
 

data/lib/mongoid/association/referenced/has_and_belongs_to_many/buildable.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -16,11 +18,12 @@ module Mongoid
           #   relation.build(association, attrs)
           #
           # @param [ Object ] base The base object.
-          # @param [ Object ] object The object to use to build the relation.
+          # @param [ Object ] object The object to use to build the association.
           # @param [ String ] type Not used in this context.
+          # @param [ nil ] selected_fields Must be nil.
           #
           # @return [ Array<Document> ] The documents.
-          def build(base, object, type = nil)
+          def build(base, object, type = nil, selected_fields = nil)
             if query?(object)
               query_criteria(object)
             else

data/lib/mongoid/association/referenced/has_and_belongs_to_many/eager.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced