mongoid 7.0.2 → 8.1.1

data/lib/mongoid/criteria/queryable/mergeable.rb

@@ -1,9 +1,10 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   class Criteria
     module Queryable
 
-      # Contains behaviour for merging existing selection with new selection.
+      # Contains behavior for merging existing selection with new selection.
       module Mergeable
 
         # @attribute [rw] strategy The name of the current strategy.
@@ -15,8 +16,6 @@ module Mongoid
         #   mergeable.intersect.in(field: [ 1, 2, 3 ])
         #
         # @return [ Mergeable ] The intersect flagged mergeable.
-        #
-        # @since 1.0.0
         def intersect
           use(:__intersect__)
         end
@@ -27,8 +26,6 @@ module Mongoid
         #   mergeable.override.in(field: [ 1, 2, 3 ])
         #
         # @return [ Mergeable ] The override flagged mergeable.
-        #
-        # @since 1.0.0
         def override
           use(:__override__)
         end
@@ -39,22 +36,41 @@ module Mongoid
         #   mergeable.union.in(field: [ 1, 2, 3 ])
         #
         # @return [ Mergeable ] The union flagged mergeable.
-        #
-        # @since 1.0.0
         def union
           use(:__union__)
         end
 
-        # Reset the stratgies to nil, used after cloning.
+        # Clear the current strategy and negating flag, used after cloning.
         #
         # @example Reset the strategies.
         #   mergeable.reset_strategies!
         #
-        # @return [ nil ] nil.
-        #
-        # @since 1.0.0
+        # @return [ Criteria ] self.
         def reset_strategies!
-          self.strategy, self.negating = nil, nil
+          self.strategy = nil
+          self.negating = nil
+          self
+        end
+
+        # Merge criteria with operators using the and operator.
+        #
+        # @param [ Hash ] criterion The criterion to add to the criteria.
+        # @param [ String ] operator The MongoDB operator.
+        #
+        # @return [ Criteria ] The resulting criteria.
+        def and_with_operator(criterion, operator)
+          crit = self
+          if criterion
+            criterion.each_pair do |field, value|
+              val = prepare(field, operator, value)
+              # The prepare method already takes the negation into account. We
+              # set negating to false here so that ``and`` doesn't also apply
+              # negation and we have a double negative.
+              crit.negating = false
+              crit = crit.and(field => val)
+            end
+          end
+          crit
         end
 
         private
@@ -70,8 +86,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __add__(criterion, operator)
           with_strategy(:__add__, criterion, operator)
         end
@@ -88,8 +102,6 @@ module Mongoid
         # @param [ String ] inner The inner MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __expanded__(criterion, outer, inner)
           selection(criterion) do |selector, field, value|
             selector.store(field, { outer => { inner => value }})
@@ -107,8 +119,6 @@ module Mongoid
         # @param [ Hash ] criterion The criteria.
         #
         # @return [ Mergeable ] The cloned object.
-        #
-        # @since 2.0.0
         def __merge__(criterion)
           selection(criterion) do |selector, field, value|
             selector.merge!(field.__expr_part__(value))
@@ -126,40 +136,198 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __intersect__(criterion, operator)
           with_strategy(:__intersect__, criterion, operator)
         end
 
-        # Adds the criterion to the existing selection.
+        # Adds $and/$or/$nor criteria to a copy of this selection.
+        #
+        # Each of the criteria can be a Hash of key/value pairs or MongoDB
+        # operators (keys beginning with $), or a Selectable object
+        # (which typically will be a Criteria instance).
         #
         # @api private
         #
         # @example Add the criterion.
         #   mergeable.__multi__([ 1, 2 ], "$in")
         #
-        # @param [ Hash ] criterion The criteria.
+        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        #   matches or Criteria objects.
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
-        def __multi__(criterion, operator)
+        def __multi__(criteria, operator)
           clone.tap do |query|
             sel = query.selector
-            criterion.flatten.each do |expr|
+            criteria.flatten.each do |expr|
               next unless expr
-              criteria = sel[operator] || []
-              normalized = expr.inject({}) do |hash, (field, value)|
-                hash.merge!(field.__expr_part__(value.__expand_complex__))
-                hash
+              result_criteria = sel[operator] || []
+              if expr.is_a?(Selectable)
+                expr = expr.selector
               end
-              sel.store(operator, criteria.push(normalized))
+              normalized = _mongoid_expand_keys(expr)
+              sel.store(operator, result_criteria.push(normalized))
             end
           end
         end
 
+        # Combines criteria into a MongoDB selector.
+        #
+        # Criteria is an array of criterion objects which will be flattened.
+        #
+        # Each criterion can be:
+        # - A hash
+        # - A Criteria instance
+        # - nil, in which case it is ignored
+        #
+        # @api private
+        private def _mongoid_add_top_level_operation(operator, criteria)
+          # Flatten the criteria. The idea is that predicates in MongoDB
+          # are always hashes and are never arrays. This method additionally
+          # allows Criteria instances as predicates.
+          # The flattening is existing Mongoid behavior but we could possibly
+          # get rid of it as applications can splat their predicates, or
+          # flatten if needed.
+          clone.tap do |query|
+            sel = query.selector
+            _mongoid_flatten_arrays(criteria).each do |criterion|
+              if criterion.is_a?(Selectable)
+                expr = _mongoid_expand_keys(criterion.selector)
+              else
+                expr = _mongoid_expand_keys(criterion)
+              end
+              if sel.empty?
+                sel.store(operator, [expr])
+              elsif sel.keys == [operator]
+                sel.store(operator, sel[operator] + [expr])
+              else
+                operands = [sel.dup] + [expr]
+                sel.clear
+                sel.store(operator, operands)
+              end
+            end
+          end
+        end
+
+        # Calling .flatten on an array which includes a Criteria instance
+        # evaluates the criteria, which we do not want. Hence this method
+        # explicitly only expands Array objects and Array subclasses.
+        private def _mongoid_flatten_arrays(array)
+          out = []
+          pending = array.dup
+          until pending.empty?
+            item = pending.shift
+            if item.nil?
+              # skip
+            elsif item.is_a?(Array)
+              pending += item
+            else
+              out << item
+            end
+          end
+          out
+        end
+
+        # Takes a criteria hash and expands Key objects into hashes containing
+        # MQL corresponding to said key objects. Also converts the input to
+        # BSON::Document to permit indifferent access.
+        #
+        # The argument must be a hash containing key-value pairs of the
+        # following forms:
+        # - {field_name: value}
+        # - {'field_name' => value}
+        # - {key_instance: value}
+        # - {:$operator => operator_value_expression}
+        # - {'$operator' => operator_value_expression}
+        #
+        # Ruby does not permit multiple symbol operators. For example,
+        # {:foo.gt => 1, :foo.gt => 2} is collapsed to {:foo.gt => 2} by the
+        # language. Therefore this method never has to deal with multiple
+        # identical operators.
+        #
+        # Similarly, this method should never need to expand a literal value
+        # and an operator at the same time.
+        #
+        # This method effectively converts symbol keys to string keys in
+        # the input +expr+, such that the downstream code can assume that
+        # conditions always contain string keys.
+        #
+        # @param [ Hash ] expr Criteria including Key instances.
+        #
+        # @return [ BSON::Document ] The expanded criteria.
+        private def _mongoid_expand_keys(expr)
+          unless expr.is_a?(Hash)
+            raise ArgumentError, 'Argument must be a Hash'
+          end
+
+          result = BSON::Document.new
+          expr.each do |field, value|
+            field.__expr_part__(value.__expand_complex__, negating?).each do |k, v|
+              if existing = result[k]
+                if existing.is_a?(Hash)
+                  # Existing value is an operator.
+                  # If new value is also an operator, ensure there are no
+                  # conflicts and add
+                  if v.is_a?(Hash)
+                    # The new value is also an operator.
+                    # If there are no conflicts, combine the hashes, otherwise
+                    # add new conditions to top level with $and.
+                    if (v.keys & existing.keys).empty?
+                      existing.update(v)
+                    else
+                      raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                      result['$and'] ||= []
+                      result['$and'] << {k => v}
+                    end
+                  else
+                    # The new value is a simple value.
+                    # Transform the implicit equality to either $eq or $regexp
+                    # depending on the type of the argument. See
+                    # https://www.mongodb.com/docs/manual/reference/operator/query/eq/#std-label-eq-usage-examples
+                    # for the description of relevant server behavior.
+                    op = case v
+                    when Regexp, BSON::Regexp::Raw
+                      '$regex'
+                    else
+                      '$eq'
+                    end
+                    # If there isn't an $eq/$regex operator already in the
+                    # query, transform the new value into an operator
+                    # expression and add it to the existing hash. Otherwise
+                    # add the new condition with $and to the top level.
+                    if existing.key?(op)
+                      raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                      result['$and'] ||= []
+                      result['$and'] << {k => v}
+                    else
+                      existing.update(op => v)
+                    end
+                  end
+                else
+                  # Existing value is a simple value.
+                  # See the notes above about transformations to $eq/$regex.
+                  op = case existing
+                  when Regexp, BSON::Regexp::Raw
+                    '$regex'
+                  else
+                    '$eq'
+                  end
+                  if v.is_a?(Hash) && !v.key?(op)
+                    result[k] = {op => existing}.update(v)
+                  else
+                    raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                    result['$and'] ||= []
+                    result['$and'] << {k => v}
+                  end
+                end
+              else
+                result[k] = v
+              end
+            end
+          end
+          result
+        end
+
         # Adds the criterion to the existing selection.
         #
         # @api private
@@ -167,13 +335,14 @@ module Mongoid
         # @example Add the criterion.
         #   mergeable.__override__([ 1, 2 ], "$in")
         #
-        # @param [ Hash ] criterion The criteria.
+        # @param [ Hash | Criteria ] criterion The criteria.
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __override__(criterion, operator)
+          if criterion.is_a?(Selectable)
+            criterion = criterion.selector
+          end
           selection(criterion) do |selector, field, value|
             expression = prepare(field, operator, value)
             existing = selector[field]
@@ -196,8 +365,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __union__(criterion, operator)
           with_strategy(:__union__, criterion, operator)
         end
@@ -212,8 +379,6 @@ module Mongoid
         # @param [ Symbol ] strategy The strategy to use.
         #
         # @return [ Mergeable ] The existing mergeable.
-        #
-        # @since 1.0.0
         def use(strategy)
           tap do |mergeable|
             mergeable.strategy = strategy
@@ -225,15 +390,13 @@ module Mongoid
         # @api private
         #
         # @example Add criterion with a strategy.
-        #   mergeable.with_strategy(:__union__, [ 1, 2, 3 ], "$in")
+        #   mergeable.with_strategy(:__union__, {field_name: [ 1, 2, 3 ]}, "$in")
         #
         # @param [ Symbol ] strategy The name of the strategy method.
         # @param [ Object ] criterion The criterion to add.
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The cloned query.
-        #
-        # @since 1.0.0
         def with_strategy(strategy, criterion, operator)
           selection(criterion) do |selector, field, value|
             selector.store(
@@ -254,8 +417,6 @@ module Mongoid
         # @param [ Object ] value The value.
         #
         # @return [ Object ] The serialized value.
-        #
-        # @since 1.0.0
         def prepare(field, operator, value)
           unless operator =~ /exists|type|size/
             value = value.__expand_complex__

data/lib/mongoid/criteria/queryable/optional.rb

@@ -1,9 +1,10 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   class Criteria
     module Queryable
 
-      # The optional module includes all behaviour that has to do with extra
+      # The optional module includes all behavior that has to do with extra
       # options surrounding queries, like skip, limit, sorting, etc.
       module Optional
         extend Macroable
@@ -16,11 +17,9 @@ module Mongoid
         # @example Add ascending sorting.
         #   optional.ascending(:first_name, :last_name)
         #
-        # @param [ Array<Symbol> ] fields The fields to sort.
+        # @param [ Symbol... ] *fields The field(s) to sort.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def ascending(*fields)
           sort_with_list(*fields, 1)
         end
@@ -37,8 +36,6 @@ module Mongoid
         # @param [ Integer ] value The batch size.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def batch_size(value = nil)
           option(value) { |options| options.store(:batch_size, value) }
         end
@@ -48,11 +45,9 @@ module Mongoid
         # @example Add descending sorting.
         #   optional.descending(:first_name, :last_name)
         #
-        # @param [ Array<Symbol> ] fields The fields to sort.
+        # @param [ Symbol... ] *fields The field(s) to sort.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def descending(*fields)
           sort_with_list(*fields, -1)
         end
@@ -68,8 +63,6 @@ module Mongoid
         # @param [ Hash ] value The index hint.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def hint(value = nil)
           option(value) { |options| options.store(:hint, value) }
         end
@@ -82,8 +75,6 @@ module Mongoid
         # @param [ Integer ] value The number of documents to return.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def limit(value = nil)
           option(value) do |options, query|
             val = value.to_i
@@ -101,8 +92,6 @@ module Mongoid
         # @param [ Integer ] value The max number of documents to scan.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def max_scan(value = nil)
           option(value) { |options| options.store(:max_scan, value) }
         end
@@ -115,8 +104,6 @@ module Mongoid
         # @param [ Integer ] value The max time in milliseconds for processing operations on a cursor.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 6.0.0
         def max_time_ms(value = nil)
           option(value) { |options| options.store(:max_time_ms, value) }
         end
@@ -127,8 +114,6 @@ module Mongoid
         #   optional.no_timeout
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def no_timeout
           clone.tap { |query| query.options.store(:timeout, false) }
         end
@@ -138,11 +123,9 @@ module Mongoid
         # @example Limit the results to the provided fields.
         #   optional.only(:name, :dob)
         #
-        # @param [ Array<Symbol> ] args The fields to return.
+        # @param [ Symbol... ] *args The field(s) to return.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def only(*args)
           args = args.flatten
           option(*args) do |options|
@@ -169,10 +152,10 @@ module Mongoid
         #   optional.order_by([[ name, 1 ], [ dob, -1 ]])
         #
         # @example Add sorting options via an array with symbol directions.
-        #   optional.order_by([[ name, :asc ], [ dob, :desc ]])
+        #   optional.order_by([[ :name, :asc ], [ :dob, :desc ]])
         #
         # @example Add sorting options via an array with string directions.
-        #   optional.order_by([[ name, "asc" ], [ dob, "desc" ]])
+        #   optional.order_by([[ "name", "asc" ], [ "dob", "desc" ]])
         #
         # @example Add sorting options with keys.
         #   optional.order_by(:name.asc, :dob.desc)
@@ -180,11 +163,9 @@ module Mongoid
         # @example Add sorting options via a string.
         #   optional.order_by("name ASC, dob DESC")
         #
-        # @param [ Array, Hash, String ] spec The sorting specification.
+        # @param [ [ Array | Hash | String ]... ] *spec The sorting specification.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def order_by(*spec)
           option(spec) do |options, query|
             spec.compact.each do |criterion|
@@ -203,11 +184,9 @@ module Mongoid
         # @example Replace the ordering.
         #   optional.reorder(name: :asc)
         #
-        # @param [ Array, Hash, String ] spec The sorting specification.
+        # @param [ [ Array | Hash | String ]... ] *spec The sorting specification.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 2.1.0
         def reorder(*spec)
           clone.tap do |query|
             query.options.delete(:sort)
@@ -222,8 +201,6 @@ module Mongoid
         # @param [ Integer ] value The number to skip.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def skip(value = nil)
           option(value) do |options, query|
             val = value.to_i
@@ -241,8 +218,6 @@ module Mongoid
         # @param [ Hash ] criterion The slice options.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def slice(criterion = nil)
           option(criterion) do |options|
             options.__union__(
@@ -259,8 +234,6 @@ module Mongoid
         #   optional.snapshot
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def snapshot
           clone.tap do |query|
             query.options.store(:snapshot, true)
@@ -272,11 +245,9 @@ module Mongoid
         # @example Limit the results to the fields not provided.
         #   optional.without(:name, :dob)
         #
-        # @param [ Array<Symbol> ] args The fields to ignore.
+        # @param [ Symbol... ] *args The field(s) to ignore.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def without(*args)
           args = args.flatten
           option(*args) do |options|
@@ -299,8 +270,6 @@ module Mongoid
         # @param [ String ] comment The comment to be associated with the query.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 2.2.0
         def comment(comment = nil)
           clone.tap do |query|
             query.options.store(:comment, comment)
@@ -318,8 +287,6 @@ module Mongoid
         # @param [ Symbol ] type The type of cursor to create.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 2.2.0
         def cursor_type(type)
           clone.tap { |query| query.options.store(:cursor_type, type) }
         end
@@ -332,8 +299,6 @@ module Mongoid
         # @param [ Hash ] collation_doc The document describing the collation to use.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 6.1.0
         def collation(collation_doc)
           clone.tap { |query| query.options.store(:collation, collation_doc) }
         end
@@ -352,18 +317,10 @@ module Mongoid
         # @param [ Integer ] direction The sort direction.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def add_sort_option(options, field, direction)
-          if driver == :mongo1x
-            sorting = (options[:sort] || []).dup
-            sorting.push([ field, direction ])
-            options.store(:sort, sorting)
-          else
-            sorting = (options[:sort] || {}).dup
-            sorting[field] = direction
-            options.store(:sort, sorting)
-          end
+          sorting = (options[:sort] || {}).dup
+          sorting[field] = direction
+          options.store(:sort, sorting)
         end
 
         # Take the provided criterion and store it as an option in the query
@@ -374,11 +331,9 @@ module Mongoid
         # @example Store the option.
         #   optional.option({ skip: 10 })
         #
-        # @param [ Array ] args The options.
+        # @param [ Object... ] *args The options.
         #
         # @return [ Queryable ] The cloned queryable.
-        #
-        # @since 1.0.0
         def option(*args)
           clone.tap do |query|
             unless args.compact.empty?
@@ -394,12 +349,10 @@ module Mongoid
         # @example Add multiple sort options.
         #   optional.sort_with_list(:name, :dob, 1)
         #
-        # @param [ Array<String> ] fields The field names.
+        # @param [ [ Symbol | String ]... ] *fields The field name(s).
         # @param [ Integer ] direction The sort direction.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def sort_with_list(*fields, direction)
           option(fields) do |options, query|
             fields.flatten.compact.each do |field|
@@ -417,8 +370,6 @@ module Mongoid
           #   Optional.forwardables
           #
           # @return [ Array<Symbol> ] The names of the forwardable methods.
-          #
-          # @since 1.0.0
           def forwardables
             public_instance_methods(false) - [ :options, :options= ]
           end