mongoid 8.1.5 → 9.0.0

data/lib/mongoid/factory.rb

@@ -1,11 +1,137 @@
 # frozen_string_literal: true
 
 module Mongoid
-
   # Instantiates documents that came from the database.
   module Factory
     extend self
 
+    # A helper class for instantiating a model using either it's type
+    # class directly, or via a type class specified via a discriminator
+    # key.
+    #
+    # @api private
+    class Instantiator
+      # @return [ Mongoid::Document ] The primary model class being referenced
+      attr_reader :klass
+
+      # @return [ Hash | nil ] The Hash of attributes to use when
+      #   instantiating the model.
+      attr_reader :attributes
+
+      # @return [ Mongoid::Criteria | nil ] The criteria object to
+      #   use as a secondary source for the selected fields; also used when
+      #   setting the inverse association.
+      attr_reader :criteria
+
+      # @return [ Array | nil ] The list of field names that should
+      #   be explicitly (and exclusively) included in the new record.
+      attr_reader :selected_fields
+
+      # @return [ String | nil ] The identifier of the class that
+      #   should be loaded and instantiated, in the case of a polymorphic
+      #   class specification.
+      attr_reader :type
+
+      # Creates a new Factory::Initiator.
+      #
+      # @param klass [ Mongoid::Document ] The primary class to reference when
+      #   instantiating the model.
+      # @param attributes [ Hash | nil ] (Optional) The hash of attributes to
+      #   use when instantiating the model.
+      # @param criteria [ Mongoid::Criteria | nil ] (Optional) The criteria
+      #   object to use as a secondary source for the selected fields; also
+      #   used when setting the inverse association.
+      # @param selected_fields [ Array | nil ] The list of field names that
+      #   should be explicitly (and exclusively) included in the new record.
+      def initialize(klass, attributes, criteria, selected_fields)
+        @klass = klass
+        @attributes = attributes
+        @criteria = criteria
+        @selected_fields = selected_fields ||
+                           (criteria && criteria.options[:fields])
+        @type = attributes && attributes[klass.discriminator_key]
+      end
+
+      # Builds and returns a new instance of the requested class.
+      #
+      # @param execute_callbacks [ true | false ] Whether or not the Document
+      #   callbacks should be invoked with the new instance.
+      #
+      # @raise [ Errors::UnknownModel ] when the requested type does not exist,
+      #   or if it does not respond to the `instantiate` method.
+      #
+      # @return [ Mongoid::Document ] The new document instance.
+      def instance(execute_callbacks: Threaded.execute_callbacks?)
+        if type.blank?
+          instantiate_without_type(execute_callbacks)
+        else
+          instantiate_with_type(execute_callbacks)
+        end
+      end
+
+      private
+
+      # Instantiate the given class without any given subclass.
+      #
+      # @param [ true | false ] execute_callbacks Whether this method should
+      #   invoke document callbacks.
+      #
+      # @return [ Document ] The instantiated document.
+      def instantiate_without_type(execute_callbacks)
+        klass.instantiate_document(attributes, selected_fields, execute_callbacks: execute_callbacks).tap do |obj|
+          if criteria&.association && criteria&.parent_document
+            obj.set_relation(criteria.association.inverse, criteria.parent_document)
+          end
+        end
+      end
+
+      # Instantiate the given `type`, which must map to another Mongoid::Document
+      # model.
+      #
+      # @param [ true | false ] execute_callbacks Whether this method should
+      #   invoke document callbacks.
+      #
+      # @return [ Document ] The instantiated document.
+      def instantiate_with_type(execute_callbacks)
+        constantized_type.instantiate_document(
+          attributes, selected_fields,
+          execute_callbacks: execute_callbacks
+        )
+      end
+
+      # Retreive the `Class` instance of the requested type, either by finding it
+      # in the `klass` discriminator mapping, or by otherwise finding a
+      # Document model with the given name.
+      #
+      # @return [ Mongoid::Document ] the requested Document model
+      def constantized_type
+        @constantized_type ||= begin
+          constantized = klass.get_discriminator_mapping(type) || constantize(type)
+
+          # Check if the class is a Document class
+          raise Errors::UnknownModel.new(camelized, type) unless constantized.respond_to?(:instantiate)
+
+          constantized
+        end
+      end
+
+      # Attempts to convert the argument into a Class object by camelizing
+      # it and treating the result as the name of a constant.
+      #
+      # @param type [ String ] The name of the type to constantize
+      #
+      # @raise [ Errors::UnknownModel ] if the argument does not correspond to
+      #   an existing constant.
+      #
+      # @return [ Class ] the Class that the type resolves to
+      def constantize(type)
+        camelized = type.camelize
+        camelized.constantize
+      rescue NameError
+        raise Errors::UnknownModel.new(camelized, type)
+      end
+    end
+
     # Builds a new +Document+ from the supplied attributes.
     #
     # This method either instantiates klass or a descendant of klass if the attributes include
@@ -20,17 +146,12 @@ module Mongoid
     #
     # @param [ Class ] klass The class to instantiate from if _type is not present.
     # @param [ Hash ] attributes The document attributes.
-    # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
+    #
+    # @option options [ true | false ] :execute_callbacks Flag specifies whether callbacks
     #   should be run.
     #
     # @return [ Document ] The instantiated document.
     def build(klass, attributes = nil)
-      # A bug in Ruby 2.x (including 2.7.7) causes the attributes hash to be
-      # interpreted as keyword arguments, because execute_build accepts
-      # a keyword argument. Forcing an empty set of keyword arguments works
-      # around the bug. Once Ruby 2.x support is dropped, this hack can be
-      # removed.
-      # See https://bugs.ruby-lang.org/issues/15753
       execute_build(klass, attributes)
     end
 
@@ -110,38 +231,11 @@ module Mongoid
     # @return [ Document ] The instantiated document.
     #
     # @api private
-    def execute_from_db(klass, attributes = nil, criteria = nil, selected_fields = nil, execute_callbacks: Threaded.execute_callbacks?)
-      if criteria
-        selected_fields ||= criteria.options[:fields]
-      end
-      type = (attributes || {})[klass.discriminator_key]
-      if type.blank?
-        obj = klass.instantiate_document(attributes, selected_fields, execute_callbacks: execute_callbacks)
-        if criteria && criteria.association && criteria.parent_document
-          obj.set_relation(criteria.association.inverse, criteria.parent_document)
-        end
-        obj
-      else
-        constantized = klass.get_discriminator_mapping(type)
-
-        unless constantized
-          camelized = type.camelize
-
-          # Check if the class exists
-          begin
-            constantized = camelized.constantize
-          rescue NameError
-            raise Errors::UnknownModel.new(camelized, type)
-          end
-        end
-
-        # Check if the class is a Document class
-        if !constantized.respond_to?(:instantiate)
-          raise Errors::UnknownModel.new(camelized, type)
-        end
-
-        constantized.instantiate_document(attributes, selected_fields, execute_callbacks: execute_callbacks)
-      end
+    def execute_from_db(klass, attributes = nil, criteria = nil,
+                        selected_fields = nil,
+                        execute_callbacks: Threaded.execute_callbacks?)
+      Instantiator.new(klass, attributes, criteria, selected_fields)
+                  .instance(execute_callbacks: execute_callbacks)
     end
   end
 end

data/lib/mongoid/fields/encrypted.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+  module Fields
+    # Represents a field that should be encrypted.
+    class Encrypted < Standard
+      def initialize(name, options = {})
+        @encryption_options = if options[:encrypt].is_a?(Hash)
+                                options[:encrypt]
+                              else
+                                {}
+                              end
+        super
+      end
+
+      # @return [ true | false | nil ] Whether the field should be encrypted using a
+      #   deterministic encryption algorithm; if not specified, nil is returned.
+      def deterministic?
+        @encryption_options[:deterministic]
+      end
+
+      # @return [ String | nil ] The key id to use for encryption; if not specified,
+      #   nil is returned.
+      def key_id
+        @encryption_options[:key_id]
+      end
+
+      # @return [ String | nil ] The name of the field that contains the
+      #   key alt name to use for encryption; if not specified, nil is returned.
+      def key_name_field
+        @encryption_options[:key_name_field]
+      end
+
+      # Override the key_id for the field.
+      #
+      # 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)
+        @encryption_options[:key_id] = key_id
+      end
+    end
+  end
+end

data/lib/mongoid/fields/foreign_key.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Fields
+
+    # Represents a BSON document field definition which stores
+    # a foreign key that references the ID of another document.
+    # Used for association behavior.
     class ForeignKey < Standard
 
       # Adds the atomic changes for this type of resizable field.
@@ -9,7 +14,7 @@ module Mongoid
       # @example Add the atomic changes.
       #   field.add_atomic_changes(doc, "key", {}, [], [])
       #
-      # @todo: Durran: Refactor, big time.
+      # @todo: Refactor, big time.
       #
       # @param [ Document ] document The document to add to.
       # @param [ String ] name The name of the field.
@@ -90,7 +95,7 @@ module Mongoid
       # @return [ Object ] The mongoized object.
       def mongoize(object)
         if type.resizable? || object_id_field?
-          type.__mongoize_fk__(association, object)
+          mongoize_foreign_key(object)
         else
           related_id_field.mongoize(object)
         end
@@ -119,6 +124,28 @@ module Mongoid
 
       private
 
+      # Convert the provided object to a Mongo-friendly foreign key.
+      #
+      # @example Convert the object to a foreign key.
+      #   mongoize_foreign_key(object)
+      #
+      # @param [ Object ] object The object to convert.
+      #
+      # @return [ Object ] The converted object.
+      def mongoize_foreign_key(object)
+        if type == Array || type == Set
+          object = object.to_a if type == Set || object.is_a?(Set)
+
+          if object.resizable?
+            object.blank? ? object : association.convert_to_foreign_key(object)
+          else
+            object.blank? ? [] : association.convert_to_foreign_key(Array(object))
+          end
+        elsif !(object.nil? || object == '')
+          association.convert_to_foreign_key(object)
+        end
+      end
+
       # Evaluate the default proc. In some cases we need to instance exec,
       # in others we don't.
       #
@@ -148,7 +175,6 @@ module Mongoid
         @primary_key_field ||= association.klass.fields[association.primary_key]
       end
 
-
       # This is used when default values need to be serialized. Most of the
       # time just return the object.
       #

data/lib/mongoid/fields/localized.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Fields
+
+    # Represents a BSON document field definition which stores
+    # different values for different user locale keys in a Ruby
+    # hashmap (BSON "Object" type). Used for internationalization
+    # (I18n) support.
     class Localized < Standard
 
       # Demongoize the object based on the current locale. Will look in the

data/lib/mongoid/fields/standard.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Fields
+
+    # Represents a standard field definition (name, type, etc.)
+    # used to enforce consistent schema structure to the BSON
+    # documents which Mongoid persists.
     class Standard
       extend Forwardable
 

data/lib/mongoid/fields/validators/macro.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Fields
@@ -19,7 +20,8 @@ module Mongoid
           :pre_processed,
           :subtype,
           :type,
-          :overwrite
+          :overwrite,
+          :encrypt
         ]
 
         # Validate the field definition.

data/lib/mongoid/fields/validators.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/fields/validators/macro"

data/lib/mongoid/fields.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/fields/standard"
+require "mongoid/fields/encrypted"
 require "mongoid/fields/foreign_key"
 require "mongoid/fields/localized"
 require "mongoid/fields/validators"
@@ -287,8 +289,7 @@ module Mongoid
       #   end
       #
       # @param [ Symbol ] option_name the option name to match against
-      # @param [ Proc ] block the handler to execute when the option is
-      #   provided.
+      # @param &block the handler to execute when the option is provided.
       def option(option_name, &block)
         options[option_name] = block
       end
@@ -320,8 +321,10 @@ module Mongoid
       # @param [ Hash ] associations The associations to begin the search with.
       # @param [ Hash ] aliased_associations The alaised associations to begin
       #   the search with.
-      # @param [ Proc ] block The block takes in three paramaters, the current
-      #   meth, the field or the relation, and whether the second parameter is a
+      # @param &block The block.
+      # @yieldparam [ Symbol ] The current method.
+      # @yieldparam [ Symbol | String ] The field or the relation.
+      # @yieldparam [ true | false ] Whether the second yield parameter is a
       #   field or not.
       #
       # @return [ Field ] The field found for the given key at the end of the
@@ -398,41 +401,35 @@ module Mongoid
       #
       # @param [ String | Symbol ] name The name to get.
       # @param [ Hash ] relations The associations.
-      # @param [ Hash ] alaiased_fields The aliased fields.
-      # @param [ Hash ] alaiased_associations The aliased associations.
+      # @param [ Hash ] aliased_fields The aliased fields.
+      # @param [ Hash ] aliased_associations The aliased associations.
       #
       # @return [ String ] The name of the field as stored in the database.
       #
       # @api private
       def database_field_name(name, relations, aliased_fields, aliased_associations)
-        if Mongoid.broken_alias_handling
-          return nil unless name
-          normalized = name.to_s
-          aliased_fields[normalized] || normalized
-        else
-          return nil unless name.present?
-          key = name.to_s
-          segment, remaining = key.split('.', 2)
-
-          # Don't get the alias for the field when a belongs_to association
-          # is not the last item. Therefore, get the alias when one of the
-          # following is true:
-          # 1. This is the last item, i.e. there is no remaining.
-          # 2. It is not an association.
-          # 3. It is not a belongs association
-          if !remaining || !relations.key?(segment) || !relations[segment].is_a?(Association::Referenced::BelongsTo)
-            segment = aliased_fields[segment]&.dup || segment
-          end
+        return nil unless name.present?
+        key = name.to_s
+        segment, remaining = key.split('.', 2)
+
+        # Don't get the alias for the field when a belongs_to association
+        # is not the last item. Therefore, get the alias when one of the
+        # following is true:
+        # 1. This is the last item, i.e. there is no remaining.
+        # 2. It is not an association.
+        # 3. It is not a belongs association
+        if !remaining || !relations.key?(segment) || !relations[segment].is_a?(Association::Referenced::BelongsTo)
+          segment = aliased_fields[segment]&.dup || segment
+        end
 
-          return segment unless remaining
+        return segment unless remaining
 
-          relation = relations[aliased_associations[segment] || segment]
-          if relation
-            k = relation.klass
-            "#{segment}.#{database_field_name(remaining, k.relations, k.aliased_fields, k.aliased_associations)}"
-          else
-            "#{segment}.#{remaining}"
-          end
+        relation = relations[aliased_associations[segment] || segment]
+        if relation
+          k = relation.klass
+          "#{segment}.#{database_field_name(remaining, k.relations, k.aliased_fields, k.aliased_associations)}"
+        else
+          "#{segment}.#{remaining}"
         end
       end
     end
@@ -516,8 +513,10 @@ module Mongoid
       # given key.
       #
       # @param [ String ] key The key used to search the association tree.
-      # @param [ Proc ] block The block takes in three paramaters, the current
-      #   meth, the field or the relation, and whether the second parameter is a
+      # @param &block The block.
+      # @yieldparam [ Symbol ] The current method.
+      # @yieldparam [ Symbol | String ] The field or the relation.
+      # @yieldparam [ true | false ] Whether the second yield parameter is a
       #   field or not.
       #
       # @return [ Field ] The field found for the given key at the end of the
@@ -799,6 +798,7 @@ module Mongoid
         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]
+        return Fields::Encrypted.new(name, opts) if options[:encrypt]
         Fields::Standard.new(name, opts)
       end
 
@@ -809,7 +809,7 @@ module Mongoid
       #
       # @return [ Class ] The type of the field.
       #
-      # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
+      # @raise [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
       #   type.
       #
       # @api private

data/lib/mongoid/findable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
@@ -37,7 +38,6 @@ module Mongoid
       :for_js,
       :fourth,
       :fourth!,
-      :geo_near,
       :includes,
       :last!,
       :map_reduce,
@@ -133,7 +133,7 @@ module Mongoid
     # even if its _id is given multiple times in the argument to +find+.
     # If the +raise_not_found_error+ Mongoid configuration option is truthy,
     # +Errors::DocumentNotFound+ exception is raised if any of the specified
-    # _ids were not found in the database. If the ++raise_not_found_error+
+    # _ids were not found in the database. If the +raise_not_found_error+
     # Mongoid configuration option is falsy, only those documents which are
     # found are returned; if no documents are found, the return value is an
     # empty array.

data/lib/mongoid/indexable/specification.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Indexable
@@ -44,9 +45,9 @@ module Mongoid
         options = opts || {}
         Validators::Options.validate(klass, key, options)
         @klass = klass
-        @key = normalize_key(key)
+        @key = normalize_aliases!(key.dup)
         @fields = @key.keys
-        @options = normalize_options(options.dup)
+        @options = normalize_options!(options.deep_dup)
       end
 
       # Get the index name, generated using the index key.
@@ -63,39 +64,74 @@ module Mongoid
 
       private
 
-      # Normalize the spec, in case aliased fields are provided.
+      # Normalize the spec in-place, in case aliased fields are provided.
       #
       # @api private
       #
-      # @example Normalize the spec.
-      #   specification.normalize_key(name: 1)
+      # @example Normalize the spec in-place.
+      #   specification.normalize_aliases!(name: 1)
       #
-      # @param [ Hash ] key The index key(s).
+      # @param [ Hash ] spec The index specification.
       #
       # @return [ Hash ] The normalized specification.
-      def normalize_key(key)
-        normalized = {}
-        key.each_pair do |name, direction|
-          normalized[klass.database_field_name(name).to_sym] = direction
+      def normalize_aliases!(spec)
+        return unless spec.is_a?(Hash)
+
+        spec.transform_keys! do |name|
+          klass.database_field_name(name).to_sym
         end
-        normalized
       end
 
-      # Normalize the index options, if any are provided.
+      # Normalize the index options in-place. Performs deep normalization
+      # on options which have a fields hash value.
       #
       # @api private
       #
-      # @example Normalize the index options.
-      #   specification.normalize_options(unique: true)
+      # @example Normalize the index options in-place.
+      #   specification.normalize_options!(unique: true)
       #
-      # @param [ Hash ] opts The index options.
+      # @param [ Hash ] options The index options.
       #
       # @return [ Hash ] The normalized options.
-      def normalize_options(opts)
-        options = {}
-        opts.each_pair do |option, value|
-          options[MAPPINGS[option] || option] = value
+      def normalize_options!(options)
+
+        options.transform_keys! do |option|
+          option = option.to_sym
+          MAPPINGS[option] || option
+        end
+
+        %i[partial_filter_expression weights wildcard_projection].each do |key|
+          recursive_normalize_conditionals!(options[key])
         end
+
+        options
+      end
+
+      # Recursively normalizes the nested elements of an options hash in-place,
+      # to account for $and operator (and other potential $-prefixed operators
+      # which may be supported by MongoDB in the future.)
+      #
+      # @api private
+      #
+      # @example Recursively normalize the index options in-place.
+      #   opts = { '$and' => [{ name: { '$eq' => 'Bob' } },
+      #                       { age: { '$gte' => 20 } }] }
+      #   specification.recursive_normalize_conditionals!(opts)
+      #
+      # @param [ Hash | Array | Object ] options The index options.
+      #
+      # @return [ Hash | Array | Object ] The normalized options.
+      def recursive_normalize_conditionals!(options)
+        case options
+        when Hash
+          normalize_aliases!(options)
+          options.keys.select { |key| key.to_s.start_with?('$') }.each do |key|
+            recursive_normalize_conditionals!(options[key])
+          end
+        when Array
+          options.each { |opt| recursive_normalize_conditionals!(opt) }
+        end
+
         options
       end
     end

data/lib/mongoid/indexable/validators/options.rb

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

data/lib/mongoid/indexable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require "mongoid/indexable/specification"
 require "mongoid/indexable/validators/options"

data/lib/mongoid/inspectable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
@@ -18,6 +19,37 @@ module Mongoid
       "#<#{self.class.name} _id: #{_id}, #{inspection * ', '}>"
     end
 
+    # This pretty prints the same information as the inspect method. This is
+    # meant to be called by the standard 'pp' library.
+    #
+    # @param [ PP ] pretty_printer The pretty printer.
+    #
+    # @example Pretty print the document.
+    #   person.pretty_inspect
+    #
+    # @api private
+    def pretty_print(pretty_printer)
+      keys = fields.keys | attributes.keys
+      pretty_printer.group(1, "#<#{self.class.name}", '>') do
+        sep = lambda { pretty_printer.text(',') }
+        pretty_printer.seplist(keys, sep) do |key|
+          pretty_printer.breakable
+          field = fields[key]
+          as = "(#{field.options[:as]})" if field && field.options[:as]
+          pretty_printer.text("#{key}#{as}")
+          pretty_printer.text(':')
+          pretty_printer.group(1) do
+            pretty_printer.breakable
+            if key == "_id"
+              pretty_printer.text(_id.to_s)
+            else
+              pretty_printer.pp(@attributes[key])
+            end
+          end
+        end
+      end
+    end
+
     private
 
     # Get an array of inspected fields for the document.