The unknown type is a type-safe counterpart to any. While any completely disables type checking, unknown represents a value that could be anything but forces you to perform type checking (like type guards, assertions, or instanceof) before you can operate on it.
In TypeScript, both any and unknown are top types, meaning they can hold any value. However, they serve fundamentally different purposes in terms of type safety. any is the escape hatch from the type system—it tells the compiler to completely opt out of type checking for that value, allowing any operation without restriction. unknown is the type-safe alternative: it also accepts any value, but it requires you to first prove the type through some form of narrowing (like typeof, instanceof, or a custom type guard) before you can perform operations on it.
Type Safety:
anydisables all type checking;unknownrequires type narrowing before operations.Property Access:
anyallows access to any property;unknowndisallows property access entirely until the type is narrowed.Function Calls:
anyallows being called as a function;unknowncannot be called without first proving it's a function.Arithmetic:
anycan be used in arithmetic operations;unknowncannot.Assignability:
anycan be assigned to any other type;unknowncan only be assigned toanyorunknownwithout a type assertion.Spread in Objects:
anycan be spread into an object;unknowncannot be spread without prior validation.
Use
unknownwhen: You receive values from truly dynamic sources (APIs, user input,JSON.parse) and need to validate them before use. This is the recommended practice for handling external data.Use
anywhen: You are migrating a JavaScript project to TypeScript incrementally and need a quick escape hatch, or when working with third-party libraries that are genuinely impossible to type. However, even then, preferunknownwith type guards.Never use
anyas a shortcut to silence type errors. It defeats the purpose of using TypeScript. Preferunknownor more specific types.Use
unknownin catch blocks: The caught error in acatchblock is typed asunknown, forcing you to check its type (e.g.,if (error instanceof Error)) before accessingerror.message.Use
unknownin generic constraints: When you need to accept any type but still enforce type safety later, useT extends unknown(though this is rarely needed explicitly).