Jb

A simpler and faster Jbuilder alternative.

Installation

Add this line to your application's Gemfile:

gem 'jb'

And bundle.

Usage

Put a template file named *.jb in your Rails app's app/views/* directory, and render it.

Features

• No original builder syntax that you have to learn
• No method_missing calls
• render_partial with :collection option actually renders the collection (unlike Jbuilder)

Syntax

A .jb template should contain Ruby code that returns any Ruby Object that responds_to to_json (generally Hash or Array). Then the return value will be to_jsoned to a JSON String.

Examples

Let's start with a very simple one. Just write a Ruby Hash as a template:

{language: 'Ruby', author: {name: 'Matz'}}

This renders the following JSON text:

{"language": "Ruby", "author": {"name": "Matz"}}

Note that modern Ruby Hash syntax pretty much looks alike JSON syntax. It's super-straight forward. Who needs a DSL to do this?

Next one is a little bit advanced usage. The template doesn't have to be a single literal but can be any code that returns a Hash object:

# app/views/messages/show.json.jb

json = {
  content: format_content(@message.content),
  created_at: @message.created_at,
  updated_at: @message.updated_at,
  author: {
    name: @message.creator.name.familiar,
    email_address: @message.creator.email_address_with_name,
    url: url_for(@message.creator, format: :json)
  }
}

if current_user.admin?
  json[:visitors] = calculate_visitors(@message)
end

json[:comments] = @message.comments.map do |comment|
  {
    content: comment.content,
    created_at: comment.created_at
  }
end

json[:attachments] = @message.attachments.map do |attachment|
  {
    filename: attachment.filename,
    url: url_for(attachment)
  }
end

json

This will build the following structure:

{
  "content": "10x JSON",
  "created_at": "2016-06-29T20:45:28-05:00",
  "updated_at": "2016-06-29T20:45:28-05:00",

  "author": {
    "name": "Yukihiro Matz",
    "email_address": "[email protected]",
    "url": "http://example.com/users/1-matz.json"
  },

  "visitors": 1326,

  "comments": [
    { "content": "Hello, world!", "created_at": "2016-06-29T20:45:28-05:00" },
    { "content": "<script>alert('Hello, world!');</script>", "created_at": "2016-06-29T20:47:28-05:00" }
  ],

  "attachments": [
    { "filename": "sushi.png", "url": "http://example.com/downloads/sushi.png" },
    { "filename": "sake.jpg", "url": "http://example.com/downloads/sake.jpg" }
  ]
}

If you want to define attribute and structure names dynamically, of course you still can do this with a Ruby Hash literal.

# model_name, column_name = :author, :name

{model_name => {column_name => 'Matz'}}

# => {"author": {"name": "Matz"}}

Top level arrays can be handled directly. Useful for index and other collection actions. And you know, Ruby is such a powerful language for manipulating collections:

# @comments = @post.comments

@comments.reject {|c| c.marked_as_spam_by?(current_user) }.map do |comment|
  {
    body: comment.body,
    author: {
      first_name: comment.author.first_name,
      last_name: comment.author.last_name
    }
  }
end

# => [{"body": "🍣 is omakase...", "author": {"first_name": "Yukihiro", "last_name": "Matz"}}]

Jb has no special DSL method for extracting attributes from array directly, but you can do that with Ruby.

# @people = People.all

@people.map {|p| {id: p.id, name: p.name}}

# => [{"id": 1, "name": "Matz"}, {"id": 2, "name": "Nobu"}]

You can use Jb directly as an Action View template language. When required in Rails, you can create views ala show.json.jb. You'll notice in the following example that the .jb template doesn't have to be one big Ruby Hash literal as a whole but it can be any Ruby code that finally returns a Hash instance.

# Any helpers available to views are available in the template
json = {
  content: format_content(@message.content),
  created_at: @message.created_at,
  updated_at: @message.updated_at,

  author: {
    name: @message.creator.name.familiar,
    email_address: @message.creator.email_address_with_name,
    url: url_for(@message.creator, format: :json)
  }
}

if current_user.admin?
  json[:visitors] = calculate_visitors(@message)
end

json

You can use partials as well. The following will render the file views/comments/_comments.json.jb, and set a local variable comments with all this message's comments, which you can use inside the partial.

render 'comments/comments', comments: @message.comments

It's also possible to render collections of partials:

render partial: 'posts/post', collection: @posts, as: :post

NOTE: Don't use render @post.comments because if the collection is empty, render will return nil instead of an empty array.

You can pass any objects into partial templates with or without :locals option.

render 'sub_template', locals: {user: user}

# or

render 'sub_template', user: user

You can of course include Ruby nil as a Hash value if you want. That would become null in the JSON.

You can use Hash#compact/! method to prevent including null values in the output:

{foo: nil, bar: 'bar'}.compact

# => {"bar": "bar"}

If you want to cache a template fragment, just directly call Rails.cache.fetch:

Rails.cache.fetch ['v1', @person], expires_in: 10.minutes do
  {name: @person.name, age: @person.age}
end

ActionController::API

ActionController::API doesn't render view templates by default. So, in order to render .jb templates from API controllers, Jb includes ActionView::Rendering, ActionController::Helpers, and ActionController::ImplicitRender into ActionController::API (just like Jbuilder does).

Note that this changes the behavior of API controller actions that don't explicitly call render. Instead of always responding with 204 No Content, such an action now renders its template if one exists, raises ActionController::UnknownFormat if templates exist only for other formats, and raises ActionController::MissingExactTemplate for a GET request for HTML from a browser with no template.

The Generator

Jb extends the default Rails scaffold generator and adds some .jb templates. If you don't need them, please configure like so.

Rails.application.config.generators.jb false

Why is Jb fast?

Jbuilder's partial + :collection internally calls array! method inside which _render_partial is called per each element of the given collection, and then it falls back to the view_context's render method.

So, for example if the collection has 100 elements, Jbuilder's render partial: performs render method 100 times, and so it calls find_template method (which is known as one of the heaviest parts of Action View) 100 times.

OTOH, Jb simply calls ActionView::PartialRenderer's render which is cleverly implemented to find_template only once beforehand, then pass each element to that template.

Benchmarks

Here're the results of a benchmark (which you can find here in this repo) rendering a collection to JSON.

RAILS_ENV=development

% ./bin/benchmark.sh
* Rendering 10 partials via render_partial
Warming up --------------------------------------
                  jb    15.000  i/100ms
            jbuilder     8.000  i/100ms
Calculating -------------------------------------
                  jb    156.375  (± 7.0%) i/s -    780.000  in   5.016581s
            jbuilder     87.890  (± 6.8%) i/s -    440.000  in   5.037225s

Comparison:
                  jb:      156.4 i/s
            jbuilder:       87.9 i/s - 1.78x slower


* Rendering 100 partials via render_partial
Warming up --------------------------------------
                  jb    13.000  i/100ms
            jbuilder     1.000  i/100ms
Calculating -------------------------------------
                  jb    121.187  (±14.0%) i/s -    598.000  in   5.049667s
            jbuilder     11.478  (±26.1%) i/s -     54.000  in   5.061996s

Comparison:
                  jb:      121.2 i/s
            jbuilder:       11.5 i/s - 10.56x slower


* Rendering 1000 partials via render_partial
Warming up --------------------------------------
                  jb     4.000  i/100ms
            jbuilder     1.000  i/100ms
Calculating -------------------------------------
                  jb     51.472  (± 7.8%) i/s -    256.000  in   5.006584s
            jbuilder      1.510  (± 0.0%) i/s -      8.000  in   5.383548s

Comparison:
                  jb:       51.5 i/s
            jbuilder:        1.5 i/s - 34.08x slower

RAILS_ENV=production

% RAILS_ENV=production ./bin/benchmark.sh
* Rendering 10 partials via render_partial
Warming up --------------------------------------
                  jb   123.000  i/100ms
            jbuilder    41.000  i/100ms
Calculating -------------------------------------
                  jb      1.406k (± 4.2%) i/s -      7.134k in   5.084030s
            jbuilder    418.360  (± 9.8%) i/s -      2.091k in   5.043381s

Comparison:
                  jb:     1405.8 i/s
            jbuilder:      418.4 i/s - 3.36x slower


* Rendering 100 partials via render_partial
Warming up --------------------------------------
                  jb    37.000  i/100ms
            jbuilder     5.000  i/100ms
Calculating -------------------------------------
                  jb    383.082  (± 8.4%) i/s -      1.924k in   5.061973s
            jbuilder     49.914  (± 8.0%) i/s -    250.000  in   5.040364s

Comparison:
                  jb:      383.1 i/s
            jbuilder:       49.9 i/s - 7.67x slower


* Rendering 1000 partials via render_partial
Warming up --------------------------------------
                  jb     4.000  i/100ms
            jbuilder     1.000  i/100ms
Calculating -------------------------------------
                  jb     43.017  (± 9.3%) i/s -    216.000  in   5.080482s
            jbuilder      4.604  (±21.7%) i/s -     23.000  in   5.082100s

Comparison:
                  jb:       43.0 i/s
            jbuilder:        4.6 i/s - 9.34x slower

Summary

According to the benchmark results, you can expect 2-30x performance improvement in development env, and 3-10x performance improvement in production env.

Contributing

Pull requests are welcome on GitHub at https://github.com/amatsuda/jb.

License

The gem is available as open source under the terms of the MIT License.