Adds :lazy_load_data option

If you include a default empty `data` option in your JSON API response,
many frontend frameworks will ignore your `related` link that could be
used to load relationship records, and will instead treat the
relationship as empty.

This adds a `lazy_load_data` option which will:

  * stop the serializer attempting to load the data and;
  * exclude the `data` key from the final response

This allows you to lazy load a JSON API relationship.

Author: nikz

README.md

@@ -262,17 +262,15 @@ class MovieSerializer
 end
 ```
 
-This will create a `self` reference for the relationship, and a `related` link for loading the actors relationship later. NB: This will not automatically disable including the data in the relationship, you'll need to do that using the yielded block:
+This will create a `self` reference for the relationship, and a `related` link for loading the actors relationship later. NB: This will not automatically disable loading the data in the relationship, you'll need to do that using the `lazy_load_data` option:
 
 ```ruby
-  has_many :actors, links: {
+  has_many :actors, lazy_load_data: true, links: {
     self: :url,
     related: -> (object) {
       "https://movies.com/#{object.id}/actors"
     }
-  } do |movie|
-    movie.actors.limit(5)
-  end
+  }
 ```
 
 ### Meta Per Resource

lib/fast_jsonapi/object_serializer.rb

@@ -250,7 +250,8 @@ def create_relationship(base_key, relationship_type, options, block)
           cached: options[:cached],
           polymorphic: fetch_polymorphic_option(options),
           conditional_proc: options[:if],
-          links: options[:links]
+          links: options[:links],
+          lazy_load_data: options[:lazy_load_data]
         )
       end
 

lib/fast_jsonapi/relationship.rb

@@ -1,6 +1,6 @@
 module FastJsonapi
   class Relationship
-    attr_reader :key, :name, :id_method_name, :record_type, :object_method_name, :object_block, :serializer, :relationship_type, :cached, :polymorphic, :conditional_proc, :links
+    attr_reader :key, :name, :id_method_name, :record_type, :object_method_name, :object_block, :serializer, :relationship_type, :cached, :polymorphic, :conditional_proc, :links, :lazy_load_data
 
     def initialize(
       key:,
@@ -14,7 +14,8 @@ def initialize(
       cached: false,
       polymorphic:,
       conditional_proc:,
-      links:
+      links:,
+      lazy_load_data: false
     )
       @key = key
       @name = name
@@ -28,14 +29,17 @@ def initialize(
       @polymorphic = polymorphic
       @conditional_proc = conditional_proc
       @links = links || {}
+      @lazy_load_data = lazy_load_data
     end
 
     def serialize(record, serialization_params, output_hash)
       if include_relationship?(record, serialization_params)
         empty_case = relationship_type == :has_many ? [] : nil
-        output_hash[key] = {
-          data: ids_hash_from_record_and_relationship(record, serialization_params) || empty_case
-        }
+
+        output_hash[key] = {}
+        unless lazy_load_data
+          output_hash[key][:data] = ids_hash_from_record_and_relationship(record, serialization_params) || empty_case
+        end
         add_links_hash(record, serialization_params, output_hash) if links.present?
       end
     end

spec/lib/object_serializer_relationship_links_spec.rb

@@ -6,23 +6,23 @@
   context "params option" do
     let(:hash) { serializer.serializable_hash }
 
-    before(:context) do
-      class MovieSerializer
-        has_many :actors, links: {
-          self:    :actors_relationship_url,
-          related: -> (object, params = {}) {
-            "#{params.has_key?(:secure) ? "https" : "http"}://movies.com/movies/#{object.name.parameterize}/actors/"
-          }
-        }
-      end
-    end
-
     context "generating links for a serializer relationship" do
       let(:params) { {  } }
       let(:options_with_params) { { params: params } }
       let(:relationship_url) { "http://movies.com/#{movie.id}/relationships/actors" }
       let(:related_url) { "http://movies.com/movies/#{movie.name.parameterize}/actors/" }
 
+      before(:context) do
+        class MovieSerializer
+          has_many :actors, lazy_load_data: false, links: {
+            self:    :actors_relationship_url,
+            related: -> (object, params = {}) {
+              "#{params.has_key?(:secure) ? "https" : "http"}://movies.com/movies/#{object.name.parameterize}/actors/"
+            }
+          }
+        end
+      end
+
       context "with a single record" do
         let(:serializer) { MovieSerializer.new(movie, options_with_params) }
         let(:links) { hash[:data][:relationships][:actors][:links] }
@@ -49,5 +49,23 @@ class MovieSerializer
       end
 
     end
+
+    context "lazy loading relationship data" do
+      before(:context) do
+        class LazyLoadingMovieSerializer < MovieSerializer
+          has_many :actors, lazy_load_data: true, links: {
+            related: :actors_relationship_url
+          }
+        end
+      end
+
+      let(:serializer) { LazyLoadingMovieSerializer.new(movie) }
+      let(:actor_hash) { hash[:data][:relationships][:actors] }
+
+      it "does not include the :data key" do
+        expect(actor_hash).to be_present
+        expect(actor_hash).not_to have_key(:data)
+      end
+    end
   end
 end