Merge pull request #265 from Netflix/dev

Dev

Author: shishirmk

README.md

@@ -30,6 +30,8 @@ Fast JSON API serialized 250 records in 3.01 ms
   * [Collection Serialization](#collection-serialization)
   * [Caching](#caching)
   * [Params](#params)
+  * [Conditional Attributes](#conditional-attributes)
+  * [Conditional Relationships](#conditional-relationships)
 * [Contributing](#contributing)
 
 
@@ -259,6 +261,26 @@ hash = MovieSerializer.new([movie, movie], options).serializable_hash
 json_string = MovieSerializer.new([movie, movie], options).serialized_json
 ```
 
+#### Control Over Collection Serialization
+
+You can use `is_collection` option to have better control over collection serialization.
+
+If this option is not provided or `nil` autedetect logic is used to try understand
+if provided resource is a single object or collection.
+
+Autodetect logic is compatible with most DB toolkits (ActiveRecord, Sequel, etc.) but
+**cannot** guarantee that single vs collection will be always detected properly.
+
+```ruby
+options[:is_collection]
+```
+
+was introduced to be able to have precise control this behavior
+
+- `nil` or not provided: will try to autodetect single vs collection (please, see notes above)
+- `true` will always treat input resource as *collection*
+- `false` will always treat input resource as *single object*
+
 ### Caching
 Requires a `cache_key` method be defined on model:
 
@@ -307,6 +329,53 @@ serializer.serializable_hash
 Custom attributes and relationships that only receive the resource are still possible by defining
 the block to only receive one argument.
 
+### Conditional Attributes
+
+Conditional attributes can be defined by passing a Proc to the `if` key on the `attribute` method. Return `true` if the attribute should be serialized, and `false` if not. The record and any params passed to the serializer are available inside the Proc as the first and second parameters, respectively.
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+
+  attributes :name, :year
+  attribute :release_year, if: Proc.new do |record|
+    # Release year will only be serialized if it's greater than 1990
+    record.release_year > 1990
+  end
+
+  attribute :director, if: Proc.new do |record, params|
+    # The director will be serialized only if the :admin key of params is true
+    params && params[:admin] == true
+  end
+end
+
+# ...
+current_user = User.find(cookies[:current_user_id])
+serializer = MovieSerializer.new(movie, { params: { admin: current_user.admin? }})
+serializer.serializable_hash
+```
+
+### Conditional Relationships
+
+Conditional relationships can be defined by passing a Proc to the `if` key. Return `true` if the relationship should be serialized, and `false` if not. The record and any params passed to the serializer are available inside the Proc as the first and second parameters, respectively.
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+
+  # Actors will only be serialized if the record has any associated actors
+  has_many :actors, if: Proc.new { |record| record.actors.any? }
+
+  # Owner will only be serialized if the :admin key of params is true
+  belongs_to :owner, if: Proc.new { |record, params| params && params[:admin] == true }
+end
+
+# ...
+current_user = User.find(cookies[:current_user_id])
+serializer = MovieSerializer.new(movie, { params: { admin: current_user.admin? }})
+serializer.serializable_hash
+```
+
 ### Customizable Options
 
 Option | Purpose | Example

lib/extensions/has_one.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
-if defined?(::ActiveRecord)
-  ::ActiveRecord::Associations::Builder::HasOne.class_eval do
-    # Based on
-    # https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/builder/collection_association.rb#L50
-    # https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/builder/singular_association.rb#L11
-    def self.define_accessors(mixin, reflection)
-      super
-      name = reflection.name
-      mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
-        def #{name}_id
-          # if an attribute is already defined with this methods name we should just use it
-          return read_attribute(__method__) if has_attribute?(__method__)
-          association(:#{name}).reader.try(:id)
-        end
-      CODE
-    end
+::ActiveRecord::Associations::Builder::HasOne.class_eval do
+  # Based on
+  # https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/builder/collection_association.rb#L50
+  # https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/builder/singular_association.rb#L11
+  def self.define_accessors(mixin, reflection)
+    super
+    name = reflection.name
+    mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
+      def #{name}_id
+        # if an attribute is already defined with this methods name we should just use it
+        return read_attribute(__method__) if has_attribute?(__method__)
+        association(:#{name}).reader.try(:id)
+      end
+    CODE
   end
 end

lib/fast_jsonapi.rb

@@ -2,5 +2,9 @@
 
 module FastJsonapi
   require 'fast_jsonapi/object_serializer'
-  require 'extensions/has_one'
+  if defined?(::Rails)
+    require 'fast_jsonapi/railtie'
+  elsif defined?(::ActiveRecord)
+    require 'extensions/has_one'
+  end
 end

lib/fast_jsonapi/attribute.rb

@@ -0,0 +1,29 @@
+module FastJsonapi
+  class Attribute
+    attr_reader :key, :method, :conditional_proc
+
+    def initialize(key:, method:, options: {})
+      @key = key
+      @method = method
+      @conditional_proc = options[:if]
+    end
+
+    def serialize(record, serialization_params, output_hash)
+      if include_attribute?(record, serialization_params)
+        output_hash[key] = if method.is_a?(Proc)
+          method.arity == 1 ? method.call(record) : method.call(record, serialization_params)
+        else
+          record.public_send(method)
+        end
+      end
+    end
+
+    def include_attribute?(record, serialization_params)
+      if conditional_proc.present?
+        conditional_proc.call(record, serialization_params)
+      else
+        true
+      end
+    end
+  end
+end

lib/fast_jsonapi/link.rb

@@ -0,0 +1,18 @@
+module FastJsonapi
+  class Link
+    attr_reader :key, :method
+
+    def initialize(key:, method:)
+      @key = key
+      @method = method
+    end
+
+    def serialize(record, serialization_params, output_hash)
+      output_hash[key] = if method.is_a?(Proc)
+        method.arity == 1 ? method.call(record) : method.call(record, serialization_params)
+      else
+        record.public_send(method)
+      end
+    end
+  end
+end

lib/fast_jsonapi/object_serializer.rb

@@ -3,6 +3,9 @@
 require 'active_support/core_ext/object'
 require 'active_support/concern'
 require 'active_support/inflector'
+require 'fast_jsonapi/attribute'
+require 'fast_jsonapi/relationship'
+require 'fast_jsonapi/link'
 require 'fast_jsonapi/serialization_core'
 
 module FastJsonapi
@@ -25,7 +28,7 @@ def initialize(resource, options = {})
     end
 
     def serializable_hash
-      return hash_for_collection if is_collection?(@resource)
+      return hash_for_collection if is_collection?(@resource, @is_collection)
 
       hash_for_one_record
     end
@@ -72,6 +75,7 @@ def process_options(options)
       @known_included_objects = {}
       @meta = options[:meta]
       @links = options[:links]
+      @is_collection = options[:is_collection]
       @params = options[:params] || {}
       raise ArgumentError.new("`params` option passed to serializer must be a hash") unless @params.is_a?(Hash)
 
@@ -81,8 +85,10 @@ def process_options(options)
       end
     end
 
-    def is_collection?(resource)
-      resource.respond_to?(:each) && !resource.respond_to?(:each_pair)
+    def is_collection?(resource, force_is_collection = nil)
+      return force_is_collection unless force_is_collection.nil?
+
+      resource.respond_to?(:size) && !resource.respond_to?(:each_pair)
     end
 
     class_methods do
@@ -118,6 +124,9 @@ def set_key_transform(transform_name)
           underscore: :underscore
         }
         self.transform_method = mapping[transform_name.to_sym]
+
+        # ensure that the record type is correctly transformed
+        set_type(reflected_record_type) if reflected_record_type
       end
 
       def run_key_transform(input)
@@ -149,48 +158,51 @@ def cache_options(cache_options)
 
       def attributes(*attributes_list, &block)
         attributes_list = attributes_list.first if attributes_list.first.class.is_a?(Array)
+        options = attributes_list.last.is_a?(Hash) ? attributes_list.pop : {}
         self.attributes_to_serialize = {} if self.attributes_to_serialize.nil?
+
         attributes_list.each do |attr_name|
           method_name = attr_name
           key = run_key_transform(method_name)
-          attributes_to_serialize[key] = block || method_name
+          attributes_to_serialize[key] = Attribute.new(
+            key: key,
+            method: block || method_name,
+            options: options
+          )
         end
       end
 
       alias_method :attribute, :attributes
 
-      def add_relationship(name, relationship)
+      def add_relationship(relationship)
         self.relationships_to_serialize = {} if relationships_to_serialize.nil?
         self.cachable_relationships_to_serialize = {} if cachable_relationships_to_serialize.nil?
         self.uncachable_relationships_to_serialize = {} if uncachable_relationships_to_serialize.nil?
-
-        if !relationship[:cached]
-          self.uncachable_relationships_to_serialize[name] = relationship
+        
+        if !relationship.cached
+          self.uncachable_relationships_to_serialize[relationship.name] = relationship
         else
-          self.cachable_relationships_to_serialize[name] = relationship
+          self.cachable_relationships_to_serialize[relationship.name] = relationship
         end
-        self.relationships_to_serialize[name] = relationship
-     end
+        self.relationships_to_serialize[relationship.name] = relationship
+      end
 
       def has_many(relationship_name, options = {}, &block)
-        name = relationship_name.to_sym
-        hash = create_relationship_hash(relationship_name, :has_many, options, block)
-        add_relationship(name, hash)
+        relationship = create_relationship(relationship_name, :has_many, options, block)
+        add_relationship(relationship)
       end
 
       def has_one(relationship_name, options = {}, &block)
-        name = relationship_name.to_sym
-        hash = create_relationship_hash(relationship_name, :has_one, options, block)
-        add_relationship(name, hash)
+        relationship = create_relationship(relationship_name, :has_one, options, block)
+        add_relationship(relationship)
       end
 
       def belongs_to(relationship_name, options = {}, &block)
-        name = relationship_name.to_sym
-        hash = create_relationship_hash(relationship_name, :belongs_to, options, block)
-        add_relationship(name, hash)
+        relationship = create_relationship(relationship_name, :belongs_to, options, block)
+        add_relationship(relationship)
       end
 
-      def create_relationship_hash(base_key, relationship_type, options, block)
+      def create_relationship(base_key, relationship_type, options, block)
         name = base_key.to_sym
         if relationship_type == :has_many
           base_serialization_key = base_key.to_s.singularize
@@ -201,7 +213,7 @@ def create_relationship_hash(base_key, relationship_type, options, block)
           base_key_sym = name
           id_postfix = '_id'
         end
-        {
+        Relationship.new(
           key: options[:key] || run_key_transform(base_key),
           name: name,
           id_method_name: options[:id_method_name] || "#{base_serialization_key}#{id_postfix}".to_sym,
@@ -210,9 +222,10 @@ def create_relationship_hash(base_key, relationship_type, options, block)
           object_block: block,
           serializer: compute_serializer_name(options[:serializer] || base_key_sym),
           relationship_type: relationship_type,
-          cached: options[:cached] || false,
-          polymorphic: fetch_polymorphic_option(options)
-        }
+          cached: options[:cached],
+          polymorphic: fetch_polymorphic_option(options),
+          conditional_proc: options[:if]
+        )
       end
 
       def compute_serializer_name(serializer_key)
@@ -233,7 +246,11 @@ def link(link_name, link_method_name = nil, &block)
         self.data_links = {} if self.data_links.nil?
         link_method_name = link_name if link_method_name.nil?
         key = run_key_transform(link_name)
-        self.data_links[key] = block || link_method_name
+
+        self.data_links[key] = Link.new(
+          key: key,
+          method: block || link_method_name
+        )
       end
 
       def validate_includes!(includes)
@@ -244,8 +261,8 @@ def validate_includes!(includes)
           parse_include_item(include_item).each do |parsed_include|
             relationship_to_include = klass.relationships_to_serialize[parsed_include]
             raise ArgumentError, "#{parsed_include} is not specified as a relationship on #{klass.name}" unless relationship_to_include
-            raise NotImplementedError if relationship_to_include[:polymorphic].is_a?(Hash)
-            klass = relationship_to_include[:serializer].to_s.constantize
+            raise NotImplementedError if relationship_to_include.polymorphic.is_a?(Hash)
+            klass = relationship_to_include.serializer.to_s.constantize
           end
         end
       end

lib/fast_jsonapi/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+class Railtie < Rails::Railtie
+  initializer 'fast_jsonapi.active_record' do
+    ActiveSupport.on_load :active_record do
+      require 'extensions/has_one'
+    end
+  end
+end