any vs unknown w TypeScript: różnice i kiedy którego użyć

any i unknown przyjmują każdą wartość. Różnica polega na tym, co możesz z tą wartością potem zrobić: any pozwala na wszystko i niczego nie sprawdza, a unknown nie pozwala prawie na nic, dopóki nie udowodnisz, czym jest wartość.

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
}

Bez linii @ts-expect-error wywołanie u.toUpperCase() to błąd kompilacji TS18046. Sprawdzenie typeof zawęża u do string i wewnątrz tego bloku dostępna jest każda metoda napisów.

any vs unknown w skrócie

W terminologii teorii typów unknown to typ górny: każdy typ da się do niego przypisać, a on sam da się przypisać tylko do unknown i any. any to furtka awaryjna przypisywalna w obie strony, do wszystkiego poza never.

any wyłącza sprawdzanie typów

Wartości typu any kompilator ufa na ślepo. Akceptuje literówki, złe typy i brakujące właściwości, a błędy wychodzą dopiero w czasie działania.

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

Wynik pokazuje problem: zmienna z adnotacją number przechowuje napis, a ostatnia linia rzuca Cannot read properties of undefined (reading 'city'). any też się rozprzestrzenia. user.name jest typu any, więc każda wartość z niego obliczona jest any, a jedna nieotypowana wartość może wyłączyć sprawdzanie daleko od miejsca, w którym się pojawiła.

unknown każe najpierw sprawdzić

Przy unknown kompilator odrzuca każdą operację, dopóki kod nie zawęzi wartości. Zawężanie używa zwykłych sprawdzeń JavaScriptu, a w każdej gałęzi wartość ma sprawdzony typ.

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

Sprawdzenie value === null musi być przed sprawdzeniem obiektu, bo typeof null to "object". Po "id" in value TypeScript wie, że obiekt ma właściwość id typu unknown, bo nic nie mówi, co ona zawiera. String() jawnie zamienia ją na tekst; żeby użyć jej jako liczby, trzeba ją najpierw sprawdzić przez typeof.

Możesz też pominąć sprawdzenie asercją value as string i kompilator ją zaakceptuje. To obietnica bez żadnego sprawdzenia w czasie działania, więc lepiej wybierz prawdziwe sprawdzenie; zobacz asercje typów.

Walidacja JSON z unknown

JSON.parse jest zadeklarowane jako zwracające any, więc jego wynik po cichu wyłącza sprawdzanie. Dodaj do wyniku adnotację unknown i napisz strażnika typu, który sprawdzi kształt, zanim reszta kodu mu zaufa.

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

Pierwsze wejście wypisuje dark at 14px, drugie zostaje odrzucone, bo brakuje fontSize. Z any drugie wejście przeszłoby dalej jako Settings z niezdefiniowanym fontSize. Przy dużych schematach tę samą pracę wykonuje biblioteka walidująca, która przy okazji wyprowadza typ.

noImplicitAny

any bierze się nie tylko stąd, że ktoś go napisał. Parametr bez adnotacji i bez kontekstu, z którego można wywnioskować typ, też byłby any. Opcja noImplicitAny, włączana przez strict, zgłasza to jako błąd:

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

Poprawka to adnotacja, function double(x: number). Jawne napisanie x: any też się kompiluje i o to właśnie chodzi: any pozostaje widoczne w kodzie, więc można je wyszukać i przejrzeć.

Gdzie any nadal się wkrada

Nawet przy strict poniższe przypadki dają any, choć to słowo nie pojawia się w twoim kodzie:

Zmienna w catch jest typu unknown przy strict, bo rzucić można cokolwiek, nie tylko obiekty Error. Zawęź ją przez e instanceof Error, zanim odczytasz e.message.

Kiedy any jest dopuszczalne

any nie jest zakazane, ale każde użycie to miejsce, którego kompilator już nie chroni. Rozsądne zastosowania:

• Migracja projektu JavaScript, gdzie any oznacza to, co nie ma jeszcze typów.
• Kod, którego system typów nie potrafi dobrze wyrazić, trzymany w małym zakresie za otypowaną sygnaturą funkcji.
• Kod testów, który celowo przekazuje złe dane.

We wszystkich innych przypadkach unknown obsługuje tę samą sytuację „nie znam tego typu”, zachowując sprawdzanie. Wiele zespołów wymusza to regułą lintera @typescript-eslint/no-explicit-any. Pokrewny typ, Record<string, unknown>, to zwykły wybór dla „jakiegoś obiektu o nieznanych wartościach”.