active_model_serializers 0.8.3 → 0.10.0.rc4

data/lib/active_model/serializer/fieldset.rb

@@ -0,0 +1,31 @@
+module ActiveModel
+  class Serializer
+    class Fieldset
+      def initialize(fields)
+        @raw_fields = fields || {}
+      end
+
+      def fields
+        @fields ||= parsed_fields
+      end
+
+      def fields_for(type)
+        fields[type.singularize.to_sym] || fields[type.pluralize.to_sym]
+      end
+
+      protected
+
+      attr_reader :raw_fields
+
+      private
+
+      def parsed_fields
+        if raw_fields.is_a?(Hash)
+          raw_fields.each_with_object({}) { |(k, v), h| h[k.to_sym] = v.map(&:to_sym) }
+        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/include_tree.rb

@@ -0,0 +1,111 @@
+module ActiveModel
+  class Serializer
+    # TODO: description of this class, and overview of how it's used
+    class IncludeTree
+      module Parsing
+        module_function
+
+        # Translates a comma separated list of dot separated paths (JSON API 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)
+          # TODO: Needs comment walking through the process of what all this is doing.
+          included.delete(' ').split(',').reduce({}) do |hash, path|
+            include_tree = path.split('.').reverse_each.reduce({}) { |a, e| { e.to_sym => a } }
+            hash.deep_merge!(include_tree)
+          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: {} } } }`.
+        #
+        # @example
+        #  `[:author, :comments => [:author]]`
+        #
+        #   would become
+        #
+        #   `{:author => {}, :comments => { author: {} } }`
+        #
+        # @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({}) do |(key, value), hash|
+              hash[key] = include_args_to_hash(value)
+            end
+          when Array
+            included.reduce({}) { |a, e| a.deep_merge!(include_args_to_hash(e)) }
+          when String
+            include_string_to_hash(included)
+          else
+            {}
+          end
+        end
+      end
+
+      # Builds an IncludeTree from a comma separated list of dot separated paths (JSON API format).
+      # @example `'posts.author, posts.comments.upvotes, posts.comments.author'`
+      #
+      # @param [String] included
+      # @return [IncludeTree]
+      #
+      def self.from_string(included)
+        new(Parsing.include_string_to_hash(included))
+      end
+
+      # Translates the arguments passed to the include option into an IncludeTree.
+      # The format can be either a String (see #from_string), an Array of Symbols and Hashes, or a mix of both.
+      # @example `posts: [:author, comments: [:author, :upvotes]]`
+      #
+      # @param [Symbol, Hash, Array, String] included
+      # @return [IncludeTree]
+      #
+      def self.from_include_args(included)
+        return included if included.is_a?(IncludeTree)
+
+        new(Parsing.include_args_to_hash(included))
+      end
+
+      # @param [Hash] hash
+      def initialize(hash = {})
+        @hash = hash
+      end
+
+      def key?(key)
+        @hash.key?(key) || @hash.key?(:*) || @hash.key?(:**)
+      end
+
+      def [](key)
+        # TODO(beauby): Adopt a lazy caching strategy for generating subtrees.
+        case
+        when @hash.key?(key)
+          self.class.new(@hash[key])
+        when @hash.key?(:*)
+          self.class.new(@hash[:*])
+        when @hash.key?(:**)
+          self.class.new(:** => {})
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/links.rb

@@ -0,0 +1,33 @@
+module ActiveModel
+  class Serializer
+    module Links
+      extend ActiveSupport::Concern
+
+      included do
+        with_options instance_writer: false, instance_reader: true do |serializer|
+          serializer.class_attribute :_links # @api private
+          self._links ||= {}
+        end
+
+        extend ActiveSupport::Autoload
+      end
+
+      module ClassMethods
+        def inherited(base)
+          super
+          base._links = _links.dup
+        end
+
+        # Define a link on a serializer.
+        # @example
+        #   link :self { "//example.com/posts/#{object.id}" }
+        # @example
+        #   link :self, "//example.com/user"
+        #
+        def link(name, value = nil, &block)
+          _links[name] = block || value
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/lint.rb

@@ -0,0 +1,142 @@
+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, and
+    # is part of the (self-expiring) cache_key, 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>updated_at</tt> and if it takes no
+    # arguments.
+    # Fails otherwise.
+    #
+    # <tt>updated_at</tt> returns a Time object or iso8601 string and
+    # is part of the (self-expiring) cache_key, which is used by the adapter.
+    # It is not required unless caching is enabled.
+    def test_updated_at
+      assert_respond_to resource, :updated_at
+      actual_arity = resource.method(:updated_at).arity
+      assert_equal 0, actual_arity
+    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 0, resource.method(:id).arity
+    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/reflection.rb

@@ -0,0 +1,91 @@
+require 'active_model/serializer/field'
+
+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
+    #     has_many :comments, key: :last_comments do
+    #       object.comments.last(1)
+    #     end
+    #     has_many :secret_meta_data, if: :is_admin?
+    #
+    #     def is_admin?
+    #       current_user.admin?
+    #     end
+    #   end
+    #
+    #  Specifically, the association 'comments' is evaluated two different ways:
+    #  1) as 'comments' and named 'comments'.
+    #  2) as 'object.comments.last(1)' and named 'last_comments'.
+    #
+    #  PostSerializer._reflections #=>
+    #    # [
+    #    #   HasOneReflection.new(:author, serializer: AuthorSerializer),
+    #    #   HasManyReflection.new(:comments)
+    #    #   HasManyReflection.new(:comments, { key: :last_comments }, #<Block>)
+    #    #   HasManyReflection.new(:secret_meta_data, { if: :is_admin? })
+    #    # ]
+    #
+    # So you can inspect reflections in your Adapters.
+    #
+    class Reflection < Field
+      # 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 = value(subject)
+        reflection_options = options.dup
+        serializer_class = subject.class.serializer_for(association_value, reflection_options)
+
+        if serializer_class
+          begin
+            serializer = serializer_class.new(
+              association_value,
+              serializer_options(subject, parent_serializer_options, reflection_options)
+            )
+          rescue ActiveModel::Serializer::CollectionSerializer::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(subject, 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[:serializer_context_class] = subject.class
+        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/type.rb

@@ -0,0 +1,25 @@
+module ActiveModel
+  class Serializer
+    module Type
+      extend ActiveSupport::Concern
+
+      included do
+        with_options instance_writer: false, instance_reader: true do |serializer|
+          serializer.class_attribute :_type # @api private
+        end
+
+        extend ActiveSupport::Autoload
+      end
+
+      module ClassMethods
+        # Set the JSON API type of a serializer.
+        # @example
+        #   class AdminAuthorSerializer < ActiveModel::Serializer
+        #     type 'authors'
+        def type(type)
+          self._type = type
+        end
+      end
+    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.rc4'
   end
 end