mongoid 7.4.0 → 8.0.3

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.
+      #
+      # 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):
+      #
+      #   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:
       #
-      # @example Get the database field name of an embedded field.
-      #   Model.database_field_name('customers.addresses.city')
+      #   school._id
       #
-      # @param [ String, Symbol ] name The name to get.
+      # 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
@@ -613,6 +766,19 @@ module Mongoid
         opts = options.merge(klass: self)
         type_mapping = TYPE_MAPPINGS[options[:type]]
         opts[:type] = type_mapping || unmapped_type(options)
+        if !opts[:type].is_a?(Class)
+          raise Errors::InvalidFieldType.new(self, name, options[:type])
+        else
+          if INVALID_BSON_CLASSES.include?(opts[:type])
+            warn_message = "Using #{opts[:type]} as the field type is not supported. "
+            if opts[:type] == 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+."
+            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
+        end
         return Fields::Localized.new(name, opts) if options[:localize]
         return Fields::ForeignKey.new(name, opts) if options[:identity]
         Fields::Standard.new(name, opts)

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

data/lib/mongoid/interceptable.rb

@@ -27,7 +27,7 @@ module Mongoid
       :before_save,
       :before_update,
       :before_upsert,
-      :before_validation
+      :before_validation,
     ].freeze
 
     included do
@@ -37,6 +37,12 @@ module Mongoid
       define_model_callbacks :build, :find, :initialize, :touch, only: :after
       define_model_callbacks :create, :destroy, :save, :update, :upsert
 
+      # This callback is used internally by Mongoid to save association
+      # targets for referenced associations after the parent model is persisted.
+      #
+      # @api private
+      define_model_callbacks :persist_parent
+
       attr_accessor :before_callback_halted
     end
 
@@ -47,7 +53,7 @@ module Mongoid
     #
     # @param [ Symbol ] kind The type of callback.
     #
-    # @return [ true, false ] If the callback can be executed.
+    # @return [ true | false ] If the callback can be executed.
     def callback_executable?(kind)
       respond_to?("_#{kind}_callbacks")
     end
@@ -60,7 +66,7 @@ module Mongoid
     #
     # @param [ Symbol ] kind The callback kind.
     #
-    # @return [ true, false ] If the document is in a callback state.
+    # @return [ true | false ] If the document is in a callback state.
     def in_callback_state?(kind)
       [ :create, :destroy ].include?(kind) || new_record? || flagged_for_destroy? || changed?
     end
@@ -109,22 +115,76 @@ module Mongoid
     #   end
     #
     # @param [ Symbol ] kind The type of callback to execute.
-    # @param [ Array ] args Any options.
-    #
-    # @return [ Document ] The document
-    ruby2_keywords def run_callbacks(kind, *args, &block)
-      cascadable_children(kind).each do |child|
-        if child.run_callbacks(child_callback_type(kind, child), *args) == false
-          return false
+    # @param [ true | false ] with_children Flag specifies whether callbacks of embedded document should be run.
+    def run_callbacks(kind, with_children: true, &block)
+      if with_children
+        cascadable_children(kind).each do |child|
+          if child.run_callbacks(child_callback_type(kind, child), with_children: with_children) == false
+            return false
+          end
         end
       end
       if callback_executable?(kind)
-        super(kind, *args, &block)
+        super(kind, &block)
       else
         true
       end
     end
 
+    # Run the callbacks for embedded documents.
+    #
+    # @param [ Symbol ] kind The type of callback to execute.
+    # @param [ Array<Document> ] children Children to exeute callbacks on. If
+    #   nil, callbacks will be executed on all cascadable children of
+    #   the document.
+    #
+    # @api private
+    def _mongoid_run_child_callbacks(kind, children: nil, &block)
+      child, *tail = (children || cascadable_children(kind))
+      if child.nil?
+        return block&.call
+      elsif tail.empty?
+        return child.run_callbacks(child_callback_type(kind, child), &block)
+      else
+        return child.run_callbacks(child_callback_type(kind, child)) do
+          _mongoid_run_child_callbacks(kind, children: tail, &block)
+        end
+      end
+    end
+
+    # This is used to store callbacks to be executed later. A good use case for
+    # this is delaying the after_find and after_initialize callbacks until the
+    # associations are set on the document. This can also be used to delay
+    # applying the defaults on a document.
+    #
+    # @return [ Array<Symbol> ] an array of symbols that represent the pending callbacks.
+    #
+    # @api private
+    def pending_callbacks
+      @pending_callbacks ||= [].to_set
+    end
+
+    # @api private
+    def pending_callbacks=(value)
+      @pending_callbacks = value
+    end
+
+    # Run the pending callbacks. If the callback is :apply_defaults, we will apply
+    # the defaults for this document. Otherwise, the callback is passed to the
+    # run_callbacks function.
+    #
+    # @api private
+    def run_pending_callbacks
+      pending_callbacks.each do |cb|
+        if [:apply_defaults, :apply_post_processed_defaults].include?(cb)
+          send(cb)
+        else
+          self.run_callbacks(cb, with_children: false)
+        end
+      end
+      pending_callbacks.clear
+    end
+
     private
 
     # We need to hook into this for autosave, since we don't want it firing if
@@ -135,7 +195,7 @@ module Mongoid
     # @example Was a before callback halted?
     #   document.before_callback_halted?
     #
-    # @return [ true, false ] If a before callback was halted.
+    # @return [ true | false ] If a before callback was halted.
     def before_callback_halted?
       !!@before_callback_halted
     end
@@ -175,7 +235,7 @@ module Mongoid
     # @param [ Symbol ] kind The type of callback.
     # @param [ Document ] child The child document.
     #
-    # @return [ true, false ] If the child should fire the callback.
+    # @return [ true | false ] If the child should fire the callback.
     def cascadable_child?(kind, child, association)
       return false if kind == :initialize || kind == :find || kind == :touch
       return false if kind == :validate && association.validate?

data/lib/mongoid/matchable.rb

@@ -15,7 +15,7 @@ module Mongoid
     #
     # @param [ Hash ] selector The MongoDB selector.
     #
-    # @return [ true, false ] True if matches, false if not.
+    # @return [ true | false ] True if matches, false if not.
     def _matches?(selector)
       Matcher::Expression.matches?(self, selector)
     end