fast_jsonapi 1.0.17 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c5fa6a70751601bec882ccec2e0e70b3b76fd084
-  data.tar.gz: 307516586bee4df357afb385ee89776bc118cd13
+SHA256:
+  metadata.gz: fed8f385f05f5ea345918e1e5310e3b0a36b1dfe0c7a5cf001d7eddba8374e38
+  data.tar.gz: fb2c1aac0e54a6dae6a6c1838005995531f25b1689168caed6ecf6f6602ddc0d
 SHA512:
-  metadata.gz: 982f868f471f0ad64e8d424ba3fe1313f0c14ee841b87ce8920d68816ef8d306f18b5b39be13eaffdf7c00ed888be3059195c7008f8541dfeefe2036ebd4c1ad
-  data.tar.gz: 27aef6f9b9e7fb5b94f881c190814dcc7d44d6919118cf732f42a77fe5bf941644bcfbef9986417926a68981d3c00bcfc35276504a0294b2dd2445968b4cab1e
+  metadata.gz: f935259ae0fcaa99dfb30d048d1fde82c99aba7d9abd21a4162cfad35b7448614cf44086414b9e0980bc9737794db31350124f7b9533968f97563c2f7fafbe76
+  data.tar.gz: e20e432a1a4e03f08d055cb134a894afe14e12a8c714be5330c1cc8259e6a592ff9ab4869156dc85af67ee21005bf6769660d872e8be5a9c2461b0530876d8bd

data/README.md

@@ -1,12 +1,12 @@
 # Fast JSON API
 
-[![NetflixOSS Lifecycle](https://img.shields.io/osslifecycle/Netflix/osstracker.svg)]()
+[![Build Status](https://travis-ci.org/Netflix/fast_jsonapi.svg?branch=master)](https://travis-ci.org/Netflix/fast_jsonapi)
 
 A lightning fast [JSON:API](http://jsonapi.org/) serializer for Ruby Objects.
 
 # Performance Comparison
 
-We compare serialization times with Active Model Serializer as part of RSpec performance tests included on this library. We want to ensure that with every change on this library, serialization time is at least `25 times` faster than Active Model Serializers on up to current benchmark of 1000 records.
+We compare serialization times with Active Model Serializer as part of RSpec performance tests included on this library. We want to ensure that with every change on this library, serialization time is at least `25 times` faster than Active Model Serializers on up to current benchmark of 1000 records. Please read the [performance document](https://github.com/Netflix/fast_jsonapi/blob/master/performance_methodology.md) for any questions related to methodology.
 
 ## Benchmark times for 250 records
 
@@ -21,10 +21,12 @@ Fast JSON API serialized 250 records in 3.01 ms
 * [Features](#features)
 * [Installation](#installation)
 * [Usage](#usage)
+  * [Rails Generator](#rails-generator)
   * [Model Definition](#model-definition)
   * [Serializer Definition](#serializer-definition)
   * [Object Serialization](#object-serialization)
   * [Compound Document](#compound-document)
+  * [Key Transforms](#key-transforms)
   * [Collection Serialization](#collection-serialization)
   * [Caching](#caching)
 * [Contributing](#contributing)
@@ -54,11 +56,19 @@ $ bundle install
 
 ## Usage
 
+### Rails Generator
+You can use the bundled generator if you are using the library inside of
+a Rails project:
+
+    rails g Serializer Movie name year
+
+This will create a new serializer in `app/serializers/movie_serializer.rb`
+
 ### Model Definition
 
 ```ruby
 class Movie
-  attr_accessor :id, :name, :year, :actor_ids, :owner_id
+  attr_accessor :id, :name, :year, :actor_ids, :owner_id, :movie_type_id
 end
 ```
 
@@ -68,6 +78,7 @@ end
 class MovieSerializer
   include FastJsonapi::ObjectSerializer
   set_type :movie  # optional
+  set_id :owner_id # optional
   attributes :name, :year
   has_many :actors
   belongs_to :owner, record_type: :user
@@ -104,7 +115,7 @@ json_string = MovieSerializer.new(movie).serialized_json
 ```json
 {
   "data": {
-    "id": "232",
+    "id": "3",
     "type": "movie",
     "attributes": {
       "name": "test movie",
@@ -134,6 +145,65 @@ json_string = MovieSerializer.new(movie).serialized_json
 }
 
 ```
+
+### Key Transforms
+By default fast_jsonapi underscores the key names. It supports the same key transforms that are supported by AMS. Here is the syntax of specifying a key transform
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+  # Available options :camel, :camel_lower, :dash, :underscore(default)
+  set_key_transform :camel
+end
+```
+Here are examples of how these options transform the keys
+
+```ruby
+set_key_transform :camel # "some_key" => "SomeKey"
+set_key_transform :camel_lower # "some_key" => "someKey"
+set_key_transform :dash # "some_key" => "some-key"
+set_key_transform :underscore # "some_key" => "some_key"
+```
+
+### Attributes
+Attributes are defined in FastJsonapi using the `attributes` method.  This method is also aliased as `attribute`, which is useful when defining a single attribute.
+
+By default, attributes are read directly from the model property of the same name.  In this example, `name` is expected to be a property of the object being serialized:
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+  
+  attribute :name
+end
+```
+
+Custom attributes that must be serialized but do not exist on the model can be declared using Ruby block syntax:
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+  
+  attributes :name, :year
+  
+  attribute :name_with_year do |object|
+    "#{object.name} (#{object.year})"
+  end
+end
+```
+
+The block syntax can also be used to override the property on the object:
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+  
+  attribute :name do |object|
+    "#{object.name} Part 2"
+  end
+end
+```
+
 ### Compound Document
 
 Support for top-level included member through ` options[:include] `.
@@ -169,68 +239,66 @@ end
 Option | Purpose | Example
 ------------ | ------------- | -------------
 set_type | Type name of Object | ```set_type :movie ```
+set_id | ID of Object | ```set_id :owner_id ```
 cache_options | Hash to enable caching and set cache length | ```cache_options enabled: true, cache_length: 12.hours```
 id_method_name | Set custom method name to get ID of an object | ```has_many :locations, id_method_name: :place_ids ```
 object_method_name | Set custom method name to get related objects | ```has_many :locations, object_method_name: :places ```
 record_type | Set custom Object Type for a relationship | ```belongs_to :owner, record_type: :user```
 serializer | Set custom Serializer for a relationship | ```has_many :actors, serializer: :custom_actor```
 
+### Instrumentation
 
-## Contributing
+`fast_jsonapi` also has builtin [Skylight](https://www.skylight.io/) integration. To enable, add the following to an initializer:
 
-This gem is built using a gem building gem called [juwelier](https://github.com/flajann2/juwelier).
+```ruby
+require 'fast_jsonapi/instrumentation/skylight'
+```
 
-Beyond just editing source code, you’ll be interacting with the gem using rake a lot. To see all the tasks available with a brief description, you can run:
+Skylight relies on `ActiveSupport::Notifications` to track these two core methods. If you would like to use these notifications without using Skylight, simply require the instrumentation integration:
 
-```bash
-rake -T
+```ruby
+require 'fast_jsonapi/instrumentation'
 ```
 
-### Updating Project information
-You can update the project information of the gem by updating the [Rakefile](Rakefile). Then you need to generate a new gemspec:
+The two instrumented notifcations are supplied by these two constants:
+* `FastJsonapi::ObjectSerializer::SERIALIZABLE_HASH_NOTIFICATION`
+* `FastJsonapi::ObjectSerializer::SERIALIZED_JSON_NOTIFICATION`
 
-```bash
-rake gemspec
+It is also possible to instrument one method without the other by using one of the following require statements:
+
+```ruby
+require 'fast_jsonapi/instrumentation/serializable_hash'
+require 'fast_jsonapi/instrumentation/serialized_json'
 ```
 
+Same goes for the Skylight integration:
+```ruby
+require 'fast_jsonapi/instrumentation/skylight/normalizers/serializable_hash'
+require 'fast_jsonapi/instrumentation/skylight/normalizers/serialized_json'
+```
+
+## Contributing
+Please see [contribution check](https://github.com/Netflix/fast_jsonapi/blob/master/CONTRIBUTING.md) for more details on contributing
+
 ### Running Tests
-We use [RSpec](http://rspec.info/) for testing. We have unit tests, functional tests and performance tests. To run tests use the following rake task:
+We use [RSpec](http://rspec.info/) for testing. We have unit tests, functional tests and performance tests. To run tests use the following command:
 
 ```bash
-rake spec
+rspec
 ```
 
-### Installation
+To run tests without the performance tests (for quicker test runs):
 
 ```bash
-$ rake install
+rspec spec --tag ~performance:true
 ```
 
-The install rake task builds the gem and then installs it. You're all
-set if you're using [RVM](http://rvm.beginrescueend.com/), but you may
-need to run it with sudo if you have a system-installed Ruby:
-
-### Bumping Version
-
-It feels good to release code. Do it, do it often. But before that, bump
-the version. Then release it. There's a few ways to update the version:
+To run tests only performance tests:
 
 ```bash
-# version:write like before
-$ rake version:write MAJOR=0 MINOR=3 PATCH=0
-
-# bump just major, ie 0.1.0 -> 1.0.0
-$ rake version:bump:major
-
-# bump just minor, ie 0.1.0 -> 0.2.0
-$ rake version:bump:minor
-
-# bump just patch, ie 0.1.0 -> 0.1.1
-$ rake version:bump:patch
+rspec spec --tag performance:true
 ```
 
----
-
 ### We're Hiring!
 
 Join the Netflix Studio Engineering team and help us build gems like this!

data/lib/extensions/has_one.rb

@@ -1,16 +1,22 @@
-require 'active_record'
+# frozen_string_literal: true
 
-::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.to_s}_id
-        association(:#{name}).reader.id
-      end
-    CODE
+begin
+  require 'active_record'
+
+  ::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
+          association(:#{name}).reader.try(:id)
+        end
+      CODE
+    end
   end
+rescue LoadError
+  # active_record can't be loaded so we shouldn't try to monkey-patch it.
 end

data/lib/fast_jsonapi.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FastJsonapi
   require 'fast_jsonapi/object_serializer'
   require 'extensions/has_one'

data/lib/fast_jsonapi/instrumentation.rb

@@ -0,0 +1,2 @@
+require 'fast_jsonapi/instrumentation/serializable_hash'
+require 'fast_jsonapi/instrumentation/serialized_json'

data/lib/fast_jsonapi/instrumentation/serializable_hash.rb

@@ -0,0 +1,15 @@
+require 'active_support/notifications'
+
+module FastJsonapi
+  module ObjectSerializer
+
+    alias_method :serializable_hash_without_instrumentation, :serializable_hash
+
+    def serializable_hash
+      ActiveSupport::Notifications.instrument(SERIALIZABLE_HASH_NOTIFICATION, { name: self.class.name }) do
+        serializable_hash_without_instrumentation
+      end
+    end
+
+  end
+end

data/lib/fast_jsonapi/instrumentation/serialized_json.rb

@@ -0,0 +1,15 @@
+require 'active_support/notifications'
+
+module FastJsonapi
+  module ObjectSerializer
+
+    alias_method :serialized_json_without_instrumentation, :serialized_json
+
+    def serialized_json
+      ActiveSupport::Notifications.instrument(SERIALIZED_JSON_NOTIFICATION, { name: self.class.name }) do
+        serialized_json_without_instrumentation
+      end
+    end
+
+  end
+end

data/lib/fast_jsonapi/instrumentation/skylight.rb

@@ -0,0 +1,2 @@
+require 'fast_jsonapi/instrumentation/skylight/normalizers/serializable_hash'
+require 'fast_jsonapi/instrumentation/skylight/normalizers/serialized_json'

data/lib/fast_jsonapi/instrumentation/skylight/normalizers/serializable_hash.rb

@@ -0,0 +1,22 @@
+require 'skylight'
+require 'fast_jsonapi/instrumentation/serializable_hash'
+
+module FastJsonapi
+  module Instrumentation
+    module Skylight
+      module Normalizers
+        class SerializableHash < Skylight::Normalizers::Normalizer
+
+          register FastJsonapi::ObjectSerializer::SERIALIZABLE_HASH_NOTIFICATION
+
+          CAT = "view.#{FastJsonapi::ObjectSerializer::SERIALIZABLE_HASH_NOTIFICATION}".freeze
+
+          def normalize(trace, name, payload)
+            [ CAT, payload[:name], nil ]
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/fast_jsonapi/instrumentation/skylight/normalizers/serialized_json.rb

@@ -0,0 +1,22 @@
+require 'skylight'
+require 'fast_jsonapi/instrumentation/serializable_hash'
+
+module FastJsonapi
+  module Instrumentation
+    module Skylight
+      module Normalizers
+        class SerializedJson < Skylight::Normalizers::Normalizer
+
+          register FastJsonapi::ObjectSerializer::SERIALIZED_JSON_NOTIFICATION
+
+          CAT = "view.#{FastJsonapi::ObjectSerializer::SERIALIZED_JSON_NOTIFICATION}".freeze
+
+          def normalize(trace, name, payload)
+            [ CAT, payload[:name], nil ]
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/fast_jsonapi/multi_to_json.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Usage:
+#   class Movie
+#     def to_json(payload)
+#       FastJsonapi::MultiToJson.to_json(payload)
+#     end
+#   end
+module FastJsonapi
+  module MultiToJson
+    # Result object pattern is from https://johnnunemaker.com/resilience-in-ruby/
+    # e.g. https://github.com/github/github-ds/blob/fbda5389711edfb4c10b6c6bad19311dfcb1bac1/lib/github/result.rb
+    class Result
+      def initialize(*rescued_exceptions)
+        rescued_exceptions = [StandardError] if rescued_exceptions.empty?
+        @value = yield
+        @error = nil
+      rescue *rescued_exceptions => e
+        @error = e
+      end
+
+      def ok?
+        @error.nil?
+      end
+
+      def value!
+        if ok?
+          @value
+        else
+          raise @error
+        end
+      end
+
+      def rescue
+        return self if ok?
+        Result.new { yield(@error) }
+      end
+    end
+
+    def self.logger(device=nil)
+      return @logger = Logger.new(device) if device
+      @logger ||= Logger.new(IO::NULL)
+    end
+
+    # Encoder-compatible with default MultiJSON adapters and defaults
+    def self.to_json_method
+      encode_method = String.new(%(def _fast_to_json(object)\n ))
+      encode_method << Result.new(LoadError) {
+        require 'oj'
+        %(::Oj.dump(object, mode: :compat, time_format: :ruby, use_to_json: true))
+      }.rescue {
+        require 'yajl'
+        %(::Yajl::Encoder.encode(object))
+      }.rescue {
+        require 'jrjackson' unless defined?(::JrJackson)
+        %(::JrJackson::Json.dump(object))
+      }.rescue {
+        require 'json'
+        %(JSON.fast_generate(object, create_additions: false, quirks_mode: true))
+      }.rescue {
+        require 'gson'
+        %(::Gson::Encoder.new({}).encode(object))
+      }.rescue {
+        require 'active_support/json/encoding'
+        %(::ActiveSupport::JSON.encode(object))
+      }.rescue {
+        warn "No JSON encoder found. Falling back to `object.to_json`"
+        %(object.to_json)
+      }.value!
+      encode_method << "\nend"
+    end
+
+    def self.to_json(object)
+      _fast_to_json(object)
+    rescue NameError
+      define_to_json(FastJsonapi::MultiToJson)
+      _fast_to_json(object)
+    end
+
+    def self.define_to_json(receiver)
+      cl = caller_locations[0]
+      method_body = to_json_method
+      logger.debug { "Defining #{receiver}._fast_to_json as #{method_body.inspect}" }
+      receiver.instance_eval method_body, cl.absolute_path, cl.lineno
+    end
+
+    def self.reset_to_json!
+      undef :_fast_to_json if method_defined?(:_fast_to_json)
+      logger.debug { "Undefining #{receiver}._fast_to_json" }
+    end
+  end
+end