alba 1.1.0 → 1.5.0

data/lib/alba.rb

@@ -1,5 +1,7 @@
+require 'json'
 require_relative 'alba/version'
 require_relative 'alba/resource'
+require_relative 'alba/deprecation'
 
 # Core module
 module Alba
@@ -9,8 +11,14 @@ module Alba
   # Error class for backend which is not supported
   class UnsupportedBackend < Error; end
 
+  # Error class for type which is not supported
+  class UnsupportedType < Error; end
+
   class << self
-    attr_reader :backend, :encoder, :inferring, :_on_error
+    attr_reader :backend, :encoder, :inferring, :_on_error, :_on_nil, :transforming_root_key
+
+    # Accessor for inflector, a module responsible for incflecting strings
+    attr_accessor :inflector
 
     # Set the backend, which actually serializes object into JSON
     #
@@ -20,24 +28,35 @@ module Alba
     # @raise [Alba::UnsupportedBackend] if backend is not supported
     def backend=(backend)
       @backend = backend&.to_sym
-      set_encoder
+      set_encoder_from_backend
+    end
+
+    # Set encoder, a Proc object that accepts an object and generates JSON from it
+    # Set backend as `:custom` which indicates no preset encoder is used
+    #
+    # @param encoder [Proc]
+    # @raise [ArgumentError] if given encoder is not a Proc or its arity is not one
+    def encoder=(encoder)
+      raise ArgumentError, 'Encoder must be a Proc accepting one argument' unless encoder.is_a?(Proc) && encoder.arity == 1
+
+      @encoder = encoder
+      @backend = :custom
     end
 
     # Serialize the object with inline definitions
     #
     # @param object [Object] the object to be serialized
-    # @param key [Symbol]
+    # @param key [Symbol, nil, true] DEPRECATED, use root_key instead
+    # @param root_key [Symbol, nil, true]
     # @param block [Block] resource block
     # @return [String] serialized JSON string
     # @raise [ArgumentError] if block is absent or `with` argument's type is wrong
-    def serialize(object, key: nil, &block)
-      raise ArgumentError, 'Block required' unless block
+    def serialize(object, key: nil, root_key: nil, &block)
+      Alba::Deprecation.warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
+      klass = block ? resource_class(&block) : infer_resource_class(object.class.name)
 
-      klass = Class.new
-      klass.include(Alba::Resource)
-      klass.class_eval(&block)
       resource = klass.new(object)
-      resource.serialize(key: key)
+      resource.serialize(root_key: root_key || key)
     end
 
     # Enable inference for key and resource name
@@ -59,6 +78,9 @@ module Alba
     #
     # @param [Symbol] handler
     # @param [Block]
+    # @raise [ArgumentError] if both handler and block params exist
+    # @raise [ArgumentError] if both handler and block params don't exist
+    # @return [void]
     def on_error(handler = nil, &block)
       raise ArgumentError, 'You cannot specify error handler with both Symbol and block' if handler && block
       raise ArgumentError, 'You must specify error handler with either Symbol or block' unless handler || block
@@ -66,18 +88,59 @@ module Alba
       @_on_error = handler || block
     end
 
+    # Set nil handler
+    #
+    # @param block [Block]
+    # @return [void]
+    def on_nil(&block)
+      @_on_nil = block
+    end
+
+    # Enable root key transformation
+    def enable_root_key_transformation!
+      @transforming_root_key = true
+    end
+
+    # Disable root key transformation
+    def disable_root_key_transformation!
+      @transforming_root_key = false
+    end
+
+    # @param block [Block] resource body
+    # @return [Class<Alba::Resource>] resource class
+    def resource_class(&block)
+      klass = Class.new
+      klass.include(Alba::Resource)
+      klass.class_eval(&block)
+      klass
+    end
+
+    # @param name [String] a String Alba infers resource name with
+    # @param nesting [String, nil] namespace Alba tries to find resource class in
+    # @return [Class<Alba::Resource>] resource class
+    def infer_resource_class(name, nesting: nil)
+      enable_inference!
+      const_parent = nesting.nil? ? Object : Object.const_get(nesting)
+      const_parent.const_get("#{ActiveSupport::Inflector.classify(name)}Resource")
+    end
+
+    # Reset config variables
+    # Useful for test cleanup
+    def reset!
+      @encoder = default_encoder
+      @_on_error = :raise
+      @_on_nil = nil
+      @transforming_root_key = false # TODO: This will be true since 2.0
+    end
+
     private
 
-    def set_encoder
+    def set_encoder_from_backend
       @encoder = case @backend
-                 when :oj, :oj_strict
-                   try_oj
-                 when :oj_rails
-                   try_oj(mode: :rails)
-                 when :active_support
-                   try_active_support
-                 when nil, :default, :json
-                   default_encoder
+                 when :oj, :oj_strict then try_oj
+                 when :oj_rails then try_oj(mode: :rails)
+                 when :active_support then try_active_support
+                 when nil, :default, :json then default_encoder
                  else
                    raise Alba::UnsupportedBackend, "Unsupported backend, #{backend}"
                  end
@@ -101,12 +164,10 @@ module Alba
 
     def default_encoder
       lambda do |hash|
-        require 'json'
         JSON.dump(hash)
       end
     end
   end
 
-  @encoder = default_encoder
-  @_on_error = :raise
+  reset!
 end

data/script/perf_check.rb

@@ -0,0 +1,174 @@
+# Benchmark script to run varieties of JSON serializers
+# Fetch Alba from local, otherwise fetch latest from RubyGems
+# exit(status)
+
+# --- 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 "alba", path: '../'
+  gem "benchmark-ips"
+  gem "blueprinter"
+  gem "jbuilder"
+  gem "multi_json"
+  gem "oj"
+  gem "sqlite3"
+end
+
+# --- Test data model setup ---
+
+require "active_record"
+require "oj"
+require "sqlite3"
+Oj.optimize_rails
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+
+ActiveRecord::Schema.define do
+  create_table :posts, force: true do |t|
+    t.string :body
+  end
+
+  create_table :comments, force: true do |t|
+    t.integer :post_id
+    t.string :body
+    t.integer :commenter_id
+  end
+
+  create_table :users, force: true do |t|
+    t.string :name
+  end
+end
+
+class Post < ActiveRecord::Base
+  has_many :comments
+  has_many :commenters, through: :comments, class_name: 'User', source: :commenter
+
+  def attributes
+    {id: nil, body: nil, commenter_names: commenter_names}
+  end
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+  belongs_to :commenter, class_name: 'User'
+
+  def attributes
+    {id: nil, body: nil}
+  end
+end
+
+class User < ActiveRecord::Base
+  has_many :comments
+end
+
+# --- Alba serializers ---
+
+require "alba"
+
+class AlbaCommentResource
+  include ::Alba::Resource
+  attributes :id, :body
+end
+
+class AlbaPostResource
+  include ::Alba::Resource
+  attributes :id, :body
+  attribute :commenter_names do |post|
+    post.commenters.pluck(:name)
+  end
+  many :comments, resource: AlbaCommentResource
+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, :commenter_names, :comments)
+    end
+  end
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+class Comment
+  def to_builder
+    Jbuilder.new do |comment|
+      comment.call(self, :id, :body)
+    end
+  end
+end
+
+# --- Test data creation ---
+
+100.times do |i|
+  post = Post.create!(body: "post#{i}")
+  user1 = User.create!(name: "John#{i}")
+  user2 = User.create!(name: "Jane#{i}")
+  10.times do |n|
+    post.comments.create!(commenter: user1, body: "Comment1_#{i}_#{n}")
+    post.comments.create!(commenter: user2, body: "Comment2_#{i}_#{n}")
+  end
+end
+
+posts = Post.all.to_a
+
+# --- Store the serializers in procs ---
+
+alba = Proc.new { AlbaPostResource.new(posts).serialize }
+blueprinter = Proc.new { PostBlueprint.render(posts) }
+jbuilder = Proc.new do
+  Jbuilder.new do |json|
+    json.array!(posts) do |post|
+      json.post post.to_builder
+    end
+  end.target!
+end
+
+# --- Run the benchmarks ---
+
+require 'benchmark/ips'
+result = Benchmark.ips do |x|
+  x.report(:alba, &alba)
+  x.report(:blueprinter, &blueprinter)
+  x.report(:jbuilder, &jbuilder)
+end
+
+entries = result.entries.map {|entry| [entry.label, entry.iterations]}
+alba_ips = entries.find {|e| e.first == :alba }.last
+blueprinter_ips = entries.find {|e| e.first == :blueprinter }.last
+jbuidler_ips = entries.find {|e| e.first == :jbuilder }.last
+# Alba should be as fast as jbuilder and faster than blueprinter
+alba_is_fast_enough = (alba_ips - jbuidler_ips) > -10.0 && (alba_ips - blueprinter_ips) > 10.0
+exit(alba_is_fast_enough)

data/sider.yml

@@ -49,10 +49,8 @@ linter:
 #     norc: true
 
 # # https://help.sider.review/getting-started/custom-configuration#ignore
-# ignore:
-#   - "*.pdf"
-#   - "*.mp4"
-#   - "images/**"
+ignore:
+  - 'test/**/*'
 
 # # https://help.sider.review/getting-started/custom-configuration#branchesexclude
 # branches:

metadata

@@ -1,25 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.5.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-23 00:00:00.000000000 Z
+date: 2021-11-28 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
-  do similar things. The internal is so simple that it's easy to hack and maintain.
+description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
+  flexibility and usability.
 email:
 - masafumi.o1988@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
+- ".github/dependabot.yml"
 - ".github/workflows/main.yml"
+- ".github/workflows/perf.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".yardopts"
@@ -29,21 +32,29 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - alba.gemspec
-- benchmark/local.rb
+- benchmark/collection.rb
+- benchmark/single_resource.rb
 - bin/console
 - bin/setup
 - codecov.yml
+- docs/migrate_from_active_model_serializers.md
+- docs/migrate_from_jbuilder.md
 - gemfiles/all.gemfile
 - gemfiles/without_active_support.gemfile
 - gemfiles/without_oj.gemfile
 - lib/alba.rb
 - lib/alba/association.rb
-- lib/alba/key_transformer.rb
+- lib/alba/default_inflector.rb
+- lib/alba/deprecation.rb
+- lib/alba/key_transform_factory.rb
 - lib/alba/many.rb
 - lib/alba/one.rb
 - lib/alba/resource.rb
+- lib/alba/typed_attribute.rb
 - lib/alba/version.rb
+- script/perf_check.rb
 - sider.yml
 homepage: https://github.com/okuramasafumi/alba
 licenses:
@@ -51,7 +62,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/okuramasafumi/alba
   source_code_uri: https://github.com/okuramasafumi/alba
-  changelog_uri: https://github.com/okuramasafumi/alba/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -67,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.16
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.

data/lib/alba/key_transformer.rb

@@ -1,32 +0,0 @@
-module Alba
-  # Transform keys using `ActiveSupport::Inflector`
-  module KeyTransformer
-    begin
-      require 'active_support/inflector'
-    rescue LoadError
-      raise ::Alba::Error, 'To use transform_keys, please install `ActiveSupport` gem.'
-    end
-
-    module_function
-
-    # Transform key as given transform_type
-    #
-    # @params key [String] key to be transformed
-    # @params transform_type [Symbol] transform type
-    # @return [String] transformed key
-    # @raise [Alba::Error] when transform_type is not supported
-    def transform(key, transform_type)
-      key = key.to_s
-      case transform_type
-      when :camel
-        ActiveSupport::Inflector.camelize(key)
-      when :lower_camel
-        ActiveSupport::Inflector.camelize(key, false)
-      when :dash
-        ActiveSupport::Inflector.dasherize(key)
-      else
-        raise ::Alba::Error, "Unknown transform_type: #{transform_type}. Supported transform_type are :camel, :lower_camel and :dash."
-      end
-    end
-  end
-end