https://github.com/varvet/serial
Plain old Ruby for generating primitive data structures from object graphs.
https://github.com/varvet/serial
Last synced: about 2 months ago
JSON representation
Plain old Ruby for generating primitive data structures from object graphs.
- Host: GitHub
- URL: https://github.com/varvet/serial
- Owner: varvet
- Created: 2015-08-31T15:28:46.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2018-01-12T07:50:18.000Z (over 7 years ago)
- Last Synced: 2025-07-13T11:46:20.503Z (3 months ago)
- Language: Ruby
- Homepage:
- Size: 63.5 KB
- Stars: 107
- Watchers: 11
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Serial
[](http://travis-ci.org/elabs/serial)
[](https://gemnasium.com/elabs/serial)
[](https://codeclimate.com/github/elabs/serial)
[](http://badge.fury.io/rb/serial)
[](http://inch-ci.org/github/elabs/serial)
*Psst, full documentation can be found at [rubydoc.info/gems/serial](http://www.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][].
[![elabs logo][]][Elabs]
[Elabs]: http://www.elabs.se/
[elabs logo]: ./elabs-logo.png?raw=true
## Installation
Add this line to your application's Gemfile:
```ruby
gem "serial"
```
And then execute:
$ bundle
## The DSL
*Full reference: [Serial::HashBuilder](http://www.rubydoc.info/gems/serial/Serial/HashBuilder), [Serial::ArrayBuilder](http://www.rubydoc.info/gems/serial/Serial/ArrayBuilder).*
- All keys are turned into strings.
- There is no automatic camel-casing. You name your keys the way you want them.
- Using the same key twice will raise an error by default.
- To override the value for an existing key, use the respective !-method DSL, i.e. `#attribute!`, `#collection!`, `#map!`, or `#merge!`.
### Simple attributes
`#attribute` creates a simple attribute with a value.
``` ruby
ProjectSerializer = Serial::Serializer.new do |h, project|
h.attribute(:id, project.id)
h.attribute(:displayName, project.display_name)
end # => { "id" => …, "displayName" => … }
```
### Nested attributes
`#attribute` supports nesting by giving it a block.
``` ruby
ProjectSerializer = Serial::Serializer.new do |h, project|
h.attribute(:owner, project.owner) do |h, owner|
h.attribute(:name, owner.name)
end
end # => { "owner" => { "name" => … } }
```
### Collections
`#map` is a convenient method for serializing lists of items.
``` ruby
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`.
``` ruby
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" => [{…}, {…}, [{…}, {…}]] }
```
### Merging
`#merge` will let you merge another serializer without introducing a new nesting level.
``` ruby
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" => … }
```
### Composition
You can compose serializers by passing them as blocks to the DSL methods.
``` ruby
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" => … }, …] }
```
## Using your serializers
*Full reference: [Serial::Serializer](http://www.rubydoc.info/gems/serial/Serial/Serializer).*
- The context parameter in the below examples (when using `#call` and `#map`) is optional, if not provided regular block scoping rules apply.
- Tip: include [Serial::RailsHelpers](http://www.rubydoc.info/gems/serial/Serial/RailsHelpers) in ApplicationController for a convenient `#serialize` method.
### Serializing a single object
``` ruby
project = Project.find(…)
context = self
ProjectSerializer.call(context, project) # => { … }
```
### Serializing a list of objects
``` ruby
projects = Project.all
context = self
ProjectSerializer.map(context, projects) # => [{ … }, …]
```
### Using with Rails
```ruby
# app/serializers/project_serializer.rb
ProjectSerializer = Serial::Serializer.new do |h, project|
…
end
```
``` ruby
# 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
```
## Development
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](https://rubygems.org).
## Contributing
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.md) code of conduct.
## License
The gem is available as open source under the terms of the
[MIT License](http://opensource.org/licenses/MIT).