mongoid 7.3.5 → 7.4.0

data/lib/mongoid/attributes/projector.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Attributes

data/lib/mongoid/attributes/readonly.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Attributes
@@ -22,8 +21,6 @@ module Mongoid
       #
       # @return [ true, false ] If the document is new, or if the field is not
       #   readonly.
-      #
-      # @since 3.0.0
       def attribute_writable?(name)
         new_record? || (!readonly_attributes.include?(name) && _loaded?(name))
       end
@@ -65,8 +62,6 @@ module Mongoid
         #   end
         #
         # @param [ Array<Symbol> ] names The names of the fields.
-        #
-        # @since 3.0.0
         def attr_readonly(*names)
           names.each do |name|
             readonly_attributes << database_field_name(name)

data/lib/mongoid/attributes.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "active_model/attribute_methods"
 require "mongoid/attributes/dynamic"
@@ -29,8 +28,6 @@ module Mongoid
     # @param [ String, Symbol ] name The name of the attribute.
     #
     # @return [ true, false ] True if present, false if not.
-    #
-    # @since 1.0.0
     def attribute_present?(name)
       attribute = read_raw_attribute(name)
       !attribute.blank? || attribute == false
@@ -44,8 +41,6 @@ module Mongoid
     #   document.attributes_before_type_cast
     #
     # @return [ Hash ] The uncast attributes.
-    #
-    # @since 3.1.0
     def attributes_before_type_cast
       @attributes_before_type_cast ||= {}
     end
@@ -58,8 +53,6 @@ module Mongoid
     # @param [ String, Symbol ] name The name of the attribute.
     #
     # @return [ true, false ] If the key is present in the attributes.
-    #
-    # @since 3.0.0
     def has_attribute?(name)
       attributes.key?(name.to_s)
     end
@@ -74,8 +67,6 @@ module Mongoid
     #
     # @return [ true, false ] If the key is present in the
     #   attributes_before_type_cast.
-    #
-    # @since 3.1.0
     def has_attribute_before_type_cast?(name)
       attributes_before_type_cast.key?(name.to_s)
     end
@@ -92,8 +83,6 @@ module Mongoid
     # @param [ String, Symbol ] name The name of the attribute to get.
     #
     # @return [ Object ] The value of the attribute.
-    #
-    # @since 1.0.0
     def read_attribute(name)
       field = fields[name.to_s]
       raw = read_raw_attribute(name)
@@ -112,8 +101,6 @@ module Mongoid
     #
     # @return [ Object ] The value of the attribute before type cast, if
     #   available. Otherwise, the value of the attribute.
-    #
-    # @since 3.1.0
     def read_attribute_before_type_cast(name)
       attr = name.to_s
       if attributes_before_type_cast.key?(attr)
@@ -133,8 +120,6 @@ module Mongoid
     #
     # @raise [ Errors::ReadonlyAttribute ] If the field cannot be removed due
     #   to being flagged as reaodnly.
-    #
-    # @since 1.0.0
     def remove_attribute(name)
       as_writable_attribute!(name) do |access|
         _assigning do
@@ -157,8 +142,6 @@ module Mongoid
     #
     # @param [ String, Symbol ] name The name of the attribute to update.
     # @param [ Object ] value The value to set for the attribute.
-    #
-    # @since 1.0.0
     def write_attribute(name, value)
       field_name = database_field_name(name)
 
@@ -201,8 +184,6 @@ module Mongoid
     #   person.assign_attributes({ :title => "Mr." }, :as => :admin)
     #
     # @param [ Hash ] attrs The new attributes to set.
-    #
-    # @since 2.2.1
     def assign_attributes(attrs = nil)
       _assigning do
         process_attributes(attrs)
@@ -220,8 +201,6 @@ module Mongoid
     #   person.attributes = { :title => "Mr." }
     #
     # @param [ Hash ] attrs The new attributes to set.
-    #
-    # @since 1.0.0
     def write_attributes(attrs = nil)
       assign_attributes(attrs)
     end
@@ -236,8 +215,6 @@ module Mongoid
     # @param [ String ] name The name of the attribute.
     #
     # @return [ true, false ] If the attribute is missing.
-    #
-    # @since 4.0.0
     def attribute_missing?(name)
       !Projector.new(__selected_fields).attribute_or_path_allowed?(name)
     end
@@ -248,8 +225,6 @@ module Mongoid
     #   document.typed_attributes
     #
     # @return [ Object ] The hash with keys and values of the type-casted attributes.
-    #
-    # @since 6.1.0
     def typed_attributes
       attribute_names.map { |name| [name, send(name)] }.to_h
     end
@@ -264,8 +239,6 @@ module Mongoid
     #   model.hash_dot_syntax?
     #
     # @return [ true, false ] If the string contains a "."
-    #
-    # @since 3.0.15
     def hash_dot_syntax?(string)
       string.include?(".")
     end
@@ -279,8 +252,6 @@ module Mongoid
     # @param [ Object ] value The uncast value.
     #
     # @return [ Object ] The cast value.
-    #
-    # @since 1.0.0
     def typed_value_for(key, value)
       fields.key?(key) ? fields[key].mongoize(value) : value.mongoize
     end
@@ -316,8 +287,6 @@ module Mongoid
       #
       # @param [ Symbol ] name The new name.
       # @param [ Symbol ] original The original name.
-      #
-      # @since 2.3.0
       def alias_attribute(name, original)
         aliased_fields[name.to_s] = original.to_s
 
@@ -368,8 +337,6 @@ module Mongoid
     #
     # @param [ String, Symbol ] field_name The name of the field.
     # @param [ Object ] value The value to be validated.
-    #
-    # @since 3.0.10
     def validate_attribute_value(field_name, value)
       return if value.nil?
       field = fields[field_name]

data/lib/mongoid/cacheable.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
 
   # Encapsulates behavior around caching.
-  #
-  # @since 6.0.0
   module Cacheable
     extend ActiveSupport::Concern
 
@@ -21,14 +18,12 @@ module Mongoid
     # If not             - will append /id-updated_at.to_s(cache_timestamp_format)
     # Without updated_at - will append /id
     #
-    # This is usually called insode a cache() block
+    # This is usually called inside a cache() block
     #
     # @example Returns the cache key
     #   document.cache_key
     #
     # @return [ String ] the string with or without updated_at
-    #
-    # @since 2.4.0
     def cache_key
       return "#{model_key}/new" if new_record?
       return "#{model_key}/#{_id}-#{updated_at.utc.to_s(cache_timestamp_format)}" if do_or_do_not(:updated_at)

data/lib/mongoid/changeable.rb

@@ -1,11 +1,8 @@
 # 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 +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
@@ -27,20 +22,15 @@ module Mongoid
     #   model.changed?
     #
     # @return [ true, false ] If the document is changed.
-    #
-    # @since 2.4.0
     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
     def children_changed?
       _children.any?(&:changed?)
     end
@@ -51,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
@@ -63,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|
@@ -81,8 +67,6 @@ module Mongoid
     #
     # @example Move the changes to previous.
     #   person.move_changes
-    #
-    # @since 2.1.0
     def move_changes
       @previous_changes = changes
       Atomic::UPDATES.each do |update|
@@ -95,10 +79,8 @@ module Mongoid
     #
     # @example Handle post persistence.
     #   document.post_persist
-    #
-    # @since 3.0.0
     def post_persist
-      reset_persisted_children
+      reset_persisted_descendants
       move_changes
     end
 
@@ -108,21 +90,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
     def remove_change(name)
       changed_attributes.delete(name.to_s)
     end
@@ -136,8 +114,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|
@@ -165,8 +141,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)
@@ -180,8 +154,6 @@ module Mongoid
     # @param [ String ] attr The name of the attribute.
     #
     # @return [ true, false ] Whether the attribute has changed.
-    #
-    # @since 2.1.6
     def attribute_changed?(attr)
       attr = database_field_name(attr)
       return false unless changed_attributes.key?(attr)
@@ -196,8 +168,6 @@ module Mongoid
     # @param [ String ] attr The name of the attribute.
     #
     # @return [ true, false ] If the attribute differs.
-    #
-    # @since 3.0.0
     def attribute_changed_from_default?(attr)
       field = fields[attr]
       return false unless field
@@ -210,8 +180,6 @@ 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]
@@ -225,8 +193,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__
@@ -241,8 +207,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)
@@ -270,8 +234,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 +253,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,8 +268,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_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_changed?") do
@@ -325,8 +283,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
@@ -342,8 +298,6 @@ module Mongoid
       #
       # @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
@@ -359,8 +313,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 +328,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 +343,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,8 +358,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
@@ -427,8 +373,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,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Clients
@@ -20,8 +19,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]
@@ -38,8 +35,6 @@ module Mongoid
       #   found.
       #
       # @return [ Mongo::Client ] The default client.
-      #
-      # @since 3.0.0
       def default
         create_client(Mongoid.clients[:default])
       end
@@ -56,8 +51,6 @@ 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
         config = configuration.dup

data/lib/mongoid/clients/options.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Clients
@@ -19,8 +18,6 @@ module Mongoid
       # @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
       def with(options_or_context, &block)
         original_context = PersistenceContext.get(self)
         original_cluster = persistence_context.cluster
@@ -92,8 +89,6 @@ module Mongoid
         # @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
         def with(options, &block)
           original_context = PersistenceContext.get(self)
           original_cluster = persistence_context.cluster

data/lib/mongoid/clients/sessions.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Clients
@@ -7,8 +6,6 @@ module Mongoid
     # 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.
@@ -38,8 +35,6 @@ 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 = {})
         if Threaded.get_session
           raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting)
@@ -97,8 +92,6 @@ 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 = {})
           if Threaded.get_session
             raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting)

data/lib/mongoid/clients/storage_options.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Clients
@@ -48,8 +47,6 @@ module Mongoid
         # @option options [ String | Symbol ] :client The client name.
         #
         # @return [ Class ] The model class.
-        #
-        # @since 3.0.0
         def store_in(options)
           Validators::Storage.validate(self, options)
           storage_options.merge!(options)
@@ -59,8 +56,6 @@ module Mongoid
         #
         # @example Reset the store_in options
         #   Model.reset_storage_options!
-        #
-        # @since 4.0.0
         def reset_storage_options!
           self.storage_options = storage_options_defaults.dup
           PersistenceContext.clear(self)
@@ -72,8 +67,6 @@ module Mongoid
         #   Model.storage_options_defaults
         #
         # @return [ Hash ] Default storage options.
-        #
-        # @since 4.0.0
         def storage_options_defaults
           {
             collection: name.collectionize.to_sym,

data/lib/mongoid/clients/validators/storage.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Clients
@@ -10,8 +9,6 @@ module Mongoid
         extend self
 
         # The valid options for storage.
-        #
-        # @since 3.0.0
         VALID_OPTIONS = [ :collection, :database, :client ].freeze
 
         # Validate the options provided to :store_in.
@@ -21,8 +18,6 @@ module Mongoid
         #
         # @param [ Class ] klass The model class.
         # @param [ Hash, String, Symbol ] options The provided options.
-        #
-        # @since 3.0.0
         def validate(klass, options)
           valid_keys?(options) or raise Errors::InvalidStorageOptions.new(klass, options)
           valid_parent?(klass) or raise Errors::InvalidStorageParent.new(klass)
@@ -37,8 +32,6 @@ module Mongoid
         # @param [ Class ] klass
         #
         # @return [ true, false ] If the class is valid
-        #
-        # @since 4.0.0
         def valid_parent?(klass)
           !klass.superclass.include?(Mongoid::Document)
         end
@@ -53,8 +46,6 @@ module Mongoid
         # @param [ Hash ] options The options hash.
         #
         # @return [ true, false ] If all keys are valid.
-        #
-        # @since 3.0.0
         def valid_keys?(options)
           return false unless options.is_a?(::Hash)
           options.keys.all? do |key|

data/lib/mongoid/clients/validators.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/clients/validators/storage"

data/lib/mongoid/clients.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/clients/factory"
 require "mongoid/clients/validators"
@@ -22,8 +21,6 @@ module Mongoid
       #   Mongoid::Clients.clear
       #
       # @return [ Array ] The empty clients.
-      #
-      # @since 3.0.0
       def clear
         clients.clear
       end
@@ -34,8 +31,6 @@ module Mongoid
       #   Mongoid::Clients.default
       #
       # @return [ Mongo::Client ] The default client.
-      #
-      # @since 3.0.0
       def default
         with_name(:default)
       end
@@ -46,8 +41,6 @@ module Mongoid
       #   Mongoid::Clients.disconnect
       #
       # @return [ true ] True.
-      #
-      # @since 3.1.0
       def disconnect
         clients.values.each do |client|
           client.close
@@ -62,8 +55,6 @@ module Mongoid
       # @param [ String | Symbol ] name The name of the client.
       #
       # @return [ Mongo::Client ] The named client.
-      #
-      # @since 3.0.0
       def with_name(name)
         name_as_symbol = name.to_sym
         return clients[name_as_symbol] if clients[name_as_symbol]

data/lib/mongoid/composable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/changeable"
 require "mongoid/findable"
@@ -22,8 +21,6 @@ require "mongoid/validatable"
 module Mongoid
 
   # This module provides inclusions of all behavior in a Mongoid document.
-  #
-  # @since 4.0.0
   module Composable
     extend ActiveSupport::Concern
 
@@ -99,8 +96,6 @@ module Mongoid
     # separately.
     #
     # @return [ Array<Symbol> ] A list of reserved method names.
-    #
-    # @since 6.0.0
     RESERVED_METHOD_NAMES = [ :fields,
                               :aliased_fields,
                               :localized_fields,
@@ -123,8 +118,6 @@ module Mongoid
       #   Mongoid::Components.prohibited_methods
       #
       # @return [ Array<Symbol> ]
-      #
-      # @since 2.1.8
       def prohibited_methods
         @prohibited_methods ||= MODULES.flat_map do |mod|
           mod.instance_methods.map(&:to_sym)