mongoid 3.1.5 → 8.0.2

data/lib/mongoid/scopable.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # This module contains behavior for all Mongoid scoping - named scopes,
+  # default scopes, and criteria accessors via scoped and unscoped.
+  module Scopable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :default_scoping
+      class_attribute :_declared_scopes
+      self._declared_scopes = {}
+    end
+
+    private
+
+    # Apply the default scoping to the attributes of the document, as long as
+    # they are not complex queries.
+    #
+    # @api private
+    #
+    # @example Apply the default scoping.
+    #   document.apply_default_scoping
+    #
+    # @return [ true | false ] If default scoping was applied.
+    def apply_default_scoping
+      if default_scoping
+        default_scoping.call.selector.each do |field, value|
+          attributes[field] = value unless value.respond_to?(:each)
+        end
+      end
+    end
+
+    module ClassMethods
+
+      # Returns a hash of all the scopes defined for this class, including
+      # scopes defined on ancestor classes.
+      #
+      # @example Get the defined scopes for a class
+      #   class Band
+      #     include Mongoid::Document
+      #     field :active, type: Boolean
+      #
+      #     scope :active, -> { where(active: true) }
+      #   end
+      #   Band.scopes
+      #
+      # @return [ Hash ] The scopes defined for this class
+      def scopes
+        defined_scopes = {}
+        ancestors.reverse.each do |klass|
+          if klass.respond_to?(:_declared_scopes)
+            defined_scopes.merge!(klass._declared_scopes)
+          end
+        end
+        defined_scopes.freeze
+      end
+
+      # Add a default scope to the model. This scope will be applied to all
+      # criteria unless #unscoped is specified.
+      #
+      # @example Define a default scope with a criteria.
+      #   class Band
+      #     include Mongoid::Document
+      #     field :active, type: Boolean
+      #     default_scope where(active: true)
+      #   end
+      #
+      # @example Define a default scope with a proc.
+      #   class Band
+      #     include Mongoid::Document
+      #     field :active, type: Boolean
+      #     default_scope ->{ where(active: true) }
+      #   end
+      #
+      # @param [ Proc | Criteria ] value The default scope.
+      #
+      # @raise [ Errors::InvalidScope ] If the scope is not a proc or criteria.
+      #
+      # @return [ Proc ] The default scope.
+      def default_scope(value = nil)
+        value = Proc.new { yield } if block_given?
+        check_scope_validity(value)
+        self.default_scoping = process_default_scope(value)
+      end
+
+      # Is the class able to have the default scope applied?
+      #
+      # @example Can the default scope be applied?
+      #   Band.default_scopable?
+      #
+      # @return [ true | false ] If the default scope can be applied.
+      def default_scopable?
+        default_scoping? && !Threaded.without_default_scope?(self)
+      end
+
+      # Get a queryable, either the last one on the scope stack or a fresh one.
+      #
+      # @api private
+      #
+      # @example Get a queryable.
+      #   Model.queryable
+      #
+      # @return [ Criteria ] The queryable.
+      def queryable
+        crit = Threaded.current_scope(self) || Criteria.new(self)
+        crit.embedded = true if (crit.klass.embedded? && !crit.klass.cyclic?)
+        crit
+      end
+
+      # Create a scope that can be accessed from the class level or chained to
+      # criteria by the provided name.
+      #
+      # @example Create named scopes.
+      #
+      #   class Person
+      #     include Mongoid::Document
+      #     field :active, type: Boolean
+      #     field :count, type: Integer
+      #
+      #     scope :active, -> { where(active: true) }
+      #     scope :at_least, ->(count){ where(:count.gt => count) }
+      #   end
+      #
+      # @param [ Symbol ] name The name of the scope.
+      # @param [ Proc ] value The conditions of the scope.
+      #
+      # @raise [ Errors::InvalidScope ] If the scope is not a proc.
+      # @raise [ Errors::ScopeOverwrite ] If the scope name already exists.
+      def scope(name, value, &block)
+        normalized = name.to_sym
+        check_scope_validity(value)
+        check_scope_name(normalized)
+        _declared_scopes[normalized] = {
+          scope: value,
+          extension: Module.new(&block)
+        }
+        define_scope_method(normalized)
+      end
+
+      # Get a criteria for the document with normal scoping.
+      #
+      # @example Get the criteria.
+      #   Band.scoped(skip: 10)
+      #
+      # @note This will force the default scope to be applied.
+      #
+      # @param [ Hash ] options Query options for the criteria.
+      #
+      # @option options [ Integer ] :skip Optional number of documents to skip.
+      # @option options [ Integer ] :limit Optional number of documents to
+      #   limit.
+      # @option options [ Array ] :sort Optional sorting options.
+      #
+      # @return [ Criteria ] A scoped criteria.
+      def scoped(options = nil)
+        queryable.scoped(options)
+      end
+
+      # Get the criteria without the default scoping applied.
+      #
+      # @example Get the unscoped criteria.
+      #   Band.unscoped
+      #
+      # @example Yield to block with no default scoping.
+      #   Band.unscoped do
+      #     Band.where(name: "Depeche Mode")
+      #   end
+      #
+      # @note This will force the default scope to be removed.
+      #
+      # @return [ Criteria | Object ] The unscoped criteria or result of the
+      #   block.
+      def unscoped
+        if block_given?
+          without_default_scope do
+            yield(self)
+          end
+        else
+          queryable.unscoped
+        end
+      end
+
+      # Get a criteria with the default scope applied, if possible.
+      #
+      # @example Get a criteria with the default scope.
+      #   Model.with_default_scope
+      #
+      # @return [ Criteria ] The criteria.
+      def with_default_scope
+        queryable.with_default_scope
+      end
+      alias :criteria :with_default_scope
+
+      # Pushes the provided criteria onto the scope stack, and removes it after the
+      # provided block is yielded.
+      #
+      # @example Yield to the criteria.
+      #   Person.with_scope(criteria)
+      #
+      # @param [ Criteria ] criteria The criteria to apply.
+      #
+      # @return [ Criteria ] The yielded criteria.
+      def with_scope(criteria)
+        previous = Threaded.current_scope(self)
+        Threaded.set_current_scope(criteria, self)
+        begin
+          yield criteria
+        ensure
+          if Mongoid.broken_scoping
+            Threaded.set_current_scope(nil, self)
+          else
+            Threaded.set_current_scope(previous, self)
+          end
+        end
+      end
+
+      # Execute the block without applying the default scope.
+      #
+      # @example Execute without the default scope.
+      #   Band.without_default_scope do
+      #     Band.where(name: "Depeche Mode")
+      #   end
+      #
+      # @return [ Object ] The result of the block.
+      def without_default_scope
+        Threaded.begin_without_default_scope(self)
+        yield
+      ensure
+        Threaded.exit_without_default_scope(self)
+      end
+
+      private
+
+      # Warns or raises exception if overriding another scope or method.
+      #
+      # @api private
+      #
+      # @example Warn or raise error if name exists.
+      #   Model.valid_scope_name?("test")
+      #
+      # @param [ String | Symbol ] name The name of the scope.
+      #
+      # @raise [ Errors::ScopeOverwrite ] If the name exists and configured to
+      #   raise the error.
+      def check_scope_name(name)
+        if _declared_scopes[name] || respond_to?(name, true)
+          if Mongoid.scope_overwrite_exception
+            raise Errors::ScopeOverwrite.new(self.name, name)
+          else
+            if Mongoid.logger
+              Mongoid.logger.warn(
+                "Creating scope :#{name}. " +
+                "Overwriting existing method #{self.name}.#{name}."
+              )
+            end
+          end
+        end
+      end
+
+      # Checks if the intended scope is a valid object, either a criteria or
+      # proc with a criteria.
+      #
+      # @api private
+      #
+      # @example Check if the scope is valid.
+      #   Model.check_scope_validity({})
+      #
+      # @param [ Object ] value The intended scope.
+      #
+      # @raise [ Errors::InvalidScope ] If the scope is not a valid object.
+      def check_scope_validity(value)
+        unless value.respond_to?(:call)
+          raise Errors::InvalidScope.new(self, value)
+        end
+      end
+
+      # Defines the actual class method that will execute the scope when
+      # called.
+      #
+      # @api private
+      #
+      # @example Define the scope class method.
+      #   Model.define_scope_method(:active)
+      #
+      # @param [ Symbol ] name The method/scope name.
+      #
+      # @return [ Method ] The defined method.
+      def define_scope_method(name)
+        singleton_class.class_eval do
+          ruby2_keywords(
+            define_method(name) do |*args|
+              scoping = _declared_scopes[name]
+              scope = instance_exec(*args, &scoping[:scope])
+              extension = scoping[:extension]
+              to_merge = scope || queryable
+              criteria = to_merge.empty_and_chainable? ? to_merge : with_default_scope.merge(to_merge)
+              criteria.extend(extension)
+              criteria
+            end
+          )
+        end
+      end
+
+      # Process the default scope value. If one already exists, we merge the
+      # new one into the old one.
+      #
+      # @api private
+      #
+      # @example Process the default scope.
+      #   Model.process_default_scope(value)
+      #
+      # @param [ Criteria | Proc ] value The default scope value.
+      def process_default_scope(value)
+        if existing = default_scoping
+          ->{ existing.call.merge(value.to_proc.call) }
+        else
+          value.to_proc
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/selectable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # Provides behavior for generating the selector for a specific document.
+  module Selectable
+    extend ActiveSupport::Concern
+
+    # Get the atomic selector for the document. This is a hash in the simplest
+    # case { "_id" => id }, but can become more complex for embedded documents
+    # and documents that use a shard key.
+    #
+    # @example Get the document's atomic selector.
+    #   document.atomic_selector
+    #
+    # @return [ Hash ] The document's selector.
+    def atomic_selector
+      embedded? ? embedded_atomic_selector : root_atomic_selector_in_db
+    end
+
+    private
+
+    # Get the atomic selector for an embedded document.
+    #
+    # @api private
+    #
+    # @example Get the embedded atomic selector.
+    #   document.embedded_atomic_selector
+    #
+    # @return [ Hash ] The embedded document selector.
+    def embedded_atomic_selector
+      if persisted? && _id_changed?
+        _parent.atomic_selector
+      else
+        _parent.atomic_selector.merge("#{atomic_path}._id" => _id)
+      end
+    end
+
+    # Get the atomic selector that would match the existing version of the
+    # root document.
+    #
+    # @api private
+    #
+    # @return [ Hash ] The root document selector.
+    def root_atomic_selector_in_db
+      { "_id" => _id }.merge!(shard_key_selector_in_db)
+    end
+  end
+end

data/lib/mongoid/serializable.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # This module provides the extra behavior for including associations in JSON
+  # and XML serialization.
+  module Serializable
+    extend ActiveSupport::Concern
+
+    # We need to redefine where the JSON configuration is getting defined,
+    # similar to +ActiveRecord+.
+    included do
+
+      class << self
+        # Note that this intentionally only delegates :include_root_in_json
+        # and not :include_root_in_json? - delegating the latter produces
+        # wrong behavior.
+        # Also note that this intentionally uses the ActiveSupport delegation
+        # functionality and not the Ruby standard library one.
+        # See https://jira.mongodb.org/browse/MONGOID-4849.
+        delegate :include_root_in_json, to: ::Mongoid
+      end
+    end
+
+    # Gets the document as a serializable hash, used by ActiveModel's JSON
+    # serializer.
+    #
+    # @example Get the serializable hash.
+    #   document.serializable_hash
+    #
+    # @example Get the serializable hash with options.
+    #   document.serializable_hash(:include => :addresses)
+    #
+    # @param [ Hash ] options The options to pass.
+    #
+    # @option options [ Symbol | String | Array<Symbol | String> ] :except
+    #   Do not include these field(s).
+    # @option options [ Symbol | String | Array<Symbol | String> ] :include
+    #   Which association(s) to include.
+    # @option options [ Symbol | String | Array<Symbol | String> ] :only
+    #   Limit the field(s) to only these.
+    # @option options [ Symbol | String | Array<Symbol | String> ] :methods
+    #   What methods to include.
+    #
+    # @return [ Hash ] The document, ready to be serialized.
+    def serializable_hash(options = nil)
+      options ||= {}
+      attrs = {}
+
+      names = field_names(options)
+
+      method_names = Array.wrap(options[:methods]).map do |name|
+        name.to_s if respond_to?(name)
+      end.compact
+
+      (names + method_names).each do |name|
+        without_autobuild do
+          serialize_attribute(attrs, name, names, options)
+        end
+      end
+      serialize_relations(attrs, options) if options[:include]
+      attrs
+    end
+
+    private
+
+    # Get the names of all fields that will be serialized.
+    #
+    # @api private
+    #
+    # @example Get all the field names.
+    #   document.send(:field_names)
+    #
+    # @return [ Array<String> ] The names of the fields.
+    def field_names(options)
+      names = (as_attributes.keys + attribute_names).uniq.sort
+
+      only = Array.wrap(options[:only]).map(&:to_s)
+      except = Array.wrap(options[:except]).map(&:to_s)
+      except |= [self.class.discriminator_key] unless Mongoid.include_type_for_serialization
+
+      if !only.empty?
+        names &= only
+      elsif !except.empty?
+        names -= except
+      end
+      names
+    end
+
+    # Serialize a single attribute. Handles associations, fields, and dynamic
+    # attributes.
+    #
+    # @api private
+    #
+    # @example Serialize the attribute.
+    #   document.serialize_attribute({}, "id" , [ "id" ])
+    #
+    # @param [ Hash ] attrs The attributes.
+    # @param [ String ] name The attribute name.
+    # @param [ Array<String> ] names The names of all attributes.
+    # @param [ Hash ] options The options.
+    #
+    # @return [ Object ] The attribute.
+    def serialize_attribute(attrs, name, names, options)
+      if relations.key?(name)
+        value = send(name)
+        attrs[name] = value ? value.serializable_hash(options) : nil
+      elsif names.include?(name) && !fields.key?(name)
+        attrs[name] = read_raw_attribute(name)
+      elsif !attribute_missing?(name)
+        attrs[name] = send(name)
+      end
+    end
+
+    # For each of the provided include options, get the association needed and
+    # provide it in the hash.
+    #
+    # @example Serialize the included associations.
+    #   document.serialize_relations({}, :include => :addresses)
+    #
+    # @param [ Hash ] attributes The attributes to serialize.
+    # @param [ Hash ] options The serialization options.
+    #
+    # @option options [ Symbol ] :include What associations to include
+    # @option options [ Symbol ] :only Limit the fields to only these.
+    # @option options [ Symbol ] :except Dont include these fields.
+    def serialize_relations(attributes = {}, options = {})
+      inclusions = options[:include]
+      relation_names(inclusions).each do |name|
+        association = relations[name.to_s]
+        if association && relation = send(association.name)
+          attributes[association.name.to_s] =
+            relation.serializable_hash(relation_options(inclusions, options, name))
+        end
+      end
+    end
+
+    # Since the inclusions can be a hash, symbol, or array of symbols, this is
+    # provided as a convenience to parse out the names.
+    #
+    # @example Get the association names.
+    #   document.relation_names(:include => [ :addresses ])
+    #
+    # @param [ Hash | Symbol | Array<Symbol> ] inclusions The inclusions.
+    #
+    # @return [ Array<Symbol> ] The names of the included associations.
+    def relation_names(inclusions)
+      inclusions.is_a?(Hash) ? inclusions.keys : Array.wrap(inclusions)
+    end
+
+    # Since the inclusions can be a hash, symbol, or array of symbols, this is
+    # provided as a convenience to parse out the options.
+    #
+    # @example Get the association options.
+    #   document.relation_names(:include => [ :addresses ])
+    #
+    # @param [ Hash | Symbol | Array<Symbol> ] inclusions The inclusions.
+    # @param [ Hash ] options The options.
+    # @param [ Symbol ] name The name of the association.
+    #
+    # @return [ Hash ] The options for the association.
+    def relation_options(inclusions, options, name)
+      if inclusions.is_a?(Hash)
+        inclusions[name]
+      else
+        { except: options[:except], only: options[:only] }
+      end
+    end
+  end
+end

data/lib/mongoid/shardable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # This module contains behavior for adding shard key fields to updates.
+  module Shardable
+    extend ActiveSupport::Concern
+
+    included do
+      # Returns the list of shard key fields, if shard key was declared on
+      # this model. If no shard key was declared, returns an empty array.
+      #
+      # @return [ Array<Symbol> ] List of shard key fields.
+      # @api public
+      cattr_accessor :shard_key_fields
+      self.shard_key_fields = []
+
+      # Returns the shard configuration, which is a hash with the following
+      # (symbol) keys:
+      #
+      # - keys: A hash mapping (symbol) field names to values, defining the
+      #   shard key. Values can be either the integer 1 for ranged sharding
+      #   or the string "hashed" for hashed sharding.
+      # - options: A hash containing options for shardCollections command.
+      #
+      # If shard key was not declared via the +shard_key+ macro, +shard_config+
+      # attribute is nil.
+      #
+      # @example Get the shard configuration.
+      #   Model.shard_config
+      #   # => {key: {foo: 1, bar: 1}, options: {unique: true}}
+      #
+      # @return [ Hash | nil ] Shard configuration.
+      # @api public
+      cattr_accessor :shard_config
+    end
+
+    # Get the shard key fields.
+    #
+    # @note Refactored from using delegate for class load performance.
+    #
+    # @example Get the shard key fields.
+    #   model.shard_key_fields
+    #
+    # @return [ Array<String> ] The shard key field names.
+    def shard_key_fields
+      self.class.shard_key_fields
+    end
+
+    # Returns the selector that would match the current version of this
+    # document.
+    #
+    # @return [ Hash ] The shard key selector.
+    #
+    # @api private
+    def shard_key_selector
+      selector = {}
+      shard_key_fields.each do |field|
+        selector[field.to_s] = send(field)
+      end
+      selector
+    end
+
+    # Returns the selector that would match the existing version of this
+    # document in the database.
+    #
+    # If the document is not persisted, this method uses the current values
+    # of the shard key fields. If the document is persisted, this method
+    # uses the values retrieved from the database.
+    #
+    # @return [ Hash ] The shard key selector.
+    #
+    # @api private
+    def shard_key_selector_in_db
+      selector = {}
+      shard_key_fields.each do |field|
+        selector[field.to_s] = new_record? ? send(field) : attribute_was(field)
+      end
+      selector
+    end
+
+    module ClassMethods
+
+      # Specifies a shard key with the field(s) specified.
+      #
+      # @example Specify the shard key.
+      #
+      #   class Person
+      #     include Mongoid::Document
+      #     field :first_name, :type => String
+      #     field :last_name, :type => String
+      #
+      #     shard_key first_name: 1, last_name: 1
+      #   end
+      def shard_key(*args)
+        unless args.first.is_a?(Hash)
+          # Shorthand syntax
+          if args.last.is_a?(Hash)
+            raise ArgumentError, 'Shorthand shard_key syntax does not permit options'
+          end
+
+          spec = Hash[args.map do |name|
+            [name, 1]
+          end]
+
+          return shard_key(spec)
+        end
+
+        if args.length > 2
+          raise ArgumentError, 'Full shard_key syntax requires 1 or 2 arguments'
+        end
+
+        spec, options = args
+
+        spec = Hash[spec.map do |name, value|
+          if value.is_a?(Symbol)
+            value = value.to_s
+          end
+          [database_field_name(name).to_sym, value]
+        end]
+
+        self.shard_key_fields = spec.keys
+        self.shard_config = {
+          key: spec.freeze,
+          options: (options || {}).dup.freeze,
+        }.freeze
+      end
+    end
+  end
+end