typescript-strict-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript Strict Patterns

TypeScript 严格编码模式

Project setup — read
project-setup.md
when bootstrapping a new project or changing tsconfig / ts-reset / type-fest. ESLint baseline — read
eslint.config.mjs
when adding or tweaking lint rules.

项目设置 — 当启动新项目或修改tsconfig、ts-reset、type-fest时，请阅读
project-setup.md
。 ESLint 基准配置 — 当添加或调整 lint 规则时，请阅读
eslint.config.mjs
。

Discriminated Unions + Exhaustive Checking

可区分联合 + 穷尽性检查

Model variants as discriminated unions — never bags of optional properties:

typescript

// GOOD — each variant carries exactly its data
type Result =
  | { status: "ok"; data: string }
  | { status: "error"; message: string };

// Exhaustive check helper — will fail to compile if a variant is missed
function assertNever(x: never): never {
  throw new Error(`Unexpected: ${JSON.stringify(x)}`);
}

function handle(r: Result) {
  switch (r.status) {
    case "ok": return r.data;
    case "error": return r.message;
    default: assertNever(r); // compile error if a case is missing
  }
}

Use

satisfies never

or the

assertNever

helper at the

default:

branch. ESLint's

switch-exhaustiveness-check

enforces this at lint time.

将变体建模为可区分联合 — 绝不要使用一堆可选属性：

typescript

// GOOD — each variant carries exactly its data
type Result =
  | { status: "ok"; data: string }
  | { status: "error"; message: string };

// Exhaustive check helper — will fail to compile if a variant is missed
function assertNever(x: never): never {
  throw new Error(`Unexpected: ${JSON.stringify(x)}`);
}

function handle(r: Result) {
  switch (r.status) {
    case "ok": return r.data;
    case "error": return r.message;
    default: assertNever(r); // compile error if a case is missing
  }
}

在

default:

分支使用

satisfies never

或

assertNever

辅助函数。ESLint的

switch-exhaustiveness-check

规则会在lint阶段强制执行这一点。

Branded Types

品牌类型

Prevent accidental interchange of structurally identical types with a brand:

typescript

type Brand<T, B extends string> = T & { readonly __brand: B };

type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;

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

const uid = "abc" as UserId; // cast once at the boundary
getUser(uid);    // OK
getUser("abc");  // compile error — plain string is not UserId

Brand at system boundaries (API response parsing, DB reads). Internal code then carries the brand without further casts.

通过品牌防止结构相同的类型被意外混用：

typescript

type Brand<T, B extends string> = T & { readonly __brand: B };

type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;

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

const uid = "abc" as UserId; // cast once at the boundary
getUser(uid);    // OK
getUser("abc");  // compile error — plain string is not UserId

在系统边界（API响应解析、数据库读取）处添加品牌标记。内部代码随后可携带该品牌，无需再次转换。

Template Literal Types

模板字面量类型

Enforce string formats at the type level:

typescript

type HexColor = `#${string}`;
type Route = `/${string}`;
type EventName = `on${Capitalize<string>}`;

function setColor(c: HexColor) { /* ... */ }
setColor("#ff0000"); // OK
setColor("red");     // compile error

Useful for config keys, route paths, and event names where runtime validation is overkill but typos are common.

在类型层面强制字符串格式：

typescript

type HexColor = `#${string}`;
type Route = `/${string}`;
type EventName = `on${Capitalize<string>}`;

function setColor(c: HexColor) { /* ... */ }
setColor("#ff0000"); // OK
setColor("red");     // compile error

适用于配置键、路由路径和事件名称等场景，这些场景中运行时验证有些过度，但拼写错误很常见。

as

in Production Code

生产代码中禁止使用

或

as

Non-null assertions (

) and type assertions (

as

) are banned in production code. They hide type errors. Allowed in test files where the tradeoff is acceptable (enforced by ESLint config).

Replacements:

Destructuring with defaults instead of
```
obj.prop!
```
:
```
const { name = '' } = config;
```

.at()
+ nullish coalescing instead of

arr[0]!

const first = arr.at(0) ?? fallback;

Guard clause instead of
```
value as Foo
```
: narrow with a type guard, then the type flows naturally.

生产代码中禁止使用非空断言符(

)和类型断言(

as

)，它们会隐藏类型错误。测试文件中允许使用，因为在测试场景下这种权衡是可接受的（由ESLint配置强制执行）。

替代方案：

带默认值的解构替代
```
obj.prop!
```
：
```
const { name = '' } = config;
```

.at()
+ 空值合并运算符替代

arr[0]!

：

const first = arr.at(0) ?? fallback;

守卫子句替代
```
value as Foo
```
：通过类型守卫收窄类型，类型会自然推导。

Const Arrays Over Enums

优先使用Const数组而非枚举

Never use

enum

(enforced by ESLint). Use

as const

arrays with derived types:

typescript

const STATUSES = ["pending", "active", "done"] as const;
type Status = (typeof STATUSES)[number];

At system boundaries where Zod already validates, prefer

z.enum(STATUSES)

— it gives you the union type and runtime validation in one step.

绝不要使用

enum

（由ESLint强制执行）。使用

as const

数组并派生类型：

typescript

const STATUSES = ["pending", "active", "done"] as const;
type Status = (typeof STATUSES)[number];

在Zod已进行验证的系统边界处，优先使用

z.enum(STATUSES)

— 它能一步提供联合类型和运行时验证。

Zod Schemas at System Boundaries

系统边界处的Zod模式

Use Zod schemas as the single source of truth for data crossing system boundaries (disk I/O, env vars, API responses, config files). Derive types with

z.infer<>

— never duplicate a hand-written interface alongside a schema.

typescript

export const sessionMetaSchema = z.object({
  token: z.string(),
  status: z.enum(["running", "completed", "error"]),
});
export type SessionMeta = z.infer<typeof sessionMetaSchema>;

Use
```
safeParse()
```
for data that may be corrupt (disk reads, JSONL) — skip gracefully
Use
```
parse()
```
for startup validation (env vars) where failure is fatal
Skip Zod for internal function arguments between trusted modules and for SDK-owned types

使用Zod模式作为跨系统边界（磁盘I/O、环境变量、API响应、配置文件）数据的唯一可信来源。通过

z.infer<>

派生类型 — 绝不要在模式旁重复手写接口。

typescript

export const sessionMetaSchema = z.object({
  token: z.string(),
  status: z.enum(["running", "completed", "error"]),
});
export type SessionMeta = z.infer<typeof sessionMetaSchema>;

对于可能损坏的数据（磁盘读取、JSONL），使用
```
safeParse()
```
— 优雅跳过错误
对于启动时的验证（环境变量），使用
```
parse()
```
— 验证失败则终止程序
可信模块间的内部函数参数和SDK自有类型无需使用Zod

Safe Indexed Access

安全索引访问

With

noUncheckedIndexedAccess

, bracket access returns

T | undefined

. Always narrow:

Use
```
.at(index)
```
— clearer intent than bracket access
Handle with
```
if (item !== undefined)
```
or
```
??
```
Prefer
```
.find()
```
,
```
.filter()
```
, or destructuring over index access

启用

noUncheckedIndexedAccess

后，方括号访问会返回

T | undefined

。必须始终收窄类型：

使用
```
.at(index)
```
— 比方括号访问的意图更清晰
通过
```
if (item !== undefined)
```
或
```
??
```
处理可能的undefined
优先使用
```
.find()
```
、
```
.filter()
```
或解构而非索引访问

Type Helpers (type-fest as Inspiration)

类型辅助工具（以type-fest为参考）

Use type-fest as a reference catalog when strict patterns make code verbose. Browse its source for solutions like

SetRequired

Simplify

JsonValue

. Copy the single type definition you need into

src/types/

with attribution. Don't add the full package as a dependency — keep the dependency graph small.

当严格模式导致代码冗长时，将type-fest作为参考目录使用。浏览其源码寻找

SetRequired

、

Simplify

、

JsonValue

等解决方案。将所需的单个类型定义复制到

src/types/

并注明出处。不要添加完整包作为依赖 — 保持依赖图精简。

typescript-strict-patterns

Original

Translation

TypeScript Strict Patterns

TypeScript 严格编码模式

Discriminated Unions + Exhaustive Checking

可区分联合 + 穷尽性检查

Branded Types

品牌类型

Template Literal Types

模板字面量类型

No
`!`
or
`as`
in Production Code

生产代码中禁止使用
`!`
或
`as`

Const Arrays Over Enums

优先使用Const数组而非枚举

Zod Schemas at System Boundaries

系统边界处的Zod模式

Safe Indexed Access

安全索引访问

Type Helpers (type-fest as Inspiration)

类型辅助工具（以type-fest为参考）

typescript-strict-patterns

Original

Translation

TypeScript Strict Patterns

TypeScript 严格编码模式

Discriminated Unions + Exhaustive Checking

可区分联合 + 穷尽性检查

Branded Types

品牌类型

Template Literal Types

模板字面量类型

No ! or as in Production Code

生产代码中禁止使用!或as

Const Arrays Over Enums

优先使用Const数组而非枚举

Zod Schemas at System Boundaries

系统边界处的Zod模式

Safe Indexed Access

安全索引访问

Type Helpers (type-fest as Inspiration)

类型辅助工具（以type-fest为参考）

No
`!`
or
`as`
in Production Code

生产代码中禁止使用
`!`
或
`as`