CH5 · TypeScript 詳細 ROADMAP
計畫文件，不會被 Quartz 渲染。
回主 roadmap → frontend/ROADMAP.md
章節目標
TypeScript 不是「加型別的 JS」這麼簡單。建立從「為什麼要用」到型別體操、從 Utility Types 到 Infer、從 Runtime validation 到跟後端 contract 對齊的完整 TS 能力。讓讀者能駕馭 TS 的表達力，而不是被 TS 的複雜度綁住。
🌱 基本介紹
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 01 | 為什麼要用 TypeScript | why | 🌿 | 已有（涵蓋 Why 的答案） |
| 02 | 基本型別（primitives） | primitives | 🌿 | 已有 |
| 03 | TypeScript 是什麼 vs 什麼不是 | 03-what-is-typescript | 🌱 | 不是新語言、是 JS superset、編譯期檢查不是 runtime、跟 Flow / Hegel 的差異、不是解所有問題 |
❓ 為什麼需要
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 04 | 為什麼需要型別系統（JSDoc 不夠嗎） | 04-why-type-system | 🌱 | IDE 提示深度、重構安全、團隊溝通契約、為什麼 JSDoc 型別註解最終被 TS 取代 |
| 05 | 為什麼要用泛型（為什麼不寫一堆重複型別） | 05-why-generics | 🌱 | 型別參數化的價值、避免 any 的唯一方式、React 組件的 props 型別靈活度 |
| 06 | 為什麼需要 Runtime validation（TS 不夠嗎） | 06-why-runtime-validation | 🌱 | 編譯期 vs 執行期的界線、API 回傳不受 TS 保護、外部資料必須驗證、Zod / Valibot / Yup 解的問題 |
| 07 | 為什麼 TS 有時候反而是障礙 | 07-when-ts-hurts | 🌱 | 過度 typing 的代價、library 型別品質問題、新手陷入型別體操、反省何時該用 any / unknown |
🕰️ 演進
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 08 | TypeScript 版本史 | 08-ts-version-history | 🌱 | 0.x（2012）→ 2.x 成熟 → 3.x 泛型爆發 → 4.x 變種型別 → 5.x 現代（decorator 正式）、重要里程碑 |
| 09 | 型別系統演進 | 09-type-system-evolution | 🌱 | 結構性型別 → Variance → Template Literal Types → Infer → Conditional Type Narrowing |
| 10 | TS 競爭者與替代 | 10-ts-alternatives-history | 🌱 | Flow（Meta 棄）→ Hegel → JSDoc + checkJs → TS 獨佔原因、2024 年 VS Code 全部用 TS 的生態效應 |
🧠 知識型
實戰 patterns（現有）
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 11 | Utility Types、命名轉換 | practical-patterns | 🌿 | 已有 |
| 12 | 泛型與 Type Guard | practical-patterns-2 | 🌿 | 已有 |
| 13 | Conditional / Mapped Types | practical-patterns-3 | 🌿 | 已有 |
型別系統深入
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 14 | Template Literal Types | 14-template-literal-types | 🌱 | type Route = \/user/${number}“、字串型型別組合、常見模式 |
| 15 | Infer 與型別推斷 | 15-infer-type-inference | 🌱 | infer 關鍵字、遞迴型別、實戰例（ReturnType / Parameters 自製） |
| 16 | Variance（協變 / 逆變） | 16-variance | 🌱 | 為什麼 function 參數是逆變、readonly 陣列的協變、常見錯誤修正 |
| 17 | Type Narrowing 進階 | 17-type-narrowing | 🌱 | in / instanceof / 自訂 type guard、discriminated unions、exhaustiveness check |
| 18 | Branded Types / Opaque Types | 18-branded-types | 🌱 | 避免 UserId 跟 PostId 混用、值物件模式 |
Error handling 型別化
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 19 | 錯誤處理的型別模式 | 19-error-type-patterns | 🌱 | Result / Either 型別、neverthrow library、為什麼 TS 沒原生支援 checked exception |
🔧 小實作注意事項
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 20 | TS 技巧速查合輯 | 20-ts-tips | 🌱 | 常用 Utility Types（Pick / Omit / Partial / Required / Record / Awaited）、常用 type guards、常見 1-liner |
| 21 | 型別體操實戰題 | 21-type-gymnastics | 🌱 | type-challenges 精選題目、訓練型別思維 |
| 22 | 跟後端 contract 對齊 | 22-backend-contract | 🌱 | OpenAPI → TS 自動生成（openapi-typescript）、GraphQL codegen、tRPC 的方案 |
| 23 | Runtime validation 整合 | 23-runtime-validation | 🌱 | Zod / Valibot / Yup 比較、schema-first vs type-first、從 schema infer TS type |
| 24 | tsconfig 工程化 | 24-tsconfig | 🌱 | strict flags 逐條解釋、path alias、monorepo 配置、composite build |
| 25 | TS 專案結構 | 25-ts-project-structure | 🌱 | 型別檔案組織（types/ vs co-located）、module augmentation、.d.ts 寫作 |
| 26 | 從 JS 遷移到 TS 策略（總覽） | 26-js-to-ts-migration | 🌱 | 為什麼要做、為什麼會失敗、漸進式 vs 一次性轉換、KPI 怎麼定（不是「全部 any 清零」，是「生產 bug 減少」） |
| 27 | 轉換前的心態與團隊溝通 | 27-migration-mindset | 🌱 | 怎麼跟主管爭取轉換時間、怎麼跟不熟 TS 的同事共事、預期會遇到的阻力（過度 strict、型別體操癮、PR review 變慢）、成功失敗案例對比 |
| 28 | JS → TS 轉換實務工具箱 | 28-migration-toolkit | 🌱 | allowJs（JS/TS 共存）、checkJs + @ts-check（JS 也做型別檢查）、JSDoc 型別註解作為中間站、ts-migrate（Airbnb 自動轉換）、rename script 策略、typescript-eslint 的遷移期 safety net |
| 29 | 編譯 vs 直接執行：TS 的兩種 runtime 場景 | 29-ts-runtime-scenarios | 🌱 | 場景 A：TS → tsc/esbuild/swc/tsup → JS 發佈（library / npm / browser build）；場景 B：直接跑 TS（Bun / Deno / Node 22+ --experimental-strip-types / tsx / ts-node）。兩種場景的選擇依據、工具選型、陷阱（e.g., declaration file 生成、sourcemap） |
💣 Anti-pattern
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 30 | TypeScript Anti-patterns | 30-ts-anti-patterns | 🌱 | any 濫用、assertions 濫用（as Type）、過度巢狀泛型、ignore comment 偷懶、拿 TS 當 runtime 檢查 |
🧰 對應檢查工具
| # | 主題 | Slug | Stage | 大綱 |
|---|
| 31 | TS 檢查工具 | 31-ts-tooling | 🌱 | tsc —noEmit、@typescript-eslint、ts-morph、type-coverage、dprint、api-extractor |
📎 補充
| # | 主題 | Slug | Stage | 大綱 |
|---|
| S01 | Decorators（ES2023 Stage 4） | s01-decorators | 🌱 | TC39 decorator、TS 舊版 experimental decorator 差異、Angular/NestJS 用法 |
| S02 | TypeScript 的 Effect 系統 | s02-effect-ts | 🌱 | Effect-ts / fp-ts 函數式 TS 生態 |
| S03 | TypeScript 編譯器 API | s03-compiler-api | 🌱 | 寫 custom transformer、自己造 lint rule、ts-morph 進階 |
| S04 | TypeScript Performance | s04-ts-performance | 🌱 | 大型專案編譯慢的原因、skipLibCheck、incremental build |
章節進度統計
- 知識主題：31 + 4 補充 = 35 項
- 🌿 growing：5（已有）
- 🌱 seed：30
跨系列連結
- →
frontend/js/ CH3（TS 建立在 JS 語言核心之上）
- →
frontend/framework/ CH6（React / Vue 的 TS 整合）
- →
frontend/application/ CH8 F09（API contract、OpenAPI）
- →
backend/ 系列（後端 TS 使用）
- →
frontend/testing/ CH10（TS 測試策略）