MONGOID-4979 Add :touch option to model save method (#5397)

* MONGOID-4979 test set_created_at

* MONGOID-4979 undo test

* MONGOID-4979 add touch: false option

* MONGOID-4979 use the timeless method instead

* MONGOID-4979 add optimization and timeless tests

* MONGOID-4979 fix docs

* MONGOID-4979 add release note

* MONGOID-4979 add crud docs

Author: neilshweky

docs/reference/crud.txt

@@ -145,6 +145,11 @@ operations with examples.
        the save.*
 
        *Pass* ``validate: false`` *option to bypass validations.*
+
+       *Pass* ``touch: false`` *option to ignore the updates to the updated_at
+       field. If the document being save has not been previously persisted,
+       this option is ignored and the created_at and updated_at fields will be
+       updated with the current time.*
      -
         .. code-block:: ruby
 
@@ -154,6 +159,7 @@ operations with examples.
           )
           person.save
           person.save(validate: false)
+          person.save(touch: false)
 
           person.first_name = "Christian Johan"
           person.save

docs/release-notes/mongoid-8.1.txt

@@ -42,3 +42,18 @@ with a bang (!) raise an error:
 
   Band.none.first!
   # => raise Mongoid::Errors::DocumentNotFound
+
+
+Added ``:touch`` option to ``#save``
+------------------------------------
+
+Support for the ``:touch`` option has been added to the ``#save`` and ``#save!``
+methods. When this option is false, the ``updated_at`` field on the saved
+document and all of it's embedded documents will not be updated with the
+current time. When this option is true or unset, the ``updated_at`` field will
+be updated with the current time.
+
+If the document being saved is a new document (i.e. it has not yet been
+persisted to the database), then the ``:touch`` option will be ignored, and the
+``updated_at`` (and ``created_at``) fields will be updated with the current
+time.

lib/mongoid/interceptable.rb

@@ -134,7 +134,7 @@ def run_callbacks(kind, with_children: true, &block)
     # Run the callbacks for embedded documents.
     #
     # @param [ Symbol ] kind The type of callback to execute.
-    # @param [ Array<Document> ] children Children to exeute callbacks on. If
+    # @param [ Array<Document> ] children Children to execute callbacks on. If
     #   nil, callbacks will be executed on all cascadable children of
     #   the document.
     #

lib/mongoid/persistable/savable.rb

@@ -14,7 +14,13 @@ module Savable
       #
       # @param [ Hash ] options Options to pass to the save.
       #
-      # @return [ true | false ] True is success, false if not.
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time. When this option is
+      #   false, none of the embedded documents will be touched. This option is
+      #   ignored when saving a new document, and the created_at and updated_at
+      #   will be set to the current time.
+      #
+      # @return [ true | false ] True if success, false if not.
       def save(options = {})
         if new_record?
           !insert(options).new_record?
@@ -31,6 +37,12 @@ def save(options = {})
       #
       # @param [ Hash ] options Options to pass to the save.
       #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time. When this option is
+      #   false, none of the embedded documents will be touched.This option is
+      #   ignored when saving a new document, and the created_at and updated_at
+      #   will be set to the current time.
+      #
       # @raise [ Errors::Validations ] If validation failed.
       # @raise [ Errors::Callback ] If a callback returns false.
       #

lib/mongoid/persistable/updatable.rb

@@ -91,16 +91,21 @@ def init_atomic_updates
       #
       # @param [ Hash ] options The options.
       #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time.
+      #
       # @return [ true | false ] The result of the update.
       def prepare_update(options = {})
         return false if performing_validations?(options) &&
           invalid?(options[:context] || :update)
         process_flagged_destroys
+        update_children = cascadable_children(:update)
+        process_touch_option(options, update_children)
         run_callbacks(:save, with_children: false) do
           run_callbacks(:update, with_children: false) do
             run_callbacks(:persist_parent, with_children: false) do
               _mongoid_run_child_callbacks(:save) do
-                _mongoid_run_child_callbacks(:update) do
+                _mongoid_run_child_callbacks(:update, children: update_children) do
                   result = yield(self)
                   self.previously_new_record = false
                   post_process_persist(result, options)
@@ -160,6 +165,24 @@ def update_document(options = {})
           end
         end
       end
+
+      # If there is a touch option and it is false, this method will call the
+      # timeless method so that the updated_at attribute is not updated. It
+      # will call the timeless method on all of the cascadable children as
+      # well. Note that timeless is cleared in the before_update callback.
+      #
+      # @param [ Hash ] options The options.
+      # @param [ Array<Document> ] children The children that the :update
+      #   callbacks will be executed on.
+      #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time.
+      def process_touch_option(options, children)
+        unless options.fetch(:touch, true)
+          timeless
+          children.each(&:timeless)
+        end
+      end
     end
   end
 end

spec/mongoid/timestamps_spec.rb

@@ -127,7 +127,7 @@
   end
 
   # This section of tests describes the behavior of the updated_at field for
-  # different updates on associations, as outlined in PR #5219.
+  # different updates on referenced associations, as outlined in PR #5219.
   describe "updated_at attribute" do
     let!(:start_time) { Timecop.freeze(Time.at(Time.now.to_i)) }
 

spec/mongoid/touchable_spec.rb

@@ -89,7 +89,7 @@
         end
       end
 
-      shared_examples 'updates the parent when :touch is not set' do
+      shared_examples 'updates the parent when :touch is false' do
         it 'does not update updated_at on parent' do
           entrance
           update_time
@@ -130,7 +130,7 @@
 
         include_examples 'updates the child'
         include_examples 'updates the parent when :touch is true'
-        include_examples 'updates the parent when :touch is not set'
+        include_examples 'updates the parent when :touch is false'
 
         context 'when also updating an additional field' do
           it 'persists the update to the additional field' do
@@ -701,4 +701,237 @@
       end
     end
   end
+
+  describe "when saving a document" do
+
+    let!(:start_time) { Timecop.freeze(Time.at(Time.now.to_i)) }
+
+    let(:update_time) do
+      Timecop.freeze(Time.at(Time.now.to_i) + 2)
+    end
+
+    after do
+      Timecop.return
+    end
+
+    context "when only using the root document" do
+
+      shared_examples "timeless is cleared" do
+        it "clears the timeless option" do
+          expect(doc.timeless?).to be false
+        end
+      end
+
+      shared_examples "touches the document" do
+        it "touches the document" do
+          expect(doc.created_at).to eq(start_time)
+          expect(doc.updated_at).to eq(start_time)
+        end
+      end
+
+      shared_examples "updates the document" do
+        it "updates the document" do
+          expect(doc.created_at).to eq(start_time)
+          expect(doc.updated_at).to eq(update_time)
+        end
+      end
+
+      let(:doc) { Dokument.new }
+
+      context "when saving a new document" do
+
+        context "when not passing a touch option" do
+
+          before do
+            doc.save!
+          end
+
+          include_examples "touches the document"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: true" do
+
+          before do
+            doc.save!(touch: true)
+          end
+
+          include_examples "touches the document"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: false" do
+
+          before do
+            doc.save!(touch: false)
+          end
+
+          include_examples "touches the document"
+          include_examples "timeless is cleared"
+        end
+      end
+
+      context "when updating a document" do
+        before do
+          doc.save!
+          doc.title = "title"
+          update_time
+        end
+
+        context "when not passing a touch option" do
+
+          before do
+            doc.save!
+          end
+
+          include_examples "updates the document"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: true" do
+
+          before do
+            doc.save!(touch: true)
+          end
+
+          include_examples "updates the document"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: false" do
+
+          before do
+            doc.save!(touch: false)
+          end
+
+          include_examples "touches the document"
+          include_examples "timeless is cleared"
+        end
+      end
+    end
+
+    context "when saving embedded associations with cascadable callbacks" do
+
+      shared_examples "timeless is cleared" do
+        it "clears the timeless option" do
+          expect(book.timeless?).to be false
+          expect(book.covers.first.timeless?).to be false
+        end
+      end
+
+      shared_examples "touches the document" do
+        it "touches the document" do
+          expect(book.created_at).to eq(start_time)
+          expect(book.updated_at).to eq(start_time)
+        end
+      end
+
+      shared_examples "updates the document" do
+        it "updates the document" do
+          expect(book.created_at).to eq(start_time)
+          expect(book.updated_at).to eq(update_time)
+        end
+      end
+
+      shared_examples "touches the children" do
+        it "touches the children" do
+          expect(book.covers.first.created_at).to eq(start_time)
+          expect(book.covers.first.updated_at).to eq(start_time)
+        end
+      end
+
+      shared_examples "updates the children" do
+        it "updates the children" do
+          expect(book.covers.first.created_at).to eq(start_time)
+          expect(book.covers.first.updated_at).to eq(update_time)
+        end
+      end
+
+      let(:book) do
+        Book.new(covers: [ cover ])
+      end
+
+      let(:cover) do
+        Cover.new
+      end
+
+      context "when saving a new document" do
+
+        context "when not passing a touch option" do
+
+          before do
+            book.save!
+          end
+
+          include_examples "touches the document"
+          include_examples "touches the children"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: true" do
+
+          before do
+            book.save!(touch: true)
+          end
+
+          include_examples "touches the document"
+          include_examples "touches the children"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: false" do
+
+          before do
+            book.save!(touch: false)
+          end
+
+          include_examples "touches the document"
+          include_examples "touches the children"
+          include_examples "timeless is cleared"
+        end
+      end
+
+      context "when updating a document" do
+        before do
+          book.save!
+          book.title = "title"
+          book.covers.first.title = "title"
+          update_time
+        end
+
+        context "when not passing a touch option" do
+
+          before do
+            book.save!
+          end
+
+          include_examples "updates the document"
+          include_examples "updates the children"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: true" do
+
+          before do
+            book.save!(touch: true)
+          end
+
+          include_examples "updates the document"
+          include_examples "updates the children"
+          include_examples "timeless is cleared"
+        end
+
+        context "when passing touch: false" do
+
+          before do
+            book.save!(touch: false)
+          end
+
+          include_examples "touches the document"
+          include_examples "touches the children"
+          include_examples "timeless is cleared"
+        end
+      end
+    end
+  end
 end