MONGOID-4528 Add more dirty methods (#5440)

Co-authored-by: Oleg Pudeyev <39304720+p-mongo@users.noreply.github.com>

Author: comandeo-mongo

docs/release-notes/mongoid-8.1.txt

@@ -17,6 +17,74 @@ The complete list of releases is available `on GitHub
 please consult GitHub releases for detailed release notes and JIRA for
 the complete list of issues fixed in each release, including bug fixes.
 
+Added ``attribute_before_last_save``, ``saved_change_to_attribute``, ``saved_change_to_attribute?``, and ``will_save_change_to_attribute?``  methods
+----------------------------------------------------------------------------------------------------------------------------------------------------
+
+These new methods behave identically to corresponding methods
+from ``ActiveRecord::AttributeMethods::Dirty``. The methods are particularly useful in
+callbacks:
+
+.. code-block:: ruby
+
+  class Person
+    include Mongoid::Document
+
+    field :name, type: String
+
+    before_save do
+      puts "attribute_was(:name): #{attribute_was(:name)}"
+      puts "attribute_before_last_save(:name): #{attribute_before_last_save(:name)}"
+      puts "will_save_change_to_attribute?(:name): #{will_save_change_to_attribute?(:name)}"
+    end
+
+    after_save do
+      puts "attribute_was(:name): #{attribute_was(:name)}"
+      puts "attribute_before_last_save(:name): #{attribute_before_last_save(:name)}"
+      puts "saved_change_to_attribute(:name): #{saved_change_to_attribute(:name)}"
+      puts "attribute_changed?(:name): #{attribute_changed?(:name)}"
+      puts "saved_change_to_attribute?(:name): #{saved_change_to_attribute?(:name)}"
+    end
+  end
+
+  person = Person.create(name: 'John')
+  #
+  # before_save
+  #
+  ## attribute_was(:name): nil
+  ## attribute_before_last_save(:name): nil
+  ## will_save_change_to_attribute?(:name): true
+  #
+  # after_save
+  #
+  ## attribute_was(:name): John => New value
+  ## attribute_before_last_save(:name): nil => Value before save
+  ## saved_change_to_attribute(:name): [nil, "John"] => Both values
+  ## attribute_changed?(:name): false
+  ## saved_change_to_attribute?(:name): true => Correctly indicates that the change for :name was saved
+
+  person.name = 'Jane'
+  person.save
+  #
+  # before_save
+  #
+  ## attribute_was(:name): John => attribute_was not look back before the last save
+  ## attribute_before_last_save(:name): nil => value before the last save
+  ## will_save_change_to_attribute?(:name): true
+  #
+  # after_save
+  #
+  ## attribute_was(:name): Jane => New value
+  ## attribute_before_last_save(:name): John => Value before save
+  ## saved_change_to_attribute(:name): ["John", "Jane"] => Both values
+  ## attribute_changed?(:name): false
+  ## saved_change_to_attribute?(:name): true => Correctly indicates that the change for :name was saved
+
+For all of the new methods there are also shorter forms created dynamically, e.g.
+``attribute_before_last_save(:name)`` is equivalent to ``name_before_last_save``,
+``saved_change_to_attribute(:name)`` is equivalent to ``saved_change_to_name``,
+``saved_change_to_attribute?(:name)`` is equivalent to ``saved_change_to_name?``,
+and ``will_save_change_to_attribute?(:name)`` is equivalent to ``will_save_change_to_name?``.
+
 
 Configuration DSL No Longer Requires an Argument to its Block
 -------------------------------------------------------------

lib/mongoid/changeable.rb

@@ -68,7 +68,9 @@ def changes
     # @example Move the changes to previous.
     #   person.move_changes
     def move_changes
+      @changes_before_last_save = @previous_changes
       @previous_changes = changes
+      @attributes_before_last_save = @previous_attributes
       @previous_attributes = attributes.dup
       Atomic::UPDATES.each do |update|
         send(update).clear
@@ -133,6 +135,72 @@ def setters
       mods
     end
 
+    # Returns the original value of an attribute before the last save.
+    #
+    # This method is useful in after callbacks to get the original value of
+    #   an attribute before the save that triggered the callbacks to run.
+    #
+    # @param [ Symbol | String ] attr The name of the attribute.
+    #
+    # @return [ Object ] Value of the attribute before the last save.
+    def attribute_before_last_save(attr)
+      attr = database_field_name(attr)
+      attributes_before_last_save[attr]
+    end
+
+    # Returns the change to an attribute during the last save.
+    #
+    # @param [ Symbol | String ] attr The name of the attribute.
+    #
+    # @return [ Array<Object> | nil ] If the attribute was changed, returns
+    #   an array containing the original value and the saved value, otherwise nil.
+    def saved_change_to_attribute(attr)
+      attr = database_field_name(attr)
+      previous_changes[attr]
+    end
+
+    # Returns whether this attribute changed during the last save.
+    #
+    # This method is useful in after callbacks, to see the change
+    #   in an attribute during the save that triggered the callbacks to run.
+    #
+    # @param [ String ] attr The name of the attribute.
+    # @param **kwargs The optional keyword arguments.
+    #
+    # @option **kwargs [ Object ] :from The object the attribute was changed from.
+    # @option **kwargs [ Object ] :to The object the attribute was changed to.
+    #
+    # @return [ true | false ] Whether the attribute has changed during the last save.
+    def saved_change_to_attribute?(attr, **kwargs)
+      changes = saved_change_to_attribute(attr)
+      return false unless changes.is_a?(Array)
+      if kwargs.key?(:from) && kwargs.key?(:to)
+        changes.first == kwargs[:from] && changes.last == kwargs[:to]
+      elsif kwargs.key?(:from)
+        changes.first == kwargs[:from]
+      elsif kwargs.key?(:to)
+        changes.last == kwargs[:to]
+      else
+        true
+      end
+    end
+
+    # Returns whether this attribute change the next time we save.
+    #
+    # This method is useful in validations and before callbacks to determine
+    #   if the next call to save will change a particular attribute.
+    #
+    # @param [ String ] attr The name of the attribute.
+    # @param **kwargs The optional keyword arguments.
+    #
+    # @option **kwargs [ Object ] :from The object the attribute was changed from.
+    # @option **kwargs [ Object ] :to The object the attribute was changed to.
+    #
+    # @return [ true | false ] Whether the attribute change the next time we save.
+    def will_save_change_to_attribute?(attr, **kwargs)
+      attribute_changed?(attr, **kwargs)
+    end
+
     private
 
     # Get attributes of the document before the document was saved.
@@ -142,6 +210,14 @@ def previous_attributes
       @previous_attributes ||= {}
     end
 
+    def changes_before_last_save
+      @changes_before_last_save ||= {}
+    end
+
+    def attributes_before_last_save
+      @attributes_before_last_save ||= {}
+    end
+
     # Get the old and new value for the provided attribute.
     #
     # @example Get the attribute change.
@@ -317,6 +393,9 @@ def create_dirty_change_check(name, meth)
           re_define_method("#{meth}_changed?") do |**kwargs|
             attribute_changed?(name, **kwargs)
           end
+          re_define_method("will_save_change_to_#{meth}?") do |**kwargs|
+            will_save_change_to_attribute?(name, **kwargs)
+          end
         end
       end
 
@@ -350,6 +429,15 @@ def create_dirty_previous_value_accessor(name, meth)
           re_define_method("#{meth}_previously_was") do
             attribute_previously_was(name)
           end
+          re_define_method("#{meth}_before_last_save") do
+            attribute_before_last_save(name)
+          end
+          re_define_method("saved_change_to_#{meth}") do
+            saved_change_to_attribute(name)
+          end
+          re_define_method("saved_change_to_#{meth}?") do |**kwargs|
+            saved_change_to_attribute?(name, **kwargs)
+          end
         end
       end
 

spec/integration/callbacks_spec.rb

@@ -447,4 +447,111 @@ class PreviouslyPersistedPerson
       expect(saved_person.previously_persisted_value).to be_truthy
     end
   end
+
+  context 'saved_change_to_attribute, attribute_before_last_save, will_save_change_to_attribute' do
+    class TestSCTAAndABLSInCallbacks
+      include Mongoid::Document
+
+      field :name, type: String
+      field :age, type: Integer
+
+      set_callback :save, :before do |doc|
+        [:name, :age].each do |attr|
+          saved_change_to_attribute_values_before[attr] += [saved_change_to_attribute(attr)]
+          attribute_before_last_save_values_before[attr] += [attribute_before_last_save(attr)]
+          will_save_change_to_attribute_values_before[attr] += [will_save_change_to_attribute?(attr)]
+        end
+      end
+
+      set_callback :save, :after do |doc|
+        [:name, :age].each do |attr|
+          saved_change_to_attribute_values_after[attr] += [saved_change_to_attribute(attr)]
+          saved_change_to_attribute_q_values_after[attr] += [saved_change_to_attribute?(attr)]
+          attribute_before_last_save_values_after[attr] += [attribute_before_last_save(attr)]
+        end
+      end
+
+      def saved_change_to_attribute_values_before
+        @saved_change_to_attribute_values_before ||= Hash.new do
+          []
+        end
+      end
+
+      def attribute_before_last_save_values_before
+        @attribute_before_last_save_values_before ||= Hash.new do
+          []
+        end
+      end
+
+      def saved_change_to_attribute_values_after
+        @saved_change_to_attribute_values_after ||= Hash.new do
+          []
+        end
+      end
+
+      def saved_change_to_attribute_q_values_after
+        @saved_change_to_attribute_q_values_after ||= Hash.new do
+          []
+        end
+      end
+
+      def attribute_before_last_save_values_after
+        @attribute_before_last_save_values_after ||= Hash.new do
+          []
+        end
+      end
+
+      def will_save_change_to_attribute_values_before
+        @will_save_change_to_attribute_values_before ||= Hash.new do
+          []
+        end
+      end
+    end
+
+    it 'reproduces ActiveRecord::AttributeMethods::Dirty behavior' do
+      subject = TestSCTAAndABLSInCallbacks.new(name: 'Name 1')
+      subject.save!
+      subject.age = 18
+      subject.save!
+      subject.name = 'Name 2'
+      subject.save!
+
+      expect(subject.saved_change_to_attribute_values_before).to eq(
+        {
+          :name => [nil, [nil, "Name 1"], nil],
+          :age => [nil, nil, [nil, 18]],
+        }
+      )
+      expect(subject.saved_change_to_attribute_values_after).to eq(
+        {
+          :name => [[nil, "Name 1"], nil, ["Name 1", "Name 2"]],
+          :age => [nil, [nil, 18], nil],
+        }
+      )
+      expect(subject.saved_change_to_attribute_q_values_after).to eq(
+        {
+          :name => [true, false, true],
+          :age => [false, true, false],
+        }
+      )
+      expect(subject.attribute_before_last_save_values_before).to eq(
+        {
+          :name => [nil, nil, "Name 1"],
+          :age => [nil, nil, nil]
+        }
+      )
+      expect(subject.attribute_before_last_save_values_after).to eq(
+        {
+          :name => [nil, "Name 1", "Name 1"],
+          :age => [nil, nil, 18]
+        }
+      )
+      expect(subject.will_save_change_to_attribute_values_before).to eq(
+        {
+          :name => [true, false, true],
+          :age => [false, true, false]
+        }
+      )
+    end
+  end
 end