active_model_serializers 0.8.3 → 0.10.0

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,35 @@
+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) { resource_url(object) }
+        # @example
+        #   link(:self) { "http://example.com/resource/#{object.id}" }
+        # @example
+        #   link :resource, "http://example.com/resource"
+        #
+        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,146 @@
+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
+      # using absolute value since arity is:
+      #  1 for def read_attribute_for_serialization(name); end
+      # -1 for alias :read_attribute_for_serialization :send
+      assert_equal 1, actual_arity.abs, "expected #{actual_arity.inspect}.abs to be 1 or -1"
+    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>
+    # 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
+      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
+
+    def test_active_model_errors
+      assert_respond_to resource, :errors
+    end
+
+    def test_active_model_errors_human_attribute_name
+      assert_respond_to resource.class, :human_attribute_name
+      assert_equal(-2, resource.class.method(:human_attribute_name).arity)
+    end
+
+    def test_active_model_errors_lookup_ancestors
+      assert_respond_to resource.class, :lookup_ancestors
+      assert_equal 0, resource.class.method(:lookup_ancestors).arity
+    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/meta.rb

@@ -0,0 +1,29 @@
+module ActiveModel
+  class Serializer
+    module Meta
+      extend ActiveSupport::Concern
+
+      included do
+        with_options instance_writer: false, instance_reader: true do |serializer|
+          serializer.class_attribute :_meta # @api private
+        end
+
+        extend ActiveSupport::Autoload
+      end
+
+      module ClassMethods
+        # Set the JSON API meta attribute of a serializer.
+        # @example
+        #   class AdminAuthorSerializer < ActiveModel::Serializer
+        #     meta { stuff: 'value' }
+        # @example
+        #     meta do
+        #       { comment_count: object.comments.count }
+        #     end
+        def meta(value = nil, &block)
+          self._meta = block || value
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/null.rb

@@ -0,0 +1,17 @@
+module ActiveModel
+  class Serializer
+    class Null < Serializer
+      def attributes(*)
+        {}
+      end
+
+      def associations(*)
+        {}
+      end
+
+      def serializable_hash(*)
+        {}
+      end
+    end
+  end
+end

data/lib/active_model/serializer/reflection.rb

@@ -0,0 +1,147 @@
+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
+      def initialize(*)
+        super
+        @_links = {}
+        @_include_data = true
+        @_meta = nil
+      end
+
+      def link(name, value = nil, &block)
+        @_links[name] = block || value
+        :nil
+      end
+
+      def meta(value = nil, &block)
+        @_meta = block || value
+        :nil
+      end
+
+      def include_data(value = true)
+        @_include_data = value
+        :nil
+      end
+
+      # @param serializer [ActiveModel::Serializer]
+      # @yield [ActiveModel::Serializer]
+      # @return [:nil, associated resource or resource collection]
+      # @example
+      #   has_one :blog do |serializer|
+      #     serializer.cached_blog
+      #   end
+      #
+      #   def cached_blog
+      #     cache_store.fetch("cached_blog:#{object.updated_at}") do
+      #       Blog.find(object.blog_id)
+      #     end
+      #   end
+      def value(serializer)
+        @object = serializer.object
+        @scope = serializer.scope
+
+        if block
+          block_value = instance_exec(serializer, &block)
+          if block_value == :nil
+            serializer.read_attribute_for_serialization(name)
+          else
+            block_value
+          end
+        else
+          serializer.read_attribute_for_serialization(name)
+        end
+      end
+
+      # 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)
+        reflection_options[:include_data] = @_include_data
+
+        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, @_links, @_meta)
+      end
+
+      protected
+
+      attr_accessor :object, :scope
+
+      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 && type.to_s
+        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'.freeze
   end
 end