jb 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a9a695209a26ce29bec15c3875242b2681f33df
-  data.tar.gz: 2b5a75df2740953a69f6a6e8c2703e4b2bdf1f13
+  metadata.gz: 7cc429668499e99d5acd8fc816c5edbecd363d57
+  data.tar.gz: debb9265b363fa660ef632fa1fde79c76f0a1065
 SHA512:
-  metadata.gz: 2ebedcd7cc5498c5143ad74121dbd7ddfa5cf4fcb8f0089a1d26b7b92fe3b01d6c41399bf73c9b971f9535569344ad0200bf1c12b40d02667a1419ce7b168f21
-  data.tar.gz: 3beb62bd3a5024b9fb0af6f7f948a712bc161f5fe509aed130f24e38bfe4aafd035586382c895646163a5e9133f17dd23c71ee37504c7ea9ef3db5614fb25826
+  metadata.gz: 0f24ea0311ab49e1bdc5559f04e9feabc829643c4a9f1bdf9714084bb903589d81ea266ef8c269adb06c10ba27b9b7b255eae9a1e3366116e475f8f9ac212d9f
+  data.tar.gz: 30a0eb11d629dae406df1407de317cad6aad8bd59119cbd926f1041342483f3dad4a5a3735c8cf8433c2693aa506c37955f874cbf486910fba51a587fce271c7

data/Gemfile

@@ -2,3 +2,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in jb.gemspec
 gemspec
+
+# For benchmarking
+gem 'jbuilder'
+gem 'benchmark-ips'
+gem 'action_args'

data/README.md

@@ -16,8 +16,7 @@ And bundle.
 
 ## Usage
 
-Write a template that contains a Ruby code that returns a Ruby Hash / Array object.
-Then the object will be `to_json`ed to a JSON String.
+Put a template file named `*.jb` in your Rails app's `app/views/*` directory, and render it.
 
 
 ## Features
@@ -27,6 +26,299 @@ Then the object will be `to_json`ed to a JSON String.
 * `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_json`ed to a JSON String.
+
+
+## Examples
+
+``` ruby
+# 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] = {
+  content: @message.comments.content,
+  created_at: @message.comments.created_at
+}
+
+json[:attachments] = @message.attachments.map do |attachment|
+  filename: attachment.filename,
+  url: url_for(attachment)
+end
+
+json
+```
+
+This will build the following structure:
+
+``` javascript
+{
+  "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": "matz@example.com",
+    "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" }
+  ]
+}
+```
+
+To define attribute and structure names dynamically, just use Ruby Hash.
+Note that modern Ruby Hash syntax pretty much looks alike JSON syntax.
+It's super-straight forward. Who needs a DSL to do this?
+
+``` ruby
+{author: {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:
+
+``` ruby
+# @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.
+
+``` 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.
+
+``` ruby
+# 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.
+
+```ruby
+render 'comments/comments', comments: @message.comments
+```
+
+It's also possible to render collections of partials:
+
+```ruby
+render partial: 'posts/post', collection: @posts, as: :post
+
+# or
+
+render @post.comments
+```
+
+You can pass any objects into partial templates with or without `:locals` option.
+
+```ruby
+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.
+
+To prevent Jb from including null values in the output, Active Support provides `Hash#compact!` method for you:
+
+```ruby
+{foo: nil, bar: 'bar'}.compact
+
+# => {"bar": "bar"}
+```
+
+If you want to cache a template fragment, just directly call `Rails.cache.fetch`:
+
+```ruby
+Rails.cache.fetch ['v1', @person], expires_in: 10.minutes do
+  {name: @person.name, age: @person.age}
+end
+```
+
+
+## The Generator
+Jb extends the default Rails scaffold generator and adds some .jb templates.
+If you don't need them, please configure like so.
+
+```ruby
+Rails.application.config.generators.jb false
+```
+
+
+## Why is Jb fast?
+
+Jbuilder's `partial` + `:collection` [internally calls `array!` method](https://github.com/rails/jbuilder/blob/83a682aeebde96c6ef02ce742c0b97dc393f5e22/lib/jbuilder/jbuilder_template.rb#L85-L95)
+inside which [`_render_partial` is called per each element of the given collection](https://github.com/rails/jbuilder/blob/83a682aeebde96c6ef02ce742c0b97dc393f5e22/lib/jbuilder/jbuilder_template.rb#L93),
+and then it [falls back to the `view_context`'s `render` method](https://github.com/rails/jbuilder/blob/83a682aeebde96c6ef02ce742c0b97dc393f5e22/lib/jbuilder/jbuilder_template.rb#L100-L103).
+
+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`](https://github.com/rails/rails/blob/49a881e0db1ef64fcbae2b7ddccfd5ccea26ae01/actionview/lib/action_view/renderer/partial_renderer.rb#L423-L443) which is cleverly implmented to `find_template` only once beforehand, then pass each element to that template.
+
+
+## Bencharks
+Here're the results of a benchmark (which you can find [here](https://github.com/amatsuda/jb/blob/master/test/dummy_app/app/controllers/benchmarks_controller.rb) 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.

data/bin/benchmark.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+cd $(dirname "$0")/../test/dummy_app
+
+BUNDLE_GEMFILE=../../Gemfile bundle e rails r bin/bench.rb

data/lib/generators/rails/jb_generator.rb

@@ -0,0 +1,34 @@
+require 'rails/generators/named_base'
+require 'rails/generators/resource_helpers'
+
+module Rails
+  module Generators
+    class JbGenerator < NamedBase # :nodoc:
+      include Rails::Generators::ResourceHelpers
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      argument :attributes, type: :array, default: [], banner: 'field:type field:type'
+
+      def create_root_folder
+        path = File.join('app/views', controller_file_path)
+        empty_directory path unless File.directory?(path)
+      end
+
+      def copy_view_files
+        template 'index.json.jb', File.join('app/views', controller_file_path, 'index.json.jb')
+        template 'show.json.jb', File.join('app/views', controller_file_path, 'show.json.jb')
+      end
+
+
+      private
+      def attributes_names
+        [:id] + super
+      end
+
+      def attributes_names_with_timestamps
+        attributes_names + %w(created_at updated_at)
+      end
+    end
+  end
+end

data/lib/generators/rails/scaffold_controller_generator.rb

@@ -0,0 +1,10 @@
+require 'rails/generators'
+require 'rails/generators/rails/scaffold_controller/scaffold_controller_generator'
+
+module Rails
+  module Generators
+    class ScaffoldControllerGenerator
+      hook_for :jb, default: true
+    end
+  end
+end

data/lib/generators/rails/templates/index.json.jb

@@ -0,0 +1,8 @@
+@<%= plural_table_name %>.map do |<%= singular_table_name %>|
+  {
+<% attributes_names.each do |attr| -%>
+    <%= attr %>: <%= singular_table_name %>.<%= attr %>,
+<% end -%>
+    url: <%= singular_table_name %>_url(<%= singular_table_name %>, format: :json)
+  }
+end

data/lib/generators/rails/templates/show.json.jb

@@ -0,0 +1,3 @@
+{
+  <%= attributes_names_with_timestamps.map {|attr| "#{attr}: @#{singular_table_name}.#{attr}"}.join(",\n  ") %>
+}

data/lib/jb/railtie.rb

@@ -7,5 +7,11 @@ module Jb
         ::ActionView::Template.register_template_handler :jb, Jb::Handler
       end
     end
+
+    generators do |app|
+      Rails::Generators.configure! app.config.generators
+      Rails::Generators.hidden_namespaces.uniq!
+      require_relative '../generators/rails/scaffold_controller_generator'
+    end
   end
 end

data/lib/jb/version.rb

@@ -1,3 +1,3 @@
 module Jb
-  VERSION = "0.1.1"
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jb
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Akira Matsuda
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-04 00:00:00.000000000 Z
+date: 2016-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -93,9 +93,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/benchmark.sh
 - bin/console
 - bin/setup
 - jb.gemspec
+- lib/generators/rails/jb_generator.rb
+- lib/generators/rails/scaffold_controller_generator.rb
+- lib/generators/rails/templates/index.json.jb
+- lib/generators/rails/templates/show.json.jb
 - lib/jb.rb
 - lib/jb/action_view_monkeys.rb
 - lib/jb/handler.rb
@@ -121,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.4
 signing_key: 
 specification_version: 4
 summary: Faster and simpler Jbuilder alternative