mongoid 3.1.5 → 8.0.2

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

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Mongoid
+  class Criteria
+    module Queryable
+
+      # The selector is a special kind of hash that knows how to serialize values
+      # coming into it as well as being alias and locale aware for key names.
+      class Selector < Smash
+
+        # Merges another selector into this one.
+        #
+        # @example Merge in another selector.
+        #   selector.merge!(name: "test")
+        #
+        # @param [ Hash | Selector ] other The object to merge in.
+        #
+        # @return [ Selector ] The selector.
+        def merge!(other)
+          other.each_pair do |key, value|
+            if value.is_a?(Hash) && self[key.to_s].is_a?(Hash)
+              value = self[key.to_s].merge(value) do |_key, old_val, new_val|
+                case _key
+                when '$in'
+                  new_val & old_val
+                when '$nin'
+                  (old_val + new_val).uniq
+                else
+                  new_val
+                end
+              end
+            end
+            if multi_selection?(key)
+              value = (self[key.to_s] || []).concat(value)
+            end
+            store(key, value)
+          end
+        end
+
+        # Store the value in the selector for the provided key. The selector will
+        # handle all necessary serialization and localization in this step.
+        #
+        # @example Store a value in the selector.
+        #   selector.store(:key, "testing")
+        #
+        # @param [ String | Symbol ] key The name of the attribute.
+        # @param [ Object ] value The value to add.
+        #
+        # @return [ Object ] The stored object.
+        def store(key, value)
+          name, serializer = storage_pair(key)
+          if multi_selection?(name)
+            store_name = name
+            store_value = evolve_multi(value)
+          else
+            store_name, store_value = store_creds(name, serializer, value)
+          end
+          super(store_name, store_value)
+        end
+        alias :[]= :store
+
+        # Convert the selector to an aggregation pipeline entry.
+        #
+        # @example Convert the selector to a pipeline.
+        #   selector.to_pipeline
+        #
+        # @return [ Array<Hash> ] The pipeline entry for the selector.
+        def to_pipeline
+          pipeline = []
+          pipeline.push({ "$match" => self }) unless empty?
+          pipeline
+        end
+
+        private
+
+        # Get the store name and store value. If the value is of type range,
+        # we need may need to change the store_name as well as the store_value,
+        # therefore, we cannot just use the evole method.
+        #
+        # @param [ String ] name The name of the field.
+        # @param [ Object ] serializer The optional serializer for the field.
+        # @param [ Object ] value The value to serialize.
+        #
+        # @return [ Array<String, String> ] The store name and store value.
+        def store_creds(name, serializer, value)
+          store_name = localized_key(name, serializer)
+          if Range === value
+            evolve_range(store_name, serializer, value)
+          else
+            [ store_name, evolve(serializer, value) ]
+          end
+        end
+
+        # Evolves a multi-list selection, like an $and or $or criterion, and
+        # performs the necessary serialization.
+        #
+        # @example Evolve the multi-selection.
+        #   selector.evolve_multi([{ field: "value" }])
+        #
+        # @param [ Array<Hash> ] specs The multi-selection.
+        #
+        # @return [ Array<Hash> ] The serialized values.
+        #
+        # @api private
+        def evolve_multi(specs)
+          unless specs.is_a?(Array)
+            raise ArgumentError, "specs is not an array: #{specs.inspect}"
+          end
+          specs.map do |spec|
+            Hash[spec.map do |key, value|
+              # If an application nests conditionals, e.g.
+              # {'$or' => [{'$or' => {...}}]},
+              # when evolve_multi is called for the top level hash,
+              # this call recursively transforms the bottom level $or.
+              if multi_selection?(key)
+                value = evolve_multi(value)
+              end
+
+              # storage_pair handles field aliases but not localization for
+              # some reason, although per its documentation Smash supposedly
+              # owns both.
+              name, serializer = storage_pair(key)
+              # This performs type conversions on the value and transformations
+              # that depend on the type of the field that the value is stored
+              # in, but not transformations that have to do with query shape.
+              final_key, evolved_value = store_creds(name, serializer, value)
+
+              # This builds a query shape around the value, when the query
+              # involves complex keys. For example, {:foo.lt => 5} produces
+              # {'foo' => {'$lt' => 5}}. This step should be done after all
+              # value-based processing is complete.
+              if key.is_a?(Key)
+                evolved_value = key.transform_value(evolved_value)
+              end
+
+              [ final_key, evolved_value ]
+            end]
+          end.uniq
+        end
+
+        # Evolve a single key selection with various types of values.
+        #
+        # @api private
+        #
+        # @example Evolve a simple selection.
+        #   selector.evolve(field, 5)
+        #
+        # @param [ Object ] serializer The optional serializer for the field.
+        # @param [ Object ] value The value to serialize.
+        #
+        # @return [ Object ] The serialized object.
+        def evolve(serializer, value)
+          case value
+          when Hash
+            evolve_hash(serializer, value)
+          when Array
+            evolve_array(serializer, value)
+          when Range
+            value.__evolve_range__(serializer: serializer)
+          else
+            (serializer || value.class).evolve(value)
+          end
+        end
+
+        # Evolve a single key selection with array values.
+        #
+        # @api private
+        #
+        # @example Evolve a simple selection.
+        #   selector.evolve(field, [ 1, 2, 3 ])
+        #
+        # @param [ Object ] serializer The optional serializer for the field.
+        # @param [ Array<Object> ] value The array to serialize.
+        #
+        # @return [ Object ] The serialized array.
+        def evolve_array(serializer, value)
+          value.map do |_value|
+            evolve(serializer, _value)
+          end
+        end
+
+        # Evolve a single key selection with hash values.
+        #
+        # @api private
+        #
+        # @example Evolve a simple selection.
+        #   selector.evolve(field, { "$gt" => 5 })
+        #
+        # @param [ Object ] serializer The optional serializer for the field.
+        # @param [ Hash ] value The hash to serialize.
+        #
+        # @return [ Object ] The serialized hash.
+        def evolve_hash(serializer, value)
+          value.each_pair do |operator, _value|
+            if operator =~ /exists|type|size/
+              value[operator] = _value
+            else
+              value[operator] = evolve(serializer, _value)
+            end
+          end
+        end
+
+        # Evolve a single key selection with range values. This method traverses
+        # the association tree to build a query for the given value and
+        # serializer. There are three parts to the query here:
+        #
+        # (1) "klass.child.gchild" => {
+        #       "$elemMatch" => {
+        #     (2) "ggchild.field" => (3) { "$gte" => 6, "$lte" => 10 }
+        #       }
+        #     }
+        # (1) The first n fields are dotted together until the last
+        #     embeds_many or field of type array. In the above case, gchild
+        #     would be an embeds_many or Array, and ggchild would be an
+        #     embeds_one or a hash.
+        # (2) The last fields are used inside the $elemMatch. This one is
+        #     actually optional, and will be ignored if the last field is an
+        #     array or embeds_many. If the last field is an array (1), (2) and
+        #     (3) will look like:
+        #
+        #       "klass.child.gchild.ggchild.field" => {
+        #         { "$elemMatch" => { "$gte" => 6, "$lte" => 10 } }
+        #       }
+        #
+        # (3) This is calculated by:
+        #
+        #       value.__evolve_range__(serializer: serializer).
+        #
+        # @api private
+        #
+        # @param [ String ] key The to store the range for.
+        # @param [ Object ] serializer The optional serializer for the field.
+        # @param [ Range ] value The Range to serialize.
+        #
+        # @return [ Array<String, Hash> ] The store name and serialized Range.
+        def evolve_range(key, serializer, value)
+          v = value.__evolve_range__(serializer: serializer)
+          assocs = []
+          Fields.traverse_association_tree(key, serializers, associations, aliased_associations) do |meth, obj, is_field|
+            assocs.push([meth, obj, is_field])
+          end
+
+          # Iterate backwards until you get a field with type
+          # Array or an embeds_many association.
+          inner_key = ""
+          loop do
+            # If there are no arrays or embeds_many associations, just return
+            # the key and value without $elemMatch.
+            return [ key, v ] if assocs.empty?
+
+            meth, obj, is_field = assocs.last
+            break if (is_field && obj.type == Array) || (!is_field && obj.is_a?(Association::Embedded::EmbedsMany))
+
+            assocs.pop
+            inner_key = "#{meth}.#{inner_key}"
+          end
+
+          # If the last array or embeds_many association is the last field,
+          # the inner key (2) is ignored, and the outer key (1) is the original
+          # key.
+          if inner_key.blank?
+            [ key, { "$elemMatch" => v }]
+          else
+            store_key = assocs.map(&:first).join('.')
+            store_value = { "$elemMatch" => { inner_key.chop => v } }
+            [ store_key,  store_value ]
+          end
+        end
+
+        # Determines if the selection is a multi-select, like an $and or $or or $nor
+        # selection.
+        #
+        # @api private
+        #
+        # @example Is the selection a multi-select?
+        #   selector.multi_selection?("$and")
+        #
+        # @param [ String ] key The key to check.
+        #
+        # @return [ true | false ] If the key is for a multi-select.
+        def multi_selection?(key)
+          %w($and $or $nor).include?(key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Mongoid
+  class Criteria
+    module Queryable
+
+      # This is a smart hash for use with options and selectors.
+      class Smash < Hash
+
+        # @attribute [r] aliases The aliases.
+        attr_reader :aliases
+
+        # @attribute [r] serializers The serializers.
+        attr_reader :serializers
+
+        # @attribute [r] associations The associations.
+        attr_reader :associations
+
+        # @attribute [r] aliased_associations The aliased_associations.
+        attr_reader :aliased_associations
+
+        # Perform a deep copy of the smash.
+        #
+        # @example Perform a deep copy.
+        #   smash.__deep_copy__
+        #
+        # @return [ Smash ] The copied hash.
+        def __deep_copy__
+          self.class.new(aliases, serializers, associations, aliased_associations) do |copy|
+            each_pair do |key, value|
+              copy.store(key, value.__deep_copy__)
+            end
+          end
+        end
+
+        # Initialize the new selector.
+        #
+        # @example Initialize the new selector.
+        #   Queryable::Smash.new(aliases, serializers)
+        #
+        # @param [ Hash ] aliases A hash of mappings from aliases to the actual
+        #   field names in the database.
+        # @param [ Hash ] serializers An optional hash of objects that are
+        #   responsible for serializing values. The keys of the hash must be
+        #   strings that match the field name, and the values must respond to
+        #   #localized? and #evolve(object).
+        # @param [ Hash ] associations An optional hash of names to association
+        #   objects.
+        # @param [ Hash ] aliased_associations An optional hash of mappings from
+        #   aliases for associations to their actual field names in the database.
+        def initialize(aliases = {}, serializers = {}, associations = {}, aliased_associations = {})
+          @aliases = aliases
+          @serializers = serializers
+          @associations = associations
+          @aliased_associations = aliased_associations
+          yield(self) if block_given?
+        end
+
+        # Get an item from the smart hash by the provided key.
+        #
+        # @example Get an item by the key.
+        #   smash["test"]
+        #
+        # @param [ String ] key The key.
+        #
+        # @return [ Object ] The found object.
+        def [](key)
+          fetch(aliases[key]) { super }
+        end
+
+        private
+
+        # Get the localized value for the key if needed. If the field uses
+        # localization the current locale will be appended to the key in
+        # MongoDB dot notation.
+        #
+        # @api private
+        #
+        # @example Get the normalized key name.
+        #   smash.localized_key("field", serializer)
+        #
+        # @param [ String ] name The name of the field.
+        # @param [ Object ] serializer The optional field serializer.
+        #
+        # @return [ String ] The normalized key.
+        def localized_key(name, serializer)
+          serializer && serializer.localized? ? "#{name}.#{::I18n.locale}" : name
+        end
+
+        # Get the pair of objects needed to store the value in a hash by the
+        # provided key. This is the database field name and the serializer.
+        #
+        # @api private
+        #
+        # @example Get the name and serializer.
+        #   smash.storage_pair("id")
+        #
+        # @param [ Symbol | String ] key The key provided to the selection.
+        #
+        # @return [ Array<String, Object> ] The name of the db field and
+        #   serializer.
+        def storage_pair(key)
+          field = key.to_s
+          name = Fields.database_field_name(field, associations, aliases, aliased_associations)
+          [ name, get_serializer(name) ]
+        end
+
+        private
+
+        # Retrieves the serializer for the given name. If the name exists in
+        # the serializers hash then return that immediately, otherwise
+        # recursively look through the associations and find the appropriate
+        # field.
+        #
+        # @param [ String ] name The name of the db field.
+        #
+        # @return [ Object ] The serializer.
+        def get_serializer(name)
+          if s = serializers[name]
+            s
+          else
+            Fields.traverse_association_tree(name, serializers, associations, aliased_associations)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module Mongoid
+  class Criteria
+    module Queryable
+      # This module encapsulates methods that write query expressions into
+      # the Criteria's selector.
+      #
+      # The query expressions must have already been expanded as necessary.
+      # The methods of this module do not perform processing on expression
+      # values.
+      #
+      # Methods in this module do not handle negation - if negation is needed,
+      # it must have already been handled upstream of these methods.
+      #
+      # @api private
+      module Storable
+
+        # Adds a field expression to the query.
+        #
+        # +field+ must be a field name, and it must be a string. The upstream
+        # code must have converted other field/key types to the simple string
+        # form by the time this method is invoked.
+        #
+        # +value+ can be of any type, it is written into the selector unchanged.
+        #
+        # This method performs no processing on the provided field value.
+        #
+        # Mutates the receiver.
+        #
+        # @param [ String ] field The field name.
+        # @param [ Object ] value The field value.
+        #
+        # @return [ Storable ] self.
+        def add_field_expression(field, value)
+          unless field.is_a?(String)
+            raise ArgumentError, "Field must be a string: #{field}"
+          end
+
+          if field.start_with?('$')
+            raise ArgumentError, "Field cannot be an operator (i.e. begin with $): #{field}"
+          end
+
+          if selector[field]
+            # We already have a restriction by the field we are trying
+            # to restrict, combine the restrictions.
+            if value.is_a?(Hash) && selector[field].is_a?(Hash) &&
+              value.keys.all? { |key|
+                key_s = key.to_s
+                key_s.start_with?('$') && !selector[field].key?(key_s)
+              }
+            then
+              # Multiple operators can be combined on the same field by
+              # adding them to the existing hash.
+              new_value = selector[field].merge(value)
+              selector.store(field, new_value)
+            elsif selector[field] != value
+              add_operator_expression('$and', [{field => value}])
+            end
+          else
+            selector.store(field, value)
+          end
+
+          self
+        end
+
+        # Adds a logical operator expression to the selector.
+        #
+        # This method only handles logical operators ($and, $nor and $or).
+        # It raises ArgumentError if called with another operator. Note that
+        # in MQL, $not is a field-level operator and not a query-level one,
+        # and therefore $not is not handled by this method.
+        #
+        # This method takes the operator and the operator value expression
+        # separately for callers' convenience. It can be considered to
+        # handle storing the hash +{operator => op_expr}+.
+        #
+        # If the selector consists of a single condition which is the specified
+        # operator (on the top level), the new condition given in op_expr is
+        # added to the existing conditions for the specified operator.
+        # For example, if the selector is currently:
+        #
+        #     {'$or' => [{'hello' => 'world'}]}
+        #
+        # ... and operator is '$or' and op_expr is `[{'test' => 123'}]`,
+        # the resulting selector will be:
+        #
+        #     {'$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        #
+        # This method always adds the new conditions as additional requirements;
+        # in other words, it does not implement the ActiveRecord or/nor behavior
+        # where the receiver becomes one of the operands. It is expected that
+        # code upstream of this method implements such behavior.
+        #
+        # This method does not simplify values (i.e. if the selector is
+        # currently empty and operator is $and, op_expr is written to the
+        # selector with $and even if the $and can in principle be elided).
+        # Such simplification is also expected to have already been performed
+        # by the upstream code.
+        #
+        # This method mutates the receiver.
+        #
+        # @param [ String ] operator The operator to add.
+        # @param [ Array<Hash> ] op_expr Operator value to add.
+        #
+        # @return [ Storable ] self.
+        def add_logical_operator_expression(operator, op_expr)
+          unless operator.is_a?(String)
+            raise ArgumentError, "Operator must be a string: #{operator}"
+          end
+
+          unless %w($and $nor $or).include?(operator)
+            raise ArgumentError, "This method only handles logical operators ($and, $nor, $or). Operator given: #{operator}"
+          end
+
+          unless op_expr.is_a?(Array)
+            raise Errors::InvalidQuery, "#{operator} argument must be an array: #{Errors::InvalidQuery.truncate_expr(op_expr)}"
+          end
+
+          if selector.length == 1 && selector.keys.first == operator
+            new_value = selector.values.first + op_expr
+            selector.store(operator, new_value)
+          elsif operator == '$and' || selector.empty?
+            # $and can always be added to top level and it will be combined
+            # with whatever other conditions exist.
+            if !Mongoid.broken_and && current_value = selector[operator]
+              new_value = current_value + op_expr
+              selector.store(operator, new_value)
+            else
+              selector.store(operator, op_expr)
+            end
+          else
+            # Other operators need to be added separately
+            if selector[operator]
+              add_logical_operator_expression('$and', [operator => op_expr])
+            else
+              selector.store(operator, op_expr)
+            end
+          end
+
+          self
+        end
+
+        # Adds an operator expression to the selector.
+        #
+        # This method takes the operator and the operator value expression
+        # separately for callers' convenience. It can be considered to
+        # handle storing the hash +{operator => op_expr}+.
+        #
+        # The operator value can be of any type.
+        #
+        # If the selector already has the specified operator in it (on the
+        # top level), the new condition given in op_expr is added to the
+        # existing conditions for the specified operator. This is
+        # straightforward for $and; for other logical operators, the behavior
+        # of this method is to add the new conditions to the existing operator.
+        # For example, if the selector is currently:
+        #
+        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
+        #
+        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
+        # the resulting selector will be:
+        #
+        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        #
+        # This does not implement an OR between the existing selector and the
+        # new operator expression - handling this is the job of upstream
+        # methods. This method simply stores op_expr into the selector on the
+        # assumption that the existing selector is the correct left hand side
+        # of the operation already.
+        #
+        # For non-logical query-level operators like $where and $text, if
+        # there already is a top-level operator with the same name, the
+        # op_expr is added to the selector via a top-level $and operator,
+        # thus producing a selector having both operator values.
+        #
+        # This method does not simplify values (i.e. if the selector is
+        # currently empty and operator is $and, op_expr is written to the
+        # selector with $and even if the $and can in principle be elided).
+        #
+        # This method mutates the receiver.
+        #
+        # @param [ String ] operator The operator to add.
+        # @param [ Object ] op_expr Operator value to add.
+        #
+        # @return [ Storable ] self.
+        def add_operator_expression(operator, op_expr)
+          unless operator.is_a?(String)
+            raise ArgumentError, "Operator must be a string: #{operator}"
+          end
+
+          unless operator.start_with?('$')
+            raise ArgumentError, "Operator must begin with $: #{operator}"
+          end
+
+          if %w($and $nor $or).include?(operator)
+            return add_logical_operator_expression(operator, op_expr)
+          end
+
+          # For other operators, if the operator already exists in the
+          # query, add the new condition with $and, otherwise add the
+          # new condition to the top level.
+          if selector[operator]
+            add_logical_operator_expression('$and', [{operator => op_expr}])
+          else
+            selector.store(operator, op_expr)
+          end
+
+          self
+        end
+
+        # Adds an arbitrary expression to the query.
+        #
+        # Field can either be a field name or an operator.
+        #
+        # Mutates the receiver.
+        #
+        # @param [ String ] field Field name or operator name.
+        # @param [ Object ] value Field value or operator expression.
+        #
+        # @return [ Storable ] self.
+        def add_one_expression(field, value)
+          unless field.is_a?(String)
+            raise ArgumentError, "Field must be a string: #{field}"
+          end
+
+          if field.start_with?('$')
+            add_operator_expression(field, value)
+          else
+            add_field_expression(field, value)
+          end
+        end
+
+      end
+    end
+  end
+end