DEV Community: Kuncheria Kuruvilla

Branded Types in TypeScript: Beyond Primitive Type Safety

Kuncheria Kuruvilla — Tue, 17 Jun 2025 11:18:16 +0000

When working with TypeScript, we often find ourselves dealing with values that are technically the same type but represent completely different concepts. A user ID and a product ID are both strings, but mixing them up can lead to serious bugs. This is where branded types come to the rescue.

What Are Branded Types?

Branded types (also known as nominal types or opaque types) are a TypeScript pattern that allows you to create distinct types from existing primitives, even when they have the same underlying structure. They add semantic meaning to your types, making your code more expressive and catching errors at compile time.

// Without branded types - dangerous!
function getUser(userId: string): User { /* ... */ }
function getProduct(productId: string): Product { /* ... */ }

const userId = "user_123";
const productId = "prod_456";

// Oops! This compiles but is logically wrong
getUser(productId); // TypeScript won't catch this error

Creating Branded Types

The most common pattern for creating branded types uses intersection types with a unique symbol:

declare const __brand: unique symbol;
type Brand<T, TBrand> = T & { [__brand]: TBrand };

// Create branded types
type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;
type DateString = Brand<string, "DateString">;

Now let's create helper functions to safely create these branded types:

function createUserId(id: string): UserId {
  // Add validation logic here if needed
  if (!id.startsWith("user_")) {
    throw new Error("Invalid user ID format");
  }
  return id as UserId;
}

function createProductId(id: string): ProductId {
  if (!id.startsWith("prod_")) {
    throw new Error("Invalid product ID format");
  }
  return id as ProductId;
}

function createDateString(date: Date): DateString {
  return date.toISOString() as DateString;
}

Real-World Example: Date Strings

One of the most practical applications of branded types is handling date strings. Consider an application where you need to work with different date formats:

type ISODateString = Brand<string, "ISODateString">;
type LocalDateString = Brand<string, "LocalDateString">;
type UTCDateString = Brand<string, "UTCDateString">;

// Factory functions with validation
function createISODateString(date: Date): ISODateString {
  return date.toISOString() as ISODateString;
}

function createLocaleDateString(date: Date): LocalDateString {
  return date.toLocaleDateString() as LocalDateString;
}

function createUTCDateString(date: Date): UTCDateString {
  return date.toUTCString() as UTCDateString;
}

// API functions that expect specific date formats
function saveEventToDatabase(eventDate: ISODateString, title: string) {
  // Database expects ISO format
  console.log(`Saving event: ${title} at ${eventDate}`);
}

function displayEventToUser(eventDate: LocalDateString, title: string) {
  // UI expects localized format
  console.log(`Event: ${title} on ${eventDate}`);
}

// Usage
const now = new Date();
const isoDate = createISODateString(now);
const localeDate = createLocaleDateString(now);

saveEventToDatabase(isoDate, "Team Meeting"); // ✅ Correct
// saveEventToDatabase(localeDate, "Team Meeting"); // ❌ TypeScript error!

Advanced Branded Types with Validation

You can enhance branded types with runtime validation to ensure data integrity:

type Email = Brand<string, "Email">;
type PhoneNumber = Brand<string, "PhoneNumber">;
type PositiveNumber = Brand<number, "PositiveNumber">;

function createEmail(value: string): Email {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(value)) {
    throw new Error(`Invalid email format: ${value}`);
  }
  return value as Email;
}

function createPhoneNumber(value: string): PhoneNumber {
  const phoneRegex = /^\+?[\d\s-()]+$/;
  if (!phoneRegex.test(value) || value.length < 10) {
    throw new Error(`Invalid phone number format: ${value}`);
  }
  return value as PhoneNumber;
}

function createPositiveNumber(value: number): PositiveNumber {
  if (value <= 0) {
    throw new Error(`Number must be positive: ${value}`);
  }
  return value as PositiveNumber;
}

// Type-safe user registration
interface UserRegistration {
  email: Email;
  phone: PhoneNumber;
  age: PositiveNumber;
}

function registerUser(registration: UserRegistration) {
  // All inputs are guaranteed to be valid
  console.log("Registering user:", registration);
}

// Usage with validation
try {
  const user: UserRegistration = {
    email: createEmail("user@example.com"),
    phone: createPhoneNumber("+1-555-0123"),
    age: createPositiveNumber(25)
  };

  registerUser(user);
} catch (error) {
  console.error("Registration failed:", error.message);
}

Branded Types for API Responses

Branded types are particularly useful when working with external APIs where you want to ensure data flows correctly:

type ApiResponse<T> = Brand<T, "ApiResponse">;
type ValidatedData<T> = Brand<T, "ValidatedData">;

interface RawUser {
  id: string;
  email: string;
  created_at: string;
}

interface User {
  id: UserId;
  email: Email;
  createdAt: DateString;
}

function fetchUserFromApi(id: UserId): ApiResponse<RawUser> {
  // Simulate API call
  const rawUser = {
    id: id,
    email: "user@example.com",
    created_at: "2024-01-15T10:30:00Z"
  };
  return rawUser as ApiResponse<RawUser>;
}

function validateApiUser(apiUser: ApiResponse<RawUser>): ValidatedData<User> {
  const validated: User = {
    id: createUserId(apiUser.id),
    email: createEmail(apiUser.email),
    createdAt: apiUser.created_at as DateString
  };
  return validated as ValidatedData<User>;
}

function processValidatedUser(user: ValidatedData<User>) {
  // We know this data is safe to use
  console.log("Processing validated user:", user);
}

// Type-safe data flow
const userId = createUserId("user_123");
const apiResponse = fetchUserFromApi(userId);
const validatedUser = validateApiUser(apiResponse);
processValidatedUser(validatedUser);

Utility Types for Branded Types

Here are some useful utility types to work with branded types:

// Extract the underlying type from a branded type
type Unbrand<T> = T extends Brand<infer U, any> ? U : T;

// Check if a type is branded
type IsBranded<T> = T extends Brand<any, any> ? true : false;

// Create a branded type from an existing branded type
type Rebrand<T, TBrand> = Unbrand<T> extends infer U ? Brand<U, TBrand> : never;

// Example usage
type UnbrandedUserId = Unbrand<UserId>; // string
type IsUserIdBranded = IsBranded<UserId>; // true
type AdminId = Rebrand<UserId, "AdminId">; // Brand<string, "AdminId">

When to Use Branded Types

Branded types are most beneficial when:

Domain Separation: You have multiple concepts using the same primitive type (IDs, different string formats)
API Boundaries: Ensuring data validation at system boundaries
Critical Operations: Preventing mix-ups in financial calculations, medical data, etc.
Configuration Management: Distinguishing between different environment configs
Data Transformation Pipelines: Tracking data through validation and transformation stages

Performance Considerations

Branded types are a compile-time feature and have zero runtime overhead. The branding information is erased during compilation, so your JavaScript output remains clean and efficient.

Conclusion

Branded types are a powerful pattern for creating more expressive and safer TypeScript code. They help catch logical errors at compile time, make your intentions clearer, and provide a foundation for building robust type-safe applications.

By using branded types for concepts like date strings, IDs, and validated data, you can significantly reduce runtime errors and make your codebase more maintainable. The small upfront investment in setting up branded types pays dividends in code quality and developer confidence.

Start small by identifying a few key areas in your codebase where primitive types are being mixed up, and gradually expand your use of branded types as you see their benefits in action.

Have you used branded types in your TypeScript projects? Share your experiences and use cases in the comments below!

Exploring TypeScript Enums and Discriminated Unions

Kuncheria Kuruvilla — Tue, 31 Oct 2023 09:11:00 +0000

In the realm of software development, effective communication between components is crucial. When working with TypeScript, a statically typed superset of JavaScript, it's possible to create robust data structures to represent different types of messages and their details. In this blog post, we'll take a deep dive into a TypeScript code snippet that showcases the use of enums and discriminated unions for message handling.

Defining Message Types

To start, we define an enum called MessageType that represents the different types of messages:

enum MessageType {
  BROADCAST,
  P2P
}

In this case, we have two message types: BROADCAST and P2P. These enums allow us to categorize messages into distinct groups.

Message Details

We also define two custom types, BroadcastDetails and P2PDetails, to represent the details of each type of message. These types specify the properties that are relevant for each type:

type BroadcastDetails = {
  sender: string;
  receiver: string[];
  broadcastName: string;
};

type P2PDetails = {
  sender: string;
  receiver: string;
};

BroadcastDetails includes properties like the sender's name, the list of receivers, and the name of the broadcast. On the other hand, P2PDetails represents a peer-to-peer message, involving the sender and a single receiver.

Message Variants

Now, we define message variants using TypeScript's discriminated union feature. We create two message types, BroadcastMessage and P2PMessage, which include a type property from the MessageType enum to distinguish the message type and messageDetails to hold the specific message details:

type BroadcastMessage = {
  type: MessageType.BROADCAST;
  messageDetails: BroadcastDetails;
};

type P2PMessage = {
  type: MessageType.P2P;
  messageDetails: P2PDetails;
};

type MessageDetails = BroadcastMessage | P2PMessage;

By including the type property, we create a discriminated union, making it easy to identify and work with different message types. The MessageDetails type is defined as a union type of the BroadcastMessage and P2PMessage types, which means it can be either a BroadcastMessage or a P2PMessage.

Message Container

To encompass the message and its details, we define a Message type that combines the message content with the specific message details:

type Message = { message: string } & MessageDetails;

This allows us to create messages with a content string and the relevant message details.

Message Instances

We then create two message instances, brdcst and p2p, each representing a different message type:

const brdcst: Message = {
  message: 'this is a broadcast',
  type: MessageType.BROADCAST,
  messageDetails: {
    broadcastName: 'test',
    sender: '+01 999-999-999',
    receiver: ['+01 000-000-0001', '+01 000-000-0002']
  };
};

const p2p: Message = {
  message: 'this is a P2P message',
  type: MessageType.P2P,
  messageDetails: {
    sender: '+01 999-999-999',
    receiver: '+01 000-000-0001'
  };
};

In brdcst, we create a broadcast message with a specified broadcast name, sender, and a list of receivers. In p2p, we define a peer-to-peer message with a sender and a single receiver.

Conclusion

This TypeScript code snippet exemplifies how to implement message handling using enums and discriminated unions. By defining different message types and their details, we can ensure robust communication between components while leveraging TypeScript's strong type-checking capabilities. Whether you're building a chat application, an API, or any system involving message exchange, these techniques can help you manage your messages effectively.

TypeScript Magic: Extracting Route Parameters with Conditional Types

Kuncheria Kuruvilla — Tue, 31 Oct 2023 09:05:33 +0000

In the world of web development, building and managing routes is a common task. Whether you're creating a RESTful API or a dynamic web application, handling route parameters is essential. TypeScript, a statically typed superset of JavaScript, offers a powerful feature known as conditional types. In this blog post, we'll delve into a piece of TypeScript magic that demonstrates how to extract route parameters from a path string using conditional types.

The `IsPathParameter` and `GetPathParameter` Types

Our journey begins with two TypeScript types: IsPathParameter and GetPathParameter.

`IsPathParameter<Part extends string>`

The IsPathParameter type takes a string Part as a parameter and serves as our starting point. It's designed to check whether Part corresponds to a path parameter or a wildcard in a route. Here's how it works:

type IsPathParameter<Part extends string> = 
    Part extends `:${infer Parameter}` ? Parameter : 
    Part extends `*` ? '*' : 
    never;

If Part begins with a colon (":"), it uses the infer keyword to capture the parameter name after the colon. This parameter name is then returned.
If Part is an asterisk (""), it simply returns a string containing "".
If neither of these conditions is met, it returns never, indicating that the input is neither a parameter nor a wildcard.

`GetPathParameter<Path extends string>`

Now, let's move to the GetPathParameter type. This type is where the magic happens. It takes a path string Path as a parameter and recursively breaks it down to extract route parameters. Here's the definition:

export type GetPathParameter<Path extends string> =
  Path extends `${infer A}/${infer B}`
    ? IsPathParameter<A> | GetPathParameter<B>
    : IsPathParameter<Path>;

It begins by checking if the Path can be divided into two segments using a slash ("/"). If it can, it proceeds to check the first segment (A).
If A corresponds to a route parameter, it includes it in the result, and then it recursively analyzes the second segment (B).
If the Path can't be divided any further, the type checks whether the whole Path is a route parameter. If it is, it includes it in the result.

Practical Application: Building a Record

Let's put these types into action by building a Record type. We'll use GetPathParameter to extract route parameters from a path string and create a record type. Here's an example:

type X = Record<GetPathParameter<'base/:a/:b'>, string>;

In this example, we're defining a type X by using Record. We pass the string 'base/:a/:b' to GetPathParameter. As a result, X becomes a record type with keys based on the route parameters in the path and values of type string.

Conclusion

Conditional types, as demonstrated by IsPathParameter and GetPathParameter, provide a powerful mechanism for handling complex type transformations in TypeScript. These types can be invaluable when working with routing systems, ensuring type safety and making your code more robust. So, whether you're creating APIs or web applications, remember that TypeScript has the tools to handle route parameters effectively.

TypeScript Type Utilities: Extracting Array Element Types

Kuncheria Kuruvilla — Tue, 31 Oct 2023 08:58:44 +0000

TypeScript provides the ability to create custom type utilities that can simplify complex type operations. In this blog post, we'll explore a custom type utility called ArrayElement, which is designed to extract the element type of an array. We'll also demonstrate how it can be utilized in practical scenarios.

The ArrayElement Type Utility

Let's begin by taking a closer look at the ArrayElement type utility:

type ArrayElement<ArrayType extends readonly unknown[]> =
ArrayType extends readonly (infer ElementType)[] ? ElementType : never;

At first glance, this code might appear a bit cryptic, but we'll break it down step by step.

The ArrayElement type utility is a generic type that expects an array type, denoted as ArrayType, as its parameter. Its primary purpose is to determine the data type of the elements within the array.

Conditional Typing

One of the powerful features of TypeScript is conditional typing, and this is where it comes into play in the ArrayElement type. The conditional expression ArrayType extends readonly (infer ElementType)[] checks if the ArrayType meets the criteria of an array represented as readonly (infer ElementType)[]. The readonly keyword ensures that the array is read-only, making it compatible with most TypeScript arrays.(Read more)

Extracting the Element Type

If the ArrayType satisfies the condition, TypeScript proceeds to infer the element type of the array and assigns it to the variable ElementType. In essence, this step extracts the type of the elements contained within the array.

Using the never Type

On the other hand, if the ArrayType does not match the pattern of a read-only array, TypeScript uses the never type. The never type is a TypeScript construct indicating that a type does not exist or is not valid in the given context. In this case, it signifies that the ArrayType is not an array as per the defined criteria.

Practical Usage

Now that we've examined the ArrayElement type utility, let's see how it can be applied in practical scenarios.

Consider the following example:

type NumbersArray = Array<number>;
const numbers: NumbersArray = [10, 20, 30];

const number: ArrayElement<NumbersArray> = 12;

In this example, we define a type called NumbersArray, which represents an array containing numbers. We then initialize an array called numbers with values 10, 20, and 30, and TypeScript ensures that it adheres to the defined NumbersArray type.

Next, we declare a constant variable named number and assign it the value 12. TypeScript's type inference capabilities come into play here. By using the ArrayElement type utility with NumbersArray as the generic type parameter, TypeScript correctly deduces that number should have a type of number. This showcases how the ArrayElement utility can be used to ensure that a variable is of the expected element type.

Conclusion

Custom type utilities, like the ArrayElement type we've explored here, can greatly enhance the type safety and expressiveness of your TypeScript code. By utilizing conditional typing and type inference, you can create more robust and maintainable TypeScript applications. Whether you're building web applications, libraries, or APIs, TypeScript's type system offers valuable tools to keep your code reliable and error-free.

iterate , iterate, iterate

Kuncheria Kuruvilla — Sat, 11 Jun 2022 17:55:36 +0000

Lets cut to the chase and look at what we are trying to do here. We need to write a function that can spit an array of any given size, such that every element is obtained by applying a function on the previous element.

Let us consider an initial element x and a function f, what we need is an array which looks something like this :

[x, f(x), f(f(x)), ...]

Well, the simplest application of such a function would be to create a series of numbers like , squares of 2 : 1 ,2, 4, 8 ..

Now lets look at how we can write such a function

function iterate(fn, ele, n) {
  if (n === 0) return [];
  return [ele, ...iterate(fn, fn(ele), n - 1)];
}

Our function iterate, returns a list of repeated applications of fn to ele, repeated n number of times:
Lets try out some examples


    
function iterate(fn, ele, iterationCount) {
  if (iterationCount === 0) return [];
  return [ele, ...iterate(fn, fn(ele), iterationCount - 1)];
}


    
const multiply = (x) => (y) => x * y;
console.log(iterate(multiply(2), 1, 5));

The initial item and the function you apply can be anything that you can think of. You could easily create a list of dummy products take a look at the example:


    
function iterate(fn, ele, iterationCount) {
  if (iterationCount === 0) return [];
  return [ele, ...iterate(fn, fn(ele), iterationCount - 1)];
}


    

const initialProduct = { id: 100, slug: `prd${100}`, name: `Product-${100}` };

const createNextProduct = (product) => {
  const nextProductId = product.id + 1;
  return {
    id: nextProductId,
    slug: `prd${nextProductId}`,
    name: `Product-${nextProductId}`,
  };
};
console.log(iterate(createNextProduct, initialProduct, 5));

Filtering an array against another array conditionally

Kuncheria Kuruvilla — Sat, 11 Jun 2022 17:53:27 +0000

In this series of articles we look at several practical use cases and see how we can write clean JavaScript in functional style. You might need a little bit of understanding about functional programming and ramda to follow along.

Problem statement

We need to build a function that takes an array of strings as query and another array of strings as target. The function should return an array with those strings in target that starts with any item in query.
Lets look at an example.
If query is

["pen", "paper"]

and target is

["pen", "pencil", "paper", "", "books", "paperback"]

the result should be

["pen", "pencil", "paper", "paperback"]

Solution

Lets look at the final solution first and then break it down.

Our textStartsWith function takes query as its argument and returns another function which accepts target and returns the result.
If we take a look at the pipe function it becomes more interesting

const textStartsWith = pipe(map(startsWith), anyPass, filter);

map(startsWith) actually creates an array of predicates, each corresponding to the items in query. This list of predicates is passed to anyPass. Now what we have is a single predicate with resolves to true if a given string starts with any of the strings in query. We can now pass this predicate as an argument to filter. Now when you call textStartsWith with the list of strings or query we get back a filter function with the predicate already partially applied. Now all we need to do is pass the target array as an argument to this function.

P.S. If you need more insights to the solution check out this thread on stack overflow

Jun 9 '21

I would combine startsWith and anyPass like this:

const textStartsWith = pipe (
  map (startsWith), 
  anyPass,
  flip (o) (String),
  filter
)

console .log (
  textStartsWith 
    (['pen', 'paper']) 
    (['pen', 'pencil', 'paper', '', undefined, true, 'books', 'paperback'])
)

<script src="https://cdnjs.cloudflare.com/ajax/libs/ramda/0.27.1/ramda.min.js"></script>
<script>const {pipe, map, startsWith, anyPass, flip, o, filter} =

…

</p>

Open Full Answer

DEV Community: Kuncheria Kuruvilla

Branded Types in TypeScript: Beyond Primitive Type Safety

What Are Branded Types?

Creating Branded Types

Real-World Example: Date Strings

Advanced Branded Types with Validation

Branded Types for API Responses

Utility Types for Branded Types

When to Use Branded Types

Performance Considerations

Conclusion

Exploring TypeScript Enums and Discriminated Unions

Defining Message Types

Message Details

Message Variants

Message Container

Message Instances

Conclusion

TypeScript Magic: Extracting Route Parameters with Conditional Types

The IsPathParameter and GetPathParameter Types

IsPathParameter<Part extends string>

GetPathParameter<Path extends string>

Practical Application: Building a Record

Conclusion

TypeScript Type Utilities: Extracting Array Element Types

iterate , iterate, iterate

Filtering an array against another array conditionally

Problem statement

Solution

The `IsPathParameter` and `GetPathParameter` Types

`IsPathParameter<Part extends string>`

`GetPathParameter<Path extends string>`