mongoid 7.2.1 → 9.0.0

data/lib/mongoid/timestamps/created.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require "mongoid/timestamps/created/short"
 
@@ -24,9 +24,9 @@ module Mongoid
       #   person.set_created_at
       def set_created_at
         if !timeless? && !created_at
-          time = Time.now.utc
-          self.updated_at = time if is_a?(Updated) && !updated_at_changed?
-          self.created_at = time
+          now = Time.current
+          self.updated_at = now if is_a?(Updated) && !updated_at_changed?
+          self.created_at = now
         end
         clear_timeless_option
       end

data/lib/mongoid/timestamps/short.rb

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

data/lib/mongoid/timestamps/timeless.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Timestamps
@@ -15,8 +15,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,13 +30,15 @@ module Mongoid
       #   person.timeless.save
       #
       # @return [ Document ] The document this was called on.
-      #
-      # @since 2.3.0
       def timeless
         self.class.timeless
         self
       end
 
+      # Returns whether the document should skip timestamping.
+      #
+      # @return [ true | false ] Whether the document should
+      #   skip timestamping.
       def timeless?
         self.class.timeless?
       end
@@ -46,6 +46,12 @@ module Mongoid
       class << self
         extend Forwardable
 
+        # Returns the in-memory thread cache of classes
+        # for which to skip timestamping.
+        #
+        # @return [ Hash ] The timeless table.
+        #
+        # @api private
         def timeless_table
           Thread.current['[mongoid]:timeless'] ||= Hash.new
         end
@@ -63,8 +69,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
@@ -73,6 +77,9 @@ module Mongoid
           self
         end
 
+        # Removes the timeless option on the current class.
+        #
+        # @return [ true ] Always true.
         def clear_timeless_option
           if counter = Timeless[name]
             counter -= 1
@@ -81,6 +88,10 @@ module Mongoid
           true
         end
 
+        # Sets to remove the timeless option when the next
+        # instance of the current class is updated.
+        #
+        # @return [ true ] Always true.
         def clear_timeless_option_on_update
           if counter = Timeless[name]
             counter -= 1 if self < Mongoid::Timestamps::Created
@@ -89,10 +100,21 @@ module Mongoid
           end
         end
 
+        # Clears the timeless counter for the current class
+        # if the value has reached zero.
+        #
+        # @param [ Integer ] counter The counter value.
+        #
+        # @return [ Integer | nil ] The counter value, or nil
+        #   if the counter was cleared.
         def set_timeless_counter(counter)
           Timeless[name] = (counter == 0) ? nil : counter
         end
 
+        # Returns whether the current class should skip timestamping.
+        #
+        # @return [ true | false ] Whether the current class should
+        #   skip timestamping.
         def timeless?
           !!Timeless[name]
         end

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

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

data/lib/mongoid/timestamps/updated.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require "mongoid/timestamps/updated/short"
 
@@ -25,7 +25,7 @@ module Mongoid
       #   person.set_updated_at
       def set_updated_at
         if able_to_set_updated_at?
-          self.updated_at = Time.now.utc unless updated_at_changed?
+          self.updated_at = Time.current unless updated_at_changed?
         end
 
         clear_timeless_option
@@ -36,9 +36,7 @@ module Mongoid
       # @example Can the timestamp be set?
       #   document.able_to_set_updated_at?
       #
-      # @return [ true, false ] If the timestamp can be set.
-      #
-      # @since 2.4.0
+      # @return [ true | false ] If the timestamp can be set.
       def able_to_set_updated_at?
         !frozen? && !timeless? && (new_record? || changed?)
       end

data/lib/mongoid/timestamps.rb

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

data/lib/mongoid/touchable.rb

@@ -1,11 +1,38 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
+
+  # Mixin module which is included in Mongoid::Document to add "touch"
+  # functionality to update a document's timestamp(s) atomically.
   module Touchable
 
+    # Used to provide mixin functionality.
+    #
+    # @todo Refactor using ActiveSupport::Concern
     module InstanceMethods
 
+      # Suppresses the invocation of touch callbacks, for the class that
+      # includes this module, for the duration of the block.
+      #
+      # @example Suppress touch callbacks on Person documents:
+      #   person.suppress_touch_callbacks { ... }
+      #
+      # @api private
+      def suppress_touch_callbacks
+        Touchable.suppress_touch_callbacks(self.class.name) { yield }
+      end
+
+      # Queries whether touch callbacks are being suppressed for the class
+      # that includes this module.
+      #
+      # @return [ true | false ] Whether touch callbacks are suppressed.
+      #
+      # @api private
+      def touch_callbacks_suppressed?
+        Touchable.touch_callbacks_suppressed?(self.class.name)
+      end
+
       # Touch the document, in effect updating its updated_at timestamp and
       # optionally the provided field to the current time. If any belongs_to
       # associations exist with a touch option, they will be updated as well.
@@ -20,24 +47,96 @@ 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
+      # @return [ true/false ] false if document is new_record otherwise true.
       def touch(field = nil)
         return false if _root.new_record?
-        current = Time.now
-        field = database_field_name(field)
-        write_attribute(:updated_at, current) if respond_to?("updated_at=")
-        write_attribute(field, current) if field
 
-        touches = touch_atomic_updates(field)
-        unless touches["$set"].blank?
-          selector = atomic_selector
-          _root.collection.find(selector).update_one(positionally(selector, touches), session: _session)
+        begin
+          touches = _gather_touch_updates(Time.current, field)
+          _root.send(:persist_atomic_operations, '$set' => touches) if touches.present?
+          _run_touch_callbacks_from_root
+        ensure
+          _clear_touch_updates(field)
         end
-        run_callbacks(:touch)
+
         true
       end
+
+      # Recursively sets touchable fields on the current document and each of its
+      # parents, including the root node. Returns the combined atomic $set
+      # operations to be performed on the root document.
+      #
+      # @param [ Time ] now The timestamp used for synchronizing the touched time.
+      # @param [ Symbol ] field The name of an additional field to update.
+      #
+      # @return [ Hash<String, Time> ] The touch operations to perform as an atomic $set.
+      #
+      # @api private
+      def _gather_touch_updates(now, field = nil)
+        return if touch_callbacks_suppressed?
+
+        field = database_field_name(field)
+
+        write_attribute(:updated_at, now) if respond_to?("updated_at=")
+        write_attribute(field, now) if field
+
+        touches = _extract_touches_from_atomic_sets(field) || {}
+        touches.merge!(_parent._gather_touch_updates(now) || {}) if _touchable_parent?
+        touches
+      end
+
+      # Clears changes for the model caused by touch operation.
+      #
+      # @param [ Symbol ] field The name of an additional field to update.
+      #
+      # @api private
+      def _clear_touch_updates(field = nil)
+        remove_change(:updated_at)
+        remove_change(field) if field
+        _parent._clear_touch_updates if _touchable_parent?
+      end
+
+      # Recursively runs :touch callbacks for the document and its parents,
+      # beginning with the root document and cascading through each successive
+      # child document.
+      #
+      # @api private
+      def _run_touch_callbacks_from_root
+        return if touch_callbacks_suppressed?
+        _parent._run_touch_callbacks_from_root if _touchable_parent?
+        run_callbacks(:touch)
+      end
+
+      # Indicates whether the parent exists and is touchable.
+      #
+      # @api private
+      def _touchable_parent?
+        _parent && _association&.inverse_association&.touchable?
+      end
+
+      private
+
+      # Extract and remove the atomic updates for the touch operation(s)
+      # from the currently enqueued atomic $set operations.
+      #
+      # @param [ Symbol ] field The optional field.
+      #
+      # @return [ Hash ] The field-value pairs to update atomically.
+      #
+      # @api private
+      def _extract_touches_from_atomic_sets(field = nil)
+        updates = atomic_updates['$set']
+        return {} unless updates
+
+        touchable_keys = Set['updated_at', 'u_at']
+        touchable_keys << field.to_s if field.present?
+
+        updates.keys.each_with_object({}) do |key, touches|
+          if touchable_keys.include?(key.split('.').last)
+            touches[key] = updates.delete(key)
+          end
+        end
+      end
     end
 
     extend self
@@ -48,23 +147,57 @@ module Mongoid
     # @example Add the touchable.
     #   Model.define_touchable!(assoc)
     #
-    # @param [ Association ] association The association metadata.
+    # @param [ Mongoid::Association::Relatable ] 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)
       association.inverse_class.tap do |klass|
         klass.after_save method_name
         klass.after_destroy method_name
-        klass.after_touch method_name
+
+        # Embedded docs handle touch updates recursively within
+        # the #touch method itself
+        klass.after_touch method_name unless association.embedded?
       end
     end
 
+    # Suppresses touch callbacks for the named class, for the duration of
+    # the associated block.
+    #
+    # @api private
+    def suppress_touch_callbacks(name)
+      save, touch_callback_statuses[name] = touch_callback_statuses[name], true
+      yield
+    ensure
+      touch_callback_statuses[name] = save
+    end
+
+    # Queries whether touch callbacks are being suppressed for the named
+    # class.
+    #
+    # @return [ true | false ] Whether touch callbacks are suppressed.
+    #
+    # @api private
+    def touch_callbacks_suppressed?(name)
+      touch_callback_statuses[name]
+    end
+
     private
 
+    # The key to use to store the active touch callback suppression statuses
+    SUPPRESS_TOUCH_CALLBACKS_KEY = "[mongoid]:suppress-touch-callbacks"
+
+    # Returns a hash to be used to store and query the various touch callback
+    # suppression statuses for different classes.
+    #
+    # @return [ Hash ] The hash that contains touch callback suppression
+    #   statuses
+    def touch_callback_statuses
+      Thread.current[SUPPRESS_TOUCH_CALLBACKS_KEY] ||= {}
+    end
+
     # Define the method that will get called for touching belongs_to
     # associations.
     #
@@ -75,9 +208,7 @@ module Mongoid
     #   Model.define_relation_touch_method(:band, :band_updated_at)
     #
     # @param [ Symbol ] name The name of the association.
-    # @param [ Association ] association The association metadata.
-    #
-    # @since 3.1.0
+    # @param [ Mongoid::Association::Relatable ] association The association metadata.
     #
     # @return [ Symbol ] The method name.
     def define_relation_touch_method(name, association)
@@ -87,19 +218,14 @@ module Mongoid
                            [ association.relation_class ]
                          end
 
-      relation_classes.each { |c| c.send(:include, InstanceMethods) }
       method_name = "touch_#{name}_after_create_or_destroy"
       association.inverse_class.class_eval do
         define_method(method_name) do
           without_autobuild do
-            if relation = __send__(name)
-              if association.touch_field
-                # Note that this looks up touch_field at runtime, rather than
-                # at method definition time.
-                relation.touch association.touch_field
-              else
-                relation.touch
-              end
+            if !touch_callbacks_suppressed? && relation = __send__(name)
+              # This looks up touch_field at runtime, rather than at method definition time.
+              # If touch_field is nil, it will only touch the default field (updated_at).
+              relation.touch(association.touch_field)
             end
           end
         end