mongoid 8.1.5 → 9.0.0

data/lib/mongoid/interceptable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 
@@ -43,6 +44,10 @@ module Mongoid
       # @api private
       define_model_callbacks :persist_parent
 
+      define_callbacks :commit, :rollback,
+                       only: :after,
+                       scope: [:kind, :name]
+
       attr_accessor :before_callback_halted
     end
 
@@ -115,8 +120,14 @@ module Mongoid
     #   end
     #
     # @param [ Symbol ] kind The type of callback to execute.
-    # @param [ true | false ] with_children Flag specifies whether callbacks of embedded document should be run.
-    def run_callbacks(kind, with_children: true, &block)
+    # @param [ true | false ] with_children Flag specifies whether callbacks
+    #   of embedded document should be run.
+    # @param [ Proc | nil ] skip_if If this proc returns true, the callbacks
+    #   will not be triggered, while the given block will be still called.
+    def run_callbacks(kind, with_children: true, skip_if: nil, &block)
+      if skip_if&.call
+        return block&.call
+      end
       if with_children
         cascadable_children(kind).each do |child|
           if child.run_callbacks(child_callback_type(kind, child), with_children: with_children) == false

data/lib/mongoid/loadable.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+
+  # Defines how Mongoid can autoload all defined models.
+  module Loadable
+    # The default list of paths where model classes should be looked for. If
+    # Rails is present, the "app/models" paths will be used instead.
+    # (See #model_paths.)
+    DEFAULT_MODEL_PATHS = %w( ./app/models ./lib/models ).freeze
+
+    # Search a list of model paths to get every model and require it, so
+    # that indexing and inheritance work in both development and production
+    # with the same results.
+    #
+    # @example Load all the application models from default model paths.
+    #   Mongoid.load_models
+    #
+    # @example Load all application models from a non-standard set of paths.
+    #   Mongoid.load_models(%w( ./models ./admin/models ))
+    #
+    # @param [ Array ] paths The list of paths that should be looked in
+    #   for model files. These must either be absolute paths, or relative to
+    #   the current working directory.
+    def load_models(paths = model_paths)
+      paths.each do |path|
+        if preload_models.resizable?
+          files = preload_models.map { |model| "#{path}/#{model.underscore}.rb" }
+        else
+          files = Dir.glob("#{path}/**/*.rb")
+        end
+
+        files.sort.each do |file|
+          load_model(file.gsub(/^#{path}\// , "").gsub(/\.rb$/, ""))
+        end
+      end
+    end
+
+    # A convenience method for loading a model's file. If Rails'
+    # `require_dependency` method exists, it will be used; otherwise
+    # `require` will be used.
+    #
+    # @example Load the model.
+    #   Mongoid.load_model("/mongoid/behavior")
+    #
+    # @param [ String ] file The base filename.
+    #
+    # @api private
+    def load_model(file)
+      if defined?(require_dependency)
+        require_dependency(file)
+      else
+        require(file)
+      end
+    end
+
+    # Returns the array of paths where the application's model definitions
+    # are located. If Rails is loaded, this defaults to the configured
+    # "app/models" paths (e.g. `config.paths["app/models"]`); otherwise, it
+    # defaults to `%w(./app/models ./lib/models)`.
+    #
+    # Note that these paths are the *roots* of the directory hierarchies where
+    # the models are located; it is not necessary to indicate every subdirectory,
+    # as long as these root paths are located in `$LOAD_PATH`.
+    #
+    # @return [ Array<String> ] the array of model paths
+    def model_paths
+      @model_paths ||= defined?(Rails) ?
+        Rails.application.config.paths["app/models"].expanded :
+        DEFAULT_MODEL_PATHS
+    end
+
+    # Sets the model paths to the given array of paths. These are the paths
+    # where the application's model definitions are located.
+    #
+    # @param [ Array<String> ] paths The list of model paths
+    def model_paths=(paths)
+      @model_paths = paths
+    end
+  end
+
+end

data/lib/mongoid/loggable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 

data/lib/mongoid/matchable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
 

data/lib/mongoid/matcher/all.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $all expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/all/
+    #
     # @api private
     module All
+
+      # Returns whether a value satisfies an $all expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Object> ] condition The $all condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         unless Array === condition
           raise Errors::InvalidQuery, "$all argument must be an array: #{Errors::InvalidQuery.truncate_expr(condition)}"

data/lib/mongoid/matcher/and.rb

@@ -1,8 +1,22 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $and expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/and/
+    #
     # @api private
     module And
+
+      # Returns whether a document satisfies an $and expression.
+      #
+      # @param [ Mongoid::Document ] document The document.
+      # @param [ Array<Hash> ] expr The $and conditions.
+      #
+      # @return [ true | false ] Whether the document matches.
+      #
+      # @api private
       module_function def matches?(document, expr)
         unless expr.is_a?(Array)
           raise Errors::InvalidQuery, "$and argument must be an array: #{Errors::InvalidQuery.truncate_expr(expr)}"

data/lib/mongoid/matcher/bits.rb

@@ -1,8 +1,22 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Mixin module included in bitwise expression matchers.
+    #
     # @api private
     module Bits
+
+      # Returns whether a value satisfies a bitwise expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Object ] value The value to check.
+      # @param [ Numeric | Array<Numeric> ] condition The expression
+      #   predicate as a bitmask or position list.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def matches?(exists, value, condition)
         case value
         when BSON::Binary
@@ -33,6 +47,11 @@ module Mongoid
         end
       end
 
+      # Returns the name of the expression operator.
+      #
+      # @return [ String ] The operator name.
+      #
+      # @api private
       module_function def operator_name
         name.sub(/.*::/, '').sub(/\A(.)/) { |l| l.downcase }
       end

data/lib/mongoid/matcher/bits_all_clear.rb

@@ -1,17 +1,38 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $bitsAllClear expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/bitsAllClear/
+    #
     # @api private
     module BitsAllClear
       include Bits
       extend self
 
+      # Returns whether a position list condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Numeric> ] condition The position list condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def array_matches?(value, condition)
         condition.all? do |c|
           value & (1<<c) == 0
         end
       end
 
+      # Returns whether a bitmask condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Numeric ] condition The bitmask condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def int_matches?(value, condition)
         value & condition == 0
       end

data/lib/mongoid/matcher/bits_all_set.rb

@@ -1,17 +1,38 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $bitsAllSet expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/bitsAllSet/
+    #
     # @api private
     module BitsAllSet
       include Bits
       extend self
 
+      # Returns whether a position list condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Numeric> ] condition The position list condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def array_matches?(value, condition)
         condition.all? do |c|
           value & (1<<c) > 0
         end
       end
 
+      # Returns whether a bitmask condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Numeric ] condition The bitmask condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def int_matches?(value, condition)
         value & condition == condition
       end

data/lib/mongoid/matcher/bits_any_clear.rb

@@ -1,17 +1,38 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $bitsAnyClear expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/bitsAnyClear/
+    #
     # @api private
     module BitsAnyClear
       include Bits
       extend self
 
+      # Returns whether a position list condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Numeric> ] condition The position list condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def array_matches?(value, condition)
         condition.any? do |c|
           value & (1<<c) == 0
         end
       end
 
+      # Returns whether a bitmask condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Numeric ] condition The bitmask condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def int_matches?(value, condition)
         value & condition < condition
       end

data/lib/mongoid/matcher/bits_any_set.rb

@@ -1,17 +1,38 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $bitsAnySet expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/bitsAnySet/
+    #
     # @api private
     module BitsAnySet
       include Bits
       extend self
 
+      # Returns whether a position list condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Numeric> ] condition The position list condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def array_matches?(value, condition)
         condition.any? do |c|
           value & (1<<c) > 0
         end
       end
 
+      # Returns whether a bitmask condition matches a value.
+      #
+      # @param [ Object ] value The value to check.
+      # @param [ Numeric ] condition The bitmask condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       def int_matches?(value, condition)
         value & condition > 0
       end

data/lib/mongoid/matcher/elem_match.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $elemMatch expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/elemMatch/
+    #
     # @api private
     module ElemMatch
+
+      # Returns whether a value satisfies an $elemMatch expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Object | Array<Object> ] value The value to check.
+      # @param [ Hash ] expr The $elemMatch condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         unless Hash === condition
           raise Errors::InvalidQuery, "$elemMatch requires a Hash operand: #{Errors::InvalidQuery.truncate_expr(condition)}"

data/lib/mongoid/matcher/elem_match_expression.rb

@@ -1,11 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
-    # $elemMatch argument can be a top-level expression and some specific
-    # operator combinations like $not with a regular expression.
+    # In-memory matcher used to evaluate whether an $elemMatch predicate
+    # matches and individual document. The $elemMatch predicate can be a
+    # logical expressions including $and, $or, $nor, and $not. $not can
+    # also have a regular expression predicate.
     #
     # @api private
     module ElemMatchExpression
+
+      # Returns whether a document satisfies an $elemMatch expression.
+      #
+      # @param [ Mongoid::Document ] document The document.
+      # @param [ Hash ] expr The $elemMatch condition predicate.
+      #
+      # @return [ true | false ] Whether the document matches.
+      #
+      # @api private
       module_function def matches?(document, expr)
         Expression.matches?(document, expr)
       rescue Mongoid::Errors::InvalidExpressionOperator

data/lib/mongoid/matcher/eq.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $eq expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/eq/
+    #
     # @api private
     module Eq
+
+      # Returns whether a value satisfies an $eq expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Hash ] expr The $eq condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         EqImpl.matches?(exists, value, condition, '$eq')
       end

data/lib/mongoid/matcher/eq_impl.rb

@@ -1,3 +1,4 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
@@ -9,6 +10,17 @@ module Mongoid
     #
     # @api private
     module EqImpl
+
+      # Returns whether a value satisfies an $eq (or similar) expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Object ] value The value to check.
+      # @param [ Object | Range ] condition The equality condition predicate.
+      # @param [ String ] original_operator Operator to use in exception messages.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition, original_operator)
         case condition
         when Range
@@ -24,21 +36,16 @@ module Mongoid
 =end
         else
           # When doing a comparison with Time objects, compare using millisecond precision
-          if Mongoid.compare_time_by_ms
-            if value.kind_of?(Time) && condition.kind_of?(Time)
-              time_eq?(value, condition)
-            elsif value.is_a?(Array) && condition.kind_of?(Time)
-              value.map do |v|
-                if v.kind_of?(Time)
-                  time_rounded_to_millis(v)
-                else
-                  v
-                end
-              end.include?(time_rounded_to_millis(condition))
-            else
-              value == condition ||
-              value.is_a?(Array) && value.include?(condition)
-            end
+          if value.kind_of?(Time) && condition.kind_of?(Time)
+            time_eq?(value, condition)
+          elsif value.is_a?(Array) && condition.kind_of?(Time)
+            value.map do |v|
+              if v.kind_of?(Time)
+                time_rounded_to_millis(v)
+              else
+                v
+              end
+            end.include?(time_rounded_to_millis(condition))
           else
             value == condition ||
             value.is_a?(Array) && value.include?(condition)
@@ -54,11 +61,21 @@ module Mongoid
       # calculations using integer math, as inexactness of floating point calculations may produce
       # unexpected results.
       #
-      # As such, perform a similar operation to what the bson-ruby gem does
+      # As such, perform a similar operation to what the bson-ruby gem does.
+      #
+      # @param [ Time ] time_a The first time value.
+      # @param [ Time ] time_b The second time value.
+      #
+      # @return [ true | false ] Whether the two times are equal to the millisecond.
       module_function def time_eq?(time_a, time_b)
         time_rounded_to_millis(time_a) == time_rounded_to_millis(time_b)
       end
 
+      # Rounds a time value to nearest millisecond.
+      #
+      # @param [ Time ] time The time value.
+      #
+      # @return [ true | false ] The time rounded to the millisecond.
       module_function def time_rounded_to_millis(time)
         return time._bson_to_i * 1000 + time.usec.divmod(1000).first
       end

data/lib/mongoid/matcher/eq_impl_with_regexp.rb

@@ -1,3 +1,4 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
@@ -6,6 +7,18 @@ module Mongoid
     #
     # @api private
     module EqImplWithRegexp
+
+      # Returns whether a value satisfies an $eq (or similar) expression,
+      # performing a regular expression match if the condition is a regular
+      # expression.
+      #
+      # @param [ String ] original_operator Not used.
+      # @param [ Object ] value The value to check.
+      # @param [ Object ] condition The equality condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(original_operator, value, condition)
         case condition
         when Regexp
@@ -13,8 +26,7 @@ module Mongoid
         when ::BSON::Regexp::Raw
           value =~ condition.compile
         else
-          if Mongoid.compare_time_by_ms &&
-            value.kind_of?(Time) && condition.kind_of?(Time)
+          if value.kind_of?(Time) && condition.kind_of?(Time)
             EqImpl.time_eq?(value, condition)
           else
             value == condition

data/lib/mongoid/matcher/exists.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $exists expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/exists/
+    #
     # @api private
     module Exists
+
+      # Returns whether an $exists expression is satisfied.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value Not used.
+      # @param [ true | false ] condition The $exists condition predicate.
+      #
+      # @return [ true | false ] Whether the existence condition is met.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when Range

data/lib/mongoid/matcher/expression.rb

@@ -1,8 +1,21 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Base singleton module used for evaluating whether a given
+    # document in-memory matches an MSQL query expression.
+    #
     # @api private
     module Expression
+
+      # Returns whether a document satisfies a query expression.
+      #
+      # @param [ Mongoid::Document ] document The document.
+      # @param [ Hash ] expr The expression.
+      #
+      # @return [ true | false ] Whether the document matches.
+      #
+      # @api private
       module_function def matches?(document, expr)
         if expr.nil?
           raise Errors::InvalidQuery, "Nil condition in expression context"

data/lib/mongoid/matcher/expression_operator.rb

@@ -1,6 +1,10 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Singleton module provides lookup of logical query operator
+    # matchers.
+    #
     # @api private
     module ExpressionOperator
       MAP = {
@@ -9,6 +13,16 @@ module Mongoid
         '$or' => Or,
       }.freeze
 
+      # Returns the matcher module for a given operator.
+      #
+      # @param [ String ] op The operator name.
+      #
+      # @return [ Module ] The matcher module.
+      #
+      # @raises [ Mongoid::Errors::InvalidExpressionOperator ]
+      #   Raised if the given operator is unknown.
+      #
+      # @api private
       module_function def get(op)
         MAP.fetch(op)
       rescue KeyError

data/lib/mongoid/matcher/field_expression.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Singleton module used for evaluating whether a given
+    # value in-memory matches an MSQL query expression related
+    # to a specific field.
+    #
     # @api private
     module FieldExpression
+
+      # Returns whether a value satisfies a condition.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Hash | Object ] condition The condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         if condition.is_a?(Hash)
           condition.all? do |k, cond_v|