alba 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01d43d93e589197104d9ee166e6a9dcf727fd204524b52145d7d93b45ba79cd2
-  data.tar.gz: 023f2e0f8ff17bc78a01e2dc1eb1f98d9c41b0cd353e311f350c2704a9ffa602
+  metadata.gz: 34c441cbc87f959f73c3e7a0175309f780b23ce840add4d53cf5083488390f1f
+  data.tar.gz: f78fb2eea40f502c6f7b3c905317616054bd397d30aa9ce979285003205c81af
 SHA512:
-  metadata.gz: 99992932a0f6a3d589e77e1b7dc4225be2e083a15320fa00a96f07a4cd9bbe9803454b94ecae409d439809a53225fb54ce283fcca074c0aed479e7d8b808d545
-  data.tar.gz: c77e99af9cf98781a2e961817b5c60e31fe178e6eef7bb8bd77b1af199043b8acd8395a27dd7cb10680ae82d28ec57e98106fef42f57055cb23752d63605a7b9
+  metadata.gz: 326ac8e731f2b4e0fe4afbb8f690059ecd578ffcb9270b9779bdcb6bb50d57d063ec0a98fc488398915c39ca2978b41e79d53bb1f5a809f9272ad885c383a549
+  data.tar.gz: 2b36eb5d07749505b4ab377b56cc7e564bcd6e86d872e7cb2c45f62ae2cf91a41b2c6e0b70cdcbb8d2a5d802528e4d9bfb113b723a2be7b1bdbc207c0277df45

data/CHANGELOG.md

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] 2021-11-28
+
+- [Feat] Add nil handler
+- [Feat] Implement layout feature
+- [Improve] if option now works with Symbol
+- [Improve] Add an alias for serialize
+- [Improve] Deprecation warning now printed with caller
+
 ## [1.4.0] 2021-06-30
 
 - [Feat] Add a config method to set encoder directly
@@ -14,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [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
+- [Deprecated] `Resource.key` and `Resource.key!` are deprecated
 
 ## [1.3.0] 2021-05-31
 

data/Gemfile

@@ -9,8 +9,8 @@ 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.13.0', require: false # For lint
-gem 'rubocop-performance', '~> 1.11.0', require: false # For lint
+gem 'rubocop-minitest', '~> 0.17.0', require: false # For lint
+gem 'rubocop-performance', '~> 1.12.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

data/README.md

@@ -65,9 +65,11 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 * Key transformation
 * Root key inference
 * Error handling
+* Nil handling
 * Resource name inflection based on association name
 * Circular associations control
 * [Experimental] Types for validation and conversion
+* Layout
 * No runtime dependencies
 
 ## Anti features
@@ -129,7 +131,7 @@ Alba.on_error :ignore
 
 For the details, see [Error handling section](#error-handling)
 
-### Simple serialization with key
+### Simple serialization with root key
 
 ```ruby
 class User
@@ -146,7 +148,7 @@ end
 class UserResource
   include Alba::Resource
 
-  key :user
+  root_key :user
 
   attributes :id, :name
 
@@ -243,7 +245,7 @@ end
 `Alba.serialize` method is a shortcut to define everything inline.
 
 ```ruby
-Alba.serialize(user, key: :foo) do
+Alba.serialize(user, root_key: :foo) do
   attributes :id
   many :articles do
     attributes :title, :body
@@ -325,7 +327,7 @@ UserResourceCamel.new(user).serialize
 You can also transform root key when:
 
 * `Alba.enable_inference!` is called
-* `key!` is called in Resource class
+* `root_key!` is called in Resource class
 * `root` option of `transform_keys` is set to true or `Alba.enable_root_key_transformation!` is called.
 
 ```ruby
@@ -342,7 +344,7 @@ end
 class BankAccountResource
   include Alba::Resource
 
-  key!
+  root_key!
 
   attributes :account_number
   transform_keys :dash, root: true
@@ -570,6 +572,95 @@ Alba.on_error do |error, object, key, attribute, resource_class|
 end
 ```
 
+### Nil handling
+
+Sometimes we want to convert `nil` to different values such as empty string. Alba provides a flexible way to handle `nil`.
+
+```ruby
+class User
+  attr_reader :id, :name, :age
+
+  def initialize(id, name = nil, age = nil)
+    @id = id
+    @name = name
+    @age = age
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  on_nil { '' }
+
+  root_key :user, :users
+
+  attributes :id, :name, :age
+end
+
+UserResource.new(User.new(1)).serialize
+# => '{"user":{"id":1,"name":"","age":""}}'
+```
+
+You can get various information via block parameters.
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  on_nil do |object, key|
+    if key == age
+      20
+    else
+      "User#{object.id}"
+    end
+  end
+
+  root_key :user, :users
+
+  attributes :id, :name, :age
+end
+
+UserResource.new(User.new(1)).serialize
+# => '{"user":{"id":1,"name":"User1","age":20}}'
+```
+
+You can also set global nil handler.
+
+```ruby
+Alba.on_nil { 'default name' }
+
+class Foo
+  attr_reader :name
+  def initialize(name)
+    @name = name
+  end
+end
+
+class FooResource
+  include Alba::Resource
+
+  key :foo
+
+  attributes :name
+end
+
+FooResource.new(Foo.new).serialize
+# => '{"foo":{"name":"default name"}}'
+
+class FooResource2
+  include Alba::Resource
+
+  key :foo
+
+  on_nil { '' } # This is applied instead of global handler
+
+  attributes :name
+end
+
+FooResource2.new(Foo.new).serialize
+# => '{"foo":{"name":""}}'
+```
+
 ### Metadata
 
 You can set a metadata with `meta` DSL or `meta` option.
@@ -667,6 +758,68 @@ UserResource.new(user).serialize
 
 Note that this feature is experimental and interfaces are subject to change.
 
+### Layout
+
+Sometimes we'd like to serialize JSON into a template. In other words, we need some structure OUTSIDE OF serialized JSON. IN HTML world, we call it a "layout".
+
+Alba supports serializing JSON in a layout. You need a file for layout and then to specify file with `layout` method.
+
+```erb
+{
+  "header": "my_header",
+  "body": <%= serialized_json %>
+}
+```
+
+```ruby
+class FooResource
+  include Alba::Resource
+  layout file: 'my_layout.json.erb'
+end
+```
+
+Note that layout files are treated as `json` and `erb` and evaluated in a context of the resource, meaning
+
+* A layout file must be a valid JSON
+* You must write `<%= serialized_json %>` in a layout to put serialized JSON string into a layout
+* You can access `params` in a layout so that you can add virtually any objects to a layout
+  * When you access `params`, it's usually a Hash. You can use `encode` method in a layout to convert `params` Hash into a JSON with the backend you use
+* You can also access `object`, the underlying object for the resource
+
+In case you don't want to have a file for layout, Alba lets you define and apply layouts inline:
+
+```ruby
+class FooResource
+  include Alba::Resource
+  layout inline: proc do
+    {
+      header: 'my header',
+      body: serializable_hash
+    }
+  end
+end
+```
+
+In the example above, we specify a Proc which returns a Hash as an inline layout. In the Proc we can use `serializable_hash` method to access a Hash right before serialization.
+
+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
+    %({
+      "header": "my header",
+      "body": #{serialized_json}
+    })
+  end
+end
+```
+
+It looks similar to file layout but you must use string interpolation for method calls since it's not an ERB.
+
+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.
+
 ### 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).

data/benchmark/collection.rb

@@ -16,8 +16,11 @@ gemfile(true) do
   gem "benchmark-memory"
   gem "blueprinter"
   gem "jbuilder"
+  gem "jserializer"
   gem "jsonapi-serializer" # successor of fast_jsonapi
   gem "multi_json"
+  gem "panko_serializer"
+  gem "pg"
   gem "primalize"
   gem "oj"
   gem "representable"
@@ -27,7 +30,9 @@ end
 
 # --- Test data model setup ---
 
+require "pg"
 require "active_record"
+require "active_record/connection_adapters/postgresql_adapter"
 require "logger"
 require "oj"
 require "sqlite3"
@@ -157,6 +162,22 @@ class Comment
   end
 end
 
+# --- Jserializer serializers ---
+
+require 'jserializer'
+
+class JserializerCommentSerializer < Jserializer::Base
+  attributes :id, :body
+end
+
+class JserializerPostSerializer < Jserializer::Base
+  attributes :id, :body, :commenter_names
+  has_many :comments, serializer: JserializerCommentSerializer
+  def commenter_names
+    object.commenters.pluck(:name)
+  end
+end
+
 # --- JSONAPI:Serializer serializers / (successor of fast_jsonapi) ---
 
 class JsonApiStandardCommentSerializer
@@ -218,6 +239,26 @@ class JsonApiSameFormatPostSerializer < JsonApiSameFormatSerializer
   end
 end
 
+# --- Panko serializers ---
+#
+
+require "panko_serializer"
+
+class PankoCommentSerializer < Panko::Serializer
+  attributes :id, :body
+end
+
+
+class PankoPostSerializer < Panko::Serializer
+  attributes :id, :body, :commenter_names
+
+  has_many :comments, serializer: PankoCommentSerializer
+
+  def commenter_names
+    object.comments.pluck(:name)
+  end
+end
+
 # --- Primalize serializers ---
 #
 class PrimalizeCommentResource < Primalize::Single
@@ -328,8 +369,10 @@ jbuilder = Proc.new do
     end
   end.target!
 end
+jserializer = Proc.new { JserializerPostSerializer.new(posts, is_collection: true).to_json }
 jsonapi = proc { JsonApiStandardPostSerializer.new(posts).to_json }
 jsonapi_same_format = proc { JsonApiSameFormatPostSerializer.new(posts).to_json }
+panko = proc { Panko::ArraySerializer.new(posts, each_serializer: PankoPostSerializer).to_json }
 primalize = proc { PrimalizePostsResource.new(posts: posts).to_json }
 rails = Proc.new do
   ActiveSupport::JSON.encode(posts.map{ |post| post.serializable_hash(include: :comments) })
@@ -346,8 +389,10 @@ puts "Serializer outputs ----------------------------------"
   ams: ams,
   blueprinter: blueprinter,
   jbuilder: jbuilder, # different order
+  jserializer: jserializer,
   jsonapi: jsonapi, # nested JSON:API format
   jsonapi_same_format: jsonapi_same_format,
+  panko: panko,
   primalize: primalize,
   rails: rails,
   representable: representable,
@@ -363,8 +408,10 @@ Benchmark.ips do |x|
   x.report(:ams, &ams)
   x.report(:blueprinter, &blueprinter)
   x.report(:jbuilder, &jbuilder)
+  x.report(:jserializer, &jserializer)
   x.report(:jsonapi, &jsonapi)
   x.report(:jsonapi_same_format, &jsonapi_same_format)
+  x.report(:panko, &panko)
   x.report(:primalize, &primalize)
   x.report(:rails, &rails)
   x.report(:representable, &representable)
@@ -381,8 +428,10 @@ Benchmark.memory do |x|
   x.report(:ams, &ams)
   x.report(:blueprinter, &blueprinter)
   x.report(:jbuilder, &jbuilder)
+  x.report(:jserializer, &jserializer)
   x.report(:jsonapi, &jsonapi)
   x.report(:jsonapi_same_format, &jsonapi_same_format)
+  x.report(:panko, &panko)
   x.report(:primalize, &primalize)
   x.report(:rails, &rails)
   x.report(:representable, &representable)

data/benchmark/single_resource.rb

@@ -13,10 +13,14 @@ gemfile(true) do
   gem "activerecord", "6.1.3"
   gem "alba", path: '../'
   gem "benchmark-ips"
+  gem "benchmark-memory"
   gem "blueprinter"
   gem "jbuilder"
+  gem "jserializer"
   gem "jsonapi-serializer" # successor of fast_jsonapi
   gem "multi_json"
+  gem "panko_serializer"
+  gem "pg"
   gem "primalize"
   gem "oj"
   gem "representable"
@@ -26,7 +30,9 @@ end
 
 # --- Test data model setup ---
 
+require "pg"
 require "active_record"
+require "active_record/connection_adapters/postgresql_adapter"
 require "logger"
 require "oj"
 require "sqlite3"
@@ -154,6 +160,23 @@ class Comment
   end
 end
 
+# --- Jserializer serializers ---
+
+require 'jserializer'
+
+class JserializerCommentSerializer < Jserializer::Base
+  attributes :id, :body
+end
+
+class JserializerPostSerializer < Jserializer::Base
+  attributes :id, :body, :commenter_names
+  has_many :comments, serializer: JserializerCommentSerializer
+  def commenter_names
+    object.commenters.pluck(:name)
+  end
+end
+
+
 # --- JSONAPI:Serializer serializers / (successor of fast_jsonapi) ---
 
 class JsonApiStandardCommentSerializer
@@ -215,6 +238,25 @@ class JsonApiSameFormatPostSerializer < JsonApiSameFormatSerializer
   end
 end
 
+# --- Panko serializers ---
+#
+require "panko_serializer"
+
+class PankoCommentSerializer < Panko::Serializer
+  attributes :id, :body
+end
+
+
+class PankoPostSerializer < Panko::Serializer
+  attributes :id, :body, :commenter_names
+
+  has_many :comments, serializer: PankoCommentSerializer
+
+  def commenter_names
+    object.comments.pluck(:name)
+  end
+end
+
 # --- Primalize serializers ---
 #
 class PrimalizeCommentResource < Primalize::Single
@@ -308,8 +350,10 @@ end
 ams = Proc.new { AMSPostSerializer.new(post, {}).to_json }
 blueprinter = Proc.new { PostBlueprint.render(post) }
 jbuilder = Proc.new { post.to_builder.target! }
+jserializer = Proc.new { JserializerPostSerializer.new(post).to_json }
 jsonapi = proc { JsonApiStandardPostSerializer.new(post).to_json }
 jsonapi_same_format = proc { JsonApiSameFormatPostSerializer.new(post).to_json }
+panko = proc { PankoPostSerializer.new.serialize_to_json(post) }
 primalize = proc { PrimalizePostResource.new(post).to_json }
 rails = Proc.new { ActiveSupport::JSON.encode(post.serializable_hash(include: :comments)) }
 representable = Proc.new { PostRepresenter.new(post).to_json }
@@ -324,8 +368,10 @@ puts "Serializer outputs ----------------------------------"
   ams: ams,
   blueprinter: blueprinter,
   jbuilder: jbuilder, # different order
+  jserializer: jserializer,
   jsonapi: jsonapi, # nested JSON:API format
   jsonapi_same_format: jsonapi_same_format,
+  panko: panko,
   primalize: primalize,
   rails: rails,
   representable: representable,
@@ -341,8 +387,10 @@ Benchmark.ips do |x|
   x.report(:ams, &ams)
   x.report(:blueprinter, &blueprinter)
   x.report(:jbuilder, &jbuilder)
+  x.report(:jserializer, &jserializer)
   x.report(:jsonapi, &jsonapi)
   x.report(:jsonapi_same_format, &jsonapi_same_format)
+  x.report(:panko, &panko)
   x.report(:primalize, &primalize)
   x.report(:rails, &rails)
   x.report(:representable, &representable)
@@ -359,8 +407,10 @@ Benchmark.memory do |x|
   x.report(:ams, &ams)
   x.report(:blueprinter, &blueprinter)
   x.report(:jbuilder, &jbuilder)
+  x.report(:jserializer, &jserializer)
   x.report(:jsonapi, &jsonapi)
   x.report(:jsonapi_same_format, &jsonapi_same_format)
+  x.report(:panko, &panko)
   x.report(:primalize, &primalize)
   x.report(:rails, &rails)
   x.report(:representable, &representable)

data/docs/migrate_from_active_model_serializers.md

@@ -0,0 +1,359 @@
+---
+title: Upgrading from ActiveModelSerializers
+---
+
+<!-- @format -->
+
+This guide is aimed at helping ActiveModelSerializers users transition to Alba, and it consists of three parts:
+
+1. Basic serialization
+2. Complex serialization
+3. Unsupported features
+
+## Example class
+
+Example clsss is inherited `ActiveRecord::Base`, because [serializing PORO with AMS is pretty hard](https://github.com/rails-api/active_model_serializers/blob/0-10-stable/docs/howto/serialize_poro.md).
+
+```rb
+class User < ActiveRecord::Base
+  # columns: id, created_at, updated_at
+  has_one :profile
+  has_many :articles
+end
+
+class Profile < ActiveRecord::Base
+  # columns: id, user_id, email, created_at, updated_at
+  belongs_to :user
+end
+
+class Article < ActiveRecord::Base
+  # columns: id, user_id, title, body, created_at, updated_at
+  belongs_to :user
+end
+```
+
+## 1. Basic serialization
+
+### #serializable_hash
+
+- or #as_json, #to_json
+
+#### ActiveModelSerializer
+
+```rb
+# Infer and use by "#{MODEL_NAME}Serializer" in app/serializers/user_serializer.rb
+class UserSerializer < ActiveModel::Serializer
+  type :user
+  attributes :id, :created_at, :updated_at
+end
+
+# serialze
+user = User.create!
+ActiveModelSerializers::SerializableResource.new(
+  user
+).serializable_hash
+# => {
+#   user: {
+#     id: id,
+#     created_at: created_at,
+#     updated_at: updated_at
+#   }
+# }
+```
+
+#### Alba
+
+```rb
+# Infer and use by "#{MODEL_NAME}Resource"
+# In app/resources/user_resource.rb
+class UserResource
+  include Alba::Resource
+  attributes :id, :created_at, :updated_at
+end
+
+# serialze
+user = User.create!
+UserResource.new(user).serializable_hash
+# => {
+#   id: id,
+#   created_at: created_at,
+#   updated_at: updated_at,
+# }
+
+# If want `user key`
+class UserResource
+  include Alba::Resource
+  root_key :user # Call root_key method like ActiveModel::Serializer#type
+  attributes :id, :created_at, :updated_at
+end
+
+# serialze
+user = User.create!
+JSON.parse UserResource.new(user).serialize # ！！！！serializable_hash does not support root key！！！ Must use JSON.parse and serialize
+# => {
+#   "user"=>{
+#     "id"=>id,
+#     "created_at"=>created_at,
+#     "updated_at"=>updated_at
+#   }
+# }
+# If want symbolize keys with #deep_symbolize_keys in Rails
+user = User.create!
+JSON.parse(UserResource.new(user).serialize).deep_symbolize_keys
+# => {
+#   user: {
+#     id: id,
+#     created_at: created_at,
+#     updated_at: updated_at
+#   }
+# }
+```
+
+## 2. Complex serialization
+
+### Serialize collections
+
+#### ActiveModelSerializer
+
+```rb
+class UserSerializer < ActiveModel::Serializer
+  type :user
+  attributes :id, :created_at, :updated_at
+end
+3.times { User.create! }
+users = User.limit 3
+ActiveModelSerializers::SerializableResource.new(
+  users,
+  adapter: :attributes # Comment out this line if you want users key
+  # Want to specified key to call with root: args
+).serializable_hash
+# => [{:id=>1, :created_at=>created_at, :updated_at=>updated_at},
+#    {:id=>2, :created_at=>created_at, :updated_at=>updated_at},
+#    {:id=>3, :created_at=>created_at, :updated_at=>updated_at}]
+```
+
+#### Alba
+
+```rb
+class UserResource
+  include Alba::Resource
+  attributes :id, :created_at, :updated_at
+end
+3.times { User.create! }
+users = User.limit 3
+UserResource.new(users).serializable_hash
+# =>[{:id=>1, :created_at=>created_at, :updated_at=>updated_at},
+#    {:id=>2, :created_at=>created_at, :updated_at=>updated_at},
+#    {:id=>3, :created_at=>created_at, :updated_at=>updated_at}]
+# or
+JSON.parse UserResource.new(users).serialize(root_key: :users)
+# => {"users"=>
+#   [{"id"=>1, "created_at"=>created_at, "updated_at"=>updated_at},
+#    {"id"=>2, "created_at"=>created_at, "updated_at"=>updated_at},
+#    {"id"=>3, "created_at"=>created_at, "updated_at"=>updated_at}]}
+```
+
+### Nested serialization
+
+#### ActiveModelSerializer
+
+```rb
+class ProfileSerializer < ActiveModel::Serializer
+  type :profile
+  attributes :email
+end
+
+class ArticleSerializer < ActiveModel::Serializer
+  type :article
+  attributes :title, :body
+end
+
+class UserSerializer < ActiveModel::Serializer
+  type :user
+  attributes :id, :created_at, :updated_at
+  has_one :profile, serializer: ProfileSerializer # For has_one relation
+  has_many :articles, serializer: ArticleSerializer # For has_many relation
+end
+user = User.create!
+user.craete_profile! email: email
+user.articles.create! title: title, body: body
+ActiveModelSerializers::SerializableResource.new(
+  user
+).serializable_hash
+# => {
+#   :user=> {
+#     :id=>1,
+#     :created_at=>created_at,
+#     :updated_at=>updated_at,
+#     :profile=> {
+#       :email=>email
+#     },
+#     :articles => [
+#       {
+#         :title=>title,
+#         :body=>body
+#       }
+#     ]
+#   }
+# }
+```
+
+#### Alba
+
+```rb
+class ProfileResource
+  include Alba::Resource
+  root_key :profile
+  attributes :email
+end
+
+class ArticleResource
+  include Alba::Resource
+  root_key :article
+  attributes :title, :body
+end
+
+class UserResource
+  include Alba::Resource
+  root_key :user
+  attributes :id, :created_at, :updated_at
+  one :profile, resource: ProfileResource # For has_one relation
+  many :articles, resource: ArticleResource # For has_many relation
+end
+
+user = User.create!
+user.craete_profile! email: email
+user.articles.create! title: title, body: body
+UserResource.new(user).serializable_hash
+# => {
+#   :id=>1,
+#   :created_at=>created_at,
+#   :updated_at=>updated_at,
+#   :profile=> {
+#     :email=>email
+#   },
+#   :articles => [
+#     {
+#       :title=>title,
+#       :body=>body
+#     }
+#   ]
+# }
+```
+
+### Serialize with custom serializer
+
+#### ActiveModelSerializer
+
+```rb
+class CustomUserSerializer < ActiveModel::Serializer
+  type :user
+  attribute :email do
+    object.profile.email
+  end
+end
+
+# serialze
+user = User.create!
+user.craete_profile! email: email
+ActiveModelSerializers::SerializableResource.new(
+  user,
+  serializer: ::CustomUserSerializer # Call with serializer arg
+).serializable_hash
+# => {
+#   user: {
+#     email: email
+#   }
+# }
+```
+
+#### Alba
+
+```rb
+class CustomUserResource
+  include Alba::Resource
+  root_key :user
+  attribute :email do
+    object.profile.email
+  end
+end
+
+# serialze
+user = User.create!
+user.craete_profile! email: email
+CustomUserResource.new(user).serializable_hash
+# => {
+#   email: email
+# }
+```
+
+### Passing arbitrary options to a serializer
+
+#### ActiveModelSerializer
+
+```rb
+class UserSerializer < ApplicationSerializer
+  type :user
+  attributes :id, :created_at, :updated_at
+  attribute :custom_params do
+    pp instance_options
+    # => given_params: { a: :b }
+    instance_options # Access by instance_options method
+  end
+end
+
+# serialze
+user = User.create!
+ActiveModelSerializers::SerializableResource.new(
+  user,
+  given_params: { a: :b } # Give with your favorite keyword argument
+).serializable_hash
+# => {
+#   :id=>1,
+#   :created_at=>created_at,
+#   :updated_at=>updated_at,
+#   :custom_params=>{
+#     :given_params=>{
+#       :a=>:b
+#     }
+#   }
+# }
+```
+
+#### Alba
+
+```rb
+class UserResource
+  include Alba::Resource
+  root_key :user
+  attributes :id, :created_at, :updated_at
+  attribute :custom_params do
+    pp params
+    # => { :a=>:b }
+    params
+  end
+end
+
+# serialze
+user = User.create!
+UserResource.new(
+  user,
+  params: { a: :b } # Give with :params keyword argument
+).serializable_hash
+# => {
+#   :id=>1,
+#   :created_at=>created_at,
+#   :updated_at=>updated_at,
+#   :custom_params=>{
+#     :a=>:b
+#   }
+# }
+```
+
+## 3. Unsupported features
+
+- [RelationshipLinks](https://github.com/rails-api/active_model_serializers/blob/v0.10.6/docs/howto/add_relationship_links.md)
+- [PaginationLinks](https://github.com/rails-api/active_model_serializers/blob/v0.10.6/docs/howto/add_pagination_links.md)
+- [Logging](https://github.com/rails-api/active_model_serializers/blob/v0.10.6/docs/general/logging.md)
+- [Caching](https://github.com/rails-api/active_model_serializers/blob/v0.10.6/docs/general/caching.md)
+- [Rendering](https://github.com/rails-api/active_model_serializers/blob/v0.10.6/docs/general/rendering.md)

data/docs/migrate_from_jbuilder.md

@@ -0,0 +1,223 @@
+---
+title: Upgrading from Jbuilder
+---
+
+<!-- @format -->
+
+This guide is aimed at helping Jbuilder users transition to Alba, and it consists of three parts:
+
+1. Basic serialization
+2. Complex serialization
+3. Unsupported features
+
+## Example class
+
+This example will also be replaced by ActiveReord.
+
+```rb
+class User
+  attr_reader :id, :created_at, :updated_at
+  attr_accessor :profile, :articles
+
+  def initialize(id)
+    @id = id
+    @created_at = Time.now
+    @updated_at = Time.now
+    @articles = []
+  end
+end
+
+class Profile
+  attr_reader :email
+
+  def initialize(email)
+    @email = email
+  end
+end
+
+class Article
+  attr_accessor :title, :body
+
+  def initialize(title, body)
+    @title = title
+    @body = body
+  end
+end
+```
+
+## 1. Basic serialization
+
+#### Jbuilder
+
+```rb
+# show.json.jbuilder
+# With block
+@user = User.new(id)
+json.user do |user|
+  user.id @user.id
+  user.created_at @user.created_at
+  user.updated_at @user.updated_at
+end
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at}'
+# or #extract!
+json.extract! @user, :id, :created_at, :updated_at
+# => '{"id":id, "created_at": created_at, "updated_at": updated_at}'
+```
+
+#### Alba
+
+```rb
+# With block
+user = User.new(id)
+Alba.serialize(user, root_key: :user) do
+  attributes :id, :created_at, :updated_at
+end
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at}'
+# or with resourceClass.
+# Infer and use by "#{MODEL_NAME}Resource"
+class UserResource
+  include Alba::Resource
+  root_key :user
+  attributes :id, :created_at, :updated_at
+end
+UserResource.new(user).serialize
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at}'
+```
+
+## 2. Complex serialization
+
+### Serialize collections
+
+#### Jbuilder
+
+```rb
+@users = ids.map { |id| User.new(id) }
+# index.json.jbuilder
+json.array! @users, :id, :created_at, :updated_at
+# => '[{"id":id, "created_at": created_at, "updated_at": updated_at}, {"id":id, "created_at": created_at, "updated_at": updated_at}, {"id":id, "created_at": created_at, "updated_at": updated_at}]'
+```
+
+#### Alba
+
+```rb
+class UserResource
+  include Alba::Resource
+  root_key :user
+  attributes :id, :created_at, :updated_at
+end
+users = ids.map { |id| User.new(id) }
+UserResource.new(users).serialize
+# => '[{"id":id, "created_at": created_at, "updated_at": updated_at}, {"id":id, "created_at": created_at, "updated_at": updated_at}, {"id":id, "created_at": created_at, "updated_at": updated_at}]'
+
+```
+
+### Nested serialization
+
+#### Jbuilder
+
+```rb
+# show.json.jbuilder
+@user = User.new(id)
+@user.profile = Profile.new(email)
+@user.articles = [Article.new(title, body)]
+json.user do |user|
+  user.id @user.id
+  user.created_at @user.created_at
+  user.updated_at @user.updated_at
+  json.profile do
+    json.email @user.profile.email
+  end
+  json.articles do
+    json.array! @user.articles, :title, :body
+  end
+end
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at, "profile": {"email": email}, articles: [{"title": title, "body": body}]}'
+# or #merge!
+profile_hash = { profile: { email: @user.profile.email } }
+articles_hash = { articles: @user.articles.map { |article| { title: article.title, body: article.body } } }
+json.user do |user|
+  user.id @user.id
+  user.created_at @user.created_at
+  user.updated_at @user.updated_at
+  json.merge! profile_hash
+  json.merge! articles_hash
+end
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at, "profile": {"email": email}, articles: [{"title": title, "body": body}]}'
+# or #partial!
+# profiles/_profile.json.jbuilder
+json.profile do
+  json.email @profile.email
+end
+# articles/_article.json.jbuilder
+json.extract! article, :title, :body
+# user/show.json.jbuilder
+json.user do |user|
+  user.id @user.id
+  user.created_at @user.created_at
+  user.updated_at @user.updated_at
+  json.partial! @user.profile, as: :profile
+  json.articles @user.articles do |article|
+    json.partial! article, partial: 'articles/article'
+  end
+end
+```
+
+#### Alba
+
+```rb
+# With ResourceClass by each resources
+class ProfileResource
+  include Alba::Resource
+  root_key :profile
+  attributes :email
+end
+class ArticleResource
+  include Alba::Resource
+  root_key :article
+  attributes :title, :body
+end
+class UserResource
+  include Alba::Resource
+  root_key :user
+  attributes :id, :created_at, :updated_at
+  one :profile, resource: ProfileResource
+  many :articles, resource: ArticleResource
+end
+user = User.new(id)
+user.profile = Profile.new(email)
+user.articles = [Article.new(title, body)]
+UserResource.new(user).serialize
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at, "profile": {"email": email}, articles: [{"title": title, "body": body}]}'
+
+# or #attribute
+class UserResource
+  include Alba::Resource
+  root_key :user
+  attributes :id, :created_at, :updated_at
+
+  attribute :profile do
+    {
+      email: object.profile.email # Can access to received resource by #object method
+    }
+  end
+
+  attribute :articles do
+    object.articles.map do |article|
+      {
+        title: article.title,
+        body: article.body,
+      }
+    end
+  end
+end
+user = User.new(id)
+user.profile = Profile.new(email)
+UserResource.new(user).serialize
+# => '{"user":{"id":id, "created_at": created_at, "updated_at": updated_at, "profile": {"email": email}, articles: [{"title": title, "body": body}]}'
+```
+
+## 3. Unsupported features
+
+- Jbuilder#ignore_nil!
+- Jbuilder#cache!
+- Jbuilder.key_format! and Jbuilder.deep_format_keys!

data/lib/alba/deprecation.rb

@@ -0,0 +1,14 @@
+module Alba
+  # Module for printing deprecation warning
+  module Deprecation
+    # Similar to {Kernel.warn} but prints caller as well
+    #
+    # @param message [String] main message to print
+    # @return void
+    def warn(message)
+      Kernel.warn(message)
+      Kernel.warn(caller_locations(2..2).first) # For performance reason we use (2..2).first
+    end
+    module_function :warn
+  end
+end

data/lib/alba/resource.rb

@@ -2,13 +2,14 @@ require_relative 'one'
 require_relative 'many'
 require_relative 'key_transform_factory'
 require_relative 'typed_attribute'
+require_relative 'deprecation'
 
 module Alba
   # This module represents what should be serialized
   module Resource
     # @!parse include InstanceMethods
     # @!parse extend ClassMethods
-    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
+    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_key_function: nil, _transforming_root_key: false, _on_error: nil, _on_nil: nil, _layout: nil}.freeze # rubocop:disable Layout/LineLength
     private_constant :DSLS
 
     WITHIN_DEFAULT = Object.new.freeze
@@ -48,7 +49,7 @@ module Alba
       # @param meta [Hash] metadata for this seialization
       # @return [String] serialized JSON string
       def serialize(key: nil, root_key: nil, meta: {})
-        warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
+        Alba::Deprecation.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}
@@ -56,8 +57,9 @@ module Alba
                else
                  serializable_hash
                end
-        Alba.encoder.call(hash)
+        serialize_with(hash)
       end
+      alias to_json serialize
 
       # A Hash for serialization
       #
@@ -69,6 +71,25 @@ module Alba
 
       private
 
+      attr_reader :serialized_json # Mainly for layout
+
+      def encode(hash)
+        Alba.encoder.call(hash)
+      end
+
+      def serialize_with(hash)
+        @serialized_json = encode(hash)
+        case @_layout
+        when String # file
+          ERB.new(File.read(@_layout)).result(binding)
+        when Proc # inline
+          inline = instance_eval(&@_layout)
+          inline.is_a?(Hash) ? encode(inline) : inline
+        else # no layout
+          @serialized_json
+        end
+      end
+
       def hash_with_metadata(hash, meta)
         base = @_meta ? instance_eval(&@_meta) : {}
         metadata = base.merge(meta)
@@ -120,23 +141,38 @@ module Alba
         if attribute.is_a?(Array) # Conditional
           conditional_attribute(object, key, attribute)
         else
-          [key, fetch_attribute(object, attribute)]
+          fetched_attribute = fetch_attribute(object, key, attribute)
+          [key, fetched_attribute]
         end
       end
 
       def conditional_attribute(object, key, attribute)
         condition = attribute.last
+        if condition.is_a?(Proc)
+          conditional_attribute_with_proc(object, key, attribute.first, condition)
+        else
+          conditional_attribute_with_symbol(object, key, attribute.first, condition)
+        end
+      end
+
+      def conditional_attribute_with_proc(object, key, attribute, condition)
         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 = attribute.first.is_a?(Alba::Association) ? attribute.first.object : fetched_attribute
+        fetched_attribute = fetch_attribute(object, key, attribute)
+        attr = attribute.is_a?(Alba::Association) ? attribute.object : fetched_attribute
         return [] if arity >= 2 && !instance_exec(object, attr, &condition)
 
         [key, fetched_attribute]
       end
 
+      def conditional_attribute_with_symbol(object, key, attribute, condition)
+        return [] unless __send__(condition)
+
+        [key, fetch_attribute(object, key, attribute)]
+      end
+
       def handle_error(error, object, key, attribute)
         on_error = @_on_error || Alba._on_error
         case on_error
@@ -156,15 +192,20 @@ module Alba
         @_transform_key_function.call(key.to_s)
       end
 
-      def fetch_attribute(object, attribute)
-        case attribute
-        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
+      def fetch_attribute(object, key, attribute)
+        value = case attribute
+                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
+        value.nil? && nil_handler ? instance_exec(object, key, attribute, &nil_handler) : value
+      end
+
+      def nil_handler
+        @nil_handler ||= (@_on_nil || Alba._on_nil)
       end
 
       def yield_if_within(association_name)
@@ -289,7 +330,7 @@ module Alba
       # @param key [String, Symbol]
       # @deprecated Use {#root_key} instead
       def key(key)
-        warn '[DEPRECATION] `key` is deprecated, use `root_key` instead.'
+        Alba::Deprecation.warn '[DEPRECATION] `key` is deprecated, use `root_key` instead.'
         @_key = key.respond_to?(:to_sym) ? key.to_sym : key
       end
 
@@ -307,7 +348,7 @@ module Alba
       #
       # @deprecated Use {#root_key!} instead
       def key!
-        warn '[DEPRECATION] `key!` is deprecated, use `root_key!` instead.'
+        Alba::Deprecation.warn '[DEPRECATION] `key!` is deprecated, use `root_key!` instead.'
         @_key = true
         @_key_for_collection = true
       end
@@ -323,6 +364,14 @@ module Alba
         @_meta = block
       end
 
+      # Set layout
+      #
+      # @params file [String] name of the layout file
+      # @params inline [Proc] a proc returning JSON string or a Hash representing JSON
+      def layout(file: nil, inline: nil)
+        @_layout = file || inline
+      end
+
       # Delete attributes
       # Use this DSL in child class to ignore certain attributes
       #
@@ -354,6 +403,13 @@ module Alba
         @_on_error = handler || block
       end
 
+      # Set nil handler
+      #
+      # @param block [Block]
+      def on_nil(&block)
+        @_on_nil = block
+      end
+
       # rubocop:enable Metrics/ParameterLists
     end
   end

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '1.4.0'.freeze
+  VERSION = '1.5.0'.freeze
 end

data/lib/alba.rb

@@ -1,6 +1,7 @@
 require 'json'
 require_relative 'alba/version'
 require_relative 'alba/resource'
+require_relative 'alba/deprecation'
 
 # Core module
 module Alba
@@ -14,7 +15,7 @@ module Alba
   class UnsupportedType < Error; end
 
   class << self
-    attr_reader :backend, :encoder, :inferring, :_on_error, :transforming_root_key
+    attr_reader :backend, :encoder, :inferring, :_on_error, :_on_nil, :transforming_root_key
 
     # Accessor for inflector, a module responsible for incflecting strings
     attr_accessor :inflector
@@ -51,7 +52,7 @@ module Alba
     # @return [String] serialized JSON string
     # @raise [ArgumentError] if block is absent or `with` argument's type is wrong
     def serialize(object, key: nil, root_key: nil, &block)
-      warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
+      Alba::Deprecation.warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
       klass = block ? resource_class(&block) : infer_resource_class(object.class.name)
 
       resource = klass.new(object)
@@ -87,6 +88,14 @@ module Alba
       @_on_error = handler || block
     end
 
+    # Set nil handler
+    #
+    # @param block [Block]
+    # @return [void]
+    def on_nil(&block)
+      @_on_nil = block
+    end
+
     # Enable root key transformation
     def enable_root_key_transformation!
       @transforming_root_key = true
@@ -115,6 +124,15 @@ module Alba
       const_parent.const_get("#{ActiveSupport::Inflector.classify(name)}Resource")
     end
 
+    # Reset config variables
+    # Useful for test cleanup
+    def reset!
+      @encoder = default_encoder
+      @_on_error = :raise
+      @_on_nil = nil
+      @transforming_root_key = false # TODO: This will be true since 2.0
+    end
+
     private
 
     def set_encoder_from_backend
@@ -151,7 +169,5 @@ module Alba
     end
   end
 
-  @encoder = default_encoder
-  @_on_error = :raise
-  @transforming_root_key = false # TODO: This will be true since 2.0
+  reset!
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-06-30 00:00:00.000000000 Z
+date: 2021-11-28 00:00:00.000000000 Z
 dependencies: []
 description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
   flexibility and usability.
@@ -39,12 +39,15 @@ files:
 - bin/console
 - bin/setup
 - codecov.yml
+- docs/migrate_from_active_model_serializers.md
+- docs/migrate_from_jbuilder.md
 - gemfiles/all.gemfile
 - gemfiles/without_active_support.gemfile
 - gemfiles/without_oj.gemfile
 - lib/alba.rb
 - lib/alba/association.rb
 - lib/alba/default_inflector.rb
+- lib/alba/deprecation.rb
 - lib/alba/key_transform_factory.rb
 - lib/alba/many.rb
 - lib/alba/one.rb
@@ -75,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.16
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.