jsonapi-resources 0.8.3 → 0.9.0.beta1

data/lib/jsonapi/resource.rb

@@ -36,6 +36,10 @@ module JSONAPI
       _model.public_send(self.class._primary_key)
     end
 
+    def cache_id
+      [id, _model.public_send(self.class._cache_field)]
+    end
+
     def is_new?
       id.nil?
     end
@@ -165,6 +169,11 @@ module JSONAPI
       {}
     end
 
+    def preloaded_fragments
+      # A hash of hashes
+      @preloaded_fragments ||= Hash.new
+    end
+
     private
 
     def save
@@ -315,7 +324,7 @@ module JSONAPI
       relationship = self.class._relationships[relationship_type.to_sym]
 
       _model.public_send("#{relationship.foreign_key}=", key_value)
-      _model.public_send("#{relationship.polymorphic_type}=", key_type.to_s.classify)
+      _model.public_send("#{relationship.polymorphic_type}=", _model_class_name(key_type))
 
       @save_needed = true
 
@@ -395,10 +404,17 @@ module JSONAPI
       :completed
     end
 
+    def _model_class_name(key_type)
+      type_class_name = key_type.to_s.classify
+      resource = self.class.resource_for(type_class_name)
+      resource ? resource._model_name.to_s : type_class_name
+    end
+
     class << self
       def inherited(subclass)
         subclass.abstract(false)
         subclass.immutable(false)
+        subclass.caching(false)
         subclass._attributes = (_attributes || {}).dup
         subclass._model_hints = (_model_hints || {}).dup
 
@@ -417,9 +433,7 @@ module JSONAPI
         type = subclass.name.demodulize.sub(/Resource$/, '').underscore
         subclass._type = type.pluralize.to_sym
 
-        unless subclass._attributes[:id]
-          subclass.attribute :id, format: :id
-        end
+        subclass.attribute :id, format: :id
 
         check_reserved_resource_name(subclass._type, subclass.name)
       end
@@ -453,7 +467,8 @@ module JSONAPI
         end
       end
 
-      attr_accessor :_attributes, :_relationships, :_allowed_filters, :_type, :_paginator, :_model_hints
+      attr_accessor :_attributes, :_relationships, :_type, :_model_hints
+      attr_writer :_allowed_filters, :_paginator
 
       def create(context)
         new(create_model, context)
@@ -559,20 +574,9 @@ module JSONAPI
         @_primary_key = key.to_sym
       end
 
-      # TODO: remove this after the createable_fields and updateable_fields are phased out
-      # :nocov:
-      def method_missing(method, *args)
-        if method.to_s.match /createable_fields/
-          ActiveSupport::Deprecation.warn('`createable_fields` is deprecated, please use `creatable_fields` instead')
-          creatable_fields(*args)
-        elsif method.to_s.match /updateable_fields/
-          ActiveSupport::Deprecation.warn('`updateable_fields` is deprecated, please use `updatable_fields` instead')
-          updatable_fields(*args)
-        else
-          super
-        end
+      def cache_field(field)
+        @_cache_field = field.to_sym
       end
-      # :nocov:
 
       # Override in your resource to filter the updatable keys
       def updatable_fields(_context = nil)
@@ -581,7 +585,7 @@ module JSONAPI
 
       # Override in your resource to filter the creatable keys
       def creatable_fields(_context = nil)
-        _updatable_relationships | _attributes.keys - [:id]
+        _updatable_relationships | _attributes.keys
       end
 
       # Override in your resource to filter the sortable keys
@@ -729,19 +733,8 @@ module JSONAPI
         count_records(filter_records(filters, options))
       end
 
-      # Override this method if you have more complex requirements than this basic find method provides
       def find(filters, options = {})
-        context = options[:context]
-
-        records = filter_records(filters, options)
-
-        sort_criteria = options.fetch(:sort_criteria) { [] }
-        order_options = construct_order_options(sort_criteria)
-        records = sort_records(records, order_options, context)
-
-        records = apply_pagination(records, options[:paginator], order_options)
-
-        resources_for(records, context)
+        resources_for(find_records(filters, options), options[:context])
       end
 
       def resources_for(records, context)
@@ -761,17 +754,39 @@ module JSONAPI
         end
       end
 
+      def find_serialized_with_caching(filters_or_source, serializer, options = {})
+        if filters_or_source.is_a?(ActiveRecord::Relation)
+          records = filters_or_source
+        elsif _model_class.respond_to?(:all) && _model_class.respond_to?(:arel_table)
+          records = find_records(filters_or_source, options.except(:include_directives))
+        else
+          records = find(filters_or_source, options)
+        end
+        cached_resources_for(records, serializer, options)
+      end
+
       def find_by_key(key, options = {})
         context = options[:context]
-        records = records(options)
-        records = apply_includes(records, options)
-        model = records.where({_primary_key => key}).first
+        records = find_records({_primary_key => key}, options.except(:paginator, :sort_criteria))
+        model = records.first
         fail JSONAPI::Exceptions::RecordNotFound.new(key) if model.nil?
         self.resource_for_model(model).new(model, context)
       end
 
+      def find_by_key_serialized_with_caching(key, serializer, options = {})
+        if _model_class.respond_to?(:all) && _model_class.respond_to?(:arel_table)
+          results = find_serialized_with_caching({_primary_key => key}, serializer, options)
+          result = results.first
+          fail JSONAPI::Exceptions::RecordNotFound.new(key) if result.nil?
+          return result
+        else
+          resource = find_by_key(key, options)
+          return cached_resources_for([resource], serializer, options).first
+        end
+      end
+
       # Override this method if you want to customize the relation for
-      # finder methods (find, find_by_key)
+      # finder methods (find, find_by_key, find_serialized_with_caching)
       def records(_options = {})
         _model_class.all
       end
@@ -882,13 +897,24 @@ module JSONAPI
       end
 
       def _model_name
-        _abstract ? '' : @_model_name ||= name.demodulize.sub(/Resource$/, '')
+        if _abstract
+          return ''
+        else
+          return @_model_name if defined?(@_model_name)
+          class_name = self.name
+          return '' if class_name.nil?
+          return @_model_name = class_name.demodulize.sub(/Resource$/, '')
+        end
       end
 
       def _primary_key
         @_primary_key ||= _model_class.respond_to?(:primary_key) ? _model_class.primary_key : :id
       end
 
+      def _cache_field
+        @_cache_field ||= JSONAPI.configuration.default_resource_cache_field
+      end
+
       def _table_name
         @_table_name ||= _model_class.respond_to?(:table_name) ? _model_class.table_name : _model_name.tableize
       end
@@ -898,7 +924,7 @@ module JSONAPI
       end
 
       def _allowed_filters
-        !@_allowed_filters.nil? ? @_allowed_filters : { id: {} }
+        defined?(@_allowed_filters) ? @_allowed_filters : { id: {} }
       end
 
       def _paginator
@@ -929,10 +955,27 @@ module JSONAPI
         !@immutable
       end
 
+      def caching(val = true)
+        @caching = val
+      end
+
+      def _caching
+        @caching
+      end
+
+      def caching?
+        @caching && !JSONAPI.configuration.resource_cache.nil?
+      end
+
+      def attribute_caching_context(context)
+        nil
+      end
+
       def _model_class
         return nil if _abstract
 
-        return @model if @model
+        return @model if defined?(@model)
+        return nil if self.name.to_s.blank? && _model_name.to_s.blank?
         @model = _model_name.to_s.safe_constantize
         warn "[MODEL NOT FOUND] Model could not be found for #{self.name}. If this a base Resource declare it as abstract." if @model.nil?
         @model
@@ -989,6 +1032,36 @@ module JSONAPI
 
       private
 
+      def cached_resources_for(records, serializer, options)
+        if records.is_a?(Array) && records.all?{|rec| rec.is_a?(JSONAPI::Resource)}
+          resources = records.map{|r| [r.id, r] }.to_h
+        elsif self.caching?
+          t = _model_class.arel_table
+          cache_ids = pluck_arel_attributes(records, t[_primary_key], t[_cache_field])
+          resources = CachedResourceFragment.fetch_fragments(self, serializer, options[:context], cache_ids)
+        else
+          resources = resources_for(records, options).map{|r| [r.id, r] }.to_h
+        end
+
+        preload_included_fragments(resources, records, serializer, options)
+
+        resources.values
+      end
+
+      def find_records(filters, options = {})
+        context = options[:context]
+
+        records = filter_records(filters, options)
+
+        sort_criteria = options.fetch(:sort_criteria) { [] }
+        order_options = construct_order_options(sort_criteria)
+        records = sort_records(records, order_options, context)
+
+        records = apply_pagination(records, options[:paginator], order_options)
+
+        records
+      end
+
       def check_reserved_resource_name(type, name)
         if [:ids, :types, :hrefs, :links].include?(type)
           warn "[NAME COLLISION] `#{name}` is a reserved resource name."
@@ -1021,6 +1094,129 @@ module JSONAPI
           warn "[DUPLICATE ATTRIBUTE] `#{name}` has already been defined in #{_resource_name_from_type(_type)}."
         end
       end
+
+      def preload_included_fragments(resources, records, serializer, options)
+        return if resources.empty?
+        res_ids = resources.keys
+
+        include_directives = options[:include_directives]
+        return unless include_directives
+
+        relevant_options = options.except(:include_directives, :order, :paginator)
+        context = options[:context]
+
+        # For each association, including indirect associations, find the target record ids.
+        # Even if a target class doesn't have caching enabled, we still have to look up
+        # and match the target ids here, because we can't use ActiveRecord#includes.
+        #
+        # Note that `paths` returns partial paths before complete paths, so e.g. the partial
+        # fragments for posts.comments will exist before we start working with posts.comments.author
+        target_resources = {}
+        include_directives.paths.each do |path|
+          # If path is [:posts, :comments, :author], then...
+          pluck_attrs = [] # ...will be [posts.id, comments.id, authors.id, authors.updated_at]
+          pluck_attrs << self._model_class.arel_table[self._primary_key]
+
+          relation = records
+            .except(:limit, :offset, :order)
+            .where({_primary_key => res_ids})
+
+          # These are updated as we iterate through the association path; afterwards they will
+          # refer to the final resource on the path, i.e. the actual resource to find in the cache.
+          # So e.g. if path is [:posts, :comments, :author], then after iteration...
+          parent_klass = nil # Comment
+          klass = self # Person
+          relationship = nil # JSONAPI::Relationship::ToOne for CommentResource.author
+          table = nil # people
+          assocs_path = [] # [ :posts, :approved_comments, :author ]
+          ar_hash = nil # { :posts => { :approved_comments => :author } }
+
+          # For each step on the path, figure out what the actual table name/alias in the join
+          # will be, and include the primary key of that table in our list of fields to select
+          path.each do |elem|
+            relationship = klass._relationships[elem]
+            assocs_path << relationship.relation_name(options).to_sym
+            # Converts [:a, :b, :c] to Rails-style { :a => { :b => :c }}
+            ar_hash = assocs_path.reverse.reduce{|memo, step| { step => memo } }
+            # We can't just look up the table name from the resource class, because Arel could
+            # have used a table alias if the relation includes a self-reference.
+            join_source = relation.joins(ar_hash).arel.source.right.reverse.find do |arel_node|
+              arel_node.is_a?(Arel::Nodes::InnerJoin)
+            end
+            table = join_source.left
+            parent_klass = klass
+            klass = relationship.resource_klass
+            pluck_attrs << table[klass._primary_key]
+          end
+
+          # Pre-fill empty hashes for each resource up to the end of the path.
+          # This allows us to later distinguish between a preload that returned nothing
+          # vs. a preload that never ran.
+          prefilling_resources = resources.values
+          path.each do |rel_name|
+            rel_name = serializer.key_formatter.format(rel_name)
+            prefilling_resources.map! do |res|
+              res.preloaded_fragments[rel_name] ||= {}
+              res.preloaded_fragments[rel_name].values
+            end
+            prefilling_resources.flatten!(1)
+          end
+
+          pluck_attrs << table[klass._cache_field] if klass.caching?
+          relation = relation.joins(ar_hash)
+          if relationship.is_a?(JSONAPI::Relationship::ToMany)
+            # Rails doesn't include order clauses in `joins`, so we have to add that manually here.
+            # FIXME Should find a better way to reflect on relationship ordering. :-(
+            relation = relation.order(parent_klass._model_class.new.send(assocs_path.last).arel.orders)
+          end
+
+          # [[post id, comment id, author id, author updated_at], ...]
+          id_rows = pluck_arel_attributes(relation.joins(ar_hash), *pluck_attrs)
+
+          target_resources[klass.name] ||= {}
+
+          if klass.caching?
+            sub_cache_ids = id_rows
+              .map{|row| row.last(2) }
+              .reject{|row| target_resources[klass.name].has_key?(row.first) }
+              .uniq
+            target_resources[klass.name].merge! CachedResourceFragment.fetch_fragments(
+              klass, serializer, context, sub_cache_ids
+            )
+          else
+            sub_res_ids = id_rows
+              .map(&:last)
+              .reject{|id| target_resources[klass.name].has_key?(id) }
+              .uniq
+            found = klass.find({klass._primary_key => sub_res_ids}, relevant_options)
+            target_resources[klass.name].merge! found.map{|r| [r.id, r] }.to_h
+          end
+
+          id_rows.each do |row|
+            res = resources[row.first]
+            path.each_with_index do |rel_name, index|
+              rel_name = serializer.key_formatter.format(rel_name)
+              rel_id = row[index+1]
+              assoc_rels = res.preloaded_fragments[rel_name]
+              if index == path.length - 1
+                assoc_rels[rel_id] = target_resources[klass.name].fetch(rel_id)
+              else
+                res = assoc_rels[rel_id]
+              end
+            end
+          end
+        end
+      end
+
+      def pluck_arel_attributes(relation, *attrs)
+        conn = relation.connection
+        quoted_attrs = attrs.map do |attr|
+          quoted_table = conn.quote_table_name(attr.relation.table_alias || attr.relation.name)
+          quoted_column = conn.quote_column_name(attr.name)
+          "#{quoted_table}.#{quoted_column}"
+        end
+        relation.pluck(*quoted_attrs)
+      end
     end
   end
 end

data/lib/jsonapi/resource_serializer.rb

@@ -1,7 +1,9 @@
 module JSONAPI
   class ResourceSerializer
 
-    attr_reader :link_builder, :key_formatter, :serialization_options, :primary_class_name
+    attr_reader :link_builder, :key_formatter, :serialization_options, :primary_class_name,
+                :fields, :include_directives, :always_include_to_one_linkage_data,
+                :always_include_to_many_linkage_data
 
     # initialize
     # Options can include
@@ -13,7 +15,7 @@ module JSONAPI
     #              relationship ids in the links section for a resource. Fields are global for a resource type.
     #     Example: { people: [:id, :email, :comments], posts: [:id, :title, :author], comments: [:id, :body, :post]}
     # key_formatter: KeyFormatter instance to override the default configuration
-    # serializer_options: additional options that will be passed to resource meta and links lambdas
+    # serialization_options: additional options that will be passed to resource meta and links lambdas
 
     def initialize(primary_resource_klass, options = {})
       @primary_resource_klass = primary_resource_klass
@@ -21,6 +23,7 @@ module JSONAPI
       @fields                 = options.fetch(:fields, {})
       @include                = options.fetch(:include, [])
       @include_directives     = options[:include_directives]
+      @include_directives     ||= JSONAPI::IncludeDirectives.new(@primary_resource_klass, @include)
       @key_formatter          = options.fetch(:key_formatter, JSONAPI.configuration.key_formatter)
       @id_formatter           = ValueFormatter.value_formatter_for(:id)
       @link_builder           = generate_link_builder(primary_resource_klass, options)
@@ -33,16 +36,19 @@ module JSONAPI
       # Warning: This makes ResourceSerializer non-thread-safe. That's not a problem with the
       # request-specific way it's currently used, though.
       @value_formatter_type_cache = NaiveCache.new{|arg| ValueFormatter.value_formatter_for(arg) }
+
+      @_config_keys = {}
+      @_supplying_attribute_fields = {}
+      @_supplying_relationship_fields = {}
     end
 
     # Converts a single resource, or an array of resources to a hash, conforming to the JSONAPI structure
     def serialize_to_hash(source)
-      @top_level_sources = Set.new([source].flatten.compact.map {|s| top_level_source_key(s) })
+      @top_level_sources = Set.new([source].flatten(1).compact.map {|s| top_level_source_key(s) })
 
       is_resource_collection = source.respond_to?(:to_ary)
 
       @included_objects = {}
-      @include_directives ||= JSONAPI::IncludeDirectives.new(@primary_resource_klass, @include)
 
       process_primary(source, @include_directives.include_directives)
 
@@ -92,67 +98,120 @@ module JSONAPI
       @value_formatter_type_cache.get(format).format(value)
     end
 
-    private
-
-    # Process the primary source object(s). This will then serialize associated object recursively based on the
-    # requested includes. Fields are controlled fields option for each resource type, such
-    # as fields: { people: [:id, :email, :comments], posts: [:id, :title, :author], comments: [:id, :body, :post]}
-    # The fields options controls both fields and included links references.
-    def process_primary(source, include_directives)
-      if source.respond_to?(:to_ary)
-        source.each { |resource| process_primary(resource, include_directives) }
-      else
-        return {} if source.nil?
-
-        resource = source
-        id = resource.id
-        add_included_object(id, object_hash(source, include_directives), true)
+    def config_key(resource_klass)
+      @_config_keys.fetch resource_klass do
+        desc = self.config_description(resource_klass).map(&:inspect).join(",")
+        key = JSONAPI.configuration.resource_cache_digest_function.call(desc)
+        @_config_keys[resource_klass] = "SRLZ-#{key}"
       end
     end
 
+    def config_description(resource_klass)
+      {
+        class_name: self.class.name,
+        seriserialization_options: serialization_options.sort.map(&:as_json),
+        supplying_attribute_fields: supplying_attribute_fields(resource_klass).sort,
+        supplying_relationship_fields: supplying_relationship_fields(resource_klass).sort,
+        link_builder_base_url: link_builder.base_url,
+        route_formatter_class: link_builder.route_formatter.uncached.class.name,
+        key_formatter_class: key_formatter.uncached.class.name,
+        always_include_to_one_linkage_data: always_include_to_one_linkage_data,
+        always_include_to_many_linkage_data: always_include_to_many_linkage_data
+      }
+    end
+
     # Returns a serialized hash for the source model
-    def object_hash(source, include_directives)
+    def object_hash(source, include_directives = {})
       obj_hash = {}
 
-      id_format = source.class._attribute_options(:id)[:format]
-      # protect against ids that were declared as an attribute, but did not have a format set.
-      id_format = 'id' if id_format == :default
-      obj_hash['id'] = format_value(source.id, id_format)
+      if source.is_a?(JSONAPI::CachedResourceFragment)
+        obj_hash['id'] = source.id
+        obj_hash['type'] = source.type
 
-      obj_hash['type'] = format_key(source.class._type.to_s)
+        obj_hash['links'] = source.links_json if source.links_json
+        obj_hash['attributes'] = source.attributes_json if source.attributes_json
 
-      links = links_hash(source)
-      obj_hash['links'] = links unless links.empty?
+        relationships = cached_relationships_hash(source, include_directives)
+        obj_hash['relationships'] = relationships unless relationships.empty?
 
-      attributes = attributes_hash(source)
-      obj_hash['attributes'] = attributes unless attributes.empty?
+        obj_hash['meta'] = source.meta_json if source.meta_json
+      else
+        fetchable_fields = Set.new(source.fetchable_fields)
 
-      relationships = relationships_hash(source, include_directives)
-      obj_hash['relationships'] = relationships unless relationships.nil? || relationships.empty?
+        # TODO Should this maybe be using @id_formatter instead, for consistency?
+        id_format = source.class._attribute_options(:id)[:format]
+        # protect against ids that were declared as an attribute, but did not have a format set.
+        id_format = 'id' if id_format == :default
+        obj_hash['id'] = format_value(source.id, id_format)
 
-      meta = meta_hash(source)
-      obj_hash['meta'] = meta unless meta.empty?
+        obj_hash['type'] = format_key(source.class._type.to_s)
+
+        links = links_hash(source)
+        obj_hash['links'] = links unless links.empty?
+
+        attributes = attributes_hash(source, fetchable_fields)
+        obj_hash['attributes'] = attributes unless attributes.empty?
+
+        relationships = relationships_hash(source, fetchable_fields, include_directives)
+        obj_hash['relationships'] = relationships unless relationships.nil? || relationships.empty?
+
+        meta = meta_hash(source)
+        obj_hash['meta'] = meta unless meta.empty?
+      end
 
       obj_hash
     end
 
-    def requested_fields(klass)
-      return if @fields.nil? || @fields.empty?
-      if @fields[klass._type]
-        @fields[klass._type]
-      elsif klass.superclass != JSONAPI::Resource
-        requested_fields(klass.superclass)
+    private
+
+    # Process the primary source object(s). This will then serialize associated object recursively based on the
+    # requested includes. Fields are controlled fields option for each resource type, such
+    # as fields: { people: [:id, :email, :comments], posts: [:id, :title, :author], comments: [:id, :body, :post]}
+    # The fields options controls both fields and included links references.
+    def process_primary(source, include_directives)
+      if source.respond_to?(:to_ary)
+        source.each { |resource| process_primary(resource, include_directives) }
+      else
+        return {} if source.nil?
+        add_resource(source, include_directives, true)
       end
     end
 
-    def attributes_hash(source)
-      requested = requested_fields(source.class)
-      fields = source.fetchable_fields & source.class._attributes.keys.to_a
-      fields = requested & fields unless requested.nil?
+    def supplying_attribute_fields(resource_klass)
+      @_supplying_attribute_fields.fetch resource_klass do
+        attrs = Set.new(resource_klass._attributes.keys.map(&:to_sym))
+        cur = resource_klass
+        while cur != JSONAPI::Resource
+          if @fields.has_key?(cur._type)
+            attrs &= @fields[cur._type]
+            break
+          end
+          cur = cur.superclass
+        end
+        @_supplying_attribute_fields[resource_klass] = attrs
+      end
+    end
 
+    def supplying_relationship_fields(resource_klass)
+      @_supplying_relationship_fields.fetch resource_klass do
+        relationships = Set.new(resource_klass._relationships.keys.map(&:to_sym))
+        cur = resource_klass
+        while cur != JSONAPI::Resource
+          if @fields.has_key?(cur._type)
+            relationships &= @fields[cur._type]
+            break
+          end
+          cur = cur.superclass
+        end
+        @_supplying_relationship_fields[resource_klass] = relationships
+      end
+    end
+
+    def attributes_hash(source, fetchable_fields)
+      fields = fetchable_fields & supplying_attribute_fields(source.class)
       fields.each_with_object({}) do |name, hash|
-        format = source.class._attribute_options(name)[:format]
         unless name == :id
+          format = source.class._attribute_options(name)[:format]
           hash[format_key(name)] = format_value(source.public_send(name), format)
         end
       end
@@ -182,59 +241,101 @@ module JSONAPI
     end
 
     def top_level_source_key(source)
-      "#{source.class}_#{source.id}"
+      case source
+      when CachedResourceFragment then "#{source.resource_klass}_#{source.id}"
+      when Resource then "#{source.class}_#{@id_formatter.format(source.id)}"
+      else raise "Unknown source type #{source.inspect}"
+      end
     end
 
     def self_referential_and_already_in_source(resource)
       resource && @top_level_sources.include?(top_level_source_key(resource))
     end
 
-    def relationships_hash(source, include_directives)
-      relationships = source.class._relationships
-      requested = requested_fields(source.class)
-      fields = relationships.keys
-      fields = requested & fields unless requested.nil?
+    def relationships_hash(source, fetchable_fields, include_directives = {})
+      if source.is_a?(CachedResourceFragment)
+        return cached_relationships_hash(source, include_directives)
+      end
+
+      include_directives[:include_related] ||= {}
+
+      relationships = source.class._relationships.select{|k,v| fetchable_fields.include?(k) }
+      field_set = supplying_relationship_fields(source.class) & relationships.keys
+
+      relationships.each_with_object({}) do |(name, relationship), hash|
+        ia = include_directives[:include_related][name]
+        include_linkage = ia && ia[:include]
+        include_linked_children = ia && !ia[:include_related].empty?
 
-      field_set = Set.new(fields)
+        if field_set.include?(name)
+          hash[format_key(name)] = link_object(source, relationship, include_linkage)
+        end
 
-      included_relationships = source.fetchable_fields & relationships.keys
+        # If the object has been serialized once it will be in the related objects list,
+        # but it's possible all children won't have been captured. So we must still go
+        # through the relationships.
+        if include_linkage || include_linked_children
+          resources = if source.preloaded_fragments.has_key?(format_key(name))
+            source.preloaded_fragments[format_key(name)].values
+          else
+            [source.public_send(name)].flatten(1).compact
+          end
+          resources.each do |resource|
+            next if self_referential_and_already_in_source(resource)
+            id = resource.id
+            relationships_only = already_serialized?(relationship.type, id)
+            if include_linkage && !relationships_only
+              add_resource(resource, ia)
+            elsif include_linked_children || relationships_only
+              relationships_hash(resource, fetchable_fields, ia)
+            end
+          end
+        end
+      end
+    end
 
-      data = {}
+    def cached_relationships_hash(source, include_directives)
+      h = source.relationships || {}
+      return h unless include_directives.has_key?(:include_related)
 
-      relationships.each_with_object(data) do |(name, relationship), hash|
-        if included_relationships.include? name
-          ia = include_directives[:include_related][name]
+      relationships = source.resource_klass._relationships.select{|k,v| source.fetchable_fields.include?(k) }
 
-          include_linkage = ia && ia[:include]
-          include_linked_children = ia && !ia[:include_related].empty?
-          resources = (include_linkage || include_linked_children) && [source.public_send(name)].flatten.compact
+      relationships.each do |rel_name, relationship|
+        key = @key_formatter.format(rel_name)
+        to_many = relationship.is_a? JSONAPI::Relationship::ToMany
 
-          if field_set.include?(name)
-            hash[format_key(name)] = link_object(source, relationship, include_linkage)
+        ia = include_directives[:include_related][rel_name]
+        if ia
+          if h.has_key?(key)
+            h[key][:data] = to_many ? [] : nil
           end
 
-          # If the object has been serialized once it will be in the related objects list,
-          # but it's possible all children won't have been captured. So we must still go
-          # through the relationships.
-          if include_linkage || include_linked_children
-            resources.each do |resource|
-              next if self_referential_and_already_in_source(resource)
-              id = resource.id
-              type = resource.class.resource_for_model(resource._model)
-              relationships_only = already_serialized?(type, id)
-              if include_linkage && !relationships_only
-                add_included_object(id, object_hash(resource, ia))
-              elsif include_linked_children || relationships_only
-                relationships_hash(resource, ia)
+          source.preloaded_fragments[key].each do |id, f|
+            add_resource(f, ia)
+
+            if h.has_key?(key)
+              # The hash already has everything we need except the :data field
+              data = {
+                type: format_key(f.is_a?(Resource) ? f.class._type : f.type),
+                id: @id_formatter.format(id)
+              }
+
+              if to_many
+                h[key][:data] << data
+              else
+                h[key][:data] = data
               end
             end
           end
         end
       end
+
+      return h
     end
 
     def already_serialized?(type, id)
       type = format_key(type)
+      id = @id_formatter.format(id)
       @included_objects.key?(type) && @included_objects[type].key?(id)
     end
 
@@ -247,8 +348,10 @@ module JSONAPI
     end
 
     def to_one_linkage(source, relationship)
-      return unless linkage_id = foreign_key_value(source, relationship)
-      return unless linkage_type = format_key(relationship.type_for_source(source))
+      linkage_id = foreign_key_value(source, relationship)
+      linkage_type = format_key(relationship.type_for_source(source))
+      return unless linkage_id.present? && linkage_type.present?
+
       {
         type: linkage_type,
         id: linkage_id,
@@ -257,7 +360,27 @@ module JSONAPI
 
     def to_many_linkage(source, relationship)
       linkage = []
-      linkage_types_and_values = foreign_key_types_and_values(source, relationship)
+      linkage_types_and_values = if source.preloaded_fragments.has_key?(format_key(relationship.name))
+        source.preloaded_fragments[format_key(relationship.name)].map do |_, resource|
+          [relationship.type, resource.id]
+        end
+      elsif relationship.polymorphic?
+        assoc = source._model.public_send(relationship.name)
+        # Avoid hitting the database again for values already pre-loaded
+        if assoc.respond_to?(:loaded?) and assoc.loaded?
+          assoc.map do |obj|
+            [obj.type.underscore.pluralize, obj.id]
+          end
+        else
+          assoc.pluck(:type, :id).map do |type, id|
+            [type.underscore.pluralize, id]
+          end
+        end
+      else
+        source.public_send(relationship.name).map do |value|
+          [relationship.type, value.id]
+        end
+      end
 
       linkage_types_and_values.each do |type, value|
         if type && value
@@ -297,18 +420,18 @@ module JSONAPI
 
     # Extracts the foreign key value for a to_one relationship.
     def foreign_key_value(source, relationship)
-      # If you have direct access to the underlying id, you don't have to load the relationship
-      # which can save quite a lot of time when loading a lot of data.
-      # This does not apply to e.g. has_one :through relationships.
-      if source._model.respond_to?("#{relationship.name}_id")
-        related_resource_id = source._model.public_send("#{relationship.name}_id")
-        return nil unless related_resource_id
-        @id_formatter.format(related_resource_id)
+      related_resource_id = if source.preloaded_fragments.has_key?(format_key(relationship.name))
+        source.preloaded_fragments[format_key(relationship.name)].values.first.try(:id)
+      elsif source.respond_to?("#{relationship.name}_id")
+        # If you have direct access to the underlying id, you don't have to load the relationship
+        # which can save quite a lot of time when loading a lot of data.
+        # This does not apply to e.g. has_one :through relationships.
+        source.public_send("#{relationship.name}_id")
       else
-        related_resource = source.public_send(relationship.name)
-        return nil unless related_resource
-        @id_formatter.format(related_resource.id)
+        source.public_send(relationship.name).try(:id)
       end
+      return nil unless related_resource_id
+      @id_formatter.format(related_resource_id)
     end
 
     def foreign_key_types_and_values(source, relationship)
@@ -339,17 +462,28 @@ module JSONAPI
       @included_objects[type][id][:primary] = true
     end
 
-    # Collects the hashes for all objects processed by the serializer
-    def add_included_object(id, object_hash, primary = false)
-      type = object_hash['type']
+    def add_resource(source, include_directives, primary = false)
+      type = source.is_a?(JSONAPI::CachedResourceFragment) ? source.type : source.class._type
+      id = source.id
 
-      @included_objects[type] = {} unless @included_objects.key?(type)
+      @included_objects[type] ||= {}
+      existing = @included_objects[type][id]
 
-      if already_serialized?(type, id)
-        @included_objects[type][id][:object_hash].deep_merge!(object_hash)
-        set_primary(type, id) if primary
+      if existing.nil?
+        obj_hash = object_hash(source, include_directives)
+        @included_objects[type][id] = {
+            primary: primary,
+            object_hash: obj_hash,
+            includes: Set.new(include_directives[:include_related].keys)
+        }
       else
-        @included_objects[type].store(id, primary: primary, object_hash: object_hash)
+        include_related = Set.new(include_directives[:include_related].keys)
+        unless existing[:includes].superset?(include_related)
+          obj_hash = object_hash(source, include_directives)
+          @included_objects[type][id][:object_hash].deep_merge!(obj_hash)
+          @included_objects[type][id][:includes].add(include_related)
+          @included_objects[type][id][:primary] = existing[:primary] | primary
+        end
       end
     end