3378 words

17 minutes

Value Objects & Entities in TypeScript: Building Blocks That Can't Break

2026-06-30

Series: TDD & Software Design Part 2 of 4

TDD Isn't About Bugs — It's Your Permission to Refactor

TypeScript DDD Aggregates & Repositories

Learn how Value Objects and Entities make invalid states impossible in TypeScript. Build self-validating domain code with TDD — the blocks that can't break.

TL;DR — What is a Value Object?

A Value Object is an immutable object defined entirely by its attributes. Two Email("[email protected]") are equal because their values match, not because they share a reference. Value Objects have four properties:

Immutability — created once, never modified

Equality by value — equals() compares internal state

Self-validating — cannot exist in an invalid state

No side effects — pure construction

The Validation Everywhere Problem#

Last time, I showed you how TDD gives you permission to refactor. But there’s a problem I glossed over: what happens when the same validation rule appears in five different places?

I ran into this on a real project. Email validation lived in four separate files:

1
// ❌ Scattered across the codebase
2

3
if (!req.body.email.includes("@")) {
4
  return res.status(400).json({ error: "Invalid email" });
5
}
6

7
// src/services/userService.ts
8
if (!email.includes("@")) {
9
  return err(new InvalidEmailError());
10
}
11

12
// src/middleware/validateRegistration.ts
13
if (!input.email.includes("@")) {
14
  return res.status(400).json({ field: "email", message: "Invalid" });
15
}
16

17
// src/utils/validators.ts
18
export function isValidEmail(email: string): boolean {
19
  return email.includes("@");
20
}

Four files. Four implementations. Slightly different error messages. And when the product team asked us to also reject emails longer than 254 characters, I had to find and update all four places.

I missed one. A bug shipped to production.

That’s when I realized the real problem was design — testing only revealed it. I was encoding validation into the data, not applying it to the data.

In the last article, I introduced the Result<T, E> pattern and hinted at Value Objects. I’ll build them here, with TDD driving every decision.

The thesis: Value Objects encode rules into types. Once you have them, validation disappears from your services because the types themselves reject bad data.

What Is a Value Object?#

A Value Object is an immutable object defined by its attributes, not its identity. Two Email("[email protected]") objects are equal because their values are equal, not because they share a reference.

Value Objects have four properties:

Immutability: created once, never modified
Equality by value: equals() compares internal state
Self-validating: cannot exist in an invalid state
No side effects: pure construction

This is what that looks like. Compare the primitive approach with the Value Object:

1
// ❌ Primitive: any string is "valid"
2
const email: string = "not-an-email";
3
const email2: string = "";
4

5
// ✅ Value Object: only valid emails can exist
6
class InvalidEmailError {
7
  readonly code = "INVALID_EMAIL";
8
  constructor(public readonly input: string) {}
9
}
10

11
class Email {
12
  private constructor(private readonly value: string) {}
13

14
  static create(value: string): Result<Email, InvalidEmailError> {
15
    const trimmed = value.trim().toLowerCase();
16
    if (!trimmed.includes("@") || !trimmed.includes(".")) {
17
      return err(new InvalidEmailError(value));
18
    }
19
    if (trimmed.length > 254) {
20
      return err(new InvalidEmailError(value));
21
    }
22
    return ok(new Email(trimmed));
23
  }
24

25
  getValue(): string {
26
    return this.value;
27
  }
28

29
  equals(other: Email): boolean {
30
    return this.value === other.value;
31
  }
32
}

The private constructor is the key. You can’t call new Email("garbage"). The only way to create an Email is through Email.create(), which validates the input and returns a Result. Invalid states are impossible to construct by accident — the factory refuses to produce them.

This is Domain-Driven Design 101 — Martin Fowler’s definition of Value Object is the clearest place to start. Most TypeScript developers I meet have only seen the pattern in Java/C#, where it tends to get dismissed as enterprise ceremony. That’s a mistake. It’s the simplest tool I know for eliminating an entire class of bugs.

(One assumption I’m making throughout: strict: true and strictNullChecks: true in your tsconfig.json. The discriminated-union narrowing in Result<T, E> only works safely under strict mode.)

The TDD Cycle for Value Objects#

I didn’t design Email on a whiteboard. I let tests drive it. Here’s the full red-green-refactor cycle.

Iteration 1: Basic Creation (Red)#

I started by writing the tests I wanted to pass:

1
describe("Email Value Object", () => {
2
  it("should create a valid email", () => {
3
    const result = Email.create("[email protected]");
4

5
    expect(result.ok).toBe(true);
6
    if (result.ok) {
7
      expect(result.value.getValue()).toBe("[email protected]");
8
    }
9
  });
10

11
  it("should reject email without @", () => {
12
    const result = Email.create("no-at-sign");
13

14
    expect(result.ok).toBe(false);
15
    if (!result.ok) {
16
      expect(result.error.code).toBe("INVALID_EMAIL");
17
    }
18
  });
19
});

Tests fail. Good. That’s the red phase.

Iteration 1: Basic Creation (Green)#

The simplest implementation that passes:

1
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
2

3
function ok<T>(value: T): Result<T, never> {
4
  return { ok: true, value };
5
}
6

7
function err<E>(error: E): Result<never, E> {
8
  return { ok: false, error };
9
}
10

11
class InvalidEmailError {
12
  readonly code = "INVALID_EMAIL";
13
  constructor(public readonly input: string) {}
14
}
15

16
class Email {
17
  private constructor(private readonly value: string) {}
18

19
  static create(value: string): Result<Email, InvalidEmailError> {
20
    if (!value.includes("@")) {
21
      return err(new InvalidEmailError(value));
22
    }
23
    return ok(new Email(value));
24
  }
25

26
  getValue(): string {
27
    return this.value;
28
  }
29
}

Tests pass. Green.

Iteration 2: Edge Cases (Red)#

Now I push the design by adding more tests:

1
it("should normalize email to lowercase", () => {
2
  const result = Email.create("[email protected]");
3

4
  expect(result.ok).toBe(true);
5
  if (result.ok) {
6
    expect(result.value.getValue()).toBe("[email protected]");
7
  }
8
});
9

10
it("should trim whitespace", () => {
11
  const result = Email.create("  [email protected]  ");
12

13
  expect(result.ok).toBe(true);
14
  if (result.ok) {
15
    expect(result.value.getValue()).toBe("[email protected]");
16
  }
17
});
18

19
it("should reject empty string", () => {
20
  const result = Email.create("");
21

22
  expect(result.ok).toBe(false);
23
});
24

25
it("should reject email without a domain suffix", () => {
26
  const result = Email.create("user@localhost");
27

28
  expect(result.ok).toBe(false);
29
});
30

31
it("should reject email over 254 characters", () => {
32
  const long = "a".repeat(250) + "@b.co";
33
  const result = Email.create(long);
34

35
  expect(result.ok).toBe(false);
36
});

Iteration 2: Edge Cases (Green)#

I update Email.create() to pass all tests:

1
static create(value: string): Result<Email, InvalidEmailError> {
2
  const trimmed = value.trim().toLowerCase();
3
  if (!trimmed.includes("@") || !trimmed.includes(".")) {
4
    return err(new InvalidEmailError(value));
5
  }
6
  if (trimmed.length > 254) {
7
    return err(new InvalidEmailError(value));
8
  }
9
  return ok(new Email(trimmed));
10
}

Green. All tests pass.

Iteration 3: Equality (Red)#

One more behavior I need: can I compare two emails?

1
describe("Email Equality", () => {
2
  it("should consider same emails equal", () => {
3
    const a = Email.create("[email protected]");
4
    const b = Email.create("[email protected]");
5

6
    if (a.ok && b.ok) {
7
      expect(a.value.equals(b.value)).toBe(true);
8
    }
9
  });
10

11
  it("should consider different emails unequal", () => {
12
    const a = Email.create("[email protected]");
13
    const b = Email.create("[email protected]");
14

15
    if (a.ok && b.ok) {
16
      expect(a.value.equals(b.value)).toBe(false);
17
    }
18
  });
19
});

Iteration 3: Equality (Green)#

1
equals(other: Email): boolean {
2
  return this.value === other.value;
3
}

The insight: the equals() method only exists because a test required it. I didn’t plan it upfront. TDD exerted design pressure: the tests told me what the object needed to do, and I responded.

This is what I mean when I say TDD is design work. The tests come along for the ride.

Building More Value Objects#

Once you’ve built one Value Object, the pattern repeats. Same shape. Same TDD cycle. Two more examples follow.

Age Value Object#

1
class InvalidAgeError {
2
  readonly code = "INVALID_AGE";
3
  constructor(public readonly reason: string) {}
4
}
5

6
class Age {
7
  private constructor(private readonly value: number) {}
8

9
  static create(value: number): Result<Age, InvalidAgeError> {
10
    if (!Number.isInteger(value)) {
11
      return err(new InvalidAgeError("Age must be a whole number"));
12
    }
13
    if (value < 0) {
14
      return err(new InvalidAgeError("Age cannot be negative"));
15
    }
16
    if (value < 18) {
17
      return err(new InvalidAgeError("Must be at least 18"));
18
    }
19
    if (value > 150) {
20
      return err(new InvalidAgeError("Age seems unrealistic"));
21
    }
22
    return ok(new Age(value));
23
  }
24

25
  getValue(): number {
26
    return this.value;
27
  }
28

29
  equals(other: Age): boolean {
30
    return this.value === other.value;
31
  }
32
}

And the tests that drove it:

1
describe("Age Value Object", () => {
2
  it("should create a valid age", () => {
3
    const result = Age.create(25);
4
    expect(result.ok).toBe(true);
5
  });
6

7
  it("should reject negative ages", () => {
8
    const result = Age.create(-1);
9
    expect(result.ok).toBe(false);
10
  });
11

12
  it("should reject ages under 18", () => {
13
    const result = Age.create(17);
14
    expect(result.ok).toBe(false);
15
    if (!result.ok) {
16
      expect(result.error.reason).toContain("18");
17
    }
18
  });
19

20
  it("should reject non-integer ages", () => {
21
    const result = Age.create(25.5);
22
    expect(result.ok).toBe(false);
23
  });
24

25
  it("should reject unrealistic ages", () => {
26
    const result = Age.create(200);
27
    expect(result.ok).toBe(false);
28
  });
29
});

Username Value Object#

1
class InvalidUsernameError {
2
  readonly code = "INVALID_USERNAME";
3
  constructor(public readonly reason: string) {}
4
}
5

6
class Username {
7
  private constructor(private readonly value: string) {}
8

9
  static create(value: string): Result<Username, InvalidUsernameError> {
10
    const trimmed = value.trim();
11
    if (trimmed.length < 3) {
12
      return err(
13
        new InvalidUsernameError("Username must be at least 3 characters")
14
      );
15
    }
16
    if (trimmed.length > 30) {
17
      return err(
18
        new InvalidUsernameError("Username must be at most 30 characters")
19
      );
20
    }
21
    if (!/^[a-zA-Z0-9_]+$/.test(trimmed)) {
22
      return err(
23
        new InvalidUsernameError(
24
          "Username can only contain letters, numbers, and underscores"
25
        )
26
      );
27
    }
28
    return ok(new Username(trimmed));
29
  }
30

31
  getValue(): string {
32
    return this.value;
33
  }
34

35
  equals(other: Username): boolean {
36
    return this.value === other.value;
37
  }
38
}

Notice the pattern? Every Value Object follows the same shape:

Private constructor: you can’t create one directly
Static factory returning Result<T, E>: validation happens here
Getter for the internal value
equals() for comparison
All validation in the factory

I didn’t plan this pattern. It emerged from writing the same test structure over and over. TDD revealed it.

What Is an Entity?#

Value Objects are defined by their attributes. But some things in your domain have identity: they matter because of who they are, not what they contain.

A User with email [email protected] and age 25 is different from another User with the same data but a different ID. The ID is what matters. That’s an Entity.

Entities have four properties:

Identity: a unique ID that persists across state changes
Mutable: attributes can change over time (but the ID never does)
Equality by identity: two users with the same ID are the same, regardless of their current data
Contains Value Objects: attributes are Value Objects, not primitives

Here’s a UserId Value Object (yes, IDs are Value Objects) and a User Entity:

1
class UserId {
2
  private constructor(private readonly value: string) {}
3

4
  static generate(): UserId {
5
    // Node 19+ / modern browsers expose crypto.randomUUID globally.
6
    // On older Node versions: `import { randomUUID } from "node:crypto"`.
7
    return new UserId(crypto.randomUUID());
8
  }
9

10
  static fromString(value: string): UserId {
11
    return new UserId(value);
12
  }
13

14
  getValue(): string {
15
    return this.value;
16
  }
17

18
  equals(other: UserId): boolean {
19
    return this.value === other.value;
20
  }
21
}
22

23
type ValidationError =
24
  InvalidEmailError | InvalidAgeError | InvalidUsernameError;
25

26
class User {
27
  private constructor(
28
    private readonly id: UserId,
29
    private email: Email,
30
    private age: Age,
31
    private username: Username
32
  ) {}
33

34
  static create(
35
    emailStr: string,
36
    ageNum: number,
37
    usernameStr: string
38
  ): Result<User, ValidationError> {
39
    const emailResult = Email.create(emailStr);
40
    if (!emailResult.ok) return err(emailResult.error);
41

42
    const ageResult = Age.create(ageNum);
43
    if (!ageResult.ok) return err(ageResult.error);
44

45
    const usernameResult = Username.create(usernameStr);
46
    if (!usernameResult.ok) return err(usernameResult.error);
47

48
    return ok(
49
      new User(
50
        UserId.generate(),
51
        emailResult.value,
52
        ageResult.value,
53
        usernameResult.value
54
      )
55
    );
56
  }
57

58
  static of(id: UserId, email: Email, age: Age, username: Username): User {
59
    return new User(id, email, age, username);
60
  }
61

62
  changeEmail(newEmailStr: string): Result<void, InvalidEmailError> {
63
    const result = Email.create(newEmailStr);
64
    if (!result.ok) return err(result.error);
65
    this.email = result.value;
66
    return ok(undefined);
67
  }
68

69
  getEmail(): Email {
70
    return this.email;
71
  }
72

73
  getAge(): Age {
74
    return this.age;
75
  }
76

77
  getUsername(): Username {
78
    return this.username;
79
  }
80

81
  getId(): UserId {
82
    return this.id;
83
  }
84

85
  equals(other: User): boolean {
86
    return this.id.equals(other.id);
87
  }
88
}

Look at User.create(). It doesn’t validate anything itself. It delegates to Email.create(), Age.create(), and Username.create(). The Entity is thin because the Value Objects do the heavy lifting.

User.of(id, email, age, username) is the second factory: same construction, but you pass in a known UserId instead of generating one. We’ll need that when we rehydrate a User from a database in the next post.

And changeEmail(): same pattern. It doesn’t check @ signs. It trusts Email.create() to enforce the rules. One line of delegation instead of five lines of validation.

Here are the tests that drove this Entity:

1
describe("User Entity", () => {
2
  it("should create a user with valid email, age, and username", () => {
3
    const result = User.create("[email protected]", 25, "alice_99");
4

5
    expect(result.ok).toBe(true);
6
    if (result.ok) {
7
      expect(result.value.getEmail().getValue()).toBe("[email protected]");
8
      expect(result.value.getAge().getValue()).toBe(25);
9
      expect(result.value.getUsername().getValue()).toBe("alice_99");
10
    }
11
  });
12

13
  it("should reject user with invalid email", () => {
14
    const result = User.create("not-an-email", 25, "alice_99");
15

16
    expect(result.ok).toBe(false);
17
  });
18

19
  it("should reject user under 18", () => {
20
    const result = User.create("[email protected]", 17, "alice_99");
21

22
    expect(result.ok).toBe(false);
23
  });
24

25
  it("should reject user with invalid username", () => {
26
    const result = User.create("[email protected]", 25, "a");
27

28
    expect(result.ok).toBe(false);
29
  });
30

31
  it("should change email successfully", () => {
32
    const user = User.create("[email protected]", 25, "alice_99");
33
    if (!user.ok) return;
34

35
    const result = user.value.changeEmail("[email protected]");
36

37
    expect(result.ok).toBe(true);
38
    expect(user.value.getEmail().getValue()).toBe("[email protected]");
39
  });
40

41
  it("should reject invalid email on change", () => {
42
    const user = User.create("[email protected]", 25, "alice_99");
43
    if (!user.ok) return;
44

45
    const result = user.value.changeEmail("bad");
46

47
    expect(result.ok).toBe(false);
48
    expect(user.value.getEmail().getValue()).toBe("[email protected]");
49
  });
50

51
  it("should treat users with the same ID as equal, even if their data differs", () => {
52
    const id = UserId.fromString("user-123");
53
    const email = Email.create("[email protected]");
54
    const age = Age.create(25);
55
    const username = Username.create("alice_99");
56

57
    if (!email.ok || !age.ok || !username.ok) return;
58

59
    const userA = User.of(id, email.value, age.value, username.value);
60
    const userB = User.of(id, email.value, age.value, username.value);
61

62
    expect(userA.equals(userB)).toBe(true);
63
  });
64

65
  it("should treat users with different IDs as unequal, even with the same data", () => {
66
    const email = Email.create("[email protected]");
67
    const age = Age.create(25);
68
    const username = Username.create("alice_99");
69

70
    if (!email.ok || !age.ok || !username.ok) return;
71

72
    const userA = User.of(
73
      UserId.fromString("user-A"),
74
      email.value,
75
      age.value,
76
      username.value
77
    );
78
    const userB = User.of(
79
      UserId.fromString("user-B"),
80
      email.value,
81
      age.value,
82
      username.value
83
    );
84

85
    expect(userA.equals(userB)).toBe(false);
86
  });
87
});

Two User objects built with the same UserId are equal — regardless of what their attributes currently say. Two User objects built with different UserIds are unequal — even if every attribute matches. That’s the Entity identity rule, enforced by the tests, expressed through User.of(id, ...).

Value Object vs Entity: How to Decide#

When I first learned this distinction, I kept asking: “But how do I know which one to use?”

The decision framework I reach for:

1
Does it have a unique identity that persists across changes?
2
  ├── Yes → Entity
3
  └── No → Value Object
4

5
Can it change over time?
6
  ├── Yes, and it has identity → Entity
7
  ├── Yes, but no identity → Create a new Value Object (immutability)
8
  └── No → Value Object
9

10
Is equality based on attributes or identity?
11
  ├── Attributes → Value Object
12
  └── Identity → Entity

Some concrete examples from domains I’ve worked in:

Concept	Type	Why
Email	Value Object	No identity, immutable, compared by value
User	Entity	Has ID, email can change, compared by ID
Money	Value Object	No identity, $5 is$ 5
Order	Entity	Has order ID, items change over time
Address	Value Object	Compared by street + city + zip
Customer	Entity	Has customer ID, address can change
DateRange	Value Object	Compared by start + end
Subscription	Entity	Has subscription ID, status changes over time

When I’m unsure, I ask myself one question: “If two of these had the same data, would they be the same thing?”

Two emails [email protected]? Same thing. → Value Object.
Two users named Alice? Could be different people. → Entity.

Getting this wrong has consequences: identity logic scatters when you treat an Entity as a Value Object, and unnecessary overhead piles up when you treat a Value Object as an Entity.

Real-World: Rebuilding the Registration System#

Before and after of validation: scattered validation logic duplicated across user_service.ts, user_repo.ts, signup.ts, update-user.ts, validators.ts, and helpers.ts collapses into a single Email Value Object as the source of truth, returning a Result<Email> that yields either Success or ValidationError. The refactor extracts, encapsulates, and centralizes validation in one place.

Time to put it all together. That scattered validation from the beginning — here’s the before and after.

Before: Validation Everywhere#

1
// ❌ 80+ lines of a registration service
2

3
class RegistrationService {
4
  register(email: string, age: number, username: string): Result<User, Error> {
5
    // Validate email
6
    if (!email || !email.includes("@") || !email.includes(".")) {
7
      return err(new Error("Invalid email"));
8
    }
9
    const normalizedEmail = email.trim().toLowerCase();
10
    if (normalizedEmail.length > 254) {
11
      return err(new Error("Email too long"));
12
    }
13

14
    // Validate age
15
    if (typeof age !== "number" || !Number.isInteger(age)) {
16
      return err(new Error("Age must be a number"));
17
    }
18
    if (age < 18) {
19
      return err(new Error("Must be at least 18"));
20
    }
21

22
    // Validate username
23
    if (!username || username.trim().length < 3) {
24
      return err(new Error("Username too short"));
25
    }
26
    if (username.trim().length > 30) {
27
      return err(new Error("Username too long"));
28
    }
29
    if (!/^[a-zA-Z0-9_]+$/.test(username.trim())) {
30
      return err(new Error("Invalid username characters"));
31
    }
32

33
    // Finally, create the user
34
    const user = new User(normalizedEmail, age, username.trim());
35
    return ok(user);
36
  }
37
}

One method. 30+ lines of validation. And if I need to validate an email anywhere else (password reset, email change, account linking), I have to duplicate or extract this logic.

After: Value Objects Do the Work#

1
// ✅ ~15 lines, all validation delegated
2

3
class RegistrationService {
4
  register(
5
    emailStr: string,
6
    ageNum: number,
7
    usernameStr: string
8
  ): Result<User, ValidationError> {
9
    const emailResult = Email.create(emailStr);
10
    if (!emailResult.ok) return err(emailResult.error);
11

12
    const ageResult = Age.create(ageNum);
13
    if (!ageResult.ok) return err(ageResult.error);
14

15
    const usernameResult = Username.create(usernameStr);
16
    if (!usernameResult.ok) return err(usernameResult.error);
17

18
    return ok(
19
      User.of(
20
        UserId.generate(),
21
        emailResult.value,
22
        ageResult.value,
23
        usernameResult.value
24
      )
25
    );
26
  }
27
}

The service doesn’t know what makes an email valid. It doesn’t care. It hands the raw strings to Email.create(), Age.create(), and Username.create(), then composes them into a User via User.of(...). Every layer trusts the layer below it: the service trusts the Value Objects, the Entity trusts the Value Objects, the Value Objects trust themselves. If the rules change (say, we add a check for disposable email domains), we update Email.create() in one place, and every layer above it benefits without changes.

Tests for the registration flow:

1
describe("Registration Service", () => {
2
  it("should register a valid user", () => {
3
    const service = new RegistrationService();
4
    const result = service.register("[email protected]", 25, "alice_99");
5

6
    expect(result.ok).toBe(true);
7
  });
8

9
  it("should reject invalid email during registration", () => {
10
    const service = new RegistrationService();
11
    const result = service.register("not-an-email", 25, "alice_99");
12

13
    expect(result.ok).toBe(false);
14
    if (!result.ok) {
15
      expect(result.error.code).toBe("INVALID_EMAIL");
16
    }
17
  });
18

19
  it("should reject underage user during registration", () => {
20
    const service = new RegistrationService();
21
    const result = service.register("[email protected]", 16, "alice_99");
22

23
    expect(result.ok).toBe(false);
24
    if (!result.ok) {
25
      expect(result.error.code).toBe("INVALID_AGE");
26
    }
27
  });
28

29
  it("should reject invalid username during registration", () => {
30
    const service = new RegistrationService();
31
    const result = service.register("[email protected]", 25, "a");
32

33
    expect(result.ok).toBe(false);
34
    if (!result.ok) {
35
      expect(result.error.code).toBe("INVALID_USERNAME");
36
    }
37
  });
38
});

These tests survive refactoring. They test the behavior, what comes in and what comes out, not the internal structure. I can rewrite the entire RegistrationService tomorrow and these tests won’t blink.

That’s the permission slip from the first article, made concrete.

FAQ#

Should every domain concept become a Value Object?#

No. Start with primitives. When you see the same validation appearing in two or more places, extract it into a Value Object. Premature abstraction is still premature, even when it’s domain-driven. I usually wait for the second duplication before extracting.

What about performance? Doesn’t wrapping primitives add overhead?#

In the domains I work in (web backends, APIs), the overhead is negligible. You’re creating small objects instead of passing strings. The GC cost is trivial. If you’re building a game loop or a real-time system with millions of allocations per frame, this pattern might not fit. But for business logic? The safety is worth the microsecond.

How do I persist Value Objects to a database?#

You persist their internal values. An Email becomes a VARCHAR column. An Age becomes an INTEGER. The ORM or query layer unwraps the Value Object with getValue(). The validation still happens at construction time. Your database just stores the raw value. I’ll show this pattern in detail when we get to Repositories.

Summary#

Value Objects encode rules into types. Entities compose Value Objects and manage identity.

Together, they give you code where invalid states are impossible to construct by accident — not just unlikely.

The TDD insight here is deeper than it looks. I didn’t sit down and decide “I need an Email Value Object.” The tests told me. Every time I wrote a test that said “should reject invalid email,” the design pressure pushed me toward a self-validating type. The Value Object emerged from the tests.

That’s what TDD is for. Design first. The tests come as a byproduct.

Three things to remember:

Value Objects are immutable, self-validating, compared by value. They make invalid states impossible to construct by accident.
Entities have identity, can change over time, compared by ID. They compose Value Objects.
TDD reveals the pattern. You don’t plan Value Objects. You let the tests push you toward them.

What’s Next?#

Value Objects protect single attributes. Entities protect a single object’s identity. But what happens when business rules span multiple objects? “A user can’t place an order over $1000” involves User, Order, OrderLine, and Money. That’s not a single Value Object’s job.

Next time: Aggregates & Repositories — Refactoring Without Fear. We’ll build clusters of objects that enforce business rules together, and abstract away persistence so your domain tests don’t need a database.

Value Objects protect data. Aggregates protect invariants. Repositories protect persistence. That’s the next layer.

Continue the TDD & Software Design Series#

Questions? Hit reply. I read everything.

— Corentin

P.S. If you haven’t read the first article yet, start there. This one builds on the Result<T, E> pattern and the “test behavior, not implementation” principle. The whole series makes more sense in order.

Value Objects & Entities in TypeScript: Building Blocks That Can't Break

https://corentings.dev/blog/tdd-value-objects-entities/

Author

Corentin Giaufer Saubert

Published at

2026-06-30

License

CC BY-NC-SA 4.0

Share this post

Repository Updates in TypeScript: Locks and Optimistic Concurrency

Learn when transactional update closures, optimistic versioning, and rollback-safe repository fakes fit in TypeScript.

2026-07-16

TestingTDD

TypeScript DDD Aggregates & Repositories

Build DDD aggregates and repositories in TypeScript with TDD. Enforce invariants and test application flows with an in-memory repository.

2026-07-07

TestingTDD

TDD Isn't About Bugs — It's Your Permission to Refactor

Learn why test-driven development is really about permission to refactor, not catching bugs. With TypeScript examples, Result<T, E> patterns, and behavior-based testing from 3 years in production.

2026-05-24

TestingTDD

Go Goroutines vs C# async/await: Who Carries the Cognitive Load?

Beyond PGN: Designing an Ultra-Efficient Chess Storage Format

Corentin GS's Blog

Value Objects & Entities in TypeScript: Building Blocks That Can't Break

The Validation Everywhere Problem#

What Is a Value Object?#

The TDD Cycle for Value Objects#

Iteration 1: Basic Creation (Red)#

Iteration 1: Basic Creation (Green)#

Iteration 2: Edge Cases (Red)#

Iteration 2: Edge Cases (Green)#

Iteration 3: Equality (Red)#

Iteration 3: Equality (Green)#

Building More Value Objects#

Age Value Object#

Username Value Object#

What Is an Entity?#

Value Object vs Entity: How to Decide#

Real-World: Rebuilding the Registration System#

Before: Validation Everywhere#

After: Value Objects Do the Work#

FAQ#

Should every domain concept become a Value Object?#

What about performance? Doesn’t wrapping primitives add overhead?#

How do I persist Value Objects to a database?#

Summary#

What’s Next?#

Continue the TDD & Software Design Series#

Related Posts

Repository Updates in TypeScript: Locks and Optimistic Concurrency

TypeScript DDD Aggregates & Repositories

TDD Isn't About Bugs — It's Your Permission to Refactor

Corentin GS's Blog

Value Objects & Entities in TypeScript: Building Blocks That Can't Break

The Validation Everywhere Problem#

What Is a Value Object?#

The TDD Cycle for Value Objects#

Iteration 1: Basic Creation (Red)#

Iteration 1: Basic Creation (Green)#

Iteration 2: Edge Cases (Red)#

Iteration 2: Edge Cases (Green)#

Iteration 3: Equality (Red)#

Iteration 3: Equality (Green)#

Building More Value Objects#

Age Value Object#

Username Value Object#

What Is an Entity?#

Value Object vs Entity: How to Decide#

Real-World: Rebuilding the Registration System#

Before: Validation Everywhere#

After: Value Objects Do the Work#

FAQ#

Should every domain concept become a Value Object?#

What about performance? Doesn’t wrapping primitives add overhead?#

How do I persist Value Objects to a database?#

Summary#

What’s Next?#

Continue the TDD & Software Design Series#

More on Programming

Related Posts

Repository Updates in TypeScript: Locks and Optimistic Concurrency

TypeScript DDD Aggregates & Repositories

TDD Isn't About Bugs — It's Your Permission to Refactor