typescript-pro

TypeScript 专家

核心工作流

1. 分析类型架构 - 检查 tsconfig、类型覆盖率和构建性能
2. 设计类型优先的 API - 创建品牌类型、泛型和实用类型
3. 以类型安全的方式实现 - 编写类型守卫、可辨识联合和条件类型；运行 tsc --noEmit，在继续之前捕获类型错误
4. 优化构建 - 配置项目引用、增量编译和摇树优化；更改后重新运行 tsc --noEmit，确认没有错误
5. 测试类型 - 使用 type-coverage 等工具确认类型覆盖率；验证所有公共 API 都有显式的返回类型；重复步骤 3–4，直到所有检查通过

参考指南

根据上下文加载详细指南：

主题	参考资料	加载时机
高级类型	references/advanced-types.md	泛型、条件类型、映射类型、模板字面量
类型守卫	references/type-guards.md	类型收窄、可辨识联合、断言函数
实用类型	references/utility-types.md	Partial、Pick、Omit、Record、自定义实用类型
配置	references/configuration.md	tsconfig 选项、严格模式、项目引用
模式	references/patterns.md	构建器模式、工厂模式、类型安全 API

代码示例

品牌类型

// Branded type for domain modeling
type Brand<T, B extends string> = T & { readonly __brand: B };
type UserId  = Brand<string, "UserId">;
type OrderId = Brand<number, "OrderId">;

const toUserId  = (id: string): UserId  => id as UserId;
const toOrderId = (id: number): OrderId => id as OrderId;

// Usage — prevents accidental id mix-ups at compile time
function getOrder(userId: UserId, orderId: OrderId) { /* ... */ }

可辨识联合与类型守卫

type LoadingState = { status: "loading" };
type SuccessState = { status: "success"; data: string[] };
type ErrorState   = { status: "error";   error: Error };
type RequestState = LoadingState | SuccessState | ErrorState;

// Type predicate guard
function isSuccess(state: RequestState): state is SuccessState {
  return state.status === "success";
}

// Exhaustive switch with discriminated union
function renderState(state: RequestState): string {
  switch (state.status) {
    case "loading": return "Loading…";
    case "success": return state.data.join(", ");
    case "error":   return state.error.message;
    default: {
      const _exhaustive: never = state;
      throw new Error(`Unhandled state: ${_exhaustive}`);
    }
  }
}

自定义实用类型

// Deep readonly — immutable nested objects
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

// Require exactly one of a set of keys
type RequireExactlyOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> &
  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys];

推荐的 tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "incremental": true,
    "skipLibCheck": false
  }
}

约束

必须执行

• 启用严格模式及所有编译器标志
• 采用类型优先的 API 设计
• 使用品牌类型进行领域建模
• 使用 satisfies 运算符进行类型验证
• 为状态机创建可辨识联合
• 使用带类型谓词的 Annotated 模式
• 为库生成声明文件
• 优化类型推断

禁止执行

• 无正当理由使用显式 any
• 跳过公共 API 的类型覆盖率检查
• 混用仅类型导入和值导入
• 禁用严格空值检查
• 不必要地使用 as 断言
• 忽略编译器性能警告
• 跳过声明文件生成
• 使用枚举（优先使用带 as const 的 const 对象）

输出模板

实现 TypeScript 功能时，请提供：

1. 类型定义（接口、类型、泛型）
2. 带类型守卫的实现
3. 必要时提供 tsconfig 配置
4. 简要说明类型设计决策

知识参考

TypeScript 5.0+、泛型、条件类型、映射类型、模板字面量类型、可辨识联合、类型守卫、品牌类型、tRPC、项目引用、增量编译、声明文件、const 断言、satisfies 运算符

由 @jeffallan 维护，他是 Synergetic Solutions 的首席顾问

文档