mongoid 7.4.3 → 8.0.7

data/lib/mongoid/fields/standard.rb

@@ -48,7 +48,7 @@ module Mongoid
       # @example Is the field a foreign key?
       #   field.foreign_key?
       #
-      # @return [ true, false ] If the field is a foreign key.
+      # @return [ true | false ] If the field is a foreign key.
       def foreign_key?
         false
       end
@@ -82,7 +82,7 @@ module Mongoid
       # @example Is the field lazy?
       #   field.lazy?
       #
-      # @return [ true, false ] If the field is lazy.
+      # @return [ true | false ] If the field is lazy.
       def lazy?
         false
       end
@@ -92,7 +92,7 @@ module Mongoid
       # @example Is the field localized?
       #   field.localized?
       #
-      # @return [ true, false ] If the field is localized.
+      # @return [ true | false ] If the field is localized.
       def localized?
         false
       end
@@ -112,7 +112,7 @@ module Mongoid
       # @example Is the field a BSON::ObjectId?
       #   field.object_id_field?
       #
-      # @return [ true, false ] If the field is a BSON::ObjectId.
+      # @return [ true | false ] If the field is a BSON::ObjectId.
       def object_id_field?
         @object_id_field ||= (type == BSON::ObjectId)
       end
@@ -122,7 +122,7 @@ module Mongoid
       # @example Does the field pre-process the default?
       #   field.pre_processed?
       #
-      # @return [ true, false ] If the field's default is pre-processed.
+      # @return [ true | false ] If the field's default is pre-processed.
       def pre_processed?
         @pre_processed ||=
           (options[:pre_processed] || (default_val && !default_val.is_a?(::Proc)))
@@ -161,7 +161,7 @@ module Mongoid
       #
       # @note Ruby's instance_exec was just too slow.
       #
-      # @param [ Class, Module ] object The class or module the field is
+      # @param [ Class | Module ] object The class or module the field is
       #   defined on.
       def define_default_method(object)
         object.__send__(:define_method, default_name, default_val)
@@ -177,7 +177,7 @@ module Mongoid
       #
       # @param [ Hash ] fields The field limitations.
       #
-      # @return [ true, false ] If the field was included.
+      # @return [ true | false ] If the field was included.
       def included?(fields)
         (fields.values.first == 1 && fields[name.to_s] == 1) ||
           (fields.values.first == 0 && !fields.has_key?(name.to_s))

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

@@ -8,9 +8,6 @@ module Mongoid
       module Macro
         extend self
 
-        # The warning message to give when a field is of type Symbol.
-        FIELD_TYPE_IS_SYMBOL = 'The BSON symbol type is deprecated; use String instead'.freeze
-
         OPTIONS = [
           :as,
           :default,
@@ -69,7 +66,7 @@ module Mongoid
         def validate_field_name(klass, name)
           [name, "#{name}?".to_sym, "#{name}=".to_sym].each do |n|
             if Mongoid.destructive_fields.include?(n)
-              raise Errors::InvalidField.new(klass, n)
+              raise Errors::InvalidField.new(klass, name, n)
             end
           end
         end
@@ -91,7 +88,7 @@ module Mongoid
         def validate_name_uniqueness(klass, name, options)
           if !options[:overwrite] && klass.fields.keys.include?(name.to_s)
             if Mongoid.duplicate_fields_exception
-              raise Errors::InvalidField.new(klass, name)
+              raise Errors::InvalidField.new(klass, name, name)
             else
               Mongoid.logger.warn("Overwriting existing field #{name} in class #{klass.name}.") if Mongoid.logger
             end
@@ -117,10 +114,7 @@ module Mongoid
             end
 
             if option == :type && options[option] == Symbol
-              @field_type_is_symbol_warned ||= begin
-                Mongoid.logger.warn(FIELD_TYPE_IS_SYMBOL)
-                true
-              end
+              Mongoid::Warnings.warn_symbol_type_deprecated
             end
           end
         end

data/lib/mongoid/fields.rb

@@ -42,6 +42,11 @@ module Mongoid
     # @api private
     IDS = [ :_id, '_id', ].freeze
 
+    # BSON classes that are not supported as field types
+    #
+    # @api private
+    INVALID_BSON_CLASSES = [ BSON::Decimal128, BSON::Int32, BSON::Int64 ].freeze
+
     module ClassMethods
       # Returns the list of id fields for this model class, as both strings
       # and symbols.
@@ -142,7 +147,7 @@ module Mongoid
     # @example Apply all the non-proc defaults.
     #   model.apply_pre_processed_defaults
     #
-    # @return [ Array<String ] The names of the non-proc defaults.
+    # @return [ Array<String> ] The names of the non-proc defaults.
     def apply_pre_processed_defaults
       pre_processed_defaults.each do |name|
         apply_default(name)
@@ -154,8 +159,9 @@ module Mongoid
     # @example Apply all the proc defaults.
     #   model.apply_post_processed_defaults
     #
-    # @return [ Array<String ] The names of the proc defaults.
+    # @return [ Array<String> ] The names of the proc defaults.
     def apply_post_processed_defaults
+      pending_callbacks.delete(:apply_post_processed_defaults)
       post_processed_defaults.each do |name|
         apply_default(name)
       end
@@ -184,6 +190,7 @@ module Mongoid
     # @example Apply all the defaults.
     #   model.apply_defaults
     def apply_defaults
+      pending_callbacks.delete(:apply_defaults)
       apply_pre_processed_defaults
       apply_post_processed_defaults
     end
@@ -207,7 +214,7 @@ module Mongoid
     # @example Get the database field name.
     #   model.database_field_name(:authorization)
     #
-    # @param [ String, Symbol ] name The name to get.
+    # @param [ String | Symbol ] name The name to get.
     #
     # @return [ String ] The name of the field as it's stored in the db.
     def database_field_name(name)
@@ -222,7 +229,7 @@ module Mongoid
     # @param [ Field ] field The field.
     # @param [ Object ] value The current value.
     #
-    # @return [ true, false ] If we set the field lazily.
+    # @return [ true | false ] If we set the field lazily.
     def lazy_settable?(field, value)
       !frozen? && value.nil? && field.lazy?
     end
@@ -234,11 +241,37 @@ module Mongoid
     # @example Is the document using object ids?
     #   model.using_object_ids?
     #
-    # @return [ true, false ] Using object ids.
+    # @return [ true | false ] Using object ids.
     def using_object_ids?
       self.class.using_object_ids?
     end
 
+    # Does this field start with a dollar sign ($) or contain a dot/period (.)?
+    #
+    # @api private
+    #
+    # @param [ String ] name The field name.
+    #
+    # @return [ true | false ] If this field is dotted or dollared.
+    def dot_dollar_field?(name)
+      n = aliased_fields[name] || name
+      fields.key?(n) && (n.include?('.') || n.start_with?('$'))
+    end
+
+    # Validate whether or not the field starts with a dollar sign ($) or
+    # contains a dot/period (.).
+    #
+    # @api private
+    #
+    # @raise [ InvalidDotDollarAssignment ] If contains dots or starts with a dollar.
+    #
+    # @param [ String ] name The field name.
+    def validate_writable_field_name!(name)
+      if dot_dollar_field?(name)
+        raise Errors::InvalidDotDollarAssignment.new(self.class, name)
+      end
+    end
+
     class << self
 
       # Stores the provided block to be run when the option name specified is
@@ -270,21 +303,64 @@ module Mongoid
       def options
         @options ||= {}
       end
-    end
-
-    module ClassMethods
 
-      # Returns an array of names for the attributes available on this object.
+      # Traverse down the association tree and search for the field for the
+      # given key. To do this, split the key by '.' and for each part (meth) of
+      # the key:
       #
-      # Provides the field names in an ORM-agnostic way. Rails v3.1+ uses this
-      # method to automatically wrap params in JSON requests.
+      # - If the meth is a field, yield the meth, field, and is_field as true.
+      # - If the meth is an association, update the klass to the association's
+      #   klass, and yield the meth, klass, and is_field as false.
       #
-      # @example Get the field names
-      #   Model.attribute_names
+      # The next iteration will use klass's fields and associations to continue
+      # traversing the tree.
       #
-      # @return [ Array<String> ] The field names
-      def attribute_names
-        fields.keys
+      # @param [ String ] key The key used to search the association tree.
+      # @param [ Hash ] fields The fields to begin the search with.
+      # @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
+      #   field or not.
+      #
+      # @return [ Field ] The field found for the given key at the end of the
+      #   search. This will return nil if the last thing found is an association
+      #   or no field was found for the given key.
+      #
+      # @api private
+      def traverse_association_tree(key, fields, associations, aliased_associations)
+        klass = nil
+        field = nil
+        key.split('.').each_with_index do |meth, i|
+          fs = i == 0 ? fields : klass&.fields
+          rs = i == 0 ? associations : klass&.relations
+          as = i == 0 ? aliased_associations : klass&.aliased_associations
+
+          # Associations can possibly have two "keys", their name and their alias.
+          # The fields name is what is used to store it in the klass's relations
+          # and field hashes, and the alias is what's used to store that field
+          # in the database. The key inputted to this function is the aliased
+          # key. We can convert them back to their names by looking in the
+          # aliased_associations hash.
+          aliased = meth
+          if as && a = as.fetch(meth, nil)
+            aliased = a.to_s
+          end
+
+          field = nil
+          klass = nil
+          if fs && f = fs[aliased]
+            field = f
+            yield(meth, f, true) if block_given?
+          elsif rs && rel = rs[aliased]
+            klass = rel.klass
+            yield(meth, rel, false) if block_given?
+          else
+            yield(meth, nil, false) if block_given?
+          end
+        end
+        field
       end
 
       # Get the name of the provided field as it is stored in the database.
@@ -292,16 +368,43 @@ module Mongoid
       # finds aliases for embedded documents and fields, delimited with
       # period "." character.
       #
-      # @example Get the database field name of a field.
-      #   Model.database_field_name(:authorization)
+      # Note that this method returns the name of associations as they're
+      # stored in the database, whereas the `relations` hash uses their in-code
+      # aliases. In order to check for membership in the relations hash, you
+      # would first have to look up the string returned from this method in
+      # the aliased_associations hash.
       #
-      # @example Get the database field name of an embedded field.
-      #   Model.database_field_name('customers.addresses.city')
+      # This method will not expand the alias of a belongs_to association that
+      # is not the last item. For example, if we had a School that has_many
+      # Students, and the field name passed was (from the Student's perspective):
       #
-      # @param [ String, Symbol ] name The name to get.
+      #   school._id
+      #
+      # The alias for a belongs_to association is that association's _id field.
+      # Therefore, expanding out this association would yield:
+      #
+      #   school_id._id
+      #
+      # This is not the correct field name, because the intention here was not
+      # to get a property of the _id field. The intention was to get a property
+      # of the referenced document. Therefore, if a part of the name passed is
+      # a belongs_to association that is not the last part of the name, we
+      # won't expand its alias, and return:
+      #
+      #   school._id
+      #
+      # If the belongs_to association is the last part of the name, we will
+      # pass back the _id field.
+      #
+      # @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.
       #
       # @return [ String ] The name of the field as stored in the database.
-      def database_field_name(name)
+      #
+      # @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
@@ -310,31 +413,68 @@ module Mongoid
           return nil unless name.present?
           key = name.to_s
           segment, remaining = key.split('.', 2)
-          segment = aliased_fields[segment]&.dup || segment
+
+          # 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
 
           relation = relations[aliased_associations[segment] || segment]
           if relation
-            "#{segment}.#{relation.klass.database_field_name(remaining)}"
+            k = relation.klass
+            "#{segment}.#{database_field_name(remaining, k.relations, k.aliased_fields, k.aliased_associations)}"
           else
             "#{segment}.#{remaining}"
           end
         end
       end
+    end
+
+    module ClassMethods
+
+      # Returns an array of names for the attributes available on this object.
+      #
+      # Provides the field names in an ORM-agnostic way. Rails v3.1+ uses this
+      # method to automatically wrap params in JSON requests.
+      #
+      # @example Get the field names
+      #   Model.attribute_names
+      #
+      # @return [ Array<String> ] The field names
+      def attribute_names
+        fields.keys
+      end
+
+      # Get the name of the provided field as it is stored in the database.
+      # Used in determining if the field is aliased or not.
+      #
+      # @param [ String | Symbol ] name The name to get.
+      #
+      # @return [ String ] The name of the field as it's stored in the db.
+      def database_field_name(name)
+        Fields.database_field_name(name, relations, aliased_fields, aliased_associations)
+      end
 
       # Defines all the fields that are accessible on the Document
       # For each field that is defined, a getter and setter will be
       # added as an instance method to the Document.
       #
       # @example Define a field.
-      #   field :score, :type => Integer, :default => 0
+      #   field :score, type: Integer, default: 0
       #
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The options to pass to the field.
       #
-      # @option options [ Class ] :type The type of the field.
+      # @option options [ Class | Symbol | String ] :type The type of the field.
       # @option options [ String ] :label The label for the field.
-      # @option options [ Object, Proc ] :default The field's default
+      # @option options [ Object | Proc ] :default The field's default.
       #
       # @return [ Field ] The generated field
       def field(name, options = {})
@@ -367,11 +507,28 @@ module Mongoid
       # @example Does this class use object ids?
       #   person.using_object_ids?
       #
-      # @return [ true, false ] If the class uses BSON::ObjectIds for the id.
+      # @return [ true | false ] If the class uses BSON::ObjectIds for the id.
       def using_object_ids?
         fields["_id"].object_id_field?
       end
 
+      # Traverse down the association tree and search for the field for the
+      # 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
+      #   field or not.
+      #
+      # @return [ Field ] The field found for the given key at the end of the
+      #   search. This will return nil if the last thing found is an association
+      #   or no field was found for the given key.
+      #
+      # @api private
+      def traverse_association_tree(key, &block)
+        Fields.traverse_association_tree(key, fields, relations, aliased_associations, &block)
+      end
+
       protected
 
       # Add the defaults to the model. This breaks them up between ones that
@@ -479,9 +636,7 @@ module Mongoid
             if lazy_settable?(field, raw)
               write_attribute(name, field.eval_default(self))
             else
-              value = field.demongoize(raw)
-              attribute_will_change!(name) if value.resizable?
-              value
+              process_raw_attribute(name.to_s, raw, field)
             end
           end
         end
@@ -573,10 +728,8 @@ module Mongoid
         generated_methods.module_eval do
           re_define_method("#{meth}_translations=") do |value|
             attribute_will_change!(name)
-            if value
-              value.update_values do |_value|
-                field.type.mongoize(_value)
-              end
+            value&.transform_values! do |_value|
+              field.type.mongoize(_value)
             end
             attributes[name] = value
           end
@@ -611,20 +764,60 @@ module Mongoid
 
       def field_for(name, options)
         opts = options.merge(klass: self)
-        type_mapping = TYPE_MAPPINGS[options[:type]]
-        opts[:type] = type_mapping || unmapped_type(options)
+        opts[:type] = retrieve_and_validate_type(name, options[:type])
         return Fields::Localized.new(name, opts) if options[:localize]
         return Fields::ForeignKey.new(name, opts) if options[:identity]
         Fields::Standard.new(name, opts)
       end
 
-      def unmapped_type(options)
-        if "Boolean" == options[:type].to_s
+      # Get the class for the given type.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
+      #   type.
+      #
+      # @api private
+      def retrieve_and_validate_type(name, type)
+        result = TYPE_MAPPINGS[type] || unmapped_type(type)
+        raise Errors::InvalidFieldType.new(self, name, type) if !result.is_a?(Class)
+
+        if unsupported_type?(result)
+          warn_message = "Using #{result} as the field type is not supported. "
+          if result == BSON::Decimal128
+            warn_message += 'In BSON <= 4, the BSON::Decimal128 type will work as expected for both storing and querying, but will return a BigDecimal on query in BSON 5+. To use literal BSON::Decimal128 fields with BSON 5, set Mongoid.allow_bson5_decimal128 to true.'
+          else
+            warn_message += 'Saving values of this type to the database will work as expected, however, querying them will return a value of the native Ruby Integer type.'
+          end
+          Mongoid.logger.warn(warn_message)
+        end
+
+        result
+      end
+
+      def unmapped_type(type)
+        if "Boolean" == type.to_s
           Mongoid::Boolean
         else
-          options[:type] || Object
+          type || Object
         end
       end
+
+      # Queries whether or not the given type is permitted as a declared field
+      # type.
+      #
+      # @param [ Class ] type The type to query
+      #
+      # @return [ true | false ] whether or not the type is supported
+      #
+      # @api private
+      def unsupported_type?(type)
+        return !Mongoid::Config.allow_bson5_decimal128? if type == BSON::Decimal128
+        INVALID_BSON_CLASSES.include?(type)
+      end
     end
   end
 end

data/lib/mongoid/findable.rb

@@ -38,12 +38,16 @@ module Mongoid
       :max,
       :min,
       :none,
+      :pick,
       :pluck,
       :read,
       :sum,
+      :take,
+      :take!,
+      :tally,
       :text_search,
       :update,
-      :update_all
+      :update_all,
 
     # Returns a count of records in the database.
     # If you want to specify conditions use where.
@@ -72,7 +76,7 @@ module Mongoid
     # @example Are there no saved documents for this model?
     #   Person.empty?
     #
-    # @return [ true, false ] If the collection is empty.
+    # @return [ true | false ] If the collection is empty.
     def empty?
       count == 0
     end
@@ -83,7 +87,7 @@ module Mongoid
     # @example Do any documents exist for the conditions?
     #   Person.exists?
     #
-    # @return [ true, false ] If any documents exist for the conditions.
+    # @return [ true | false ] If any documents exist for the conditions.
     def exists?
       with_default_scope.exists?
     end
@@ -118,18 +122,32 @@ module Mongoid
     # strings will be transparently converted to +BSON::ObjectId+ instances
     # during query construction.
     #
+    # If this method is given a block, it delegates to +Enumerable#find+ and
+    # returns the first document of those found by the current Crieria object
+    # for which the block returns a truthy value. If both a block and ids are
+    # given, the block is ignored and the documents for the given ids are
+    # returned. If a block and a Proc are given, the method delegates to
+    # +Enumerable#find+ and uses the proc as the default.
+    #
     # The +find+ method takes into account the default scope defined on the
     # model class, if any.
     #
-    # @param [ Object | Array<Object> ] args The _id values to find or an
-    #   array thereof.
+    # @note Each argument can be an individual id, an array of ids or
+    #   a nested array. Each array will be flattened.
+    #
+    # @param [ Object | Array<Object> ] *args The _id value(s) to find.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #
     # @raise Errors::DocumentNotFound If not all documents are found and
     #   the +raise_not_found_error+ Mongoid configuration option is truthy.
-    def find(*args)
-      with_default_scope.find(*args)
+    def find(*args, &block)
+      empty_or_proc = args.empty? || (args.length == 1 && args.first.is_a?(Proc))
+      if block_given? && empty_or_proc
+        with_default_scope.find(*args, &block)
+      else
+        with_default_scope.find(*args)
+      end
     end
 
     # Find the first +Document+ given the conditions.
@@ -145,7 +163,7 @@ module Mongoid
     # @raise [ Errors::DocumentNotFound ] If no document found
     # and Mongoid.raise_not_found_error is true.
     #
-    # @return [ Document, nil ] A matching document.
+    # @return [ Document | nil ] A matching document.
     def find_by(attrs = {})
       result = where(attrs).find_first
       if result.nil? && Mongoid.raise_not_found_error
@@ -166,7 +184,6 @@ module Mongoid
     # @raise [ Errors::DocumentNotFound ] If no document found.
     #
     # @return [ Document ] A matching document.
-    #
     def find_by!(attrs = {})
       result = where(attrs).find_first
       raise(Errors::DocumentNotFound.new(self, attrs)) unless result
@@ -179,9 +196,11 @@ module Mongoid
     # @example Find the first document.
     #   Person.first
     #
+    # @param [ Integer ] limit The number of documents to return.
+    #
     # @return [ Document ] The first matching document.
-    def first
-      with_default_scope.first
+    def first(limit = nil)
+      with_default_scope.first(limit)
     end
     alias :one :first
 
@@ -190,9 +209,11 @@ module Mongoid
     # @example Find the last document.
     #   Person.last
     #
+    # @param [ Integer ] limit The number of documents to return.
+    #
     # @return [ Document ] The last matching document.
-    def last
-      with_default_scope.last
+    def last(limit = nil)
+      with_default_scope.last(limit)
     end
   end
 end

data/lib/mongoid/indexable/specification.rb

@@ -27,7 +27,7 @@ module Mongoid
       #
       # @param [ Specification ] other The spec to compare against.
       #
-      # @return [ true, false ] If the specs are equal.
+      # @return [ true | false ] If the specs are equal.
       def ==(other)
         fields == other.fields && key == other.key
       end
@@ -86,7 +86,7 @@ module Mongoid
       # @api private
       #
       # @example Normalize the index options.
-      #   specification.normalize_options(drop_dups: true)
+      #   specification.normalize_options(unique: true)
       #
       # @param [ Hash ] opts The index options.
       #

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

@@ -13,7 +13,6 @@ module Mongoid
           :database,
           :default_language,
           :language_override,
-          :drop_dups,
           :name,
           :sparse,
           :unique,
@@ -29,7 +28,8 @@ module Mongoid
           :text_version,
           :version,
           :partial_filter_expression,
-          :collation
+          :collation,
+          :wildcard_projection,
         ]
 
         VALID_TYPES = [
@@ -98,6 +98,10 @@ module Mongoid
             unless VALID_TYPES.include?(value)
               raise Errors::InvalidIndex.new(klass, spec, options)
             end
+
+            if value == "geoHaystack"
+              Mongoid::Warnings.warn_geo_haystack_deprecated
+            end
           end
         end
       end