mongoid 7.5.0 → 8.0.2

data/lib/mongoid/extensions/time.rb

@@ -14,19 +14,13 @@ module Mongoid
         self
       end
 
-      # Constant for epoch - used when passing invalid times.
-      #
-      # @deprecated No longer used as a return value from #mongoize passed
-      #   an invalid time string.
-      EPOCH = ::Time.utc(1970, 1, 1, 0, 0, 0)
-
       # Turn the object from the ruby type we deal with to a Mongo friendly
       # type.
       #
       # @example Mongoize the object.
       #   time.mongoize
       #
-      # @return [ Time ] The object mongoized.
+      # @return [ Time | nil ] The object mongoized or nil.
       def mongoize
         ::Time.mongoize(self)
       end
@@ -51,14 +45,28 @@ module Mongoid
         #
         # @param [ Time ] object The time from Mongo.
         #
-        # @return [ Time ] The object as a date.
+        # @return [ Time | nil ] The object as a time.
         def demongoize(object)
-          return nil if object.blank?
-          object = object.getlocal unless Mongoid::Config.use_utc?
+          return if object.blank?
+          time = if object.acts_like?(:time)
+            Mongoid::Config.use_utc? ? object : object.getlocal
+          elsif object.acts_like?(:date)
+            ::Date.demongoize(object).to_time
+          elsif object.is_a?(String)
+            begin
+              object.__mongoize_time__
+            rescue ArgumentError
+              nil
+            end
+          end
+
+          return if time.nil?
+
           if Mongoid::Config.use_activesupport_time_zone?
-            object = object.in_time_zone(Mongoid.time_zone)
+            time.in_time_zone(Mongoid.time_zone)
+          else
+            time
           end
-          object
         end
 
         # Turn the object from the ruby type we deal with to a Mongo friendly
@@ -69,11 +77,16 @@ module Mongoid
         #
         # @param [ Object ] object The object to mongoize.
         #
-        # @return [ Time ] The object mongoized.
+        # @return [ Time | nil ] The object mongoized or nil.
         def mongoize(object)
-          return nil if object.blank?
+          return if object.blank?
           begin
             time = object.__mongoize_time__
+          rescue ArgumentError
+            return
+          end
+
+          if time.acts_like?(:time)
             if object.respond_to?(:sec_fraction)
               ::Time.at(time.to_i, object.sec_fraction * 10**6).utc
             elsif time.respond_to?(:subsec)
@@ -81,8 +94,6 @@ module Mongoid
             else
               ::Time.at(time.to_i, time.usec).utc
             end
-          rescue ArgumentError
-            nil
           end
         end
       end

data/lib/mongoid/extensions/time_with_zone.rb

@@ -49,8 +49,7 @@ module Mongoid
         #
         # @return [ TimeWithZone ] The object as a date.
         def demongoize(object)
-          return nil if object.blank?
-          ::Time.demongoize(object).in_time_zone
+          ::Time.demongoize(object).try(:in_time_zone)
         end
 
         # Turn the object from the ruby type we deal with to a Mongo friendly

data/lib/mongoid/extensions/true_class.rb

@@ -21,7 +21,7 @@ module Mongoid
       #
       # @param [ Class ] other The class to check.
       #
-      # @return [ true, false ] If the other is a boolean.
+      # @return [ true | false ] If the other is a boolean.
       def is_a?(other)
         if other == Mongoid::Boolean || other.class == Mongoid::Boolean
           return true

data/lib/mongoid/extensions.rb

@@ -34,6 +34,7 @@ end
 
 require "mongoid/extensions/array"
 require "mongoid/extensions/big_decimal"
+require "mongoid/extensions/binary"
 require "mongoid/extensions/boolean"
 require "mongoid/extensions/date"
 require "mongoid/extensions/date_time"

data/lib/mongoid/factory.rb

@@ -6,9 +6,6 @@ module Mongoid
   module Factory
     extend self
 
-    # @deprecated
-    TYPE = "_type".freeze
-
     # Builds a new +Document+ from the supplied attributes.
     #
     # This method either instantiates klass or a descendant of klass if the attributes include
@@ -23,16 +20,32 @@ 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
+    #   should be run.
     #
     # @return [ Document ] The instantiated document.
     def build(klass, attributes = nil)
+      execute_build(klass, attributes, execute_callbacks: true)
+    end
+
+    # Execute the build.
+    #
+    # @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
+    #   should be run.
+    #
+    # @return [ Document ] The instantiated document.
+    #
+    # @api private
+    def execute_build(klass, attributes = nil, execute_callbacks: true)
       attributes ||= {}
       dvalue = attributes[klass.discriminator_key] || attributes[klass.discriminator_key.to_sym]
       type = klass.get_discriminator_mapping(dvalue)
       if type
-        type.new(attributes)
+        type.construct_document(attributes, execute_callbacks: execute_callbacks)
       else
-        klass.new(attributes)
+        klass.construct_document(attributes, execute_callbacks: execute_callbacks)
       end
     end
 
@@ -63,12 +76,34 @@ module Mongoid
     #
     # @return [ Document ] The instantiated document.
     def from_db(klass, attributes = nil, criteria = nil, selected_fields = nil)
+      execute_from_db(klass, attributes, criteria, selected_fields, execute_callbacks: true)
+    end
+
+    # Execute from_db.
+    #
+    # @param [ Class ] klass The class to instantiate from if _type is not present.
+    # @param [ Hash ] attributes The document attributes.
+    # @param [ Criteria ] criteria Optional criteria object.
+    # @param [ Hash ] selected_fields Fields which were retrieved via
+    #   #only. If selected_fields are specified, fields not listed in it
+    #   will not be accessible in the returned document.
+    # @param [ true | false ] execute_callbacks Whether this method should
+    #   invoke the callbacks. If true, the callbacks will be invoked normally.
+    #   If false, the callbacks will be stored in the +pending_callbacks+ list
+    #   and caller is responsible for invoking +run_pending_callbacks+ at a
+    #   later time. Use this option to defer callback execution until the
+    #   entire object graph containing embedded associations is constructed.
+    #
+    # @return [ Document ] The instantiated document.
+    #
+    # @api private
+    def execute_from_db(klass, attributes = nil, criteria = nil, selected_fields = nil, execute_callbacks: true)
       if criteria
         selected_fields ||= criteria.options[:fields]
       end
       type = (attributes || {})[klass.discriminator_key]
       if type.blank?
-        obj = klass.instantiate(attributes, selected_fields)
+        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
@@ -92,7 +127,7 @@ module Mongoid
           raise Errors::UnknownModel.new(camelized, type)
         end
 
-        constantized.instantiate(attributes, selected_fields)
+        constantized.instantiate_document(attributes, selected_fields, execute_callbacks: execute_callbacks)
       end
     end
   end

data/lib/mongoid/fields/foreign_key.rb

@@ -43,7 +43,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?
         true
       end
@@ -60,6 +60,8 @@ module Mongoid
         if object_id_field? || object.is_a?(Document)
           if association.polymorphic?
             association.convert_to_foreign_key(object)
+          elsif object.is_a?(Document) && object.respond_to?(association.primary_key)
+            primary_key_field.evolve(object.send(association.primary_key))
           else
             object.__evolve_object_id__
           end
@@ -73,7 +75,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?
         type.resizable?
       end
@@ -99,7 +101,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 ||=
             association.polymorphic? ? true : association.klass.using_object_ids?
@@ -110,7 +112,7 @@ module Mongoid
       # @example Is the field resizable?
       #   field.resizable?
       #
-      # @return [ true, false ] If the field is resizable.
+      # @return [ true | false ] If the field is resizable.
       def resizable?
         type.resizable?
       end
@@ -142,6 +144,11 @@ module Mongoid
         @related_id_field ||= association.klass.fields["_id"]
       end
 
+      def primary_key_field
+        @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

@@ -24,7 +24,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?
         true
       end
@@ -50,7 +50,7 @@ module Mongoid
       # @example Should fallbacks be used.
       #   field.fallbacks?
       #
-      # @return [ true, false ] If fallbacks should be used.
+      # @return [ true | false ] If fallbacks should be used.
       def fallbacks?
         return true if options[:fallbacks].nil?
         !!options[:fallbacks]

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
@@ -363,7 +396,7 @@ module Mongoid
       # 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 [ 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.
@@ -422,7 +455,7 @@ module Mongoid
       # 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.
+      # @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)
@@ -474,7 +507,7 @@ 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
@@ -603,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
@@ -697,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
@@ -737,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,6 +38,7 @@ module Mongoid
       :max,
       :min,
       :none,
+      :pick,
       :pluck,
       :read,
       :sum,
@@ -75,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
@@ -86,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
@@ -121,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.
@@ -148,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
@@ -169,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
@@ -182,15 +196,11 @@ module Mongoid
     # @example Find the first document.
     #   Person.first
     #
-    # @param [ Integer | Hash ] limit_or_opts The number of documents to
-    #   return, or a hash of options.
-    #
-    # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
-    #   Don't apply a sort on _id if no other sort is defined on the criteria.
+    # @param [ Integer ] limit The number of documents to return.
     #
     # @return [ Document ] The first matching document.
-    def first(limit_or_opts = nil)
-      with_default_scope.first(limit_or_opts)
+    def first(limit = nil)
+      with_default_scope.first(limit)
     end
     alias :one :first
 
@@ -199,15 +209,11 @@ module Mongoid
     # @example Find the last document.
     #   Person.last
     #
-    # @param [ Integer | Hash ] limit_or_opts The number of documents to
-    #   return, or a hash of options.
-    #
-    # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
-    #   Don't apply a sort on _id if no other sort is defined on the criteria.
+    # @param [ Integer ] limit The number of documents to return.
     #
     # @return [ Document ] The last matching document.
-    def last(limit_or_opts = nil)
-      with_default_scope.last(limit_or_opts)
+    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.
       #