mongoid 7.2.1 → 9.0.0

data/lib/mongoid/traversable.rb

@@ -1,32 +1,99 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
-require "mongoid/fields/validators/macro"
+require 'mongoid/fields/validators/macro'
 
 module Mongoid
-
-  # Provides behavior around traversing the document graph.
-  #
-  # @since 4.0.0
+  # Mixin module included in Mongoid::Document to provide behavior
+  # around traversing the document graph.
   module Traversable
     extend ActiveSupport::Concern
 
+    # Class-level methods for the Traversable behavior.
+    module ClassMethods
+      # Determines if the document is a subclass of another document.
+      #
+      # @example Check if the document is a subclass.
+      #   Square.hereditary?
+      #
+      # @return [ true | false ] True if hereditary, false if not.
+      def hereditary?
+        !!(superclass < Mongoid::Document)
+      end
+
+      # When inheriting, we want to copy the fields from the parent class and
+      # set the on the child to start, mimicking the behavior of the old
+      # class_inheritable_accessor that was deprecated in Rails edge.
+      #
+      # @example Inherit from this class.
+      #   Person.inherited(Doctor)
+      #
+      # @param [ Class ] subclass The inheriting class.
+      #
+      # rubocop:disable Metrics/AbcSize
+      def inherited(subclass)
+        super
+        @_type = nil
+        subclass.aliased_fields = aliased_fields.dup
+        subclass.localized_fields = localized_fields.dup
+        subclass.fields = fields.dup
+        subclass.pre_processed_defaults = pre_processed_defaults.dup
+        subclass.post_processed_defaults = post_processed_defaults.dup
+        subclass._declared_scopes = Hash.new { |_hash, key| _declared_scopes[key] }
+        subclass.discriminator_value = subclass.name
+
+        # We need to do this here because the discriminator_value method is
+        # overridden in the subclass above.
+        subclass.include DiscriminatorRetrieval
+
+        # We only need the _type field if inheritance is in play, but need to
+        # add to the root class as well for backwards compatibility.
+        return if fields.key?(discriminator_key)
+
+        default_proc = -> { self.class.discriminator_value }
+        field(discriminator_key, default: default_proc, type: String)
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+
+    # `_parent` is intentionally not implemented via attr_accessor because
+    # of the need to use a double underscore for the instance variable.
+    # Associations automatically create backing variables prefixed with a
+    # single underscore, which would conflict with this accessor if a model
+    # were to declare a `parent` association.
+
+    # Retrieves the parent document of this document.
+    #
+    # @return [ Mongoid::Document | nil ] the parent document
+    #
+    # @api private
     def _parent
-      @__parent ||= nil
+      @__parent || nil
     end
 
-    def _parent=(p)
-      @__parent = p
+    # Sets the parent document of this document.
+    #
+    # @param [ Mongoid::Document | nil ] document the document to set as
+    #   the parent document.
+    #
+    # @returns [ Mongoid::Document ] The parent document.
+    #
+    # @api private
+    def _parent=(document)
+      @__parent = document
     end
 
     # Module used for prepending to the various discriminator_*= methods
     #
     # @api private
     module DiscriminatorAssignment
+      # Sets the discriminator key.
+      #
+      # @param [ String ] value The discriminator key to set.
+      #
+      # @api private
+      # rubocop:disable Metrics/AbcSize
       def discriminator_key=(value)
-        if hereditary?
-          raise Errors::InvalidDiscriminatorKeyTarget.new(self, self.superclass)
-        end
+        raise Errors::InvalidDiscriminatorKeyTarget.new(self, superclass) if hereditary?
 
         _mongoid_clear_types
 
@@ -47,14 +114,20 @@ module Mongoid
         # an existing field.
         # This condition also checks if the class has any descendants, because
         # if it doesn't then it doesn't need a discriminator key.
-        if !fields.has_key?(self.discriminator_key) && !descendants.empty?
-          default_proc = lambda { self.class.discriminator_value }
-          field(self.discriminator_key, default: default_proc, type: String)
-        end
+        return unless !fields.key?(discriminator_key) && !descendants.empty?
+
+        default_proc = -> { self.class.discriminator_value }
+        field(discriminator_key, default: default_proc, type: String)
       end
+      # rubocop:enable Metrics/AbcSize
 
+      # Returns the discriminator key.
+      #
+      # @return [ String ] The discriminator key.
+      #
+      # @api private
       def discriminator_value=(value)
-        value ||= self.name
+        value ||= name
         _mongoid_clear_types
         add_discriminator_mapping(value)
         @discriminator_value = value
@@ -66,14 +139,13 @@ module Mongoid
     # A separate module was needed because the subclasses of this class
     # need to be manually prepended with the discriminator_value and can't
     # rely on being a class_attribute because the .discriminator_value
-    # method is overriden by every subclass in the inherited method.
+    # method is overridden by every subclass in the inherited method.
     #
     # @api private
     module DiscriminatorRetrieval
-
       # Get the name on the reading side if the discriminator_value is nil
       def discriminator_value
-        @discriminator_value || self.name
+        @discriminator_value || name
       end
     end
 
@@ -98,7 +170,7 @@ module Mongoid
       # @param [ Class ] The class the discriminator_value was set on
       #
       # @api private
-      def self.add_discriminator_mapping(value, klass=self)
+      def self.add_discriminator_mapping(value, klass = self)
         self.discriminator_mapping ||= {}
         self.discriminator_mapping[value] = klass
         superclass.add_discriminator_mapping(value, klass) if hereditary?
@@ -118,53 +190,96 @@ module Mongoid
       end
     end
 
-    # Get all child +Documents+ to this +Document+, going n levels deep if
-    # necessary. This is used when calling update persistence operations from
+    # Get all child +Documents+ to this +Document+
+    #
+    # @return [ Array<Document> ] All child documents in the hierarchy.
+    #
+    # @api private
+    def _children(reset: false)
+      # See discussion above for the `_parent` method, as to why the variable
+      # here needs to have two underscores.
+      #
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      if reset
+        @__children = nil
+      else
+        @__children ||= collect_children
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
+    end
+
+    # Get all descendant +Documents+ of this +Document+ recursively.
+    # This is used when calling update persistence operations from
     # the root document, where changes in the entire tree need to be
     # determined. Note that persistence from the embedded documents will
     # always be preferred, since they are optimized calls... This operation
     # can get expensive in domains with large hierarchies.
     #
-    # @example Get all the document's children.
-    #   person._children
+    # @return [ Array<Document> ] All descendant documents in the hierarchy.
     #
-    # @return [ Array<Document> ] All child documents in the hierarchy.
-    def _children
-      @__children ||= collect_children
+    # @api private
+    def _descendants(reset: false)
+      # See discussion above for the `_parent` method, as to why the variable
+      # here needs to have two underscores.
+      #
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      if reset
+        @__descendants = nil
+      else
+        @__descendants ||= collect_descendants
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
     end
 
     # Collect all the children of this document.
     #
-    # @example Collect all the children.
-    #   document.collect_children
-    #
     # @return [ Array<Document> ] The children.
     #
-    # @since 2.4.0
+    # @api private
     def collect_children
-      children = []
-      embedded_relations.each_pair do |name, association|
-        without_autobuild do
-          child = send(name)
-          Array.wrap(child).each do |doc|
-            children.push(doc)
-            children.concat(doc._children)
-          end if child
+      [].tap do |children|
+        embedded_relations.each_pair do |name, _association|
+          without_autobuild do
+            child = send(name)
+            children.concat(Array.wrap(child)) if child
+          end
         end
       end
-      children
     end
 
-    # Marks all children as being persisted.
+    # Collect all the descendants of this document.
     #
-    # @example Flag all the children.
-    #   document.flag_children_persisted
+    # @return [ Array<Document> ] The descendants.
     #
-    # @return [ Array<Document> ] The flagged children.
+    # @api private
+    def collect_descendants
+      children = []
+      to_expand = _children
+      expanded = {}
+
+      until to_expand.empty?
+        expanding = to_expand
+        to_expand = []
+        expanding.each do |child|
+          next if expanded[child]
+
+          # Don't mark expanded if _id is nil, since documents are compared by
+          # their _ids, multiple embedded documents with nil ids will compare
+          # equally, and some documents will not be expanded.
+          expanded[child] = true if child._id
+          children << child
+          to_expand += child._children
+        end
+      end
+
+      children
+    end
+
+    # Marks all descendants as being persisted.
     #
-    # @since 3.0.7
-    def flag_children_persisted
-      _children.each do |child|
+    # @return [ Array<Document> ] The flagged descendants.
+    def flag_descendants_persisted
+      _descendants.each do |child|
         child.new_record = false
       end
     end
@@ -174,7 +289,7 @@ module Mongoid
     # @example Check if the document is a subclass
     #   Square.new.hereditary?
     #
-    # @return [ true, false ] True if hereditary, false if not.
+    # @return [ true | false ] True if hereditary, false if not.
     def hereditary?
       self.class.hereditary?
     end
@@ -201,49 +316,39 @@ module Mongoid
     #   document.remove_child(child)
     #
     # @param [ Document ] child The child (embedded) document to remove.
-    #
-    # @since 2.0.0.beta.1
     def remove_child(child)
       name = child.association_name
       if child.embedded_one?
+        attributes.delete(child._association.store_as)
         remove_ivar(name)
       else
         relation = send(name)
-        relation.send(:delete_one, child)
+        relation._remove(child)
       end
     end
 
-    # After children are persisted we can call this to move all their changes
-    # and flag them as persisted in one call.
-    #
-    # @example Reset the children.
-    #   document.reset_persisted_children
+    # After descendants are persisted we can call this to move all their
+    # changes and flag them as persisted in one call.
     #
-    # @return [ Array<Document> ] The children.
-    #
-    # @since 2.1.0
-    def reset_persisted_children
-      _children.each do |child|
+    # @return [ Array<Document> ] The descendants.
+    def reset_persisted_descendants
+      _descendants.each do |child|
         child.move_changes
         child.new_record = false
       end
-      _reset_memoized_children!
+      _reset_memoized_descendants!
     end
 
-    # Resets the memoized children on the object. Called internally when an
+    # Resets the memoized descendants on the object. Called internally when an
     # embedded array changes size.
     #
-    # @api semiprivate
-    #
-    # @example Reset the memoized children.
-    #   document._reset_memoized_children!
-    #
     # @return [ nil ] nil.
     #
-    # @since 5.0.0
-    def _reset_memoized_children!
-      _parent._reset_memoized_children! if _parent
-      @__children = nil
+    # @api private
+    def _reset_memoized_descendants!
+      _parent&._reset_memoized_descendants!
+      _children reset: true
+      _descendants reset: true
     end
 
     # Return the root document in the object graph. If the current document
@@ -255,7 +360,7 @@ module Mongoid
     # @return [ Document ] The root document in the hierarchy.
     def _root
       object = self
-      while (object._parent) do object = object._parent; end
+      object = object._parent while object._parent
       object
     end
 
@@ -264,59 +369,9 @@ module Mongoid
     # @example Is the document the root?
     #   document._root?
     #
-    # @return [ true, false ] If the document is the root.
-    #
-    # @since 3.1.0
+    # @return [ true | false ] If the document is the root.
     def _root?
       _parent ? false : true
     end
-
-    module ClassMethods
-
-      # Determines if the document is a subclass of another document.
-      #
-      # @example Check if the document is a subclass.
-      #   Square.hereditary?
-      #
-      # @return [ true, false ] True if hereditary, false if not.
-      def hereditary?
-        !!(Mongoid::Document > superclass)
-      end
-
-      # When inheriting, we want to copy the fields from the parent class and
-      # set the on the child to start, mimicking the behavior of the old
-      # class_inheritable_accessor that was deprecated in Rails edge.
-      #
-      # @example Inherit from this class.
-      #   Person.inherited(Doctor)
-      #
-      # @param [ Class ] subclass The inheriting class.
-      #
-      # @since 2.0.0.rc.6
-      def inherited(subclass)
-        super
-        @_type = nil
-        subclass.aliased_fields = aliased_fields.dup
-        subclass.localized_fields = localized_fields.dup
-        subclass.fields = fields.dup
-        subclass.pre_processed_defaults = pre_processed_defaults.dup
-        subclass.post_processed_defaults = post_processed_defaults.dup
-        subclass._declared_scopes = Hash.new { |hash,key| self._declared_scopes[key] }
-        subclass.discriminator_value = subclass.name
-
-        # We need to do this here because the discriminator_value method is
-        # overriden in the subclass above.
-        class << subclass
-          include DiscriminatorRetrieval
-        end
-
-        # We only need the _type field if inheritance is in play, but need to
-        # add to the root class as well for backwards compatibility.
-        unless fields.has_key?(self.discriminator_key)
-          default_proc = lambda { self.class.discriminator_value }
-          field(self.discriminator_key, default: default_proc, type: String)
-        end
-      end
-    end
   end
 end

data/lib/mongoid/utils.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mongoid
+  # Utility functions for Mongoid.
+  #
+  # @api private
+  module Utils
+    extend self
+
+    # A unique placeholder value that will never accidentally collide with
+    # valid values. This is useful as a default keyword argument value when
+    # you want the argument to be optional, but you also want to be able to
+    # recognize that the caller did not provide a value for it.
+    PLACEHOLDER = Object.new.freeze
+
+    # Asks if the given value is a placeholder or not.
+    #
+    # @param [ Object ] value the value to compare
+    #
+    # @return [ true | false ] if the value is a placeholder or not.
+    def placeholder?(value)
+      value == PLACEHOLDER
+    end
+
+    # This function should be used if you need to measure time.
+    # @example Calculate elapsed time.
+    #   starting = Utils.monotonic_time
+    #   # do something time consuming
+    #   ending = Utils.monotonic_time
+    #   puts "It took #{(ending - starting).to_i} seconds"
+    #
+    # @see https://blog.dnsimple.com/2018/03/elapsed-time-with-ruby-the-right-way/
+    #
+    # @return [Float] seconds according to monotonic clock
+    #
+    # @api private
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Returns true if the string is any of the following values: "1",
+    # "yes", "true", "on". Anything else is assumed to be false. Case is
+    # ignored, as are leading or trailing spaces.
+    #
+    # @param [ String ] string the string value to consider
+    #
+    # @return [ true | false ]
+    def truthy_string?(string)
+      %w[ 1 yes true on ].include?(string.strip.downcase)
+    end
+  end
+end

data/lib/mongoid/validatable/associated.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Validatable
@@ -16,34 +16,110 @@ module Mongoid
     #
     #     validates_associated :name, :addresses
     #   end
-    class AssociatedValidator < ActiveModel::EachValidator
+    class AssociatedValidator < ActiveModel::Validator
+      # Required by `validates_with` so that the validator
+      # gets added to the correct attributes.
+      def attributes
+        options[:attributes]
+      end
 
-      # Validates that the associations provided are either all nil or all
-      # valid. If neither is true then the appropriate errors will be added to
-      # the parent document.
+      # Checks that the named associations of the given record
+      # (`attributes`) are valid. This does NOT load the associations
+      # from the database, and will only validate records that are dirty
+      # or unpersisted.
       #
-      # @example Validate the association.
-      #   validator.validate_each(document, :name, name)
+      # If anything is not valid, appropriate errors will be added to
+      # the `document` parameter.
+      #
+      # @param [ Mongoid::Document ] document the document with the
+      #   associations to validate.
+      def validate(document)
+        options[:attributes].each do |attr_name|
+          validate_association(document, attr_name)
+        end
+      end
+
+      private
+
+      # Validates that the given association provided is either nil,
+      # persisted and unchanged, or invalid. Otherwise, the appropriate errors
+      # will be added to the parent document.
       #
       # @param [ Document ] document The document to validate.
       # @param [ Symbol ] attribute The association to validate.
-      # @param [ Object ] value The value of the association.
-      #
-      # @since 2.0.0
-      def validate_each(document, attribute, value)
-        begin
-          document.begin_validate
-          valid = Array.wrap(value).collect do |doc|
-            if doc.nil? || doc.flagged_for_destroy?
-              true
+      def validate_association(document, attribute)
+        # grab the proxy from the instance variable directly; we don't want
+        # any loading logic to run; we just want to see if it's already
+        # been loaded.
+        proxy = document.ivar(attribute)
+        return unless proxy
+
+        # if the variable exists, now we see if it is a proxy, or an actual
+        # document. It might be a literal document instead of a proxy if this
+        # document was created with a Document instance as a provided attribute,
+        # e.g. "Post.new(message: Message.new)".
+        target = proxy.respond_to?(:_target) ? proxy._target : proxy
+
+        # Now, fetch the list of documents from the target. Target may be a
+        # single value, or a list of values, and in the case of HasMany,
+        # might be a rather complex collection. We need to do this without
+        # triggering a load, so it's a bit of a delicate dance.
+        list = get_target_documents(target)
+
+        valid = document.validating do
+          # Now, treating the target as an array, look at each element
+          # and see if it is valid, but only if it has already been
+          # persisted, or changed, and hasn't been flagged for destroy.
+          list.all? do |value|
+            if value && !value.flagged_for_destroy? && (!value.persisted? || value.changed?)
+              value.validated? ? true : value.valid?
             else
-              doc.validated? ? true : doc.valid?
+              true
             end
-          end.all?
-        ensure
-          document.exit_validate
+          end
+        end
+
+        document.errors.add(attribute, :invalid) unless valid
+      end
+
+      private
+
+      # Examine the given target object and return an array of
+      # documents (possibly empty) that the target represents.
+      #
+      # @param [ Array | Mongoid::Document | Mongoid::Association::Proxy | HasMany::Enumerable ] target
+      #   the target object to examine.
+      #
+      # @return [ Array<Mongoid::Document> ] the list of documents
+      def get_target_documents(target)
+        if target.respond_to?(:_loaded?)
+          get_target_documents_for_has_many(target)
+        else
+          get_target_documents_for_other(target)
         end
-        document.errors.add(attribute, :invalid, options) unless valid
+      end
+
+      # Returns the list of all currently in-memory values held by
+      # the target. The target will not be loaded.
+      #
+      # @param [ HasMany::Enumerable ] target the target that will
+      #   be examined for in-memory documents.
+      #
+      # @return [ Array<Mongoid::Document> ] the in-memory documents
+      #   held by the target.
+      def get_target_documents_for_has_many(target)
+        [ *target._loaded.values, *target._added.values ]
+      end
+
+      # Returns the target as an array. If the target represents a single
+      # value, it is wrapped in an array.
+      #
+      # @param [ Array | Mongoid::Document | Mongoid::Association::Proxy ] target
+      #   the target to return.
+      #
+      # @return [ Array<Mongoid::Document> ] the target, as an array.
+      def get_target_documents_for_other(target)
+        Array.wrap(target)
       end
     end
   end

data/lib/mongoid/validatable/format.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Validatable

data/lib/mongoid/validatable/length.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Validatable

data/lib/mongoid/validatable/localizable.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Validatable
@@ -13,10 +13,8 @@ module Mongoid
       #   validator.validate_each(model, :name, "value")
       #
       # @param [ Document ] document The document.
-      # @param [ Symbol, String ] attribute The attribute to validate.
+      # @param [ Symbol | String ] attribute The attribute to validate.
       # @param [ Object ] value The attribute value.
-      #
-      # @since 2.4.2
       def validate_each(document, attribute, value)
         field = document.fields[document.database_field_name(attribute)]
         if field.try(:localized?) && !value.blank?