Make Illegal States Unrepresentable! - Domain-Driven Design w/ TypeScript

By using TypeScript's static type system, not only can we enforce (typically challenging things like) business rules and error states, but we can create a domain-specific language so well-defined that it becomes virtually impossible for any future code to be written that puts the system in an illegal state.

When we first learn how to code, we're typically most focused on making things work. We visualize the finished product as a coming together of several technologies. A common MVC-mental model for a full-stack web app is: database + React app + Express API.

This works really well for a long time in CRUD and MVC-based applications without lots of business logic because we can (usually) think about them imperatively.

"This string maps to this column in the database. I'll just do some validation in the service to make sure it's not longer than 30 characters".

This approach to structuring business logic is called a "Transaction Script" and it's the most basic one. It's defined by the absense of a domain model and all business rules being represented with simple control statements like if or switch.

Transaction Scripts

Here's an example of creating a user using the Transaction Script approach.

export class UserService {
  createUser (email: string, firstName: string, lastName: string): Promise<void> {
    const UserModel = this.models.User;
    const isEmailValid = TextUtils.validateEmail(email);
    const isFirstNameValid = TextUtils.greaterThan(1, firstName) 
      && TextUtils.lessThan(31, firstName);
    const isLastNameValid = TextUtils.greaterThan(1, lastName) 
      && TextUtils.lessThan(71, lastName);

    if (!isEmailValid) {
      throw new Error("Email isn't valid");

    if (!isFirstNameValid) {
      throw new Error("First name isn't valid");

    if (!isLastNameValid) {
      throw new Error("Last name isn't valid");

    const user: User = new User({ email, firstName, lastName });

    await UserModel.create(user);


What's wrong with this code?

You know, it's not that bad. It works. But there are a couple of important things here being ignored.

  1. Errors aren't given the love that they deserve. We're making it hard for the calling code to be able to handle the errors possibly thrown by this block.

We're not really solving this problem, we're just putting it off for someone else to figure out how to decipher the errors later. It would be a lot easier for the next person if the errors were treated as types just like everything else in our domain.

  1. There are important business rules here (constraints) that can easily be circumvented.

In order to create a User, we need a valid email, a firstName from 2-30 characters, and a lastName from 2-70 characters.

What's stopping a new developer joining our team from just doing:

const user: User = new User({ email: 'bob', firstName: 'b', lastName: 'c' })

...completely circumenting our efforts defining business logic (validation logic is a form of business logic).

Nothing 😨.

There's another problem too.

Duplicating business rules

It's nice that we're at least trying to prevent against violations to the upper and lower bound lengths for the strings, but what happens when we create the updateUser method in our UserService? How much of that constraint logic do we have to duplicate?

All of it.

And what if the business rules changed a little bit?

What if, in order to create a user, you need to have either an email + firstName OR firstName and lastName?

That would make the User creation logic a little bit more complex, and we'd have to repeat it anywhere that we create users in our code.

That's a textbook anemic domain model. Not usually fun for web development (though, see Entity Component Systems for times it is fun).

This sucks. What should we do?

Make illegal states unrepresentable

Earlier this year, functional programming fanatic John A De Goes blasted out a tweet:

Making illegal states unrepresentable is all about statically proving that all runtime values (without exception) correspond to valid objects in the business domain. The effect of this technique on eliminating meaningless runtime states is astounding and cannot be overstated.

— John A De Goes (@jdegoes) January 28, 2019

This is an awesome quote. In programming (and science), it's often impossible to prove that something is correct, but it's reasonable to prove that something is correct enough.

With types, we can achieve that correct enough, and that makes our code much easier to reason about. And that gives us confidence to know that our business rules are being respected.

This builds trust. This means potentially less unit tests against the business logic, and more tests with various inputs to the system. This makes it safer to refactor code. This enables us to continue to push forward the design. This means that the types serve as a form of documentation to the system. This reduces the amount of supplementary documentation necessary. This enables new developers to onboard faster. This makes us happier.

This also happens to be the core of what Scott Wlaschin teaches with his book, blog, and talks on functional domain modeling.

Let's recap some approaches that we've already covered in detail on the blog, and look at a few alternative approaches as well.

Wrapping primitives with domain specific types to express a common language and prevent misuse

The essence of DDD is to build a shared understanding of the domain with stakeholders, non-technical folk, and technical folk, and then codify that.

Using types, non-techncial stakeholders can understand our code.

Like this.

// UserName is from a separate subdomain, `Users`
import { UserName } from '../../users/domain/types'

type MemberId = string;
type Member = {
  id: MemberId,
  name: UserName

type Text = string;
type Link = string;

type PostTitle = string;
type PostId = string;

type Post = {
  postId: PostId
  postedBy: Member,
  title: PostTitle,
  content: Text | Link,

type Upvote = {
  postId: PostId,
  memberId: MemberId

type Downvote = {
  postId: PostId,
  memberId: MemberId

You probably have a good idea about the type of domain that we're dealing with simply by looking at the names of the types and their relationships.

Using classes (because of its nominal typing) yields a benefit (that I haven't yet been able to get working with purely functional types in TypeScript):

Forcing strictly nominal type checks (based on the name)

For example, even though PostId and PostTitle might just be wrappers to a string value, like this:

interface PostIdProps {
  id: string;

export class PostId {
  // Value is protected 
  private props: PostIdProps;

  // There is only a getter, because it should never be able to change
  get value (): string {

interface PostTitleProps {
  title: string;

export class PostTitle {
  // Also protected
  private props: PostTitleProps;
  // Also only needs a getter
  get value (): string {
    return this.props.title;

We can't just substitute them in for each other.

export class PostSlug {

  // We need a PostTitle to create a PostSlug
  public static create (postTitle: PostTitle): Result<PostSlug> {

let postId: PostId = PostId.create();
let postSlug: PostSlug = PostSlug.create(postId); // Error

We can also think of this as a way to encode business requirements. If the only way to create a PostSlug is to first create a PostTitle, then we're forced to first locate the factory that creates PostTitles.

Think of the amount of illegal states we prevented by wrapping primitives in domain-specific types.

Using public setters sparingly

It's easy to add getters and setters for all of the properties of a class, but should we?

Consider modeling a User entity with a public UserId.

export class User extends Entity<UserProps> {
  get userId () : UserId {
    return this.props.userId;


Should we also add a setter?

That depends on if doing so is valid to the domain.

From a Users, Identity & Access Management context, there's no reason why the UserId should ever change to a new value. Doing so would break the relationships between User and any other subdomains that have a 1-to-1 relationship with User like Member from the Forum subdomain in

So lets make it entirely impossible.

export class User extends Entity<UserProps> {
  get userId () : UserId {
    return this.props.userId;

  // set userId (userId: UserId) {
  //   this.props.userId = userId;
  // }

I might even discourage the use of public setters in general because of their rigid method signature. They clash with the way that we handle updates in aggregates using DDD using Results.

Strictly typing "null"s

What should you do in scenarios when you "try to create an object and it fails" or you "try to retrieve an object and it's not found"? How do you represent that?

Those are pretty realistic scenarios to run into, and passing null is a common practice, though not a very good one.

Nulls aren't nice because to the client, they masquerade 🎭 as if they're actually the object(s) you're looking for, but as soon as you call a method or try to access a property on them, they throw errors.

let votes: Votes[] = [vote1, vote2, vote3, null];

for (let vote of votes) {
  // throws error on the last element
  console.log(`This vote was cast by ${vote.member.memberId}`) 

Undefined and null-y values are things that we should be prepared to deal with.

In Scott Wlaschin's talk, "Domain Modeling Made Functional", he suggests representing null or undefined with its own type, like Nothing.

type Nothing = null | undefined | '';

Using this type, we can create optional types using unions:

type SomeString = string;

type OptionalString = 
  SomeString |

type SomeNumber = number;

type OptionalNumber = 
  SomeNumber |

Or we can make it generic in order to strictly represent any type that may or may not have a value.

type Option<T> = T | Nothing;

type OptionalString = Option<string>;
type OptionalNumber = Option<number>;

Building on that, the type for a Factory Function could adequately

type Email = string;

function createEmail (email: string): Option<Email> {
  return email.contains('@') 
    ? '' as Nothing
    : email as Email;

This particular functional design pattern used to represent types that may or may not exist is called a monad.

When we model nothingness as a type in our domain instead of just passing null, it forces any client code that relies on it to accomodate the possibility of nothingness.

I wrote an article describing how to use the Result monad to model nothingness and wrap failure states with error messages. Check it out, it's called "Flexible Error Handling w/ the Result Class | Enterprise Node.js + TypeScript".

Enforcing object creation constraints with factories

Object constraints (in OO we refer to these as class invariants) are the rules that dictate size, shape, length, or the state that a particular domain object is allowed to be in, and at which point in time.

Here are some constraint (invariant) examples:

  • Length constraints: PostText cannot be longer than 50 characters (overflow), and must be at least 3 characters (underflow)
  • Pattern constraints: Email must be a valid email address based on a regex formula that we constructed.
  • Complex constraints: PaidJobDetails cannot be less than 15 dollars an hour if the Job's Location is based in Ontario.

It's important that the language we choose is able to reduce all the possible ways to create a valid domain object to one way.

We can use the factory pattern for this.

Here's a purely functional approach:

type Nothing = undefined | null;
type EmailAddress = string;

type Option<T> = T | Nothing;

let createEmailAddress: Option<EmailAddress> = (email: string) => (
  !!email === true && email.includes('@') 
    ? email as Email
    : null as Nothing

This is great an all, but there's nothing stopping me from doing:

let email: EmailAddress = ''

This is one of the things that I've been able to enforce with classes using an Object-Oriented approach. Using private constructors and static factory methods, we can ensure that the only way domain objects is through the static factory.

interface EmailAddressProps {
  value: string;

export class EmailAddress extends ValueObject<EmailAddressProps> {

  get value () : string {
    return this.props.value;

  // Can't invoke with new from outside of class.
  private constructor (props: EmailAddressProps) {

  // Only way to create an EmailAddress is through the static factory method 
  public static create (email: string): Result<EmailAddress> {
    const guardResult = Guard.againstNullOrUndefined(email, 'email');

    if (guardResult.isFailure() || !TextUtils.validateEmail(email)) {
    } else {
      return Result.ok<EmailAddress>(new EmailAddress({ value: email }))


Handling error states

There are errors that we expect and know how to deal with, and errors that we don't expect and don't really know how to deal with.

It's also true that for every single use case, there are at least one or more possible ways that it can fail.

So why is it that we often let error states fall through the cracks?

We should strictly type them and represent them as domain concepts.

For example, if we were building, and we wanted to code out the UpvotePost use case, here's a namespace containing objects for all the possible ways it can fail.

import { UseCaseError } from "../../../../../shared/core/UseCaseError";
import { Result } from "../../../../../shared/core/Result";

export namespace UpvotePostErrors {

  export class MemberNotFoundError extends Result<UseCaseError> {
    constructor () {
      super(false, {
        message: `Couldn't find a member to upvote the post.`
      } as UseCaseError)

  export class PostNotFoundError extends Result<UseCaseError> {
    constructor (slug: string) {
      super(false, {
        message: `Couldn't find a post by slug {${slug}}.`
      } as UseCaseError)

  export class AlreadyUpvotedError extends Result<UseCaseError> {
    constructor (postId: string, memberId: string) {
      super(false, {
        message: `This post was already upvoted postId {${postId}}, memberId {${memberId}}.`
      } as UseCaseError)


For that single use case, there are at least three ways that it can fail.

Using the Either<T, U> monad, we can take a step up from the basic Result<T> class that we learned about here, and we can segregate all the possible failure states from the single success state.

Here's what the response type for this use case might look like:

import { Either, Result } from "../../../../../shared/core/Result";
import { UpvotePostErrors } from "./UpvotePostErrors";
import { AppError } from "../../../../../shared/core/AppError";

export type UpvotePostResponse = Either<
  // Failures
  UpvotePostErrors.MemberNotFoundError |
  UpvotePostErrors.AlreadyUpvotedError |
  UpvotePostErrors.PostNotFoundError |
  AppError.UnexpectedError |

  // Success

Note: If you haven't already read it, check out "Functional Error Handling with Express.js and DDD | Enterprise Node.js + TypeScript" to learn how to stop throwing errors and prefer a functional approach to expressing error states.


The main takeaways here are to:

  • Use Factories and Factory Methods to prevent from repeating validation logic. Encapsulate it in one place. When the creation rules change, you only need to update code in one place. See this article on Value Objects for how to implement this.
  • Make it impossible for you to create domain objects without going through the factory. Use private constructors to prevent the use of the new keyword.
  • Wrap primitives with their own domain specific classes in order to make the language more expressive, encode business requirements, and protect their internal values from change operations that don't make sense to the domain.
  • Prefer update methods over public setters to encapsulate change rules within the entity itself. Make it impossible to change things when they shouldn't be changed.
  • Strictly type errors, nulls, and nothingness in order to remove the guesswork from client side code. They should always be able to accomodate for when something failed or was not found through static typing.

Types are law

Types are the laws that dictate what's allowed to happen in our domain. Next time you write some code, think not only about what it would take to make the code work, but also think about what could be done using types (and any language features) to prevent anyone else from putting the system in a state invalid to the domain. If you're using vanilla JavaScript, consider the challenges of preventing team members from doing invalid things, and consider if TypeScript would improve the bylaws of your codebase.

References & resources

For a purely functional introduction to how to implement your domain layer code functionally, watch Scott's "Domain Modeling Made Functional" talk. I recommend you check it out. It's well worth your time.


Liked this? Sing it loud and proud 👨‍🎤.


8 months ago

Very useful post. Thanks!.

In most cases, we might need to validate incoming request with multiple repositories(from database). Usecase/service is the place where we have access to both repo layer and the incoming dto. It makes it easier to add validation in this layer.

How do you pass the data fetched from repository into the domain models just for validation.

You might have to pass a lot of objects as parameters.

Khalil Stemmler
7 months ago

I'm not entirely sure I understand the question. An example would be helpful.

I think what you're talking about are scenarios where you need to retrieve objects from a repository first before you can continue the request?

Perhaps like an example from White Label where you need to add genres to a vinyl by including an array of `genreIds` from within the DTO, like:


interface UpdateVinylDTO {

vinylId: string;

genreIds?: string[];



And before you could do `vinyl.addGenre(genre: Genre)` or `vinyl.setGenres(genres: Genre[])`, at the start of your Use Case invocation, you'd need to retrieve them from the repository like:


if (has(dto, 'genreIds') {

try {

genres = await this.genreRepo.findByIds(dto.genreIds);

} catch (err) {

return left (new UpdateVinylErrors.GenreDoestExistError(err))




You said "Usecase/service is the place where we have access to both repo layer and the incoming dto.  It makes it easier to add validation in this layer."

I just want to clarify that in the Use Case, we still do a little bit of validation, but it's different from the validation we do in Entities and Value Objects. Use Cases can validate the arguments of the request (the DTO), but should contain no business rules.

In commands, the only job of the Use Case is to fetch the objects needed so that the domain services and aggregates can do their job.

In queries, they only retrieve and return objects from repositories.

6 months ago

Great post.

In the first code example for `UserService.ts` it looks like there is a minor type. I think you want to check for the "not" conditional. i.e.

    if (! isEmailValid) {
      throw new Error("Email isn't valid");

    if (! isFirstNameValid) {
      throw new Error("First name isn't valid");

    if (! isLastNameValid) {
      throw new Error("Last name isn't valid");

Khalil Stemmler
6 months ago

Thanks, Michael! Fixed it :)

Nick Hodges
5 months ago

This is a phenomenally good post.

Farren C
3 months ago

I think when working with 'disjoint unions' in TS, you will want to 'tag' them.

So your 'Option' should look more like:

This is a common pattern in other languages too:

Chris C
18 days ago

Have you considered branded types as an alternative to class types?

type PostId = string & { readonly PostId: unique symbol }

This technique is used by io-ts library and by the typescript team internally.

6 days ago

I wonder how you'd handle the EmailContactInfo = Unverified | Verified case as shown in Scott Wlaschin's video. The EmailAddress is stored in the User entity table and I assume you also need an IsUserEmailValidated field to be present. Should this be implemented as an EmailContactInfo interface with 2 value objects UnverifiedEmail and VerifiedEmail that are a property on the User aggregate root?

Stay in touch!

About the author

Khalil Stemmler,
Developer Advocate @ Apollo GraphQL ⚡

Khalil is a software developer, writer, and musician. He frequently publishes articles about Domain-Driven Design, software design and Advanced TypeScript & Node.js best practices for large-scale applications.

View more in Domain-Driven Design

You may also enjoy...

A few more related articles

How to Handle Updates on Aggregates - Domain-Driven Design w/ TypeScript
In this article, you'll learn approaches for handling aggregates on Aggregates in Domain-Driven Design.
Decoupling Logic with Domain Events [Guide] - Domain-Driven Design w/ TypeScript
In this article, we'll walk through the process of using Domain Events to clean up how we decouple complex domain logic across the...
Does DDD Belong on the Frontend? - Domain-Driven Design w/ TypeScript
Should we utilize Domain-Driven Design principles and patterns in front-end applications? How far does domain modeling reach from ...
An Introduction to Domain-Driven Design - DDD w/ TypeScript
Domain-Driven Design is the approach to software development which enables us to translate complex problem domains into rich, expr...

Want to be notified when new content comes out?

Join 5000+ other developers learning about Domain-Driven Design and Enterprise Node.js.

I won't spam ya. 🖖 Unsubscribe anytime.

Get updates