alba 0.10.2 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5b12eead5b50b0e426952a2318fa85d852326a078fa5e285dc7a402ee19688d
-  data.tar.gz: 89dc5fb1295528255ba028e2dfd8e30a2c136ff8a2ac9b9fb65b869a259f9435
+  metadata.gz: 993f4b887c19f4e1149ddb850cd07a8cb8c2042cde0fb3974b1380537707a55d
+  data.tar.gz: acf77a0aa35f7fe23fc3f98843064d2800e0b4e0739e587dd29aab65f06269ad
 SHA512:
-  metadata.gz: c7d13ca3b2c592e97501cfb79de3aba84eb9ffeb107099bccde9a55a81b6bd36c93e9acda83d237b1e36de8dc34b3bb5aabbad68c7dd09cb998a5482d11f86f3
-  data.tar.gz: 8e9ab49f10f5f09669ffc27135d9fe5fe57da8b5d9e57cd7d250d661d7f5cc0f9453992c78d8db3fbd8c08ed22b4b058266faf63977f95668481151a42434d97
+  metadata.gz: 9b8e52dcaf4ca33cba0685c2a0a06c16df69cd04b6d399c092e920548f5baa6a21aeab8097f90e92ab35ac9c260d83858c19462a9ec2a689d97c6999daef5e3a
+  data.tar.gz: e525a66c30477cab6741436128398a6f0309a0f786040fe946a9f2783d08f619df00d85157d04c5876cc579e19cceabf22dcb3556addf6ad061d44d1f0cfa888

data/.github/workflows/main.yml

@@ -0,0 +1,25 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        ruby: [2.5, 2.6, 2.7, 3.0, head, truffleruby]
+        exclude:
+          - os: windows-latest
+            ruby: truffleruby
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run the default task
+      run: |
+        bundle exec rake

data/.rubocop.yml

@@ -6,11 +6,13 @@ inherit_gem:
 require:
   - rubocop-minitest
   - rubocop-performance
+  - rubocop-rake
 
 AllCops:
   Exclude:
     - 'Rakefile'
     - 'alba.gemspec'
+    - 'benchmark/**/*.rb'
   NewCops: enable
   EnabledByDefault: true
 
@@ -18,9 +20,6 @@ AllCops:
 Bundler/GemComment:
   Enabled: false
 
-Layout/ClassStructure:
-  Enabled: true
-
 Layout/SpaceInsideHashLiteralBraces:
   EnforcedStyle: no_space
 
@@ -38,12 +37,14 @@ Metrics/MethodLength:
   Max: 15
 
 Style/ConstantVisibility:
-  Enabled: false
+  Exclude:
+    - 'lib/alba/version.rb'
 
 Style/Copyright:
   Enabled: false
 
-Style/DocumentationMethod:
+# I know what I do :)
+Style/DisableCopsWithinSourceCodeDirective:
   Enabled: false
 
 Style/FrozenStringLiteralComment:

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--exclude lib/alba/version.rb

data/Gemfile

@@ -5,10 +5,12 @@ gemspec
 
 gem 'activesupport', require: false # For backend
 gem 'coveralls', require: false # For test coverage
-gem 'minitest', '~> 5.0' # For test
-gem 'oj', '~> 3.10', platform: :ruby, require: false # For backend
+gem 'minitest', '~> 5.14' # For test
+gem 'oj', '~> 3.11', platform: :ruby, require: false # For backend
 gem 'rake', '~> 13.0' # For test and automation
 gem 'rubocop', '>= 0.79.0', require: false # For lint
-gem 'rubocop-minitest', '~> 0.10.1', require: false # For lint
-gem 'rubocop-performance', '~> 1.7.1', require: false # For lint
+gem 'rubocop-minitest', '~> 0.10.3', require: false # For lint
+gem 'rubocop-performance', '~> 1.10.1', 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 'yard', require: false

data/Gemfile.lock

@@ -1,20 +1,19 @@
 PATH
   remote: .
   specs:
-    alba (0.10.2)
+    alba (0.13.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.3.2)
+    activesupport (6.1.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    ast (2.4.1)
-    bigdecimal (2.0.0)
-    concurrent-ruby (1.1.6)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    concurrent-ruby (1.1.8)
     coveralls (0.8.23)
       json (>= 1.8, < 3)
       simplecov (~> 0.16.1)
@@ -22,37 +21,39 @@ GEM
       thor (>= 0.19.4, < 2.0)
       tins (~> 1.6)
     docile (1.3.2)
-    i18n (1.8.5)
+    i18n (1.8.9)
       concurrent-ruby (~> 1.0)
     json (2.3.1)
-    minitest (5.14.1)
-    oj (3.10.12)
-      bigdecimal (>= 1.0, < 3)
-    parallel (1.19.2)
-    parser (2.7.1.4)
+    minitest (5.14.3)
+    oj (3.11.2)
+    parallel (1.20.1)
+    parser (3.0.0.0)
       ast (~> 2.4.1)
     rainbow (3.0.0)
-    rake (13.0.1)
-    regexp_parser (1.7.1)
+    rake (13.0.3)
+    regexp_parser (2.1.1)
     rexml (3.2.4)
-    rubocop (0.89.1)
+    rubocop (1.11.0)
       parallel (~> 1.10)
-      parser (>= 2.7.1.1)
+      parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.7)
+      regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 0.3.0, < 1.0)
+      rubocop-ast (>= 1.2.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (0.3.0)
-      parser (>= 2.7.1.4)
-    rubocop-minitest (0.10.1)
-      rubocop (>= 0.87)
-    rubocop-performance (1.7.1)
-      rubocop (>= 0.82.0)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.4.1)
+      parser (>= 2.7.1.5)
+    rubocop-minitest (0.10.3)
+      rubocop (>= 0.87, < 2.0)
+    rubocop-performance (1.10.1)
+      rubocop (>= 0.90.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rake (0.5.1)
+      rubocop
     rubocop-sensible (0.3.0)
       rubocop (>= 0.60.0)
-    ruby-progressbar (1.10.1)
+    ruby-progressbar (1.11.0)
     simplecov (0.16.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
@@ -62,13 +63,13 @@ GEM
     term-ansicolor (1.7.1)
       tins (~> 1.0)
     thor (1.0.1)
-    thread_safe (0.3.6)
     tins (1.25.0)
       sync
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.7.0)
-    zeitwerk (2.4.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.0.0)
+    yard (0.9.26)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
@@ -77,13 +78,15 @@ DEPENDENCIES
   activesupport
   alba!
   coveralls
-  minitest (~> 5.0)
-  oj (~> 3.10)
+  minitest (~> 5.14)
+  oj (~> 3.11)
   rake (~> 13.0)
   rubocop (>= 0.79.0)
-  rubocop-minitest (~> 0.10.1)
-  rubocop-performance (~> 1.7.1)
+  rubocop-minitest (~> 0.10.3)
+  rubocop-performance (~> 1.10.1)
+  rubocop-rake (>= 0.5.1)
   rubocop-sensible (~> 0.3.0)
+  yard
 
 BUNDLED WITH
-   2.1.4
+   2.2.6

data/README.md

@@ -2,26 +2,28 @@
 [![Build Status](https://travis-ci.com/okuramasafumi/alba.svg?branch=master)](https://travis-ci.com/okuramasafumi/alba)
 [![Coverage Status](https://coveralls.io/repos/github/okuramasafumi/alba/badge.svg?branch=master)](https://coveralls.io/github/okuramasafumi/alba?branch=master)
 [![Maintainability](https://api.codeclimate.com/v1/badges/fdab4cc0de0b9addcfe8/maintainability)](https://codeclimate.com/github/okuramasafumi/alba/maintainability)
+![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/okuramasafumi/alba)
+![GitHub](https://img.shields.io/github/license/okuramasafumi/alba)
 
 # Alba
 
 `Alba` is the fastest JSON serializer for Ruby.
 
-# Why yet another JSON serializer?
+## Why yet another JSON serializer?
 
 We know that there are several other JSON serializers for Ruby around, but none of them made us satisfied.
 
 Alba has some advantages over other JSON serializers which we've wanted to have.
 
-## Easy to understand
+### Easy to understand
 
 DSL is great. It makes the coding experience natural and intuitive. However, remembering lots of DSL requires us a lot of effort. Unfortunately, most of the existing libraries have implemented their features via DSL and it's not easy to understand how they behave entirely. Alba's core DSL are only four (`attributes`, `attribute`, `one` and `many`) so it's easy to understand how to use.
 
-Alba is also understandable internally. The codebase is much smaller than the alternatives. In fact, it's less than 300 lines of code. Look at the code on [GitHub](https://github.com/okuramasafumi/alba/tree/master/lib) and you'll be surprised how simple it is!
+Alba is also understandable internally. The codebase is much smaller than the alternatives. In fact, it's about 330 lines of code. Look at the code on [GitHub](https://github.com/okuramasafumi/alba/tree/master/lib) and you'll be surprised how simple it is!
 
-## Performance
+### Performance
 
-Alba is faster than most of the alternatives. We have a [benchmark](https://gist.github.com/okuramasafumi/4e375525bd3a28e4ca812d2a3b3e5829).
+Alba is faster than most of the alternatives. We have a [benchmark](https://github.com/okuramasafumi/alba/tree/master/benchmark).
 
 ## Installation
 
@@ -43,6 +45,33 @@ Or install it yourself as:
 
 Alba supports CRuby 2.5.7 and higher and latest TruffleRuby.
 
+## Documentation
+
+You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramasafumi/alba).
+
+## Features
+
+* Resource-based serialization
+* Arbitrary attribute definition
+* One and many association with the ability to define them inline
+* Adding condition and filter to association
+* Parameters can be injected and used in attributes and associations
+* Setting root key separately in Serializer
+* Adding metadata
+* Selectable backend
+* Key transformation
+* No runtime dependencies
+
+## Anti features
+
+* Sorting keys
+* Class level support of parameters
+* Supporting all existing JSON encoder/decoder
+* Cache
+* [JSON:API](https://jsonapi.org) support
+* Association name inflection
+* And many others
+
 ## Usage
 
 ### Configuration
@@ -129,7 +158,7 @@ class ArticleResource
   attributes :title
 end
 
-class UserResource1
+class UserResource
   include Alba::Resource
 
   attributes :id
@@ -143,7 +172,7 @@ user.articles << article1
 article2 = Article.new(2, 'Super nice', 'Really nice!')
 user.articles << article2
 
-UserResource1.new(user).serialize
+UserResource.new(user).serialize
 # => '{"id":1,"articles":[{"title":"Hello World!"},{"title":"Super nice"}]}'
 ```
 
@@ -193,6 +222,76 @@ RestrictedFooResouce.new(foo).serialize
 end
 ```
 
+### Attribute key transformation
+
+** Note: You need to install `active_support` gem to use `transform_keys` DSL.
+
+With `active_support` installed, you can transform attribute keys.
+
+```ruby
+class User
+  attr_reader :id, :first_name, :last_name
+
+  def initialize(id, first_name, last_name)
+    @id = id
+    @first_name = first_name
+    @last_name = last_name
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  attributes :id, :first_name, :last_name
+
+  transform_keys :lower_camel
+end
+
+user = User.new(1, 'Masafumi', 'Okura')
+UserResourceCamel.new(user).serialize
+# => '{"id":1,"firstName":"Masafumi","lastName":"Okura"}'
+```
+
+Supported transformation types are :camel, :lower_camel and :dash.
+
+### Filtering attributes
+
+You can filter attributes by overriding `Alba::Resource#converter` method, but it's a bit tricky.
+
+```ruby
+class User
+  attr_accessor :id, :name, :email, :created_at, :updated_at
+
+  def initialize(id, name, email)
+    @id = id
+    @name = name
+    @email = email
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  attributes :id, :name, :email
+
+  private
+
+  # Here using `Proc#>>` method to compose a proc from `super`
+  def converter
+    super >> proc { |hash| hash.compact }
+  end
+end
+
+user = User.new(1, nil, nil)
+UserResource.new(user).serialize # => '{"id":1}'
+
+
+```
+
+The key part is the use of `Proc#>>` since `Alba::Resource#converter` returns a `Proc` which contains the basic logic and it's impossible to change its behavior by just overriding the method.
+
+It's not recommended to swap the whole conversion logic. It's recommended to always call `super` when you override `converter`.
+
 ## Comparison
 
 Alba is faster than alternatives.

data/benchmark/local.rb

@@ -0,0 +1,198 @@
+# Benchmark script to run varieties of JSON serializers
+# Fetch Alba from local, otherwise fetch latest from RubyGems
+
+require "bundler/inline"
+
+gemfile(true) do
+  source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+  gem "activerecord", "6.1.3"
+  gem "sqlite3"
+  gem "jbuilder"
+  gem "active_model_serializers"
+  gem "blueprinter"
+  gem "representable"
+  gem "alba", path: '../'
+  gem "oj"
+  gem "multi_json"
+end
+
+require "active_record"
+require "sqlite3"
+require "logger"
+require "oj"
+Oj.optimize_rails
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+# ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+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
+
+require "alba"
+Alba.backend = :oj
+
+class AlbaCommentResource
+  include ::Alba::Resource
+  attributes :id, :body
+end
+
+class AlbaPostResource
+  include ::Alba::Resource
+  attributes :id, :body
+  many :comments, resource: AlbaCommentResource
+  attribute :commenter_names do |post|
+    post.commenters.pluck(:name)
+  end
+end
+
+require "jbuilder"
+class Post
+  def to_builder
+    Jbuilder.new do |post|
+      post.call(self, :id, :body, :comments, :commenter_names)
+    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
+
+require "active_model_serializers"
+
+class AMSCommentSerializer < ActiveModel::Serializer
+  attributes :id, :body
+end
+
+class AMSPostSerializer < ActiveModel::Serializer
+  attributes :id, :body
+  has_many :comments, serializer: AMSCommentSerializer
+  attribute :commenter_names
+  def commenter_names
+    object.commenters.pluck(:name)
+  end
+end
+
+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
+
+require "representable"
+
+class CommentRepresenter < Representable::Decorator
+  include Representable::JSON
+
+  property :id
+  property :body
+end
+
+class PostRepresenter < Representable::Decorator
+  include Representable::JSON
+
+  property :id
+  property :body
+  property :commenter_names
+  collection :comments
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+post = Post.create!(body: 'post')
+user1 = User.create!(name: 'John')
+user2 = User.create!(name: 'Jane')
+post.comments.create!(commenter: user1, body: 'Comment1')
+post.comments.create!(commenter: user2, body: 'Comment2')
+post.reload
+
+alba = Proc.new { AlbaPostResource.new(post).serialize }
+jbuilder = Proc.new { post.to_builder.target! }
+ams = Proc.new { AMSPostSerializer.new(post, {}).to_json }
+rails = Proc.new { ActiveSupport::JSON.encode(post.serializable_hash(include: :comments)) }
+blueprinter = Proc.new { PostBlueprint.render(post) }
+representable = Proc.new { PostRepresenter.new(post).to_json }
+alba_inline = Proc.new do
+  Alba.serialize(post) do
+    attributes :id, :body
+    attribute :commenter_names do |post|
+      post.commenters.pluck(:name)
+    end
+    many :comments do
+      attributes :id, :body
+    end
+  end
+end
+[alba, jbuilder, ams, rails, blueprinter, representable, alba_inline].each {|x| puts x.call }
+
+require 'benchmark'
+time = 1000
+Benchmark.bmbm do |x|
+  x.report(:alba) { time.times(&alba) }
+  x.report(:jbuilder) { time.times(&jbuilder) }
+  x.report(:ams) { time.times(&ams) }
+  x.report(:rails) { time.times(&rails) }
+  x.report(:blueprinter) { time.times(&blueprinter) }
+  x.report(:representable) { time.times(&representable) }
+  x.report(:alba_inline) { time.times(&alba_inline) }
+end

data/lib/alba.rb

@@ -1,21 +1,37 @@
-require 'alba/version'
-require 'alba/serializer'
-require 'alba/resource'
+require_relative 'alba/version'
+require_relative 'alba/serializer'
+require_relative 'alba/resource'
 
 # Core module
 module Alba
+  # Base class for Errors
   class Error < StandardError; end
+
+  # Error class for backend which is not supported
   class UnsupportedBackend < Error; end
 
   class << self
     attr_reader :backend, :encoder
     attr_accessor :default_serializer
 
+    # Set the backend, which actually serializes object into JSON
+    #
+    # @param backend [#to_sym, nil] the name of the backend
+    #   Possible values are `oj`, `active_support`, `default`, `json` and nil
+    # @return [Proc] the proc to encode object into JSON
+    # @raise [Alba::UnsupportedBackend] if backend is not supported
     def backend=(backend)
       @backend = backend&.to_sym
       set_encoder
     end
 
+    # Serialize the object with inline definitions
+    #
+    # @param object [Object] the object to be serialized
+    # @param with [nil, Proc, Alba::Serializer] selializer
+    # @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, with: nil, &block)
       raise ArgumentError, 'Block required' unless block
 
@@ -63,9 +79,9 @@ module Alba
 
     def resource_class
       @resource_class ||= begin
-                             klass = Class.new
-                             klass.include(Alba::Resource)
-                           end
+        klass = Class.new
+        klass.include(Alba::Resource)
+      end
     end
   end
 

data/lib/alba/association.rb

@@ -2,6 +2,10 @@ module Alba
   # Base class for `One` and `Many`
   # Child class should implement `to_hash` method
   class Association
+    # @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 block [Block] used to define resource when resource arg is absent
     def initialize(name:, condition: nil, resource: nil, &block)
       @name = name
       @condition = condition
@@ -10,6 +14,7 @@ module Alba
       raise ArgumentError, 'resource or block is required' if @resource.nil? && @block.nil?
     end
 
+    # @abstract
     def to_hash
       :not_implemented
     end

data/lib/alba/key_transformer.rb

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

data/lib/alba/many.rb

@@ -1,11 +1,18 @@
-require 'alba/association'
+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 params [Hash] user-given Hash for arbitrary data
+    # @return [Array<Hash>]
     def to_hash(target, params: {})
       objects = target.public_send(@name)
-      objects = @condition.call(objects) if @condition
+      objects = @condition.call(objects, params) if @condition
+      return if objects.nil?
+
       objects.map { |o| @resource.new(o, params: params).to_hash }
     end
   end

data/lib/alba/one.rb

@@ -1,11 +1,18 @@
-require 'alba/association'
+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 params [Hash] user-given Hash for arbitrary data
+    # @return [Hash]
     def to_hash(target, params: {})
       object = target.public_send(@name)
-      object = @condition.call(object) if @condition
+      object = @condition.call(object, params) if @condition
+      return if object.nil?
+
       @resource.new(object, params: params).to_hash
     end
   end

data/lib/alba/resource.rb

@@ -1,11 +1,16 @@
-require 'alba/serializer'
-require 'alba/one'
-require 'alba/many'
+require_relative 'serializer'
+require_relative 'one'
+require_relative 'many'
 
 module Alba
   # This module represents what should be serialized
   module Resource
-    DSLS = {_attributes: {}, _serializer: nil, _key: nil}.freeze
+    # @!parse include InstanceMethods
+    # @!parse extend ClassMethods
+    DSLS = {_attributes: {}, _serializer: nil, _key: nil, _transform_keys: nil}.freeze
+    private_constant :DSLS
+
+    # @private
     def self.included(base)
       super
       base.class_eval do
@@ -22,12 +27,18 @@ module Alba
     module InstanceMethods
       attr_reader :object, :_key, :params
 
+      # @param object [Object] the object to be serialized
+      # @param params [Hash] user-given Hash for arbitrary data
       def initialize(object, params: {})
         @object = object
-        @params = params
+        @params = params.freeze
         DSLS.each_key { |name| instance_variable_set("@#{name}", self.class.public_send(name)) }
       end
 
+      # Get serializer with `with` argument and serialize self with it
+      #
+      # @param with [nil, Proc, Alba::Serializer] selializer
+      # @return [String] serialized JSON string
       def serialize(with: nil)
         serializer = case with
                      when nil
@@ -42,31 +53,49 @@ module Alba
         serializer.new(self).serialize
       end
 
+      # A Hash for serialization
+      #
+      # @return [Hash]
       def serializable_hash
         collection? ? @object.map(&converter) : converter.call(@object)
       end
       alias to_hash serializable_hash
 
+      # @return [Symbol]
       def key
         @_key || self.class.name.delete_suffix('Resource').downcase.gsub(/:{2}/, '_').to_sym
       end
 
       private
 
+      # rubocop:disable Style/MethodCalledOnDoEndBlock
       def converter
         lambda do |resource|
-          @_attributes.transform_values do |attribute|
-            case attribute
-            when Symbol
-              resource.public_send attribute
-            when Proc
-              instance_exec(resource, &attribute)
-            when Alba::One, Alba::Many
-              attribute.to_hash(resource, params: params)
-            else
-              raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
-            end
-          end
+          @_attributes.map do |key, attribute|
+            [transform_key(key), fetch_attribute(resource, attribute)]
+          end.to_h
+        end
+      end
+      # rubocop:enable Style/MethodCalledOnDoEndBlock
+
+      # Override this method to supply custom key transform method
+      def transform_key(key)
+        return key unless @_transform_keys
+
+        require_relative 'key_transformer'
+        KeyTransformer.transform(key, @_transform_keys)
+      end
+
+      def fetch_attribute(resource, attribute)
+        case attribute
+        when Symbol
+          resource.public_send attribute
+        when Proc
+          instance_exec(resource, &attribute)
+        when Alba::One, Alba::Many
+          attribute.to_hash(resource, params: params)
+        else
+          raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
         end
       end
 
@@ -91,43 +120,86 @@ module Alba
     module ClassMethods
       attr_reader(*DSLS.keys)
 
+      # @private
       def inherited(subclass)
         super
         DSLS.each_key { |name| subclass.instance_variable_set("@#{name}", instance_variable_get("@#{name}").clone) }
       end
 
+      # Set multiple attributes at once
+      #
+      # @param attrs [Array<String, Symbol>]
       def attributes(*attrs)
         attrs.each { |attr_name| @_attributes[attr_name.to_sym] = attr_name.to_sym }
       end
 
+      # Set an attribute with the given block
+      #
+      # @param name [String, Symbol] key name
+      # @param block [Block] the block called during serialization
+      # @raise [ArgumentError] if block is absent
       def attribute(name, &block)
         raise ArgumentError, 'No block given in attribute method' unless block
 
         @_attributes[name.to_sym] = block
       end
 
+      # 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 block [Block]
+      # @see Alba::One#initialize
       def one(name, condition = nil, resource: nil, key: nil, &block)
         @_attributes[key&.to_sym || name.to_sym] = One.new(name: name, condition: condition, resource: resource, &block)
       end
+      alias has_one one
 
+      # 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 block [Block]
+      # @see Alba::Many#initialize
       def many(name, condition = nil, resource: nil, key: nil, &block)
         @_attributes[key&.to_sym || name.to_sym] = Many.new(name: name, condition: condition, resource: resource, &block)
       end
+      alias has_many many
 
+      # Set serializer for the resource
+      #
+      # @param name [Alba::Serializer]
       def serializer(name)
         @_serializer = name <= Alba::Serializer ? name : nil
       end
 
+      # Set key
+      #
+      # @param key [String, Symbol]
       def key(key)
         @_key = key.to_sym
       end
 
+      # Delete attributes
       # Use this DSL in child class to ignore certain attributes
+      #
+      # @param attributes [Array<String, Symbol>]
       def ignoring(*attributes)
         attributes.each do |attr_name|
           @_attributes.delete(attr_name.to_sym)
         end
       end
+
+      # Transform keys as specified type
+      #
+      # @param type [String, Symbol]
+      def transform_keys(type)
+        @_transform_keys = type.to_sym
+      end
     end
   end
 end

data/lib/alba/serializer.rb

@@ -1,26 +1,34 @@
 module Alba
   # This module represents how a resource should be serialized.
   module Serializer
+    # @!parse include InstanceMethods
+    # @!parse extend ClassMethods
+
+    # @private
     def self.included(base)
       super
-      base.class_eval do
-        @_opts = {} unless instance_variable_defined?('@_opts')
-        @_metadata = {} unless instance_variable_defined?('@_metadata')
-      end
+      base.instance_variable_set('@_opts', {}) unless base.instance_variable_defined?('@_opts')
+      base.instance_variable_set('@_metadata', {}) unless base.instance_variable_defined?('@_metadata')
       base.include InstanceMethods
       base.extend ClassMethods
     end
 
     # Instance methods
     module InstanceMethods
+      # @param resource [Alba::Resource]
       def initialize(resource)
         @resource = resource
         @hash = resource.serializable_hash
         @hash = {key.to_sym => @hash} if key
+        return if metadata.empty?
+
         # @hash is either Hash or Array
         @hash.is_a?(Hash) ? @hash.merge!(metadata.to_h) : @hash << metadata
       end
 
+      # Use real encoder to actually serialize to JSON
+      #
+      # @return [String] JSON string
       def serialize
         Alba.encoder.call(@hash)
       end
@@ -42,17 +50,25 @@ module Alba
     module ClassMethods
       attr_reader :_opts, :_metadata
 
+      # @private
       def inherited(subclass)
         super
         %w[_opts _metadata].each { |name| subclass.instance_variable_set("@#{name}", public_send(name).clone) }
       end
 
+      # Set options, currently key only
+      #
+      # @param key [Boolean, Symbol]
       def set(key: false)
         @_opts[:key] = key
       end
 
+      # Set metadata
+      #
+      # @param name [String, Symbol] key for the metadata
+      # @param block [Block] the content of the metadata
       def metadata(name, &block)
-        @_metadata[name] = block
+        @_metadata[name.to_sym] = block
       end
     end
   end

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '0.10.2'.freeze
+  VERSION = '0.13.1'.freeze
 end

data/sider.yml

@@ -7,6 +7,7 @@ linter:
       - "rubocop-minitest"
       - "rubocop-performance"
       - "rubocop-sensible"
+      - "rubocop-rake"
     safe: false
 
 #   # https://help.sider.review/tools/ruby/reek

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.13.1
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-24 00:00:00.000000000 Z
+date: 2021-03-24 00:00:00.000000000 Z
 dependencies: []
 description: Alba is designed to be a simple, easy to use and fast alternative to
   existing JSON serializers. Its performance is better than almost all gems which
@@ -19,9 +19,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/main.yml"
 - ".gitignore"
 - ".rubocop.yml"
-- ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -29,10 +30,12 @@ files:
 - README.md
 - Rakefile
 - alba.gemspec
+- benchmark/local.rb
 - bin/console
 - bin/setup
 - lib/alba.rb
 - lib/alba/association.rb
+- lib/alba/key_transformer.rb
 - lib/alba/many.rb
 - lib/alba/one.rb
 - lib/alba/resource.rb
@@ -61,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.11
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.

data/.travis.yml

@@ -1,9 +0,0 @@
----
-language: ruby
-cache: bundler
-rvm:
-  - 2.5.8
-  - 2.6.6
-  - 2.7.1
-  - truffleruby
-before_install: gem install bundler -v 2.1.4