lazygophers/typescript-types

TypeScript 类型系统规范

本 skill 同时覆盖 JavaScript 项目；JS 项目用 JSDoc + tsc --checkJs 获得 80% 类型保护，见末尾兜底章节。

类型系统两大用途：建模业务状态 (discriminated unions / branded types) + 验证外部输入 (Zod / Valibot)。

类型命名

type UserDTO = { id: string; name: string };           // PascalCase
type ApiResponse<T> = { data: T; status: number };
type Status = "active" | "inactive" | "pending";

// 禁止 I 前缀
// type IUser = {};

Discriminated Unions (状态机首选)

type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

function render<T>(state: AsyncState<T>): string {
  switch (state.status) {
    case "idle":    return "Waiting...";
    case "loading": return "Loading...";
    case "success": return `Got: ${JSON.stringify(state.data)}`;
    case "error":   return `Error: ${state.error.message}`;
    default: {
      const _exhaustive: never = state; // 穷举检查
      return _exhaustive;
    }
  }
}

Const Type Parameters (TS 5.0+)

function createConfig<const T extends Record<string, unknown>>(c: T): T {
  return c;
}
const cfg = createConfig({ api: "/v1", timeout: 3000 });
// typeof cfg = { readonly api: "/v1"; readonly timeout: 3000 }

模板字面量类型

type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE";
type APIRoute = `/api/${string}`;
type Endpoint = `${HTTPMethod} ${APIRoute}`;
type EventName = `on${Capitalize<string>}`;

类型守卫 (TS 5.5 inferred predicates)

// TS 5.5+: 推断类型谓词
function isNonNullable<T>(v: T): v is NonNullable<T> {
  return v !== null && v !== undefined;
}
const users: (User | null)[] = [u1, null, u2];
const valid = users.filter(isNonNullable); // User[]

// 显式自定义类型守卫
function isUser(v: unknown): v is User {
  return typeof v === "object" && v !== null
    && "id" in v && typeof (v as { id: unknown }).id === "string";
}

Zod 4 运行时验证 (推荐)

import { z } from "zod";

const UserSchema = z.object({
  id: z.uuid(),                          // Zod 4: 顶层 helper
  name: z.string().min(1).max(100),
  email: z.email(),
  role: z.enum(["admin", "user", "guest"]),
  metadata: z.record(z.string(), z.unknown()).optional(),
});

type User = z.infer<typeof UserSchema>;  // schema-first 类型

const r = UserSchema.safeParse(data);
if (!r.success) console.error(z.treeifyError(r.error));

// 派生 schema
const CreateUserSchema = UserSchema.omit({ id: true }).extend({
  password: z.string().min(8).regex(/[A-Z]/).regex(/[0-9]/),
});

替代选择：Valibot (更小 bundle，函数式 API，<2KB)，用于体积敏感场景。

Branded Types (编译期区分语义)

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

function getUser(id: UserId): Promise<User> { /* ... */ }
// getUser("123" as UserId); // OK
// getUser("123" as PostId); // Error

satisfies (TS 4.9+，保留字面量)

const routes = {
  home: "/",
  about: "/about",
  user: "/user/:id",
} satisfies Record<string, string>;
// typeof routes.home = "/" (非 string)

工具类型常用

// 内置：Partial / Required / Pick / Omit / Record / Readonly / Awaited / ReturnType / Parameters

// type-fest 推荐补充：SetOptional, SetRequired, Merge, CamelCase, etc.

type ExtractPromise<T> = T extends Promise<infer U> ? U : T;
type DeepReadonly<T> = { readonly [K in keyof T]: DeepReadonly<T[K]> };

JS-only 兜底：JSDoc + checkJs

JS 项目无需切 TS 也能获得 80% 类型保护：

// jsconfig.json
{
  "compilerOptions": {
    "target": "ES2025",
    "module": "NodeNext",
    "allowJs": true,
    "checkJs": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["src/**/*"]
}

// JSDoc 类型定义
/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} name
 * @property {'admin' | 'user' | 'guest'} role
 */

/** @typedef {{ status: 'idle' } | { status: 'loading' } | { status: 'success'; data: User } | { status: 'error'; error: Error }} AsyncState */

/**
 * @param {string} id
 * @returns {Promise<User>}
 */
export async function getUser(id) {
  const r = await fetch(`/api/users/${id}`);
  return /** @type {User} */ (await r.json());
}

// Zod 在 JS 同样可用，z.infer 通过 JSDoc 桥接
import { z } from 'zod';
const UserSchema = z.object({ id: z.uuid(), name: z.string() });
/** @typedef {z.infer<typeof UserSchema>} User */

pnpm tsc --noEmit          # 当 linter 跑

渐进迁移：JSDoc → 文件级 .ts → 局部启 strict → 全量 strict。

Red Flags

| 现象 | 问题 | 严重 | |------|------|------| | any | 用 unknown + 守卫 | 高 | | 未穷举的 switch | DU 遗漏分支 | 高 | | as 强转 | 可能隐藏错误 (仅边界用) | 中 | | 外部数据无 Zod | 运行时类型不安全 | 高 | | 递归类型 > 5 层 | 编译性能 | 中 | | I 前缀 | C# 约定 | 低 | | enum | tree-shake 不友好 | 中 | | JS 项目无 checkJs | 失去类型保护 | 中 |

检查清单

• [ ] 无 any，外部数据 Zod / Valibot 验证
• [ ] discriminated unions 有 never 穷举
• [ ] import type 分离类型 (TS)
• [ ] 泛型有 extends 约束
• [ ] 复杂常量用 satisfies
• [ ] 语义相同 string/number 用 branded type
• [ ] 类型 PascalCase，无 I 前缀
• [ ] JS 项目：jsconfig + checkJs: true + JSDoc