mongoid 7.0.5 → 8.1.0

data/lib/mongoid/changeable.rb

@@ -1,9 +1,8 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
 
-  # Defines behaviour for dirty tracking.
-  #
-  # @since 4.0.0
+  # Defines behavior for dirty tracking.
   module Changeable
     extend ActiveSupport::Concern
 
@@ -13,8 +12,6 @@ module Mongoid
     #   model.changed
     #
     # @return [ Array<String> ] The changed attributes.
-    #
-    # @since 2.4.0
     def changed
       changed_attributes.keys.select { |attr| attribute_change(attr) }
     end
@@ -24,21 +21,16 @@ module Mongoid
     # @example Has the document changed?
     #   model.changed?
     #
-    # @return [ true, false ] If the document is changed.
-    #
-    # @since 2.4.0
+    # @return [ true | false ] If the document is changed.
     def changed?
       changes.values.any? { |val| val } || children_changed?
     end
 
     # Have any children (embedded documents) of this document changed?
     #
-    # @example Have any children changed?
-    #   model.children_changed?
+    # @note This intentionally only considers children and not descendants.
     #
-    # @return [ true, false ] If any children have changed.
-    #
-    # @since 2.4.1
+    # @return [ true | false ] If any children have changed.
     def children_changed?
       _children.any?(&:changed?)
     end
@@ -49,8 +41,6 @@ module Mongoid
     #   model.changed_attributes
     #
     # @return [ Hash<String, Object> ] The attribute changes.
-    #
-    # @since 2.4.0
     def changed_attributes
       @changed_attributes ||= {}
     end
@@ -61,8 +51,6 @@ module Mongoid
     #   model.changes
     #
     # @return [ Hash<String, Array<Object, Object> ] The changes.
-    #
-    # @since 2.4.0
     def changes
       _changes = {}
       changed.each do |attr|
@@ -74,15 +62,16 @@ module Mongoid
 
     # Call this method after save, so the changes can be properly switched.
     #
-    # This will unset the memoized children array, set new record to
+    # This will unset the memoized children array, set new record flag to
     # false, set the document as validated, and move the dirty changes.
     #
     # @example Move the changes to previous.
     #   person.move_changes
-    #
-    # @since 2.1.0
     def move_changes
+      @changes_before_last_save = @previous_changes
       @previous_changes = changes
+      @attributes_before_last_save = @previous_attributes
+      @previous_attributes = attributes.dup
       Atomic::UPDATES.each do |update|
         send(update).clear
       end
@@ -93,10 +82,9 @@ module Mongoid
     #
     # @example Handle post persistence.
     #   document.post_persist
-    #
-    # @since 3.0.0
     def post_persist
-      reset_persisted_children
+      reset_persisted_descendants
+      reset_attributes_before_type_cast
       move_changes
     end
 
@@ -106,21 +94,17 @@ module Mongoid
     #   model.previous_changes
     #
     # @return [ Hash<String, Array<Object, Object> ] The previous changes.
-    #
-    # @since 2.4.0
     def previous_changes
       @previous_changes ||= {}
     end
 
     # Remove a change from the dirty attributes hash. Used by the single field
-    # atomic updators.
+    # atomic updaters.
     #
     # @example Remove a flagged change.
     #   model.remove_change(:field)
     #
-    # @param [ Symbol, String ] name The name of the field.
-    #
-    # @since 2.1.0
+    # @param [ Symbol | String ] name The name of the field.
     def remove_change(name)
       changed_attributes.delete(name.to_s)
     end
@@ -134,8 +118,6 @@ module Mongoid
     #   person.setters # returns { "title" => "Madam" }
     #
     # @return [ Hash ] A +Hash+ of atomic setters.
-    #
-    # @since 2.0.0
     def setters
       mods = {}
       changes.each_pair do |name, changes|
@@ -153,8 +135,89 @@ module Mongoid
       mods
     end
 
+    # Returns the original value of an attribute before the last save.
+    #
+    # This method is useful in after callbacks to get the original value of
+    #   an attribute before the save that triggered the callbacks to run.
+    #
+    # @param [ Symbol | String ] attr The name of the attribute.
+    #
+    # @return [ Object ] Value of the attribute before the last save.
+    def attribute_before_last_save(attr)
+      attr = database_field_name(attr)
+      attributes_before_last_save[attr]
+    end
+
+    # Returns the change to an attribute during the last save.
+    #
+    # @param [ Symbol | String ] attr The name of the attribute.
+    #
+    # @return [ Array<Object> | nil ] If the attribute was changed, returns
+    #   an array containing the original value and the saved value, otherwise nil.
+    def saved_change_to_attribute(attr)
+      attr = database_field_name(attr)
+      previous_changes[attr]
+    end
+
+    # Returns whether this attribute changed during the last save.
+    #
+    # This method is useful in after callbacks, to see the change
+    #   in an attribute during the save that triggered the callbacks to run.
+    #
+    # @param [ String ] attr The name of the attribute.
+    # @param **kwargs The optional keyword arguments.
+    #
+    # @option **kwargs [ Object ] :from The object the attribute was changed from.
+    # @option **kwargs [ Object ] :to The object the attribute was changed to.
+    #
+    # @return [ true | false ] Whether the attribute has changed during the last save.
+    def saved_change_to_attribute?(attr, **kwargs)
+      changes = saved_change_to_attribute(attr)
+      return false unless changes.is_a?(Array)
+      if kwargs.key?(:from) && kwargs.key?(:to)
+        changes.first == kwargs[:from] && changes.last == kwargs[:to]
+      elsif kwargs.key?(:from)
+        changes.first == kwargs[:from]
+      elsif kwargs.key?(:to)
+        changes.last == kwargs[:to]
+      else
+        true
+      end
+    end
+
+    # Returns whether this attribute change the next time we save.
+    #
+    # This method is useful in validations and before callbacks to determine
+    #   if the next call to save will change a particular attribute.
+    #
+    # @param [ String ] attr The name of the attribute.
+    # @param **kwargs The optional keyword arguments.
+    #
+    # @option **kwargs [ Object ] :from The object the attribute was changed from.
+    # @option **kwargs [ Object ] :to The object the attribute was changed to.
+    #
+    # @return [ true | false ] Whether the attribute change the next time we save.
+    def will_save_change_to_attribute?(attr, **kwargs)
+      attribute_changed?(attr, **kwargs)
+    end
+
     private
 
+    # Get attributes of the document before the document was saved.
+    #
+    # @return [ Hash ] Previous attributes
+    def previous_attributes
+      @previous_attributes ||= {}
+    end
+
+    def changes_before_last_save
+      @changes_before_last_save ||= {}
+    end
+
+    def attributes_before_last_save
+      @attributes_before_last_save ||= {}
+    end
+
     # Get the old and new value for the provided attribute.
     #
     # @example Get the attribute change.
@@ -163,8 +226,6 @@ module Mongoid
     # @param [ String ] attr The name of the attribute.
     #
     # @return [ Array<Object> ] The old and new values.
-    #
-    # @since 2.1.0
     def attribute_change(attr)
       attr = database_field_name(attr)
       [changed_attributes[attr], attributes[attr]] if attribute_changed?(attr)
@@ -176,14 +237,24 @@ module Mongoid
     #   model.attribute_changed?("name")
     #
     # @param [ String ] attr The name of the attribute.
+    # @param **kwargs The optional keyword arguments.
     #
-    # @return [ true, false ] Whether the attribute has changed.
+    # @option **kwargs [ Object ] :from The object the attribute was changed from.
+    # @option **kwargs [ Object ] :to The object the attribute was changed to.
     #
-    # @since 2.1.6
-    def attribute_changed?(attr)
+    # @return [ true | false ] Whether the attribute has changed.
+    def attribute_changed?(attr, **kwargs)
       attr = database_field_name(attr)
       return false unless changed_attributes.key?(attr)
-      changed_attributes[attr] != attributes[attr]
+      return false if changed_attributes[attr] == attributes[attr]
+      if kwargs.key?(:from)
+        return false if changed_attributes[attr] != kwargs[:from]
+      end
+      if kwargs.key?(:to)
+        return false if attributes[attr] != kwargs[:to]
+      end
+
+      true
     end
 
     # Get whether or not the field has a different value from the default.
@@ -193,9 +264,7 @@ module Mongoid
     #
     # @param [ String ] attr The name of the attribute.
     #
-    # @return [ true, false ] If the attribute differs.
-    #
-    # @since 3.0.0
+    # @return [ true | false ] If the attribute differs.
     def attribute_changed_from_default?(attr)
       field = fields[attr]
       return false unless field
@@ -208,13 +277,30 @@ module Mongoid
     #   model.attribute_was("name")
     #
     # @param [ String ] attr The attribute name.
-    #
-    # @since 2.4.0
     def attribute_was(attr)
       attr = database_field_name(attr)
       attribute_changed?(attr) ? changed_attributes[attr] : attributes[attr]
     end
 
+    # Get the previous attribute value that was changed
+    # before the document was saved.
+    #
+    # It the document has not been saved yet, or was just loaded from database,
+    # this method returns nil for all attributes.
+    #
+    # @param [ String ] attr The attribute name.
+    #
+    # @return [ Object | nil ] Attribute value before the document was saved,
+    #   or nil if the document has not been saved yet.
+    def attribute_previously_was(attr)
+      attr = database_field_name(attr)
+      if previous_changes.key?(attr)
+        previous_changes[attr].first
+      else
+        previous_attributes[attr]
+      end
+    end
+
     # Flag an attribute as going to change.
     #
     # @example Flag the attribute.
@@ -223,8 +309,6 @@ module Mongoid
     # @param [ String ] attr The name of the attribute.
     #
     # @return [ Object ] The old value.
-    #
-    # @since 2.3.0
     def attribute_will_change!(attr)
       unless changed_attributes.key?(attr)
         changed_attributes[attr] = read_raw_attribute(attr).__deep_copy__
@@ -239,8 +323,6 @@ module Mongoid
     # @param [ String ] attr The name of the attribute.
     #
     # @return [ Object ] The old value.
-    #
-    # @since 2.4.0
     def reset_attribute!(attr)
       attr = database_field_name(attr)
       attributes[attr] = changed_attributes.delete(attr) if attribute_changed?(attr)
@@ -255,6 +337,10 @@ module Mongoid
       end
     end
 
+    def reset_attributes_before_type_cast
+      @attributes_before_type_cast = @attributes.dup
+    end
+
     module ClassMethods
 
       private
@@ -268,8 +354,6 @@ module Mongoid
       # @param [ String ] meth The name of the accessor.
       #
       # @return [ Module ] The fields module.
-      #
-      # @since 2.4.0
       def create_dirty_methods(name, meth)
         create_dirty_change_accessor(name, meth)
         create_dirty_change_check(name, meth)
@@ -289,8 +373,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_change_accessor(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_change") do
@@ -306,12 +388,13 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_change_check(name, meth)
         generated_methods.module_eval do
-          re_define_method("#{meth}_changed?") do
-            attribute_changed?(name)
+          re_define_method("#{meth}_changed?") do |**kwargs|
+            attribute_changed?(name, **kwargs)
+          end
+          re_define_method("will_save_change_to_#{meth}?") do |**kwargs|
+            will_save_change_to_attribute?(name, **kwargs)
           end
         end
       end
@@ -323,8 +406,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_default_change_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_changed_from_default?") do
@@ -333,20 +414,30 @@ module Mongoid
         end
       end
 
-      # Creates the dirty change previous value accessor.
+      # Creates the dirty change previous value accessors.
       #
       # @example Create the accessor.
       #   Model.create_dirty_previous_value_accessor("name", "alias")
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_previous_value_accessor(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_was") do
             attribute_was(name)
           end
+          re_define_method("#{meth}_previously_was") do
+            attribute_previously_was(name)
+          end
+          re_define_method("#{meth}_before_last_save") do
+            attribute_before_last_save(name)
+          end
+          re_define_method("saved_change_to_#{meth}") do
+            saved_change_to_attribute(name)
+          end
+          re_define_method("saved_change_to_#{meth}?") do |**kwargs|
+            saved_change_to_attribute?(name, **kwargs)
+          end
         end
       end
 
@@ -357,8 +448,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_change_flag(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_will_change!") do
@@ -374,8 +463,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_reset(name, meth)
         generated_methods.module_eval do
           re_define_method("reset_#{meth}!") do
@@ -391,8 +478,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 3.0.0
       def create_dirty_reset_to_default(name, meth)
         generated_methods.module_eval do
           re_define_method("reset_#{meth}_to_default!") do
@@ -408,8 +493,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 6.0.0
       def create_dirty_previously_changed?(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_previously_changed?") do
@@ -425,8 +508,6 @@ module Mongoid
       #
       # @param [ String ] name The attribute name.
       # @param [ String ] meth The name of the accessor.
-      #
-      # @since 6.0.0
       def create_dirty_previous_change(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_previous_change") do

data/lib/mongoid/clients/factory.rb

@@ -1,9 +1,10 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module Mongoid
   module Clients
     module Factory
       extend self
+      extend Loggable
 
       # Create a new client given the named configuration. If no name is
       # provided, return a new client with the default configuration. If a
@@ -11,15 +12,13 @@ module Mongoid
       # raised.
       #
       # @example Create the client.
-      #   Factory.create(:secondary)
+      #   Factory.create(:analytics)
       #
-      # @param [ String, Symbol ] name The named client configuration.
+      # @param [ String | Symbol ] name The named client configuration.
       #
       # @raise [ Errors::NoClientConfig ] If no config could be found.
       #
       # @return [ Mongo::Client ] The new client.
-      #
-      # @since 3.0.0
       def create(name = nil)
         return default unless name
         config = Mongoid.clients[name]
@@ -36,8 +35,6 @@ module Mongoid
       #   found.
       #
       # @return [ Mongo::Client ] The default client.
-      #
-      # @since 3.0.0
       def default
         create_client(Mongoid.clients[:default])
       end
@@ -54,26 +51,54 @@ module Mongoid
       # @param [ Hash ] configuration The client config.
       #
       # @return [ Mongo::Client ] The client.
-      #
-      # @since 3.0.0
       def create_client(configuration)
         raise Errors::NoClientsConfig.new unless configuration
-        if configuration[:uri]
-          Mongo::Client.new(configuration[:uri], options(configuration))
+        config = configuration.dup
+        uri = config.delete(:uri)
+        database = config.delete(:database)
+        hosts = config.delete(:hosts)
+        opts = config.delete(:options) || {}
+        unless config.empty?
+          default_logger.warn("Unknown config options detected: #{config}.")
+        end
+        if uri
+          Mongo::Client.new(uri, options(opts))
         else
           Mongo::Client.new(
-            configuration[:hosts],
-            options(configuration).merge(database: configuration[:database])
+            hosts,
+            options(opts).merge(database: database)
           )
         end
       end
 
-      def options(configuration)
-        config = configuration.dup
-        options = config.delete(:options) || {}
+      MONGOID_WRAPPING_LIBRARY = {
+        name: 'Mongoid',
+        version: VERSION,
+      }.freeze
+
+      def driver_version
+        Mongo::VERSION.split('.')[0...2].map(&:to_i)
+      end
+
+      # Prepare options for Mongo::Client based on Mongoid client configuration.
+      #
+      # @param [ Hash ] opts Parameters from options section of Mongoid client configuration.
+      # @return [ Hash ] Options that should be passed to Mongo::Client constructor.
+      #
+      # @api private
+      def options(opts)
+        options = opts.dup
         options[:platform] = PLATFORM_DETAILS
         options[:app_name] = Mongoid::Config.app_name if Mongoid::Config.app_name
-        options.reject{ |k, v| k == :hosts }.to_hash.symbolize_keys!
+        if (driver_version <=> [2, 13]) >= 0
+          wrap_lib = if options[:wrapping_libraries]
+            [MONGOID_WRAPPING_LIBRARY] + options[:wrapping_libraries]
+          else
+            [MONGOID_WRAPPING_LIBRARY]
+          end
+          options[:wrapping_libraries] = wrap_lib
+        end
+        options.reject{ |k, _v| k == :hosts }.to_hash.symbolize_keys!
       end
     end
   end

data/lib/mongoid/clients/options.rb

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Clients
     module Options
@@ -7,18 +8,16 @@ module Mongoid
       # Change the persistence context for this object during the block.
       #
       # @example Save the current document to a different collection.
-      #   model.with(collection: "secondary") do |m|
+      #   model.with(collection: "bands") do |m|
       #     m.save
       #   end
       #
-      # @param [ Hash, Mongoid::PersistenceContext ] options_or_context
+      # @param [ Hash | Mongoid::PersistenceContext ] options_or_context
       #   The storage options or a persistence context.
       #
-      # @option options [ String, Symbol ] :collection The collection name.
-      # @option options [ String, Symbol ] :database The database name.
-      # @option options [ String, Symbol ] :client The client name.
-      #
-      # @since 6.0.0
+      # @option options [ String | Symbol ] :collection The collection name.
+      # @option options [ String | Symbol ] :database The database name.
+      # @option options [ String | Symbol ] :client The client name.
       def with(options_or_context, &block)
         original_context = PersistenceContext.get(self)
         original_cluster = persistence_context.cluster
@@ -46,6 +45,10 @@ module Mongoid
             PersistenceContext.new(self.class)
       end
 
+      def persistence_context?
+        !!(PersistenceContext.get(self) || PersistenceContext.get(self.class))
+      end
+
       private
 
       def set_persistence_context(options_or_context)
@@ -81,17 +84,15 @@ module Mongoid
         # Change the persistence context for this class during the block.
         #
         # @example Save the current document to a different collection.
-        #   Model.with(collection: "secondary") do |m|
+        #   Model.with(collection: "bands") do |m|
         #     m.create
         #   end
         #
         # @param [ Hash ] options The storage options.
         #
-        # @option options [ String, Symbol ] :collection The collection name.
-        # @option options [ String, Symbol ] :database The database name.
-        # @option options [ String, Symbol ] :client The client name.
-        #
-        # @since 6.0.0
+        # @option options [ String | Symbol ] :collection The collection name.
+        # @option options [ String | Symbol ] :database The database name.
+        # @option options [ String | Symbol ] :client The client name.
         def with(options, &block)
           original_context = PersistenceContext.get(self)
           original_cluster = persistence_context.cluster

data/lib/mongoid/clients/sessions.rb

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Clients
 
     # Encapsulates behavior for getting a session from the client of a model class or instance,
     # setting the session on the current thread, and yielding to a block.
     # The session will be closed after the block completes or raises an error.
-    #
-    # @since 6.4.0
     module Sessions
 
       # Execute a block within the context of a session.
@@ -35,15 +35,15 @@ module Mongoid
       # @return [ Object ] The result of calling the block.
       #
       # @yieldparam [ Mongo::Session ] The session being used for the block.
-      #
-      # @since 6.4.0
       def with_session(options = {})
-        raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting) if Threaded.get_session
+        if Threaded.get_session
+          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting)
+        end
         session = persistence_context.client.start_session(options)
         Threaded.set_session(session)
         yield(session)
       rescue Mongo::Error::InvalidSession => ex
-        if ex.message == Mongo::Session::SESSIONS_NOT_SUPPORTED
+        if Mongo::Error::SessionsNotSupported === ex
           raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
         end
         raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
@@ -86,15 +86,15 @@ module Mongoid
         # @return [ Object ] The result of calling the block.
         #
         # @yieldparam [ Mongo::Session ] The session being used for the block.
-        #
-        # @since 6.4.0
         def with_session(options = {})
-          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting) if Threaded.get_session
+          if Threaded.get_session
+            raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting)
+          end
           session = persistence_context.client.start_session(options)
           Threaded.set_session(session)
           yield(session)
         rescue Mongo::Error::InvalidSession => ex
-          if ex.message == Mongo::Session::SESSIONS_NOT_SUPPORTED
+          if Mongo::Error::SessionsNotSupported === ex
             raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
           end
           raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)