TypeScript 入門：型別是你的隊友
從 JS 工程師的角度理解型別思維

// JavaScript（無型別）
function getUser(id) {
  return fetch('/api/users/' + id).then(r => r.json());
}

const user = await getUser(1);
console.log(user.nmae);  // typo！但 JS 不報錯，執行時才發現是 undefined

// ─────────────────────────────────────────────
// TypeScript（有型別）
type User = {
  id: number;
  name: string;
  email: string;
};

async function getUser(id: number): Promise<User> {
  const res = await fetch('/api/users/' + id);
  return res.json();
}

const user = await getUser(1);
console.log(user.nmae);  // ❌ 編譯錯誤：Property 'nmae' does not exist on type 'User'
console.log(user.name);  // ✅ IDE 自動補全，100% 正確

// ── 基本型別 ──────────────────────────────────────
let name: string = 'Joseph';
let age: number = 26;
let isActive: boolean = true;
let data: null = null;
let value: undefined = undefined;

// ── 型別推斷：TypeScript 很聰明，通常不需要手動標注 ──
let count = 0;           // 推斷為 number
let title = 'Hello';     // 推斷為 string
// count = 'abc';        // ❌ 錯誤：不能把 string 指定給 number

// ── 陣列 ────────────────────────────────────────
const ids: number[] = [1, 2, 3];
const names: Array<string> = ['Alice', 'Bob'];

// ── 物件（inline 型別）──────────────────────────
const user: { id: number; name: string } = { id: 1, name: 'Joseph' };

// ── Union 型別（可以是多種型別之一）──────────────
let status: 'pending' | 'shipped' | 'delivered' = 'pending';
let id: string | number = 1;
id = 'abc';   // 也合法

// ── Literal 型別（精確的值）─────────────────────
type Direction = 'up' | 'down' | 'left' | 'right';
function move(dir: Direction) { /* ... */ }
move('up');      // ✅
// move('diagonal'); // ❌ 型別錯誤

// ── any 和 unknown（謹慎使用）──────────────────
let anything: any = 'hello';  // 關閉型別檢查，盡量避免
let safe: unknown = 42;       // 比 any 安全，使用前必須 type guard

// ── Interface：定義物件的形狀 ──────────────────────
interface User {
  id: number;
  name: string;
  email?: string;  // ? 代表可選屬性
  readonly createdAt: Date;  // readonly：只讀不可改
}

// Interface 可以繼承（extends）
interface Admin extends User {
  role: 'admin' | 'superadmin';
  permissions: string[];
}

// Interface 可以宣告合併（Declaration Merging）
// 同名 interface 會自動合併——擴充第三方 library 時很有用，但也是陷阱來源
interface User { phone?: string; }  // 合法！現在 User 多了 phone 欄位
// ⚠️ 陷阱：若你定義了和第三方庫同名的 interface（例如 Session），
// 你的合併會悄悄改變第三方型別的形狀，導致奇怪的型別錯誤：
// interface Session { userId: number; }  // 如果第三方庫已有 Session，這會合併！
// → 避免在全域 scope 定義與第三方庫同名的 interface

// ── Type Alias：更靈活的型別定義 ─────────────────
type Point = { x: number; y: number };

// Type 可以定義 Union、Intersection 等複雜型別（Interface 不行）
type ID = string | number;
type Response<T> = { data: T; error: string | null };

// Type 用 & 做交叉型別（類似繼承）
type AdminUser = User & { role: string };

// ── 實務建議 ─────────────────────────────────────
// ✅ 物件形狀（API 回應、Props）→ 用 Interface
// ✅ Union / Intersection / 別名 → 用 Type
// ✅ React 組件 Props → Interface（社群慣例）
// 兩者差異其實不大，保持一致風格比選哪個更重要

// ── 問題：沒有泛型，要為每種型別寫重複的函數 ────────
function firstItem_number(arr: number[]): number { return arr[0]; }
function firstItem_string(arr: string[]): string { return arr[0]; }
// 這樣很冗餘...

// ── 解法：泛型讓函數「型別參數化」─────────────────
function firstItem<T>(arr: T[]): T {
    return arr[0];
}
firstItem([1, 2, 3]);       // 推斷 T = number，回傳 number
firstItem(['a', 'b', 'c']); // 推斷 T = string，回傳 string

// ── 實際案例：API 回應的通用型別 ──────────────────
interface ApiResponse<T> {
    data: T;
    message: string;
    success: boolean;
}

// 使用時代入具體型別
type UserResponse = ApiResponse<User>;     // data 是 User
type ListResponse = ApiResponse<User[]>;   // data 是 User 陣列

async function fetchUser(id: number): Promise<ApiResponse<User>> {
    const res = await fetch('/api/users/' + id);
    return res.json();
}

// ── React Hooks 中的泛型 ──────────────────────────
const [users, setUsers] = useState<User[]>([]);   // 明確告訴 TS 是 User 陣列
const [error, setError] = useState<string | null>(null);

// ── 泛型約束（extends）────────────────────────────
// 限制 T 必須有 id 屬性
function findById<T extends { id: number }>(list: T[], id: number): T | undefined {
    return list.find(item => item.id === id);
}
findById(users, 1);    // ✅ User 有 id
// findById([1,2,3], 1); // ❌ number 沒有 id 屬性

// ── 1. 組件 Props 型別 ────────────────────────────
interface ButtonProps {
    label: string;
    onClick: () => void;
    variant?: 'primary' | 'secondary' | 'danger';
    disabled?: boolean;
    children?: React.ReactNode;  // 可以接受任何 JSX 內容
}

function Button({ label, onClick, variant = 'primary', disabled }: ButtonProps) {
    return (
        <button
            onClick={onClick}
            disabled={disabled}
            className={variant === 'primary' ? 'bg-blue-500' : 'bg-gray-500'}
        >
            {label}
        </button>
    );
}

// ── 2. useState 與 useRef ──────────────────────────
const [user, setUser] = useState<User | null>(null);
const inputRef = useRef<HTMLInputElement>(null);  // DOM 元素型別

// ── 3. Event 型別 ─────────────────────────────────
function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    console.log(e.target.value);
}

function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    // ...
}

// ── 4. 子組件傳遞 children ────────────────────────
interface CardProps {
    title: string;
    children: React.ReactNode;  // 最彈性的子組件型別
}

// ── 5. 非同步函數的回傳型別 ──────────────────────
async function loadData(): Promise<User[]> {
    const res = await fetch('/api/users');
    if (!res.ok) throw new Error('Failed to fetch');
    return res.json() as Promise<User[]>;  // as 做型別斷言
}

{
  "compilerOptions": {
    "strict": true,           // 開啟所有嚴格模式（強烈建議）
    // strict: true 等同於以下設定：
    // "noImplicitAny": true,         // 不允許隱式 any
    // "strictNullChecks": true,      // null 和 undefined 必須明確處理
    // "strictFunctionTypes": true,   // 函數型別嚴格檢查
    // "strictPropertyInitialization": true, // 類別屬性必須初始化

    "noUnusedLocals": true,    // 未使用的本地變數報錯
    "noUnusedParameters": true, // 未使用的函數參數報錯
    "noImplicitReturns": true,  // 函數所有路徑都必須有 return

    "target": "ES2020",
    "lib": ["ES2020", "DOM"],
    "moduleResolution": "bundler",
    "jsx": "preserve"
  }
}