alba 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2c2e8c84ddccf4db9f9f18dd155361567f2a1733c55f817f5b4d97d573675d5
-  data.tar.gz: 3f11dd120c8b57aef909d79f6570482b8af810cd19c57ddcaa0d7b2ee70c2d6b
+  metadata.gz: 01d43d93e589197104d9ee166e6a9dcf727fd204524b52145d7d93b45ba79cd2
+  data.tar.gz: 023f2e0f8ff17bc78a01e2dc1eb1f98d9c41b0cd353e311f350c2704a9ffa602
 SHA512:
-  metadata.gz: 8948a681fb88b3d84e3751e6df0f5ca28314d6c9b5e183666780be95b14fd3c7728e6ad1eb13309d4b7114115b56edbb28fe929c2376bbcc5b762846a7d00404
-  data.tar.gz: 9a2430efc4cf3b7a24b27bb40228dad67e00bd0cb10c9e0fc3764eb49e9caafda5b6d9fa0cc0335c77edc42e0a60416b20343dee5cee23dcfbfe350bed90e9a6
+  metadata.gz: 99992932a0f6a3d589e77e1b7dc4225be2e083a15320fa00a96f07a4cd9bbe9803454b94ecae409d439809a53225fb54ce283fcca074c0aed479e7d8b808d545
+  data.tar.gz: c77e99af9cf98781a2e961817b5c60e31fe178e6eef7bb8bd77b1af199043b8acd8395a27dd7cb10680ae82d28ec57e98106fef42f57055cb23752d63605a7b9

data/.github/workflows/perf.yml

@@ -0,0 +1,21 @@
+name: Performance Check
+
+on: [pull_request]
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6, 2.7, 3.0]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run benchmark
+      run: |
+        ruby script/perf_check.rb

data/.rubocop.yml

@@ -13,12 +13,13 @@ AllCops:
     - 'Rakefile'
     - 'alba.gemspec'
     - 'benchmark/**/*.rb'
+    - 'script/**/*.rb'
   NewCops: enable
   EnabledByDefault: true
   TargetRubyVersion: 2.5
 
-# Oneline comment is not valid so until it gets valid, we disable it
-Bundler/GemComment:
+# Items in Gemfile is dev dependencies and we don't have to specify versions.
+Bundler/GemVersion:
   Enabled: false
 
 # We'd like to write something like:
@@ -44,9 +45,6 @@ Metrics:
   Exclude:
     - 'test/**/*.rb'
 
-Metrics/MethodLength:
-  Max: 15
-
 # `Resource` module is a core module and its length tends to be long...
 Metrics/ModuleLength:
   Exclude:
@@ -55,7 +53,6 @@ Metrics/ModuleLength:
 # 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
@@ -81,7 +78,10 @@ Style/InlineComment:
   Enabled: false
 
 Style/MethodCallWithArgsParentheses:
-  Enabled: false
+  IgnoredMethods: ['require', 'require_relative', 'include', 'extend', 'puts', 'p', 'warn', 'raise', 'send', 'public_send']
+  Exclude:
+    # There are so many `attributes` call without parenthese and that's absolutely fine
+    - 'test/**/*.rb'
 
 # There are so many cases we just want `if` expression!
 Style/MissingElse:

data/CHANGELOG.md

@@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] 2021-06-30
+
+- [Feat] Add a config method to set encoder directly
+- [Feat] Implement `meta` method and option for metadata
+- [Feat] Add `root_key` option to `Resource#serialize`
+- [Feat] Enable setting key for collection with `root_key`
+- [Feat] Add `Resource.root_key` and `Resource.root_key!`
+- [Feat] `Alba.serialize` now infers resource class
+
 ## [1.3.0] 2021-05-31
 
 - [Perf] Improve performance for `many` [641d8f9]

data/Gemfile

@@ -5,16 +5,17 @@ gemspec
 
 gem 'activesupport', require: false # For backend
 gem 'ffaker', require: false # For testing
+gem 'inch', require: false # For inline documents
 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.12.0', require: false # For lint
+gem 'rubocop-minitest', '~> 0.13.0', 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
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'oj', '~> 3.11', require: false # For backend

data/README.md

@@ -2,6 +2,7 @@
 [![CI](https://github.com/okuramasafumi/alba/actions/workflows/main.yml/badge.svg)](https://github.com/okuramasafumi/alba/actions/workflows/main.yml)
 [![codecov](https://codecov.io/gh/okuramasafumi/alba/branch/master/graph/badge.svg?token=3D3HEZ5OXT)](https://codecov.io/gh/okuramasafumi/alba)
 [![Maintainability](https://api.codeclimate.com/v1/badges/fdab4cc0de0b9addcfe8/maintainability)](https://codeclimate.com/github/okuramasafumi/alba/maintainability)
+[![Inline docs](http://inch-ci.org/github/okuramasafumi/alba.svg?branch=main)](http://inch-ci.org/github/okuramasafumi/alba)
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/okuramasafumi/alba)
 ![GitHub](https://img.shields.io/github/license/okuramasafumi/alba)
 
@@ -98,6 +99,16 @@ You can set a backend like this:
 Alba.backend = :oj
 ```
 
+#### Encoder configuration
+
+You can also set JSON encoder directly with a Proc.
+
+```ruby
+Alba.encoder = ->(object) { JSON.generate(object) }
+```
+
+You can consider setting a backend with Symbol as a shortcut to set encoder.
+
 #### Inference configuration
 
 You can enable inference feature using `enable_inference!` method.
@@ -198,6 +209,35 @@ UserResource.new(user).serialize
 # => '{"id":1,"articles":[{"title":"Hello World!"},{"title":"Super nice"}]}'
 ```
 
+You can define associations inline if you don't need a class for association.
+
+```ruby
+class ArticleResource
+  include Alba::Resource
+
+  attributes :title
+end
+
+class UserResource
+  include Alba::Resource
+
+  attributes :id
+
+  many :articles, resource: ArticleResource
+end
+
+# This class works the same as `UserResource`
+class AnotherUserResource
+  include Alba::Resource
+
+  attributes :id
+
+  many :articles do
+    attributes :title
+  end
+end
+```
+
 ### Inline definition with `Alba.serialize`
 
 `Alba.serialize` method is a shortcut to define everything inline.
@@ -212,6 +252,13 @@ end
 # => '{"foo":{"id":1,"articles":[{"title":"Hello World!","body":"Hello World!!!"},{"title":"Super nice","body":"Really nice!"}]}}'
 ```
 
+`Alba.serialize` can be used when you don't know what kind of object you serialize. For example:
+
+```ruby
+Alba.serialize(something)
+# => Same as `FooResource.new(something).serialize` when `something` is an instance of `Foo`.
+```
+
 Although this might be useful sometimes, it's generally recommended to define a class for Resource.
 
 ### Inheritance and Ignorance
@@ -235,13 +282,12 @@ class GenericFooResource
   attributes :id, :name, :body
 end
 
-class RestrictedFooResouce < GenericFooResource
+class RestrictedFooResource < GenericFooResource
   ignoring :id, :body
 end
 
-RestrictedFooResouce.new(foo).serialize
+RestrictedFooResource.new(foo).serialize
 # => '{"name":"my foo"}'
-end
 ```
 
 ### Key transformation
@@ -402,6 +448,20 @@ user = User.new(1, nil, nil)
 UserResource.new(user).serialize # => '{"id":1}'
 ```
 
+### Default
+
+Alba doesn't support default value for attributes, but it's easy to set a default value.
+
+```ruby
+class FooResource
+  attribute :bar do |foo|
+    foo.bar || 'default bar'
+  end
+end
+```
+
+We believe this is clearer than using some (not implemented yet) DSL such as `default` because there are some conditions where default values should be applied (`nil`, `blank?`, `empty?` etc.)
+
 ### Inference
 
 After `Alba.enable_inference!` called, Alba tries to infer root key and association resource name.
@@ -510,6 +570,54 @@ Alba.on_error do |error, object, key, attribute, resource_class|
 end
 ```
 
+### Metadata
+
+You can set a metadata with `meta` DSL or `meta` option.
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  root_key :user, :users
+
+  attributes :id, :name
+
+  meta do
+    if object.is_a?(Enumerable)
+      {size: object.size}
+    else
+      {foo: :bar}
+    end
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new([user]).serialize
+# => '{"users":[{"id":1,"name":"Masafumi OKURA"}],"meta":{"size":1}}'
+
+# You can merge metadata with `meta` option
+
+UserResource.new([user]).serialize(meta: {foo: :bar})
+# => '{"users":[{"id":1,"name":"Masafumi OKURA"}],"meta":{"size":1,"foo":"bar"}}'
+
+# You can set metadata with `meta` option alone
+
+class UserResourceWithoutMeta
+  include Alba::Resource
+
+  root_key :user, :users
+
+  attributes :id, :name
+end
+
+UserResource.new([user]).serialize(meta: {foo: :bar})
+# => '{"users":[{"id":1,"name":"Masafumi OKURA"}],"meta":{"foo":"bar"}}'
+```
+
+You can use `object` method to access the underlying object and `params` to access the params in `meta` block.
+
+Note that setting root key is required when setting a metadata.
+
 ### Circular associations control
 
 **Note that this feature works correctly since version 1.3. In previous versions it doesn't work as expected.**

data/alba.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/okuramasafumi/alba'
-  spec.metadata['changelog_uri'] = 'https://github.com/okuramasafumi/alba/blob/master/CHANGELOG.md'
+  spec.metadata['changelog_uri'] = 'https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/gemfiles/all.gemfile

@@ -11,7 +11,7 @@ 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
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'oj', '~> 3.11', require: false # For backend

data/gemfiles/without_active_support.gemfile

@@ -9,7 +9,7 @@ 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
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'oj', '~> 3.11', require: false # For backend

data/gemfiles/without_oj.gemfile

@@ -10,7 +10,7 @@ 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
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'ruby-prof', require: false # For performance profiling

data/lib/alba.rb

@@ -1,3 +1,4 @@
+require 'json'
 require_relative 'alba/version'
 require_relative 'alba/resource'
 
@@ -14,6 +15,8 @@ module Alba
 
   class << self
     attr_reader :backend, :encoder, :inferring, :_on_error, :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,24 +27,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)
+      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
@@ -63,6 +77,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
@@ -80,18 +97,32 @@ module Alba
       @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
+
     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
@@ -115,7 +146,6 @@ module Alba
 
     def default_encoder
       lambda do |hash|
-        require 'json'
         JSON.dump(hash)
       end
     end

data/lib/alba/association.rb

@@ -4,9 +4,10 @@ module Alba
   class Association
     attr_reader :object, :name
 
-    # @param name [Symbol] name of the method to fetch association
-    # @param condition [Proc] a proc filtering data
-    # @param resource [Class<Alba::Resource>] a resource class for the association
+    # @param name [Symbol, String] name of the method to fetch association
+    # @param condition [Proc, nil] a proc filtering data
+    # @param resource [Class<Alba::Resource>, nil] a resource class for the association
+    # @param nesting [String] a namespace where source class is inferred with
     # @param block [Block] used to define resource when resource arg is absent
     def initialize(name:, condition: nil, resource: nil, nesting: nil, &block)
       @name = name
@@ -31,24 +32,12 @@ module Alba
 
     def assign_resource(nesting)
       @resource = if @block
-                    resource_class
+                    Alba.resource_class(&@block)
                   elsif Alba.inferring
-                    resource_class_with_nesting(nesting)
+                    Alba.infer_resource_class(@name, nesting: nesting)
                   else
                     raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
                   end
     end
-
-    def resource_class
-      klass = Class.new
-      klass.include(Alba::Resource)
-      klass.class_eval(&@block)
-      klass
-    end
-
-    def resource_class_with_nesting(nesting)
-      const_parent = nesting.nil? ? Object : Object.const_get(nesting)
-      const_parent.const_get("#{ActiveSupport::Inflector.classify(@name)}Resource")
-    end
   end
 end

data/lib/alba/default_inflector.rb

@@ -11,7 +11,7 @@ module Alba
 
     # Camelizes a key
     #
-    # @params key [String] key to be camelized
+    # @param key [String] key to be camelized
     # @return [String] camelized key
     def camelize(key)
       ActiveSupport::Inflector.camelize(key)
@@ -19,7 +19,7 @@ module Alba
 
     # Camelizes a key, 1st letter lowercase
     #
-    # @params key [String] key to be camelized
+    # @param key [String] key to be camelized
     # @return [String] camelized key
     def camelize_lower(key)
       ActiveSupport::Inflector.camelize(key, false)
@@ -27,7 +27,7 @@ module Alba
 
     # Dasherizes a key
     #
-    # @params key [String] key to be dasherized
+    # @param key [String] key to be dasherized
     # @return [String] dasherized key
     def dasherize(key)
       ActiveSupport::Inflector.dasherize(key)

data/lib/alba/key_transform_factory.rb

@@ -4,7 +4,7 @@ module Alba
     class << self
       # Create key transform function for given transform_type
       #
-      # @params transform_type [Symbol] transform type
+      # @param transform_type [Symbol] transform type
       # @return [Proc] transform function
       # @raise [Alba::Error] when transform_type is not supported
       def create(transform_type)

data/lib/alba/resource.rb

@@ -8,7 +8,7 @@ module Alba
   module Resource
     # @!parse include InstanceMethods
     # @!parse extend ClassMethods
-    DSLS = {_attributes: {}, _key: nil, _transform_key_function: nil, _transforming_root_key: false, _on_error: nil}.freeze
+    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_key_function: nil, _transforming_root_key: false, _on_error: nil}.freeze # rubocop:disable Layout/LineLength
     private_constant :DSLS
 
     WITHIN_DEFAULT = Object.new.freeze
@@ -33,7 +33,7 @@ module Alba
 
       # @param object [Object] the object to be serialized
       # @param params [Hash] user-given Hash for arbitrary data
-      # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
+      # @param within [Object, nil, false, true] determines what associations to be serialized. If not set, it serializes all associations.
       def initialize(object, params: {}, within: WITHIN_DEFAULT)
         @object = object
         @params = params.freeze
@@ -43,11 +43,19 @@ module Alba
 
       # Serialize object into JSON string
       #
-      # @param key [Symbol]
+      # @param key [Symbol, nil, true] DEPRECATED, use root_key instead
+      # @param root_key [Symbol, nil, true]
+      # @param meta [Hash] metadata for this seialization
       # @return [String] serialized JSON string
-      def serialize(key: nil)
-        key = key.nil? ? _key : key
-        hash = key && key != '' ? {key.to_s => serializable_hash} : serializable_hash
+      def serialize(key: nil, root_key: nil, meta: {})
+        warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
+        key = key.nil? && root_key.nil? ? fetch_key : root_key || key
+        hash = if key && key != ''
+                 h = {key.to_s => serializable_hash}
+                 hash_with_metadata(h, meta)
+               else
+                 serializable_hash
+               end
         Alba.encoder.call(hash)
       end
 
@@ -61,15 +69,29 @@ module Alba
 
       private
 
+      def hash_with_metadata(hash, meta)
+        base = @_meta ? instance_eval(&@_meta) : {}
+        metadata = base.merge(meta)
+        hash[:meta] = metadata unless metadata.empty?
+        hash
+      end
+
+      def fetch_key
+        collection? ? _key_for_collection : _key
+      end
+
+      def _key_for_collection
+        return @_key_for_collection.to_s unless @_key_for_collection == true && Alba.inferring
+
+        key = resource_name.pluralize
+        transforming_root_key? ? transform_key(key) : key
+      end
+
       # @return [String]
       def _key
         return @_key.to_s unless @_key == true && Alba.inferring
 
-        transforming_root_key? ? transform_key(key_from_resource_name) : key_from_resource_name
-      end
-
-      def key_from_resource_name
-        collection? ? resource_name.pluralize : resource_name
+        transforming_root_key? ? transform_key(resource_name) : resource_name
       end
 
       def resource_name
@@ -105,14 +127,11 @@ module Alba
       def conditional_attribute(object, key, attribute)
         condition = attribute.last
         arity = condition.arity
+        # We can return early to skip fetch_attribute
         return [] if arity <= 1 && !instance_exec(object, &condition)
 
         fetched_attribute = fetch_attribute(object, attribute.first)
-        attr = if attribute.first.is_a?(Alba::Association)
-                 attribute.first.object
-               else
-                 fetched_attribute
-               end
+        attr = attribute.first.is_a?(Alba::Association) ? attribute.first.object : fetched_attribute
         return [] if arity >= 2 && !instance_exec(object, attr, &condition)
 
         [key, fetched_attribute]
@@ -121,14 +140,10 @@ module Alba
       def handle_error(error, object, key, attribute)
         on_error = @_on_error || Alba._on_error
         case on_error
-        when :raise, nil
-          raise
-        when :nullify
-          [key, nil]
-        when :ignore
-          []
-        when Proc
-          on_error.call(error, object, key, attribute, self.class)
+        when :raise, nil then raise
+        when :nullify then [key, nil]
+        when :ignore then []
+        when Proc then on_error.call(error, object, key, attribute, self.class)
         else
           raise ::Alba::Error, "Unknown on_error: #{on_error.inspect}"
         end
@@ -143,34 +158,27 @@ module Alba
 
       def fetch_attribute(object, attribute)
         case attribute
-        when Symbol
-          object.public_send attribute
-        when Proc
-          instance_exec(object, &attribute)
-        when Alba::One, Alba::Many
-          within = check_within(attribute.name.to_sym)
-          return unless within
-
-          attribute.to_hash(object, params: params, within: within)
-        when TypedAttribute
-          attribute.value(object)
+        when Symbol then object.public_send attribute
+        when Proc then instance_exec(object, &attribute)
+        when Alba::One, Alba::Many then yield_if_within(attribute.name.to_sym) { |within| attribute.to_hash(object, params: params, within: within) }
+        when TypedAttribute then attribute.value(object)
         else
           raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
         end
       end
 
+      def yield_if_within(association_name)
+        within = check_within(association_name)
+        yield(within) if within
+      end
+
       def check_within(association_name)
         case @within
-        when WITHIN_DEFAULT # Default value, doesn't check within tree
-          WITHIN_DEFAULT
-        when Hash # Traverse within tree
-          @within.fetch(association_name, nil)
-        when Array # within tree ends with Array
-          @within.find { |item| item.to_sym == association_name }
-        when Symbol # within tree could end with Symbol
-          @within == association_name
-        when nil, true, false # In these cases, Alba stops serialization here.
-          false
+        when WITHIN_DEFAULT then WITHIN_DEFAULT # Default value, doesn't check within tree
+        when Hash then @within.fetch(association_name, nil) # Traverse within tree
+        when Array then @within.find { |item| item.to_sym == association_name }
+        when Symbol then @within == association_name
+        when nil, true, false then false # Stop here
         else
           raise Alba::Error, "Unknown type for within option: #{@within.class}"
         end
@@ -191,11 +199,16 @@ module Alba
         DSLS.each_key { |name| subclass.instance_variable_set("@#{name}", instance_variable_get("@#{name}").clone) }
       end
 
+      # Defining methods for DSLs and disable parameter number check since for users' benefits increasing params is fine
+      # rubocop:disable Metrics/ParameterLists
+
       # Set multiple attributes at once
       #
       # @param attrs [Array<String, Symbol>]
-      # @param if [Boolean] condition to decide if it should render these attributes
-      # @param attrs_with_types [Hash] attributes with name in its key and type and optional type converter in its value
+      # @param if [Proc] condition to decide if it should serialize these attributes
+      # @param attrs_with_types [Hash<[Symbol, String], [Array<Symbol, Proc>, Symbol]>]
+      #   attributes with name in its key and type and optional type converter in its value
+      # @return [void]
       def attributes(*attrs, if: nil, **attrs_with_types) # rubocop:disable Naming/MethodParameterName
         if_value = binding.local_variable_get(:if)
         assign_attributes(attrs, if_value)
@@ -224,9 +237,11 @@ module Alba
       # Set an attribute with the given block
       #
       # @param name [String, Symbol] key name
-      # @param options [Hash] option hash including `if` that is a  condition to render
+      # @param options [Hash<Symbol, Proc>]
+      # @option options [Proc] if a condition to decide if this attribute should be serialized
       # @param block [Block] the block called during serialization
       # @raise [ArgumentError] if block is absent
+      # @return [void]
       def attribute(name, **options, &block)
         raise ArgumentError, 'No block given in attribute method' unless block
 
@@ -235,12 +250,14 @@ module Alba
 
       # Set One association
       #
-      # @param name [String, Symbol]
-      # @param condition [Proc]
-      # @param resource [Class<Alba::Resource>]
-      # @param key [String, Symbol] used as key when given
-      # @param options [Hash] option hash including `if` that is a  condition to render
+      # @param name [String, Symbol] name of the association, used as key when `key` param doesn't exist
+      # @param condition [Proc, nil] a Proc to modify the association
+      # @param resource [Class<Alba::Resource>, String, nil] representing resource for this association
+      # @param key [String, Symbol, nil] used as key when given
+      # @param options [Hash<Symbol, Proc>]
+      # @option options [Proc] if a condition to decide if this association should be serialized
       # @param block [Block]
+      # @return [void]
       # @see Alba::One#initialize
       def one(name, condition = nil, resource: nil, key: nil, **options, &block)
         nesting = self.name&.rpartition('::')&.first
@@ -251,12 +268,14 @@ module Alba
 
       # Set Many association
       #
-      # @param name [String, Symbol]
-      # @param condition [Proc]
-      # @param resource [Class<Alba::Resource>]
-      # @param key [String, Symbol] used as key when given
-      # @param options [Hash] option hash including `if` that is a  condition to render
+      # @param name [String, Symbol] name of the association, used as key when `key` param doesn't exist
+      # @param condition [Proc, nil] a Proc to filter the collection
+      # @param resource [Class<Alba::Resource>, String, nil] representing resource for this association
+      # @param key [String, Symbol, nil] used as key when given
+      # @param options [Hash<Symbol, Proc>]
+      # @option options [Proc] if a condition to decide if this association should be serialized
       # @param block [Block]
+      # @return [void]
       # @see Alba::Many#initialize
       def many(name, condition = nil, resource: nil, key: nil, **options, &block)
         nesting = self.name&.rpartition('::')&.first
@@ -268,14 +287,40 @@ module Alba
       # Set key
       #
       # @param key [String, Symbol]
+      # @deprecated Use {#root_key} instead
       def key(key)
+        warn '[DEPRECATION] `key` is deprecated, use `root_key` instead.'
         @_key = key.respond_to?(:to_sym) ? key.to_sym : key
       end
 
+      # Set root key
+      #
+      # @param key [String, Symbol]
+      # @param key_for_collection [String, Symbol]
+      # @raise [NoMethodError] when key doesn't respond to `to_sym` method
+      def root_key(key, key_for_collection = nil)
+        @_key = key.to_sym
+        @_key_for_collection = key_for_collection&.to_sym
+      end
+
       # Set key to true
       #
+      # @deprecated Use {#root_key!} instead
       def key!
+        warn '[DEPRECATION] `key!` is deprecated, use `root_key!` instead.'
         @_key = true
+        @_key_for_collection = true
+      end
+
+      # Set root key to true
+      def root_key!
+        @_key = true
+        @_key_for_collection = true
+      end
+
+      # Set metadata
+      def meta(&block)
+        @_meta = block
       end
 
       # Delete attributes
@@ -298,15 +343,18 @@ module Alba
       end
 
       # Set error handler
+      # If this is set it's used as a error handler overriding global one
       #
-      # @param [Symbol] handler
-      # @param [Block]
+      # @param handler [Symbol] `:raise`, `:ignore` or `:nullify`
+      # @param block [Block]
       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
 
         @_on_error = handler || block
       end
+
+      # rubocop:enable Metrics/ParameterLists
     end
   end
 end

data/lib/alba/typed_attribute.rb

@@ -28,12 +28,9 @@ module Alba
     def check(object)
       value = object.public_send(@name)
       type_correct = case @type
-                     when :String, ->(klass) { klass == String }
-                       value.is_a?(String)
-                     when :Integer, ->(klass) { klass == Integer }
-                       value.is_a?(Integer)
-                     when :Boolean
-                       [true, false].include?(value)
+                     when :String, ->(klass) { klass == String } then value.is_a?(String)
+                     when :Integer, ->(klass) { klass == Integer } then value.is_a?(Integer)
+                     when :Boolean then [true, false].include?(value)
                      else
                        raise Alba::UnsupportedType, "Unknown type: #{@type}"
                      end

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '1.3.0'.freeze
+  VERSION = '1.4.0'.freeze
 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.4.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-31 00:00:00.000000000 Z
+date: 2021-06-30 00:00:00.000000000 Z
 dependencies: []
 description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
   flexibility and usability.
@@ -22,6 +22,7 @@ files:
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".github/dependabot.yml"
 - ".github/workflows/main.yml"
+- ".github/workflows/perf.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".yardopts"
@@ -50,6 +51,7 @@ files:
 - 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:
@@ -57,7 +59,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: