mongoid 7.2.1 → 9.0.0

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/embedded/embeds_many/binding'
 require 'mongoid/association/embedded/embeds_many/buildable'
@@ -10,8 +10,6 @@ module Mongoid
     module Embedded
 
       # The EmbedsMany type association.
-      #
-      # @since 7.0
       class EmbedsMany
         include Relatable
         include Buildable
@@ -20,8 +18,6 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :as,
             :cascade_callbacks,
@@ -38,15 +34,11 @@ module Mongoid
         # the shared ones.
         #
         # @return [ Array<Symbol> ] The valid options.
-        #
-        # @since 7.0
         VALID_OPTIONS = (ASSOCIATION_OPTIONS + SHARED_OPTIONS).freeze
 
         # Setup the instance methods, fields, etc. on the association owning class.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup!
           setup_instance_methods!
           @owner_class.embedded_relations = @owner_class.embedded_relations.merge(name => self)
@@ -57,8 +49,6 @@ module Mongoid
         # The field key used to store the list of association objects.
         #
         # @return [ String ] The field name.
-        #
-        # @since 7.0
         def store_as
           @store_as ||= (@options[:store_as].try(:to_s) || name.to_s)
         end
@@ -66,8 +56,6 @@ module Mongoid
         # The key that is used to get the attributes for the associated object.
         #
         # @return [ String ] The name of the field used to store the association.
-        #
-        # @since 7.0
         def key
           store_as.to_s
         end
@@ -75,8 +63,6 @@ module Mongoid
         # Is this association type embedded?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def embedded?; true; end
 
         # Get the default validation setting for the association. Determines if
@@ -86,15 +72,11 @@ module Mongoid
         #   Proxy.validation_default
         #
         # @return [ true ] Always true.
-        #
-        # @since 2.1.9
         def validation_default; true; end
 
         # Does this association type store the foreign key?
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def stores_foreign_key?; false; end
 
         # The primary key
@@ -105,17 +87,13 @@ module Mongoid
         # Get the association proxy class for this association type.
         #
         # @return [ Association::Embedded::EmbedsMany::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
-        #
-        # @since 7.0
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           @polymorphic ||= !!@options[:as]
         end
@@ -124,9 +102,7 @@ module Mongoid
         #
         # @note Only relevant if the association is polymorphic.
         #
-        # @return [ String, nil ] The field for storing the associated object's type.
-        #
-        # @since 7.0
+        # @return [ String | nil ] The field for storing the associated object's type.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -137,8 +113,6 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::Many ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::Many.new(self, attributes, options)
         end
@@ -152,8 +126,6 @@ module Mongoid
         #
         # @return [ Mongoid::Atomic::Paths::Embedded::Many ]
         #   The embedded many atomic path calculator.
-        #
-        # @since 2.1.0
         def path(document)
           Mongoid::Atomic::Paths::Embedded::Many.new(document)
         end
@@ -162,8 +134,6 @@ module Mongoid
         #
         # @param [ Document ] base The base document.
         # @param [ Document ] target The children documents.
-        #
-        # @since 7.0
         def criteria(base, target)
           criterion = klass.scoped
           criterion.embedded = true

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -7,8 +7,6 @@ module Mongoid
       class EmbedsOne
 
         # Binding class for all embeds_one associations.
-        #
-        # @since 7.0
         class Binding
           include Bindable
 
@@ -21,12 +19,10 @@ module Mongoid
           # @example Bind the document.
           #   person.name.bind(:continue => true)
           #   person.name = Name.new
-          #
-          # @since 2.0.0.rc.1
           def bind_one
             _target.parentize(_base)
             binding do
-              _target.do_or_do_not(_association.inverse_setter(_target), _base)
+              try_method(_target, _association.inverse_setter(_target), _base)
             end
           end
 
@@ -36,11 +32,9 @@ module Mongoid
           # @example Unbind the document.
           #   person.name.unbind(:continue => true)
           #   person.name = nil
-          #
-          # @since 2.0.0.rc.1
           def unbind_one
             binding do
-              _target.do_or_do_not(_association.inverse_setter(_target), nil)
+              try_method(_target, _association.inverse_setter(_target), nil)
             end
           end
         end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -7,8 +7,6 @@ module Mongoid
       class EmbedsOne
 
         # Builder class for embeds_one associations.
-        #
-        # @since 7.0
         module Buildable
           include Threaded::Lifecycle
 
@@ -20,7 +18,7 @@ module Mongoid
           #   Builder.new(meta, attrs).build
           #
           # @param [ Document ] base The document this association hangs off of.
-          # @param [ Document ] object The related document.
+          # @param [ Document | Hash ] object The related document.
           # @param [ String ] _type Not used in this context.
           # @param [ Hash ] selected_fields Fields which were retrieved via
           #   #only. If selected_fields are specified, fields not listed in it
@@ -28,11 +26,25 @@ module Mongoid
           #
           # @return [ Document ] A single document.
           def build(base, object, _type = nil, selected_fields = nil)
-            return object unless object.is_a?(Hash)
-            if _loading? && base.persisted?
-              Factory.from_db(klass, object, nil, selected_fields)
+            if object.is_a?(Hash)
+              if _loading? && base.persisted?
+                Factory.execute_from_db(klass, object, nil, selected_fields, execute_callbacks: false)
+              else
+                Factory.build(klass, object)
+              end
             else
-              Factory.build(klass, object)
+              clear_associated(object)
+              object
+            end
+          end
+
+          private
+
+          def clear_associated(doc)
+            if doc && (inv = inverse(doc))
+              if associated = doc.ivar(inv)
+                associated.substitute(nil)
+              end
             end
           end
         end

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

@@ -1,24 +1,25 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 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.
-          #
-          # @since 7.0
-          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.
@@ -28,13 +29,14 @@ 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)
-              _base._reset_memoized_children!
+              update_attributes_hash(_target)
+              _base._reset_memoized_descendants!
               _target.save if persistable?
             end
           end
@@ -45,28 +47,24 @@ module Mongoid
           # @example Substitute the new document.
           #   person.name.substitute(new_name)
           #
-          # @param [ Document ] replacement A document to replace the target.
+          # @param [ Document | Hash ] replacement A document to replace the target.
           #
-          # @return [ Document, nil ] The association or nil.
-          #
-          # @since 2.0.0.rc.1
+          # @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?
-              end
-              unbind_one
-              return nil unless replacement
-              replacement = Factory.build(klass, replacement) if replacement.is_a?(::Hash)
-              self._target = replacement
-              bind_one
-              characterize_one(_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
 
@@ -78,8 +76,6 @@ module Mongoid
           #   relation.binding([ address ])
           #
           # @return [ Binding ] The association's binding.
-          #
-          # @since 2.0.0.rc.1
           def binding
             Binding.new(_base, _target, _association)
           end
@@ -89,14 +85,111 @@ module Mongoid
           # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the association is persistable.
-          #
-          # @since 2.1.0
+          # @return [ true | false ] If the association is persistable.
           def persistable?
             _base.persisted? && !_binding? && !_building? && !_assigning?
           end
 
+          # Update the _base's attributes hash with the _target's attributes
+          #
+          # @param replacement [ Document | nil ] The doc to use to update the
+          #   attributes hash.
+          #
+          # @api private
+          def update_attributes_hash(replacement)
+            if replacement
+              _base.attributes.merge!(_association.store_as => replacement.attributes)
+            else
+              _base.attributes.delete(_association.store_as)
+            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.
@@ -105,8 +198,6 @@ module Mongoid
             #   Association::Embedded::EmbedsOne.embedded?
             #
             # @return [ true ] true.
-            #
-            # @since 2.0.0.rc.1
             def embedded?
               true
             end
@@ -120,8 +211,6 @@ module Mongoid
             #
             # @return [ Mongoid::Atomic::Paths::Embedded::One ]
             #   The embedded one atomic path calculator.
-            #
-            # @since 2.1.0
             def path(document)
               Mongoid::Atomic::Paths::Embedded::One.new(document)
             end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/embedded/embeds_one/binding'
 require 'mongoid/association/embedded/embeds_one/buildable'
@@ -10,8 +10,6 @@ module Mongoid
     module Embedded
 
       # The EmbedsOne type association.
-      #
-      # @since 7.0
       class EmbedsOne
         include Relatable
         include Buildable
@@ -20,8 +18,6 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :autobuild,
             :as,
@@ -34,15 +30,11 @@ module Mongoid
         # the shared ones.
         #
         # @return [ Array<Symbol> ] The valid options.
-        #
-        # @since 7.0
         VALID_OPTIONS = (ASSOCIATION_OPTIONS + SHARED_OPTIONS).freeze
 
         # Setup the instance methods, fields, etc. on the association owning class.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup!
           setup_instance_methods!
           @owner_class.embedded_relations = @owner_class.embedded_relations.merge(name => self)
@@ -53,8 +45,6 @@ module Mongoid
         # The field key used to store the association object.
         #
         # @return [ String ] The field name.
-        #
-        # @since 7.0
         def store_as
           @store_as ||= (@options[:store_as].try(:to_s) || name.to_s)
         end
@@ -62,8 +52,6 @@ module Mongoid
         # The key that is used to get the attributes for the associated object.
         #
         # @return [ String ] The name of the field used to store the association.
-        #
-        # @since 7.0
         def key
           store_as.to_s
         end
@@ -71,8 +59,6 @@ module Mongoid
         # Is this association type embedded?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def embedded?; true; end
 
         # Get the default validation setting for the association. Determines if
@@ -81,16 +67,12 @@ module Mongoid
         # @example Get the validation default.
         #   Proxy.validation_default
         #
-        # @return [ true, false ] The validation default.
-        #
-        # @since 2.1.9
+        # @return [ true | false ] The validation default.
         def validation_default; true; end
 
         # Does this association type store the foreign key?
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def stores_foreign_key?; false; end
 
         # The primary key
@@ -101,17 +83,13 @@ module Mongoid
         # Get the association proxy class for this association type.
         #
         # @return [ Association::Embedded::EmbedsMany::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
-        #
-        # @since 7.0
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           @polymorphic ||= !!@options[:as]
         end
@@ -120,9 +98,7 @@ module Mongoid
         #
         # @note Only relevant if the association is polymorphic.
         #
-        # @return [ String, nil ] The field for storing the associated object's type.
-        #
-        # @since 7.0
+        # @return [ String | nil ] The field for storing the associated object's type.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -133,8 +109,6 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::One ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::One.new(self, attributes, options)
         end

data/lib/mongoid/association/embedded.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# 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'