By Adriano Di Giovanni in Domain-Driven Design (DDD) — Oct 15, 2024

Understanding Value Object

What it is, when to use it, and how to model it effectively.

Value Object is a tactical design pattern in Domain-Driven Design (DDD), as introduced in Eric Evans's Domain-Driven Design: Tackling Complexity in the Heart of Software. It was previously featured in Martin Fowler's Patterns of Enterprise Application Architecture.

Value Object represents a domain concept by encapsulating its values, protecting its invariants, and enforcing its business rules. This definition aligns with common tactical design patterns, but let's dive deeper into Value Objects specifically.

While it's often described as lacking identity, I offer a different perspective, which I explore further in Identity in software design.

Identity is about defining uniqueness and sameness. In software design, identity is relative, based on a specific criterion or Sortal that determines both.

For Value Objects, the Sortal is the content, with uniqueness defined by the content itself, and sameness determined by comparing that content through value equality. Since content defines uniqueness, Value Objects are inherently immutable.

This immutability makes them ideal for representing immutable domain concepts that quantify or describe others that may change. Value Objects often represent quantities, measurements, or observations as conceptual wholes, providing operations to manipulate and combine them. These operations are deterministic and produce Side-Effect-Free Behavior, ensuring referential transparency.

Thanks to this immutability, Value Objects also prevent aliasing issues, ensuring that multiple references to the same object do not lead to unintended side effects or state changes.

Value Objects enhance explicitness, preventing validation and duplication issues that often arise when modeling domain concepts using primitive types. They harness the type system to cohesively represent domain concepts, keeping validation and business logic centralized and avoiding the pitfalls of an anemic domain model.

To better understand what a Value Object is, when to use it, and how to model it, let's explore an example comparing implementations using primitives and Value Objects in a language without special constructs for Value Objects like TypeScript.

The listing below shows the Elevator and Load entities interact to manage the total weight of loads boarding into the elevator while ensuring that its capacity isn't exceeded:

	import { Elevator } from './elevator';
	import { Load } from './load';

	describe(Elevator.name, () => {
	it('should throw a RangeError when attempting to create an elevator with negative capacity', () => {
	expect(() => new Elevator(-1)).toThrow(RangeError);
	});

	it('should successfully create an elevator with a valid capacity', () => {
	const capacity = 400;
	const elevator = new Elevator(capacity);
	expect(elevator).toBeDefined();
	expect(elevator.capacity).toEqual(capacity);
	});

	it('should initialize with a load weight of 0', () => {
	const elevator = new Elevator(400);
	expect(elevator.calculateLoadWeight()).toEqual(0);
	});

	it('should correctly calculate the load weight after a single load is boarded', () => {
	const load = new Load(50);
	const elevator = new Elevator(400);
	elevator.boardLoad(load);
	expect(elevator.calculateLoadWeight()).toEqual(load.weight);
	});

	it('should correctly calculate the load weight after multiple loads are boarded', () => {
	const load1 = new Load(50);
	const load2 = new Load(65);
	const elevator = new Elevator(400);
	elevator.boardLoad(load1);
	elevator.boardLoad(load2);
	expect(elevator.calculateLoadWeight()).toEqual(load1.weight + load2.weight);
	});

	it('should throw a RangeError when the total load weight exceeds the elevator capacity', () => {
	expect(() => {
	const load1 = new Load(200);
	const load2 = new Load(201);
	const elevator = new Elevator(400);
	elevator.boardLoad(load1);
	elevator.boardLoad(load2);
	}).toThrow(RangeError);
	});
	});

view raw elevator.spec.ts hosted with ❤ by GitHub

	import { Load } from './load';

	export class Elevator {
	private readonly loads: Load[] = [];

	constructor(readonly capacity: number) {
	if (capacity < 0) {
	throw new RangeError('Capacity must be greater than or equal to 0');
	}
	}

	boardLoad(load: Load): void {
	const currentLoadWeight = this.calculateLoadWeight();
	const projectedLoadWeight = currentLoadWeight + load.weight;
	if (projectedLoadWeight > this.capacity) {
	throw new RangeError('Load weight exceeds elevator capacity');
	}
	this.loads.push(load);
	}

	calculateLoadWeight(): number {
	return this.loads.reduce((loadWeight, load) => loadWeight + load.weight, 0);
	}
	}

view raw elevator.ts hosted with ❤ by GitHub

	import { Load } from './load';

	describe(Load.name, () => {
	it('should throw when weight is negative', () => {
	expect(() => new Load(-1)).toThrow(RangeError);
	});
	});

view raw load.spec.ts hosted with ❤ by GitHub

	export class Load {
	constructor(readonly weight: number) {
	if (weight < 0) {
	throw new RangeError('Weight must be greater than or equal to 0');
	}
	}
	}

view raw load.ts hosted with ❤ by GitHub

Using primitives like number for weights introduces several issues:

Implicit meaning. The concept of weight is only implied by variable names like capacity and weight, leading to potential inconsistencies.
Implicit units. Weight is a quantity combining a value and a unit associated with it, but the unit is implied and unknown unless explicitly stated wherever it's used.
Inconsistent validation. Weight must be non-negative, but the primitive type does not enforce this invariant, requiring defensive programming in constructors and methods, which can lead to inconsistencies across the system.
Broken encapsulation. The `capacity` and `weight` attributes are public, meaning it is not possible to control access through behavior.
No enforcement of combination logic. Without encapsulation, the logic for combining weights through addition is not enforced by the type system, meaning there's no guarantee the weights will always be combined in a valid or meaningful way.

By contrast, implementing weight as a Value Object provides a more robust design. Since its identity is based on its content (a value and a unit), it naturally fits the immutable nature of concepts like weight, which quantifies load and elevator capacity.

The listing below shows a minimal implementation of the Weight Value Object and its usage by Load and Elevator.

	export const KILOGRAM_TO_POUND = 2.20462;
	export const POUND_TO_KILOGRAM = 0.453592;

view raw constants.ts hosted with ❤ by GitHub

	import { Elevator } from './elevator';
	import { Load } from './load';
	import { Weight } from './weight';
	import { WeightUnit } from './weight-unit.enum';

	describe(Elevator.name, () => {
	it('should successfully create an elevator with a valid capacity', () => {
	const capacity = new Weight(400, WeightUnit.Kilogram);
	const elevator = new Elevator(capacity);
	expect(elevator).toBeDefined();
	expect(elevator.capacity.equals(capacity)).toBe(true);
	});

	it('should initialize with a load weight of 0', () => {
	const elevator = new Elevator(new Weight(400, WeightUnit.Kilogram));
	expect(elevator.calculateLoadWeight()).toEqual(
	new Weight(0, WeightUnit.Kilogram)
	);
	});

	it('should correctly calculate the load weight after a single load is boarded', () => {
	const elevator = new Elevator(new Weight(400, WeightUnit.Kilogram));
	const load = new Load(new Weight(50, WeightUnit.Kilogram));
	elevator.boardLoad(load);
	expect(elevator.calculateLoadWeight()).toEqual(load.weight);
	});

	it('should correctly calculate the load weight after multiple loads are boarded', () => {
	const load1 = new Load(new Weight(50, WeightUnit.Kilogram));
	const load2 = new Load(new Weight(100, WeightUnit.Kilogram));
	const elevator = new Elevator(new Weight(400, WeightUnit.Kilogram));
	elevator.boardLoad(load1);
	elevator.boardLoad(load2);
	expect(elevator.calculateLoadWeight()).toEqual(
	load1.weight.add(load2.weight)
	);
	});

	it('should throw a RangeError when the total load weight exceeds the elevator capacity', () => {
	expect(() => {
	const load1 = new Load(new Weight(200, WeightUnit.Kilogram));
	const load2 = new Load(new Weight(201, WeightUnit.Kilogram));
	const elevator = new Elevator(new Weight(400, WeightUnit.Kilogram));
	elevator.boardLoad(load1);
	elevator.boardLoad(load2);
	}).toThrow(RangeError);
	});
	});

view raw elevator.spec.ts hosted with ❤ by GitHub

	import { Load } from './load';
	import { Weight } from './weight';

	export class Elevator {
	private readonly loads: Load[] = [];

	constructor(readonly capacity: Weight) {}

	boardLoad(load: Load): void {
	const currentLoadWeight = this.calculateLoadWeight();
	const projectedLoadWeight = currentLoadWeight.add(load.weight);
	if (projectedLoadWeight.isGreaterThan(this.capacity)) {
	throw new RangeError('Load weight exceeds elevator capacity');
	}
	this.loads.push(load);
	}

	calculateLoadWeight(): Weight {
	return this.loads.reduce(
	(loadWeight, load) => loadWeight.add(load.weight),
	this.capacity.zero()
	);
	}
	}

view raw elevator.ts hosted with ❤ by GitHub

	import { Weight } from './weight';

	export class Load {
	constructor(readonly weight: Weight) {}
	}

view raw load.ts hosted with ❤ by GitHub

	export enum WeightUnit {
	Kilogram = 'kg',
	Pound = 'lb',
	}

view raw weight-unit.enum.ts hosted with ❤ by GitHub

	import { KILOGRAM_TO_POUND, POUND_TO_KILOGRAM } from './constants';
	import { Weight } from './weight';
	import { WeightUnit } from './weight-unit.enum';

	describe.each([
	[WeightUnit.Kilogram, WeightUnit.Pound, KILOGRAM_TO_POUND],
	[WeightUnit.Pound, WeightUnit.Kilogram, POUND_TO_KILOGRAM],
	])(Weight.name, (unit, otherUnit, conversionFactor) => {
	it('should throw a RangeError when attempting to create a weight with negative value', () => {
	expect(() => new Weight(-1, unit)).toThrow(RangeError);
	});

	it.each([0, 50])(
	'should successfully create a weight with a valid value',
	() => {
	const weight = new Weight(50, unit);
	expect(weight).toBeDefined();
	}
	);

	describe(Weight.prototype.add.name, () => {
	it('should add a weight with the same unit', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(2, unit);
	const actualWeight = weight1.add(weight2);
	const expectedWeight = new Weight(3, unit);
	expect(actualWeight.equals(expectedWeight)).toBe(true);
	});

	it('should add a weight with a different unit', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(1 * conversionFactor, otherUnit);
	const actualWeight = weight1.add(weight2);
	const expectedWeight = new Weight(2, unit);
	expect(actualWeight.equals(expectedWeight)).toBe(true);
	});
	});

	describe(Weight.prototype.compareTo.name, () => {
	it('should return 0 when comparing to itself', () => {
	const weight = new Weight(50, unit);
	expect(weight.compareTo(weight)).toBe(0);
	});

	it(
	'should return 0' +
	' when comparing to another weight with the same value and unit',
	() => {
	const weight1 = new Weight(50, unit);
	const weight2 = new Weight(50, unit);
	expect(weight1.compareTo(weight2)).toBe(0);
	}
	);

	it(
	'should return 0' +
	' when comparing to another weight with the same value but different unit',
	() => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(1 * conversionFactor, otherUnit);
	expect(weight1.compareTo(weight2)).toBe(0);
	}
	);

	it('should return -1 when comparing to a weight with a greater value', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(2, unit);
	expect(weight1.compareTo(weight2)).toBe(-1);
	});

	it('should return 1 when comparing to a weight with a lesser value', () => {
	const weight1 = new Weight(2, unit);
	const weight2 = new Weight(1, unit);
	expect(weight1.compareTo(weight2)).toBe(1);
	});

	it(
	'should return -1' +
	' when comparing to a weight with a greater value in a different unit',
	() => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(2 * conversionFactor, otherUnit);
	expect(weight1.compareTo(weight2)).toBe(-1);
	}
	);

	it(
	'should return 1' +
	' when comparing to a weight with a lesser value in a different unit',
	() => {
	const weight1 = new Weight(2 * conversionFactor, otherUnit);
	const weight2 = new Weight(1, unit);
	expect(weight1.compareTo(weight2)).toBe(1);
	}
	);
	});

	describe(Weight.prototype.convertTo.name, () => {
	it('should convert weight to the same unit', () => {
	const weight = new Weight(50, unit);
	const convertedWeight = weight.convertTo(unit);
	expect(weight.equals(convertedWeight)).toBe(true);
	});

	it('should convert between units', () => {
	const weight = new Weight(1, unit);
	const convertedWeight = weight.convertTo(otherUnit);
	const expectedWeight = new Weight(1 * conversionFactor, otherUnit);
	expect(convertedWeight.equals(expectedWeight)).toBe(true);
	});
	});

	describe(Weight.prototype.equals.name, () => {
	it('should equal itself', () => {
	const weight = new Weight(1, unit);
	expect(weight.equals(weight)).toBe(true);
	});

	it('should equal another weight with the same value and unit', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(1, unit);
	expect(weight1.equals(weight2)).toBe(true);
	});

	it('should equal another weight with the same value but different unit', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(1 * conversionFactor, otherUnit);
	expect(weight1.equals(weight2)).toBe(true);
	});

	it('should not equal another weight with the same unit but different value', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(2, unit);
	expect(weight1.equals(weight2)).toBe(false);
	});

	it('should not equal another weight with the same value but different unit', () => {
	const weight1 = new Weight(1, unit);
	const weight2 = new Weight(1, otherUnit);
	expect(weight1.equals(weight2)).toBe(false);
	});
	});
	});

view raw weight.spec.ts hosted with ❤ by GitHub

	import { KILOGRAM_TO_POUND, POUND_TO_KILOGRAM } from './constants';
	import { WeightUnit } from './weight-unit.enum';

	export class Weight {
	private static readonly Epsilon = 1e-5;
	constructor(
	private readonly value: number,
	private readonly unit: WeightUnit
	) {
	if (value < 0) {
	throw new RangeError('Weight must be greater than or equal to 0');
	}
	}

	add(other: Weight): Weight {
	const convertedOther = other.convertTo(this.unit);
	return new Weight(this.value + convertedOther.value, this.unit);
	}

	compareTo(other: Weight): number {
	const convertedOther = other.convertTo(this.unit);
	const difference = this.value - convertedOther.value;
	return Math.abs(difference) < Weight.Epsilon ? 0 : Math.sign(difference);
	}

	convertTo(unit: WeightUnit): Weight {
	if (unit === this.unit) {
	return this;
	}
	const coefficient =
	this.unit === WeightUnit.Kilogram ? KILOGRAM_TO_POUND : POUND_TO_KILOGRAM;
	const newValue = this.value * coefficient;
	return new Weight(newValue, unit);
	}

	equals(other: Weight): boolean {
	const convertedOther = other.convertTo(this.unit);
	return Math.abs(this.value - convertedOther.value) < Weight.Epsilon;
	}

	isGreaterThan(other: Weight): boolean {
	return this.compareTo(other) > 0;
	}

	zero(): Weight {
	return new Weight(0, this.unit);
	}
	}

view raw weight.ts hosted with ❤ by GitHub

Even this basic implementation offers clear benefits:

Explicit meaning. The concept of weight is explicitly modeled and reusable across the system.
Explicit units. Weight represents the conceptual whole of a quantity combining a value and a unit, enabling conversions between units and combinations of weights using different units.
Consistent validation. Invariants such as non-negative values are protected within the Weight class.
Strong encapsulation. The capacity and weight attributes are private, ensuring controlled access through behavior.
Enforced combination logic. The type system guarantees that weight combinations are valid and meaningful.

Although the Value Object approach may seem more complex, it efficiently addresses complexities overlooked when using primitive types, from ensuring domain explicitness to managing floating-point comparisons. More importantly, Software is a medium for storing executable knowledge, and using Value Objects helps make the code and tests valuable learning resources.

The simplicity and immutability of Value Objects make them easy to create, test, use, optimize, and maintain. When appropriate, prefer modeling domain concepts as Value Objects.

In summary, a Value Object:

Represents a domain concept by encapsulating its values, protecting its invariants, and enforcing its business rules.
Is identified by its content, with uniqueness defined by the content itself, and sameness determined by comparing that content through value equality.
Is inherently immutable.
Represents immutable domain concepts that quantify or describe others that may change.
Ensures referential transparency through deterministic operations that provide Side-Effect-Free Behavior.

For simplicity, I haven’t covered serialization and persistence of Value Objects, standard and tiny types, or discussed implementing interfaces like Comparable and Equatable, which are often used in Value Object implementations. These topics, along with other related considerations, will be explored in future articles.

References

Evans, E. (2003). Domain-driven design: Tackling complexity in the heart of software. Addison-Wesley.
Fowler, M. (2002). Patterns of enterprise application architecture. Addison-Wesley.
Vernon, V. (2013). Implementing domain-driven design. Addison-Wesley Professional.
Beck, K. (2002). Test driven development: By example. Addison-Wesley Professional.
Fowler, M. (2015). Analysis patterns: Reusable object models. Addison-Wesley Professional.
Millett, S., & Tune, N. (2015). Patterns, principles, and practices of domain-driven design. Wrox.
Vernon, V. (2016). Domain-driven design distilled. Addison-Wesley Professional.

References

Subscribe to Adriano Di Giovanni