mongoid 7.5.4 → 8.1.7

data/lib/mongoid/document.rb

@@ -56,7 +56,7 @@ module Mongoid
     # @example Check if frozen
     #   document.frozen?
     #
-    # @return [ true, false ] True if frozen, else false.
+    # @return [ true | false ] True if frozen, else false.
     def frozen?
       attributes.frozen?
     end
@@ -100,21 +100,8 @@ module Mongoid
     # @param [ Hash ] attrs The attributes to set up the document with.
     #
     # @return [ Document ] A new document.
-    def initialize(attrs = nil)
-      @__parent = nil
-      _building do
-        @new_record = true
-        @attributes ||= {}
-        apply_pre_processed_defaults
-        apply_default_scoping
-        process_attributes(attrs) do
-          yield(self) if block_given?
-        end
-        apply_post_processed_defaults
-        # @todo: #2586: Need to have access to parent document in these
-        #   callbacks.
-        run_callbacks(:initialize) unless _initialize_callbacks.empty?
-      end
+    def initialize(attrs = nil, &block)
+      construct_document(attrs, &block)
     end
 
     # Return the model name of the document.
@@ -137,18 +124,6 @@ module Mongoid
       (persisted? || destroyed?) ? [ _id.to_s ] : nil
     end
 
-    # Return an array with this +Document+ only in it.
-    #
-    # @example Return the document in an array.
-    #   document.to_a
-    #
-    # @return [ Array<Document> ] An array with the document as its only item.
-    #
-    # @deprecated
-    def to_a
-      [ self ]
-    end
-
     # Return a hash of the entire document hierarchy from this document and
     # below. Used when the attributes are needed for everything and not just
     # the current document.
@@ -175,14 +150,14 @@ module Mongoid
     #
     # @param [ Hash ] options The options.
     #
-    # @option options [ true, false ] :compact (Deprecated) Whether to include fields
+    # @option options [ true | false ] :compact (Deprecated) Whether to include fields
     #   with nil values in the json document.
     #
     # @return [ Hash ] The document as json.
     def as_json(options = nil)
       rv = super
       if options && options[:compact]
-        Mongoid.logger.warn('#as_json :compact option is deprecated. Please call #compact on the returned Hash object instead.')
+        Mongoid::Warnings.warn_as_json_compact_deprecated
         rv = rv.compact
       end
       rv
@@ -230,6 +205,47 @@ module Mongoid
 
     private
 
+    # Does the construction of a document.
+    #
+    # @param [ Hash ] attrs The attributes to set up the document with.
+    # @param [ Hash ] options The options to use.
+    #
+    # @option options [ true | false ] :execute_callbacks Flag specifies
+    #   whether callbacks should be run.
+    #
+    # @return [ Document ] A new document.
+    #
+    # @note A Ruby 2.x bug prevents the options hash from being keyword
+    #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+    #   the options hash as keyword arguments.
+    #   See https://bugs.ruby-lang.org/issues/15753
+    #
+    # @api private
+    def construct_document(attrs = nil, options = {})
+      execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+
+      @__parent = nil
+      _building do
+        @new_record = true
+        @attributes ||= {}
+        apply_pre_processed_defaults
+        apply_default_scoping
+        process_attributes(attrs) do
+          yield(self) if block_given?
+        end
+        @attributes_before_type_cast = @attributes.merge(attributes_before_type_cast)
+
+        if execute_callbacks
+          apply_post_processed_defaults
+          run_callbacks(:initialize) unless _initialize_callbacks.empty?
+        else
+          pending_callbacks << :apply_post_processed_defaults
+          pending_callbacks << :initialize
+        end
+      end
+      self
+    end
+
     # Returns the logger
     #
     # @return [ Logger ] The configured logger or a default Logger instance.
@@ -247,6 +263,14 @@ module Mongoid
       @model_cache_key ||= self.class.model_name.cache_key
     end
 
+    # Returns a hash of the attributes.
+    #
+    # Note this method modifies the attributes hash that already exists on the
+    # class and returns it. This means that the hash returned by this method
+    # refers to the same hash as calling #attributes on the instance. See
+    # MONGOID-4476 for an explanation on how this is used.
+    #
+    # @return [ Hash ] The attributes hash.
     def as_attributes
       return attributes if frozen?
       embedded_relations.each_pair do |name, meta|
@@ -266,6 +290,20 @@ module Mongoid
 
     module ClassMethods
 
+      # Indicate whether callbacks should be invoked by default or not,
+      # within the block. Callbacks may always be explicitly invoked by passing
+      # `execute_callbacks: true` where available.
+      #
+      # @params execute_callbacks [ true | false ] Whether callbacks should be
+      #   suppressed or not.
+      def with_callbacks(execute_callbacks)
+        saved, Threaded.execute_callbacks =
+          Threaded.execute_callbacks?, execute_callbacks
+        yield
+      ensure
+        Threaded.execute_callbacks = saved
+      end
+
       # Instantiate a new object, only when loaded from the database or when
       # the attributes have already been typecast.
       #
@@ -275,11 +313,33 @@ module Mongoid
       # @param [ Hash ] attrs The hash of attributes to instantiate with.
       # @param [ Integer ] selected_fields The selected fields from the
       #   criteria.
+      # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
+      #   should be run.
+      #
+      # @return [ Document ] A new document.
+      def instantiate(attrs = nil, selected_fields = nil, &block)
+        instantiate_document(attrs, selected_fields, &block)
+      end
+
+      # Instantiate the document.
+      #
+      # @param [ Hash ] attrs The hash of attributes to instantiate with.
+      # @param [ Integer ] selected_fields The selected fields from the
+      #   criteria.
+      # @param [ Hash ] options The options to use.
+      #
+      # @option options [ true | false ] :execute_callbacks Flag specifies
+      #   whether callbacks should be run.
       #
       # @return [ Document ] A new document.
       #
+      # @note A Ruby 2.x bug prevents the options hash from being keyword
+      #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+      #   the options hash as keyword arguments.
+      #
       # @api private
-      def instantiate(attrs = nil, selected_fields = nil)
+      def instantiate_document(attrs = nil, selected_fields = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
         attributes = if Mongoid.legacy_attributes
           attrs
         else
@@ -289,13 +349,45 @@ module Mongoid
         doc = allocate
         doc.__selected_fields = selected_fields
         doc.instance_variable_set(:@attributes, attributes)
-        doc.apply_defaults
-        yield(doc) if block_given?
-        doc.run_callbacks(:find) unless doc._find_callbacks.empty?
-        doc.run_callbacks(:initialize) unless doc._initialize_callbacks.empty?
+        # TODO: remove the to_h when the legacy_attributes flag is removed.
+        # The to_h ensures that we don't accidentally make attributes_before_type_cast
+        # a BSON::Document.
+        doc.instance_variable_set(:@attributes_before_type_cast, attributes&.to_h.dup)
+
+        if execute_callbacks
+          doc.apply_defaults
+          yield(doc) if block_given?
+          doc.run_callbacks(:find) unless doc._find_callbacks.empty?
+          doc.run_callbacks(:initialize) unless doc._initialize_callbacks.empty?
+        else
+          yield(doc) if block_given?
+          doc.pending_callbacks += [:apply_defaults, :find, :initialize]
+        end
+
         doc
       end
 
+      # Allocates and constructs a document.
+      #
+      # @param [ Hash ] attrs The attributes to set up the document with.
+      # @param [ Hash ] options The options to use.
+      #
+      # @option options [ true | false ] :execute_callbacks Flag specifies
+      #   whether callbacks should be run.
+      #
+      # @note A Ruby 2.x bug prevents the options hash from being keyword
+      #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+      #   the options hash as keyword arguments.
+      #   See https://bugs.ruby-lang.org/issues/15753
+      #
+      # @return [ Document ] A new document.
+      #
+      # @api private
+      def construct_document(attrs = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+        with_callbacks(execute_callbacks) { new(attrs) }
+      end
+
       # Returns all types to query for when using this class as the base.
       #
       # @example Get the types.

data/lib/mongoid/equality.rb

@@ -26,9 +26,9 @@ module Mongoid
     # @example Compare for equality.
     #   document == other
     #
-    # @param [ Document, Object ] other The other object to compare with.
+    # @param [ Document | Object ] other The other object to compare with.
     #
-    # @return [ true, false ] True if the ids are equal, false if not.
+    # @return [ true | false ] True if the ids are equal, false if not.
     def ==(other)
       self.class == other.class &&
           attributes["_id"] == other.attributes["_id"]
@@ -39,9 +39,9 @@ module Mongoid
     # @example Compare the classes.
     #   document === other
     #
-    # @param [ Document, Object ] other The other object to compare with.
+    # @param [ Document | Object ] other The other object to compare with.
     #
-    # @return [ true, false ] True if the classes are equal, false if not.
+    # @return [ true | false ] True if the classes are equal, false if not.
     def ===(other)
       if Mongoid.legacy_triple_equals
         other.class == Class ? self.class === other : self == other
@@ -55,9 +55,9 @@ module Mongoid
     # @example Perform equality checking.
     #   document.eql?(other)
     #
-    # @param [ Document, Object ] other The object to check against.
+    # @param [ Document | Object ] other The object to check against.
     #
-    # @return [ true, false ] True if equal, false if not.
+    # @return [ true | false ] True if equal, false if not.
     def eql?(other)
       self == (other)
     end
@@ -68,9 +68,9 @@ module Mongoid
       # @example Compare the classes.
       #   document === other
       #
-      # @param [ Document, Object ] other The other object to compare with.
+      # @param [ Document | Object ] other The other object to compare with.
       #
-      # @return [ true, false ] True if the classes are equal, false if not.
+      # @return [ true | false ] True if the classes are equal, false if not.
       def ===(other)
         if Mongoid.legacy_triple_equals
           other.class == Class ? self <= other : other.is_a?(self)

data/lib/mongoid/errors/create_collection_failure.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to create a collection failed.
+    class CreateCollectionFailure < MongoidError
+
+      # Instantiate the create collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to create.
+      # @param [ Hash ] collection_options The options that were used when
+      #   tried to create the collection.
+      # @param [ Mongo::Error::OperationFailure ] error The error raised when
+      #   tried to create the collection.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "create_collection_failure",
+                {
+                  collection_name: collection_name,
+                  collection_options: collection_options,
+                  error: "#{error.class}: #{error.message}"
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/document_not_found.rb

@@ -19,8 +19,9 @@ module Mongoid
       #   DocumentNotFound.new(Person, :ssn => "1234", :name => "Helen")
       #
       # @param [ Class ] klass The model class.
-      # @param [ Hash, Array, Object ] params The attributes or ids.
-      # @param [ Array ] unmatched The unmatched ids, if appropriate
+      # @param [ Hash | Array | Object ] params The attributes or ids.
+      # @param [ Array | Hash ] unmatched The unmatched ids, if appropriate. If
+      #   there is a shard key this will be a hash.
       def initialize(klass, params, unmatched = nil)
         if !unmatched && !params.is_a?(Hash)
           unmatched = Array(params) if params
@@ -35,7 +36,8 @@ module Mongoid
               searched: searched(params),
               attributes: params,
               total: total(params),
-              missing: missing(unmatched)
+              missing: missing(unmatched),
+              shard_key: shard_key(unmatched)
             }
           )
         )
@@ -48,12 +50,14 @@ module Mongoid
       # @example Get the missing string.
       #   error.missing(1)
       #
-      # @param [ Object, Array ] unmatched The ids that did not match.
+      # @param [ Object | Array ] unmatched The ids that did not match.
       #
       # @return [ String ] The missing string.
       def missing(unmatched)
         if unmatched.is_a?(::Array)
           unmatched.join(", ")
+        elsif unmatched.is_a?(::Hash)
+          unmatched[:_id] || unmatched["_id"]
         else
           unmatched
         end
@@ -64,7 +68,7 @@ module Mongoid
       # @example Get the searched string.
       #   error.searched(1)
       #
-      # @param [ Object, Array ] params The ids that were searched for.
+      # @param [ Object | Array ] params The ids that were searched for.
       #
       # @return [ String ] The searched string.
       def searched(params)
@@ -80,7 +84,7 @@ module Mongoid
       # @example Get the total.
       #   error.total([ 1, 2, 3 ])
       #
-      # @param [ Object, Array ] params What was searched for.
+      # @param [ Object | Array ] params What was searched for.
       #
       # @return [ Integer ] The total number.
       def total(params)

data/lib/mongoid/errors/drop_collection_failure.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to drop a collection failed.
+    class DropCollectionFailure < MongoidError
+
+      # Instantiate the drop collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to drop.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "drop_collection_failure",
+                {
+                  collection_name: collection_name
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/immutable_attribute.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when attempting the change the value of an
+    # immutable attribute. For example, the _id attribute is immutable,
+    # and attempting to change it on a document that has already been
+    # persisted will result in this error.
+    class ImmutableAttribute < MongoidError
+
+      # Create the new error.
+      #
+      # @example Create the new error.
+      #   ImmutableAttribute.new(:_id, "1234")
+      #
+      # @param [ Symbol | String ] name The name of the attribute.
+      # @param [ Object ] value The attempted set value.
+      def initialize(name, value)
+        super(
+          compose_message("immutable_attribute", { name: name, value: value })
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_async_query_executor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad async query executor option is attempted
+    # to be set.
+    class InvalidQueryExecutor < MongoidError
+
+      # Create the new error.
+      #
+      # @param [ Symbol | String ] executor The attempted async query executor.
+      #
+      # @api private
+      def initialize(executor)
+        super(
+          compose_message(
+            "invalid_async_query_executor",
+            { executor: executor, options: [:immediate, :global_thread_pool] }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_config_option.rb

@@ -12,7 +12,7 @@ module Mongoid
       # @example Create the new error.
       #   InvalidConfigOption.new(:name, [ :option ])
       #
-      # @param [ Symbol, String ] name The attempted config option name.
+      # @param [ Symbol | String ] name The attempted config option name.
       def initialize(name)
         super(
           compose_message(

data/lib/mongoid/errors/invalid_dependent_strategy.rb

@@ -13,7 +13,7 @@ module Mongoid
       #
       # @param [ Mongoid::Association ] association The association for which this
       #   dependency is defined.
-      # @param [ Symbol, String ] invalid_strategy The attempted invalid strategy.
+      # @param [ Symbol | String ] invalid_strategy The attempted invalid strategy.
       # @param [ Array<Symbol> ] valid_strategies The valid strategies.
       def initialize(association, invalid_strategy, valid_strategies)
         super(

data/lib/mongoid/errors/invalid_dot_dollar_assignment.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when trying to use the setter for a field that starts
+    # with a dollar sign ($) or contains a dot/period (.).
+    class InvalidDotDollarAssignment < MongoidError
+
+      # Create the new error.
+      #
+      # @param [ Class ] klass The class of the document.
+      # @param [ Class ] attr The attribute attempted to be written.
+      #
+      # @api private
+      def initialize(klass, attr)
+        super(
+          compose_message("invalid_dot_dollar_assignment", { klass: klass, attr: attr })
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_field.rb

@@ -12,14 +12,18 @@ module Mongoid
       # @example Create the error.
       #   InvalidField.new(person, :crazy_method_name)
       #
+      # @api private
+      #
       # @param [ Class ] klass The document class.
+      # @param [ Symbol ] field The field name.
       # @param [ Symbol ] name The method name.
-      def initialize(klass, name)
+      def initialize(klass, field, name)
         super(
           compose_message(
             "invalid_field",
             {
               name: name,
+              field: field,
               origin: origin(klass, name),
               file: location(klass, name)[0],
               line: location(klass, name)[1]
@@ -38,7 +42,7 @@ module Mongoid
       # @param [ Class ] klass The document class.
       # @param [ Symbol ] name The method name.
       #
-      # @return [ Class, Module ] The originating class or module.
+      # @return [ Class | Module ] The originating class or module.
       def origin(klass, name)
         klass.instance_method(name).owner
       end

data/lib/mongoid/errors/invalid_field_type.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when trying to define a field using a :type option value
+    # that is not present in the field type mapping.
+    class InvalidFieldType < MongoidError
+
+      # Create the new error.
+      #
+      # @example Instantiate the error.
+      #   InvalidFieldType.new('Person', 'first_name', 'stringgy')
+      #
+      # @param [ String ] klass The model class.
+      # @param [ String ] field The field on which the invalid type is used.
+      # @param [ Symbol | String ] type The value of the field :type option.
+      def initialize(klass, field, type)
+        super(
+          compose_message('invalid_field_type',
+            klass: klass, field: field, type_inspection: type.inspect)
+        )
+      end
+    end
+  end
+end

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_relation.rb

@@ -38,7 +38,7 @@ module Mongoid
       # @param [ Class ] klass The document class.
       # @param [ Symbol ] name The method name.
       #
-      # @return [ Class, Module ] The originating class or module.
+      # @return [ Class | Module ] The originating class or module.
       def origin(klass, name)
         klass.instance_method(name).owner
       end

data/lib/mongoid/errors/invalid_relation_option.rb

@@ -12,7 +12,7 @@ module Mongoid
       #   InvalidRelationOption.new(Person, invalid_option: 'make_me_a_sandwich')
       #
       # @param [ Class ] klass The model class.
-      # @param [ String, Symbol ] name The association name.
+      # @param [ String | Symbol ] name The association name.
       # @param [ Symbol ] option The invalid option.
       # @param [ Array<Symbol> ] valid_options The valid option.
       def initialize(klass, name, option, valid_options)

data/lib/mongoid/errors/invalid_session_use.rb

@@ -12,7 +12,7 @@ module Mongoid
       # @example Create the error.
       #   InvalidSessionUse.new(:invalid_session_use)
       #
-      # @param [ :invalid_session_use, :invalid_session_nesting ] error_type The type of session misuse.
+      # @param [ :invalid_session_use | :invalid_session_nesting ] error_type The type of session misuse.
       def initialize(error_type)
         super(compose_message(error_type.to_s))
       end

data/lib/mongoid/errors/invalid_storage_options.rb

@@ -12,7 +12,7 @@ module Mongoid
       #   InvalidStorageOptions.new(Person, invalid_option: 'name')
       #
       # @param [ Class ] klass The model class.
-      # @param [ Hash, String, Symbol ] options The provided options.
+      # @param [ Hash | String | Symbol ] options The provided options.
       def initialize(klass, options)
         super(
           compose_message(

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/mongoid_error.rb

@@ -53,7 +53,7 @@ module Mongoid
       # @example Create the problem.
       #   error.problem("error", {})
       #
-      # @param [ String, Symbol ] key The error key.
+      # @param [ String | Symbol ] key The error key.
       # @param [ Hash ] attributes The attributes to interpolate.
       #
       # @return [ String ] The problem.
@@ -66,7 +66,7 @@ module Mongoid
       # @example Create the summary.
       #   error.summary("error", {})
       #
-      # @param [ String, Symbol ] key The error key.
+      # @param [ String | Symbol ] key The error key.
       # @param [ Hash ] attributes The attributes to interpolate.
       #
       # @return [ String ] The summary.
@@ -79,7 +79,7 @@ module Mongoid
       # @example Create the resolution.
       #   error.resolution("error", {})
       #
-      # @param [ String, Symbol ] key The error key.
+      # @param [ String | Symbol ] key The error key.
       # @param [ Hash ] attributes The attributes to interpolate.
       #
       # @return [ String ] The resolution.

data/lib/mongoid/errors/nested_attributes_metadata_not_found.rb

@@ -13,7 +13,7 @@ module Mongoid
       #   NestedAttributesMetadataNotFound.new(klass, name)
       #
       # @param [ Class ] klass The class of the document.
-      # @param [ Symbol, String ] name The name of the association
+      # @param [ Symbol | String ] name The name of the association
       def initialize(klass, name)
         super(
           compose_message(

data/lib/mongoid/errors/no_client_database.rb

@@ -11,7 +11,7 @@ module Mongoid
       # @example Create the new error.
       #   NoClientDatabase.new(:default, {}})
       #
-      # @param [ Symbol, String ] name The db config key.
+      # @param [ Symbol | String ] name The db config key.
       # @param [ Hash ] config The hash configuration options.
       def initialize(name, config)
         super(