MONGOID-5943: Add changeset persistence layer

AGENTS.md

@@ -13,6 +13,10 @@ Mongoid is a Ruby Object-Document Mapper (ODM) framework for MongoDB. Mongoid al
 
 # Development Workflow
 
+## Planning and Design
+
+When producing a design document or specification for a new feature or significant change, leave the document unstaged. Do not add it to the repository.
+
 ## Running tests
 
 Tests require a running MongoDB instance. Set the URI via the `MONGODB_URI` environment variable:

lib/config/locales/en.yml

@@ -413,6 +413,10 @@ en:
           message: "A transaction was started while another transaction was being used on this client."
           summary: "Transactions cannot be nested. Only one transaction can be used in a thread per client."
           resolution: "Only use one transaction per client at a time; transactions cannot be nested."
+        transaction_in_changeset:
+          message: "Cannot start a transaction inside a changeset."
+          summary: "A changeset defers all writes and flushes them as a batch when the outermost block exits. Starting a transaction inside a changeset would have no effect, because the operations inside the transaction block are queued rather than executed immediately."
+          resolution: "Do not nest a transaction inside a changeset."
         inverse_not_found:
           message: "When adding a(n) %{klass} to %{base}#%{name}, Mongoid could
             not determine the inverse foreign key to set. The attempted key was

lib/mongoid.rb

@@ -28,6 +28,7 @@
 require 'mongoid/tasks/encryption'
 require 'mongoid/warnings'
 require 'mongoid/utils'
+require 'mongoid/changeset'
 
 # If we are using Rails then we will include the Mongoid railtie.
 # This configures initializers required to integrate Mongoid with Rails.
@@ -107,6 +108,23 @@ def reconnect_clients
     Clients.reconnect
   end
 
+  # Creates or reuses the current changeset, yields it to the block, and
+  # flushes when the outermost scope exits. When nested inside an existing
+  # changeset block, the inner call accumulates without flushing.
+  #
+  # @example Explicit outer scope — flush happens once at block exit.
+  #   Mongoid.changeset do |cs|
+  #     parent.save
+  #     child.save
+  #   end
+  def changeset
+    outermost = Threaded.current_changeset.nil?
+    cs = Threaded.current_changeset || (Threaded.current_changeset = Changeset.new)
+    cs.run { yield cs }
+  ensure
+    Threaded.current_changeset = nil if outermost
+  end
+
   # Convenience method for getting a named client.
   #
   # @example Get a named client.

lib/mongoid/association/embedded/batchable.rb

@@ -33,10 +33,16 @@ def batch_insert(docs)
         def batch_clear(docs)
           pre_process_batch_remove(docs, :delete)
           unless docs.empty?
-            collection.find(selector).update_one(
-              positionally(selector, '$unset' => { path => true }),
-              session: _session
-            )
+            Mongoid.changeset do |cs|
+              cs.add(
+                type: :update,
+                collection: collection,
+                selector: selector,
+                payload: positionally(selector, '$unset' => { path => true }),
+                document: nil,
+                session: _session
+              )
+            end
             # This solves the case in which a user sets, clears and resets an
             # embedded document. Previously, since the embedded document was
             # already marked not a "new_record", it wouldn't be persisted to
@@ -67,22 +73,38 @@ def batch_remove(docs, method = :delete)
           end
 
           if docs.empty?
-            collection.find(selector).update_one(
-              positionally(selector, '$set' => { path => [] }),
-              session: _session
-            )
-          else
-            unless pulls.empty?
-              collection.find(selector).update_one(
-                positionally(selector, '$pull' => { path => { '_id' => { '$in' => pulls.pluck('_id') } } }),
+            Mongoid.changeset do |cs|
+              cs.add(
+                type: :update,
+                collection: collection,
+                selector: selector,
+                payload: positionally(selector, '$set' => { path => [] }),
+                document: nil,
                 session: _session
               )
             end
-            unless pull_alls.empty?
-              collection.find(selector).update_one(
-                positionally(selector, '$pullAll' => { path => pull_alls }),
-                session: _session
-              )
+          else
+            Mongoid.changeset do |cs|
+              unless pulls.empty?
+                cs.add(
+                  type: :update,
+                  collection: collection,
+                  selector: selector,
+                  payload: positionally(selector, '$pull' => { path => { '_id' => { '$in' => pulls.pluck('_id') } } }),
+                  document: nil,
+                  session: _session
+                )
+              end
+              unless pull_alls.empty?
+                cs.add(
+                  type: :update,
+                  collection: collection,
+                  selector: selector,
+                  payload: positionally(selector, '$pullAll' => { path => pull_alls }),
+                  document: nil,
+                  session: _session
+                )
+              end
             end
             post_process_batch_remove(docs, method)
           end
@@ -154,10 +176,16 @@ def execute_batch_set(docs)
           self.inserts_valid = true
           inserts = pre_process_batch_insert(docs)
           if insertable?
-            collection.find(selector).update_one(
-              positionally(selector, '$set' => { path => inserts }),
-              session: _session
-            )
+            Mongoid.changeset do |cs|
+              cs.add(
+                type: :update,
+                collection: collection,
+                selector: selector,
+                payload: positionally(selector, '$set' => { path => inserts }),
+                document: nil,
+                session: _session
+              )
+            end
             post_process_batch_insert(docs)
           end
           inserts
@@ -177,10 +205,16 @@ def execute_batch_push(docs)
           self.inserts_valid = true
           pushes = pre_process_batch_insert(docs)
           if insertable?
-            collection.find(selector).update_one(
-              positionally(selector, '$push' => { path => { '$each' => pushes } }),
-              session: _session
-            )
+            Mongoid.changeset do |cs|
+              cs.add(
+                type: :update,
+                collection: collection,
+                selector: selector,
+                payload: positionally(selector, '$push' => { path => { '$each' => pushes } }),
+                document: nil,
+                session: _session
+              )
+            end
             post_process_batch_insert(docs)
           end
           pushes

lib/mongoid/association/nested/many.rb

@@ -160,11 +160,7 @@ def destroy_document(relation, doc)
         # @param [ Hash ] attrs The attributes.
         def update_document(doc, attrs)
           delete_id(attrs)
-          if association.embedded?
-            doc.assign_attributes(attrs)
-          else
-            doc.update_attributes(attrs)
-          end
+          doc.assign_attributes(attrs)
         end
 
         # Update nested association.

lib/mongoid/association/referenced/has_and_belongs_to_many/proxy.rb

@@ -79,8 +79,10 @@ def <<(*args)
                 #    the changed_attributes hash.
                 #    See MONGOID-4843 for a longer discussion about this.
                 reset_foreign_key_changes do
-                  _base.add_to_set(foreign_key => doc.public_send(_association.primary_key))
-                  doc.save if child_persistable?(doc)
+                  Mongoid.changeset do
+                    _base.add_to_set(foreign_key => doc.public_send(_association.primary_key))
+                    doc.save! if child_persistable?(doc)
+                  end
                   reset_unloaded
                 end
               end

lib/mongoid/association/referenced/has_many/proxy.rb

@@ -73,7 +73,7 @@ def <<(*args)
 
             if (doc = docs.first)
               append(doc)
-              doc.save if persistable? && !_assigning? && !doc.validated?
+              doc.save! if persistable? && !_assigning? && !doc.validated?
             end
             self
           end
@@ -597,7 +597,7 @@ def save_or_delay(doc, docs, inserts)
               docs.push(doc)
               inserts.push(doc.send(:as_attributes))
             else
-              doc.save
+              doc.save!
             end
           end
         end

lib/mongoid/association/referenced/has_one/proxy.rb

@@ -45,7 +45,7 @@ def initialize(base, target, association)
               raise_mixed if klass.embedded? && !klass.cyclic?
               characterize_one(_target)
               bind_one
-              _target.save if persistable?
+              _target.save! if persistable?
             end
           end