void: почему колбэк может вернуть что угодно

Функция без return в JavaScript всё равно что-то отдаёт — undefined. В системе типов для этой ситуации есть отдельное имя: void. Писать его руками не обязательно, компилятор ставит его сам.

Убедиться проще всего трюком из статьи про сужение: присвоить результат переменной заведомо неподходящего типа и прочитать, что назовёт диагностика.

function save(name: string) {
  console.log("сохранил: " + name);
}
// намеренно врём с типом, чтобы компилятор сам назвал возврат save
const check: null = save("рико");
console.log(check);

«Тип "void" не может быть назначен для типа "null"» — вот и ответ: возврат вывелся как void, хотя никакой аннотации мы не писали. А на исполнении в check всё-таки лежит undefined — разницу между этими двумя ответами разбирает следующий раздел.

Аннотацию : void ставят, когда хотят закрепить намерение: «эта функция работает ради побочного эффекта, смотреть на её возврат незачем». Нарушить обещание прямо в теле функции нельзя.

function logTotal(items: number[]): void {
  let sum = 0;
  for (const item of items) {
    sum += item;
  }
  console.log("итого: " + sum);
  return sum;
}
logTotal([1, 2, 3]);

TS2322, «Тип "number" не может быть назначен для типа "void"», на строке с return sum. Диагностика есть, но, как всегда, ничего не отменяет: код выполнился, шестёрка напечаталась, а сама функция вернула её вызывающему — типы до браузера не доезжают.

Способов честно вернуть void ровно три, и все три равноправны.

function first(): void {
  console.log("про возврат не написано ни слова");
}
function second(flag: boolean): void {
  if (flag) {
    return; // выход без значения — это тоже void
  }
  console.log("сюда не дошли");
}
function third(): void {
  return undefined;
}
console.log(first(), second(true), third());

«Функция ничего не возвращает» — неточность. Возвращает: undefined. void говорит другое — что на этот возврат не надо смотреть.

На исполнении разницы между ними нет никакой: и void-функция, и функция с return undefined отдают одно и то же значение. В типах разница есть, и она односторонняя.

function save(): void {
  console.log("сохранил");
}
const result = save();
console.log(result);
const asUndefined: undefined = save();
console.log(asUndefined);

Печатается undefined, а присвоить это же самое значение переменной типа undefined компилятор не даёт: TS2322, «Тип "void" не может быть назначен для типа "undefined"».

Причина в смысле, а не в значении. undefined — обычный тип с ровно одним значением, и это значение вы вправе разглядывать. void — пометка «возврат есть, но он не для вас»; сегодня там undefined, а завтра автор функции решит что-то возвращать, и ваш код не должен от этого зависеть. Поэтому void не пускают никуда, где ждут конкретное значение.

function save(): void {
  console.log("сохранил");
}
const maybe: string | undefined = save();
console.log(maybe);
let box: void = undefined;
box = null;
console.log(box);

Две диагностики: void не лезет даже в string | undefined, где место под undefined явно есть, — а null в переменную типа void не лезет тем более. Обратное направление разрешено: undefined в void кладётся молча.

Последняя строка называет диагностику, которой в прошлых статьях не встречалось, — TS1345. Она ждёт вас в разделе про потерянный возврат, и там же станет понятно, почему запрет разумный.

const nothing = void 0;
console.log(nothing);
console.log(typeof nothing);

Теперь главная странность. Соберём удвоенные числа привычным способом — через forEach и push.

const doubled: number[] = [];
[1, 2, 3].forEach((n) => doubled.push(n * 2));
console.log(doubled);

Ни одной диагностики — и это удивительнее, чем кажется. push возвращает не undefined, а новую длину массива, то есть число. Стрелка без фигурных скобок этот результат отдаёт наружу. А в стандартной библиотеке forEach объявлен так: (value: T, index: number, array: T[]) => void. Число вместо void — и тишина.

Правило: если в типе слота стоит возврат void, туда разрешено класть функцию с любым возвратом. Значение просто выбросят. Работает это только тогда, когда тип приходит из контекста — из аннотации переменной, из сигнатуры параметра, из алиаса. Аннотация, написанная прямо на самой функции, остаётся обещанием, и его проверяют.

Четыре объявления ниже отличаются мелочами. Прежде чем запускать, отметьте, на каких строках будет диагностика.

type Job = () => void;
const one: Job = () => "готово";
const two: Job = () => {
  console.log("готово");
};
const three: () => string = () => {
  console.log("готово");
};
const four = (): void => "готово";
one();
two();
three();
four();

Зачем понадобилось послабление, видно из первого примера: без него doubled.push(n * 2) пришлось бы заворачивать в фигурные скобки только ради того, чтобы выбросить возврат. И так с каждым методом, который принимает колбэк «для побочного эффекта», — правило избавляет от этого налога всю стандартную библиотеку сразу.

const asNumber: () => number = () => {
  console.log("работаю");
};
console.log(asNumber());

Послабление касается только возврата. Параметры живут по обычным строгим правилам: пропустить лишний в колбэке можно, а объявить лишний — нет.

У послабления есть цена. «Возврат игнорируют» — это не «компилятор перестал следить»: значение действительно возвращается и на исполнении доступно, но тип выражения теперь void, и воспользоваться им не выйдет.

Самый частый случай — алиас для проверки, в котором забыли написать возврат.

type Check = (value: string) => void;
const filled: Check = (value) => value.trim() !== "";
const words = ["рико", "  ", "код"];
const good: string[] = [];
for (const word of words) {
  if (filled(word)) {
    good.push(word);
  }
}
console.log(good);

TS1345, «Выражение типа "void" не может быть проверено на истинность». Обиднее всего, что код совершенно правильный: запустите — и в консоли окажется ["рико", "код"], потому что стрелка и вправду возвращает boolean. Тип потерялся в момент присваивания в Check, и вернуть его на месте использования нечем.

Лечится это не приведением типа, а исправлением алиаса: type Check = (value: string) => boolean. Правило простое — void в типе колбэка означает «результат мне не нужен». Если он нужен, так и пишите.

Вторая половина той же беды — перепутать forEach с map. У forEach не только колбэк объявлен через void: он и сам возвращает void.

const scores = [3, 8, 5];
const bonus: number[] = scores.forEach((score) => score * 2);
console.log(bonus);

«Тип "void" не может быть назначен для типа "number[]"» — аннотация сработала как ловушка для опечатки. Обратите внимание, что про сам колбэк (score) => score * 2 компилятор не сказал ничего: по правилу из прошлого раздела он имеет полное право возвращать число.

const scores = [3, 8, 5];
const bonus = scores.forEach((score) => score * 2);
console.log(bonus);
console.log(scores.map((score) => score * 2));

У асинхронной функции без возврата тип не void, а Promise<void>: значение всё-таки есть — промис, и его можно дождаться. Правило из третьего раздела этой разницы не замечает, потому что не различает, что именно кладут в void-слот.

type Task = () => void;
const tasks: Task[] = [];
tasks.push(async () => {
  await Promise.resolve();
  console.log("задача выполнена");
});
function runAll(list: Task[]): void {
  for (const task of list) {
    task();
  }
  console.log("все задачи запущены");
}
runAll(tasks);

Порядок вывода — весь урок целиком: сначала «все задачи запущены», и только потом «задача выполнена». Диагностик нет ни одной. Промис, который вернула асинхронная стрелка, лёг в слот () => void и был выброшен; runAll вернулся, не дождавшись ничего, а ошибка внутри такой задачи стала бы необработанным отказом промиса.

В стандартной библиотеке эта история встречается на каждом шагу.

async function price(id: number): Promise<number> {
  await Promise.resolve();
  return id * 10;
}
const prices: number[] = [];
[1, 2, 3].forEach(async (id) => {
  prices.push(await price(id));
});
console.log(prices);

Пустой массив, и снова ни слова от компилятора. forEach обошёл все три элемента, запустил три асинхронные функции, получил от каждой промис, выбросил его — и вернул управление раньше, чем отработал первый await. Заполнится prices позже, когда его уже никто не читает.

Починка не в том, чтобы уговорить forEach ждать, — он не умеет. Нужен метод, чей колбэк возвращает значение.

async function price(id: number): Promise<number> {
  await Promise.resolve();
  return id * 10;
}
async function main(): Promise<void> {
  // map отдаёт Promise<number>[], потому что его колбэк возвращает не void
  const prices = await Promise.all([1, 2, 3].map((id) => price(id)));
  console.log(prices);
}
main();

У map в сигнатуре стоит => U, а не => void: возврат колбэка становится частью типа результата, и промисы никуда не деваются. Обычный for..of с await внутри годится не хуже — он ждёт по очереди, Promise.all запускает всё сразу. Такие места умеет находить и линтер: правило no-misused-promises ловит forEach с асинхронной стрелкой, подробнее о нём — в статье «typescript-eslint: правила, которых нет у компилятора».

Правило на каждый день: увидели async-стрелку в аргументе — проверьте по сигнатуре, ждёт ли её тот, кому вы её отдаёте.

type Task = () => Promise<void>;
const tasks: Task[] = [];
tasks.push(() => {
  console.log("синхронная задача");
});
console.log(tasks.length);