Associations refactoring

* Move all associations related code from Serializer class to Associations module
* Introduce Reflection class hierarchy
* Introduce Association class
* Rid off Serializer#each_association
* Introduce Serializer#associations enumerator

lib/active_model/serializer/adapter/json.rb

@@ -7,7 +7,7 @@ module ActiveModel
         def serializable_hash(options = nil)
           options ||= {}
           if serializer.respond_to?(:each)
-            @result = serializer.map{|s| FlattenJson.new(s).serializable_hash(options) }
+            @result = serializer.map { |s| FlattenJson.new(s).serializable_hash(options) }
           else
             @hash = {}
 
@@ -15,24 +15,26 @@ module ActiveModel
               serializer.attributes(options)
             end
 
-            serializer.each_association do |key, association, opts|
-              if association.respond_to?(:each)
-                array_serializer = association
-                @hash[key] = array_serializer.map do |item|
+            serializer.associations.each do |association|
+              serializer = association.serializer
+              opts = association.options
+
+              if serializer.respond_to?(:each)
+                array_serializer = serializer
+                @hash[association.key] = array_serializer.map do |item|
                   cache_check(item) do
                     item.attributes(opts)
                   end
                 end
               else
-                if association && association.object
-                  @hash[key] = cache_check(association) do
-                    association.attributes(options)
+                @hash[association.key] =
+                  if serializer && serializer.object
+                    cache_check(serializer) do
+                      serializer.attributes(options)
+                    end
+                  elsif opts[:virtual_value]
+                    opts[:virtual_value]
                   end
-                elsif opts[:virtual_value]
-                  @hash[key] = opts[:virtual_value]
-                else
-                  @hash[key] = nil
-                end
               end
             end
             @result = @core.merge @hash

lib/active_model/serializer/adapter/json_api.rb

@@ -75,8 +75,10 @@ module ActiveModel
           end
 
           serializers.each do |serializer|
-            serializer.each_association do |key, association, opts|
-              add_included(key, association, resource_path) if association
+            serializer.associations.each do |association|
+              serializer = association.serializer
+
+              add_included(association.key, serializer, resource_path) if serializer
             end if include_nested_assoc? resource_path
           end
         end
@@ -131,22 +133,26 @@ module ActiveModel
         def add_resource_relationships(attrs, serializer, options = {})
           options[:add_included] = options.fetch(:add_included, true)
 
-          serializer.each_association do |key, association, opts|
+          serializer.associations.each do |association|
+            key = association.key
+            serializer = association.serializer
+            opts = association.options
+
             attrs[:relationships] ||= {}
 
-            if association.respond_to?(:each)
-              add_relationships(attrs, key, association)
+            if serializer.respond_to?(:each)
+              add_relationships(attrs, key, serializer)
             else
               if opts[:virtual_value]
                 add_relationship(attrs, key, nil, opts[:virtual_value])
               else
-                add_relationship(attrs, key, association)
+                add_relationship(attrs, key, serializer)
               end
             end
 
             if options[:add_included]
-              Array(association).each do |association|
-                add_included(key, association)
+              Array(serializer).each do |serializer|
+                add_included(key, serializer)
               end
             end
           end

lib/active_model/serializer/association.rb

@@ -0,0 +1,21 @@
+module ActiveModel
+  class Serializer
+    # This class hold all information about serializer's association.
+    #
+    # @param [Symbol] name
+    # @param [ActiveModel::Serializer] serializer
+    # @param [Hash{Symbol => Object}] options
+    #
+    # @example
+    #  Association.new(:comments, CommentSummarySerializer, embed: :ids)
+    #
+    Association = Struct.new(:name, :serializer, :options) do
+
+      # @return [Symbol]
+      #
+      def key
+        options.fetch(:key, name)
+      end
+    end
+  end
+end

lib/active_model/serializer/associations.rb

@@ -0,0 +1,107 @@
+module ActiveModel
+  class Serializer
+    # Defines an association in the object should be rendered.
+    #
+    # The serializer object should implement the association name
+    # as a method which should return an array when invoked. If a method
+    # with the association name does not exist, the association name is
+    # dispatched to the serialized object.
+    #
+    module Associations
+      extend ActiveSupport::Concern
+
+      included do |base|
+        class << base
+          attr_accessor :_reflections
+        end
+
+        autoload :Association
+        autoload :Reflection
+        autoload :SingularReflection
+        autoload :CollectionReflection
+        autoload :BelongsToReflection
+        autoload :HasOneReflection
+        autoload :HasManyReflection
+      end
+
+      module ClassMethods
+        def inherited(base)
+          base._reflections = self._reflections.try(:dup) || []
+        end
+
+        # @param [Array(Array<Symbol>, Hash{Symbol => Object})] attrs
+        # @return [void]
+        #
+        # @example
+        #  has_many :comments, serializer: CommentSummarySerializer
+        #  has_many :commits, authors
+        #
+        def has_many(*attrs)
+          associate attrs do |name, options|
+            HasManyReflection.new(name, options)
+          end
+        end
+
+        # @param [Array(Array<Symbol>, Hash{Symbol => Object})] attrs
+        # @return [void]
+        #
+        # @example
+        #  belongs_to :author, serializer: AuthorSerializer
+        #
+        def belongs_to(*attrs)
+          associate attrs do |name, options|
+            BelongsToReflection.new(name, options)
+          end
+        end
+
+        # @param [Array(Array<Symbol>, Hash{Symbol => Object})] attrs
+        # @return [void]
+        #
+        # @example
+        #  has_one :author, serializer: AuthorSerializer
+        #
+        def has_one(*attrs)
+          associate attrs do |name, options|
+            HasOneReflection.new(name, options)
+          end
+        end
+
+        private
+
+        # Add reflection and define {name} accessor.
+        # @param [Array<Symbol>]
+        # @yield [Symbol] return reflection
+        #
+        # @api private
+        #
+        def associate(attrs)
+          options = attrs.extract_options!
+
+          self._reflections = _reflections.dup
+
+          attrs.each do |name|
+            unless method_defined?(name)
+              define_method name do
+                object.send name
+              end
+            end
+
+            self._reflections << yield(name, options)
+          end
+        end
+      end
+
+      # @return [Enumerator<Association>]
+      #
+      def associations
+        return unless object
+
+        Enumerator.new do |y|
+          self.class._reflections.each do |reflection|
+            y.yield reflection.build_association(self, options)
+          end
+        end
+      end
+    end
+  end
+end

lib/active_model/serializer/belongs_to_reflection.rb

@@ -0,0 +1,10 @@
+module ActiveModel
+  class Serializer
+    # @api private
+    class BelongsToReflection < SingularReflection
+      def macro
+        :belongs_to
+      end
+    end
+  end
+end

lib/active_model/serializer/collection_reflection.rb

@@ -0,0 +1,7 @@
+module ActiveModel
+  class Serializer
+    # @api private
+    class CollectionReflection < Reflection
+    end
+  end
+end

lib/active_model/serializer/has_many_reflection.rb

@@ -0,0 +1,10 @@
+module ActiveModel
+  class Serializer
+    # @api private
+    class HasManyReflection < CollectionReflection
+      def macro
+        :has_many
+      end
+    end
+  end
+end

lib/active_model/serializer/has_one_reflection.rb

@@ -0,0 +1,10 @@
+module ActiveModel
+  class Serializer
+    # @api private
+    class HasOneReflection < SingularReflection
+      def macro
+        :has_one
+      end
+    end
+  end
+end

lib/active_model/serializer/reflection.rb

@@ -0,0 +1,74 @@
+module ActiveModel
+  class Serializer
+    # Holds all the meta-data about an association as it was specified in the
+    # ActiveModel::Serializer class.
+    #
+    # @example
+    #  class PostSerializer < ActiveModel::Serializer
+    #     has_one :author, serializer: AuthorSerializer
+    #     has_many :comments
+    #  end
+    #
+    #  PostSerializer._reflections #=>
+    #    # [
+    #    #   HasOneReflection.new(:author, serializer: AuthorSerializer),
+    #    #   HasManyReflection.new(:comments)
+    #    # ]
+    #
+    # So you can inspect reflections in your Adapters.
+    #
+    Reflection = Struct.new(:name, :options) do
+      # Build association. This method is used internally to
+      # build serializer's association by its reflection.
+      #
+      # @param [Serializer] subject is a parent serializer for given association
+      # @param [Hash{Symbol => Object}] parent_serializer_options
+      #
+      # @example
+      #    # Given the following serializer defined:
+      #    class PostSerializer < ActiveModel::Serializer
+      #      has_many :comments, serializer: CommentSummarySerializer
+      #    end
+      #
+      #    # Then you instantiate your serializer
+      #    post_serializer = PostSerializer.new(post, foo: 'bar') #
+      #    # to build association for comments you need to get reflection
+      #    comments_reflection = PostSerializer._reflections.detect { |r| r.name == :comments }
+      #    # and #build_association
+      #    comments_reflection.build_association(post_serializer, foo: 'bar')
+      #
+      # @api private
+      #
+      def build_association(subject, parent_serializer_options)
+        association_value = subject.send(name)
+        reflection_options = options.dup
+        serializer_class = ActiveModel::Serializer.serializer_for(association_value, reflection_options)
+
+        if serializer_class
+          begin
+            serializer = serializer_class.new(
+              association_value,
+              serializer_options(parent_serializer_options, reflection_options)
+            )
+          rescue ActiveModel::Serializer::ArraySerializer::NoSerializerError
+            reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
+          end
+        elsif !association_value.nil? && !association_value.instance_of?(Object)
+          reflection_options[:virtual_value] = association_value
+        end
+
+        Association.new(name, serializer, reflection_options)
+      end
+
+      private
+
+      def serializer_options(parent_serializer_options, reflection_options)
+        serializer = reflection_options.fetch(:serializer, nil)
+
+        serializer_options = parent_serializer_options.except(:serializer)
+        serializer_options[:serializer] = serializer if serializer
+        serializer_options
+      end
+    end
+  end
+end

lib/active_model/serializer/singular_reflection.rb

@@ -0,0 +1,7 @@
+module ActiveModel
+  class Serializer
+    # @api private
+    class SingularReflection < Reflection
+    end
+  end
+end