Vì TypeScript là structural typing, một UserId và một OrderId mà cả hai đều là string thì có thể hoán đổi cho nhau — compiler không thể ngăn bạn nhầm lẫn chúng. Branded type mô phỏng kiểu nominal bằng cách gắn một "brand" phantom duy nhất để các kiểu vốn giống hệt nhau trở nên khác biệt.
// brand là một thuộc tính chỉ tồn tại trong type system, không bao giờ ở runtime
type Brand<T, B> = T & { readonly __brand: B };
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
function getUser(id: UserId) { return id; }
const uid = "u1" as UserId;
const oid = "o1" as OrderId;
getUser(uid); // ✅
getUser(oid); // ❌ Lỗi: OrderId không gán được cho UserId
getUser("u1"); // ❌ Lỗi: string thuần không phải là UserId
Thuộc tính __brand không bao giờ tồn tại ở runtime (giá trị chỉ là một string), nhưng trong type system nó làm cho UserId và OrderId không tương thích — ngăn chặn cả một lớp bug nhầm lẫn.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation diễn ra ở đây, một lần
}
Xác thực một lần tại ranh giới; phần còn lại của code tin tưởng vào branded type.
Các ID (UserId so với OrderId), các string đã validate/sanitize (Email, SafeHtml), đơn vị (Meters so với Feet), PositiveNumber — bất cứ nơi nào hai giá trị chia sẻ một kiểu primitive nhưng không được phép nhầm lẫn.
Branded type bổ sung sự an toàn nominal ở những nơi mà structural typing quá dễ dãi.
Chúng bắt được nhầm lẫn thứ tự đối số và sự lẫn lộn "chưa validate vs đã validate" ngay lúc compile, với chi phí runtime bằng không — một pattern mạnh mẽ cho việc mô hình hóa domain trong các codebase lớn, đòi hỏi tính đúng đắn cao.