active_model_serializers 0.10.0.rc4 → 0.10.0.rc5

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