mongoid 3.1.5 → 8.0.2

data/lib/mongoid/findable.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # This module defines the finder methods that hang off the document at the
+  # class level.
+  module Findable
+    extend Forwardable
+
+    def_delegators :with_default_scope, *(
+      Criteria::Queryable::Selectable.forwardables +
+      Criteria::Queryable::Optional.forwardables
+    )
+
+    # These are methods defined on the criteria that should also be accessible
+    # directly from the class level.
+    def_delegators :with_default_scope,
+      :aggregates,
+      :avg,
+      :create_with,
+      :distinct,
+      :each,
+      :each_with_index,
+      :extras,
+      :find_one_and_delete,
+      :find_one_and_replace,
+      :find_one_and_update,
+      :find_or_create_by,
+      :find_or_create_by!,
+      :find_or_initialize_by,
+      :first_or_create,
+      :first_or_create!,
+      :first_or_initialize,
+      :for_js,
+      :geo_near,
+      :includes,
+      :map_reduce,
+      :max,
+      :min,
+      :none,
+      :pick,
+      :pluck,
+      :read,
+      :sum,
+      :take,
+      :take!,
+      :tally,
+      :text_search,
+      :update,
+      :update_all,
+
+    # Returns a count of records in the database.
+    # If you want to specify conditions use where.
+    #
+    # @example Get the count of matching documents.
+    #   Person.count
+    #   Person.where(title: "Sir").count
+    #
+    # @return [ Integer ] The number of matching documents.
+    def count
+      with_default_scope.count
+    end
+
+    # Returns an estimated count of records in the database.
+    #
+    # @example Get the count of matching documents.
+    #   Person.estimated_count
+    #
+    # @return [ Integer ] The number of matching documents.
+    def estimated_count
+      with_default_scope.estimated_count
+    end
+
+    # Returns true if count is zero
+    #
+    # @example Are there no saved documents for this model?
+    #   Person.empty?
+    #
+    # @return [ true | false ] If the collection is empty.
+    def empty?
+      count == 0
+    end
+
+    # Returns true if there are on document in database based on the
+    # provided arguments.
+    #
+    # @example Do any documents exist for the conditions?
+    #   Person.exists?
+    #
+    # @return [ true | false ] If any documents exist for the conditions.
+    def exists?
+      with_default_scope.exists?
+    end
+
+    # Finds a +Document+ or multiple documents by their _id values.
+    #
+    # If a single non-Array argument is given, this argument is interpreted
+    # as the _id value of a document to find. If there is a matching document
+    # in the database, this document is returned; otherwise, if the
+    # +raise_not_found_error+ Mongoid configuration option is truthy
+    # (which is the default), +Errors::DocumentNotFound+ is raised, and if
+    # +raise_not_found_error+ is falsy, +find+ returns +nil+.
+    #
+    # If multiple arguments are given, or an Array argument is given, the
+    # array is flattened and each array element is interpreted as the _id
+    # value of the document to find. Mongoid then attempts to retrieve all
+    # documents with the provided _id values. The return value is an array
+    # of found documents. Each document appears one time in the returned array,
+    # even if its _id is given multiple times in the argument to +find+.
+    # If the +raise_not_found_error+ Mongoid configuration option is truthy,
+    # +Errors::DocumentNotFound+ exception is raised if any of the specified
+    # _ids were not found in the database. If the ++raise_not_found_error+
+    # Mongoid configuration option is falsy, only those documents which are
+    # found are returned; if no documents are found, the return value is an
+    # empty array.
+    #
+    # Note that MongoDB does not allow the _id field to be an array.
+    #
+    # The argument undergoes customary Mongoid type conversions based on
+    # the type declared for the _id field. By default the _id field is a
+    # +BSON::ObjectId+; this allows strings to be passed to +find+ and the
+    # strings will be transparently converted to +BSON::ObjectId+ instances
+    # during query construction.
+    #
+    # If this method is given a block, it delegates to +Enumerable#find+ and
+    # returns the first document of those found by the current Crieria object
+    # for which the block returns a truthy value. If both a block and ids are
+    # given, the block is ignored and the documents for the given ids are
+    # returned. If a block and a Proc are given, the method delegates to
+    # +Enumerable#find+ and uses the proc as the default.
+    #
+    # The +find+ method takes into account the default scope defined on the
+    # model class, if any.
+    #
+    # @note Each argument can be an individual id, an array of ids or
+    #   a nested array. Each array will be flattened.
+    #
+    # @param [ Object | Array<Object> ] *args The _id value(s) to find.
+    #
+    # @return [ Document | Array<Document> | nil ] A document or matching documents.
+    #
+    # @raise Errors::DocumentNotFound If not all documents are found and
+    #   the +raise_not_found_error+ Mongoid configuration option is truthy.
+    def find(*args, &block)
+      empty_or_proc = args.empty? || (args.length == 1 && args.first.is_a?(Proc))
+      if block_given? && empty_or_proc
+        with_default_scope.find(*args, &block)
+      else
+        with_default_scope.find(*args)
+      end
+    end
+
+    # Find the first +Document+ given the conditions.
+    # If a matching Document is not found and
+    # Mongoid.raise_not_found_error is true it raises
+    # Mongoid::Errors::DocumentNotFound, return null nil elsewise.
+    #
+    # @example Find the document by attribute other than id
+    #   Person.find_by(:username => "superuser")
+    #
+    # @param [ Hash ] attrs The attributes to check.
+    #
+    # @raise [ Errors::DocumentNotFound ] If no document found
+    # and Mongoid.raise_not_found_error is true.
+    #
+    # @return [ Document | nil ] A matching document.
+    def find_by(attrs = {})
+      result = where(attrs).find_first
+      if result.nil? && Mongoid.raise_not_found_error
+        raise(Errors::DocumentNotFound.new(self, attrs))
+      end
+      yield(result) if result && block_given?
+      result
+    end
+
+    # Find the first +Document+ given the conditions, or raises
+    # Mongoid::Errors::DocumentNotFound
+    #
+    # @example Find the document by attribute other than id
+    #   Person.find_by(:username => "superuser")
+    #
+    # @param [ Hash ] attrs The attributes to check.
+    #
+    # @raise [ Errors::DocumentNotFound ] If no document found.
+    #
+    # @return [ Document ] A matching document.
+    def find_by!(attrs = {})
+      result = where(attrs).find_first
+      raise(Errors::DocumentNotFound.new(self, attrs)) unless result
+      yield(result) if result && block_given?
+      result
+    end
+
+    # Find the first +Document+ given the conditions.
+    #
+    # @example Find the first document.
+    #   Person.first
+    #
+    # @param [ Integer ] limit The number of documents to return.
+    #
+    # @return [ Document ] The first matching document.
+    def first(limit = nil)
+      with_default_scope.first(limit)
+    end
+    alias :one :first
+
+    # Find the last +Document+ given the conditions.
+    #
+    # @example Find the last document.
+    #   Person.last
+    #
+    # @param [ Integer ] limit The number of documents to return.
+    #
+    # @return [ Document ] The last matching document.
+    def last(limit = nil)
+      with_default_scope.last(limit)
+    end
+  end
+end

data/lib/mongoid/indexable/specification.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Indexable
+
+    # Encapsulates behavior around an index specification.
+    class Specification
+
+      # The mappings of nice Ruby-style names to the corresponding driver
+      # option name.
+      MAPPINGS = {
+        expire_after_seconds: :expire_after
+      }
+
+      # @!attribute klass
+      #   @return [ Class ] The class the index is defined on.
+      # @!attribute key
+      #   @return [ Hash ] The index key.
+      # @!attribute options
+      #   @return [ Hash ] The index options.
+      attr_reader :klass, :key, :fields, :options
+
+      # Is this index specification equal to another?
+      #
+      # @example Check equality of the specifications.
+      #   specification == other
+      #
+      # @param [ Specification ] other The spec to compare against.
+      #
+      # @return [ true | false ] If the specs are equal.
+      def ==(other)
+        fields == other.fields && key == other.key
+      end
+
+      # Instantiate a new index specification.
+      #
+      # @example Create the new specification.
+      #   Specification.new(Band, { name: 1 }, background: true)
+      #
+      # @param [ Class ] klass The class the index is defined on.
+      # @param [ Hash ] key The hash of name/direction pairs.
+      # @param [ Hash ] opts the index options.
+      def initialize(klass, key, opts = nil)
+        options = opts || {}
+        Validators::Options.validate(klass, key, options)
+        @klass = klass
+        @key = normalize_key(key)
+        @fields = @key.keys
+        @options = normalize_options(options.dup)
+      end
+
+      # Get the index name, generated using the index key.
+      #
+      # @example Get the index name.
+      #   specification.name
+      #
+      # @return [ String ] name The index name.
+      def name
+        @name ||= key.reduce([]) do |n, (k,v)|
+          n << "#{k}_#{v}"
+        end.join('_')
+      end
+
+      private
+
+      # Normalize the spec, in case aliased fields are provided.
+      #
+      # @api private
+      #
+      # @example Normalize the spec.
+      #   specification.normalize_key(name: 1)
+      #
+      # @param [ Hash ] key The index key(s).
+      #
+      # @return [ Hash ] The normalized specification.
+      def normalize_key(key)
+        normalized = {}
+        key.each_pair do |name, direction|
+          normalized[klass.database_field_name(name).to_sym] = direction
+        end
+        normalized
+      end
+
+      # Normalize the index options, if any are provided.
+      #
+      # @api private
+      #
+      # @example Normalize the index options.
+      #   specification.normalize_options(unique: true)
+      #
+      # @param [ Hash ] opts The index options.
+      #
+      # @return [ Hash ] The normalized options.
+      def normalize_options(opts)
+        options = {}
+        opts.each_pair do |option, value|
+          options[MAPPINGS[option] || option] = value
+        end
+        options
+      end
+    end
+  end
+end

data/lib/mongoid/indexable/validators/options.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Indexable
+    module Validators
+
+      # Validates the options passed to the index macro.
+      module Options
+        extend self
+
+        VALID_OPTIONS = [
+          :background,
+          :database,
+          :default_language,
+          :language_override,
+          :name,
+          :sparse,
+          :unique,
+          :max,
+          :min,
+          :bits,
+          :bucket_size,
+          :expire_after_seconds,
+          :weights,
+          :storage_engine,
+          :key,
+          :sphere_version,
+          :text_version,
+          :version,
+          :partial_filter_expression,
+          :collation,
+          :wildcard_projection,
+        ]
+
+        VALID_TYPES = [
+          1,
+          -1,
+          "2d",
+          "2dsphere",
+          "geoHaystack",
+          "text",
+          "hashed"
+        ]
+
+        # Validate the index specification.
+        #
+        # @example Validate the index spec.
+        #   Options.validate(Band, name: 1)
+        #
+        # @param [ Class ] klass The model class.
+        # @param [ Hash ] spec The index specification.
+        # @param [ Hash ] options The index options.
+        #
+        # @raise [ Errors::InvalidIndex ] If validation failed.
+        def validate(klass, spec, options)
+          validate_spec(klass, spec, options)
+          validate_options(klass, spec, options)
+        end
+
+        private
+
+        # Validates the options of the index spec.
+        #
+        # @api private
+        #
+        # @example Validate the options.
+        #   Options.validate_options(Band, name: 1)
+        #
+        # @param [ Class ] klass The model class.
+        # @param [ Hash ] spec The index specification.
+        # @param [ Hash ] options The index options.
+        #
+        # @raise [ Errors::InvalidIndex ] If validation failed.
+        def validate_options(klass, spec, options)
+          options.each_pair do |name, value|
+            unless VALID_OPTIONS.include?(name)
+              raise Errors::InvalidIndex.new(klass, spec, options)
+            end
+          end
+        end
+
+        # Validates the index spec.
+        #
+        # @api private
+        #
+        # @example Validate the spec.
+        #   Options.validate_spec(Band, name: 1)
+        #
+        # @param [ Class ] klass The model class.
+        # @param [ Hash ] spec The index specification.
+        # @param [ Hash ] options The index options.
+        #
+        # @raise [ Errors::InvalidIndex ] If validation failed.
+        def validate_spec(klass, spec, options)
+          raise Errors::InvalidIndex.new(klass, spec, options) if !spec.is_a?(::Hash)
+          spec.each_pair do |name, value|
+            next if name == :options
+            unless VALID_TYPES.include?(value)
+              raise Errors::InvalidIndex.new(klass, spec, options)
+            end
+
+            if value == "geoHaystack"
+              Mongoid::Warnings.warn_geo_haystack_deprecated
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/indexable.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "mongoid/indexable/specification"
+require "mongoid/indexable/validators/options"
+require "ostruct"
+
+module Mongoid
+
+  # Encapsulates behavior around defining indexes.
+  module Indexable
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_accessor :index_specifications
+      self.index_specifications = []
+    end
+
+    module ClassMethods
+
+      # Send the actual index creation comments to the MongoDB driver
+      #
+      # @example Create the indexes for the class.
+      #   Person.create_indexes
+      #
+      # @return [ true ] If the operation succeeded.
+      def create_indexes
+        return unless index_specifications
+
+        default_options = {background: Config.background_indexing}
+
+        index_specifications.each do |spec|
+          key, options = spec.key, default_options.merge(spec.options)
+          if database = options[:database]
+            with(database: database) do |klass|
+              klass.collection.indexes(session: _session).create_one(key, options.except(:database))
+            end
+          else
+            collection.indexes(session: _session).create_one(key, options)
+          end
+        end and true
+      end
+
+      # Send the actual index removal comments to the MongoDB driver,
+      # but lets _id untouched.
+      #
+      # @example Remove the indexes for the class.
+      #   Person.remove_indexes
+      #
+      # @return [ true ] If the operation succeeded.
+      def remove_indexes
+        indexed_database_names.each do |database|
+          with(database: database) do |klass|
+            begin
+              klass.collection.indexes(session: _session).each do |spec|
+                unless spec["name"] == "_id_"
+                  klass.collection.indexes(session: _session).drop_one(spec["key"])
+                  logger.info(
+                    "MONGOID: Removed index '#{spec["name"]}' on collection " +
+                    "'#{klass.collection.name}' in database '#{database}'."
+                  )
+                end
+              end
+            rescue Mongo::Error::OperationFailure; end
+          end
+        end and true
+      end
+
+      # Add the default indexes to the root document if they do not already
+      # exist. Currently this is only _type.
+      #
+      # @example Add Mongoid internal indexes.
+      #   Person.add_indexes
+      #
+      # @return [ true ] If the operation succeeded.
+      def add_indexes
+        if hereditary? && !index_keys.include?(self.discriminator_key.to_sym => 1)
+          index({ self.discriminator_key.to_sym => 1 }, unique: false, background: true)
+        end
+        true
+      end
+
+      # Adds an index definition for the provided single or compound keys.
+      #
+      # @example Create a basic index.
+      #   class Person
+      #     include Mongoid::Document
+      #     field :name, type: String
+      #     index({ name: 1 }, { background: true })
+      #   end
+      #
+      # @param [ Hash ] spec The index spec.
+      # @param [ Hash ] options The index options.
+      #
+      # @return [ Hash ] The index options.
+      def index(spec, options = nil)
+        specification = Specification.new(self, spec, options)
+        if !index_specifications.include?(specification)
+          index_specifications.push(specification)
+        end
+      end
+
+      # Get an index specification for the provided key.
+      #
+      # @example Get the index specification.
+      #   Model.index_specification(name: 1)
+      #
+      # @param [ Hash ] index_hash The index key/direction pair.
+      # @param [ String ] index_name The index name.
+      #
+      # @return [ Specification ] The found specification.
+      def index_specification(index_hash, index_name = nil)
+        index = OpenStruct.new(fields: index_hash.keys, key: index_hash)
+        index_specifications.detect do |spec|
+          spec == index || (index_name && index_name == spec.name)
+        end
+      end
+
+      private
+
+      # Get the names of all databases for this model that have index
+      # definitions.
+      #
+      # @api private
+      #
+      # @example Get the indexed database names.
+      #   Model.indexed_database_names
+      #
+      # @return [ Array<String> ] The names.
+      def indexed_database_names
+        index_specifications.map do |spec|
+          spec.options[:database] || database_name
+        end.uniq
+      end
+
+      # Gets a list of index specification keys.
+      #
+      # @api private
+      #
+      # @example Get the specification key list.
+      #   Model.index_keys
+      #
+      # @return [ Array<Hash> ] The specification keys.
+      def index_keys
+        index_specifications.map(&:key)
+      end
+    end
+  end
+end

data/lib/mongoid/inspectable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # Contains the behavior around inspecting documents via inspect.
+  module Inspectable
+
+    # Returns the class name plus its attributes. If using dynamic fields will
+    # include those as well.
+    #
+    # @example Inspect the document.
+    #   person.inspect
+    #
+    # @return [ String ] A nice pretty string to look at.
+    def inspect
+      inspection = []
+      inspection.concat(inspect_fields).concat(inspect_dynamic_fields)
+      "#<#{self.class.name} _id: #{_id}, #{inspection * ', '}>"
+    end
+
+    private
+
+    # Get an array of inspected fields for the document.
+    #
+    # @api private
+    #
+    # @example Inspect the defined fields.
+    #   document.inspect_fields
+    #
+    # @return [ String ] An array of pretty printed field values.
+    def inspect_fields
+      fields.map do |name, field|
+        unless name == "_id"
+          as = field.options[:as]
+          "#{name}#{as ? "(#{as})" : nil}: #{@attributes[name].inspect}"
+        end
+      end.compact
+    end
+
+    # Get an array of inspected dynamic fields for the document.
+    #
+    # @api private
+    #
+    # @example Inspect the dynamic fields.
+    #   document.inspect_dynamic_fields
+    #
+    # @return [ String ] An array of pretty printed dynamic field values.
+    def inspect_dynamic_fields
+      []
+    end
+  end
+end