jsonapi_serializer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 21d607d922e598bf9866f8b829def185ff0f1f72
+  data.tar.gz: 5a80e053e723f7180018d582d2871426f713723f
+SHA512:
+  metadata.gz: 1c727a0615f60c522a665e6725e91b8a5770d8c959cf60f4ebb176da8db2d5322e2bb8faeb6eb239e106e3a9d71a4b7bcfcae2f4163b5c72c7274dab0cdd0820
+  data.tar.gz: 88855eeaf4da64bd790379072c66881512ca675c5d0137600314200df71795ce94cbb58072a83363407557ce533ab416964ceea647855ef3207e89813c66b805

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.13.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ivan.youroff@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jsonapi_serializer.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Ivan Youroff
+
+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,278 @@
+# Alt JSON API
+[![Build Status](https://travis-ci.org/youroff/jsonapi_serializer.svg?branch=master)](https://travis-ci.org/youroff/jsonapi_serializer)
+
+JSONApi serializer for Ruby objects. Inspired by [Fast JSON API](https://github.com/Netflix/fast_jsonapi).
+
+### Features
+
+  * Flexible mapping of attributes
+  * Custom computed attributes
+  * Custom ID-mapping
+  * Manual type setting
+  * Key and type transforms
+  * Polymorphic associations
+  * Sparse fieldsets support
+  * Nested includes (arbitrary depth)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'oj'
+gem 'jsonapi_serializer'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+## Usage
+
+### Record identification
+
+Records in JSONApi are identified by `type` and `id`. Normally these attributes can be derived implicitly from serializer name and id by default is just `object.id`. But you can redefine this behavior by using following DSL-methods:
+
+```ruby
+class MovieSerializer
+  include JsonapiSerializer::Base
+  # Without type hook, type of the record will be derived
+  # from the serializer name. In this case it would be :movie
+  type :film
+
+  # Using id hook, you can define how id would be retrieved.
+  # By default it will be taken from `id` attribute of the model.
+  id { |object| object.slug }
+
+  # You can also pass a symbol of attribute of the model that represents id
+  id :slug
+end
+```
+
+You can use public method `MovieSerializer.new.id_hash(record)` to get identification object (for example): `{id: 'matrix', type: :film}`
+
+### Types and keys transforms
+
+JSON API spec does not define how exactly `keys` and `types` should be formatted. For example, if you have a model defined in `BlockbusterMovie`, it can be represented by `blockbuster_movie`, `blockbuster-movie` or `blockbusterMovie`, or anything else that makes sense for your application. `JsonapiSerializer` allows for customization of this behavior, but only globally so far. If you use Ruby on Rails, you can put these settings in `config/initializers/jsonapi_serializer.rb`:
+
+```ruby
+# You can pass a symbol matching on of predefined transforms (:underscore, :dasherize or :camelize)
+# or implement your own logic, using block.
+# The following example will convert all attribute keys into dasherized-form:
+JsonapiSerializer.set_key_transform :dasherize
+
+# This will drop all non alphabet characters and upcase everything:
+JsonapiSerializer.set_key_transform do |str|
+  str.to_s.upcase.gsub(/[^A-Z]/, "").to_sym
+end
+
+# The same applies to type transform:
+JsonapiSerializer.set_type_transform :camelize
+
+# There is also still unresolved debate on how to treat namespaces in json-api.
+# For example, you have `Library::AuthorSerializer` and corresponding model.
+# Most of serializers would just drop namespace while trying to retrieve the type.
+# We can either drop it too, or replace `::` with defined separator:
+JsonapiSerializer.set_type_namespace_separator "-_-"
+
+# Or if you want to ignore (drop) it:
+JsonapiSerializer.set_type_namespace_separator :ignore
+
+# The default option is "_"
+# Bear in mind that only " " (space), "_" and "-" or any combination of these
+# are allowed as per json-api spec and attempt to set anything else
+# will cause an error.   
+```
+
+### Attributes configuration
+
+Alt JSON API supports direct mapping of attributes, as well as remapping and custom attributes that are generated by lambda.
+
+```ruby
+class MovieSerializer
+  include JsonapiSerializer::Base
+  # attributes accepts names of attributes
+  # and/or pairs (hash) of attributes of serialized model
+  # pointing to attributes of target model
+  attributes :name, release_year: :year
+
+  # attribute accepts a block with serializable record as parameter
+  attribute :rating do |movie|
+    "%.2g" % (movie.rating / 10.0)
+  end
+
+  # you can call class methods of serializer to split complex calculations
+  attribute :comlex_attribute do |movie|
+    do_heavy_calc(movie)
+  end
+
+  def self.do_heavy_calc(movie)
+    #...
+  end
+end
+```
+
+In this example, serializer will access `record.name` and `record.year` to fill attributes `name` and `release_year` respectively. Rating block will convert 95 into 9.5 and make it string.
+
+### Relationships configuration
+
+In order to define relationships, you can use `belongs_to` and `has_many` DSL methods. They accept options `serializer` and `from`. By default, serializer will try to guess relationship serializer by the name of relation. In case of `:director` relation, it would try to use `DirectorSerializer` and crash since it's not defined. Use `serializer` parameter to set serializer explicitly. Option `from` is used to point at the attribute of the model that actually returns the relation object(s) if it's different.
+
+```ruby
+class MovieSerializer
+  include JsonapiSerializer::Base
+  belongs_to :director, serializer: PersonSerializer
+  has_many :actors, from: :cast
+end
+```
+
+From the perspective of serializer, there is no distinction between `belongs_to` and `has_one` relations. Current implementation does not use ActiveRecord's specifics, such as `object.{relation}_id` or `object.{relation}_ids` to access relation ids, which means you will have to preload these relations to avoid DB-calls during serialization. This is done deliberately for two reasons:
+
+  * Identifier of serialized object (`id`) can be remapped to another attribute, for example `slug`.
+  * This library is intended to be ORM-agnostic, you can easily use it to serialize some graph structures.
+
+### Polymorphic models and relationships
+
+There are two kinds of polymorphism that `jsonapi_serializer` supports. First is polymorphic model (STI models in ActiveRecord), where most attributes are shared, but children have different types. Ultimately it is still one kind of entity: think of `Vehicle` base class inherited by `Car`, `Truck` and `Motorcycle`. Second kind is polymorphic relationship, where one relationship can contain entirely different models. Let's say you have `Post` and `Product`, and both can have comments, hence from the perspective of individual comment it belongs to `Commentable`. Even though `Post` and `Model` can share some attributes, their serializers will be used mostly along from comments.
+
+These types of serializers share most of the implementation implemented similarly, they share most of the logic and both need a `resolver`, which is implicitly defined as a lambda, that applies `JsonapiSerializer.type_transform` to the record class name.
+
+#### Polymorphic Models
+
+To create a serializer for STI models:
+
+```ruby
+class VehicleSerializer
+  include JsonapiSerializer::Polymorphic
+  attributes :name, :num_of_wheels
+end
+
+class CarSerializer < VehicleSerializer
+  attributes :trunk_volume
+end
+
+class TruckSerializer < VehicleSerializer
+  attributes :bed_size
+end
+
+class MotorcycleSerializer < VehicleSerializer
+end
+```
+
+In this case common attributes will be inherited from `VehicleSerializer` and children will be registered automatically. Optionally you can add a `resolver` to the parent:
+
+```ruby
+resolver do |model|
+  case model
+  when Motorcycle then :motorcycle
+  when Truck then :truck
+  when Car then :car
+  end
+end
+```
+
+But usually you don't need to, the implicit resolver does the same for you. To specify the rules of type transform and how the namespace is treated, read `Types and keys transforms` section.
+
+#### Polymorphic Relationships
+
+With polymorphic relationships we usually have several independent serializers for models that can appear in one relationships. In order to teach polymorphic serializer to use them, we just need to register these classes using `polymorphic_for`.  
+
+```ruby
+class CommentableSerializer
+  include JsonapiSerializer::Polymorphic
+  # Here we register standalone serializers
+  # as targets for our polymorphic relationship.
+  # Be aware that in this case attributes will have no effect.
+  polymorphic_for PostSerializer, ProductSerializer
+
+  # You can set up a resolver here as well!
+end
+
+class PostSerializer
+  include JsonapiSerializer::Base
+  attributes :title, :body
+end
+
+class ProductSerializer
+  include JsonapiSerializer::Base
+  attributes :sku, :name, :description
+end
+```
+
+Then use it exactly the same as regular serializers. But keep in mind that you cannot randomly inherit serializer classes, an attempt to inherit regular serializer's class will cause an error.
+
+### Initialization and serialization
+
+Once serializers are defined, you can instantiate them with several options. Currently supported options are: `fields` and `include`.
+
+`fields` must be a hash, where keys represent record types and values are list of attributes and relationships of the corresponding type that will be present in serialized object. If some type is missing, that means all attributes and relationships defined in serializer will be serialized. In case of `polymorphic` serializer, you can supply shared fields under polymorphic type. **_There is a caveat, though: if you define a fieldset for a parent polymorphic class and omit fieldsets for subclasses it will be considered that you did not want any of attributes and relationships defined in subclass to be serialized._** It works the same fashion for polymorphic relationships, so if you want only `title` from `Post` and `name` from `Product`, you can supply `{commentable: ["title", "name"]}` as a `fields` parameter for `CommentableSerializer`.
+
+`include` defines an arbitrary depth tree of included relationships in a similar way as ActiveRecord's `includes`. Bear in mind that `fields` has precedence, which means that if some relationship is missing in fields, it will not be included either.  
+
+```ruby
+options = {}
+
+# We're omitting fieldset for ItemSerializer here,
+# only attributes/relationships defined in CommentableSerializer
+# will be serialized for Item objects
+options[:fields] = {
+  commentable: [:title],
+  post: [:body]
+}
+
+# You can define arbitrary nesting here
+options[:include] = [:tags, author: :some_authors_relation]
+
+serializer = CommentableSerializer.new(options)
+```
+
+Then you can just reuse serializer's instance to serialize appropriate datasets, while supplying optional parameters, such as meta object.
+
+```ruby
+serializer.serialazable_hash(movies, meta: meta)
+# or
+serializer.serialized_json(movies, meta: meta)
+```
+
+## Performance
+
+By running `bin/benchmark` you can launch performance test locally, however numbers are fluctuating widely. The example output is as follows:
+
+### Base case
+
+|       Adapters       |  10 hash/json (ms)   |  100 hash/json (ms)  | 1000 hash/json (ms)  | 10000 hash/json (ms) |
+| -------------------- |:--------------------:|:--------------------:|:--------------------:|:--------------------:|
+|    JsonapiSerializerTest    |     0.36 / 1.17      |     1.55 / 1.98      |    13.74 / 20.18     |   156.31 / 208.86    |
+|   FastJsonapiTest    |     0.16 / 0.19      |     1.14 / 1.75      |    11.86 / 18.13     |   124.13 / 176.97    |
+
+### With includes
+
+|       Adapters       |  10 hash/json (ms)   |  100 hash/json (ms)  | 1000 hash/json (ms)  | 10000 hash/json (ms) |
+| -------------------- |:--------------------:|:--------------------:|:--------------------:|:--------------------:|
+|    JsonapiSerializerTest    |     0.51 / 0.46      |     2.05 / 2.50      |    15.28 / 21.59     |   159.89 / 214.49    |
+|   FastJsonapiTest    |     0.26 / 0.25      |     2.01 / 2.47      |    15.54 / 20.11     |   154.82 / 211.48    |
+
+Performance tests do not include any advanced features, such as fieldsets, nested includes or polymorphic serializers, and were mostly intended to make sure that adding these features did not make serializer slower (or at least significantly slower), but there are models prepared to extend these tests. PRs are welcome.
+
+## Roadmap
+
+  * Removing as many dependencies as possible. Opt-in JSON-library. Possibly removing dependency on `active_support`.
+  * Creating jsonapi_serializer_rails to make rails integration simple
+  * ...
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jsonapi_serializer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/benchmark

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "jsonapi_serializer"
+require "./perf/runner"
+require "./perf/jsonapi_serializer_test"
+require "./perf/fast_jsonapi_test"
+GC.disable
+
+runner = Runner.new(10_000)
+runner.set_modules(JsonapiSerializerTest, FastJsonapiTest)
+runner.set_tests(:base, :with_included)
+runner.set_takes(10, 100, 1000, 10_000)
+runner.run
+
+print "\n"
+print "### Base case\n"
+print "\n"
+runner.print_table(:base)
+print "\n"
+print "### With includes\n"
+print "\n"
+runner.print_table(:with_included)

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "jsonapi_serializer"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start