merging with release-1.1

Netflix · Mar 18, 2018 · cf86cd8 · cf86cd8
2 parents 7e59446 + c40354e
commit cf86cd8
Show file tree

Hide file tree

Showing 40 changed files with 1,774 additions and 520 deletions.
diff --git a/.gitignore b/.gitignore
@@ -16,18 +16,14 @@ doc
 # For MacOS:
 .DS_Store
 
-# juwelier generated
-pkg
-
 # For MacOS:
 .DS_Store
 
 # For TextMate
 #*.tmproj
 #tmtags
 
-# For vim:
-#*.swp
+*.swp
 
 # For redcar:
 #.redcar
@@ -37,3 +33,9 @@ pkg
 
 # For the gem
 test.db
+
+# For those using rbenv
+.ruby-version
+
+# For those who install gems locally to a vendor dir
+/vendor
diff --git a/.travis.yml b/.travis.yml
@@ -1,5 +1,8 @@
 language: ruby
 rvm:
-  - 2.3.1
+  - 2.2.9
+  - 2.3.6
+  - 2.4.3
+  - 2.5.0
 script:
-  - bundle exec rake spec
+  - bundle exec rspec
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,11 +1,8 @@
 PATH
   remote: .
   specs:
-    fast_jsonapi (1.0.17)
-      activerecord (~> 5.0)
-      activesupport (~> 5.0)
-      multi_json (~> 1.12)
-      oj (~> 3.3)
+    fast_jsonapi (1.1.0)
+      activesupport (>= 4.2)
 
 GEM
   remote: https://rubygems.org/
@@ -39,8 +36,6 @@ GEM
       i18n (~> 0.7)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
     arel (8.0.0)
     benchmark-perf (0.2.1)
     builder (3.2.3)
@@ -49,55 +44,27 @@ GEM
       activesupport
     concurrent-ruby (1.0.5)
     crass (1.0.3)
-    descendants_tracker (0.0.4)
-      thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.3)
-    docile (1.1.5)
     erubi (1.7.0)
-    faraday (0.12.2)
-      multipart-post (>= 1.2, < 3)
-    git (1.3.0)
-    github_api (0.18.2)
-      addressable (~> 2.4)
-      descendants_tracker (~> 0.0.4)
-      faraday (~> 0.8)
-      hashie (~> 3.5, >= 3.5.2)
-      oauth2 (~> 1.0)
-    hashie (3.5.6)
-    highline (1.7.10)
     i18n (0.9.1)
       concurrent-ruby (~> 1.0)
-    json (1.8.6)
+    jsonapi-deserializable (0.2.0)
+    jsonapi-rb (0.5.0)
+      jsonapi-deserializable (~> 0.2.0)
+      jsonapi-serializable (~> 0.3.0)
     jsonapi-renderer (0.2.0)
-    juwelier (2.1.3)
-      builder
-      bundler (>= 1.13)
-      git (>= 1.2.5)
-      github_api
-      highline (>= 1.6.15)
-      nokogiri (>= 1.5.10)
-      rake
-      rdoc
-      semver
-    jwt (1.5.6)
+    jsonapi-serializable (0.3.0)
+      jsonapi-renderer (~> 0.2.0)
+    jsonapi-serializers (1.0.0)
+      activesupport
     loofah (2.1.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mini_portile2 (2.3.0)
     minitest (5.10.3)
-    multi_json (1.12.2)
-    multi_xml (0.6.0)
-    multipart-post (2.0.0)
     nokogiri (1.8.1)
       mini_portile2 (~> 2.3.0)
-    oauth2 (1.4.0)
-      faraday (>= 0.8, < 0.13)
-      jwt (~> 1.0)
-      multi_json (~> 1.3)
-      multi_xml (~> 0.5)
-      rack (>= 1.2, < 3)
     oj (3.4.0)
-    public_suffix (3.0.1)
     rack (2.0.3)
     rack-test (0.8.2)
       rack (>= 1.0, < 3)
@@ -106,9 +73,6 @@ GEM
       nokogiri (>= 1.6)
     rails-html-sanitizer (1.0.3)
       loofah (~> 2.0)
-    rake (12.3.0)
-    rdoc (3.12.2)
-      json (~> 1.4)
     rspec (3.5.0)
       rspec-core (~> 3.5.0)
       rspec-expectations (~> 3.5.0)
@@ -125,12 +89,6 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
-    semver (1.0.1)
-    simplecov (0.15.1)
-      docile (~> 1.1.0)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
     skylight (1.5.0)
       activesupport (>= 3.0.0)
     sqlite3 (1.3.13)
@@ -142,17 +100,18 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  active_model_serializers (~> 0.10.4)
+  active_model_serializers (~> 0.10.7)
+  activerecord (>= 4.2)
   bundler (~> 1.0)
   byebug
   fast_jsonapi!
-  juwelier (~> 2.1.0)
-  rdoc (~> 3.12)
+  jsonapi-rb (~> 0.5.0)
+  jsonapi-serializers (~> 1.0.0)
+  oj (~> 3.3)
   rspec (~> 3.5.0)
   rspec-benchmark (~> 0.3.0)
-  simplecov
   skylight (~> 1.3)
   sqlite3 (~> 1.3)
 
 BUNDLED WITH
-   1.16.0
+   1.16.1
diff --git a/README.md b/README.md
@@ -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,6 +56,14 @@ $ 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
@@ -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,69 +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:
 
-Please follow the steps on [contribution check](https://github.com/Netflix/fast_jsonapi/blob/master/CONTRIBUTING.md).
-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!