active_model_serializers 0.8.3 → 0.10.0

data/lib/active_model_serializers/adapter/attributes.rb

@@ -0,0 +1,76 @@
+module ActiveModelSerializers
+  module Adapter
+    class Attributes < Base
+      def initialize(serializer, options = {})
+        super
+        @include_tree = ActiveModel::Serializer::IncludeTree.from_include_args(options[:include] || '*')
+        @cached_attributes = options[:cache_attributes] || {}
+      end
+
+      def serializable_hash(options = nil)
+        options = serialization_options(options)
+
+        if serializer.respond_to?(:each)
+          serializable_hash_for_collection(options)
+        else
+          serializable_hash_for_single_resource(options)
+        end
+      end
+
+      private
+
+      def serializable_hash_for_collection(options)
+        cache_attributes
+
+        serializer.map { |s| Attributes.new(s, instance_options).serializable_hash(options) }
+      end
+
+      def serializable_hash_for_single_resource(options)
+        resource = resource_object_for(options)
+        relationships = resource_relationships(options)
+        resource.merge(relationships)
+      end
+
+      def resource_relationships(options)
+        relationships = {}
+        serializer.associations(@include_tree).each do |association|
+          relationships[association.key] ||= relationship_value_for(association, options)
+        end
+
+        relationships
+      end
+
+      def relationship_value_for(association, options)
+        return association.options[:virtual_value] if association.options[:virtual_value]
+        return unless association.serializer && association.serializer.object
+
+        opts = instance_options.merge(include: @include_tree[association.key])
+        relationship_value = Attributes.new(association.serializer, opts).serializable_hash(options)
+
+        if association.options[:polymorphic] && relationship_value
+          polymorphic_type = association.serializer.object.class.name.underscore
+          relationship_value = { type: polymorphic_type, polymorphic_type.to_sym => relationship_value }
+        end
+
+        relationship_value
+      end
+
+      # Set @cached_attributes
+      def cache_attributes
+        return if @cached_attributes.present?
+
+        @cached_attributes = ActiveModel::Serializer.cache_read_multi(serializer, self, @include_tree)
+      end
+
+      def resource_object_for(options)
+        if serializer.class.cache_enabled?
+          @cached_attributes.fetch(serializer.cache_key(self)) do
+            serializer.cached_fields(options[:fields], self)
+          end
+        else
+          serializer.cached_fields(options[:fields], self)
+        end
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/base.rb

@@ -0,0 +1,83 @@
+require 'active_model_serializers/key_transform'
+
+module ActiveModelSerializers
+  module Adapter
+    class Base
+      # Automatically register adapters when subclassing
+      def self.inherited(subclass)
+        ActiveModelSerializers::Adapter.register(subclass)
+      end
+
+      attr_reader :serializer, :instance_options
+
+      def initialize(serializer, options = {})
+        @serializer = serializer
+        @instance_options = options
+      end
+
+      def cached_name
+        @cached_name ||= self.class.name.demodulize.underscore
+      end
+
+      # Subclasses that implement this method must first call
+      #   options = serialization_options(options)
+      def serializable_hash(_options = nil)
+        fail NotImplementedError, 'This is an abstract method. Should be implemented at the concrete adapter.'
+      end
+
+      def as_json(options = nil)
+        serializable_hash(options)
+      end
+
+      def fragment_cache(cached_hash, non_cached_hash)
+        non_cached_hash.merge cached_hash
+      end
+
+      def cache_check(serializer)
+        serializer.cache_check(self) do
+          yield
+        end
+      end
+
+      private
+
+      # see https://github.com/rails-api/active_model_serializers/pull/965
+      # When <tt>options</tt> is +nil+, sets it to +{}+
+      def serialization_options(options)
+        options ||= {} # rubocop:disable Lint/UselessAssignment
+      end
+
+      def root
+        serializer.json_key.to_sym if serializer.json_key
+      end
+
+      class << self
+        # Sets the default transform for the adapter.
+        #
+        # @return [Symbol] the default transform for the adapter
+        def default_key_transform
+          :unaltered
+        end
+
+        # Determines the transform to use in order of precedence:
+        #   adapter option, global config, adapter default.
+        #
+        # @param options [Object]
+        # @return [Symbol] the transform to use
+        def transform(options)
+          return options[:key_transform] if options && options[:key_transform]
+          ActiveModelSerializers.config.key_transform || default_key_transform
+        end
+
+        # Transforms the casing of the supplied value.
+        #
+        # @param value [Object] the value to be transformed
+        # @param options [Object] serializable resource options
+        # @return [Symbol] the default transform for the adapter
+        def transform_key_casing!(value, options)
+          KeyTransform.send(transform(options), value)
+        end
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/json.rb

@@ -0,0 +1,21 @@
+module ActiveModelSerializers
+  module Adapter
+    class Json < Base
+      def serializable_hash(options = nil)
+        options = serialization_options(options)
+        serialized_hash = { root => Attributes.new(serializer, instance_options).serializable_hash(options) }
+        serialized_hash[meta_key] = meta unless meta.blank?
+
+        self.class.transform_key_casing!(serialized_hash, instance_options)
+      end
+
+      def meta
+        instance_options.fetch(:meta, nil)
+      end
+
+      def meta_key
+        instance_options.fetch(:meta_key, 'meta'.freeze)
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/json_api/deserialization.rb

@@ -0,0 +1,213 @@
+module ActiveModelSerializers
+  module Adapter
+    class JsonApi
+      # NOTE(Experimental):
+      # This is an experimental feature. Both the interface and internals could be subject
+      # to changes.
+      module Deserialization
+        InvalidDocument = Class.new(ArgumentError)
+
+        module_function
+
+        # Transform a JSON API document, containing a single data object,
+        # into a hash that is ready for ActiveRecord::Base.new() and such.
+        # Raises InvalidDocument if the payload is not properly formatted.
+        #
+        # @param [Hash|ActionController::Parameters] document
+        # @param [Hash] options
+        #   only: Array of symbols of whitelisted fields.
+        #   except: Array of symbols of blacklisted fields.
+        #   keys: Hash of translated keys (e.g. :author => :user).
+        #   polymorphic: Array of symbols of polymorphic fields.
+        # @return [Hash]
+        #
+        # @example
+        #   document = {
+        #     data: {
+        #       id: 1,
+        #       type: 'post',
+        #       attributes: {
+        #         title: 'Title 1',
+        #         date: '2015-12-20'
+        #       },
+        #       associations: {
+        #         author: {
+        #           data: {
+        #             type: 'user',
+        #             id: 2
+        #           }
+        #         },
+        #         second_author: {
+        #           data: nil
+        #         },
+        #         comments: {
+        #           data: [{
+        #             type: 'comment',
+        #             id: 3
+        #           },{
+        #             type: 'comment',
+        #             id: 4
+        #           }]
+        #         }
+        #       }
+        #     }
+        #   }
+        #
+        #   parse(document) #=>
+        #     # {
+        #     #   title: 'Title 1',
+        #     #   date: '2015-12-20',
+        #     #   author_id: 2,
+        #     #   second_author_id: nil
+        #     #   comment_ids: [3, 4]
+        #     # }
+        #
+        #   parse(document, only: [:title, :date, :author],
+        #                   keys: { date: :published_at },
+        #                   polymorphic: [:author]) #=>
+        #     # {
+        #     #   title: 'Title 1',
+        #     #   published_at: '2015-12-20',
+        #     #   author_id: '2',
+        #     #   author_type: 'people'
+        #     # }
+        #
+        def parse!(document, options = {})
+          parse(document, options) do |invalid_payload, reason|
+            fail InvalidDocument, "Invalid payload (#{reason}): #{invalid_payload}"
+          end
+        end
+
+        # Same as parse!, but returns an empty hash instead of raising InvalidDocument
+        # on invalid payloads.
+        def parse(document, options = {})
+          document = document.dup.permit!.to_h if document.is_a?(ActionController::Parameters)
+
+          validate_payload(document) do |invalid_document, reason|
+            yield invalid_document, reason if block_given?
+            return {}
+          end
+
+          primary_data = document['data']
+          attributes = primary_data['attributes'] || {}
+          attributes['id'] = primary_data['id'] if primary_data['id']
+          relationships = primary_data['relationships'] || {}
+
+          filter_fields(attributes, options)
+          filter_fields(relationships, options)
+
+          hash = {}
+          hash.merge!(parse_attributes(attributes, options))
+          hash.merge!(parse_relationships(relationships, options))
+
+          hash
+        end
+
+        # Checks whether a payload is compliant with the JSON API spec.
+        #
+        # @api private
+        # rubocop:disable Metrics/CyclomaticComplexity
+        def validate_payload(payload)
+          unless payload.is_a?(Hash)
+            yield payload, 'Expected hash'
+            return
+          end
+
+          primary_data = payload['data']
+          unless primary_data.is_a?(Hash)
+            yield payload, { data: 'Expected hash' }
+            return
+          end
+
+          attributes = primary_data['attributes'] || {}
+          unless attributes.is_a?(Hash)
+            yield payload, { data: { attributes: 'Expected hash or nil' } }
+            return
+          end
+
+          relationships = primary_data['relationships'] || {}
+          unless relationships.is_a?(Hash)
+            yield payload, { data: { relationships: 'Expected hash or nil' } }
+            return
+          end
+
+          relationships.each do |(key, value)|
+            unless value.is_a?(Hash) && value.key?('data')
+              yield payload, { data: { relationships: { key => 'Expected hash with :data key' } } }
+            end
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity
+
+        # @api private
+        def filter_fields(fields, options)
+          if (only = options[:only])
+            fields.slice!(*Array(only).map(&:to_s))
+          elsif (except = options[:except])
+            fields.except!(*Array(except).map(&:to_s))
+          end
+        end
+
+        # @api private
+        def field_key(field, options)
+          (options[:keys] || {}).fetch(field.to_sym, field).to_sym
+        end
+
+        # @api private
+        def parse_attributes(attributes, options)
+          transform_keys(attributes, options)
+            .map { |(k, v)| { field_key(k, options) => v } }
+            .reduce({}, :merge)
+        end
+
+        # Given an association name, and a relationship data attribute, build a hash
+        # mapping the corresponding ActiveRecord attribute to the corresponding value.
+        #
+        # @example
+        #   parse_relationship(:comments, [{ 'id' => '1', 'type' => 'comments' },
+        #                                  { 'id' => '2', 'type' => 'comments' }],
+        #                                 {})
+        #    # => { :comment_ids => ['1', '2'] }
+        #   parse_relationship(:author, { 'id' => '1', 'type' => 'users' }, {})
+        #    # => { :author_id => '1' }
+        #   parse_relationship(:author, nil, {})
+        #    # => { :author_id => nil }
+        # @param [Symbol] assoc_name
+        # @param [Hash] assoc_data
+        # @param [Hash] options
+        # @return [Hash{Symbol, Object}]
+        #
+        # @api private
+        def parse_relationship(assoc_name, assoc_data, options)
+          prefix_key = field_key(assoc_name, options).to_s.singularize
+          hash =
+            if assoc_data.is_a?(Array)
+              { "#{prefix_key}_ids".to_sym => assoc_data.map { |ri| ri['id'] } }
+            else
+              { "#{prefix_key}_id".to_sym => assoc_data ? assoc_data['id'] : nil }
+            end
+
+          polymorphic = (options[:polymorphic] || []).include?(assoc_name.to_sym)
+          if polymorphic
+            hash["#{prefix_key}_type".to_sym] = assoc_data.present? ? assoc_data['type'] : nil
+          end
+
+          hash
+        end
+
+        # @api private
+        def parse_relationships(relationships, options)
+          transform_keys(relationships, options)
+            .map { |(k, v)| parse_relationship(k, v['data'], options) }
+            .reduce({}, :merge)
+        end
+
+        # @api private
+        def transform_keys(hash, options)
+          transform = options[:key_transform] || :underscore
+          KeyTransform.send(transform, hash)
+        end
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/json_api/error.rb

@@ -0,0 +1,96 @@
+module ActiveModelSerializers
+  module Adapter
+    class JsonApi < Base
+      module Error
+        # rubocop:disable Style/AsciiComments
+        UnknownSourceTypeError = Class.new(ArgumentError)
+
+        # Builds a JSON API Errors Object
+        # {http://jsonapi.org/format/#errors JSON API Errors}
+        #
+        # @param [ActiveModel::Serializer::ErrorSerializer] error_serializer
+        # @return [Array<Symbol, Array<String>>] i.e. attribute_name, [attribute_errors]
+        def self.resource_errors(error_serializer, options)
+          error_serializer.as_json.flat_map do |attribute_name, attribute_errors|
+            attribute_name = JsonApi.send(:transform_key_casing!, attribute_name,
+              options)
+            attribute_error_objects(attribute_name, attribute_errors)
+          end
+        end
+
+        # definition:
+        #   JSON Object
+        #
+        # properties:
+        #   ☐ id      : String
+        #   ☐ status  : String
+        #   ☐ code    : String
+        #   ☐ title   : String
+        #   ☑ detail  : String
+        #   ☐ links
+        #   ☐ meta
+        #   ☑ error_source
+        #
+        # description:
+        #   id     : A unique identifier for this particular occurrence of the problem.
+        #   status : The HTTP status code applicable to this problem, expressed as a string value
+        #   code   : An application-specific error code, expressed as a string value.
+        #   title  : A short, human-readable summary of the problem. It **SHOULD NOT** change from
+        #     occurrence to occurrence of the problem, except for purposes of localization.
+        #   detail : A human-readable explanation specific to this occurrence of the problem.
+        # structure:
+        #   {
+        #     title: 'SystemFailure',
+        #     detail: 'something went terribly wrong',
+        #     status: '500'
+        #   }.merge!(errorSource)
+        def self.attribute_error_objects(attribute_name, attribute_errors)
+          attribute_errors.map do |attribute_error|
+            {
+              source: error_source(:pointer, attribute_name),
+              detail: attribute_error
+            }
+          end
+        end
+
+        # errorSource
+        # description:
+        #   oneOf
+        #     ☑ pointer   : String
+        #     ☑ parameter : String
+        #
+        # description:
+        #   pointer: A JSON Pointer RFC6901 to the associated entity in the request document e.g. "/data"
+        #   for a primary data object, or "/data/attributes/title" for a specific attribute.
+        #   https://tools.ietf.org/html/rfc6901
+        #
+        #   parameter: A string indicating which query parameter caused the error
+        # structure:
+        #   if is_attribute?
+        #     {
+        #       pointer: '/data/attributes/red-button'
+        #     }
+        #   else
+        #     {
+        #       parameter: 'pres'
+        #     }
+        #   end
+        def self.error_source(source_type, attribute_name)
+          case source_type
+          when :pointer
+            {
+              pointer: ActiveModelSerializers::JsonPointer.new(:attribute, attribute_name)
+            }
+          when :parameter
+            {
+              parameter: attribute_name
+            }
+          else
+            fail UnknownSourceTypeError, "Unknown source type '#{source_type}' for attribute_name '#{attribute_name}'"
+          end
+        end
+        # rubocop:enable Style/AsciiComments
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/json_api/jsonapi.rb

@@ -0,0 +1,49 @@
+module ActiveModelSerializers
+  module Adapter
+    class JsonApi < Base
+      # {http://jsonapi.org/format/#document-jsonapi-object Jsonapi Object}
+
+      # toplevel_jsonapi
+      # definition:
+      #   JSON Object
+      #
+      # properties:
+      #   version : String
+      #   meta
+      #
+      # description:
+      #   An object describing the server's implementation
+      # structure:
+      #   {
+      #     version: ActiveModelSerializers.config.jsonapi_version,
+      #     meta: ActiveModelSerializers.config.jsonapi_toplevel_meta
+      #   }.reject! { |_, v| v.blank? }
+      # prs:
+      #   https://github.com/rails-api/active_model_serializers/pull/1050
+      module Jsonapi
+        module_function
+
+        def add!(hash)
+          hash.merge!(object) if include_object?
+        end
+
+        def include_object?
+          ActiveModelSerializers.config.jsonapi_include_toplevel_object
+        end
+
+        # TODO: see if we can cache this
+        def object
+          object = {
+            jsonapi: {
+              version: ActiveModelSerializers.config.jsonapi_version,
+              meta: ActiveModelSerializers.config.jsonapi_toplevel_meta
+            }
+          }
+          object[:jsonapi].reject! { |_, v| v.blank? }
+
+          object
+        end
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/json_api/link.rb

@@ -0,0 +1,83 @@
+module ActiveModelSerializers
+  module Adapter
+    class JsonApi
+      # link
+      # definition:
+      #  oneOf
+      #    linkString
+      #    linkObject
+      #
+      # description:
+      #   A link **MUST** be represented as either: a string containing the link's URL or a link
+      #   object."
+      # structure:
+      #   if href?
+      #     linkString
+      #   else
+      #     linkObject
+      #   end
+      #
+      # linkString
+      # definition:
+      #   URI
+      #
+      # description:
+      #   A string containing the link's URL.
+      # structure:
+      #  'http://example.com/link-string'
+      #
+      # linkObject
+      # definition:
+      #   JSON Object
+      #
+      # properties:
+      #   href (required) : URI
+      #   meta
+      # structure:
+      #   {
+      #     href: 'http://example.com/link-object',
+      #     meta: meta,
+      #   }.reject! {|_,v| v.nil? }
+      class Link
+        include SerializationContext::UrlHelpers
+
+        def initialize(serializer, value)
+          @_routes ||= nil # handles warning
+          # actionpack-4.0.13/lib/action_dispatch/routing/route_set.rb:417: warning: instance variable @_routes not initialized
+          @object = serializer.object
+          @scope = serializer.scope
+          # Use the return value of the block unless it is nil.
+          if value.respond_to?(:call)
+            @value = instance_eval(&value)
+          else
+            @value = value
+          end
+        end
+
+        def href(value)
+          @href = value
+          nil
+        end
+
+        def meta(value)
+          @meta = value
+          nil
+        end
+
+        def as_json
+          return @value if @value
+
+          hash = {}
+          hash[:href] = @href if defined?(@href)
+          hash[:meta] = @meta if defined?(@meta)
+
+          hash
+        end
+
+        protected
+
+        attr_reader :object, :scope
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter/json_api/meta.rb

@@ -0,0 +1,37 @@
+module ActiveModelSerializers
+  module Adapter
+    class JsonApi
+      # meta
+      # definition:
+      #   JSON Object
+      #
+      # description:
+      #   Non-standard meta-information that can not be represented as an attribute or relationship.
+      # structure:
+      #   {
+      #     attitude: 'adjustable'
+      #   }
+      class Meta
+        def initialize(serializer)
+          @object = serializer.object
+          @scope = serializer.scope
+
+          # Use the return value of the block unless it is nil.
+          if serializer._meta.respond_to?(:call)
+            @value = instance_eval(&serializer._meta)
+          else
+            @value = serializer._meta
+          end
+        end
+
+        def as_json
+          @value
+        end
+
+        protected
+
+        attr_reader :object, :scope
+      end
+    end
+  end
+end