📘 Total TypeScript Essentials

type State = {
  status: 'loading' | 'success' | 'error'
  error?: string
  data?: string
}

type State =
  | { status: 'loading' }
  | { status: 'error'; error: string }
  | { status: 'success'; data: string }

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.side ** 2;
    default: {
      // ★ 加了新的 kind 卻忘了處理 → s 不再是 never → 這一行編譯錯誤
      const _exhaustive: never = s;
      throw new Error(`unhandled shape: ${JSON.stringify(_exhaustive)}`);
    }
  }
}

export function assertNever(x: never): never {
  throw new Error(`unexpected: ${JSON.stringify(x)}`);
}
// default: return assertNever(s);

// ❌ 用可選欄位：四種欄位組合，但只有三種是合法的
type Request = {
  status: "loading" | "success" | "error";
  data?: Data;       // ★ status 是 success 時才該有
  error?: Error;     // ★ status 是 error 時才該有
};
// → 每次用 data 都要 `if (req.data)`，而且 {status:"success"} 沒有 data 也編得過
 
// ✅ 判別聯集：不合法的組合根本不存在
type Request =
  | { status: "loading" }
  | { status: "success"; data: Data }      // ★ 保證有 data
  | { status: "error"; error: Error };     // ★ 保證有 error
 
if (req.status === "success") {
  render(req.data);          // ★ 不用檢查，型別已經保證了
}

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };
 
const r = await fetchUser(id);
if (!r.ok) return handle(r.error);
use(r.value);                     // ★ 這裡 value 保證存在

const config: Record<string, Color> = {
  foreground: { r: 255, g: 255, b: 255 },
  border: "transparent",
};
 
config.foreground.r;  // ❌ 錯：TS 只知道值是 Color，不知道 foreground 存在

const config = {
  foreground: { r: 255, g: 255, b: 255 },
  border: "transparent",
} satisfies Record<string, Color>;
 
config.foreground.r;          // ✅
config.border.toUpperCase();  // ✅ TS 知道這支是 string
config.primary = 123;         // ✅ 仍然會被擋下來

const album = { format: "Vinyl" } satisfies Album;
// album.format 推論為 "Vinyl"，不是 "CD" | "Vinyl" | "Digital"

type Config = Record<string, { url: string; retries: number }>;
 
// ① 標註（annotation）—— 檢查了，但★ 具體資訊被吃掉
const a: Config = { prod: { url: "...", retries: 3 } };
a.prod;          // ★ 可以，但 a.typo 也「可以」（因為型別是 Record<string, ...>）
 
// ② as（斷言）—— ★ 不檢查，只是叫編譯器閉嘴
const b = { prod: { url: "...", retries: "3" } } as Config;   // ★ retries 是字串也不報錯！
 
// ③ satisfies —— ★ 檢查形狀，同時保留具體推論
const c = { prod: { url: "...", retries: 3 } } satisfies Config;
c.prod;          // ✅
c.typo;          // ★ 編譯錯誤：Property 'typo' does not exist

const routes = {
  home:    { path: "/",        auth: false },
  profile: { path: "/me",      auth: true  },
  admin:   { path: "/admin",   auth: true  },
} satisfies Record<string, { path: string; auth: boolean }>;
 
type RouteName = keyof typeof routes;        // ★ "home" | "profile" | "admin"
 
function go(name: RouteName) { ... }
go("home");     // ✅
go("hom");      // ★ 編譯錯誤

const defaults = { timeout: 30_000, retries: 3 } satisfies Partial<Options>;
const opts = { ...defaults, ...userOpts };   // ★ 見 [[建造者模式]]

const handlers = {
  create: (p: CreatePayload) => { ... },
  update: (p: UpdatePayload) => { ... },
} satisfies Record<string, (p: any) => void>;
 
type Action = keyof typeof handlers;         // ★ 自動推導

const theme = {
  primary: "#0af",
  danger:  "#f33",
} satisfies Record<string, `#${string}`>;    // ★ 檢查是合法的 hex 形狀
 
theme.primary;                                // ★ 型別是 "#0af"（字面量），不是 string

// 1. 標註變數：可以重新指派，但限制在聯集內
let genre: AlbumGenre = "rock";
 
// 2. 標註物件：整體受約束（但會抹掉精確推論）
const attrs: AlbumAttributes = { status: "on-sale" };
 
// 3. as const：整個結構凍成唯讀的字面量
const attrs = { status: "on-sale" } as const;

const albumTypes = {
  CD: "cd",
  VINYL: "vinyl",
  DIGITAL: "digital",
} as const;
 
type AlbumType = (typeof albumTypes)[keyof typeof albumTypes];
// "cd" | "vinyl" | "digital"

let   a = "hello";                 // string          ★ let → 拓寬
const b = "hello";                 // "hello"         ★ const → 字面量
 
const o = { k: "v" };              // { k: string }   ★ 物件屬性「仍然」被拓寬
const o2 = { k: "v" } as const;    // { readonly k: "v" }
 
const arr = [1, 2];                // number[]        ★ 陣列被拓寬
const t = [1, 2] as const;         // readonly [1, 2] ★ 變成元組（tuple）

const action = { type: "increment", by: 1 };
dispatch(action);        // ★ 錯誤：type 是 string，不符合 Action 聯集
 
const action = { type: "increment", by: 1 } as const;
dispatch(action);        // ✅

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = typeof ROLES[number];       // ★ "admin" | "editor" | "viewer"
 
function can(r: Role) { ... }
can("admin");   // ✅
can("admn");    // ★ 編譯錯誤
 
// 執行期也能用同一份資料
if (ROLES.includes(input as Role)) { ... }

function useToggle(): [boolean, () => void] { ... }
// 內部 return [v, fn] as const   ← ★ 否則會被推成 (boolean | (() => void))[]

const theme = {
  primary: "#0af",
  danger:  "#f33",
} as const satisfies Record<string, `#${string}`>;
// ★ 既檢查了是合法 hex，又保留了 "#0af" 這個字面量，而且是 readonly

const c = { a: 1 } as const;
c.a = 2;                       // ★ 編譯錯誤
 
// ★ 但執行期完全沒有保護
const d = c as { a: number };
d.a = 2;                       // ★ 編譯通過，而且真的改掉了

type Role string
const (
    RoleAdmin  Role = "admin"
    RoleEditor Role = "editor"
)

const albumTypes = { CD: "cd", VINYL: "vinyl" } as const;
type AlbumType = (typeof albumTypes)[keyof typeof albumTypes];

// ❌ 誘人但耦合：UI 元件綁死資料層的型別
type AvatarImageProps = Pick<User, "imageUrl" | "name">;
 
// ✅ 各自寫清楚
type AvatarImageProps = { imageUrl: string; name: string };

const routes = { home: "/", admin: "/admin" } satisfies Record<string, string>;
type RouteName = keyof typeof routes;      // ★ 加路由自動更新，不用維護兩份

import { z } from "zod";
 
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().min(0),
});
 
type User = z.infer<typeof UserSchema>;    // ★ 型別從驗證器推導
 
// ★ 一份定義，同時給「執行期驗證」和「編譯期型別」
const user = UserSchema.parse(await res.json());

type Params = Parameters<typeof myFunc>;
type Result = Awaited<ReturnType<typeof fetchUser>>;

// ❌ 讓回傳型別被推導 → 改實作可能意外改變公開 API
export function getUser(id: string) {
  return { id, name: "x" };            // ★ 多加一個內部欄位就變成 API 的一部分
}
// ✅ 明寫契約
export function getUser(id: string): User { ... }

// ❌ 不標註：錯誤出現在「使用的地方」，離源頭很遠
const config = { retries: "3" };
doWork(config);                          // ★ 這裡才報錯
 
// ✅ 標註：錯誤出現在「定義的地方」
const config: Config = { retries: "3" };  // ★ 這裡就報錯

type PublicUser = Omit<User, "password">;
type UserUpdate = Partial<Omit<User, "id">>;
type UserCreate = Pick<User, "email" | "password">;
type UserId     = User["id"];

{
  "compilerOptions": {
    /* Base Options */
    "skipLibCheck": true,        // 跳過 .d.ts 的型別檢查，加快編譯
    "target": "es2022",          // 隨時間往上調
    "esModuleInterop": true,     // CJS 與 ESM 的互通性
    "allowJs": true,             // 允許引入 .js
    "resolveJsonModule": true,   // 允許引入 .json
    "moduleDetection": "force",  // 所有 .ts 都當成 module，不是 script
    "isolatedModules": true,     // 每個檔案都能被獨立轉譯
 
    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true  // ⭐ 見下方
  }
}

import type { Album } from "./album";      // 整行都會被移除
import { type Album, createAlbum } from "./album";  // 只移除型別部分