mongoid 8.1.13 → 9.0.0

data/lib/mongoid/association/embedded/embeds_one/proxy.rb

@@ -4,18 +4,22 @@ module Mongoid
   module Association
     module Embedded
       class EmbedsOne
-
+        # Transparent proxy for embeds_one associations.
+        # An instance of this class is returned when calling the
+        # association getter method on the parent document. This
+        # class inherits from Mongoid::Association::Proxy and forwards
+        # most of its methods to the target of the association, i.e.
+        # the child document.
         class Proxy < Association::One
-
           # The valid options when defining this association.
           #
           # @return [ Array<Symbol> ] The allowed options when defining this association.
-          VALID_OPTIONS = [
-              :autobuild,
-              :as,
-              :cascade_callbacks,
-              :cyclic,
-              :store_as
+          VALID_OPTIONS = %i[
+            autobuild
+            as
+            cascade_callbacks
+            cyclic
+            store_as
           ].freeze
 
           # Instantiate a new embeds_one association.
@@ -25,15 +29,15 @@ module Mongoid
           #
           # @param [ Document ] base The document this association hangs off of.
           # @param [ Document ] target The child document in the association.
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           def initialize(base, target, association)
-            init(base, target, association) do
+            super do
               characterize_one(_target)
               bind_one
               characterize_one(_target)
               update_attributes_hash(_target)
-              _target.save if persistable?
               _base._reset_memoized_descendants!
+              _target.save if persistable?
             end
           end
 
@@ -47,51 +51,20 @@ module Mongoid
           #
           # @return [ Document | nil ] The association or nil.
           def substitute(replacement)
-            if replacement != self
-              if _assigning?
-                _base.add_atomic_unset(_target) unless replacement
-              else
-                # The associated object will be replaced by the below update if non-nil, so only
-                # run the callbacks and state-changing code by passing persist: false in that case.
-                _target.destroy(persist: !replacement) if persistable?
-
-                unless Mongoid.broken_updates
-                  # A little explanation on why this is needed... Say we have three assignments:
-                  #
-                  # canvas.palette = palette
-                  # canvas.palette = nil
-                  # canvas.palette = palette
-                  # Where canvas embeds_one palette.
-                  #
-                  # Previously, what was happening was, on the first assignment,
-                  # palette was considered a "new record" (new_record?=true) and
-                  # thus palette was being inserted into the database. However,
-                  # on the third assignment, we're trying to reassign the palette,
-                  # palette is no longer considered a new record, because it had
-                  # been inserted previously. This is not exactly accurate,
-                  # because the second assignment ultimately removed the palette
-                  # from the database, so it needs to be reinserted. Since the
-                  # palette's new_record is false, Mongoid ends up "updating" the
-                  # document, which doesn't reinsert it into the database.
-                  #
-                  # The change I introduce here, respecifies palette as a "new
-                  # record" when it gets removed from the database, so if it is
-                  # reassigned, it will be reinserted into the database.
-                  _target.new_record = true
-                end
-              end
-              unbind_one
-              unless replacement
-                update_attributes_hash(replacement)
-                return nil
-              end
-              replacement = Factory.build(klass, replacement) if replacement.is_a?(::Hash)
-              self._target = replacement
-              characterize_one(_target)
-              bind_one
-              update_attributes_hash(_target)
-              _target.save if persistable?
+            return self if replacement == self
+
+            if _assigning?
+              _base.add_atomic_unset(_target) unless replacement
+            else
+              update_target_when_not_assigning(replacement)
             end
+
+            unbind_one
+
+            return nil if replace_with_nil_document(replacement)
+
+            replace_with(replacement)
+
             self
           end
 
@@ -131,7 +104,92 @@ module Mongoid
             end
           end
 
+          # When not ``_assigning?``, the target may need to be destroyed, and
+          # may need to be marked as a new record. This method takes care of
+          # that, with extensive documentation for why it is necessary.
+          #
+          # @param [ Mongoid::Document ] replacement the replacement document
+          def update_target_when_not_assigning(replacement)
+            # The associated object will be replaced by the below update if non-nil, so only
+            # run the callbacks and state-changing code by passing persist: false in that case.
+            _target.destroy(persist: !replacement) if persistable?
+
+            # A little explanation on why this is needed... Say we have three assignments:
+            #
+            # canvas.palette = palette
+            # canvas.palette = nil
+            # canvas.palette = palette
+            # Where canvas embeds_one palette.
+            #
+            # Previously, what was happening was, on the first assignment,
+            # palette was considered a "new record" (new_record?=true) and
+            # thus palette was being inserted into the database. However,
+            # on the third assignment, we're trying to reassign the palette,
+            # palette is no longer considered a new record, because it had
+            # been inserted previously. This is not exactly accurate,
+            # because the second assignment ultimately removed the palette
+            # from the database, so it needs to be reinserted. Since the
+            # palette's new_record is false, Mongoid ends up "updating" the
+            # document, which doesn't reinsert it into the database.
+            #
+            # The change I introduce here, respecifies palette as a "new
+            # record" when it gets removed from the database, so if it is
+            # reassigned, it will be reinserted into the database.
+            _target.new_record = true
+          end
+
+          # Checks the argument. If it is non-nil, this method does nothing.
+          # Otherwise, it performs the logic for replacing the current
+          # document with nil.
+          #
+          # @param [ Mongoid::Document | Hash | nil ] replacement the document
+          #   to check.
+          #
+          # @return [ true | false ] whether a nil document was substituted
+          #   or not.
+          def replace_with_nil_document(replacement)
+            return false if replacement
+
+            update_attributes_hash(replacement)
+
+            # when `touch: true` is the default (see MONGOID-5016), creating
+            # an embedded document will touch the parent, and will cause the
+            # _descendants list to be initialized and memoized. If the object
+            # is then deleted, we need to make sure and un-memoize that list,
+            # otherwise when the update happens, the memoized _descendants list
+            # gets used and the "deleted" subdocument gets added again.
+            _reset_memoized_descendants!
+
+            true
+          end
+
+          # Replaces the current document with the given replacement
+          # document, which may be a Hash of attributes.
+          #
+          # @param [ Mongoid::Document | Hash ] replacement the document to
+          #   substitute in place of the current document.
+          def replace_with(replacement)
+            replacement = Factory.build(klass, replacement) if replacement.is_a?(::Hash)
+            self._target = replacement
+            characterize_one(_target)
+            bind_one
+            update_attributes_hash(_target)
+            _target.save if persistable?
+          end
+
           class << self
+            # Returns the eager loader for this association.
+            #
+            # @param [ Array<Mongoid::Association> ] associations The
+            #   associations to be eager loaded
+            # @param [ Array<Mongoid::Document> ] docs The parent documents
+            #   that possess the given associations, which ought to be
+            #   populated by the eager-loaded documents.
+            #
+            # @return [ Mongoid::Association::Embedded::Eager ]
+            def eager_loader(associations, docs)
+              Eager.new(associations, docs)
+            end
 
             # Returns true if the association is an embedded one. In this case
             # always true.

data/lib/mongoid/association/embedded/embeds_one.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/embedded/embeds_one/binding'
 require 'mongoid/association/embedded/embeds_one/buildable'

data/lib/mongoid/association/embedded.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/embedded/cyclic'
+require 'mongoid/association/embedded/eager'
 require 'mongoid/association/embedded/embedded_in'
 require 'mongoid/association/embedded/embeds_many'
 require 'mongoid/association/embedded/embeds_one'

data/lib/mongoid/association/macros.rb

@@ -2,7 +2,6 @@
 
 module Mongoid
   module Association
-
     # This module contains the core macros for defining associations between
     # documents. They can be either embedded or referenced.
     module Macros
@@ -35,7 +34,7 @@ module Mongoid
         # @api private
         class_attribute :aliased_associations
 
-        # @return [ Set<String> ] The set of associations that are configured 
+        # @return [ Set<String> ] The set of associations that are configured
         #   with :store_as parameter.
         class_attribute :stored_as_associations
 
@@ -53,11 +52,11 @@ module Mongoid
       #
       # @return [ Hash ] The associations.
       def associations
-        self.relations
+        relations
       end
 
+      # Class methods for associations.
       module ClassMethods
-
         # Adds the association back to the parent document. This macro is
         # necessary to set the references from the child back to the parent
         # document. If a child does not define this association calling
@@ -77,7 +76,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embedded_in(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -100,7 +99,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -123,7 +122,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -145,11 +144,13 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def belongs_to(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
+        # rubocop:disable Naming/PredicateName
+
         # Adds a referenced association from a parent Document to many
         # Documents in another database or collection.
         #
@@ -167,7 +168,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -189,7 +190,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_and_belongs_to_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -211,20 +212,22 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
+        # rubocop:enable Naming/PredicateName
+
         private
 
         def define_association!(macro_name, name, options = {}, &block)
           Association::MACRO_MAPPING[macro_name].new(self, name, options, &block).tap do |assoc|
             assoc.setup!
-            self.relations = self.relations.merge(name => assoc)
+            self.relations = relations.merge(name => assoc)
             if assoc.embedded? && assoc.respond_to?(:store_as) && assoc.store_as != name
-              self.aliased_associations[assoc.store_as] = name
-              self.stored_as_associations << assoc.store_as
+              aliased_associations[assoc.store_as] = name
+              stored_as_associations << assoc.store_as
             end
           end
         end

data/lib/mongoid/association/many.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association

data/lib/mongoid/association/marshalable.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
+
+    # Mixin module for Mongoid::Association::Proxy which adds
+    # custom Marshal.dump functionality.
     module Marshalable
 
       # Provides the data needed to Marshal.dump an association proxy.

data/lib/mongoid/association/nested/many.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on many-to-n associations.
       class Many
         include Buildable
 
@@ -40,7 +44,7 @@ module Mongoid
         # @example Initialize the builder.
         #   Many.new(association, attributes, options)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         # @param [ Hash ] attributes The attributes hash to attempt to set.
         # @param [ Hash ] options The options defined.
         def initialize(association, attributes, options = {})
@@ -97,7 +101,8 @@ module Mongoid
         # @param [ Hash ] attrs The single document attributes to process.
         def process_attributes(parent, attrs)
           return if reject?(parent, attrs)
-          if id = attrs.extract_id
+
+          if (id = extract_id(attrs))
             update_nested_relation(parent, id, attrs)
           else
             existing.push(Factory.build(@class_name, attrs)) unless destroyable?(attrs)
@@ -149,7 +154,7 @@ module Mongoid
         # @param [ Document ] doc The document to update.
         # @param [ Hash ] attrs The attributes.
         def update_document(doc, attrs)
-          attrs.delete_id
+          delete_id(attrs)
           if association.embedded?
             doc.assign_attributes(attrs)
           else
@@ -169,7 +174,7 @@ module Mongoid
         # @param [ Hash ] attrs The single document attributes to process.
         def update_nested_relation(parent, id, attrs)
           first = existing.first
-          converted = convert_id(first ? first.class : association.klass, id)
+          converted = first ? convert_id(first.class, id) : id
 
           if existing.where(_id: converted).exists?
             # document exists in association
@@ -179,46 +184,11 @@ module Mongoid
             else
               update_document(doc, attrs)
             end
-          elsif association.embedded?
-            raise Errors::DocumentNotFound.new(association.klass, id)
-          elsif destroyable?(attrs)
-            # A destroy of a document that is not in the association is
-            # ignored, rather than reaching for it outside the association.
-            nil
-          elsif Mongoid.allow_reparenting_via_nested_attributes?
-            Mongoid::Warnings.warn_reparenting_via_nested_attributes
-
+          else
             # push existing document to association
             doc = association.klass.unscoped.find(converted)
-            # find returns nil instead of raising when
-            # Mongoid.raise_not_found_error is false; a missing document
-            # must still be an error here, consistent with the other
-            # not-found branches.
-            raise Errors::DocumentNotFound.new(association.klass, id) if doc.nil?
-
             update_document(doc, attrs)
-            existing.push(doc)
-          else
-            raise Errors::DocumentNotFound.new(association.klass, not_found_params(parent, id))
-          end
-        end
-
-        # The params to report when an id in the nested attributes could not
-        # be resolved within the association.
-        #
-        # @api private
-        #
-        # @param [ Document ] parent The parent document.
-        # @param [ String | BSON::ObjectId ] id of the related document.
-        #
-        # @return [ Hash | Object ] The params for the not found error.
-        def not_found_params(parent, id)
-          if association.is_a?(Association::Referenced::HasAndBelongsToMany)
-            # A many-to-many association has no foreign key on the child, so
-            # the id is only ever resolved within the association itself.
-            id
-          else
-            { _id: id, association.foreign_key => parent.id }
+            existing.push(doc) unless destroyable?(attrs)
           end
         end
       end

data/lib/mongoid/association/nested/nested_buildable.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Mixin module containing common functionality used to
+      # perform #accepts_nested_attributes_for attribute assignment
+      # on associations.
       module Buildable
 
         attr_accessor :attributes, :existing, :association, :options
@@ -53,26 +58,39 @@ module Mongoid
         # @example Convert the id.
         #   builder.convert_id(Person, "4d371b444835d98b8b000010")
         #
-        # Ids arriving from a form are always scalars. A Hash or an Array
-        # here means the parameters were crafted, and letting one through
-        # would turn the id into a query operator, so they are rejected.
-        #
         # @param [ Class ] klass The class we're trying to convert for.
         # @param [ String ] id The id, usually coming from the form.
         #
         # @return [ BSON::ObjectId | String | Object ] The converted id.
-        #
-        # @raise [ Errors::DocumentNotFound ] if the id is not a scalar, or
-        #   cannot be converted to the type the class uses for its ids.
-        #   The BSON::Error rescue is defensive: a value that reaches
-        #   BSON::ObjectId.mongoize and raises there must not surface as an
-        #   unhandled BSON error in the caller.
         def convert_id(klass, id)
-          raise Errors::DocumentNotFound.new(klass, id) if id.is_a?(::Hash) || id.is_a?(::Array)
-
           klass.using_object_ids? ? BSON::ObjectId.mongoize(id) : id
-        rescue BSON::Error
-          raise Errors::DocumentNotFound.new(klass, id)
+        end
+
+        private
+
+        # Get the id attribute from the given hash, whether it's
+        # prefixed with an underscore or is a symbol.
+        #
+        # @example Get the id.
+        #   extract_id({ _id: 1 })
+        #
+        # @param [ Hash ] hash The hash from which to extract.
+        #
+        # @return [ Object ] The value of the id.
+        def extract_id(hash)
+          hash['_id'] || hash[:_id] || hash['id'] || hash[:id]
+        end
+
+        # Deletes the id key from the given hash.
+        #
+        # @example Delete an id value.
+        #   delete_id({ "_id" => 1 })
+        #
+        # @param [ Hash ] hash The hash from which to delete.
+        #
+        # @return [ Object ] The deleted value, or nil.
+        def delete_id(hash)
+          hash.delete('_id') || hash.delete(:_id) || hash.delete('id') || hash.delete(:id)
         end
       end
     end

data/lib/mongoid/association/nested/one.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on one-to-n associations.
       class One
         include Buildable
 
         attr_accessor :destroy
 
-
         # Builds the association depending on the attributes and the options
         # passed to the macro.
         #
@@ -26,7 +29,7 @@ module Mongoid
           return if reject?(parent, attributes)
           @existing = parent.send(association.name)
           if update?
-            attributes.delete_id
+            delete_id(attributes)
             existing.assign_attributes(attributes)
           elsif replace?
             parent.send(association.setter, Factory.build(@class_name, attributes))
@@ -43,7 +46,7 @@ module Mongoid
         # @example Instantiate the builder.
         #   One.new(association, attributes)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         # @param [ Hash ] attributes The attributes hash to attempt to set.
         # @param [ Hash ] options The options defined.
         def initialize(association, attributes, options)

data/lib/mongoid/association/nested.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/nested/nested_buildable'
 require 'mongoid/association/nested/many'

data/lib/mongoid/association/one.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association

data/lib/mongoid/association/options.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
 
+    # Options context used for all association types.
     module Options
 
       # Returns the name of the parent to a polymorphic child.
@@ -112,8 +114,13 @@ module Mongoid
         @touch_field ||= options[:touch] if (options[:touch].is_a?(String) || options[:touch].is_a?(Symbol))
       end
 
-      private
-
+      # Whether the association object should be automatically touched
+      # when its inverse object is updated.
+      #
+      # @return [ true | false ] returns true if this association is
+      #   automatically touched, false otherwise. The default is false.
+      #
+      # @api private
       def touchable?
         !!@options[:touch]
       end