active_model_serializers 0.8.3 → 0.10.0.rc4

data/lib/active_model/serializable_resource.rb

@@ -0,0 +1,72 @@
+require 'set'
+module ActiveModel
+  class SerializableResource
+    ADAPTER_OPTION_KEYS = Set.new([:include, :fields, :adapter, :meta, :meta_key, :links])
+    include ActiveModelSerializers::Logging
+
+    delegate :serializable_hash, :as_json, :to_json, to: :adapter
+    notify :serializable_hash, :render
+    notify :as_json, :render
+    notify :to_json, :render
+
+    # Primary interface to composing a resource with a serializer and adapter.
+    # @return the serializable_resource, ready for #as_json/#to_json/#serializable_hash.
+    def initialize(resource, options = {})
+      @resource = resource
+      @adapter_opts, @serializer_opts =
+        options.partition { |k, _| ADAPTER_OPTION_KEYS.include? k }.map { |h| Hash[h] }
+    end
+
+    def serialization_scope=(scope)
+      serializer_opts[:scope] = scope
+    end
+
+    def serialization_scope
+      serializer_opts[:scope]
+    end
+
+    def serialization_scope_name=(scope_name)
+      serializer_opts[:scope_name] = scope_name
+    end
+
+    def adapter
+      @adapter ||= ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)
+    end
+    alias_method :adapter_instance, :adapter
+
+    def serializer_instance
+      @serializer_instance ||= serializer.new(resource, serializer_opts)
+    end
+
+    # Get serializer either explicitly :serializer or implicitly from resource
+    # Remove :serializer key from serializer_opts
+    # Replace :serializer key with :each_serializer if present
+    def serializer
+      @serializer ||=
+        begin
+          @serializer = serializer_opts.delete(:serializer)
+          @serializer ||= ActiveModel::Serializer.serializer_for(resource)
+
+          if serializer_opts.key?(:each_serializer)
+            serializer_opts[:serializer] = serializer_opts.delete(:each_serializer)
+          end
+          @serializer
+        end
+    end
+    alias_method :serializer_class, :serializer
+
+    # True when no explicit adapter given, or explicit appear is truthy (non-nil)
+    # False when explicit adapter is falsy (nil or false)
+    def use_adapter?
+      !(adapter_opts.key?(:adapter) && !adapter_opts[:adapter])
+    end
+
+    def serializer?
+      use_adapter? && !!(serializer)
+    end
+
+    protected
+
+    attr_reader :resource, :adapter_opts, :serializer_opts
+  end
+end

data/lib/active_model/serializer/adapter/attributes.rb

@@ -0,0 +1,66 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Attributes < Base
+        def initialize(serializer, options = {})
+          super
+          @include_tree = IncludeTree.from_include_args(options[:include] || '*')
+        end
+
+        def serializable_hash(options = nil)
+          options ||= {}
+
+          if serializer.respond_to?(:each)
+            serializable_hash_for_collection(options)
+          else
+            serializable_hash_for_single_resource(options)
+          end
+        end
+
+        def fragment_cache(cached_hash, non_cached_hash)
+          Json::FragmentCache.new.fragment_cache(cached_hash, non_cached_hash)
+        end
+
+        private
+
+        def serializable_hash_for_collection(options)
+          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])
+          Attributes.new(association.serializer, opts).serializable_hash(options)
+        end
+
+        # no-op: Attributes adapter does not include meta data, because it does not support root.
+        def include_meta(json)
+          json
+        end
+
+        def resource_object_for(options)
+          cache_check(serializer) do
+            serializer.attributes(options[:fields])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/base.rb

@@ -0,0 +1,58 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Base
+        # Automatically register adapters when subclassing
+        def self.inherited(subclass)
+          ActiveModel::Serializer::Adapter.register(subclass)
+        end
+
+        attr_reader :serializer, :instance_options
+
+        def initialize(serializer, options = {})
+          @serializer = serializer
+          @instance_options = options
+        end
+
+        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)
+          hash = serializable_hash(options)
+          include_meta(hash)
+          hash
+        end
+
+        def fragment_cache(*_args)
+          fail NotImplementedError, 'This is an abstract method. Should be implemented at the concrete adapter.'
+        end
+
+        def cache_check(serializer)
+          CachedSerializer.new(serializer).cache_check(self) do
+            yield
+          end
+        end
+
+        private
+
+        def meta
+          instance_options.fetch(:meta, nil)
+        end
+
+        def meta_key
+          instance_options.fetch(:meta_key, 'meta'.freeze)
+        end
+
+        def root
+          serializer.json_key.to_sym if serializer.json_key
+        end
+
+        def include_meta(json)
+          json[meta_key] = meta if meta
+          json
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/cached_serializer.rb

@@ -0,0 +1,45 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class CachedSerializer
+        def initialize(serializer)
+          @cached_serializer = serializer
+          @klass             = @cached_serializer.class
+        end
+
+        def cache_check(adapter_instance)
+          if cached?
+            @klass._cache.fetch(cache_key, @klass._cache_options) do
+              yield
+            end
+          elsif fragment_cached?
+            FragmentCache.new(adapter_instance, @cached_serializer, adapter_instance.instance_options).fetch
+          else
+            yield
+          end
+        end
+
+        def cached?
+          @klass._cache && !@klass._cache_only && !@klass._cache_except
+        end
+
+        def fragment_cached?
+          @klass._cache_only && !@klass._cache_except || !@klass._cache_only && @klass._cache_except
+        end
+
+        def cache_key
+          parts = []
+          parts << object_cache_key
+          parts << @klass._cache_digest unless @klass._cache_options && @klass._cache_options[:skip_digest]
+          parts.join('/')
+        end
+
+        def object_cache_key
+          object_time_safe = @cached_serializer.object.updated_at
+          object_time_safe = object_time_safe.strftime('%Y%m%d%H%M%S%9N') if object_time_safe.respond_to?(:strftime)
+          (@klass._cache_key) ? "#{@klass._cache_key}/#{@cached_serializer.object.id}-#{object_time_safe}" : @cached_serializer.object.cache_key
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/fragment_cache.rb

@@ -0,0 +1,111 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class FragmentCache
+        attr_reader :serializer
+
+        def initialize(adapter, serializer, options)
+          @instance_options = options
+          @adapter    = adapter
+          @serializer = serializer
+        end
+
+        # TODO: Use Serializable::Resource
+        # TODO: call +constantize+ less
+        # 1. Create a CachedSerializer and NonCachedSerializer from the serializer class
+        # 2. Serialize the above two with the given adapter
+        # 3. Pass their serializations to the adapter +::fragment_cache+
+        def fetch
+          klass = serializer.class
+          # It will split the serializer into two, one that will be cached and one that will not
+          serializers = fragment_serializer(serializer.object.class.name, klass)
+
+          # Instantiate both serializers
+          cached_serializer     = serializers[:cached].constantize.new(serializer.object)
+          non_cached_serializer = serializers[:non_cached].constantize.new(serializer.object)
+
+          cached_adapter     = adapter.class.new(cached_serializer, instance_options)
+          non_cached_adapter = adapter.class.new(non_cached_serializer, instance_options)
+
+          # Get serializable hash from both
+          cached_hash     = cached_adapter.serializable_hash
+          non_cached_hash = non_cached_adapter.serializable_hash
+
+          # Merge both results
+          adapter.fragment_cache(cached_hash, non_cached_hash)
+        end
+
+        protected
+
+        attr_reader :instance_options, :adapter
+
+        private
+
+        # Given a serializer class and a hash of its cached and non-cached serializers
+        # 1. Determine cached attributes from serializer class options
+        # 2. Add cached attributes to cached Serializer
+        # 3. Add non-cached attributes to non-cached Serializer
+        def cached_attributes(klass, serializers)
+          attributes            = serializer.class._attributes
+          cached_attributes     = (klass._cache_only) ? klass._cache_only : attributes.reject { |attr| klass._cache_except.include?(attr) }
+          non_cached_attributes = attributes - cached_attributes
+
+          cached_attributes.each do |attribute|
+            options = serializer.class._attributes_keys[attribute]
+            options ||= {}
+            # Add cached attributes to cached Serializer
+            serializers[:cached].constantize.attribute(attribute, options)
+          end
+
+          non_cached_attributes.each do |attribute|
+            options = serializer.class._attributes_keys[attribute]
+            options ||= {}
+            # Add non-cached attributes to non-cached Serializer
+            serializers[:non_cached].constantize.attribute(attribute, options)
+          end
+        end
+
+        # Given a resource name and its serializer's class
+        # 1. Dyanmically creates a CachedSerializer and NonCachedSerializer
+        #   for a given class 'name'
+        # 2. Call
+        #       CachedSerializer.cache(serializer._cache_options)
+        #       CachedSerializer.fragmented(serializer)
+        #       NontCachedSerializer.cache(serializer._cache_options)
+        # 3. Build a hash keyed to the +cached+ and +non_cached+ serializers
+        # 4. Call +cached_attributes+ on the serializer class and the above hash
+        # 5. Return the hash
+        #
+        # @example
+        #   When +name+ is <tt>User::Admin</tt>
+        #   creates the Serializer classes (if they don't exist).
+        #     User_AdminCachedSerializer
+        #     User_AdminNOnCachedSerializer
+        #
+        def fragment_serializer(name, klass)
+          cached     = "#{to_valid_const_name(name)}CachedSerializer"
+          non_cached = "#{to_valid_const_name(name)}NonCachedSerializer"
+
+          Object.const_set cached, Class.new(ActiveModel::Serializer) unless Object.const_defined?(cached)
+          Object.const_set non_cached, Class.new(ActiveModel::Serializer) unless Object.const_defined?(non_cached)
+
+          klass._cache_options ||= {}
+          klass._cache_options[:key] = klass._cache_key if klass._cache_key
+
+          cached.constantize.cache(klass._cache_options)
+
+          cached.constantize.fragmented(serializer)
+          non_cached.constantize.fragmented(serializer)
+
+          serializers = { cached: cached, non_cached: non_cached }
+          cached_attributes(klass, serializers)
+          serializers
+        end
+
+        def to_valid_const_name(name)
+          name.gsub('::', '_')
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json/fragment_cache.rb

@@ -0,0 +1,13 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Json
+        class FragmentCache
+          def fragment_cache(cached_hash, non_cached_hash)
+            non_cached_hash.merge cached_hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json.rb

@@ -0,0 +1,21 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Json < Base
+        extend ActiveSupport::Autoload
+        autoload :FragmentCache
+
+        def serializable_hash(options = nil)
+          options ||= {}
+          { root => Attributes.new(serializer, instance_options).serializable_hash(options) }
+        end
+
+        private
+
+        def fragment_cache(cached_hash, non_cached_hash)
+          ActiveModel::Serializer::Adapter::Json::FragmentCache.new.fragment_cache(cached_hash, non_cached_hash)
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json_api/deserialization.rb

@@ -0,0 +1,207 @@
+module ActiveModel
+  class Serializer
+    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)
+            attributes
+              .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)
+            hash.merge!("#{prefix_key}_type".to_sym => assoc_data['type']) if polymorphic
+
+            hash
+          end
+
+          # @api private
+          def parse_relationships(relationships, options)
+            relationships
+              .map { |(k, v)| parse_relationship(k, v['data'], options) }
+              .reduce({}, :merge)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json_api/fragment_cache.rb

@@ -0,0 +1,21 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class JsonApi
+        class FragmentCache
+          def fragment_cache(root, cached_hash, non_cached_hash)
+            hash              = {}
+            core_cached       = cached_hash.first
+            core_non_cached   = non_cached_hash.first
+            no_root_cache     = cached_hash.delete_if { |key, value| key == core_cached[0] }
+            no_root_non_cache = non_cached_hash.delete_if { |key, value| key == core_non_cached[0] }
+            cached_resource   = (core_cached[1]) ? core_cached[1].deep_merge(core_non_cached[1]) : core_non_cached[1]
+            hash = (root) ? { root => cached_resource } : cached_resource
+
+            hash.deep_merge no_root_non_cache.deep_merge no_root_cache
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json_api/link.rb

@@ -0,0 +1,44 @@
+module ActiveModel
+  class Serializer
+    module Adapter
+      class JsonApi
+        class Link
+          def initialize(serializer, value)
+            @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 = { href: @href }
+            hash.merge!(meta: @meta) if @meta
+
+            hash
+          end
+
+          protected
+
+          attr_reader :object, :scope
+        end
+      end
+    end
+  end
+end