Czemu any odbiera przekazany typ?

Otypuj parametr jako any i TypeScript przestaje sprawdzać wszystko, co wychodzi z funkcji:

1
2
3
4
5
6

function firstElement(arr: any[]): any {
  return arr[0];
}

const n = firstElement([1, 2, 3]);
n.toUpperCase(); // kompiluje się, wywala w czasie działania

Ty wiesz, że przekazałeś tablicę liczb. Kompilator nie wie, bo any mówi mu, żeby przestał patrzeć. n wraca jako any, więc wywołanie metody string na liczbie kompiluje się bez problemu i wyrzuca TypeError: n.toUpperCase is not a function przy uruchomieniu.

Generic nazywa typ, zamiast go odrzucać:

1
2
3
4
5
6
7

function firstElement<T>(arr: T[]): T {
  return arr[0];
}

const n = firstElement([1, 2, 3]); // n: number
const s = firstElement(["a", "b"]); // s: string
n.toUpperCase(); // błąd: Property 'toUpperCase' does not exist on type 'number'

T to parametr typu, placeholder wypełniany przy każdym wywołaniu. firstElement([1, 2, 3]) wypełnia T typem number, typ zwracany staje się number, a błędne wywołanie .toUpperCase() zawodzi w edytorze, nie na produkcji. Funkcję piszesz raz, a każdy typ elementu zachowuje swoją kontrolę.

W dalszej części przewodnika pokazujemy, jak używać generics bez komplikowania sygnatury bardziej, niż komplikowałby życie błąd, któremu mają zapobiegać.

Jak TypeScript wnioskuje parametr typu?

Nie napisałeś wyżej firstElement<number>([1, 2, 3]) i rzadko musisz. TypeScript porównuje argument z zadeklarowaną formą parametru (T[]) i rozwiązuje T. To ta sama inferencja, która typuje const x = 5 jako number, zastosowana do parametrów typu.

Gdy nie ma z czego wnioskować, T spada do unknown:

1
2
3
4
5
6

function makeEmptyArray<T>(): T[] {
  return [];
}

const arr = makeEmptyArray(); // T jest unknown, wnioskowane jako `unknown[]`
const nums = makeEmptyArray<number>(); // jawny argument typu, nums: number[]

Gdy wywołanie nie ma żadnej wartości, z której można wnioskować, podaj argument typu sam, w ostrych nawiasach.

Inferencja może też pójść nie tak, gdy dwa argumenty trafiają do tego samego T i są niezgodne. TypeScript wybiera jednego kandydata i zgłasza drugi argument jako problem, co może skończyć się błędem, który nazywa typ, jakiego nigdy nie napisałeś:

1
2
3
4
5
6

function longest<T>(a: T, b: T): T {
  return a;
}

longest([1, 2], "abc");
// błąd: Argument of type 'number[]' is not assignable to parameter of type '"abc"'

Gdy generyczne wywołanie kończy się niejasnym błędem lub nieoczekiwanym typem, najedź w edytorze na wywołanie i zobacz, co zostało wywnioskowane dla T. Zwykle to wyjaśnia problem szybciej niż czytanie komunikatu.

Jak ograniczyć generic za pomocą extends i keyof?

Nieograniczony T może być czymkolwiek, więc w funkcji możesz zrobić tylko to, co obsługuje każdy typ, czyli niemal nic ponad przekazywanie wartości dalej. Większość realnych generycznych funkcji musi coś zakładać o T, a extends to sposób, żeby to powiedzieć:

1
2
3
4
5
6
7
8

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const dev = { name: "Tobias", role: "backend", salary: 95000 };

getProperty(dev, "role"); // "backend", typ string
getProperty(dev, "pay"); // błąd: Argument of type '"pay"' is not assignable to parameter of type '"name" | "role" | "salary"'

K extends keyof T ogranicza K do nazw właściwości obiektu, który przekazujesz, a T[K] odczytuje typ tej właściwości. Lista dopuszczalnych kluczy pochodzi z obiektu w miejscu wywołania, nie z unii wpisanej na sztywno. Literówka jak "pay" staje się błędem kompilacji, nie cichym undefined.

Ograniczenie może być też prostym kształtem:

1
2
3
4
5
6
7
8

function logLength<T extends { length: number }>(value: T): T {
  console.log(value.length);
  return value;
}

logLength("hello"); // 5
logLength([1, 2, 3]); // 3
logLength(42); // błąd: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'

I stringi, i tablice mają length, więc obie przechodzą. Liczba nie, i wywołanie jest odrzucane, zanim ciało funkcji w ogóle się wykona. Ponieważ typem zwracanym jest T, a nie { length: number }, logLength("hello") nadal zwraca string.

Jak działają generyczne interfejsy i klasy?

Generyczny interfejs to kształt z parametrem typu:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

interface Box<T> {
  value: T;
  unwrap(): T;
}

const numberBox: Box<number> = {
  value: 5,
  unwrap() {
    return this.value;
  },
};

Generyczna klasa współdzieli swój parametr typu między wszystkimi polami i metodami:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items[this.items.length - 1];
  }
}

const numbers = new Stack<number>();
numbers.push(1);
numbers.push(2);
numbers.peek(); // 2, typ number | undefined

new Stack<number>() i new Stack<string>() są w pełni otypowane, a klasa istnieje tylko raz. Ten sam wzorzec pojawia się wszędzie, gdzie używasz dependency injection: piszesz Repository<T> raz, a potem wstrzykujesz Repository<User> i Repository<Order> tam, gdzie są potrzebne, zamiast trzymać osobną, prawie identyczną klasę na każdą jednostkę.

Wiele parametrów typu działa tak samo, i każdy może mieć własne ograniczenie:

1
2
3
4
5

function pair<K, V>(key: K, value: V): [K, V] {
  return [key, value];
}

pair("id", 42); // [string, number]

Dwa parametry to też sposób, w jaki typ Result<T, E> łączy wartość sukcesu z typem błędu. Jeśli zastanawiasz się, czy funkcje powinny rzucać wyjątki, czy zwracać błędy jako dane, exceptions vs wartości błędów omawia ten wybór.

Jak działają domyślne parametry typu?

Parametr typu może mieć wartość domyślną, podobnie jak parametr funkcji z wartością domyślną:

1
2
3
4
5
6

class ApiResponse<T = unknown> {
  constructor(public data: T, public status: number) {}
}

const raw = new ApiResponse({ ok: true }, 200); // T wnioskowane jako { ok: boolean }
const typed: ApiResponse<{ id: number }> = new ApiResponse({ id: 1 }, 200);

Inferencja ma pierwszeństwo, gdy jest argument, z którego można wnioskować, tak jak w raw. Wartość domyślna działa, gdy nic nie wypełnia T, na przykład gdy piszesz ApiResponse jako anotację typu bez argumentu typu. To sprawia, że wartości domyślne są przydatne w wrapperach takich jak typy odpowiedzi i payloady zdarzeń, gdzie wielu miejscom wywołania nie zależy na dokładnym typie danych. Jako domyślny wybierz unknown, nie any: wciąż wymusza sprawdzenie, zanim ktoś odczyta data.

Kiedy użyć union type zamiast generic?

Zadaj sobie jedno pytanie, zanim dodasz <T>: czy typ zwracany zależy od tego, co przekazano? Jeśli funkcja zwraca ten sam typ niezależnie od wejścia, unia wystarczy, a generic nic nie dodaje:

1
2
3
4

// tu generic nie jest potrzebny: typ zwracany nie zależy od wejścia
function describe(value: string | number): string {
  return typeof value === "string" ? value.toUpperCase() : value.toFixed(2);
}

firstElement, getProperty i Stack<T> są inne. Każda z nich zwraca coś, czego typ zależy od tego, co weszło, i właśnie ten związek między wejściem a wyjściem daje generic. Jeśli możesz napisać funkcję z unią, nic nie tracąc, użyj unii.

Dodawanie parametrów typu, bo funkcja mogłaby być generyczna, kosztuje czytelność i nic nie daje. Helper z trzema parametrami typu, wywoływany tylko ze string i number, jest trudniejszy do czytania niż dwa przeciążenia. Dodaj <T>, gdy realny wywołujący potrzebuje, żeby typ przepłynął, i usuń je, gdy każde miejsce wywołania ustala ten sam konkretny typ.

Czemu nie można użyć T w czasie działania?

Parametry typu są usuwane w czasie kompilacji. JavaScript, który się wykonuje, nie ma w sobie żadnego T, więc nie możesz go skonstruować, sprawdzić instanceof T, ani rozgałęziać się na jego podstawie:

1
2
3
4

function create<T>(): T {
  // return new T(); // błąd: 'T' only refers to a type, but is being used as a value here
  throw new Error("not implemented");
}

Jeśli funkcja musi zbudować T lub sprawdzić go w czasie działania, przekaż prawdziwą wartość jako argument: konstruktor, schemat albo tag typu. Generics są kontraktem w czasie kompilacji, nie ochroną w czasie działania, więc dane przychodzące z zewnątrz programu (odpowiedź API, JSON.parse) wciąż wymagają walidacji, nawet gdy są otypowane jako ApiResponse<User>.

Aby zobaczyć każdy błąd z tego przewodnika na własne oczy, zainstaluj TypeScript za pomocą npm, Yarn lub pnpm (tego, co już używa twój projekt), wklej przykłady do pliku .ts i uruchom npx tsc --noEmit --strict. Potem otwórz najczęściej używane any w swoim kodzie i sprawdź, czy <T> pozwoliłoby typowi przepłynąć.

Powiązane artykuły