alba 1.3.0 → 1.6.0

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/gemfiles/all.gemfile

@@ -1,6 +1,7 @@
 source 'https://rubygems.org'
 
 gem 'activesupport', require: false # For backend
+gem 'dry-inflector', require: false # For inflector
 gem 'ffaker', require: false # For testing
 gem 'minitest', '~> 5.14' # For test
 gem 'rake', '~> 13.0' # For test and automation
@@ -11,7 +12,7 @@ gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
 gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
 gem 'simplecov', '~> 0.21.0', require: false # For test coverage
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'oj', '~> 3.11', require: false # For backend

data/gemfiles/without_active_support.gemfile

@@ -9,7 +9,7 @@ gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
 gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
 gem 'simplecov', '~> 0.21.0', require: false # For test coverage
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'oj', '~> 3.11', require: false # For backend

data/gemfiles/without_oj.gemfile

@@ -10,7 +10,7 @@ gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
 gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
 gem 'simplecov', '~> 0.21.0', require: false # For test coverage
 gem 'simplecov-cobertura', require: false # For test coverage
-gem 'yard', require: false
+gem 'yard', require: false # For documentation
 
 platforms :ruby do
   gem 'ruby-prof', require: false # For performance profiling

data/lib/alba/association.rb

@@ -1,21 +1,40 @@
 module Alba
-  # Base class for `One` and `Many`
-  # Child class should implement `to_hash` method
+  # Representing association
   class Association
+    @const_cache = {}
+    class << self
+      attr_reader :const_cache
+    end
+
     attr_reader :object, :name
 
-    # @param name [Symbol] name of the method to fetch association
-    # @param condition [Proc] a proc filtering data
-    # @param resource [Class<Alba::Resource>] a resource class for the association
+    # @param name [Symbol, String] name of the method to fetch association
+    # @param condition [Proc, nil] a proc filtering data
+    # @param resource [Class<Alba::Resource>, nil] a resource class for the association
+    # @param nesting [String] a namespace where source class is inferred with
     # @param block [Block] used to define resource when resource arg is absent
     def initialize(name:, condition: nil, resource: nil, nesting: nil, &block)
       @name = name
       @condition = condition
-      @block = block
       @resource = resource
       return if @resource
 
-      assign_resource(nesting)
+      assign_resource(nesting, block)
+    end
+
+    # Recursively converts an object into a Hash
+    #
+    # @param target [Object] the object having an association method
+    # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
+    # @param params [Hash] user-given Hash for arbitrary data
+    # @return [Hash]
+    def to_h(target, within: nil, params: {})
+      @object = target.public_send(@name)
+      @object = @condition.call(object, params) if @condition
+      return if @object.nil?
+
+      @resource = constantize(@resource)
+      @resource.new(object, params: params, within: within).to_h
     end
 
     private
@@ -25,30 +44,20 @@ module Alba
       when Class
         resource
       when Symbol, String
-        Object.const_get(resource)
+        self.class.const_cache.fetch(resource) do
+          self.class.const_cache[resource] = Object.const_get(resource)
+        end
       end
     end
 
-    def assign_resource(nesting)
-      @resource = if @block
-                    resource_class
+    def assign_resource(nesting, block)
+      @resource = if block
+                    Alba.resource_class(&block)
                   elsif Alba.inferring
-                    resource_class_with_nesting(nesting)
+                    Alba.infer_resource_class(@name, nesting: nesting)
                   else
                     raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
                   end
     end
-
-    def resource_class
-      klass = Class.new
-      klass.include(Alba::Resource)
-      klass.class_eval(&@block)
-      klass
-    end
-
-    def resource_class_with_nesting(nesting)
-      const_parent = nesting.nil? ? Object : Object.const_get(nesting)
-      const_parent.const_get("#{ActiveSupport::Inflector.classify(@name)}Resource")
-    end
   end
 end