any и unknown в TypeScript: разница и когда что использовать

И any, и unknown принимают любое значение. Разница в том, что можно делать со значением дальше: any позволяет что угодно и ничего не проверяет, а unknown почти ничего не позволяет, пока вы не докажете, что это за значение.

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

Без строки @ts-expect-error вызов u.toUpperCase() был бы ошибкой компиляции TS18046. Проверка typeof сужает u до string, и внутри этого блока доступны все методы строки.

any и unknown коротко

В терминах теории типов unknown это верхний тип: любой тип присваивается ему, а сам он присваивается только unknown и any. any это лазейка, которая присваивается в обе стороны, всему, кроме never.

any отключает проверку типов

Значению с типом any доверяют вслепую. Компилятор принимает опечатки, неверные типы и отсутствующие свойства, и ошибки всплывают уже во время выполнения.

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

Вывод показывает проблему: переменная с аннотацией number хранит строку, а последняя строка выбрасывает Cannot read properties of undefined (reading 'city'). Кроме того, any распространяется. user.name имеет тип any, поэтому любое значение, вычисленное из него, тоже any, и одно нетипизированное значение может отключить проверку далеко от того места, где оно появилось.

unknown заставляет сначала проверить

С unknown компилятор отвергает любую операцию, пока код не сузит значение. Сужение делается обычными проверками JavaScript, и внутри каждой ветки значение имеет проверенный тип.

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

Проверка value === null должна идти перед проверкой на объект, потому что typeof null это "object". После "id" in value TypeScript знает, что у объекта есть свойство id с типом unknown, ведь ничто не говорит, что в нём хранится. String() явно превращает его в текст; чтобы использовать его как число, сначала проверьте его через typeof.

Проверку можно пропустить и с помощью утверждения value as string, и компилятор его примет. Это обещание без какой-либо проверки во время выполнения, поэтому предпочитайте настоящую проверку; см. утверждения типов.

Проверка JSON через unknown

JSON.parse объявлен как возвращающий any, поэтому его результат молча отключает проверку. Аннотируйте результат как unknown и напишите защитник типа, который проверяет структуру, прежде чем остальной код станет ей доверять.

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

Первый ввод печатает dark at 14px, второй отвергается, потому что в нём нет fontSize. С any второй ввод прошёл бы дальше как Settings с неопределённым fontSize. Для больших схем ту же работу делает библиотека валидации, которая ещё и выводит тип за вас.

noImplicitAny

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

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

Исправление это аннотация: function double(x: number). Явная запись x: any тоже компилируется, и в этом весь смысл: any остаётся видимым в коде, его можно найти поиском и проверить на ревью.

Где any всё ещё пробирается

Даже при strict эти источники дают any, хотя самого слова в вашем коде нет:

Переменная catch при strict имеет тип unknown, потому что выбросить можно что угодно, а не только объекты Error. Сузьте её через e instanceof Error, прежде чем читать e.message.

Когда any допустим

any не запрещён, но каждое его использование это место, которое компилятор больше не защищает. Разумные случаи:

• Миграция кодовой базы на JavaScript, где any отмечает то, что ещё не типизировано.
• Код, который система типов не может хорошо выразить, небольшой и скрытый за типизированной сигнатурой функции.
• Тестовый код, который намеренно передаёт неверные данные.

Для всего остального unknown покрывает тот же случай «я не знаю этот тип», сохраняя проверки. Многие команды закрепляют это правилом линтера @typescript-eslint/no-explicit-any. Родственный тип Record<string, unknown> это обычный выбор для «какого-то объекта с неизвестными значениями».