mongoid_includes 1.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 10b99b346c88aaba6c21b90999b43d202fa5e7df
+  data.tar.gz: 84b0ad21bf1d12b739969f02f7a852415ab2f5aa
+SHA512:
+  metadata.gz: a04a4f1ce0b3b430049a73a180fdbcfcd5ce20c05cc54bfae92dcd8b253c369dc6ee9982f0a766abec54c00503f68dbc2da12906fe93beb98bc6a99e70649096
+  data.tar.gz: 81011321c771106225cf87a5401ef1970f21b663311bfa15bd383e774624998d82b7cf7b9b5008528aead0a9e73c2e28cc31318e2188fdc863faebcba5bb378d

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## Mongoid::Includes 1.0.3 (2015-10-10) ##
+
+*   Add support for Mongoid 5.
+
+## Mongoid::Includes 1.0.2 (2015-10-08) ##
+
+*   Fix error when using `merge` or `merge!` with a criteria and `includes`.
+*   Replace the internal structure with a Set to be more robust when avoiding duplicate relations.
+
+## Mongoid::Includes 1.0.1 (August 5, 2015) ##
+
+*   Fix error messages for polymorphic includes.
+*   Add :with option that receives the criteria that will be used to include documents.
+
+## Mongoid::Includes 1.0.0 (July 30, 2015) ##
+
+*   Initial Version.

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Máximo Mussini
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+Mongoid::Includes
+=====================
+[![Gem Version](https://badge.fury.io/rb/mongoid_includes.svg)](http://badge.fury.io/rb/mongoid_includes)
+[![Build Status](https://travis-ci.org/ElMassimo/mongoid_includes.svg)](https://travis-ci.org/ElMassimo/mongoid_includes)
+[![Test Coverage](https://codeclimate.com/github/ElMassimo/mongoid_includes/badges/coverage.svg)](https://codeclimate.com/github/ElMassimo/mongoid_includes)
+[![Code Climate](https://codeclimate.com/github/ElMassimo/mongoid_includes.png)](https://codeclimate.com/github/ElMassimo/mongoid_includes)
+[![Inline docs](http://inch-ci.org/github/ElMassimo/mongoid_includes.svg)](http://inch-ci.org/github/ElMassimo/mongoid_includes)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ElMassimo/mongoid_includes/blob/master/LICENSE.txt)
+
+`Mongoid::Includes` improves eager loading in Mongoid, supporting polymorphic associations, and up to two-levels of eager loading.
+
+### Usage
+
+```ruby
+Album.includes(:songs).includes(:musicians, from: :band)
+
+Band.includes(:albums, with: ->(albums) { albums.gt(release: 1970) })
+```
+
+## Advantages
+
+* Avoid N+1 queries and get better performance.
+* No boilerplate code is required.
+* Can avoid loading all the related documents if necessary.
+
+
+License
+--------
+
+    Copyright (c) 2015 Máximo Mussini
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,31 @@
+require 'bundler'
+Bundler.setup
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'mongoid/includes/version'
+
+task :gem => :build
+task :build do
+  system 'gem build mongoid_includes.gemspec'
+end
+
+task :install => :build do
+  system "sudo gem install mongoid_includes-#{Mongoid::Includes::VERSION}.gem"
+end
+
+task :release => :build do
+  system "git tag -a v#{Mongoid::Includes::VERSION} -m 'Tagging #{Mongoid::Includes::VERSION}'"
+  system 'git push --tags'
+  system "gem push mongoid_includes-#{Mongoid::Includes::VERSION}.gem"
+  system "rm mongoid_includes-#{Mongoid::Includes::VERSION}.gem"
+end
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = ['--format progress']
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => :spec

data/lib/config/locales/en.yml

@@ -0,0 +1,19 @@
+en:
+  mongoid:
+    errors:
+      messages:
+        invalid_includes:
+          message: "Invalid includes directive: %{klass}.includes(%{args})"
+          summary: "Eager loading in Mongoid only supports providing arguments
+            to %{klass}.includes that are the names of relations on the %{klass}
+            model."
+          resolution: "Ensure that each parameter passed to %{klass}.includes is
+            a valid name of a relation on the %{klass} model. These are: %{relations}."
+
+        invalid_polymorphic_nested_includes:
+          message: "Invalid nested include directive: %{klass}.includes(%{args}, from: %{from}), %{from}
+            is a polymorphic relation."
+          summary: "Given that %{from} is a polymorphic relation, you must specify
+            :from_class when calling the method to resolve the ambiguity."
+          resolution: "Ensure that the first parameter passed to %{klass}.includes is
+            a non-polymorphic relation in the %{klass} model, or a explicit class in :from_class"

data/lib/mongoid/includes.rb

@@ -0,0 +1,4 @@
+require 'mongoid/includes/version'
+require 'mongoid/includes/criteria'
+require 'mongoid/includes/eager_load'
+require 'mongoid/includes/relations/eager'

data/lib/mongoid/includes/criteria.rb

@@ -0,0 +1,67 @@
+require 'mongoid/includes/errors'
+require 'mongoid/includes/inclusions'
+
+module Mongoid
+  module Includes
+
+    # Internal: Adds and overrides methods in Mongoid::Criteria to enhance eager loading.
+    module Criteria
+
+      # Overrides: Get a list of criteria that are to be executed for eager loading.
+      def inclusions
+        @inclusions ||= Mongoid::Includes::Inclusions.new
+      end
+
+      # Public: Eager loads the specified associations.
+      #
+      # relations   - The relations of the two-level relations to eager load.
+      # from:       - The relation through which two-level relations are
+      #               loaded from.
+      # from_class: - Necessary to solve ambiguity when doing two-level eager
+      #               load through a polymorphic relation.
+      # loader:       - An optional block that specifies how to load all the
+      #               related documents.
+      #
+      # Notes:
+      #   Eager loading brings all the documents into memory, so there is a
+      #   sweet spot on the performance gains. Internal benchmarks show that
+      #   eager loading becomes slower around 100k documents, but this will
+      #   naturally depend on the specific application.
+      #
+      #   Polymorphic belongs_to relations are supported, but will trigger a
+      #   query for each collection of the matched documents types.
+      #
+      # Example:
+      #   Album.includes(:musicians, from: :band)
+      #
+      # Returns the cloned Mongoid::Criteria.
+      def includes(*relations, **options)
+        if options[:from]
+          from_metadata = add_inclusion(klass, options[:from])
+          if from_metadata.polymorphic_belongs_to? && !options[:from_class]
+            raise Mongoid::Includes::Errors::InvalidPolymorphicIncludes.new(klass, relations, options)
+          end
+        end
+
+        owner_class = options[:from_class] || from_metadata.try!(:klass) || self.klass
+
+        relations.flatten.each do |relation|
+          add_inclusion(owner_class, relation, options)
+        end
+        clone
+      end
+
+    private
+
+      # Internal: Adds a new inclusion to the criteria.
+      #
+      # Returns the Mongoid::Includes::Inclusion for the included relation.
+      def add_inclusion(owner_class, relation, options = {})
+        unless metadata = owner_class.reflect_on_association(relation)
+          raise Mongoid::Includes::Errors::InvalidIncludes.new(owner_class, relation, options)
+        end
+        inclusions.include?(metadata) || inclusions.push(metadata, options)
+      end
+    end
+  end
+end

data/lib/mongoid/includes/eager_load.rb

@@ -0,0 +1,50 @@
+module Mongoid
+  module Includes
+
+    # Public: Adds support for polymorphic and nested eager loading.
+    module EagerLoad
+
+      # Override: Partitions the inclusions into the different types.
+      def eager_load(docs)
+        return false unless eager_loadable?
+
+        nested_inclusions, inclusions = criteria.inclusions.partition(&:nested?)
+        polymorphic_inclusions, inclusions = inclusions.partition(&:polymorphic_belongs_to?)
+        full_preload(docs, inclusions, polymorphic_inclusions, nested_inclusions)
+
+        self.eager_loaded = true
+      end
+
+      # Internal: Performs the normal inclusions first, which allows to perform
+      # the polymorphic eager loading. Nested inclusions are performed at the end.
+      def full_preload(docs, inclusions, polymorphic_inclusions, nested_inclusions)
+        preload(inclusions, docs)
+
+        polymorphic_inclusions.each do |metadata|
+          preload_polymorphic(metadata, docs)
+        end
+
+        preload_nested(nested_inclusions, docs)
+      end
+
+      # Internal: Preloads each polymorphic includes, by grouping the documents by
+      # concrete type of the polymorphic relation, and making a query for each type.
+      def preload_polymorphic(inclusion, docs)
+        docs.group_by do |doc|
+          doc.send(inclusion.inverse_type) # The {name}_type attribute in polymorphic relations.
+        end.each do |type, docs|
+          concrete_inclusion = inclusion.for_class_name(type)
+          preload([concrete_inclusion], docs)
+        end
+      end
+
+      # Internal: The documents are grouped by the nested property, and all the
+      # includes by that property are processed as usual.
+      def preload_nested(nested_inclusions, docs)
+        nested_inclusions.group_by(&:from).each do |from, inclusions|
+          preload(inclusions, docs.map(&from).flatten)
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/includes/errors.rb

@@ -0,0 +1,2 @@
+require 'mongoid/includes/errors/invalid_includes'
+require 'mongoid/includes/errors/invalid_polymorphic_includes'

data/lib/mongoid/includes/errors/invalid_includes.rb

@@ -0,0 +1,30 @@
+module Mongoid
+  module Includes
+    module Errors
+
+      # Public: This error is raised when an invalid include is performed.
+      class InvalidIncludes < Mongoid::Errors::MongoidError
+
+        # Public: Composes a message from the class the includes would be
+        # performed on, the relations to be included, and the options.
+        def initialize(klass, args, options)
+          super compose_message(type, options.merge(
+            klass: klass, relations: klass.relations.keys, args: Array.wrap(args)
+          ))
+        end
+
+        # Internal: Key of the translation message
+        def type
+          :invalid_includes
+        end
+
+        # Overrides: Helps to keep the templates simple by using inspect on the options.
+        def compose_message(type, options)
+          super type, options.transform_values { |value|
+            value.is_a?(Array) ? value.map(&:inspect).join(', ') : value.inspect
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/includes/errors/invalid_polymorphic_includes.rb

@@ -0,0 +1,16 @@
+module Mongoid
+  module Includes
+    module Errors
+
+      # Public: This error is raised when an invalid nested inclusion is
+      # attempted through a polymorphic relation.
+      class InvalidPolymorphicIncludes < InvalidIncludes
+
+        # Internal: Key of the translation message
+        def type
+          :invalid_polymorphic_nested_includes
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/includes/inclusion.rb

@@ -0,0 +1,64 @@
+module Mongoid
+  module Includes
+
+    # Public: Represents a relation that needs to be eager loaded.
+    class Inclusion < SimpleDelegator
+
+      # Public: Convenience getter for the wrapped metadata.
+      alias_method :metadata, :__getobj__
+
+      def initialize(metadata, options = {})
+        super(metadata)
+        @options = options
+      end
+
+      # Public: Returns true if the relation is not direct.
+      def nested?
+        !!from
+      end
+
+      # Public: Returns true if the relation is a polymorphic belongs_to.
+      def polymorphic_belongs_to?
+        metadata.polymorphic? && metadata.relation == Mongoid::Relations::Referenced::In
+      end
+
+      # Public: Name of the relation from which a nested inclusion is performed.
+      def from
+        @from ||= @options[:from]
+      end
+
+      # Internal: Proc that will return the included documents from a set of foreign keys.
+      def loader
+        @loader ||= @options[:loader]
+      end
+
+      # Internal: Proc that will modify the documents to include in the relation.
+      def modifier
+        @modifier ||= @options[:with]
+      end
+
+      # Public: Preloads the documents for the relation. Users a custom block
+      # if one was provided, or fetches them using the class and the foreign key.
+      def load_documents_for(foreign_key, foreign_key_values)
+        if loader
+          loader.call(foreign_key, foreign_key_values)
+        else
+          docs = klass.any_in(foreign_key => foreign_key_values)
+          modifier ? modifier.call(docs) : docs
+        end
+      end
+
+      # Public: Clones the inclusion and changes the Mongoid::Metadata::Relation
+      # that it wraps to make it non polymorphic and target a particular class.
+      #
+      # Returns an Inclusion that can be eager loaded as usual.
+      def for_class_name(class_name)
+        Inclusion.new metadata.clone.instance_eval { |relation_metadata|
+          self[:class_name] = @class_name = class_name
+          self[:polymorphic], self[:as], @polymorphic, @klass = nil
+          self
+        }
+      end
+    end
+  end
+end

data/lib/mongoid/includes/inclusions.rb

@@ -0,0 +1,40 @@
+require 'mongoid/includes/inclusion'
+
+module Mongoid
+  module Includes
+
+    # Public: Collection of relations that need to be eager loaded.
+    class Inclusions < SimpleDelegator
+
+      # Internal: By default, it wraps an empty set.
+      def initialize(object = [])
+        super Set.new(object)
+      end
+
+      # Public: Adds a new relation as an inclusion.
+      #
+      # Returns the added inclusion.
+      def push(metadata, options = {})
+        metadata = Inclusion.new(metadata, options) unless metadata.is_a?(Inclusion)
+        add(metadata)
+        metadata
+      end
+
+      # Public: Checks if the collection already has an inclusion with the
+      # specified metadata.
+      def include?(metadata)
+        find { |inclusion| inclusion.metadata == metadata }
+      end
+
+      # Public: Returns the sum of the inclusions without any duplicates.
+      def +(inclusions)
+        Inclusions.new(union(inclusions))
+      end
+
+      # Public: Returns a new Inclusions without any duplicates.
+      def uniq
+        dup
+      end
+    end
+  end
+end

data/lib/mongoid/includes/relations/eager.rb

@@ -0,0 +1,19 @@
+module Mongoid
+  module Includes
+    module Relations
+
+      # Internal: Patch to the base class for eager load preload functions,
+      # that interacts with the Mongoid::Includes::Inclusion as @medatada.
+      module Eager
+
+        # Internal: Performs eager load and iterates over the preloaded documents
+        # for the current relation.
+        def each_loaded_document
+          @metadata.load_documents_for(key, keys_from_docs).each do |doc|
+            yield doc
+          end
+        end
+      end
+    end
+  end
+end