Skip to content
A JSON Serializer for Ruby Objects
Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmark
lib
test
.codeclimate.yml
.editorconfig
.gitignore
.rubocop.yml
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
jserializer.gemspec

README.md

JSerializer

Build Status Code Climate

JSerializer is a JSON Serializer for Ruby objects. It is designed to be a drop-in replacement of Active Model Serializer (target version: 0.8) with better performance.

JSerializer does not rely on Rails or Active Model or Active Support, which makes it easier to be integrated into general Ruby projects.

Installation

Add this line to your application's Gemfile:

gem 'jserializer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jserializer

Usage

Define a Model

Person = Struct.new(:id, :first_name, :last_name, :age, :gender, :country)

Create a Serializer

class PersonSerializer < Jserializer::Base
  root :user
  attributes :full_name, :age, :gender
  attribute :country, key: :country_code

  def full_name
    "#{object.first_name} #{object.last_name}"
  end

  def gender
    object.gender == 'm' ? 'Male' : 'Female'
  end

  def include_age?
    object.age >= 18
  end
end

Generate JSON

person = Person.new(1, 'John', 'Doe', 16, 'm', 'US')
serializer = PersonSerializer.new(person)

# generates a Hash without root key
# => {:full_name=>"John Doe", :gender=>"Male", :country_code=>"US"}
serializer.serializable_hash

# generates a Hash with root key
# => {:user=>{:full_name=>"John Doe", :gender=>"Male", :country_code=>"US"}}
serializer.as_json

# generates JSON => {"user":{"full_name":"John Doe","gender":"Male","country_code":"US"}}
serializer.to_json

Generate JSON Collection

persons = 2.times.map{|i| Person.new(i, 'Person', "#{i}", 17 + i, 'm', 'US') }
serializer = PersonSerializer.new(persons, is_collection: true)
serializer.to_json

You will get:

{
  "user":[
    {
      "full_name":"Person 0",
      "gender":"Male",
      "country_code":"US"
    },
    {
      "full_name":"Person 1",
      "age":18,
      "gender":"Male",
      "country_code":"US"
    }
  ]
}

Bring Your Own JSON Encoder

Our to_json method uses standard JSON module to generate JSON string. There are many JSON encode backend there, and they offer different customization options. Besides, you can use MultiJson to switch between different backends.

You are welcome to bring your own solution here. To do that, simply override the to_json method

class ApplicationSerializer < Jserializer::Base
  def to_json(*)
    # use ActiveSupport in Rails as a delegator
    ActiveSupport::JSON.encode(as_json)
    # use oj:
    # Oj.dump(as_json, mode: :compat, use_to_json: true)
  end
end

Then the rest of your serializers can inherit from ApplicationSerializer and start to use your preferred encoder.

Serializer Class Definition Options

Method Options Description
root N/A Set the root key of the generated JSON
attributes N/A Define a list of fields separated by , to be exposed from a Ruby object
attribute :key - The name in the JSON output Similar to attributes but for one field
has_many :serializer
:key
:embed
:embed_key
Include a collection of objects with has many association
has_one Same as has_many Include a object with has one association
embed :ids
:objects
Determine if only include IDs of the associations

Example

This example shows you where to apply the above methods

class PostSerializer < Jserializer::Base
  root :article
  embed :ids
  attributes :id, :title, :content
  attribute :writer, key: :written_by
  has_many :comments, serializer: CommentSerializer, embed: :objects
  has_one :author, serializer: AuthorSerializer, embed_key: :id
end

For associations, Jserializer uses the following ways to retrieve data:

Type Method Example
has_many collection_singular_ids posts => post_ids
has_one association.id account => account.id

Initialization Options for Serializer Instance

Options Description
root Set the root key of the generated JSON, set it to false to disable
meta Meta information to be included in the JSON output
meta_key The key name of the meta information, the default is :meta
is_collection Whether the given object is a collection or single object
only An array of attributes to be included in the JSON output
except An array of attributes to be excluded in the JSON output
current_user Use for determine the authorization scope

Example

PostSerializer.new(posts,
                   root: :post,
                   meta: { page: 1, total: 100},
                   is_collection: true,
                   only: [:title, :content])

You can enable/disable root when initializing a serializer instance:

PostSerializer.new(post, root: false)

Or when calling as_json method:

# here the root option only accept a boolean value
# you cannot rename root at this point
PostSerializer.new(post).as_json(root: false)

You can always get the Hash representation without root and meta information by calling serializable_hash

PostSerializer.new(post).serializable_hash

Collection

The active_serializer_model gem includes the ArraySerializer class to handle collections. There are a lot of magics happening underneath when you pass a collection object into render json: @xxx, to allow ArraySerializer gets triggered automatically.

Unlike active_serializer_model, there is no separate serializer class for array. To serialize a collection, you need to set is_collection: true when initializing a new serializer

serializer = PostSerializer.new(posts, is_collection: true)
serializer.serializable_hash # or serializer.as_json to include root

You can also call serializable_collection method directly which will ignore the is_collection option

serializer = PostSerializer.new(posts)
serializer.serializable_collection

Compatibility & Migration

Currently, this gem is not compatible with active_serializer_model if you:

  • have include_xxx? as private method
  • override the instance method attributes
  • override any internal method _xxx (e.g. _serializable_array)
  • expect serializer to automatically include a root for you
  • expect serializer figures out if the object is a collection automatically

Since we try to reuse serializer instances to avoid unnecessary object creations, make sure there is no things like ||= in the serializer class. Or you can override reset method to clean things out

class MySerializer < Jserializer::Base
  ... ...
  def reset(object)
    @my_cached_stuff = nil
    ... ...
    super
  end

active_model_serializer method

This gem will try to find and use the serializer class defined by active_model_serializer method in a model, if you don't specify serializer explicitly

class Post < ActiveRecord::Base
  def active_model_serializer
    MyPostSerializer
  end
end

Use in Rails Action Controller

Active Model Serializer overrides render :json in ActionController::Serialization, which is convenient. But it touches Rails internal methods which could bring compatibility issues when upgrading Rails.

This gem does not provide such feature, but you can easily achieve it in application layer, for example, create a wrapper method for render:

class ApplicationController < ActionController::Base
  # ... ...
  def render_json(resource, options = {})
    if options.key?(:serializer)
      serializer = options.delete(:serializer)
    elsif options.key?(:each_serializer)
      serializer = options.delete(:each_serializer)
      options[:is_collection] = true
    end

    if !serializer && resource.respond_to?(:active_model_serializer)
      serializer = resource.active_model_serializer
    end

    if serializer
      options[:scope] = current_user
      options[:json] = serializer.new(resource, options)
    else
      options[:json] = resource
    end
    render options
  end
end

Then you can use this render_json method whenever you need to call render json: resource ... in your controllers. And this is probably a good way to migrate gradually.

Caching

This gem does not plan to implement the cache feature.

Benchmark

See here

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/distil/jserializer.

You can’t perform that action at this time.