alba 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fc2741e03be6373aa324768358a1acf4b713ec43bba5daf80d133a08d0cc12b
-  data.tar.gz: 7228dc09384d5d4d6e99456a6f14d6e0cb3d678483cd59a7439d6a150f463e4b
+  metadata.gz: 36890dfa4b9b73b60f1d6a09cf674de7ff7a6dd495ff4b74bbb3d048f9cf5a85
+  data.tar.gz: 3e3d49619f646be866262e14e21e5fba11e2caafbc24064d57eb9c549cb64e4d
 SHA512:
-  metadata.gz: 0fb68a3a1c786aa1b776246d08fd23bada8d4c7fcff0ea2ba33a49a1410d9b1e839407450ff2d1137f531a8e80738977369a4f857199d3bb65c98b140d7cd6b9
-  data.tar.gz: fcfb93544bab6b48e6ae24946992231a6023df52763d807dad276f1468c1ce77d255fe637de3a72efacffe2d20915d203ddc1f247908c4f6e4d69ae6ea4c97da
+  metadata.gz: fc7e025a035b41dadaab5300096cf920eb3557a4be900d31b514dfc66e8ae803b0fb63d77ec06174d72d70ad2e07da81c491502c8462ad306f2379720222fc65
+  data.tar.gz: 741f5c1c69b2809aec51d2a2a139d4d8e00060c9aa174bf5fb68d5dbcec7996096aced5fb377d77fa147d7b6086a65191c8c764802c65bbd88d3806751ec0eb4

data/.gitignore

@@ -8,3 +8,4 @@
 /tmp/
 
 Gemfile.lock
+/gemfiles/*.lock

data/.rubocop.yml

@@ -30,17 +30,23 @@ Layout/MultilineAssignmentLayout:
 Lint/ConstantResolution:
   Enabled: false
 
-Metrics/ClassLength:
+# In test code we don't care about the metrics!
+Metrics:
   Exclude:
-    - 'test/alba_test.rb'
+    - 'test/**/*.rb'
 
 Metrics/MethodLength:
   Max: 15
 
+# `Resource` module is a core module and its length tends to be long...
+Metrics/ModuleLength:
+  Max: 150
+
 # Resource class includes DSLs, which tend to accept long list of parameters
 Metrics/ParameterLists:
   Exclude:
     - 'lib/alba/resource.rb'
+    - 'test/**/*.rb'
 
 # We need to eval resource code to test errors on resource classes
 Security/Eval:

data/CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2021-04-23
+
+- [Feat] Implement circular associations control [71e1543]
+- [Feat] Support :oj_rails backend [76e519e]
+
 ## [1.0.1] - 2021-04-15
 
 - [Fix] Don't cache resource class for `Alba.serialize` [9ed5253]

data/Gemfile

@@ -4,11 +4,12 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'activesupport', require: false # For backend
+gem 'ffaker', require: false # For testing
 gem 'minitest', '~> 5.14' # For test
 gem 'rake', '~> 13.0' # For test and automation
 gem 'rubocop', '>= 0.79.0', require: false # For lint
 gem 'rubocop-minitest', '~> 0.11.0', require: false # For lint
-gem 'rubocop-performance', '~> 1.10.1', require: false # For lint
+gem 'rubocop-performance', '~> 1.11.0', require: false # For lint
 gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
 gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
 gem 'simplecov', '~> 0.21.0', require: false # For test coverage

data/README.md

@@ -7,7 +7,7 @@
 
 # Alba
 
-`Alba` is the fastest JSON serializer for Ruby, JRuby an TruffleRuby.
+Alba is the fastest JSON serializer for Ruby, JRuby, and TruffleRuby.
 
 ## Discussions
 
@@ -70,6 +70,7 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 * Root key inference
 * Error handling
 * Resource name inflection based on association name
+* Circular associations control
 * No runtime dependencies
 
 ## Anti features
@@ -450,14 +451,15 @@ Alba.on_error do |error, object, key, attribute, resource_class|
 end
 ```
 
-### Caching
+### Circular associations control
 
-Currently, Alba doesn't support caching, primarily due to the behavior of `ActiveRecord::Relation`'s cache. See [the issue](https://github.com/rails/rails/issues/41784).
+You can control circular associations with `within` option. `within` option is a nested Hash such as `{book: {authors: books}}`. In this example, Alba serializes a book's authors' books. This means you can reference `BookResource` from `AuthorResource` and vice versa. This is really powerful when you have a complex data structure and serialize certain parts of it.
 
-## Comparison
+For more details, please refer to [test code](https://github.com/okuramasafumi/alba/blob/master/test/usecases/circular_association_test.rb)
 
-Alba is faster than alternatives.
-For a performance benchmark, see https://gist.github.com/okuramasafumi/4e375525bd3a28e4ca812d2a3b3e5829.
+### Caching
+
+Currently, Alba doesn't support caching, primarily due to the behavior of `ActiveRecord::Relation`'s cache. See [the issue](https://github.com/rails/rails/issues/41784).
 
 ## Rails
 
@@ -465,6 +467,8 @@ When you use Alba in Rails, you can create an initializer file with the line bel
 
 ```ruby
 Alba.backend = :active_support
+# or
+Alba.backend = :oj_rails
 ```
 
 ## Why named "Alba"?

data/benchmark/local.rb

@@ -1,32 +1,37 @@
 # Benchmark script to run varieties of JSON serializers
 # Fetch Alba from local, otherwise fetch latest from RubyGems
 
+# --- Bundle dependencies ---
+
 require "bundler/inline"
 
 gemfile(true) do
   source "https://rubygems.org"
-
   git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-  gem "activerecord", "6.1.3"
-  gem "sqlite3"
-  gem "jbuilder"
   gem "active_model_serializers"
-  gem "blueprinter"
-  gem "representable"
+  gem "activerecord", "6.1.3"
   gem "alba", path: '../'
-  gem "oj"
+  gem "benchmark-ips"
+  gem "blueprinter"
+  gem "jbuilder"
+  gem "jsonapi-serializer" # successor of fast_jsonapi
   gem "multi_json"
+  gem "oj"
+  gem "representable"
+  gem "sqlite3"
 end
 
+# --- Test data model setup ---
+
 require "active_record"
-require "sqlite3"
 require "logger"
 require "oj"
+require "sqlite3"
 Oj.optimize_rails
 
 ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
-# ActiveRecord::Base.logger = Logger.new(STDOUT)
+# ActiveRecord::Base.logger = Logger.new($stdout)
 
 ActiveRecord::Schema.define do
   create_table :posts, force: true do |t|
@@ -70,8 +75,9 @@ class User < ActiveRecord::Base
   has_many :comments
 end
 
+# --- Alba serializers ---
+
 require "alba"
-Alba.backend = :oj
 
 class AlbaCommentResource
   include ::Alba::Resource
@@ -81,17 +87,55 @@ end
 class AlbaPostResource
   include ::Alba::Resource
   attributes :id, :body
-  many :comments, resource: AlbaCommentResource
   attribute :commenter_names do |post|
     post.commenters.pluck(:name)
   end
+  many :comments, resource: AlbaCommentResource
+end
+
+# --- ActiveModelSerializer serializers ---
+
+require "active_model_serializers"
+
+class AMSCommentSerializer < ActiveModel::Serializer
+  attributes :id, :body
 end
 
+class AMSPostSerializer < ActiveModel::Serializer
+  attributes :id, :body
+  attribute :commenter_names
+  has_many :comments, serializer: AMSCommentSerializer
+
+  def commenter_names
+    object.commenters.pluck(:name)
+  end
+end
+
+# --- Blueprint serializers ---
+
+require "blueprinter"
+
+class CommentBlueprint < Blueprinter::Base
+  fields :id, :body
+end
+
+class PostBlueprint < Blueprinter::Base
+  fields :id, :body, :commenter_names
+  association :comments, blueprint: CommentBlueprint
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+# --- JBuilder serializers ---
+
 require "jbuilder"
+
 class Post
   def to_builder
     Jbuilder.new do |post|
-      post.call(self, :id, :body, :comments, :commenter_names)
+      post.call(self, :id, :body, :commenter_names, :comments)
     end
   end
 
@@ -108,35 +152,69 @@ class Comment
   end
 end
 
-require "active_model_serializers"
+# --- JSONAPI:Serializer serializers / (successor of fast_jsonapi) ---
 
-class AMSCommentSerializer < ActiveModel::Serializer
-  attributes :id, :body
+class JsonApiStandardCommentSerializer
+  include JSONAPI::Serializer
+
+  attribute :id
+  attribute :body
 end
 
-class AMSPostSerializer < ActiveModel::Serializer
-  attributes :id, :body
-  has_many :comments, serializer: AMSCommentSerializer
+class JsonApiStandardPostSerializer
+  include JSONAPI::Serializer
+
+  # set_type :post  # optional
+  attribute :id
+  attribute :body
   attribute :commenter_names
-  def commenter_names
-    object.commenters.pluck(:name)
+
+  attribute :comments do |post|
+    post.comments.map { |comment| JsonApiSameFormatCommentSerializer.new(comment) }
   end
 end
 
-require "blueprinter"
+# --- JSONAPI:Serializer serializers that format the code the same flat way as the other gems here ---
 
-class CommentBlueprint < Blueprinter::Base
-  fields :id, :body
+# code to convert from JSON:API output to "flat" JSON, like the other serializers build
+class JsonApiSameFormatSerializer
+  include JSONAPI::Serializer
+
+  def as_json(*_options)
+    hash = serializable_hash
+
+    if hash[:data].is_a? Hash
+      hash[:data][:attributes]
+
+    elsif hash[:data].is_a? Array
+      hash[:data].pluck(:attributes)
+
+    elsif hash[:data].nil?
+      { }
+
+    else
+      raise "unexpected data type #{hash[:data].class}"
+    end
+  end
 end
 
-class PostBlueprint < Blueprinter::Base
-  fields :id, :body, :commenter_names
-  association :comments, blueprint: CommentBlueprint
-  def commenter_names
-    commenters.pluck(:name)
+class JsonApiSameFormatCommentSerializer < JsonApiSameFormatSerializer
+  attribute :id
+  attribute :body
+end
+
+class JsonApiSameFormatPostSerializer < JsonApiSameFormatSerializer
+  attribute :id
+  attribute :body
+  attribute :commenter_names
+
+  attribute :comments do |post|
+    post.comments.map { |comment| JsonApiSameFormatCommentSerializer.new(comment) }
   end
 end
 
+# --- Representable serializers ---
+
 require "representable"
 
 class CommentRepresenter < Representable::Decorator
@@ -159,6 +237,8 @@ class PostRepresenter < Representable::Decorator
   end
 end
 
+# --- Test data creation ---
+
 post = Post.create!(body: 'post')
 user1 = User.create!(name: 'John')
 user2 = User.create!(name: 'Jane')
@@ -166,12 +246,9 @@ post.comments.create!(commenter: user1, body: 'Comment1')
 post.comments.create!(commenter: user2, body: 'Comment2')
 post.reload
 
+# --- Store the serializers in procs ---
+
 alba = Proc.new { AlbaPostResource.new(post).serialize }
-jbuilder = Proc.new { post.to_builder.target! }
-ams = Proc.new { AMSPostSerializer.new(post, {}).to_json }
-rails = Proc.new { ActiveSupport::JSON.encode(post.serializable_hash(include: :comments)) }
-blueprinter = Proc.new { PostBlueprint.render(post) }
-representable = Proc.new { PostRepresenter.new(post).to_json }
 alba_inline = Proc.new do
   Alba.serialize(post) do
     attributes :id, :body
@@ -183,16 +260,56 @@ alba_inline = Proc.new do
     end
   end
 end
-[alba, jbuilder, ams, rails, blueprinter, representable, alba_inline].each {|x| puts x.call }
+ams = Proc.new { AMSPostSerializer.new(post, {}).to_json }
+blueprinter = Proc.new { PostBlueprint.render(post) }
+jbuilder = Proc.new { post.to_builder.target! }
+jsonapi = proc { JsonApiStandardPostSerializer.new(post).to_json }
+jsonapi_same_format = proc { JsonApiSameFormatPostSerializer.new(post).to_json }
+rails = Proc.new { ActiveSupport::JSON.encode(post.serializable_hash(include: :comments)) }
+representable = Proc.new { PostRepresenter.new(post).to_json }
+
+# --- Execute the serializers to check their output ---
+
+puts "Serializer outputs ----------------------------------"
+{
+  alba: alba,
+  alba_inline: alba_inline,
+  ams: ams,
+  blueprinter: blueprinter,
+  jbuilder: jbuilder, # different order
+  jsonapi: jsonapi, # nested JSON:API format
+  jsonapi_same_format: jsonapi_same_format,
+  rails: rails,
+  representable: representable
+}.each { |name, serializer| puts "#{name.to_s.ljust(24, ' ')} #{serializer.call}" }
+
+# --- Run the benchmarks ---
 
 require 'benchmark'
 time = 1000
 Benchmark.bmbm do |x|
   x.report(:alba) { time.times(&alba) }
-  x.report(:jbuilder) { time.times(&jbuilder) }
+  x.report(:alba_inline) { time.times(&alba_inline) }
   x.report(:ams) { time.times(&ams) }
-  x.report(:rails) { time.times(&rails) }
   x.report(:blueprinter) { time.times(&blueprinter) }
+  x.report(:jbuilder) { time.times(&jbuilder) }
+  x.report(:jsonapi) { time.times(&jsonapi) }
+  x.report(:jsonapi_same_format) { time.times(&jsonapi_same_format) }
+  x.report(:rails) { time.times(&rails) }
   x.report(:representable) { time.times(&representable) }
-  x.report(:alba_inline) { time.times(&alba_inline) }
+end
+
+require 'benchmark/ips'
+Benchmark.ips do |x|
+  x.report(:alba, &alba)
+  x.report(:alba_inline, &alba_inline)
+  x.report(:ams, &ams)
+  x.report(:blueprinter, &blueprinter)
+  x.report(:jbuilder, &jbuilder)
+  x.report(:jsonapi, &jsonapi)
+  x.report(:jsonapi_same_format, &jsonapi_same_format)
+  x.report(:rails, &rails)
+  x.report(:representable, &representable)
+
+  x.compare!
 end

data/codecov.yml

@@ -0,0 +1,5 @@
+coverage:
+  status:
+    project:
+      default:
+        informational: true

data/gemfiles/all.gemfile

@@ -1,6 +1,7 @@
 source 'https://rubygems.org'
 
 gem 'activesupport', require: false # For backend
+gem 'ffaker', require: false # For testing
 gem 'minitest', '~> 5.14' # For test
 gem 'rake', '~> 13.0' # For test and automation
 gem 'rubocop', '>= 0.79.0', require: false # For lint

data/lib/alba.rb

@@ -70,8 +70,10 @@ module Alba
 
     def set_encoder
       @encoder = case @backend
-                 when :oj
+                 when :oj, :oj_strict
                    try_oj
+                 when :oj_rails
+                   try_oj(mode: :rails)
                  when :active_support
                    try_active_support
                  when nil, :default, :json
@@ -81,9 +83,9 @@ module Alba
                  end
     end
 
-    def try_oj
+    def try_oj(mode: :strict)
       require 'oj'
-      ->(hash) { Oj.dump(hash, mode: :strict) }
+      ->(hash) { Oj.dump(hash, mode: mode) }
     rescue LoadError
       Kernel.warn '`Oj` is not installed, falling back to default JSON encoder.'
       default_encoder

data/lib/alba/many.rb

@@ -6,15 +6,16 @@ module Alba
     # Recursively converts objects into an Array of Hashes
     #
     # @param target [Object] the object having an association method
+    # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
     # @param params [Hash] user-given Hash for arbitrary data
     # @return [Array<Hash>]
-    def to_hash(target, params: {})
+    def to_hash(target, within: nil, params: {})
       @object = target.public_send(@name)
       @object = @condition.call(@object, params) if @condition
       return if @object.nil?
 
       @resource = constantize(@resource)
-      @object.map { |o| @resource.new(o, params: params).to_hash }
+      @object.map { |o| @resource.new(o, params: params, within: within).to_hash }
     end
   end
 end

data/lib/alba/one.rb

@@ -6,15 +6,16 @@ module Alba
     # Recursively converts an object into a Hash
     #
     # @param target [Object] the object having an association method
+    # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
     # @param params [Hash] user-given Hash for arbitrary data
     # @return [Hash]
-    def to_hash(target, params: {})
+    def to_hash(target, within: nil, params: {})
       @object = target.public_send(@name)
       @object = @condition.call(object, params) if @condition
       return if @object.nil?
 
       @resource = constantize(@resource)
-      @resource.new(object, params: params).to_hash
+      @resource.new(object, params: params, within: within).to_hash
     end
   end
 end

data/lib/alba/resource.rb

@@ -28,9 +28,11 @@ module Alba
 
       # @param object [Object] the object to be serialized
       # @param params [Hash] user-given Hash for arbitrary data
-      def initialize(object, params: {})
+      # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
+      def initialize(object, params: {}, within: true)
         @object = object
         @params = params.freeze
+        @within = within
         DSLS.each_key { |name| instance_variable_set("@#{name}", self.class.public_send(name)) }
       end
 
@@ -130,12 +132,32 @@ module Alba
         when Proc
           instance_exec(object, &attribute)
         when Alba::One, Alba::Many
-          attribute.to_hash(object, params: params)
+          within = check_within
+          return unless within
+
+          attribute.to_hash(object, params: params, within: within)
         else
           raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
         end
       end
 
+      def check_within
+        case @within
+        when Hash # Traverse within tree
+          @within.fetch(_key.to_sym, nil)
+        when Array # within tree ends with Array
+          @within.find { |item| item.to_sym == _key.to_sym } # Check if at least one item in the array matches current resource
+        when Symbol # within tree could end with Symbol
+          @within == _key.to_sym # Check if the symbol matches current resource
+        when true # In this case, Alba serializes all associations.
+          true
+        when nil, false # In these cases, Alba stops serialization here.
+          false
+        else
+          raise Alba::Error, "Unknown type for within option: #{@within.class}"
+        end
+      end
+
       def collection?
         @object.is_a?(Enumerable)
       end

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-15 00:00:00.000000000 Z
+date: 2021-04-23 00:00:00.000000000 Z
 dependencies: []
 description: Alba is designed to be a simple, easy to use and fast alternative to
   existing JSON serializers. Its performance is better than almost all gems which
@@ -33,6 +33,7 @@ files:
 - benchmark/local.rb
 - bin/console
 - bin/setup
+- codecov.yml
 - gemfiles/all.gemfile
 - gemfiles/without_active_support.gemfile
 - gemfiles/without_oj.gemfile
@@ -66,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.14
+rubygems_version: 3.2.16
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.