mongoid 8.0.10 → 8.1.0

data/lib/mongoid/contextual/none.rb

@@ -80,15 +80,24 @@ module Mongoid
       # @example Do any documents exist in the null context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
       # @return [ false ] Always false.
-      def exists?; false; end
+      def exists?(id_or_conditions = :none); false; end
 
       # Pluck the field values in null context.
       #
       # @example Get the values for null context.
       #   context.pluck(:name)
       #
-      # @param [ String | Symbol ] *_fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pluck.
       #
       # @return [ Array ] An empty Array.
       def pluck(*_fields)
@@ -100,9 +109,9 @@ module Mongoid
       # @example Get the value for null context.
       #   context.pick(:name)
       #
-      # @param [ String | Symbol ] *_fields Field or fields to pick.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pick.
       #
-      # @return [ nil ] Always reeturn nil.
+      # @return [ nil ] Always return nil.
       def pick(*_fields)
         nil
       end
@@ -136,11 +145,21 @@ module Mongoid
       #
       # @param [ Integer ] limit The number of documents to return.
       #
-      # @return [ nil ] Always nil.
+      # @return [ [] | nil ] Empty array or nil.
       def first(limit = nil)
         [] unless limit.nil?
       end
 
+      # Always raises an error.
+      #
+      # @example Get the first document in null context.
+      #   context.first!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def first!
+        raise_document_not_found_error
+      end
+
       # Always returns nil.
       #
       # @example Get the last document in null context.
@@ -148,11 +167,21 @@ module Mongoid
       #
       # @param [ Integer ] limit The number of documents to return.
       #
-      # @return [ nil ] Always nil.
+      # @return [ [] | nil ] Empty array or nil.
       def last(limit = nil)
         [] unless limit.nil?
       end
 
+      # Always raises an error.
+      #
+      # @example Get the last document in null context.
+      #   context.last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def last!
+        raise_document_not_found_error
+      end
+
       # Returns nil or empty array.
       #
       # @example Take a document in null context.
@@ -172,7 +201,127 @@ module Mongoid
       #
       # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
       def take!
-        raise Errors::DocumentNotFound.new(klass, nil, nil)
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the second document in null context.
+      #   context.second
+      #
+      # @return [ nil ] Always nil.
+      def second
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the second document in null context.
+      #   context.second!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def second!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the third document in null context.
+      #   context.third
+      #
+      # @return [ nil ] Always nil.
+      def third
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the third document in null context.
+      #   context.third!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def third!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the fourth document in null context.
+      #   context.fourth
+      #
+      # @return [ nil ] Always nil.
+      def fourth
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the fourth document in null context.
+      #   context.fourth!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def fourth!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the fifth document in null context.
+      #   context.fifth
+      #
+      # @return [ nil ] Always nil.
+      def fifth
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the fifth document in null context.
+      #   context.fifth!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def fifth!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the second to last document in null context.
+      #   context.second_to_last
+      #
+      # @return [ nil ] Always nil.
+      def second_to_last
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the second to last document in null context.
+      #   context.second_to_last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def second_to_last!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the third to last document in null context.
+      #   context.third_to_last
+      #
+      # @return [ nil ] Always nil.
+      def third_to_last
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the third to last document in null context.
+      #   context.third_to_last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def third_to_last!
+        raise_document_not_found_error
       end
 
       # Always returns zero.
@@ -188,6 +337,12 @@ module Mongoid
 
       alias :find_first :first
       alias :one :first
+
+      private
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
     end
   end
 end

data/lib/mongoid/contextual.rb

@@ -35,6 +35,18 @@ module Mongoid
       @context ||= create_context
     end
 
+    # Instructs the context to schedule an asynchronous loading of documents
+    # specified by the criteria.
+    #
+    # Note that depending on the context and on the Mongoid configuration,
+    # documents can be loaded synchronously on the caller's thread.
+    #
+    # @return [ Criteria ] Returns self.
+    def load_async
+      context.load_async if context.respond_to?(:load_async)
+      self
+    end
+
     private
 
     # Create the context for the queries to execute. Will be memory for

data/lib/mongoid/criteria/findable.rb

@@ -21,7 +21,7 @@ module Mongoid
         multi ? result : result.first
       end
 
-      # Find the matchind document(s) in the criteria for the provided ids.
+      # Find the matching document(s) in the criteria for the provided id(s).
       #
       # @note Each argument can be an individual id, an array of ids or
       #   a nested array. Each array will be flattened.
@@ -32,7 +32,7 @@ module Mongoid
       # @example Find by multiple ids.
       #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
       #
-      # @param [ Object | Array<Object> ] *args The ids to search for.
+      # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
       #
       # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)

data/lib/mongoid/criteria/includable.rb

@@ -21,8 +21,8 @@ module Mongoid
       # @example Eager load the provided associations.
       #   Person.includes(:posts, :game)
       #
-      # @param [ Array<Symbol>, Array<Hash> ] relations The names of the associations to eager
-      #   load.
+      # @param [ [ Symbol | Hash ]... ] *relations The names of the association(s)
+      #   to eager load.
       #
       # @return [ Criteria ] The cloned criteria.
       def includes(*relations)
@@ -70,7 +70,8 @@ module Mongoid
       #   association originates.
       # @param [ String ] parent The name of the association above this one in
       #   the inclusion tree, if it is a nested inclusion.
-      # @param relations_list The names of the associations to eager load.
+      # @param [ [ Symbol | Hash | Array<Symbol | Hash> ]... ] *relations_list
+      #   The names of the association(s) to eager load.
       def extract_includes_list(_parent_class, parent, *relations_list)
         relations_list.flatten.each do |relation_object|
           if relation_object.is_a?(Hash)

data/lib/mongoid/criteria/queryable/extensions/numeric.rb

@@ -43,21 +43,7 @@ module Mongoid
             #
             # @return [ Object ] The converted number.
             def __numeric__(object)
-              str = object.to_s
-              raise ArgumentError if str.empty?
-
-              # These requirements seem a bit odd, but they're explicitly specified in the tests,
-              # so we're obligated to keep them, for now. (This code was rewritten from a one-line
-              # regex, due to security concerns with a polynomial regex being used on uncontrolled
-              # data).
-
-              str = str.chop if str.end_with?('.')
-              return 0 if str.empty?
-
-              result = Integer(str) rescue Float(object)
-
-              integer = result.to_i
-              integer == result ? integer : result
+              object.to_s.match?(/\A[-+]?[0-9]*[0-9.]0*\z/) ? object.to_i : Float(object)
             end
 
             # Evolve the object to an integer.

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

@@ -91,7 +91,7 @@ module Mongoid
 
         # Calculate the hash code for a key.
         #
-        # @return [ Fixnum ] The hash code for the key.
+        # @return [ Integer ] The hash code for the key.
         def hash
           [name, operator, expanded].hash
         end

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

@@ -283,7 +283,7 @@ module Mongoid
                     # 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://docs.mongodb.com/manual/reference/operator/query/eq/#std-label-eq-usage-examples
+                    # 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

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

@@ -17,7 +17,7 @@ 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.
         def ascending(*fields)
@@ -45,7 +45,7 @@ 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.
         def descending(*fields)
@@ -123,7 +123,7 @@ 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.
         def only(*args)
@@ -163,7 +163,7 @@ 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.
         def order_by(*spec)
@@ -184,7 +184,7 @@ 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.
         def reorder(*spec)
@@ -245,7 +245,7 @@ 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.
         def without(*args)
@@ -331,7 +331,7 @@ 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.
         def option(*args)
@@ -349,7 +349,7 @@ 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.

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

@@ -31,7 +31,7 @@ module Mongoid
         # @example Execute an $all in a where query.
         #   selectable.where(:field.all => [ 1, 2 ])
         #
-        # @param [ Hash ] criterion The key value pairs for $all matching.
+        # @param [ Hash... ] *criteria The key value pair(s) for $all matching.
         #
         # @return [ Selectable ] The cloned selectable.
         def all(*criteria)
@@ -69,8 +69,9 @@ module Mongoid
         # @example Add the criterion.
         #   selectable.and({ field: value }, { other: value })
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects that all must match to return results.
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
+        #   Multiple key/value pair matches or Criteria objects that all must
+        #   match to return results.
         #
         # @return [ Selectable ] The new selectable.
         def and(*criteria)
@@ -199,7 +200,7 @@ module Mongoid
         #   the upper right (north east) as the second argument.
         #   Important: When latitude and longitude are passed, longitude is
         #   expected as the first element of the coordinate pair.
-        #   Source: https://docs.mongodb.com/manual/reference/operator/query/box/
+        #   Source: https://www.mongodb.com/docs/manual/reference/operator/query/box/
         #
         # @example Add a geo intersect criterion for a line.
         #   query.geo_spatial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])
@@ -516,8 +517,8 @@ module Mongoid
         # @example Add the $nor selection.
         #   selectable.nor(field: 1, field: 2)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects.
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
+        #   Multiple key/value pair matches or Criteria objects.
         #
         # @return [ Selectable ] The new selectable.
         def nor(*criteria)
@@ -545,7 +546,7 @@ module Mongoid
         # @example Execute a $not in a where query.
         #   selectable.where(:field.not => /Bob/)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
         #   matches or Criteria objects to negate.
         #
         # @return [ Selectable ] The new selectable.
@@ -580,6 +581,35 @@ module Mongoid
         end
         key :not, :override, "$not"
 
+        # Negate the arguments, constraining the query to only those documents
+        # that do NOT match the arguments.
+        #
+        # @example Exclude a single criterion.
+        #   selectable.none_of(name: /Bob/)
+        #
+        # @example Exclude multiple criteria.
+        #   selectable.none_of(name: /Bob/, country: "USA")
+        #
+        # @example Exclude multiple criteria as an array.
+        #   selectable.none_of([{ name: /Bob/ }, { country: "USA" }])
+        #
+        # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
+        #   matches or Criteria objects to negate.
+        #
+        # @return [ Selectable ] The new selectable.
+        def none_of(*criteria)
+          criteria = _mongoid_flatten_arrays(criteria)
+          return dup if criteria.empty?
+
+          exprs = criteria.map do |criterion|
+            _mongoid_expand_keys(
+                criterion.is_a?(Selectable) ?
+                  criterion.selector : criterion)
+          end
+
+          self.and('$nor' => exprs)
+        end
+
         # Creates a disjunction using $or from the existing criteria in the
         # receiver and the provided arguments.
         #
@@ -605,7 +635,7 @@ module Mongoid
         # @example Same as previous example, also deprecated.
         #   selectable.or([{field: 1}], [{field: 2}])
         #
-        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
         #   Multiple key/value pair matches or Criteria objects, or arrays
         #   thereof. Passing arrays is deprecated.
         #
@@ -635,7 +665,7 @@ module Mongoid
         # @example Same as previous example, also deprecated.
         #   selectable.any_of([{field: 1}], [{field: 2}])
         #
-        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
         #   Multiple key/value pair matches or Criteria objects, or arrays
         #   thereof. Passing arrays is deprecated.
         #
@@ -731,7 +761,7 @@ module Mongoid
         # @example Construct a text search selector with options.
         #   selectable.text_search("testing", :$language => "fr")
         #
-        # @note Per https://docs.mongodb.com/manual/reference/operator/query/text/
+        # @note Per https://www.mongodb.com/docs/manual/reference/operator/query/text/
         #   it is not currently possible to supply multiple text search
         #   conditions in a query. Mongoid will build such a query but the
         #   server will return an error when trying to execute it.
@@ -751,7 +781,7 @@ module Mongoid
             criterion = {'$text' => { '$search' => terms }}
             criterion['$text'].merge!(opts) if opts
             if query.selector['$text']
-              # Per https://docs.mongodb.com/manual/reference/operator/query/text/
+              # Per https://www.mongodb.com/docs/manual/reference/operator/query/text/
               # multiple $text expressions are not currently supported by
               # MongoDB server, but build the query correctly instead of
               # overwriting previous text search condition with the currently
@@ -774,7 +804,8 @@ module Mongoid
         # @example Add a javascript selection.
         #   selectable.where("this.name == 'syd'")
         #
-        # @param [ String | Hash ] criterion The javascript or standard selection.
+        # @param [ [ Hash | String ]... ] *criterion The standard selection
+        #   or javascript string.
         #
         # @return [ Selectable ] The cloned selectable.
         def where(*criteria)

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

@@ -20,7 +20,7 @@ module Mongoid
           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.to_s
+                case _key
                 when '$in'
                   new_val & old_val
                 when '$nin'

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

@@ -47,7 +47,7 @@ module Mongoid
             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].keys.map(&:to_s).include?(key_s)
+                key_s.start_with?('$') && !selector[field].key?(key_s)
               }
             then
               # Multiple operators can be combined on the same field by

data/lib/mongoid/criteria.rb

@@ -89,7 +89,7 @@ module Mongoid
     # @example Tries to find a document whose _id is the stringification of the provided Proc, typically failing.
     #   enumerator = criteria.find(-> { "Default Band" })
     #
-    # @param [ Object | Array<Object> ] *args The ids.
+    # @param [ [ Object | Array<Object> ]... ] *args The id(s).
     # @param [ Proc ] block Optional block to pass.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
@@ -285,7 +285,7 @@ module Mongoid
     # @example Limit the fields returned from the database.
     #   Band.only(:name)
     #
-    # @param [ Array<Symbol> ] args The names of the fields.
+    # @param [ [ Symbol | Array<Symbol> ]... ] *args The field name(s).
     #
     # @return [ Criteria ] The cloned criteria.
     def only(*args)
@@ -319,7 +319,7 @@ module Mongoid
     # @example Exclude fields returned from the database.
     #   Band.without(:name)
     #
-    # @param [ Array<Symbol> ] args The names of the fields.
+    # @param [ Symbol... ] *args The field name(s).
     #
     # @return [ Criteria ] The cloned criteria.
     def without(*args)
@@ -386,7 +386,8 @@ module Mongoid
     # @example Add a javascript selection.
     #   criteria.where("this.name == 'syd'")
     #
-    # @param [ String | Hash ] expression The javascript or standard selection.
+    # @param [ [ Hash | String ]... ] *args The standard selection
+    #   or javascript string.
     #
     # @raise [ UnsupportedJavascript ] If provided a string and the criteria
     #   is embedded.
@@ -496,7 +497,7 @@ module Mongoid
     #   criteria.method_missing(:name)
     #
     # @param [ Symbol ] name The method name.
-    # @param [ Array ] args The arguments.
+    # @param [ Object... ] *args The arguments.
     #
     # @return [ Object ] The result of the method call.
     ruby2_keywords def method_missing(name, *args, &block)

data/lib/mongoid/deprecable.rb

@@ -27,8 +27,7 @@ module Mongoid
     # @param [ [ Symbol | Hash<Symbol, [ Symbol | String ]> ]... ] *method_descriptors
     #   The methods to deprecate, with optional replacement instructions.
     def deprecate(target_module, *method_descriptors)
-      @_deprecator ||= Mongoid::Deprecation.new
-      @_deprecator.deprecate_methods(target_module, *method_descriptors)
+      Mongoid::Deprecation.deprecate_methods(target_module, *method_descriptors)
     end
   end
 end

data/lib/mongoid/deprecation.rb

@@ -15,10 +15,10 @@ module Mongoid
     #
     # @return Array<Proc> The deprecation behavior.
     def behavior
-      @behavior ||= Array(->(*args) {
+      @behavior ||= Array(->(message, callstack, _deprecation_horizon, _gem_name) {
         logger = Mongoid.logger
-        logger.warn(args[0])
-        logger.debug(args[1].join("\n  ")) if debug
+        logger.warn(message)
+        logger.debug(callstack.join("\n  ")) if debug
       })
     end
   end

data/lib/mongoid/document.rb

@@ -133,14 +133,7 @@ module Mongoid
     #
     # @return [ Hash ] A hash of all attributes in the hierarchy.
     def as_document
-      attrs = as_attributes
-
-      # legacy attributes have a tendency to leak internal state via
-      # `as_document`; we have to deep_dup the attributes here to prevent
-      # that.
-      attrs = attrs.deep_dup if Mongoid.legacy_attributes
-
-      BSON::Document.new(attrs)
+      BSON::Document.new(as_attributes)
     end
 
     # Calls #as_json on the document with additional, Mongoid-specific options.

data/lib/mongoid/errors/create_collection_failure.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to create a collection failed.
+    class CreateCollectionFailure < MongoidError
+
+      # Instantiate the create collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to create.
+      # @param [ Hash ] collection_options The options that were used when
+      #   tried to create the collection.
+      # @param [ Mongo::Error::OperationFailure ] error The error raised when
+      #   tried to create the collection.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "create_collection_failure",
+                {
+                  collection_name: collection_name,
+                  collection_options: collection_options,
+                  error: "#{error.class}: #{error.message}"
+                }
+            )
+        )
+      end
+    end
+  end
+end