mongoid 7.2.1 → 9.0.0

data/lib/mongoid/contextual/atomic.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Contextual
+
+    # Mixin module included in Mongoid::Criteria which provides a
+    # direct method interface to MongoDB's Update Operators ($set,
+    # $pull, $inc, etc.) These operators can be applied to update
+    # all documents in the database within the criteria scope,
+    # without loading each document into Mongoid's memory.
     module Atomic
 
       # Execute an atomic $addToSet on the matching documents.
@@ -13,8 +19,6 @@ module Mongoid
       # @param [ Hash ] adds The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def add_to_set(adds)
         view.update_many("$addToSet" => collect_operations(adds))
       end
@@ -27,8 +31,6 @@ module Mongoid
       # @param [ Hash ] adds The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 7.0.0
       def add_each_to_set(adds)
         view.update_many("$addToSet" => collect_each_operations(adds))
       end
@@ -41,8 +43,6 @@ module Mongoid
       # @param [ Hash ] bits The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def bit(bits)
         view.update_many("$bit" => collect_operations(bits))
       end
@@ -55,12 +55,22 @@ module Mongoid
       # @param [ Hash ] incs The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       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.mul(likes: 10)
+      #
+      # @param [ Hash ] factors The operations.
+      #
+      # @return [ nil ] Nil.
+      def 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.
@@ -72,8 +82,6 @@ module Mongoid
       # @param [ Hash ] pops The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def pop(pops)
         view.update_many("$pop" => collect_operations(pops))
       end
@@ -88,8 +96,6 @@ module Mongoid
       # @param [ Hash ] pulls The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def pull(pulls)
         view.update_many("$pull" => collect_operations(pulls))
       end
@@ -102,8 +108,6 @@ module Mongoid
       # @param [ Hash ] pulls The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def pull_all(pulls)
         view.update_many("$pullAll" => collect_operations(pulls))
       end
@@ -116,8 +120,6 @@ module Mongoid
       # @param [ Hash ] pushes The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def push(pushes)
         view.update_many("$push" => collect_operations(pushes))
       end
@@ -130,8 +132,6 @@ module Mongoid
       # @param [ Hash ] pushes The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def push_all(pushes)
         view.update_many("$push" => collect_each_operations(pushes))
       end
@@ -144,8 +144,6 @@ module Mongoid
       # @param [ Hash ] renames The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def rename(renames)
         operations = renames.inject({}) do |ops, (old_name, new_name)|
           ops[old_name] = new_name.to_s
@@ -162,8 +160,6 @@ module Mongoid
       # @param [ Hash ] sets The operations.
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def set(sets)
         view.update_many("$set" => collect_operations(sets))
       end
@@ -173,20 +169,72 @@ module Mongoid
       # @example Unset the field on the matches.
       #   context.unset(:name)
       #
-      # @param [ String, Symbol, Array ] args The name of the fields.
+      # @param [ [ String | Symbol | Array<String | Symbol> | Hash ]... ] *unsets
+      #   The name(s) of the field(s) to unset. If a Hash is specified,
+      #   its keys will be used irrespective of value, even if the value
+      #   is nil or false.
+      #
+      # @return [ nil ] Nil.
+      def unset(*unsets)
+        view.update_many('$unset' => collect_unset_operations(unsets))
+      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)
       #
-      # @since 3.0.0
-      def unset(*args)
-        fields = args.__find_args__.collect { |f| [database_field_name(f), true] }
-        view.update_many("$unset" => Hash[fields])
+      # @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
@@ -196,6 +244,25 @@ module Mongoid
           operations[database_field_name(field)] = { "$each" => Array.wrap(value).mongoize }
         end
       end
+
+      # Builds the selector an atomic $unset operation from arguments.
+      #
+      # @example Prepare selector from array.
+      #   context.collect_unset_operations([:name, :age])
+      #   #=> { "name" => true, "age" => true }
+      #
+      # @example Prepare selector from hash.
+      #   context.collect_unset_operations({ name: 1 }, { age: 1 })
+      #   #=> { "name" => true, "age" => true }
+      #
+      # @param [ String | Symbol | Array<String | Symbol> | Hash ] ops
+      #   The name(s) of the field(s) to unset.
+      #
+      # @return [ Hash ] The selector for the atomic $unset operation.
+      def collect_unset_operations(ops)
+        ops.map { |op| op.is_a?(Hash) ? op.keys : op }.flatten
+           .map { |field| [database_field_name(field), true] }.to_h
+      end
     end
   end
 end

data/lib/mongoid/contextual/command.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Contextual
+
+    # Mixin module included in objects which represent database commands.
     module Command
 
       # @attribute [r] collection The collection to query against.
@@ -15,8 +17,6 @@ module Mongoid
       #   command.command
       #
       # @return [ Hash ] The db command.
-      #
-      # @since 3.0.0
       def command
         @command ||= {}
       end
@@ -27,8 +27,6 @@ module Mongoid
       #   command.client
       #
       # @return [ Mongo::Client ] The Mongo client.
-      #
-      # @since 3.0.0
       def client
         collection.database.client
       end

data/lib/mongoid/contextual/map_reduce.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Contextual
+
+    # Represents a mapReduce database command instruction.
     class MapReduce
       extend Forwardable
       include Enumerable
@@ -17,8 +19,6 @@ module Mongoid
       #   map_reduce.counts
       #
       # @return [ Hash ] The counts.
-      #
-      # @since 3.0.0
       def counts
         results["counts"]
       end
@@ -32,8 +32,6 @@ module Mongoid
       #   end
       #
       # @return [ Enumerator ] The enumerator.
-      #
-      # @since 3.0.0
       def each
         validate_out!
         if block_given?
@@ -51,8 +49,6 @@ module Mongoid
       #   map_reduce.emitted
       #
       # @return [ Integer ] The number of emitted documents.
-      #
-      # @since 3.0.0
       def emitted
         counts["emit"]
       end
@@ -65,8 +61,6 @@ module Mongoid
       # @param [ String ] function The finalize function.
       #
       # @return [ MapReduce ] The map reduce.
-      #
-      # @since 3.0.0
       def finalize(function)
         @map_reduce = @map_reduce.finalize(function)
         self
@@ -80,8 +74,6 @@ module Mongoid
       # @param [ Criteria ] criteria The Mongoid criteria.
       # @param [ String ] map The map js function.
       # @param [ String ] reduce The reduce js function.
-      #
-      # @since 3.0.0
       def initialize(collection, criteria, map, reduce)
         @collection = collection
         @criteria = criteria
@@ -94,8 +86,6 @@ module Mongoid
       #   map_reduce.input
       #
       # @return [ Integer ] The number of input documents.
-      #
-      # @since 3.0.0
       def input
         counts["input"]
       end
@@ -106,8 +96,6 @@ module Mongoid
       #   map_reduce.js_mode
       #
       # @return [ MapReduce ] The map/reduce.
-      #
-      # @since 3.0.0
       def js_mode
         @map_reduce = @map_reduce.js_mode(true)
         self
@@ -134,11 +122,9 @@ module Mongoid
       # @param [ Hash ] location The place to store the results.
       #
       # @return [ MapReduce ] The map/reduce object.
-      #
-      # @since 3.0.0
       def out(location)
         normalized = location.dup
-        normalized.update_values do |value|
+        normalized.transform_values! do |value|
           value.is_a?(::Symbol) ? value.to_s : value
         end
         @map_reduce = @map_reduce.out(normalized)
@@ -151,8 +137,6 @@ module Mongoid
       #   map_reduce.output
       #
       # @return [ Integer ] The number of output documents.
-      #
-      # @since 3.0.0
       def output
         counts["output"]
       end
@@ -163,12 +147,10 @@ module Mongoid
       #   map_reduce.raw
       #
       # @return [ Hash ] The raw output.
-      #
-      # @since 3.0.0
       def raw
         validate_out!
         cmd = command
-        opts = { read: cmd.delete(:read) } if cmd[:read]
+        opts = { read: criteria.options.fetch(:read) } if criteria.options[:read]
         @map_reduce.database.command(cmd, (opts || {}).merge(session: _session)).first
       end
       alias :results :raw
@@ -180,8 +162,6 @@ module Mongoid
       #   map_reduce.execute
       #
       # @return [ Hash ] The raw output
-      #
-      # @since 3.1.0
       alias :execute :raw
 
       # Get the number of documents reduced by the map/reduce.
@@ -190,8 +170,6 @@ module Mongoid
       #   map_reduce.reduced
       #
       # @return [ Integer ] The number of reduced documents.
-      #
-      # @since 3.0.0
       def reduced
         counts["reduce"]
       end
@@ -204,8 +182,6 @@ module Mongoid
       # @param [ Hash ] object A hash of key/values for the global scope.
       #
       # @return [ MapReduce ]
-      #
-      # @since 3.0.0
       def scope(object)
         @map_reduce = @map_reduce.scope(object)
         self
@@ -217,8 +193,6 @@ module Mongoid
       #   map_reduce.time
       #
       # @return [ Float ] The time in milliseconds.
-      #
-      # @since 3.0.0
       def time
         results["timeMillis"]
       end
@@ -230,8 +204,6 @@ module Mongoid
       #   map_reduce.inspect
       #
       # @return [ String ] The inspection string.
-      #
-      # @since 3.1.0
       def inspect
 %Q{#<Mongoid::Contextual::MapReduce
   selector: #{criteria.selector.inspect}
@@ -243,6 +215,9 @@ module Mongoid
 }
       end
 
+      # Returns the selector of the command spec.
+      #
+      # @return [ Hash ] The selector.
       def command
         @map_reduce.send(:map_reduce_spec)[:selector]
       end