TypeScript Any, Unknown And Never
The TypeScript any vs unknown choice is one of the most important decisions you will make when handling uncertain data. Both types can hold any value, but they treat type safety in opposite ways. The never type is the third piece: it represents values that should not exist. Together, these three types control how safely your code handles the unknown.
This tutorial explains what each type does, why any removes safety, how unknown keeps it, and how never helps with exhaustive checking. You will see real code for parsing JSON safely and for catching a missing switch case at compile time. By the end, you will know when to use each type and why unknown is usually the better default.
What Are any, unknown, and never in TypeScript?
any disables type checking for a value, allowing any operation. unknown accepts any value but requires a check before you use it. never represents a value that can never occur, such as a function that always throws. These three types sit at opposite ends of the type-safety scale.
Here is a quick look at the difference:
let loose: any = "hello";
loose.toUpperCase(); // allowed, no check
loose = 42; // allowed
let safe: unknown = "hello";
// safe.toUpperCase();
// Error: 'safe' is of type 'unknown'.
if (typeof safe === "string") {
safe.toUpperCase(); // allowed after the check
}
// Output: (no runtime output for this snippet)
The any variable accepts everything and allows everything. The unknown variable accepts everything but allows nothing until you prove the type with a check.
What Does any Do and Why Does It Remove Type Safety?
The any type tells TypeScript to stop checking. A value typed as any can be assigned to any variable, called as a function, and have any property accessed. There is no compile-time protection. This is why avoid any is a common rule in strict codebases.
function processInput(data: any): void {
console.log(data.toUpperCase());
}
processInput("hello");
processInput(123);
// Output: HELLO
// Runtime error: data.toUpperCase is not a function
How it works: The compiler does not check whether data has toUpperCase. The first call works because a string has that method. The second call crashes at runtime because a number does not. The compiler gave no warning, so the bug reached production. This is the danger of any: it moves errors from compile time to runtime.
How Is unknown the Safe Alternative?
The unknown type is the type-safe counterpart of any. It can hold any value, but you cannot use the value until you narrow it with a check like typeof, instanceof, or a custom type guard. Narrowing means proving the type to the compiler so it allows the operation.
function printLength(value: unknown): void {
if (typeof value === "string") {
console.log(value.length);
} else {
console.log("Not a string");
}
}
printLength("TypeScript");
printLength(42);
// Output: 10
// Output: Not a string
How it works: Inside the if, TypeScript knows value is a string because of the typeof check. It allows .length. In the else branch, value is still unknown, so you cannot call string methods on it. This forces you to handle each case explicitly, which is exactly what safe code should do. The Type Guards & Narrowing tutorial covers more narrowing patterns.
How Do You Narrow unknown Safely?
Narrowing unknown usually uses typeof for primitives, Array.isArray for arrays, and instanceof for class instances. For objects, you check that the value is not null and has the properties you expect.
type User = { name: string; age: number };
function isUser(value: unknown): value is User {
return (
typeof value === "object" &&
value !== null &&
"name" in value &&
"age" in value
);
}
function showUser(value: unknown): void {
if (isUser(value)) {
console.log(`${value.name} is ${value.age}.`);
} else {
console.log("Invalid user data");
}
}
showUser({ name: "Riya", age: 28 });
showUser("not a user");
// Output: Riya is 28.
// Output: Invalid user data
How it works: isUser is a type guard: a function whose return type is value is User. When it returns true, TypeScript treats value as a User inside the if. The checks inside isUser verify the shape at runtime. This pattern is essential when you receive data from an API or JSON.parse.
What Is the never Type?
The never type represents a value that cannot exist. Functions that always throw an error or loop forever return never. It is also used to mark impossible branches in a switch, which gives you exhaustive checking: the compiler confirms you handled every case.
function fail(message: string): never {
throw new Error(message);
}
// fail("Something went wrong");
// Uncaught Error: Something went wrong
How it works: The fail function never returns normally. Its return type is never, which means no value comes back. If you tried to assign its return to a variable, TypeScript would know that line is unreachable. This is useful for error helpers and for functions that must stop execution.
How Do You Use never for Exhaustive Checking?
Exhaustive checking means proving that every possible case is handled. In a switch over a union, you can add a default branch that assigns the value to never. If a new case is added later and not handled, the compiler reports an error.
type PaymentStatus = "created" | "paid" | "refunded";
function describeStatus(status: PaymentStatus): string {
switch (status) {
case "created":
return "Awaiting payment.";
case "paid":
return "Payment received.";
case "refunded":
return "Money returned.";
default:
return assertNever(status);
}
}
function assertNever(value: never): never {
throw new Error(`Unexpected value: ${String(value)}`);
}
console.log(describeStatus("paid"));
// Output: Payment received.
How it works: If every case is handled, status in the default branch is narrowed to never. Passing it to assertNever compiles. If someone later adds "cancelled" to PaymentStatus without adding a case, the default branch receives a string value that is not never, and the compiler reports an error. This catches missing cases at build time, before users see a bug.
What Is the Difference Between void and never?
void means a function returns no useful value, but it does return normally. never means a function never returns at all. A function that logs a message returns void. A function that always throws returns never.
function logMessage(message: string): void {
console.log(message);
}
function failHard(): never {
throw new Error("Stopped");
}
logMessage("Hello");
// Output: Hello
How it works: logMessage finishes its work and returns. Its return type is void. failHard never reaches a return statement; it throws every time. Its return type is never. You cannot assign a void result to anything useful, and you cannot call code after a never function returns because it never returns.
Comparison: any vs unknown vs never
| Feature | any | unknown | never |
|---|---|---|---|
| Accepts any value | Yes | Yes | No |
| Can be used without a check | Yes | No | No |
| Type safety | None | High (after narrowing) | N/A |
| Common use | Legacy code, escape hatch | API input, JSON.parse |
Errors, exhaustive switches |
| Assignable to other types | Yes | No (must narrow) | Yes (to anything) |
| Recommended | Avoid | Prefer over any | Use for impossible states |
Common Mistakes and Best Practices
- Reaching for
anyto silence an error. This hides the problem instead of fixing it. Useunknownand narrow it, or write a type guard. The compiler is telling you something for a reason. - Turning off
noImplicitAny. This option, on by default under"strict": true, stops untyped parameters from silently becomingany. Keep it on so every value has a real type. - Treating
unknownlikeanyby casting immediately. Writing(value as string)bypasses the check. Narrow withtypeofor a type guard so the safety actually works. - Forgetting the
defaultbranch in a switch over a union. WithoutassertNever, adding a new union member does not trigger a compile error, so a case can be missed silently. - Using
neveras a variable type by mistake.neveris for return types and impossible states. A variable of typenevercan never be assigned a value, so the code is useless.
Real-World Example: Safe JSON Parsing and Exhaustive Handling
This example parses unknown JSON safely and uses never in an exhaustive switch.
type ApiResponse =
| { status: "ok"; data: { name: string } }
| { status: "error"; message: string };
function parseResponse(raw: unknown): ApiResponse {
if (
typeof raw === "object" &&
raw !== null &&
"status" in raw &&
(raw as { status: unknown }).status === "ok" &&
"data" in raw &&
typeof (raw as { data: unknown }).data === "object" &&
(raw as { data: unknown }).data !== null &&
"name" in ((raw as { data: object }).data)
) {
const data = (raw as { data: { name: string } }).data;
return { status: "ok", data: { name: data.name } };
}
return { status: "error", message: "Invalid response" };
}
function handleResponse(response: ApiResponse): string {
switch (response.status) {
case "ok":
return `Hello, ${response.data.name}!`;
case "error":
return `Error: ${response.message}`;
default:
return assertNever(response);
}
}
function assertNever(value: never): never {
throw new Error(`Unexpected: ${String(value)}`);
}
const good = parseResponse({ status: "ok", data: { name: "Anaya" } });
const bad = parseResponse("broken");
console.log(handleResponse(good));
console.log(handleResponse(bad));
// Output: Hello, Anaya!
// Output: Error: Invalid response
How it works, line by line. parseResponse accepts unknown, so any input is allowed. It checks typeof raw === "object" and raw !== null before reading properties. It verifies the status field and the nested data.name field. If the shape matches, it returns the ok variant. Otherwise, it returns the error variant. handleResponse switches on response.status. Because ApiResponse is a union, TypeScript narrows response in each case. The default branch calls assertNever, which only compiles if response is never, proving every case is handled. If you added a third variant to ApiResponse and forgot a case, the compiler would stop you. This is the combined power of unknown, union types, and never.
Summary
- The TypeScript any vs unknown choice decides whether type safety is on or off:
anyturns it off,unknownkeeps it on. anyallows every operation and moves errors to runtime; avoid any in new code.unknownrequires narrowing withtypeof,in, or type guards before use.nevermarks impossible values, including functions that always throw and unreachable switch branches.- Exhaustive checking with
neverin adefaultbranch catches missing cases at compile time. voidmeans a function returns normally with no value;nevermeans it never returns at all.
Now that you can handle uncertain and impossible values, continue to the TypeScript Interfaces tutorial to learn how to describe the shape of objects cleanly.
Frequently Asked Questions
Is any ever useful in TypeScript?
It can be useful when you migrate old JavaScript code or interact with a library that has no types. Use it in small, isolated places and add a comment explaining why. For new code, prefer unknown because it keeps safety while still accepting any value. Treat any as an escape hatch, not a default.
Why can I not use an unknown value directly?
Because unknown means the compiler has no information about the type. Allowing any operation would be unsafe. You must narrow the value first with a check like typeof value === "string" or a custom type guard. After the check, TypeScript knows the narrowed type and allows the correct operations.
What is the difference between never and void?
void means a function returns no value but does return normally. never means the function never returns at all, usually because it throws or loops forever. A logging function returns void; a function that always throws returns never. never is also used for impossible branches in exhaustive checks.
How does assertNever help catch missing cases?
assertNever accepts a parameter of type never. In a switch over a union, if all cases are handled, the default branch narrows to never and compiles. If a new union member is added and not handled, the default branch receives that member, which is not never, and the compiler reports an error. This turns a runtime bug into a compile-time error.
Should I enable noImplicitAny in my project?
Yes. noImplicitAny is part of "strict": true and stops untyped parameters from silently becoming any. Without it, you can write functions with untyped parameters and lose type safety without noticing. Keep it on so every value has a known type, and fix the errors it reports.
Practice Exercises
Exercise 1 (Easy): Replace any with unknown
Rewrite a function that currently accepts any and calls .toUpperCase() so it accepts unknown and narrows with typeof first.
Show solution
function shout(value: unknown): void {
if (typeof value === "string") {
console.log(value.toUpperCase());
} else {
console.log("Not a string");
}
}
shout("hello");
shout(42);
// Output: HELLO
// Output: Not a string
The typeof check narrows value to string before calling .toUpperCase(), so no runtime crash occurs.
Exercise 2 (Easy): Write a never Function
Write a function fail that accepts a string message and always throws. Give it the never return type.
Show solution
function fail(message: string): never {
throw new Error(message);
}
// fail("Stopped");
// Uncaught Error: Stopped
The function never reaches a return statement, so never is the correct return type.
Exercise 3 (Medium): Exhaustive Switch with assertNever
Create a union type Shape = "circle" | "square" | "triangle". Write a function with a switch that handles each case and uses assertNever in the default branch.
Show solution
type Shape = "circle" | "square" | "triangle";
function sides(shape: Shape): number {
switch (shape) {
case "circle":
return 0;
case "square":
return 4;
case "triangle":
return 3;
default:
return assertNever(shape);
}
}
function assertNever(value: never): never {
throw new Error(`Unexpected shape: ${String(value)}`);
}
console.log(sides("circle"));
console.log(sides("square"));
// Output: 0
// Output: 4
If a fourth shape is added to the union and not handled, the default branch no longer receives never, and the compiler reports an error.
Exercise 4 (Challenge): Safe Parse of unknown JSON
Write a function parseName that accepts unknown and returns a string. It should return the name property if the input is an object with a string name, and "Unknown" otherwise.
Show solution
function parseName(value: unknown): string {
if (
typeof value === "object" &&
value !== null &&
"name" in value &&
typeof (value as { name: unknown }).name === "string"
) {
return (value as { name: string }).name;
}
return "Unknown";
}
console.log(parseName({ name: "Vikram" }));
console.log(parseName({ name: 42 }));
console.log(parseName("text"));
// Output: Vikram
// Output: Unknown
// Output: Unknown
Each check narrows the type step by step: first object, then not null, then the name property, then the property type. Only after all checks does the cast to { name: string } become safe.
Written by Shaikh Abdul Shahid
A Full-Stack Developer with experience in PHP, Laravel, JavaScript, and React.
Founder of Online Learner, sharing practical knowledge and programming tutorials.
Building and maintaining real-world web applications since 2017.
Your Feedback
Help us improve by sharing your thoughts.
Online Learner helps developers master programming, database concepts, interview preparation, and real-world implementation through structured learning paths.
Quick Links
© 2023 - 2026 OnlineLearner.in | All Rights Reserved.
