Cleanup sparse fieldset handling and docs.

Author: fotinakis

README.md

@@ -419,60 +419,33 @@ This option overrides the `jsonapi_serializer_class_name` method.
 
 ### Sparse fieldsets
 
-The JSON:API spec allows to return only [specific fields](http://jsonapi.org/format/#fetching-sparse-fieldsets).
+The JSON:API spec allows to return only [specific fields](http://jsonapi.org/format/#fetching-sparse-fieldsets) from attributes and relationships.
 
-For example, if you wanted to return only `title` and `author` fields for `posts` type and `name` field for `users` type, you could write the following code:
+For example, if you wanted to return only the `title` field and `author` relationship link for `posts`:
 
 ```ruby
-fields = {posts: 'title,author', users: 'name'}
-JSONAPI::Serializer.serialize(post, fields: fields, include: 'author')
+fields =
+JSONAPI::Serializer.serialize(post, fields: {posts: [:title]})
 ```
 
-Returns:
+Sparse fieldsets also affect relationship links. In this case, only the `author` relationship link would be included:
 
-```json
-{
-  "data": {
-    "type": "posts",
-    "id": "1",
-    "attributes": {
-      "title": "Title for Post 1"
-    },
-   "links": {
-      "self": "/posts/1"
-    },
-    "relationships": {
-      "author": {
-        "links": {
-          "self": "/posts/1/relationships/author",
-          "related": "/posts/1/author"
-        },
-        "data": { "type": "users", "id": "3" }
-      }
-    }
-  },
- "included": [
-    {
-      "type": "users",
-      "id": "3",
-      "attributes": {
-        "name": "User #3"
-      },
-      "links": {
-        "self": "/users/3"
-      }
-    }
-  ]
-}
+``` ruby
+JSONAPI::Serializer.serialize(post, fields: {posts: [:title, :author]})
 ```
 
-You could also pass an array of specific fields for given type instead of comma-separated values:
+Sparse fieldsets operate on a per-type basis, so they affect all resources in the response including in compound documents. For example, this will affect both the `posts` type in the primary data and the `users` type in the compound data:
 
 ``` ruby
-fields = {posts: ['title', 'author'], users: ['name']}
-JSONAPI::Serializer.serialize(post, fields: fields, include: 'author')
+JSONAPI::Serializer.serialize(
+  post,
+  fields: {posts: ['title', 'author'], users: ['name']},
+  include: 'author',
+)
 ```
 
+Sparse fieldsets support comma-separated strings (`fields: {posts: 'title,author'}`, arrays of strings (`fields: {posts: ['title', 'author']}`), single symbols (`fields: {posts: :title}`), and arrays of symbols (`fields: {posts: [:title, :author]}`).
+
 ## Relationships
 
 You can easily specify relationships with the `has_one` and `has_many` directives.

lib/jsonapi-serializers/serializer.rb

@@ -25,16 +25,15 @@ module InstanceMethods
       attr_accessor :object
       attr_accessor :context
       attr_accessor :base_url
-      attr_accessor :fields
 
       def initialize(object, options = {})
         @object = object
         @options = options
         @context = options[:context] || {}
         @base_url = options[:base_url]
-        @fields = options[:fields] || {}
 
         # Internal serializer options, not exposed through attr_accessor. No touchie.
+        @_fields = options[:fields] || {}
         @_include_linkages = options[:include_linkages] || []
       end
 
@@ -166,7 +165,8 @@ def relationships
       def attributes
         return {} if self.class.attributes_map.nil?
         attributes = {}
-        self.class.attributes_map.select(&should_include_attr_proc).each do |attribute_name, attr_data|
+        self.class.attributes_map.each do |attribute_name, attr_data|
+          next if !should_include_attr?(attribute_name, attr_data)
           value = evaluate_attr_or_block(attribute_name, attr_data[:attr_or_block])
           attributes[format_name(attribute_name)] = value
         end
@@ -176,7 +176,8 @@ def attributes
       def has_one_relationships
         return {} if self.class.to_one_associations.nil?
         data = {}
-        self.class.to_one_associations.select(&should_include_attr_proc).each do |attribute_name, attr_data|
+        self.class.to_one_associations.each do |attribute_name, attr_data|
+          next if !should_include_attr?(attribute_name, attr_data)
           data[attribute_name] = attr_data
         end
         data
@@ -189,7 +190,8 @@ def has_one_relationship(attribute_name, attr_data)
       def has_many_relationships
         return {} if self.class.to_many_associations.nil?
         data = {}
-        self.class.to_many_associations.select(&should_include_attr_proc).each do |attribute_name, attr_data|
+        self.class.to_many_associations.each do |attribute_name, attr_data|
+          next if !should_include_attr?(attribute_name, attr_data)
           data[attribute_name] = attr_data
         end
         data
@@ -199,23 +201,18 @@ def has_many_relationship(attribute_name, attr_data)
         evaluate_attr_or_block(attribute_name, attr_data[:attr_or_block])
       end
 
-      def should_include_attr?(attribute_name, if_method_name, unless_method_name)
+      def should_include_attr?(attribute_name, attr_data)
         # Allow "if: :show_title?" and "unless: :hide_title?" attribute options.
+        if_method_name = attr_data[:options][:if]
+        unless_method_name = attr_data[:options][:unless]
         show_attr = true
         show_attr &&= send(if_method_name) if if_method_name
         show_attr &&= !send(unless_method_name) if unless_method_name
-        show_attr &&= @fields[type].include?(attribute_name) if @fields[type]
+        show_attr &&= @_fields[type.to_s].include?(attribute_name) if @_fields[type.to_s]
         show_attr
       end
       protected :should_include_attr?
 
-      def should_include_attr_proc
-        lambda do |attribute_name, attr_data|
-          should_include_attr?(attribute_name, attr_data[:options][:if], attr_data[:options][:unless])
-        end
-      end
-      private :should_include_attr_proc
-
       def evaluate_attr_or_block(attribute_name, attr_or_block)
         if attr_or_block.is_a?(Proc)
           # A custom block was given, call it to get the value.
@@ -259,7 +256,7 @@ def self.serialize(objects, options = {})
       options[:jsonapi] = options.delete('jsonapi') || options[:jsonapi]
       options[:meta] = options.delete('meta') || options[:meta]
       options[:links] = options.delete('links') || options[:links]
-      options[:fields] = options.delete('fields') || options[:fields]
+      options[:fields] = options.delete('fields') || options[:fields] || {}
 
       # Deprecated: use serialize_errors method instead
       options[:errors] = options.delete('errors') || options[:errors]
@@ -268,20 +265,19 @@ def self.serialize(objects, options = {})
       includes = options[:include]
       includes = (includes.is_a?(String) ? includes.split(',') : includes).uniq if includes
 
-      fields = options[:fields] || {}
       # Transforms input so that the comma-separated fields are separate symbols in array
       # and keys are stringified
       # Example:
       # {posts: 'title,author,long_comments'} => {'posts' => [:title, :author, :long_comments]}
       # {posts: ['title', 'author', 'long_comments'} => {'posts' => [:title, :author, :long_comments]}
       #
-      fields = Hash[fields.map do |type, whitelisted_fields|
-        if whitelisted_fields.respond_to?(:to_ary)
-          [type.to_s, whitelisted_fields.map(&:to_sym)]
-        else
-          [type.to_s, whitelisted_fields.split(",").map(&:to_sym)]
-        end
-      end]
+      fields = {}
+      # Normalize fields to accept a comma-separated string or an array of strings.
+      options[:fields].map do |type, whitelisted_fields|
+        whitelisted_fields = [whitelisted_fields] if whitelisted_fields.is_a?(Symbol)
+        whitelisted_fields = whitelisted_fields.split(',') if whitelisted_fields.is_a?(String)
+        fields[type.to_s] = whitelisted_fields.map(&:to_sym)
+      end
 
       # An internal-only structure that is passed through serializers as they are created.
       passthrough_options = {

spec/serializer_spec.rb

@@ -441,12 +441,12 @@ def serialize_primary(object, options = {})
     it 'can include a top level errors node' do
       errors = [
         {
-          'source' => { 'pointer' => '/data/attributes/first-name' },
+          'source' => {'pointer' => '/data/attributes/first-name'},
           'title' => 'Invalid Attribute',
           'detail' => 'First name must contain at least three characters.'
         },
         {
-          'source' => { 'pointer' => '/data/attributes/first-name' },
+          'source' => {'pointer' => '/data/attributes/first-name'},
           'title' => 'Invalid Attribute',
           'detail' => 'First name must contain an emoji.'
         }
@@ -477,15 +477,15 @@ def read_attribute_for_validation(attr)
       user = DummyUser.new
       jsonapi_errors = [
         {
-          'source' => { 'pointer' => '/data/attributes/email' },
+          'source' => {'pointer' => '/data/attributes/email'},
           'detail' => 'Email is invalid'
         },
         {
-          'source' => { 'pointer' => '/data/attributes/email' },
+          'source' => {'pointer' => '/data/attributes/email'},
           'detail' => "Email can't be blank"
         },
         {
-          'source' => { 'pointer' => '/data/attributes/first-name' },
+          'source' => {'pointer' => '/data/attributes/first-name'},
           'detail' => "First name can't be blank"
         }
       ]
@@ -864,7 +864,7 @@ def read_attribute_for_validation(attr)
         long_comments = [first_comment, second_comment]
         post = create(:post, :with_author, long_comments: long_comments)
 
-        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: 'title'})
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: :title})
         expect(serialized_data).to eq ({
           'data' => {
             'type' => 'posts',
@@ -878,7 +878,6 @@ def read_attribute_for_validation(attr)
           }
         })
       end
-
       it 'allows to limit fields(relationships) for serialized resource' do
         first_user = create(:user)
         second_user = create(:user)
@@ -887,7 +886,8 @@ def read_attribute_for_validation(attr)
         long_comments = [first_comment, second_comment]
         post = create(:post, :with_author, long_comments: long_comments)
 
-        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: 'title,author,long_comments'})
+        fields = {posts: 'title,author,long_comments'}
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: fields)
         expect(serialized_data['data']['relationships']).to eq ({
           'author' => {
             'links' => {
@@ -903,7 +903,6 @@ def read_attribute_for_validation(attr)
           }
         })
       end
-
       it "allows also to pass specific fields as array instead of comma-separates values" do
         first_user = create(:user)
         second_user = create(:user)
@@ -925,7 +924,6 @@ def read_attribute_for_validation(attr)
           }
         })
       end
-
       it 'allows to limit fields(attributes and relationships) for included resources' do
         first_user = create(:user)
         second_user = create(:user)
@@ -937,40 +935,30 @@ def read_attribute_for_validation(attr)
         expected_primary_data = serialize_primary(post, {
           serializer: MyApp::PostSerializer,
           include_linkages: ['author'],
-          fields: { 'posts' => [:title, :author] }
+          fields: {'posts' => [:title, :author] }
         })
 
-        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: 'title,author', users: ''}, include: 'author')
+        fields = {posts: 'title,author', users: ''}
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: fields, include: 'author')
         expect(serialized_data).to eq ({
           'data' => expected_primary_data,
           'included' => [
-            serialize_primary(post.author, serializer: MyAppOtherNamespace::UserSerializer, fields: { 'users' => [] })
+            serialize_primary(
+              post.author,
+              serializer: MyAppOtherNamespace::UserSerializer,
+              fields: {'users' => []},
+            )
           ]
         })
 
-        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: 'title,author'}, include: 'author')
+        fields = {posts: 'title,author'}
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: fields, include: 'author')
         expect(serialized_data).to eq ({
           'data' => expected_primary_data,
           'included' => [
             serialize_primary(post.author, serializer: MyAppOtherNamespace::UserSerializer)
           ]
         })
-
-        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: 'title,author', users: 'nonexistent'}, include: 'author')
-        expect(serialized_data).to eq ({
-          'data' => expected_primary_data,
-          'included' => [
-            serialize_primary(post.author, serializer: MyAppOtherNamespace::UserSerializer, fields: { 'users' => [:nonexistent] })
-          ]
-        })
-
-        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: 'title,author', users: 'name'}, include: 'author')
-        expect(serialized_data).to eq ({
-          'data' => expected_primary_data,
-          'included' => [
-            serialize_primary(post.author, serializer: MyAppOtherNamespace::UserSerializer, fields: { 'users' => [:name] })
-          ]
-        })
       end
     end
   end