Alba JSON Serializer

Alba follows a simple design pattern centered around the Alba::Resource module. To use Alba in a class, you simply include Alba::Resource.

This inclusion provides two layers of functionality:

1. Class Methods (DSL): Used to define the structure of the serialized output (e.g., defining which attributes or associations to include).
2. Instance Methods: Used to perform the actual serialization of a target object based on the configuration defined by the class methods.

When a class includes Alba::Resource, the class methods collect metadata that the instance methods later use during the serialization process.

class User
  include Alba::Resource

  attributes :id, :name
end

Since Alba resources are standard Ruby classes, you can use traditional OOP inheritance. Subclasses can add new attributes or override existing configurations like root_key.

class FooResource
  include Alba::Resource
  root_key :foo
  attributes :bar
end

class ExtendedFooResource < FooResource
  root_key :foofoo
  attributes :baz
end

Standard class inheritance does not work for sharing behaviors with inline associations (like has_many or one) because associations are implemented as separate internal classes that do not inherit from your base resource class. To share methods with these associations, use the helper block. All methods defined within a helper block must be defined without self..

class ApplicationResource
  include Alba::Resource

  helper do
    def with_id
      attributes(:id)
    end
  end
end

class LibraryResource < ApplicationResource
  with_id
  attributes :created_at

  with_many :library_books do
    with_id # This now works because of the helper block
    attributes :created_at
  end
end

By default, if a method name exists in both the Resource class and the target object, Alba prioritizes the method defined in the Resource class.

If you want Alba to prioritize the method on the target object (the object being serialized), use the prefer_object_method! macro.

class FooResource
  include Alba::Resource

  prefer_object_method! # Prioritizes Foo#bar over FooResource#bar

  attributes :bar
end

Alba handles different types of attribute definitions by applying specific resolution logic to the target object (@object). Depending on how you define an attribute, Alba uses different internal mechanisms:

Note: @object can represent either a single object or a collection of objects.

To use Alba, include Alba::Resource in your serializer class. You can define a root_key, specify multiple attributes at once, or define a single attribute with a block for custom logic. Use .new(resource).serialize to generate the JSON string.

class User
  attr_accessor :id, :name, :email

  def initialize(id, name, email)
    @id = id
    @name = name
    @email = email
  end
end

class UserResource
  include Alba::Resource

  root_key :user

  attributes :id, :name

  attribute :name_with_email do |resource|
    "#{resource.name}: #{resource.email}"
  end
end

user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
UserResource.new(user).serialize
# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"Masafumi OKURA: masafumi@example.com"}}'

To configure Alba's behavior in a Rails application, create an initializer file (e.g., config/initializers/alba.rb).

As of Alba 2.2, Rails integration is built-in, meaning you do not need an initializer to set the inflector to :active_support. However, you still need an initializer if you want to:

1. Change the backend (e.g., to :oj_rails).
2. Configure the inflector to something other than :active_support.

# config/initializers/alba.rb
Alba.backend = :active_support
Alba.inflector = :active_support

# Or using Oj for backend
Alba.backend = :oj_rails

You can install Alba by adding it to your application's Gemfile or by installing the gem directly via the command line.

Using Bundler: Add this to your Gemfile:

gem 'alba'

Then run:

bundle install

Direct Installation:

gem install alba

Alba uses one and many to define associations, whereas AMS uses has_one and has_many. You must explicitly specify the resource class to use for the nested serialization.

class ProfileResource
  include Alba::Resource
  root_key :profile
  attributes :email
end

class UserResource
  include Alba::Resource
  root_key :user
  attributes :id, :created_at, :updated_at
  
  # For has_one relations
  one :profile, resource: ProfileResource
  
  # For has_many relations
  many :articles, resource: ArticleResource
end