mongoid 8.1.12 → 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

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
@@ -60,6 +65,33 @@ module Mongoid
         def convert_id(klass, id)
           klass.using_object_ids? ? BSON::ObjectId.mongoize(id) : 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
   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

data/lib/mongoid/association/proxy.rb

@@ -1,21 +1,32 @@
 # frozen_string_literal: true
 
-require "mongoid/association/marshalable"
+require 'mongoid/association/marshalable'
 
 module Mongoid
   module Association
-
     # 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
+      alias extend_proxy extend
+
+      # specific methods to prevent from being undefined
+      KEEPER_METHODS = %i[
+        send
+        object_id
+        equal?
+        respond_to?
+        respond_to_missing?
+        tap
+        public_send
+        extend_proxy
+        extend_proxies
+      ].freeze
 
       # 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\?|respond_to_missing\?|tap|public_send|extend_proxy|extend_proxies)\z/
+        undef_method(method) unless method.to_s.start_with?('__') || KEEPER_METHODS.include?(method)
       end
 
       include Threaded::Lifecycle
@@ -41,16 +52,12 @@ module Mongoid
       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.
-      #
-      # @example Initialize the proxy.
-      #   proxy.init(person, name, association)
+      # Sets the target and the association metadata properties.
       #
       # @param [ Document ] base The base document on the proxy.
       # @param [ Document | Array<Document> ] target The target of the proxy.
-      # @param [ Association ] association The association metadata.
-      def init(base, target, association)
+      # @param [ Mongoid::Association::Relatable ] association The association metadata.
+      def initialize(base, target, association)
         @_base, @_target, @_association = base, target, association
         yield(self) if block_given?
         extend_proxies(association.extension) if association.extension
@@ -58,7 +65,7 @@ module Mongoid
 
       # Allow extension to be an array and extend each module
       def extend_proxies(*extension)
-        extension.flatten.each {|ext| extend_proxy(ext) }
+        extension.flatten.each { |ext| extend_proxy(ext) }
       end
 
       # Get the class from the association, or return nil if no association present.
@@ -68,7 +75,7 @@ module Mongoid
       #
       # @return [ Class ] The association class.
       def klass
-        _association ? _association.klass : nil
+        _association&.klass
       end
 
       # Resets the criteria inside the association proxy. Used by many to many
@@ -119,10 +126,16 @@ module Mongoid
       #
       # @param [ String | Symbol ] name The name of the method.
       # @param [ Object... ] *args The arguments passed to the method.
+      # @param &block Optional block to pass.
       ruby2_keywords def method_missing(name, *args, &block)
         _target.send(name, *args, &block)
       end
 
+      # Whether the proxy can forward the method to the target.
+      #
+      # @param [ String | Symbol ] name The name of the method.
+      # @param [ Object... ] *args The +respond_to?+ arguments.
+      #
       # @api private
       ruby2_keywords def respond_to_missing?(name, *args)
         _target.respond_to?(name, *args)
@@ -174,21 +187,20 @@ module Mongoid
       #
       # @return [ Object ] The result of the given block
       def execute_callbacks_around(name, doc)
-        execute_callback :"before_#{name.to_s}", doc
+        execute_callback :"before_#{name}", doc
         yield.tap do
-          execute_callback :"after_#{name.to_s}", doc
+          execute_callback :"after_#{name}", doc
         end
       end
 
       class << self
-
         # Apply ordering to the criteria if it was defined on the association.
         #
         # @example Apply the ordering.
         #   Proxy.apply_ordering(criteria, association)
         #
         # @param [ Criteria ] criteria The criteria to modify.
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ Criteria ] The ordered criteria.
         def apply_ordering(criteria, association)

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

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Referenced
 
+      # Mixin module included into Mongoid::Document which adds
+      # the ability to automatically save opposite-side documents
+      # in referenced associations when saving the subject document.
       module AutoSave
         extend ActiveSupport::Concern
 
@@ -43,7 +47,7 @@ module Mongoid
         # @example Define the autosave method:
         #   Association::Referenced::Autosave.define_autosave!(association)
         #
-        # @param [ Association ] association The association for which autosaving is enabled.
+        # @param [ Mongoid::Association::Relatable ] association The association for which autosaving is enabled.
         #
         # @return [ Class ] The association's owner class.
         def self.define_autosave!(association)
@@ -56,7 +60,7 @@ module Mongoid
                 __autosaving__ do
                   if assoc_value = ivar(association.name)
                     Array(assoc_value).each do |doc|
-                      pc = doc.persistence_context? ? doc.persistence_context : persistence_context
+                      pc = doc.persistence_context? ? doc.persistence_context : persistence_context.for_child(doc)
                       doc.with(pc) do |d|
                         d.save
                       end