As Ruby on Rails developers, we tend to add too much code in the same ActiveRecord
model. Very often, this is because we fail to identify new objects. This article presents a concrete tool that helps keep our ActiveRecord
models sizes under control thanks to the serialize method.
Identifying value objects in Rails
Let's take a concrete example. Imagine that we are working on an invoicing system, each invoice being composed of multiple line items. Our Invoice model would look like this:
class Invoice < ApplicationRecord
has_many :line_items, dependent: :destroy
end
In our example, a LineItem
will have a quantity
stored as an integer and a unit_price
stored as a decimal. The LineItem
model would look like this:
class LineItem < ApplicationRecord
belongs_to :invoice
validates :quantity, numericality: { only_integer: true, greater_than: 0 }
validates :unit_price, numericality: { greater_than: 0 }
def total_price
(unit_price * quantity).round(2)
end
end
Let's now imagine a new requirement: we have to handle VAT rates of 0%, 10%, and 20% on line items, 0% VAT rate being for tourist taxes. The most straightforward implementation would probably be to add all of the VAT rates in the LineItem
model as it already exists. We would add a tax_code string field in our line_items
table, and our LineItem
model would start growing:
class LineItem < ApplicationRecord
# previous associations and validations
TAX_CODES = { vat_0: 0.0, vat_10: 0.1, vat_20: 0.2 }
validates :tax_code, inclusion: { in: TAX_CODES.keys.map(&:to_s) }
def tax_rate
TAX_CODES[tax_code.to_sym]
end
def tourist_tax?
tax_code.to_sym == :vat_0
end
# We now have to take the tax_rate into account
def total_price
(unit_price * quantity * (1 + tax_rate)).round(2)
end
end
This is a very simple example of course but failing to identify value objects creates two issues:
- Our
LineItem
model is doing too much. Failing to identify new objects will make the model longer and longer, and it will harm readability sooner or later. - Tax-related information is now entangled inside of our LineItem model. If we want to reuse tax codes elsewhere in our application, we are stuck.
Tax codes represent something important in our application and we should give them a proper place to live.
Extracting value objects in Rails
We are first going to give this object a new home and a new name. With a few minor changes, we have extracted all the methods in the TaxCode
object:
# app/models/tax_code.rb
class TaxCode
TAX_CODES = { vat_0: 0.0, vat_10: 0.1, vat_20: 0.2 }
attr_reader :key
def initialize(key)
@key = key.to_sym
end
def tax_rate
TAX_CODES[key]
end
def tourist_tax?
key == :vat_0
end
end
Our LineItem
model is now much smaller and focused on its main responsibility as we removed all the tax code related code:
class LineItem < ApplicationRecord
# previous associations and validations
validates :tax_code, inclusion: { in: TaxCode::TAX_CODES.keys.map(&:to_s) }
def total_price
(unit_price * quantity * (1 + tax_rate)).round(2)
end
def tax_rate
TaxCode.new(tax_code).tax_rate
end
end
There is still one issue to solve: The LineItem#tax_code
does not return a TaxCode
object. Let's demonstrate this issue in the rails console:
line_item = LineItem.create(quantity: 1, unit_price: 100, tax_code: :vat_20)
line_item.tax_code
=> "vat_20"
We want to get a TaxCode
object when calling the LineItem#tax_code
method. Luckily, Rails provides a way to do precisely that, thanks to the serialize method. Let's instruct the LineItem model that its tax_code method should return a TaxCode object:
class LineItem < ApplicationController
serialize :tax_code, TaxCode
# all the previous code...
end
For the .serialize
method to work, TaxCode
should implement both the .load
and .dump
class methods. As mentioned in the documentation, .dump
will be called to serialize an object and should return the serialized value to be stored in the database. On the other hand, .load
will be called to reverse the process and deserialize from the database. In our case, that means converting a string into a TaxCode
object.
Let's add those two class methods to the TaxCode
class:
# app/models/tax_code.rb
class TaxCode
def self.load(key)
# We don't want to build TaxCodes with a nil key
new(key) if key
end
def self.dump(tax_code)
case tax_code
when self then tax_code.key
else tax_code
end
end
# all the previous code...
end
Great! Now the LineItem#tax_code
method should return a TaxCode
object! Let's update the validations and the LineItem#total_price
method accordingly:
class LineItem
# all the previous code
validates :tax_code, inclusion: { in: TaxCode.all }
def total_price
(unit_price * quantity * (1 + tax_code.tax_rate)).round(2)
end
end
Let's add the .all
method on TaxCode
and the #==
method to be able to compare two tax codes as it is necessary for the inclusion validation to be able to compare them:
# app/models/tax_code.rb
class TaxCode
# all the previous code...
def self.all
TAX_CODES.keys.map { |key| new(key) }
end
# Tax codes are equal if they have the same key
def ==(other)
if other.is_a?(self.class)
key == other.key
end
end
end
Let's restart our rails console and try again:
line_item = LineItem.create(quantity: 1, unit_price: 100, tax_code: :vat_20)
line_item.tax_code
=> <TaxCode:0x00007fd0c6316728 @key=:vat_20>
That was a lot of work! Let's look at the final implementation of the LineItem
model:
class LineItem < ApplicationRecord
belongs_to :invoice
validates :quantity, numericality: { only_integer: true, greater_than: 0 }
validates :unit_price, numericality: { greater_than: 0 }
validates :tax_code, inclusion: { in: TaxCode.all }
serialize :tax_code, TaxCode
def total_price
(unit_price * quantity * (1 + tax_code.tax_rate)).round(2)
end
end
As we can see, our model is very small and only focused on line items related calculations. All taxes related code has been extracted to the TaxCode class.
We can notice the same beneficial effects in the TaxCode
class. All tax-related code is isolated in a small class with a single responsibility:
# app/models/tax_code.rb
class TaxCode
TAX_CODES = { vat_0: 0.0, vat_10: 0.1, vat_20: 0.2 }
def self.load(key)
new(key) if key
end
def self.dump(tax_code)
case tax_code
when self then tax_code.key
else tax_code
end
end
def self.all
TAX_CODES.keys.map { |key| new(key) }
end
attr_reader :key
def initialize(key)
@key = key.to_sym
end
def tax_rate
TAX_CODES[key]
end
def tourist_tax?
key == :vat_0
end
def ==(other)
if other.is_a?(self.class)
key == other.key
end
end
end
Our TaxCode
model is now completely extracted and can be reused anywhere inside our application!
Serialization in the wild
Admittedly, our value object example is a bit simple. Let's explore a real-world example. ActionText
is a part of the Ruby on Rails framework and enables us to add rich text to our applications with just one line of code. To add rich text to an Article
model for example, we would simply add the following line to our model:
class Article < ApplicationRecord
has_rich_text :content
end
Under the hood, the .has_rich_text
method defines a has_one
association with an object of class ActionText::RichText
. The ActionText::RichText
object holds the rich text inside the database in a body field that gets serialized in an ActionText::Content
object.
module ActionText
class RichText < Record
serialize :body, ActionText::Content
# ...
end
end
The ActionText::Content
object does much more than our simple TaxCode
example of course; it defines many more methods! The .load
and .dump
methods are defined in the ActionText::Serialization
concern that is included in ActionText::Content
.
Did you like this article?
You can follow me on Twitter as I announce all my articles there!
Top comments (2)
👌👌👌
Awesome !