V10 Client: Move .query/useQuery to the front?

[KATT]

Resolved: #3042 (comment)

Problem / background

After using tRPC 10 for a while now, I've warmed up to the idea of flipping the procedure type to the beginning of the statements in the client.

I find myself writing trpc.post.byId() often instead of trpc.post.byId.useQuery(), and I'm one of the authors of this thing.

Current

// Raw client
const post = await trpc.post.byId.query({ id: "1" })

const addPost = await trpc.post.add.mutate({ title: "hello world" });;

// React
const postQuery = trpc.post.byId.useQuery({ id: "1" }, { /* react-query options */ })
const postListQuery = trpc.post.list.useInfiniteQuery({ limit: 10 }, { /* react-query options */ })

const addPostMutation = trpc.post.add.useMutation({ /* react-query options */ }); // then: `addPostMutation.mutate({ title: "hello world" }); 

Proposal - move .query/.mutation to the front

// Raw client
const post = await trpc.query.post.byId({ id: "1" }, { /* react-query options */ })

const addPost = await trpc.mutation.post.add({ title: "hello world" });;

// React
const postQuery = trpc.useQuery.post.byId({ id: "1" }, /* react-query options */)
const postListQuery = trpc.useInfiniteQuery.post.byId({ limit: 10 }, { /* react-query options */ })

const addPostMutation = trpc.useMutation.post.add({ /* react-query options */ }); // then: `addPostMutation.mutate({ title: "hello world" }); 

Motivation

Pros

• Show intent up-front - I will likely know upfront if I want to query something.
• More intuitive? I do write trpc.post.byId() myself sometimes
• We can destructure queries in a shared utils const {query, mutation} = trpc and use that easily
• Add extra methods at the root trpc-client object that won't interfere with actual routers/procedures

Cons

Misalignment between backend and frontend:

In the backend, we add procedures in the procedure.input(y).query(() => '...')-fashion.

useQuery/useMutation looks like a hook but is an object

Might lead to same situations where people try to call useQuery() instead of useQuery.post.byId() as it looks like a hook.

Standard linters in React

useQuery.post.byId() will not be interpreted as a hook in the React linter, but neither does post.byId.useQuery() currently - facebook/react#25065

Additional information

• Open question how do the Proxy utilities get affected?
• This is the last RFC of v10.
• We will not be removing the distinction between queries and mutations - if you propose something that alludes to that or something that is not technically feasible without codegen, your post will be deleted or hidden.
• Should be cleared up before we do final 10.0.0 release, but we can still go ahead with RC, I think.
• #2270 - discussion about client API design that went a bit out of hand
• #2316 - Path proxy PR, an alternative solution

[rhenriquez28]

Not feeling too strongly about either of the two. However, here are some thoughts I wanted to share:

We can destructure queries in a shared utils const {query, mutation} = trpc and use that easily

This is cool, although I think I see people destructuring more based on routers than on operations, but I could be wrong. Could be something that we can ask on twitter maybe?

When it comes to this:

const postQuery = trpc.useQuery.post.byId({ id: "1" })

I don't find this weird, maybe because I'm a relative beginner in React, but do React people expect more that a hook should be a function instead of an object? Don't really know what React Hooks best practices say about this considering that in this case the actual hook would be byId instead of useQuery as I understand it.

[KATT]

They could do this:

const {useQuery} = trpc;

function MyComp() {
  const postQuery = useQuery.post.byId({ id: "1" }) 
  // [..]
}

I get your point though, people might think that it should be a fn the same way I try to call the end bit as a fn now.

[TkDodo]

I do like this. The biggest cons for all of this is the linter imo. What about if useQuery would be a function though? Would the linter "get it" ?

const postQuery = trpc.useQuery().post.byId({ id: "1" }) 

or is this too weird 😅

otherwise, what would you think about forking the react lint rules and publishing them as a trpc eslint plugin that would adapt the linter to the trpc needs ?

[KATT]

Making it a function would make it very confusing I think (it would make it lint though), but yes, should be possible to fork the lint rules

[KATT]

Ability to add more stuff to the root tRPC object - this seems like the biggest potential pro to me personally. If this allows some great design decisions, then I'm all for it.

Random example:

Let's say you want to use the underlying observable that .query() has or make a "safe" promise that never throws and returns an Either<Result, TRPCClientError<AppRouter>>, this could allow for that:

const clientBase = createTRPCProxyClient<AppRouter>();

/// imaginary
const safe = createSafeProcedureCalls(clientBase); // -> { safeQuery: {..}, safeMutation: {...} }
const observerCalls = createObserverProcedureCalls(clientBase); // -> { $query: {..}, $mutation: {...} }

export const client = {
 ...base,
  ...safe
  ...observerCalls
})

We could also use a method for this to potentially make TRPCClient slimmer and remove the default code for subscriptions.

Linting - this is unfortunate, and if you think that one version is more likely to get good linting support in the foreseeable future then this would be a very strong argument for me to favor that syntax.

Yeah, it's only about detecting rules of hooks really. They're so ingrained in me that I used tRPC myself for a year and a half before someone pointed it out.

Could do a custom lint rule if we really want it.

[rhenriquez28]

Let's say you want to use the underlying observable that .query() has or make a "safe" promise that never throws and returns an Either<Result, TRPCClientError>, this could allow for that.

Now this is dopeee. If moving query to the front unlocks this kind of things to be added, I'm all for it 🔥

[JonParton]

Just to throw in my 2 cents (For what it's worth!).

I'm definitely in favour of moving to the front for ease of use ...

• Like Katt I've been finding myself missing the .useQuery() off the end of the proxy and having to go back and add it!

• I also like the fact that the useQuery / query and useMutation / mutation at the front will then filter provided options from intelesense to either read or write. I think most people when they start looking for something know if it's a mutation or a query they are looking for when they start.

  • It's OK remembering which are mutations, and which are queries, when you are in the flow of creating the backend but when you have created them a while ago or a new person mainly focussing on front end starts to use it having that clear distinction, I think is valuable.
    • The only way currently to tell if a procedure is a mutation or a query is .ing off the end or going to look at the procedure (Or using consistent naming OfCourse!).

The only other downside in addition to those already mentioned I see is if we only do this on the trpc client side object it will also be inconsistent even on the front end with the utils object... which is very much a router first approach currently:

const utils = trpc.useContext()

utils.post.invalidate()

Also - one extra thing to highlight - I'm guessing we would need useQuery, useMutation and useInfiniteQuery on the react side!

[KATT]

The only other downside in addition to those already mentioned I see is if we only do this on the trpc client side object it will also be inconsistent even on the front end with the utils object... which is very much a router first approach currently:

const utils = trpc.useContext()

utils.post.invalidate()

If we were to do this, I guess we'd need to refactor the proxy to be something like

const utils = trpc.useContext();

// before
utils.post.invalidate()
utils.post.byId.invalidate()
utils.post.byId.invalidate({ id: "1" })

// after:
utils.invalidate.post()
utils.invalidate.post.byId()
utils.invalidate.post.byId({ id: "1" })

Also - one extra thing to highlight - I'm guessing we would need useQuery, useMutation and useInfiniteQuery on the react side!

Yes, true!

[c-ehrlich]

After thinking about it a bit more, I really like the new syntax proposal. In a way it feels "closer to React Query".

A huge percentage of the tRPC questions we get on create-t3-app are actually just React Query questions, so any amount of making the RQ docs easier to apply to tRPC is a win to me.

// tRPC with this syntax
import { useQuery } from "../util/trpc"; // it would be possible to export like this

function SomeComponent() {
  const { data, etc } = useQuery.router.procedure({ foo: "bar" });
  return <div>{data?.buzz}</div>
}

// React Query
import { useQuery } from "@tanstack/react-query";

function SomeComponent() {
  const { data, etc } = useQuery(['router', 'procedure', { foo: "bar" }]);
  return <div>{data?.buzz}</div>
}

Disregard my previous post, I'm all for it!

[lunacrafts]

I have very deep trpc router which I use as a proxy for few external services. None of them has repeatable API, many of them have different purpose, so It's far from simple byId. With current approach I can explore both procedures namespaces simply by typing namespace path which is very convenient.

before

const { data }  = myApi.namespace.domain.findAll.useQuery()
const { mutate } = myApi.namespace.domain.create.useMutation();

after

const { data } = myApi.useQuery.namespace.domain.findAll()
const { mutate }  = myApi.useMutation.namespace.domain.create();

Original approach Is more aligned with my way of thinking. Firstly I'm thinking about a namespace and a domain, then about action I want to perform. But tRPC made my life so easy that there is literally zero difference for me. Current syntax is more intuitive imho.

---

edit:

Ok I have to admit that new syntax is sexy as well. Getting rid of useQuery before passing arguments to the method might be a strong argument here.

[juliusmarminge]

I'm not the biggest fan of this proposal. To me, it feels quite intuitive that I'm traversing my router and eventually calling a method (i.e. the hook) on a procedure. Even more so when the backend router now really is an object.

Say I have this router

const router({
  user: router({
    byId: publicProcedure...
    list: publicProcedure...
  })
})

I would go down the router until I get to the target procedure, and then eventually calling the desired method on it, e.g.

const user = trpc.user.byId
// i have now traversed the router object, lets call the method on it
.useQuery()
// or for the utils stuff
.invalidate()

To me, this intuitiveness disappears when the order is switched, especially since we're now never calling a hook, we just use the hook name as some sort of object attribute which feels even stranger when you think of rules of hook and that hooks are not supposed to be conditionally called - well now we're never calling a hook?

I get that it's "more similar to React Query", but I don't see that as a problem. If you want it at the front for those purposes, I like #2316 more.

[iway1]

Another benefit to this syntax is it makes leveraging auto complete more intuitive (which IMO is a one of the major factors in what makes tRPC so valuable to developers).

In practice with V9, it's very common for me to begin typing useMutation or useQuery and then scroll through the end point names in order to find the one I'm looking for, because I can always remember whether I need a query versus a mutation but rarely can I remember the actual end point name.

Having that differentiation up front means it narrows down the end points and should make it easier to find the end point the dev is looking for quickly, theoretically halving the number of end points to scroll through and preventing situations where the dev confuses a query end point with a mutation end point. This makes finding the endpoint via autocomplete much, much easier.

With the current V10 syntax, we're always having to scroll through all of the query and mutation end points even when we already know we're looking for a mutation. Visually that's just going to be a lot harder to process and more difficult to find the endpoint we want.

The syntax switch would have a significant positive impact on the usability of the in-editor autocomplete and for that reason alone I think it's better.

[TheOtterlord]

I wasn't sold at first, but after giving it a little think, the benefits are pretty good. Obviously autocomplete becomes less cluttered and top level methods that don't require scope data become a possibility. I think giving up a little consistency is worth it

[spenceradolph]

I am not (initially) in favor of this proposal, for me it’s intuitive that for each api call I make, I am getting the same “output” as far as what I can use.

.useQuery() at the ends tells me what kind of things I can extract, and if it switched to
.byId() I start to assume “this no longer is a library call, this is something I wrote”

I typically reformat my calls to something like
api.user.getAll.useQuery()

If I saw .getAll(), I might mistakenly assume it returns the complete list of users. For me personally, if I’m reading code quickly, I would start at the end of the line since that’s what ultimately giving me the return.

edit: of course, given some time to get used to it, I could see myself abstracting the call away into
apiQuery.user.getAll()
But those were my initial take-aways.

[devjmetivier]

Not a fan of this proposal as I don't think think that this meaningfully improves the ergonomics of the API. I think that the "lexical" changes with this proposal break down the deeper that routers are nested as well.

The "traditional" art of programming I'm used to, or that I would expect, with a fully typed system like this is to traverse the various options defined in my schema of routes/procedures and then the methods (queries, mutations, etc) are consequently revealed to me.

Prisma is a really great example of this:

prisma.user.findUniqueOrThrow(...)

prisma being the client I'm using, user being the part of the schema I wish to perform actions/methods on, findUniqueOrThrow being an available method that exists in that schema.

The con of "Misalignment between backend and frontend" is further compounded by using tools like Prisma in your procedures because it moves away from a sense of consistency that the tRPC client already has with it. I would imagine many users of tRPC would also use Prisma. The changes in this proposal fundamentally break what I would consider to be the most familiar way to traverse the available methods of a client.

---

A separate issue is one of discoverability. I understand the appeal of defining your intentions up front but that might present some challenges for an engineer being onboarded to a project where the entire schema is not presented up front by the client. For example:

trpc.useQuery.post.byId(...)

☝🏼 My understanding with these changes is that by defining useQuery up front narrows the other parts of the post router by scoping to what I can get from executing the procedure. And the deeper the routes go, the harder I think it is to find what I can and can't do. As opposed to the current way:

trpc.post.byId.useQuery(...)

☝🏼 Even if don't use any other procedures under post, if I traversed the client with intellisense to get to the procedure I want to call, I was still presented with all of my available options. Not just scoped by what is allowed to be queried or mutated or subscribed to.

---

I will say one of the pros mentioned in this RFC is nice in that we would have access to more methods straight off of the trpc client object, but I wouldn't trade my familiar lexical understanding of using software for it. I'm just fine traversing through what I can do with the client, and I would argue that it would encourage playing with your API and maybe finding ways to improve it.

[juliusmarminge]

Cons

Misalignment between backend and frontend:

In the backend, we add procedures in the procedure.input(y).query(() => '...')-fashion.

Haven't seen anyone else commenting on this part so I thought I'd jump on it.

I think this is quite a big deal actually. To keep the API intuitive and uniform these sorts of things can confuse newcomers quite a bit?

If I for example can chain inputs in a "forward fashion", the middleware is chained before the resolver function and then finally the query/mutation. Then, on the frontend we flip it around and the part that we'd think is the function (query(() => ...) is just accessed like an object attribute 🤔.

[chrisflatley]

Sorry, I'm against for a couple of reasons.

The cons look fundamental and scary but the pros seem cosmetic.

Personally, I like trpc.blah.useQuery - it reads like a 'fully qualified' hook.

Is there another hook library which has useSomething.something()? Doesn't feel like a standard React convention, but perhaps I'm not looking in the right places.

---

I don't see the operation first autocompletion argument. You can already do it - just arrange your router in that way yourself.

(I admit that would be manual work and have the useQuery at the end).

---

We have useQuery and useInfiniteQuery already. In future versions, perhaps we'll have a greater number of operations which will
'pollute' the top level trpc.*.

Whilst it would be nice not to have to write useQuery() at the end, at least it's very flexible to new additions (on an endpoint by endpoint basis too).

---

My biggest trpc API gripe is where .invalidate currently sits. The trpc.useContext() reads as a dangerous under the hood thing. I don't feel I own that in the same way I own the endpoints I've written (or the data from them I want to invalidate).

I think all the endpoint operations in the same place.

I'd even be happy with const {invalidate} = trpc.post.byId.useInvalidate() for consistency!

---

With Next 13/React 18, perhaps trpc will change too - more (server side component) code looking like const result = use(trpc.post.byId.query({id: 1})) within server components.

It seems premature to change the v10 API now, when there's a big stuff happening in the wider ecosystem which might result in more fundamental changes later.

[iway1]

"I don't see the operation first autocompletion argument. You can already do it - just arrange your router in that way yourself.

(I admit that would be manual work and have the useQuery at the end)."

this would be a pretty significant amount of extra work to achieve something that we're currently getting for free in V9 and with the proposed change. Definitely don't like the idea of having to create a completely new nested router structure in order to achieve separation of queries and mutations that we're already getting for free, plus we'd end up with an additional level of nesting even if we did do it manually which seems clunky.

Autocomplete may not be as important to most people as it is to me and that's fine, but the RFC is a big upgrade in the autocomplete department, that's for sure.

"I'd even be happy with const {invalidate} = trpc.post.byId.useInvalidate() for consistency!"

Why not just

trpc.post.byId.invalidate()??? that'd be so cool! That's closer to how I use vanilla react query too, (importing the query client and using it to invalidate directly with no hook)

[juliusmarminge]

trpc.post.byId.invalidate()??? that'd be so cool! That's closer to how I use vanilla react query too, (importing the query client and using it to invalidate directly with no hook)

Breaks rules of React Hooks

[iway1]

@juliusmarminge no it doesn't, invalidate doesn't have to be a hook (plus react query allows basically the same thing)

IE in react query we can do:

import {queryClient} from 'src/queryClient';

export default function Component() {
    function someEventHandler() {
        queryClient.invalidateQueries(['key']);
    }
    //...
}

[juliusmarminge]

@juliusmarminge no it doesn't, invalidate doesn't have to be a hook (plus react query allows basically the same thing)

No, but getting the queryClient is a hook (useQueryClient), thus you need to call trpc.useContext on a top level. (Then invalidate on top of that)

[iway1]

@juliusmarminge that's how it works currently, yeah, doesn't necessarily have too work that way though. would have to like pass the query client into the trpc client when initializing it or something I guess so that trpc could access the client without a hook. that's a pretty big ask though, i guess. would just be really nice to not have to have the hook (definitely is possible to create a situation where the hook isn't necessary)

[KATT]

Curious about this one -- is there a difference of opinion between @trpc/react & @trpc/client, perhaps?

i.e. both of these could be true:

• client.query.post.byId({ id: 1 }) is nicer than client.post.byId.query({ id: 1 })
• client.post.byId.useQuery({ id: 1 }) is nicer than client.useQuery.post.byId({ id: 1 })

We don't have to have the react package exactly map the client package.

[chrisflatley]

You might be right.

I think it's got to 'read good' and fit in the conventions.

Eg for react it needs to look like a hook (hence my invalidate hook comment).

For client you read that nicely as 'trpc query posts by id (please)'. It's the typical verbNoun method naming we love.

I don't know if it's good if they are different between the paradigms. Perhaps that best of both worlds and clarifies a difference - or perhaps confusing.

If this something that could be a configurable project (router) preference? (I assume not, the TS definitions are probably crazy already)

[KATT]

If this something that could be a configurable project (router) preference? (I assume not, the TS definitions are probably crazy already)

Yes, but we already maintain a large API surface and it's not something we'd want to do

[tunnckoCore]

For "raw" it really seems logical and good trpc.query.post.byId(). But for "react" as you mentioned, it feels bad yea - trpc.useQuery.post.byId(). And if it's one way for the "raw" and the another way for "react" it would become even worse.

I'm feeling and seeing this RFC as con in general.

• prisma is similar to as it is currently prisma.post.byId.findOne() and trpc.post.byId.query()
• currently it is similar to router definition - router({ post: { byId: procedure.query(() => {}) } } - post -> byId -> query
• seen somewhere in the comments "to be configurable" or something - not good, better to remain a bit more opinionated and strict/safe. the whole point is to be safe, intuitive and strict.
• you wrote the router anyway, you absolutely know how it is structured and the most logical and closest to your mind is to start getting/writing properties the same way. "Uh yea, it's user by id query, then trpc.post. ([IDE suggestions trigger] if needed) byId.query()".

So no, to me it's hard No. I love it they way it is in v10 and thinking to go hard on tRPC.

[Nick-Lucas]

Coming with the perspective of a long time react person, hooks must be functions. I've seen in the issues trpc is already asking for and blocked by changes to the linting rules for v10, and I suspect going down this road will lead to the react team shutting down any discussion of supporting this API via lint rules. It's just not how hooks are intended to be.

Anyway, to be part of the solution: Perhaps a way to go which would be supported by the existing lint rules, and also solve this problem would be like:

const { useQuery, useMutation, useInfiniteQuery } = trpcClient

// React
const postQuery = useQuery(api => api.post.byId(params), { /* react-query opts */ })
const postListQuery = useInfiniteQuery(api => api.post.byId(params), { /* react-query opts */ })

const addPostMutation = useMutation(api => api.post.add, { /* react-query opts */ })
// then: `addPostMutation.mutate({ title: "hello world" }); 

Lots of ways this could be implemented under the hood, including just wrapping the core of this RFC which would make the react-query portion a pretty skinny shim, or doing something more clever because of course query-keys need to be generated properly. I'm pretty sure it could be made to work and keep the performance benefits of V10, while inferring the type of useQuery or useMutation based on the wrapped selection.

[at-nage]

Totally support this idea, with v10 aproach I have to do something like that if I want use onSuccess option

example.hello.useQuery(undefined, { onSuccess: (data) => console.log(data) });

Hate this undefined that I have to pass as an input when input is void | undefind

[KATT]

We've decided not to proceed with this at the moment. If we do revisit it in the future we will provide a codemod to do the change automatically.