Функции в TypeScript: типы параметров, возврат и void

Функция в TypeScript это функция JavaScript с типами у параметров и, при желании, у возвращаемого значения. Каждый параметр получает аннотацию, возвращаемый тип пишется после списка параметров, и компилятор сверяет с ними каждый вызов.

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);

Оба неправильных вызова дают ошибки компиляции (TS2345 и TS2554). Комментарии // @ts-expect-error сообщают компилятору, что на следующей строке ожидается ошибка, поэтому остальной файл всё равно выполняется. Удалите один из них и запустите снова, чтобы увидеть настоящее сообщение.

Типы параметров

Каждый параметр записывается как name: Type. В режиме strict, который в TypeScript 7 включён по умолчанию, параметр без аннотации и без контекста для вывода даёт ошибку: Parameter 'x' implicitly has an 'any' type. (TS7006). Так что на практике каждый параметр самостоятельной функции аннотируется.

Типом параметра может быть любой тип: примитивы, массивы, объектные типы, объединения, другие функции.

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 проверяет и количество аргументов. Передать больше или меньше, чем объявлено, это ошибка, в отличие от обычного JavaScript, который заполняет недостающие аргументы undefined и игнорирует лишние. Как сделать параметр опциональным или задать ему значение по умолчанию, описано на странице опциональные параметры.

Возвращаемые типы: указать или вывести

Возвращаемый тип идёт после закрывающей скобки: function f(): Type. Он необязателен. Без него TypeScript выводит тип из каждого return в теле.

// 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

Аннотация оправдана, когда функция экспортируется, когда у неё несколько путей возврата или когда она рекурсивная. Тогда ошибка появляется внутри функции, у неверного 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));

Компилятор сообщает index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Добавьте в конце return "C";, и код запустится. Без аннотации : string функция скомпилировалась бы с выведенным типом "A" | "B" | undefined, и проблема переместилась бы к тому, кто использует результат.

void: функции, которые ничего не возвращают

У функции, которая только что-то делает (пишет в лог, записывает, изменяет), возвращаемый тип void. Именно его TypeScript выводит, когда нет return со значением, и его можно написать явно.

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 ]

Эти правила про void удивляют многих:

Вторая строка так устроена намеренно. Именно поэтому arr.forEach(x => list.push(x)) компилируется, хотя push возвращает число. void в типе функции означает «что бы она ни вернула, это никто не читает». Для функции, которая вообще никогда не возвращает управление (всегда бросает исключение или зацикливается навсегда), возвращаемый тип never.

Стрелочные функции и функциональные выражения

Стрелочные функции и функциональные выражения аннотируются так же. Возвращаемый тип идёт после списка параметров, перед =>.

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 }

Без скобок (x, y) => { x, y } это блок без return, и функция возвращает undefined. Правила времени выполнения для стрелочных функций (нет своего this, нет arguments) те же, что в JavaScript; см. стрелочные функции в JavaScript.

Когда функция написана прямо в аргументе, её параметры обычно вообще не аннотируют. TypeScript знает, что получает колбэк, из функции, в которую он передаётся (контекстная типизация): в [1, 2].map(n => n * 2) у n уже тип number. Запись типа функции как значения, (n: number) => string, описана на странице типы функций.

Возврат нескольких значений

Функция возвращает одно значение, поэтому верните объект или кортеж и деструктурируйте его.

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

Кортежному возвращаемому типу нужна аннотация. Без неё [a, b] выводится как string[]: деструктуризация по-прежнему работает, но тип больше не говорит, что элементов ровно два.

Async-функции

async-функция всегда возвращает Promise. Аннотируйте возвращаемый тип как Promise<T>, где T это то, что функция возвращает внутри.

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();

Запись async function f(): number даёт ошибку: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

Параметр this

JavaScript определяет this в момент вызова. TypeScript позволяет объявить, каким должен быть this, через фиктивный первый параметр с именем this. Он удаляется из скомпилированного JavaScript, и вызывающий код его не передаёт.

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'.

Без параметра this внутри самостоятельной функции this имеет неявный тип any, и строгий режим сообщает 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). В методах классов this уже типизирован как экземпляр класса, поэтому этот параметр полезен в основном для самостоятельных функций, прикреплённых к объектам, и для колбэков, которые библиотеки вызывают с определённым this.