Entities: Custom Schema

We can take data integrity a step further: we can optionally define our own entity internal schema.

Custom schema is optional for SQL databases, while it's mandatory for entities without a database table, or while using with a non-SQL database.

Custom schema takes precedence over automatic schema. If we use custom schema, we need to manually add all the new columns from the corresponding SQL database table.

Default mode

# lib/bookshelf/entities/user.rb
class User < Hanami::Entity
  EMAIL_FORMAT = /\@/

  attributes do
    attribute :id,         Types::Int
    attribute :name,       Types::String
    attribute :email,      Types::String.constrained(format: EMAIL_FORMAT)
    attribute :age,        Types::Int.constrained(gt: 18)
    attribute :codes,      Types::Collection(Types::Coercible::Int)
    attribute :comments,   Types::Collection(Comment)
    attribute :created_at, Types::Time
    attribute :updated_at, Types::Time
  end
end

Let’s instantiate it with proper values:

user = User.new(name: "Luca", age: 35, email: "luca@hanami.test")

user.name     # => "Luca"
user.age      # => 35
user.email    # => "luca@hanami.test"
user.codes    # => nil
user.comments # => nil

It can coerce values:

user = User.new(codes: ["123", "456"])
user.codes # => [123, 456]

Other entities can be passed as concrete instance:

user = User.new(comments: [Comment.new(text: "cool")])
user.comments
  # => [#<Comment:0x007f966be20c58 @attributes={:text=>"cool"}>]

Or as data:

user = User.new(comments: [{text: "cool"}])
user.comments
  # => [#<Comment:0x007f966b689e40 @attributes={:text=>"cool"}>]

It enforces data integrity via exceptions:

User.new(email: "foo")     # => TypeError: "foo" (String) has invalid type for :email
User.new(comments: [:foo]) # => TypeError: :foo must be coercible into Comment

Strict mode

# lib/bookshelf/entities/user.rb
class User < Hanami::Entity
  EMAIL_FORMAT = /\@/

  attributes :strict do
    attribute :id,    Types::Strict::Int
    attribute :name,  Types::Strict::String
    attribute :email, Types::Strict::String.constrained(format: EMAIL_FORMAT)
    attribute :age,   Types::Strict::Int.constrained(gt: 18)
  end
end

Let’s instantiate it with proper values:

user = User.new(id: 1, name: "Luca", age: 35, email: "luca@hanami.test")

user.id    # => 1
user.name  # => "Luca"
user.age   # => 35
user.email # => "luca@hanami.test"

It cannot be instantiated with missing keys

User.new
  # => ArgumentError: :id is missing in Hash input

User.new(id: 1, name: "Luca", age: 35)
  # => ArgumentError: :email is missing in Hash input

Or with nil:

User.new(id: 1, name: nil, age: 35, email: "luca@hanami.test")
  # => TypeError: nil (NilClass) has invalid type for :name violates constraints (type?(String, nil) failed)

It accepts strict values and it doesn’t attempt to coerce:

User.new(id: "1", name: "Luca", age: 35, email: "luca@hanami.test")
  # => TypeError: "1" (String) has invalid type for :id violates constraints (type?(Integer, "1") failed)

It enforces data integrity via exceptions:

User.new(id: 1, name: "Luca", age: 1, email: "luca@hanami.test")
  # => TypeError: 1 (Integer) has invalid type for :age violates constraints (gt?(18, 1) failed)

User.new(id: 1, name: "Luca", age: 35, email: "foo")
  # => TypeError: "foo" (String) has invalid type for :email violates constraints (format?(/\@/, "foo") failed)

Learn more about data types in the dedicated article.