Surrealist
Surrealist is a schema-driven object serialization ruby library. It also provides a trivial type checking in the runtime before serialization. Yard documentation
Motivation
A typical use case for this gem could be, for example, serializing a (decorated) object outside of the view context. The schema is described through a hash, so you can build the structure of serialized object independently of its methods and attributes, while also having possibility to serialize nested objects and structures. Introductory blogpost.
- Installation
- Usage
- Simple example
- Nested structures
- Nested objects
- Collection Surrealization
- Defining custom serializers
- Multiple serializers
- Build schema
- Defined schema
- Working with ORMs
- ActiveRecord
- ROM
- Sequel
- Usage with Dry::Types
- Delegating Surrealization
- Optional arguments
- Camelization
- Include root
- Root
- Include namespaces
- Configuration
- Hash serialization
- Bool and Any
- Type errors
- Undefined methods in schema
- Other notes
- Roadmap
- Contributing
- Credits
- Authors
- License
Installation
Add this line to your application's Gemfile:
gem 'surrealist'
And then execute:
$ bundle
Or install it yourself as:
$ gem install surrealist
Usage
Schema should be defined with a block that contains a hash. Every key of the schema should be either a name of a method of the surrealizable object (or it's ancestors/mixins), or - in case you want to build json structure independently from object's structure - a symbol. Every value of the hash should be a constant that represents a Ruby class, that will be used for type-checks.
Simple example
- Include Surrealist in your class.
- Define a schema with methods that need to be serialized.
class Person
include Surrealist
json_schema do
{ name: String, age: Integer }
end
def name
'John Doe'
end
def age
42
end
end
- Surrealize it.
Person.new.surrealize
# => '{ "name": "John Doe", "age": 42 }'
Nested structures
class Person
include Surrealist
json_schema do
{
foo: String,
name: String,
nested: {
at: {
any: Integer,
level: Bool,
},
},
}
end
# ... method definitions
end
Person.find_by(email: '[email protected]').surrealize
# => '{ "foo": "Some string", "name": "John Doe", "nested": { "at": { "any": 42, "level": true } } }'
Nested objects
If you need to serialize nested objects and their attributes, you should define a method that calls nested object:
class User
include Surrealist
json_schema do
{
name: String,
credit_card: {
number: Integer,
cvv: Integer,
},
}
end
def name
'John Doe'
end
def credit_card
# Assuming that instance of a CreditCard has methods #number and #cvv defined
CreditCard.find_by(holder: name)
end
end
User.new.surrealize
# => '{ "name": "John Doe", "credit_card": { "number": 1234, "cvv": 322 } }'
Collection Surrealization
Since 0.2.0 Surrealist has API for collection serialization. Example for ActiveRecord:
class User < ActiveRecord::Base
include Surrealist
json_schema do
{ name: String, age: Integer }
end
end
users = User.all
# => [#<User:0x007fa1485de878 id: 1, name: "Nikita", age: 23>, #<User:0x007fa1485de5f8 id: 2, name: "Alessandro", age: 24>]
Surrealist.surrealize_collection(users)
# => '[{ "name": "Nikita", "age": 23 }, { "name": "Alessandro", "age": 24 }]'
You can find motivation behind introducing new API versus monkey-patching here.
#surrealize_collection
works for all data structures that behave like Enumerable
. All ActiveRecord
features (like associations, inheritance etc) are supported and covered. Further reading: working with ORMs.
All optional arguments (camelize
, include_root
etc) are also supported.
An additional and unique argument for #surrealize_collection
is raw
which is evaluated as a Boolean.
If this option is 'truthy' then the results will be an array of surrealized hashes (i.e. NOT a JSON string).
Surrealist.surrealize_collection(users, raw: true)
# => [{ "name": "Nikita", "age": 23 }, { "name": "Alessandro", "age": 24 }]
Defining custom serializers
If you need to keep serialization logic separately from the model, you can define a class that
will inherit from Surrealist::Serializer
. To point to that class from the model use a class method
.surrealize_with
. Example usage:
class CatSerializer < Surrealist::Serializer
json_schema { { age: Integer, age_group: String } }
def age_group
age <= 5 ? 'kitten' : 'cat'
end
end
class Cat
include Surrealist
attr_reader :age
surrealize_with CatSerializer
def initialize(age)
@age = age
end
end
Cat.new(12).surrealize # Implicit usage through .surrealize_with
# => '{ "age": 12, "age_group": "cat" }'
CatSerializer.new(Cat.new(3)).surrealize # explicit usage of CatSerializer
# => '{ "age": 3, "age_group": "kitten" }'
The constructor of Surrealist::Serializer
takes two arguments: serializable model (or collection) and
a context hash. So if there is an object that is not coupled to serializable model
but it is still necessary for constructing JSON, you can pass it to constructor as a hash. It will
be available in the serializer in the context
hash.
class IncomeSerializer < Surrealist::Serializer
json_schema { { amount: Integer } }
def amount
current_user.guest? ? 100000000 : object.amount
end
def current_user
context[:current_user]
end
end
class Income
include Surrealist
surrealize_with IncomeSerializer
attr_reader :amount
def initialize(amount)
@amount = amount
end
end
income = Income.new(200)
IncomeSerializer.new(income, current_user: GuestUser.new).surrealize
# => '{ "amount": 100000000 }'
IncomeSerializer.new(income, current_user: User.find(3)).surrealize
# => '{ "amount": 200 }'
If you happen to pass a context to a serializer, there is a handy DSL to reduce the number of methods you have to define yourself. DSL looks as follows
class IncomeSerializer < Surrealist::Serializer
serializer_context :current_user
json_schema { { amount: Integer } }
def amount
current_user.guest? ? 100000000 : object.amount
end
end
.serializer_context
takes an array of symbols and dynamically defines instance methods
that read values from the context hash. So .serializer_context :current_user
will become
def current_user
context[:current_user]
end
There is also an alias in the plural form: .serializer_contexts
.
Multiple serializers
You can define several custom serializers for one object and use it in different cases. Just mark it with a tag:
class PostSerializer < Surrealist::Serializer
json_schema { { id: Integer, title: String, author: { name: String } } }
end
class PreviewSerializer < Surrealist::Serializer
json_schema { { id: Integer, title: String } }
end
class Post
include Surrealist
surrealize_with PostSerializer
surrealize_with PreviewSerializer, tag: :preview
attr_reader :id, :title, :author
end
And then specify serializer's tag with for
argument:
= Struct.new(:name).new("John")
post = Post.new(1, "Ruby is awesome", )
post.surrealize # => '{ "id": 1, "title": "Ruby is awesome", author: { name: "John" } }'
post.surrealize(for: :preview) # => '{ "id": 1, "title": "Ruby is awesome" }'
Or specify serializer explicitly with serializer
argument:
post.surrealize(serializer: PreviewSerializer) # => '{ "id": 1, "title": "Ruby is awesome" }'
Build schema
If you don't need to dump the hash to json, you can use #build_schema
method on the instance. It calculates values and checks types, but returns
a hash instead of a JSON string. From the previous example:
Car.new.build_schema
# => { age: 7, brand: "Toyota", doors: nil, horsepower: 140, fuel_system: "Direct injection", previous_owner: "John Doe" }
Defined schema
Use the .defined_schema
method to get the schema that has been defined with json_schema
:
User.defined_schema
# => { name: String, age: Integer }
Working with ORMs
There are two kinds of return values of ORM methods: some return collections of objects, while others return instances.
For the first ones one should use instance#surrealize
, whereas for the second ones Surrealist.surrealize_collection(collection)
Please keep in mind that if your serialization logic is kept in a separate class which is inherited from
Surrealist::Serializer
, than usage boils down to YourSerializer.new(instance || collection).surrealize
.
ActiveRecord
All associations work as expected: .has_many
, .has_and_belongs_to_many
return collections,
.has_one
, .belongs_to
return instances.
Methods that return instances:
.find
.find_by
.find_by!
.take!
.first
.first!
.second
.second!
.third
.third!
.fourth
.fourth!
.fifth
.fifth!
.forty_two
.forty_two!
.last
.last!
.third_to_last
.third_to_last!
.second_to_last
.second_to_last!
Methods that return collections:
.all
.where
.where_not
.order
.take
.limit
.offset
.lock
.readonly
.reorder
.distinct
.find_each
.select
.group
.order
.except
.extending
.having
.references
.includes
.joins
ROM
For detailed usage example (covering ROM 3.x and ROM 4.x) please see spec/orms/rom/
.
Under the hood ROM uses Sequel, and Sequel returns instances only on .first
, .last
, .[]
and .with_pk!
.
Collections are returned for all other methods.
container = ROM.container(:sql, ['sqlite::memory']) do |conf|
conf.default.create_table(:users) do
primary_key :id
column :name, String, null: false
column :email, String, null: false
end
# ...
end
users = UserRepo.new(container).users
# => #<ROM::Relation[Users] name=ROM::Relation::Name(users) dataset=#<Sequel::SQLite::Dataset: "SELECT `users`.`id`, `users`.`name`, `users`.`email` FROM `users` ORDER BY `users`.`id`">>
Basically, there are several ways to fetch/represent data in ROM:
# With json_schema defined in ROM::Struct::User
class ROM::Struct::User < ROM::Struct
include Surrealist
json_schema { { name: String } }
end
users.to_a.first # => #<ROM::Struct::User id=1 name="Jane Struct" email="[email protected]">
users.to_a.first.surrealize # => "{\"name\":\"Jane Struct\"}"
users.where(id: 1).first # => #<ROM::Struct::User id=1 name="Jane Struct" email="[email protected]">
users.where(id: 1).first.surrealize # => "{\"name\":\"Jane Struct\"}"
Surrealist.surrealize_collection(users.to_a) # => "[{\"name\":\"Jane Struct\"},{\"name\":\"Dane As\"},{\"name\":\"Jack Mapper\"}]"
# using ROM::Struct::Model#as(Representative) with json_schema defined in representative
class RomUser < Dry::Struct
include Surrealist
attribute :name, String
attribute :email, String
json_schema { { email: String } }
end
# ROM 3.x
rom_users = users.as(RomUser).to_a
# ROM 4.x
rom_users = users.map_to(RomUser).to_a
rom_users[1].surrealize # => "{\"email\":\"[email protected]\"}"
Surrealist.surrealize_collection(rom_users) # => "[{\"email\":\"[email protected]\"},{\"email\":\"[email protected]\"},{\"email\":\"[email protected]\"}]"
# using Mappers
class UserModel
include Surrealist
json_schema { { id: Integer, email: String } }
attr_reader :id, :name, :email
def initialize(attributes)
@id, @name, @email = attributes.values_at(:id, :name, :email)
end
end
class UsersMapper < ROM::Mapper
register_as :user_obj
relation :users
model UserModel
end
# ROM 3.x
mapped = users.as(:user_obj)
# ROM 4.x
mapped = users.map_with(:user_obj)
mapped.to_a[2] # => #<UserModel:0x00007f8ec19fb3c8 @email="[email protected]", @id=3, @name="Jack Mapper">
mapped.where(id: 3).first # => #<UserModel:0x00007f8ec19fb3c8 @email="[email protected]", @id=3, @name="Jack Mapper">
mapped.to_a[2].surrealize # => "{\"id\":3,\"email\":\"[email protected]\"}"
Surrealist.surrealize_collection(mapped.to_a) # => "[{\"email\":\"[email protected]\"},{\"email\":\"[email protected]\"},{\"email\":\"[email protected]\"}]"
Surrealist.surrealize_collection(mapped.where { id < 4 }.to_a) # => "[{\"email\":\"[email protected]\"},{\"email\":\"[email protected]\"},{\"email\":\"[email protected]\"}]"
Sequel
Basically, Sequel returns instances only on .first
, .last
, .[]
and .with_pk!
. Collections are returned for all other methods.
Most of them are covered in spec/orms/sequel
specs, please refer to them for code examples.
Associations serialization works the same way as it does with ActiveRecord.
Usage with Dry::Types
You can use Dry::Types
for type checking. Note that Surrealist does not ship
with dry-types by default, so you should do the installation and configuration
by yourself. All built-in features of dry-types work, so if you use, say, Types::Coercible::String
,
your data will be coerced if it is able to, otherwise you will get a TypeError.
Assuming that you have defined module called Types
:
require 'dry-types'
class Car
include Surrealist
json_schema do
{
age: Types::Coercible::Integer,
brand: Types::Coercible::String,
doors: Types::Integer.optional,
horsepower: Types::Strict::Integer.constrained(gteq: 20),
fuel_system: Types::Any,
previous_owner: Types::String,
}
end
def age;
'7'
end
def previous_owner;
'John Doe'
end
def horsepower;
140
end
def brand;
'Toyota'
end
def doors; end
def fuel_system;
'Direct injection'
end
end
Car.new.surrealize
# => '{ "age": 7, "brand": "Toyota", "doors": null, "horsepower": 140, "fuel_system": "Direct injection", "previous_owner": "John Doe" }'
Delegating surrealization
You can share the json_schema
between classes:
class Host
include Surrealist
json_schema do
{ name: String }
end
def name
'Host'
end
end
class Guest
delegate_surrealization_to Host
def name
'Guest'
end
end
Host.new.surrealize
# => '{ "name": "Host" }'
Guest.new.surrealize
# => '{ "name": "Guest" }'
Schema delegation works without inheritance as well, so if you wish you can
delegate surrealization not only to parent classes, but to any class. Please note that
in this case you have to include Surrealist
in class that delegates schema as well.
class Potato
include Surrealist
delegate_surrealization_to Host
def name
'Potato'
end
end
Potato.new.surrealize
# => '{ "name": "Potato" }'
Optional arguments
Camelization
If you need to have keys in camelBack, you can pass optional camelize
argument
to #surrealize or #build_schema
. From the previous example:
Car.new.surrealize(camelize: true)
# => '{ "age": 7, "brand": "Toyota", "doors": null, "horsepower": 140, "fuelSystem": "Direct injection", "previousOwner": "John Doe" }'
Include root
If you want to wrap the resulting JSON into a root key, you can pass optional include_root
argument
to #surrealize
or #build_schema
. The root key in this case will be taken from the class name of the
surrealizable object.
class Cat
include Surrealist
json_schema do
{ weight: String }
end
def weight
'3 kilos'
end
end
Cat.new.surrealize(include_root: true)
# => '{ "cat": { "weight": "3 kilos" } }'
With nested classes the last namespace will be taken as root key:
class Animal
class Dog
include Surrealist
json_schema do
{ breed: String }
end
def breed
'Collie'
end
end
end
Animal::Dog.new.surrealize(include_root: true)
# => '{ "dog": { "breed": "Collie" } }'
Root
If you want to wrap the resulting JSON into a specified root key, you can pass optional root
argument
to #surrealize
or #build_schema
. The root
argument will be stripped of whitespaces.
class Cat
include Surrealist
json_schema do
{ weight: String }
end
def weight
'3 kilos'
end
end
Cat.new.surrealize(root: :kitten)
# => '{ "kitten": { "weight": "3 kilos" } }'
Cat.new.surrealize(root: ' kitten ')
# => '{ "kitten": { "weight": "3 kilos" } }'
This overrides the include_root
and include_namespaces
arguments.
Animal::Cat.new.surrealize(include_root: true, root: :kitten)
# => '{ "kitten": { "weight": "3 kilos" } }'
Animal::Cat.new.surrealize(include_namespaces: true, root: 'kitten')
# => '{ "kitten": { "weight": "3 kilos" } }'
Include namespaces
You can build wrap schema into a nested hash from namespaces of the object's class.
class BusinessSystem::Cashout::ReportSystem::Withdraws
include Surrealist
json_schema do
{ withdraws_amount: Integer }
end
def withdraws_amount
34
end
end
withdraws = BusinessSystem::Cashout::ReportSystem::Withdraws.new
withdraws.surrealize(include_namespaces: true)
# => '{ "business_system": { "cashout": { "report_system": { "withdraws": { "withdraws_amount": 34 } } } } }'
By default all namespaces will be taken. If you want you can explicitly specify the level of nesting:
withdraws.surrealize(include_namespaces: true, namespaces_nesting_level: 2)
# => '{ "report_system": { "withdraws": { "withdraws_amount": 34 } } }'
Configuration
There are two ways of setting default arguments for serialization,
by passing a block to Surrealist.configure
:
Surrealist.configure do |config|
config.camelize = true
config.namespaces_nesting_level = 2
end
And by passing a hash:
Surrealist.configure(camelize: true, include_root: true)
These arguments will be applied to all calls of #build_schema
and #surrealize
.
If these methods will be called with arguments, they will be merged with respect to explicitly passed ones:
Surrealist.configure(camelize: true, include_root: true)
Something.new.surrealize(camelize: false)
# will result in Something.new.surrealize(camelize: false, include_root: true)
Hash serialization
You can pass a hash to serializer and it will use the keys instead of methods.
class HashSerializer < Surrealist::Serializer
json_schema { { string: String, int: Integer } }
end
HashSerializer.new(string: 'string', int: 4).surrealize
# => '{ "string": "string", "int": 4}'
HashSerializer.new(string: 'string', int: 'not int').surrealize
# => Surrealist::InvalidTypeError: Wrong type for key `int`. Expected Integer, got String.
Bool and Any
If you have a parameter that is of boolean type, or if you don't care about the type, you
can use Bool
and Any
respectively.
class User
include Surrealist
json_schema do
{
age: Any,
admin: Bool,
}
end
end
Type Errors
Surrealist::InvalidTypeError
is thrown if types (and dry-types) mismatch.
class CreditCard
include Surrealist
json_schema do
{ number: Integer }
end
def number
'string'
end
end
CreditCard.new.surrealize
# => Surrealist::InvalidTypeError: Wrong type for key `number`. Expected Integer, got String.
Undefined methods in schema
Surrealist::UndefinedMethodError
is thrown if a key defined in the schema does not have
a corresponding method defined in the object.
class Car
include Surrealist
json_schema do
{ weight: Integer }
end
end
Car.new.surrealize
# => Surrealist::UndefinedMethodError: undefined method `weight' for #<Car:0x007f9bc1dc7fa8>. You have probably defined a key in the schema that doesn't have a corresponding method.
Other notes
- nil values are allowed by default, so if you have, say,
age: String
, but the actual value is nil, type check will be passed. If you want to be strict aboutnil
s consider usingDry::Types
. - Surrealist officially supports MRI Ruby 2.3+ but should be working on other platforms as well.
Roadmap
Here is a list of features that are not implemented yet (contributions are welcome):
- Automatic endpoint documentation
- API for validating (contracts) without actually serializing to JSON (maybe with deserialization from JSON)
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/nesaulov/surrealist. 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.
Credits
The icon was created by Simon Child from Noun Project and is published under Creative Commons License
Authors
Created by Nikita Esaulov with help from Alessandro Minali and Alexey Bespalov.
License
The gem is available as open source under the terms of the MIT License.