Psst, full documentation can be found at rubydoc.info/gems/serial
Serial is a light-weight and simple serialization library. Its primary purpose is to generate primitive datastructures from object graphs, in other words to help you serialize your data.
Serial is sponsored by Elabs.
Add this line to your application's Gemfile:
gem "serial"
And then execute:
$ bundle
Full reference: Serial::HashBuilder, Serial::ArrayBuilder.
#attribute!
, #collection!
, #map!
, or #merge!
.#attribute
creates a simple attribute with a value.
ProjectSerializer = Serial::Serializer.new do |h, project|
h.attribute(:id, project.id)
h.attribute(:displayName, project.display_name)
end # => { "id" => …, "displayName" => … }
#attribute
supports nesting by giving it a block.
ProjectSerializer = Serial::Serializer.new do |h, project|
h.attribute(:owner, project.owner) do |h, owner|
h.attribute(:name, owner.name)
end
end # => { "owner" => { "name" => … } }
#map
is a convenient method for serializing lists of items.
ProjectSerializer = Serial::Serializer.new do |h, project|
h.map(:assignments, project.assignments) do |h, assignment|
h.attribute(:id, assignment.id)
h.attribute(:duration, assignment.duration)
end
end # => { "assignments" => [{ "id" => …, "duration" => … }, …] }
The low-level interface powering #map
is #collection
.
ProjectSerializer = Serial::Serializer.new do |h, project|
h.collection(:indices) do |l|
l.element { |h| h.attribute(…) }
l.element { |h| h.attribute(…) }
l.collection do |l|
l.element { … }
l.element { … }
end
end
end # => { "indices" => [{…}, {…}, [{…}, {…}]] }
#merge
will let you merge another serializer without introducing a new nesting level.
ProjectSerializer = Serial::Serializer.new do |h, project|
h.attribute(:name, project.name)
end # => { "name" => … }
FullProjectSerializer = Serial::Serializer.new do |h, project|
h.merge(project, &ProjectSerializer)
h.attribute(:description, project.description)
end # { "name" => …, "description" => … }
You can compose serializers by passing them as blocks to the DSL methods.
PersonSerializer = Serial::Serializer.new do |h, person|
h.attribute(:name, person.name)
end # => { "name" => … }
ProjectSerializer = Serial::Serializer.new do |h, project|
h.attribute(:owner, project.owner, &PersonSerializer)
h.map(:people, project.people, &PersonSerializer)
end # { "owner" => { "name" => … }, "people" => [{ "name" => … }, …] }
Full reference: Serial::Serializer.
#call
and #map
) is optional, if not provided regular block scoping rules apply.#serialize
method.project = Project.find(…)
context = self
ProjectSerializer.call(context, project) # => { … }
projects = Project.all
context = self
ProjectSerializer.map(context, projects) # => [{ … }, …]
# app/serializers/project_serializer.rb
ProjectSerializer = Serial::Serializer.new do |h, project|
…
end
# app/controllers/project_controller.rb
class ProjectController < ApplicationController
include Serial::RailsHelpers
def show
project = Project.find(…)
# 1. Using helper from RailsHelpers.
render json: serialize(project)
# 2. Explicitly mentioning serializer using helper method.
render json: serialize(project, &ProjectSerializer)
# 3. Explicitly mentioning serializer.
render json: ProjectSerializer.call(self, project)
end
end
After checking out the repo, run bin/setup
to install dependencies. Then, run
rake spec
to run the tests. You can also run bin/console
for an interactive
prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To
release a new version, update the version number in version.rb
, and then run
bundle exec rake release
, which will create a git tag for the version, push
git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/elabs/serial. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.