alba 1.1.0 → 1.5.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

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

data/gemfiles/without_active_support.gemfile

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

data/gemfiles/without_oj.gemfile

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

data/lib/alba/association.rb

@@ -2,11 +2,12 @@ module Alba
   # Base class for `One` and `Many`
   # Child class should implement `to_hash` method
   class Association
-    attr_reader :object
+    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
@@ -15,14 +16,7 @@ module Alba
       @resource = resource
       return if @resource
 
-      if @block
-        @resource = resource_class
-      elsif Alba.inferring
-        const_parent = nesting.nil? ? Object : Object.const_get(nesting)
-        @resource = const_parent.const_get("#{ActiveSupport::Inflector.classify(@name)}Resource")
-      else
-        raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
-      end
+      assign_resource(nesting)
     end
 
     private
@@ -36,11 +30,14 @@ module Alba
       end
     end
 
-    def resource_class
-      klass = Class.new
-      klass.include(Alba::Resource)
-      klass.class_eval(&@block)
-      klass
+    def assign_resource(nesting)
+      @resource = if @block
+                    Alba.resource_class(&@block)
+                  elsif Alba.inferring
+                    Alba.infer_resource_class(@name, nesting: nesting)
+                  else
+                    raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
+                  end
     end
   end
 end

data/lib/alba/default_inflector.rb

@@ -0,0 +1,36 @@
+module Alba
+  # This module represents the inflector, which is used by default
+  module DefaultInflector
+    begin
+      require 'active_support/inflector'
+    rescue LoadError
+      raise ::Alba::Error, 'To use transform_keys, please install `ActiveSupport` gem.'
+    end
+
+    module_function
+
+    # Camelizes a key
+    #
+    # @param key [String] key to be camelized
+    # @return [String] camelized key
+    def camelize(key)
+      ActiveSupport::Inflector.camelize(key)
+    end
+
+    # Camelizes a key, 1st letter lowercase
+    #
+    # @param key [String] key to be camelized
+    # @return [String] camelized key
+    def camelize_lower(key)
+      ActiveSupport::Inflector.camelize(key, false)
+    end
+
+    # Dasherizes a key
+    #
+    # @param key [String] key to be dasherized
+    # @return [String] dasherized key
+    def dasherize(key)
+      ActiveSupport::Inflector.dasherize(key)
+    end
+  end
+end

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