alba 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c68ec07a949642b11dfd36b3bf748249d0d725178ece9dd331e373fc2339cb8a
-  data.tar.gz: 7704431d69f96b88d9632c114dae90cfceae018c8372c8736c091efd2050b65a
+  metadata.gz: 89ce66083a51c7811468f9435288afbc53f81418f21635af4393eaf1ac635d14
+  data.tar.gz: 7344d77ba35c156a6a18abe6f5ff498b7a8cd24b460c5b3f6bf1f0739bd0c8aa
 SHA512:
-  metadata.gz: 98ca1b6fa7c6851f3a69d6d1cb54cd782a3142fccfb33391eb08cbc093ad691496a8fdb9e93e5ce89543032a0003ab8b60022ca8bbbba81c73de249b571a3fa6
-  data.tar.gz: 3756fe21da92358031a722d83b7169ef81e8749ccf6430bef577dfaac7ab4a80e68c07c6e0205497e54692f74b16e66aabad390db6eda09e486a732387541630
+  metadata.gz: 33e534a676d589ba88db064b8ba57bbd10a20d268c417d8ed89fbc9b830f2861e4d3c1b46772d9151fce5dcff909e591f26f4fe1be77c247da4e1ceb4998d1cc
+  data.tar.gz: 401030ee3033228b11d2b75fa411809e7707b0c8b6791c2fe9da8bf9ce290c290225cb4e23895bc31019cc8cead19ac20335fffb24682c58ebc7f09a8250999a

data/.codeclimate.yml

@@ -9,3 +9,4 @@ checks:
 exclude_patterns:
   - "benchmark/**/*"
   - "script/**/*"
+  - "test/**/*"

data/.editorconfig

@@ -0,0 +1,10 @@
+[*]
+end_of_line              = lf
+insert_final_newline     = true
+charset                  = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size  = 2
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false

data/.rubocop.yml

@@ -1,9 +1,14 @@
 ---
 
 inherit_gem:
-  rubocop-sensible: 'config/rubocop.yml'
+  rubocop-gem_dev: 'config/rubocop.yml'
+
+inherit_mode:
+  merge:
+    - Exclude
 
 require:
+  - rubocop-md
   - rubocop-minitest
   - rubocop-performance
   - rubocop-rake
@@ -13,6 +18,7 @@ AllCops:
     - 'Rakefile'
     - 'alba.gemspec'
     - 'benchmark/**/*.rb'
+    - 'docs/**/*'
     - 'script/**/*.rb'
   NewCops: enable
   EnabledByDefault: true
@@ -22,6 +28,15 @@ AllCops:
 Bundler/GemVersion:
   Enabled: false
 
+# Test class is a class, but not really
+Layout/ClassStructure:
+  Exclude:
+    - 'test/**/*'
+
+# LineLength 80 comes from restrictions in good old days.
+Layout/LineLength:
+  Max: 160
+
 # We'd like to write something like:
 #   assert_equal(
 #     expected,
@@ -63,6 +78,11 @@ Metrics/ParameterLists:
 Minitest/EmptyLineBeforeAssertionMethods:
   Enabled: false
 
+# By nature of that test
+Minitest/NoTestCases:
+  Exclude:
+    - 'test/dependencies/test_dependencies.rb'
+
 # We need to eval resource code to test errors on resource classes
 Security/Eval:
   Exclude:
@@ -80,14 +100,26 @@ Style/Copyright:
 Style/DisableCopsWithinSourceCodeDirective:
   Enabled: false
 
+Style/Documentation:
+  Exclude:
+    - 'test/**/*'
+
+Style/DocumentationMethod:
+  Exclude:
+    - 'README.md'
+
 Style/FrozenStringLiteralComment:
   Enabled: false
 
+Style/ImplicitRuntimeError:
+  Exclude:
+    - 'README.md'
+
 Style/InlineComment:
   Enabled: false
 
 Style/MethodCallWithArgsParentheses:
-  IgnoredMethods: ['require', 'require_relative', 'include', 'extend', 'puts', 'p', 'warn', 'raise', 'send', 'public_send']
+  AllowedMethods: ['require', 'require_relative', 'include', 'extend', 'puts', 'p', 'warn', 'raise', 'send', 'public_send', 'alias_method']
   Exclude:
     # There are so many `attributes` call without parenthese and that's absolutely fine
     - 'test/**/*.rb'
@@ -95,3 +127,7 @@ Style/MethodCallWithArgsParentheses:
 # There are so many cases we just want `if` expression!
 Style/MissingElse:
   EnforcedStyle: case
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'README.md'

data/CHANGELOG.md

@@ -6,6 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] 2023-08-02
+
+### Added
+
+- Implement helper [#322](https://github.com/okuramasafumi/alba/pull/322)
+- Add `prefer_resource_method!` [#323](https://github.com/okuramasafumi/alba/pull/323)
+
+### Fixed
+
+- Fix the bug of resource name inference [No PR](https://github.com/okuramasafumi/alba/commit/dab7091efa4a76ce9e538e08efa7349c296a705c)
+
+## [2.3.0] 2023-04-24
+
+### Added
+
+- Add compatibility option for key [#304](https://github.com/okuramasafumi/alba/pull/304)
+- It now infers resource name from Serializer [#309](https://github.com/okuramasafumi/alba/pull/309)
+- `Alba.serialize` is easier to use for multiple root keys [#311](https://github.com/okuramasafumi/alba/pull/311)
+- Gives access to params in nested_attribute [#312](https://github.com/okuramasafumi/alba/pull/312)
+  - Thank you, @GabrielErbetta
+
 ## [2.2.0] 2023-02-17
 
 ### Added

data/Gemfile

@@ -10,12 +10,13 @@ gem 'minitest', '~> 5.14' # For test
 gem 'railties', require: false # For Rails integration testing
 gem 'rake', '~> 13.0' # For test and automation
 gem 'rubocop', '>= 0.79.0', require: false # For lint
+gem 'rubocop-gem_dev', '>= 0.3.0', require: false # For lint
+gem 'rubocop-md', '~> 1.0', require: false # For lint
 gem 'rubocop-minitest', '>= 0.25.0', require: false # For lint
 gem 'rubocop-performance', '>= 1.15.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 'ruby-lsp', require: false # For language server
-gem 'simplecov', '~> 0.21.0', require: false # For test coverage
+gem 'simplecov', '~> 0.22.0', require: false # For test coverage
 gem 'simplecov-cobertura', require: false # For test coverage
 # gem 'steep', require: false # For language server and typing
 # gem 'typeprof', require: false # For language server and typing

data/HACKING.md

@@ -17,6 +17,7 @@ Class methods (DSL):
 * `attribute` for block style attribute
 * `attributes` for symbol style attribute
 * `association` and its aliases such as `one` for association
+* `nested` for nested attribute
 
 Instance methods:
 
@@ -29,7 +30,7 @@ Other methods are rather trivial. They'll be added to this list when it turned o
 
 In `Alba::Resource` module there are some things to note.
 
-`@object` is an object for serialization. It's either singular object or collection.
+`@object` is an object for serialization. It's either a singular object or a collection.
 
 Attribute object can be either `Symbol`, `Proc`, `Alba::Association` or `Alba::TypedAttribute`.
 

data/README.md

@@ -11,6 +11,40 @@
 
 Alba is a JSON serializer for Ruby, JRuby, and TruffleRuby.
 
+## TL;DR
+
+Alba allows you to do something like below.
+
+```ruby
+class User
+  attr_accessor :id, :name, :email
+
+  def initialize(id, name, email)
+    @id = id
+    @name = name
+    @email = email
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  root_key :user
+
+  attributes :id, :name
+
+  attribute :name_with_email do |resource|
+    "#{resource.name}: #{resource.email}"
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new(user).serialize
+# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"Masafumi OKURA: masafumi@example.com"}}'
+```
+
+Seems useful? Continue reading!
+
 ## Discussions
 
 Alba uses [GitHub Discussions](https://github.com/okuramasafumi/alba/discussions) to openly discuss the project.
@@ -43,7 +77,7 @@ Alba is faster than most of the alternatives. We have a [benchmark](https://gith
 
 ### Easy
 
-Alba is easy to use because there are only a few methods to remember. It's also easy to understand due to clean and short codebase. Finally it's easy to extend since it provides some methods for override to change default behavior of Alba.
+Alba is easy to use because there are only a few methods to remember. It's also easy to understand due to clean and small codebase. Finally it's easy to extend since it provides some methods for override to change default behavior of Alba.
 
 ### Feature rich
 
@@ -82,7 +116,7 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 * Error handling
 * Nil handling
 * Circular associations control
-* [Experimental] Types for validation and conversion
+* Types for validation and conversion
 * Layout
 * No runtime dependencies
 
@@ -143,13 +177,27 @@ Alba.inflector = nil
 To check if inference is enabled etc, inspect the return value of `inflector`:
 
 ```ruby
-if Alba.inflector == nil
-  puts "inflector not set"
+if Alba.inflector.nil?
+  puts 'inflector not set'
 else
   puts "inflector is set to #{Alba.inflector}"
 end
 ```
 
+### Naming
+
+Alba tries to infer resource name from class name like the following.
+
+|Class name|Resource name|
+| --- | --- |
+| FooResource | Foo |
+| FooSerializer | Foo |
+| FooElse | FooElse |
+
+Resource name is used as the default name of the root key, so you might want to name it ending with "Resource" or "Serializer"
+
+When you use Alba with Rails, it's recommended to put your resource/serializer classes in corresponding directory such as `app/resources` or `app/serializers`.
+
 ### Simple serialization with root key
 
 You can define attributes with (yes) `attributes` macro with attribute names. If your attribute need some calculations, you can use `attribute` with block.
@@ -157,6 +205,7 @@ You can define attributes with (yes) `attributes` macro with attribute names. If
 ```ruby
 class User
   attr_accessor :id, :name, :email, :created_at, :updated_at
+
   def initialize(id, name, email)
     @id = id
     @name = name
@@ -220,6 +269,72 @@ class UserResource
 end
 ```
 
+#### Prefer methods on resource
+
+By default, Alba prefers methods on the object to methods on the resource. This means if you have a following situation:
+
+```ruby
+class User
+  attr_accessor :id, :name, :email
+
+  def initialize(id, name, email)
+    @id = id
+    @name = name
+    @email = email
+  end
+
+  def name_with_email
+    "dummy!"
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  root_key :user, :users # Later is for plural
+
+  attributes :id, :name, :name_with_email
+
+  # Same method exists in `User` class!
+  # This is not called
+  def name_with_email(user)
+    "#{user.name}: #{user.email}"
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new(user).serialize
+# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"dummy!"}}'
+```
+
+You can see that `name_with_email` is now `dummy!` from `User#name_with_email`. You cna change this behavior by using `prefer_resource_method!` DSL in a resource class:
+
+```ruby
+# With the same `User` class
+
+class UserResource
+  include Alba::Resource
+
+  prefer_resource_method! # This line is important
+
+  root_key :user, :users # Later is for plural
+
+  attributes :id, :name, :name_with_email
+
+  # Same method exists in `User` class!
+  # But now this is called!
+  def name_with_email(user)
+    "#{user.name}: #{user.email}"
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new(user).serialize
+# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"Masafumi OKURA: masafumi@example.com"}}'
+```
+
+The next major version of Alba will change this default behavior to prefer resource methods. In case you want to preserve current behavior, there's `prefer_object_method!` DSL, which does that.
+
 #### Params
 
 You can pass a Hash to the resource for internal use. It can be used as "flags" to control attribute content.
@@ -356,11 +471,11 @@ class UserResource
 
   # Second proc works as a filter
   many :articles,
-    proc { |articles, params, user|
-      filter = params[:filter] || :odd?
-      articles.select {|a| a.id.send(filter) && !user.banned  }
-    },
-    resource: ArticleResource
+       proc { |articles, params, user|
+         filter = params[:filter] || :odd?
+         articles.select { |a| a.id.__send__(filter) && !user.banned }
+       },
+       resource: ArticleResource
 end
 
 user = User.new(1)
@@ -384,8 +499,8 @@ class UserResource
   attributes :id
 
   many :articles,
-    key: 'my_articles', # Set key here
-    resource: ArticleResource
+       key: 'my_articles', # Set key here
+       resource: ArticleResource
 end
 UserResource.new(user).serialize
 # => '{"id":1,"my_articles":[{"title":"Hello World!"}]}'
@@ -452,7 +567,7 @@ class FooResourceWithParamsOverride
 
   root_key :foo
 
-  one :bar, resource: BarResource, params: { expose_secret: false }
+  one :bar, resource: BarResource, params: {expose_secret: false}
 end
 
 Baz = Struct.new(:data, :secret)
@@ -544,6 +659,48 @@ Alba.serialize(something)
 
 Although this might be useful sometimes, it's generally recommended to define a class for Resource.
 
+#### Inline definition for multiple root keys
+
+While Alba doesn't directly support multiple root keys, you can simulate it with `Alba.serialize`.
+
+```ruby
+# Define foo and bar local variables here
+
+Alba.serialize do
+  attribute :key1 do
+    FooResource.new(foo).to_h
+  end
+
+  attribute :key2 do
+    BarResource.new(bar).to_h
+  end
+end
+# => JSON containing "key1" and "key2" as root keys
+```
+
+Note that we must use `to_h`, not `serialize`, with resources.
+
+We can also generate a JSON with multiple root keys without making any class by the combination of `Alba.serialize` and `Alba.hashify`.
+
+```ruby
+# Define foo and bar local variables here
+
+Alba.serialize do
+  attribute :foo do
+    Alba.hashify(foo) do
+      attributes :id, :name # For example
+    end
+  end
+
+  attribute :bar do
+    Alba.hashify(bar) do
+      attributes :id
+    end
+  end
+end
+# => JSON containing "foo" and "bar" as root keys
+```
+
 ### Serializable Hash
 
 Instead of serializing to JSON, you can also output a Hash by calling `serializable_hash` or the `to_h` alias. Note also that the `serialize` method is aliased as `to_json`.
@@ -796,20 +953,15 @@ A custom inflector can be plugged in as follows.
 module CustomInflector
   module_function
 
-  def camelize(string)
-  end
+  def camelize(string); end
 
-  def camelize_lower(string)
-  end
+  def camelize_lower(string); end
 
-  def dasherize(string)
-  end
+  def dasherize(string); end
 
-  def underscore(string)
-  end
+  def underscore(string); end
 
-  def classify(string)
-  end
+  def classify(string); end
 end
 
 Alba.inflector = CustomInflector
@@ -926,7 +1078,7 @@ class User
   end
 
   def email
-    raise RuntimeError, 'Error!'
+    raise 'Error!'
   end
 end
 
@@ -1018,6 +1170,11 @@ UserResource.new(User.new(1)).serialize
 # => '{"user":{"id":1,"name":"User1","age":20}}'
 ```
 
+Note that `on_nil` does NOT work when the given object itself is `nil`. There are a few possible ways to deal with `nil`.
+
+- Use `if` statement and avoid using Alba when the object is `nil`
+- Use "Null Object" pattern
+
 ### Metadata
 
 You can set a metadata with `meta` DSL or `meta` option.
@@ -1122,8 +1279,10 @@ Sometimes we want to serialize a collection into a Hash, not an Array. It's poss
 ```ruby
 class User
   attr_reader :id, :name
+
   def initialize(id, name)
-    @id, @name = id, name
+    @id = id
+    @name = name
   end
 end
 
@@ -1179,12 +1338,12 @@ In case you don't want to have a file for layout, Alba lets you define and apply
 ```ruby
 class FooResource
   include Alba::Resource
-  layout inline: proc do
+  layout inline: proc {
     {
       header: 'my header',
       body: serializable_hash
     }
-  end
+  }
 end
 ```
 
@@ -1195,12 +1354,12 @@ You can also use a Proc which returns String, not a Hash, for an inline layout.
 ```ruby
 class FooResource
   include Alba::Resource
-  layout inline: proc do
+  layout inline: proc {
     %({
       "header": "my header",
       "body": #{serialized_json}
     })
-  end
+  }
 end
 ```
 
@@ -1208,6 +1367,49 @@ It looks similar to file layout but you must use string interpolation for method
 
 Also note that we use percentage notation here to use double quotes. Using single quotes in inline string layout causes the error which might be resolved in other ways.
 
+### Helper
+
+Inheritance works well in most of the cases to share behaviors. One of the exceptions is when you want to shared behaviors with inline association. For example:
+
+```ruby
+class ApplicationResource
+  include Alba::Resource
+
+  def self.with_id
+    attributes :id
+  end
+end
+
+class LibraryResource < ApplicationResource
+  with_id
+  attributes :created_at
+
+  with_many :library_books do
+    with_id # This DOES NOT work!
+    attributes :created_at
+  end
+end
+```
+
+This doesn't work. Technically, inside of `has_many` is a separate class which doesn't inherit from the base class (`LibraryResource` in this example).
+
+`helper` solves this problem. It's just a mark for methods that should be shared with inline associations.
+
+```ruby
+class ApplicationResource
+  include Alba::Resource
+
+  helper do
+    def with_id
+      attributes :id
+    end
+  end
+end
+# Now `LibraryResource` works!
+```
+
+Within `helper` block, all methods should be defined without `self.`.
+
 ### 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).
@@ -1289,8 +1491,8 @@ module AlbaExtension
   # Here attrs are an Array of Symbol
   def formatted_time_attributes(*attrs)
     attrs.each do |attr|
-      attribute attr do |object|
-        time = object.send(attr)
+      attribute(attr) do |object|
+        time = object.__send__(attr)
         time.strftime('%m/%d/%Y')
       end
     end
@@ -1347,13 +1549,14 @@ Alba currently doesn't support logging directly, but you can add your own loggin
 
 ```ruby
 module Logging
-  def serialize(...) # `...` was added in Ruby 2.7
+  # `...` was added in Ruby 2.7
+  def serialize(...)
     puts serializable_hash
     super(...)
   end
 end
 
-FooResource.prepend Logging
+FooResource.prepend(Logging)
 FooResource.new(foo).serialize
 # => "{:id=>1}" is printed
 ```

data/alba.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
 
   spec.metadata = {
-    'bug_tracker_uri' => 'https://github.com/okuramasafumi/issues',
+    'bug_tracker_uri' => 'https://github.com/okuramasafumi/alba/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',

data/benchmark/README.md

@@ -10,72 +10,76 @@ Machine spec:
 
 |Key|Value|
 |---|---|
-|OS|macOS 12.2.1|
+|OS|macOS 13.2.1|
 |CPU|Intel Corei7 Quad Core 2.3Ghz|
 |RAM|32GB|
-|Ruby|ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-darwin19]|
+|Ruby|ruby 3.2.1 (2023-02-08 revision 31819e82c8) [x86_64-darwin21]|
+
+Library versions:
+
+|Library|Version|
+|---|---|
+|alba|2.2.0|
+|blueprinter|0.25.3|
+|fast_serializer_ruby|0.6.9|
+|jserializer|0.2.1|
+|oj|3.14.2|
+|simple_ams|0.2.6|
+|representable|3.2.0|
+|turbostreamer|1.10.0|
+|jbuilder|2.11.5|
+|panko_serializer|0.7.9|
+|active_model_serializers|0.10.13|
 
 `benchmark-ips` with `Oj.optimize_rails`:
 
 ```
 Comparison:
-               panko:      267.6 i/s
-               rails:      111.2 i/s - 2.41x  (± 0.00) slower
-         jserializer:      106.2 i/s - 2.52x  (± 0.00) slower
-                alba:      102.8 i/s - 2.60x  (± 0.00) slower
-       turbostreamer:       99.9 i/s - 2.68x  (± 0.00) slower
-            jbuilder:       90.7 i/s - 2.95x  (± 0.00) slower
-         alba_inline:       90.0 i/s - 2.97x  (± 0.00) slower
-           primalize:       82.1 i/s - 3.26x  (± 0.00) slower
-     fast_serializer:       62.7 i/s - 4.27x  (± 0.00) slower
- jsonapi_same_format:       59.5 i/s - 4.50x  (± 0.00) slower
-             jsonapi:       55.3 i/s - 4.84x  (± 0.00) slower
-         blueprinter:       54.1 i/s - 4.95x  (± 0.00) slower
-       representable:       35.9 i/s - 7.46x  (± 0.00) slower
-          simple_ams:       25.4 i/s - 10.53x  (± 0.00) slower
-                 ams:        9.1 i/s - 29.39x  (± 0.00) slower
+               panko:      310.4 i/s
+         jserializer:      120.6 i/s - 2.57x  slower
+       turbostreamer:      117.3 i/s - 2.65x  slower
+               rails:      114.0 i/s - 2.72x  slower
+         alba_inline:       99.3 i/s - 3.13x  slower
+                alba:       94.1 i/s - 3.30x  slower
+     fast_serializer:       67.8 i/s - 4.58x  slower
+         blueprinter:       57.6 i/s - 5.39x  slower
+       representable:       36.3 i/s - 8.56x  slower
+          simple_ams:       23.3 i/s - 13.32x  slower
+                 ams:       10.9 i/s - 28.53x  slower
 ```
 
 `benchmark-ips` without `Oj.optimize_rails`:
 
 ```
 Comparison:
-               panko:      283.8 i/s
-       turbostreamer:      102.9 i/s - 2.76x  (± 0.00) slower
-                alba:      102.4 i/s - 2.77x  (± 0.00) slower
-         alba_inline:       98.7 i/s - 2.87x  (± 0.00) slower
-         jserializer:       93.3 i/s - 3.04x  (± 0.00) slower
-     fast_serializer:       60.1 i/s - 4.73x  (± 0.00) slower
-         blueprinter:       53.8 i/s - 5.28x  (± 0.00) slower
-               rails:       37.1 i/s - 7.65x  (± 0.00) slower
-            jbuilder:       37.1 i/s - 7.66x  (± 0.00) slower
-           primalize:       31.2 i/s - 9.08x  (± 0.00) slower
- jsonapi_same_format:       28.3 i/s - 10.03x  (± 0.00) slower
-       representable:       27.8 i/s - 10.23x  (± 0.00) slower
-             jsonapi:       27.5 i/s - 10.34x  (± 0.00) slower
-          simple_ams:       16.9 i/s - 16.75x  (± 0.00) slower
-                 ams:        8.3 i/s - 34.36x  (± 0.00) slower
+               panko:      326.1 i/s
+       turbostreamer:      120.6 i/s - 2.70x  slower
+         jserializer:      119.2 i/s - 2.74x  slower
+         alba_inline:      104.3 i/s - 3.13x  slower
+                alba:      102.2 i/s - 3.19x  slower
+     fast_serializer:       66.9 i/s - 4.88x  slower
+         blueprinter:       56.7 i/s - 5.75x  slower
+               rails:       33.9 i/s - 9.63x  slower
+       representable:       30.3 i/s - 10.77x  slower
+          simple_ams:       16.4 i/s - 19.84x  slower
+                 ams:        9.4 i/s - 34.56x  slower
 ```
 
 `benchmark-memory`:
 
 ```
 Comparison:
-               panko:     230418 allocated
-                alba:     733217 allocated - 3.18x more
-         alba_inline:     748297 allocated - 3.25x more
-       turbostreamer:     781008 allocated - 3.39x more
-         jserializer:     819705 allocated - 3.56x more
-           primalize:    1195163 allocated - 5.19x more
-     fast_serializer:    1232385 allocated - 5.35x more
-               rails:    1236761 allocated - 5.37x more
-         blueprinter:    1588937 allocated - 6.90x more
-            jbuilder:    1774157 allocated - 7.70x more
- jsonapi_same_format:    2132489 allocated - 9.25x more
-             jsonapi:    2279958 allocated - 9.89x more
-       representable:    2869166 allocated - 12.45x more
-                 ams:    4473161 allocated - 19.41x more
-          simple_ams:    7868345 allocated - 34.15x more
+               panko:     242426 allocated
+       turbostreamer:     817568 allocated - 3.37x more
+         jserializer:     831705 allocated - 3.43x more
+                alba:    1072217 allocated - 4.42x more
+         alba_inline:    1084889 allocated - 4.48x more
+     fast_serializer:    1244385 allocated - 5.13x more
+               rails:    1272761 allocated - 5.25x more
+         blueprinter:    1680137 allocated - 6.93x more
+       representable:    2892425 allocated - 11.93x more
+                 ams:    4479569 allocated - 18.48x more
+          simple_ams:    6957913 allocated - 28.70x more
 ```
 
-Conclusion: panko is extremely fast but it's a C extension gem. As pure Ruby gems, Alba, turbostreamer and jserializer are notably faster than others. With `Oj.optimize_rails` jbuilder and Rails standard serialization are also fast.
+Conclusion: panko is extremely fast but it's a C extension gem. As pure Ruby gems, Alba, `turbostreamer` and `jserializer` are notably faster than others, but Alba is slightly slower than other two. With `Oj.optimize_rails`, `jbuilder` and Rails standard serialization are also fast.

data/docs/rails.md

@@ -14,11 +14,13 @@ You might want to add some configurations to initializer file such as `alba.rb`
 ```ruby
 # alba.rb
 Alba.backend = :active_support
-Alba.enable_inference!(with: :active_support)
+Alba.inflector = :active_support
 ```
 
 You can also use `:oj_rails` for backend if you prefer using Oj.
 
+Alba 2.2 introduced new Rails integration so that you don't have to add initializer file for setting inflector. You still need to add initializer file if you want to set backend or configure inflector with something different from `active_support`.
+
 ## Rendering JSON
 
 You can render JSON with Rails in two ways. One way is to pass JSON String.

data/lib/alba/association.rb

@@ -1,8 +1,10 @@
 module Alba
   # Representing association
+  # @api private
   class Association
     @const_cache = {}
     class << self
+      # cache for `const_get`
       attr_reader :const_cache
     end
 
@@ -14,15 +16,16 @@ module Alba
     # @param params [Hash] params override for the association
     # @param nesting [String] a namespace where source class is inferred with
     # @param key_transformation [Symbol] key transformation type
+    # @param helper [Module] helper module to include
     # @param block [Block] used to define resource when resource arg is absent
-    def initialize(name:, condition: nil, resource: nil, params: {}, nesting: nil, key_transformation: :none, &block)
+    def initialize(name:, condition: nil, resource: nil, params: {}, nesting: nil, key_transformation: :none, helper: nil, &block)
       @name = name
       @condition = condition
       @resource = resource
       @params = params
       return if @resource
 
-      assign_resource(nesting, key_transformation, block)
+      assign_resource(nesting, key_transformation, block, helper)
     end
 
     # Recursively converts an object into a Hash
@@ -32,7 +35,7 @@ module Alba
     # @param params [Hash] user-given Hash for arbitrary data
     # @return [Hash]
     def to_h(target, within: nil, params: {})
-      params = params.merge(@params) unless @params.empty?
+      params = params.merge(@params)
       @object = target.__send__(@name)
       @object = @condition.call(object, params, target) if @condition
       return if @object.nil?
@@ -59,9 +62,10 @@ module Alba
       end
     end
 
-    def assign_resource(nesting, key_transformation, block)
+    def assign_resource(nesting, key_transformation, block, helper) # rubocop:disable Metrics/MethodLength
       @resource = if block
                     klass = Alba.resource_class
+                    klass.helper(helper) if helper
                     klass.transform_keys(key_transformation)
                     klass.class_eval(&block)
                     klass

data/lib/alba/conditional_attribute.rb

@@ -3,6 +3,7 @@ require_relative 'constants'
 
 module Alba
   # Represents attribute with `if` option
+  # @api private
   class ConditionalAttribute
     # @param body [Symbol, Proc, Alba::Association, Alba::TypedAttribute] real attribute wrapped with condition
     # @param condition [Symbol, Proc] condition to check
@@ -20,7 +21,7 @@ module Alba
       return Alba::REMOVE_KEY unless condition_passes?(resource, object)
 
       fetched_attribute = yield(@body)
-      return fetched_attribute if !with_two_arity_proc_condition
+      return fetched_attribute unless with_two_arity_proc_condition
 
       return Alba::REMOVE_KEY unless resource.instance_exec(object, attribute_from_association_body_or(fetched_attribute), &@condition)
 

data/lib/alba/default_inflector.rb

@@ -2,7 +2,7 @@ begin
   require 'active_support/inflector'
   require 'active_support/core_ext/module/delegation'
 rescue LoadError
-  raise ::Alba::Error, 'To use default inflector, please install `ActiveSupport` gem.'
+  raise Alba::Error, 'To use default inflector, please install `ActiveSupport` gem.'
 end
 
 module Alba
@@ -11,6 +11,18 @@ module Alba
   # Another is that `ActiveSupport::Inflector` doesn't have `camelize_lower` method that we want it to have, so this module works as an adapter.
   module DefaultInflector
     class << self
+      # @!method camelize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize ActiveSupport::Inflector#camelize
+      # @!method dasherize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-dasherize ActiveSupport::Inflector#dasherize
+      # @!method underscore(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore ActiveSupport::Inflector#underscore
+      # @!method classify(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-classify ActiveSupport::Inflector#classify
+      # @!method demodulize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-demodulize ActiveSupport::Inflector#demodulize
+      # @!method pluralize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-pluralize ActiveSupport::Inflector#pluralize
       delegate :camelize, :dasherize, :underscore, :classify, :demodulize, :pluralize, to: ActiveSupport::Inflector
     end
 

data/lib/alba/deprecation.rb

@@ -1,7 +1,8 @@
 module Alba
   # Module for printing deprecation warning
+  # @api private
   module Deprecation
-    # Similar to {Kernel.warn} but prints caller as well
+    # Similar to {#warn} but prints caller as well
     #
     # @param message [String] main message to print
     # @return void

data/lib/alba/layout.rb

@@ -3,6 +3,7 @@ require 'forwardable'
 
 module Alba
   # Layout serialization
+  # @api private
   class Layout
     extend Forwardable
 

data/lib/alba/nested_attribute.rb

@@ -1,5 +1,6 @@
 module Alba
   # Representing nested attribute
+  # @api private
   class NestedAttribute
     # @param key_transformation [Symbol] determines how to transform keys
     # @param block [Proc] class body
@@ -8,12 +9,14 @@ module Alba
       @block = block
     end
 
-    # @return [Hash]
-    def value(object)
+    # @param object [Object] the object being serialized
+    # @param params [Hash] params Hash inherited from Resource
+    # @return [Hash] hash serialized from running the class body in the object
+    def value(object:, params:)
       resource_class = Alba.resource_class
       resource_class.transform_keys(@key_transformation)
       resource_class.class_eval(&@block)
-      resource_class.new(object).serializable_hash
+      resource_class.new(object, params: params).serializable_hash
     end
   end
 end

data/lib/alba/resource.rb

@@ -11,21 +11,27 @@ module Alba
   module Resource
     # @!parse include InstanceMethods
     # @!parse extend ClassMethods
-    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_type: :none, _transforming_root_key: false, _key_transformation_cascade: true, _on_error: nil, _on_nil: nil, _layout: nil, _collection_key: nil}.freeze # rubocop:disable Layout/LineLength
+    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_type: :none, _transforming_root_key: false, _key_transformation_cascade: true, _on_error: nil, _on_nil: nil, _layout: nil, _collection_key: nil, _helper: nil}.freeze # rubocop:disable Layout/LineLength
     private_constant :DSLS
 
     WITHIN_DEFAULT = Object.new.freeze
     private_constant :WITHIN_DEFAULT
 
+    # `setup` method is meta-programmatically defined here for performance.
     # @private
-    def self.included(base)
+    def self.included(base) # rubocop:disable Metrics/MethodLength
       super
+      setup_method_body = 'private def _setup;'
       base.class_eval do
         # Initialize
         DSLS.each do |name, initial|
           instance_variable_set("@#{name}", initial.dup) unless instance_variable_defined?("@#{name}")
+          setup_method_body << "@#{name} = self.class.#{name};"
         end
+        base.define_method(:encode, Alba.encoder)
       end
+      setup_method_body << 'end'
+      base.class_eval(setup_method_body, __FILE__, __LINE__ + 1)
       base.include InstanceMethods
       base.extend ClassMethods
     end
@@ -41,7 +47,7 @@ module Alba
         @object = object
         @params = params
         @within = within
-        DSLS.each_key { |name| instance_variable_set("@#{name}", self.class.__send__(name)) }
+        _setup
       end
 
       # Serialize object into JSON string
@@ -74,13 +80,14 @@ module Alba
         end
       end
 
-      # Returns a Hash correspondng {Resource#serialize}
+      # Returns a Hash correspondng {#serialize}
       #
       # @param root_key [Symbol, nil, true]
       # @param meta [Hash] metadata for this seialization
       # @return [Hash]
       def as_json(root_key: nil, meta: {})
-        key = root_key.nil? ? fetch_key : root_key.to_s
+        key = root_key.nil? ? fetch_key : root_key
+        key = Alba.regularize_key(key)
         if key && !key.empty?
           h = {key => serializable_hash}
           hash_with_metadata(h, meta)
@@ -99,15 +106,9 @@ module Alba
 
       private
 
-      def encode(hash)
-        Alba.encoder.call(hash)
-      end
-
       def _to_json(root_key, meta, options)
         options.reject! { |k, _| %i[layout prefixes template status].include?(k) } # Rails specific guard
-        # TODO: use `filter_map` after dropping support of Ruby 2.6
-        names = options.map { |k, v| k unless v.nil? }
-        names.compact!
+        names = options.filter_map { |k, v| k unless v.nil? }
         unless names.empty?
           names.sort!
           names.map! { |s| "\"#{s}\"" }
@@ -134,7 +135,11 @@ module Alba
 
       def serializable_hash_for_collection
         if @_collection_key
-          @object.to_h { |item| [item.public_send(@_collection_key).to_s, converter.call(item)] }
+          @object.to_h do |item|
+            k = item.public_send(@_collection_key)
+            key = Alba.regularize_key(k)
+            [key, converter.call(item)]
+          end
         else
           @object.each_with_object([], &collection_converter)
         end
@@ -147,34 +152,26 @@ module Alba
       end
 
       def _key_for_collection
-        if Alba.inflector
-          @_key_for_collection == true ? resource_name(pluralized: true) : @_key_for_collection.to_s
-        else
-          @_key_for_collection == true ? raise_root_key_inference_error : @_key_for_collection.to_s
-        end
+        k = @_key_for_collection == true ? resource_name(pluralized: true) : @_key_for_collection
+        Alba.regularize_key(k)
       end
 
-      # @return [String]
       def _key
-        if Alba.inflector
-          @_key == true ? resource_name(pluralized: false) : @_key.to_s
-        else
-          @_key == true ? raise_root_key_inference_error : @_key.to_s
-        end
+        k = @_key == true ? resource_name(pluralized: false) : @_key
+        Alba.regularize_key(k)
       end
 
       def resource_name(pluralized: false)
-        class_name = self.class.name
         inflector = Alba.inflector
-        name = inflector.demodulize(class_name).delete_suffix('Resource')
+        raise Alba::Error, 'You must set inflector when setting root key as true.' unless inflector
+
+        class_name = self.class.name
+        suffix = class_name.end_with?('Resource') ? 'Resource' : 'Serializer'
+        name = inflector.demodulize(class_name).delete_suffix(suffix)
         underscore_name = inflector.underscore(name)
         pluralized ? inflector.pluralize(underscore_name) : underscore_name
       end
 
-      def raise_root_key_inference_error
-        raise Alba::Error, 'You must set inflector when setting root key as true.'
-      end
-
       def transforming_root_key?
         @_transforming_root_key
       end
@@ -237,14 +234,16 @@ module Alba
         end
       end
 
-      # @return [Symbol]
-      def transform_key(key) # rubocop:disable Metrics/CyclomaticComplexity
-        key = key.to_s
-        return key if @_transform_type == :none || key.empty? # We can skip transformation
+      def transform_key(key)
+        return Alba.regularize_key(key) if @_transform_type == :none || key.nil? || key.empty? # We can skip transformation
 
         inflector = Alba.inflector
         raise Alba::Error, 'Inflector is nil. You must set inflector before transforming keys.' unless inflector
 
+        Alba.regularize_key(_transform_key(inflector, key.to_s))
+      end
+
+      def _transform_key(inflector, key)
         case @_transform_type # rubocop:disable Style/MissingElse
         when :camel then inflector.camelize(key)
         when :lower_camel then inflector.camelize_lower(key)
@@ -258,20 +257,31 @@ module Alba
                 when Symbol then fetch_attribute_from_object_and_resource(obj, attribute)
                 when Proc then instance_exec(obj, &attribute)
                 when Alba::Association then yield_if_within(attribute.name.to_sym) { |within| attribute.to_h(obj, params: params, within: within) }
-                when TypedAttribute, NestedAttribute then attribute.value(obj)
+                when TypedAttribute then attribute.value(obj)
+                when NestedAttribute then attribute.value(object: obj, params: params)
                 when ConditionalAttribute then attribute.with_passing_condition(resource: self, object: obj) { |attr| fetch_attribute(obj, key, attr) }
-                else
-                  raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
+                else raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
                 end
         value.nil? && nil_handler ? instance_exec(obj, key, attribute, &nil_handler) : value
       end
 
+      # TODO: from version 3, `_fetch_attribute_from_resource_first` is default
       def fetch_attribute_from_object_and_resource(obj, attribute)
+        _fetch_attribute_from_object_first(obj, attribute)
+      end
+
+      def _fetch_attribute_from_object_first(obj, attribute)
         obj.__send__(attribute)
       rescue NoMethodError
         __send__(attribute, obj)
       end
 
+      def _fetch_attribute_from_resource_first(obj, attribute)
+        __send__(attribute, obj)
+      rescue NoMethodError
+        obj.__send__(attribute)
+      end
+
       def nil_handler
         @_on_nil
       end
@@ -327,8 +337,9 @@ module Alba
 
       def assign_attributes(attrs, if_value)
         attrs.each do |attr_name|
-          attr = if_value ? ConditionalAttribute.new(body: attr_name.to_sym, condition: if_value) : attr_name.to_sym
-          @_attributes[attr_name.to_sym] = attr
+          attr_name = attr_name.to_sym
+          attr = if_value ? ConditionalAttribute.new(body: attr_name, condition: if_value) : attr_name
+          @_attributes[attr_name] = attr
         end
       end
       private :assign_attributes
@@ -373,8 +384,7 @@ module Alba
       def association(name, condition = nil, resource: nil, key: nil, params: {}, **options, &block)
         key_transformation = @_key_transformation_cascade ? @_transform_type : :none
         assoc = Association.new(
-          name: name, condition: condition, resource: resource, params: params, nesting: nesting, key_transformation: key_transformation,
-&block
+          name: name, condition: condition, resource: resource, params: params, nesting: nesting, key_transformation: key_transformation, helper: @_helper, &block
         )
         @_attributes[key&.to_sym || name.to_sym] = options[:if] ? ConditionalAttribute.new(body: assoc, condition: options[:if]) : assoc
       end
@@ -387,7 +397,7 @@ module Alba
         if name.nil?
           nil
         else
-          name.rpartition('::').first.tap { |n| n.empty? ? nil : n }
+          name.rpartition('::').first.then { |n| n.empty? ? nil : n }
         end
       end
       private :nesting
@@ -502,6 +512,25 @@ module Alba
       def on_nil(&block)
         @_on_nil = block
       end
+
+      # Define helper methods
+      #
+      # @param mod [Module] a module to extend
+      def helper(mod = @_helper || Module.new, &block)
+        mod.module_eval(&block) if block
+        extend mod
+        @_helper = mod
+      end
+
+      # DSL for alias, purely for readability
+      def prefer_resource_method!
+        alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_resource_first
+      end
+
+      # DSL for alias, purely for readability
+      def prefer_object_method!
+        alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_object_first
+      end
     end
   end
 end

data/lib/alba/typed_attribute.rb

@@ -1,5 +1,6 @@
 module Alba
   # Representing typed attributes to encapsulate logic about types
+  # @api private
   class TypedAttribute
     # @param name [Symbol, String]
     # @param type [Symbol, Class]

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '2.2.0'.freeze
+  VERSION = '2.4.0'.freeze
 end

data/lib/alba.rb

@@ -44,19 +44,29 @@ module Alba
     # @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, root_key: nil, &block)
-      klass = block ? resource_class(&block) : infer_resource_class(object.class.name)
-
-      resource = klass.new(object)
+    def serialize(object = nil, root_key: nil, &block)
+      resource = resource_with(object, &block)
       resource.serialize(root_key: root_key)
     end
 
+    # Hashify the object with inline definitions
+    #
+    # @param object [Object] the object to be serialized
+    # @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 hashify(object = nil, root_key: nil, &block)
+      resource = resource_with(object, &block)
+      resource.as_json(root_key: root_key)
+    end
+
     # Enable inference for key and resource name
     #
     # @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
-    # @deprecated Use {#inflector=} instead
+    # @deprecated Use {.inflector=} instead
     def enable_inference!(with:)
       Alba::Deprecation.warn('Alba.enable_inference! is deprecated. Use `Alba.inflector=` instead.')
       @inflector = inflector_from(with)
@@ -65,14 +75,14 @@ module Alba
 
     # Disable inference for key and resource name
     #
-    # @deprecated Use {#inflector=} instead
+    # @deprecated Use {.inflector=} instead
     def disable_inference!
       Alba::Deprecation.warn('Alba.disable_inference! is deprecated. Use `Alba.inflector = nil` instead.')
       @inferring = false
       @inflector = nil
     end
 
-    # @deprecated Use {#inflector} instead
+    # @deprecated Use {.inflector} instead
     # @return [Boolean] whether inference is enabled or not
     def inferring
       Alba::Deprecation.warn('Alba.inferring is deprecated. Use `Alba.inflector` instead.')
@@ -107,16 +117,45 @@ module Alba
       const_parent.const_get("#{inflector.classify(name)}Resource")
     end
 
+    # Configure Alba to symbolize keys
+    def symbolize_keys!
+      @symbolize_keys = true
+    end
+
+    # Configure Alba to stringify (not symbolize) keys
+    def stringify_keys!
+      @symbolize_keys = false
+    end
+
+    # Regularize key to be either Symbol or String depending on @symbolize_keys
+    # Returns nil if key is nil
+    #
+    # @param key [String, Symbol, nil]
+    # @return [Symbol, String, nil]
+    def regularize_key(key)
+      return if key.nil?
+
+      @symbolize_keys ? key.to_sym : key.to_s
+    end
+
     # Reset config variables
     # Useful for test cleanup
     def reset!
       @encoder = default_encoder
+      @symbolize_keys = false
       @_on_error = :raise
       @_on_nil = nil
     end
 
     private
 
+    # This method could be part of public API, but for now it's private
+    def resource_with(object, &block)
+      klass = block ? resource_class(&block) : infer_resource_class(object.class.name)
+
+      klass.new(object)
+    end
+
     def inflector_from(name_or_module)
       case name_or_module
       when nil then nil
@@ -126,8 +165,7 @@ module Alba
       when :dry
         require 'dry/inflector'
         Dry::Inflector.new
-      else
-        validate_inflector(name_or_module)
+      else validate_inflector(name_or_module)
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-17 00:00:00.000000000 Z
+date: 2023-08-01 00:00:00.000000000 Z
 dependencies: []
 description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
   flexibility and usability.
@@ -19,6 +19,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".codeclimate.yml"
+- ".editorconfig"
 - ".github/ISSUE_TEMPLATE/bug_report.md"
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".github/dependabot.yml"
@@ -71,7 +72,7 @@ homepage: https://github.com/okuramasafumi/alba
 licenses:
 - MIT
 metadata:
-  bug_tracker_uri: https://github.com/okuramasafumi/issues
+  bug_tracker_uri: https://github.com/okuramasafumi/alba/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
@@ -91,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.