This content originally appeared on Level Up Coding - Medium and was authored by Vivek Garg
If you’ve ever worked with TypeScript for more than 5 minutes, you’ve probably met its “wild child”: the any type. It’s like giving someone a blank check – you can do whatever you want with it, but you also risk losing all the safety that TypeScript promised in the first place.
That’s where unknown comes in. Think of unknown as any’s more responsible older sibling. It still allows flexibility, but it says:
“Sure, you can use me… but first, prove you know what you’re doing!”
In this blog, we’ll go from beginner to expert level about unknown. We’ll cover why it was introduced, how it solves problems, when to use it, when to avoid it, and sprinkle in some real-world code examples (and maybe a little humor). Buckle up! 🚀
Beginner Level => What is unknown?
In simple terms:
- any = “I don’t care, do whatever you want.”
- unknown = “I don’t know yet, so you need to prove it before using me.”
Think of unknown as a locked treasure chest. You know something is inside, but TypeScript won’t let you use it until you have the right type-checking key.
let anything: any = "Hello World!";
anything.trim(); // Works (even if anything was not a string)
let mystery: unknown = "Hello World!";
// mystery.trim(); ❌ Error: Object is of type 'unknown'
With unknown, TypeScript stops you from doing random stuff without checking the type.
Why unknown was introduced 🤔
Before TypeScript 3.0, developers only had any for unknown values. But using any is basically turning TypeScript into plain JavaScript – zero type safety.
So the TypeScript team introduced unknown to:
- Keep flexibility (accept anything at first).
- Force validation before usage.
- Prevent runtime errors by making developers more cautious.
In other words: any = YOLO 😎, unknown = "Hold my coffee ☕, let’s check this carefully."
Intermediate Level => How to Use unknown
Since you can’t directly operate on unknown, you must narrow it down before use.
1. Using Type Guards
function processValue(value: unknown) {
if (typeof value === "string") {
console.log("String length:", value.length);
} else if (typeof value === "number") {
console.log("Number squared:", value * value);
} else {
console.log("Unknown type 🤷");
}
}2. Using Type Assertions
If you’re sure of the type, you can assert it:
llet input: unknown = "typescript";
console.log((input as string).toUpperCase()); // ✅ Safe (if you're sure)
But careful: abusing type assertions defeats the purpose of unknown. It’s like wearing a helmet but not buckling it. 🚴♂️
3. With Generics
unknown plays nicely with generics when you want to represent truly flexible but checked types.
function logUnknown<T extends unknown>(value: T) {
console.log(value);
}It basically says: “I don’t know what T will be, but I’ll respect whatever comes.”
unknown vs any
let a: any = 10;
let b: unknown = 20;
let num: number;
// Works with any
num = a; // no problem
// Error with unknown
num = b; // ❌ Type 'unknown' is not assignable to type 'number'
This extra step saves you from bugs like calling .toUpperCase() on a number.
Union & Intersection with unknown
- Union: unknown | T simplifies to unknown.
- Intersection: unknown & T simplifies to T.
Example:
type A = unknown | string; // unknown
type B = unknown & string; // string
This behavior makes sense:
- If something could be unknown, it overshadows everything in a union.
- But in intersection, unknown politely steps aside.
never vs unknown
- never: represents a value that never occurs.
- unknown: represents any possible value, but unknown to us.
Think of it like this:
- never = “This road is closed forever.” 🚧
- unknown = “This road might lead anywhere, but check the map first.” 🗺️
Expert Level=> Advanced Use Cases 🚀
Now let’s go deeper.
a) Safe API Handling
When consuming APIs, you rarely trust the data blindly:
function fetchData(): unknown {
return JSON.parse('{"name": "Alice"}');
}
let response = fetchData();
if (typeof response === "object" && response !== null && "name" in response) {
console.log((response as { name: string }).name);
}b) Exhaustive Type Guards
You can combine unknown with custom type guards:
function isUser(obj: unknown): obj is { name: string } {
return typeof obj === "object" && obj !== null && "name" in obj;
}
let data: unknown = { name: "Bob" };
if (isUser(data)) {
console.log(data.name); // Safe access
}c) Utility Types with unknown
TypeScript’s built-in utilities use unknown under the hood. For example, ReturnType<T> and Awaited<T> rely on it to handle values that could be anything.
Pros and Cons of unknown
Let’s be brutally honest:
✅ Pros:
1. Safer than any (forces you to check types).
2. Great for working with external/untrusted data.
3. Encourages better coding habits.
4. Plays well with generics and utility types.
❌ Cons:
1. Slightly more verbose (you must narrow types).
2. Might feel annoying if you “just want it to work.”
3. Can be abused with type assertions (which ruins the point).
When Should You Use unknown?
- When working with external input (e.g., API response, user input).
- When parsing dynamic JSON.
- In utility functions where type is not known upfront.
- When writing libraries that need maximum flexibility but still enforce safety
- Conclusion: Unknown, But Not Unloved ❤️
function parseJson(json: string): unknown {
return JSON.parse(json);
}
let data = parseJson('{"name": "Vivek"}');
// Must check before use
if (typeof data === "object" && data !== null && "name" in data) {
console.log((data as { name: string }).name);
}Conclusion 🎯
The unknown type is TypeScript’s gentle way of saying:
“I’ll give you freedom, but with responsibilities.”
It’s not here to make your life harder. It’s here to save you from any-induced chaos. Think of it as JavaScript’s safety net that still lets you play acrobat.
So next time you feel tempted to use any, ask yourself:
👉 “Do I really want to live dangerously, or should I let unknown keep me safe?”
Your future self debugging at 3 AM will thank you. 😅
Why TypeScript Introduced ‘unknown' was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Vivek Garg
Vivek Garg | Sciencx (2025-08-28T20:42:21+00:00) Why TypeScript Introduced ‘unknown’. Retrieved from https://www.scien.cx/2025/08/28/why-typescript-introduced-unknown/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.