mongoid 8.0.9 → 8.1.0

data/lib/mongoid/config.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "mongoid/config/defaults"
 require "mongoid/config/environment"
 require "mongoid/config/options"
 require "mongoid/config/validators"
@@ -11,6 +12,7 @@ module Mongoid
   module Config
     extend Forwardable
     extend Options
+    extend Defaults
     extend self
 
     def_delegators ::Mongoid, :logger, :logger=
@@ -70,6 +72,7 @@ module Mongoid
 
     # Use ActiveSupport's time zone in time operations instead of the
     # Ruby default time zone.
+    # @deprecated
     option :use_activesupport_time_zone, default: true
 
     # Return stored times as UTC.
@@ -125,22 +128,35 @@ module Mongoid
     # always return a Hash.
     option :legacy_attributes, default: false
 
-    # Allow BSON::Decimal128 to be parsed and returned directly in
-    # field values. When BSON 5 is present and the this option is set to false
-    # (the default), BSON::Decimal128 values in the database will be returned
-    # as BigDecimal.
-    #
-    # @note this option only has effect when BSON 5+ is present. Otherwise,
-    #   the setting is ignored.
-    option :allow_bson5_decimal128, default: false, on_change: -> (allow) do
-      if BSON::VERSION >= '5.0.0'
-        if allow
-          BSON::Registry.register(BSON::Decimal128::BSON_TYPE, BSON::Decimal128)
-        else
-          BSON::Registry.register(BSON::Decimal128::BSON_TYPE, BigDecimal)
-        end
-      end
-    end
+    # Sets the async_query_executor for the application. By default the thread pool executor
+    #   is set to `:immediate. Options are:
+    #
+    #   - :immediate - Initializes a single +Concurrent::ImmediateExecutor+
+    #   - :global_thread_pool - Initializes a single +Concurrent::ThreadPoolExecutor+
+    #      that uses the +async_query_concurrency+ for the +max_threads+ value.
+    option :async_query_executor, default: :immediate
+
+    # Defines how many asynchronous queries can be executed concurrently.
+    # This option should be set only if `async_query_executor` is set
+    # to `:global_thread_pool`.
+    option :global_executor_concurrency, default: nil
+
+    # When this flag is false, a document will become read-only only once the
+    # #readonly! method is called, and an error will be raised on attempting
+    # to save or update such documents, instead of just on delete. When this
+    # flag is true, a document is only read-only if it has been projected
+    # using #only or #without, and read-only documents will not be
+    # deletable/destroyable, but they will be savable/updatable.
+    # When this feature flag is turned on, the read-only state will be reset on
+    # reload, but when it is turned off, it won't be.
+    option :legacy_readonly, default: true
+
+    # When this flag is true, any attempt to change the _id of a persisted
+    # document will raise an exception (`Errors::ImmutableAttribute`).
+    # This will be the default in 9.0. When this flag is false (the default
+    # in 8.x), changing the _id of a persisted document might be ignored,
+    # or it might work, depending on the situation.
+    option :immutable_ids, default: false
 
     # When this flag is true, callbacks for every embedded document will be
     # called only once, even if the embedded document is embedded in multiple
@@ -152,18 +168,12 @@ module Mongoid
     # See https://jira.mongodb.org/browse/MONGOID-5542
     option :prevent_multiple_calls_of_embedded_callbacks, default: false
 
-    # When this flag is true, callbacks for embedded documents will not be
-    # called. This is the default in 8.x, but will be changed to false in 9.0.
-    #
-    # Setting this flag to true (as it is in 8.x) may lead to stack
-    # overflow errors if there are more than cicrca 1000 embedded
-    # documents in the root document's dependencies graph.
+    # Returns the Config singleton, for use in the configure DSL.
     #
-    # It is strongly recommended to set this flag to false in 8.x, if you
-    # are not using around callbacks for embedded documents.
-    #
-    # See https://jira.mongodb.org/browse/MONGOID-5658 for more details.
-    option :around_callbacks_for_embeds, default: true
+    # @return [ self ] The Config singleton.
+    def config
+      self
+    end
 
     # Has Mongoid been configured? This is checking that at least a valid
     # client config exists.
@@ -246,6 +256,17 @@ module Mongoid
       end
     end
 
+    # Deregister a model in the application with Mongoid.
+    #
+    # @param [ Class ] klass The model to deregister.
+    #
+    # @api private
+    def deregister_model(klass)
+      LOCK.synchronize do
+        models.delete(klass)
+      end
+    end
+
     # From a hash of settings, load all the configuration.
     #
     # @example Load the configuration.
@@ -318,6 +339,7 @@ module Mongoid
     # @param [ Hash ] options The configuration options.
     def options=(options)
       if options
+        Validators::AsyncQueryExecutor.validate(options)
         options.each_pair do |option, value|
           Validators::Option.validate(option)
           send("#{option}=", value)
@@ -385,5 +407,44 @@ module Mongoid
         client
       end
     end
+
+    module DeprecatedOptions
+      OPTIONS = %i[ use_activesupport_time_zone
+                    broken_aggregables
+                    broken_alias_handling
+                    broken_and
+                    broken_scoping
+                    broken_updates
+                    compare_time_by_ms
+                    legacy_attributes
+                    legacy_pluck_distinct
+                    legacy_triple_equals
+                    object_id_as_json_oid
+                    overwrite_chained_operators ]
+
+      if RUBY_VERSION < '3.0'
+        def self.prepended(klass)
+          klass.class_eval do
+            OPTIONS.each do |option|
+              alias_method :"#{option}_without_deprecation=", :"#{option}="
+
+              define_method(:"#{option}=") do |value|
+                Mongoid::Warnings.send(:"warn_#{option}_deprecated")
+                send(:"#{option}_without_deprecation=", value)
+              end
+            end
+          end
+        end
+      else
+        OPTIONS.each do |option|
+          define_method(:"#{option}=") do |value|
+            Mongoid::Warnings.send(:"warn_#{option}_deprecated")
+            super(value)
+          end
+        end
+      end
+    end
+
+    prepend DeprecatedOptions
   end
 end

data/lib/mongoid/contextual/atomic.rb

@@ -150,7 +150,7 @@ module Mongoid
       # @example Unset the field on the matches.
       #   context.unset(:name)
       #
-      # @param [ String | Symbol | Array<String | Symbol> | Hash ] args
+      # @param [ [ String | Symbol | Array<String | Symbol> | Hash ]... ] *args
       #   The name(s) of the field(s) to unset.
       #   If a Hash is specified, its keys will be used irrespective of what
       #   each key's value is, even if the value is nil or false.

data/lib/mongoid/contextual/memory.rb

@@ -110,9 +110,24 @@ module Mongoid
       # @example Do any documents exist for the context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.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 the count is more than zero.
-      def exists?
-        any?
+      #   Always false if passed nil or false.
+      def exists?(id_or_conditions = :none)
+        case id_or_conditions
+        when :none then any?
+        when nil, false then false
+        when Hash then Memory.new(criteria.where(id_or_conditions)).exists?
+        else Memory.new(criteria.where(_id: id_or_conditions)).exists?
+        end
       end
 
       # Get the first document in the database for the criteria's selector.
@@ -133,6 +148,20 @@ module Mongoid
       alias :one :first
       alias :find_first :first
 
+      # Get the first document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the first document.
+      #   context.first!
+      #
+      # @return [ Document ] The first document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def first!
+        first || raise_document_not_found_error
+      end
+
       # Create the new in memory context.
       #
       # @example Create the new context.
@@ -180,37 +209,18 @@ module Mongoid
         end
       end
 
-      # Take the given number of documents from the database.
-      #
-      # @example Take a document.
-      #   context.take
-      #
-      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      # Get the last document in the database for the criteria's selector or
+      # raise an error if none is found.
       #
-      # @return [ Document ] The document.
-      def take(limit = nil)
-        if limit
-          eager_load(documents.take(limit))
-        else
-          eager_load([documents.first]).first
-        end
-      end
-
-      # Take the given number of documents from the database.
-      #
-      # @example Take a document.
-      #   context.take
+      # @example Get the last document.
+      #   context.last!
       #
-      # @return [ Document ] The document.
+      # @return [ Document ] The last document.
       #
       # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
       #   documents to take.
-      def take!
-        if documents.empty?
-          raise Errors::DocumentNotFound.new(klass, nil, nil)
-        else
-          eager_load([documents.first]).first
-        end
+      def last!
+        last || raise_document_not_found_error
       end
 
       # Get the length of matching documents in the context.
@@ -242,7 +252,7 @@ module Mongoid
       # @example Get the values in memory.
       #   context.pluck(:name)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
       #
       # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
@@ -260,9 +270,9 @@ module Mongoid
       # @example Get the values in memory.
       #   context.pick(:name)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pick.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pick.
       #
-      # @return [ Object, Array<Object> ] The picked values.
+      # @return [ Object | Array<Object> ] The picked values.
       def pick(*fields)
         if doc = documents.first
           pluck_from_doc(doc, *fields)
@@ -285,6 +295,36 @@ module Mongoid
         end
       end
 
+      # Take the given number of documents from the database.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      #
+      # @return [ Document ] The document.
+      def take(limit = nil)
+        if limit
+          eager_load(documents.take(limit))
+        else
+          eager_load([documents.first]).first
+        end
+      end
+
+      # Take the given number of documents from the database or raise an error
+      # if none are found.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        take || raise_document_not_found_error
+      end
+
       # Skips the provided number of documents.
       #
       # @example Skip the documents.
@@ -335,6 +375,162 @@ module Mongoid
         update_documents(attributes, entries)
       end
 
+      # Get the second document in the database for the criteria's selector.
+      #
+      # @example Get the second document.
+      #   context.second
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The second document.
+      def second
+        eager_load([documents.second]).first
+      end
+
+      # Get the second document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the second document.
+      #   context.second!
+      #
+      # @return [ Document ] The second document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def second!
+        second || raise_document_not_found_error
+      end
+
+      # Get the third document in the database for the criteria's selector.
+      #
+      # @example Get the third document.
+      #   context.third
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The third document.
+      def third
+        eager_load([documents.third]).first
+      end
+
+      # Get the third document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the third document.
+      #   context.third!
+      #
+      # @return [ Document ] The third document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def third!
+        third || raise_document_not_found_error
+      end
+
+      # Get the fourth document in the database for the criteria's selector.
+      #
+      # @example Get the fourth document.
+      #   context.fourth
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The fourth document.
+      def fourth
+        eager_load([documents.fourth]).first
+      end
+
+      # Get the fourth document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the fourth document.
+      #   context.fourth!
+      #
+      # @return [ Document ] The fourth document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def fourth!
+        fourth || raise_document_not_found_error
+      end
+
+      # Get the fifth document in the database for the criteria's selector.
+      #
+      # @example Get the fifth document.
+      #   context.fifth
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The fifth document.
+      def fifth
+        eager_load([documents.fifth]).first
+      end
+
+      # Get the fifth document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the fifth document.
+      #   context.fifth!
+      #
+      # @return [ Document ] The fifth document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def fifth!
+        fifth || raise_document_not_found_error
+      end
+
+      # Get the second to last document in the database for the criteria's selector.
+      #
+      # @example Get the second to last document.
+      #   context.second_to_last
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The second to last document.
+      def second_to_last
+        eager_load([documents.second_to_last]).first
+      end
+
+      # Get the second to last document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the second to last document.
+      #   context.second_to_last!
+      #
+      # @return [ Document ] The second to last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def second_to_last!
+        second_to_last || raise_document_not_found_error
+      end
+
+      # Get the third to last document in the database for the criteria's selector.
+      #
+      # @example Get the third to last document.
+      #   context.third_to_last
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The third to last document.
+      def third_to_last
+        eager_load([documents.third_to_last]).first
+      end
+
+      # Get the third to last document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the third to last document.
+      #   context.third_to_last!
+      #
+      # @return [ Document ] The third to last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def third_to_last!
+        third_to_last || raise_document_not_found_error
+      end
+
       private
 
       # Get the documents the context should iterate. This follows 3 rules:
@@ -561,9 +757,9 @@ module Mongoid
       # Pluck the field values from the given document.
       #
       # @param [ Document ] doc The document to pluck from.
-      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
       #
-      # @return [ Object, Array<Object> ] The plucked values.
+      # @return [ Object | Array<Object> ] The plucked values.
       def pluck_from_doc(doc, *fields)
         if fields.length == 1
           retrieve_value_at_path(doc, fields.first)
@@ -573,6 +769,10 @@ module Mongoid
           end
         end
       end
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
     end
   end
 end

data/lib/mongoid/contextual/mongo/documents_loader.rb

@@ -0,0 +1,177 @@
+require "mongoid/association/eager_loadable"
+
+module Mongoid
+  module Contextual
+    class Mongo
+      # Loads documents for the provided criteria.
+      #
+      # @api private
+      class DocumentsLoader
+        extend Forwardable
+        include Association::EagerLoadable
+
+        def_delegators :@future, :value!, :value, :wait!, :wait
+
+        # Returns synchronous executor to be used when async_query_executor config option
+        # is set to :immediate. This executor runs all operations on the current
+        # thread, blocking as necessary.
+        #
+        # @return [ Concurrent::ImmediateExecutor ] The executor
+        #   to be used to execute document loading tasks.
+        def self.immediate_executor
+          @@immediate_executor ||= Concurrent::ImmediateExecutor.new
+        end
+
+        # Returns asynchronous executor to be used when async_query_executor config option
+        # is set to :global_thread_pool. This executor runs operations on background threads
+        # using a thread pool.
+        #
+        # @return [ Concurrent::ThreadPoolExecutor ] The executor
+        #   to be used to execute document loading tasks.
+        def self.global_thread_pool_async_query_executor
+          create_pool = Proc.new do |concurrency|
+            Concurrent::ThreadPoolExecutor.new(
+              min_threads: 0,
+              max_threads: concurrency,
+              max_queue: concurrency * 4,
+              fallback_policy: :caller_runs
+            )
+          end
+          concurrency = Mongoid.global_executor_concurrency || 4
+          @@global_thread_pool_async_query_executor ||= create_pool.call(concurrency)
+          if @@global_thread_pool_async_query_executor.max_length != concurrency
+            old_pool = @@global_thread_pool_async_query_executor
+            @@global_thread_pool_async_query_executor = create_pool.call(concurrency)
+            old_pool.shutdown
+          end
+          @@global_thread_pool_async_query_executor
+        end
+
+        # Returns suitable executor according to Mongoid config options.
+        #
+        # @param [ String | Symbol] name The query executor name, can be either
+        #   :immediate or :global_thread_pool. Defaulted to `async_query_executor`
+        #   config option.
+        #
+        # @return [ Concurrent::ImmediateExecutor | Concurrent::ThreadPoolExecutor ] The executor
+        #   to be used to execute document loading tasks.
+        #
+        # @raise [ Errors::InvalidQueryExecutor ] If an unknown name is provided.
+        def self.executor(name = Mongoid.async_query_executor)
+          case name.to_sym
+          when :immediate
+            immediate_executor
+          when :global_thread_pool
+            global_thread_pool_async_query_executor
+          else
+            raise Errors::InvalidQueryExecutor.new(name)
+          end
+        end
+
+        # @return [ Mongoid::Criteria ] Criteria that specifies which documents should
+        #   be loaded. Exposed here because `eager_loadable?` method from
+        #   `Association::EagerLoadable` expects this to be available.
+        attr_accessor :criteria
+
+        # Instantiates the document loader instance and immediately schedules
+        # its execution using the provided executor.
+        #
+        # @param [ Mongo::Collection::View ] view The collection view to get
+        #   records from the database.
+        # @param [ Class ] klass Mongoid model class to instantiate documents.
+        #   All records obtained from the database will be converted to an
+        #   instance of this class, if possible.
+        # @param [ Mongoid::Criteria ] criteria. Criteria that specifies which
+        #   documents should be loaded.
+        # @param [ Concurrent::AbstractExecutorService ] executor. Executor that
+        #   is capable of running `Concurrent::Promises::Future` instances.
+        def initialize(view, klass, criteria, executor: self.class.executor)
+          @view = view
+          @klass = klass
+          @criteria = criteria
+          @mutex = Mutex.new
+          @state = :pending
+          @future = Concurrent::Promises.future_on(executor) do
+            start && execute
+          end
+        end
+
+        # Returns false or true whether the loader is in pending state.
+        #
+        # Pending state means that the loader execution has been scheduled,
+        # but has not been started yet.
+        #
+        # @return [ true | false ] true if the loader is in pending state,
+        #   otherwise false.
+        def pending?
+          @mutex.synchronize do
+            @state == :pending
+          end
+        end
+
+        # Returns false or true whether the loader is in started state.
+        #
+        # Started state means that the loader execution has been started.
+        # Note that the loader stays in this state even after the execution
+        # completed (successfully or failed).
+        #
+        # @return [ true | false ] true if the loader is in started state,
+        #   otherwise false.
+        def started?
+          @mutex.synchronize do
+            @state == :started
+          end
+        end
+
+        # Mark the loader as unscheduled.
+        #
+        # If the loader is marked unscheduled, it will not be executed. The only
+        # option to load the documents is to call `execute` method directly.
+        #
+        # Please note that if execution of a task has been already started,
+        # unscheduling does not have any effect.
+        def unschedule
+          @mutex.synchronize do
+            @state = :cancelled unless @state == :started
+          end
+        end
+
+        # Loads records specified by `@criteria` from the database, and convert
+        # them to Mongoid documents of `@klass` type.
+        #
+        # This method is called by the task (possibly asynchronous) scheduled
+        # when creating an instance of the loader. However, this method can be
+        # called directly, if it is desired to execute loading on the caller
+        # thread immediately.
+        #
+        # Calling this method does not change the state of the loader.
+        #
+        # @return [ Array<Mongoid::Document> ] Array of document loaded from
+        #   the database.
+        def execute
+          documents = @view.map do |doc|
+            Factory.from_db(@klass, doc, @criteria)
+          end
+          eager_load(documents) if eager_loadable?
+          documents
+        end
+
+        private
+
+        # Mark the loader as started if possible.
+        #
+        # @return [ true | false ] Whether the state was changed to :started.
+        def start
+          @mutex.synchronize do
+            if @state == :pending
+              @state = :started
+              true
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end