MONGOID-5217 Add _previously_was methods (#5195)

Author: comandeo-mongo

docs/release-notes/mongoid-8.0.txt

@@ -169,7 +169,7 @@ Mongoid 8.0 behavior:
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).
     any_of({members: 2}, {last_tour: 1995})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990}],
   #     "$and"=>[{"$or"=>[{"members"=>2}, {"last_tour"=>1995}]}]}
@@ -178,7 +178,7 @@ Mongoid 8.0 behavior:
   #   embedded: false>
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).any_of({members: 2})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990}], "members"=>2}
   #   options:  {}
@@ -191,7 +191,7 @@ Mongoid 7 behavior:
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).
     any_of({members: 2}, {last_tour: 1995})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990},
   #     {"members"=>2}, {"last_tour"=>1995}]}
@@ -200,7 +200,7 @@ Mongoid 7 behavior:
   #   embedded: false>
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).any_of({members: 2})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990}], "members"=>2}
   #   options:  {}
@@ -248,3 +248,31 @@ Mongoid 7 output:
 
 Notice that in 7 ``attribute_was(:age)`` returns the old attribute value,
 while in 8.0 ``attribute_was(:age)`` returns the new value.
+
+``*_previously_was``, ``previously_new_record?``, and ``previously_persisted?`` helpers
+---------------------------------------------------------------------------------------
+
+Mongoid 8.0 introduces ActiveModel-compatible ``*_previously_was`` helpers,
+as well as ActiveRecord-compatible ``previously_new_record?`` and
+``previously_persisted?`` helpers:
+
+.. code-block:: ruby
+
+  class User
+    include Mongoid::Document
+
+    field :name, type: String
+    field :age, type: Integer
+  end
+
+  user = User.create!(name: 'Sam', age: 18)
+  user.previously_new_record?     # => true
+
+  user.name = "Nick"
+  user.save!
+  user.name_previously_was        # => "Sam"
+  user.age_previously_was         # => 18
+  user.previously_new_record?     # => false
+
+  user.destroy
+  user.previously_persisted?   # => true

lib/mongoid/changeable.rb

@@ -69,6 +69,7 @@ def changes
     #   person.move_changes
     def move_changes
       @previous_changes = changes
+      @previous_attributes = attributes.dup
       Atomic::UPDATES.each do |update|
         send(update).clear
       end
@@ -133,6 +134,13 @@ def setters
 
     private
 
+    # Get attributes of the document before the document was saved.
+    #
+    # @return [ Hash ] Previous attributes
+    def previous_attributes
+      @previous_attributes ||= {}
+    end
+
     # Get the old and new value for the provided attribute.
     #
     # @example Get the attribute change.
@@ -185,6 +193,25 @@ def attribute_was(attr)
       attribute_changed?(attr) ? changed_attributes[attr] : attributes[attr]
     end
 
+    # Get the previous attribute value that was changed
+    # before the document was saved.
+    #
+    # It the document has not been saved yet, or was just loaded from database,
+    # this method returns nil for all attributes.
+    #
+    # @param [ String ] attr The attribute name.
+    #
+    # @return [ Object | nil ] Attribute value before the document was saved,
+    #   or nil if the document has not been saved yet.
+    def attribute_previously_was(attr)
+      attr = database_field_name(attr)
+      if previous_changes.key?(attr)
+        previous_changes[attr].first
+      else
+        previous_attributes[attr]
+      end
+    end
+
     # Flag an attribute as going to change.
     #
     # @example Flag the attribute.
@@ -291,7 +318,7 @@ def create_dirty_default_change_check(name, meth)
         end
       end
 
-      # Creates the dirty change previous value accessor.
+      # Creates the dirty change previous value accessors.
       #
       # @example Create the accessor.
       #   Model.create_dirty_previous_value_accessor("name", "alias")
@@ -303,6 +330,9 @@ def create_dirty_previous_value_accessor(name, meth)
           re_define_method("#{meth}_was") do
             attribute_was(name)
           end
+          re_define_method("#{meth}_previously_was") do
+            attribute_previously_was(name)
+          end
         end
       end
 

lib/mongoid/persistable/updatable.rb

@@ -102,6 +102,7 @@ def prepare_update(options = {})
               _mongoid_run_child_callbacks(:save) do
                 _mongoid_run_child_callbacks(:update) do
                   result = yield(self)
+                  self.previously_new_record = false
                   post_process_persist(result, options)
                   true
                 end

lib/mongoid/reloadable.rb

@@ -27,7 +27,10 @@ def reload
       end
       @attributes = reloaded
       @attributes_before_type_cast = {}
-      changed_attributes.clear
+      @changed_attributes = {}
+      @previous_changes = {}
+      @previous_attributes = {}
+      @previously_new_record = false
       reset_readonly
       apply_defaults
       reload_relations

lib/mongoid/stateful.rb

@@ -6,7 +6,15 @@ module Mongoid
   # document can transition through.
   module Stateful
 
-    attr_writer :destroyed, :flagged_for_destroy, :new_record
+    attr_writer :destroyed, :flagged_for_destroy, :previously_new_record
+
+    def new_record=(new_value)
+      @new_record ||= false
+      if @new_record && !new_value
+        @previously_new_record = true
+      end
+      @new_record = new_value
+    end
 
     # Returns true if the +Document+ has not been persisted to the database,
     # false if it has. This is determined by the variable @new_record
@@ -20,6 +28,15 @@ def new_record?
       @new_record ||= false
     end
 
+    # Returns true if this document was just created -- that is, prior to the last
+    # save, the object didn't exist in the database and new_record? would have
+    # returned true.
+    #
+    # @return [ true, false ] True if was just created, false if not.
+    def previously_new_record?
+      @previously_new_record ||= false
+    end
+
     # Checks if the document has been saved to the database. Returns false
     # if the document has been destroyed.
     #
@@ -31,6 +48,15 @@ def persisted?
       !new_record? && !destroyed?
     end
 
+    # Checks if the document was previously saved to the database
+    # but now it has been deleted.
+    #
+    # @return [ true, false ] True if was persisted but now destroyed,
+    #   otherwise false.
+    def previously_persisted?
+      !new_record? && destroyed?
+    end
+
     # Returns whether or not the document has been flagged for deletion, but
     # not destroyed yet. Used for atomic pulls of child documents.
     #

spec/integration/callbacks_spec.rb

@@ -360,4 +360,91 @@ class CBIntSpecProfile
       expect(architect.after_remove_num_buildings).to eq(2)
     end
   end
+
+  context '_previously was methods in after_save callback' do
+    let(:title) do
+      "Title"
+    end
+
+    let(:updated_title) do
+      "Updated title"
+    end
+
+    let(:age) do
+      10
+    end
+
+    it do
+      class PreviouslyWasPerson
+        include Mongoid::Document
+
+        field :title, type: String
+        field :age, type: Integer
+
+        attr_reader :after_save_vals
+
+        set_callback :save, :after do |doc|
+          @after_save_vals ||= []
+          @after_save_vals << [doc.title_previously_was, doc.age_previously_was]
+        end
+      end
+
+      person = PreviouslyWasPerson.create!(title: title, age: age)
+      person.title = updated_title
+      person.save!
+      expect(person.after_save_vals).to eq([
+        # Field values are nil before create
+        [nil, nil],
+        [title, age]
+        ])
+    end
+  end
+
+  context 'previously_new_record? in after_save' do
+    it do
+      class PreviouslyNewRecordPerson
+        include Mongoid::Document
+
+        field :title, type: String
+        field :age, type: Integer
+
+        attr_reader :previously_new_record_value
+
+        set_callback :save, :after do |doc|
+          @previously_new_record_value = doc.previously_new_record?
+        end
+      end
+
+      person = PreviouslyNewRecordPerson.create!(title: "title", age: 55)
+      expect(person.previously_new_record_value).to be_truthy
+      person.title = "New title"
+      person.save!
+      expect(person.previously_new_record_value).to be_falsey
+    end
+  end
+
+  context 'previously_persisted? in after_destroy' do
+    it do
+      class PreviouslyPersistedPerson
+        include Mongoid::Document
+
+        field :title, type: String
+        field :age, type: Integer
+
+        attr_reader :previously_persisted_value
+
+        set_callback :destroy, :after do |doc|
+          @previously_persisted_value = doc.previously_persisted?
+        end
+      end
+
+      unsaved_person = PreviouslyPersistedPerson.new(title: "title", age: 55)
+      unsaved_person.destroy
+      expect(unsaved_person.previously_persisted_value).to be_falsey
+
+      saved_person = PreviouslyPersistedPerson.create(title: "title", age: 55)
+      saved_person.destroy
+      expect(saved_person.previously_persisted_value).to be_truthy
+    end
+  end
 end

spec/mongoid/changeable_spec.rb

@@ -555,6 +555,56 @@
     end
   end
 
+  describe '#attribute_previously_was' do
+    let(:previous_title) do
+      "Grand Poobah"
+    end
+
+    let(:age) do
+      10
+    end
+
+    let(:person) do
+      Person.create!(title: previous_title, age: age)
+    end
+
+    let(:updated_title) do
+      "Captain Obvious"
+    end
+
+    before do
+      person.title = updated_title
+      person.save!
+    end
+
+    context 'when attribute changed' do
+      it "returns the old value" do
+        expect(person.send(:attribute_previously_was, "title")).to eq(previous_title)
+      end
+
+      it "allows access via (attribute)_was" do
+        expect(person.title_previously_was).to eq(previous_title)
+      end
+    end
+
+    context 'when attribute did not change' do
+      it "returns the same value" do
+        expect(person.send(:attribute_previously_was, "age")).to eq(age)
+      end
+
+      it "allows access via (attribute)_was" do
+        expect(person.age_previously_was).to eq(age)
+      end
+    end
+
+    it 'clears after reload' do
+      person.reload
+      expect(person.title_previously_was).to be_nil
+      expect(person.age_previously_was).to be_nil
+    end
+
+  end
+
   describe "#attribute_will_change!" do
 
     let(:aliases) do

spec/mongoid/reloadable_spec.rb

@@ -628,5 +628,38 @@
         church.acolytes.first.name.should == 'Borg'
       end
     end
+
+    context 'when document has previous changes' do
+      context 'when document was updated' do
+        let(:person) do
+          Person.create!(title: 'Sir')
+        end
+
+        before do
+          person.title = 'Madam'
+          person.save!
+          person.reload
+        end
+
+        it "resets previous changes" do
+          expect(person.title_previously_was).to be_nil
+          expect(person).not_to be_previously_persisted
+        end
+      end
+
+      context 'when document was created' do
+        let(:person) do
+          Person.create!(title: 'Sir')
+        end
+
+        before do
+          person.reload
+        end
+
+        it "resets previous changes" do
+          expect(person).not_to be_previously_new_record
+        end
+      end
+    end
   end
 end