mongoid 8.0.10 → 8.1.0

data/lib/mongoid/errors/drop_collection_failure.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to drop a collection failed.
+    class DropCollectionFailure < MongoidError
+
+      # Instantiate the drop collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to drop.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "drop_collection_failure",
+                {
+                  collection_name: collection_name
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/immutable_attribute.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when attempting the change the value of an
+    # immutable attribute. For example, the _id attribute is immutable,
+    # and attempting to change it on a document that has already been
+    # persisted will result in this error.
+    class ImmutableAttribute < MongoidError
+
+      # Create the new error.
+      #
+      # @example Create the new error.
+      #   ImmutableAttribute.new(:_id, "1234")
+      #
+      # @param [ Symbol | String ] name The name of the attribute.
+      # @param [ Object ] value The attempted set value.
+      def initialize(name, value)
+        super(
+          compose_message("immutable_attribute", { name: name, value: value })
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_async_query_executor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad async query executor option is attempted
+    # to be set.
+    class InvalidQueryExecutor < MongoidError
+
+      # Create the new error.
+      #
+      # @param [ Symbol | String ] executor The attempted async query executor.
+      #
+      # @api private
+      def initialize(executor)
+        super(
+          compose_message(
+            "invalid_async_query_executor",
+            { executor: executor, options: [:immediate, :global_thread_pool] }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_global_executor_concurrency.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad global executor concurrency option is attempted
+    # to be set.
+    class InvalidGlobalExecutorConcurrency < MongoidError
+
+      # Create the new error.
+      #
+      # @api private
+      def initialize
+        super(
+          compose_message(
+            "invalid_global_executor_concurrency"
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_storage_parent.rb

@@ -4,6 +4,8 @@ module Mongoid
   module Errors
 
     # Raised when calling store_in in a sub-class of Mongoid::Document
+    #
+    # @deprecated
     class InvalidStorageParent < MongoidError
 
       # Create the new error.

data/lib/mongoid/errors.rb

@@ -3,11 +3,14 @@
 require "mongoid/errors/mongoid_error"
 require "mongoid/errors/ambiguous_relationship"
 require "mongoid/errors/callback"
+require "mongoid/errors/create_collection_failure"
 require "mongoid/errors/criteria_argument_required"
 require "mongoid/errors/document_not_destroyed"
 require "mongoid/errors/document_not_found"
 require "mongoid/errors/empty_config_file"
+require "mongoid/errors/immutable_attribute"
 require "mongoid/errors/in_memory_collation_not_supported"
+require "mongoid/errors/invalid_async_query_executor"
 require "mongoid/errors/invalid_collection"
 require "mongoid/errors/invalid_config_file"
 require "mongoid/errors/invalid_config_option"
@@ -16,6 +19,7 @@ require "mongoid/errors/invalid_field"
 require "mongoid/errors/invalid_field_option"
 require "mongoid/errors/invalid_field_type"
 require "mongoid/errors/invalid_find"
+require "mongoid/errors/invalid_global_executor_concurrency"
 require "mongoid/errors/invalid_includes"
 require "mongoid/errors/invalid_index"
 require "mongoid/errors/invalid_options"
@@ -35,7 +39,6 @@ require "mongoid/errors/invalid_scope"
 require "mongoid/errors/invalid_session_use"
 require "mongoid/errors/invalid_set_polymorphic_relation"
 require "mongoid/errors/invalid_storage_options"
-require "mongoid/errors/invalid_storage_parent"
 require "mongoid/errors/invalid_time"
 require "mongoid/errors/inverse_not_found"
 require "mongoid/errors/mixed_relations"

data/lib/mongoid/extensions/hash.rb

@@ -38,12 +38,8 @@ module Mongoid
         consolidated = {}
         each_pair do |key, value|
           if key =~ /\$/
-            value.keys.each do |key2|
-              value2 = value[key2]
-              real_key = klass.database_field_name(key2)
-
-              value.delete(key2) if real_key != key2
-              value[real_key] = value_for(key, klass, real_key, value2)
+            value.each_pair do |_key, _value|
+              value[_key] = (key == "$rename") ? _value.to_s : mongoize_for(key, klass, _key, _value)
             end
             consolidated[key] ||= {}
             consolidated[key].update(value)
@@ -185,24 +181,6 @@ module Mongoid
 
       private
 
-      # Get the value for the provided operator, klass, key and value.
-      #
-      # This is necessary for special cases like $rename, $addToSet and $push.
-      #
-      # @param [ String ] operator The operator.
-      # @param [ Class ] klass The model class.
-      # @param [ String | Symbol ] key The field key.
-      # @param [ Object ] value The original value.
-      #
-      # @return [ Object ] Value prepared for the provided operator.
-      def value_for(operator, klass, key, value)
-        case operator
-        when "$rename" then value.to_s
-        when "$addToSet", "$push" then value.mongoize
-        else mongoize_for(operator, klass, operator, value)
-        end
-      end
-
       # Mongoize for the klass, key and value.
       #
       # @api private

data/lib/mongoid/extensions/object.rb

@@ -91,7 +91,7 @@ module Mongoid
       #   object.do_or_do_not(:use, "The Force")
       #
       # @param [ String | Symbol ] name The method name.
-      # @param [ Array ] args The arguments.
+      # @param [ Object... ] *args The arguments.
       #
       # @return [ Object | nil ] The result of the method call or nil if the
       #   method does not exist.
@@ -190,7 +190,7 @@ module Mongoid
       #   object.you_must(:use, "The Force")
       #
       # @param [ String | Symbol ] name The method name.
-      # @param [ Array ] args The arguments.
+      # @param [ Object... ] *args The arguments.
       #
       # @return [ Object | nil ] The result of the method call or nil if the
       #   method does not exist. Nil if the object is frozen.

data/lib/mongoid/extensions/time.rb

@@ -34,6 +34,8 @@ module Mongoid
         #   ::Time.configured
         #
         # @return [ Time ] The configured time.
+        #
+        # @deprecated
         def configured
           Mongoid.use_activesupport_time_zone? ? (::Time.zone || ::Time) : ::Time
         end

data/lib/mongoid/fields/localized.rb

@@ -31,6 +31,16 @@ module Mongoid
         true
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        options[:localize] == :present
+      end
+
       # Convert the provided string into a hash for the locale.
       #
       # @example Serialize the value.

data/lib/mongoid/fields/standard.rb

@@ -97,6 +97,16 @@ module Mongoid
         false
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        false
+      end
+
       # Get the metadata for the field if its a foreign key.
       #
       # @example Get the metadata.

data/lib/mongoid/fields.rb

@@ -47,11 +47,6 @@ module Mongoid
     # @api private
     INVALID_BSON_CLASSES = [ BSON::Decimal128, BSON::Int32, BSON::Int64 ].freeze
 
-    # The suffix for generated translated fields.
-    # 
-    # @api private
-    TRANSLATIONS_SFX = '_translations'
-
     module ClassMethods
       # Returns the list of id fields for this model class, as both strings
       # and symbols.
@@ -104,8 +99,8 @@ module Mongoid
           ar.each_with_index do |fn, i|
             key = fn
             unless klass.fields.key?(fn) || klass.relations.key?(fn)
-              if fn.end_with?(TRANSLATIONS_SFX)
-                key = fn.delete_suffix(TRANSLATIONS_SFX)
+              if tr = fn.match(/(.*)_translations\z/)&.captures&.first
+                key = tr
               else
                 key = fn
               end
@@ -543,6 +538,8 @@ module Mongoid
       #   Model.add_defaults(field)
       #
       # @param [ Field ] field The field to add for.
+      #
+      # @api private
       def add_defaults(field)
         default, name = field.default_val, field.name.to_s
         remove_defaults(name)
@@ -562,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
@@ -589,6 +588,8 @@ module Mongoid
       #   # => "called"
       #
       # @param [ Field ] field the field to process
+      #
+      # @api private
       def process_options(field)
         field_options = field.options
 
@@ -611,6 +612,8 @@ module Mongoid
       # @param [ Symbol ] name The name of the field.
       # @param [ Symbol ] meth The name of the accessor.
       # @param [ Hash ] options The options.
+      #
+      # @api private
       def create_accessors(name, meth, options = {})
         field = fields[name]
 
@@ -634,6 +637,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_getter(name, meth, field)
         generated_methods.module_eval do
           re_define_method(meth) do
@@ -656,6 +661,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_getter_before_type_cast(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_before_type_cast") do
@@ -676,6 +683,8 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}=") do |value|
@@ -695,6 +704,8 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}?") do
@@ -711,13 +722,15 @@ module Mongoid
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_translations_getter(name, meth)
         generated_methods.module_eval do
-          re_define_method("#{meth}#{TRANSLATIONS_SFX}") do
+          re_define_method("#{meth}_translations") do
             attributes[name] ||= {}
             attributes[name].with_indifferent_access
           end
-          alias_method :"#{meth}_t", :"#{meth}#{TRANSLATIONS_SFX}"
+          alias_method :"#{meth}_t", :"#{meth}_translations"
         end
       end
 
@@ -729,16 +742,18 @@ module Mongoid
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_translations_setter(name, meth, field)
         generated_methods.module_eval do
-          re_define_method("#{meth}#{TRANSLATIONS_SFX}=") do |value|
+          re_define_method("#{meth}_translations=") do |value|
             attribute_will_change!(name)
             value&.transform_values! do |_value|
               field.type.mongoize(_value)
             end
             attributes[name] = value
           end
-          alias_method :"#{meth}_t=", :"#{meth}#{TRANSLATIONS_SFX}="
+          alias_method :"#{meth}_t=", :"#{meth}_translations="
         end
       end
 
@@ -748,6 +763,8 @@ module Mongoid
       #   Person.generated_methods
       #
       # @return [ Module ] The module of generated methods.
+      #
+      # @api private
       def generated_methods
         @generated_methods ||= begin
           mod = Module.new
@@ -762,11 +779,21 @@ module Mongoid
       #   Model.remove_defaults(name)
       #
       # @param [ String ] name The field name.
+      #
+      # @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)
         opts[:type] = retrieve_and_validate_type(name, options[:type])
@@ -787,22 +814,32 @@ module Mongoid
       #
       # @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.'
+        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
-          Mongoid.logger.warn(warn_message)
         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
@@ -810,19 +847,6 @@ module Mongoid
           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

@@ -22,18 +22,24 @@ module Mongoid
       :each,
       :each_with_index,
       :extras,
+      :fifth,
+      :fifth!,
       :find_one_and_delete,
       :find_one_and_replace,
       :find_one_and_update,
       :find_or_create_by,
       :find_or_create_by!,
       :find_or_initialize_by,
+      :first!,
       :first_or_create,
       :first_or_create!,
       :first_or_initialize,
       :for_js,
+      :fourth,
+      :fourth!,
       :geo_near,
       :includes,
+      :last!,
       :map_reduce,
       :max,
       :min,
@@ -41,11 +47,19 @@ module Mongoid
       :pick,
       :pluck,
       :read,
+      :second,
+      :second!,
+      :second_to_last,
+      :second_to_last!,
       :sum,
       :take,
       :take!,
       :tally,
       :text_search,
+      :third,
+      :third!,
+      :third_to_last,
+      :third_to_last!,
       :update,
       :update_all,
 
@@ -87,9 +101,19 @@ module Mongoid
     # @example Do any documents exist for the conditions?
     #   Person.exists?
     #
+    # @example Do any documents exist for given _id.
+    #   Person.exists?(BSON::ObjectId(...))
+    #
+    # @example Do any documents exist for given conditions.
+    #   Person.exists?(name: "...")
+    #
+    # @param [ Hash | Object | false ] id_or_conditions an _id to
+    #   search for, a hash of conditions, nil or false.
+    #
     # @return [ true | false ] If any documents exist for the conditions.
-    def exists?
-      with_default_scope.exists?
+    #   Always false if passed nil or false.
+    def exists?(id_or_conditions = :none)
+      with_default_scope.exists?(id_or_conditions)
     end
 
     # Finds a +Document+ or multiple documents by their _id values.
@@ -135,7 +159,7 @@ module Mongoid
     # @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.
+    # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #