mongoid 7.2.1 → 9.0.0

data/lib/mongoid/matcher/bits_any_clear.rb

@@ -0,0 +1,41 @@
+# 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
+    end
+  end
+end

data/lib/mongoid/matcher/bits_any_set.rb

@@ -0,0 +1,41 @@
+# 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
+    end
+  end
+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)}"
@@ -15,7 +30,8 @@ module Mongoid
           # Validate the condition is valid, even though we will never attempt
           # matching it.
           condition.each do |k, v|
-            if k.to_s.start_with?('$')
+            k = k.to_s
+            if k.start_with?('$')
               begin
                 ExpressionOperator.get(k)
               rescue Mongoid::Errors::InvalidExpressionOperator

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
@@ -23,10 +35,50 @@ module Mongoid
           end
 =end
         else
-          value == condition ||
-          value.is_a?(Array) && value.include?(condition)
+          # When doing a comparison with Time objects, compare using millisecond precision
+          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
         end
       end
+
+      # Per https://www.mongodb.com/docs/ruby-driver/current/tutorials/bson-v4/#time-instances,
+      # > Times in BSON (and MongoDB) can only have millisecond precision. When Ruby Time instances
+      # are serialized to BSON or Extended JSON, the times are floored to the nearest millisecond.
+      #
+      # > Because of this flooring, applications are strongly recommended to perform all time
+      # 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.
+      #
+      # @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
     end
   end
 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,7 +26,11 @@ module Mongoid
         when ::BSON::Regexp::Raw
           value =~ condition.compile
         else
-          value == condition
+          if value.kind_of?(Time) && condition.kind_of?(Time)
+            EqImpl.time_eq?(value, condition)
+          else
+            value == condition
+          end
         end
       end
     end

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"
@@ -12,25 +25,20 @@ module Mongoid
         end
         expr.all? do |k, expr_v|
           k = k.to_s
+          if k == "$comment"
+            # Nothing
+            return true
+          end
           if k.start_with?('$')
             ExpressionOperator.get(k).matches?(document, expr_v)
           else
-            exists, value, expanded = Matcher.extract_attribute(document, k)
-            # The value may have been expanded into an array, but then
-            # array may have been shrunk back to a scalar (or hash) when
-            # path contained a numeric position.
-            # Do not treat a hash as an array here (both are iterable).
-            if expanded && Array === value
-              if value == []
-                # Empty array is technically equivalent to exists: false.
-                FieldExpression.matches?(false, nil, expr_v)
-              else
-                value.any? do |v|
-                  FieldExpression.matches?(true, v, expr_v)
-                end
+            values = Matcher.extract_attribute(document, k)
+            if values.length > 0
+              values.any? do |v|
+                FieldExpression.matches?(true, v, expr_v)
               end
             else
-              FieldExpression.matches?(exists, value, expr_v)
+              FieldExpression.matches?(false, nil, expr_v)
             end
           end
         end

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|
@@ -36,14 +51,13 @@ module Mongoid
                 FieldOperator.get(k).matches?(exists, value, cond_v)
               end
             elsif Hash === value
-              sub_exists, sub_value, expanded =
-                Matcher.extract_attribute(value, k)
-              if expanded
-                sub_value.any? do |sub_v|
+              sub_values = Matcher.extract_attribute(value, k)
+              if sub_values.length > 0
+                sub_values.any? do |sub_v|
                   Eq.matches?(true, sub_v, cond_v)
                 end
               else
-                Eq.matches?(sub_exists, sub_value, cond_v)
+                Eq.matches?(false, nil, cond_v)
               end
             else
               false

data/lib/mongoid/matcher/field_operator.rb

@@ -1,10 +1,18 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Singleton module provides lookup of query operator matchers
+    # related to field values.
+    #
     # @api private
     module FieldOperator
       MAP = {
         '$all' => All,
+        '$bitsAllClear' => BitsAllClear,
+        '$bitsAllSet' => BitsAllSet,
+        '$bitsAnyClear' => BitsAnyClear,
+        '$bitsAnySet' => BitsAnySet,
         '$elemMatch' => ElemMatch,
         '$eq' => Eq,
         '$exists' => Exists,
@@ -13,19 +21,36 @@ module Mongoid
         '$in' => In,
         '$lt' => Lt,
         '$lte' => Lte,
+        '$mod' => Mod,
         '$nin' => Nin,
         '$ne' => Ne,
         '$not' => Not,
         '$regex' => Regex,
         '$size' => Size,
+        '$type' => Type,
       }.freeze
 
+      # Returns the matcher module for a given operator.
+      #
+      # @param [ String ] op The operator name.
+      #
+      # @return [ Module ] The matcher module.
+      #
+      # @raises [ Mongoid::Errors::InvalidFieldOperator ]
+      #   Raised if the given operator is unknown.
+      #
+      # @api private
       module_function def get(op)
         MAP.fetch(op)
       rescue KeyError
         raise Errors::InvalidFieldOperator.new(op)
       end
 
+      # Used for evaluating $lt, $lte, $gt, $gte comparison operators.
+      #
+      # @todo Refactor this as it is only relevant to $lt, $lte, $gt, $gte.
+      #
+      # @api private
       module_function def apply_array_field_operator(exists, value, condition)
         if Array === value
           value.any? { |v| yield v }
@@ -34,6 +59,11 @@ module Mongoid
         end
       end
 
+      # Used for evaluating $lt, $lte, $gt, $gte comparison operators.
+      #
+      # @todo Refactor this as it is only relevant to $lt, $lte, $gt, $gte.
+      #
+      # @api private
       module_function def apply_comparison_operator(operator, left, right)
         left.send(operator, right)
       rescue ArgumentError, NoMethodError, TypeError

data/lib/mongoid/matcher/gt.rb

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

data/lib/mongoid/matcher/gte.rb

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

data/lib/mongoid/matcher/in.rb

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

data/lib/mongoid/matcher/lt.rb

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

data/lib/mongoid/matcher/lte.rb

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

data/lib/mongoid/matcher/mod.rb

@@ -0,0 +1,33 @@
+# rubocop:todo all
+module Mongoid
+  module Matcher
+
+    # In-memory matcher for $mod expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/mod/
+    #
+    # @api private
+    module Mod
+
+      # Returns whether a value satisfies a $mod expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Numeric ] value The value to check.
+      # @param [ Array<Numeric> ] condition The $mod condition predicate,
+      #   which is a 2-tuple containing the divisor and remainder.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
+      module_function def matches?(exists, value, condition)
+        unless Array === condition
+          raise Errors::InvalidQuery, "Unknown $mod argument #{condition}"
+        end
+        if condition.length != 2
+          raise Errors::InvalidQuery, "Malformed $mod argument #{condition}, should have 2 elements"
+        end
+        condition[1] == value%condition[0]
+      end
+    end
+  end
+end

data/lib/mongoid/matcher/ne.rb

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