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.