---

name: typescript-ops description: "TypeScript 类型系统、泛型、工具类型、严格模式和生态系统模式。适用于：typescript、ts、type、generic、utility type、Partial、Pick、Omit、Record、Exclude、Extract、ReturnType、Parameters、keyof、typeof、infer、mapped type、conditional type、template literal type、discriminated union、type guard、type assertion、type narrowing、tsconfig、strict mode、declaration file、zod、valibot。" license: MIT allowed-tools: "Read Write Bash" metadata: author: claude-mods related-skills: react-ops, testing-ops

TypeScript 操作指南

全面的 TypeScript 技能，涵盖类型系统、泛型和生产模式。

类型收窄决策树

如何收窄类型？
│
├─ 原始类型检查
│  └─ typeof：typeof x === "string"
│
├─ 实例检查
│  └─ instanceof：x instanceof Date
│
├─ 属性存在性
│  └─ in："email" in user
│
├─ 可辨识联合
│  └─ 对字面量字段 switch：switch (event.type)
│
├─ Null/undefined 检查
│  └─ 真值判断：if (x) 或 if (x != null)
│
├─ 自定义逻辑
│  └─ 类型谓词：function isUser(x: unknown): x is User
│
└─ 断言（你比 TS 更了解）
   └─ as：value as string（逃生舱口，尽量避免）

类型守卫示例

interface Dog { bark(): void; breed: string }
interface Cat { meow(): void; color: string }

function isDog(pet: Dog | Cat): pet is Dog {
    return "bark" in pet;
}

function handlePet(pet: Dog | Cat) {
    if (isDog(pet)) {
        pet.bark(); // TS knows it's Dog here
    } else {
        pet.meow(); // TS knows it's Cat here
    }
}

可辨识联合

type Result<T> =
    | { status: "success"; data: T }
    | { status: "error"; error: string }
    | { status: "loading" };

function handle<T>(result: Result<T>) {
    switch (result.status) {
        case "success": return result.data;
        case "error":   throw new Error(result.error);
        case "loading": return null;
    }
    const _exhaustive: never = result;
}

工具类型速查表

| 工具类型 | 作用 | 示例 | |---------|-------------|---------| | Partial<T> | 所有属性可选 | Partial<User> 用于更新载荷 | | Required<T> | 所有属性必需 | Required<Config> 用于已验证配置 | | Readonly<T> | 所有属性只读 | Readonly<State> 用于不可变状态 | | Pick<T, K> | 选择特定属性 | Pick<User, "id" \| "name"> | | Omit<T, K> | 移除特定属性 | Omit<User, "password"> | | Record<K, V> | 类型化键值对象 | Record<string, number> | | Exclude<U, E> | 从联合中移除类型 | Exclude<Status, "deleted"> | | Extract<U, E> | 从联合中保留类型 | Extract<Event, { type: "click" }> | | NonNullable<T> | 移除 null/undefined | NonNullable<string \| null> | | ReturnType<F> | 函数返回类型 | ReturnType<typeof fetchUser> | | Parameters<F> | 函数参数元组 | Parameters<typeof createUser> | | Awaited<T> | 解包 Promise 类型 | Awaited<Promise<User>> = User |

泛型模式

约束泛型

// 基本约束
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
    return obj[key];
}

// 多重约束
function merge<T extends object, U extends object>(a: T, b: U): T & U {
    return { ...a, ...b };
}

// 默认泛型类型
type ApiResponse<T = unknown> = {
    data: T;
    status: number;
};

条件类型

// 基本条件
type IsString<T> = T extends string ? true : false;

// infer 关键字 - 提取内部类型
type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
type UnwrapArray<T> = T extends (infer U)[] ? U : T;

// 分布式条件（在联合上分布）
type ToArray<T> = T extends any ? T[] : never;
// ToArray<string | number> = string[] | number[]

映射类型

// 所有属性可选且可空
type Nullable<T> = { [K in keyof T]: T[K] | null };

// 为键添加前缀
type Prefixed<T, P extends string> = {
    [K in keyof T as `${P}${Capitalize<string & K>}`]: T[K];
};

// 按值类型过滤键
type StringKeys<T> = {
    [K in keyof T as T[K] extends string ? K : never]: T[K];
};

tsconfig 快速参考

{
    "compilerOptions": {
        // 严格模式（始终启用）
        "strict": true,
        "noUncheckedIndexedAccess": true,

        // 模块系统
        "module": "ESNext",
        "moduleResolution": "bundler",

        // 输出
        "target": "ES2022",
        "outDir": "./dist",

        // 路径
        "baseUrl": ".",
        "paths": { "@/*": ["./src/*"] }
    }
}

附加资源

• ./references/generics-patterns.md - 高级类型编程、递归类型、模板字面量类型
• ./references/tsconfig-guide.md - 完整 tsconfig 选项指南
• ./references/zod-patterns.md - Zod 运行时验证模式