mongoid 7.3.2 → 7.4.0

data/lib/mongoid/persistable/poppable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $pop operations.
-    #
-    # @since 4.0.0
     module Poppable
       extend ActiveSupport::Concern
 
@@ -24,8 +21,6 @@ module Mongoid
       # @param [ Hash ] pops The field/value pop operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def pop(pops)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pops) do |field, value|

data/lib/mongoid/persistable/pullable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $pull and $pullAll operations.
-    #
-    # @since 4.0.0
     module Pullable
       extend ActiveSupport::Concern
 
@@ -20,8 +17,6 @@ module Mongoid
       # @param [ Hash ] pulls The field/value pull pairs.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def pull(pulls)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pulls) do |field, value|
@@ -40,8 +35,6 @@ module Mongoid
       # @param [ Hash ] pulls The pull all operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def pull_all(pulls)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pulls) do |field, value|

data/lib/mongoid/persistable/pushable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $push and $addToSet operations.
-    #
-    # @since 4.0.0
     module Pushable
       extend ActiveSupport::Concern
 
@@ -19,8 +16,6 @@ module Mongoid
       # @param [ Hash ] adds The field/value pairs to add.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def add_to_set(adds)
         prepare_atomic_operation do |ops|
           process_atomic_operations(adds) do |field, value|
@@ -52,8 +47,6 @@ module Mongoid
       # @param [ Hash ] pushes The $push operations.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def push(pushes)
         prepare_atomic_operation do |ops|
           process_atomic_operations(pushes) do |field, value|

data/lib/mongoid/persistable/renamable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $rename operations.
-    #
-    # @since 4.0.0
     module Renamable
       extend ActiveSupport::Concern
 
@@ -20,8 +17,6 @@ module Mongoid
       # @param [ Hash ] renames The rename pairs of old name/new name.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def rename(renames)
         prepare_atomic_operation do |ops|
           process_atomic_operations(renames) do |old_field, new_field|

data/lib/mongoid/persistable/savable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for persistence operations that save documents.
-    #
-    # @since 4.0.0
     module Savable
 
       # Save the document - will perform an insert if the document is new, and
@@ -18,8 +15,6 @@ module Mongoid
       # @param [ Hash ] options Options to pass to the save.
       #
       # @return [ true, false ] True is success, false if not.
-      #
-      # @since 1.0.0
       def save(options = {})
         if new_record?
           !insert(options).new_record?
@@ -40,8 +35,6 @@ module Mongoid
       # @raise [ Errors::Callback ] If a callback returns false.
       #
       # @return [ true, false ] True if validation passed.
-      #
-      # @since 1.0.0
       def save!(options = {})
         unless save(options)
           fail_due_to_validation! unless errors.empty?

data/lib/mongoid/persistable/settable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $set operations.
-    #
-    # @since 4.0.0
     module Settable
       extend ActiveSupport::Concern
 
@@ -47,8 +44,6 @@ module Mongoid
       # @param [ Hash ] setters The field/value pairs to set.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def set(setters)
         prepare_atomic_operation do |ops|
           process_atomic_operations(setters) do |field, value|

data/lib/mongoid/persistable/unsettable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for $unset operations.
-    #
-    # @since 4.0.0
     module Unsettable
       extend ActiveSupport::Concern
 
@@ -20,8 +17,6 @@ module Mongoid
       #   unset.
       #
       # @return [ Document ] The document.
-      #
-      # @since 4.0.0
       def unset(*fields)
         prepare_atomic_operation do |ops|
           fields.flatten.each do |field|

data/lib/mongoid/persistable/updatable.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for persistence operations that update existing
     # documents.
-    #
-    # @since 4.0.0
     module Updatable
 
       # Update a single attribute and persist the entire document.
@@ -20,11 +17,9 @@ module Mongoid
       # @param [ Object ] value The new value of the attribute.a
       #
       # @raise [ Errors::ReadonlyAttribute ] If the field cannot be changed due
-      #   to being flagged as reaodnly.
+      #   to being flagged as read-only.
       #
-      # @return [ true, false ] True if save was successfull, false if not.
-      #
-      # @since 2.0.0
+      # @return [ true, false ] True if save was successful, false if not.
       def update_attribute(name, value)
         as_writable_attribute!(name, value) do |access|
           normalized = name.to_s
@@ -41,8 +36,6 @@ module Mongoid
       # @param [ Hash ] attributes The attributes to update.
       #
       # @return [ true, false ] True if validation passed, false if not.
-      #
-      # @since 1.0.0
       def update(attributes = {})
         assign_attributes(attributes)
         save
@@ -61,8 +54,6 @@ module Mongoid
       # @raise [ Errors::Callbacks ] If a callback returns false.
       #
       # @return [ true, false ] True if validation passed.
-      #
-      # @since 1.0.0
       def update!(attributes = {})
         result = update_attributes(attributes)
         unless result
@@ -83,8 +74,6 @@ module Mongoid
       #   document.init_atomic_updates
       #
       # @return [ Array<Hash> ] The updates and conflicts.
-      #
-      # @since 4.0.0
       def init_atomic_updates
         updates = atomic_updates
         conflicts = updates.delete(:conflicts) || {}
@@ -103,8 +92,6 @@ module Mongoid
       # @param [ Hash ] options The options.
       #
       # @return [ true, false ] The result of the update.
-      #
-      # @since 4.0.0
       def prepare_update(options = {})
         return false if performing_validations?(options) &&
           invalid?(options[:context] || :update)
@@ -128,8 +115,6 @@ module Mongoid
       # @option options [ true, false ] :validate Whether or not to validate.
       #
       # @return [ true, false ] True if succeeded, false if not.
-      #
-      # @since 1.0.0
       def update_document(options = {})
         prepare_update(options) do
           updates, conflicts = init_atomic_updates

data/lib/mongoid/persistable/upsertable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Persistable
 
     # Defines behavior for persistence operations that upsert documents.
-    #
-    # @since 4.0.0
     module Upsertable
 
       # Perform an upsert of the document. If the document does not exist in the
@@ -19,8 +16,6 @@ module Mongoid
       # @param [ Hash ] options The validation options.
       #
       # @return [ true ] True.
-      #
-      # @since 3.0.0
       def upsert(options = {})
         prepare_upsert(options) do
           collection.find(atomic_selector).update_one(
@@ -42,8 +37,6 @@ module Mongoid
       # @param [ Hash ] options The options hash.
       #
       # @return [ true, false ] If the operation succeeded.
-      #
-      # @since 4.0.0
       def prepare_upsert(options = {})
         return false if performing_validations?(options) && invalid?(:upsert)
         result = run_callbacks(:upsert) do

data/lib/mongoid/persistable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/persistable/creatable"
 require "mongoid/persistable/deletable"
@@ -19,8 +18,6 @@ require "mongoid/persistable/unsettable"
 module Mongoid
 
   # Contains general behavior for persistence operations.
-  #
-  # @since 2.0.0
   module Persistable
     extend ActiveSupport::Concern
     include Creatable
@@ -40,8 +37,6 @@ module Mongoid
     include Unsettable
 
     # The atomic operations that deal with arrays or sets in the db.
-    #
-    # @since 4.0.0
     LIST_OPERATIONS = [ "$addToSet", "$push", "$pull", "$pullAll" ].freeze
 
     # Execute operations atomically (in a single database call) for everything
@@ -89,8 +84,6 @@ module Mongoid
     #   for the same document, if one exists.
     #
     # @return [ true, false ] If the operation succeeded.
-    #
-    # @since 4.0.0
     def atomically(join_context: nil)
       join_context = Mongoid.join_contexts if join_context.nil?
       call_depth = @atomic_depth ||= 0
@@ -128,8 +121,6 @@ module Mongoid
     #   Person.fail_due_to_validation!(person)
     #
     # @raise [ Errors::Validations ] The validation error.
-    #
-    # @since 4.0.0
     def fail_due_to_validation!
       raise Errors::Validations.new(self)
     end
@@ -142,8 +133,6 @@ module Mongoid
     # @param [ Symbol ] method The method being called.
     #
     # @raise [ Errors::Callback ] The callback error.
-    #
-    # @since 4.0.0
     def fail_due_to_callback!(method)
       raise Errors::Callback.new(self.class, method)
     end
@@ -158,8 +147,6 @@ module Mongoid
     #   document.executing_atomically?
     #
     # @return [ true, false ] If we are current executing atomically.
-    #
-    # @since 4.0.0
     def executing_atomically?
       !@atomic_updates_to_execute_stack.nil?
     end
@@ -175,8 +162,6 @@ module Mongoid
     # @param [ Hash ] options The options.
     #
     # @return [ true ] true.
-    #
-    # @since 4.0.0
     def post_process_persist(result, options = {})
       post_persist unless result == false
       errors.clear unless performing_validations?(options)
@@ -194,8 +179,6 @@ module Mongoid
     #   end
     #
     # @return [ Object ] The result of the operation.
-    #
-    # @since 4.0.0
     def prepare_atomic_operation
       operations = yield({})
       persist_or_delay_atomic_operation(operations)
@@ -216,8 +199,6 @@ module Mongoid
     # @param [ Hash ] operations The atomic operations.
     #
     # @return [ Hash ] The operations.
-    #
-    # @since 4.0.0
     def process_atomic_operations(operations)
       operations.each do |field, value|
         access = database_field_name(field)
@@ -295,8 +276,6 @@ module Mongoid
     #   document.persist_or_delay_atomic_operation(ops)
     #
     # @param [ Hash ] operation The operation.
-    #
-    # @since 4.0.0
     def persist_or_delay_atomic_operation(operation)
       if executing_atomically?
         operation.each do |(name, hash)|
@@ -316,8 +295,6 @@ module Mongoid
     #   persist_atomic_operations(ops)
     #
     # @param [ Hash ] operations The atomic operations.
-    #
-    # @since 4.0.0
     def persist_atomic_operations(operations)
       if persisted? && operations && !operations.empty?
         selector = atomic_selector

data/lib/mongoid/persistence_context.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
 
   # Object encapsulating logic for setting/getting a collection and database name
   # and a client with particular options to use when persisting models.
-  #
-  # @since 6.0.0
   class PersistenceContext
     extend Forwardable
 
@@ -19,8 +16,6 @@ module Mongoid
     # The options defining this persistence context.
     #
     # @return [ Hash ] The persistence context options.
-    #
-    # @since 6.0.0
     attr_reader :options
 
     # Extra options in addition to driver client options that determine the
@@ -28,8 +23,6 @@ module Mongoid
     #
     # @return [ Array<Symbol> ] The list of extra options besides client options
     #   that determine the persistence context.
-    #
-    # @since 6.0.0
     EXTRA_OPTIONS = [ :client,
                       :collection
                     ].freeze
@@ -38,8 +31,6 @@ module Mongoid
     #
     # @return [ Array<Symbol> ] The full list of options defining the persistence
     #   context.
-    #
-    # @since 6.0.0
     VALID_OPTIONS = ( Mongo::Client::VALID_OPTIONS + EXTRA_OPTIONS ).freeze
 
     # Initialize the persistence context object.
@@ -50,8 +41,6 @@ module Mongoid
     # @param [ Object ] object The class or model instance for which a persistence context
     #   should be created.
     # @param [ Hash ] opts The persistence context options.
-    #
-    # @since 6.0.0
     def initialize(object, opts = {})
       @object = object
       set_options!(opts)
@@ -67,8 +56,6 @@ module Mongoid
     #
     # @return [ Mongo::Collection ] The collection for this persistence
     #   context.
-    #
-    # @since 6.0.0
     def collection(parent = nil)
       parent ? parent.collection.with(client_options) : client[collection_name.to_sym]
     end
@@ -80,8 +67,6 @@ module Mongoid
     #
     # @return [ String ] The collection name for this persistence
     #  context.
-    #
-    # @since 6.0.0
     def collection_name
       @collection_name ||= (__evaluate__(options[:collection] ||
                              storage_options[:collection]))
@@ -94,8 +79,6 @@ module Mongoid
     #
     # @return [ String ] The database name for this persistence
     #  context.
-    #
-    # @since 6.0.0
     def database_name
       __evaluate__(database_name_option) || client.database.name
     end
@@ -107,8 +90,6 @@ module Mongoid
     #
     # @return [ Mongo::Client ] The client for this persistence
     #  context.
-    #
-    # @since 6.0.0
     def client
       @client ||= begin
         client = Clients.with_name(client_name)
@@ -136,8 +117,6 @@ module Mongoid
     # @param [ Object ] other The object to be compared with this one.
     #
     # @return [ true, false ] Whether the two persistence contexts are equal.
-    #
-    # @since 6.0.0
     def ==(other)
       return false unless other.is_a?(PersistenceContext)
       options == other.options
@@ -192,8 +171,6 @@ module Mongoid
       #   options or a persistence context object.
       #
       # @return [ Mongoid::PersistenceContext ] The persistence context for the object.
-      #
-      # @since 6.0.0
       def set(object, options_or_context)
         key = "[mongoid][#{object.object_id}]:context"
         existing_context = Thread.current[key]
@@ -218,8 +195,6 @@ module Mongoid
       # @param [ Object ] object The class or model instance.
       #
       # @return [ Mongoid::PersistenceContext ] The persistence context for the object.
-      #
-      # @since 6.0.0
       def get(object)
         Thread.current["[mongoid][#{object.object_id}]:context"]
       end
@@ -233,11 +208,11 @@ module Mongoid
       # @param [ Mongo::Cluster ] cluster The original cluster before this context was used.
       # @param [ Mongoid::PersistenceContext ] original_context The original persistence
       #   context that was set before this context was used.
-      #
-      # @since 6.0.0
       def clear(object, cluster = nil, original_context = nil)
         if context = get(object)
-          context.client.close unless (context.cluster.equal?(cluster) || cluster.nil?)
+          unless cluster.nil? || context.cluster.equal?(cluster)
+            context.client.close
+          end
         end
       ensure
         Thread.current["[mongoid][#{object.object_id}]:context"] = original_context

data/lib/mongoid/positional.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
 
   # This module is responsible for taking update selectors and switching out
   # the indexes for the $ positional operator where appropriate.
-  #
-  # @since 4.0.0
   module Positional
 
     # Takes the provided selector and atomic operations and replaces the
@@ -33,8 +30,6 @@ module Mongoid
     # @param [ Hash ] processed The processed update operations.
     #
     # @return [ Hash ] The new operations.
-    #
-    # @since 3.1.0
     def positionally(selector, operations, processed = {})
       if selector.size == 1 || selector.values.any? { |val| val.nil? }
         return operations

data/lib/mongoid/query_cache.rb

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
 
   # A cache of database queries on a per-request basis.
-  #
-  # @since 4.0.0
   module QueryCache
-    class << self
+    # @api private
+    LEGACY_WARNING = <<~DOC
+      You are using the legacy Mongoid query cache which has known issues.
+      Please upgrade the `mongo' gem to at least 2.14.0 to use the improved driver query cache.
+      Refer to: https://docs.mongodb.com/mongoid/current/tutorials/mongoid-queries/#the-improved-driver-query-cache
+    DOC
 
+    class << self
       # Get the cached queries.
       #
       # @example Get the cached queries from the current thread.
       #   QueryCache.cache_table
       #
       # @return [ Hash ] The hash of cached queries.
-      #
-      # @since 4.0.0
       # @api private
       def cache_table
         if defined?(Mongo::QueryCache)
@@ -32,8 +33,6 @@ module Mongoid
       #   QueryCache.clear_cache
       #
       # @return [ nil ] Always nil.
-      #
-      # @since 4.0.0
       def clear_cache
         if defined?(Mongo::QueryCache)
           Mongo::QueryCache.clear
@@ -48,8 +47,6 @@ module Mongoid
       #   QueryCache.enabled = true
       #
       # @param [ true, false ] value The enabled value.
-      #
-      # @since 4.0.0
       def enabled=(value)
         if defined?(Mongo::QueryCache)
           Mongo::QueryCache.enabled = value
@@ -64,8 +61,6 @@ module Mongoid
       #   QueryCache.enabled?
       #
       # @return [ true, false ] If the cache is enabled.
-      #
-      # @since 4.0.0
       def enabled?
         if defined?(Mongo::QueryCache)
           Mongo::QueryCache.enabled?
@@ -80,12 +75,14 @@ module Mongoid
       #   QueryCache.cache { collection.find }
       #
       # @return [ Object ] The result of the block.
-      #
-      # @since 4.0.0
       def cache(&block)
         if defined?(Mongo::QueryCache)
           Mongo::QueryCache.cache(&block)
         else
+          @legacy_query_cache_warned ||= begin
+            Mongoid.logger.warn(LEGACY_WARNING)
+            true
+          end
           enabled = QueryCache.enabled?
           QueryCache.enabled = true
           begin
@@ -122,8 +119,6 @@ module Mongoid
     else
       # The middleware to be added to a rack application in order to activate the
       # query cache.
-      #
-      # @since 4.0.0
       class Middleware
 
         # Instantiate the middleware.
@@ -132,8 +127,6 @@ module Mongoid
         #   Middleware.new(app)
         #
         # @param [ Object ] app The rack application stack.
-        #
-        # @since 4.0.0
         def initialize(app)
           @app = app
         end
@@ -146,8 +139,6 @@ module Mongoid
         # @param [ Object ] env The environment.
         #
         # @return [ Object ] The result of the call.
-        #
-        # @since 4.0.0
         def call(env)
           QueryCache.cache do
             @app.call(env)
@@ -160,8 +151,6 @@ module Mongoid
 
     # A Cursor that attempts to load documents from memory first before hitting
     # the database if the same query has already been executed.
-    #
-    # @since 5.0.0
     # @deprecated This class is only used with driver versions 2.13 and lower.
     class CachedCursor < Mongo::Cursor
 
@@ -172,8 +161,6 @@ module Mongoid
       #   cursor.each do |doc|
       #     # ...
       #   end
-      #
-      # @since 5.0.0
       def each
         if @cached_documents
           @cached_documents.each do |doc|
@@ -190,8 +177,6 @@ module Mongoid
       #   cursor.inspect
       #
       # @return [ String ] A string representation of a +Cursor+ instance.
-      #
-      # @since 2.0.0
       def inspect
         "#<Mongoid::QueryCache::CachedCursor:0x#{object_id} @view=#{@view.inspect}>"
       end
@@ -211,8 +196,6 @@ module Mongoid
 
     # Included to add behavior for clearing out the query cache on certain
     # operations.
-    #
-    # @since 4.0.0
     # @deprecated This module is only used with driver versions 2.13 and lower.
     module Base
 
@@ -231,8 +214,6 @@ module Mongoid
 
     # Contains enhancements to the Mongo::Collection::View in order to get a
     # cached cursor or a regular cursor on iteration.
-    #
-    # @since 5.0.0
     # @deprecated This module is only used with driver versions 2.13 and lower.
     module View
       extend ActiveSupport::Concern
@@ -256,8 +237,6 @@ module Mongoid
       #   view.each do |doc|
       #     # ...
       #   end
-      #
-      # @since 5.0.0
       def each
         if system_collection? || !QueryCache.enabled? || (respond_to?(:write?, true) && write?)
           super
@@ -311,8 +290,6 @@ module Mongoid
     end
 
     # Adds behavior to the query cache for collections.
-    #
-    # @since 5.0.0
     # @deprecated This module is only used with driver versions 2.13 and lower.
     module Collection
       extend ActiveSupport::Concern