active_model_serializers 0.8.3 → 0.10.0.rc3

data/lib/active_model/serializer/associations.rb

@@ -1,230 +1,94 @@
 module ActiveModel
   class Serializer
-    module Associations #:nodoc:
-      class Config #:nodoc:
-        class_attribute :options
-
-        def self.refine(name, class_options)
-          current_class = self
-
-          Class.new(self) do
-            singleton_class.class_eval do
-              define_method(:to_s) do
-                "(subclass of #{current_class.name})"
-              end
-
-              alias inspect to_s
-            end
-
-            self.options = class_options
-
-            # cache the root so we can reuse it without falling back on a per-instance basis
-            begin
-              self.options[:root] ||= self.new(name, nil).root
-            rescue
-              # this could fail if it needs a valid source, for example a polymorphic association
-            end
-
-          end
-        end
-
-        self.options = {}
-
-        def initialize(name, source, options={})
-          @name = name
-          @source = source
-          @options = options
-        end
-
-        def option(key, default=nil)
-          if @options.key?(key)
-            @options[key]
-          elsif self.class.options.key?(key)
-            self.class.options[key]
-          else
-            default
-          end
-        end
-
-        def target_serializer
-          serializer = option(:serializer)
-          serializer.is_a?(String) ? serializer.constantize : serializer
-        end
-
-        def source_serializer
-          @source
-        end
-
-        def key
-          option(:key) || @name
-        end
-
-        def root
-          option(:root) || @name
-        end
-
-        def name
-          option(:name) || @name
-        end
-
-        def associated_object
-          option(:value) || source_serializer.send(name)
-        end
-
-        def embed_ids?
-          [:id, :ids].include? option(:embed, source_serializer._embed)
-        end
-
-        def embed_objects?
-          [:object, :objects].include? option(:embed, source_serializer._embed)
-        end
-
-        def embed_in_root?
-          option(:include, source_serializer._root_embed)
-        end
-
-        def embeddable?
-          !associated_object.nil?
-        end
-
-      protected
-
-        def find_serializable(object)
-          if target_serializer
-            target_serializer.new(object, source_serializer.options)
-          elsif object.respond_to?(:active_model_serializer) && (ams = object.active_model_serializer)
-            ams.new(object, source_serializer.options)
-          else
-            object
-          end
-        end
+    # 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
 
-      class HasMany < Config #:nodoc:
-        def key
-          if key = option(:key)
-            key
-          elsif embed_ids?
-            "#{@name.to_s.singularize}_ids".to_sym
-          else
-            @name
-          end
-        end
-
-        def embed_key
-          if key = option(:embed_key)
-            key
-          else
-            :id
-          end
-        end
-
-        def serialize
-          associated_object.map do |item|
-            find_serializable(item).serializable_hash
-          end
-        end
-
-        def serializables
-          associated_object.map do |item|
-            find_serializable(item)
-          end
-        end
-
-        def serialize_ids
-          ids_key = "#{@name.to_s.singularize}_ids".to_sym
-          if !option(:embed_key) && !source_serializer.respond_to?(@name.to_s) && source_serializer.object.respond_to?(ids_key)
-            source_serializer.object.read_attribute_for_serialization(ids_key)
-          else
-            associated_object.map do |item|
-              item.read_attribute_for_serialization(embed_key)
-            end
-          end
+      module ClassMethods
+        def inherited(base)
+          base._reflections = self._reflections.try(:dup) || []
+        end
+
+        # @param [Symbol] name of the association
+        # @param [Hash<Symbol => any>] options for the reflection
+        # @return [void]
+        #
+        # @example
+        #  has_many :comments, serializer: CommentSummarySerializer
+        #
+        def has_many(name, options = {})
+          associate HasManyReflection.new(name, options)
+        end
+
+        # @param [Symbol] name of the association
+        # @param [Hash<Symbol => any>] options for the reflection
+        # @return [void]
+        #
+        # @example
+        #  belongs_to :author, serializer: AuthorSerializer
+        #
+        def belongs_to(name, options = {})
+          associate BelongsToReflection.new(name, options)
+        end
+
+        # @param [Symbol] name of the association
+        # @param [Hash<Symbol => any>] options for the reflection
+        # @return [void]
+        #
+        # @example
+        #  has_one :author, serializer: AuthorSerializer
+        #
+        def has_one(name, options = {})
+          associate HasOneReflection.new(name, options)
+        end
+
+        private
+
+        # Add reflection and define {name} accessor.
+        # @param [ActiveModel::Serializer::Reflection] reflection
+        # @return [void]
+        #
+        # @api private
+        #
+        def associate(reflection)
+          self._reflections = _reflections.dup
+
+          define_method reflection.name do
+            object.send reflection.name
+          end unless method_defined?(reflection.name)
+
+          self._reflections << reflection
         end
       end
 
-      class HasOne < Config #:nodoc:
-        def embeddable?
-          if polymorphic? && associated_object.nil?
-            false
-          else
-            true
-          end
-        end
-
-        def polymorphic?
-          option :polymorphic
-        end
-
-        def root
-          if root = option(:root)
-            root
-          elsif polymorphic?
-            associated_object.class.to_s.pluralize.demodulize.underscore.to_sym
-          else
-            @name.to_s.pluralize.to_sym
-          end
-        end
-
-        def key
-          if key = option(:key)
-            key
-          elsif embed_ids? && !polymorphic?
-            "#{@name}_id".to_sym
-          else
-            @name
-          end
-        end
-
-        def embed_key
-          if key = option(:embed_key)
-            key
-          else
-            :id
-          end
-        end
-
-        def polymorphic_key
-          associated_object.class.to_s.demodulize.underscore.to_sym
-        end
-
-        def serialize
-          object = associated_object
-
-          if object && polymorphic?
-            {
-              :type => polymorphic_key,
-              polymorphic_key => find_serializable(object).serializable_hash
-            }
-          elsif object
-            find_serializable(object).serializable_hash
-          end
-        end
-
-        def serializables
-          object = associated_object
-          value = object && find_serializable(object)
-          value ? [value] : []
-        end
-
-        def serialize_ids
-          id_key = "#{@name}_id".to_sym
+      # @return [Enumerator<Association>]
+      #
+      def associations
+        return unless object
 
-          if polymorphic?
-            if associated_object
-              {
-                :type => polymorphic_key,
-                :id => associated_object.read_attribute_for_serialization(embed_key)
-              }
-            else
-              nil
-            end
-          elsif !option(:embed_key) && !source_serializer.respond_to?(@name.to_s) && source_serializer.object.respond_to?(id_key)
-            source_serializer.object.read_attribute_for_serialization(id_key)
-          elsif associated_object
-            associated_object.read_attribute_for_serialization(embed_key)
-          else
-            nil
+        Enumerator.new do |y|
+          self.class._reflections.each do |reflection|
+            y.yield reflection.build_association(self, options)
           end
         end
       end

data/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

data/lib/active_model/serializer/collection_reflection.rb

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

data/lib/active_model/serializer/configuration.rb

@@ -0,0 +1,14 @@
+module ActiveModel
+  class Serializer
+    module Configuration
+      include ActiveSupport::Configurable
+      extend ActiveSupport::Concern
+
+      included do |base|
+        base.config.array_serializer = ActiveModel::Serializer::ArraySerializer
+        base.config.adapter = :flatten_json
+        base.config.jsonapi_resource_type = :plural
+      end
+    end
+  end
+end

data/lib/active_model/serializer/fieldset.rb

@@ -0,0 +1,40 @@
+module ActiveModel
+  class Serializer
+    class Fieldset
+      def initialize(fields, root = nil)
+        @root       = root
+        @raw_fields = fields
+      end
+
+      def fields
+        @fields ||= parsed_fields
+      end
+
+      def fields_for(serializer)
+        key = serializer.json_key
+        fields[key.to_sym] || fields[key.pluralize.to_sym]
+      end
+
+      private
+
+      ActiveModelSerializers.silence_warnings do
+        attr_reader :raw_fields, :root
+      end
+
+      def parsed_fields
+        if raw_fields.is_a?(Hash)
+          raw_fields.inject({}) { |h, (k, v)| h[k.to_sym] = v.map(&:to_sym); h }
+        elsif raw_fields.is_a?(Array)
+          if root.nil?
+            raise ArgumentError, 'The root argument must be specified if the fields argument is an array.'
+          end
+          hash = {}
+          hash[root.to_sym] = raw_fields.map(&:to_sym)
+          hash
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/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

data/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

data/lib/active_model/serializer/lint.rb

@@ -0,0 +1,129 @@
+module ActiveModel::Serializer::Lint
+  # == Active \Model \Serializer \Lint \Tests
+  #
+  # You can test whether an object is compliant with the Active \Model \Serializers
+  # API by including <tt>ActiveModel::Serializer::Lint::Tests</tt> in your TestCase.
+  # It will include tests that tell you whether your object is fully compliant,
+  # or if not, which aspects of the API are not implemented.
+  #
+  # Note an object is not required to implement all APIs in order to work
+  # with Active \Model \Serializers. This module only intends to provide guidance in case
+  # you want all features out of the box.
+  #
+  # These tests do not attempt to determine the semantic correctness of the
+  # returned values. For instance, you could implement <tt>serializable_hash</tt> to
+  # always return +{}+, and the tests would pass. It is up to you to ensure
+  # that the values are semantically meaningful.
+  module Tests
+    # Passes if the object responds to <tt>serializable_hash</tt> and if it takes
+    # zero or one arguments.
+    # Fails otherwise.
+    #
+    # <tt>serializable_hash</tt> returns a hash representation of a object's attributes.
+    # Typically, it is implemented by including ActiveModel::Serialization.
+    def test_serializable_hash
+      assert_respond_to resource, :serializable_hash, 'The resource should respond to serializable_hash'
+      resource.serializable_hash
+      resource.serializable_hash(nil)
+    end
+
+    # Passes if the object responds to <tt>read_attribute_for_serialization</tt>
+    # and if it requires one argument (the attribute to be read).
+    # Fails otherwise.
+    #
+    # <tt>read_attribute_for_serialization</tt> gets the attribute value for serialization
+    # Typically, it is implemented by including ActiveModel::Serialization.
+    def test_read_attribute_for_serialization
+      assert_respond_to resource, :read_attribute_for_serialization, 'The resource should respond to read_attribute_for_serialization'
+      actual_arity = resource.method(:read_attribute_for_serialization).arity
+      if defined?(::Rubinius)
+        #  1 for def read_attribute_for_serialization(name); end
+        # -2 for alias :read_attribute_for_serialization :send for rbx because :shrug:
+        assert_includes [1, -2], actual_arity, "expected #{actual_arity.inspect} to be 1 or -2"
+      else
+        # using absolute value since arity is:
+        #  1 for def read_attribute_for_serialization(name); end
+        # -1 for alias :read_attribute_for_serialization :send
+        assert_includes [1, -1], actual_arity, "expected #{actual_arity.inspect} to be 1 or -1"
+      end
+    end
+
+    # Passes if the object responds to <tt>as_json</tt> and if it takes
+    # zero or one arguments.
+    # Fails otherwise.
+    #
+    # <tt>as_json</tt> returns a hash representation of a serialized object.
+    # It may delegate to <tt>serializable_hash</tt>
+    # Typically, it is implemented either by including ActiveModel::Serialization
+    # which includes ActiveModel::Serializers::JSON.
+    # or by the JSON gem when required.
+    def test_as_json
+      assert_respond_to resource, :as_json
+      resource.as_json
+      resource.as_json(nil)
+    end
+
+    # Passes if the object responds to <tt>to_json</tt> and if it takes
+    # zero or one arguments.
+    # Fails otherwise.
+    #
+    # <tt>to_json</tt> returns a string representation (JSON) of a serialized object.
+    # It may be called on the result of <tt>as_json</tt>.
+    # Typically, it is implemented on all objects when the JSON gem is required.
+    def test_to_json
+      assert_respond_to resource, :to_json
+      resource.to_json
+      resource.to_json(nil)
+    end
+
+    # Passes if the object responds to <tt>cache_key</tt> and if it takes no
+    # arguments (Rails 4.0) or a splat (Rails 4.1+).
+    # Fails otherwise.
+    #
+    # <tt>cache_key</tt> returns a (self-expiring) unique key for the object,
+    # which is used by the adapter.
+    # It is not required unless caching is enabled.
+    def test_cache_key
+      assert_respond_to resource, :cache_key
+      actual_arity = resource.method(:cache_key).arity
+      # using absolute value since arity is:
+      #   0 for Rails 4.1+, *timestamp_names
+      #  -1 for Rails 4.0, no arguments
+      assert_includes [-1, 0], actual_arity, "expected #{actual_arity.inspect} to be 0 or -1"
+    end
+
+    # Passes if the object responds to <tt>id</tt> and if it takes no
+    # arguments.
+    # Fails otherwise.
+    #
+    # <tt>id</tt> returns a unique identifier for the object.
+    # It is not required unless caching is enabled.
+    def test_id
+      assert_respond_to resource, :id
+      assert_equal resource.method(:id).arity, 0
+    end
+
+    # Passes if the object's class responds to <tt>model_name</tt> and if it
+    # is in an instance of +ActiveModel::Name+.
+    # Fails otherwise.
+    #
+    # <tt>model_name</tt> returns an ActiveModel::Name instance.
+    # It is used by the serializer to identify the object's type.
+    # It is not required unless caching is enabled.
+    def test_model_name
+      resource_class = resource.class
+      assert_respond_to resource_class, :model_name
+      assert_instance_of resource_class.model_name, ActiveModel::Name
+    end
+
+    private
+
+    def resource
+      @resource or fail "'@resource' must be set as the linted object"
+    end
+
+    def assert_instance_of(result, name)
+      assert result.instance_of?(name), "#{result} should be an instance of #{name}"
+    end
+  end
+end

data/lib/active_model/serializer/railtie.rb

@@ -0,0 +1,15 @@
+require 'rails/railtie'
+module ActiveModel
+  class Railtie < Rails::Railtie
+    initializer 'active_model_serializers.logger' do
+      ActiveSupport.on_load(:action_controller) do
+        ActiveModelSerializers.logger = ActionController::Base.logger
+      end
+    end
+
+    initializer 'generators' do |app|
+      app.load_generators
+      require 'generators/serializer/resource_override'
+    end
+  end
+end

data/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

data/lib/active_model/serializer/singular_reflection.rb

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

data/lib/active_model/serializer/utils.rb

@@ -0,0 +1,35 @@
+module ActiveModel::Serializer::Utils
+  module_function
+
+  # Translates a comma separated list of dot separated paths (JSONAPI format) into a Hash.
+  # Example: `'posts.author, posts.comments.upvotes, posts.comments.author'` would become `{ posts: { author: {}, comments: { author: {}, upvotes: {} } } }`.
+  #
+  # @param [String] included
+  # @return [Hash] a Hash representing the same tree structure
+  def include_string_to_hash(included)
+    included.delete(' ').split(',').inject({}) do |hash, path|
+      hash.deep_merge!(path.split('.').reverse_each.inject({}) { |a, e| { e.to_sym => a } })
+    end
+  end
+
+  # Translates the arguments passed to the include option into a Hash. The format can be either
+  # a String (see #include_string_to_hash), an Array of Symbols and Hashes, or a mix of both.
+  # Example: `posts: [:author, comments: [:author, :upvotes]]` would become `{ posts: { author: {}, comments: { author: {}, upvotes: {} } } }`.
+  #
+  # @param [Symbol, Hash, Array, String] included
+  # @return [Hash] a Hash representing the same tree structure
+  def include_args_to_hash(included)
+    case included
+    when Symbol
+      { included => {} }
+    when Hash
+      included.each_with_object({}) { |(key, value), hash| hash[key] = include_args_to_hash(value) }
+    when Array
+      included.inject({}) { |a, e| a.merge!(include_args_to_hash(e)) }
+    when String
+      include_string_to_hash(included)
+    else
+      {}
+    end
+  end
+end

data/lib/active_model/{serializers → serializer}/version.rb

@@ -1,5 +1,5 @@
 module ActiveModel
   class Serializer
-    VERSION = "0.8.3"
+    VERSION = '0.10.0.rc3'
   end
 end