1
2
3
4
5
6

type Direction = "up" | "down";   // 字符串字面量联合——最常用的建模手段 🔥
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Yes = true;

const a: Direction = "up";        // ✅
const b: Direction = "left";      // ❌ TS2322: '"left"' is not assignable to '"up" | "down"'

1
2
3
4
5
6
7
8
9

// as const 的典型用途：让配置对象保留精确字面量
const config = {
  host: "localhost",
  port: 8080,
  mode: "dev",
} as const;

type Mode = typeof config.mode;   // "dev"（而不是 string）
type Port = typeof config.port;   // 8080（而不是 number）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

type Greeting = `hello ${string}`;
const g1: Greeting = "hello world";   // ✅
const g2: Greeting = "goodbye";       // ❌ TS2322

// 组合内置字符串工具类型
type EventName = "click" | "focus";
type Handler = `on${Capitalize<EventName>}`;   // "onClick" | "onFocus"

// 解析字符串结构（配合 infer，见 05）
type ExtractRouteParam<T> = T extends `${string}:${infer P}` ? P : never;
type P = ExtractRouteParam<"/user/:id">;   // "id"

1
2
3
4
5

const KEY: unique symbol = Symbol("key");   // 必须 const + 直接初始化
type KEY = typeof KEY;                      // 类型是 typeof KEY，不是 symbol

const other: symbol = Symbol("key");
const bad: typeof KEY = other;   // ❌ TS2322: symbol 不能赋给 unique symbol

1
2
3
4
5
6
7
8

// 用 unique symbol 做「名义类型」标记
declare const brand: unique symbol;
type UserId = string & { readonly [brand]: "UserId" };
type OrderId = string & { readonly [brand]: "OrderId" };

declare const uid: UserId;
declare const oid: OrderId;
const x: OrderId = uid;   // ❌ TS2322: 两者结构不同，无法互赋 🔥

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

type Callback = () => void;

const returnsNumber = () => 42;
const cb: Callback = returnsNumber;   // ✅ 合法！

// 原因：调用方声明「我不关心返回值」，实现返回什么都无害
[1, 2, 3].forEach((n) => n * 2);      // ✅ 箭头函数返回了值，照样合法

// 但直接声明返回值时必须一致
function f(): void { return 42; }      // ❌ TS2322: Type 'number' is not assignable to type 'void'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

function f(u: unknown) {
  return u.toFixed();     // ❌ TS18046: 'u' is of type 'unknown'.
}

function g(u: unknown) {
  if (typeof u === "number") {
    return u.toFixed(2);  // ✅ 收窄之后才能用
  }
  return "not a number";
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 所有「外部来的」数据先声明成 unknown，再收窄
async function loadUser(id: string): Promise<User> {
  const raw: unknown = await (await fetch(`/api/users/${id}`)).json();
  if (!isUser(raw)) {                     // 自定义守卫，见 11
    throw new Error("响应格式不符合预期");
  }
  return raw;                             // ✅ 此时已收窄为 User
}

function isUser(v: unknown): v is User {
  return typeof v === "object" && v !== null
    && typeof (v as User).name === "string";
}

1
2
3
4
5

declare const nv: never;
const s: string = nv;      // ✅ never 可以赋给任何类型
const n: number = nv;      // ✅ 也可以

const bad: never = 1;      // ❌ TS2322: Type '1' is not assignable to type 'never'.

1
2
3
4
5
6
7
8
9

function fail(msg: string): never {
  throw new Error(msg);
}

// 对控制流分析有意义：TS 知道这行之后不可达
function pick(v: string | undefined): string {
  if (v === undefined) fail("缺少 v");
  return v;      // ✅ TS 知道 v 已不是 undefined，无需再判断
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };

function area(sh: Shape): number {
  switch (sh.kind) {
    case "circle": return Math.PI * sh.r ** 2;
    case "square": return sh.s ** 2;
    default:
      const _exhaustive: never = sh;   // ✅ 所有分支都覆盖了，sh 已收窄为 never
      return _exhaustive;
  }
}

1
2
3
4
5
6

type Shape = { kind: "circle"; r: number }
           | { kind: "square"; s: number }
           | { kind: "triangle"; b: number; h: number };   // 🆕 新增

// ❌ TS2322: Type '{ kind: "triangle"; ... }' is not assignable to type 'never'.
//    ← 编译器强迫你处理新情况，而不是运行时静默返回 undefined

1
2
3
4
5
6
7

const a: {} = "x";            // ✅ 字符串可以！{} 不是「空对象」
const b: object = "x";        // ❌ TS2322: Type 'string' is not assignable to type 'object'.
const c: object = null;       // ❌ TS2322: Type 'null' is not assignable to type 'object'.
const d: {} = null;           // ❌ TS2322: Type 'null' is not assignable to type '{}'.
const e: object = { x: 1 };   // ✅
const f: object = () => {};   // ✅ 函数也是 object
const g: object = [1, 2];     // ✅ 数组也是 object

1
2
3

never  ⊂  所有类型（never 可赋给一切）
一切   ⊂  unknown（一切可赋给 unknown）
any    ↔  一切（双向自由通行，但不安全）

1
2
3

type Named = { name: string };
type Aged = { age: number };
type Person = Named & Aged;   // { name: string; age: number }

1
2
3
4
5
6

type A = { v: string };
type B = { v: number };
type C = A & B;               // 类型上合法，但 v 变成 string & number = never
declare const c: C;
c.v;                          // 类型是 never —— 这个值不可能存在
const bad: C = { v: "x" };    // ❌ TS2322

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// 品牌类型：让「字符串」变成不可混淆的「用户 ID」
declare const brand: unique symbol;
type Brand<T, B> = T & { readonly [brand]: B };

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

function toUserId(s: string): UserId { return s as UserId; }

declare const uid: UserId;
declare const oid: OrderId;
const x: OrderId = uid;   // ❌ TS2322: 结构不同，无法互赋 🔥

1
2
3
4
5

type Opt = { a?: number };   // a 可以「不存在」，或为 number

const x: Opt = {};           // ✅
const y: Opt = { a: 1 };     // ✅
const z: Opt = { a: undefined };   // 默认允许；开启 exactOptionalPropertyTypes 后 ❌

1
2
3
4

type R = { readonly a: { b: number } };
declare const r: R;
r.a = { b: 2 };      // ❌ TS2540: Cannot assign to 'a' because it is a read-only property.
r.a.b = 2;           // ✅ 合法！readonly 只保护第一层

1
2
3
4
5

let mutable: string[] = ["a"];
let ro: readonly string[] = mutable;   // ✅ 可变 -> 只读，允许
let back: string[] = ro;               // ❌ TS4104: The type 'readonly string[]' is
                                       //    'readonly' and cannot be assigned to the mutable type 'string[]'.
ro.push("b");                          // ❌ TS2339: Property 'push' does not exist on type 'readonly string[]'.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// 逆变：参数类型必须更宽
declare const wide: (x: string | number) => void;
declare const narrow: (x: string) => void;

const a: typeof wide = narrow;   // ❌ TS2322: 参数 'x' 类型不兼容
const b: typeof narrow = wide;   // ✅ 更宽可以赋给更窄

// 方法双变：同样的形状，写成方法就放行了 ⚠️
type FnProp   = { f: (x: string | number) => void };
type FnMethod = { f(x: string | number): void };

const p: FnProp = { f: narrow };     // ❌ TS2322
declare const narM: { f(x: string): void };
const m: FnMethod = narM;            // ✅ 方法双变，放行

1
2
3
4
5
6
7

type Status = "idle" | "loading" | "done" | "error";
type FinalStatus = Exclude<Status, "idle" | "loading">;   // "done" | "error"
type ErrStatus   = Extract<Status, "error">;              // "error"

// 可辨识联合的实用模式：按 kind 取出某个成员
type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };
type Circle = Extract<Shape, { kind: "circle" }>;         // { kind: "circle"; r: number } 🔥

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

declare function createUser(name: string, age: number): User;

type Args = Parameters<typeof createUser>;   // [name: string, age: number]
type Ret  = ReturnType<typeof createUser>;   // User

class Service { constructor(private url: string) {} }
type SvcArgs = ConstructorParameters<typeof Service>;   // [url: string]
type Svc     = InstanceType<typeof Service>;            // Service

// 从任意函数提取类型——避免重复定义
async function fetchUser() { return { id: 1, name: "a" }; }
type FetchedUser = Awaited<ReturnType<typeof fetchUser>>;   // { id: number; name: string } 🔥

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 最常用：从事件名生成 handler 名
type Event = "click" | "focus";
type HandlerName = `on${Capitalize<Event>}`;   // "onClick" | "onFocus"

// 生成 getter 类型（键重映射）
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};
type PersonGetters = Getters<{ name: string; age: number }>;
// { getName: () => string; getAge: () => number }

1
2
3
4
5
6
7
8

// NoInfer：让第二个参数不参与 T 的推断
function createFSM<T extends string>(
  states: T[],
  initial: NoInfer<T>,      // 不参与推断，只能从 states 推
) { return { states, initial }; }

createFSM(["idle", "done"], "idle");   // ✅ T = "idle" | "done"
createFSM(["idle", "done"], "typo");   // ❌ TS2345: '"typo"' is not assignable to '"idle" | "done"'