读写 TypeScript/JavaScript…

在编写或阅读 `.ts`、`.tsx`、`.js` 或 `tsconfig.json` 时，应用本技能做类型优先建模、Zod 运行时校验和可选 type-fest 高级类型，减少非法状态、重复类型和边界数据错误。

适用场景

解决思路

1. 遵循来自 `CLAUDE.md` 的 type-first、函数式与错误处理模式；本技能只覆盖语言特定惯用法。
2. 用类型系统在编译期阻止非法状态，目标是让非法状态无法被表示。
3. 对互斥状态使用可辨识联合（discriminated unions），只允许有效组合；不要用一个包含多个可选布尔/字段的对象来允许加载中同时出错等无效组合。
4. 对领域基础类型使用品牌类型（branded types），例如 `type UserId = string & { readonly __brand: 'UserId' }`、`type OrderId = string & { readonly __brand: 'OrderId' }`，让编译器阻止把 `OrderId` 传给期望 `UserId` 的函数。
5. 对字面量联合使用 `as const` 断言，例如 `const ROLES = ['admin', 'user', 'guest'] as const`，再定义 `type Role = typeof ROLES[number]`，让数组和类型自动保持同步。
6. 为字面量联合提供类型守卫，例如 `function isValidRole(role: string): role is Role { return ROLES.includes(role as Role); }`。
7. 在 `switch` 中对联合类型做穷尽检查：在 `default` 分支声明 `const _exhaustive: never = status;`，若遗漏分支则编译报错，并抛出未处理状态错误。
8. 用 Zod 做运行时校验：把 schema 作为唯一事实来源，用 `z.infer<>` 推导 TypeScript 类型，避免重复定义类型和 schema。
9. 在预期会失败的用户输入处理中用 `safeParse`。
10. 在信任边界（如 API 响应）用 `parse`，因为无效数据应被视为 bug 并抛出异常。
11. 用 `.extend()`、`.pick()`、`.omit()`、`.merge()` 组合 schema，保持 DRY。
12. 在解析时用 `.transform()` 做数据归一化，例如 trim 字符串、把日期字符串解析为 `Date`。
13. 在信任边界严格解析，例如 `fetchUser` 中检查 `response.ok`，失败抛错，然后用 `UserSchema.parse(await response.json())` 返回类型安全数据。
14. 对用户表单输入处理成功和失败，例如 `UserSchema.safeParse(formData)`；若 `!result.success`，则用 `result.error.flatten().fieldErrors` 设置错误并返回。
15. 可选：对超出 TypeScript 内置能力的高级类型工具，考虑使用 `type-fest`。
16. 可选：使用 `Opaque<T, Token>` 创建比手动 `& { __brand }` 更干净品牌类型。
17. 可选：使用 `PartialDeep<T>` 表示嵌套对象的递归 partial。
18. 可选：使用 `ReadonlyDeep<T>` 表示不可变数据的递归 readonly。
19. 可选：使用 `SetRequired<T, K>` / `SetOptional<T, K>` 对指定字段做有目标的必选/可选修改。
20. 可选：使用 `Simplify<T>` 在 IDE tooltip 中展平复杂交叉类型。

适用边界 · 注意事项

• 处理 React 组件（`.tsx`、`.jsx` 文件或 `@react` imports）时，不要只依赖本技能；必须同时加载 `react-best-practices`，因为 effects、hooks、refs、组件设计等 React 特定模式不在本技能覆盖范围内。
• 如果任务完全不涉及 TypeScript/JavaScript 文件（`.ts`、`.tsx`、`.js`、`tsconfig.json`），则不适用。