mongoid 7.0.12 → 7.3.3

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

@@ -1,17 +1,20 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasMany
 
-        # This class defines the behaviour for all relations that are a
+        # This class defines the behavior for all associations that are a
         # one-to-many between documents in different collections.
         class Proxy < Association::Many
+          extend Forwardable
 
-          delegate :count, to: :criteria
-          delegate :first, :in_memory, :last, :reset, :uniq, to: :_target
+          def_delegator :criteria, :count
+          def_delegators :_target, :first, :in_memory, :last, :reset, :uniq
 
-          # Appends a document or array of documents to the relation. Will set
+          # Appends a document or array of documents to the association. Will set
           # the parent and update the index in the process.
           #
           # @example Append a document.
@@ -40,7 +43,7 @@ module Mongoid
 
           alias :push :<<
 
-          # Appends an array of documents to the relation. Performs a batch
+          # Appends an array of documents to the association. Performs a batch
           # insert of the documents instead of persisting one at a time.
           #
           # @example Concat with other documents.
@@ -63,9 +66,9 @@ module Mongoid
           end
 
           # Build a new document from the attributes and append it to this
-          # relation without saving.
+          # association without saving.
           #
-          # @example Build a new document on the relation.
+          # @example Build a new document on the association.
           #   person.posts.build(:title => "A new post")
           #
           # @param [ Hash ] attributes The attributes of the new document.
@@ -85,9 +88,9 @@ module Mongoid
 
           alias :new :build
 
-          # Delete the document from the relation. This will set the foreign key
-          # on the document to nil. If the dependent options on the relation are
-          # :delete or :destroy the appropriate removal will occur.
+          # Delete the document from the association. This will set the foreign key
+          # on the document to nil. If the dependent options on the association are
+          # :delete_all or :destroy the appropriate removal will occur.
           #
           # @example Delete the document.
           #   person.posts.delete(post)
@@ -111,10 +114,10 @@ module Mongoid
           # Deletes all related documents from the database given the supplied
           # conditions.
           #
-          # @example Delete all documents in the relation.
+          # @example Delete all documents in the association.
           #   person.posts.delete_all
           #
-          # @example Conditonally delete all documents in the relation.
+          # @example Conditonally delete all documents in the association.
           #   person.posts.delete_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to delete with.
@@ -129,10 +132,10 @@ module Mongoid
           # Destroys all related documents from the database given the supplied
           # conditions.
           #
-          # @example Destroy all documents in the relation.
+          # @example Destroy all documents in the association.
           #   person.posts.destroy_all
           #
-          # @example Conditonally destroy all documents in the relation.
+          # @example Conditonally destroy all documents in the association.
           #   person.posts.destroy_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to destroy with.
@@ -144,10 +147,10 @@ module Mongoid
             remove_all(conditions, :destroy_all)
           end
 
-          # Iterate over each document in the relation and yield to the provided
+          # Iterate over each document in the association and yield to the provided
           # block.
           #
-          # @note This will load the entire relation into memory.
+          # @note This will load the entire association into memory.
           #
           # @example Iterate over the documents.
           #   person.posts.each do |post|
@@ -165,7 +168,14 @@ module Mongoid
             end
           end
 
-          # Determine if any documents in this relation exist in the database.
+          # Determine if any documents in this association exist in the database.
+          #
+          # If the association contains documents but all of the documents
+          # exist only in the application, i.e. have not been persisted to the
+          # database, this method returns false.
+          #
+          # This method queries the database on each invocation even if the
+          # association is already loaded into memory.
           #
           # @example Are there persisted documents?
           #   person.posts.exists?
@@ -198,19 +208,19 @@ module Mongoid
             matching
           end
 
-          # Instantiate a new references_many relation. Will set the foreign key
+          # Instantiate a new references_many association. Will set the foreign key
           # and the base on the inverse object.
           #
-          # @example Create the new relation.
+          # @example Create the new association.
           #   Referenced::Many.new(base, target, association)
           #
-          # @param [ Document ] base The document this relation hangs off of.
-          # @param [ Array<Document> ] target The target of the relation.
+          # @param [ Document ] base The document this association hangs off of.
+          # @param [ Array<Document> ] target The target of the association.
           # @param [ Association ] association The association metadata.
           #
           # @since 2.0.0.beta.1
           def initialize(base, target, association)
-            enum = HasMany::Targets::Enumerable.new(target, base, association)
+            enum = HasMany::Enumerable.new(target, base, association)
             init(base, enum, association) do
               raise_mixed if klass.embedded? && !klass.cyclic?
             end
@@ -220,7 +230,7 @@ module Mongoid
           # documents by deleting the foreign keys and the references, orphaning
           # the target documents in the process.
           #
-          # @example Nullify the relation.
+          # @example Nullify the association.
           #   person.posts.nullify
           #
           # @since 2.0.0.rc.1
@@ -234,13 +244,13 @@ module Mongoid
 
           alias :nullify_all :nullify
 
-          # Clear the relation. Will delete the documents from the db if they are
+          # Clear the association. Will delete the documents from the db if they are
           # already persisted.
           #
-          # @example Clear the relation.
+          # @example Clear the association.
           #   person.posts.clear
           #
-          # @return [ Many ] The relation emptied.
+          # @return [ Many ] The association emptied.
           #
           # @since 2.0.0.beta.1
           def purge
@@ -267,15 +277,15 @@ module Mongoid
           alias :clear :purge
 
           # Substitutes the supplied target documents for the existing documents
-          # in the relation. If the new target is nil, perform the necessary
+          # in the association. If the new target is nil, perform the necessary
           # deletion.
           #
-          # @example Replace the relation.
+          # @example Replace the association.
           #   person.posts.substitute([ new_post ])
           #
           # @param [ Array<Document> ] replacement The replacement target.
           #
-          # @return [ Many ] The relation.
+          # @return [ Many ] The association.
           #
           # @since 2.0.0.rc.1
           def substitute(replacement)
@@ -311,7 +321,7 @@ module Mongoid
           # Appends the document to the target array, updating the index on the
           # document at the same time.
           #
-          # @example Append the document to the relation.
+          # @example Append the document to the association.
           #   relation.append(document)
           #
           # @param [ Document ] document The document to append to the target.
@@ -326,7 +336,7 @@ module Mongoid
           end
 
           # Execute before/after add callbacks around the block unless the objects
-          # already have a persisted relation.
+          # already have a persisted association.
           #
           # @example Execute before/after add callbacks around the block.
           #   relation.with_add_callbacks(document, false)
@@ -342,7 +352,7 @@ module Mongoid
             execute_callback :after_add, document unless already_related
           end
 
-          # Whether the document and the base already have a persisted relation.
+          # Whether the document and the base already have a persisted association.
           #
           # @example Is the document already related to the base.
           #   relation.already_related?(document)
@@ -350,17 +360,17 @@ module Mongoid
           # @param [ Document ] document The document to possibly append to the target.
           #
           # @return [ true, false ] Whether the document is already related to the base and the
-          #   relation is persisted.
+          #   association is persisted.
           #
           # @since 5.1.0
           def already_related?(document)
             document.persisted? &&
                 document._association &&
                 document.respond_to?(document._association.foreign_key) &&
-                document.__send__(document._association.foreign_key) == _base.id
+                document.__send__(document._association.foreign_key) == _base._id
           end
 
-          # Instantiate the binding associated with this relation.
+          # Instantiate the binding associated with this association.
           #
           # @example Get the binding.
           #   relation.binding([ address ])
@@ -372,12 +382,12 @@ module Mongoid
             HasMany::Binding.new(_base, _target, _association)
           end
 
-          # Get the collection of the relation in question.
+          # Get the collection of the association in question.
           #
-          # @example Get the collection of the relation.
+          # @example Get the collection of the association.
           #   relation.collection
           #
-          # @return [ Collection ] The collection of the relation.
+          # @return [ Collection ] The collection of the association.
           #
           # @since 2.0.2
           def collection
@@ -387,7 +397,7 @@ module Mongoid
           # Returns the criteria object for the target class with its documents set
           # to target.
           #
-          # @example Get a criteria for the relation.
+          # @example Get a criteria for the association.
           #   relation.criteria
           #
           # @return [ Criteria ] A new criteria.
@@ -433,7 +443,7 @@ module Mongoid
           # @return [ Criteria, Object ] A Criteria or return value from the target.
           #
           # @since 2.0.0.beta.1
-          def method_missing(name, *args, &block)
+          ruby2_keywords def method_missing(name, *args, &block)
             if _target.respond_to?(name)
               _target.send(name, *args, &block)
             else
@@ -465,12 +475,12 @@ module Mongoid
             end
           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?
@@ -480,10 +490,10 @@ module Mongoid
           # Deletes all related documents from the database given the supplied
           # conditions.
           #
-          # @example Delete all documents in the relation.
+          # @example Delete all documents in the association.
           #   person.posts.delete_all
           #
-          # @example Conditonally delete all documents in the relation.
+          # @example Conditonally delete all documents in the association.
           #   person.posts.delete_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to delete with.
@@ -558,10 +568,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?
             #   Referenced::Many.embedded?
             #
             # @return [ false ] Always false.

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

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/referenced/has_many/binding'
 require 'mongoid/association/referenced/has_many/buildable'
 require 'mongoid/association/referenced/has_many/proxy'
@@ -119,7 +122,7 @@ module Mongoid
         # @since 7.0
         def stores_foreign_key?; false; end
 
-        # Get the relation proxy class for this association type.
+        # Get the association proxy class for this association type.
         #
         # @return [ Association::HasMany::Proxy ] The proxy class.
         #
@@ -128,9 +131,9 @@ module Mongoid
           Proxy
         end
 
-        # The criteria used for querying this relation.
+        # The criteria used for querying this association.
         #
-        # @return [ Mongoid::Criteria ] The criteria used for querying this relation.
+        # @return [ Mongoid::Criteria ] The criteria used for querying this association.
         #
         # @since 7.0
         def criteria(base)
@@ -139,7 +142,7 @@ module Mongoid
 
         # The type of this association if it's polymorphic.
         #
-        # @note Only relevant for polymorphic relations.
+        # @note Only relevant for polymorphic associations.
         #
         # @return [ String, nil ] The type field.
         #

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

@@ -1,16 +1,18 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasOne
 
-        # Binding class for has_one relations.
+        # Binding class for has_one associations.
         #
         # @since 7.0
         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 metadata on the inverse object as well as the

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

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -13,8 +15,13 @@ module Mongoid
           # inverse side using the id or sets the object after clearing the
           # associated object.
           #
+          # @param [ Object ] base The base object.
+          # @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)
             if query?(object)
               if !base.new_record?
                 execute_query(object, base)
@@ -28,6 +35,14 @@ module Mongoid
           private
 
           def clear_associated(object)
+            unless inverse
+              raise Errors::InverseNotFound.new(
+                  @owner_class,
+                  name,
+                  object.class,
+                  foreign_key,
+              )
+            end
             if object && (associated = object.send(inverse))
               associated.substitute(nil)
             end
@@ -39,7 +54,7 @@ module Mongoid
           end
 
           def execute_query(object, base)
-            query_criteria(object, base).limit(-1).first(id_sort: :none)
+            query_criteria(object, base).limit(1).first(id_sort: :none)
           end
 
           def with_polymorphic_criterion(criteria, base)

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

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

data/lib/mongoid/association/referenced/has_one/nested_builder.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -7,15 +9,15 @@ module Mongoid
 
           attr_accessor :destroy
 
-          # Builds the relation depending on the attributes and the options
+          # Builds the association depending on the attributes and the options
           # passed to the macro.
           #
           # @example Build a 1-1 nested document.
           #   one.build(person, as: :admin)
           #
           # @note This attempts to perform 3 operations, either one of an update of
-          #   the existing relation, a replacement of the relation with a new
-          #   document, or a removal of the relation.
+          #   the existing association, a replacement of the association with a new
+          #   document, or a removal of the association.
           #
           # @param [ Document ] parent The parent document.
           #
@@ -36,7 +38,7 @@ module Mongoid
           end
 
           # Create the new builder for nested attributes on one-to-one
-          # relations.
+          # associations.
           #
           # @example Instantiate the builder.
           #   One.new(association, attributes)
@@ -56,7 +58,7 @@ module Mongoid
           private
 
           # Is the id in the attribtues acceptable for allowing an update to
-          # the existing relation?
+          # the existing association?
           #
           # @api private
           #
@@ -67,28 +69,28 @@ module Mongoid
           #
           # @since 2.0.0
           def acceptable_id?
-            id = convert_id(existing.class, attributes[:id])
+            id = convert_id(existing.class, attributes[:_id])
             existing._id == id || id.nil? || (existing._id != id && update_only?)
           end
 
-          # Can the existing relation be deleted?
+          # Can the existing association be deleted?
           #
           # @example Can the existing object be deleted?
           #   one.delete?
           #
-          # @return [ true, false ] If the relation should be deleted.
+          # @return [ true, false ] If the association should be deleted.
           #
           # @since 2.0.0
           def delete?
-            destroyable? && !attributes[:id].nil?
+            destroyable? && !attributes[:_id].nil?
           end
 
-          # Can the existing relation potentially be destroyed?
+          # Can the existing association potentially be destroyed?
           #
           # @example Is the object destroyable?
           #   one.destroyable?({ :_destroy => "1" })
           #
-          # @return [ true, false ] If the relation can potentially be
+          # @return [ true, false ] If the association can potentially be
           #   destroyed.
           #
           # @since 2.0.0

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

@@ -1,21 +1,23 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasOne
 
-        # This class defines the behaviour for all relations that are a
+        # This class defines the behavior for all associations that are a
         # one-to-one between documents in different collections.
         class Proxy < Association::One
 
-          # Instantiate a new references_one relation. Will set the foreign key
+          # Instantiate a new references_one association. Will set the foreign key
           # and the base on the inverse object.
           #
-          # @example Create the new relation.
+          # @example Create the new association.
           #   Referenced::One.new(base, target, association)
           #
-          # @param [ Document ] base The document this relation hangs off of.
-          # @param [ Document ] target The target (child) of the relation.
+          # @param [ Document ] base The document this association hangs off of.
+          # @param [ Document ] target The target (child) of the association.
           # @param [ Association ] association The association metadata.
           def initialize(base, target, association)
             init(base, target, association) do
@@ -30,7 +32,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
           #
           # @since 2.0.0.rc.1
@@ -40,21 +42,26 @@ module Mongoid
           end
 
           # Substitutes the supplied target document for the existing document
-          # in the relation. If the new target is nil, perform the necessary
+          # in the association. If the new target is nil, perform the necessary
           # deletion.
           #
-          # @example Replace the relation.
+          # @example Replace the association.
           #   person.game.substitute(new_game)
           #
           # @param [ Array<Document> ] replacement The replacement target.
           #
-          # @return [ One ] The relation.
+          # @return [ One ] The association.
           #
           # @since 2.0.0.rc.1
           def substitute(replacement)
+            # If the same object currently associated is being assigned,
+            # rebind the association and save the target but do not destroy
+            # the target.
+
             unbind_one
             if persistable?
-              if _association.destructive?
+              # TODO can this entire method be skipped if self == replacement?
+              if _association.destructive? && self != replacement
                 send(_association.dependent)
               else
                 save if persisted?
@@ -65,7 +72,7 @@ module Mongoid
 
           private
 
-          # Instantiate the binding associated with this relation.
+          # Instantiate the binding associated with this association.
           #
           # @example Get the binding.
           #   relation.binding([ address ])
@@ -75,12 +82,12 @@ module Mongoid
             HasOne::Binding.new(_base, _target, _association)
           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?
@@ -93,10 +100,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?
             #   Referenced::One.embedded?
             #
             # @return [ false ] Always false.

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

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/referenced/has_one/binding'
 require 'mongoid/association/referenced/has_one/buildable'
 require 'mongoid/association/referenced/has_one/proxy'
@@ -88,7 +91,7 @@ module Mongoid
         # @since 7.0
         def validation_default; true; end
 
-        # Get the relation proxy class for this association type.
+        # Get the association proxy class for this association type.
         #
         # @return [ Association::HasOne::Proxy ] The proxy class.
         #
@@ -120,7 +123,7 @@ module Mongoid
 
         # The type of this association if it's polymorphic.
         #
-        # @note Only relevant for polymorphic relations.
+        # @note Only relevant for polymorphic associations.
         #
         # @return [ String, nil ] The type field.
         #

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

@@ -1,14 +1,16 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
 
-      # This module handles the behaviour for synchronizing foreign keys between
-      # both sides of a many to many relations.
+      # This module handles the behavior for synchronizing foreign keys between
+      # both sides of a many to many associations.
       module Syncable
 
         # Is the document able to be synced on the inverse side? This is only if
-        # the key has changed and the relation bindings have not been run.
+        # the key has changed and the association bindings have not been run.
         #
         # @example Are the foreign keys syncable?
         #   document._syncable?(association)
@@ -65,7 +67,7 @@ module Mongoid
           end
         end
 
-        # Update the inverse keys for the relation.
+        # Update the inverse keys for the association.
         #
         # @example Update the inverse keys
         #   document.update_inverse_keys(association)
@@ -128,7 +130,7 @@ module Mongoid
           # @example Set up the save syncing.
           #   Person.synced_save(association)
           #
-          # @param [ Association ] association The relation association.
+          # @param [ Association ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
           #

data/lib/mongoid/association/referenced.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/referenced/auto_save'
 require 'mongoid/association/referenced/counter_cache'
 require 'mongoid/association/referenced/syncable'