Branded Types

In this guide, we will explore the concept of branded types in TypeScript and learn how to create and work with them using the Brand module. Branded types are TypeScript types with an added type tag that helps prevent accidental usage of a value in the wrong context. They allow us to create distinct types based on an existing underlying type, enabling type safety and better code organization.

The Problem with TypeScript’s Structural Typing

TypeScript’s type system is structurally typed, meaning that two types are considered compatible if their members are compatible. This can lead to situations where values of the same underlying type are used interchangeably, even when they represent different concepts or have different meanings.

Consider the following types:

1
type UserId = number
2

3
type ProductId = number

Here, UserId and ProductId are structurally identical as they are both based on number. TypeScript will treat these as interchangeable, potentially causing bugs if they are mixed up in your application.

Example (Unintended Type Compatibility)

1
type UserId = number
2

3
type ProductId = number
4

5
const getUserById = (id: UserId) => {
6
  // Logic to retrieve user
7
}
8

9
const getProductById = (id: ProductId) => {
10
  // Logic to retrieve product
11
}
12

13
const id: UserId = 1
14

15
getProductById(id) // No type error, but incorrect usage

In the example above, passing a UserId to getProductById does not produce a type error, even though it’s logically incorrect. This happens because both types are considered interchangeable.

How Branded Types Help

Branded types allow you to create distinct types from the same underlying type by adding a unique type tag, enforcing proper usage at compile-time.

Branding is accomplished by adding a symbolic identifier that distinguishes one type from another at the type level. This method ensures that types remain distinct without altering their runtime characteristics.

Let’s start by introducing the BrandTypeId symbol:

1
const BrandTypeId: unique symbol = Symbol.for("effect/Brand")
2

3
type ProductId = number & {
4
  readonly [BrandTypeId]: {
5
    readonly ProductId: "ProductId" // unique identifier for ProductId
6
  }
7
}

This approach assigns a unique identifier as a brand to the number type, effectively differentiating ProductId from other numerical types. The use of a symbol ensures that the branding field does not conflict with any existing properties of the number type.

Attempting to use a UserId in place of a ProductId now results in an error:

Example (Enforcing Type Safety with Branded Types)

1
const BrandTypeId: unique symbol = Symbol.for("effect/Brand")
2

3
type ProductId = number & {
4
  readonly [BrandTypeId]: {
5
    readonly ProductId: "ProductId"
6
  }
7
}
8

9
const getProductById = (id: ProductId) => {
10
  // Logic to retrieve product
11
}
12

13
type UserId = number
14

15
const id: UserId = 1
16

17
// @errors: 2345
18
getProductById(id)

The error message clearly states that a number cannot be used in place of a ProductId.

TypeScript won’t let us pass an instance of number to the function accepting ProductId because it’s missing the brand field.

Let’s add branding to UserId as well:

Example (Branding UserId and ProductId)

1
const BrandTypeId: unique symbol = Symbol.for("effect/Brand")
2

3
type ProductId = number & {
4
  readonly [BrandTypeId]: {
5
    readonly ProductId: "ProductId" // unique identifier for ProductId
6
  }
7
}
8

9
const getProductById = (id: ProductId) => {
10
  // Logic to retrieve product
11
}
12

13
type UserId = number & {
14
  readonly [BrandTypeId]: {
15
    readonly UserId: "UserId" // unique identifier for UserId
16
  }
17
}
18

19
declare const id: UserId
20

21
// @errors: 2345
22
getProductById(id)

The error indicates that while both types use branding, the unique values associated with the branding fields ("ProductId" and "UserId") ensure they remain distinct and non-interchangeable.

Generalizing Branded Types

To enhance the versatility and reusability of branded types, they can be generalized using a standardized approach:

1
const BrandTypeId: unique symbol = Symbol.for("effect/Brand")
2

3
// Create a generic Brand interface using a unique identifier
4
interface Brand<in out ID extends string | symbol> {
5
  readonly [BrandTypeId]: {
6
    readonly [id in ID]: ID
7
  }
8
}
9

10
// Define a ProductId type branded with a unique identifier
11
type ProductId = number & Brand<"ProductId">
12

13
// Define a UserId type branded similarly
14
type UserId = number & Brand<"UserId">

This design allows any type to be branded using a unique identifier, either a string or symbol.

Here’s how you can utilize the Brand interface, which is readily available from the Brand module, eliminating the need to craft your own implementation:

Example (Using the Brand Interface from the Brand Module)

1
import { Brand } from "effect"
2

3
// Define a ProductId type branded with a unique identifier
4
type ProductId = number & Brand.Brand<"ProductId">
5

6
// Define a UserId type branded similarly
7
type UserId = number & Brand.Brand<"UserId">

However, creating instances of these types directly leads to an error because the type system expects the brand structure:

Example (Direct Assignment Error)

1
const BrandTypeId: unique symbol = Symbol.for("effect/Brand")
2

3
interface Brand<in out K extends string | symbol> {
4
  readonly [BrandTypeId]: {
5
    readonly [k in K]: K
6
  }
7
}
8

9
type ProductId = number & Brand<"ProductId">
10

11
// @errors: 2322
12
const id: ProductId = 1

You cannot directly assign a number to ProductId. The Brand module provides utilities to correctly construct values of branded types.

Constructing Branded Types

The Brand module provides two main functions for creating branded types: nominal and refined.

nominal

The Brand.nominal function is designed for defining branded types that do not require runtime validations. It simply adds a type tag to the underlying type, allowing us to distinguish between values of the same type but with different meanings. Nominal branded types are useful when we only want to create distinct types for clarity and code organization purposes.

Example (Defining Distinct Identifiers with Nominal Branding)

1
import { Brand } from "effect"
2

3
// Define UserId as a branded number
4
type UserId = number & Brand.Brand<"UserId">
5

6
// Constructor for UserId
7
const UserId = Brand.nominal<UserId>()
8

9
const getUserById = (id: UserId) => {
10
  // Logic to retrieve user
11
}
12

13
// Define ProductId as a branded number
14
type ProductId = number & Brand.Brand<"ProductId">
15

16
// Constructor for ProductId
17
const ProductId = Brand.nominal<ProductId>()
18

19
const getProductById = (id: ProductId) => {
20
  // Logic to retrieve product
21
}

Attempting to assign a non-ProductId value will result in a compile-time error:

Example (Type Safety with Branded Identifiers)

1
import { Brand } from "effect"
2

3
type UserId = number & Brand.Brand<"UserId">
4

5
const UserId = Brand.nominal<UserId>()
6

7
const getUserById = (id: UserId) => {
8
  // Logic to retrieve user
9
}
10

11
type ProductId = number & Brand.Brand<"ProductId">
12

13
const ProductId = Brand.nominal<ProductId>()
14

15
const getProductById = (id: ProductId) => {
16
  // Logic to retrieve product
17
}
18

19
// Correct usage
20
getProductById(ProductId(1))
21

22
// Incorrect, will result in an error
23
// @errors: 2345
24
getProductById(1)
25

26
// Also incorrect, will result in an error
27
// @errors: 2345
28
getProductById(UserId(1))

refined

The Brand.refined function enables the creation of branded types that include data validation. It requires a refinement predicate to check the validity of input data against specific criteria.

When the input data does not meet the criteria, the function uses Brand.error to generate a BrandErrors data type. This provides detailed information about why the validation failed.

Example (Creating a Branded Type with Validation)

1
import { Brand } from "effect"
2

3
// Define a branded type 'Int' to represent integer values
4
type Int = number & Brand.Brand<"Int">
5

6
// Define the constructor using 'refined' to enforce integer values
7
const Int = Brand.refined<Int>(
8
  // Validation to ensure the value is an integer
9
  (n) => Number.isInteger(n),
10
  // Provide an error if validation fails
11
  (n) => Brand.error(`Expected ${n} to be an integer`),
12
)

Example (Using the Int Constructor)

1
import { Brand } from "effect"
2

3
type Int = number & Brand.Brand<"Int">
4

5
const Int = Brand.refined<Int>(
6
  // Check if the value is an integer
7
  (n) => Number.isInteger(n),
8
  // Error message if the value is not an integer
9
  (n) => Brand.error(`Expected ${n} to be an integer`),
10
)
11

12
// Create a valid Int value
13
const x: Int = Int(3)
14
console.log(x) // Output: 3
15

16
// Attempt to create an Int with an invalid value
17
const y: Int = Int(3.14)
18
// throws [ { message: 'Expected 3.14 to be an integer' } ]

Attempting to assign a non-Int value will result in a compile-time error:

Example (Compile-Time Error for Incorrect Assignments)

1
import { Brand } from "effect"
2

3
type Int = number & Brand.Brand<"Int">
4

5
const Int = Brand.refined<Int>(
6
  (n) => Number.isInteger(n),
7
  (n) => Brand.error(`Expected ${n} to be an integer`),
8
)
9

10
// Correct usage
11
const good: Int = Int(3)
12

13
// Incorrect, will result in an error
14
// @errors: 2322
15
const bad1: Int = 3
16

17
// Also incorrect, will result in an error
18
// @errors: 2322
19
const bad2: Int = 3.14

Combining Branded Types

In some cases, you might need to combine multiple branded types. The Brand module provides the Brand.all API for this purpose:

Example (Combining Multiple Branded Types)

1
import { Brand } from "effect"
2

3
type Int = number & Brand.Brand<"Int">
4

5
const Int = Brand.refined<Int>(
6
  (n) => Number.isInteger(n),
7
  (n) => Brand.error(`Expected ${n} to be an integer`),
8
)
9

10
type Positive = number & Brand.Brand<"Positive">
11

12
const Positive = Brand.refined<Positive>(
13
  (n) => n > 0,
14
  (n) => Brand.error(`Expected ${n} to be positive`),
15
)
16

17
// Combine the Int and Positive constructors
18
// into a new branded constructor PositiveInt
19
const PositiveInt = Brand.all(Int, Positive)
20

21
// Extract the branded type from the PositiveInt constructor
22
type PositiveInt = Brand.Brand.FromConstructor<typeof PositiveInt>
23

24
// Usage example
25

26
// Valid positive integer
27
const good: PositiveInt = PositiveInt(10)
28

29
// throws [ { message: 'Expected -5 to be positive' } ]
30
const bad1: PositiveInt = PositiveInt(-5)
31

32
// throws [ { message: 'Expected 3.14 to be an integer' } ]
33
const bad2: PositiveInt = PositiveInt(3.14)