mongoid 8.1.7 → 9.0.0

data/lib/mongoid/criteria.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/criteria/findable"
 require "mongoid/criteria/includable"
@@ -40,6 +41,26 @@ module Mongoid
     include Clients::Sessions
     include Options
 
+    class << self
+      # Convert the given hash to a criteria. Will iterate over each keys in the
+      # hash which must correspond to method on a criteria object. The hash
+      # must also include a "klass" key.
+      #
+      # @example Convert the hash to a criteria.
+      #   Criteria.from_hash({ klass: Band, where: { name: "Depeche Mode" })
+      #
+      # @param [ Hash ] hash The hash to convert.
+      #
+      # @return [ Criteria ] The criteria.
+      def from_hash(hash)
+        criteria = Criteria.new(hash.delete(:klass) || hash.delete('klass'))
+        hash.each_pair do |method, args|
+          criteria = criteria.__send__(method, args)
+        end
+        criteria
+      end
+    end
+
     # Static array used to check with method missing - we only need to ever
     # instantiate once.
     CHECK = []
@@ -90,7 +111,8 @@ module Mongoid
     #   enumerator = criteria.find(-> { "Default Band" })
     #
     # @param [ [ Object | Array<Object> ]... ] *args The id(s).
-    # @param [ Proc ] block Optional block to pass.
+    # @param &block Optional block to pass.
+    # @yield [ Object ] Yields each enumerable element to the block.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #
@@ -158,7 +180,7 @@ module Mongoid
     #
     # @return [ Object ] The id.
     def extract_id
-      selector.extract_id
+      selector['_id'] || selector[:_id] || selector['id'] || selector[:id]
     end
 
     # Adds a criterion to the +Criteria+ that specifies additional options
@@ -221,7 +243,7 @@ module Mongoid
     # may be desired.
     #
     # @example Merge the criteria with another criteria.
-    #   criteri.merge(other_criteria)
+    #   criteria.merge(other_criteria)
     #
     # @example Merge the criteria with a hash. The hash must contain a klass
     #   key and the key/value pairs correspond to method names/args.
@@ -246,16 +268,16 @@ module Mongoid
     # @example Merge another criteria into this criteria.
     #   criteria.merge(Person.where(name: "bob"))
     #
-    # @param [ Criteria ] other The criteria to merge in.
+    # @param [ Criteria | Hash ] other The criteria to merge in.
     #
     # @return [ Criteria ] The merged criteria.
     def merge!(other)
-      criteria = other.to_criteria
-      selector.merge!(criteria.selector)
-      options.merge!(criteria.options)
-      self.documents = criteria.documents.dup unless criteria.documents.empty?
-      self.scoping_options = criteria.scoping_options
-      self.inclusions = (inclusions + criteria.inclusions).uniq
+      other = self.class.from_hash(other) if other.is_a?(Hash)
+      selector.merge!(other.selector)
+      options.merge!(other.options)
+      self.documents = other.documents.dup unless other.documents.empty?
+      self.scoping_options = other.scoping_options
+      self.inclusions = (inclusions + other.inclusions).uniq
       self
     end
 
@@ -348,9 +370,11 @@ module Mongoid
     #   criteria.to_criteria
     #
     # @return [ Criteria ] self.
+    # @deprecated
     def to_criteria
       self
     end
+    Mongoid.deprecate(self, :to_criteria)
 
     # Convert the criteria to a proc.
     #
@@ -437,6 +461,8 @@ module Mongoid
     # @param [ Hash ] scope The scope for the code.
     #
     # @return [ Criteria ] The criteria.
+    #
+    # @deprecated
     def for_js(javascript, scope = {})
       code = if scope.empty?
         # CodeWithScope is not supported for $where as of MongoDB 4.4
@@ -446,6 +472,7 @@ module Mongoid
       end
       js_query(code)
     end
+    Mongoid.deprecate(self, :for_js)
 
     private
 

data/lib/mongoid/deprecable.rb

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

data/lib/mongoid/deprecation.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
   # Utility class for logging deprecation warnings.
   class Deprecation < ::ActiveSupport::Deprecation
 
-    @gem_name = 'Mongoid'
+    def initialize
+      # Per change policy, deprecations will be removed in the next major version.
+      deprecation_horizon = "#{Mongoid::VERSION.split('.').first.to_i + 1}.0".freeze
+      gem_name = 'Mongoid'
+      super(deprecation_horizon, gem_name)
+    end
 
-    # Per change policy, deprecations will be removed in the next major version.
-    @deprecation_horizon = "#{Mongoid::VERSION.split('.').first.to_i + 1}.0".freeze
 
     # Overrides default ActiveSupport::Deprecation behavior
     # to use Mongoid's logger.
     #
-    # @return Array<Proc> The deprecation behavior.
+    # @return [ Array<Proc> ] The deprecation behavior.
     def behavior
       @behavior ||= Array(->(*args) {
         logger = Mongoid.logger

data/lib/mongoid/document.rb

@@ -1,25 +1,24 @@
 # frozen_string_literal: true
 
-require "mongoid/positional"
-require "mongoid/evolvable"
-require "mongoid/extensions"
-require "mongoid/errors"
-require "mongoid/threaded"
-require "mongoid/atomic"
-require "mongoid/attributes"
-require "mongoid/contextual"
-require "mongoid/copyable"
-require "mongoid/equality"
-require "mongoid/criteria"
-require "mongoid/factory"
-require "mongoid/fields"
-require "mongoid/timestamps"
-require "mongoid/association"
-require "mongoid/composable"
-require "mongoid/touchable"
+require 'mongoid/positional'
+require 'mongoid/evolvable'
+require 'mongoid/extensions'
+require 'mongoid/errors'
+require 'mongoid/threaded'
+require 'mongoid/atomic'
+require 'mongoid/attributes'
+require 'mongoid/contextual'
+require 'mongoid/copyable'
+require 'mongoid/equality'
+require 'mongoid/criteria'
+require 'mongoid/factory'
+require 'mongoid/fields'
+require 'mongoid/timestamps'
+require 'mongoid/association'
+require 'mongoid/composable'
+require 'mongoid/touchable'
 
 module Mongoid
-
   # This is the base module for all domain objects that need to be persisted to
   # the database as documents.
   module Document
@@ -84,7 +83,7 @@ module Mongoid
     #
     # @return [ Array ] An array containing [document.class, document._id]
     def identity
-      [ self.class, self._id ]
+      [ self.class, _id ]
     end
 
     # Instantiate a new +Document+, setting the Document's attributes if
@@ -95,7 +94,7 @@ module Mongoid
     # otherwise it will be set to a fresh +BSON::ObjectId+ string.
     #
     # @example Create a new document.
-    #   Person.new(:title => "Sir")
+    #   Person.new(:title => 'Sir')
     #
     # @param [ Hash ] attrs The attributes to set up the document with.
     #
@@ -136,33 +135,6 @@ module Mongoid
       BSON::Document.new(as_attributes)
     end
 
-    # Calls #as_json on the document with additional, Mongoid-specific options.
-    #
-    # @note Rails 6 changes return value of as_json for non-primitive types
-    #   such as BSON::ObjectId. In Rails <= 5, as_json returned these as
-    #   instances of the class. In Rails 6, these are returned serialized to
-    #   primitive types (e.g. {"$oid"=>"5bcfc40bde340b37feda98e9"}).
-    #   See https://github.com/rails/rails/commit/2e5cb980a448e7f4ab00df6e9ad4c1cc456616aa
-    #   for more information.
-    #
-    # @example Get the document as json.
-    #   document.as_json(compact: true)
-    #
-    # @param [ Hash ] options The options.
-    #
-    # @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::Warnings.warn_as_json_compact_deprecated
-        rv = rv.compact
-      end
-      rv
-    end
-
     # Returns an instance of the specified class with the attributes,
     # errors, and embedded documents of the current document.
     #
@@ -175,34 +147,52 @@ module Mongoid
     #
     # @return [ Document ] An instance of the specified class.
     def becomes(klass)
-      unless klass.include?(Mongoid::Document)
-        raise ArgumentError, "A class which includes Mongoid::Document is expected"
-      end
+      mongoid_document_check!(klass)
 
       became = klass.new(clone_document)
-      became._id = _id
-      became.instance_variable_set(:@changed_attributes, changed_attributes)
-      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[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|
-        without_autobuild do
-          relation = became.__send__(name)
-          Array.wrap(relation).each do |r|
-            r.instance_variable_set(:@new_record, new_record?)
-          end
-        end
-      end
+      became.internal_state = internal_state
 
       became
     end
 
+    # Sets the internal state of this document. Used only by #becomes to
+    # help initialize a retyped document.
+    #
+    # @param [ Hash ] state The map of internal state values.
+    #
+    # @api private
+    def internal_state=(state)
+      self._id = state[:id]
+      @changed_attributes = state[:changed_attributes]
+      @errors = ActiveModel::Errors.new(self).tap { |e| e.copy!(state[:errors]) }
+      @new_record = state[:new_record]
+      @destroyed = state[:destroyed]
+
+      update_discriminator(state[:discriminator_key_was])
+
+      mark_persisted_state_for_embedded_documents(state[:new_record])
+    end
+
+    # Handles the setup and execution of callbacks, if callbacks are to
+    # be executed; otherwise, adds the appropriate callbacks to the pending
+    # callbacks list.
+    #
+    # @param execute_callbacks [ true | false ] Whether callbacks should be
+    #   executed or not.
+    #
+    # @api private
+    def _handle_callbacks_after_instantiation(execute_callbacks)
+      if execute_callbacks
+        apply_defaults
+        yield self if block_given?
+        run_callbacks(:find) unless _find_callbacks.empty?
+        run_callbacks(:initialize) unless _initialize_callbacks.empty?
+      else
+        yield self if block_given?
+        self.pending_callbacks += %i[ apply_defaults find initialize ]
+      end
+    end
+
     private
 
     # Does the construction of a document.
@@ -224,28 +214,29 @@ module Mongoid
     def construct_document(attrs = nil, options = {})
       execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
 
-      @__parent = nil
+      self._parent = nil
       _building do
-        @new_record = true
-        @attributes ||= {}
-        apply_pre_processed_defaults
-        apply_default_scoping
+        prepare_to_process_attributes
+
         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
+        resolve_post_construction_callbacks(execute_callbacks)
       end
       self
     end
 
+    # Initializes the object state prior to attribute processing; this is
+    # called only from #construct_document.
+    def prepare_to_process_attributes
+      @new_record = true
+      @attributes ||= {}
+      apply_pre_processed_defaults
+      apply_default_scoping
+    end
+
     # Returns the logger
     #
     # @return [ Logger ] The configured logger or a default Logger instance.
@@ -260,7 +251,7 @@ module Mongoid
     #
     # @return [ String ] The model key.
     def model_key
-      @model_cache_key ||= self.class.model_name.cache_key
+      @model_key ||= self.class.model_name.cache_key
     end
 
     # Returns a hash of the attributes.
@@ -273,28 +264,103 @@ module Mongoid
     # @return [ Hash ] The attributes hash.
     def as_attributes
       return attributes if frozen?
+
       embedded_relations.each_pair do |name, meta|
         without_autobuild do
-          relation, stored = send(name), meta.store_as
-          if attributes.key?(stored) || !relation.blank?
-            if !relation.nil?
-              attributes[stored] = relation.send(:as_attributes)
-            else
-              attributes.delete(stored)
-            end
-          end
+          add_attributes_for_relation(name, meta)
         end
       end
+
       attributes
     end
 
-    module ClassMethods
+    # Adds the attributes for the given relation to the document's attributes.
+    #
+    # @param name [ String | Symbol ] the name of the relation to add
+    # @param meta [ Mongoid::Assocation::Relatable ] the relation object
+    def add_attributes_for_relation(name, meta)
+      relation, stored = send(name), meta.store_as
+      return unless attributes.key?(stored) || !relation.blank?
 
+      if relation.nil?
+        attributes.delete(stored)
+      else
+        attributes[stored] = relation.send(:as_attributes)
+      end
+    end
+
+    # Checks that the given argument is an instance of `Mongoid::Document`.
+    #
+    # @param klass [ Class ] The class to test.
+    #
+    # @raise [ ArgumentError ] if the class does not include
+    #   Mongoid::Document.
+    def mongoid_document_check!(klass)
+      return if klass.include?(Mongoid::Document)
+
+      raise ArgumentError, 'A class which includes Mongoid::Document is expected'
+    end
+
+    # Constructs a hash representing the internal state of this object,
+    # suitable for passing to #internal_state=.
+    #
+    # @return [ Hash ] the map of internal state values
+    def internal_state
+      {
+        id: _id,
+        changed_attributes: changed_attributes,
+        errors: errors,
+        new_record: new_record?,
+        destroyed: destroyed?,
+        discriminator_key_was: self.class.discriminator_value
+      }
+    end
+
+    # Updates the value of the discriminator_key for this object, setting its
+    # previous value to `key_was`.
+    #
+    # @param key_was [ String ] the previous value of the discriminator key.
+    def update_discriminator(key_was)
+      changed_attributes[self.class.discriminator_key] = key_was
+      self[self.class.discriminator_key] = self.class.discriminator_value
+    end
+
+    # Marks all embedded documents with the given "new_record" state.
+    #
+    # @param [ true | false ] new_record  whether or not the embedded records
+    #   should be flagged as new records or not.
+    def mark_persisted_state_for_embedded_documents(new_record)
+      embedded_relations.each_pair do |name, _meta|
+        without_autobuild do
+          relation = __send__(name)
+          Array.wrap(relation).each do |r|
+            r.instance_variable_set(:@new_record, new_record)
+          end
+        end
+      end
+    end
+
+    # Either executes or enqueues the post-construction callbacks.
+    #
+    # @param [ true | false ] execute_callbacks whether the callbacks
+    #   should be executed (true) or enqueued (false)
+    def resolve_post_construction_callbacks(execute_callbacks)
+      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
+
+    # Class-level methods for Document objects.
+    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
+      # @param [ true | false ] execute_callbacks Whether callbacks should be
       #   suppressed or not.
       def with_callbacks(execute_callbacks)
         saved, Threaded.execute_callbacks =
@@ -308,13 +374,11 @@ module Mongoid
       # the attributes have already been typecast.
       #
       # @example Create the document.
-      #   Person.instantiate(:title => "Sir", :age => 30)
+      #   Person.instantiate(:title => 'Sir', :age => 30)
       #
       # @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)
@@ -331,6 +395,9 @@ module Mongoid
       # @option options [ true | false ] :execute_callbacks Flag specifies
       #   whether callbacks should be run.
       #
+      # @yield [ Mongoid::Document ] If a block is given, yields the newly
+      #   instantiated document to it.
+      #
       # @return [ Document ] A new document.
       #
       # @note A Ruby 2.x bug prevents the options hash from being keyword
@@ -338,32 +405,18 @@ module Mongoid
       #   the options hash as keyword arguments.
       #
       # @api private
-      def instantiate_document(attrs = nil, selected_fields = nil, options = {})
+      def instantiate_document(attrs = nil, selected_fields = nil, options = {}, &block)
         execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
-        attributes = if Mongoid.legacy_attributes
-          attrs
-        else
-          attrs&.to_h
-        end || {}
+        attributes = attrs&.to_h || {}
 
         doc = allocate
         doc.__selected_fields = selected_fields
         doc.instance_variable_set(:@attributes, attributes)
-        # 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.instance_variable_set(:@attributes_before_type_cast, attributes.dup)
+
+        doc._handle_callbacks_after_instantiation(execute_callbacks, &block)
 
+        doc.remember_storage_options!
         doc
       end
 
@@ -395,7 +448,7 @@ module Mongoid
       #
       # @return [ Array<Class> ] All subclasses of the current document.
       def _types
-        @_type ||= (descendants + [ self ]).uniq.map(&:discriminator_value)
+        @_types ||= (descendants + [ self ]).uniq.map(&:discriminator_value)
       end
 
       # Clear the @_type cache. This is generally called when changing the discriminator
@@ -406,7 +459,7 @@ module Mongoid
       #
       # @api private
       def _mongoid_clear_types
-        @_type = nil
+        @_types = nil
         superclass._mongoid_clear_types if hereditary?
       end
 

data/lib/mongoid/encryptable.rb

@@ -0,0 +1,53 @@
+# rubocop:todo all
+module Mongoid
+  # This module is used to extend Mongoid::Document
+  # to add encryption functionality.
+  module Encryptable
+    extend ActiveSupport::Concern
+
+    included do
+      # @return [Hash] The encryption metadata for the model.
+      class_attribute :encrypt_metadata
+      self.encrypt_metadata = {}
+    end
+
+    module ClassMethods
+      # Set the encryption metadata for the model. Parameters set here will be
+      # used to encrypt the fields of the model, unless overridden on the
+      # field itself.
+      #
+      # @param [ Hash ] options The encryption metadata.
+      # @option options [ String ] :key_id The base64-encoded UUID of the key
+      #   used to encrypt fields. Mutually exclusive with :key_name_field option.
+      # @option options [ String ] :key_name_field The name of the field that
+      #   contains the key alt name to use for encryption. Mutually exclusive
+      #   with :key_id option.
+      # @option options [ true | false ] :deterministic Whether the encryption
+      # is deterministic or not.
+      def encrypt_with(options = {})
+        self.encrypt_metadata = options
+      end
+
+      # Whether the model is encrypted. It means that either the encrypt_with
+      # method was called on the model, or at least one of the fields
+      # is encrypted.
+      #
+      # @return [ true | false ] Whether the model is encrypted.
+      def encrypted?
+        !encrypt_metadata.empty? || fields.any? { |_, field| field.is_a?(Mongoid::Fields::Encrypted) }
+      end
+
+      # Override the key_id for the model.
+      #
+      # This method is solely for testing purposes and should not be used in
+      # the application code. The schema_map is generated very early in the
+      # application lifecycle, and overriding the key_id after that will not
+      # have any effect.
+      #
+      # @api private
+      def set_key_id(key_id)
+        self.encrypt_metadata[:key_id] = key_id
+      end
+    end
+  end
+end

data/lib/mongoid/equality.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
@@ -34,22 +35,6 @@ module Mongoid
           attributes["_id"] == other.attributes["_id"]
     end
 
-    # 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.class === other : self == other
-      else
-        super
-      end
-    end
-
     # Delegates to ==. Used when needing checks in hashes.
     #
     # @example Perform equality checking.
@@ -72,11 +57,7 @@ module Mongoid
       #
       # @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
+        other.is_a?(self)
       end
     end
   end

data/lib/mongoid/errors/ambiguous_relationship.rb

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