mongoid 7.2.1 → 9.0.0

data/lib/mongoid/persistable/destroyable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for persistence operations that destroy documents.
-    #
-    # @since 4.0.0
     module Destroyable
       extend ActiveSupport::Concern
 
@@ -15,21 +13,51 @@ module Mongoid
       # @example Destroy a document.
       #   document.destroy
       #
-      # @param [ Hash ] options Options to pass to destroy.
+      # @param [ Hash ] options The options.
+      # @option options [ true | false ] :persist Whether to persist
+      #   the delete action. Callbacks will still be run even if false.
+      # @option options [ true | false ] :suppress Whether to update
+      #   the parent document in-memory when deleting an embedded document.
       #
-      # @return [ true, false ] True if successful, false if not.
-      #
-      # @since 1.0.0
+      # @return [ true | false ] True if successful, false if not.
       def destroy(options = nil)
         raise Errors::ReadonlyDocument.new(self.class) if readonly?
         self.flagged_for_destroy = true
-        result = run_callbacks(:destroy) { delete(options || {}) }
+        result = run_callbacks(:commit, skip_if: -> { in_transaction? }) do
+          run_callbacks(:destroy) do
+            if catch(:abort) { apply_destroy_dependencies! }
+              delete(options || {}).tap do |res|
+                if res && in_transaction?
+                  Threaded.add_modified_document(_session, self)
+                end
+              end
+            else
+              false
+            end
+          end
+        end
         self.flagged_for_destroy = false
         result
       end
 
+      # Remove the document from the database with callbacks. Raises
+      # an error if the document is not destroyed.
+      #
+      # @example Destroy a document.
+      #   document.destroy!
+      #
+      # @param [ Hash ] options The options.
+      # @option options [ true | false ] :persist Whether to persist
+      #   the delete action. Callbacks will still be run even if false.
+      # @option options [ true | false ] :suppress Whether to update
+      #   the parent document in-memory when deleting an embedded document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotDestroyed ] Raised if
+      #   the document was not destroyed.
+      #
+      # @return [ true ] Always true.
       def destroy!(options = {})
-        destroy || raise(Errors::DocumentNotDestroyed.new(id, self.class))
+        destroy(options) || raise(Errors::DocumentNotDestroyed.new(_id, self.class))
       end
 
       module ClassMethods
@@ -47,8 +75,6 @@ module Mongoid
         # @param [ Hash ] conditions Optional conditions to destroy by.
         #
         # @return [ Integer ] The number of documents destroyed.
-        #
-        # @since 1.0.0
         def destroy_all(conditions = nil)
           where(conditions || {}).destroy
         end

data/lib/mongoid/persistable/incrementable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $inc operations.
-    #
-    # @since 4.0.0
     module Incrementable
       extend ActiveSupport::Concern
 
@@ -20,12 +18,10 @@ module Mongoid
       # @param [ Hash ] increments The field/inc increment pairs.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def inc(increments)
         prepare_atomic_operation do |ops|
           process_atomic_operations(increments) do |field, value|
-            increment = value.__to_inc__
+            increment = value.is_a?(BigDecimal) ? value.to_f : value
             current = attributes[field]
             new_value = (current || 0) + increment
             process_attribute field, new_value if executing_atomically?

data/lib/mongoid/persistable/logical.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for logical bitwise operations.
-    #
-    # @since 4.0.0
     module Logical
       extend ActiveSupport::Concern
 
@@ -19,8 +17,6 @@ module Mongoid
       # @param [ Hash ] operations The bitwise operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def bit(operations)
         prepare_atomic_operation do |ops|
           process_atomic_operations(operations) do |field, values|

data/lib/mongoid/persistable/maxable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+  module Persistable
+
+    # Defines behavior for setting a field (or fields) to the larger of
+    # either it's current value, or a given value.
+    module Maxable
+      extend ActiveSupport::Concern
+
+      # Set the given field or fields to the larger of either it's current
+      # value, or a given value.
+      #
+      # @example Set a field to be no less than 100.
+      #   document.set_max(field: 100)
+      #
+      # @param [ Hash<Symbol | String, Comparable> ] fields The fields to
+      #   set, with corresponding minimum values.
+      #
+      # @return [ Document ] The document.
+      def set_max(fields)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(fields) do |field, value|
+            current_value = attributes[field]
+            if value > current_value
+              process_attribute field, value
+              ops[atomic_attribute_name(field)] = value
+            end
+          end
+          { "$max" => ops } unless ops.empty?
+        end
+      end
+      alias :clamp_lower_bound :set_max
+    end
+  end
+end

data/lib/mongoid/persistable/minable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+  module Persistable
+
+    # Defines behavior for setting a field (or fields) to the smaller of
+    # either it's current value, or a given value.
+    module Minable
+      extend ActiveSupport::Concern
+
+      # Set the given field or fields to the smaller of either it's current
+      # value, or a given value.
+      #
+      # @example Set a field to be no more than 100.
+      #   document.min(field: 100)
+      #
+      # @param [ Hash<Symbol | String, Comparable> ] fields The fields to
+      #   set, with corresponding maximum values.
+      #
+      # @return [ Document ] The document.
+      def set_min(fields)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(fields) do |field, value|
+            current_value = attributes[field]
+            if value < current_value
+              process_attribute field, value
+              ops[atomic_attribute_name(field)] = value
+            end
+          end
+          { "$min" => ops } unless ops.empty?
+        end
+      end
+      alias :clamp_upper_bound :set_min
+    end
+  end
+end

data/lib/mongoid/persistable/multipliable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+  module Persistable
+
+    # Defines behavior for $mul operations.
+    module Multipliable
+      extend ActiveSupport::Concern
+
+      # Multiply the provided fields by the corresponding values. Values can
+      # be positive or negative, and if no value exists for the field it will
+      # be set to zero.
+      #
+      # @example Multiply the fields.
+      #   document.mul(score: 10, place: 1, lives: -10)
+      #
+      # @param [ Hash ] factors The field/factor multiplier pairs.
+      #
+      # @return [ Document ] The document.
+      def mul(factors)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(factors) do |field, value|
+            factor = value.is_a?(BigDecimal) ? value.to_f : value
+            current = attributes[field]
+            new_value = (current || 0) * factor
+            process_attribute field, new_value if executing_atomically?
+            attributes[field] = new_value
+            ops[atomic_attribute_name(field)] = factor
+          end
+          { "$mul" => ops } unless ops.empty?
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/persistable/poppable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $pop operations.
-    #
-    # @since 4.0.0
     module Poppable
       extend ActiveSupport::Concern
 
@@ -24,8 +22,6 @@ module Mongoid
       # @param [ Hash ] pops The field/value pop operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def pop(pops)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pops) do |field, value|

data/lib/mongoid/persistable/pullable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $pull and $pullAll operations.
-    #
-    # @since 4.0.0
     module Pullable
       extend ActiveSupport::Concern
 
@@ -20,8 +18,6 @@ module Mongoid
       # @param [ Hash ] pulls The field/value pull pairs.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def pull(pulls)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pulls) do |field, value|
@@ -40,8 +36,6 @@ module Mongoid
       # @param [ Hash ] pulls The pull all operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def pull_all(pulls)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pulls) do |field, value|

data/lib/mongoid/persistable/pushable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $push and $addToSet operations.
-    #
-    # @since 4.0.0
     module Pushable
       extend ActiveSupport::Concern
 
@@ -19,8 +17,6 @@ module Mongoid
       # @param [ Hash ] adds The field/value pairs to add.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def add_to_set(adds)
         prepare_atomic_operation do |ops|
           process_atomic_operations(adds) do |field, value|
@@ -52,8 +48,6 @@ module Mongoid
       # @param [ Hash ] pushes The $push operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def push(pushes)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pushes) do |field, value|

data/lib/mongoid/persistable/renamable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $rename operations.
-    #
-    # @since 4.0.0
     module Renamable
       extend ActiveSupport::Concern
 
@@ -20,8 +18,6 @@ module Mongoid
       # @param [ Hash ] renames The rename pairs of old name/new name.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def rename(renames)
         prepare_atomic_operation do |ops|
           process_atomic_operations(renames) do |old_field, new_field|

data/lib/mongoid/persistable/savable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for persistence operations that save documents.
-    #
-    # @since 4.0.0
     module Savable
 
       # Save the document - will perform an insert if the document is new, and
@@ -17,9 +15,13 @@ module Mongoid
       #
       # @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.
       #
-      # @since 1.0.0
+      # @return [ true | false ] True if success, false if not.
       def save(options = {})
         if new_record?
           !insert(options).new_record?
@@ -36,12 +38,16 @@ module Mongoid
       #
       # @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.
       #
-      # @return [ true, false ] True if validation passed.
-      #
-      # @since 1.0.0
+      # @return [ true | false ] True if validation passed.
       def save!(options = {})
         unless save(options)
           fail_due_to_validation! unless errors.empty?

data/lib/mongoid/persistable/settable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $set operations.
-    #
-    # @since 4.0.0
     module Settable
       extend ActiveSupport::Concern
 
@@ -47,8 +45,6 @@ module Mongoid
       # @param [ Hash ] setters The field/value pairs to set.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def set(setters)
         prepare_atomic_operation do |ops|
           process_atomic_operations(setters) do |field, value|

data/lib/mongoid/persistable/unsettable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $unset operations.
-    #
-    # @since 4.0.0
     module Unsettable
       extend ActiveSupport::Concern
 
@@ -16,12 +14,10 @@ module Mongoid
       # @example Unset the values.
       #   document.unset(:first_name, :last_name, :middle)
       #
-      # @param [ Array<String, Symbol> ] fields The names of the fields to
-      #   unset.
+      # @param [ [ String | Symbol | Array<String | Symbol>]... ] *fields
+      #   The names of the field(s) to unset.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def unset(*fields)
         prepare_atomic_operation do |ops|
           fields.flatten.each do |field|

data/lib/mongoid/persistable/updatable.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Persistable
 
     # Defines behavior for persistence operations that update existing
     # documents.
-    #
-    # @since 4.0.0
     module Updatable
 
       # Update a single attribute and persist the entire document.
@@ -16,15 +14,13 @@ module Mongoid
       # @example Update the attribute.
       #   person.update_attribute(:title, "Sir")
       #
-      # @param [ Symbol, String ] name The name of the attribute.
+      # @param [ Symbol | String ] name The name of the attribute.
       # @param [ Object ] value The new value of the attribute.a
       #
       # @raise [ Errors::ReadonlyAttribute ] If the field cannot be changed due
-      #   to being flagged as reaodnly.
+      #   to being flagged as read-only.
       #
-      # @return [ true, false ] True if save was successfull, false if not.
-      #
-      # @since 2.0.0
+      # @return [ true | false ] True if save was successful, false if not.
       def update_attribute(name, value)
         as_writable_attribute!(name, value) do |access|
           normalized = name.to_s
@@ -40,9 +36,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The attributes to update.
       #
-      # @return [ true, false ] True if validation passed, false if not.
-      #
-      # @since 1.0.0
+      # @return [ true | false ] True if validation passed, false if not.
       def update(attributes = {})
         assign_attributes(attributes)
         save
@@ -60,9 +54,7 @@ module Mongoid
       # @raise [ Errors::Validations ] If validation failed.
       # @raise [ Errors::Callbacks ] If a callback returns false.
       #
-      # @return [ true, false ] True if validation passed.
-      #
-      # @since 1.0.0
+      # @return [ true | false ] True if validation passed.
       def update!(attributes = {})
         result = update_attributes(attributes)
         unless result
@@ -83,8 +75,6 @@ module Mongoid
       #   document.init_atomic_updates
       #
       # @return [ Array<Hash> ] The updates and conflicts.
-      #
-      # @since 4.0.0
       def init_atomic_updates
         updates = atomic_updates
         conflicts = updates.delete(:conflicts) || {}
@@ -102,20 +92,26 @@ module Mongoid
       #
       # @param [ Hash ] options The options.
       #
-      # @return [ true, false ] The result of the update.
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time.
       #
-      # @since 4.0.0
+      # @return [ true | false ] The result of the update.
       def prepare_update(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
+        enforce_immutability_of_id_field!
+        ensure_client_compatibility!
         return false if performing_validations?(options) &&
           invalid?(options[:context] || :update)
         process_flagged_destroys
-        result = run_callbacks(:save) do
-          run_callbacks(:update) do
-            yield(self)
+        update_children = cascadable_children(:update)
+        process_touch_option(options, update_children) do
+          run_all_callbacks_for_update(update_children) do
+            result = yield(self)
+            self.previously_new_record = false
+            post_process_persist(result, options)
             true
           end
         end
-        post_process_persist(result, options) and result
       end
 
       # Update the document in the database.
@@ -125,24 +121,114 @@ module Mongoid
       #
       # @param [ Hash ] options Options to pass to update.
       #
-      # @option options [ true, false ] :validate Whether or not to validate.
-      #
-      # @return [ true, false ] True if succeeded, false if not.
+      # @option options [ true | false ] :validate Whether or not to validate.
       #
-      # @since 1.0.0
+      # @return [ true | false ] True if succeeded, false if not.
       def update_document(options = {})
         prepare_update(options) do
           updates, conflicts = init_atomic_updates
           unless updates.empty?
             coll = collection(_root)
             selector = atomic_selector
+
+            # TODO: DRIVERS-716: If a new "Bulk Write" API is introduced, it may
+            # become possible to handle the writes for conflicts in the following call.
             coll.find(selector).update_one(positionally(selector, updates), session: _session)
-            conflicts.each_pair do |key, value|
-              coll.find(selector).update_one(positionally(selector, { key => value }), session: _session)
+
+            # The following code applies updates which would cause
+            # path conflicts in MongoDB, for example when changing attributes
+            # of foo.0.bars while adding another foo. Each conflicting update
+            # is applied using its own write.
+            conflicts.each_pair do |modifier, changes|
+
+              # Group the changes according to their root key which is
+              # the top-level association name.
+              # This handles at least the cases described in MONGOID-4982.
+              conflicting_change_groups = changes.group_by do |key, _|
+                key.split(".", 2).first
+              end.values
+
+              # Apply changes in batches. Pop one change from each
+              # field-conflict group round-robin until all changes
+              # have been applied.
+              while batched_changes = conflicting_change_groups.map(&:pop).compact.to_h.presence
+                coll.find(selector).update_one(
+                  positionally(selector, modifier => batched_changes),
+                  session: _session,
+                )
+              end
             end
           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)
+        if options.fetch(:touch, true)
+          yield
+        else
+          timeless
+          children.each(&:timeless)
+          suppress_touch_callbacks { yield }
+        end
+      end
+
+      # Checks to see if the _id field has been modified. If it has, and if
+      # the document has already been persisted, this is an error. Otherwise,
+      # returns without side-effects.
+      #
+      # Note that if `Mongoid::Config.immutable_ids` is false, this will do
+      # nothing.
+      #
+      # @raise [ Errors::ImmutableAttribute ] if _id has changed, and document
+      #   has been persisted.
+      def enforce_immutability_of_id_field!
+        # special case here: we *do* allow the _id to be mutated if it was
+        # previously nil. This addresses an odd case exposed in
+        # has_one/proxy_spec.rb where `person.create_address` would
+        # (somehow?) create the address with a nil _id first, before then
+        # saving it *again* with the correct _id.
+
+        if _id_changed? && !_id_was.nil? && persisted?
+          if Mongoid::Config.immutable_ids
+            raise Errors::ImmutableAttribute.new(:_id, _id)
+          else
+            Mongoid::Warnings.warn_mutable_ids
+          end
+        end
+      end
+
+      # Consolidates all the callback invocations into a single place, to
+      # avoid cluttering the logic in #prepare_update.
+      #
+      # @param [ Array<Document> ] update_children The children that the
+      #   :update callbacks will be executed on.
+      def run_all_callbacks_for_update(update_children)
+        run_callbacks(:commit, with_children: true, skip_if: -> { in_transaction? }) do
+          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, children: update_children) do
+                    yield
+                  end # _mongoid_run_child_callbacks :update
+                end # _mongoid_run_child_callbacks :save
+              end # :persist_parent
+            end # :update
+          end # :save
+        end # :commit
+      end
+
     end
   end
 end