mongoid 6.4.8 → 7.5.4

data/lib/mongoid/findable.rb

@@ -1,18 +1,20 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
 
   # This module defines the finder methods that hang off the document at the
   # class level.
-  #
-  # @since 4.0.0
   module Findable
-    extend Mongoid::Criteria::Queryable::Forwardable
+    extend Forwardable
 
-    select_with :with_default_scope
+    def_delegators :with_default_scope, *(
+      Criteria::Queryable::Selectable.forwardables +
+      Criteria::Queryable::Optional.forwardables
+    )
 
     # These are methods defined on the criteria that should also be accessible
     # directly from the class level.
-    delegate \
+    def_delegators :with_default_scope,
       :aggregates,
       :avg,
       :create_with,
@@ -39,9 +41,12 @@ module Mongoid
       :pluck,
       :read,
       :sum,
+      :take,
+      :take!,
+      :tally,
       :text_search,
       :update,
-      :update_all, to: :with_default_scope
+      :update_all,
 
     # Returns a count of records in the database.
     # If you want to specify conditions use where.
@@ -55,6 +60,16 @@ module Mongoid
       with_default_scope.count
     end
 
+    # Returns an estimated count of records in the database.
+    #
+    # @example Get the count of matching documents.
+    #   Person.estimated_count
+    #
+    # @return [ Integer ] The number of matching documents.
+    def estimated_count
+      with_default_scope.estimated_count
+    end
+
     # Returns true if count is zero
     #
     # @example Are there no saved documents for this model?
@@ -76,20 +91,46 @@ module Mongoid
       with_default_scope.exists?
     end
 
-    # Find a +Document+ in several different ways.
-    #
-    # If a +String+ is provided, it will be assumed that it is a
-    # representation of a Mongo::ObjectID and will attempt to find a single
-    # +Document+ based on that id. If a +Symbol+ and +Hash+ is provided then
-    # it will attempt to find either a single +Document+ or multiples based
-    # on the conditions provided and the first parameter.
-    #
-    # @example Find a single document by an id.
-    #   Person.find(BSON::ObjectId)
-    #
-    # @param [ Array ] args An assortment of finder options.
-    #
-    # @return [ Document, nil, Criteria ] A document or matching documents.
+    # Finds a +Document+ or multiple documents by their _id values.
+    #
+    # If a single non-Array argument is given, this argument is interpreted
+    # as the _id value of a document to find. If there is a matching document
+    # in the database, this document is returned; otherwise, if the
+    # +raise_not_found_error+ Mongoid configuration option is truthy
+    # (which is the default), +Errors::DocumentNotFound+ is raised, and if
+    # +raise_not_found_error+ is falsy, +find+ returns +nil+.
+    #
+    # If multiple arguments are given, or an Array argument is given, the
+    # array is flattened and each array element is interpreted as the _id
+    # value of the document to find. Mongoid then attempts to retrieve all
+    # documents with the provided _id values. The return value is an array
+    # of found documents. Each document appears one time in the returned array,
+    # even if its _id is given multiple times in the argument to +find+.
+    # If the +raise_not_found_error+ Mongoid configuration option is truthy,
+    # +Errors::DocumentNotFound+ exception is raised if any of the specified
+    # _ids were not found in the database. If the ++raise_not_found_error+
+    # Mongoid configuration option is falsy, only those documents which are
+    # found are returned; if no documents are found, the return value is an
+    # empty array.
+    #
+    # Note that MongoDB does not allow the _id field to be an array.
+    #
+    # The argument undergoes customary Mongoid type conversions based on
+    # the type declared for the _id field. By default the _id field is a
+    # +BSON::ObjectId+; this allows strings to be passed to +find+ and the
+    # strings will be transparently converted to +BSON::ObjectId+ instances
+    # during query construction.
+    #
+    # The +find+ method takes into account the default scope defined on the
+    # model class, if any.
+    #
+    # @param [ Object | Array<Object> ] args The _id values to find or an
+    #   array thereof.
+    #
+    # @return [ Document | Array<Document> | nil ] A document or matching documents.
+    #
+    # @raise Errors::DocumentNotFound If not all documents are found and
+    #   the +raise_not_found_error+ Mongoid configuration option is truthy.
     def find(*args)
       with_default_scope.find(*args)
     end
@@ -108,8 +149,6 @@ module Mongoid
     # and Mongoid.raise_not_found_error is true.
     #
     # @return [ Document, nil ] A matching document.
-    #
-    # @since 3.0.0
     def find_by(attrs = {})
       result = where(attrs).find_first
       if result.nil? && Mongoid.raise_not_found_error
@@ -143,9 +182,15 @@ module Mongoid
     # @example Find the first document.
     #   Person.first
     #
+    # @param [ Integer | Hash ] limit_or_opts The number of documents to
+    #   return, or a hash of options.
+    #
+    # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
+    #   Don't apply a sort on _id if no other sort is defined on the criteria.
+    #
     # @return [ Document ] The first matching document.
-    def first
-      with_default_scope.first
+    def first(limit_or_opts = nil)
+      with_default_scope.first(limit_or_opts)
     end
     alias :one :first
 
@@ -154,9 +199,15 @@ module Mongoid
     # @example Find the last document.
     #   Person.last
     #
+    # @param [ Integer | Hash ] limit_or_opts The number of documents to
+    #   return, or a hash of options.
+    #
+    # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
+    #   Don't apply a sort on _id if no other sort is defined on the criteria.
+    #
     # @return [ Document ] The last matching document.
-    def last
-      with_default_scope.last
+    def last(limit_or_opts = nil)
+      with_default_scope.last(limit_or_opts)
     end
   end
 end

data/lib/mongoid/indexable/specification.rb

@@ -1,16 +1,13 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Indexable
 
-    # Encapsulates behaviour around an index specification.
-    #
-    # @since 4.0.0
+    # Encapsulates behavior around an index specification.
     class Specification
 
       # The mappings of nice Ruby-style names to the corresponding driver
       # option name.
-      #
-      # @since 4.0.0
       MAPPINGS = {
         expire_after_seconds: :expire_after
       }
@@ -31,8 +28,6 @@ module Mongoid
       # @param [ Specification ] other The spec to compare against.
       #
       # @return [ true, false ] If the specs are equal.
-      #
-      # @since 4.0.0
       def ==(other)
         fields == other.fields && key == other.key
       end
@@ -45,8 +40,6 @@ module Mongoid
       # @param [ Class ] klass The class the index is defined on.
       # @param [ Hash ] key The hash of name/direction pairs.
       # @param [ Hash ] opts the index options.
-      #
-      # @since 4.0.0
       def initialize(klass, key, opts = nil)
         options = opts || {}
         Validators::Options.validate(klass, key, options)
@@ -62,8 +55,6 @@ module Mongoid
       #   specification.name
       #
       # @return [ String ] name The index name.
-      #
-      # @since 5.0.2
       def name
         @name ||= key.reduce([]) do |n, (k,v)|
           n << "#{k}_#{v}"
@@ -82,8 +73,6 @@ module Mongoid
       # @param [ Hash ] key The index key(s).
       #
       # @return [ Hash ] The normalized specification.
-      #
-      # @since 4.0.0
       def normalize_key(key)
         normalized = {}
         key.each_pair do |name, direction|
@@ -102,8 +91,6 @@ module Mongoid
       # @param [ Hash ] opts The index options.
       #
       # @return [ Hash ] The normalized options.
-      #
-      # @since 4.0.0
       def normalize_options(opts)
         options = {}
         opts.each_pair do |option, value|

data/lib/mongoid/indexable/validators/options.rb

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Indexable
     module Validators
@@ -51,8 +52,6 @@ module Mongoid
         # @param [ Hash ] options The index options.
         #
         # @raise [ Errors::InvalidIndex ] If validation failed.
-        #
-        # @since 3.0.0
         def validate(klass, spec, options)
           validate_spec(klass, spec, options)
           validate_options(klass, spec, options)
@@ -72,8 +71,6 @@ module Mongoid
         # @param [ Hash ] options The index options.
         #
         # @raise [ Errors::InvalidIndex ] If validation failed.
-        #
-        # @since 3.0.0
         def validate_options(klass, spec, options)
           options.each_pair do |name, value|
             unless VALID_OPTIONS.include?(name)
@@ -94,8 +91,6 @@ module Mongoid
         # @param [ Hash ] options The index options.
         #
         # @raise [ Errors::InvalidIndex ] If validation failed.
-        #
-        # @since 3.0.0
         def validate_spec(klass, spec, options)
           raise Errors::InvalidIndex.new(klass, spec, options) if !spec.is_a?(::Hash)
           spec.each_pair do |name, value|

data/lib/mongoid/indexable.rb

@@ -1,13 +1,12 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "mongoid/indexable/specification"
 require "mongoid/indexable/validators/options"
 require "ostruct"
 
 module Mongoid
 
-  # Encapsulates behaviour around defining indexes.
-  #
-  # @since 4.0.0
+  # Encapsulates behavior around defining indexes.
   module Indexable
     extend ActiveSupport::Concern
 
@@ -24,12 +23,13 @@ module Mongoid
       #   Person.create_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 1.0.0
       def create_indexes
         return unless index_specifications
+
+        default_options = {background: Config.background_indexing}
+
         index_specifications.each do |spec|
-          key, options = spec.key, spec.options
+          key, options = spec.key, default_options.merge(spec.options)
           if database = options[:database]
             with(database: database) do |klass|
               klass.collection.indexes(session: _session).create_one(key, options.except(:database))
@@ -47,8 +47,6 @@ module Mongoid
       #   Person.remove_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 3.0.0
       def remove_indexes
         indexed_database_names.each do |database|
           with(database: database) do |klass|
@@ -74,11 +72,9 @@ module Mongoid
       #   Person.add_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 1.0.0
       def add_indexes
-        if hereditary? && !index_keys.include?(_type: 1)
-          index({ _type: 1 }, unique: false, background: true)
+        if hereditary? && !index_keys.include?(self.discriminator_key.to_sym => 1)
+          index({ self.discriminator_key.to_sym => 1 }, unique: false, background: true)
         end
         true
       end
@@ -92,12 +88,10 @@ module Mongoid
       #     index({ name: 1 }, { background: true })
       #   end
       #
-      # @param [ Symbol ] spec The index spec.
+      # @param [ Hash ] spec The index spec.
       # @param [ Hash ] options The index options.
       #
       # @return [ Hash ] The index options.
-      #
-      # @since 1.0.0
       def index(spec, options = nil)
         specification = Specification.new(self, spec, options)
         if !index_specifications.include?(specification)
@@ -114,8 +108,6 @@ module Mongoid
       # @param [ String ] index_name The index name.
       #
       # @return [ Specification ] The found specification.
-      #
-      # @since 4.0.0
       def index_specification(index_hash, index_name = nil)
         index = OpenStruct.new(fields: index_hash.keys, key: index_hash)
         index_specifications.detect do |spec|
@@ -134,8 +126,6 @@ module Mongoid
       #   Model.indexed_database_names
       #
       # @return [ Array<String> ] The names.
-      #
-      # @since 3.1.0
       def indexed_database_names
         index_specifications.map do |spec|
           spec.options[:database] || database_name
@@ -150,8 +140,6 @@ module Mongoid
       #   Model.index_keys
       #
       # @return [ Array<Hash> ] The specification keys.
-      #
-      # @since 4.0.0
       def index_keys
         index_specifications.map(&:key)
       end

data/lib/mongoid/inspectable.rb

@@ -1,9 +1,8 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
 
-  # Contains the bahviour around inspecting documents via inspect.
-  #
-  # @since 4.0.0
+  # Contains the behavior around inspecting documents via inspect.
   module Inspectable
 
     # Returns the class name plus its attributes. If using dynamic fields will
@@ -13,12 +12,10 @@ module Mongoid
     #   person.inspect
     #
     # @return [ String ] A nice pretty string to look at.
-    #
-    # @since 1.0.0
     def inspect
       inspection = []
       inspection.concat(inspect_fields).concat(inspect_dynamic_fields)
-      "#<#{self.class.name} _id: #{id}, #{inspection * ', '}>"
+      "#<#{self.class.name} _id: #{_id}, #{inspection * ', '}>"
     end
 
     private
@@ -31,8 +28,6 @@ module Mongoid
     #   document.inspect_fields
     #
     # @return [ String ] An array of pretty printed field values.
-    #
-    # @since 1.0.0
     def inspect_fields
       fields.map do |name, field|
         unless name == "_id"
@@ -50,8 +45,6 @@ module Mongoid
     #   document.inspect_dynamic_fields
     #
     # @return [ String ] An array of pretty printed dynamic field values.
-    #
-    # @since 1.0.0
     def inspect_dynamic_fields
       []
     end

data/lib/mongoid/interceptable.rb

@@ -1,9 +1,8 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
 
   # This module contains all the callback hooks for Mongoid.
-  #
-  # @since 4.0.0
   module Interceptable
     extend ActiveSupport::Concern
 
@@ -49,8 +48,6 @@ module Mongoid
     # @param [ Symbol ] kind The type of callback.
     #
     # @return [ true, false ] If the callback can be executed.
-    #
-    # @since 3.0.6
     def callback_executable?(kind)
       respond_to?("_#{kind}_callbacks")
     end
@@ -64,15 +61,13 @@ module Mongoid
     # @param [ Symbol ] kind The callback kind.
     #
     # @return [ true, false ] If the document is in a callback state.
-    #
-    # @since 3.1.0
     def in_callback_state?(kind)
       [ :create, :destroy ].include?(kind) || new_record? || flagged_for_destroy? || changed?
     end
 
     # Run only the after callbacks for the specific event.
     #
-    # @note ActiveSupport does not allow this type of behaviour by default, so
+    # @note ActiveSupport does not allow this type of behavior by default, so
     #   Mongoid has to get around it and implement itself.
     #
     # @example Run only the after save callbacks.
@@ -81,8 +76,6 @@ module Mongoid
     # @param [ Array<Symbol> ] kinds The events that are occurring.
     #
     # @return [ Object ] The result of the chain executing.
-    #
-    # @since 3.0.0
     def run_after_callbacks(*kinds)
       kinds.each do |kind|
         run_targeted_callbacks(:after, kind)
@@ -91,7 +84,7 @@ module Mongoid
 
     # Run only the before callbacks for the specific event.
     #
-    # @note ActiveSupport does not allow this type of behaviour by default, so
+    # @note ActiveSupport does not allow this type of behavior by default, so
     #   Mongoid has to get around it and implement itself.
     #
     # @example Run only the before save callbacks.
@@ -100,8 +93,6 @@ module Mongoid
     # @param [ Array<Symbol> ] kinds The events that are occurring.
     #
     # @return [ Object ] The result of the chain executing.
-    #
-    # @since 3.0.0
     def run_before_callbacks(*kinds)
       kinds.each do |kind|
         run_targeted_callbacks(:before, kind)
@@ -121,15 +112,17 @@ module Mongoid
     # @param [ Array ] args Any options.
     #
     # @return [ Document ] The document
-    #
-    # @since 2.3.0
-    def run_callbacks(kind, *args, &block)
+    ruby2_keywords def run_callbacks(kind, *args, &block)
       cascadable_children(kind).each do |child|
         if child.run_callbacks(child_callback_type(kind, child), *args) == false
           return false
         end
       end
-      callback_executable?(kind) ? super(kind, *args, &block) : true
+      if callback_executable?(kind)
+        super(kind, *args, &block)
+      else
+        true
+      end
     end
 
     private
@@ -143,8 +136,6 @@ module Mongoid
     #   document.before_callback_halted?
     #
     # @return [ true, false ] If a before callback was halted.
-    #
-    # @since 3.0.3
     def before_callback_halted?
       !!@before_callback_halted
     end
@@ -157,11 +148,9 @@ module Mongoid
     # @param [ Symbol ] kind The type of callback.
     #
     # @return [ Array<Document> ] The children.
-    #
-    # @since 2.3.0
     def cascadable_children(kind, children = Set.new)
-      embedded_relations.each_pair do |name, metadata|
-        next unless metadata.cascading_callbacks?
+      embedded_relations.each_pair do |name, association|
+        next unless association.cascading_callbacks?
         without_autobuild do
           delayed_pulls = delayed_atomic_pulls[name]
           delayed_unsets = delayed_atomic_unsets[name]
@@ -170,7 +159,7 @@ module Mongoid
           relation = send(name)
           Array.wrap(relation).each do |child|
             next if children.include?(child)
-            children.add(child) if cascadable_child?(kind, child, metadata)
+            children.add(child) if cascadable_child?(kind, child, association)
             child.send(:cascadable_children, kind, children)
           end
         end
@@ -187,11 +176,9 @@ module Mongoid
     # @param [ Document ] child The child document.
     #
     # @return [ true, false ] If the child should fire the callback.
-    #
-    # @since 2.3.0
-    def cascadable_child?(kind, child, metadata)
+    def cascadable_child?(kind, child, association)
       return false if kind == :initialize || kind == :find || kind == :touch
-      return false if kind == :validate && metadata.validate?
+      return false if kind == :validate && association.validate?
       child.callback_executable?(kind) ? child.in_callback_state?(kind) : false
     end
 
@@ -207,8 +194,6 @@ module Mongoid
     # @param [ Document ] child The child document
     #
     # @return [ Symbol ] The name of the callback.
-    #
-    # @since 2.3.0
     def child_callback_type(kind, child)
       if kind == :update
         return :create if child.new_record?
@@ -228,9 +213,9 @@ module Mongoid
     #   document.halted_callback_hook(filter)
     #
     # @param [ Symbol ] filter The callback that halted.
-    #
-    # @since 3.0.3
-    def halted_callback_hook(filter)
+    # @param [ Symbol ] name The name of the callback that was halted
+    #   (requires Rails 6.1+)
+    def halted_callback_hook(filter, name = nil)
       @before_callback_halted = true
     end
 
@@ -244,8 +229,6 @@ module Mongoid
     # @param [ Symbol ] kind The type of callback, :save, :create, :update.
     #
     # @return [ Object ] The result of the chain execution.
-    #
-    # @since 3.0.0
     def run_targeted_callbacks(place, kind)
       name = "_run__#{place}__#{kind}__callbacks"
       unless respond_to?(name)

data/lib/mongoid/loggable.rb

@@ -1,20 +1,19 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
 
-  # Contains logging behaviour.
+  # Contains logging behavior.
   module Loggable
 
     # Get the logger.
     #
     # @note Will try to grab Rails' logger first before creating a new logger
-    #   with stdout.
+    #   with stderr.
     #
     # @example Get the logger.
     #   Loggable.logger
     #
     # @return [ Logger ] The logger.
-    #
-    # @since 3.0.0
     def logger
       return @logger if defined?(@logger)
       @logger = rails_logger || default_logger
@@ -23,20 +22,18 @@ module Mongoid
     # Set the logger.
     #
     # @example Set the logger.
-    #   Loggable.logger = Logger.new($stdout)
+    #   Loggable.logger = Logger.new(STDERR)
     #
     # @param [ Logger ] logger The logger to set.
     #
     # @return [ Logger ] The new logger.
-    #
-    # @since 3.0.0
     def logger=(logger)
       @logger = logger
     end
 
     private
 
-    # Gets the default Mongoid logger - stdout.
+    # Gets the default Mongoid logger - stderr.
     #
     # @api private
     #
@@ -44,15 +41,13 @@ module Mongoid
     #   Loggable.default_logger
     #
     # @return [ Logger ] The default logger.
-    #
-    # @since 3.0.0
     def default_logger
-      logger = Logger.new($stdout)
+      logger = Logger.new(STDERR)
       logger.level = Mongoid::Config.log_level
       logger
     end
 
-    # Get the Rails logger if it's defined.
+    # Get the Rails logger if loaded in a Rails application, otherwise nil.
     #
     # @api private
     #
@@ -60,10 +55,12 @@ module Mongoid
     #   Loggable.rails_logger
     #
     # @return [ Logger ] The Rails logger.
-    #
-    # @since 3.0.0
     def rails_logger
-      defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+      if defined?(::Rails)
+        ::Rails.logger
+      else
+        nil
+      end
     end
   end
 end