useQuery via object

[ianmacartney]

const { status, value, error } = useQuery({
  query: api.foo.bar,
  args: { ... },
  initialValue: someCachedValue,
  throwOnError: true,
});

Allow calling useQuery with an object instead of (api.foo.bar, args)

• adds initialValue support
• allows returning the error instead of throwing
• unifies usePreloadedQuery, enabling skipping

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ianmacartney]

My biggest question right now is around the skip arg.

1. Passing { skip: shouldSkip, ... } or "skip" is redundant - ideally we start with just one.
2. If it's true, the args type might not match (e.g. { skip: !!userId, args: { userId }, ...} - if userId is required, then we need a more complicated type here such that when skip is truthy args isn't type-checked. I'm hesitant to complicate the types if avoidable.
3. Passing shouldSkip? "skip" : {...} makes the types easier

I'm also hesitant to make args optional when they can be empty - seems like more trouble than it's worth for libraries to have to support.

[ianmacartney]

I'm leaning towards only having useQuery(someCondition ? "skip" : { query, args: typeSafeArgs })

[thomasballinger]

@ianmacartney this is another start on this type, in the final form of this PR would be good to unify

[ianmacartney]

Thanks! Missed that - wdyt about QueryOptions instead of ConvexQueryOptions? The naming conflict with react-query is my guess as to why the namespacing? But none of the other types have this namespace, and users likely won't be importing the type

[thomasballinger]

Yeah QueryOptions is good, I was looking too-far into the future here

[chenxin-yan]

My biggest question right now is around the skip arg.

1. Passing `{ skip: shouldSkip, ... }` or `"skip"` is redundant - ideally we start with just one.

2. If it's true, the args type might not match (e.g. `{ skip: !!userId, args: { userId }, ...}` - if userId is required, then we need a more complicated type here such that when skip is truthy args isn't type-checked. I'm hesitant to complicate the types if avoidable.

3. Passing `shouldSkip? "skip" : {...}` makes the types easier

I'm also hesitant to make args optional when they can be empty - seems like more trouble than it's worth for libraries to have to support.

Agree that shouldSkip? "skip" : {...} might be the best for now, and have you take a look at tanstack query's enabled implementation yet?

Also, if we implement skip option, do you think its a good idea to use discriminated union so that when skip is true, the args field would not exists. args only exists when skip is false or is undefined. will this make sure args isn't type-checked when the query is skipped?

[ianmacartney]

@chenxin-yan I explored it in #262 (not making args missing, but unknown, since you want to do something like useQuery({query: api.foo.bar, args: { userId }, skip: !userId }). Unfortunately the type discrimination doesn't work, so you're left with !userId ? { skip: true } : {args: { userId}, ...} which may as well be the "skip" sentinel.

One way to alleviate the "I don't like that it's a magic string" would be to export const skipToken = "skip" as const"; and use !userId? skipToken : { query, args, ..}