mongoid 7.1.1 → 8.1.0

data/lib/mongoid/document.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/positional"
 require "mongoid/evolvable"
@@ -40,8 +39,6 @@ module Mongoid
     # that should be used instead.
     # When ruby driver 2.3.0 is released and Mongoid can be updated
     # to require >= 2.3.0, the BSON constant can be used.
-    #
-    # @since 6.0.0
     ILLEGAL_KEY = /(\A[$])|(\.)/.freeze
 
     # Freezes the internal attributes of the document.
@@ -50,8 +47,6 @@ module Mongoid
     #   document.freeze
     #
     # @return [ Document ] The document.
-    #
-    # @since 2.0.0
     def freeze
       as_attributes.freeze and self
     end
@@ -61,9 +56,7 @@ module Mongoid
     # @example Check if frozen
     #   document.frozen?
     #
-    # @return [ true, false ] True if frozen, else false.
-    #
-    # @since 2.0.0
+    # @return [ true | false ] True if frozen, else false.
     def frozen?
       attributes.frozen?
     end
@@ -78,8 +71,6 @@ module Mongoid
     #   document.hash
     #
     # @return [ Integer ] The hash of the document's identity.
-    #
-    # @since 1.0.0
     def hash
       identity.hash
     end
@@ -92,8 +83,6 @@ module Mongoid
     #   document.identity
     #
     # @return [ Array ] An array containing [document.class, document._id]
-    #
-    # @since 3.0.0
     def identity
       [ self.class, self._id ]
     end
@@ -111,23 +100,8 @@ module Mongoid
     # @param [ Hash ] attrs The attributes to set up the document with.
     #
     # @return [ Document ] A new document.
-    #
-    # @since 1.0.0
-    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.
@@ -136,8 +110,6 @@ module Mongoid
     #   document.model_name
     #
     # @return [ String ] The model name.
-    #
-    # @since 3.0.16
     def model_name
       self.class.model_name
     end
@@ -148,22 +120,8 @@ module Mongoid
     #   document.to_key
     #
     # @return [ String ] The id of the document or nil if new.
-    #
-    # @since 2.4.0
     def to_key
-      (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.
-    #
-    # @since 1.0.0
-    def to_a
-      [ self ]
+      (persisted? || destroyed?) ? [ _id.to_s ] : nil
     end
 
     # Return a hash of the entire document hierarchy from this document and
@@ -174,8 +132,6 @@ module Mongoid
     #   person.as_document
     #
     # @return [ Hash ] A hash of all attributes in the hierarchy.
-    #
-    # @since 1.0.0
     def as_document
       BSON::Document.new(as_attributes)
     end
@@ -194,15 +150,14 @@ module Mongoid
     #
     # @param [ Hash ] options The options.
     #
-    # @option options [ true, false ] :compact Whether to include fields with
-    #   nil values in the json document.
+    # @option options [ true | false ] :compact (Deprecated) Whether to include fields
+    #   with nil values in the json document.
     #
     # @return [ Hash ] The document as json.
-    #
-    # @since 5.1.0
     def as_json(options = nil)
       rv = super
       if options && options[:compact]
+        Mongoid::Warnings.warn_as_json_compact_deprecated
         rv = rv.compact
       end
       rv
@@ -219,8 +174,6 @@ module Mongoid
     # @param [ Class ] klass The class to become.
     #
     # @return [ Document ] An instance of the specified class.
-    #
-    # @since 2.0.0
     def becomes(klass)
       unless klass.include?(Mongoid::Document)
         raise ArgumentError, "A class which includes Mongoid::Document is expected"
@@ -229,12 +182,13 @@ module Mongoid
       became = klass.new(clone_document)
       became._id = _id
       became.instance_variable_set(:@changed_attributes, changed_attributes)
-      became.instance_variable_set(:@errors, ActiveModel::Errors.new(became))
-      became.errors.instance_variable_set(:@messages, errors.instance_variable_get(:@messages))
+      new_errors = ActiveModel::Errors.new(became)
+      new_errors.copy!(errors)
+      became.instance_variable_set(:@errors, new_errors)
       became.instance_variable_set(:@new_record, new_record?)
       became.instance_variable_set(:@destroyed, destroyed?)
-      became.changed_attributes["_type"] = self.class.to_s
-      became._type = klass.to_s
+      became.changed_attributes[klass.discriminator_key] = self.class.discriminator_value
+      became[klass.discriminator_key] = klass.discriminator_value
 
       # mark embedded docs as persisted
       embedded_relations.each_pair do |name, meta|
@@ -251,11 +205,50 @@ 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.
-    #
-    # @since 2.2.0
     def logger
       Mongoid.logger
     end
@@ -266,26 +259,18 @@ module Mongoid
     #   model.model_key
     #
     # @return [ String ] The model key.
-    #
-    # @since 2.4.0
     def model_key
       @model_cache_key ||= self.class.model_name.cache_key
     end
 
-    # Implement this for calls to flatten on array.
+    # Returns a hash of the attributes.
     #
-    # @example Get the document as an array.
-    #   document.to_ary
+    # 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 [ nil ] Always nil.
-    #
-    # @since 2.1.0
-    def to_ary
-      nil
-    end
-
-    private
-
+    # @return [ Hash ] The attributes hash.
     def as_attributes
       return attributes if frozen?
       embedded_relations.each_pair do |name, meta|
@@ -305,18 +290,18 @@ module Mongoid
 
     module ClassMethods
 
-      # Performs class equality checking.
+      # 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.
       #
-      # @example Compare the classes.
-      #   document === other
-      #
-      # @param [ Document, Object ] other The other object to compare with.
-      #
-      # @return [ true, false ] True if the classes are equal, false if not.
-      #
-      # @since 2.0.0.rc.4
-      def ===(other)
-        other.class == Class ? self <= other : other.is_a?(self)
+      # @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
@@ -328,39 +313,106 @@ 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.
       #
-      # @since 1.0.0
-      def instantiate(attrs = nil, selected_fields = nil)
-        attributes = attrs || {}
+      # @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_document(attrs = nil, selected_fields = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+        attributes = if Mongoid.legacy_attributes
+          attrs
+        else
+          attrs&.to_h
+        end || {}
+
         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.
       #   document._types
       #
       # @return [ Array<Class> ] All subclasses of the current document.
-      #
-      # @since 1.0.0
       def _types
-        @_type ||= (descendants + [ self ]).uniq.map(&:to_s)
+        @_type ||= (descendants + [ self ]).uniq.map(&:discriminator_value)
+      end
+
+      # Clear the @_type cache. This is generally called when changing the discriminator
+      # key/value on a class.
+      #
+      # @example Get the types.
+      #   document._mongoid_clear_types
+      #
+      # @api private
+      def _mongoid_clear_types
+        @_type = nil
+        superclass._mongoid_clear_types if hereditary?
       end
 
       # Set the i18n scope to overwrite ActiveModel.
       #
       # @return [ Symbol ] :mongoid
-      #
-      # @since 2.0.0
       def i18n_scope
         :mongoid
       end
@@ -371,8 +423,6 @@ module Mongoid
       #   Person.logger
       #
       # @return [ Logger ] The configured logger or a default Logger instance.
-      #
-      # @since 2.2.0
       def logger
         Mongoid.logger
       end

data/lib/mongoid/equality.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
 
   # This module contains the behavior of Mongoid's clone/dup of documents.
   module Equality
+    # Leave the current contents of this module outside of InstanceMethods
+    # to prevent cherry picking conflicts. For now...
+    extend ActiveSupport::Concern
 
     # Default comparison is via the string version of the id.
     #
@@ -14,8 +16,6 @@ module Mongoid
     # @param [ Document ] other The document to compare with.
     #
     # @return [ Integer ] -1, 0, 1.
-    #
-    # @since 1.0.0
     def <=>(other)
       attributes["_id"].to_s <=> other.attributes["_id"].to_s
     end
@@ -26,11 +26,9 @@ module Mongoid
     # @example Compare for equality.
     #   document == other
     #
-    # @param [ Document, Object ] other The other object to compare with.
-    #
-    # @return [ true, false ] True if the ids are equal, false if not.
+    # @param [ Document | Object ] other The other object to compare with.
     #
-    # @since 1.0.0
+    # @return [ true | false ] True if the ids are equal, false if not.
     def ==(other)
       self.class == other.class &&
           attributes["_id"] == other.attributes["_id"]
@@ -41,13 +39,15 @@ module Mongoid
     # @example Compare the classes.
     #   document === other
     #
-    # @param [ Document, Object ] other The other object to compare with.
-    #
-    # @return [ true, false ] True if the classes are equal, false if not.
+    # @param [ Document | Object ] other The other object to compare with.
     #
-    # @since 1.0.0
+    # @return [ true | false ] True if the classes are equal, false if not.
     def ===(other)
-      other.class == Class ? self.class === other : self == other
+      if Mongoid.legacy_triple_equals
+        other.class == Class ? self.class === other : self == other
+      else
+        super
+      end
     end
 
     # Delegates to ==. Used when needing checks in hashes.
@@ -55,13 +55,29 @@ 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.
-    #
-    # @since 1.0.0
+    # @return [ true | false ] True if equal, false if not.
     def eql?(other)
       self == (other)
     end
+
+    module ClassMethods
+      # Performs class equality checking.
+      #
+      # @example Compare the classes.
+      #   document === other
+      #
+      # @param [ Document | Object ] other The other object to compare with.
+      #
+      # @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)
+        else
+          other.is_a?(self)
+        end
+      end
+    end
   end
 end

data/lib/mongoid/errors/ambiguous_relationship.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Errors
 
-    # This error is raised in case of an ambigous association.
+    # This error is raised in case of an ambiguous association.
     #
-    # @example An ambigous association.
+    # @example An ambiguous association.
     #   class Person
     #     include Mongoid::Document
     #
@@ -33,8 +32,6 @@ module Mongoid
       # @param [ Class ] inverse The inverse class.
       # @param [ Symbol ] name The relation name.
       # @param [ Array<Symbol> ] candidates The potential inverses.
-      #
-      # @since 3.0.0
       def initialize(klass, inverse, name, candidates)
         super(
           compose_message(

data/lib/mongoid/errors/callback.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Errors
@@ -15,8 +14,6 @@ module Mongoid
       #
       # @param [ Class ] klass The class of the document.
       # @param [ Symbol ] method The name of the method.
-      #
-      # @since 2.2.0
       def initialize(klass, method)
         super(
           compose_message("callbacks", { klass: klass, method: method })

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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Errors

data/lib/mongoid/errors/delete_restriction.rb

@@ -1,27 +1,23 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Errors
 
-    # This error is raised when calling #save! or .create! on a model when one
-    # of the callbacks returns false.
+    # This error is raised when attempting to destroy a model which has
+    # an association with dependency option set to restrict.
     class DeleteRestriction < MongoidError
 
       # Create the new callbacks error.
       #
-      # @example Create the new callbacks error.
-      #   Callbacks.new(Post, :create!)
-      #
-      # @param [ Class ] document
-      # @param [ Symbol ] association
-      #
-      # @since 3.0.0
-      def initialize(document, relation)
+      # @param [ Document ] document The document that was attempted to be
+      #   destroyed.
+      # @param [ Symbol ] association_name The name of the dependent
+      #   association that prevents the document from being deleted.
+      def initialize(document, association_name)
         super(
           compose_message(
             "delete_restriction",
-            { document: document.class, relation: relation }
+            { document: document.class, relation: association_name }
           )
         )
       end

data/lib/mongoid/errors/document_not_destroyed.rb

@@ -1,24 +1,19 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Errors
 
-    # Raised when attempting to destroy a document that had destory callbacks
+    # Raised when attempting to destroy a document that had destroy callbacks
     # return false.
-    #
-    # @since 4.0.0
     class DocumentNotDestroyed < MongoidError
 
-      # Instnatiate the exception.
+      # Instantiate the exception.
       #
       # @example Create the error.
       #   DocumentNotDestroyed.new(Band)
       #
       # @param [ Object ] id The document id.
       # @param [ Class ] klass The document class.
-      #
-      # @since 4.0.0
       def initialize(id, klass)
         super(compose_message("document_not_destroyed", { id: id.inspect, klass: klass }))
       end