Support typed errors in query functions and mutations

[nirtamir2]

Background

I’ve been rethinking error handling in TypeScript.

In TypeScript, throwing errors causes the error type to be unknown. To refine it, we need instanceof checks or type guards, but we don’t get type safety for domain-specific error values.

A common alternative is the Result pattern:

type Result<Data, Error> =
  | { data: NonNullable<Data>; error: null }
  | { data: null; error: NonNullable<Error> }

Libraries like Effect and neverthrow use this to provide type safety and better error modeling.

---

The Problem

To make this work with TanStack Query today, we need to do something like:

queryFn: async () => {
  const response = await clientApi.GET("/api");
  if (response.data == null) {
    throw response.error; // loses type information
  }
  return response.data;
},

This allows onError to catch errors, but we lose type information about what those errors are.

If we instead return errors as part of the queryFn:

queryFn: async () => {
  return await clientApi.GET("/api");
},

we preserve type safety, but the code becomes misleading (errors look like successes).

const query = useQuery({
queryFn
})

if(query.isSuccess){
	if(query.data.error != null){
	  // handle typed query.data.data
   }
   else {
	  // handle typed query.data.error
   }
}


if(query.isError){
	  // handle query.error in type Error (unknown error)
   }
}

It also risks breaking built-in mechanisms like retries and suspense - because the call looks like a success but it failed internall.

---

What I’d Like

As a user, I want to express my code in terms of success and failure while retaining type safety for known errors.
I would like to introcude the distinction between a success API that returns error, and success API that returns success data and API failure. Maybe we can create a function that will tell tanstack query how to extract the error / data from the success data, and will pipe the data to data, error and defect (current tanstack error)

We can add a function like extractSuccessValue<T, E>: (value: T | E) => T | null that can somehow split the success value that contains error to a differect value / callback.

const query = useQuery({
  queryFn: async (): Promise<Result<string[], { code: "NotFound" | "Unauthorized" }>> => {
    return await client.GET("/api");
  },
},
extractSuccessValue: (value: Result<string[], { code: "NotFound" | "Unauthorized" }> ) => value.data // hopefully this will help narrowing the success value to string[]
);

// Usage
if (query.error) {
  // narrowed to { code: "NotFound" | "Unauthorized" }
}

if (query.defect) {
  // regular runtime Error
}

if (query.data) {
  // string[]
}

I'm not sure the current suggestion of my implementation is possible due to typescipt limitation, but I think we can somehow split between success values and errors with type-safety. Let me know what do you think

[carloitaben]

I think something similar can be already done in userland by creating custom queryOption and mutationOption functions that:

• Expect a Result type as the return type of queryFn and mutationFn
• Call the function, rethrow errors, and return data
• Infer the error type and pass it to the TError generic of queryOption and mutationOption
• Infer the result type and pass it to the TData generic of queryOption and mutationOption

Effect has the same issue, and community projects like effect-query tackle it in a similar way.

I personally need to spend some time on this since the TypeScript stuff is a bit overwhelming for me 😅 For example, I don’t really get the difference between the TQueryFnData and TData generics. But the runtime implementation seems pretty simple 🙂