Исполняемые доки TypeScript: Типы функций

Q: Как описать тип функции в TypeScript?

Используйте стрелочный синтаксис: (a: number, b: number) => number. Дайте ему имя через псевдоним типа, type Compare = (a: number, b: number) => number;, и используйте это имя для переменных, параметров и свойств. Имена параметров входят в синтаксис, но служат только документацией: функция с другими именами параметров тоже подходит.

Q: Как типизировать параметр-колбэк в TypeScript?

Укажите тип функции как тип параметра: function onEach(items: string[], cb: (item: string, index: number) => void) { ... }. Вызывающий код может передать функцию с меньшим числом параметров, а параметры самого колбэка выводятся из этого типа, так что onEach(list, (item) => ...) не требует аннотаций.

Q: Почему не стоит использовать тип Function в TypeScript?

Function принимает любую функцию, а её вызов не проверяется: разрешены любые аргументы, а результат имеет тип any. Напишите настоящую сигнатуру, например () => void или (value: string) => number, или (...args: never[]) => unknown, если вы действительно принимаете любую функцию.

Q: Чем тип функции отличается от сигнатуры вызова?

Они описывают одно и то же. (n: number) => string это сокращение для объектного типа { (n: number): string }. Форма с сигнатурой вызова нужна, когда у функции есть ещё и свойства, например { (n: number): string; label: string }.

Тип функции описывает её параметры и возвращаемое значение и записывается через стрелку: (a: number, b: number) => number. Дайте ему имя через type, и его можно использовать для переменных, параметров и свойств объектов.

type Operation = (a: number, b: number) => number;

const add: Operation = (a, b) => a + b;       // a and b are number
const multiply: Operation = (x, y) => x * y;  // names do not have to match

function apply(op: Operation, a: number, b: number): number {
  return op(a, b);
}

console.log(apply(add, 2, 3));      // 5
console.log(apply(multiply, 2, 3)); // 6

Функции, присвоенной add, аннотации не нужны: типы её параметров берутся из Operation. Это называется контекстной типизацией, и это главная причина давать типам функций имена.

Синтаксис типа функции

Форма такая: (parameters) => ReturnType. Каждому параметру нужны имя и тип. Имена нужны для читаемости и подсказок редактора; подходит любая функция с совместимыми типами параметров, как бы она их ни называла.

type Predicate = (value: number) => boolean;
type Formatter = (value: number, digits?: number) => string; // optional parameter
type Logger = (...parts: string[]) => void;                    // rest parameter
type Factory = () => { id: number };                           // no parameters

Имя не является необязательным. (string) => void объявляет параметр с именем string без типа, и строгий режим отвергает это с TS7051: Parameter has a name but no type. Did you mean 'arg0: string'?. Пишите (value: string) => void.

Типизация стрелочных функций

Стрелочную функцию можно типизировать двумя способами. Аннотировать саму функцию или аннотировать переменную типом функции, чтобы параметры вывелись.

// 1. Annotations on the function
const toCelsius = (f: number): number => ((f - 32) * 5) / 9;

// 2. A function type on the variable
const toFahrenheit: (c: number) => number = (c) => (c * 9) / 5 + 32;

// 3. The same, with a named type
type Convert = (value: number) => number;
const round1: Convert = (v) => Math.round(v * 10) / 10;

console.log(round1(toCelsius(100)));  // 37.8
console.log(toFahrenheit(37));        // 98.6

Форма 1 обычный выбор для самостоятельной функции. Форма 3 окупается, когда у нескольких функций одна сигнатура (обработчики, компараторы, конвертеры): сигнатура пишется один раз, и её изменение проверяется везде.

Типы колбэков

Параметр, тип которого является типом функции, это колбэк. Функция вызывающего кода проверяется по нему, а её параметры из него выводятся.

function repeat(times: number, action: (index: number) => void): void {
  for (let i = 0; i < times; i++) action(i);
}

repeat(3, (i) => console.log("run", i));

function mapValues(values: number[], fn: (value: number, index: number) => string): string[] {
  const out: string[] = [];
  values.forEach((v, i) => out.push(fn(v, i)));
  return out;
}

// A callback may ignore trailing parameters: this one takes only value.
console.log(mapValues([1.5, 2.25], (v) => v.toFixed(1))); // [ '1.5', '2.3' ]

Два правила делают колбэки удобными:

Меньше параметров можно. Функцию с одним параметром можно передать туда, где предлагаются два. JavaScript игнорирует лишние аргументы, поэтому TypeScript это разрешает. Больше параметров, чем предлагает тип, это ошибка (Target signature provides too few arguments.).
Возврат void принимает что угодно. Колбэк с типом (...) => void может вернуть значение; вызывающий код обещает его не использовать. Поэтому list.forEach((x) => other.push(x)) компилируется, хотя push возвращает число.

Типы параметров всё равно должны быть совместимы. Передача (x: string) => ... туда, где ожидается (a: number, b: number) => number, падает с Types of parameters 'x' and 'a' are incompatible.

Сигнатуры вызова

(n: number) => string это сокращение для объектного типа с сигнатурой вызова: { (n: number): string }. Длинная форма нужна, когда у функции есть ещё и свойства.

type Counter = {
  (): number;        // call signature: calling it returns a number
  count: number;     // and it has a property
  reset: () => void; // and a method
};

function makeCounter(): Counter {
  const fn = () => ++fn.count;
  fn.count = 0;
  fn.reset = () => { fn.count = 0; };
  return fn;
}

const next = makeCounter();
next();
next();
console.log(next(), next.count); // 3 3
next.reset();
console.log(next.count);         // 0

TypeScript позволяет добавлять свойства функции, объявленной через const, в той же области видимости и отслеживает их в типе функции. Сигнатуру вызова может содержать и интерфейс: interface Counter { (): number; count: number }.

Сигнатура конструирования описывает то, что вызывается через new. Перед ней добавляется new: new (name: string) => User или { new (name: string): User } в объектной форме. Так типизируют параметр, который получает класс.

Синтаксис метода и синтаксис свойства

В объектном типе функциональный член можно записать как метод, handle(value: string): void, или как свойство, хранящее функцию, handle: (value: string) => void. Выглядят они взаимозаменяемыми, но в режиме strict проверяются по-разному:

// This does not compile: the property form checks parameters strictly.
interface WithMethod { handle(value: string | number): void }
interface WithProperty { handle: (value: string | number) => void }

const onlyStrings = (value: string) => console.log(value.toUpperCase());

const a: WithMethod = { handle: onlyStrings };   // accepted
const b: WithProperty = { handle: onlyStrings }; // rejected
a.handle(42);

Компилятор сообщает:

index.ts(8,27): error TS2322: Type '(value: string) => void' is not assignable to type '(value: string | number) => void'.
  Types of parameters 'value' and 'value' are incompatible.
    Type 'string | number' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.

Ошибка справедлива: onlyStrings не умеет обрабатывать число. Форма метода пропускает ту же ошибку (параметры методов по историческим причинам проверяются «бивариантно»), и a.handle(42) упал бы во время выполнения с TypeError: value.toUpperCase is not a function. Удалите строку с b, чтобы увидеть это падение. Когда вы пишете свои объектные типы, форма свойства ловит больше.

Избегайте типа Function

Function это встроенный тип, которому соответствует любое значение-функция. Почти никогда это не то, что нужно: TypeScript не знает ни параметров, ни возвращаемого типа, поэтому любой вызов принимается и возвращает any.

const loose: Function = Math.max;
const result = loose("a", {});   // compiles: any arguments, result is any
console.log(result);             // NaN

const strict: (...values: number[]) => number = Math.max;
console.log(strict(3, 9, 4));    // 9
// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
strict("a");

Замените Function настоящей сигнатурой. Если вы действительно принимаете любую функцию (обобщённый debounce, обёртку для логирования), (...args: never[]) => unknown принимает любую функцию и при этом оставляет результат unknown, а не any. О функциях, типы которых зависят от входных данных, читайте на странице дженерики: обобщённый тип функции выглядит как <T>(value: T) => T.

Часто задаваемые вопросы

Как описать тип функции в TypeScript?

Используйте стрелочный синтаксис: (a: number, b: number) => number. Дайте ему имя через псевдоним типа, type Compare = (a: number, b: number) => number;, и используйте это имя для переменных, параметров и свойств. Имена параметров входят в синтаксис, но служат только документацией: функция с другими именами параметров тоже подходит.

Как типизировать параметр-колбэк в TypeScript?

Укажите тип функции как тип параметра: function onEach(items: string[], cb: (item: string, index: number) => void) { ... }. Вызывающий код может передать функцию с меньшим числом параметров, а параметры самого колбэка выводятся из этого типа, так что onEach(list, (item) => ...) не требует аннотаций.

Почему не стоит использовать тип Function в TypeScript?

Function принимает любую функцию, а её вызов не проверяется: разрешены любые аргументы, а результат имеет тип any. Напишите настоящую сигнатуру, например () => void или (value: string) => number, или (...args: never[]) => unknown, если вы действительно принимаете любую функцию.

Чем тип функции отличается от сигнатуры вызова?

Они описывают одно и то же. (n: number) => string это сокращение для объектного типа { (n: number): string }. Форма с сигнатурой вызова нужна, когда у функции есть ещё и свойства, например { (n: number): string; label: string }.

Как типизировать стрелочную функцию в TypeScript?

Либо аннотируйте её параметры и возвращаемый тип прямо на месте, const half = (n: number): number => n / 2;, либо дайте переменной тип функции, и параметры выведутся: const half: (n: number) => number = (n) => n / 2;.

Связанные концепции