Please provide an alternative error-return mechanism

[aryzing]

Currently, the only way to "return an error" within a handler is by throwing it. Which does a pretty good job at catering for most use-cases. However, often it is useful to treat the error as a value and have its type inferred in the error prop of the query/mutation. This is especially useful if multiple errors can be "returned" and the UI needs to respond to each of them.

If it helps, Elysia uses an error() helper to return errors from its handlers that tanstack/query may get inspiration from?

Ideally, we'd have an API the looks something like,

const { data, error } = useQuery({
  async queryFn() {
    const res = await fetch("http://example");

    if (!res.ok) return error("Fetch failed" as const);

    const data = await res.json();

    if (data.foo < 10) return error({ type: "too-low", value: data.foo });
    if (data.foo > 100) return error({ type: "too-high", value: data.foo });

    // return ok(data.foo);
    // return success(data.foo);
    return data.foo;
  },
});

[TkDodo]

I think this might be a good idea, but note that we still can’t guarantee anything on type level because a runtime error can occur at any time in javascript, so even with the code above, we could still get errors from res.json() for example.

So, with that said, why is the shown code so much better than creating your own sub-class of error and doing:

const { data, error } = useQuery({
  async queryFn() {
    const res = await fetch("http://example");

    if (!res.ok) throw new MyError("Fetch failed" as const);

    const data = await res.json();

    if (data.foo < 10) throw new MyError({ type: "too-low", value: data.foo });
    if (data.foo > 100) throw new MyError({ type: "too-high", value: data.foo });

    // return ok(data.foo);
    // return success(data.foo);
    return data.foo;
  },
});

then, you can check if error instanceof MyError and handle it accordingly ...

[aryzing]

Something along those lines would work, although we'd need to define custom error types ahead of time. Which is totally doable, just tedious when there are a lot of them.

For APIs with typed clients, it would be great UX being able to forward the error and have its type inferred,

async function queryFn() {
  const { error: apiError, data } = await api.exampleEndpoint();

  if (apiError) return error(apiError);

  return data;
}

To account for thrown errors, handlers using error() could perhaps be inferred as InferredFromErrorFn | UnknownThrownError?

I'm not sure this approach would be "so much better", but treating errors as values is definitely more ergonomic than wrapping everything in custom error classes + throwing + comparing with instanceof. Is it worth implementing? I'd certainly appreciate the feature, although unsure if the added value would justify its implementation cost.

[TkDodo]

although we'd need to define custom error types ahead of time

imo this is good practice, as we need to union with Error anyways because of potential runtime errors. So if you do: return error('foo'), best case scenario is that your error type will be 'foo' | Error, and that isn't really better imo.