MONGOID-4403 Support Dirty Tracking changed from/to (#5432)

* MONGOID-4403 Support Dirty Tracking changed from/to

* Apply suggestions from code review

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

* MONGOID-4403 add false example

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

Author: neilshweky

docs/release-notes/mongoid-8.1.txt

@@ -116,3 +116,32 @@ from the ``_translations`` hash:
 
 See the section on :ref:`Localize :present Field Option <present-fields>` for
 more details on how these are used.
+
+
+Added ``:to`` and ``:from`` options to ``attribute_changed?``
+-------------------------------------------------------------
+
+Mongoid 8.1 adds the ``:to`` and ``:from`` options on the ``attribute_changed?``
+method. These options can be used to inquire whether the attribute has been changed
+to or from a certain value:
+
+.. code:
+
+  class Person
+    include Mongoid::Document
+    field :name, type: String
+  end
+
+  person = Person.create!(name: "Trout")
+  person.name = "Ohtani"
+
+  person.name_changed?
+  # => true
+  person.name_changed?(from: "Trout")
+  # => true
+  person.name_changed?(to: "Ohtani")
+  # => true
+  person.name_changed?(from: "Trout", to: "Ohtani")
+  # => true
+  person.name_changed?(from: "Trout", to: "Fletcher")
+  # => false

lib/mongoid/changeable.rb

@@ -161,12 +161,24 @@ def attribute_change(attr)
     #   model.attribute_changed?("name")
     #
     # @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.
-    def attribute_changed?(attr)
+    def attribute_changed?(attr, **kwargs)
       attr = database_field_name(attr)
       return false unless changed_attributes.key?(attr)
-      changed_attributes[attr] != attributes[attr]
+      return false if changed_attributes[attr] == attributes[attr]
+      if kwargs.key?(:from)
+        return false if changed_attributes[attr] != kwargs[:from]
+      end
+      if kwargs.key?(:to)
+        return false if attributes[attr] != kwargs[:to]
+      end
+
+      true
     end
 
     # Get whether or not the field has a different value from the default.
@@ -302,8 +314,8 @@ def create_dirty_change_accessor(name, meth)
       # @param [ String ] meth The name of the accessor.
       def create_dirty_change_check(name, meth)
         generated_methods.module_eval do
-          re_define_method("#{meth}_changed?") do
-            attribute_changed?(name)
+          re_define_method("#{meth}_changed?") do |**kwargs|
+            attribute_changed?(name, **kwargs)
           end
         end
       end

spec/mongoid/changeable_spec.rb

@@ -476,6 +476,188 @@
         end
       end
     end
+
+    context "when including key word args" do
+
+      let(:person) { Person.new }
+
+      context "when only including from" do
+
+        context "when the object has not changed" do
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, from: nil)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil)).to be false
+          end
+        end
+
+        context "when the object has changed from the wrong item" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, from: 1)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(from: 1)).to be false
+          end
+        end
+
+        context "when the object has changed from the correct item" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns true" do
+            expect(person.send(:attribute_changed?, :score, from: nil)).to be true
+          end
+
+          it "returns true using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil)).to be true
+          end
+        end
+      end
+
+      context "when only including to" do
+
+        context "when the object has not changed" do
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, to: nil)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(to: nil)).to be false
+          end
+        end
+
+        context "when the object has changed to the wrong item" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, to: 1)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(to: 1)).to be false
+          end
+        end
+
+        context "when the object has changed to the correct item" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns true" do
+            expect(person.send(:attribute_changed?, :score, to: 2)).to be true
+          end
+
+          it "returns true using (attribute)_changed?" do
+            expect(person.score_changed?(to: 2)).to be true
+          end
+        end
+      end
+
+      context "when including from and to" do
+
+        context "when the object has not changed" do
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, from: nil, to: nil)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil, to: nil)).to be false
+          end
+        end
+
+        context "when only the from is correct" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, from: nil, to: 3)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil, to: 3)).to be false
+          end
+        end
+
+        context "when only the to is correct" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns false" do
+            expect(person.send(:attribute_changed?, :score, from: 1, to: 2)).to be false
+          end
+
+          it "returns false using (attribute)_changed?" do
+            expect(person.score_changed?(from: 1, to: 2)).to be false
+          end
+        end
+
+        context "when the from and to are correct" do
+
+          before do
+            person.score = 2
+          end
+
+          it "returns true" do
+            expect(person.send(:attribute_changed?, :score, from: nil, to: 2)).to be true
+          end
+
+          it "returns true using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil, to: 2)).to be true
+          end
+        end
+
+        context "when value is mongoized" do
+
+          before do
+            person.score = "2"
+          end
+
+          it "returns true with mongoized value" do
+            expect(person.send(:attribute_changed?, :score, from: nil, to: 2)).to be true
+          end
+
+          it "returns true with mongoized value using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil, to: 2)).to be true
+          end
+        end
+
+        context "when value is mongoized" do
+
+          before do
+            person.score = "2"
+          end
+
+          it "returns false with unmongoized value" do
+            expect(person.send(:attribute_changed?, :score, from: nil, to: "2")).to be false
+          end
+
+          it "returns false with unmongoized value using (attribute)_changed?" do
+            expect(person.score_changed?(from: nil, to: "2")).to be false
+          end
+        end
+      end
+    end
   end
 
   describe "#attribute_changed_from_default?" do