mongoid 8.1.7 → 9.0.0

data/lib/mongoid/config.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/config/defaults"
 require "mongoid/config/environment"
 require "mongoid/config/options"
 require "mongoid/config/validators"
+require "mongoid/config/introspection"
+require "mongoid/config/encryption"
 
 module Mongoid
 
@@ -13,16 +16,17 @@ module Mongoid
     extend Forwardable
     extend Options
     extend Defaults
+    extend Encryption
     extend self
 
     def_delegators ::Mongoid, :logger, :logger=
 
     LOCK = Mutex.new
 
-    # Application name that is printed to the mongodb logs upon establishing
-    # a connection in server versions >= 3.4. Note that the name cannot
-    # exceed 128 bytes. It is also used as the database name if the
-    # database name is not explicitly defined.
+    # Application name that is printed to the MongoDB logs upon establishing
+    # a connection. Note that the name cannot exceed 128 bytes in length.
+    # It is also used as the database name if the database name is not
+    # explicitly defined.
     option :app_name, default: nil
 
     # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
@@ -70,64 +74,12 @@ module Mongoid
     # existing method.
     option :scope_overwrite_exception, default: false
 
-    # Use ActiveSupport's time zone in time operations instead of the
-    # Ruby default time zone.
-    # @deprecated
-    option :use_activesupport_time_zone, default: true
-
     # Return stored times as UTC.
     option :use_utc, default: false
 
     # Store BigDecimals as Decimal128s instead of strings in the db.
     option :map_big_decimal_to_decimal128, default: true
 
-    # Update embedded documents correctly when setting it, unsetting it
-    # and resetting it. See MONGOID-5206 and MONGOID-5240 for more details.
-    option :broken_updates, default: false
-
-    # Maintain legacy behavior of === on Mongoid documents, which returns
-    # true in a number of cases where Ruby's === implementation would
-    # return false.
-    option :legacy_triple_equals, default: false
-
-    # When exiting a nested `with_scope' block, set the current scope to
-    # nil instead of the parent scope for backwards compatibility.
-    option :broken_scoping, default: false
-
-    # Maintain broken behavior of sum over empty result sets for backwards
-    # compatibility.
-    option :broken_aggregables, default: false
-
-    # Ignore aliased fields in embedded documents when performing pluck and
-    # distinct operations, for backwards compatibility.
-    option :broken_alias_handling, default: false
-
-    # Maintain broken `and' behavior when using the same operator on the same
-    # field multiple times for backwards compatibility.
-    option :broken_and, default: false
-
-    # Use millisecond precision when comparing Time objects with the _matches?
-    # function.
-    option :compare_time_by_ms, default: true
-
-    # Use bson-ruby's implementation of as_json for BSON::ObjectId instead of
-    # the one monkey-patched into Mongoid.
-    option :object_id_as_json_oid, default: false
-
-    # Maintain legacy behavior of pluck and distinct, which does not
-    # demongoize the values on returning them.
-    option :legacy_pluck_distinct, default: false
-
-    # Combine chained operators, which use the same field and operator,
-    # using and's instead of overwriting them.
-    option :overwrite_chained_operators, default: false
-
-    # When this flag is true, the attributes method on a document will return
-    # a BSON::Document when that document is retrieved from the database, and
-    # a Hash otherwise. When this flag is false, the attributes method will
-    # always return a Hash.
-    option :legacy_attributes, default: false
-
     # Allow BSON::Decimal128 to be parsed and returned directly in
     # field values. When BSON 5 is present and the this option is set to false
     # (the default), BSON::Decimal128 values in the database will be returned
@@ -136,14 +88,14 @@ module Mongoid
     # @note this option only has effect when BSON 5+ is present. Otherwise,
     #   the setting is ignored.
     option :allow_bson5_decimal128, default: false, on_change: -> (allow) do
-      if BSON::VERSION >= '5.0.0'
-        if allow
-          BSON::Registry.register(BSON::Decimal128::BSON_TYPE, BSON::Decimal128)
-        else
-          BSON::Registry.register(BSON::Decimal128::BSON_TYPE, BigDecimal)
+        if BSON::VERSION >= '5.0.0'
+          if allow
+            BSON::Registry.register(BSON::Decimal128::BSON_TYPE, BSON::Decimal128)
+          else
+            BSON::Registry.register(BSON::Decimal128::BSON_TYPE, BigDecimal)
+          end
         end
       end
-    end
 
     # Sets the async_query_executor for the application. By default the thread pool executor
     #   is set to `:immediate. Options are:
@@ -166,37 +118,58 @@ module Mongoid
     # deletable/destroyable, but they will be savable/updatable.
     # When this feature flag is turned on, the read-only state will be reset on
     # reload, but when it is turned off, it won't be.
-    option :legacy_readonly, default: true
+    option :legacy_readonly, default: false
+
+    # When this flag is false (the default as of Mongoid 9.0), a document that
+    # is created or loaded will remember the storage options that were active
+    # when it was loaded, and will use those same options by default when
+    # saving or reloading itself.
+    #
+    # When this flag is true you'll get pre-9.0 behavior, where a document will
+    # not remember the storage options from when it was loaded/created, and
+    # subsequent updates will need to explicitly set up those options each time.
+    #
+    # For example:
+    #
+    #    record = Model.with(collection: 'other_collection') { Model.first }
+    #
+    # This will try to load the first document from 'other_collection' and
+    # instantiate it as a Model instance. Pre-9.0, the record object would
+    # not remember that it came from 'other_collection', and attempts to
+    # update it or reload it would fail unless you first remembered to
+    # explicitly specify the collection every time.
+    #
+    # As of Mongoid 9.0, the record will remember that it came from
+    # 'other_collection', and updates and reloads will automatically default
+    # to that collection, for that record object.
+    option :legacy_persistence_context_behavior, default: false
 
     # When this flag is true, any attempt to change the _id of a persisted
     # document will raise an exception (`Errors::ImmutableAttribute`).
-    # This will be the default in 9.0. When this flag is false (the default
-    # in 8.x), changing the _id of a persisted document might be ignored,
-    # or it might work, depending on the situation.
-    option :immutable_ids, default: false
+    # This is the default in 9.0. Setting this flag to false restores the
+    # pre-9.0 behavior, where changing the _id of a persisted
+    # document might be ignored, or it might work, depending on the situation.
+    option :immutable_ids, default: true
 
     # When this flag is true, callbacks for every embedded document will be
     # called only once, even if the embedded document is embedded in multiple
     # documents in the root document's dependencies graph.
-    # This will be the default in 9.0. Setting this flag to false restores the
+    # This is the default in 9.0. Setting this flag to false restores the
     # pre-9.0 behavior, where callbacks are called for every occurrence of an
     # embedded document. The pre-9.0 behavior leads to a problem that for multi
     # level nested documents callbacks are called multiple times.
     # See https://jira.mongodb.org/browse/MONGOID-5542
-    option :prevent_multiple_calls_of_embedded_callbacks, default: false
+    option :prevent_multiple_calls_of_embedded_callbacks, default: true
 
-    # When this flag is true, callbacks for embedded documents will not be
-    # called. This is the default in 8.x, but will be changed to false in 9.0.
-    #
-    # Setting this flag to true (as it is in 8.x) may lead to stack
-    # overflow errors if there are more than cicrca 1000 embedded
-    # documents in the root document's dependencies graph.
-    #
-    # It is strongly recommended to set this flag to false in 8.x, if you
-    # are not using around callbacks for embedded documents.
+    # When this flag is false, callbacks for embedded documents will not be
+    # called. This is the default in 9.0.
     #
+    # Setting this flag to true restores the pre-9.0 behavior, where callbacks
+    # for embedded documents are called. This may lead to stack overflow errors
+    # if there are more than cicrca 1000 embedded documents in the root
+    # document's dependencies graph.
     # See https://jira.mongodb.org/browse/MONGOID-5658 for more details.
-    option :around_callbacks_for_embeds, default: true
+    option :around_callbacks_for_embeds, default: false
 
     # Returns the Config singleton, for use in the configure DSL.
     #
@@ -403,10 +376,14 @@ module Mongoid
     #   config.running_with_passenger?
     #
     # @return [ true | false ] If the app is deployed on Passenger.
+    #
+    # @deprecated
     def running_with_passenger?
       @running_with_passenger ||= defined?(PhusionPassenger)
     end
 
+    Mongoid.deprecate(self, :running_with_passenger?)
+
     private
 
     def set_log_levels
@@ -439,18 +416,7 @@ module Mongoid
     end
 
     module DeprecatedOptions
-      OPTIONS = %i[ use_activesupport_time_zone
-                    broken_aggregables
-                    broken_alias_handling
-                    broken_and
-                    broken_scoping
-                    broken_updates
-                    compare_time_by_ms
-                    legacy_attributes
-                    legacy_pluck_distinct
-                    legacy_triple_equals
-                    object_id_as_json_oid
-                    overwrite_chained_operators ]
+      OPTIONS = %i[]
 
       if RUBY_VERSION < '3.0'
         def self.prepended(klass)

data/lib/mongoid/contextual/aggregable/memory.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Contextual

data/lib/mongoid/contextual/aggregable/mongo.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/contextual/aggregable"
 
@@ -28,11 +29,7 @@ module Mongoid
         def aggregates(field)
           result = collection.aggregate(pipeline(field), session: _session).to_a
           if result.empty?
-            if Mongoid.broken_aggregables
-              { "count" => 0, "sum" => nil, "avg" => nil, "min" => nil, "max" => nil }
-            else
-              Aggregable::EMPTY_RESULT.dup
-            end
+            Aggregable::EMPTY_RESULT.dup
           else
             result.first
           end

data/lib/mongoid/contextual/aggregable/none.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/contextual/aggregable"
 

data/lib/mongoid/contextual/aggregable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Contextual

data/lib/mongoid/contextual/atomic.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
+# 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.
@@ -52,6 +59,18 @@ module Mongoid
         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.
@@ -150,23 +169,72 @@ module Mongoid
       # @example Unset the field on the matches.
       #   context.unset(:name)
       #
-      # @param [ [ String | Symbol | Array<String | Symbol> | Hash ]... ] *args
-      #   The name(s) of the field(s) to unset.
-      #   If a Hash is specified, its keys will be used irrespective of what
-      #   each key's value is, even if the value is nil or false.
+      # @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 unset(*args)
-        fields = args.map { |a| a.is_a?(Hash) ? a.keys : a }
-                     .__find_args__
-                     .map { |f| [database_field_name(f), true] }
-        view.update_many("$unset" => Hash[fields])
+      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 +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,7 +1,10 @@
 # frozen_string_literal: true
+# 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.

data/lib/mongoid/contextual/map_reduce.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Contextual
+
+    # Represents a mapReduce database command instruction.
     class MapReduce
       extend Forwardable
       include Enumerable
@@ -212,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

data/lib/mongoid/contextual/memory.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/contextual/aggregable/memory"
 require "mongoid/association/eager_loadable"
 
 module Mongoid
   module Contextual
+
+    # Context object used for performing bulk query and persistence
+    # operations on documents which have been loaded into application
+    # memory. The method interface of this class is consistent with
+    # Mongoid::Contextual::Mongo.
     class Memory
       include Enumerable
       include Aggregable::Memory
@@ -78,11 +84,7 @@ module Mongoid
       #
       # @return [ Array<Object> ] The distinct values for the field.
       def distinct(field)
-        if Mongoid.legacy_pluck_distinct
-          documents.map{ |doc| doc.send(field) }.uniq
-        else
-          pluck(field).uniq
-        end
+        pluck(field).uniq
       end
 
       # Iterate over the context. If provided a block, yield to a Mongoid
@@ -156,7 +158,7 @@ module Mongoid
       #
       # @return [ Document ] The first document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def first!
         first || raise_document_not_found_error
@@ -217,7 +219,7 @@ module Mongoid
       #
       # @return [ Document ] The last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def last!
         last || raise_document_not_found_error
@@ -256,12 +258,8 @@ module Mongoid
       #
       # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
-        if Mongoid.legacy_pluck_distinct
-          documents.pluck(*fields)
-        else
-          documents.map do |doc|
-            pluck_from_doc(doc, *fields)
-          end
+        documents.map do |doc|
+          pluck_from_doc(doc, *fields)
         end
       end
 
@@ -319,7 +317,7 @@ module Mongoid
       #
       # @return [ Document ] The document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def take!
         take || raise_document_not_found_error
@@ -380,8 +378,6 @@ module Mongoid
       # @example Get the second document.
       #   context.second
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The second document.
       def second
         eager_load([documents.second]).first
@@ -395,7 +391,7 @@ module Mongoid
       #
       # @return [ Document ] The second document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def second!
         second || raise_document_not_found_error
@@ -406,8 +402,6 @@ module Mongoid
       # @example Get the third document.
       #   context.third
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The third document.
       def third
         eager_load([documents.third]).first
@@ -421,7 +415,7 @@ module Mongoid
       #
       # @return [ Document ] The third document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def third!
         third || raise_document_not_found_error
@@ -432,8 +426,6 @@ module Mongoid
       # @example Get the fourth document.
       #   context.fourth
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The fourth document.
       def fourth
         eager_load([documents.fourth]).first
@@ -447,7 +439,7 @@ module Mongoid
       #
       # @return [ Document ] The fourth document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def fourth!
         fourth || raise_document_not_found_error
@@ -458,8 +450,6 @@ module Mongoid
       # @example Get the fifth document.
       #   context.fifth
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The fifth document.
       def fifth
         eager_load([documents.fifth]).first
@@ -473,7 +463,7 @@ module Mongoid
       #
       # @return [ Document ] The fifth document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def fifth!
         fifth || raise_document_not_found_error
@@ -484,8 +474,6 @@ module Mongoid
       # @example Get the second to last document.
       #   context.second_to_last
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The second to last document.
       def second_to_last
         eager_load([documents.second_to_last]).first
@@ -499,7 +487,7 @@ module Mongoid
       #
       # @return [ Document ] The second to last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def second_to_last!
         second_to_last || raise_document_not_found_error
@@ -510,8 +498,6 @@ module Mongoid
       # @example Get the third to last document.
       #   context.third_to_last
       #
-      # @param [ Integer ] limit The number of documents to return.
-      #
       # @return [ Document ] The third to last document.
       def third_to_last
         eager_load([documents.third_to_last]).first
@@ -525,7 +511,7 @@ module Mongoid
       #
       # @return [ Document ] The third to last document.
       #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      # @raise [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
       def third_to_last!
         third_to_last || raise_document_not_found_error
@@ -641,7 +627,8 @@ module Mongoid
         end
       end
 
-      # Compare two values, checking for nil.
+      # Compare two values, handling the cases when
+      # either value is nil.
       #
       # @api private
       #
@@ -649,15 +636,15 @@ module Mongoid
       #   context.compare(a, b)
       #
       # @param [ Object ] a The first object.
-      # @param [ Object ] b The first object.
+      # @param [ Object ] b The second object.
       #
       # @return [ Integer ] The comparison value.
       def compare(a, b)
-        case
-        when a.nil? then b.nil? ? 0 : 1
-        when b.nil? then -1
-        else a <=> b
-        end
+        return 0 if a.nil? && b.nil?
+        return 1 if a.nil?
+        return -1 if b.nil?
+
+        compare_operand(a) <=> compare_operand(b)
       end
 
       # Sort the documents in place.
@@ -669,9 +656,8 @@ module Mongoid
       def in_place_sort(values)
         documents.sort! do |a, b|
           values.map do |field, direction|
-            a_value, b_value = a[field], b[field]
-            direction * compare(a_value.__sortable__, b_value.__sortable__)
-          end.find { |value| !value.zero? } || 0
+            direction * compare(a[field], b[field])
+          end.detect { |value| !value.zero? } || 0
         end
       end
 
@@ -697,6 +683,23 @@ module Mongoid
         @criteria.send(:_session)
       end
 
+      # Get the operand value to be used in comparison.
+      # Adds capability to sort boolean values.
+      #
+      # @example Get the comparison operand.
+      #   compare_operand(true) #=> 1
+      #
+      # @param [ Object ] value The value to be used in comparison.
+      #
+      # @return [ Integer | Object ] The comparison operand.
+      def compare_operand(value)
+        case value
+        when TrueClass then 1
+        when FalseClass then 0
+        else value
+        end
+      end
+
       # Retrieve the value for the current document at the given field path.
       #
       # For example, if I have the following models: