解鎖TypeScript的潛力：改進標準庫類型
在 TypeScript 項目中，我們的編寫代碼并不是唯一的代碼。標準庫和運行環境也會參與類型檢查。這些包括在全局范圍內可用的JavaScript方法和Web平臺API，包括用于處理數組、window對象、Fetch API等方法。本文將探討TypeScript標準庫最常見的問題以及編寫更安全、可靠的代碼的方法！
1、TypeScript 標準庫的問題
Summer IS HERE
TypeScript的標準庫在很大程度上提供了高質量的類型定義，但是一些廣泛使用的 API 的類型聲明可能過于寬松或過于嚴格。
過于寬松類型的最常見問題是使用 any 而不是更精確的類型，比如 unknown。在標準庫中，Fetch API 是導致類型安全問題最常見的來源。json()方法返回的是 any 類型的值，這可能導致運行時錯誤和類型不匹配，同樣的情況也適用于JSON.parse方法。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = await response.json();
return data;
}
const pokemons = await fetchPokemons();
// ^? any
pokemons.data.map(pokemon => pokemon.name);
// ^ TypeError: Cannot read properties of undefined另一方面，有一些API的類型聲明過于限制，可能導致開發體驗較差。例如，Array.filter方法的工作方式與直覺相反，需要手動進行類型轉換或編寫類型保護。
// filteredArray 的類型是 Array<number | undefined>。
const filteredArray = [1, 2, undefined].filter(Boolean);
// filteredArray的類型是 Array<number>
const filteredArray = [1, 2, undefined].filter(
(item): item is number => Boolean(item)
);沒有簡單的方法來升級或替換標準庫的類型聲明，因為它的類型定義是隨 TypeScript 編譯器一起提供的。然而，如果想充分利用 TypeScript，有多種方法可以解決這個問題。
下面來以 Fetch API 為例探討一些選項。
2、使用類型斷言
Summer IS HERE
一個快速解決方案是手動指定類型。為了做到這一點，需要描述響應的格式并將any類型轉換為所需的類型。這樣就可以將對any的使用限制在代碼庫的一小部分中，比在整個程序中都使用返回的any類型要好很多。
interface PokemonListResponse {
count: number;
next: string | null;
previous: string | null;
results: Pokemon[];
}
interface Pokemon {
name: string;
url: string;
}
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = await response.json() as PokemonListResponse;
return data;
}
const pokemons = await fetchPokemons();
// ^? PokemonListResponse另外，TypeScript 現在將會突出顯示對不存在字段的訪問的錯誤。然而，類型轉換給我們帶來了額外的責任，即準確描述從服務端返回的類型。
pokemons.data.map(pokemon => pokemon.name);
// ^ Error: “Pokemon List Response”類型中不存在屬性“data”
// 應該在這里使用 'results' 字段類型斷言可能存在風險，應謹慎使用。如果斷言不正確，可能會導致意外行為。例如，在描述類型時容易犯錯，比如忽略字段可能為null或undefined的情況。
3、使用類型保護
Summer IS HERE
我們可以通過首先將any強制轉換為unknown來增強上述解決方案。這清楚地表明 fetch 函數可以返回任何類型的數據。然后需要通過編寫類型保護來驗證響應是否具有需要的數據，如下所示：
function isPokemonListResponse(data: unknown): data is PokemonListResponse {
if (typeof data !== 'object' || data === null) return false;
if (typeof data.count !== 'number') return false;
if (data.next !== null && typeof data.next !== 'string') return false;
if (data.previous !== null && typeof data.previous !== 'string') return false;
if (!Array.isArray(data.results)) return false;
for (const pokemon of data.results) {
if (typeof pokemon.name !== 'string') return false;
if (typeof pokemon.url !== 'string') return false;
}
return true;
}類型守衛函數接收一個具有unknown類型的變量作為輸入。使用is操作符來指定輸出類型，表示已經檢查了data變量中的數據，并且它具有這種類型。在函數內部，編寫所有必要的檢查，以驗證需要的所有字段。
可以使用得到的類型守衛來將unknown類型縮小到想要處理的類型。這樣，如果響應數據格式發生變化，可以迅速檢測到并在應用邏輯中處理該情況。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = (await response.json()) as unknown;
if (!isPokemonListResponse(data)) {
throw new Error('error');
}
return data;
}
const pokemons = await fetchPokemons();
// ^? PokemonListResponse然而，編寫類型守衛可能會很繁瑣，特別是在處理大量數據時。此外，在類型守衛中犯錯的風險很高，這等同于在類型定義本身上犯錯。
4、使用 Zod 庫
Summer IS HERE
為了簡化類型保護的編寫，可以使用 Zod 等數據驗證庫。使用 Zod，可以定義一個數據模式，然后調用一個函數來根據該模式檢查數據格式。
import { z } from 'zod';
const schema = z.object({
count: z.number(),
next: z.string().nullable(),
previous: z.string().nullable(),
results: z.array(
z.object({
name: z.string(),
url: z.string(),
})
),
});這類庫最初是以TypeScript為目標開發的。它們允許我們只需一次描述數據模式，然后自動生成類型定義。這消除了手動編寫TypeScript接口的需要，并避免了重復工作。
type PokemonListResponse = z.infer<typeof schema>;這個函數本質上就像一個類型守衛，而我們無需手動編寫它。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = (await response.json()) as unknown;
return schema.parse(data);
}
const pokemons = await fetchPokemons();
// ^? PokemonListResponse因此，我們得到了一種可靠的解決方案，不留下任何犯錯的機會。由于不再手動編寫類型定義，因此無法出現類型定義的錯誤。類型守衛也不會出現錯誤。模式中可能會出現錯誤，但可以在開發過程中察覺到這些錯誤。
5、Zod 的替代品
Summer IS HERE
Zod有許多不同的替代品，它們在功能、捆綁大小和性能上有所區別。對于每個應用程序，您可以選擇最合適的選項。
例如，superstruct 庫是Zod的一個更輕量級的替代方案。由于該庫相對較?。?3.1 kB 對比 3.4 kB），因此更適合在客戶端使用。
typia 庫是一種稍微不同的方法，它采用提前編譯的方式。由于編譯階段，數據驗證的速度更快。這對于大量數據或服務端重型代碼特別重要。
6、解決根本問題
Summer IS HERE
使用 Zod 等庫進行數據驗證可以幫助克服 TypeScript 標準庫中任何類型的問題。但是，了解返回 any 的標準庫方法仍然很重要，并在使用這些方法時將這些類型替換為unknown。
理想情況下，標準庫應該使用unknown類型而不是any。這將使編譯器能夠建議所有需要類型保護的地方。幸運的是，TypeScript 的聲明合并功能提供了這種可能性。
在 TypeScript 中，接口有一個有用的功能，即同名接口的多個聲明將合并為一個聲明。例如，如果有一個帶有name字段的 User 接口，然后聲明另一個帶有age字段的 User 接口，則生成的 User 接口將同時具有name和age字段。
interface User {
name: string;
}
interface User {
age: number;
}
const user: User = {
name: 'CUGGZ',
age: 25,
};這個特性不僅在單個文件內有效，而是在整個項目范圍內全局有效。這意味著可以使用這個特性來擴展 Window 類型，甚至是擴展外部庫的類型，包括標準庫。
declare global {
interface Window {
sayHello: () => void;
}
}
window.sayHello();
// ^ TypeScript 現在知道這個方法了通過使用聲明合并，可以完全解決TypeScript標準庫中 any 類型的問題。
7、Fetch API 更好的類型
Summer IS HERE
為了改進標準庫中的 Fetch API，需要更正 json() 方法的類型，以便它始終返回 unknown 而不是any。首先，確定json方法是 Response 接口的一部分。
interface Response extends Body {
readonly headers: Headers;
readonly ok: boolean;
readonly redirected: boolean;
readonly status: number;
readonly statusText: string;
readonly type: ResponseType;
readonly url: string;
clone(): Response;
}在Response的方法中找不到json()方法。相反，可以看到 Response 接口繼承自 Body 接口。因此，查看 Body 接口以找到需要的方法?？梢钥吹剑琷son()方法實際上返回any類型。
interface Body {
readonly body: ReadableStream<Uint8Array> | null;
readonly bodyUsed: boolean;
arrayBuffer(): Promise<ArrayBuffer>;
blob(): Promise<Blob>;
formData(): Promise<FormData>;
text(): Promise<string>;
json(): Promise<any>;
}為了解決這個問題，可以在項目中再定義一次 Body 接口，如下所示：
declare global {
interface Body {
json(): Promise<unknown>;
}
}由于聲明合并， json()方法現在將始終返回 unknown 類型。
async function fetchPokemons() {
const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const data = await response.json();
// ^? unknown
return data;
}8、JSON.parse 更好的類型
Summer IS HERE
同樣，我們可以修復JSON解析的問題。默認情況下，parse()方法返回any類型，這可能會在使用解析后的數據時導致運行時錯誤。
const data = JSON.parse(text);
// ^? any為了解決這個問題，我們需要知道 parse() 方法是 JSON 接口的一部分。然后可以在項目中聲明類型，如下所示：
declare global {
interface JSON {
parse(
text: string,
reviver?: (this: any, key: string, value: any) => any
): unknown;
}
}現在，JSON 解析總是返回unknow類型，這可以帶來更安全、更易于維護的代碼庫。
const data = JSON.parse(text);
// ^? unknown9、Array.isArray 更好的類型
Summer IS HERE
另一個常見的例子是檢查變量是否是數組。默認情況下，此方法返回包含any類型的數組，基本上與使用any沒有區別。
if (Array.isArray(userInput)) {
console.log(userInput);
// ^? any[]
}這里可以擴展數組構造函數的類型，如下所示，該方法現在返回一個包含unknown類型的數組，這樣更安全和準確。
declare global {
interface ArrayConstructor {
isArray(arg: any): arg is unknown[];
}
}
if (Array.isArray(userInput)) {
console.log(userInput);
// ^? unknown[]
}10、structuredClone 更好的類型
Summer IS HERE
最近引入的克隆對象方法 structuredClone 也返回 any。
const user = {
name: 'John',
age: 30,
};
const copy = structuredClone(user);
// ^? any修復這個問題和前面的方法一樣。不過，在這種情況下，需要添加一個新的函數簽名而不是擴展接口。幸運的是，聲明合并對函數也同樣適用。因此，可以按照以下方式修復這個問題：
declare global {
declare function structuredClone<T>(value: T, options?: StructuredSerializeOptions): T;
}現在克隆的對象將具有與原始對象具有相同的類型。
const user = {
name: 'John',
age: 30,
};
const copy = structuredClone(user);
// ^? { name: string, age: number }11、Array.filter 更好的類型
Summer IS HERE
聲明合并不僅對修復any類型的問題很有用，還可以改進標準庫的易用性。下面來看一下Array.filter方法的例子。
const filteredArray = [1, 2, undefined].filter(Boolean);
// ^? Array<number | undefined>可以讓 TypeScript 在應用 Boolean 過濾函數后自動縮小數組類型。為此，需要擴展 Array 接口，如下所示：
type NonFalsy<T> = T extends false | 0 | "" | null | undefined | 0n ? never : T;
declare global {
interface Array<T> {
filter(predicate: BooleanConstructor, thisArg?: any): Array<NonFalsy<T>>;
}
}現在可以使用filter的簡寫形式，并獲得正確的數據類型作為結果。
12、ts-reset
Summer IS HERE
TypeScript 的標準庫包含超過 1000 個 any 類型的實例。在使用嚴格類型的代碼時，有很多地方可以改善開發體驗。避免手動修復標準庫的一種解決方案是使用 ts-reset 庫。它易于使用，只需在項目中導入一次。
import "@total-typescript/ts-reset";該庫相對較新，因此它對標準庫的修復還沒有想要的那么多。然而，我相信這只是一個開始。值得注意的是，ts-reset 僅包含對全局類型的安全更改，不會導致潛在的運行時錯誤。
13、避免在庫中使用
Summer IS HERE
改進 TypeScript 的標準庫有很多好處。然而，值得注意的是，重新定義標準庫的全局類型限制了這種方法僅適用于應用。不適用于庫，因為使用這樣的庫會意外地改變應用的全局類型的行為。
一般來說，建議避免在庫中修改 TypeScript 的標準庫類型。相反，可以使用靜態分析工具在代碼質量和類型安全方面獲得類似的結果，這適用于庫開發。
14、總結
Summer IS HERE
TypeScript的標準庫是TypeScript編譯器的一個關鍵組成部分，提供了一系列內置類型，用于處理JavaScript和Web平臺API。然而，標準庫并不完美，其中一些類型聲明存在問題，可能導致代碼中的類型檢查質量較低。本文探討了一些TypeScript標準庫常見的問題以及編寫更安全、更可靠的代碼的方法。
通過使用類型斷言、類型守衛和類似Zod的庫，可以改善代碼庫的類型安全性和代碼質量。此外，還可以通過使用聲明合并來修復問題的根本，從而改善TypeScript標準庫的類型安全性和人性化程度。
