fast_serializer 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9aa9a0f0945690089e7b2811fc8a7a2bd7d5d391a44d6ffd5da46fde8cde178a
-  data.tar.gz: 5c7767c57d03ec466b8b0b8a241ecaaf1190b04115db5bbe63a04884e302320e
+  metadata.gz: 01d2bc87adca177550f7f64de96b9b0429686f2c1dde32551e651a3cea327a78
+  data.tar.gz: 5cef7d23fd40ec13f732cf6c5bb0426ccd70179cbce967c426bd6e5714e1e690
 SHA512:
-  metadata.gz: 6b385a08ca0c432e8f8660e19f95ad0f33b43372084dcd9910a10410f3f7cd168158e1138bfae101a76a216e210b50dfdea7a8207864182ab96ef65f099cef53
-  data.tar.gz: 3b39610d1a17bece32360aac268b5fd508e0fe46bb2fd2b29fa22f6e422e93fa2c8ae7b11bdd926f848b30e8c40f68d508e6ffe57c04eeea8cbbeb77e06fcceb
+  metadata.gz: b3256245ddafd1c12a22b753c2adca878cfabafea1b454030bee2eeb983fc9060241d07bd6f6befc12bf8c9bd9e09f468d39f848b72de10c4f6b6fe2efc68c63
+  data.tar.gz: e8b27a9a15222a5203f6c2db8d07851a74a004fe643a6abe0974354653f30afc89653e0ada6dee3e462ec1c09e9b779b9221d83c0dca586084d8d77aa03f3919

data/HISTORY.md

@@ -1,3 +1,13 @@
+### 1.1.0
+
+* Add helper method for scope option.
+
+* Pass serialization options to child serializers.
+
+* Add `if` option to conditionally include fields.
+
+* Better cache keys handling for more complex objects.
+
 ### 1.0.2
 
 * Better integration with ActiveSupport caching.

data/README.md

@@ -1,4 +1,4 @@
-This gem provides a highly optimized framework for serializing Ruby objects into hashes suitable for serialization to some other format (i.e. JSON). It provides many of the same features as other serialization frameworks like active_model_serializers, but it is designed to emphasize code efficiency over feature set.
+This gem provides a highly optimized framework for serializing Ruby objects into hashes suitable for serialization to some other format (i.e. JSON). It provides many of the same features as other serialization frameworks like active_model_serializers, but it is designed to emphasize code efficiency over feature set and syntactic surgar.
 
 ## Examples
 
@@ -27,7 +27,7 @@ person = Person.new(:id => 1, :first_name => "John", :last_name => "Doe", :gende
 
 Serializers are classes that include `FastSerializer::Serializer`. Call the `serialize` method to specify which fields to include in the serialized object. Field values are gotten by calling the corresponding method on the serializer. By default each serialized field will define a method that delegates to the wrapped object.
 
-ruby```
+```ruby
 class PersonSerializer
   include FastSerializer::Serializer
   serialize :id, :name
@@ -81,6 +81,25 @@ PersonSerializer.new(person).as_json # => {
                                      #    }
 ```
 
+Subclasses of serializers inherit all attributes. You can add or remove additional attributes in a subclass.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name
+  serialize :phone
+end
+
+class EmployeeSerializer < PersonSerializer
+  serialize :email
+  remove :phone
+end
+
+PersonSerializer.new(person).as_json # => {:id => 1, :name => "John Doe", :phone => "222-555-1212"}
+EmployeeSerializer.new(person).as_json # => {:id => 1, :name => "John Doe", :email => "john@example.com"}
+```
+
 ### Optional and excluding fields
 
 Serializer can have optional fields. You can also specify fields to exclude.
@@ -102,6 +121,34 @@ PersonSerializer.new(person, :include => [:gender]).as_json # => {:id => 1, :nam
 PersonSerializer.new(person, :exclude => [:id]).as_json # => {:name => "John Doe"}
 ```
 
+You can also pass the `:include` and `:exclude` options as hashes if you want to have them apply to associated records.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name
+  serialize :company, serializer: CompanySerializer
+end
+
+PersonSerializer.new(person, :exclude => {:company => :address}).as_json
+```
+
+You can also specify fields to be optional with an `:if` block in the definition with the name of a method from the serializer. It can also be a `Proc` that will be executed with the binding of an instance of the serializer. The field will only be included if the method returns a truthy value.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name, if: -> { scope && scope.id == id }
+  serialize :role, if: :staff?
+
+  def staff?
+    object.staff?
+  end
+end
+```
+
 ### Serializer options
 
 You can specify custom options that control how the object is serialized.
@@ -125,6 +172,17 @@ PersonSerializer.new(person).as_json # => {:id => 1, :name => "John Doe"}
 PersonSerializer.new(person, :last_first => true).as_json # => {:id => 1, :name => "Doe, John"}
 ```
 
+The options hash is passed to all nested serializers. The special option name `:scope` is available as a method within the serializer and is used by convention to enforce various data restrictions.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name
+  serialize :email, if: -> { scope && scope.id == object.id }
+end
+```
+
 ### Caching
 
 You can make serializers cacheable so that the serialized value can be stored and fetched from a cache.
@@ -162,6 +220,7 @@ You can also pass a cache to a serializer using the `:cache` option.
 If you have a collection of objects to serialize, you can use the `FastSerializer::ArraySerializer` to serialize an enumeration of objects.
 
 ```ruby
+  FastSerializer::ArraySerializer.new([a, b, c, d], :serializer => MyObjectSerializer)
 ```
 
 ## Performance

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.1.0

data/fast_serializer.gemspec

@@ -20,5 +20,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~>1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~>3.0"
-  spec.add_development_dependency "active_support", "~>4.0"
+  spec.add_development_dependency "active_support", ">=4.0"
 end

data/lib/fast_serializer/serialized_field.rb

@@ -1,11 +1,12 @@
 module FastSerializer
   # Data structure used internally for maintaining a field to be serialized.
   class SerializedField
-    attr_reader :name
+    attr_reader :name, :condition
 
-    def initialize(name, optional: false, serializer: nil, serializer_options: nil, enumerable: false)
+    def initialize(name, optional: false, serializer: nil, serializer_options: nil, enumerable: false, condition: nil)
       @name = name
       @optional = !!optional
+      @condition = condition
       if serializer
         @serializer = serializer
         @serializer_options = serializer_options
@@ -18,13 +19,13 @@ module FastSerializer
     end
 
     # Wrap a value in the serializer if one has been set. Otherwise just returns the raw value.
-    def serialize(value)
+    def serialize(value, options = nil)
       if value && @serializer
         serializer = nil
         if @enumerable
-          serializer = ArraySerializer.new(value, :serializer => @serializer, :serializer_options => @serializer_options)
+          serializer = ArraySerializer.new(value, :serializer => @serializer, :serializer_options => serializer_options(options))
         else
-          serializer = @serializer.new(value, @serializer_options)
+          serializer = @serializer.new(value, serializer_options(options))
         end
         context = SerializationContext.current
         if context
@@ -39,30 +40,39 @@ module FastSerializer
 
     private
 
+    def serializer_options(options)
+      if options
+        if @serializer_options
+          deep_merge(@serializer_options, options)
+        else
+          options
+        end
+      else
+        @serializer_options
+      end
+    end
+
+    def deep_merge(hash, merge_hash)
+      retval = {}
+      merge_hash.each do |key, merge_value|
+        value = hash[key]
+        if value.is_a?(Hash) && merge_value.is_a?(Hash)
+          retval[key] = deep_merge(value, merge_value)
+        else
+          retval[key] = merge_value
+        end
+      end
+      retval
+    end
+
     # Convert the value to primitive data types: string, number, boolean, symbol, time, date, array, hash.
     def serialize_value(value)
       if value.is_a?(String) || value.is_a?(Numeric) || value == nil || value == true || value == false || value.is_a?(Time) || value.is_a?(Date) || value.is_a?(Symbol)
         value
       elsif value.is_a?(Hash)
-        hash = nil
-        value.each do |k, v|
-          val = serialize_value(v)
-          if val.object_id != v.object_id
-            hash = value.dup unless hash
-            hash[k] = val
-          end
-        end
-        hash || value
+        serialize_hash(value)
       elsif value.is_a?(Enumerable)
-        array = nil
-        value.each_with_index do |v, i|
-          val = serialize_value(v)
-          if val.object_id != v.object_id
-            array = value.dup unless array
-            array[i] = val
-          end
-        end
-        array || value
+        serialize_enumerable(value)
       elsif value.respond_to?(:as_json)
         value.as_json
       elsif value.respond_to?(:to_hash)
@@ -74,5 +84,28 @@ module FastSerializer
       end
     end
 
+    def serialize_hash(value)
+      hash = nil
+      value.each do |k, v|
+        val = serialize_value(v)
+        if val.object_id != v.object_id
+          hash = value.dup unless hash
+          hash[k] = val
+        end
+      end
+      hash || value
+    end
+
+    def serialize_enumerable(value)
+      array = nil
+      value.each_with_index do |v, i|
+        val = serialize_value(v)
+        if val.object_id != v.object_id
+          array = value.dup unless array
+          array[i] = val
+        end
+      end
+      array || value
+    end
   end
 end

data/lib/fast_serializer/serializer.rb

@@ -94,9 +94,25 @@ module FastSerializer
       #   used if the :serializer option has been set. If the field is marked as enumerable, then the value will be
       #   serialized as an array with each element wrapped in the specified serializer.
       #
+      # * condition: Block or method name that will be called at runtime bound to the serializer that will
+      #   determine if the attribute will be included or not.
+      #
       # Subclasses will inherit all of their parent classes serialized fields. Subclasses can override fields
       # defined on the parent class by simply defining them again.
-      def serialize(*fields, as: nil, optional: false, delegate: true, serializer: nil, serializer_options: nil, enumerable: false)
+      def serialize(*fields)
+        options = {}
+        if fields.size > 1 && fields.last.is_a?(Hash)
+          options = fields.last
+          fields = fields[0, fields.size - 1]
+        end
+        as = options[:as]
+        optional = options.fetch(:optional, false)
+        delegate = options.fetch(:delegate, true)
+        enumerable = options.fetch(:enumerable, false)
+        serializer = options[:serializer]
+        serializer_options = options[:serializer_options]
+        condition = options[:if]
+
         if as && fields.size > 1
           raise ArgumentError.new("Cannot specify :as argument with multiple fields to serialize")
         end
@@ -109,7 +125,7 @@ module FastSerializer
 
           field = field.to_sym
           attribute = (name || field).to_sym
-          add_field(attribute, optional: optional, serializer: serializer, serializer_options: serializer_options, enumerable: enumerable)
+          add_field(attribute, optional: optional, serializer: serializer, serializer_options: serializer_options, enumerable: enumerable, condition: condition)
 
           if delegate && !method_defined?(attribute)
             define_delegate(attribute, field)
@@ -209,9 +225,16 @@ module FastSerializer
       private
 
       # Add a field to be serialized.
-      def add_field(name, optional:, serializer:, serializer_options:, enumerable:)
+      def add_field(name, optional:, serializer:, serializer_options:, enumerable:, condition:)
         name = name.to_sym
-        field = SerializedField.new(name, optional: optional, serializer: serializer, serializer_options: serializer_options, enumerable: enumerable)
+        if condition.is_a?(Proc)
+          include_method_name = "__include_#{name}?".to_sym
+          define_method(include_method_name, condition)
+          private include_method_name
+          condition = include_method_name
+        end
+        
+        field = SerializedField.new(name, optional: optional, serializer: serializer, serializer_options: serializer_options, enumerable: enumerable, condition: condition)
 
         # Add the field to the frozen list of fields.
         field_list = []
@@ -278,6 +301,10 @@ module FastSerializer
       @options[name] if @options
     end
 
+    def scope
+      option(:scope)
+    end
+
     # Return true if this serializer is cacheable.
     def cacheable?
       option(:cacheable) || self.class.cacheable?
@@ -297,7 +324,8 @@ module FastSerializer
     # key is an array made up of the serializer class name, wrapped object, and
     # serialization options hash.
     def cache_key
-      [self.class.name, object, options]
+      object_cache_key = (object.respond_to?(:cache_key) ? object.cache_key : object)
+      [self.class.name, object_cache_key, options_cache_key(options)]
     end
 
     # :nodoc:
@@ -316,17 +344,40 @@ module FastSerializer
       SerializationContext.use do
         self.class.serializable_fields.each do |field|
           name = field.name
+          
           if field.optional?
             next unless include_fields && include_fields.include?(name)
           end
-          next if excluded_fields && excluded_fields.include?(name)
-          value = field.serialize(send(name))
+          next if excluded_fields && excluded_fields[name] == true
+          condition = field.condition
+          next if condition && !send(condition)
+          
+          value = field.serialize(send(name), serializer_options(name))
           hash[name] = value
         end
       end
       hash
     end
 
+    def serializer_options(name)
+      opts = options
+      return nil unless opts
+      if opts && (opts.include?(:include) || opts.include?(:exclude))
+        opts = opts.dup
+        include_options = opts[:include]
+        if include_options.is_a?(Hash)
+          include_options = include_options[name.to_sym]
+          opts[:include] = include_options if include_options
+        end
+        exclude_options = options[:exclude]
+        if exclude_options.is_a?(Hash)
+          exclude_options = exclude_options[name.to_sym]
+          opts[:exclude] = exclude_options if exclude_options
+        end
+      end
+      opts
+    end
+
     # Load the hash that will represent the wrapped object as a serialized object from a cache.
     def load_from_cache
       if cache
@@ -340,24 +391,52 @@ module FastSerializer
 
     private
 
-    # Return a list of optional fields to be included in the output from the :include option.
-    def included_optional_fields
-      included_fields = option(:include)
-      if included_fields
-        Array(included_fields).collect(&:to_sym)
+    def options_cache_key(options)
+      return nil if options.nil?
+      if options.respond_to?(:cache_key)
+        options.cache_key
+      elsif options.is_a?(Hash)
+        hash_key = {}
+        options.each do |key, value|
+          hash_key[key] = options_cache_key(value)
+        end
+        hash_key
+      elsif options.is_a?(Enumerable)
+        options.collect{|option| options_cache_key(option)}
       else
-        nil
+        options
       end
     end
 
+    # Return a list of optional fields to be included in the output from the :include option.
+    def included_optional_fields
+      normalize_field_list(option(:include))
+    end
+
     # Return a list of fields to be excluded from the output from the :exclude option.
     def excluded_regular_fields
-      excluded_fields = option(:exclude)
-      if excluded_fields
-        Array(excluded_fields).collect(&:to_sym)
+      normalize_field_list(option(:exclude))
+    end
+
+    def normalize_field_list(vals)
+      return nil if vals.nil?
+      if vals.is_a?(Hash)
+        hash = nil
+        vals.each do |key, values|
+          if hash || !key.is_a?(Symbol)
+            hash ||= {}
+            hash[key.to_sym] = values
+          end
+        end
+        vals = hash if hash
       else
-        nil
+        hash = {}
+        Array(vals).each do |key|
+          hash[key.to_sym] = true
+        end
+        vals = hash
       end
+      vals
     end
   end
 end

data/spec/serializer_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe FastSerializer::Serializer do
 
-  let(:model){ SimpleModel.new(:id => 1, :name => "foo", :description => "foobar") }
+  let(:model){ SimpleModel.new(:id => 1, :name => "foo", :description => "foobar", :number => 12) }
 
   it "should serialize object to JSON compatible format" do
     serializer = SimpleSerializer.new(model)
@@ -102,6 +102,25 @@ describe FastSerializer::Serializer do
     })
   end
 
+  it "should pass include and exclude options to child serializers" do
+    other_model = SimpleModel.new(:id => 3, :name => "other")
+    complex = SimpleModel.new(:id => 2, :name => :complex, :parent => model, :associations => [model, other_model])
+    serializer = ComplexSerializer.new(complex, :serial_number => 15, :exclude => {:associations => [:validated]}, :include => {:parent => :amount})
+    expect(serializer.as_json).to eq({
+      :id => 2, :name => :complex, :validated => false, :serial_number => 15,
+      :associations => [
+        {:id => 1, :name => "foo"},
+        {:id => 3, :name => "other"}
+      ],
+      :parent => {:id => 1, :name => "foo", :validated => false, :amount => 12}
+    })
+  end
+
+  it "should have a scope option" do
+    serializer = CachedSerializer.new(model, :scope => :foo)
+    expect(serializer.scope).to eq :foo
+  end
+
   it "should return identical serialized values for serializers on the same object and options inside the same context" do
     other_model = SimpleModel.new(:id => 3, :name => "other")
     complex = SimpleModel.new(:id => 2, :name => "complex", :associations => [model, other_model, model])
@@ -122,7 +141,7 @@ describe FastSerializer::Serializer do
       "associations" => [
         {"id" => 1, "name" => "foo", "validated" => false}
       ],
-      "parent" => {"id" => 1, "name" => "foo", "validated" => false}
+      "parent" => {"id" => 1, "name" => "foo", "validated" => false, "description"=>"foobar"}
     })
   end
 
@@ -149,4 +168,10 @@ describe FastSerializer::Serializer do
     serializer = CircularSerializer.new(model)
     expect{ serializer.as_json }.to raise_error(FastSerializer::CircularReferenceError)
   end
+
+  it "should allow conditionals on serialized fields" do
+    expect(ConditionalSerializer.new(model).as_json).to eq({:id => 1})
+    expect(ConditionalSerializer.new(model, :scope => :description).as_json).to eq({:id => 1,  :description => "foobar"})
+    expect(ConditionalSerializer.new(model, :scope => :name).as_json).to eq({:id => 1,  :name => "foo"})
+  end
 end

data/spec/support/test_models.rb

@@ -51,7 +51,7 @@ end
 class ComplexSerializer < SimpleSerializer
   serialize :serial_number, delegate: false
   serialize :associations, delegate: true, serializer: CachedSerializer, enumerable: true
-  serialize :parent, delegate: true, serializer: SimpleSerializer
+  serialize :parent, delegate: true, serializer: SimpleSerializer, serializer_options: {include: :description}
 
   def serial_number
     option(:serial_number)
@@ -62,3 +62,13 @@ class CircularSerializer < SimpleSerializer
   remove :name, :validated
   serialize :parent, serializer: self
 end
+
+class ConditionalSerializer < SimpleSerializer
+  remove :validated
+  serialize :description, if: -> { scope == :description }
+  serialize :name, if: :show_name?
+  
+  def show_name?
+    scope == :name
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_serializer
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - We Heart It
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-06 00:00:00.000000000 Z
+date: 2018-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -57,14 +57,14 @@ dependencies:
   name: active_support
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
 description: Super fast object serialization for API's combining a simple DSL with