mongoid 7.0.2 → 8.1.1

data/lib/mongoid/fields.rb

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "mongoid/fields/standard"
 require "mongoid/fields/foreign_key"
 require "mongoid/fields/localized"
@@ -6,13 +7,14 @@ require "mongoid/fields/validators"
 
 module Mongoid
 
-  # This module defines behaviour for fields.
+  # This module defines behavior for fields.
   module Fields
     extend ActiveSupport::Concern
 
+    StringifiedSymbol = Mongoid::StringifiedSymbol
+    Boolean = Mongoid::Boolean
+
     # For fields defined with symbols use the correct class.
-    #
-    # @since 4.0.0
     TYPE_MAPPINGS = {
       array: Array,
       big_decimal: BigDecimal,
@@ -28,14 +30,94 @@ module Mongoid
       regexp: Regexp,
       set: Set,
       string: String,
+      stringified_symbol: StringifiedSymbol,
       symbol: Symbol,
       time: Time
     }.with_indifferent_access
 
-    # Constant for all names of the id field in a document.
+    # Constant for all names of the _id field in a document.
+    #
+    # This does not include aliases of _id field.
     #
-    # @since 5.0.0
-    IDS = [ :_id, :id, '_id', 'id' ].freeze
+    # @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.
+      #
+      # @return [ Array<Symbol | String> ] List of id fields.
+      #
+      # @api private
+      def id_fields
+        IDS.dup.tap do |id_fields|
+          aliased_fields.each do |k, v|
+            if v == '_id'
+              id_fields << k.to_sym
+              id_fields << k
+            end
+          end
+        end
+      end
+
+      # Extracts the id field from the specified attributes hash based on
+      # aliases defined in this class.
+      #
+      # @param [ Hash ] attributes The attributes to inspect.
+      #
+      # @return [ Object ] The id value.
+      #
+      # @api private
+      def extract_id_field(attributes)
+        id_fields.each do |k|
+          if v = attributes[k]
+            return v
+          end
+        end
+        nil
+      end
+
+      # Removes the _translations from the given field name. This is done only
+      # when there doesn't already exist a field name or relation with the
+      # same name (i.e. with the _translations suffix). This check for an
+      # existing field is done recursively
+      #
+      # @param [ String | Symbol ] name The name of the field to cleanse.
+      #
+      # @return [ Field ] The field name without _translations
+      def cleanse_localized_field_names(name)
+        name = database_field_name(name.to_s)
+
+        klass = self
+        [].tap do |res|
+          ar = name.split('.')
+          ar.each_with_index do |fn, i|
+            key = fn
+            unless klass.fields.key?(fn) || klass.relations.key?(fn)
+              if tr = fn.match(/(.*)_translations\z/)&.captures&.first
+                key = tr
+              else
+                key = fn
+              end
+
+            end
+            res.push(key)
+
+            if klass.fields.key?(fn)
+              res.push(ar.drop(i+1).join('.')) unless i == ar.length - 1
+              break
+            elsif klass.relations.key?(fn)
+              klass = klass.relations[key].klass
+            end
+          end
+        end.join('.')
+      end
+    end
 
     included do
       class_attribute :aliased_fields
@@ -57,8 +139,7 @@ module Mongoid
         type: BSON::ObjectId
       )
 
-      alias :id :_id
-      alias :id= :_id=
+      alias_attribute(:id, :_id)
     end
 
     # Apply all default values to the document which are not procs.
@@ -66,9 +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.
-    #
-    # @since 2.4.0
+    # @return [ Array<String> ] The names of the non-proc defaults.
     def apply_pre_processed_defaults
       pre_processed_defaults.each do |name|
         apply_default(name)
@@ -80,10 +159,9 @@ module Mongoid
     # @example Apply all the proc defaults.
     #   model.apply_post_processed_defaults
     #
-    # @return [ Array<String ] The names of the proc defaults.
-    #
-    # @since 2.4.0
+    # @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
@@ -95,8 +173,6 @@ module Mongoid
     #   model.apply_default("name")
     #
     # @param [ String ] name The name of the field.
-    #
-    # @since 2.4.0
     def apply_default(name)
       unless attributes.key?(name)
         if field = fields[name]
@@ -113,9 +189,8 @@ module Mongoid
     #
     # @example Apply all the defaults.
     #   model.apply_defaults
-    #
-    # @since 2.4.0
     def apply_defaults
+      pending_callbacks.delete(:apply_defaults)
       apply_pre_processed_defaults
       apply_post_processed_defaults
     end
@@ -126,11 +201,9 @@ module Mongoid
     # method to automatically wrap params in JSON requests.
     #
     # @example Get the field names
-    #   docment.attribute_names
+    #   document.attribute_names
     #
     # @return [ Array<String> ] The field names
-    #
-    # @since 3.0.0
     def attribute_names
       self.class.attribute_names
     end
@@ -141,11 +214,9 @@ 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.
-    #
-    # @since 3.0.7
     def database_field_name(name)
       self.class.database_field_name(name)
     end
@@ -158,9 +229,7 @@ module Mongoid
     # @param [ Field ] field The field.
     # @param [ Object ] value The current value.
     #
-    # @return [ true, false ] If we set the field lazily.
-    #
-    # @since 3.1.0
+    # @return [ true | false ] If we set the field lazily.
     def lazy_settable?(field, value)
       !frozen? && value.nil? && field.lazy?
     end
@@ -172,17 +241,43 @@ 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
       # defined on a field.
       #
-      # No assumptions are made about what sort of work the handler might
+      # No assumptions are made about what functionality the handler might
       # perform, so it will always be called if the `option_name` key is
       # provided in the field definition -- even if it is false or nil.
       #
@@ -194,8 +289,6 @@ module Mongoid
       # @param [ Symbol ] option_name the option name to match against
       # @param [ Proc ] block the handler to execute when the option is
       #   provided.
-      #
-      # @since 2.1.0
       def option(option_name, &block)
         options[option_name] = block
       end
@@ -207,11 +300,141 @@ module Mongoid
       #   # => { :required => #<Proc:0x00000100976b38> }
       #
       # @return [ Hash ] the option map
-      #
-      # @since 2.1.0
       def options
         @options ||= {}
       end
+
+      # 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:
+      #
+      # - 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.
+      #
+      # The next iteration will use klass's fields and associations to continue
+      # traversing the tree.
+      #
+      # @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.
+      # Used in determining if the field is aliased or not. Recursively
+      # finds aliases for embedded documents and fields, delimited with
+      # period "." character.
+      #
+      # 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:
+      #
+      #   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.
+      #
+      # @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 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
+        end
+      end
     end
 
     module ClassMethods
@@ -225,8 +448,6 @@ module Mongoid
       #   Model.attribute_names
       #
       # @return [ Array<String> ] The field names
-      #
-      # @since 3.0.0
       def attribute_names
         fields.keys
       end
@@ -234,18 +455,11 @@ 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.
       #
-      # @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.
-      #
-      # @since 3.0.7
       def database_field_name(name)
-        return nil unless name
-        normalized = name.to_s
-        aliased_fields[normalized] || normalized
+        Fields.database_field_name(name, relations, aliased_fields, aliased_associations)
       end
 
       # Defines all the fields that are accessible on the Document
@@ -253,14 +467,14 @@ module Mongoid
       # 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 = {})
@@ -282,8 +496,6 @@ module Mongoid
       # @param [ Class ] type The new type of field.
       #
       # @return [ Serializable ] The new field.
-      #
-      # @since 2.1.0
       def replace_field(name, type)
         remove_defaults(name)
         add_field(name, fields[name].options.merge(type: type))
@@ -295,13 +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.
-      #
-      # @since 1.0.0
+      # @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
@@ -312,7 +539,7 @@ module Mongoid
       #
       # @param [ Field ] field The field to add for.
       #
-      # @since 2.4.0
+      # @api private
       def add_defaults(field)
         default, name = field.default_val, field.name.to_s
         remove_defaults(name)
@@ -332,6 +559,8 @@ module Mongoid
       #
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The hash of options.
+      #
+      # @api private
       def add_field(name, options = {})
         aliased = options[:as]
         aliased_fields[aliased.to_s] = name if aliased
@@ -359,6 +588,8 @@ module Mongoid
       #   # => "called"
       #
       # @param [ Field ] field the field to process
+      #
+      # @api private
       def process_options(field)
         field_options = field.options
 
@@ -382,7 +613,7 @@ module Mongoid
       # @param [ Symbol ] meth The name of the accessor.
       # @param [ Hash ] options The options.
       #
-      # @since 2.0.0
+      # @api private
       def create_accessors(name, meth, options = {})
         field = fields[name]
 
@@ -407,7 +638,7 @@ module Mongoid
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
       #
-      # @since 2.4.0
+      # @api private
       def create_field_getter(name, meth, field)
         generated_methods.module_eval do
           re_define_method(meth) do
@@ -415,9 +646,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
@@ -433,7 +662,7 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       #
-      # @since 3.1.0
+      # @api private
       def create_field_getter_before_type_cast(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_before_type_cast") do
@@ -455,7 +684,7 @@ module Mongoid
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
       #
-      # @since 2.4.0
+      # @api private
       def create_field_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}=") do |value|
@@ -476,7 +705,7 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       #
-      # @since 2.4.0
+      # @api private
       def create_field_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}?") do
@@ -494,11 +723,12 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       #
-      # @since 2.4.0
+      # @api private
       def create_translations_getter(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations") do
-            (attributes[name] ||= {}).with_indifferent_access
+            attributes[name] ||= {}
+            attributes[name].with_indifferent_access
           end
           alias_method :"#{meth}_t", :"#{meth}_translations"
         end
@@ -513,15 +743,13 @@ module Mongoid
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
       #
-      # @since 2.4.0
+      # @api private
       def create_translations_setter(name, meth, field)
         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
@@ -536,7 +764,7 @@ module Mongoid
       #
       # @return [ Module ] The module of generated methods.
       #
-      # @since 2.0.0
+      # @api private
       def generated_methods
         @generated_methods ||= begin
           mod = Module.new
@@ -552,26 +780,71 @@ module Mongoid
       #
       # @param [ String ] name The field name.
       #
-      # @since 2.4.0
+      # @api private
       def remove_defaults(name)
         pre_processed_defaults.delete_one(name)
         post_processed_defaults.delete_one(name)
       end
 
+      # Create a field for the given name and options.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Hash ] options The hash of options.
+      #
+      # @return [ Field ] The created field.
+      #
+      # @api private
       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)
+        type_mapping = TYPE_MAPPINGS[type]
+        result = type_mapping || unmapped_type(type)
+        if !result.is_a?(Class)
+          raise Errors::InvalidFieldType.new(self, name, type)
+        else
+          if INVALID_BSON_CLASSES.include?(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+."
+            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
+        result
+      end
+
+      # Returns the type of the field if the type was not in the TYPE_MAPPINGS
+      # hash.
+      #
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @api private
+      def unmapped_type(type)
+        if "Boolean" == type.to_s
           Mongoid::Boolean
         else
-          options[:type] || Object
+          type || Object
         end
       end
     end