MONGOID-5442 implement missing update operators (#5521)

* allow BSON::Timestamp to be demongoized to a Time instance

* Add support for $currentDate operation

* $min implementation for Contextual::Atomic

* Implement $min on documents

* $max implementation for Contextual::Atomic

* Implement $max operator for documents

* $mul for documents

* $mul operation for Contextual::Atomic

* initial support for $setOnInsert

note: this doesn't (yet) work for upserts with `replace: true`

* update_min => set_min, with alias as set_upper_bound

* update_max -> set_max (with clamp_lower_bound alias)

* min -> set_min (with clamp_upper_bound alias)

* max -> set_max (with clamp_lower_bound alias)

* mul -> set_mul

* mul -> set_mul

* remove the $currentDate implementation

see comment on 5442 for background

* remove current_date

* guard against empty argument (for earlier mongodb versions)

Author: jamis

lib/mongoid/contextual/atomic.rb

@@ -52,6 +52,18 @@ def inc(incs)
         view.update_many("$inc" => collect_operations(incs))
       end
 
+      # Perform an atomic $mul operation on the matching documents.
+      #
+      # @example Perform the atomic multiplication.
+      #   context.set_mul(likes: 10)
+      #
+      # @param [ Hash ] factors The operations.
+      #
+      # @return [ nil ] Nil.
+      def set_mul(factors)
+        view.update_many("$mul" => collect_operations(factors))
+      end
+
       # Perform an atomic $pop operation on the matching documents.
       #
       # @example Pop the first value on the matches.
@@ -163,10 +175,62 @@ def unset(*args)
         view.update_many("$unset" => Hash[fields])
       end
 
+      # Performs an atomic $min update operation on the given field or fields.
+      # Each field will be set to the minimum of [current_value, given value].
+      # This has the effect of making sure that each field is no
+      # larger than the given value; in other words, the given value is the
+      # effective *maximum* for that field.
+      #
+      # @note Because of the existence of
+      #   Mongoid::Contextual::Aggregable::Mongo#min, this method cannot be
+      #   named #min, and thus breaks that convention of other similar methods
+      #   of being named for the MongoDB operation they perform.
+      #
+      # @example Set "views" to be no more than 100.
+      #   context.set_min(views: 100)
+      #
+      # @param [ Hash ] fields The fields with the maximum value that each
+      #   may be set to.
+      #
+      # @return [ nil ] Nil.
+      def set_min(fields)
+        view.update_many("$min" => collect_operations(fields))
+      end
+      alias :clamp_upper_bound :set_min
+
+      # Performs an atomic $max update operation on the given field or fields.
+      # Each field will be set to the maximum of [current_value, given value].
+      # This has the effect of making sure that each field is no
+      # smaller than the given value; in other words, the given value is the
+      # effective *minimum* for that field.
+      #
+      # @note Because of the existence of
+      #   Mongoid::Contextual::Aggregable::Mongo#max, this method cannot be
+      #   named #max, and thus breaks that convention of other similar methods
+      #   of being named for the MongoDB operation they perform.
+      #
+      # @example Set "views" to be no less than 100.
+      #   context.set_max(views: 100)
+      #
+      # @param [ Hash ] fields The fields with the minimum value that each
+      #   may be set to.
+      #
+      # @return [ nil ] Nil.
+      def set_max(fields)
+        view.update_many("$max" => collect_operations(fields))
+      end
+      alias :clamp_lower_bound :set_max
+
       private
 
-      def collect_operations(ops)
-        ops.each_with_object({}) do |(field, value), operations|
+      # Collects and aggregates operations by field.
+      #
+      # @param [ Array | Hash ] ops The operations to collect.
+      # @param [ Hash ] aggregator The hash to use to aggregate the operations.
+      # 
+      # @return [ Hash ] The aggregated operations, by field.
+      def collect_operations(ops, aggregator = {})
+        ops.each_with_object(aggregator) do |(field, value), operations|
           operations[database_field_name(field)] = value.mongoize
         end
       end
@@ -176,6 +240,10 @@ def collect_each_operations(ops)
           operations[database_field_name(field)] = { "$each" => Array.wrap(value).mongoize }
         end
       end
+
+      def translate_date_type(type)
+        Mongoid::Persistable::Datable.translate_date_field_spec(type)
+      end
     end
   end
 end

lib/mongoid/extensions/time.rb

@@ -58,6 +58,8 @@ def demongoize(object)
             rescue ArgumentError
               nil
             end
+          elsif object.is_a?(BSON::Timestamp)
+            ::Time.at(object.seconds)
           end
 
           return if time.nil?

lib/mongoid/persistable.rb

@@ -5,6 +5,9 @@
 require "mongoid/persistable/destroyable"
 require "mongoid/persistable/incrementable"
 require "mongoid/persistable/logical"
+require "mongoid/persistable/maxable"
+require "mongoid/persistable/minable"
+require "mongoid/persistable/multipliable"
 require "mongoid/persistable/poppable"
 require "mongoid/persistable/pullable"
 require "mongoid/persistable/pushable"
@@ -25,6 +28,9 @@ module Persistable
     include Destroyable
     include Incrementable
     include Logical
+    include Maxable
+    include Minable
+    include Multipliable
     include Poppable
     include Positional
     include Pullable

lib/mongoid/persistable/maxable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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

lib/mongoid/persistable/minable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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

lib/mongoid/persistable/multipliable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+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.set_mul(score: 10, place: 1, lives: -10)
+      #
+      # @param [ Hash ] factors The field/factor multiplier pairs.
+      #
+      # @return [ Document ] The document.
+      def set_mul(factors)
+        prepare_atomic_operation do |ops|
+          process_atomic_operations(factors) do |field, value|
+            factor = value.__to_inc__
+            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

lib/mongoid/persistable/upsertable.rb

@@ -20,20 +20,33 @@ module Upsertable
       # @example Upsert the document with replace.
       #   document.upsert(replace: true)
       #
+      # @example Upsert with extra attributes to use when inserting.
+      #   document.upsert(set_on_insert: { created_at: DateTime.now })
+      #
       # @param [ Hash ] options The validation options.
       #
       # @option options [ true | false ] :validate Whether or not to validate.
-      # @option options [ true | false ] :replace Whether or not to replace the document on upsert.
+      # @option options [ true | false ] :replace Whether or not to replace
+      #   the document on upsert.
+      # @option options [ Hash ] :set_on_insert The attributes to include if
+      #   the document does not already exist.
       #
       # @return [ true ] True.
       def upsert(options = {})
         prepare_upsert(options) do
           if options[:replace]
+            if options[:set_on_insert]
+              raise ArgumentError, "cannot specify :set_on_insert with `replace: true`"
+            end
+
             collection.find(atomic_selector).replace_one(
               as_attributes, upsert: true, session: _session)
           else
+            attrs = { "$set" => as_attributes }
+            attrs["$setOnInsert"] = options[:set_on_insert] if options[:set_on_insert]
+
             collection.find(atomic_selector).update_one(
-              { "$set" => as_attributes }, upsert: true, session: _session)
+              attrs, upsert: true, session: _session)
           end
         end
       end