Funkcje w TypeScript: typy parametrów, typ zwracany, void

Funkcja w TypeScript to funkcja JavaScript z typami parametrów i opcjonalnie z typem wartości zwracanej. Każdy parametr dostaje adnotację, typ zwracany stoi po liście parametrów, a kompilator sprawdza względem nich każde wywołanie.

function area(width: number, height: number): number {
  return width * height;
}

console.log(area(3, 4)); // 12

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
area("3", 4);

// @ts-expect-error: Expected 2 arguments, but got 1.
area(3);

Oba błędne wywołania to błędy kompilacji (TS2345 i TS2554). Komentarze // @ts-expect-error mówią kompilatorowi, że w następnej linii spodziewany jest błąd, więc reszta pliku nadal się uruchamia. Usuń jeden z nich i uruchom ponownie, aby zobaczyć prawdziwy komunikat.

Typy parametrów

Każdy parametr zapisuje się jako name: Type. Przy strict, który w TypeScript 7 jest domyślnie włączony, parametr bez adnotacji i bez kontekstu do wnioskowania to błąd: Parameter 'x' implicitly has an 'any' type. (TS7006). W praktyce więc każdy parametr samodzielnej funkcji ma adnotację.

Jako typ parametru działa każdy typ: prymitywy, tablice, typy obiektowe, unie, inne funkcje.

type User = { name: string; tags: string[] };

function describe(user: User, maxTags: number): string {
  const shown = user.tags.slice(0, maxTags).join(", ");
  return `${user.name} (${shown})`;
}

function formatId(id: string | number): string {
  return typeof id === "number" ? id.toFixed(0).padStart(5, "0") : id.toUpperCase();
}

console.log(describe({ name: "Ada", tags: ["math", "code", "tea"] }, 2)); // Ada (math, code)
console.log(formatId(42));      // 00042
console.log(formatId("ab-7"));  // AB-7

TypeScript sprawdza też liczbę argumentów. Przekazanie większej lub mniejszej liczby, niż deklaruje funkcja, to błąd, w odróżnieniu od zwykłego JavaScriptu, który brakujące uzupełnia wartością undefined, a nadmiarowe ignoruje. Jak uczynić parametr opcjonalnym lub nadać mu wartość domyślną, opisuje strona o parametrach opcjonalnych.

Typy zwracane: adnotacja czy wnioskowanie

Typ zwracany stoi po nawiasie zamykającym: function f(): Type. Jest opcjonalny. Bez niego TypeScript wnioskuje typ z każdego return w ciele funkcji.

// Inferred: (n: number) => "even" | "odd"
function parity(n: number) {
  return n % 2 === 0 ? "even" : "odd";
}

// Annotated: the contract is written down
function average(values: number[]): number {
  if (values.length === 0) return 0;
  const sum = values.reduce((acc, v) => acc + v, 0);
  return sum / values.length;
}

const p = parity(7);
console.log(p, average([2, 4, 9])); // odd 5

Adnotacja się opłaca, gdy funkcja jest eksportowana, ma kilka ścieżek zwracania albo jest rekurencyjna. Błąd pojawia się wtedy wewnątrz funkcji, przy złym return, a nie u wywołującego. Klasyczny przypadek to gałąź, w której brakuje return:

// This does not compile: one path falls off the end of the function.
function grade(score: number): string {
  if (score >= 90) return "A";
  if (score >= 80) return "B";
}

console.log(grade(85));

Kompilator zgłasza index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Dodaj na końcu return "C";, a kod się uruchomi. Bez adnotacji : string funkcja skompilowałaby się z wywnioskowanym typem "A" | "B" | undefined, a problem przeniósłby się do tego, kto używa wyniku.

void: funkcje, które nic nie zwracają

Funkcja, która tylko coś robi (loguje, zapisuje, modyfikuje), ma typ zwracany void. TypeScript wnioskuje go, gdy nie ma return z wartością, i można go też zapisać jawnie.

function logLine(label: string, value: number): void {
  console.log(`${label.padEnd(8)}${value}`);
}

logLine("apples", 3);
logLine("pears", 12);

// A callback typed as returning void may return a value; it is ignored.
const lengths: number[] = [];
const push: (s: string) => void = (s) => lengths.push(s.length);
["a", "bcd"].forEach(push);
console.log(lengths); // [ 1, 3 ]

Te reguły dotyczące void często zaskakują:

Drugi wiersz jest celowy. Dzięki niemu arr.forEach(x => list.push(x)) się kompiluje, choć push zwraca liczbę. void w typie funkcji znaczy „cokolwiek to zwraca, nikt tego nie czyta”. Dla funkcji, która w ogóle nie wraca (zawsze rzuca wyjątek albo działa w nieskończonej pętli), typem zwracanym jest never.

Funkcje strzałkowe i wyrażenia funkcyjne

Funkcje strzałkowe i wyrażenia funkcyjne przyjmują te same adnotacje. Typ zwracany stoi po liście parametrów, przed =>.

const double = (n: number): number => n * 2;

const toUpper = function (s: string): string {
  return s.toUpperCase();
};

// Returning an object literal from an arrow needs parentheses.
const point = (x: number, y: number) => ({ x, y });

console.log(double(21), toUpper("ok")); // 42 OK
console.log(point(1, 2));               // { x: 1, y: 2 }

Bez nawiasów (x, y) => { x, y } jest blokiem bez return, a funkcja zwraca undefined. Reguły działania funkcji strzałkowych w czasie wykonania (brak własnego this, brak arguments) są takie same jak w JavaScripcie; zobacz funkcje strzałkowe w JavaScript.

Gdy funkcja jest zapisana bezpośrednio jako argument, zwykle w ogóle nie dodaje się adnotacji jej parametrów. TypeScript wie, co otrzymuje callback, z funkcji, do której jest przekazywany (typowanie kontekstowe): w [1, 2].map(n => n * 2) n ma już typ number. Zapisywanie typu funkcji jako wartości, (n: number) => string, opisuje strona o typach funkcji.

Zwracanie kilku wartości

Funkcja zwraca jedną wartość, więc zwróć obiekt albo krotkę i ją zdestrukturyzuj.

function minMax(values: number[]): { min: number; max: number } {
  return { min: Math.min(...values), max: Math.max(...values) };
}

function splitName(full: string): [first: string, last: string] {
  const i = full.indexOf(" ");
  return [full.slice(0, i), full.slice(i + 1)];
}

const { min, max } = minMax([7, 2, 9]);
const [first, last] = splitName("Grace Hopper");
console.log(min, max, first, last); // 2 9 Grace Hopper

Typ zwracany krotki wymaga adnotacji. Bez niej [a, b] jest wnioskowane jako string[]: destrukturyzacja nadal działa, ale typ nie mówi już, że elementy są dokładnie dwa.

Funkcje async

Funkcja async zawsze zwraca Promise. Zapisz typ zwracany jako Promise<T>, gdzie T to to, co funkcja zwraca w środku.

async function loadScore(id: number): Promise<number> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  return id * 10;
}

async function main(): Promise<void> {
  const score = await loadScore(4); // score: number
  console.log("score", score);
}

main();

Zapis async function f(): number to błąd: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

Parametr this

JavaScript ustala this w chwili wywołania. TypeScript pozwala zadeklarować, czym musi być this, za pomocą sztucznego pierwszego parametru o nazwie this. Jest on usuwany ze skompilowanego JavaScriptu, a wywołujący go nie przekazują.

interface Counter {
  count: number;
}

function increment(this: Counter, by: number): void {
  this.count += by;
}

const c = { count: 0, increment };
c.increment(2); // fine: this is c

increment(2);
// error TS2684: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Counter'.

Bez parametru this wewnątrz samodzielnej funkcji this jest niejawnym any, a tryb strict zgłasza 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). W metodach klas this ma już typ instancji klasy, więc ten parametr przydaje się głównie w samodzielnych funkcjach dołączanych do obiektów i w callbackach, które biblioteki wywołują z określonym this.