mongoid 8.0.5 → 8.1.0

data/lib/mongoid/errors/invalid_global_executor_concurrency.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad global executor concurrency option is attempted
+    # to be set.
+    class InvalidGlobalExecutorConcurrency < MongoidError
+
+      # Create the new error.
+      #
+      # @api private
+      def initialize
+        super(
+          compose_message(
+            "invalid_global_executor_concurrency"
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_storage_parent.rb

@@ -4,6 +4,8 @@ module Mongoid
   module Errors
 
     # Raised when calling store_in in a sub-class of Mongoid::Document
+    #
+    # @deprecated
     class InvalidStorageParent < MongoidError
 
       # Create the new error.

data/lib/mongoid/errors.rb

@@ -3,11 +3,14 @@
 require "mongoid/errors/mongoid_error"
 require "mongoid/errors/ambiguous_relationship"
 require "mongoid/errors/callback"
+require "mongoid/errors/create_collection_failure"
 require "mongoid/errors/criteria_argument_required"
 require "mongoid/errors/document_not_destroyed"
 require "mongoid/errors/document_not_found"
 require "mongoid/errors/empty_config_file"
+require "mongoid/errors/immutable_attribute"
 require "mongoid/errors/in_memory_collation_not_supported"
+require "mongoid/errors/invalid_async_query_executor"
 require "mongoid/errors/invalid_collection"
 require "mongoid/errors/invalid_config_file"
 require "mongoid/errors/invalid_config_option"
@@ -16,6 +19,7 @@ require "mongoid/errors/invalid_field"
 require "mongoid/errors/invalid_field_option"
 require "mongoid/errors/invalid_field_type"
 require "mongoid/errors/invalid_find"
+require "mongoid/errors/invalid_global_executor_concurrency"
 require "mongoid/errors/invalid_includes"
 require "mongoid/errors/invalid_index"
 require "mongoid/errors/invalid_options"
@@ -35,7 +39,6 @@ require "mongoid/errors/invalid_scope"
 require "mongoid/errors/invalid_session_use"
 require "mongoid/errors/invalid_set_polymorphic_relation"
 require "mongoid/errors/invalid_storage_options"
-require "mongoid/errors/invalid_storage_parent"
 require "mongoid/errors/invalid_time"
 require "mongoid/errors/inverse_not_found"
 require "mongoid/errors/mixed_relations"

data/lib/mongoid/extensions/object.rb

@@ -91,7 +91,7 @@ module Mongoid
       #   object.do_or_do_not(:use, "The Force")
       #
       # @param [ String | Symbol ] name The method name.
-      # @param [ Array ] args The arguments.
+      # @param [ Object... ] *args The arguments.
       #
       # @return [ Object | nil ] The result of the method call or nil if the
       #   method does not exist.
@@ -190,7 +190,7 @@ module Mongoid
       #   object.you_must(:use, "The Force")
       #
       # @param [ String | Symbol ] name The method name.
-      # @param [ Array ] args The arguments.
+      # @param [ Object... ] *args The arguments.
       #
       # @return [ Object | nil ] The result of the method call or nil if the
       #   method does not exist. Nil if the object is frozen.

data/lib/mongoid/extensions/time.rb

@@ -34,6 +34,8 @@ module Mongoid
         #   ::Time.configured
         #
         # @return [ Time ] The configured time.
+        #
+        # @deprecated
         def configured
           Mongoid.use_activesupport_time_zone? ? (::Time.zone || ::Time) : ::Time
         end

data/lib/mongoid/fields/localized.rb

@@ -31,6 +31,16 @@ module Mongoid
         true
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        options[:localize] == :present
+      end
+
       # Convert the provided string into a hash for the locale.
       #
       # @example Serialize the value.

data/lib/mongoid/fields/standard.rb

@@ -97,6 +97,16 @@ module Mongoid
         false
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        false
+      end
+
       # Get the metadata for the field if its a foreign key.
       #
       # @example Get the metadata.

data/lib/mongoid/fields.rb

@@ -538,6 +538,8 @@ module Mongoid
       #   Model.add_defaults(field)
       #
       # @param [ Field ] field The field to add for.
+      #
+      # @api private
       def add_defaults(field)
         default, name = field.default_val, field.name.to_s
         remove_defaults(name)
@@ -557,6 +559,8 @@ module Mongoid
       #
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The hash of options.
+      #
+      # @api private
       def add_field(name, options = {})
         aliased = options[:as]
         aliased_fields[aliased.to_s] = name if aliased
@@ -584,6 +588,8 @@ module Mongoid
       #   # => "called"
       #
       # @param [ Field ] field the field to process
+      #
+      # @api private
       def process_options(field)
         field_options = field.options
 
@@ -606,6 +612,8 @@ module Mongoid
       # @param [ Symbol ] name The name of the field.
       # @param [ Symbol ] meth The name of the accessor.
       # @param [ Hash ] options The options.
+      #
+      # @api private
       def create_accessors(name, meth, options = {})
         field = fields[name]
 
@@ -629,6 +637,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_getter(name, meth, field)
         generated_methods.module_eval do
           re_define_method(meth) do
@@ -651,6 +661,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_getter_before_type_cast(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_before_type_cast") do
@@ -671,6 +683,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}=") do |value|
@@ -690,6 +704,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}?") do
@@ -706,6 +722,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_translations_getter(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations") do
@@ -724,6 +742,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_translations_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations=") do |value|
@@ -743,6 +763,8 @@ module Mongoid
       #   Person.generated_methods
       #
       # @return [ Module ] The module of generated methods.
+      #
+      # @api private
       def generated_methods
         @generated_methods ||= begin
           mod = Module.new
@@ -757,21 +779,49 @@ module Mongoid
       #   Model.remove_defaults(name)
       #
       # @param [ String ] name The field name.
+      #
+      # @api private
       def remove_defaults(name)
         pre_processed_defaults.delete_one(name)
         post_processed_defaults.delete_one(name)
       end
 
+      # Create a field for the given name and options.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Hash ] options The hash of options.
+      #
+      # @return [ Field ] The created field.
+      #
+      # @api private
       def field_for(name, options)
         opts = options.merge(klass: self)
-        type_mapping = TYPE_MAPPINGS[options[:type]]
-        opts[:type] = type_mapping || unmapped_type(options)
-        if !opts[:type].is_a?(Class)
-          raise Errors::InvalidFieldType.new(self, name, options[:type])
+        opts[:type] = retrieve_and_validate_type(name, options[:type])
+        return Fields::Localized.new(name, opts) if options[:localize]
+        return Fields::ForeignKey.new(name, opts) if options[:identity]
+        Fields::Standard.new(name, opts)
+      end
+
+      # Get the class for the given type.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
+      #   type.
+      #
+      # @api private
+      def retrieve_and_validate_type(name, type)
+        type_mapping = TYPE_MAPPINGS[type]
+        result = type_mapping || unmapped_type(type)
+        if !result.is_a?(Class)
+          raise Errors::InvalidFieldType.new(self, name, type)
         else
-          if INVALID_BSON_CLASSES.include?(opts[:type])
-            warn_message = "Using #{opts[:type]} as the field type is not supported. "
-            if opts[:type] == BSON::Decimal128
+          if INVALID_BSON_CLASSES.include?(result)
+            warn_message = "Using #{result} as the field type is not supported. "
+            if result == BSON::Decimal128
               warn_message += "In BSON <= 4, the BSON::Decimal128 type will work as expected for both storing and querying, but will return a BigDecimal on query in BSON 5+."
             else
               warn_message += "Saving values of this type to the database will work as expected, however, querying them will return a value of the native Ruby Integer type."
@@ -779,16 +829,22 @@ module Mongoid
             Mongoid.logger.warn(warn_message)
           end
         end
-        return Fields::Localized.new(name, opts) if options[:localize]
-        return Fields::ForeignKey.new(name, opts) if options[:identity]
-        Fields::Standard.new(name, opts)
+        result
       end
 
-      def unmapped_type(options)
-        if "Boolean" == options[:type].to_s
+      # Returns the type of the field if the type was not in the TYPE_MAPPINGS
+      # hash.
+      #
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @api private
+      def unmapped_type(type)
+        if "Boolean" == type.to_s
           Mongoid::Boolean
         else
-          options[:type] || Object
+          type || Object
         end
       end
     end

data/lib/mongoid/findable.rb

@@ -22,18 +22,24 @@ module Mongoid
       :each,
       :each_with_index,
       :extras,
+      :fifth,
+      :fifth!,
       :find_one_and_delete,
       :find_one_and_replace,
       :find_one_and_update,
       :find_or_create_by,
       :find_or_create_by!,
       :find_or_initialize_by,
+      :first!,
       :first_or_create,
       :first_or_create!,
       :first_or_initialize,
       :for_js,
+      :fourth,
+      :fourth!,
       :geo_near,
       :includes,
+      :last!,
       :map_reduce,
       :max,
       :min,
@@ -41,11 +47,19 @@ module Mongoid
       :pick,
       :pluck,
       :read,
+      :second,
+      :second!,
+      :second_to_last,
+      :second_to_last!,
       :sum,
       :take,
       :take!,
       :tally,
       :text_search,
+      :third,
+      :third!,
+      :third_to_last,
+      :third_to_last!,
       :update,
       :update_all,
 
@@ -87,9 +101,19 @@ module Mongoid
     # @example Do any documents exist for the conditions?
     #   Person.exists?
     #
+    # @example Do any documents exist for given _id.
+    #   Person.exists?(BSON::ObjectId(...))
+    #
+    # @example Do any documents exist for given conditions.
+    #   Person.exists?(name: "...")
+    #
+    # @param [ Hash | Object | false ] id_or_conditions an _id to
+    #   search for, a hash of conditions, nil or false.
+    #
     # @return [ true | false ] If any documents exist for the conditions.
-    def exists?
-      with_default_scope.exists?
+    #   Always false if passed nil or false.
+    def exists?(id_or_conditions = :none)
+      with_default_scope.exists?(id_or_conditions)
     end
 
     # Finds a +Document+ or multiple documents by their _id values.
@@ -135,7 +159,7 @@ module Mongoid
     # @note Each argument can be an individual id, an array of ids or
     #   a nested array. Each array will be flattened.
     #
-    # @param [ Object | Array<Object> ] *args The _id value(s) to find.
+    # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #

data/lib/mongoid/interceptable.rb

@@ -79,7 +79,7 @@ module Mongoid
     # @example Run only the after save callbacks.
     #   model.run_after_callbacks(:save)
     #
-    # @param [ Array<Symbol> ] kinds The events that are occurring.
+    # @param [ Symbol... ] *kinds The events that are occurring.
     #
     # @return [ Object ] The result of the chain executing.
     def run_after_callbacks(*kinds)
@@ -96,7 +96,7 @@ module Mongoid
     # @example Run only the before save callbacks.
     #   model.run_before_callbacks(:save, :create)
     #
-    # @param [ Array<Symbol> ] kinds The events that are occurring.
+    # @param [ Symbol... ] *kinds The events that are occurring.
     #
     # @return [ Object ] The result of the chain executing.
     def run_before_callbacks(*kinds)
@@ -134,19 +134,20 @@ module Mongoid
     # Run the callbacks for embedded documents.
     #
     # @param [ Symbol ] kind The type of callback to execute.
-    # @param [ Array<Document> ] children Children to exeute callbacks on. If
+    # @param [ Array<Document> ] children Children to execute callbacks on. If
     #   nil, callbacks will be executed on all cascadable children of
     #   the document.
     #
     # @api private
     def _mongoid_run_child_callbacks(kind, children: nil, &block)
       child, *tail = (children || cascadable_children(kind))
+      with_children = !Mongoid::Config.prevent_multiple_calls_of_embedded_callbacks
       if child.nil?
-        return block&.call
+        block&.call
       elsif tail.empty?
-        return child.run_callbacks(child_callback_type(kind, child), &block)
+        child.run_callbacks(child_callback_type(kind, child), with_children: with_children, &block)
       else
-        return child.run_callbacks(child_callback_type(kind, child)) do
+        child.run_callbacks(child_callback_type(kind, child), with_children: with_children) do
           _mongoid_run_child_callbacks(kind, children: tail, &block)
         end
       end

data/lib/mongoid/matcher/eq_impl.rb

@@ -46,7 +46,7 @@ module Mongoid
         end
       end
 
-      # Per https://docs.mongodb.com/ruby-driver/current/tutorials/bson-v4/#time-instances,
+      # Per https://www.mongodb.com/docs/ruby-driver/current/tutorials/bson-v4/#time-instances,
       # > Times in BSON (and MongoDB) can only have millisecond precision. When Ruby Time instances
       # are serialized to BSON or Extended JSON, the times are floored to the nearest millisecond.
       #

data/lib/mongoid/matcher/type.rb

@@ -1,7 +1,7 @@
 module Mongoid
   module Matcher
 
-    # @see https://docs.mongodb.com/manual/reference/operator/query/type/
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/type/
     #
     # @api private
     module Type

data/lib/mongoid/persistable/creatable.rb

@@ -100,6 +100,7 @@ module Mongoid
       #
       # @return [ Document ] The document.
       def prepare_insert(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
         return self if performing_validations?(options) &&
           invalid?(options[:context] || :create)
         run_callbacks(:save, with_children: false) do

data/lib/mongoid/persistable/deletable.rb

@@ -16,7 +16,6 @@ module Mongoid
       #
       # @return [ TrueClass ] True.
       def delete(options = {})
-        raise Errors::ReadonlyDocument.new(self.class) if readonly?
         prepare_delete do
           unless options[:persist] == false
             if embedded?
@@ -102,6 +101,7 @@ module Mongoid
       #
       # @return [ Object ] The result of the block.
       def prepare_delete
+        raise Errors::ReadonlyDocument.new(self.class) if readonly?
         yield(self)
         freeze
         self.destroyed = true

data/lib/mongoid/persistable/savable.rb

@@ -14,7 +14,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.
+      #
+      # @return [ true | false ] True if success, false if not.
       def save(options = {})
         if new_record?
           !insert(options).new_record?
@@ -31,6 +37,12 @@ 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.
       #

data/lib/mongoid/persistable/unsettable.rb

@@ -13,8 +13,8 @@ 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.
       def unset(*fields)

data/lib/mongoid/persistable/updatable.rb

@@ -91,16 +91,23 @@ module Mongoid
       #
       # @param [ Hash ] options The options.
       #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time.
+      #
       # @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!
         return false if performing_validations?(options) &&
           invalid?(options[:context] || :update)
         process_flagged_destroys
+        update_children = cascadable_children(:update)
+        process_touch_option(options, update_children)
         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) do
+                _mongoid_run_child_callbacks(:update, children: update_children) do
                   result = yield(self)
                   self.previously_new_record = false
                   post_process_persist(result, options)
@@ -160,6 +167,49 @@ module Mongoid
           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)
+        unless options.fetch(:touch, true)
+          timeless
+          children.each(&:timeless)
+        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
     end
   end
 end

data/lib/mongoid/persistable/upsertable.rb

@@ -10,16 +10,32 @@ module Mongoid
       # database, then Mongo will insert a new one, otherwise the fields will get
       # overwritten with new values on the existing document.
       #
+      # If the replace option is true, unspecified attributes will be dropped,
+      # and if it is false, unspecified attributes will be maintained. The
+      # replace option defaults to true in Mongoid 8.1 and earlier. The default
+      # will be flipped to false in Mongoid 9.
+      #
       # @example Upsert the document.
       #   document.upsert
       #
+      # @example Upsert the document without replace.
+      #   document.upsert(replace: false)
+      #
       # @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.
+      #
       # @return [ true ] True.
       def upsert(options = {})
         prepare_upsert(options) do
-          collection.find(atomic_selector).replace_one(
+          if options.fetch(:replace, true)
+            collection.find(atomic_selector).replace_one(
               as_attributes, upsert: true, session: _session)
+          else
+            collection.find(atomic_selector).update_one(
+              { "$set" => as_attributes }, upsert: true, session: _session)
+          end
         end
       end
 
@@ -36,8 +52,11 @@ module Mongoid
       #
       # @param [ Hash ] options The options hash.
       #
+      # @option options [ true | false ] :validate Whether or not to validate.
+      #
       # @return [ true | false ] If the operation succeeded.
       def prepare_upsert(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
         return false if performing_validations?(options) && invalid?(:upsert)
         result = run_callbacks(:upsert) do
           yield(self)

data/lib/mongoid/persistable.rb

@@ -161,6 +161,8 @@ module Mongoid
     # @param [ Object ] result The result of the operation.
     # @param [ Hash ] options The options.
     #
+    # @option options [ true | false ] :validate Whether or not to validate.
+    #
     # @return [ true ] true.
     def post_process_persist(result, options = {})
       post_persist unless result == false
@@ -180,6 +182,7 @@ module Mongoid
     #
     # @return [ Object ] The result of the operation.
     def prepare_atomic_operation
+      raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
       operations = yield({})
       persist_or_delay_atomic_operation(operations)
       self