TypeScript 详解：JavaScript 的超集与现代前端开发的类型基石

// JS：运行时才发现类型错误
function add(a, b) {
  return a + b;
}
add(1, '2'); // "12" — 行为不符合预期，但代码"正常运行"
add(null, undefined); // NaN — 悄无声息地失败

// TS：编译时就发现错误
function add(a: number, b: number): number {
  return a + b;
}
add(1, '2'); // ❌ 编译错误：Argument of type 'string' is not assignable to parameter of type 'number'

let name: string = 'Alice';
let age: number = 25;
let isActive: boolean = true;
let data: any = 'anything';      // 尽量避免使用 any
let unknownData: unknown = 'safe any'; // 比 any 安全，使用前需类型收窄
let nothing: void;                // 函数无返回值
let neverValue: never;            // 永不会发生的类型（如抛出错误的函数）
let nullable: string | null = null; // 联合类型

// Interface：可扩展，适合对象形状定义
interface User {
  id: number;
  name: string;
  email?: string;       // 可选属性
  readonly createdAt: Date; // 只读
}

interface Admin extends User {
  permissions: string[];
}

// Type：更灵活，支持联合类型、交叉类型
type ID = string | number;
type AdminUser = User & { permissions: string[] };
type Status = 'pending' | 'active' | 'deleted'; // 字面量联合

// 泛型函数
function identity<T>(arg: T): T {
  return arg;
}
identity<string>('hello');  // 显式指定
identity(42);               // 类型推断：T = number

// 泛型接口
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

// 使用
const userResponse: ApiResponse<User> = {
  data: { id: 1, name: 'Alice' },
  status: 200,
  message: 'OK',
};

let count = 0;              // TS 推断为 number
let user = { name: 'Alice' }; // 推断为 { name: string }

// 函数返回值推断
function getUser() {
  return { id: 1, name: 'Alice' };
}
// 返回值自动推断为 { id: number; name: string }

{
  "compilerOptions": {
    "target": "ES2022",           // 编译目标 JS 版本
    "module": "ESNext",           // 模块系统
    "moduleResolution": "bundler", // 模块解析策略
    "strict": true,               // 启用所有严格类型检查（强烈推荐）
    "esModuleInterop": true,      // 兼容 CommonJS/ESM 混用
    "skipLibCheck": true,         // 跳过 node_modules 类型检查
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",           // 编译输出目录
    "rootDir": "./src",           // 源码根目录
    "resolveJsonModule": true,    // 允许 import JSON
    "declaration": true,          // 生成 .d.ts 类型声明文件
    "noImplicitAny": true,        // 禁止隐式 any
    "strictNullChecks": true,     // 严格 null/undefined 检查
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// Decorators（装饰器，Nest.js/Angular 核心语法）
function Controller(prefix: string) {
  return function (target: any) {
    target.prefix = prefix;
  };
}

@Controller('/users')
class UserController {}

// satisfies 操作符（保持类型推断的同时检查兼容性）
const config = {
  host: 'localhost',
  port: 3000,
} satisfies { host: string; port: number };

// const 类型参数（自动推断为字面量类型）
function createArray<const T>(items: readonly T[]): T[] {
  return [...items];
}
const arr = createArray([1, 2, 3] as const); // T = 1 | 2 | 3