typescript-pro

TypeScript Pro

核心工作流程

分析型別架構 — 審視 tsconfig、型別覆蓋率與建置效能
設計型別優先（Type-First）的 API — 建立品牌型別、泛型與工具型別
具備型別安全地進行實作 — 撰寫型別守衛、可辨識聯集與條件型別；在繼續之前執行 tsc --noEmit 擷取型別錯誤
最佳化建置程序 — 配置專案參考（Project References）、遞增編譯（Incremental Compilation）與 Tree Shaking；變更後重新執行 tsc --noEmit 以確認零錯誤
測試型別 — 使用如 type-coverage 等工具確認型別覆蓋率；驗證所有公開 API 皆具備明確的傳回型別；反覆執行步驟 3–4 直到所有檢查通過

參考指南

根據情境載入詳細指引：

主題	參考文件	載入時機
進階型別	`references/advanced-types.md`	泛型、條件型別、對映型別、樣板字面常數型別
型別守衛	`references/type-guards.md`	型別收窄（Type Narrowing）、可辨識聯集、斷言函式
工具型別	`references/utility-types.md`	Partial、Pick、Omit、Record 或自訂工具型別
設定配置	`references/configuration.md`	tsconfig 選項、嚴格模式、專案參考
設計模式	`references/patterns.md`	建造者模式、工廠模式、型別安全 API

程式碼範例

品牌型別 (Branded Types)

// 領域模型使用的品牌型別
type Brand<T, B extends string> = T & { readonly __brand: B };
type UserId  = Brand<string, "UserId">;
type OrderId = Brand<number, "OrderId">;

const toUserId  = (id: string): UserId  => id as UserId;
const toOrderId = (id: number): OrderId => id as OrderId;

// 使用方式 — 在編譯期防止意外混淆不同的 ID
function getOrder(userId: UserId, orderId: OrderId) { /* ... */ }

可辨識聯集與型別守衛 (Discriminated Unions & Type Guards)

type LoadingState = { status: "loading" };
type SuccessState = { status: "success"; data: string[] };
type ErrorState   = { status: "error";   error: Error };
type RequestState = LoadingState | SuccessState | ErrorState;

// 型別述語守衛（Type Predicate Guard）
function isSuccess(state: RequestState): state is SuccessState {
  return state.status === "success";
}

// 搭配可辨識聯集進行完備性檢查的 switch（Exhaustive Switch）
function renderState(state: RequestState): string {
  switch (state.status) {
    case "loading": return "Loading…";
    case "success": return state.data.join(", ");
    case "error":   return state.error.message;
    default: {
      const _exhaustive: never = state;
      throw new Error(`Unhandled state: ${_exhaustive}`);
    }
  }
}

自訂工具型別 (Custom Utility Types)

// 深度唯讀（Deep Readonly）— 不可變的巢狀物件
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

// 嚴格要求在一組 Key 中只能恰好存在一個
type RequireExactlyOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> &
  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys];