alba 1.3.0 → 1.6.0

data/lib/alba.rb

@@ -1,19 +1,15 @@
+require 'json'
 require_relative 'alba/version'
+require_relative 'alba/errors'
 require_relative 'alba/resource'
+require_relative 'alba/deprecation'
 
 # Core module
 module Alba
-  # Base class for Errors
-  class Error < StandardError; end
-
-  # 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, :transforming_root_key
+    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
@@ -24,33 +20,48 @@ 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
-    def enable_inference!
-      begin
-        require 'active_support/inflector'
-      rescue LoadError
-        raise ::Alba::Error, 'To enable inference, please install `ActiveSupport` gem.'
+    #
+    # @param with [Symbol, Class, Module] inflector
+    #   When it's a Symbol, it sets inflector with given name
+    #   When it's a Class or a Module, it sets given object to inflector
+    def enable_inference!(with: :default)
+      if with == :default
+        Alba::Deprecation.warn 'Calling `enable_inference!` without `with` keyword argument is deprecated. Pass `:active_support` to keep current behavior.'
       end
+
+      @inflector = inflector_from(with)
       @inferring = true
     end
 
@@ -63,35 +74,93 @@ 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
+    # @deprecated Use `Resource.on_error` instead
+    # @return [void]
     def on_error(handler = nil, &block)
+      Alba::Deprecation.warn '`Alba.on_error` is deprecated, use `on_error` on resource class instead.'
       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
 
       @_on_error = handler || block
     end
 
+    # Set nil handler
+    #
+    # @param block [Block]
+    # @return [void]
+    # @deprecated Use `Resource.on_nil` instead
+    def on_nil(&block)
+      Alba::Deprecation.warn '`Alba.on_nil` is deprecated, use `on_nil` on resource class instead.'
+      @_on_nil = block
+    end
+
     # Enable root key transformation
+    #
+    # @deprecated Use `Resource.transform_keys` with `root` option instead
     def enable_root_key_transformation!
+      Alba::Deprecation.warn '`Alba.enable_root_key_transformation!` is deprecated, use `transform_keys` on resource class instead.'
       @transforming_root_key = true
     end
 
     # Disable root key transformation
+    #
+    # @deprecated Use `Resource.transform_keys` with `root` option instead
     def disable_root_key_transformation!
+      Alba::Deprecation.warn '`Alba.disable_root_key_transformation!` is deprecated, use `transform_keys` on resource class instead.'
       @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)
+      raise Alba::Error, 'Inference is disabled so Alba cannot infer resource name. Use `Alba.enable_inference!` before use.' unless Alba.inferring
+
+      const_parent = nesting.nil? ? Object : Object.const_get(nesting)
+      const_parent.const_get("#{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 inflector_from(name_or_module)
+      case name_or_module
+      when :default, :active_support
+        require_relative 'alba/default_inflector'
+        Alba::DefaultInflector
+      when :dry
+        require 'dry/inflector'
+        Dry::Inflector.new
+      else
+        validate_inflector(name_or_module)
+      end
+    end
+
+    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
@@ -115,13 +184,18 @@ module Alba
 
     def default_encoder
       lambda do |hash|
-        require 'json'
         JSON.dump(hash)
       end
     end
+
+    def validate_inflector(inflector)
+      unless %i[camelize camelize_lower dasherize classify].all? { |m| inflector.respond_to?(m) }
+        raise Alba::Error, "Given inflector, #{inflector.inspect} is not valid. It must implement `camelize`, `camelize_lower`, `dasherize` and `classify`."
+      end
+
+      inflector
+    end
   end
 
-  @encoder = default_encoder
-  @_on_error = :raise
-  @transforming_root_key = false # TODO: This will be true since 2.0
+  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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.6.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-31 00:00:00.000000000 Z
+date: 2022-03-15 00:00:00.000000000 Z
 dependencies: []
 description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
   flexibility and usability.
@@ -21,7 +21,9 @@ files:
 - ".github/ISSUE_TEMPLATE/bug_report.md"
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".github/dependabot.yml"
+- ".github/workflows/codeql-analysis.yml"
 - ".github/workflows/main.yml"
+- ".github/workflows/perf.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".yardopts"
@@ -38,26 +40,30 @@ files:
 - 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/default_inflector.rb
-- lib/alba/key_transform_factory.rb
-- lib/alba/many.rb
-- lib/alba/one.rb
+- lib/alba/deprecation.rb
+- lib/alba/errors.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:
 - MIT
 metadata:
-  homepage_uri: https://github.com/okuramasafumi/alba
+  bug_tracker_uri: https://github.com/okuramasafumi/issues
+  changelog_uri: https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/github/okuramasafumi/alba
   source_code_uri: https://github.com/okuramasafumi/alba
-  changelog_uri: https://github.com/okuramasafumi/alba/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -73,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.16
+rubygems_version: 3.3.5
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.

data/lib/alba/key_transform_factory.rb

@@ -1,33 +0,0 @@
-module Alba
-  # This module creates key transform functions
-  module KeyTransformFactory
-    class << self
-      # Create key transform function for given transform_type
-      #
-      # @params transform_type [Symbol] transform type
-      # @return [Proc] transform function
-      # @raise [Alba::Error] when transform_type is not supported
-      def create(transform_type)
-        case transform_type
-        when :camel
-          ->(key) { _inflector.camelize(key) }
-        when :lower_camel
-          ->(key) { _inflector.camelize_lower(key) }
-        when :dash
-          ->(key) { _inflector.dasherize(key) }
-        else
-          raise ::Alba::Error, "Unknown transform_type: #{transform_type}. Supported transform_type are :camel, :lower_camel and :dash."
-        end
-      end
-
-      private
-
-      def _inflector
-        Alba.inflector || begin
-          require_relative './default_inflector'
-          Alba::DefaultInflector
-        end
-      end
-    end
-  end
-end

data/lib/alba/many.rb

@@ -1,21 +0,0 @@
-require_relative 'association'
-
-module Alba
-  # Representing many association
-  class Many < Association
-    # 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, 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, within: within).to_hash
-    end
-  end
-end

data/lib/alba/one.rb

@@ -1,21 +0,0 @@
-require_relative 'association'
-
-module Alba
-  # Representing one association
-  class One < Association
-    # 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, 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, within: within).to_hash
-    end
-  end
-end