fast_serializer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5f74dbde94fa39ac31bdc30753fe69645952f58e
+  data.tar.gz: bdce8bb4428da1e1a4ce866635c3a22a636d26d2
+SHA512:
+  metadata.gz: 442fa957a7d296934849581cd5dd8aa777c6cfda8ea5e52d889f0b2e27f11ce953e88a0b58ada157ce0cb89f4451dd8168d76ed43211ff7214480f3313bc1aaf
+  data.tar.gz: 07157e747b2af7c9f3e6636cbc61f2f48dd0c075530151e897a7a232714a2e12dc23666db046f5172d487b30ceb6917a7d4d555a5dd711e05940ced9ce97d707

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/HISTORY.txt

@@ -0,0 +1,3 @@
+1.0.0
+
+* Initial release

data/MIT_LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 We Heart It
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+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.
+
+## Examples
+
+For these examples we'll assume we have a simple Person class.
+
+```ruby
+class Person
+  attr_accessor :id, :first_name, :last_name, :parents, :children
+  
+  def intitialize(attributes = {})
+    @id = attributes[:id]
+    @first_name = attributes[:first_name]
+    @last_name = attributes[:last_name]
+    @gender = attributes(:gender)
+    @parent = attributes[:parents]
+    @children = attributes[:children] || {}
+  end
+  
+  def ==(other)
+    other.instance_of?(self.class) && other.id == id
+  end
+end
+
+person = Person.new(:id => 1, :first_name => "John", :last_name => "Doe", :gender => "M")
+```
+
+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```
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id, :name
+  
+  def name
+    "#{object.first_name} #{object.last_name}"
+  end
+end
+
+PersonSerializer.new(person).as_json # => {:id => 1, :name => "John Doe"}
+```
+
+You can alias fields so the serialized field name is different than the internal field name. You can also turn off creating the delegation method if it isn't needed for a field.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id, as: :person_id
+  serialize :name, :delegate => false
+  
+  def name
+    "#{object.first_name} #{object.last_name}"
+  end
+end
+
+PersonSerializer.new(person).as_json # => {:person_id => 1, :name => "John Doe"}
+```
+
+You can specify a serializer to use on fields that return complex objects.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name, :delegate => false
+  serialize :parent, serializer: PersonSerializer
+  serialize :children, serializer: PersonSerializer, enumerable: true
+  
+  def name
+    "#{object.first_name} #{object.last_name}"
+  end
+end
+
+person.parent = Person.new(:id => 2, :first_name => "Sally", :last_name => "Smith")
+person.children << Person.new(:id => 3, :first_name => "Jane", :last_name => "Doe")
+PersonSerializer.new(person).as_json # => {
+                                     #      :id => 1,
+                                     #      :name => "John Doe",
+                                     #      :parent => {:id => 2, :name => "Sally Smith"},
+                                     #      :children => [{:id => 3, :name => "Jane Doe"}]
+                                     #    }
+```
+
+Serializer can have optional fields. You can also specify fields to exclude.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name, :delegate => false
+  serialize :gender, optional: true
+  
+  def name
+    "#{object.first_name} #{object.last_name}"
+  end
+end
+
+PersonSerializer.new(person).as_json # => {:id => 1, :name => "John Doe"}
+PersonSerializer.new(person, :include => [:gender]).as_json # => {:id => 1, :name => "John Doe", :gender => "M"}
+PersonSerializer.new(person, :exclude => [:id]).as_json # => {:name => "John Doe"}
+```
+
+You can specify custom options that control how the object is serialized.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name, :delegate => false
+  
+  def name
+    if option(:last_first)
+      "#{object.last_name}, #{object.first_name}"
+    else
+      "#{object.first_name} #{object.last_name}"
+    end
+  end
+end
+
+PersonSerializer.new(person).as_json # => {:id => 1, :name => "John Doe"}
+PersonSerializer.new(person, :last_first).as_json # => {:id => 1, :name => "Doe, John"}
+```
+
+You can make serializers cacheable so that the serialized value can be stored and fetched from a cache.
+
+```ruby
+class PersonSerializer
+  include FastSerializer::Serializer
+  serialize :id
+  serialize :name, :delegate => false
+  
+  cacheable true, ttl: 60
+  
+  def name
+    if option(:last_first)
+      "#{object.last_name}, #{object.first_name}"
+    else
+      "#{object.first_name} #{object.last_name}"
+    end
+  end
+end
+
+FastSerializer.cache = MyCache.new # Must be an implementation of FastSerializer::Cache
+```
+
+## Performance
+
+Your mileage may vary. In many cases the performance of the serialization code doesn't particularly matter and this gem performs just about as well as other solutions. However, if you do have high throughput API or can utilize the caching features or have heavily nested models in your JSON responses, then the performance increase may be noticeable.

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'RVM likes to call it tests'
+task :tests => :test
+
+begin
+  require 'rspec'
+  require 'rspec/core/rake_task'
+  desc 'Run the unit tests'
+  RSpec::Core::RakeTask.new(:test)
+rescue LoadError
+  task :test do
+    STDERR.puts "You must have rspec >= 2.0 installed to run the tests"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/fast_serializer.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "fast_serializer"
+  spec.version       = File.read(File.expand_path("../VERSION", __FILE__)).chomp
+  spec.authors       = ["We Heart It", "Brian Durand"]
+  spec.email         = ["dev@weheartit.com", "bbdurand@gmail.com"]
+  spec.description   = %q{Super fast object serialization for API's combining a simple DSL with many optimizations under the hood.}
+  spec.summary       = %q{Super fast object serialization for API's.}
+  spec.homepage      = "https://github.com/weheartit/fast_serializer"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~>1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~>3.0"
+end

data/lib/fast_serializer.rb

@@ -0,0 +1,37 @@
+require 'json'
+require 'time'
+require 'date'
+
+module FastSerializer
+  require_relative 'fast_serializer/cache'
+  require_relative 'fast_serializer/cache/active_support_cache'
+  require_relative 'fast_serializer/serialization_context'
+  require_relative 'fast_serializer/serialized_field'
+  require_relative 'fast_serializer/serializer'
+  require_relative 'fast_serializer/array_serializer'
+  
+  class << self
+    # Get the global cache implementation used for storing cacheable serializers.
+    def cache
+      @cache if defined?(@cache)
+    end
+  
+    # Set the global cache implementation used for storing cacheable serializers.
+    # The cache implementation should implement the +fetch+ method as defined in 
+    # FastSerializer::Cache. By default no cache is set so caching won't do anything.
+    #
+    # In a Rails app, you can initialize the cache by simply passing in the value :rails
+    # to use the default Rails.cache.
+    def cache=(cache)
+      cache = Cache::ActiveSupportCache.new(Rails.cache) if cache == :rails
+      @cache = cache
+    end
+  end
+  
+  # Exception raised when there is a circular reference serializing a model dependent on itself.
+  class CircularReferenceError < StandardError
+    def initialize(model)
+      super("Circular refernce on #{model.inspect}")
+    end
+  end
+end

data/lib/fast_serializer/array_serializer.rb

@@ -0,0 +1,92 @@
+module FastSerializer
+  # Serializer implementation for serializing an array of objects.
+  # This class allows taking advantage of a single SerializationContext
+  # for caching duplicate serializers.
+  class ArraySerializer
+    include Serializer
+    
+    serialize :array
+    
+    def initialize(object, options = nil)
+      super(Array(object), options)
+    end
+    
+    def cache_key
+      if option(:serializer)
+        array.collect(&:cache_key)
+      else
+        super
+      end
+    end
+    
+    def cacheable?
+      if option(:cacheable) || self.class.cacheable?
+        true
+      elsif option(:serializer)
+        option(:serializer).cacheable?
+      else
+        super
+      end
+    end
+    
+    def cache_ttl
+      if option(:cache_ttl)
+        true
+      elsif option(:serializer)
+        option(:serializer).cache_ttl
+      else
+        super
+      end
+    end
+    
+    def cache
+      if option(:cache)
+        true
+      elsif option(:serializer)
+        option(:serializer).cache
+      else
+        super
+      end
+    end
+    
+    def as_json(*args)
+      if array.nil?
+        nil
+      elsif array.empty?
+        []
+      else
+        super[:array]
+      end
+    end
+    
+    undef :to_hash
+    undef :to_h
+    alias :to_a :as_json
+    
+    protected
+    
+    def load_from_cache
+      if cache
+        values = cache.fetch_all(array, cache_ttl){|serializer| serializer.as_json}
+        {:array => values}
+      else
+        load_hash
+      end
+    end
+    
+    private
+    
+    def array
+      unless defined?(@_array)
+        serializer = option(:serializer)
+        if serializer
+          serializer_options = option(:serializer_options)
+          @_array = object.collect{|obj| serializer.new(obj, serializer_options)}
+        else
+          @_array = object
+        end
+      end
+      @_array
+    end
+  end
+end

data/lib/fast_serializer/cache.rb

@@ -0,0 +1,22 @@
+module FastSerializer
+  # Base class for cache implementations for storing cacheable serializers.
+  # Implementations must implement the +fetch+ method.
+  class Cache
+    def fetch(serializer, ttl, &block)
+      raise NotImplementedError
+    end
+    
+    # Fetch multiple serializers from the cache. The default behavior is just
+    # to call +fetch+ with each serializer. Implementations may optimize this
+    # if the cache can return multiple values at once.
+    # 
+    # The block to this method will be yielded to with each uncached serializer.
+    def fetch_all(serializers, ttl)
+      serializers.collect do |serializer|
+        fetch(serializer, ttl) do
+          yield(serializer)
+        end
+      end
+    end
+  end
+end

data/lib/fast_serializer/cache/active_support_cache.rb

@@ -0,0 +1,21 @@
+module FastSerializer
+  # ActiveSupport compatible cache implementation.
+  class Cache::ActiveSupportCache < Cache
+    attr_reader :cache
+    
+    def initialize(cache)
+      @cache = cache
+    end
+    
+    def fetch(serializer, ttl, &block)
+      exists = !!@cache.read(serializer.cache_key)
+      @cache.fetch(serializer.cache_key, :expires_in => ttl, &block)
+    end
+    
+    def fetch_all(serializers, ttl)
+      @cache.fetch_multi(*serializers) do |serializer|
+        yield(serializer)
+      end
+    end
+  end
+end

data/lib/fast_serializer/serialization_context.rb

@@ -0,0 +1,70 @@
+module FastSerializer
+  # This class provides a context for creating serializers that allows
+  # duplicate serializers to be re-used within the context. This then
+  # short circuits the serialization process on the duplicates.
+  class SerializationContext
+    class << self
+      # Use a context or create one for use within a block. Any serializers
+      # based on the same object with the same options within the block will be
+      # re-used instead of creating duplicates.
+      def use
+        if Thread.current[:fast_serializer_context]
+          yield
+        else
+          begin
+            Thread.current[:fast_serializer_context] = new
+            yield
+          ensure
+            Thread.current[:fast_serializer_context] = nil
+          end
+        end
+      end
+      
+      # Return the current context or nil if none is in use.
+      def current
+        Thread.current[:fast_serializer_context]
+      end
+    end
+    
+    def initialize
+      @cache = nil
+      @references = nil
+    end
+    
+    # Returns a serializer from the context cache if a duplicate has already
+    # been created. Otherwise creates the serializer and adds it to the
+    # cache.
+    def load(serializer_class, object, options = nil)
+      key = [serializer_class, object, options]
+      serializer = nil
+      if @cache
+        serializer = @cache[key]
+      end
+      
+      unless serializer
+        serializer = serializer_class.allocate
+        serializer.send(:initialize, object, options)
+        @cache ||= {}
+        @cache[key] = serializer
+      end
+      
+      serializer
+    end
+    
+    # Maintain reference stack to avoid circular references.
+    def with_reference(object)
+      if @references
+        raise CircularReferenceError.new(object) if @references.include?(object)
+      else
+        @references = []
+      end
+      
+      begin
+        @references.push(object)
+        yield
+      ensure
+        @references.pop
+      end
+    end
+  end
+end