Add include_data :via_include_parameter

For JSONAPI, `include_data` currently means, "should we populate the
'data'" key for this relationship. Current options are true/false.

This adds the `:via_include_parameter` option. This means "only
populate the 'data' key when we are sideloading this relationship." This
is because 'data' is often only relevant to sideloading, and causes a
database hit.

Addresses #1555

Author: Lee Richmond

lib/active_model/serializer/associations.rb

@@ -82,15 +82,17 @@ def associate(reflection)
       #   +default_include_directive+ config value when not provided)
       # @return [Enumerator<Association>]
       #
-      def associations(include_directive = ActiveModelSerializers.default_include_directive)
+      def associations(include_directive = ActiveModelSerializers.default_include_directive, include_slice = nil)
+        include_slice ||= include_directive
         return unless object
 
         Enumerator.new do |y|
           self.class._reflections.each do |reflection|
             next if reflection.excluded?(self)
             key = reflection.options.fetch(:key, reflection.name)
             next unless include_directive.key?(key)
-            y.yield reflection.build_association(self, instance_options)
+
+            y.yield reflection.build_association(self, instance_options, include_slice)
           end
         end
       end

lib/active_model/serializer/reflection.rb

@@ -69,19 +69,17 @@ def include_data(value = true)
       #       Blog.find(object.blog_id)
       #     end
       #   end
-      def value(serializer)
+      def value(serializer, include_slice)
         @object = serializer.object
         @scope = serializer.scope
 
-        if block
-          block_value = instance_exec(serializer, &block)
-          if block_value != :nil
-            block_value
-          elsif @_include_data
-            serializer.read_attribute_for_serialization(name)
-          end
-        else
+        block_value = instance_exec(serializer, &block) if block
+        return unless include_data?(include_slice)
+
+        if [nil, :nil].include?(block_value)
           serializer.read_attribute_for_serialization(name)
+        else
+          block_value
         end
       end
 
@@ -106,11 +104,11 @@ def value(serializer)
       #
       # @api private
       #
-      def build_association(subject, parent_serializer_options)
-        association_value = value(subject)
+      def build_association(subject, parent_serializer_options, include_slice = {})
+        association_value = value(subject, include_slice)
         reflection_options = options.dup
         serializer_class = subject.class.serializer_for(association_value, reflection_options)
-        reflection_options[:include_data] = @_include_data
+        reflection_options[:include_data] = include_data?(include_slice)
 
         if serializer_class
           begin
@@ -134,6 +132,14 @@ def build_association(subject, parent_serializer_options)
 
       private
 
+      def include_data?(include_slice)
+        if @_include_data == :via_include_parameter
+          include_slice.key?(name)
+        else
+          @_include_data
+        end
+      end
+
       def serializer_options(subject, parent_serializer_options, reflection_options)
         serializer = reflection_options.fetch(:serializer, nil)
 

lib/active_model_serializers/adapter/json_api.rb

@@ -235,17 +235,17 @@ def resource_objects_for(serializers)
         @primary = []
         @included = []
         @resource_identifiers = Set.new
-        serializers.each { |serializer| process_resource(serializer, true) }
+        serializers.each { |serializer| process_resource(serializer, true, @include_directive) }
         serializers.each { |serializer| process_relationships(serializer, @include_directive) }
 
         [@primary, @included]
       end
 
-      def process_resource(serializer, primary)
+      def process_resource(serializer, primary, include_slice = {})
         resource_identifier = ResourceIdentifier.new(serializer, instance_options).as_json
         return false unless @resource_identifiers.add?(resource_identifier)
 
-        resource_object = resource_object_for(serializer)
+        resource_object = resource_object_for(serializer, include_slice)
         if primary
           @primary << resource_object
         else
@@ -255,21 +255,21 @@ def process_resource(serializer, primary)
         true
       end
 
-      def process_relationships(serializer, include_directive)
-        serializer.associations(include_directive).each do |association|
-          process_relationship(association.serializer, include_directive[association.key])
+      def process_relationships(serializer, include_slice)
+        serializer.associations(include_slice).each do |association|
+          process_relationship(association.serializer, include_slice[association.key])
         end
       end
 
-      def process_relationship(serializer, include_directive)
+      def process_relationship(serializer, include_slice)
         if serializer.respond_to?(:each)
-          serializer.each { |s| process_relationship(s, include_directive) }
+          serializer.each { |s| process_relationship(s, include_slice) }
           return
         end
         return unless serializer && serializer.object
-        return unless process_resource(serializer, false)
+        return unless process_resource(serializer, false, include_slice)
 
-        process_relationships(serializer, include_directive)
+        process_relationships(serializer, include_slice)
       end
 
       # {http://jsonapi.org/format/#document-resource-object-attributes Document Resource Object Attributes}
@@ -293,7 +293,7 @@ def attributes_for(serializer, fields)
       end
 
       # {http://jsonapi.org/format/#document-resource-objects Document Resource Objects}
-      def resource_object_for(serializer)
+      def resource_object_for(serializer, include_slice = {})
         resource_object = serializer.fetch(self) do
           resource_object = ResourceIdentifier.new(serializer, instance_options).as_json
 
@@ -304,7 +304,7 @@ def resource_object_for(serializer)
         end
 
         requested_associations = fieldset.fields_for(resource_object[:type]) || '*'
-        relationships = relationships_for(serializer, requested_associations)
+        relationships = relationships_for(serializer, requested_associations, include_slice)
         resource_object[:relationships] = relationships if relationships.any?
 
         links = links_for(serializer)
@@ -432,12 +432,12 @@ def resource_object_for(serializer)
       #     id: 'required-id',
       #     meta: meta
       #   }.reject! {|_,v| v.nil? }
-      def relationships_for(serializer, requested_associations)
+      def relationships_for(serializer, requested_associations, include_slice)
         include_directive = JSONAPI::IncludeDirective.new(
           requested_associations,
           allow_wildcard: true
         )
-        serializer.associations(include_directive).each_with_object({}) do |association, hash|
+        serializer.associations(include_directive, include_slice).each_with_object({}) do |association, hash|
           hash[association.key] = Relationship.new(
             serializer,
             association.serializer,

test/adapter/json_api/include_param_test.rb

@@ -0,0 +1,166 @@
+require 'test_helper'
+
+module ActiveModel
+  class Serializer
+    module Adapter
+      class JsonApi
+        class IncludeParamTest < ActiveSupport::TestCase
+          IncludeParamAuthor = Class.new(::Model)
+
+          class CustomCommentLoader
+            def all
+              [{ foo: 'bar' }]
+            end
+          end
+
+          class TagSerializer < ActiveModel::Serializer
+            attributes :id, :name
+          end
+
+          class IncludeParamAuthorSerializer < ActiveModel::Serializer
+            class_attribute :comment_loader
+
+            has_many :tags, serializer: TagSerializer do
+              link :self, '//example.com/link_author/relationships/tags'
+              include_data :via_include_parameter
+            end
+
+            has_many :unlinked_tags, serializer: TagSerializer do
+              include_data :via_include_parameter
+            end
+
+            has_many :posts, serializer: PostWithTagsSerializer do
+              include_data :via_include_parameter
+            end
+            has_many :locations do
+              include_data :via_include_parameter
+            end
+            has_many :comments do
+              include_data :via_include_parameter
+              IncludeParamAuthorSerializer.comment_loader.all
+            end
+          end
+
+          def setup
+            IncludeParamAuthorSerializer.comment_loader = Class.new(CustomCommentLoader).new
+            @tag = Tag.new(id: 1337, name: 'mytag')
+            @author = IncludeParamAuthor.new(
+              id: 1337,
+              tags: [@tag]
+            )
+          end
+
+          def test_relationship_not_loaded_when_not_included
+            expected = {
+              links: {
+                self: '//example.com/link_author/relationships/tags'
+              }
+            }
+
+            @author.define_singleton_method(:read_attribute_for_serialization) do |attr|
+              fail 'should not be called' if attr == :tags
+              super(attr)
+            end
+
+            assert_relationship(:tags, expected)
+          end
+
+          def test_relationship_included
+            expected = {
+              data: [
+                {
+                  id: '1337',
+                  type: 'tags'
+                }
+              ],
+              links: {
+                self: '//example.com/link_author/relationships/tags'
+              }
+            }
+
+            assert_relationship(:tags, expected, include: :tags)
+          end
+
+          def test_sideloads_included
+            expected = [
+              {
+                id: '1337',
+                type: 'tags',
+                attributes: { name: 'mytag' }
+              }
+            ]
+            hash = result(include: :tags)
+            assert_equal(expected, hash[:included])
+          end
+
+          def test_nested_relationship
+            expected = {
+              data: [
+                {
+                  id: '1337',
+                  type: 'tags'
+                }
+              ],
+              links: {
+                self: '//example.com/link_author/relationships/tags'
+              }
+            }
+
+            expected_no_data = {
+              links: {
+                self: '//example.com/link_author/relationships/tags'
+              }
+            }
+
+            assert_relationship(:tags, expected, include: [:tags, { posts: :tags }])
+
+            @author.define_singleton_method(:read_attribute_for_serialization) do |attr|
+              fail 'should not be called' if attr == :tags
+              super(attr)
+            end
+
+            assert_relationship(:tags, expected_no_data, include: { posts: :tags })
+          end
+
+          def test_include_params_with_no_block
+            @author.define_singleton_method(:read_attribute_for_serialization) do |attr|
+              fail 'should not be called' if attr == :locations
+              super(attr)
+            end
+
+            expected = {}
+
+            assert_relationship(:locations, expected)
+          end
+
+          def test_block_relationship
+            expected = {
+              data: [
+                { 'foo' => 'bar' }
+              ]
+            }
+
+            assert_relationship(:comments, expected, include: [:comments])
+          end
+
+          def test_node_not_included_when_no_link
+            expected = nil
+            assert_relationship(:unlinked_tags, expected)
+          end
+
+          private
+
+          def result(opts)
+            opts = { adapter: :json_api }.merge(opts)
+            serializable(@author, opts).serializable_hash
+          end
+
+          def assert_relationship(relationship_name, expected, opts = {})
+            hash = result(opts)
+            assert_equal(expected, hash[:data][:relationships][relationship_name])
+          end
+        end
+      end
+    end
+  end
+end