mongoid 7.3.5 → 7.4.0

data/lib/mongoid/threaded.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/threaded/lifecycle"
 
@@ -12,18 +11,12 @@ module Mongoid
     DATABASE_OVERRIDE_KEY = "[mongoid]:db-override"
 
     # Constant for the key to store clients.
-    #
-    # @since 5.0.0
     CLIENTS_KEY = "[mongoid]:clients"
 
     # The key to override the client.
-    #
-    # @since 5.0.0
     CLIENT_OVERRIDE_KEY = "[mongoid]:client-override"
 
     # The key for the current thread's scope stack.
-    #
-    # @since 2.0.0
     CURRENT_SCOPE_KEY = "[mongoid]:current-scope"
 
     AUTOSAVES_KEY = "[mongoid]:autosaves"
@@ -43,8 +36,6 @@ module Mongoid
     # @param [ String ] name The name of the stack
     #
     # @return [ true ] True.
-    #
-    # @since 2.4.0
     def begin_execution(name)
       stack(name).push(true)
     end
@@ -55,8 +46,6 @@ module Mongoid
     #   Threaded.database_override
     #
     # @return [ String, Symbol ] The override.
-    #
-    # @since 3.0.0
     def database_override
       Thread.current[DATABASE_OVERRIDE_KEY]
     end
@@ -69,8 +58,6 @@ module Mongoid
     # @param [ String, Symbol ] name The global override name.
     #
     # @return [ String, Symbol ] The override.
-    #
-    # @since 3.0.0
     def database_override=(name)
       Thread.current[DATABASE_OVERRIDE_KEY] = name
     end
@@ -83,8 +70,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the stack
     #
     # @return [ true ] If the stack is being executed.
-    #
-    # @since 2.4.0
     def executing?(name)
       !stack(name).empty?
     end
@@ -97,8 +82,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the stack
     #
     # @return [ true ] True.
-    #
-    # @since 2.4.0
     def exit_execution(name)
       stack(name).pop
     end
@@ -111,8 +94,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the stack
     #
     # @return [ Array ] The stack.
-    #
-    # @since 2.4.0
     def stack(name)
       Thread.current[STACK_KEYS[name]] ||= []
     end
@@ -123,8 +104,6 @@ module Mongoid
     #   Threaded.begin_autosave(doc)
     #
     # @param [ Document ] document The document to autosave.
-    #
-    # @since 3.0.0
     def begin_autosave(document)
       autosaves_for(document.class).push(document._id)
     end
@@ -135,8 +114,6 @@ module Mongoid
     #   Threaded.begin_validate(doc)
     #
     # @param [ Document ] document The document to validate.
-    #
-    # @since 2.1.9
     def begin_validate(document)
       validations_for(document.class).push(document._id)
     end
@@ -147,8 +124,6 @@ module Mongoid
     #   Threaded.exit_autosave(doc)
     #
     # @param [ Document ] document The document to autosave.
-    #
-    # @since 3.0.0
     def exit_autosave(document)
       autosaves_for(document.class).delete_one(document._id)
     end
@@ -159,8 +134,6 @@ module Mongoid
     #   Threaded.exit_validate(doc)
     #
     # @param [ Document ] document The document to validate.
-    #
-    # @since 2.1.9
     def exit_validate(document)
       validations_for(document.class).delete_one(document._id)
     end
@@ -195,8 +168,6 @@ module Mongoid
     #   Threaded.client_override
     #
     # @return [ String, Symbol ] The override.
-    #
-    # @since 5.0.0
     def client_override
       Thread.current[CLIENT_OVERRIDE_KEY]
     end
@@ -209,8 +180,6 @@ module Mongoid
     # @param [ String, Symbol ] name The global override name.
     #
     # @return [ String, Symbol ] The override.
-    #
-    # @since 3.0.0
     def client_override=(name)
       Thread.current[CLIENT_OVERRIDE_KEY] = name
     end
@@ -224,8 +193,6 @@ module Mongoid
     # @param [ Klass ] klass The class type of the scope.
     #
     # @return [ Criteria ] The scope.
-    #
-    # @since 5.0.0
     def current_scope(klass = nil)
       if klass && Thread.current[CURRENT_SCOPE_KEY].respond_to?(:keys)
         Thread.current[CURRENT_SCOPE_KEY][
@@ -244,8 +211,6 @@ module Mongoid
     # @param [ Criteria ] scope The current scope.
     #
     # @return [ Criteria ] The scope.
-    #
-    # @since 5.0.0
     def current_scope=(scope)
       Thread.current[CURRENT_SCOPE_KEY] = scope
     end
@@ -259,8 +224,6 @@ module Mongoid
     # @param [ Class ] klass The current model class.
     #
     # @return [ Criteria ] The scope.
-    #
-    # @since 5.0.1
     def set_current_scope(scope, klass)
       if scope.nil?
         if Thread.current[CURRENT_SCOPE_KEY]
@@ -293,8 +256,6 @@ module Mongoid
     # @param [ Document ] document The document to check.
     #
     # @return [ true, false ] If the document is autosaved.
-    #
-    # @since 2.1.9
     def autosaved?(document)
       autosaves_for(document.class).include?(document._id)
     end
@@ -307,8 +268,6 @@ module Mongoid
     # @param [ Document ] document The document to check.
     #
     # @return [ true, false ] If the document is validated.
-    #
-    # @since 2.1.9
     def validated?(document)
       validations_for(document.class).include?(document._id)
     end
@@ -319,8 +278,6 @@ module Mongoid
     #   Threaded.autosaves
     #
     # @return [ Hash ] The current autosaves.
-    #
-    # @since 3.0.0
     def autosaves
       Thread.current[AUTOSAVES_KEY] ||= {}
     end
@@ -331,8 +288,6 @@ module Mongoid
     #   Threaded.validations
     #
     # @return [ Hash ] The current validations.
-    #
-    # @since 2.1.9
     def validations
       Thread.current[VALIDATIONS_KEY] ||= {}
     end
@@ -345,8 +300,6 @@ module Mongoid
     # @param [ Class ] klass The class to check.
     #
     # @return [ Array ] The current autosaves.
-    #
-    # @since 3.0.0
     def autosaves_for(klass)
       autosaves[klass] ||= []
     end
@@ -358,8 +311,6 @@ module Mongoid
     # @param [ Class ] klass The class to check.
     #
     # @return [ Array ] The current validations.
-    #
-    # @since 2.1.9
     def validations_for(klass)
       validations[klass] ||= []
     end
@@ -370,8 +321,6 @@ module Mongoid
     #   Threaded.set_session(session)
     #
     # @param [ Mongo::Session ] session The session to save.
-    #
-    # @since 6.4.0
     def set_session(session)
       Thread.current[:session] = session
     end
@@ -382,8 +331,6 @@ module Mongoid
     #   Threaded.get_session
     #
     # @return [ Mongo::Session, nil ] The session cached on this thread or nil.
-    #
-    # @since 6.4.0
     def get_session
       Thread.current[:session]
     end
@@ -394,8 +341,6 @@ module Mongoid
     #   Threaded.clear_session
     #
     # @return [ nil ]
-    #
-    # @since 6.4.0
     def clear_session
       session = get_session
       session.end_session if session

data/lib/mongoid/timestamps/created/short.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Timestamps

data/lib/mongoid/timestamps/created.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/timestamps/created/short"
 

data/lib/mongoid/timestamps/short.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Timestamps

data/lib/mongoid/timestamps/timeless.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Timestamps
@@ -15,8 +14,6 @@ module Mongoid
       #   document.clear_timeless_option
       #
       # @return [ true ] True.
-      #
-      # @since 3.1.4
       def clear_timeless_option
         if self.persisted?
           self.class.clear_timeless_option_on_update
@@ -32,8 +29,6 @@ module Mongoid
       #   person.timeless.save
       #
       # @return [ Document ] The document this was called on.
-      #
-      # @since 2.3.0
       def timeless
         self.class.timeless
         self
@@ -63,8 +58,6 @@ module Mongoid
         #   Person.timeless.create(:title => "Sir")
         #
         # @return [ Class ] The class this was called on.
-        #
-        # @since 2.3.0
         def timeless
           counter = 0
           counter += 1 if self < Mongoid::Timestamps::Created

data/lib/mongoid/timestamps/updated/short.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Timestamps

data/lib/mongoid/timestamps/updated.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/timestamps/updated/short"
 
@@ -37,8 +36,6 @@ module Mongoid
       #   document.able_to_set_updated_at?
       #
       # @return [ true, false ] If the timestamp can be set.
-      #
-      # @since 2.4.0
       def able_to_set_updated_at?
         !frozen? && !timeless? && (new_record? || changed?)
       end

data/lib/mongoid/timestamps.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/timestamps/timeless"
 require "mongoid/timestamps/created"

data/lib/mongoid/touchable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Touchable
@@ -21,8 +20,6 @@ module Mongoid
       # @param [ Symbol ] field The name of an additional field to update.
       #
       # @return [ true/false ] false if record is new_record otherwise true.
-      #
-      # @since 3.0.0
       def touch(field = nil)
         return false if _root.new_record?
         current = Time.now
@@ -80,8 +77,6 @@ module Mongoid
     # @param [ Association ] association The association metadata.
     #
     # @return [ Class ] The model class.
-    #
-    # @since 3.0.0
     def define_touchable!(association)
       name = association.name
       method_name = define_relation_touch_method(name, association)
@@ -106,8 +101,6 @@ module Mongoid
     # @param [ Symbol ] name The name of the association.
     # @param [ Association ] association The association metadata.
     #
-    # @since 3.1.0
-    #
     # @return [ Symbol ] The method name.
     def define_relation_touch_method(name, association)
       relation_classes = if association.polymorphic?

data/lib/mongoid/traversable.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/fields/validators/macro"
 
 module Mongoid
 
   # Provides behavior around traversing the document graph.
-  #
-  # @since 4.0.0
   module Traversable
     extend ActiveSupport::Concern
 
@@ -66,7 +63,7 @@ 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
@@ -118,53 +115,82 @@ 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
+      @__children ||= collect_children
+    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
+      @__descendants ||= collect_descendants
     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
+          if child
+            children += Array.wrap(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 = []
+      expanded = {}
+      embedded_relations.each_pair do |name, association|
+        without_autobuild do
+          child = send(name)
+          if child
+            to_expand += Array.wrap(child)
+          end
+        end
+      end
+      until to_expand.empty?
+        expanding = to_expand
+        to_expand = []
+        expanding.each do |child|
+          next if expanded[child]
+          expanded[child] = true
+          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
@@ -201,8 +227,6 @@ 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?
@@ -213,37 +237,28 @@ module Mongoid
       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
+    # @api private
+    def _reset_memoized_descendants!
+      _parent._reset_memoized_descendants! if _parent
       @__children = nil
+      @__descendants = nil
     end
 
     # Return the root document in the object graph. If the current document
@@ -265,8 +280,6 @@ module Mongoid
     #   document._root?
     #
     # @return [ true, false ] If the document is the root.
-    #
-    # @since 3.1.0
     def _root?
       _parent ? false : true
     end
@@ -291,8 +304,6 @@ module Mongoid
       #   Person.inherited(Doctor)
       #
       # @param [ Class ] subclass The inheriting class.
-      #
-      # @since 2.0.0.rc.6
       def inherited(subclass)
         super
         @_type = nil
@@ -305,7 +316,7 @@ module Mongoid
         subclass.discriminator_value = subclass.name
 
         # We need to do this here because the discriminator_value method is
-        # overriden in the subclass above.
+        # overridden in the subclass above.
         class << subclass
           include DiscriminatorRetrieval
         end

data/lib/mongoid/validatable/associated.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Validatable
@@ -28,8 +27,6 @@ module Mongoid
       # @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

data/lib/mongoid/validatable/format.rb

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

data/lib/mongoid/validatable/length.rb

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

data/lib/mongoid/validatable/localizable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Validatable
@@ -15,8 +14,6 @@ module Mongoid
       # @param [ Document ] document The document.
       # @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?

data/lib/mongoid/validatable/macros.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Validatable
@@ -54,8 +53,6 @@ module Mongoid
       #   end
       #
       # @param [ Array ] args The names of the fields to validate.
-      #
-      # @since 2.4.0
       def validates_format_of(*args)
         validates_with(FormatValidator, _merge_attributes(args))
       end
@@ -71,8 +68,6 @@ module Mongoid
       #   end
       #
       # @param [ Array ] args The names of the fields to validate.
-      #
-      # @since 2.4.0
       def validates_length_of(*args)
         validates_with(LengthValidator, _merge_attributes(args))
       end
@@ -88,8 +83,6 @@ module Mongoid
       #   end
       #
       # @param [ Array ] args The names of the fields to validate.
-      #
-      # @since 2.4.0
       def validates_presence_of(*args)
         validates_with(PresenceValidator, _merge_attributes(args))
       end

data/lib/mongoid/validatable/presence.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Validatable
@@ -25,8 +24,6 @@ module Mongoid
       # @param [ Document ] document The document to validate.
       # @param [ Symbol ] attribute The attribute name.
       # @param [ Object ] value The current value of the field.
-      #
-      # @since 2.4.0
       def validate_each(document, attribute, value)
         field = document.fields[document.database_field_name(attribute)]
         if field.try(:localized?) && !value.blank?
@@ -53,15 +50,13 @@ module Mongoid
       # @api private
       #
       # @example Check is the association or fk is blank.
-      #   validator.relation_or_fk_mising(doc, :name, "")
+      #   validator.relation_or_fk_missing(doc, :name, "")
       #
       # @param [ Document ] doc The document.
       # @param [ Symbol ] attr The attribute.
       # @param [ Object ] value The value.
       #
       # @return [ true, false ] If the doc is missing.
-      #
-      # @since 3.0.0
       def relation_or_fk_missing?(doc, attr, value)
         return true if value.blank? && doc.send(attr).blank?
         association = doc.relations[attr.to_s]
@@ -78,8 +73,6 @@ module Mongoid
       # @param [ Object ] value The value.
       #
       # @return [ true, false ] If the value is not present.
-      #
-      # @since 3.0.5
       def not_present?(value)
         value.blank? && value != false
       end

data/lib/mongoid/validatable/queryable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Validatable
@@ -16,8 +15,6 @@ module Mongoid
       # @param [ Document ] document The document being validated.
       #
       # @return [ Object ] The result of the yield.
-      #
-      # @since 3.0.2
       def with_query(document)
         klass = document.class
         begin