mongoid 7.2.1 → 9.0.0

data/lib/mongoid/changeable.rb

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
-
   # Defines behavior for dirty tracking.
-  #
-  # @since 4.0.0
   module Changeable
     extend ActiveSupport::Concern
 
@@ -15,8 +11,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
@@ -26,21 +20,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
@@ -51,8 +40,6 @@ module Mongoid
     #   model.changed_attributes
     #
     # @return [ Hash<String, Object> ] The attribute changes.
-    #
-    # @since 2.4.0
     def changed_attributes
       @changed_attributes ||= {}
     end
@@ -63,31 +50,26 @@ module Mongoid
     #   model.changes
     #
     # @return [ Hash<String, Array<Object, Object> ] The changes.
-    #
-    # @since 2.4.0
     def changes
-      _changes = {}
-      changed.each do |attr|
+      changed.each_with_object({}) do |attr, changes|
         change = attribute_change(attr)
-        _changes[attr] = change if change
-      end
-      _changes.with_indifferent_access
+        changes[attr] = change if change
+      end.with_indifferent_access
     end
 
     # 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
-      Atomic::UPDATES.each do |update|
-        send(update).clear
-      end
+      @attributes_before_last_save = @previous_attributes
+      @previous_attributes = attributes.dup
+      reset_atomic_updates!
       changed_attributes.clear
     end
 
@@ -95,10 +77,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
 
@@ -108,21 +89,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
@@ -136,27 +113,101 @@ 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|
-        if changes
-          old, new = changes
-          field = fields[name]
-          key = atomic_attribute_name(name)
-          if field && field.resizable?
-            field.add_atomic_changes(self, name, key, mods, new, old)
-          else
-            mods[key] = new unless atomic_unsets.include?(key)
-          end
+        next unless changes
+
+        old, new = changes
+        field = fields[name]
+        key = atomic_attribute_name(name)
+        if field&.resizable?
+          field.add_atomic_changes(self, name, key, mods, new, old)
+        else
+          mods[key] = new unless atomic_unsets.include?(key)
         end
       end
       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 [ Object ] from The object the attribute was changed from (optional).
+    # @param [ Object ] to The object the attribute was changed to (optional).
+    #
+    # @return [ true | false ] Whether the attribute has changed during the last save.
+    def saved_change_to_attribute?(attr, from: Utils::PLACEHOLDER, to: Utils::PLACEHOLDER)
+      changes = saved_change_to_attribute(attr)
+      return false unless changes.is_a?(Array)
+
+      return true if Utils.placeholder?(from) && Utils.placeholder?(to)
+      return changes.first == from if Utils.placeholder?(to)
+      return changes.last == to if Utils.placeholder?(from)
+
+      changes.first == from && changes.last == to
+    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.
@@ -165,27 +216,52 @@ 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)
+      [ changed_attributes[attr], attributes[attr] ] if attribute_changed?(attr)
+    end
+
+    # A class for representing the default value that an attribute was changed
+    # from or to.
+    #
+    # @api private
+    class Anything
+      # `Anything` objects are always equal to everything. This simplifies
+      # the logic for asking whether an attribute has changed or not. If the
+      # `from` or `to` value is a `Anything` (because it was not
+      # explicitly given), any comparison with it will suggest the value has
+      # not changed.
+      #
+      # @param [ Object ] _other The object being compared with this object.
+      #
+      # @return [ true ] Always returns true.
+      def ==(_other)
+        true
+      end
     end
 
+    # a singleton object to represent an optional `to` or `from` value
+    # that was not explicitly provided to #attribute_changed?
+    ATTRIBUTE_UNCHANGED = Anything.new
+
     # Determine if a specific attribute has changed.
     #
     # @example Has the attribute changed?
     #   model.attribute_changed?("name")
     #
     # @param [ String ] attr The name of the attribute.
+    # @param [ Object ] from The object the attribute was changed from (optional).
+    # @param [ Object ] to The object the attribute was changed to (optional).
     #
-    # @return [ true, false ] Whether the attribute has changed.
-    #
-    # @since 2.1.6
-    def attribute_changed?(attr)
+    # @return [ true | false ] Whether the attribute has changed.
+    def attribute_changed?(attr, from: ATTRIBUTE_UNCHANGED, to: ATTRIBUTE_UNCHANGED)
       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]
+      return false if from != changed_attributes[attr]
+      return false if to != attributes[attr]
+
+      true
     end
 
     # Get whether or not the field has a different value from the default.
@@ -195,12 +271,10 @@ 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
+      return false unless (field = fields[attr])
+
       attributes[attr] != field.eval_default(self)
     end
 
@@ -210,13 +284,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.
@@ -225,12 +316,10 @@ 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__
-      end
+      return if changed_attributes.key?(attr)
+
+      changed_attributes[attr] = read_raw_attribute(attr).__deep_copy__
     end
 
     # Set the attribute back to its old value.
@@ -241,8 +330,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)
@@ -250,15 +337,19 @@ module Mongoid
 
     def reset_attribute_to_default!(attr)
       attr = database_field_name(attr)
-      if field = fields[attr]
+      if (field = fields[attr])
         __send__("#{attr}=", field.eval_default(self))
       else
         __send__("#{attr}=", nil)
       end
     end
 
-    module ClassMethods
+    def reset_attributes_before_type_cast
+      @attributes_before_type_cast = @attributes.dup
+    end
 
+    # Class-level methods for changeable objects.
+    module ClassMethods
       private
 
       # Generate all the dirty methods needed for the attribute.
@@ -270,8 +361,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)
@@ -291,8 +380,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
@@ -308,12 +395,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
@@ -325,8 +413,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
@@ -335,20 +421,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
 
@@ -359,8 +455,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
@@ -376,8 +470,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
@@ -393,8 +485,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
@@ -410,12 +500,10 @@ 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
-            previous_changes.keys.include?(name)
+            previous_changes.key?(name)
           end
         end
       end
@@ -427,8 +515,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,10 +1,13 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Clients
+
+    # Factory used to create database 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
@@ -19,8 +22,6 @@ module Mongoid
       # @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]
@@ -37,8 +38,6 @@ module Mongoid
       #   found.
       #
       # @return [ Mongo::Client ] The default client.
-      #
-      # @since 3.0.0
       def default
         create_client(Mongoid.clients[:default])
       end
@@ -55,20 +54,59 @@ 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) || Mongo::URI.get(uri).database
+        hosts = config.delete(:hosts)
+        opts = config.delete(:options) || {}
+        if opts.key?(:auto_encryption_options)
+          opts[:auto_encryption_options] = build_auto_encryption_options(opts, database)
+        end
+        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
 
+      # Build auto encryption options for the client based on the options
+      # provided in the Mongoid client configuration and the encryption
+      # schema map for the database.
+      #
+      # @param [ Hash ] opts Options from the Mongoid client configuration.
+      # @param [ String ] database Database name to use for encryption schema map.
+      #
+      # @return [ Hash | nil ] Auto encryption options for the client.
+      #
+      # @api private
+      def build_auto_encryption_options(opts, database)
+        return nil unless opts[:auto_encryption_options]
+
+        opts[:auto_encryption_options].dup.tap do |auto_encryption_options|
+          if auto_encryption_options.key?(:schema_map)
+            default_logger.warn(
+              'The :schema_map is configured in the :auto_encryption_options for the client;' +
+              ' encryption setting in Mongoid documents will be ignored.'
+            )
+          else
+            auto_encryption_options[:schema_map] = Mongoid.config.encryption_schema_map(database)
+          end
+          if auto_encryption_options.key?(:key_vault_client)
+            auto_encryption_options[:key_vault_client] = Mongoid.client(
+              auto_encryption_options[:key_vault_client]
+            )
+          end
+        end
+      end
+
       MONGOID_WRAPPING_LIBRARY = {
         name: 'Mongoid',
         version: VERSION,
@@ -78,9 +116,14 @@ module Mongoid
         Mongo::VERSION.split('.')[0...2].map(&:to_i)
       end
 
-      def options(configuration)
-        config = configuration.dup
-        options = config.delete(:options) || {}
+      # 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
         if (driver_version <=> [2, 13]) >= 0
@@ -91,7 +134,7 @@ module Mongoid
           end
           options[:wrapping_libraries] = wrap_lib
         end
-        options.reject{ |k, v| k == :hosts }.to_hash.symbolize_keys!
+        options.reject{ |k, _v| k == :hosts }.to_hash.symbolize_keys!
       end
     end
   end