When working with TypeScript, type safety is paramount. The unknown type, introduced in TypeScript 3.0, provides a type-safe alternative to any, helping developers write more robust and secure code. Let’s explore how to effectively use this powerful feature.
The unknown type is TypeScript’s type-safe counterpart to any. While any allows you to do anything with a value (essentially turning off type checking), unknown enforces strict type checking and requires type verification before performing operations.
Table of Contents
- Understanding the Unknown Type
- Type Checking with Unknown
- Best Practices for Unknown Type
- Common Pitfalls to Avoid
- Integration with Existing Code
- Conclusion
Understanding the Unknown Type
Let’s start with a basic example of how unknown differs from any:
let valueAny: any = 10;
let valueUnknown: unknown = 10;
// This works fine with 'any'
valueAny.toString();
// This will cause a TypeScript error
// valueUnknown.toString(); // Error: Object is of type 'unknown'
Code language: JavaScript (javascript)Type Checking with Unknown
To work with unknown values, you need to perform type checks before using them. Here are the common patterns:
Using Type Guards
function processValue(value: unknown): string {
if (typeof value === 'string') {
return value.toUpperCase(); // TypeScript knows value is a string
}
if (typeof value === 'number') {
return value.toString(); // TypeScript knows value is a number
}
return 'Unknown value';
}
Code language: JavaScript (javascript)Using Type Assertion
function processApiResponse(response: unknown) {
const data = response as { id: number; name: string };
console.log(data.id, data.name);
}
Code language: JavaScript (javascript)Best Practices for Unknown Type
1. Use Unknown for API Responses
async function fetchData(): Promise<unknown> {
const response = await fetch('https://api.example.com/data');
return response.json();
}
async function processData() {
const data = await fetchData();
if (typeof data === 'object' && data !== null && 'status' in data) {
// Now TypeScript knows data has a 'status' property
console.log((data as { status: string }).status);
}
}
Code language: JavaScript (javascript)2. Creating Type-Safe Error Handling
function handleError(error: unknown) {
if (error instanceof Error) {
console.error(error.message);
return;
}
console.error('An unknown error occurred:', error);
}
Code language: JavaScript (javascript)3. Generic Functions with Unknown
function validateInput<T>(value: unknown, validator: (value: unknown) => value is T): T {
if (validator(value)) {
return value;
}
throw new Error('Invalid input');
}
// Usage
type User = { id: number; name: string };
function isUser(value: unknown): value is User {
return (
typeof value === 'object' &&
value !== null &&
'id' in value &&
'name' in value &&
typeof (value as User).id === 'number' &&
typeof (value as User).name === 'string'
);
}
const data: unknown = { id: 1, name: 'John' };
const user = validateInput(data, isUser);
Code language: JavaScript (javascript)Common Pitfalls to Avoid
Don’t Use Type Assertion Without Checks
// Bad practice
function processData(data: unknown) {
const value = data as string; // Unsafe!
return value.toUpperCase();
}
// Good practice
function processData(data: unknown) {
if (typeof data === 'string') {
return data.toUpperCase();
}
throw new Error('Expected string input');
}
Code language: JavaScript (javascript)Avoid Nested Unknown Types
// Avoid this
type ComplexType = {
data: unknown;
metadata: unknown;
};
// Better approach
type ComplexType<T, M> = {
data: T;
metadata: M;
};
Code language: JavaScript (javascript)Integration with Existing Code
When working with existing code that uses any, you can gradually migrate to unknown for better type safety:
// Before
function processLegacyData(data: any) {
return data.toString();
}
// After
function processLegacyData(data: unknown) {
if (data === null || data === undefined) {
return 'null or undefined';
}
return String(data);
}
Code language: JavaScript (javascript)Conclusion
The unknown type is a powerful feature in TypeScript that helps write more type-safe code. By enforcing explicit type checks, it reduces runtime errors and makes code more maintainable. When working with external data or API responses, prefer unknown over any to ensure proper type checking.
Start incorporating unknown in your TypeScript projects, especially when dealing with data of uncertain types. Remember to always perform proper type checks before operating on unknown values, and use type assertions only when you’re absolutely certain about the type.
For more TypeScript type safety features, check out our guide on TypeScript Type Guards which complements the usage of the unknown type perfectly.
