29
.
04
.
2024
14
.
07
.
2022
Ruby on Rails
Domain-Driven Design
Backend
Tutorial

Value Object - DDD in Ruby on Rails

Paweł Strzałkowski
Chief Technology Officer

In this episode of "DDD in Ruby on Rails" I will introduce one of the building blocks of tactical Domain-Driven Design - a value object.

"An object that represents a descriptive aspect of the domain with no conceptual identity is called a VALUE OBJECT. VALUE OBJECTS are instantiated to represent elements of the design that we care about only for what they are, not who or which they are"

Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software

Value Object

Value Object is an immutable object, used to represent a value. It can be compared with other value objects to check whether the represented values are equal. It has no identity and no observable history.

The most famous value object, used by most of us, is Money. It represents a combination of an amount and a currency. Together, they form a value (ie. $5). Another example is a combination of latitude and longitude, which together have a meaning of geographic coordinates.

Whenever two (or more) primitive attributes gain proper meaning when read together, it is possible that they should be encapsulated within a single value object. Such transformation gives an explicit meaning to primitives scattered around an entity. It sometimes makes sense to elevate a single primitive to a value object. It allows to show its importance and meaning in the overall design.

Let's go through a real-life story to see how a value object can be used in Ruby on Rails.

We’ve got a job to do

We needed to start tracking events (expressed as strings, for example "User created"). For that, I have created a very simple service object. It had only one purpose - use Analytics::Client to track event names passed as strings.


module Analytics
  class TrackEventService
    def initialize(user:, event:)
      # ...
    end

    def call
      return false unless Configuration.enabled?

      Client.track(
        user_id: user.id,
        event: event,
        properties: properties
      )
    end

    # ...
  end
end

# Usage example

Analytics::TrackEventService.new(user: user, event: 'Item added').call

We can make it better

Primitive strings proved to be error prone, hard to track throughout the application and simply unreliable. After a while, the application ended up with events like "Job Created", "Created job" and so on. It has been suggested to implement a common event name handler and pass a noun and a verb separately.


module Analytics
  class TrackEventService
    def initialize(user:, noun:, verb:)
      # ...
    end

    def call
      # ...
    end

    private

    def event
      "#{noun} #{verb}"
    end

    # ...
  end
end

# Usage example

Analytics::TrackEventService.new(user: user, noun: 'Item', verb: 'Added').call

But… There are exceptions

A new requirement has come. We needed to handle exceptions and define events as custom strings like "Important Job Almost Created" yet again. At this point, we wanted to pass either a noun + verb pair or an event name.

Let's do it!


module Analytics
  class TrackEventService
    def initialize(user:, noun: nil, verb: nil, event: nil)
      # ...
    end

    def call
      return false unless Configuration.enabled?

      Client.track(
        user_id: user.id,
        event: event_name,
        properties: properties
      )
    end

    private

    def event_name
      return event if event.present?

      "#{noun} #{verb}"
    end

    # ...
  end
end

# Usage example

Analytics::TrackEventService.new(user: user, noun: 'Item', verb: 'Added').call
Analytics::TrackEventService.new(user: user, event: 'Item added to cart').call

There is an immediate problem with this service. It's hard to test. Mostly because, in this form, it violates the Single Responsibility Principle. Outside of its primary purpose (communication), it is also responsible for handling changing business needs by gluing 3 terms together. This kind of classes tend to grow fast and loose cohesion in the blink of an eye.

Let's use a value object

According to the definition, a value object is immutable and represents a value. In order to use this pattern, I've created an Analytics::Event class. It takes either a name (through its constructor) or a combination of a noun and a verb (through the class method combination_of) and provides a unified reading interface (name reader).


module Analytics
  class Event
    attr_reader :name

    def initialize(name:)
      @name = name.to_s
    end

    def self.combination_of(noun:, verb:)
      new(name: "#{noun} #{verb}")
    end

    def ==(other) # when comparing, we should compare values
      name == other.name 
    end
  end
end

It has replaced the primitive strings in the service implementation:


module Analytics
  class TrackEventService
    def initialize(user:, event:)
      self.user = user
      self.event = event
    end

    def call
      return false unless Configuration.enabled?

      Client.track(
        user_id: user.id,
        event: event.name,
        properties: properties
      )
    end

    # ...
  end
end

It is no longer the job of this service to know how to construct event's name. The responsibility has been moved to the value object and can be easily tested. It's straightforward to use, readable, testable and reusable.


Analytics::TrackEventService.new(
  user: user,
  event: Analytics::Event.combination_of(noun: 'Jon', verb: 'Created')
)

Analytics::TrackEventService.new(
  user: user,
  event: Analytics::Event.new(name: 'Cloned and archived related clients')
)

Value Objects in Ruby on Rails

The Ruby on Rails framework supports value objects in the form of the composed_of method. You can read more about it at https://apidock.com/rails/ActiveRecord/Aggregations/ClassMethods/composed_of

It allows you to treat a subset of an ActiveRecord entity's attributes as a value object.


# Value Object class definition

class Coordinates
  attr_reader :lat, :lon

  def initialize(lat, lon)
    @lat = lat
    @lon = lon
  end

  def ==(other)
    lat === other.lat && lon == other.lon
  end

    # ... How else can equality be checked?
end


# ActiveRecord class

class Location < ApplicationRecord
  composed_of :coordinates,
              class_name: 'Coordinates',
              mapping: [
                %w[latitude lat],
                %w[longitude lon]
              ]
end


# How to use

> a = Location.new(name: 'Warsaw One', latitude: '52.23', longitude: '21.01')
> b = Location.new(name: 'Warsaw Two', latitude: '52.23', longitude: '21.01')
> c = Location.new(name: 'London', latitude: '51.50', longitude: '-0.13')

> a.coordinates
 => #<Coordinates:0x00007fa846f7c5d8 @lat="21.01", @lon="52.23">

> a.latitude
 => "52.23"

> a.coordinates == b.coordinates
 => true

> a.coordinates == c.coordinates
 => false

Value Object’s equality

There is more than one way to check for equality in Ruby. The above examples work well for a simple == comparison. But what about eql?, which is based on the output of an internal .hashmethod? Be sure to override it to make it dependent only on the object’s value.


# Example from Money gem
# https://github.com/RubyMoney/money/blob/main/lib/money/money.rb

class Money
  # ...

  def hash
    [fractional.hash, currency.hash].hash
  end

  # ...
end

Summary

No matter if you use the composed_of method or if you create your own objects - Value Objects are a great tool to introduce consistency, testability and readability to your code. Use them and make your code better.

If you'd like to know more, I encourage you to read about the concept. As anything within the DDD realm, they are widely used in other programming languages. It makes it easy to find good examples. You may start from a great article by Martin Fowler, linked below.

Resources

Articles in this series

Paweł Strzałkowski
Chief Technology Officer

Check my Twitter

Check my Linkedin

Did you like it? 

Sign up To VIsuality newsletter

READ ALSO

Vector Search in Ruby - Paweł Strzałkowski

Vector Search in Ruby

17
.
03
.
2024
Paweł Strzałkowski
ChatGPT
Embeddings
Postgresql
Ruby
Ruby on Rails
LLM Embeddings in Ruby - Paweł Strzałkowski

LLM Embeddings in Ruby

17
.
03
.
2024
Paweł Strzałkowski
Ruby
LLM
Embeddings
ChatGPT
Ollama
Handling Errors in Concurrent Ruby, Michał Łęcicki

Handling Errors in Concurrent Ruby

14
.
11
.
2023
Michał Łęcicki
Ruby
Ruby on Rails
Tutorial
Recap of Friendly.rb 2024 conference

Insights and Inspiration from Friendly.rb: A Ruby Conference Recap

02
.
10
.
2024
Kaja Witek
Conferences
Ruby on Rails

Covering indexes - Postgres Stories

14
.
11
.
2023
Jarosław Kowalewski
Ruby on Rails
Postgresql
Backend
Ula Sołogub - SQL Injection in Ruby on Rails

The Deadly Sins in RoR security - SQL Injection

14
.
11
.
2023
Urszula Sołogub
Backend
Ruby on Rails
Software
Michal - Highlights from Ruby Unconf 2024

Highlights from Ruby Unconf 2024

14
.
11
.
2023
Michał Łęcicki
Conferences
Visuality
Cezary Kłos - Optimizing Cloud Infrastructure by $40 000 Annually

Optimizing Cloud Infrastructure by $40 000 Annually

14
.
11
.
2023
Cezary Kłos
Backend
Ruby on Rails

Smooth Concurrent Updates with Hotwire Stimulus

14
.
11
.
2023
Michał Łęcicki
Hotwire
Ruby on Rails
Software
Tutorial

Freelancers vs Software house

02
.
10
.
2024
Michał Krochecki
Visuality
Business

Table partitioning in Rails, part 2 - Postgres Stories

14
.
11
.
2023
Jarosław Kowalewski
Backend
Postgresql
Ruby on Rails

N+1 in Ruby on Rails

14
.
11
.
2023
Katarzyna Melon-Markowska
Ruby on Rails
Ruby
Backend

Turbo Streams and current user

29
.
11
.
2023
Mateusz Bilski
Hotwire
Ruby on Rails
Backend
Frontend

Showing progress of background jobs with Turbo

14
.
11
.
2023
Michał Łęcicki
Ruby on Rails
Ruby
Hotwire
Frontend
Backend

Table partitioning in Rails, part 1 - Postgres Stories

14
.
11
.
2023
Jarosław Kowalewski
Postgresql
Backend
Ruby on Rails

Table partitioning types - Postgres Stories

14
.
11
.
2023
Jarosław Kowalewski
Postgresql
Backend

Indexing partitioned table - Postgres Stories

14
.
11
.
2023
Jarosław Kowalewski
Backend
Postgresql
SQL Views in Ruby on Rails

SQL views in Ruby on Rails

14
.
11
.
2023
Jan Grela
Backend
Ruby
Ruby on Rails
Postgresql
Design your bathroom in React

Design your bathroom in React

14
.
11
.
2023
Bartosz Bazański
Frontend
React
Lazy Attributes in Ruby - Krzysztof Wawer

Lazy attributes in Ruby

14
.
11
.
2023
Krzysztof Wawer
Ruby
Software

Exporting CSV files using COPY - Postgres Stories

14
.
11
.
2023
Jarosław Kowalewski
Postgresql
Ruby
Ruby on Rails
Michał Łęcicki - From Celluloid to Concurrent Ruby

From Celluloid to Concurrent Ruby: Practical Examples Of Multithreading Calls

14
.
11
.
2023
Michał Łęcicki
Backend
Ruby
Ruby on Rails
Software

Super Slide Me - Game Written in React

14
.
11
.
2023
Antoni Smoliński
Frontend
React