branded-types

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Branded Types

品牌化类型

What & Why

是什么 & 为什么

TypeScript uses structural typing — two types with the same shape are interchangeable. This means

UserId

and

PostId

(both

string

) can be silently swapped, causing bugs:

typescript

type UserId = string
type PostId = string

function getUser(id: UserId) { /* ... */ }

const postId: PostId = "post-123"
getUser(postId) // No error! Both are just `string`

Branded types add a compile-time-only marker that makes structurally identical types incompatible. Zero runtime overhead — brands are erased during compilation.

TypeScript采用结构类型系统——两个结构相同的类型可以互换使用。这意味着

UserId

和

PostId

（均为

string

类型）可能会被无意识地混用，从而引发bug：

typescript

type UserId = string
type PostId = string

function getUser(id: UserId) { /* ... */ }

const postId: PostId = "post-123"
getUser(postId) // 无错误！两者本质都是`string`

品牌化类型会添加一个仅在编译期存在的标记，让结构相同的类型变得不兼容。完全没有运行时开销——品牌标记会在编译过程中被移除。

Core Pattern (Recommended)

核心模式（推荐）

Use a generic

Brand

utility with a single

unique symbol

typescript

// brand.ts
declare const __brand: unique symbol
type Brand<T, B extends string> = T & { readonly [__brand]: B }

Define specific branded types:

typescript

import type { Brand } from './brand'

type UserId = Brand<string, 'UserId'>
type PostId = Brand<string, 'PostId'>
type Email  = Brand<string, 'Email'>

type Meters       = Brand<number, 'Meters'>
type Seconds      = Brand<number, 'Seconds'>
type PositiveInt  = Brand<number, 'PositiveInt'>

Now

UserId

and

PostId

are incompatible at compile time:

typescript

function getUser(id: UserId) { /* ... */ }

const postId = "post-123" as PostId
getUser(postId) // TS Error: PostId is not assignable to UserId

使用带有唯一符号

unique symbol

的泛型

Brand

工具类型：

typescript

// brand.ts
declare const __brand: unique symbol
type Brand<T, B extends string> = T & { readonly [__brand]: B }

定义具体的品牌化类型：

typescript

import type { Brand } from './brand'

type UserId = Brand<string, 'UserId'>
type PostId = Brand<string, 'PostId'>
type Email  = Brand<string, 'Email'>

type Meters       = Brand<number, 'Meters'>
type Seconds      = Brand<number, 'Seconds'>
type PositiveInt  = Brand<number, 'PositiveInt'>

现在

UserId

和

PostId

在编译期是不兼容的：

typescript

function getUser(id: UserId) { /* ... */ }

const postId = "post-123" as PostId
getUser(postId) // TS错误：PostId无法赋值给UserId

Constructor Functions

构造函数

Never use bare

as

casts in application code. Create constructor/validation functions:

typescript

function createUserId(id: string): UserId {
  if (!id || id.length === 0) throw new Error('Invalid UserId')
  return id as UserId
}

function validateEmail(input: string): Email {
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input)) {
    throw new Error('Invalid email')
  }
  return input as Email
}

function toPositiveInt(n: number): PositiveInt {
  if (!Number.isInteger(n) || n <= 0) throw new Error('Must be positive integer')
  return n as PositiveInt
}

The

as

cast is confined to these constructor functions — the only place it should appear.

永远不要在业务代码中直接使用

as

类型断言。请创建构造/校验函数：

typescript

function createUserId(id: string): UserId {
  if (!id || id.length === 0) throw new Error('无效的UserId')
  return id as UserId
}

function validateEmail(input: string): Email {
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input)) {
    throw new Error('无效的邮箱')
  }
  return input as Email
}

function toPositiveInt(n: number): PositiveInt {
  if (!Number.isInteger(n) || n <= 0) throw new Error('必须是正整数')
  return n as PositiveInt
}

as

断言仅应出现在这些构造函数中——这是它唯一应该出现的地方。

Implementation Variants

实现变体

Pattern	Approach	Strength	Verbosity
A `__brand` property	`T & { __brand: B }`	Good	Low
B Per-type `unique symbol`	`T & { [MyBrand]: true }`	Strongest	High
C Generic `unique symbol` (recommended)	`T & { [__brand]: B }`	Strong	Low

Default to Pattern C — it balances safety with ergonomics. For detailed trade-offs and full examples, see references/patterns.md.

模式	实现方式	优势	冗长程度
A `__brand` 属性	`T & { __brand: B }`	良好	低
B 每个类型单独的 `unique symbol`	`T & { [MyBrand]: true }`	最安全	高
C 泛型 `unique symbol` （推荐）	`T & { [__brand]: B }`	安全性高	低

默认使用模式C——它在安全性和易用性之间取得了平衡。有关详细的权衡和完整示例，请参阅references/patterns.md。

Real-World Use Cases

实际应用场景

Type-safe IDs

类型安全的ID

typescript

type UserId    = Brand<string, 'UserId'>
type PostId    = Brand<string, 'PostId'>
type CommentId = Brand<string, 'CommentId'>

function getPost(postId: PostId) { /* ... */ }
function deleteComment(commentId: CommentId) { /* ... */ }

typescript

type UserId    = Brand<string, 'UserId'>
type PostId    = Brand<string, 'PostId'>
type CommentId = Brand<string, 'CommentId'>

function getPost(postId: PostId) { /* ... */ }
function deleteComment(commentId: CommentId) { /* ... */ }

Validated strings

经过验证的字符串

typescript

type Email           = Brand<string, 'Email'>
type NonEmptyString  = Brand<string, 'NonEmptyString'>
type SanitizedHTML   = Brand<string, 'SanitizedHTML'>
type TranslationKey  = Brand<string, 'TranslationKey'>

typescript

type Email           = Brand<string, 'Email'>
type NonEmptyString  = Brand<string, 'NonEmptyString'>
type SanitizedHTML   = Brand<string, 'SanitizedHTML'>
type TranslationKey  = Brand<string, 'TranslationKey'>

Unit-specific numbers

特定单位的数字

typescript

type Meters       = Brand<number, 'Meters'>
type Feet         = Brand<number, 'Feet'>
type Seconds      = Brand<number, 'Seconds'>
type Milliseconds = Brand<number, 'Milliseconds'>
type Percentage   = Brand<number, 'Percentage'> // 0-100

typescript

type Meters       = Brand<number, 'Meters'>
type Feet         = Brand<number, 'Feet'>
type Seconds      = Brand<number, 'Seconds'>
type Milliseconds = Brand<number, 'Milliseconds'>
type Percentage   = Brand<number, 'Percentage'> // 0-100

Tokens and sensitive values

令牌与敏感值

typescript

type AccessToken  = Brand<string, 'AccessToken'>
type RefreshToken = Brand<string, 'RefreshToken'>
type ApiKey       = Brand<string, 'ApiKey'>

typescript

type AccessToken  = Brand<string, 'AccessToken'>
type RefreshToken = Brand<string, 'RefreshToken'>
type ApiKey       = Brand<string, 'ApiKey'>

Anti-Patterns

反模式

1. Checking brand at runtime

1. 在运行时检查品牌

typescript

// WRONG — __brand does not exist at runtime
if ((value as any).__brand === 'UserId') { /* ... */ }

Branded types are compile-time only. For runtime checks, use your constructor/validation functions.

typescript

// 错误 —— __brand在运行时不存在
if ((value as any).__brand === 'UserId') { /* ... */ }

品牌化类型仅存在于编译期。如需运行时检查，请使用构造/校验函数。

2. Bare

as

casts in application code

2. 在业务代码中直接使用

as

断言

typescript

// BAD — no validation, defeats the purpose
const userId = someString as UserId

// GOOD — validated constructor
const userId = createUserId(someString)

Confine

as

casts to constructor functions only.

typescript

// 不好 —— 没有校验，失去了类型的意义
const userId = someString as UserId

// 好 —— 使用经过校验的构造函数
const userId = createUserId(someString)

仅在构造函数中使用

as

断言。

3. Over-branding

3. 过度品牌化

Don't brand every

string

number

. Use branded types when:

Mixing values would cause bugs (IDs, units, validated data)
Multiple similar types exist that should not be interchangeable
The project is large enough to benefit from the safety

不要给每个

string

或

number

都添加品牌。仅在以下场景使用品牌化类型：

混用值会导致bug（ID、单位、经过验证的数据）
存在多个不应互换的相似类型
项目规模足够大，能从类型安全中获益

4. Duplicate brand names across modules

4. 跨模块重复品牌名称

typescript

// file-a.ts — Brand<string, 'Id'>
// file-b.ts — Brand<number, 'Id'>
// These share the brand name 'Id' but mean different things!

Use specific, descriptive brand names:

'UserId'

'PostId'

, not just

'Id'

typescript

// file-a.ts —— Brand<string, 'Id'>
// file-b.ts —— Brand<number, 'Id'>
// 它们共享品牌名称'Id'，但含义完全不同！

使用具体、描述性的品牌名称：

'UserId'

、

'PostId'

，而不是仅仅

'Id'

。

Library Integrations

库集成

Zod

typescript

import { z } from 'zod'

const UserIdSchema = z.string().uuid().brand<'UserId'>()
type UserId = z.infer<typeof UserIdSchema> // string & Brand<'UserId'>

const parsed = UserIdSchema.parse(input) // typed as UserId

typescript

import { z } from 'zod'

const UserIdSchema = z.string().uuid().brand<'UserId'>()
type UserId = z.infer<typeof UserIdSchema> // string & Brand<'UserId'>

const parsed = UserIdSchema.parse(input) // 类型为UserId

Drizzle ORM

typescript

import { text } from 'drizzle-orm/pg-core'

// Brand the column output type
const users = pgTable('users', {
  id: text('id').primaryKey().$type<UserId>(),
})

// Queries return UserId, not plain string
const user = await db.select().from(users).where(eq(users.id, userId))

For detailed integration examples (end-to-end flows, more libraries), see references/integrations.md.

typescript

import { text } from 'drizzle-orm/pg-core'

// 为列的输出类型添加品牌
const users = pgTable('users', {
  id: text('id').primaryKey().$type<UserId>(),
})

// 查询返回UserId，而非普通字符串
const user = await db.select().from(users).where(eq(users.id, userId))

有关详细的集成示例（端到端流程、更多库），请参阅references/integrations.md。

When to Use Branded Types

何时使用品牌化类型

Scenario	Use branded types?
Multiple ID types that should not mix	Yes
Validated vs. unvalidated data	Yes
Unit-specific numbers (meters vs feet)	Yes
Tokens/secrets vs plain strings	Yes
Small script with few types	Probably not
Single ID type in a small project	Probably not
Need runtime type discrimination	Use discriminated unions instead

场景	是否使用品牌化类型？
存在多个不应混用的ID类型	是
经过验证的数据与未验证的数据	是
特定单位的数字（米 vs 英尺）	是
令牌/密钥与普通字符串	是
类型很少的小型脚本	不推荐
小型项目中仅有一种ID类型	不推荐
需要运行时类型区分	改用可区分联合类型

Additional Resources

额外资源

For detailed pattern comparisons: references/patterns.md
For library integration examples: references/integrations.md

详细的模式对比：references/patterns.md
库集成示例：references/integrations.md

branded-types

Original

Translation

Branded Types

品牌化类型

What & Why

是什么 & 为什么

Core Pattern (Recommended)

核心模式（推荐）

Constructor Functions

构造函数

Implementation Variants

实现变体

Real-World Use Cases

实际应用场景

Type-safe IDs

类型安全的ID

Validated strings

经过验证的字符串

Unit-specific numbers

特定单位的数字

Tokens and sensitive values

令牌与敏感值

Anti-Patterns

反模式

1. Checking brand at runtime

1. 在运行时检查品牌

2. Bare as casts in application code

2. 在业务代码中直接使用as断言

3. Over-branding

3. 过度品牌化

4. Duplicate brand names across modules

4. 跨模块重复品牌名称

Library Integrations

库集成

Zod

Zod

Drizzle ORM

Drizzle ORM

When to Use Branded Types

何时使用品牌化类型

Additional Resources

额外资源

2. Bare
`as`
casts in application code

2. 在业务代码中直接使用
`as`
断言