// 三个月后你接手这段代码
function calc(a, b) {
  return a + b; // a、b 是什么？数字？字符串？对象？
}

calc('1', 2); // '12'，不报错，但结果不是你要的
calc({}, []); // '[object Object]'，同样不报错

function calc(a: number, b: number): number {
  return a + b;
}

calc('1', 2); // ❌ 编译报错：Argument of type 'string' is not assignable to 'number'

04 TypeScript
  ├─ 前置：03 JavaScript（必须熟练）
  ├─ 紧接着：06 框架（组件 props 类型）、09 工程化（编译与产物）
  ├─ 交叉：13 测试（类型测试）、07 状态（数据契约）
  └─ 长期：17 架构（公共 API 设计）

let name: string = '张三';
let age: number = 20;
let isActive: boolean = true;
let tags: string[] = ['a', 'b'];
let tuple: [string, number] = ['张三', 20]; // 元组：位置和类型都固定
let nothing: null = null;
let missing: undefined = undefined;

let a: any = getData();
a.foo.bar;          // ✅ 不报错，但运行时可能崩
a();                // ✅ 不报错，但可能不是函数

let u: unknown = getData();
u.foo;              // ❌ 报错：Object is of type 'unknown'
u();                // ❌ 报错
if (typeof u === 'string') {
  u.toUpperCase();  // ✅ 收窄后才能用
}

// 推荐写法：把 unknown 收窄成具体类型
function isUser(value: unknown): value is { id: string; name: string } {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'name' in value
  );
}

// interface：描述对象形状，可声明合并、错误信息更友好
interface User {
  id: string;
  name: string;
  age?: number;        // 可选
  readonly createdAt: Date; // 只读
}

// type：描述联合、交叉、条件、映射等「类型运算」
type Status = 'idle' | 'loading' | 'success' | 'error';
type UserWithRole = User & { role: 'admin' | 'user' };

type A = { a: string };
type B = { b: number };

type AB = A & B;        // 交叉：同时具备
const ab: AB = { a: 'x', b: 1 };

type Size = 'sm' | 'md' | 'lg';  // 字面量联合：把「有限取值」表达成类型
function button(size: Size) {}

button('xl'); // ❌ 报错，拼写错误当场发现

function format(value: string | number | Date): string {
  if (typeof value === 'string') {
    return value.trim();          // 这里 value: string
  }
  if (typeof value === 'number') {
    return value.toFixed(2);      // 这里 value: number
  }
  return value.toISOString();     // 剩下只能是 Date
}

type Result =
  | { status: 'success'; data: User }
  | { status: 'error'; message: string }
  | { status: 'loading' };

function render(result: Result) {
  switch (result.status) {
    case 'success':
      return result.data.name;   // ✅ 编译器知道有 data
    case 'error':
      return result.message;     // ✅ 编译器知道有 message
    case 'loading':
      return '加载中';
  }
}

const el = document.getElementById('app') as HTMLDivElement;
el.innerHTML = 'ok'; // 如果元素实际是 null 或别的标签，运行时报错

const config = { mode: 'dark', retries: 3 } as const;
// 类型：{ readonly mode: "dark"; readonly retries: 3 }

type Config = typeof config;              // 从值反推类型
type Mode = Config['mode'];               // 'dark'

{
  "compilerOptions": {
    "target": "ES2022",          // 编译输出的语法版本
    "module": "ESNext",          // 模块格式
    "moduleResolution": "bundler", // 模块解析策略（Vite/webpack 项目常用）
    "strict": true,              // 打开全部严格检查（强烈建议）
    "noUncheckedIndexedAccess": true, // 数组下标访问结果可能是 undefined
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true,        // 跳过 node_modules 的 d.ts 检查（提速）
    "paths": { "@/*": ["./src/*"] } // 路径别名（需构建工具同步配置）
  }
}

.ts → [tsc / esbuild / swc] → .js（类型被擦除，无运行时开销）

function firstString(arr: string[]): string | undefined { return arr[0]; }
function firstNumber(arr: number[]): number | undefined { return arr[0]; }

/**
 * 取数组第一个元素。
 * @param arr 输入数组
 * @returns 第一个元素，空数组时为 undefined
 */
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

first([1, 2]);          // number | undefined
first(['a']);           // string | undefined

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

longest('abc', 'de');   // ✅ string 有 length
longest(1, 2);          // ❌ number 没有 length

interface ApiResponse<T = unknown> {
  code: number;
  data: T;
  message: string;
}

const res: ApiResponse = { code: 0, data: null, message: 'ok' };

type IsString<T> = T extends string ? true : false;

type A = IsString<'hello'>;  // true
type B = IsString<42>;       // false

type ToArray<T> = T extends unknown ? T[] : never;

type R1 = ToArray<string | number>;
// string[] | number[]  ← 分发后合并

// 阻止分发：用元组包裹
type ToArrayNoDistribute<T> = [T] extends [unknown] ? T[] : never;
type R2 = ToArrayNoDistribute<string | number>;
// (string | number)[]

type Exclude<T, U> = T extends U ? never : T;

type T1 = Exclude<'a' | 'b' | 'c', 'a'>; // 'b' | 'c'
// 'a' → never，'b' → 'b'，'c' → 'c'，合并后 'b' | 'c'

// 提取函数返回值
type MyReturnType<T> = T extends (...args: never[]) => infer R ? R : never;

type R = MyReturnType<() => string>; // string

// 提取数组元素类型
type ElementOf<T> = T extends (infer E)[] ? E : never;
type E = ElementOf<number[]>; // number

// 提取 Promise 结果（内置 Awaited 的简化版）
type Unwrap<T> = T extends Promise<infer U> ? Unwrap<U> : T;
type U = Unwrap<Promise<Promise<string>>>; // string

// 提取函数第一个参数
type FirstArg<T> = T extends (first: infer F, ...rest: never[]) => unknown ? F : never;

type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

// 修饰符操作：+? / -? / +readonly / -readonly
type Required<T> = { [K in keyof T]-?: T[K] };
type Mutable<T> = { -readonly [K in keyof T]: T[K] };

// 把所有字段变成 getXxx 方法类型
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type User = { name: string; age: number };
type UserGetters = Getters<User>;
// { getName: () => string; getAge: () => number }

type MyPick<T, K extends keyof T> = { [P in K]: T[P] };
type MyOmit<T, K extends keyof any> = MyPick<T, Exclude<keyof T, K>>;
type MyRecord<K extends keyof any, V> = { [P in K]: V };
type MyNonNullable<T> = T extends null | undefined ? never : T;
type MyParameters<T> = T extends (...args: infer P) => unknown ? P : never;
type MyConstructorParams<T> = T extends abstract new (...args: infer P) => unknown ? P : never;

interface User {
  id: string;
  name: string;
  password: string;
  createdAt: Date;
}

// 对外返回时去掉敏感字段
type PublicUser = Omit<User, 'password'>;

// 创建时不需要 id 与时间
type CreateUserInput = Omit<User, 'id' | 'createdAt'>;

// 更新时全部可选
type UpdateUserInput = Partial<Pick<User, 'name' | 'password'>>;

// 表单草稿：字段可为空
type Draft<T> = { [K in keyof T]?: T[K] | null };

type EventName = 'click' | 'focus' | 'blur';
type Handler = `on${Capitalize<EventName>}`;
// 'onClick' | 'onFocus' | 'onBlur'

const handlers: Record<Handler, () => void> = {
  onClick: () => {},
  onFocus: () => {},
  onBlur: () => {},
};

type Path<T, Prefix extends string = ''> = {
  [K in keyof T & string]: T[K] extends object
    ? Path<T[K], `${Prefix}${K}.`>
    : `${Prefix}${K}`;
}[keyof T & string];

interface Messages {
  common: { ok: string; cancel: string };
  user: { name: string };
}

type MessageKey = Path<Messages>;
// 'common.ok' | 'common.cancel' | 'user.name'

const routes = {
  home: '/',
  user: '/user/:id',
} satisfies Record<string, `/${string}`>;

routes.home; // 类型是 '/'，不是 string ← 保留了字面量

const a: Record<string, string> = { home: '/' };  // 类型被放宽为 string
const b = { home: '/' } as const;                 // 收窄但没有结构校验
const c = { home: '/' } satisfies Record<string, string>; // 既校验又保留字面量

// 1. 给第三方库补类型（types/lodash.d.ts）
declare module 'legacy-lib' {
  export function run(cmd: string): void;
}

// 2. 声明全局变量（如 CDN 注入的 SDK）
declare global {
  interface Window {
    __APP_CONFIG__: { env: string; apiBase: string };
  }
}

// 3. 声明非代码资源
declare module '*.svg' {
  const content: string;
  export default content;
}

import type { User } from './types';

// noUncheckedIndexedAccess
const arr: string[] = [];
arr[0].toUpperCase(); // ❌ 报错：可能为 undefined
const first = arr[0];
if (first) first.toUpperCase(); // ✅ 必须检查

// exactOptionalPropertyTypes
interface Config {
  timeout?: number;
}
const c: Config = { timeout: undefined }; // ❌ 报错（要区分「没有」与「显式 undefined」）

interface Animal { name: string }
interface Dog extends Animal { bark(): void }

let animal: Animal = { name: 'a' };
let dog: Dog = { name: 'd', bark() {} };

animal = dog;  // ✅ 协变：Dog 可以赋给 Animal（更具体→更宽泛）
dog = animal;  // ❌ 报错：Animal 缺少 bark

type Handler<T> = (value: T) => void;

let animalHandler: Handler<Animal> = () => {};
let dogHandler: Handler<Dog> = () => {};

animalHandler = dogHandler; // ❌ 不安全：(v: Dog) 无法处理任意 Animal
dogHandler = animalHandler; // ✅ 安全：(v: Animal) 能处理 Dog

interface Producer<out T> { get(): T }        // 只产出 → 协变
interface Consumer<in T> { set(v: T): void }  // 只消费 → 逆变
interface Both<in out T> { get(): T; set(v: T): void }

# 查看类型检查耗时
npx tsc --noEmit --extendedDiagnostics

# 生成性能跟踪
npx tsc --noEmit --generateTrace ./trace
# 用 chrome://tracing 打开 trace/trace.json

// 1. 用接口代替大型交叉类型（交叉类型每次都要重新计算）
type Bad = A & B & C & D;
interface Good extends A, B, C, D {}

// 2. 缓存中间结果（用类型别名固定）
type Normalized = { ... };
type Step1 = DoSomething<Normalized>;  // 复用 Step1，避免重复实例化

// 3. 避免在热路径类型里做递归
// 4. 用 as const 与 satisfies 替代复杂推断

// 给 axios 的 config 增加自定义字段
declare module 'axios' {
  export interface AxiosRequestConfig {
    /** 是否静默上报错误 */
    silent?: boolean;
  }
}

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string().min(1),
  age: z.number().int().nonnegative().optional(),
});

type User = z.infer<typeof UserSchema>;  // 类型自动推导，不用手写

// 运行时校验（接口响应、表单、localStorage 读取）
const result = UserSchema.safeParse(raw);
if (!result.success) {
  console.error(result.error.issues);
  return;
}
const user: User = result.data;

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

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

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

declare function getUser(id: UserId): void;
declare function getOrder(id: OrderId): void;

const uid = toUserId('u1');
getUser(uid);   // ✅
getOrder(uid);  // ❌ 报错：UserId 不能赋给 OrderId

// expect-type
import { expectTypeOf } from 'expect-type';

expectTypeOf<ReturnType<typeof first>>().toEqualTypeOf<string | undefined>();

// tsd
import { expectType } from 'tsd';
expectType<string>(padLeft('x', 3));

// 负向测试：断言这里必须报错
// @ts-expect-error —— 传 number 应报错
first(123);

// 1. 输入宽容，输出精确
function request<T>(url: string, options?: RequestOptions): Promise<T>;

// 2. 重载从具体到宽泛
function create(value: string): StringBox;
function create(value: number): NumberBox;
function create(value: unknown): Box;

// 3. 不要暴露内部泛型
// ❌ 调用方被迫写三个泛型
function query<T, K extends keyof T, R>(t: T, k: K, f: (v: T[K]) => R): R;
// ✅ 通过推断隐藏
function query<T, R>(t: T, f: (v: T[keyof T]) => R): R;

// 4. 错误信息要人类可读
type RequireName<T> = T extends { name: string }
  ? T
  : { error: '必须提供 name 字段'; received: T };

// package.json
{
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",   // types 条件必须放最前
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

Program（整个项目的文件图）
  └─ TypeChecker（类型查询、推断、关系判断）
  └─ SourceFile（AST）→ Transformer（转换）

import ts from 'typescript';

/**
 * 创建一个转换器：把 console.log(...) 替换为 logger.info(...)。
 * @param context 转换上下文
 * @returns 转换函数
 */
function createLoggerTransformer(context: ts.TransformationContext) {
  return (sourceFile: ts.SourceFile) => {
    const visit = (node: ts.Node): ts.Node => {
      if (
        ts.isCallExpression(node) &&
        ts.isPropertyAccessExpression(node.expression) &&
        ts.isIdentifier(node.expression.expression) &&
        node.expression.expression.text === 'console' &&
        node.expression.name.text === 'log'
      ) {
        return ts.factory.updateCallExpression(
          node,
          ts.factory.createPropertyAccessExpression(
            ts.factory.createIdentifier('logger'),
            'info'
          ),
          node.typeArguments,
          node.arguments
        );
      }
      return ts.visitEachChild(node, visit, context);
    };
    return ts.visitNode(sourceFile, visit) as ts.SourceFile;
  };
}

// 根 tsconfig
{
  "references": [{ "path": "./packages/ui" }, { "path": "./packages/utils" }]
}

开发：tsserver（编辑器内即时反馈）
构建：esbuild/swc（快，只擦除类型）
CI：tsc --noEmit（唯一的类型真相来源）

interface OrderItem {
  skuId: string;
  name: string;
  price: number;      // 单位：分，避免浮点误差
  quantity: number;
}

interface Order {
  id: string;
  status: 'pending' | 'paid' | 'shipped' | 'closed';
  items: OrderItem[];
  totalAmount: number;
  createdAt: string;  // ISO 8601 字符串（跨端传输标准）
}

interface Page<T> {
  list: T[];
  page: number;
  pageSize: number;
  total: number;
}

// DTO：与后端字段完全一致（snake_case 也照抄，不要美化）
interface OrderDTO {
  id: string;
  status: string;
  order_items: Array<{ sku_id: string; price: number; qty: number }>;
  total_amount: number;
  created_at: string;
}

// 转换层：DTO → 领域模型（做校验、默认值、字段映射）
function toOrder(dto: OrderDTO): Order {
  return {
    id: dto.id,
    status: parseStatus(dto.status),
    items: dto.order_items.map((it) => ({
      skuId: it.sku_id,
      name: '',            // 名称可能由另一个接口补齐
      price: it.price,
      quantity: it.qty,
    })),
    totalAmount: dto.total_amount,
    createdAt: dto.created_at,
  };
}

const OrderDTOSchema = z.object({
  id: z.string(),
  status: z.enum(['pending', 'paid', 'shipped', 'closed']),
  order_items: z.array(
    z.object({
      sku_id: z.string(),
      price: z.number().int().nonnegative(),
      qty: z.number().int().positive(),
    })
  ),
  total_amount: z.number().int().nonnegative(),
  created_at: z.string().datetime(),
});

type OrderDTO = z.infer<typeof OrderDTOSchema>;

type ApiResult<T> =
  | { ok: true; data: T }
  | { ok: false; code: string; message: string };

/**
 * 拉取订单列表，带运行时校验。
 * @param params 查询参数
 * @returns 统一结果对象，永不抛异常
 */
async function fetchOrders(params: {
  status?: Order['status'];
  page: number;
  pageSize?: number;
}): Promise<ApiResult<Page<Order>>> {
  try {
    const res = await fetch(`/api/orders?${new URLSearchParams(params as Record<string, string>)}`);
    if (!res.ok) return { ok: false, code: `HTTP_${res.status}`, message: '请求失败' };

    const json: unknown = await res.json();
    const parsed = PageSchema(OrderDTOSchema).safeParse(json);
    if (!parsed.success) {
      return { ok: false, code: 'SCHEMA_MISMATCH', message: '数据格式异常' };
    }

    return {
      ok: true,
      data: {
        ...parsed.data,
        list: parsed.data.list.map(toOrder),
      },
    };
  } catch (err) {
    return { ok: false, code: 'NETWORK_ERROR', message: (err as Error).message };
  }
}

/**
 * 递归只读：数组转为只读数组，函数原样保留，其余对象逐层只读。
 * @example
 * type R = DeepReadonly<{ a: { b: number }[] }>;
 * // { readonly a: readonly { readonly b: number }[] }
 */
type DeepReadonly<T> = T extends (...args: any[]) => any
  ? T
  : T extends readonly (infer U)[]
    ? ReadonlyArray<DeepReadonly<U>>
    : T extends Map<infer K, infer V>
      ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
      : T extends Set<infer U>
        ? ReadonlySet<DeepReadonly<U>>
        : T extends object
          ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
          : T;

/** 事件表：事件名 → 参数元组 */
interface Events {
  'order:created': [id: string, amount: number];
  'order:closed': [id: string];
  'cart:changed': [];
}

/**
 * 事件总线：on / emit 的参数由事件表约束。
 */
class Emitter<E extends Record<string, unknown[]>> {
  private handlers: { [K in keyof E]?: Array<(...args: E[K]) => void> } = {};

  /** 订阅事件，返回取消函数 */
  on<K extends keyof E>(type: K, fn: (...args: E[K]) => void): () => void {
    (this.handlers[type] ??= []).push(fn);
    return () => {
      const list = this.handlers[type];
      if (list) this.handlers[type] = list.filter((h) => h !== fn) as typeof list;
    };
  }

  /** 触发事件，参数个数与类型由事件表校验 */
  emit<K extends keyof E>(type: K, ...args: E[K]): void {
    this.handlers[type]?.forEach((fn) => fn(...args));
  }
}