barley

Barley is a fast and efficient ActiveModel serializer.

Cerealize your ActiveModel objects into flat hashes with a dead simple, yet versatile DSL, and caching and type-checking baked in. Our daily bread is to make your API faster.

You don't believe us? Check out the benchmarks. 😎

API documentation

Check out the API documentation here.

Usage

Add the Barley::Serializable module to your ActiveModel object.

# /app/models/user.rb
class User < ApplicationRecord
  include Barley::Serializable
end

Then define your attributes and associations in a serializer class.

# /app/serializers/user_serializer.rb
class UserSerializer < Barley::Serializer

  attributes id: Types::Strict::Integer, :name

  attribute :email
  attribute :value, type: Types::Coercible::Integer

  many :posts

  many :posts, key_name: :featured, scope: :featured

  many :posts, key_name: :popular, scope: -> { where("views > 10_000").limit(3) }

  many :posts, key_name: :in_current_language, scope: -> (context) { where(language: context.language) }

  one :group, serializer: CustomGroupSerializer

  many :related_users, key: :friends, cache: true

  one :profile, cache: { expires_in: 1.day } do
    attributes :avatar, :social_url

    attribute :badges do
      object.badges.map(&:display_name)
    end
  end

end

Then just use the as_json method on your model.

user = User.find(1)
user.as_json(only: [:id, :name, posts: [:id, :title]])

Installation

Add this line to your application's Gemfile:

gem "barley"

And then execute:

$ bundle

Or install it yourself as:

$ gem install barley

Defining the serializer

Barley uses the model name to find the serializer class. For example, if you have a User model, Barley will look for a UserSerializer class.

You can also define the serializer class with the serializer macro.

# /app/models/user.rb
class User < ApplicationRecord
  include Barley::Serializable

  serializer UserSerializer
end

DSL

Attributes

You can define attributes with the attributes macro.

  attributes :id, :name, :email, :created_at, :updated_at

You can also define attributes one by one, or a mix of both.

  attributes :id, :name, :email
  attribute :created_at
  attribute :updated_at

You can also define a custom attribute with a block. You will have a object variable available in the block. It is the object you are serializing.

  attribute :full_name do
    "#{object.first_name} #{object.last_name}"
  end

You can also set a custom key name for the attribute with the key_name option.

  attribute :updated_at, key: :last_change

Associations

One-to-one

You can define a one-to-one association with the one macro.

  one :group

Custom serializer and caching

You can define a custom serializer for the association with the serializer option, and / or caching options with the cache option.

  one :group, serializer: CustomGroupSerializer, cache: { expires_in: 1.hour }

You can of course define serializers with inner classes for simple needs.

class UserSerializer < Barley::Serializer
  attributes :id, :name, :email, :created_at, :updated_at

  one :group, serializer: LocalGroupSerializer

    class LocalGroupSerializer < Barley::Serializer
        attributes :id, :name
    end
end

Key name

You can also pass a key name for the association with the key_name option.

  one :group, key_name: :team

One-to-many

You can define a one-to-many association with the many macro.

  many :posts

Custom serializer and caching

You can define a custom serializer for the association with the serializer option, and / or caching options with the cache option.

  many :posts, serializer: CustomPostSerializer, cache: { expires_in: 1.hour }

Scope

You can pass a scope to the association with the scope option. It can either be a symbol referencing a named scope on your associated model, or a lambda.

  many :posts, scope: :published # given you have a scope named `published` on your Post model

  many :posts, scope: -> { where(published: true).limit(4) }

You can also pass a context to the lambda. See the context section for more details.

  many :posts, scope: -> (context) { where(language: context.language) }

Key name

You can also pass a key name for the association with the key_name option.

  many :posts, key_name: :articles

Associations with blocks

Feel like using a block to define your associations? You can do that too.

  one :group do
    attributes :id, :name
  end

  many :posts do
    attributes :id, :title, :body

    one :author do
      attributes :name, :email
    end
  end

Of course, all the options available for the one and many macros are also available for the block syntax.

  many :posts, key_name: :featured do
    attributes :id, :title, :body
  end

Context

You can pass a context to the serializer with the with_context method.

serializer = PostSerializer.new(Post.last).with_context(current_user: current_user)

This context will be available in the serializer with the context method. It is also available in nested serializers.

class PostSerializer < Barley::Serializer
  attributes :id, :title, :body

  attribute :is_owner do
    object.user == context.current_user
  end

  many :comments do
    many :likes do
      attribute :is_owner do
        object.user == context.current_user # context is here too!
      end
    end
  end
end

The context is also available in the scope of the lambda passed to the scope option of the many macro. See the scope section for more details.

  many :posts, scope: -> (context) { where(language: context.language) }

Using a custom context object

Barley generates a Struct from the context hash you pass to the with_context method. But you can also pass a custom context object directly in the initializer instead.

my_context = Struct.new(:current_user).new(current_user)

serializer = PostSerializer.new(Post.last, context: my_context)

Generators

You have two generators available. One to generate the serializer class:

rails generate barley:serializer User
# or
rails generate barley:serializer User --name=CustomUserSerializer

And one to generate both the serializer class and add the module to the model:

rails generate barley:serializable User
# or
rails generate barley:serializable User --name=CustomUserSerializer

Serialization options

You can pass a hash of options to the as_json method.

user = User.find(1)
user.as_json(serializer: CustomUserSerializer, cache: { expires_in: 1.hour })

Beware, this gem overrides the as_json method on your model. Calling as_json with include, only, or except options will not work.

Why? We believe it defeats the purpose of this gem. If you want to customize the serialization of your model, you should use a serializer class.

Caching

Barley supports caching out of the box. Just pass cache: true to the serializer macro.

# /app/models/user.rb
# ...
serializer UserSerializer, cache: true

Or you can pass a hash of options to the serializer macro.

# /app/models/user.rb
# ...
serializer UserSerializer, cache: { expires_in: 1.hour }

Caching options

Barley uses the MemoryStore by default. You can change the cache store with the cache_store option in an initializer.

# /config/initializers/barley.rb
Barley.configure do |config|
  config.cache_store = ActiveSupport::Cache::RedisCacheStore.new
end

Type checking

Barley can check the type of the object you are serializing with the dry-types gem.

It will raise an error if the object is not of the expected type, or coerce it to the correct type and perform constraints checks.

module Types
  include Dry.Types()
end

class UserSerializer < Barley::Serializer
  attributes id: Types::Strict::Integer, name: Types::Strict::String, email: Types::Strict::String.constrained(format: URI::MailTo::EMAIL_REGEXP)

  attribute :role, type: Types::Coercible::String do
    object.role.integer_or_string_coercible_value
  end
end

Check out dry-types for all options and available types.

Breakfast mode 🤡 (coming soon)

You will soon be able to replace all occurrences of Serializer with Cerealizer in your codebase. Just for fun. And for free.

# /app/models/user.rb
class User < ApplicationRecord
  include Barley::Cerealizable

  cerealizer UserCerealizer
end

# app/cerealizers/user_cerealizer.rb
class UserCerealizer < Barley::Cerealizer
  attributes :id, :name, :email, :created_at, :updated_at

  many :posts
  one :group
end

rails generate barley:cerealizer User
# etc.

Ah ah ah. This is so funny.

Note: we are thinking about adding a Surrealizer class for the most advanced users. Stay tuned.

JSON:API

Barley does not serialize to the JSON:API standard. We prefer to keep it simple and fast.

Benchmarks

This gem is blazing fast and efficient. It is 2 to 3 times faster than ActiveModel::Serializer and twice as fast as FastJsonapi. Memory object allocation is also much lower.

With caching enabled, it is just mind-blowing. We think. Disclaimer: we do not serialize to the JSON:API standard, so that might be the reason why we are so fast.

This is the result we get with the benchmark script used in the AMS repo on an Apple Silicon M1Pro processor. Check it out for yourself here.

bundle exec ruby benchmark.rb
-- create_table("comments", {:force=>:cascade})
-> 0.0128s
-- create_table("posts", {:force=>:cascade})
-> 0.0002s
-- create_table("users", {:force=>:cascade})
-> 0.0002s
Warming up --------------------------------------
ams                    3.000  i/100ms
jsonapi-rb             9.000  i/100ms
barley                 9.000  i/100ms
barley-cache         460.000  i/100ms
ams          eager     8.000  i/100ms
jsonapi-rb   eager    33.000  i/100ms
barley       eager    37.000  i/100ms
barley-cache eager    70.000  i/100ms
Calculating -------------------------------------
ams                    67.770  (± 1.9%) i/s -    657.000  in  10.042270s
jsonapi-rb            157.239  (± 2.3%) i/s -      1.521k in  10.010257s
barley                 96.909  (± 2.4%) i/s -    945.000  in  10.036316s
barley-cache            4.589k (± 2.8%) i/s -     44.620k in  10.010004s
ams          eager     68.237  (± 6.2%) i/s -    592.000  in  10.087602s
jsonapi-rb   eager    289.733  (± 3.7%) i/s -      2.805k in  10.033912s
barley       eager    406.732  (± 3.2%) i/s -      3.922k in  10.020076s
barley-cache eager    639.935  (± 2.4%) i/s -      6.300k in  10.053710s
with 95.0% confidence

Comparison:
barley-cache      :     4589.3 i/s
barley-cache eager:      639.9 i/s - 7.17x  (± 0.27) slower
barley       eager:      406.7 i/s - 11.29x  (± 0.49) slower
jsonapi-rb   eager:      289.7 i/s - 15.83x  (± 0.74) slower
jsonapi-rb        :      157.2 i/s - 29.17x  (± 1.08) slower
barley            :       96.9 i/s - 47.37x  (± 1.75) slower
ams          eager:       68.2 i/s - 67.25x  (± 4.69) slower
ams               :       67.8 i/s - 67.72x  (± 2.31) slower
with 95.0% confidence

Calculating -------------------------------------
ams                    1.300M memsize (   246.338k retained)
16.838k objects (     2.492k retained)
50.000  strings (    50.000  retained)
jsonapi-rb           926.082k memsize (   197.338k retained)
9.565k objects (     1.776k retained)
50.000  strings (    50.000  retained)
barley                 1.102M memsize (   177.490k retained)
12.930k objects (     1.876k retained)
50.000  strings (    35.000  retained)
barley-cache          46.090k memsize (     1.308k retained)
502.000  objects (    17.000  retained)
42.000  strings (     6.000  retained)
ams          eager     1.068M memsize (   233.994k retained)
13.723k objects (     2.308k retained)
50.000  strings (    50.000  retained)
jsonapi-rb   eager   694.430k memsize (   194.826k retained)
6.450k objects (     1.651k retained)
50.000  strings (    50.000  retained)
barley       eager   354.326k memsize (   124.282k retained)
3.694k objects (     1.208k retained)
50.000  strings (    32.000  retained)
barley-cache eager   216.790k memsize (   107.228k retained)
2.376k objects (   956.000  retained)
50.000  strings (    33.000  retained)

Comparison:
barley-cache      :      46090 allocated
barley-cache eager:     216790 allocated - 4.70x more
barley       eager:     354326 allocated - 7.69x more
jsonapi-rb   eager:     694430 allocated - 15.07x more
jsonapi-rb        :     926082 allocated - 20.09x more
ams          eager:    1068038 allocated - 23.17x more
barley            :    1102354 allocated - 23.92x more
ams               :    1299674 allocated - 28.20x more

License

The gem is available as open source under the terms of the MIT License.

Contributing

You can contribute in several ways: reporting bugs, suggesting features, or contributing code. See our contributing guidelines

Make sure you adhere to our code of conduct. We aim to keep this project open and inclusive.

Security

Please refer to our security guidelines